@cratis/showrunner.cue.react 0.0.0-stage → 2.10.0

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.
Files changed (417) hide show
  1. package/.storybook/main.ts +11 -0
  2. package/.storybook/preview.tsx +21 -0
  3. package/Configuration/CueConfiguration.ts +27 -0
  4. package/Configuration/CueProvider.tsx +64 -0
  5. package/Configuration/CueStageBoundary.tsx +37 -0
  6. package/Configuration/index.ts +6 -0
  7. package/Icons.tsx +36 -0
  8. package/Labels/CueLabels.ts +39 -0
  9. package/Labels/defaultCueLabels.ts +23 -0
  10. package/Labels/index.ts +6 -0
  11. package/Labels/resolveLabels.ts +12 -0
  12. package/Markdown/CueMarkdown.tsx +31 -0
  13. package/Markdown/index.ts +5 -0
  14. package/Markdown/safeUrl.ts +29 -0
  15. package/README.md +54 -2
  16. package/Speech/CueSpeech.ts +27 -0
  17. package/Speech/CueSpeechConfiguration.ts +21 -0
  18. package/Speech/HttpSpeechOptions.ts +37 -0
  19. package/Speech/createHttpSpeech.ts +135 -0
  20. package/Speech/index.ts +7 -0
  21. package/Speech/silentSpeech.ts +15 -0
  22. package/Speech/speechClips.ts +66 -0
  23. package/TourAnchor.tsx +162 -0
  24. package/TourAnchorSpace.ts +15 -0
  25. package/TourCallout.ts +22 -0
  26. package/TourCalloutBubble.tsx +38 -0
  27. package/TourCamera.ts +17 -0
  28. package/TourChapter.ts +24 -0
  29. package/TourChapterList.tsx +65 -0
  30. package/TourGesture.ts +30 -0
  31. package/TourOverlayShell.tsx +102 -0
  32. package/TourPointer.tsx +83 -0
  33. package/TourSection.ts +24 -0
  34. package/TourSelfPacedPanel.tsx +26 -0
  35. package/TourStep.ts +40 -0
  36. package/TourSubtitles.tsx +22 -0
  37. package/TourTimelineBar.tsx +127 -0
  38. package/Tours/index.ts +5 -0
  39. package/Tours/useCueTours.ts +63 -0
  40. package/Tours/useTourNudge.ts +37 -0
  41. package/cursorSvg.ts +12 -0
  42. package/dist/cjs/Configuration/CueConfiguration.d.ts +11 -0
  43. package/dist/cjs/Configuration/CueConfiguration.d.ts.map +1 -0
  44. package/dist/cjs/Configuration/CueProvider.d.ts +19 -0
  45. package/dist/cjs/Configuration/CueProvider.d.ts.map +1 -0
  46. package/dist/cjs/Configuration/CueProvider.js +44 -0
  47. package/dist/cjs/Configuration/CueProvider.js.map +1 -0
  48. package/dist/cjs/Configuration/CueStageBoundary.d.ts +14 -0
  49. package/dist/cjs/Configuration/CueStageBoundary.d.ts.map +1 -0
  50. package/dist/cjs/Configuration/CueStageBoundary.js +45 -0
  51. package/dist/cjs/Configuration/CueStageBoundary.js.map +1 -0
  52. package/dist/cjs/Configuration/index.d.ts +4 -0
  53. package/dist/cjs/Configuration/index.d.ts.map +1 -0
  54. package/dist/cjs/Examples/AppShell.d.ts +5 -0
  55. package/dist/cjs/Examples/AppShell.d.ts.map +1 -0
  56. package/dist/cjs/Examples/LocalizedCue.d.ts +5 -0
  57. package/dist/cjs/Examples/LocalizedCue.d.ts.map +1 -0
  58. package/dist/cjs/Examples/OrderDeskTour.d.ts +2 -0
  59. package/dist/cjs/Examples/OrderDeskTour.d.ts.map +1 -0
  60. package/dist/cjs/Examples/OwnStageGuard.d.ts +5 -0
  61. package/dist/cjs/Examples/OwnStageGuard.d.ts.map +1 -0
  62. package/dist/cjs/Examples/OwnVoice.d.ts +3 -0
  63. package/dist/cjs/Examples/OwnVoice.d.ts.map +1 -0
  64. package/dist/cjs/Icons.d.ts +19 -0
  65. package/dist/cjs/Icons.d.ts.map +1 -0
  66. package/dist/cjs/Icons.js +33 -0
  67. package/dist/cjs/Icons.js.map +1 -0
  68. package/dist/cjs/Labels/CueLabels.d.ts +18 -0
  69. package/dist/cjs/Labels/CueLabels.d.ts.map +1 -0
  70. package/dist/cjs/Labels/defaultCueLabels.d.ts +3 -0
  71. package/dist/cjs/Labels/defaultCueLabels.d.ts.map +1 -0
  72. package/dist/cjs/Labels/defaultCueLabels.js +24 -0
  73. package/dist/cjs/Labels/defaultCueLabels.js.map +1 -0
  74. package/dist/cjs/Labels/index.d.ts +4 -0
  75. package/dist/cjs/Labels/index.d.ts.map +1 -0
  76. package/dist/cjs/Labels/resolveLabels.d.ts +3 -0
  77. package/dist/cjs/Labels/resolveLabels.d.ts.map +1 -0
  78. package/dist/cjs/Labels/resolveLabels.js +17 -0
  79. package/dist/cjs/Labels/resolveLabels.js.map +1 -0
  80. package/dist/cjs/Markdown/CueMarkdown.d.ts +6 -0
  81. package/dist/cjs/Markdown/CueMarkdown.d.ts.map +1 -0
  82. package/dist/cjs/Markdown/CueMarkdown.js +34 -0
  83. package/dist/cjs/Markdown/CueMarkdown.js.map +1 -0
  84. package/dist/cjs/Markdown/index.d.ts +3 -0
  85. package/dist/cjs/Markdown/index.d.ts.map +1 -0
  86. package/dist/cjs/Markdown/safeUrl.d.ts +2 -0
  87. package/dist/cjs/Markdown/safeUrl.d.ts.map +1 -0
  88. package/dist/cjs/Markdown/safeUrl.js +34 -0
  89. package/dist/cjs/Markdown/safeUrl.js.map +1 -0
  90. package/dist/cjs/Speech/CueSpeech.d.ts +10 -0
  91. package/dist/cjs/Speech/CueSpeech.d.ts.map +1 -0
  92. package/dist/cjs/Speech/CueSpeechConfiguration.d.ts +6 -0
  93. package/dist/cjs/Speech/CueSpeechConfiguration.d.ts.map +1 -0
  94. package/dist/cjs/Speech/HttpSpeechOptions.d.ts +10 -0
  95. package/dist/cjs/Speech/HttpSpeechOptions.d.ts.map +1 -0
  96. package/dist/cjs/Speech/createHttpSpeech.d.ts +4 -0
  97. package/dist/cjs/Speech/createHttpSpeech.d.ts.map +1 -0
  98. package/dist/cjs/Speech/createHttpSpeech.js +140 -0
  99. package/dist/cjs/Speech/createHttpSpeech.js.map +1 -0
  100. package/dist/cjs/Speech/index.d.ts +5 -0
  101. package/dist/cjs/Speech/index.d.ts.map +1 -0
  102. package/dist/cjs/Speech/silentSpeech.d.ts +3 -0
  103. package/dist/cjs/Speech/silentSpeech.d.ts.map +1 -0
  104. package/dist/cjs/Speech/silentSpeech.js +16 -0
  105. package/dist/cjs/Speech/silentSpeech.js.map +1 -0
  106. package/dist/cjs/Speech/speechClips.d.ts +7 -0
  107. package/dist/cjs/Speech/speechClips.d.ts.map +1 -0
  108. package/dist/cjs/Speech/speechClips.js +60 -0
  109. package/dist/cjs/Speech/speechClips.js.map +1 -0
  110. package/dist/cjs/TourAnchor.d.ts +14 -0
  111. package/dist/cjs/TourAnchor.d.ts.map +1 -0
  112. package/dist/cjs/TourAnchor.js +150 -0
  113. package/dist/cjs/TourAnchor.js.map +1 -0
  114. package/dist/cjs/TourAnchorSpace.d.ts +2 -0
  115. package/dist/cjs/TourAnchorSpace.d.ts.map +1 -0
  116. package/dist/cjs/TourCallout.d.ts +8 -0
  117. package/dist/cjs/TourCallout.d.ts.map +1 -0
  118. package/dist/cjs/TourCalloutBubble.d.ts +9 -0
  119. package/dist/cjs/TourCalloutBubble.d.ts.map +1 -0
  120. package/dist/cjs/TourCalloutBubble.js +27 -0
  121. package/dist/cjs/TourCalloutBubble.js.map +1 -0
  122. package/dist/cjs/TourCamera.d.ts +6 -0
  123. package/dist/cjs/TourCamera.d.ts.map +1 -0
  124. package/dist/cjs/TourChapter.d.ts +8 -0
  125. package/dist/cjs/TourChapter.d.ts.map +1 -0
  126. package/dist/cjs/TourChapterList.d.ts +10 -0
  127. package/dist/cjs/TourChapterList.d.ts.map +1 -0
  128. package/dist/cjs/TourChapterList.js +68 -0
  129. package/dist/cjs/TourChapterList.js.map +1 -0
  130. package/dist/cjs/TourChapterList.stories.d.ts +21 -0
  131. package/dist/cjs/TourChapterList.stories.d.ts.map +1 -0
  132. package/dist/cjs/TourGesture.d.ts +12 -0
  133. package/dist/cjs/TourGesture.d.ts.map +1 -0
  134. package/dist/cjs/TourOverlayShell.d.ts +13 -0
  135. package/dist/cjs/TourOverlayShell.d.ts.map +1 -0
  136. package/dist/cjs/TourOverlayShell.js +77 -0
  137. package/dist/cjs/TourOverlayShell.js.map +1 -0
  138. package/dist/cjs/TourPointer.d.ts +9 -0
  139. package/dist/cjs/TourPointer.d.ts.map +1 -0
  140. package/dist/cjs/TourPointer.js +74 -0
  141. package/dist/cjs/TourPointer.js.map +1 -0
  142. package/dist/cjs/TourSection.d.ts +8 -0
  143. package/dist/cjs/TourSection.d.ts.map +1 -0
  144. package/dist/cjs/TourSelfPacedPanel.d.ts +6 -0
  145. package/dist/cjs/TourSelfPacedPanel.d.ts.map +1 -0
  146. package/dist/cjs/TourSelfPacedPanel.js +27 -0
  147. package/dist/cjs/TourSelfPacedPanel.js.map +1 -0
  148. package/dist/cjs/TourSelfPacedPanel.stories.d.ts +21 -0
  149. package/dist/cjs/TourSelfPacedPanel.stories.d.ts.map +1 -0
  150. package/dist/cjs/TourStep.d.ts +12 -0
  151. package/dist/cjs/TourStep.d.ts.map +1 -0
  152. package/dist/cjs/TourSubtitles.d.ts +5 -0
  153. package/dist/cjs/TourSubtitles.d.ts.map +1 -0
  154. package/dist/cjs/TourSubtitles.js +24 -0
  155. package/dist/cjs/TourSubtitles.js.map +1 -0
  156. package/dist/cjs/TourTimelineBar.d.ts +10 -0
  157. package/dist/cjs/TourTimelineBar.d.ts.map +1 -0
  158. package/dist/cjs/TourTimelineBar.js +134 -0
  159. package/dist/cjs/TourTimelineBar.js.map +1 -0
  160. package/dist/cjs/TourTimelineBar.stories.d.ts +24 -0
  161. package/dist/cjs/TourTimelineBar.stories.d.ts.map +1 -0
  162. package/dist/cjs/Tours/index.d.ts +3 -0
  163. package/dist/cjs/Tours/index.d.ts.map +1 -0
  164. package/dist/cjs/Tours/useCueTours.d.ts +7 -0
  165. package/dist/cjs/Tours/useCueTours.d.ts.map +1 -0
  166. package/dist/cjs/Tours/useCueTours.js +46 -0
  167. package/dist/cjs/Tours/useCueTours.js.map +1 -0
  168. package/dist/cjs/Tours/useTourNudge.d.ts +6 -0
  169. package/dist/cjs/Tours/useTourNudge.d.ts.map +1 -0
  170. package/dist/cjs/Tours/useTourNudge.js +28 -0
  171. package/dist/cjs/Tours/useTourNudge.js.map +1 -0
  172. package/dist/cjs/cursorSvg.d.ts +2 -0
  173. package/dist/cjs/cursorSvg.d.ts.map +1 -0
  174. package/dist/cjs/cursorSvg.js +15 -0
  175. package/dist/cjs/cursorSvg.js.map +1 -0
  176. package/dist/cjs/index.d.ts +41 -0
  177. package/dist/cjs/index.d.ts.map +1 -0
  178. package/dist/cjs/index.js +72 -0
  179. package/dist/cjs/index.js.map +1 -0
  180. package/dist/cjs/package.json +3 -0
  181. package/dist/cjs/tourClock.d.ts +19 -0
  182. package/dist/cjs/tourClock.d.ts.map +1 -0
  183. package/dist/cjs/tourClock.js +107 -0
  184. package/dist/cjs/tourClock.js.map +1 -0
  185. package/dist/cjs/tourGeometry.d.ts +18 -0
  186. package/dist/cjs/tourGeometry.d.ts.map +1 -0
  187. package/dist/cjs/tourGeometry.js +86 -0
  188. package/dist/cjs/tourGeometry.js.map +1 -0
  189. package/dist/cjs/tourSelfPaced.d.ts +12 -0
  190. package/dist/cjs/tourSelfPaced.d.ts.map +1 -0
  191. package/dist/cjs/tourSelfPaced.js +69 -0
  192. package/dist/cjs/tourSelfPaced.js.map +1 -0
  193. package/dist/cjs/tourTimeline.d.ts +40 -0
  194. package/dist/cjs/tourTimeline.d.ts.map +1 -0
  195. package/dist/cjs/tourTimeline.js +168 -0
  196. package/dist/cjs/tourTimeline.js.map +1 -0
  197. package/dist/cjs/useTourPlayback.d.ts +25 -0
  198. package/dist/cjs/useTourPlayback.d.ts.map +1 -0
  199. package/dist/cjs/useTourPlayback.js +245 -0
  200. package/dist/cjs/useTourPlayback.js.map +1 -0
  201. package/dist/esm/Configuration/CueConfiguration.d.ts +11 -0
  202. package/dist/esm/Configuration/CueConfiguration.d.ts.map +1 -0
  203. package/dist/esm/Configuration/CueConfiguration.js +2 -0
  204. package/dist/esm/Configuration/CueConfiguration.js.map +1 -0
  205. package/dist/esm/Configuration/CueProvider.d.ts +19 -0
  206. package/dist/esm/Configuration/CueProvider.d.ts.map +1 -0
  207. package/dist/esm/Configuration/CueProvider.js +41 -0
  208. package/dist/esm/Configuration/CueProvider.js.map +1 -0
  209. package/dist/esm/Configuration/CueStageBoundary.d.ts +14 -0
  210. package/dist/esm/Configuration/CueStageBoundary.d.ts.map +1 -0
  211. package/dist/esm/Configuration/CueStageBoundary.js +43 -0
  212. package/dist/esm/Configuration/CueStageBoundary.js.map +1 -0
  213. package/dist/esm/Configuration/index.d.ts +4 -0
  214. package/dist/esm/Configuration/index.d.ts.map +1 -0
  215. package/dist/esm/Configuration/index.js +4 -0
  216. package/dist/esm/Configuration/index.js.map +1 -0
  217. package/dist/esm/Examples/AppShell.d.ts +5 -0
  218. package/dist/esm/Examples/AppShell.d.ts.map +1 -0
  219. package/dist/esm/Examples/AppShell.js +10 -0
  220. package/dist/esm/Examples/AppShell.js.map +1 -0
  221. package/dist/esm/Examples/LocalizedCue.d.ts +5 -0
  222. package/dist/esm/Examples/LocalizedCue.d.ts.map +1 -0
  223. package/dist/esm/Examples/LocalizedCue.js +11 -0
  224. package/dist/esm/Examples/LocalizedCue.js.map +1 -0
  225. package/dist/esm/Examples/OrderDeskTour.d.ts +2 -0
  226. package/dist/esm/Examples/OrderDeskTour.d.ts.map +1 -0
  227. package/dist/esm/Examples/OrderDeskTour.js +33 -0
  228. package/dist/esm/Examples/OrderDeskTour.js.map +1 -0
  229. package/dist/esm/Examples/OwnStageGuard.d.ts +5 -0
  230. package/dist/esm/Examples/OwnStageGuard.d.ts.map +1 -0
  231. package/dist/esm/Examples/OwnStageGuard.js +17 -0
  232. package/dist/esm/Examples/OwnStageGuard.js.map +1 -0
  233. package/dist/esm/Examples/OwnVoice.d.ts +3 -0
  234. package/dist/esm/Examples/OwnVoice.d.ts.map +1 -0
  235. package/dist/esm/Examples/OwnVoice.js +35 -0
  236. package/dist/esm/Examples/OwnVoice.js.map +1 -0
  237. package/dist/esm/Icons.d.ts +19 -0
  238. package/dist/esm/Icons.d.ts.map +1 -0
  239. package/dist/esm/Icons.js +31 -0
  240. package/dist/esm/Icons.js.map +1 -0
  241. package/dist/esm/Labels/CueLabels.d.ts +18 -0
  242. package/dist/esm/Labels/CueLabels.d.ts.map +1 -0
  243. package/dist/esm/Labels/CueLabels.js +2 -0
  244. package/dist/esm/Labels/CueLabels.js.map +1 -0
  245. package/dist/esm/Labels/defaultCueLabels.d.ts +3 -0
  246. package/dist/esm/Labels/defaultCueLabels.d.ts.map +1 -0
  247. package/dist/esm/Labels/defaultCueLabels.js +22 -0
  248. package/dist/esm/Labels/defaultCueLabels.js.map +1 -0
  249. package/dist/esm/Labels/index.d.ts +4 -0
  250. package/dist/esm/Labels/index.d.ts.map +1 -0
  251. package/dist/esm/Labels/index.js +4 -0
  252. package/dist/esm/Labels/index.js.map +1 -0
  253. package/dist/esm/Labels/resolveLabels.d.ts +3 -0
  254. package/dist/esm/Labels/resolveLabels.d.ts.map +1 -0
  255. package/dist/esm/Labels/resolveLabels.js +15 -0
  256. package/dist/esm/Labels/resolveLabels.js.map +1 -0
  257. package/dist/esm/Markdown/CueMarkdown.d.ts +6 -0
  258. package/dist/esm/Markdown/CueMarkdown.d.ts.map +1 -0
  259. package/dist/esm/Markdown/CueMarkdown.js +32 -0
  260. package/dist/esm/Markdown/CueMarkdown.js.map +1 -0
  261. package/dist/esm/Markdown/index.d.ts +3 -0
  262. package/dist/esm/Markdown/index.d.ts.map +1 -0
  263. package/dist/esm/Markdown/index.js +3 -0
  264. package/dist/esm/Markdown/index.js.map +1 -0
  265. package/dist/esm/Markdown/safeUrl.d.ts +2 -0
  266. package/dist/esm/Markdown/safeUrl.d.ts.map +1 -0
  267. package/dist/esm/Markdown/safeUrl.js +32 -0
  268. package/dist/esm/Markdown/safeUrl.js.map +1 -0
  269. package/dist/esm/Speech/CueSpeech.d.ts +10 -0
  270. package/dist/esm/Speech/CueSpeech.d.ts.map +1 -0
  271. package/dist/esm/Speech/CueSpeech.js +2 -0
  272. package/dist/esm/Speech/CueSpeech.js.map +1 -0
  273. package/dist/esm/Speech/CueSpeechConfiguration.d.ts +6 -0
  274. package/dist/esm/Speech/CueSpeechConfiguration.d.ts.map +1 -0
  275. package/dist/esm/Speech/CueSpeechConfiguration.js +2 -0
  276. package/dist/esm/Speech/CueSpeechConfiguration.js.map +1 -0
  277. package/dist/esm/Speech/HttpSpeechOptions.d.ts +10 -0
  278. package/dist/esm/Speech/HttpSpeechOptions.d.ts.map +1 -0
  279. package/dist/esm/Speech/HttpSpeechOptions.js +2 -0
  280. package/dist/esm/Speech/HttpSpeechOptions.js.map +1 -0
  281. package/dist/esm/Speech/createHttpSpeech.d.ts +4 -0
  282. package/dist/esm/Speech/createHttpSpeech.d.ts.map +1 -0
  283. package/dist/esm/Speech/createHttpSpeech.js +138 -0
  284. package/dist/esm/Speech/createHttpSpeech.js.map +1 -0
  285. package/dist/esm/Speech/index.d.ts +5 -0
  286. package/dist/esm/Speech/index.d.ts.map +1 -0
  287. package/dist/esm/Speech/index.js +5 -0
  288. package/dist/esm/Speech/index.js.map +1 -0
  289. package/dist/esm/Speech/silentSpeech.d.ts +3 -0
  290. package/dist/esm/Speech/silentSpeech.d.ts.map +1 -0
  291. package/dist/esm/Speech/silentSpeech.js +14 -0
  292. package/dist/esm/Speech/silentSpeech.js.map +1 -0
  293. package/dist/esm/Speech/speechClips.d.ts +7 -0
  294. package/dist/esm/Speech/speechClips.d.ts.map +1 -0
  295. package/dist/esm/Speech/speechClips.js +58 -0
  296. package/dist/esm/Speech/speechClips.js.map +1 -0
  297. package/dist/esm/TourAnchor.d.ts +14 -0
  298. package/dist/esm/TourAnchor.d.ts.map +1 -0
  299. package/dist/esm/TourAnchor.js +148 -0
  300. package/dist/esm/TourAnchor.js.map +1 -0
  301. package/dist/esm/TourAnchorSpace.d.ts +2 -0
  302. package/dist/esm/TourAnchorSpace.d.ts.map +1 -0
  303. package/dist/esm/TourAnchorSpace.js +2 -0
  304. package/dist/esm/TourAnchorSpace.js.map +1 -0
  305. package/dist/esm/TourCallout.d.ts +8 -0
  306. package/dist/esm/TourCallout.d.ts.map +1 -0
  307. package/dist/esm/TourCallout.js +2 -0
  308. package/dist/esm/TourCallout.js.map +1 -0
  309. package/dist/esm/TourCalloutBubble.d.ts +9 -0
  310. package/dist/esm/TourCalloutBubble.d.ts.map +1 -0
  311. package/dist/esm/TourCalloutBubble.js +25 -0
  312. package/dist/esm/TourCalloutBubble.js.map +1 -0
  313. package/dist/esm/TourCamera.d.ts +6 -0
  314. package/dist/esm/TourCamera.d.ts.map +1 -0
  315. package/dist/esm/TourCamera.js +2 -0
  316. package/dist/esm/TourCamera.js.map +1 -0
  317. package/dist/esm/TourChapter.d.ts +8 -0
  318. package/dist/esm/TourChapter.d.ts.map +1 -0
  319. package/dist/esm/TourChapter.js +2 -0
  320. package/dist/esm/TourChapter.js.map +1 -0
  321. package/dist/esm/TourChapterList.d.ts +10 -0
  322. package/dist/esm/TourChapterList.d.ts.map +1 -0
  323. package/dist/esm/TourChapterList.js +66 -0
  324. package/dist/esm/TourChapterList.js.map +1 -0
  325. package/dist/esm/TourChapterList.stories.d.ts +21 -0
  326. package/dist/esm/TourChapterList.stories.d.ts.map +1 -0
  327. package/dist/esm/TourChapterList.stories.js +53 -0
  328. package/dist/esm/TourChapterList.stories.js.map +1 -0
  329. package/dist/esm/TourGesture.d.ts +12 -0
  330. package/dist/esm/TourGesture.d.ts.map +1 -0
  331. package/dist/esm/TourGesture.js +2 -0
  332. package/dist/esm/TourGesture.js.map +1 -0
  333. package/dist/esm/TourOverlayShell.d.ts +13 -0
  334. package/dist/esm/TourOverlayShell.d.ts.map +1 -0
  335. package/dist/esm/TourOverlayShell.js +75 -0
  336. package/dist/esm/TourOverlayShell.js.map +1 -0
  337. package/dist/esm/TourPointer.d.ts +9 -0
  338. package/dist/esm/TourPointer.d.ts.map +1 -0
  339. package/dist/esm/TourPointer.js +72 -0
  340. package/dist/esm/TourPointer.js.map +1 -0
  341. package/dist/esm/TourSection.d.ts +8 -0
  342. package/dist/esm/TourSection.d.ts.map +1 -0
  343. package/dist/esm/TourSection.js +2 -0
  344. package/dist/esm/TourSection.js.map +1 -0
  345. package/dist/esm/TourSelfPacedPanel.d.ts +6 -0
  346. package/dist/esm/TourSelfPacedPanel.d.ts.map +1 -0
  347. package/dist/esm/TourSelfPacedPanel.js +25 -0
  348. package/dist/esm/TourSelfPacedPanel.js.map +1 -0
  349. package/dist/esm/TourSelfPacedPanel.stories.d.ts +21 -0
  350. package/dist/esm/TourSelfPacedPanel.stories.d.ts.map +1 -0
  351. package/dist/esm/TourSelfPacedPanel.stories.js +41 -0
  352. package/dist/esm/TourSelfPacedPanel.stories.js.map +1 -0
  353. package/dist/esm/TourStep.d.ts +12 -0
  354. package/dist/esm/TourStep.d.ts.map +1 -0
  355. package/dist/esm/TourStep.js +2 -0
  356. package/dist/esm/TourStep.js.map +1 -0
  357. package/dist/esm/TourSubtitles.d.ts +5 -0
  358. package/dist/esm/TourSubtitles.d.ts.map +1 -0
  359. package/dist/esm/TourSubtitles.js +22 -0
  360. package/dist/esm/TourSubtitles.js.map +1 -0
  361. package/dist/esm/TourTimelineBar.d.ts +10 -0
  362. package/dist/esm/TourTimelineBar.d.ts.map +1 -0
  363. package/dist/esm/TourTimelineBar.js +132 -0
  364. package/dist/esm/TourTimelineBar.js.map +1 -0
  365. package/dist/esm/TourTimelineBar.stories.d.ts +24 -0
  366. package/dist/esm/TourTimelineBar.stories.d.ts.map +1 -0
  367. package/dist/esm/TourTimelineBar.stories.js +62 -0
  368. package/dist/esm/TourTimelineBar.stories.js.map +1 -0
  369. package/dist/esm/Tours/index.d.ts +3 -0
  370. package/dist/esm/Tours/index.d.ts.map +1 -0
  371. package/dist/esm/Tours/index.js +3 -0
  372. package/dist/esm/Tours/index.js.map +1 -0
  373. package/dist/esm/Tours/useCueTours.d.ts +7 -0
  374. package/dist/esm/Tours/useCueTours.d.ts.map +1 -0
  375. package/dist/esm/Tours/useCueTours.js +44 -0
  376. package/dist/esm/Tours/useCueTours.js.map +1 -0
  377. package/dist/esm/Tours/useTourNudge.d.ts +6 -0
  378. package/dist/esm/Tours/useTourNudge.d.ts.map +1 -0
  379. package/dist/esm/Tours/useTourNudge.js +26 -0
  380. package/dist/esm/Tours/useTourNudge.js.map +1 -0
  381. package/dist/esm/cursorSvg.d.ts +2 -0
  382. package/dist/esm/cursorSvg.d.ts.map +1 -0
  383. package/dist/esm/cursorSvg.js +13 -0
  384. package/dist/esm/cursorSvg.js.map +1 -0
  385. package/dist/esm/index.d.ts +41 -0
  386. package/dist/esm/index.d.ts.map +1 -0
  387. package/dist/esm/index.js +24 -0
  388. package/dist/esm/index.js.map +1 -0
  389. package/dist/esm/package.json +3 -0
  390. package/dist/esm/tourClock.d.ts +19 -0
  391. package/dist/esm/tourClock.d.ts.map +1 -0
  392. package/dist/esm/tourClock.js +103 -0
  393. package/dist/esm/tourClock.js.map +1 -0
  394. package/dist/esm/tourGeometry.d.ts +18 -0
  395. package/dist/esm/tourGeometry.d.ts.map +1 -0
  396. package/dist/esm/tourGeometry.js +80 -0
  397. package/dist/esm/tourGeometry.js.map +1 -0
  398. package/dist/esm/tourSelfPaced.d.ts +12 -0
  399. package/dist/esm/tourSelfPaced.d.ts.map +1 -0
  400. package/dist/esm/tourSelfPaced.js +64 -0
  401. package/dist/esm/tourSelfPaced.js.map +1 -0
  402. package/dist/esm/tourTimeline.d.ts +40 -0
  403. package/dist/esm/tourTimeline.d.ts.map +1 -0
  404. package/dist/esm/tourTimeline.js +154 -0
  405. package/dist/esm/tourTimeline.js.map +1 -0
  406. package/dist/esm/useTourPlayback.d.ts +25 -0
  407. package/dist/esm/useTourPlayback.d.ts.map +1 -0
  408. package/dist/esm/useTourPlayback.js +243 -0
  409. package/dist/esm/useTourPlayback.js.map +1 -0
  410. package/index.ts +68 -0
  411. package/package.json +93 -4
  412. package/styles.css +485 -0
  413. package/tourClock.ts +125 -0
  414. package/tourGeometry.ts +95 -0
  415. package/tourSelfPaced.ts +93 -0
  416. package/tourTimeline.ts +237 -0
  417. package/useTourPlayback.ts +291 -0
