@algorisys/tinyfly 0.68.1 → 0.70.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.
@@ -0,0 +1,3 @@
1
+ import type { TinyflyPlayer } from '../player/player';
2
+ /** Wire every `[data-tinyfly-choose]` under `root` to the player's scenarios. Returns a function that unwires them. */
3
+ export declare function bindChoiceHotspots(player: TinyflyPlayer, root: Element): () => void;
@@ -1,8 +1,12 @@
1
1
  import type { TinyflyPlayer } from '../player/player';
2
2
  /**
3
3
  * Controls for a teaching animation: play / pause, step back and forward
4
- * (through markers), restart, a scrub bar, speed, the current step's caption, and
5
- * a question to answer before the next step is revealed.
4
+ * (through markers), restart, a scrub bar, speed, the current step's caption, a
5
+ * question to answer before the next step is revealed, and — when the player has
6
+ * scenarios — a choice between them (a group of options, or a stepped slider).
7
+ * With `fullscreen: true`, a button shows the figure full screen: through the
8
+ * Fullscreen API where the browser has it, and as a fixed overlay where it
9
+ * doesn't (iPhone Safari supports element fullscreen only on iPad).
6
10
  *
7
11
  * Kept out of the player and engine builds. Styled only through CSS custom
8
12
  * properties on the bar (`--tf-ctl-fg`, `--tf-ctl-bg`, `--tf-ctl-accent`,
@@ -11,7 +15,8 @@ import type { TinyflyPlayer } from '../player/player';
11
15
  * can speak its own language.
12
16
  *
13
17
  * Keys work while focus is inside the figure, so several figures on one page
14
- * never react to the same key: Space plays or pauses, ← and → step, Home restarts.
18
+ * never react to the same key: Space plays or pauses, ← and → step, Home restarts,
19
+ * and F toggles full screen when it's enabled.
15
20
  */
