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

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 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';
 
 type ButtonVariant = 'primary' | 'secondary' | 'ghost';
 type ButtonSize = 'sm' | 'md' | 'lg';
@@ -124,4 +126,383 @@ interface LogoWordmarkProps extends React.SVGAttributes<SVGSVGElement> {
 }
 declare function LogoWordmark({ width, title, ...rest }: LogoWordmarkProps): react_jsx_runtime.JSX.Element;
 
-export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, LogoMonogram, LogoMonogramBg, type LogoMonogramBgProps, type LogoMonogramProps, LogoWordmark, type LogoWordmarkProps };
+interface LogoProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Mark id, e.g. `dissertation_ai_OVERLAP`. */
+    name: LogoId;
+    /** PATH (default), CUTOUT, BG, or LETTERS. See @dataimago/brand. */
+    variant?: LogoVariant;
+    /**
+     * Render width (px number or any CSS length). Height scales proportionally
+     * via the SVG viewBox. Omit to use the mark's intrinsic size.
+     */
+    width?: number | string;
+}
+/**
+ * Manifest-driven brand mark from `@dataimago/brand`. Inlines the SVG string so
+ * `currentColor` (PATH/LETTERS), the `--color-interactive-accent` badge fill
+ * (CUTOUT/BG), and the per-letter interaction classes (`.glyph`, `.logo-*`) all
+ * work — an `<img src>` can't receive those interior styles.
+ *
+ * Color flows from CSS: set `color` (PATH/LETTERS) on this element or an
+ * ancestor. Size via `width` (or CSS on the wrapper).
+ */
+declare function Logo({ name, variant, width, style, ...rest }: LogoProps): react_jsx_runtime.JSX.Element | null;
+
+/** A link the lockup renders; pass one to route through a framework link (e.g. next/link). */
+interface CopulaLinkProps {
+    href: string;
+    'aria-label': string;
+    className?: string;
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+interface CopulaLockupProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** The property's wordmark id, e.g. `dissertation_ai`. Its PATH variant is drawn. */
+    property: LogoId;
+    /** Accessible name of the property link, e.g. `dissertation-ai`. */
+    propertyLabel: string;
+    /** Where the property mark links. Defaults to `/`. */
+    propertyHref?: string;
+    /**
+     * `shown` (default): "<property> is dataimago". `hidden`: the property mark
+     * alone, with no badge, no dataimago wordmark and no link to dataimago, for
+     * apps that keep dataimago out of view while it is in stealth.
+     */
+    dataimago?: 'shown' | 'hidden';
+    /** Where the dataimago wordmark links. Defaults to https://dataimago.ai. */
+    brandHref?: string;
+    /** Wordmark height in px. Defaults to 32; the badge and spacing scale with it. */
+    height?: number;
+    /** Class for each link (colour and hover); both links share one treatment. */
+    linkClassName?: string;
+    /**
+     * Class for the `is` disc. It is not a link, so `linkClassName` does not reach
+     * it: give it the links' rest colour here (e.g. the same `text-*` class
+     * without the hover). Without it the disc takes the lockup's colour.
+     */
+    badgeClassName?: string;
+    /** Render the links with a framework component. Defaults to a plain `<a>`. */
+    renderLink?: (props: CopulaLinkProps) => React.ReactNode;
+}
+/**
+ * The copula lockup, "dissertation-ai **is** dataimago": the property wordmark,
+ * the `is_badge` disc and the dataimago wordmark, each wordmark its own link
+ * (wiki/connections/is-copula-coupling.md). The badge is a mark, not a link: at
+ * 16px it is below the 24px pointer-target floor (WCAG 2.5.8), so it is read as
+ * "is" and the philosophy page stays reachable from the nav.
+ *
+ * Spacing is ink-symmetric about the badge centre, computed from each mark's
+ * `ink` box in the @dataimago/brand manifest, so any property mark lines up
+ * without hand-tuned margins. Geometry is inline style (no Tailwind), so a
+ * consumer on plain CSS can use it too. Every piece is `currentColor`: the
+ * wordmarks take their link's colour (`linkClassName`, or the page's link
+ * colour), the disc takes `badgeClassName`'s, or the lockup's.
+ */
+declare function CopulaLockup({ property, propertyLabel, propertyHref, dataimago, brandHref, height, linkClassName, badgeClassName, renderLink, style, ...rest }: CopulaLockupProps): react_jsx_runtime.JSX.Element | null;
+
+interface BrandAnimationProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Animation id, e.g. `dissertation-ai`. See @dataimago/brand animations.json. */
+    name: AnimationId;
+    /**
+     * Render width (px number or any CSS length). Height scales via the SVG
+     * viewBox. Omit to use the animation's intrinsic size.
+     */
+    width?: number | string;
+}
+/**
+ * Decorative brand animation from `@dataimago/brand` (the animation-foundry).
+ * Inlines the pure-SMIL SVG string so its interior `<style>` works — an
+ * `<img src>` can't receive those styles (same rationale as `<Logo>`).
+ *
+ * Motion-dignity: decorative brand animation is a distinct category from the
+ * 300ms UI-transition ceiling, but it is contractually gated on
+ * `prefers-reduced-motion`. When the user prefers reduced motion this renders
+ * the static brand mark the animation settles to (its `poster`) via `<Logo>`,
+ * so no consumer can ship the motion without the fallback.
+ */
+declare function BrandAnimation({ name, width, style, ...rest }: BrandAnimationProps): react_jsx_runtime.JSX.Element | null;
+
+interface NavbarLogoProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Navbar mark id, e.g. `dissertation-ai`. See @dataimago/brand navbar.json. */
+    name: NavbarLogoId;
+    /**
+     * Render width (px number or any CSS length). Height scales via the SVG
+     * viewBox. Omit to use the mark's intrinsic size.
+     */
+    width?: number | string;
+}
+/**
+ * Animated brand mark for an app navbar, from `@dataimago/brand` (the
+ * animation-foundry's navbar set). Inlines the self-contained CSS-animated SVG
+ * so its interior `<style>` works — an `<img src>` can't receive those styles.
+ *
+ * Behaviour by mark kind (from the navbar manifest):
+ *   - `assemble` (L2: dissertation-ai, rpkg-ai, SGPc-ai): the trailing `a`/`i`
+ *     start apart and the `i` slides onto the `a`. Plays once on mount; replays
+ *     on pointer-enter via a remount (`replayKey`).
+ *   - `shimmer` (L1: dataimago-ai): the monogram is always superimposed; an
+ *     accent shimmer sweeps on `:hover` from the SVG's own CSS (no JS trigger).
+ *   - `dream` (promoted dream marks, `tools/dream-foundry/drop.mjs promote`):
+ *     a self-contained CSS hover gesture like liftwash; the poster is the mark's
+ *     own static form (`dream_<slug>` / `DREAM`). Ink is `currentColor`.
+ *
+ * Motion-dignity: the embedded CSS animation is <= 300ms and gated on
+ * `@media (prefers-reduced-motion: no-preference)`. When the user prefers
+ * reduced motion this renders the static settled mark (the manifest `poster`,
+ * the superimposed monogram) via `<Logo>` — so no consumer can ship the motion
+ * without the fallback.
+ */
+declare function NavbarLogo({ name, width, style, ...rest }: NavbarLogoProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Light/dark theme preference for dataimago apps.
+ *
+ * The house tokens (`@dataimago/tokens`) follow the operating system through
+ * `prefers-color-scheme` and yield to an explicit `data-bs-theme` on the root:
+ * `light` or `dark` forces that theme, no attribute means "follow the system".
+ * This module owns that attribute: it reads and stores the reader's choice,
+ * applies it, and reports the theme actually in effect (for canvas and WebGL
+ * surfaces that cannot read CSS variables).
+ *
+ * The choice is a per-browser convenience in localStorage. Every read and write
+ * is guarded: in a private window or with storage blocked the page simply
+ * follows the system.
+ */
+type ThemePreference = 'system' | 'light' | 'dark';
+type ResolvedTheme = 'light' | 'dark';
+declare const THEME_STORAGE_KEY = "dataimago-theme";
+declare const THEME_ATTRIBUTE = "data-bs-theme";
+/**
+ * Inline this in `<head>` before any stylesheet paints, so a stored choice is
+ * on the root before first paint (no flash of the other theme). The server
+ * markup cannot know the choice, so the consumer also puts
+ * `suppressHydrationWarning` on `<html>`. From a React server layout, render
+ * `<ThemeScript />` instead: this package is a client bundle, so a server
+ * component cannot import the string itself.
+ *
+ * ```tsx
+ * <html lang="en" suppressHydrationWarning>
+ *   <head><ThemeScript /></head>
+ * ```
+ */
+declare const themeInitScript: string;
+/** The stored choice, or `'system'` when there is none (or storage is unavailable). */
+declare function readThemePreference(): ThemePreference;
+/** Store, apply and announce a choice. `'system'` clears the stored choice. */
+declare function setThemePreference(preference: ThemePreference): void;
+/** The theme in effect: the root attribute when set, otherwise the system's. */
+declare function resolveTheme(): ResolvedTheme;
+/**
+ * The reader's choice and a setter. Server render and hydration see
+ * `'system'`; the stored choice arrives right after.
+ */
+declare function useThemePreference(): [ThemePreference, (p: ThemePreference) => void];
+/**
+ * The theme in effect, for surfaces that cannot read CSS variables (canvas,
+ * WebGL maps). Follows the toggle and, under "system", the operating system.
+ * Server render and hydration see `'light'`.
+ */
+declare function useResolvedTheme(): ResolvedTheme;
+
+interface ThemeToggleLabels {
+    /** What the control sets, read before the theme in effect ("Theme: Light"). */
+    name: string;
+    /** Added when the theme follows the operating system ("Theme: Light (System)"). */
+    system: string;
+    light: string;
+    dark: string;
+}
+interface ThemeToggleProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'children' | 'type'> {
+    /** Accessible and tooltip text; pass the property's own wording. */
+    labels?: Partial<ThemeToggleLabels>;
+}
+/**
+ * The choice one click makes: the other theme, stored as "system" when that is
+ * the operating system's own, so the page goes back to following it.
+ */
+declare function nextThemePreference(shown: ResolvedTheme, system: ResolvedTheme): ThemePreference;
+/**
+ * Light/dark toggle for an app navbar: one button, and one click always flips
+ * the theme on screen. The page follows the operating system until the first
+ * click; a click that lands on the system's own theme goes back to following
+ * it (no stored choice), and the other theme is stored and set as
+ * `data-bs-theme` on the root, which the house tokens obey. The icon shows the
+ * theme in effect: a sun in light, a moon in dark.
+ *
+ * A 48px target (the dataimago touch floor). The icon is `currentColor`.
+ * Inline styles would beat a consumer's `:hover` rule, so the two colours a
+ * navbar restyles read custom properties instead: set `--di-theme-toggle-fg`
+ * and `--di-theme-toggle-bg` on `.di-ui-theme-toggle` (and its `:hover`).
+ * Pair it with `<ThemeScript />` in `<head>` so a stored choice applies before
+ * first paint.
+ */
+declare function ThemeToggle({ labels, className, style, ...rest }: ThemeToggleProps): react_jsx_runtime.JSX.Element;
+
+interface ThemeScriptProps {
+    /** Content-Security-Policy nonce, when the app sets one. */
+    nonce?: string;
+}
+/**
+ * Renders `themeInitScript` as an inline `<script>`, so a stored choice is on
+ * the root before first paint. Use this from a server layout: this package is
+ * a client bundle, so a server component cannot import the plain string, but
+ * it can render this component. Put it in `<head>` and add
+ * `suppressHydrationWarning` to `<html>` (the script changes its attributes
+ * before React hydrates).
+ */
+declare function ThemeScript({ nonce }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
+
+/** 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 };