@@ -0,0 +1,11 @@
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 { StorybookConfig } from '@storybook/react-vite';
5
+
6
+ const config: StorybookConfig = {
7
+ stories: ['../**/*.stories.tsx'],
8
+ framework: '@storybook/react-vite'
9
+ };
10
+
11
+ export default config;
@@ -0,0 +1,21 @@
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 { CratisComponentsProvider } from '@cratis/components';
5
+ import '@cratis/components/tokens';
6
+ import '@cratis/components/styles';
7
+ import '@cratis/components/theme';
8
+ import type { Preview } from '@storybook/react-vite';
9
+ import '../styles.css';
10
+
11
+ const preview: Preview = {
12
+ decorators: [
13
+ Story => (
14
+ <CratisComponentsProvider>
15
+ <Story />
16
+ </CratisComponentsProvider>
17
+ )
18
+ ]
19
+ };
20
+
21
+ export default preview;
@@ -0,0 +1,27 @@
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 { ComponentType, ReactNode } from 'react';
5
+ import type { CueLabels } from '../Labels/CueLabels.js';
6
+ import type { CueSpeechConfiguration } from '../Speech/CueSpeechConfiguration.js';
7
+
8
+ /**
9
+ * What an application tells Cue about itself, once, for every tour it plays.
10
+ */
11
+ export interface CueConfiguration {
12
+ /**
13
+ * Where the tour's voice-over comes from. Left out, the tours play silently with their subtitles, and the voice-over
14
+ * button says why there is none. See {@link createHttpSpeech} for a text-to-speech service reached over HTTP.
15
+ */
16
+ speech?: CueSpeechConfiguration;
17
+
18
+ /** The texts of the tour's own chrome, such as its buttons. The ones left out stay English. */
19
+ labels?: Partial<CueLabels>;
20
+
21
+ /**
22
+ * Guards the stage of a tour: the surface the tour draws. A tour that cannot draw its stage reports it, and the
23
+ * transport and the chapter list stay up so the viewer can still stop the tour or pick another chapter. Left out, a
24
+ * small panel with a Try again button is shown.
25
+ */
26
+ stageBoundary?: ComponentType<{ children: ReactNode }>;
27
+ }
@@ -0,0 +1,64 @@
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 React, { type ReactNode, createContext, useContext, useMemo } from 'react';
5
+ import { type CueLabels } from '../Labels/CueLabels.js';
6
+ import { resolveLabels } from '../Labels/resolveLabels.js';
7
+ import { CueStageBoundary } from './CueStageBoundary.js';
8
+ import type { CueConfiguration } from './CueConfiguration.js';
9
+ import type { ComponentType } from 'react';
10
+ import type { CueSpeech } from '../Speech/CueSpeech.js';
11
+ import { silentSpeech } from '../Speech/silentSpeech.js';
12
+
13
+ /** The configuration as the tour reads it: everything is there. */
14
+ export interface ResolvedCueConfiguration {
15
+ /** The hook that gives a tour its voice; a silent one when the tours play without a voice-over. */
16
+ useSpeech: () => CueSpeech;
17
+ /** Unlocks audio playback from a viewer's gesture; does nothing when there is no voice-over. */
18
+ unlockAudio: () => void;
19
+ /** Every text of the tour's chrome. */
20
+ labels: CueLabels;
21
+ /** What guards the stage of a tour. */
22
+ stageBoundary: ComponentType<{ children: ReactNode }>;
23
+ }
24
+
25
+ // A tour with no voice-over plays silently: there is no service, so nothing is ever said.
26
+ const useSilentSpeech = (): CueSpeech => silentSpeech;
27
+
28
+ const defaults: ResolvedCueConfiguration = {
29
+ useSpeech: useSilentSpeech,
30
+ unlockAudio: () => undefined,
31
+ labels: resolveLabels(),
32
+ stageBoundary: CueStageBoundary
33
+ };
34
+
35
+ const CueConfigurationContext = createContext<ResolvedCueConfiguration>(defaults);
36
+
37
+ /**
38
+ * Props for {@link CueProvider}.
39
+ */
40
+ export interface CueProviderProps extends CueConfiguration {
41
+ /** What the configuration applies to: the tours. */
42
+ children: ReactNode;
43
+ }
44
+
45
+ /**
46
+ * Tells the tours below it how to speak, what to call their buttons and how to guard their stage. Put it once near the
47
+ * root of the application; without it a tour plays silently, in English.
48
+ */
49
+ export const CueProvider = ({ speech, labels, stageBoundary, children }: CueProviderProps) => {
50
+ const value = useMemo<ResolvedCueConfiguration>(() => ({
51
+ useSpeech: speech?.useSpeech ?? useSilentSpeech,
52
+ unlockAudio: () => speech?.unlock?.(),
53
+ labels: resolveLabels(labels),
54
+ stageBoundary: stageBoundary ?? CueStageBoundary
55
+ }), [speech, labels, stageBoundary]);
56
+
57
+ return <CueConfigurationContext.Provider value={value}>{children}</CueConfigurationContext.Provider>;
58
+ };
59
+
60
+ /**
61
+ * Gets the configuration of the nearest {@link CueProvider}, or the defaults when there is none.
62
+ * @returns The {@link ResolvedCueConfiguration}.
63
+ */
64
+ export const useCueConfiguration = (): ResolvedCueConfiguration => useContext(CueConfigurationContext);
@@ -0,0 +1,37 @@
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 React, { Component, type ErrorInfo, type ReactNode } from 'react';
5
+
6
+ interface CueStageBoundaryState {
7
+ failed: boolean;
8
+ }
9
+
10
+ /**
11
+ * The guard of a tour's stage when the application brings none: a panel that says the tour could not be drawn, with a way
12
+ * to try again.
13
+ */
14
+ export class CueStageBoundary extends Component<{ children: ReactNode }, CueStageBoundaryState> {
15
+ state: CueStageBoundaryState = { failed: false };
16
+
17
+ static getDerivedStateFromError(): CueStageBoundaryState {
18
+ return { failed: true };
19
+ }
20
+
21
+ componentDidCatch(error: Error, info: ErrorInfo) {
22
+ console.error('The guided tour could not be drawn.', error, info.componentStack);
23
+ }
24
+
25
+ render() {
26
+ if (!this.state.failed) {
27
+ return this.props.children;
28
+ }
29
+
30
+ return (
31
+ <div className='cue-stage-failed' role='alert'>
32
+ <p>The guided tour could not be drawn.</p>
33
+ <button type='button' onClick={() => this.setState({ failed: false })}>Try again</button>
34
+ </div>
35
+ );
36
+ }
37
+ }
@@ -0,0 +1,6 @@
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
+ export * from './CueConfiguration.js';
5
+ export * from './CueProvider.js';
6
+ export * from './CueStageBoundary.js';
package/Icons.tsx ADDED
@@ -0,0 +1,36 @@
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 React from 'react';
5
+
6
+ const paths = {
7
+ previous: 'M6 6h2v12H6zm3.5 6l8.5 6V6z',
8
+ next: 'M6 18l8.5-6L6 6v12zM16 6v12h2V6h-2z',
9
+ play: 'M8 5v14l11-7z',
10
+ pause: 'M6 19h4V5H6v14zm8-14v14h4V5h-4z',
11
+ volumeOn: 'M3 9v6h4l5 5V4L7 9H3zm13.5 3A4.5 4.5 0 0 0 14 7.97v8.05c1.48-.73 2.5-2.25 2.5-4.02zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z',
12
+ volumeOff: 'M16.5 12A4.5 4.5 0 0 0 14 7.97v2.21l2.45 2.45c.03-.2.05-.41.05-.63zm2.5 0c0 .94-.2 1.82-.54 2.64l1.51 1.51A8.796 8.796 0 0 0 21 12c0-4.28-2.99-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71zM4.27 3L3 4.27 7.73 9H3v6h4l5 5v-6.73l4.25 4.25c-.67.52-1.42.93-2.25 1.18v2.06a8.99 8.99 0 0 0 3.69-1.81L19.73 21 21 19.73l-9-9L4.27 3zM12 4L9.91 6.09 12 8.18V4z',
13
+ subtitles: 'M20 4H4c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V6c0-1.1-.9-2-2-2zM4 12h4v2H4v-2zm10 6H4v-2h10v2zm6 0h-4v-2h4v2zm0-4H10v-2h10v2z',
14
+ book: 'M21 5c-1.11-.35-2.33-.5-3.5-.5-1.95 0-4.05.4-5.5 1.5-1.45-1.1-3.55-1.5-5.5-1.5S2.45 4.9 1 6v14.65c0 .25.25.5.5.5.1 0 .15-.05.25-.05C3.1 20.45 5.05 20 6.5 20c1.95 0 4.05.4 5.5 1.5 1.35-.85 3.8-1.5 5.5-1.5 1.65 0 3.35.3 4.75 1.05.1.05.15.05.25.05.25 0 .5-.25.5-.5V6c-.6-.45-1.25-.75-2-1zm0 13.5c-1.1-.35-2.3-.5-3.5-.5-1.7 0-4.15.65-5.5 1.5V8c1.35-.85 3.8-1.5 5.5-1.5 1.2 0 2.4.15 3.5.5v11.5z',
15
+ close: 'M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z'
16
+ } as const;
17
+
18
+ /** The icons of the tour's transport. */
19
+ export type CueIconName = keyof typeof paths;
20
+
21
+ /**
22
+ * Props for {@link CueIcon}.
23
+ */
24
+ export interface CueIconProps {
25
+ /** Which icon to draw. */
26
+ name: CueIconName;
27
+ }
28
+
29
+ /**
30
+ * An icon of the tour's transport. It is decoration: the button around it carries the name.
31
+ */
32
+ export const CueIcon = ({ name }: CueIconProps) => (
33
+ <svg className='cue-icon' viewBox='0 0 24 24' width='1em' height='1em' aria-hidden='true' focusable='false'>
34
+ <path fill='currentColor' d={paths[name]} />
35
+ </svg>
36
+ );
@@ -0,0 +1,39 @@
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 texts the tour's own chrome shows. Every one is a prop so an application can localize it. The words of a tour —
6
+ * its narration, its section and chapter titles — are the tour's content and are not here.
7
+ */
8
+ export interface CueLabels {
9
+ /** The button that closes the tour. */
10
+ close: string;
11
+ /** The button that starts playback. */
12
+ play: string;
13
+ /** The button that pauses playback. */
14
+ pause: string;
15
+ /** The button that goes back one chapter. */
16
+ previousChapter: string;
17
+ /** The button that skips to the next chapter. */
18
+ nextChapter: string;
19
+ /** The button that switches the voice-over off. */
20
+ muteNarration: string;
21
+ /** The button that switches the voice-over on. */
22
+ unmuteNarration: string;
23
+ /** The explanation shown in place of the voice-over button when no voice-over is available. */
24
+ narrationUnavailable: string;
25
+ /** The explanation shown in place of the voice-over button when the voice-over failed. Pressing the button retries it. */
26
+ narrationFailed: string;
27
+ /** The button that hides the subtitles. */
28
+ hideSubtitles: string;
29
+ /** The button that shows the subtitles. */
30
+ showSubtitles: string;
31
+ /** The button that switches to reading the tour at your own pace. */
32
+ readSelfPaced: string;
33
+ /** The button that goes back to the narrated tour from reading it at your own pace. */
34
+ resumeNarrated: string;
35
+ /** The heading of the chapter list. */
36
+ chapters: string;
37
+ /** The accessible name of the scrubber. */
38
+ progress: string;
39
+ }
@@ -0,0 +1,23 @@
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 { CueLabels } from './CueLabels.js';
5
+
6
+ /** The English texts, used for every label an application does not give. */
7
+ export const defaultCueLabels: CueLabels = {
8
+ close: 'Close the tour',
9
+ play: 'Play',
10
+ pause: 'Pause',
11
+ previousChapter: 'Previous chapter',
12
+ nextChapter: 'Next chapter',
13
+ muteNarration: 'Turn the voice-over off',
14
+ unmuteNarration: 'Turn the voice-over on',
15
+ narrationUnavailable: 'Voice-over is not available',
16
+ narrationFailed: 'Voice-over failed — subtitles carry on. Press to retry',
17
+ hideSubtitles: 'Hide subtitles',
18
+ showSubtitles: 'Show subtitles',
19
+ readSelfPaced: 'Read the tour at your own pace',
20
+ resumeNarrated: 'Return to the narrated tour',
21
+ chapters: 'Chapters',
22
+ progress: 'Tour progress'
23
+ };
@@ -0,0 +1,6 @@
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
+ export * from './CueLabels.js';
5
+ export * from './defaultCueLabels.js';
6
+ export * from './resolveLabels.js';
@@ -0,0 +1,12 @@
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 { defaultCueLabels } from './defaultCueLabels.js';
5
+ import type { CueLabels } from './CueLabels.js';
6
+
7
+ /**
8
+ * Overlays the texts an application gives on the English defaults.
9
+ * @param overrides The texts to replace; the rest stay English.
10
+ * @returns The texts to show.
11
+ */
12
+ export const resolveLabels = (overrides?: Partial<CueLabels>): CueLabels => ({ ...defaultCueLabels, ...overrides });
@@ -0,0 +1,31 @@
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 React, { type ComponentProps } from 'react';
5
+ import ReactMarkdown from 'react-markdown';
6
+ import { safeUrl } from './safeUrl.js';
7
+
8
+ /**
9
+ * Props for {@link CueMarkdown}.
10
+ */
11
+ export interface CueMarkdownProps {
12
+ /** The Markdown source of a chapter. */
13
+ source: string;
14
+ }
15
+
16
+ const Link = ({ href, title, children }: ComponentProps<'a'>) => href
17
+ ? <a href={href} title={title} target='_blank' rel='noopener noreferrer'>{children}</a>
18
+ : <span>{children}</span>;
19
+
20
+ /**
21
+ * Renders a chapter's Markdown as React elements, never as injected HTML: raw HTML in the source is dropped, a link opens
22
+ * in a new tab with `noopener noreferrer`, and an address that would run script is not an address at all. Screenshots and
23
+ * animations are kept, since a written chapter shows what the narration points at.
24
+ */
25
+ export const CueMarkdown = ({ source }: CueMarkdownProps) => (
26
+ <div className='cue-markdown'>
27
+ <ReactMarkdown skipHtml urlTransform={safeUrl} components={{ a: Link }}>
28
+ {source}
29
+ </ReactMarkdown>
30
+ </div>
31
+ );
@@ -0,0 +1,5 @@
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
+ export * from './CueMarkdown.js';
5
+ export * from './safeUrl.js';
@@ -0,0 +1,29 @@
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
+ const SAFE_PROTOCOLS = ['https:', 'http:', 'mailto:', 'tel:'];
5
+
6
+ /**
7
+ * Decides which address a piece of a chapter's Markdown may point at.
8
+ * @param url The address as written.
9
+ * @returns The address when it is safe to follow or show; an empty string when it is not.
10
+ * @remarks
11
+ * A tour's chapters are the application's own writing, but they are still rendered as elements and never as HTML, so an
12
+ * address that runs script is refused. Relative addresses, anchors, bundled images and `data:` images are fine.
13
+ */
14
+ export const safeUrl = (url: string): string => {
15
+ const trimmed = url.trim();
16
+ if (trimmed.length === 0) {
17
+ return '';
18
+ }
19
+
20
+ if (/^(\/|\.\/|\.\.\/|#|[^:]*$)/.test(trimmed) || /^data:image\/(png|gif|jpeg|webp|svg\+xml)[;,]/i.test(trimmed)) {
21
+ return trimmed;
22
+ }
23
+
24
+ try {
25
+ return SAFE_PROTOCOLS.includes(new URL(trimmed).protocol) ? trimmed : '';
26
+ } catch {
27
+ return '';
28
+ }
29
+ };
package/README.md CHANGED
@@ -1,3 +1,55 @@
1
- # Temporary Holding Version
1
+ # @cratis/showrunner.cue.react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The Cue guided-tour player for React, the Showrunner guided-tour part. A tour is a script of sections, chapters and steps;
4
+ the player lays it on one clock and plays it with a voice-over, subtitles, a chapter list, a pointer and callouts, and a
5
+ written version of each chapter. Built on `@cratis/components` and the generated proxies in `@cratis/showrunner.cue`.
6
+ How to use it: [Documentation/Cue](../../../Documentation/Cue/index.md).
7
+
8
+ ## Component hierarchy
9
+
10
+ ```
11
+ CueProvider speech, labels, stage guard for every tour below it
12
+ └── TourOverlayShell useTourPlayback, then the chrome and the application's stage
13
+ ├── <stage> drawn by the application, from the playback, inside the stage guard
14
+ ├── TourSelfPacedPanel written chapter, in self-paced mode
15
+ │ └── CueMarkdown
16
+ ├── TourChapterList
17
+ ├── TourSubtitles
18
+ └── TourTimelineBar transport: chapters, play, scrubber, voice, subtitles, self-paced, close
19
+ ```
20
+
21
+ `TourAnchor`, `TourPointer` and `TourCalloutBubble` are for the application's stage: they hold the pointer and the
22
+ callouts at a place on a board and follow the camera.
23
+
24
+ ## Architecture decisions
25
+
26
+ - **The script is data, the clock is the single source of truth.** `Tour*.ts` types describe the script; `tourTimeline.ts`
27
+ lays it on a clock; `tourClock.ts` decides how the clock advances against the voice. Subtitles, progress, the current
28
+ chapter and how much of the stage shows are all read from the clock.
29
+
30
+ | Module | Decides |
31
+ | --- | --- |
32
+ | `tourTimeline.ts` | where each step, chapter and section sits on the clock, and what comes next or before |
33
+ | `tourClock.ts` | how far the clock moves in a tick, when a line ends a step early and when it holds one |
34
+ | `tourSelfPaced.ts` | whether there is anything to read, which chapter's text, and the media addresses in it |
35
+ | `tourGeometry.ts` | where a point sits on screen, in each of the four spaces |
36
+ | `Speech/speechClips.ts` | which lines have been asked of the service, and which are kept |
37
+ | `Markdown/safeUrl.ts` | which addresses a chapter's Markdown may point at |
38
+
39
+ - **The voice is configured, never chosen.** The player talks to a `CueSpeech`; where the audio comes from is the
40
+ application's `CueSpeechConfiguration` on `CueProvider`. `createHttpSpeech` is one for a service reached over HTTP.
41
+ Without one a tour plays silently.
42
+ - **The stage belongs to the application.** The overlay calls a function for it and guards it on its own, so the
43
+ transport stays up when it fails.
44
+ - **Markdown is rendered as elements, never as HTML.** `react-markdown` with `skipHtml`; every address goes through
45
+ `safeUrl`.
46
+ - **Per-frame work stays out of React.** `TourAnchor` writes its position straight to the DOM from a self-suspending
47
+ frame loop; the clock ticks every 100 ms.
48
+ - **No MVVM, no UI framework beyond Cratis Components' tokens.** Every color comes from the `--cratis-*` tokens, and the
49
+ transport's icons are inline.
50
+
51
+ ## Examples and stories
52
+
53
+ `Examples/` holds the code shown in the documentation. It is compiled with the package, and a specification fails when a
54
+ documentation page no longer contains an example exactly as it builds. `yarn storybook` runs the stories of the chapter
55
+ list, the transport and the written-chapter panel, against a small made-up tour.
@@ -0,0 +1,27 @@
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 voice-over the tour plays through: what a text-to-speech service looks like to the tour. An application gives the
6
+ * tour one through {@link CueProvider}, either built for a service with {@link createHttpSpeech} or its own.
7
+ *
8
+ * The tour asks for a line to be spoken when its step begins, asks for the lines to come ahead of time, and watches
9
+ * the state to learn when a line has finished: a line has finished once it was heard preparing or speaking and neither
10
+ * is true any more. A voice that cannot be had is reported as an error and the tour carries on with its subtitles.
11
+ */
12
+ export interface CueSpeech {
13
+ /** Whether a text-to-speech service is available at all. */
14
+ isAvailable: boolean;
15
+ /** Whether a line is being prepared: from asking for it until audio starts playing. */
16
+ isPreparing: boolean;
17
+ /** Whether audio is playing. */
18
+ isSpeaking: boolean;
19
+ /** Whether the last line failed. Cleared when the next one starts. */
20
+ hasError: boolean;
21
+ /** Speaks a line, first silencing whatever was still being said. A line asked for ahead of time with {@link prefetch} starts at once. */
22
+ speak(text: string): Promise<void>;
23
+ /** Asks for a line ahead of time, so speaking it later does not wait for the service. */
24
+ prefetch(text: string): void;
25
+ /** Silences whatever is being said. */
26
+ stop(): void;
27
+ }
@@ -0,0 +1,21 @@
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 { CueSpeech } from './CueSpeech.js';
5
+
6
+ /**
7
+ * How the tour gets its voice-over. This is what an application configures: where the audio for a line comes from.
8
+ */
9
+ export interface CueSpeechConfiguration {
10
+ /**
11
+ * The hook that gives the tour its voice. It is called on every render of the tour in the same way, so it must be a
12
+ * stable function, never created during a render.
13
+ */
14
+ useSpeech: () => CueSpeech;
15
+
16
+ /**
17
+ * Called from the viewer's first gesture, such as pressing play, to unlock audio playback in browsers that
18
+ * only allow sound after one.
19
+ */
20
+ unlock?: () => void;
21
+ }
@@ -0,0 +1,37 @@
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
+ * Where the audio for a line comes from, for {@link createHttpSpeech}.
6
+ */
7
+ export interface HttpSpeechOptions {
8
+ /**
9
+ * The address that is sent a line and answers with audio the browser can play, such as an MP3. A line is sent with
10
+ * POST, as JSON: `{ "text": "..." }` unless {@link body} says otherwise.
11
+ */
12
+ speakUrl: string;
13
+
14
+ /**
15
+ * The address that is asked, with GET, whether speech is available, and answers `{ "available": true }`. Left out, speech
16
+ * is taken to be available and a failing line is reported as it happens.
17
+ */
18
+ availableUrl?: string;
19
+
20
+ /**
21
+ * Builds what is sent for a line, when the service wants more than the text: the voice, the speed, who is speaking.
22
+ * The voice of the tour is the application's to choose here, never the browser's to name.
23
+ */
24
+ body?: (text: string) => unknown;
25
+
26
+ /** The headers sent with every request, such as an API key. */
27
+ headers?: Record<string, string>;
28
+
29
+ /** Whether cookies go with the requests. Defaults to `include`, so a service behind the application's own sign-in works. */
30
+ credentials?: RequestCredentials;
31
+
32
+ /** How many lines are kept so speaking one again does not ask for it again. Defaults to 24. */
33
+ cacheSize?: number;
34
+
35
+ /** The fetch to use. Defaults to the browser's; a specification gives its own. */
36
+ fetch?: typeof fetch;
37
+ }
@@ -0,0 +1,135 @@
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, useRef, useState } from 'react';
5
+ import type { CueSpeech } from './CueSpeech.js';
6
+ import type { CueSpeechConfiguration } from './CueSpeechConfiguration.js';
7
+ import type { HttpSpeechOptions } from './HttpSpeechOptions.js';
8
+ import { createSpeechClips } from './speechClips.js';
9
+
10
+ // A tenth of a second of silence. Playing it from a gesture is what lets a browser that blocks sound until the viewer
11
+ // has done something allow the lines that follow.
12
+ const SILENT_CLIP = 'data:audio/wav;base64,UklGRkQDAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YSADAACAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgA==';
13
+
14
+ /**
15
+ * Gives a tour its voice-over from a text-to-speech service that is reached over HTTP: each line is sent to the service,
16
+ * which answers with audio, and the audio is played one line at a time.
17
+ * @param options Where the audio comes from.
18
+ * @returns The configuration to give {@link CueProvider}.
19
+ * @remarks
20
+ * Create it once, outside any component, and keep it. An application whose service streams, mixes voices or plays through
21
+ * its own audio pipeline gives the tour a {@link CueSpeechConfiguration} of its own instead.
22
+ */
23
+ export function createHttpSpeech(options: HttpSpeechOptions): CueSpeechConfiguration {
24
+ const clips = createSpeechClips(options);
25
+ let availability: Promise<boolean> | undefined;
26
+ let element: HTMLAudioElement | undefined;
27
+
28
+ const audio = (): HTMLAudioElement => element ??= new Audio();
29
+
30
+ // Whether a service is there is the same answer for every tour, so it is asked once.
31
+ const isAvailable = (): Promise<boolean> => {
32
+ if (!options.availableUrl) {
33
+ return Promise.resolve(true);
34
+ }
35
+
36
+ availability ??= (options.fetch ?? fetch)(options.availableUrl, { credentials: options.credentials ?? 'include', headers: options.headers })
37
+ .then(response => (response.ok ? response.json() : { available: false }))
38
+ .then(payload => Boolean((payload as { available?: boolean }).available))
39
+ .catch(() => {
40
+ availability = undefined;
41
+ return false;
42
+ });
43
+ return availability;
44
+ };
45
+
46
+ const useSpeech = (): CueSpeech => {
47
+ const [available, setAvailable] = useState(!options.availableUrl);
48
+ const [isPreparing, setIsPreparing] = useState(false);
49
+ const [isSpeaking, setIsSpeaking] = useState(false);
50
+ const [hasError, setHasError] = useState(false);
51
+ const request = useRef(0);
52
+ const finish = useRef<(() => void) | null>(null);
53
+
54
+ useEffect(() => {
55
+ let current = true;
56
+ void isAvailable().then(value => {
57
+ if (current) setAvailable(value);
58
+ });
59
+ return () => { current = false; };
60
+ }, []);
61
+
62
+ const stop = useCallback(() => {
63
+ request.current++;
64
+ finish.current?.();
65
+ finish.current = null;
66
+ setIsPreparing(false);
67
+ setIsSpeaking(false);
68
+ }, []);
69
+
70
+ useEffect(() => stop, [stop]);
71
+
72
+ const speak = useCallback(async (text: string) => {
73
+ stop();
74
+ const mine = request.current;
75
+ setHasError(false);
76
+ setIsPreparing(true);
77
+ let url: string | undefined;
78
+ try {
79
+ const clip = await clips.obtain(text);
80
+ if (mine !== request.current) return;
81
+
82
+ const player = audio();
83
+ url = URL.createObjectURL(clip);
84
+ const source = url;
85
+ await new Promise<void>((resolve, reject) => {
86
+ const done = () => {
87
+ player.onplaying = null;
88
+ player.onended = null;
89
+ player.onerror = null;
90
+ player.pause();
91
+ URL.revokeObjectURL(source);
92
+ resolve();
93
+ };
94
+ finish.current = done;
95
+ player.onplaying = () => {
96
+ if (mine !== request.current) return;
97
+ setIsPreparing(false);
98
+ setIsSpeaking(true);
99
+ };
100
+ player.onended = () => {
101
+ if (mine === request.current) {
102
+ finish.current = null;
103
+ setIsSpeaking(false);
104
+ }
105
+ done();
106
+ };
107
+ player.onerror = () => reject(new Error('The line could not be played.'));
108
+ player.src = source;
109
+ player.play().catch(reject);
110
+ });
111
+ } catch {
112
+ if (url) URL.revokeObjectURL(url);
113
+ if (mine === request.current) {
114
+ setIsPreparing(false);
115
+ setIsSpeaking(false);
116
+ setHasError(true);
117
+ }
118
+ }
119
+ }, [stop]);
120
+
121
+ const prefetch = useCallback((text: string) => clips.prefetch(text), []);
122
+
123
+ return { isAvailable: available, isPreparing, isSpeaking, hasError, speak, prefetch, stop };
124
+ };
125
+
126
+ const unlock = () => {
127
+ const player = audio();
128
+ if (player.paused && !player.src) {
129
+ player.src = SILENT_CLIP;
130
+ player.play().catch(() => undefined);
131
+ }
132
+ };
133
+
134
+ return { useSpeech, unlock };
135
+ }
@@ -0,0 +1,7 @@
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
+ export * from './CueSpeech.js';
5
+ export * from './CueSpeechConfiguration.js';
6
+ export * from './createHttpSpeech.js';
7
+ export * from './HttpSpeechOptions.js';