16
21
  export interface ControlLabels {
17
22
  play: string;
@@ -30,6 +35,10 @@ export interface ControlLabels {
30
35
  * (default), `"Step {index} of {total}"`, `"第 {index} 步,共 {total} 步"`.
31
36
  */
32
37
  stepFormat: string;
38
+ /** Names the scenario choice: "Scenario", or what is being chosen ("Cache", "Servers") */
39
+ scenario: string;
40
+ fullscreen: string;
41
+ exitFullscreen: string;
33
42
  }
34
43
  export declare const DEFAULT_LABELS: ControlLabels;
35
44
  export interface ControlsOptions {
@@ -43,9 +52,24 @@ export interface ControlsOptions {
43
52
  keyboardScope?: HTMLElement;
44
53
  /** Where to put the bar (default: right after the player's container) */
45
54
  mount?: HTMLElement;
55
+ /**
56
+ * How the reader chooses a scenario: `'buttons'` (default), a group of options,
57
+ * or `'slider'`, for scenarios that are points on a scale (1, 10, 100 servers).
58
+ */
59
+ scenarioControl?: 'buttons' | 'slider';
60
+ /** Add a full screen button for the player's container (default false). F toggles it too. */
61
+ fullscreen?: boolean;
62
+ }
63
+ export interface FullscreenControl {
64
+ /** Whether the figure is full screen now, by either route */
65
+ readonly active: boolean;
66
+ enter(): Promise<void>;
67
+ exit(): Promise<void>;
46
68
  }
47
69
  export interface Controls {
48
70
  readonly element: HTMLElement;
71
+ /** Present when `fullscreen` was enabled */
72
+ readonly fullscreen?: FullscreenControl;
49
73
  destroy(): void;
50
74
  }
51
75
  export declare function createControls(player: TinyflyPlayer, container: HTMLElement, options?: ControlsOptions): Controls;
@@ -8,10 +8,11 @@
8
8
  * page is ready. Otherwise call `tinyfly.mountAll()`.
9
9
  */
10
10
  export { TinyflyPlayer, play, create } from '../player/player';
11
- export type { PlayerOptions } from '../player/player';
11
+ export type { PlayerOptions, Scenario, LoadScenariosOptions } from '../player/player';
12
12
  export { createControls, DEFAULT_LABELS } from './controls';
13
- export type { Controls, ControlsOptions, ControlLabels } from './controls';
13
+ export type { Controls, ControlsOptions, ControlLabels, FullscreenControl } from './controls';
14
14
  export { mount, mountAll, unmount } from './mount';
15
15
  export type { MountedEmbed, MountOptions } from './mount';
16
- export { validateEmbed, renderFrame, targetNamesIn } from './tools';
16
+ export { bindChoiceHotspots } from './choices';
17
+ export { validateEmbed, validateScenarios, renderFrame, targetNamesIn } from './tools';
17
18
  export type { EmbedProblem, FrameAt } from './tools';
@@ -19,6 +19,15 @@ import { type Controls, type ControlsOptions } from './controls';
19
19
  * `<script type="application/json" data-tinyfly-captions>`. `data-controls="false"`
20
20
  * leaves the controls out, and `data-labels` passes control labels as JSON.
21
21
  *
22
+ * Scenarios: give the figure several timelines, each with `data-scenario="id"` and
23
+ * `data-scenario-label="What the reader sees"`, and the reader chooses which one
24
+ * plays. The figure's own `data-scenario` picks the first shown,
25
+ * `data-scenario-legend` names the choice, and `data-scenario-control="slider"`
26
+ * makes it a stepped slider instead of a group of options. Elements with
27
+ * `data-tinyfly-choose="id"` become buttons that choose that scenario.
28
+ *
29
+ * `data-fullscreen="true"` adds a full screen button to the controls.
30
+ *
22
31
  * Embeds default to `playWhenVisible: true`. Each SVG without a role becomes a
23
32
  * labelled image (`role="img"`, named by `data-alt` or the figcaption), and the
24
33
  * step captions are announced as they change.
@@ -1,4 +1,5 @@
1
1
  import { type TimelineDefinition } from '../engine';
2
+ import type { Scenario } from '../player/player';
2
3
  /**
3
4
  * Build-time tools for embedded animations, with no DOM: validating a timeline
4
5
  * against its markup, and rendering a frame into static markup for places that
@@ -23,6 +24,15 @@ export declare function targetNamesIn(markup: string): string[];
23
24
  export declare function validateEmbed(definition: TimelineDefinition, options?: {
24
25
  markup?: string;
25
26
  }): EmbedProblem[];
27
+ /**
28
+ * Problems in a figure with scenarios: everything `validateEmbed` checks, for each
29
+ * scenario (prefixed with its id), plus repeated ids and hotspots naming a scenario
30
+ * that does not exist. An element is reported as never animated only when no
31
+ * scenario animates it.
32
+ */
33
+ export declare function validateScenarios(scenarios: Array<Pick<Scenario, 'id' | 'timeline'>>, options?: {
34
+ markup?: string;
35
+ }): EmbedProblem[];
26
36
  /** Which frame to render: the start, the end, a time in ms, or a marker id. */
27
37
  export type FrameAt = 'start' | 'end' | number | string;
28
38
  /**
@@ -1,5 +1,5 @@
1
1
  export { TinyflyPlayer, play, create } from './player';
2
- export type { PlayerOptions, TargetMapping, SymbolAnimation } from './player';
2
+ export type { PlayerOptions, TargetMapping, SymbolAnimation, Scenario, LoadScenariosOptions } from './player';
3
3
  export { MediaSync, syncMediaElement } from './media-sync';
4
4
  export type { SyncableMedia, MediaSyncOptions } from './media-sync';
5
5
  export { TinyflySequencer, playSequence } from './sequencer';
@@ -54,6 +54,21 @@ export interface SymbolAnimation {
54
54
  id: string;
55
55
  timeline: TimelineDefinition;
56
56
  }
57
+ /**
58
+ * One of several timelines a figure can play, chosen by the reader: "No cache" and
59
+ * "With cache", or a healthy cluster and one whose leader is down. All scenarios
60
+ * animate the same markup.
61
+ */
62
+ export interface Scenario {
63
+ id: string;
64
+ /** What the reader sees on the choice (default: the id) */
65
+ label?: string;
66
+ timeline: TimelineDefinition;
67
+ }
68
+ export interface LoadScenariosOptions {
69
+ /** The scenario shown first (default: the first in the list) */
70
+ initial?: string;
71
+ }
57
72
  export interface TargetMapping {
58
73
  [targetName: string]: HTMLElement | string;
59
74
  }
@@ -79,6 +94,9 @@ export declare class TinyflyPlayer {
79
94
  private mediaSync;
80
95
  private mediaTargets;
81
96
  private symbolInstances;
97
+ private scenarioList;
98
+ private scenarioId;
99
+ private readonly authored;
82
100
  private markerList;
83
101
  private readonly listeners;
84
102
  /** Where the playhead was when marker crossings were last worked out */
@@ -100,6 +118,38 @@ export declare class TinyflyPlayer {
100
118
  * Load animation from a URL or JSON object.
101
119
  */
102
120
  load(source: string | TimelineDefinition): Promise<void>;
121
+ private loadSource;
122
+ /**
123
+ * Make a definition the current timeline: targets, symbols and media bound, no
124
+ * frame drawn and nothing played. The definition itself is not modified, so a
125
+ * scenario's timeline can be used again.
126
+ */
127
+ private useDefinition;
128
+ /**
129
+ * Load several timelines for the same markup, and show one. The reader switches
130
+ * with `setScenario`; the embed's controls and `data-tinyfly-choose` hotspots
131
+ * call it.
132
+ */
133
+ loadScenarios(scenarios: Scenario[], options?: LoadScenariosOptions): Promise<void>;
134
+ /** The scenarios to choose from (empty for a single timeline). */
135
+ get scenarios(): Array<{
136
+ id: string;
137
+ label: string;
138
+ }>;
139
+ /** The id of the scenario showing, if scenarios were loaded. */
140
+ get scenario(): string | undefined;
141
+ /**
142
+ * Switch to another scenario. Whatever the previous one drew is undone first.
143
+ * The reader stays at the same step when the new scenario has a marker with the
144
+ * same id, stays at the end if they were at the end, and otherwise starts from
145
+ * the beginning. Playback continues if it was playing. Under reduced motion the
146
+ * new scenario's final frame shows. Returns false for an unknown id.
147
+ */
148
+ setScenario(id: string): boolean;
149
+ /** Remember how an element was authored, the first time it becomes a target. */
150
+ private rememberAuthored;
151
+ /** Put every target back the way it was authored. */
152
+ private restoreAuthored;
103
153
  /**
104
154
  * Be told whenever the time, play state or current marker may have changed —
105
155
  * for controls and captions. Returns a function that stops it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.68.1",
3
+ "version": "0.70.1",
4
4
  "type": "module",
5
5
  "description": "Lightweight, API-driven animation engine and editor. The engine is framework-agnostic and runs in browsers, Web Workers, and Node.",
6
6
  "license": "MIT",