@cratis/showrunner.cue.react 0.0.0-stage → 2.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.storybook/main.ts +11 -0
- package/.storybook/preview.tsx +21 -0
- package/Configuration/CueConfiguration.ts +27 -0
- package/Configuration/CueProvider.tsx +64 -0
- package/Configuration/CueStageBoundary.tsx +37 -0
- package/Configuration/index.ts +6 -0
- package/Icons.tsx +36 -0
- package/Labels/CueLabels.ts +39 -0
- package/Labels/defaultCueLabels.ts +23 -0
- package/Labels/index.ts +6 -0
- package/Labels/resolveLabels.ts +12 -0
- package/Markdown/CueMarkdown.tsx +31 -0
- package/Markdown/index.ts +5 -0
- package/Markdown/safeUrl.ts +29 -0
- package/README.md +54 -2
- package/Speech/CueSpeech.ts +27 -0
- package/Speech/CueSpeechConfiguration.ts +21 -0
- package/Speech/HttpSpeechOptions.ts +37 -0
- package/Speech/createHttpSpeech.ts +135 -0
- package/Speech/index.ts +7 -0
- package/Speech/silentSpeech.ts +15 -0
- package/Speech/speechClips.ts +66 -0
- package/TourAnchor.tsx +162 -0
- package/TourAnchorSpace.ts +15 -0
- package/TourCallout.ts +22 -0
- package/TourCalloutBubble.tsx +38 -0
- package/TourCamera.ts +17 -0
- package/TourChapter.ts +24 -0
- package/TourChapterList.tsx +65 -0
- package/TourGesture.ts +30 -0
- package/TourOverlayShell.tsx +102 -0
- package/TourPointer.tsx +83 -0
- package/TourSection.ts +24 -0
- package/TourSelfPacedPanel.tsx +26 -0
- package/TourStep.ts +40 -0
- package/TourSubtitles.tsx +22 -0
- package/TourTimelineBar.tsx +127 -0
- package/Tours/index.ts +5 -0
- package/Tours/useCueTours.ts +63 -0
- package/Tours/useTourNudge.ts +37 -0
- package/cursorSvg.ts +12 -0
- package/dist/cjs/Configuration/CueConfiguration.d.ts +11 -0
- package/dist/cjs/Configuration/CueConfiguration.d.ts.map +1 -0
- package/dist/cjs/Configuration/CueProvider.d.ts +19 -0
- package/dist/cjs/Configuration/CueProvider.d.ts.map +1 -0
- package/dist/cjs/Configuration/CueProvider.js +44 -0
- package/dist/cjs/Configuration/CueProvider.js.map +1 -0
- package/dist/cjs/Configuration/CueStageBoundary.d.ts +14 -0
- package/dist/cjs/Configuration/CueStageBoundary.d.ts.map +1 -0
- package/dist/cjs/Configuration/CueStageBoundary.js +45 -0
- package/dist/cjs/Configuration/CueStageBoundary.js.map +1 -0
- package/dist/cjs/Configuration/index.d.ts +4 -0
- package/dist/cjs/Configuration/index.d.ts.map +1 -0
- package/dist/cjs/Examples/AppShell.d.ts +5 -0
- package/dist/cjs/Examples/AppShell.d.ts.map +1 -0
- package/dist/cjs/Examples/LocalizedCue.d.ts +5 -0
- package/dist/cjs/Examples/LocalizedCue.d.ts.map +1 -0
- package/dist/cjs/Examples/OrderDeskTour.d.ts +2 -0
- package/dist/cjs/Examples/OrderDeskTour.d.ts.map +1 -0
- package/dist/cjs/Examples/OwnStageGuard.d.ts +5 -0
- package/dist/cjs/Examples/OwnStageGuard.d.ts.map +1 -0
- package/dist/cjs/Examples/OwnVoice.d.ts +3 -0
- package/dist/cjs/Examples/OwnVoice.d.ts.map +1 -0
- package/dist/cjs/Icons.d.ts +19 -0
- package/dist/cjs/Icons.d.ts.map +1 -0
- package/dist/cjs/Icons.js +33 -0
- package/dist/cjs/Icons.js.map +1 -0
- package/dist/cjs/Labels/CueLabels.d.ts +18 -0
- package/dist/cjs/Labels/CueLabels.d.ts.map +1 -0
- package/dist/cjs/Labels/defaultCueLabels.d.ts +3 -0
- package/dist/cjs/Labels/defaultCueLabels.d.ts.map +1 -0
- package/dist/cjs/Labels/defaultCueLabels.js +24 -0
- package/dist/cjs/Labels/defaultCueLabels.js.map +1 -0
- package/dist/cjs/Labels/index.d.ts +4 -0
- package/dist/cjs/Labels/index.d.ts.map +1 -0
- package/dist/cjs/Labels/resolveLabels.d.ts +3 -0
- package/dist/cjs/Labels/resolveLabels.d.ts.map +1 -0
- package/dist/cjs/Labels/resolveLabels.js +17 -0
- package/dist/cjs/Labels/resolveLabels.js.map +1 -0
- package/dist/cjs/Markdown/CueMarkdown.d.ts +6 -0
- package/dist/cjs/Markdown/CueMarkdown.d.ts.map +1 -0
- package/dist/cjs/Markdown/CueMarkdown.js +34 -0
- package/dist/cjs/Markdown/CueMarkdown.js.map +1 -0
- package/dist/cjs/Markdown/index.d.ts +3 -0
- package/dist/cjs/Markdown/index.d.ts.map +1 -0
- package/dist/cjs/Markdown/safeUrl.d.ts +2 -0
- package/dist/cjs/Markdown/safeUrl.d.ts.map +1 -0
- package/dist/cjs/Markdown/safeUrl.js +34 -0
- package/dist/cjs/Markdown/safeUrl.js.map +1 -0
- package/dist/cjs/Speech/CueSpeech.d.ts +10 -0
- package/dist/cjs/Speech/CueSpeech.d.ts.map +1 -0
- package/dist/cjs/Speech/CueSpeechConfiguration.d.ts +6 -0
- package/dist/cjs/Speech/CueSpeechConfiguration.d.ts.map +1 -0
- package/dist/cjs/Speech/HttpSpeechOptions.d.ts +10 -0
- package/dist/cjs/Speech/HttpSpeechOptions.d.ts.map +1 -0
- package/dist/cjs/Speech/createHttpSpeech.d.ts +4 -0
- package/dist/cjs/Speech/createHttpSpeech.d.ts.map +1 -0
- package/dist/cjs/Speech/createHttpSpeech.js +140 -0
- package/dist/cjs/Speech/createHttpSpeech.js.map +1 -0
- package/dist/cjs/Speech/index.d.ts +5 -0
- package/dist/cjs/Speech/index.d.ts.map +1 -0
- package/dist/cjs/Speech/silentSpeech.d.ts +3 -0
- package/dist/cjs/Speech/silentSpeech.d.ts.map +1 -0
- package/dist/cjs/Speech/silentSpeech.js +16 -0
- package/dist/cjs/Speech/silentSpeech.js.map +1 -0
- package/dist/cjs/Speech/speechClips.d.ts +7 -0
- package/dist/cjs/Speech/speechClips.d.ts.map +1 -0
- package/dist/cjs/Speech/speechClips.js +60 -0
- package/dist/cjs/Speech/speechClips.js.map +1 -0
- package/dist/cjs/TourAnchor.d.ts +14 -0
- package/dist/cjs/TourAnchor.d.ts.map +1 -0
- package/dist/cjs/TourAnchor.js +150 -0
- package/dist/cjs/TourAnchor.js.map +1 -0
- package/dist/cjs/TourAnchorSpace.d.ts +2 -0
- package/dist/cjs/TourAnchorSpace.d.ts.map +1 -0
- package/dist/cjs/TourCallout.d.ts +8 -0
- package/dist/cjs/TourCallout.d.ts.map +1 -0
- package/dist/cjs/TourCalloutBubble.d.ts +9 -0
- package/dist/cjs/TourCalloutBubble.d.ts.map +1 -0
- package/dist/cjs/TourCalloutBubble.js +27 -0
- package/dist/cjs/TourCalloutBubble.js.map +1 -0
- package/dist/cjs/TourCamera.d.ts +6 -0
- package/dist/cjs/TourCamera.d.ts.map +1 -0
- package/dist/cjs/TourChapter.d.ts +8 -0
- package/dist/cjs/TourChapter.d.ts.map +1 -0
- package/dist/cjs/TourChapterList.d.ts +10 -0
- package/dist/cjs/TourChapterList.d.ts.map +1 -0
- package/dist/cjs/TourChapterList.js +68 -0
- package/dist/cjs/TourChapterList.js.map +1 -0
- package/dist/cjs/TourChapterList.stories.d.ts +21 -0
- package/dist/cjs/TourChapterList.stories.d.ts.map +1 -0
- package/dist/cjs/TourGesture.d.ts +12 -0
- package/dist/cjs/TourGesture.d.ts.map +1 -0
- package/dist/cjs/TourOverlayShell.d.ts +13 -0
- package/dist/cjs/TourOverlayShell.d.ts.map +1 -0
- package/dist/cjs/TourOverlayShell.js +77 -0
- package/dist/cjs/TourOverlayShell.js.map +1 -0
- package/dist/cjs/TourPointer.d.ts +9 -0
- package/dist/cjs/TourPointer.d.ts.map +1 -0
- package/dist/cjs/TourPointer.js +74 -0
- package/dist/cjs/TourPointer.js.map +1 -0
- package/dist/cjs/TourSection.d.ts +8 -0
- package/dist/cjs/TourSection.d.ts.map +1 -0
- package/dist/cjs/TourSelfPacedPanel.d.ts +6 -0
- package/dist/cjs/TourSelfPacedPanel.d.ts.map +1 -0
- package/dist/cjs/TourSelfPacedPanel.js +27 -0
- package/dist/cjs/TourSelfPacedPanel.js.map +1 -0
- package/dist/cjs/TourSelfPacedPanel.stories.d.ts +21 -0
- package/dist/cjs/TourSelfPacedPanel.stories.d.ts.map +1 -0
- package/dist/cjs/TourStep.d.ts +12 -0
- package/dist/cjs/TourStep.d.ts.map +1 -0
- package/dist/cjs/TourSubtitles.d.ts +5 -0
- package/dist/cjs/TourSubtitles.d.ts.map +1 -0
- package/dist/cjs/TourSubtitles.js +24 -0
- package/dist/cjs/TourSubtitles.js.map +1 -0
- package/dist/cjs/TourTimelineBar.d.ts +10 -0
- package/dist/cjs/TourTimelineBar.d.ts.map +1 -0
- package/dist/cjs/TourTimelineBar.js +134 -0
- package/dist/cjs/TourTimelineBar.js.map +1 -0
- package/dist/cjs/TourTimelineBar.stories.d.ts +24 -0
- package/dist/cjs/TourTimelineBar.stories.d.ts.map +1 -0
- package/dist/cjs/Tours/index.d.ts +3 -0
- package/dist/cjs/Tours/index.d.ts.map +1 -0
- package/dist/cjs/Tours/useCueTours.d.ts +7 -0
- package/dist/cjs/Tours/useCueTours.d.ts.map +1 -0
- package/dist/cjs/Tours/useCueTours.js +46 -0
- package/dist/cjs/Tours/useCueTours.js.map +1 -0
- package/dist/cjs/Tours/useTourNudge.d.ts +6 -0
- package/dist/cjs/Tours/useTourNudge.d.ts.map +1 -0
- package/dist/cjs/Tours/useTourNudge.js +28 -0
- package/dist/cjs/Tours/useTourNudge.js.map +1 -0
- package/dist/cjs/cursorSvg.d.ts +2 -0
- package/dist/cjs/cursorSvg.d.ts.map +1 -0
- package/dist/cjs/cursorSvg.js +15 -0
- package/dist/cjs/cursorSvg.js.map +1 -0
- package/dist/cjs/index.d.ts +41 -0
- package/dist/cjs/index.d.ts.map +1 -0
- package/dist/cjs/index.js +72 -0
- package/dist/cjs/index.js.map +1 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/tourClock.d.ts +19 -0
- package/dist/cjs/tourClock.d.ts.map +1 -0
- package/dist/cjs/tourClock.js +107 -0
- package/dist/cjs/tourClock.js.map +1 -0
- package/dist/cjs/tourGeometry.d.ts +18 -0
- package/dist/cjs/tourGeometry.d.ts.map +1 -0
- package/dist/cjs/tourGeometry.js +86 -0
- package/dist/cjs/tourGeometry.js.map +1 -0
- package/dist/cjs/tourSelfPaced.d.ts +12 -0
- package/dist/cjs/tourSelfPaced.d.ts.map +1 -0
- package/dist/cjs/tourSelfPaced.js +69 -0
- package/dist/cjs/tourSelfPaced.js.map +1 -0
- package/dist/cjs/tourTimeline.d.ts +40 -0
- package/dist/cjs/tourTimeline.d.ts.map +1 -0
- package/dist/cjs/tourTimeline.js +168 -0
- package/dist/cjs/tourTimeline.js.map +1 -0
- package/dist/cjs/useTourPlayback.d.ts +25 -0
- package/dist/cjs/useTourPlayback.d.ts.map +1 -0
- package/dist/cjs/useTourPlayback.js +245 -0
- package/dist/cjs/useTourPlayback.js.map +1 -0
- package/dist/esm/Configuration/CueConfiguration.d.ts +11 -0
- package/dist/esm/Configuration/CueConfiguration.d.ts.map +1 -0
- package/dist/esm/Configuration/CueConfiguration.js +2 -0
- package/dist/esm/Configuration/CueConfiguration.js.map +1 -0
- package/dist/esm/Configuration/CueProvider.d.ts +19 -0
- package/dist/esm/Configuration/CueProvider.d.ts.map +1 -0
- package/dist/esm/Configuration/CueProvider.js +41 -0
- package/dist/esm/Configuration/CueProvider.js.map +1 -0
- package/dist/esm/Configuration/CueStageBoundary.d.ts +14 -0
- package/dist/esm/Configuration/CueStageBoundary.d.ts.map +1 -0
- package/dist/esm/Configuration/CueStageBoundary.js +43 -0
- package/dist/esm/Configuration/CueStageBoundary.js.map +1 -0
- package/dist/esm/Configuration/index.d.ts +4 -0
- package/dist/esm/Configuration/index.d.ts.map +1 -0
- package/dist/esm/Configuration/index.js +4 -0
- package/dist/esm/Configuration/index.js.map +1 -0
- package/dist/esm/Examples/AppShell.d.ts +5 -0
- package/dist/esm/Examples/AppShell.d.ts.map +1 -0
- package/dist/esm/Examples/AppShell.js +10 -0
- package/dist/esm/Examples/AppShell.js.map +1 -0
- package/dist/esm/Examples/LocalizedCue.d.ts +5 -0
- package/dist/esm/Examples/LocalizedCue.d.ts.map +1 -0
- package/dist/esm/Examples/LocalizedCue.js +11 -0
- package/dist/esm/Examples/LocalizedCue.js.map +1 -0
- package/dist/esm/Examples/OrderDeskTour.d.ts +2 -0
- package/dist/esm/Examples/OrderDeskTour.d.ts.map +1 -0
- package/dist/esm/Examples/OrderDeskTour.js +33 -0
- package/dist/esm/Examples/OrderDeskTour.js.map +1 -0
- package/dist/esm/Examples/OwnStageGuard.d.ts +5 -0
- package/dist/esm/Examples/OwnStageGuard.d.ts.map +1 -0
- package/dist/esm/Examples/OwnStageGuard.js +17 -0
- package/dist/esm/Examples/OwnStageGuard.js.map +1 -0
- package/dist/esm/Examples/OwnVoice.d.ts +3 -0
- package/dist/esm/Examples/OwnVoice.d.ts.map +1 -0
- package/dist/esm/Examples/OwnVoice.js +35 -0
- package/dist/esm/Examples/OwnVoice.js.map +1 -0
- package/dist/esm/Icons.d.ts +19 -0
- package/dist/esm/Icons.d.ts.map +1 -0
- package/dist/esm/Icons.js +31 -0
- package/dist/esm/Icons.js.map +1 -0
- package/dist/esm/Labels/CueLabels.d.ts +18 -0
- package/dist/esm/Labels/CueLabels.d.ts.map +1 -0
- package/dist/esm/Labels/CueLabels.js +2 -0
- package/dist/esm/Labels/CueLabels.js.map +1 -0
- package/dist/esm/Labels/defaultCueLabels.d.ts +3 -0
- package/dist/esm/Labels/defaultCueLabels.d.ts.map +1 -0
- package/dist/esm/Labels/defaultCueLabels.js +22 -0
- package/dist/esm/Labels/defaultCueLabels.js.map +1 -0
- package/dist/esm/Labels/index.d.ts +4 -0
- package/dist/esm/Labels/index.d.ts.map +1 -0
- package/dist/esm/Labels/index.js +4 -0
- package/dist/esm/Labels/index.js.map +1 -0
- package/dist/esm/Labels/resolveLabels.d.ts +3 -0
- package/dist/esm/Labels/resolveLabels.d.ts.map +1 -0
- package/dist/esm/Labels/resolveLabels.js +15 -0
- package/dist/esm/Labels/resolveLabels.js.map +1 -0
- package/dist/esm/Markdown/CueMarkdown.d.ts +6 -0
- package/dist/esm/Markdown/CueMarkdown.d.ts.map +1 -0
- package/dist/esm/Markdown/CueMarkdown.js +32 -0
- package/dist/esm/Markdown/CueMarkdown.js.map +1 -0
- package/dist/esm/Markdown/index.d.ts +3 -0
- package/dist/esm/Markdown/index.d.ts.map +1 -0
- package/dist/esm/Markdown/index.js +3 -0
- package/dist/esm/Markdown/index.js.map +1 -0
- package/dist/esm/Markdown/safeUrl.d.ts +2 -0
- package/dist/esm/Markdown/safeUrl.d.ts.map +1 -0
- package/dist/esm/Markdown/safeUrl.js +32 -0
- package/dist/esm/Markdown/safeUrl.js.map +1 -0
- package/dist/esm/Speech/CueSpeech.d.ts +10 -0
- package/dist/esm/Speech/CueSpeech.d.ts.map +1 -0
- package/dist/esm/Speech/CueSpeech.js +2 -0
- package/dist/esm/Speech/CueSpeech.js.map +1 -0
- package/dist/esm/Speech/CueSpeechConfiguration.d.ts +6 -0
- package/dist/esm/Speech/CueSpeechConfiguration.d.ts.map +1 -0
- package/dist/esm/Speech/CueSpeechConfiguration.js +2 -0
- package/dist/esm/Speech/CueSpeechConfiguration.js.map +1 -0
- package/dist/esm/Speech/HttpSpeechOptions.d.ts +10 -0
- package/dist/esm/Speech/HttpSpeechOptions.d.ts.map +1 -0
- package/dist/esm/Speech/HttpSpeechOptions.js +2 -0
- package/dist/esm/Speech/HttpSpeechOptions.js.map +1 -0
- package/dist/esm/Speech/createHttpSpeech.d.ts +4 -0
- package/dist/esm/Speech/createHttpSpeech.d.ts.map +1 -0
- package/dist/esm/Speech/createHttpSpeech.js +138 -0
- package/dist/esm/Speech/createHttpSpeech.js.map +1 -0
- package/dist/esm/Speech/index.d.ts +5 -0
- package/dist/esm/Speech/index.d.ts.map +1 -0
- package/dist/esm/Speech/index.js +5 -0
- package/dist/esm/Speech/index.js.map +1 -0
- package/dist/esm/Speech/silentSpeech.d.ts +3 -0
- package/dist/esm/Speech/silentSpeech.d.ts.map +1 -0
- package/dist/esm/Speech/silentSpeech.js +14 -0
- package/dist/esm/Speech/silentSpeech.js.map +1 -0
- package/dist/esm/Speech/speechClips.d.ts +7 -0
- package/dist/esm/Speech/speechClips.d.ts.map +1 -0
- package/dist/esm/Speech/speechClips.js +58 -0
- package/dist/esm/Speech/speechClips.js.map +1 -0
- package/dist/esm/TourAnchor.d.ts +14 -0
- package/dist/esm/TourAnchor.d.ts.map +1 -0
- package/dist/esm/TourAnchor.js +148 -0
- package/dist/esm/TourAnchor.js.map +1 -0
- package/dist/esm/TourAnchorSpace.d.ts +2 -0
- package/dist/esm/TourAnchorSpace.d.ts.map +1 -0
- package/dist/esm/TourAnchorSpace.js +2 -0
- package/dist/esm/TourAnchorSpace.js.map +1 -0
- package/dist/esm/TourCallout.d.ts +8 -0
- package/dist/esm/TourCallout.d.ts.map +1 -0
- package/dist/esm/TourCallout.js +2 -0
- package/dist/esm/TourCallout.js.map +1 -0
- package/dist/esm/TourCalloutBubble.d.ts +9 -0
- package/dist/esm/TourCalloutBubble.d.ts.map +1 -0
- package/dist/esm/TourCalloutBubble.js +25 -0
- package/dist/esm/TourCalloutBubble.js.map +1 -0
- package/dist/esm/TourCamera.d.ts +6 -0
- package/dist/esm/TourCamera.d.ts.map +1 -0
- package/dist/esm/TourCamera.js +2 -0
- package/dist/esm/TourCamera.js.map +1 -0
- package/dist/esm/TourChapter.d.ts +8 -0
- package/dist/esm/TourChapter.d.ts.map +1 -0
- package/dist/esm/TourChapter.js +2 -0
- package/dist/esm/TourChapter.js.map +1 -0
- package/dist/esm/TourChapterList.d.ts +10 -0
- package/dist/esm/TourChapterList.d.ts.map +1 -0
- package/dist/esm/TourChapterList.js +66 -0
- package/dist/esm/TourChapterList.js.map +1 -0
- package/dist/esm/TourChapterList.stories.d.ts +21 -0
- package/dist/esm/TourChapterList.stories.d.ts.map +1 -0
- package/dist/esm/TourChapterList.stories.js +53 -0
- package/dist/esm/TourChapterList.stories.js.map +1 -0
- package/dist/esm/TourGesture.d.ts +12 -0
- package/dist/esm/TourGesture.d.ts.map +1 -0
- package/dist/esm/TourGesture.js +2 -0
- package/dist/esm/TourGesture.js.map +1 -0
- package/dist/esm/TourOverlayShell.d.ts +13 -0
- package/dist/esm/TourOverlayShell.d.ts.map +1 -0
- package/dist/esm/TourOverlayShell.js +75 -0
- package/dist/esm/TourOverlayShell.js.map +1 -0
- package/dist/esm/TourPointer.d.ts +9 -0
- package/dist/esm/TourPointer.d.ts.map +1 -0
- package/dist/esm/TourPointer.js +72 -0
- package/dist/esm/TourPointer.js.map +1 -0
- package/dist/esm/TourSection.d.ts +8 -0
- package/dist/esm/TourSection.d.ts.map +1 -0
- package/dist/esm/TourSection.js +2 -0
- package/dist/esm/TourSection.js.map +1 -0
- package/dist/esm/TourSelfPacedPanel.d.ts +6 -0
- package/dist/esm/TourSelfPacedPanel.d.ts.map +1 -0
- package/dist/esm/TourSelfPacedPanel.js +25 -0
- package/dist/esm/TourSelfPacedPanel.js.map +1 -0
- package/dist/esm/TourSelfPacedPanel.stories.d.ts +21 -0
- package/dist/esm/TourSelfPacedPanel.stories.d.ts.map +1 -0
- package/dist/esm/TourSelfPacedPanel.stories.js +41 -0
- package/dist/esm/TourSelfPacedPanel.stories.js.map +1 -0
- package/dist/esm/TourStep.d.ts +12 -0
- package/dist/esm/TourStep.d.ts.map +1 -0
- package/dist/esm/TourStep.js +2 -0
- package/dist/esm/TourStep.js.map +1 -0
- package/dist/esm/TourSubtitles.d.ts +5 -0
- package/dist/esm/TourSubtitles.d.ts.map +1 -0
- package/dist/esm/TourSubtitles.js +22 -0
- package/dist/esm/TourSubtitles.js.map +1 -0
- package/dist/esm/TourTimelineBar.d.ts +10 -0
- package/dist/esm/TourTimelineBar.d.ts.map +1 -0
- package/dist/esm/TourTimelineBar.js +132 -0
- package/dist/esm/TourTimelineBar.js.map +1 -0
- package/dist/esm/TourTimelineBar.stories.d.ts +24 -0
- package/dist/esm/TourTimelineBar.stories.d.ts.map +1 -0
- package/dist/esm/TourTimelineBar.stories.js +62 -0
- package/dist/esm/TourTimelineBar.stories.js.map +1 -0
- package/dist/esm/Tours/index.d.ts +3 -0
- package/dist/esm/Tours/index.d.ts.map +1 -0
- package/dist/esm/Tours/index.js +3 -0
- package/dist/esm/Tours/index.js.map +1 -0
- package/dist/esm/Tours/useCueTours.d.ts +7 -0
- package/dist/esm/Tours/useCueTours.d.ts.map +1 -0
- package/dist/esm/Tours/useCueTours.js +44 -0
- package/dist/esm/Tours/useCueTours.js.map +1 -0
- package/dist/esm/Tours/useTourNudge.d.ts +6 -0
- package/dist/esm/Tours/useTourNudge.d.ts.map +1 -0
- package/dist/esm/Tours/useTourNudge.js +26 -0
- package/dist/esm/Tours/useTourNudge.js.map +1 -0
- package/dist/esm/cursorSvg.d.ts +2 -0
- package/dist/esm/cursorSvg.d.ts.map +1 -0
- package/dist/esm/cursorSvg.js +13 -0
- package/dist/esm/cursorSvg.js.map +1 -0
- package/dist/esm/index.d.ts +41 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +24 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/package.json +3 -0
- package/dist/esm/tourClock.d.ts +19 -0
- package/dist/esm/tourClock.d.ts.map +1 -0
- package/dist/esm/tourClock.js +103 -0
- package/dist/esm/tourClock.js.map +1 -0
- package/dist/esm/tourGeometry.d.ts +18 -0
- package/dist/esm/tourGeometry.d.ts.map +1 -0
- package/dist/esm/tourGeometry.js +80 -0
- package/dist/esm/tourGeometry.js.map +1 -0
- package/dist/esm/tourSelfPaced.d.ts +12 -0
- package/dist/esm/tourSelfPaced.d.ts.map +1 -0
- package/dist/esm/tourSelfPaced.js +64 -0
- package/dist/esm/tourSelfPaced.js.map +1 -0
- package/dist/esm/tourTimeline.d.ts +40 -0
- package/dist/esm/tourTimeline.d.ts.map +1 -0
- package/dist/esm/tourTimeline.js +154 -0
- package/dist/esm/tourTimeline.js.map +1 -0
- package/dist/esm/useTourPlayback.d.ts +25 -0
- package/dist/esm/useTourPlayback.d.ts.map +1 -0
- package/dist/esm/useTourPlayback.js +243 -0
- package/dist/esm/useTourPlayback.js.map +1 -0
- package/index.ts +68 -0
- package/package.json +93 -4
- package/styles.css +485 -0
- package/tourClock.ts +125 -0
- package/tourGeometry.ts +95 -0
- package/tourSelfPaced.ts +93 -0
- package/tourTimeline.ts +237 -0
- package/useTourPlayback.ts +291 -0
package/tourSelfPaced.ts
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// Copyright (c) Cratis. All rights reserved.
|
|
2
|
+
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The markdown walkthroughs a tour offers for reading it self-paced, keyed by chapter id — the same ids the
|
|
6
|
+
* tour's script gives its chapters. A tour without content simply never offers the self-paced switch.
|
|
7
|
+
*/
|
|
8
|
+
export type TourSelfPacedContent = Readonly<Record<string, string>>;
|
|
9
|
+
|
|
10
|
+
/** Everything the tour's chrome needs to draw itself in or out of self-paced reading mode. */
|
|
11
|
+
export interface TourSelfPacedView {
|
|
12
|
+
/** Whether the tour is being read self-paced rather than played. */
|
|
13
|
+
isSelfPaced: boolean;
|
|
14
|
+
|
|
15
|
+
/** Whether the media playback controls — play, scrubbing, narration and subtitles — are usable. */
|
|
16
|
+
isMediaPlaybackEnabled: boolean;
|
|
17
|
+
|
|
18
|
+
/** Whether the chapter list shows where on the clock each chapter starts. */
|
|
19
|
+
areTimingsShown: boolean;
|
|
20
|
+
|
|
21
|
+
/** The markdown for the chapter being read, or an empty string when the chapter has none. */
|
|
22
|
+
markdown: string;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Gets whether a tour has any self-paced content to read at all, which is what decides whether the
|
|
27
|
+
* self-paced switch is offered.
|
|
28
|
+
* @param content The tour's content, or undefined when it has none.
|
|
29
|
+
* @returns True when there is at least one chapter's markdown to show.
|
|
30
|
+
*/
|
|
31
|
+
export function hasSelfPacedContent(content: TourSelfPacedContent | undefined): boolean {
|
|
32
|
+
return content !== undefined && Object.keys(content).length > 0;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Gets the markdown to read for a chapter.
|
|
37
|
+
* @param content The tour's content, or undefined when it has none.
|
|
38
|
+
* @param chapterId The chapter being read, or undefined when the tour has no chapters.
|
|
39
|
+
* @returns The chapter's markdown, or an empty string when there is nothing to show for it.
|
|
40
|
+
*/
|
|
41
|
+
export function selfPacedMarkdownFor(content: TourSelfPacedContent | undefined, chapterId: string | undefined): string {
|
|
42
|
+
if (content === undefined || chapterId === undefined) return '';
|
|
43
|
+
|
|
44
|
+
return content[chapterId] ?? '';
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Decides how the tour's chrome behaves for the mode it is in: reading self-paced stops being a media
|
|
49
|
+
* player — the playback controls dim, the chapter timings disappear because there is no clock to time
|
|
50
|
+
* against, and the current chapter's walkthrough is shown — while narrated playback keeps all of it and
|
|
51
|
+
* shows no markdown.
|
|
52
|
+
* @param isSelfPaced Whether the viewer has switched to self-paced reading.
|
|
53
|
+
* @param content The tour's content, or undefined when it has none.
|
|
54
|
+
* @param chapterId The chapter currently reached, or undefined when the tour has no chapters.
|
|
55
|
+
* @returns The {@link TourSelfPacedView} the chrome draws from.
|
|
56
|
+
*/
|
|
57
|
+
export function selfPacedViewFor(
|
|
58
|
+
isSelfPaced: boolean,
|
|
59
|
+
content: TourSelfPacedContent | undefined,
|
|
60
|
+
chapterId: string | undefined): TourSelfPacedView {
|
|
61
|
+
// Self-paced mode without anything to read would be a silent, frozen tour — so the mode only ever
|
|
62
|
+
// engages when there is content to show.
|
|
63
|
+
const isReading = isSelfPaced && hasSelfPacedContent(content);
|
|
64
|
+
|
|
65
|
+
return {
|
|
66
|
+
isSelfPaced: isReading,
|
|
67
|
+
isMediaPlaybackEnabled: !isReading,
|
|
68
|
+
areTimingsShown: !isReading,
|
|
69
|
+
markdown: isReading ? selfPacedMarkdownFor(content, chapterId) : '',
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// Matches a markdown image (`` or ``) and captures the surrounding syntax so
|
|
74
|
+
// only the URL is rewritten — the same shape the release-notes rewriter uses.
|
|
75
|
+
const markdownImagePattern = /(!\[[^\]]*\]\()([^)\s]+)(\s*(?:"[^"]*")?\s*\))/g;
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Resolves the media references in a chapter's markdown against the URLs the bundler gave the media files.
|
|
79
|
+
* Content references its screenshots and animations with paths relative to its own folder (`media/name.png`);
|
|
80
|
+
* at runtime those files live wherever the bundler put them, and this maps each reference to that URL. A
|
|
81
|
+
* reference to a file that does not exist (yet) is left untouched, so its alt text still tells the reader
|
|
82
|
+
* what belongs there.
|
|
83
|
+
* @param markdown The chapter's markdown.
|
|
84
|
+
* @param mediaUrls The bundled URL for each media file, keyed by the path the markdown references it with.
|
|
85
|
+
* @returns The markdown with every known media reference resolved.
|
|
86
|
+
*/
|
|
87
|
+
export function resolveTourMedia(markdown: string, mediaUrls: Readonly<Record<string, string>>): string {
|
|
88
|
+
return markdown.replace(markdownImagePattern, (match, prefix, url, suffix) => {
|
|
89
|
+
const normalized = (url as string).replace(/^\.\//, '');
|
|
90
|
+
const resolved = mediaUrls[normalized];
|
|
91
|
+
return resolved === undefined ? match : `${prefix}${resolved}${suffix}`;
|
|
92
|
+
});
|
|
93
|
+
}
|
package/tourTimeline.ts
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
// Copyright (c) Cratis. All rights reserved.
|
|
2
|
+
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
|
|
3
|
+
|
|
4
|
+
import type { TourChapter } from './TourChapter.js';
|
|
5
|
+
import type { TourSection } from './TourSection.js';
|
|
6
|
+
import type { TourStep } from './TourStep.js';
|
|
7
|
+
|
|
8
|
+
/** Words per minute the narration is assumed to be read at — a calm, unhurried voice-over pace. */
|
|
9
|
+
const NARRATION_WORDS_PER_MINUTE = 145;
|
|
10
|
+
|
|
11
|
+
/** The breath left at the end of a narrated step before the next one starts. */
|
|
12
|
+
const NARRATION_TAIL_MS = 900;
|
|
13
|
+
|
|
14
|
+
/** No step is ever shorter than this, however short its line is. */
|
|
15
|
+
export const MINIMUM_STEP_MS = 2200;
|
|
16
|
+
|
|
17
|
+
/** How long a step with nothing to say lasts — a pure camera move. */
|
|
18
|
+
const SILENT_STEP_MS = 2500;
|
|
19
|
+
|
|
20
|
+
/** How far into a chapter "previous" restarts it rather than going back a chapter, as a video player does. */
|
|
21
|
+
export const RESTART_CHAPTER_WINDOW_MS = 2000;
|
|
22
|
+
|
|
23
|
+
/** A step placed on the tour's clock. */
|
|
24
|
+
export interface TimedTourStep<TStep extends TourStep = TourStep> {
|
|
25
|
+
/** The step itself. */
|
|
26
|
+
step: TStep;
|
|
27
|
+
|
|
28
|
+
/** The chapter the step belongs to. */
|
|
29
|
+
chapterIndex: number;
|
|
30
|
+
|
|
31
|
+
/** When the step starts, in milliseconds from the beginning of the tour. */
|
|
32
|
+
startMs: number;
|
|
33
|
+
|
|
34
|
+
/** When the step ends, in milliseconds from the beginning of the tour. */
|
|
35
|
+
endMs: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** A chapter placed on the tour's clock. */
|
|
39
|
+
export interface TimedTourChapter<TStep extends TourStep = TourStep> {
|
|
40
|
+
/** The chapter itself. */
|
|
41
|
+
chapter: TourChapter<TStep>;
|
|
42
|
+
|
|
43
|
+
/** The section the chapter belongs to. */
|
|
44
|
+
sectionIndex: number;
|
|
45
|
+
|
|
46
|
+
/** When the chapter starts, in milliseconds from the beginning of the tour. */
|
|
47
|
+
startMs: number;
|
|
48
|
+
|
|
49
|
+
/** When the chapter ends, in milliseconds from the beginning of the tour. */
|
|
50
|
+
endMs: number;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** A section placed on the tour's clock. */
|
|
54
|
+
export interface TimedTourSection<TStep extends TourStep = TourStep> {
|
|
55
|
+
/** The section itself. */
|
|
56
|
+
section: TourSection<TStep>;
|
|
57
|
+
|
|
58
|
+
/** When the section starts, in milliseconds from the beginning of the tour. */
|
|
59
|
+
startMs: number;
|
|
60
|
+
|
|
61
|
+
/** When the section ends, in milliseconds from the beginning of the tour. */
|
|
62
|
+
endMs: number;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The whole tour laid out on one clock, which is what the progress bar, subtitles and chapter list read. */
|
|
66
|
+
export interface TourTimeline<TStep extends TourStep = TourStep> {
|
|
67
|
+
/** Every step of every chapter of every section, in play order. */
|
|
68
|
+
steps: TimedTourStep<TStep>[];
|
|
69
|
+
|
|
70
|
+
/** Every chapter, in play order across all sections. Chapter indices used anywhere in the player index into this list. */
|
|
71
|
+
chapters: TimedTourChapter<TStep>[];
|
|
72
|
+
|
|
73
|
+
/** Every section, in play order. */
|
|
74
|
+
sections: TimedTourSection<TStep>[];
|
|
75
|
+
|
|
76
|
+
/** How long the whole tour lasts, in milliseconds. */
|
|
77
|
+
durationMs: number;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Estimates how long a line of narration takes to say.
|
|
82
|
+
* @param narration The line to be spoken.
|
|
83
|
+
* @returns The duration in milliseconds.
|
|
84
|
+
*/
|
|
85
|
+
export function narrationDurationMs(narration: string): number {
|
|
86
|
+
const words = narration.split(/\s+/u).filter(word => word.length > 0).length;
|
|
87
|
+
if (words === 0) return SILENT_STEP_MS;
|
|
88
|
+
|
|
89
|
+
const spoken = (words / NARRATION_WORDS_PER_MINUTE) * 60000;
|
|
90
|
+
return Math.max(MINIMUM_STEP_MS, Math.round(spoken + NARRATION_TAIL_MS));
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Gets how long a step lasts, preferring the script's own figure when it states one.
|
|
95
|
+
* @param step The step to measure.
|
|
96
|
+
* @returns The duration in milliseconds.
|
|
97
|
+
*/
|
|
98
|
+
export function stepDurationMs(step: TourStep): number {
|
|
99
|
+
return step.durationMs ?? narrationDurationMs(step.narration);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Lays the sections out on a single clock so every part of the player can work in one shared unit of time.
|
|
104
|
+
*
|
|
105
|
+
* The clock stays flat: steps and chapters run straight through every section, and a chapter's index is its
|
|
106
|
+
* position across the whole tour — sections only add headings and spans on top, they never fragment the clock.
|
|
107
|
+
* @param sections The scripted sections, in play order.
|
|
108
|
+
* @returns The {@link TourTimeline}.
|
|
109
|
+
*/
|
|
110
|
+
export function buildTourTimeline<TStep extends TourStep>(sections: TourSection<TStep>[]): TourTimeline<TStep> {
|
|
111
|
+
const steps: TimedTourStep<TStep>[] = [];
|
|
112
|
+
const timedChapters: TimedTourChapter<TStep>[] = [];
|
|
113
|
+
const timedSections: TimedTourSection<TStep>[] = [];
|
|
114
|
+
let cursor = 0;
|
|
115
|
+
|
|
116
|
+
sections.forEach((section, sectionIndex) => {
|
|
117
|
+
const sectionStart = cursor;
|
|
118
|
+
for (const chapter of section.chapters) {
|
|
119
|
+
const chapterStart = cursor;
|
|
120
|
+
const chapterIndex = timedChapters.length;
|
|
121
|
+
for (const step of chapter.steps) {
|
|
122
|
+
const endMs = cursor + stepDurationMs(step);
|
|
123
|
+
steps.push({ step, chapterIndex, startMs: cursor, endMs });
|
|
124
|
+
cursor = endMs;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
timedChapters.push({ chapter, sectionIndex, startMs: chapterStart, endMs: cursor });
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
timedSections.push({ section, startMs: sectionStart, endMs: cursor });
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
return { steps, chapters: timedChapters, sections: timedSections, durationMs: cursor };
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Gets which step is playing at a point on the clock.
|
|
138
|
+
* @param timeline The timeline to look in.
|
|
139
|
+
* @param timeMs The point on the clock, in milliseconds.
|
|
140
|
+
* @returns The index into {@link TourTimeline.steps}, or -1 when the timeline is empty.
|
|
141
|
+
*/
|
|
142
|
+
export function stepIndexAtTime(timeline: TourTimeline, timeMs: number): number {
|
|
143
|
+
if (timeline.steps.length === 0) return -1;
|
|
144
|
+
|
|
145
|
+
// The end of the tour belongs to its last step rather than to nothing, so the final line stays on screen
|
|
146
|
+
// when playback finishes instead of the subtitles blanking on the last frame.
|
|
147
|
+
const found = timeline.steps.findIndex(candidate => timeMs >= candidate.startMs && timeMs < candidate.endMs);
|
|
148
|
+
if (found >= 0) return found;
|
|
149
|
+
|
|
150
|
+
return timeMs < 0 ? 0 : timeline.steps.length - 1;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* Gets which chapter is playing at a point on the clock.
|
|
155
|
+
* @param timeline The timeline to look in.
|
|
156
|
+
* @param timeMs The point on the clock, in milliseconds.
|
|
157
|
+
* @returns The index into {@link TourTimeline.chapters}, or -1 when the timeline is empty.
|
|
158
|
+
*/
|
|
159
|
+
export function chapterIndexAtTime(timeline: TourTimeline, timeMs: number): number {
|
|
160
|
+
const stepIndex = stepIndexAtTime(timeline, timeMs);
|
|
161
|
+
return stepIndex < 0 ? -1 : timeline.steps[stepIndex].chapterIndex;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Gets which section is playing at a point on the clock.
|
|
166
|
+
* @param timeline The timeline to look in.
|
|
167
|
+
* @param timeMs The point on the clock, in milliseconds.
|
|
168
|
+
* @returns The index into {@link TourTimeline.sections}, or -1 when the timeline is empty.
|
|
169
|
+
*/
|
|
170
|
+
export function sectionIndexAtTime(timeline: TourTimeline, timeMs: number): number {
|
|
171
|
+
const chapterIndex = chapterIndexAtTime(timeline, timeMs);
|
|
172
|
+
return chapterIndex < 0 ? -1 : timeline.chapters[chapterIndex].sectionIndex;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Gets where on the clock a chapter begins.
|
|
177
|
+
* @param timeline The timeline to look in.
|
|
178
|
+
* @param chapterIndex The chapter to locate.
|
|
179
|
+
* @returns The point on the clock in milliseconds, or 0 when there is no such chapter.
|
|
180
|
+
*/
|
|
181
|
+
export function chapterStartMs(timeline: TourTimeline, chapterIndex: number): number {
|
|
182
|
+
return timeline.chapters[chapterIndex]?.startMs ?? 0;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* Gets where "previous chapter" should land from a point on the clock.
|
|
187
|
+
* @param timeline The timeline to look in.
|
|
188
|
+
* @param timeMs The current point on the clock, in milliseconds.
|
|
189
|
+
* @returns The point on the clock to jump to, in milliseconds.
|
|
190
|
+
*/
|
|
191
|
+
export function previousChapterTargetMs(timeline: TourTimeline, timeMs: number): number {
|
|
192
|
+
const current = chapterIndexAtTime(timeline, timeMs);
|
|
193
|
+
if (current < 0) return 0;
|
|
194
|
+
|
|
195
|
+
// Well into a chapter, "previous" restarts the one being watched — the same thing a video player does,
|
|
196
|
+
// and what someone who missed the start of an explanation actually wants.
|
|
197
|
+
const startOfCurrent = chapterStartMs(timeline, current);
|
|
198
|
+
if (timeMs - startOfCurrent > RESTART_CHAPTER_WINDOW_MS) return startOfCurrent;
|
|
199
|
+
|
|
200
|
+
return chapterStartMs(timeline, Math.max(0, current - 1));
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* Gets where "next chapter" should land from a point on the clock.
|
|
205
|
+
* @param timeline The timeline to look in.
|
|
206
|
+
* @param timeMs The current point on the clock, in milliseconds.
|
|
207
|
+
* @returns The point on the clock to jump to, in milliseconds.
|
|
208
|
+
*/
|
|
209
|
+
export function nextChapterTargetMs(timeline: TourTimeline, timeMs: number): number {
|
|
210
|
+
const current = chapterIndexAtTime(timeline, timeMs);
|
|
211
|
+
if (current < 0) return 0;
|
|
212
|
+
if (current >= timeline.chapters.length - 1) return timeline.durationMs;
|
|
213
|
+
|
|
214
|
+
return chapterStartMs(timeline, current + 1);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
// The lines still to come after a step that have something to say, in the order they will be needed — what the voice-over is
|
|
218
|
+
// asked for ahead of time so each starts the moment its step does.
|
|
219
|
+
export function narrationsAfter(timeline: TourTimeline, stepIndex: number, count: number): string[] {
|
|
220
|
+
if (stepIndex < 0) return [];
|
|
221
|
+
return timeline.steps
|
|
222
|
+
.slice(stepIndex + 1, stepIndex + 1 + count)
|
|
223
|
+
.map(timed => timed.step.narration)
|
|
224
|
+
.filter(narration => narration.length > 0);
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* Formats a point on the clock the way a video player does.
|
|
229
|
+
* @param timeMs The point on the clock, in milliseconds.
|
|
230
|
+
* @returns The time as `m:ss`.
|
|
231
|
+
*/
|
|
232
|
+
export function formatTourTime(timeMs: number): string {
|
|
233
|
+
const totalSeconds = Math.max(0, Math.floor(timeMs / 1000));
|
|
234
|
+
const minutes = Math.floor(totalSeconds / 60);
|
|
235
|
+
const seconds = totalSeconds % 60;
|
|
236
|
+
return `${minutes}:${seconds.toString().padStart(2, '0')}`;
|
|
237
|
+
}
|
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
// Copyright (c) Cratis. All rights reserved.
|
|
2
|
+
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
|
|
3
|
+
|
|
4
|
+
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
|
|
5
|
+
import { useCueConfiguration } from './Configuration/CueProvider.js';
|
|
6
|
+
import type { TourSection } from './TourSection.js';
|
|
7
|
+
import type { TourStep } from './TourStep.js';
|
|
8
|
+
import { advanceTourClock } from './tourClock.js';
|
|
9
|
+
import {
|
|
10
|
+
type TourTimeline,
|
|
11
|
+
buildTourTimeline,
|
|
12
|
+
chapterIndexAtTime,
|
|
13
|
+
chapterStartMs,
|
|
14
|
+
narrationsAfter,
|
|
15
|
+
nextChapterTargetMs,
|
|
16
|
+
previousChapterTargetMs,
|
|
17
|
+
sectionIndexAtTime,
|
|
18
|
+
stepIndexAtTime,
|
|
19
|
+
} from './tourTimeline.js';
|
|
20
|
+
|
|
21
|
+
// How many steps ahead of the one being said the voice-over is requested, so each line starts the moment its step does.
|
|
22
|
+
const NARRATION_LOOKAHEAD_STEPS = 2;
|
|
23
|
+
|
|
24
|
+
/** How often the clock advances. Fine enough for a progress bar, coarse enough not to re-render at frame rate. */
|
|
25
|
+
const TICK_MS = 100;
|
|
26
|
+
|
|
27
|
+
/** Everything the tour's chrome needs to draw itself and drive playback. */
|
|
28
|
+
export interface TourPlayback<TStep extends TourStep = TourStep> {
|
|
29
|
+
/** The whole tour laid out on one clock. */
|
|
30
|
+
timeline: TourTimeline<TStep>;
|
|
31
|
+
|
|
32
|
+
/** Where playback has got to, in milliseconds. */
|
|
33
|
+
timeMs: number;
|
|
34
|
+
|
|
35
|
+
/** Whether the tour is running. */
|
|
36
|
+
isPlaying: boolean;
|
|
37
|
+
|
|
38
|
+
/** Whether the voice-over is switched on. */
|
|
39
|
+
isAudioEnabled: boolean;
|
|
40
|
+
|
|
41
|
+
/** Whether subtitles are switched on. */
|
|
42
|
+
areSubtitlesEnabled: boolean;
|
|
43
|
+
|
|
44
|
+
/** Whether a voice-over service is available at all. */
|
|
45
|
+
isSpeechAvailable: boolean;
|
|
46
|
+
|
|
47
|
+
/** Whether the voice-over has failed and the tour is carrying on with subtitles instead. */
|
|
48
|
+
hasNarrationFailed: boolean;
|
|
49
|
+
|
|
50
|
+
/** The step being played, or undefined when the script is empty. */
|
|
51
|
+
step: TStep | undefined;
|
|
52
|
+
|
|
53
|
+
/** The chapter being played. */
|
|
54
|
+
chapterIndex: number;
|
|
55
|
+
|
|
56
|
+
/** The section the playing chapter belongs to. */
|
|
57
|
+
sectionIndex: number;
|
|
58
|
+
|
|
59
|
+
/** Starts or stops playback. */
|
|
60
|
+
togglePlay(): void;
|
|
61
|
+
|
|
62
|
+
/** Stops playback where it is, whatever state it was in — what switching to self-paced reading uses. */
|
|
63
|
+
pause(): void;
|
|
64
|
+
|
|
65
|
+
/** Moves playback to a point on the clock. */
|
|
66
|
+
seekTo(timeMs: number): void;
|
|
67
|
+
|
|
68
|
+
/** Moves playback to the start of a chapter. */
|
|
69
|
+
goToChapter(chapterIndex: number): void;
|
|
70
|
+
|
|
71
|
+
/** Restarts the current chapter, or goes back one when barely into it. */
|
|
72
|
+
goToPreviousChapter(): void;
|
|
73
|
+
|
|
74
|
+
/** Skips to the next chapter. */
|
|
75
|
+
goToNextChapter(): void;
|
|
76
|
+
|
|
77
|
+
/** Switches the voice-over on or off. */
|
|
78
|
+
toggleAudio(): void;
|
|
79
|
+
|
|
80
|
+
/** Switches subtitles on or off. */
|
|
81
|
+
toggleSubtitles(): void;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Runs the guided tour: advances one clock, and keeps the voice-over pointed at whatever the clock says is
|
|
86
|
+
* being narrated.
|
|
87
|
+
* @param sections The scripted sections to play.
|
|
88
|
+
* @returns The {@link TourPlayback} controls and state.
|
|
89
|
+
* @remarks
|
|
90
|
+
* The clock is the single source of truth — subtitles, progress, chapter highlighting and how much of the
|
|
91
|
+
* tour's stage is showing are all read from it, so seeking anywhere is consistent by construction. Pacing
|
|
92
|
+
* follows the schedule, with two adjustments at the boundaries where the schedule and the voice disagree
|
|
93
|
+
* (see {@link advanceTourClock}): a line finishing ahead of its step's estimate skips the leftover dead air,
|
|
94
|
+
* and a line still being said as the estimate runs out holds the clock at the step's end until it finishes —
|
|
95
|
+
* bounded, so a voice that never finishes cannot stall the whole tour. Whatever is playing is always
|
|
96
|
+
* silenced the moment the step it belongs to is left, whichever direction that happens in.
|
|
97
|
+
*/
|
|
98
|
+
export function useTourPlayback<TStep extends TourStep>(sections: TourSection<TStep>[]): TourPlayback<TStep> {
|
|
99
|
+
const timeline = useMemo(() => buildTourTimeline(sections), [sections]);
|
|
100
|
+
const [timeMs, setTimeState] = useState(0);
|
|
101
|
+
// The clock's position, readable by the ticker without going through a state updater: an updater must not have
|
|
102
|
+
// side effects, and the tick has one - it ends playback when the tour reaches its end.
|
|
103
|
+
const timeMsRef = useRef(0);
|
|
104
|
+
const setTimeMs = useCallback((next: number | ((current: number) => number)) => {
|
|
105
|
+
timeMsRef.current = typeof next === 'function' ? next(timeMsRef.current) : next;
|
|
106
|
+
setTimeState(timeMsRef.current);
|
|
107
|
+
}, []);
|
|
108
|
+
const [isPlaying, setIsPlaying] = useState(true);
|
|
109
|
+
const [isAudioEnabled, setIsAudioEnabled] = useState(true);
|
|
110
|
+
const [areSubtitlesEnabled, setAreSubtitlesEnabled] = useState(true);
|
|
111
|
+
const [hasNarrationFailed, setHasNarrationFailed] = useState(false);
|
|
112
|
+
const { useSpeech } = useCueConfiguration();
|
|
113
|
+
const { isAvailable: isSpeechAvailable, isPreparing, isSpeaking, hasError: hasSpeechError, speak, prefetch, stop } = useSpeech();
|
|
114
|
+
|
|
115
|
+
const stepIndex = stepIndexAtTime(timeline, timeMs);
|
|
116
|
+
const step = stepIndex >= 0 ? timeline.steps[stepIndex].step : undefined;
|
|
117
|
+
const chapterIndex = chapterIndexAtTime(timeline, timeMs);
|
|
118
|
+
const sectionIndex = sectionIndexAtTime(timeline, timeMs);
|
|
119
|
+
|
|
120
|
+
// Which step the voice has already been given. Reset to nothing whenever playback jumps or is silenced,
|
|
121
|
+
// so resuming or seeking back always speaks the line again rather than sitting through it in silence.
|
|
122
|
+
const narratedStepRef = useRef(-1);
|
|
123
|
+
|
|
124
|
+
// The narration currently being watched for completion: set when a line is handed to the voice, marked
|
|
125
|
+
// started once audio is actually being prepared or spoken, and cleared once it is known to have ended.
|
|
126
|
+
// Refs rather than state — nothing here needs to trigger its own render.
|
|
127
|
+
const pendingNarrationRef = useRef<{ stepIndex: number; started: boolean } | null>(null);
|
|
128
|
+
const narrationFinishedRef = useRef<{ stepIndex: number; finishedAt: number } | null>(null);
|
|
129
|
+
const narrationHoldRef = useRef<number | null>(null);
|
|
130
|
+
|
|
131
|
+
useEffect(() => {
|
|
132
|
+
if (!isPlaying) return;
|
|
133
|
+
|
|
134
|
+
let previous = performance.now();
|
|
135
|
+
const ticker = setInterval(() => {
|
|
136
|
+
const now = performance.now();
|
|
137
|
+
const elapsed = now - previous;
|
|
138
|
+
previous = now;
|
|
139
|
+
const advance = advanceTourClock(timeline, timeMsRef.current, elapsed, now, {
|
|
140
|
+
pendingStepIndex: pendingNarrationRef.current?.stepIndex ?? null,
|
|
141
|
+
finished: narrationFinishedRef.current,
|
|
142
|
+
holdStartedAt: narrationHoldRef.current,
|
|
143
|
+
});
|
|
144
|
+
narrationHoldRef.current = advance.holdStartedAt;
|
|
145
|
+
if (advance.finishedConsumed) {
|
|
146
|
+
narrationFinishedRef.current = null;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
setTimeMs(advance.timeMs);
|
|
150
|
+
if (!advance.isPlaying) {
|
|
151
|
+
setIsPlaying(false);
|
|
152
|
+
}
|
|
153
|
+
}, TICK_MS);
|
|
154
|
+
|
|
155
|
+
return () => clearInterval(ticker);
|
|
156
|
+
}, [isPlaying, timeline, setTimeMs]);
|
|
157
|
+
|
|
158
|
+
useEffect(() => {
|
|
159
|
+
if (!isPlaying || !isAudioEnabled || !isSpeechAvailable) {
|
|
160
|
+
narratedStepRef.current = -1;
|
|
161
|
+
pendingNarrationRef.current = null;
|
|
162
|
+
narrationFinishedRef.current = null;
|
|
163
|
+
narrationHoldRef.current = null;
|
|
164
|
+
stop();
|
|
165
|
+
return;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
if (narratedStepRef.current === stepIndex) return;
|
|
169
|
+
narratedStepRef.current = stepIndex;
|
|
170
|
+
|
|
171
|
+
narrationFinishedRef.current = null;
|
|
172
|
+
const narration = stepIndex >= 0 ? timeline.steps[stepIndex].step.narration : '';
|
|
173
|
+
if (narration.length > 0) {
|
|
174
|
+
pendingNarrationRef.current = { stepIndex, started: false };
|
|
175
|
+
|
|
176
|
+
// speak() tears down whatever the voice was still saying for the step just left, before
|
|
177
|
+
// starting this step's line — leaving a step always silences it, never lets it bleed forward.
|
|
178
|
+
void speak(narration);
|
|
179
|
+
} else {
|
|
180
|
+
// A silent, camera-only step — nothing to say, but anything still playing from the step before
|
|
181
|
+
// it must be cut off rather than left to talk over a scene it no longer belongs to.
|
|
182
|
+
pendingNarrationRef.current = null;
|
|
183
|
+
stop();
|
|
184
|
+
}
|
|
185
|
+
}, [isPlaying, isAudioEnabled, isSpeechAvailable, stepIndex, timeline, speak, stop]);
|
|
186
|
+
|
|
187
|
+
// Asks the voice for the lines still to come while the current one is being said, so each starts the moment its
|
|
188
|
+
// step does instead of waiting for the speech service. The current line goes first: nothing is requested until it
|
|
189
|
+
// is audible, so the lookahead never competes with the line the viewer is waiting for.
|
|
190
|
+
useEffect(() => {
|
|
191
|
+
if (!isPlaying || !isAudioEnabled || !isSpeechAvailable || stepIndex < 0) return;
|
|
192
|
+
|
|
193
|
+
// The line being waited for has been handed to the voice but is not audible yet: ask for nothing else.
|
|
194
|
+
const pending = pendingNarrationRef.current;
|
|
195
|
+
if (pending && (!pending.started || isPreparing)) return;
|
|
196
|
+
|
|
197
|
+
for (const narration of narrationsAfter(timeline, stepIndex, NARRATION_LOOKAHEAD_STEPS)) prefetch(narration);
|
|
198
|
+
}, [isPlaying, isAudioEnabled, isSpeechAvailable, isPreparing, stepIndex, timeline, prefetch]);
|
|
199
|
+
|
|
200
|
+
// Watches the voice to notice when the pending line has finished. "Finished" is a transition — the line
|
|
201
|
+
// must have been heard preparing or speaking before silence counts as its end, otherwise the quiet moment
|
|
202
|
+
// between asking for a clip and the first audio arriving would be mistaken for completion.
|
|
203
|
+
useEffect(() => {
|
|
204
|
+
const pending = pendingNarrationRef.current;
|
|
205
|
+
if (!pending) return;
|
|
206
|
+
|
|
207
|
+
if (isPreparing || isSpeaking) {
|
|
208
|
+
pending.started = true;
|
|
209
|
+
return;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
if (pending.started) {
|
|
213
|
+
pendingNarrationRef.current = null;
|
|
214
|
+
narrationFinishedRef.current = { stepIndex: pending.stepIndex, finishedAt: performance.now() };
|
|
215
|
+
}
|
|
216
|
+
}, [isPreparing, isSpeaking]);
|
|
217
|
+
|
|
218
|
+
// A failing voice-over must not make the tour silently silent: switch the audio toggle off so the
|
|
219
|
+
// transport shows what happened, and make sure subtitles are on so the words still reach the viewer.
|
|
220
|
+
// The clock keeps running throughout — narration failing never stalls the tour.
|
|
221
|
+
useEffect(() => {
|
|
222
|
+
if (!hasSpeechError || !isAudioEnabled) return;
|
|
223
|
+
|
|
224
|
+
setHasNarrationFailed(true);
|
|
225
|
+
setIsAudioEnabled(false);
|
|
226
|
+
setAreSubtitlesEnabled(true);
|
|
227
|
+
}, [hasSpeechError, isAudioEnabled]);
|
|
228
|
+
|
|
229
|
+
const seekTo = useCallback((target: number) => {
|
|
230
|
+
narratedStepRef.current = -1;
|
|
231
|
+
pendingNarrationRef.current = null;
|
|
232
|
+
narrationFinishedRef.current = null;
|
|
233
|
+
narrationHoldRef.current = null;
|
|
234
|
+
setTimeMs(Math.min(Math.max(0, target), timeline.durationMs));
|
|
235
|
+
}, [timeline.durationMs, setTimeMs]);
|
|
236
|
+
|
|
237
|
+
const isPlayingRef = useRef(isPlaying);
|
|
238
|
+
isPlayingRef.current = isPlaying;
|
|
239
|
+
const togglePlay = useCallback(() => {
|
|
240
|
+
// Pressing play at the very end starts over rather than doing nothing, which is what a finished
|
|
241
|
+
// video does and what someone reaching for the button after it ends is asking for.
|
|
242
|
+
if (!isPlayingRef.current) {
|
|
243
|
+
if (timeMsRef.current >= timeline.durationMs) setTimeMs(0);
|
|
244
|
+
narratedStepRef.current = -1;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
setIsPlaying(!isPlayingRef.current);
|
|
248
|
+
}, [timeline.durationMs, setTimeMs]);
|
|
249
|
+
|
|
250
|
+
const pause = useCallback(() => setIsPlaying(false), []);
|
|
251
|
+
|
|
252
|
+
const goToChapter = useCallback((target: number) => seekTo(chapterStartMs(timeline, target)), [seekTo, timeline]);
|
|
253
|
+
const goToPreviousChapter = useCallback(() => seekTo(previousChapterTargetMs(timeline, timeMs)), [seekTo, timeline, timeMs]);
|
|
254
|
+
const goToNextChapter = useCallback(() => seekTo(nextChapterTargetMs(timeline, timeMs)), [seekTo, timeline, timeMs]);
|
|
255
|
+
|
|
256
|
+
// Turning the voice-over back on is also how a failed narration is retried, so the failure flag clears
|
|
257
|
+
// and the current line is spoken afresh.
|
|
258
|
+
const isAudioEnabledRef = useRef(isAudioEnabled);
|
|
259
|
+
isAudioEnabledRef.current = isAudioEnabled;
|
|
260
|
+
const toggleAudio = useCallback(() => {
|
|
261
|
+
if (!isAudioEnabledRef.current) {
|
|
262
|
+
setHasNarrationFailed(false);
|
|
263
|
+
narratedStepRef.current = -1;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
setIsAudioEnabled(!isAudioEnabledRef.current);
|
|
267
|
+
}, []);
|
|
268
|
+
|
|
269
|
+
const toggleSubtitles = useCallback(() => setAreSubtitlesEnabled(current => !current), []);
|
|
270
|
+
|
|
271
|
+
return {
|
|
272
|
+
timeline,
|
|
273
|
+
timeMs,
|
|
274
|
+
isPlaying,
|
|
275
|
+
isAudioEnabled,
|
|
276
|
+
areSubtitlesEnabled,
|
|
277
|
+
isSpeechAvailable,
|
|
278
|
+
hasNarrationFailed,
|
|
279
|
+
step,
|
|
280
|
+
chapterIndex,
|
|
281
|
+
sectionIndex,
|
|
282
|
+
togglePlay,
|
|
283
|
+
pause,
|
|
284
|
+
seekTo,
|
|
285
|
+
goToChapter,
|
|
286
|
+
goToPreviousChapter,
|
|
287
|
+
goToNextChapter,
|
|
288
|
+
toggleAudio,
|
|
289
|
+
toggleSubtitles,
|
|
290
|
+
};
|
|
291
|
+
}
|