@meltemi/diagrams-player 0.0.0-stage → 1.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Architecture Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @meltemi/diagrams-player
 
-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.
+The HTML player of stories and diagram effects: a custom element with play, pause, scenes,
+keyboard control, reduced motion, a static view and a text summary, written as a whole offline
+page or a fragment to paste into a page. Every drawing zooms and pans, shows hover cards and a
+detail panel, and opens the views its boxes hold with a double click or a plus sign, all drawn
+around the frame and never in it. The `./node` entry gives the bundled runtime script.
+
+It is part of [Meltemi Diagrams](https://github.com/askenaz-dev/meltemi-diagrams#readme), diagrams as code with a canvas, motion and
+exports. Every package of the product has the same version.
+
+## Install
+
+```bash
+npm install @meltemi/diagrams-player
+```
+
+Node 22.12.0 or later. The package is an ES module with type declarations.
+
+## Use
+
+Most people get a player from the command line:
+
+```bash
+meltemi-diagrams export stories/purchase.meltemi --story purchase --format html
+```
+
+In code, a player document is built from a compiled story and its laid-out views:
+
+```js
+import { playerPage, storyDocument, storyViews } from "@meltemi/diagrams-player";
+import { playerScript } from "@meltemi/diagrams-player/node";
+
+const layouts = new Map();
+for (const [key, view] of storyViews(story)) {
+  layouts.set(key, { diagram: view.diagram, layout: layoutDiagram(compilation, view.diagram) });
+}
+const html = playerPage(storyDocument(story, layouts), playerScript());
+```
+
+## Documentation
+
+- [The player](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/player.md)
+- [Stories](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/language/stories.md)
+- [All documentation](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/README.md)
+
+## Licence
+
+MIT. Third-party components and their licences are listed in [THIRD_PARTY_LICENSES.md](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/THIRD_PARTY_LICENSES.md).

package/dist/controller.d.ts

@@ -0,0 +1,146 @@
+import { type Locale } from "@meltemi/diagrams-i18n";
+import { type DrillSpec, type StoryViewData, type TimelineScene } from "@meltemi/diagrams-motion";
+import type { EffectsPlayerDocument, OpenTarget, PlayerDocument, StoryPlayerDocument } from "./format.js";
+/** An element or a relation of the view on screen. */
+export interface ItemRef {
+    readonly role: "element" | "relation";
+    readonly id: string;
+}
+/** A drill-down on its way: the move, its clock, and what to do when it settles. */
+export interface DrillState {
+    readonly spec: DrillSpec;
+    /** Milliseconds since it started. */
+    time: number;
+    /** Views the document lacks, by key: the view a catalog page came from. */
+    readonly extra: Readonly<Record<string, StoryViewData>>;
+    /** The element to select once it settles. */
+    readonly select: string | null;
+    /** Whether the effects were playing before. */
+    readonly resume: boolean;
+}
+/** Where the trail of views went down: the view, and its element that opened the next one. */
+export interface TrailStep {
+    readonly view: string;
+    readonly element: string;
+}
+/** The trail never grows past this: `link` cycles are legal. */
+export declare const TRAIL_LIMIT = 32;
+export interface PlayerOptions {
+    /** Starts playing at once, unless the viewer asks for reduced motion. */
+    readonly autoplay?: boolean;
+    /** Starts again at the end. */
+    readonly loop?: boolean;
+    /** Starts in the static view. */
+    readonly static?: boolean;
+    /** The viewer asks for reduced motion: the static view, and no autoplay. */
+    readonly reducedMotion?: boolean;
+    /** The language of what the player says; English by default. */
+    readonly locale?: Locale;
+}
+export type PlayerCommand = "toggle" | "back" | "forward" | "backSmall" | "forwardSmall" | "start" | "end" | "previousScene" | "nextScene" | "toggleStatic";
+/** Steps of the arrow keys, in milliseconds. */
+export declare const STEP = 1000;
+export declare const SMALL_STEP = 100;
+/**
+ * The command of a key pressed in the player, or undefined. Left and Right step a second, `,` and
+ * `.` a tenth (Shift and the arrows pan the drawing).
+ */
+export declare function commandForKey(key: string): PlayerCommand | undefined;
+/** `1.2 s`, `800 ms` or `0 s`, with the language's decimal mark: `1,2 s` in Spanish. */
+export declare function formatTime(ms: number, locale?: Locale): string;
+/**
+ * The state of a player without its page: the clock, the scenes, the static view and what to
+ * announce. The runtime draws `frameTime` and calls `tick` on animation frames.
+ */
+export declare class PlayerController {
+    readonly document: PlayerDocument;
+    time: number;
+    playing: boolean;
+    staticView: boolean;
+    readonly loop: boolean;
+    /** The language of the announcements. */
+    readonly locale: Locale;
+    constructor(document: PlayerDocument, options?: PlayerOptions);
+    /** The view of an effects document on screen, by key. */
+    protected effectsView: string;
+    /** The element or relation selected, whose details the panel shows. */
+    selection: ItemRef | null;
+    /** The item the keyboard walk reached. */
+    focused: ItemRef | null;
+    /** The views above the one on screen, outermost first. */
+    readonly trail: TrailStep[];
+    /** A drill-down on its way, or null. */
+    drill: DrillState | null;
+    private readonly reducedMotion;
+    /** What to announce once a drill-down settles, until the runtime takes it. */
+    private settled;
+    /** The key of the view on screen: an effects document's current view, or the scene's view. */
+    get view(): string;
+    /** How long the document plays, or null for effects that repeat forever. */
+    get duration(): number | null;
+    get scenes(): readonly TimelineScene[];
+    /** The scene at a time: the last one that has started. */
+    sceneIndexAt(t: number): number;
+    get sceneIndex(): number;
+    /** The time of a scene's final state. */
+    sceneEnd(index: number): number;
+    /** Whether the play button can play: never in the static view of a story. */
+    get canPlay(): boolean;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Moves the clock on by `elapsed` ms while playing; returns true when playback ended. */
+    tick(elapsed: number): boolean;
+    /** Shows a time; in the static view, the final state of the scene at that time. */
+    seek(t: number): void;
+    goToScene(index: number): void;
+    setStatic(on: boolean): void;
+    /** The time whose frame is drawn. */
+    get frameTime(): number;
+    /** Runs a keyboard command. */
+    run(command: PlayerCommand): void;
+    /** The title of a view, or its key. */
+    titleOf(view: string): string;
+    /** The elements (with a box) and relations (with a track) of a view, in drawing order. */
+    items(view?: string): ItemRef[];
+    /**
+     * Moves the keyboard walk to the next (`1`) or previous (`-1`) item that `shown` accepts,
+     * wrapping at the ends; returns the item reached, or null when there is none.
+     */
+    moveFocus(step: 1 | -1, shown?: (item: ItemRef) => boolean): ItemRef | null;
+    /** Selects an item of the view on screen, or clears; false for an unknown item. */
+    select(item: ItemRef | null): boolean;
+    /** What an element of the view on screen opens in the document; null for stories and drills. */
+    canOpen(id: string): OpenTarget | null;
+    private durations;
+    /** How long the drill-down on its way lasts. */
+    get drillDuration(): number;
+    private start;
+    private settle;
+    /** Opens what an element of the view on screen opens; false when it opens nothing here. */
+    open(id: string): boolean;
+    /**
+     * Plays a drill-down into the document's own view from a view the document lacks (a catalog
+     * page that came from another page): going down, `element` is in `from`; going up, in the
+     * document's view.
+     */
+    enter(from: {
+        readonly key: string;
+        readonly view: StoryViewData;
+    }, element: string, direction: "down" | "up", transition: "morph" | "fade", select?: string | null): void;
+    /** Goes up to a view of the trail (the one just above by default); false when there is none. */
+    up(index?: number): boolean;
+    /** What a settled drill-down says, once: "Opened containers". */
+    takeSettled(): string | null;
+    /** What a screen reader hears about the current scene, in the player's language. */
+    announcement(): string;
+}
+export interface SummaryScene {
+    readonly heading: string;
+    readonly items: readonly string[];
+}
+/** The scenes of a story and their actions in words, with labels instead of ids. */
+export declare function storySummary(doc: StoryPlayerDocument, locale?: Locale): SummaryScene[];
+/** The effects of a diagram in words. */
+export declare function effectsSummary(doc: EffectsPlayerDocument, locale?: Locale, view?: string): string[];
+//# sourceMappingURL=controller.d.ts.map

package/dist/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,aAAa,EAElB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,qBAAqB,EACrB,UAAU,EACV,cAAc,EACd,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAGrB,sDAAsD;AACtD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACxD,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,gEAAgE;AAChE,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,iCAAiC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,MAAM,GACN,SAAS,GACT,WAAW,GACX,cAAc,GACd,OAAO,GACP,KAAK,GACL,eAAe,GACf,WAAW,GACX,cAAc,CAAC;AAEnB,gDAAgD;AAChD,eAAO,MAAM,IAAI,OAAO,CAAC;AACzB,eAAO,MAAM,UAAU,MAAM,CAAC;AAI9B;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgCpE;AAiBD,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAE,MAAuB,GAAG,MAAM,CAI9E;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IASzB,QAAQ,CAAC,QAAQ,EAAE,cAAc;IARnC,IAAI,SAAK;IACT,OAAO,UAAS;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGb,QAAQ,EAAE,cAAc,EACjC,OAAO,GAAE,aAAkB;IAW7B,yDAAyD;IACzD,SAAS,CAAC,WAAW,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,SAAS,EAAE,OAAO,GAAG,IAAI,CAAQ;IACjC,0CAA0C;IAC1C,OAAO,EAAE,OAAO,GAAG,IAAI,CAAQ;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,CAAM;IACjC,wCAAwC;IACxC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,8EAA8E;IAC9E,OAAO,CAAC,OAAO,CAAuB;IAEtC,8FAA8F;IAC9F,IAAI,IAAI,IAAI,MAAM,CAIjB;IAED,4EAA4E;IAC5E,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAI5B;IAED,IAAI,MAAM,IAAI,SAAS,aAAa,EAAE,CAErC;IAED,0DAA0D;IAC1D,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAO/B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAO/B,6EAA6E;IAC7E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,IAAI,IAAI;IAOZ,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,IAAI;IAKd,0FAA0F;IAC1F,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IA2B9B,mFAAmF;IACnF,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IASrB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAO9B,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAQ5B,qCAAqC;IACrC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,+BAA+B;IAC/B,GAAG,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IA4CjC,uCAAuC;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7B,0FAA0F;IAC1F,KAAK,CAAC,IAAI,GAAE,MAAkB,GAAG,OAAO,EAAE;IAmB1C;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAoB,GAAG,OAAO,GAAG,IAAI;IAYvF,mFAAmF;IACnF,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO;IAUrC,gGAAgG;IAChG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAMtC,OAAO,CAAC,SAAS;IAIjB,gDAAgD;IAChD,IAAI,aAAa,IAAI,MAAM,CAG1B;IAED,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,MAAM;IAad,2FAA2F;IAC3F,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAoBzB;;;;OAIG;IACH,KAAK,CACH,IAAI,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;KAAE,EAC5D,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,UAAU,EAAE,OAAO,GAAG,MAAM,EAC5B,MAAM,GAAE,MAAM,GAAG,IAAW,GAC3B,IAAI;IAoBP,gGAAgG;IAChG,EAAE,CAAC,KAAK,GAAE,MAA8B,GAAG,OAAO;IA2BlD,iEAAiE;IACjE,WAAW,IAAI,MAAM,GAAG,IAAI;IAM5B,oFAAoF;IACpF,YAAY,IAAI,MAAM;CAWvB;AAsCD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAC1B,GAAG,EAAE,mBAAmB,EACxB,MAAM,GAAE,MAAuB,GAC9B,YAAY,EAAE,CAyBhB;AAED,yCAAyC;AACzC,wBAAgB,cAAc,CAC5B,GAAG,EAAE,qBAAqB,EAC1B,MAAM,GAAE,MAAuB,EAC/B,IAAI,GAAE,MAAgB,GACrB,MAAM,EAAE,CAoBV"}