@exponential_app/eui 0.2.1 → 0.4.0

package/dist/types/src/web/primitives/motion.d.ts

@@ -0,0 +1,162 @@
+import { type ModeName, type ResolvedTheme } from "@exponential_app/eui";
+import type { HostPlugin } from "../host-types.js";
+import { type MotionFit } from "./motion-paint.js";
+export { paintMotionFrame, motionFitMatrix, motionConcat, motionFrameSize, MotionCanvasPool } from "./motion-paint.js";
+export type { MotionFit, MotionMatrix } from "./motion-paint.js";
+/** At most this many Motions animate per surface (tree order). */
+export declare const MOTION_MAX_PLAYING = 8;
+/** At most this many frames per second. */
+export declare const MOTION_MAX_FPS = 60;
+export interface MotionEnv {
+    theme: ResolvedTheme;
+    mode: ModeName;
+    reducedMotion: boolean;
+    host: HostPlugin;
+    /** A load failure (the box stays empty): the wrapper reports it as a paint error. */
+    onError?: (message: string) => void;
+    /** The node's `on` events (the wrapper's A2UI action plumbing). */
+    emit?: MotionEmit;
+    /** `on.press` is set: the Motion is a button (Enter / Space press it). */
+    pressable?: boolean;
+}
+/** The events a Motion fires (its `on`); `state` carries `{state}`. */
+export type MotionEvent = `press` | `hover` | `visible` | `complete` | `state`;
+export type MotionEmit = (event: MotionEvent, payload?: Record<string, unknown>) => void;
+type Props = Record<string, unknown>;
+/** The composition size a node declares without loading anything (the
+ *  dialect's `size`, an inline Lottie's `w`/`h`); null for `src`. */
+export declare function motionDeclaredSize(props: Props): [number, number] | null;
+/** Contract §4 (shared with eui-core's layout): an unstyled box is the
+ *  composition's px width, shrinking to the available width, aspect kept;
+ *  a style width or height wins (the aspect still fills the other edge). */
+export declare function motionBoxStyle(size: [number, number] | null, nodeStyle: unknown): Record<string, string>;
+/** The fit prop, defaulted. */
+export declare function motionFit(value: unknown): MotionFit;
+/** Contract §6: role img named by `label`; hidden (decorative) without one.
+ *  M4 §4: with `on.press` (`pressable`) a focusable button named by `label`. */
+export declare function motionA11y(label: unknown, pressable?: boolean): {
+    role?: `img` | `button`;
+    tabIndex?: number;
+    "aria-label"?: string;
+    "aria-hidden"?: `true`;
+};
+/** The theme's slot overrides for `slotIds` (contract §2). */
+export declare function motionThemeSlots(slotIds: readonly string[], theme: ResolvedTheme, mode: ModeName, own: unknown): Record<string, unknown>;
+/** Whether this environment paints Motions at all. */
+export declare function motionCanPaint(): boolean;
+/** A .lottie archive's first animation as Lottie JSON, its images inlined. */
+export declare function motionFromDotLottie(bytes: Uint8Array): Promise<string>;
+/** A .lottie archive's first animation (Lottie JSON, images inlined) and its
+ *  first state machine (dotLottie 2 `s/<id>.json`, v1 `states/`), or null. */
+export declare function motionDotLottie(bytes: Uint8Array): Promise<{
+    lottie: string;
+    stateMachine: Record<string, unknown> | null;
+}>;
+/** The engine's state-machine API (the WASM `MotionPlayer`). */
+export interface MotionMachinePlayer {
+    setStateMachine(json: string): boolean;
+    smPost(kind: string, layer: string): boolean;
+    smSetInputs(json: string): boolean;
+    smStatus(): string;
+}
+/** A Motion's state machine half (README › Interactivity §1–4). The engine
+ *  interprets the machine; this posts interactions and inputs to it, restarts
+ *  the clock when the state changes and turns its status into events:
+ *  `state` for every entered state (`{state}`), `complete` once per state
+ *  when its play finished or it is final. Without a machine it still reports
+ *  `complete` for a finished finite play. */
+export declare class MotionStateDriver {
+    private readonly player;
+    private readonly emit;
+    /** The state changed: restart the clock at 0. */
+    private readonly restart;
+    private machineKey;
+    private inputsKey;
+    private completeSent;
+    running: boolean;
+    constructor(player: MotionMachinePlayer, emit: MotionEmit, 
+    /** The state changed: restart the clock at 0. */
+    restart: () => void);
+    /** Start (or restart, when its JSON changed) the machine; null = none.
+     *  Returns whether one runs (its state's playback replaces the props'). */
+    setMachine(machine: unknown): boolean;
+    /** The node's `inputs` (literal or bound): written on every change. */
+    setInputs(inputs: unknown): void;
+    /** An interaction (`click`, `pointerDown`, `pointerUp`, `pointerEnter`, `pointerExit`). */
+    post(kind: string, layer?: string): void;
+    /** The clock reported `done` for the current play. */
+    done(): void;
+    /** A new play without a machine (the playback props changed). */
+    replay(): void;
+    private changed;
+    private drain;
+}
+/** One Motion on the page: load, clock, paint. `update` on every prop or
+ *  environment change; `destroy` on unmount. */
+export declare class MotionView {
+    readonly root: HTMLElement;
+    readonly canvas: HTMLCanvasElement;
+    private props;
+    private nodeStyle;
+    private env;
+    private sourceKey;
+    private slotsKey;
+    private playbackKey;
+    private generation;
+    private lottie;
+    /** A `.lottie` src's first state machine. */
+    private fileMachine;
+    private driver;
+    private halfSeen;
+    private visibleSent;
+    private slotIds;
+    private player;
+    private images;
+    private pool;
+    private io;
+    private ro;
+    private visible;
+    private surface;
+    private raf;
+    private last;
+    private lastPaint;
+    private elapsed;
+    private finished;
+    private restarts;
+    private inTick;
+    private painted;
+    private destroyed;
+    constructor(root: HTMLElement, canvas: HTMLCanvasElement);
+    /** `nodeStyle` = the node's own `style` (a style width/height wins over the composition size). */
+    update(props: Props, env: MotionEnv, nodeStyle?: unknown): void;
+    private emit;
+    /** `on.visible` once, as soon as there is an env to emit through. */
+    private flushVisible;
+    private onClick;
+    private onKey;
+    private onPointer;
+    /** The machine (the prop, else the file's) and its inputs → the engine. */
+    private applyMachine;
+    /** The state changed: the clock restarts at 0. */
+    private restartClock;
+    destroy(): void;
+    private fail;
+    private load;
+    private free;
+    /** (Re)build the player from the loaded Lottie with the current slots. */
+    private instantiate;
+    private loadImages;
+    private applyPlayback;
+    private wantsToAnimate;
+    private leaveSurface;
+    /** Start or stop the clock to match the state; paint the still frame when stopped. */
+    schedule(): void;
+    private stop;
+    private tick;
+    /** The frame shown while the clock is stopped. */
+    private stillFrame;
+    private repaint;
+    private paint;
+}
+/** Test seam: forget the per-theme ids (a fresh module state). */
+export declare function resetMotionThemeIds(): void;

