@algorisys/tinyfly 0.128.0 → 0.129.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.
@@ -18,6 +18,8 @@
18
18
  * `@algorisys/tinyfly/embed` and the CLI. For a page that only shows teaching
19
19
  * figures, `tinyfly-embed.iife.js` is the smaller choice.
20
20
  *
21
+ * Presentations are here as well (`createDeck`), so a deck needs this one script.
22
+ *
21
23
  * Bundler users should import the individual entry points instead
22
24
  * (`tinyfly`, `tinyfly/player`, `tinyfly/gsap-compat`, …) so unused parts
23
25
  * tree-shake away; this file exists for pages with no build step.
@@ -59,3 +61,5 @@ export type { Controls, ControlsOptions, ControlLabels, FullscreenControl } from
59
61
  export { mount, mountAll, unmount } from '../embed/mount';
60
62
  export { bindChoiceHotspots } from '../embed/choices';
61
63
  export type { MountedEmbed, MountOptions } from '../embed/mount';
64
+ export { createDeck, DeckState, DEFAULT_DECK_LABELS } from '../present';
65
+ export type { Deck, DeckOptions, DeckScene, DeckSceneFactory, DeckFrame, DeckLabels } from '../present';
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Every word the deck shows, so a deck can speak its audience's language.
3
+ * `{name}` parts are filled in by the deck.
4
+ */
5
+ export interface DeckLabels {
6
+ /** A countdown before it starts: `{seconds}` */
7
+ timerStart: string;
8
+ timerDone: string;
9
+ /** The slide number being typed: `{slide}` */
10
+ goTo: string;
11
+ helpTitle: string;
12
+ helpNext: string;
13
+ helpPrev: string;
14
+ helpGoTo: string;
15
+ helpEnds: string;
16
+ helpBlank: string;
17
+ helpFullscreen: string;
18
+ helpReplay: string;
19
+ helpTimer: string;
20
+ helpPresenter: string;
21
+ helpHelp: string;
22
+ /** The presenter window's title: `{title}` */
23
+ presenterTitle: string;
24
+ popupBlocked: string;
25
+ /** `{index}` and `{total}` */
26
+ slideOf: string;
27
+ /** `{step}` and `{steps}` */
28
+ clicks: string;
29
+ /** `{left}` and `{slot}`, both as m:ss */
30
+ timeLeft: string;
31
+ overTime: string;
32
+ prev: string;
33
+ next: string;
34
+ resetClock: string;
35
+ /** `{seconds}` */
36
+ hintTimerStart: string;
37
+ hintTimerEnd: string;
38
+ /** `{step}` */
39
+ hintStep: string;
40
+ /** `{title}` */
41
+ hintSlide: string;
42
+ hintEnd: string;
43
+ }
44
+ export declare const DEFAULT_DECK_LABELS: DeckLabels;
45
+ /** Fill `{name}` parts of a label. */
46
+ export declare function fillLabel(label: string, values: Record<string, string | number>): string;
@@ -0,0 +1,128 @@
1
+ /**
2
+ * The state of a presentation: which slide, which click, where each slide's
3
+ * scene clock is, and its countdown timers.
4
+ *
5
+ * No DOM and no clock of its own: every method that depends on the time takes
6
+ * `now` (ms), so the same calls always give the same state. `createDeck` drives
7
+ * it from the page; tests and other runtimes can drive it directly.
8
+ *
9
+ * A slide's steps come from its `marks`: `marks[0]` is the scene time (ms) where
10
+ * the entrance ends, and `marks[k]` is where click `k` ends. `next()` sets the
11
+ * target to the next mark and `advance()` plays the scene clock up to it.
12
+ * Pressing next while the clock is still running snaps to the mark, so a double
13
+ * press on a clicker never skips a step.
14
+ */
15
+ export type DeckTimerState = 'idle' | 'running' | 'done';
16
+ /** A countdown on one step of a slide (a poll, a QR code, a question). */
17
+ export interface DeckTimerSpec {
18
+ /** The step the countdown belongs to */
19
+ step: number;
20
+ /** Its length in seconds */
21
+ seconds: number;
22
+ }
23
+ export interface DeckSlideSpec {
24
+ id: string;
25
+ title?: string;
26
+ notes?: string;
27
+ /** Scene times in ms, one per step (see the file comment). Default `[0]` */
28
+ marks?: number[];
29
+ /** The highest step any markup fragment asks for; marks are padded up to it */
30
+ fragmentSteps?: number;
31
+ timers?: DeckTimerSpec[];
32
+ }
33
+ export interface DeckTimer extends DeckTimerSpec {
34
+ state: DeckTimerState;
35
+ /** `now` when it started */
36
+ startedAt: number;
37
+ /** `now` when it finished */
38
+ endedAt: number;
39
+ }
40
+ export interface DeckSlide {
41
+ id: string;
42
+ title: string;
43
+ notes: string;
44
+ marks: number[];
45
+ /** Number of clicks on this slide */
46
+ steps: number;
47
+ /** The current step, 0 … steps */
48
+ step: number;
49
+ /** The scene clock, ms */
50
+ time: number;
51
+ /** Where the scene clock is playing to, ms */
52
+ target: number;
53
+ timers: DeckTimer[];
54
+ }
55
+ /** What a scene is told about a slide's countdown while it runs or has finished. */
56
+ export interface DeckTimerFrame {
57
+ state: 'running' | 'done';
58
+ /** ms since it started */
59
+ elapsed: number;
60
+ seconds: number;
61
+ /** ms since it finished (0 while running) */
62
+ sinceEnd: number;
63
+ }
64
+ /** What `next()` did. */
65
+ export type DeckAdvance = 'snap' | 'timer-start' | 'timer-end' | 'step' | 'slide' | 'end';
66
+ /** What the next press will do, for the presenter view. */
67
+ export type DeckHint = {
68
+ kind: 'timer-start';
69
+ seconds: number;
70
+ } | {
71
+ kind: 'timer-end';
72
+ } | {
73
+ kind: 'step';
74
+ step: number;
75
+ } | {
76
+ kind: 'slide';
77
+ title: string;
78
+ } | {
79
+ kind: 'end';
80
+ };
81
+ export declare class DeckState {
82
+ readonly slides: DeckSlide[];
83
+ /** The current slide, 0-based */
84
+ index: number;
85
+ private fragmentSteps;
86
+ constructor(specs: DeckSlideSpec[]);
87
+ get slide(): DeckSlide;
88
+ /** True while the current slide's scene clock is still playing to its target. */
89
+ get playing(): boolean;
90
+ /**
91
+ * Give a slide its marks once its scene is built (scenes are built when first
92
+ * needed). The slide keeps its step, clamped to the new count.
93
+ */
94
+ setMarks(index: number, marks: number[] | undefined): void;
95
+ /**
96
+ * Show slide `index` at `step` (`'last'` for its final step). With `play`, the
97
+ * scene plays into that step from the one before; otherwise it is shown as it
98
+ * ends. Timers on the slide left and the slide shown go back to idle.
99
+ */
100
+ goTo(index: number, step?: number | 'last', options?: {
101
+ play?: boolean;
102
+ }): void;
103
+ /** The clicker's forward button. */
104
+ next(now: number): DeckAdvance;
105
+ /** Back one step, shown as it ends; from a slide's first step, to the end of the slide before. */
106
+ prev(): boolean;
107
+ /** Play the current step again. */
108
+ replay(): void;
109
+ /** The countdown that belongs to the current step, if any. */
110
+ stepTimer(): DeckTimer | undefined;
111
+ /**
112
+ * Start a countdown, or end it when it is running: the current step's, or
113
+ * `timer` (one of the current slide's, on a step already reached). False when
114
+ * there is none to toggle.
115
+ */
116
+ toggleTimer(now: number, timer?: DeckTimer | undefined): boolean;
117
+ /** Move the scene clock on by `dt` ms and finish countdowns that have run out. */
118
+ advance(dt: number, now: number): void;
119
+ /** The current slide's countdown as a scene sees it: the last one that is running or done. */
120
+ timerFrame(now: number): DeckTimerFrame | null;
121
+ /** Seconds left on a countdown, never below 0. */
122
+ secondsLeft(timer: DeckTimer, now: number): number;
123
+ /** What the next press will do. */
124
+ hint(): DeckHint;
125
+ private startTimer;
126
+ private finishTimer;
127
+ private resetTimers;
128
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * The deck's own styles: the stage, slide changes, step reveals, countdown
3
+ * buttons and the overlays. Every class is prefixed `tf-deck` or `tf-`, and the
4
+ * look is set through custom properties on the deck element:
5
+ *
6
+ * --tf-deck-bg slide background (default #fff)
7
+ * --tf-deck-accent progress bar, countdown button (default #f0812f)
8
+ * --tf-deck-panel overlays and the countdown while running (default #0e2841)
9
+ * --tf-deck-done a finished countdown (default #2e9e48)
10
+ * --tf-deck-font overlay text (default: the page's font)
11
+ *
12
+ * Slide content is the page's own markup and CSS; nothing here styles it.
13
+ */
14
+ export declare const DECK_CSS = "\nhtml.tf-deck-page, html.tf-deck-page body { margin: 0; height: 100%; background: #000; overflow: hidden; }\n.tf-deck { position: absolute; left: 0; top: 0; transform-origin: 0 0; overflow: hidden; background: var(--tf-deck-bg, #fff); }\n.tf-deck.tf-idle { cursor: none; }\n.tf-deck [data-slide] { position: absolute; inset: 0; opacity: 0; visibility: hidden; background: var(--tf-deck-bg, #fff); transition: opacity .55s ease, visibility 0s linear .55s; }\n.tf-deck [data-slide].tf-current { opacity: 1; visibility: visible; z-index: 2; transition: opacity .55s ease, visibility 0s; }\n.tf-deck canvas[data-scene] { position: absolute; left: 0; top: 0; width: 100%; height: 100%; pointer-events: none; z-index: 5; }\n.tf-deck [data-notes] { display: none; }\n.tf-deck [data-step] { opacity: 0; transform: translateY(26px); transition: opacity .5s ease, transform .6s cubic-bezier(.2,.9,.25,1.15); }\n.tf-deck [data-step][data-reveal=\"pop\"] { transform: scale(.6); }\n.tf-deck [data-step][data-reveal=\"fade\"], .tf-deck [data-step][data-reveal=\"none\"] { transform: none; }\n.tf-deck [data-step][data-reveal=\"none\"] { transition: none; }\n.tf-deck [data-step].tf-on { opacity: 1; transform: none; }\n.tf-deck [data-timer] { position: relative; overflow: hidden; min-width: 240px; height: 64px; padding: 0 28px; border: 0; border-radius: 32px; background: var(--tf-deck-accent, #f0812f); color: #fff; font: 700 26px/1 var(--tf-deck-font, inherit); cursor: pointer; }\n.tf-deck [data-timer] i { position: absolute; left: 0; top: 0; bottom: 0; width: 0; background: rgba(255,255,255,.28); }\n.tf-deck [data-timer] span, .tf-deck [data-timer] b { position: relative; }\n.tf-deck [data-timer][data-state=\"running\"] { background: var(--tf-deck-panel, #0e2841); cursor: default; }\n.tf-deck [data-timer][data-state=\"running\"] b { font-size: 40px; font-variant-numeric: tabular-nums; }\n.tf-deck [data-timer][data-state=\"done\"] { background: var(--tf-deck-done, #2e9e48); }\n.tf-deck-progress { position: absolute; left: 0; bottom: 0; height: 8px; width: 0; z-index: 50; background: var(--tf-deck-accent, #f0812f); transition: width .5s ease; }\n.tf-deck-blank { position: absolute; inset: 0; z-index: 90; background: #000; opacity: 0; pointer-events: none; transition: opacity .3s; }\n.tf-deck-blank.tf-white { background: #fff; }\n.tf-deck-blank.tf-on { opacity: 1; }\n.tf-deck-goto { position: absolute; right: 50px; top: 40px; z-index: 95; display: none; padding: 10px 30px; border-radius: 18px; background: var(--tf-deck-panel, #0e2841); color: #fff; font: 800 54px/1.2 var(--tf-deck-font, inherit); }\n.tf-deck-goto.tf-on { display: block; }\n.tf-deck-help { position: absolute; inset: 0; z-index: 99; display: none; box-sizing: border-box; padding: 100px 180px; background: var(--tf-deck-panel, #0e2841); color: #fff; font: 400 30px/1.3 var(--tf-deck-font, inherit); opacity: .96; }\n.tf-deck-help.tf-on { display: block; }\n.tf-deck-help h2 { margin: 0 0 36px; font-size: 52px; }\n.tf-deck-help table { border-collapse: collapse; }\n.tf-deck-help td { padding: 9px 40px 9px 0; vertical-align: top; }\n.tf-deck-help kbd { display: inline-block; margin-right: 6px; padding: 2px 14px; border-radius: 8px; background: #fff; color: #0e2841; font: 700 24px/1.4 var(--tf-deck-font, inherit); }\n";
15
+ /** The presenter window's styles (it is a separate document). */
16
+ export declare const PRESENTER_CSS = "\nbody { margin: 0; height: 100vh; display: grid; grid-template-rows: auto 1fr auto; background: #0e2841; color: #fff; font-family: \"Segoe UI\", Inter, Arial, sans-serif; }\nheader { display: flex; gap: 40px; align-items: baseline; padding: 22px 34px; background: #071937; }\n#timer { font-size: 64px; font-weight: 800; font-variant-numeric: tabular-nums; }\n#timer.warn { color: #f0812f; }\n#timer.over { color: #ff5a52; }\n#left { font-size: 26px; opacity: .85; }\n#clock { margin-left: auto; font-size: 30px; opacity: .7; }\nmain { padding: 28px 34px; overflow: auto; }\n#where { font-size: 22px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: #f0812f; }\n#title { margin: 6px 0 18px; font-size: 44px; font-weight: 800; }\n#steps span { display: inline-block; width: 18px; height: 18px; margin-right: 8px; border-radius: 50%; background: #33507a; }\n#steps span.on { background: #f0812f; }\n#notes { max-width: 1100px; font-size: 30px; line-height: 1.45; white-space: pre-line; }\nfooter { display: flex; gap: 30px; align-items: center; padding: 18px 34px; background: #071937; font-size: 24px; }\n#next { opacity: .85; }\nbutton { padding: 10px 22px; border: 0; border-radius: 10px; font: inherit; font-size: 22px; cursor: pointer; }\n";
@@ -0,0 +1,104 @@
1
+ import { DeckState, type DeckTimerFrame } from './deck-state';
2
+ import { type DeckLabels } from './deck-labels';
3
+ /**
4
+ * A presentation on a page: slides stepped through with a clicker or the
5
+ * keyboard, each with an optional scene that plays as the presenter clicks.
6
+ *
7
+ * <main id="deck">
8
+ * <section data-slide="intro" data-title="Hello">
9
+ * <h1>Hello</h1>
10
+ * <p data-step="1">Shown on the first click</p>
11
+ * <aside data-notes>What to say here.</aside>
12
+ * </section>
13
+ * </main>
14
+ * <script>tinyfly.createDeck('#deck', { scenes: { intro: () => ({ marks: [800, 2400], draw }) } })</script>
15
+ *
16
+ * Markup:
17
+ * - `[data-slide="id"]` is a slide; `data-title` names it for the presenter.
18
+ * - `[data-step="k"]` appears on click `k` and stays (`data-reveal`: `pop`,
19
+ * `fade` or `none` instead of the default rise). It gets `tf-on` from its step
20
+ * on and `tf-now` on its step, for the page's own CSS.
21
+ * - `[data-notes]` holds the slide's speaker notes (never shown on the slide).
22
+ * - `<button data-timer="30">` is a countdown of that many seconds on the step
23
+ * of the `[data-step]` around it. Next starts it, Next again ends it early.
24
+ * - `canvas[data-scene]` is where the slide's scene draws; one is added when
25
+ * the scene draws and the slide has none.
26
+ *
27
+ * The deck is a fixed-size stage (1920 × 1080 by default) scaled to fit the
28
+ * window, so every layout is in the same pixels on any screen.
29
+ */
30
+ /** What a scene is given each frame. */
31
+ export interface DeckFrame {
32
+ /** The slide's scene clock in ms: plays up to the current step's mark and waits there */
33
+ time: number;
34
+ /** A clock that never stops, in ms, for motion that loops while the scene waits */
35
+ clock: number;
36
+ /** The slide's current step (0 until the first click) */
37
+ step: number;
38
+ /** The slide's countdown while it runs and after it ends, or null */
39
+ timer: DeckTimerFrame | null;
40
+ width: number;
41
+ height: number;
42
+ }
43
+ export interface DeckScene {
44
+ /** Scene times in ms: `marks[0]` ends the entrance, `marks[k]` ends click `k` */
45
+ marks?: number[];
46
+ /** Paint the slide's canvas (already cleared) */
47
+ draw?(ctx: CanvasRenderingContext2D, frame: DeckFrame): void;
48
+ /** Update anything else for this frame (SVG, DOM, a tinyfly timeline's seek) */
49
+ update?(frame: DeckFrame): void;
50
+ }
51
+ export interface DeckSceneContext {
52
+ width: number;
53
+ height: number;
54
+ /** The slide's element */
55
+ el: HTMLElement;
56
+ }
57
+ /** Builds a slide's scene, the first time the slide (or the one before it) is shown. */
58
+ export type DeckSceneFactory = (context: DeckSceneContext) => DeckScene;
59
+ export interface DeckOptions {
60
+ /** Stage size in px (default 1920 × 1080) */
61
+ width?: number;
62
+ height?: number;
63
+ /** Scene factories by slide id */
64
+ scenes?: Record<string, DeckSceneFactory>;
65
+ /** The deck's name, for the presenter window (default: the page title) */
66
+ title?: string;
67
+ /** The talk's length in minutes, for the presenter's countdown */
68
+ slotMinutes?: number;
69
+ /** Visible text; missing entries use English */
70
+ labels?: Partial<DeckLabels>;
71
+ /** Keep the slide and step in the URL hash (`#5.2`) and start from it (default true) */
72
+ hash?: boolean;
73
+ /** Listen for keys on the window (default true) */
74
+ keyboard?: boolean;
75
+ /** Scale the stage to its container, or the window when that is `<body>` (default true) */
76
+ fit?: boolean;
77
+ /** Run the frame loop (default true). With false, call `render(now)` yourself */
78
+ autoStart?: boolean;
79
+ /** Called after every change of slide, step or countdown */
80
+ onChange?: (deck: Deck) => void;
81
+ }
82
+ export interface Deck {
83
+ readonly state: DeckState;
84
+ readonly element: HTMLElement;
85
+ next(): void;
86
+ prev(): void;
87
+ /** Show a slide by its number (1 is the first) at a step, playing into it */
88
+ goTo(slide: number, step?: number | 'last'): void;
89
+ /**
90
+ * Show a slide exactly as a step ends, or at scene time `ms`: for rehearsing
91
+ * and for screenshots of one moment.
92
+ */
93
+ seek(slide: number, step?: number | 'last', ms?: number): void;
94
+ replay(): void;
95
+ /** Start or end the current step's countdown */
96
+ toggleTimer(): void;
97
+ /** Toggle a black or white screen */
98
+ blank(kind?: 'black' | 'white'): void;
99
+ openPresenter(): void;
100
+ /** Advance and draw one frame at `now` (ms). The frame loop calls this */
101
+ render(now: number): void;
102
+ destroy(): void;
103
+ }
104
+ export declare function createDeck(root: HTMLElement | string, options?: DeckOptions): Deck;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * @algorisys/tinyfly/present — presentations: slides stepped through with a
3
+ * clicker, each with a scene that plays as the presenter clicks, a presenter
4
+ * window with notes and a clock, countdowns, and one offline HTML file to take
5
+ * to the venue.
6
+ *
7
+ * const deck = createDeck('#deck', { scenes: { intro: () => ({ marks: [800, 2400], draw }) } })
8
+ *
9
+ * `DeckState` is the same deck without a page: slides, steps, scene clocks and
10
+ * countdowns as plain state, driven by explicit times. `inlineDeck` builds the
11
+ * single file (the `tinyfly present` command wraps it).
12
+ */
13
+ export { createDeck } from './deck';
14
+ export type { Deck, DeckOptions, DeckScene, DeckSceneFactory, DeckSceneContext, DeckFrame } from './deck';
15
+ export { DeckState } from './deck-state';
16
+ export type { DeckSlideSpec, DeckSlide, DeckTimer, DeckTimerSpec, DeckTimerState, DeckTimerFrame, DeckAdvance, DeckHint, } from './deck-state';
17
+ export { DEFAULT_DECK_LABELS } from './deck-labels';
18
+ export type { DeckLabels } from './deck-labels';
19
+ export { inlineDeck } from './inline-deck';
20
+ export type { InlineDeckOptions, InlineDeckResult } from './inline-deck';
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Turn a deck's page and the files it loads into one HTML file that works
3
+ * offline from `file://`: scripts and stylesheets inlined, images, fonts and
4
+ * media as data URIs.
5
+ *
6
+ * It reads no files itself: the caller passes `readText` and `readBase64`, so
7
+ * it runs anywhere (the `tinyfly present` command passes Node's `fs`). Paths
8
+ * given to them are relative to the page, with `/` separators.
9
+ *
10
+ * Whatever would still need the network or another file is reported, not
11
+ * guessed at: `missing` (a local file that could not be read), `remote` (a
12
+ * script, stylesheet or media URL on the network) and `unsupported` (`srcset`,
13
+ * `@import`, module scripts that import other files). A deck is safe to take
14
+ * to a venue when all three are empty.
15
+ */
16
+ export interface InlineDeckOptions {
17
+ /** A file's text, or null when it cannot be read */
18
+ readText: (path: string) => string | null;
19
+ /** A file's bytes as base64, or null when it cannot be read */
20
+ readBase64: (path: string) => string | null;
21
+ }
22
+ export interface InlineDeckResult {
23
+ html: string;
24
+ /** Files written into the page, in the order they were first met */
25
+ inlined: string[];
26
+ missing: string[];
27
+ remote: string[];
28
+ unsupported: string[];
29
+ }
30
+ export declare function inlineDeck(html: string, options: InlineDeckOptions): InlineDeckResult;
@@ -0,0 +1,29 @@
1
+ import type { DeckState } from './deck-state';
2
+ import { type DeckLabels } from './deck-labels';
3
+ /**
4
+ * The presenter's second window: a clock, the time left of the slot, the
5
+ * current slide's title, clicks and notes, and what the next press will do.
6
+ *
7
+ * It is written into a blank window (`window.open('')`), so it works from
8
+ * `file://` and needs no second file. The window holds no state of its own:
9
+ * `update()` writes the deck's state into it.
10
+ */
11
+ export interface PresenterViewOptions {
12
+ state: DeckState;
13
+ labels: DeckLabels;
14
+ /** The deck's name, for the window title */
15
+ title: string;
16
+ /** The talk's length in minutes; without it only the elapsed time shows */
17
+ slotMinutes?: number;
18
+ onNext: () => void;
19
+ onPrev: () => void;
20
+ onKey: (event: KeyboardEvent) => void;
21
+ }
22
+ export interface PresenterView {
23
+ /** Open the window, or focus it when it is open */
24
+ open(): void;
25
+ /** Write the deck's state into the window (does nothing while it is closed) */
26
+ update(): void;
27
+ close(): void;
28
+ }
29
+ export declare function createPresenterView(options: PresenterViewOptions): PresenterView;