SwiftUI and Combine - Stories intro multi-platform widget

SwiftUI example

Features

• Long tap - pause stories showcase
• Tap - next story
• Leeway - pause before start stories
• Customize component with you own stories and every story with it's own view
• Customize time longevity for every story
• iOS and macOS support
• Customizable dark and light scheme support for every story
• Control stories run as by external sources that are not inside StoriesWidget so via Gesture
• Observing stories life circle for reacting on state change
• Internal and custom external errors handling
• Localization (En, Es) All errors and system messages are localized

1. Stories

Define enum with your stories conforming to IStory

    public enum Stories: IStory {
          
        case first
        case second
        case third

        @ViewBuilder
        public func builder(progress : Binding<CGFloat>) -> some View {
            switch(self) {
                case .first:  StoryTpl(self, .green,  "1", progress)
                case .second: StoryTpl(self, .brown,  "2", progress)
                case .third:  StoryTpl(self, .purple, "3", progress)
            }
        }
        
        public var duration: TimeInterval {
            switch self{
                case .first, .third : return 5
                default : return 3
            }
        }

        public var colorScheme: ColorScheme? {
            switch(self) {
                case .first: return .light
                default: return .dark
            }
        }

    }

2. Create stories widget

• manager - package standard manager StoriesManager.self for managing stories life circle.
  Define your own manager conforming to IStoriesManager if you need some specific managing process
• stories - stories conforming to IStory

    StoriesWidget(
        manager: StoriesManager.self,
        stories: Stories.allCases
    )

Optional

• strategy - default strategy is circle

Strategy	Description
circle	Repeat stories
once	Show just once

• current - start story if not defined start with first

• leeway - delay before start stories, default .seconds(0)

• pause - shared var to control stories run by external sources that are not inside StoriesWidget, default .constant(false). For example if you launched modal view and need to pause running stories while modal view is existed you can do it via shared variable passing as a binding in StoriesWidget.

• validator - Custom validator to check validity of stories data set before start

• onStoriesStateChanged - Closure to react on stories state change

Add video component

Stories life circle

You can observe events of the stories life circle and react on it's change. Pass closure to config of StoriesWidget.

• onStoriesStateChanged(StoriesState) - Closure to react on stories state change

    StoriesWidget(
        manager: StoriesManager.self,
        stories: Stories.allCases                    
    ){ state in
        print("Do something on stories \(state) change")
    }

State	Description
ready	Waiting to start If there's leeway this is the state during this delay before the big start
start	Big start
begin	Begin of a story
end	End of a story
suspend	At the moment of pause and then is kept until is resumed. Informs that currently demonstration is paused
resume	At the moment of resume and then is kept until the next pause or end of a story
finish	Big finish. At the end of the strategy .once

Stories error handling

There's internal check of stories data

• There are no stories
• Duration must be a positive number greater than zero

Custom stories error handling

if you need custom check for stories data, just implement validator conforming to IStoriesValidater and pass it as a parameter to StoriesWidget

    StoriesWidget(
        manager: StoriesManager.self,
        stories: Stories.allCases,
        validator: CustomStoriesValidater.self
    )

There's an example of custom validator. Take a look on CustomStoriesValidater implementation. Stories won't be started if there's an error then instead of stories there'll be the error view with description of errors.

Localization (En, Es)

All the internal errors and system messages that might occur are localized. Localization for stories is up to you as it's external source for the component.

Se localizan todos los errores internos y mensajes del sistema que puedan producirse. La localización de las historias depende de usted, ya que es la fuente externa del componente.

Documentation(API)

• You need to have Xcode 13 installed in order to have access to Documentation Compiler (DocC)
• Go to Product > Build Documentation or ⌃⇧⌘ D