package/dist/types/src/web/primitives/outline.d.ts

@@ -0,0 +1,22 @@
+export declare const OUTLINE_GEOMETRY: {
+    readonly rowHeight: 32;
+    readonly activeBar: 2;
+};
+export interface OutlineItem {
+    id: string;
+    title: string;
+    /** A muted `· n` after the title; 0 or unset = none. */
+    count?: number | null;
+}
+export declare const OUTLINE_CLASSES: {
+    readonly root: "flex min-w-0 flex-col gap-[2px]";
+    readonly caption: "px-2 py-1 text-[11px] leading-4 font-medium tracking-[0.5px] text-muted-foreground uppercase";
+    /** One row: a button, the active one `data-active=true`. */
+    readonly row: "relative flex h-[32px] w-full min-w-0 cursor-pointer items-center gap-1 overflow-hidden rounded-md px-2 text-start text-sm text-muted-foreground outline-none transition-colors duration-fast hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/50 data-[active=true]:bg-accent data-[active=true]:font-medium data-[active=true]:text-foreground";
+    /** The leading-edge bar of the active row. */
+    readonly bar: "pointer-events-none absolute inset-y-0 start-0 w-[2px] bg-foreground";
+    readonly title: "min-w-0 flex-1 truncate";
+    readonly count: "shrink-0 text-xs text-muted-foreground tabular-nums";
+};
+/** The trailing count text (`· n`), or null when there is none. */
+export declare function outlineCountText(count: number | null | undefined): string | null;

