@fxi/zartigl 0.5.0 → 0.6.0

package/dist/scalar-color-domain-PEK8Hxg1.js

@@ -0,0 +1,12 @@
+function e(r) {
+  if (r == null)
+    return null;
+  if (!Number.isFinite(r[0]) || !Number.isFinite(r[1]) || r[0] >= r[1])
+    throw new RangeError(
+      "colorDomain must contain two finite, increasing values"
+    );
+  return [r[0], r[1]];
+}
+export {
+  e as v
+};

package/dist/story.d.ts

@@ -0,0 +1,398 @@
+/** `rootMargin` that shrinks the root to a band at `line`. */
+export declare function activationMargin(line: number): string;
+
+export declare function advanceStorySequence(index: number, direction: 1 | -1, length: number, mode: "loop" | "ping-pong"): {
+    index: number;
+    direction: 1 | -1;
+};
+
+/** Layouts of the original story demo, accepted when an app names none. */
+export declare const DEFAULT_STORY_LAYOUTS: readonly string[];
+
+/**
+ * Define `<story-pager>`: ‹ 1 2 … n › ⏯ in light DOM, styled by the app.
+ * Emits `story-pager-navigate` ({@link StoryPagerNavigateDetail}) and
+ * `story-pager-toggle`; the app owns the state and sets it back. The active
+ * step has `aria-current="step"` and its `--progress` drives a fill.
+ */
+export declare function defineStoryPager(registry?: CustomElementRegistry, name?: string): void;
+
+export declare function initializeAfterStaticRender<T>(renderStatic: () => void, initialize: () => Promise<T>): Promise<T>;
+
+export declare class LoadingIndicator {
+    private readonly update;
+    private readonly revealDelayMs;
+    private readonly minimumVisibleMs;
+    private revealTimer;
+    private hideTimer;
+    private shownAt;
+    private visible;
+    constructor(update: (visible: boolean) => void, options?: LoadingIndicatorOptions);
+    show(): void;
+    hide(immediate?: boolean): void;
+    private setVisible;
+    private clearRevealTimer;
+    private clearHideTimer;
+}
+
+export declare interface LoadingIndicatorOptions {
+    revealDelayMs?: number;
+    minimumVisibleMs?: number;
+}
+
+export declare type LocalizedText = Record<string, string>;
+
+export declare function nextStoryIndex(current: number, delta: number, sceneCount: number): number;
+
+export declare function parseStoryDocuments(story: unknown, views: unknown, options?: StoryValidationOptions): {
+    story: StoryDocument;
+    views: StoryViewsDocument;
+};
+
+/** Read `#s=<scene id>&paused=1`; unknown or missing fields stay undefined. */
+export declare function parseStoryHash(hash: string): StoryHashState;
+
+export declare function resolveLocalizedText(text: LocalizedText, locale: string, defaultLocale: string, fallbacks?: readonly string[]): string;
+
+export declare function sceneShowsTime(scene: StoryScene): boolean;
+
+export declare function sceneViewId(scene: StoryScene): string | undefined;
+
+export declare function sequenceIndexAtOrBefore(times: readonly string[], time: number): number;
+
+export declare type StoryAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
+export declare type StoryBlock = StoryCopyBlock | StoryViewBlock | StoryWidgetBlock | StoryTextBlock;
+
+declare interface StoryBlockBase {
+    id: string;
+    slot: StorySlot;
+    anchor?: StoryAnchor;
+}
+
+export declare interface StoryCopyBlock extends StoryBlockBase {
+    type: "copy";
+    label?: LocalizedText;
+    heading: LocalizedText;
+    text?: LocalizedText;
+    references?: StoryReference[];
+    showTime?: boolean;
+    backdrop?: "none" | "dark-gradient";
+    orientation?: "horizontal" | "vertical-rl";
+    variant?: "hero" | "standard";
+}
+
+export declare interface StoryDocument {
+    schemaVersion: 1;
+    defaultLocale: string;
+    fallbackLocales?: string[];
+    title: LocalizedText;
+    themes: Record<string, StoryTheme>;
+    scenes: StoryScene[];
+}
+
+export declare interface StoryExternalLinkAttributes {
+    href: string;
+    target: "_blank";
+    rel: "noopener noreferrer";
+    textContent: string;
+}
+
+export declare function storyExternalLinkAttributes(reference: StoryReference, label: string): StoryExternalLinkAttributes;
+
+export declare interface StoryFrameScheduler {
+    request(callback: FrameRequestCallback): number;
+    cancel(handle: number): void;
+}
+
+/** Url hash, without the leading "#", for a scene and its play state. */
+export declare function storyHash(scene: string, paused: boolean): string;
+
+/** Shareable position in a story: the scene and whether playback holds. */
+export declare interface StoryHashState {
+    scene?: string;
+    paused?: boolean;
+}
+
+export declare interface StoryPagerElement extends HTMLElement {
+    /** Rebuild for `count` steps with the given labels. */
+    configure(count: number, labels: StoryPagerLabels): void;
+    /** Active step, 0-based. */
+    index: number;
+    playing: boolean;
+    /** Progress of the active step while playing, 0–1. */
+    progress: number;
+    disabled: boolean;
+}
+
+/** A step button, or a gap standing for hidden steps. */
+export declare type StoryPagerItem = number | "gap";
+
+/**
+ * Step buttons to show: all of them when they fit in `slots`, else the first,
+ * the last and the steps around `current`, with a gap for each hidden run.
+ * A gap takes one slot and always hides at least two steps.
+ */
+export declare function storyPagerItems(count: number, current: number, slots?: number): StoryPagerItem[];
+
+/** Accessible names of the pager controls, in the story locale. */
+export declare interface StoryPagerLabels {
+    navigation: string;
+    previous: string;
+    next: string;
+    play: string;
+    pause: string;
+    /** Name of step `index` (0-based), e.g. "3 — Arctic". */
+    step(index: number): string;
+}
+
+/** Detail of the `story-pager-navigate` event: the requested step. */
+export declare interface StoryPagerNavigateDetail {
+    index: number;
+}
+
+export declare type StoryPlayback = {
+    mode: "none";
+} | {
+    mode: "autoplay";
+} | {
+    mode: "sequence";
+    times: string[];
+    intervalMs: number;
+    direction?: "loop" | "ping-pong";
+};
+
+export declare interface StoryReference {
+    label: LocalizedText;
+    url: string;
+}
+
+export declare class StoryRegistry {
+    private readonly viewFactories;
+    private readonly viewAdapters;
+    private readonly widgets;
+    registerViewType(type: string, factory: StoryViewAdapterFactory): this;
+    registerWidgetType(type: string, renderer: StoryWidgetRenderer): this;
+    getViewAdapter(type: string): StoryViewAdapter;
+    getWidget(type: string): StoryWidgetRenderer;
+    destroy(): void;
+}
+
+export declare interface StoryScene {
+    id: string;
+    name: LocalizedText;
+    chapter?: string;
+    theme: string;
+    /** A layout id the app renders; see `StoryValidationOptions.layouts`. */
+    layout: string;
+    blocks: StoryBlock[];
+    playback?: StoryPlayback;
+    /** Auto-advance: time on this scene before the next, when the story plays. */
+    durationMs?: number;
+}
+
+/**
+ * Auto-advance clock of one scene: runs for a duration, pauses and resumes
+ * keeping the elapsed time, and calls `onDone` once when it runs out.
+ */
+export declare class StorySceneTimer {
+    private readonly onDone;
+    private readonly now;
+    private durationMs;
+    private elapsedMs;
+    private startedAt;
+    private timer;
+    constructor(onDone: () => void, now?: () => number);
+    /** Restart from zero; runs at once unless `paused`. */
+    start(durationMs: number, paused?: boolean): void;
+    get running(): boolean;
+    /** Elapsed share of the duration, 0–1. */
+    get progress(): number;
+    pause(): void;
+    resume(): void;
+    /** Stop without firing; the progress drops to zero. */
+    stop(): void;
+    private clear;
+}
+
+/** The part of IntersectionObserverEntry the scroller reads. */
+export declare interface StoryScrollEntry {
+    target: Element;
+    isIntersecting: boolean;
+}
+
+/**
+ * Scroll-driven scene activation: watches a list of sections and reports the
+ * one crossing the activation line. Between sections, the last one stays
+ * active, so a gap or a section taller than the viewport never blanks the
+ * view. No scroll listener: one IntersectionObserver.
+ */
+export declare class StoryScroller {
+    private readonly sections;
+    private readonly onActivate;
+    private readonly observer;
+    private readonly crossing;
+    private activeIndex;
+    /**
+     * @param sections Scene sections in document order.
+     * @param onActivate Called once each time another section becomes active.
+     */
+    constructor(sections: readonly Element[], onActivate: (index: number, section: Element) => void, options?: StoryScrollerOptions);
+    /** Index of the active section, -1 before the first one is reached. */
+    get active(): number;
+    destroy(): void;
+    private update;
+}
+
+export declare interface StoryScrollerOptions {
+    /**
+     * Activation line, as a share of the viewport height from the top: the
+     * section that crosses it is the active one. Defaults to 0.5.
+     */
+    line?: number;
+    /** Scroll container; the viewport when omitted. */
+    root?: Element | null;
+    createObserver?: StoryScrollObserverFactory;
+}
+
+/** The part of IntersectionObserver the scroller uses; injectable for tests. */
+export declare type StoryScrollObserverFactory = (callback: (entries: readonly StoryScrollEntry[]) => void, init: IntersectionObserverInit) => {
+    observe(target: Element): void;
+    disconnect(): void;
+};
+
+export declare type StorySlot = "copy" | "stage" | "analysis" | "edge";
+
+export declare interface StoryTextBlock extends StoryBlockBase {
+    type: "text" | "credit" | "label";
+    text: LocalizedText;
+    orientation?: "horizontal" | "vertical-rl";
+    variant?: "standard" | "small";
+}
+
+export declare interface StoryTheme {
+    background: string;
+    foreground: string;
+    muted: string;
+    accent: string;
+    accentSoft: string;
+    surface: string;
+    glowAnchor?: StoryAnchor;
+}
+
+/** Coordinates an immediate cursor update with at most one layer seek per frame. */
+export declare class StoryTimeInteraction {
+    private readonly callbacks;
+    private readonly frames;
+    private active;
+    private resumeAfterInteraction;
+    private latestTime;
+    private appliedTime;
+    private frame;
+    constructor(callbacks: StoryTimeInteractionCallbacks, frames?: StoryFrameScheduler);
+    get interacting(): boolean;
+    begin(): void;
+    request(time: number): void;
+    end(): void;
+    /** Abandons pending work without resuming playback (for navigation/cleanup). */
+    cancel(): void;
+    private applyLatest;
+    private cancelFrame;
+}
+
+export declare interface StoryTimeInteractionCallbacks {
+    isPlaying(): boolean;
+    pause(): void;
+    apply(time: number): void;
+    present(time: number): void;
+    finish(time: number | null, resume: boolean): void;
+}
+
+export declare class StoryTimePresentation {
+    private enabled;
+    get visible(): boolean;
+    setScene(scene: StoryScene): void;
+    accept(time: number): number | null;
+}
+
+export declare interface StoryValidationOptions {
+    /** Scene layout ids the app renders. */
+    layouts?: readonly string[];
+}
+
+export declare interface StoryViewAdapter {
+    activate(view: StoryViewDefinition, scene: StoryScene): Promise<void> | void;
+    play?(): Promise<void> | void;
+    pause?(): void;
+    setTime?(time: number): void;
+    deactivate?(): void;
+    destroy(): void;
+}
+
+export declare type StoryViewAdapterFactory = () => StoryViewAdapter;
+
+export declare interface StoryViewBlock extends StoryBlockBase {
+    type: "view";
+    view: string;
+    presentation?: "background" | "panel";
+}
+
+export declare interface StoryViewDefinition {
+    id: string;
+    type: string;
+    config: Record<string, unknown>;
+}
+
+export declare interface StoryViewsDocument {
+    schemaVersion: 1;
+    views: StoryViewDefinition[];
+}
+
+export declare interface StoryWidgetBlock extends StoryBlockBase {
+    type: "widget";
+    widget: string;
+    config?: Record<string, unknown>;
+    caption?: LocalizedText;
+}
+
+export declare type StoryWidgetCleanup = () => void;
+
+export declare interface StoryWidgetContext {
+    scene: StoryScene;
+    block: StoryWidgetBlock;
+    locale: string;
+    signal: AbortSignal;
+    getViewAdapter(viewId: string): StoryViewAdapter | undefined;
+    setTimeCursor(cursor: (time: number) => void): void;
+    beginTimeInteraction(): void;
+    requestTime(time: number): void;
+    endTimeInteraction(): void;
+}
+
+export declare class StoryWidgetLifecycle {
+    private readonly onCleanupError;
+    private generation;
+    private controller;
+    private cleanup;
+    constructor(onCleanupError?: (error: unknown) => void);
+    begin(): StoryWidgetRun;
+    cancel(): void;
+    private invoke;
+}
+
+export declare type StoryWidgetRenderer = (host: HTMLElement, config: Record<string, unknown>, context: StoryWidgetContext) => Promise<(() => void) | void> | (() => void) | void;
+
+export declare interface StoryWidgetRun {
+    readonly signal: AbortSignal;
+    isCurrent(): boolean;
+    runIfCurrent(effect: () => void): boolean;
+    settle(cleanup: StoryWidgetCleanup | void): void;
+}
+
+export declare function validateStoryDocument(value: unknown, options?: StoryValidationOptions): asserts value is StoryDocument;
+
+export declare function validateStoryReferences(story: StoryDocument, views: StoryViewsDocument): void;
+
+export declare function validateViewsDocument(value: unknown): asserts value is StoryViewsDocument;
+
+export { }