@dataimago/ui 0.1.0-alpha.35 → 0.1.0-alpha.42

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import React__default from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { LogoId, LogoVariant, AnimationId, NavbarLogoId } from '@dataimago/brand';
 
@@ -351,4 +352,157 @@ interface ThemeScriptProps {
  */
 declare function ThemeScript({ nonce }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
 
-export { BrandAnimation, type BrandAnimationProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CopulaLinkProps, CopulaLockup, type CopulaLockupProps, Logo, LogoMonogram, LogoMonogramBg, type LogoMonogramBgProps, type LogoMonogramProps, type LogoProps, LogoWordmark, type LogoWordmarkProps, NavbarLogo, type NavbarLogoProps, type ResolvedTheme, THEME_ATTRIBUTE, THEME_STORAGE_KEY, type ThemePreference, ThemeScript, type ThemeScriptProps, ThemeToggle, type ThemeToggleLabels, type ThemeToggleProps, nextThemePreference, readThemePreference, resolveTheme, setThemePreference, themeInitScript, useResolvedTheme, useThemePreference };
+/** The captions file a video release carries beside its WebVTT fallback. */
+declare const CAPTIONS_SCHEMA = "dataimago.video_captions.v1";
+type CaptionTreatment = 'editorial' | 'frosted' | 'boxed';
+interface CaptionWord {
+    /** The word as the script spells it; inline math stays a `$…$` span. */
+    text: string;
+    /** Spoken start, in the page's time unit: the word tones from inkMute to ink from here. */
+    at: number;
+    /** The line of the page the word sits on. */
+    line: number;
+    /** MathML for the word's `$…$` span, rendered by the foundry (Temml) at export. */
+    math?: string;
+}
+interface CaptionPage {
+    start: number;
+    end: number;
+    lines: string[];
+    words: CaptionWord[];
+}
+interface CaptionTrack {
+    schema: typeof CAPTIONS_SCHEMA;
+    work: string;
+    version: string;
+    lang: string;
+    style: {
+        profile: string;
+        treatment: CaptionTreatment;
+        /** Font weight of the caption text (400 when boxed). */
+        weight: number;
+        /** How long a word takes to tone from inkMute to ink, in seconds. */
+        toneSeconds: number;
+        lineHeight: number;
+        /** The profile's colour tokens (`color.palette.<scale>.<step>`); the player maps them to CSS variables. */
+        colors?: {
+            paper: string;
+            ink: string;
+            inkMute: string;
+        };
+    };
+    /** The canvas the captions were laid out on, in pixels: scale everything by displayed width ÷ width. */
+    frame: {
+        width: number;
+        height: number;
+        fontSize: number;
+        safe: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    /** In seconds from the start of the video, in order, never overlapping. */
+    pages: CaptionPage[];
+}
+/** The page on screen at time t (start ≤ t < end), if any. Pages must be in order. */
+declare function pageAt<P extends {
+    start: number;
+    end: number;
+}>(pages: readonly P[], t: number): P | undefined;
+/** How far a word has toned toward ink at time t: 0 before it is spoken, 1 once it has settled. */
+declare function wordTone(at: number, t: number, span: number): number;
+/** The colour for a tone between inkMute (0) and ink (1). */
+declare function toneColor(tone: number, ink: string, inkMute: string): string;
+/** A word's text split around its `$…$` span, or null when it carries no math. */
+declare function splitMath(text: string): {
+    before: string;
+    tex: string;
+    after: string;
+} | null;
+/** A palette token path as a CSS variable (`color.palette.stone.50` → `var(--color-palette-stone-50)`), or null if it is not one. */
+declare function paletteVar(token: string): string | null;
+type CaptionStyle = Record<string, string | number>;
+interface CaptionLook {
+    /** The panel around the lines. */
+    panel: CaptionStyle;
+    /** The text block: family, weight, size, line height. */
+    text: CaptionStyle;
+    /** Extra lift above the safe area, in pixels, so a panel's soft shadow stays inside it too. */
+    lift: number;
+    /** Whether words tone from inkMute to ink (boxed captions are one colour). */
+    toned: boolean;
+}
+/**
+ * The treatment at one size. `scale` multiplies the profile's fixed pixel measures
+ * (blur, border, radius on a boxed panel) and is 1 on the foundry's canvas.
+ */
+declare function captionLook(treatment: CaptionTreatment, o: {
+    size: number;
+    scale: number;
+    weight: number;
+    lineHeight: number;
+    family: string;
+    ink: string;
+    paper: string;
+}): CaptionLook;
+
+interface CaptionedVideoProps {
+    src: string;
+    /** The release's poster frame: required, as the player shows it until the reader presses play (explanatory-video-carve-out, decision 2). */
+    poster: string;
+    /** The release's captions file (dataimago.video_captions.v1): pages, word timing, MathML. */
+    captions: string;
+    /** The release's WebVTT captions: the native track, and the text drawn if `captions` fails to load. */
+    fallbackCaptions: string;
+    /** The release's WebVTT chapters. */
+    chapters?: string;
+    /** The video's accessible name. */
+    title: string;
+    /** BCP 47 language of the captions. */
+    lang?: string;
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+/** Where the reader's captions choice is kept (per browser). */
+declare const CAPTIONS_STORAGE_KEY = "dataimago:video-captions";
+/** A captions file the layer can draw; anything else takes the WebVTT fallback. */
+declare function isCaptionTrack(x: unknown): x is CaptionTrack;
+/**
+ * A video with the dataimago caption treatment drawn over it: the foundry's fonts,
+ * word tone and mathematics, from the release's captions file. The native WebVTT
+ * track stays hidden underneath, for assistive technology and as the fallback text.
+ * Fullscreen takes the whole player, so the captions come along.
+ */
+declare const CaptionedVideo: React__default.FC<CaptionedVideoProps>;
+
+interface CaptionLayerProps {
+    track: CaptionTrack;
+    /** Seconds into the video. */
+    time: number;
+    /** The video's displayed width in CSS pixels; size and insets scale from the track's canvas. */
+    width: number;
+    /**
+     * Show each page in full ink, as the foundry's reduced-motion render does. Defaults to
+     * true, the safe side; pass the reader's `prefers-reduced-motion` (CaptionedVideo does).
+     */
+    reducedMotion?: boolean;
+    /**
+     * Keep the captions at least this far above the bottom edge, in CSS pixels (the
+     * player's controls). They move up only when their own place would sit lower.
+     */
+    clearance?: number;
+    /** A page to show instead of the track's (the WebVTT fallback, already in full ink). */
+    page?: CaptionPage | null;
+}
+/**
+ * The captions over a video, in the foundry's treatment, at time `time`. Pure
+ * presentation: the caller supplies the clock and the size. The drawn layer is hidden
+ * from assistive technology; the current page is also present as visually hidden plain
+ * text, not a live region, so a braille or screen-reader user can find it without every
+ * line being spoken over the narration.
+ */
+declare const CaptionLayer: React__default.FC<CaptionLayerProps>;
+
+export { BrandAnimation, type BrandAnimationProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, CAPTIONS_SCHEMA, CAPTIONS_STORAGE_KEY, CaptionLayer, type CaptionLayerProps, type CaptionLook, type CaptionPage, type CaptionTrack, type CaptionTreatment, type CaptionWord, CaptionedVideo, type CaptionedVideoProps, type CopulaLinkProps, CopulaLockup, type CopulaLockupProps, Logo, LogoMonogram, LogoMonogramBg, type LogoMonogramBgProps, type LogoMonogramProps, type LogoProps, LogoWordmark, type LogoWordmarkProps, NavbarLogo, type NavbarLogoProps, type ResolvedTheme, THEME_ATTRIBUTE, THEME_STORAGE_KEY, type ThemePreference, ThemeScript, type ThemeScriptProps, ThemeToggle, type ThemeToggleLabels, type ThemeToggleProps, captionLook, isCaptionTrack, nextThemePreference, pageAt, paletteVar, readThemePreference, resolveTheme, setThemePreference, splitMath, themeInitScript, toneColor, useResolvedTheme, useThemePreference, wordTone };