package/dist/types/src/web/primitives/zoomable-image.d.ts

@@ -0,0 +1,158 @@
+import type * as Zoom from "../../zoom.js";
+import type { ZoomFrame, ZoomInitial, ZoomSize, ZoomView } from "../../zoom.js";
+type Core = typeof Zoom;
+/** The core functions the controller drives (`@exponential_app/eui`). */
+export type ZoomMath = Pick<Core, `ZOOM` | `zoomIsTall` | `zoomRestView` | `zoomClamp` | `zoomAtRest` | `zoomTo` | `zoomCentre` | `zoomWheel` | `zoomScroll` | `zoomStep` | `zoomDoubleTap` | `zoomKey` | `zoomDrag` | `zoomPinch` | `zoomMomentum` | `zoomMomentumActive` | `zoomPanRoom` | `zoomResize` | `zoomPercent` | `zoomMenu` | `zoomBounds`>;
+export declare const ZOOM_CONTROLS: readonly ["auto", "always", "none"];
+export type ZoomControls = (typeof ZOOM_CONTROLS)[number];
+/** What the pill draws (changes only when one of these does). */
+export interface ZoomPillState {
+    percent: string;
+    atMin: boolean;
+    atMax: boolean;
+    atRest: boolean;
+}
+/** Two taps / clicks closer than this (ms, px) are a double tap. */
+export declare const ZOOM_DOUBLE_TAP_MS = 300;
+export declare const ZOOM_DOUBLE_TAP_SLOP = 24;
+/** A press that moves less than this (px) is a tap, not a drag. */
+export declare const ZOOM_TAP_SLOP = 4;
+/** A ⌘/ctrl-wheel run settles (fires `zoom`) after this idle (ms). */
+export declare const ZOOM_WHEEL_SETTLE_MS = 150;
+/** The box's CSS aspect ratio (w/h): the picture's own, capped at the width
+ *  for a TALL picture (a square window onto its top), else 16:9; none when
+ *  the style sets a height. */
+export declare function zoomBoxAspect(math: Pick<ZoomMath, `zoomIsTall`>, natural: ZoomSize | null, styledHeight: boolean): number | null;
+/** The natural size the props declare (both positive), else null. */
+export declare function zoomDeclaredSize(width: unknown, height: unknown): ZoomSize | null;
+/** The menu's items (Fit, then the presets inside the limits) for the
+ *  current view, before the controller measured (the rest view's). */
+export declare function zoomPillOf(math: ZoomMath, view: ZoomView, frame: ZoomFrame): ZoomPillState;
+export interface ZoomControllerOptions {
+    math: ZoomMath;
+    /** The viewport: focusable, takes every gesture. */
+    root: HTMLElement;
+    /** The picture, transformed (`transform-origin: 0 0`). */
+    image: HTMLElement;
+    /** The zoom pill (its hover / focus keep it shown); null = none. */
+    pill: () => HTMLElement | null;
+    /** The picture's pixel size, null while unknown. */
+    natural: () => ZoomSize | null;
+    initial: () => ZoomInitial;
+    maxScale: () => number | undefined;
+    /** The scale the host binds (`scale`), undefined = the rest view. */
+    boundScale: () => number | undefined;
+    /** The CSS `transition` of an animated change (the theme's standard
+     *  motion); null = snap (reduced motion). */
+    transition: () => string | null;
+    /** `controls: auto` (the pill hides on its own). */
+    autoHide: () => boolean;
+    onPill: (pill: ZoomPillState) => void;
+    onPillVisible: (visible: boolean) => void;
+    /** A settled zoom change. */
+    onZoom: (scale: number, atFit: boolean) => void;
+    /** A single tap / click at rest. */
+    onTap: () => void;
+}
+export interface ZoomController {
+    view: () => ZoomView;
+    frame: () => ZoomFrame | null;
+    /** The pill's − / +. */
+    step: (direction: 1 | -1) => void;
+    /** Back to the rest view (the fit button, the menu's Fit). */
+    rest: () => void;
+    /** To `scale` about the viewport centre (the menu's presets). */
+    zoomScale: (scale: number) => void;
+    /** The bound `scale` changed from outside: apply it, no event. */
+    syncScale: () => void;
+    /** A new picture / natural size / initial / max: the rest view, at once. */
+    reset: () => void;
+    /** Keep the pill shown (its menu is open). */
+    holdPill: (hold: boolean) => void;
+    destroy: () => void;
+}
+/** Binds the gestures to `root` and paints `image`; the pill's state and
+ *  visibility go out through the callbacks. Every number comes from the
+ *  core's functions. */
+export declare function createZoomController(o: ZoomControllerOptions): ZoomController;
+/** The native's LAYOUT (inline: the theme recipe styles every part, these
+ *  only place them; React style objects, Solid passes them through `css`).
+ *  `pill` = style.json `zoomableImage.pill`. `flexShrink` comes last: jsdom
+ *  re-appends it when Solid re-applies a style, so React's order holds. */
+export declare function zoomableImageLayout(pill: {
+    inset: number;
+    percentMinWidth: number;
+}): {
+    readonly root: {
+        readonly overflow: "clip";
+        readonly userSelect: "none";
+    };
+    readonly image: {
+        readonly position: "absolute";
+        readonly left: 0;
+        readonly top: 0;
+        readonly display: "block";
+        readonly maxWidth: "none";
+        readonly maxHeight: "none";
+        readonly transformOrigin: "0 0";
+        readonly pointerEvents: "none";
+        readonly userSelect: "none";
+    };
+    readonly pill: {
+        readonly position: "absolute";
+        readonly left: "50%";
+        readonly bottom: number;
+        readonly transform: "translateX(-50%)";
+        readonly zIndex: 1;
+        readonly display: "flex";
+        readonly flexDirection: "row";
+        readonly alignItems: "center";
+        readonly whiteSpace: "nowrap";
+        readonly cursor: "default";
+        readonly transition: "opacity var(--xui-motion-standard) var(--xui-ease-standard,ease)";
+    };
+    readonly pillHidden: {
+        readonly opacity: 0;
+        readonly pointerEvents: "none";
+    };
+    readonly button: {
+        readonly display: "inline-flex";
+        readonly alignItems: "center";
+        readonly justifyContent: "center";
+        readonly cursor: "pointer";
+        readonly flexShrink: 0;
+    };
+    readonly percent: {
+        readonly display: "inline-flex";
+        readonly alignItems: "center";
+        readonly justifyContent: "center";
+        readonly cursor: "pointer";
+        readonly minWidth: number;
+        readonly fontVariantNumeric: "tabular-nums";
+        readonly flexShrink: 0;
+    };
+    readonly divider: {
+        readonly alignSelf: "center";
+        readonly flexShrink: 0;
+    };
+};
+/** The settle spring of the native (the theme's standard motion). */
+export declare const ZOOMABLE_IMAGE_NATIVE_TRANSITION = "transform var(--xui-motion-standard) var(--xui-ease-standard,ease)";
+/** The primitive's (the app's motion tokens). */
+export declare const ZOOMABLE_IMAGE_TRANSITION = "transform var(--motion-duration-standard,var(--xui-duration-standard,180ms)) var(--motion-ease-standard,cubic-bezier(0.2,0,0,1))";
+/** The primitive's picture style before the controller paints it. */
+export declare function zoomImageStyle(natural: ZoomSize | null): Record<string, string | number>;
+export declare const ZOOMABLE_IMAGE_CLASSES: {
+    /** The viewport: as wide as its parent, the picture clipped to it. */
+    readonly root: "relative w-full min-w-0 overflow-hidden rounded-md select-none outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50";
+    readonly image: "pointer-events-none absolute top-0 left-0 block max-h-none max-w-none origin-top-left select-none";
+    /** THE pill: one glass capsule bottom-centre, `pill.inset` above the edge. */
+    readonly pill: "absolute bottom-4 left-1/2 z-10 flex -translate-x-1/2 flex-row items-center gap-0.5 rounded-full border border-glass-stroke-card bg-popover p-1 whitespace-nowrap shadow-lg backdrop-blur-lg transition-opacity duration-standard ease-standard";
+    readonly pillHidden: "pointer-events-none opacity-0";
+    /** − / + / fit: ghost icon buttons, 28 px circles (no border or fill of
+     *  their own where the host has no preflight). */
+    readonly button: "size-7 rounded-full border-0 bg-transparent";
+    readonly percent: "h-7 min-w-14 rounded-full border-0 bg-transparent px-2 tabular-nums";
+    readonly divider: "mx-0.5 h-4 w-px shrink-0 bg-border";
+};
+export {};

package/dist/types/src/web/table.d.ts

@@ -11,7 +11,15 @@ export interface TableColumn {
     width?: number;
     align?: `start` | `center` | `end`;
     sortable?: boolean;
+    /** EXP-1548: one line with an ellipsis; cells wrap otherwise. */
+    truncate?: boolean;
 }
+/** Every row's grid columns (round 2 §7): a fixed `width` keeps its px, the
+ *  rest share the width, EXP-1548: never under `tableColumnMin`. */
+export declare function tableTemplate(columns: readonly TableColumn[], multiple: boolean): string;
+/** EXP-1548: the narrowest the columns fit in: header and body are at least
+ *  this wide, so a narrower table scrolls (its root is the scroller). */
+export declare function tableMinWidth(columns: readonly TableColumn[], multiple: boolean): string;
 export interface TableSort {
     key: string;
     direction: `asc` | `desc`;

package/dist/types/src/zoom.d.ts

@@ -0,0 +1,128 @@
+export declare const ZOOM: {
+    $comment: string;
+    tallAspect: number;
+    maxScale: number;
+    presets: number[];
+    menuPresets: number[];
+    doubleTapFactor: number;
+    wheelRate: number;
+    wheelLinePx: number;
+    rubber: number;
+    momentumTauMs: number;
+    autoHideMs: number;
+    pill: {
+        height: number;
+        inset: number;
+        padding: number;
+        gap: number;
+        percentMinWidth: number;
+        dividerHeight: number;
+    };
+};
+export type ZoomInitial = `auto` | `fit` | `fitWidth` | `actual`;
+export interface ZoomSize {
+    width: number;
+    height: number;
+}
+export interface ZoomPoint {
+    x: number;
+    y: number;
+}
+/** scale = displayed px per image px (1 = 100%); x/y = the picture's
+ *  top-left in the viewport. */
+export interface ZoomView {
+    scale: number;
+    x: number;
+    y: number;
+}
+/** What every function needs to know about the picture and its box. */
+export interface ZoomFrame {
+    natural: ZoomSize;
+    viewport: ZoomSize;
+    initial?: ZoomInitial;
+    maxScale?: number;
+}
+/** A picture taller than 1 / tallAspect times its width. */
+export declare function zoomIsTall(natural: ZoomSize): boolean;
+/** The whole picture inside the viewport, never upscaled: the minimum. */
+export declare function zoomFitScale(frame: ZoomFrame): number;
+/** The scale range: [fit, max(fit, maxScale)]. */
+export declare function zoomLimits(frame: ZoomFrame): {
+    min: number;
+    max: number;
+};
+/** The scale the picture opens at (and a double tap / `0` / the fit button
+ *  returns to), inside the limits. */
+export declare function zoomRestScale(frame: ZoomFrame): number;
+/** The view inside its bounds (scale within the limits, no letterbox). */
+export declare function zoomClamp(view: ZoomView, frame: ZoomFrame): ZoomView;
+/** The opening view: the rest scale, centred; a taller-than-the-viewport
+ *  picture starts at its top. */
+export declare function zoomRestView(frame: ZoomFrame): ZoomView;
+/** Whether the view sits at its rest scale. */
+export declare function zoomAtRest(view: ZoomView, frame: ZoomFrame): boolean;
+/** Zoom to `scale` (clamped) keeping the image point under `anchor` fixed. */
+export declare function zoomTo(view: ZoomView, scale: number, anchor: ZoomPoint, frame: ZoomFrame): ZoomView;
+/** The viewport's centre, the anchor of keys and the pill. */
+export declare function zoomCentre(frame: ZoomFrame): ZoomPoint;
+export type WheelDeltaMode = `pixel` | `line`;
+/** ⌘/ctrl + wheel (or a trackpad pinch delivered as a wheel): the scale
+ *  factor of one wheel event. */
+export declare function zoomWheelFactor(deltaY: number, mode?: WheelDeltaMode): number;
+/** One ⌘/ctrl-wheel event about the cursor. */
+export declare function zoomWheel(view: ZoomView, deltaY: number, mode: WheelDeltaMode, anchor: ZoomPoint, frame: ZoomFrame): ZoomView;
+/** A plain wheel / two-finger scroll: pans by the deltas, clamped. */
+export declare function zoomScroll(view: ZoomView, deltaX: number, deltaY: number, frame: ZoomFrame): ZoomView;
+/** The ladder steps walk: the presets plus the rest scale, inside the
+ *  limits, ascending. */
+export declare function zoomLadder(frame: ZoomFrame): number[];
+/** The next ladder scale strictly above (`1`) or below (`-1`) the current
+ *  one, or the current one at the end. */
+export declare function zoomStepScale(scale: number, direction: 1 | -1, frame: ZoomFrame): number;
+/** + / − (keys and the pill) about the viewport centre. */
+export declare function zoomStep(view: ZoomView, direction: 1 | -1, frame: ZoomFrame): ZoomView;
+/** The scale a double tap at rest jumps to. */
+export declare function zoomDoubleTapScale(frame: ZoomFrame): number;
+/** Double click / tap: at rest → zoom in about the point; else → rest. */
+export declare function zoomDoubleTap(view: ZoomView, point: ZoomPoint, frame: ZoomFrame): ZoomView;
+export type ZoomKey = `+` | `=` | `-` | `−` | `0` | `1`;
+/** A key while the picture has focus; null = not a zoom key. */
+export declare function zoomKey(view: ZoomView, key: string, frame: ZoomFrame): ZoomView | null;
+/** The overshoot past an edge, damped: (1 − 1 / (o·c/d + 1))·d. */
+export declare function zoomRubberBand(overshoot: number, extent: number): number;
+/** A drag from `start` by (dx, dy) while held: past an edge the overshoot
+ *  rubber-bands. The release is `zoomClamp` of the last view. */
+export declare function zoomDrag(start: ZoomView, dx: number, dy: number, frame: ZoomFrame): ZoomView;
+/** A pinch from `start` by the raw factor about `anchor` while held: past
+ *  the min/max the scale rubber-bands (d = the limit). The release is
+ *  `zoomClamp` of the last view. */
+export declare function zoomPinch(start: ZoomView, factor: number, anchor: ZoomPoint, frame: ZoomFrame): ZoomView;
+/** Mouse-drag momentum `t` ms after a release at velocity (px/ms),
+ *  exponential decay, stopping at the edges. */
+export declare function zoomMomentum(view: ZoomView, vx: number, vy: number, t: number, frame: ZoomFrame): ZoomView;
+/** Whether momentum `t` ms after a release is still moving (above 0.01 px/ms). */
+export declare function zoomMomentumActive(vx: number, vy: number, t: number): boolean;
+/** The axes the picture can pan on: an axis without room hands a swipe to
+ *  the host (paging). */
+export declare function zoomPanRoom(view: ZoomView, frame: ZoomFrame): {
+    x: boolean;
+    y: boolean;
+};
+/** A new viewport: at rest = the new rest view; zoomed = the same scale
+ *  about the viewport centre, clamped. */
+export declare function zoomResize(view: ZoomView, from: ZoomSize, frame: ZoomFrame): ZoomView;
+/** The pill's label: round(scale × 100) + `%`. */
+export declare function zoomPercent(scale: number): string;
+export interface ZoomMenuItem {
+    /** null = Fit (the rest view). */
+    scale: number | null;
+    label: string;
+    checked: boolean;
+}
+/** The % button's Menu: Fit, then the menu presets inside the limits. */
+export declare function zoomMenu(view: ZoomView, frame: ZoomFrame, fitLabel: string): ZoomMenuItem[];
+/** The pill's disabled ends. */
+export declare function zoomBounds(view: ZoomView, frame: ZoomFrame): {
+    atMin: boolean;
+    atMax: boolean;
+};