aeon-ui-engine 1.0.2 → 1.1.0

package/packages/core/dist/index.d.ts

@@ -0,0 +1,425 @@
+import { AnyStateMachine, ActorRefFrom, SnapshotFrom } from 'xstate';
+export { setup as createAeonMachine } from 'xstate';
+
+/**
+ * Aeon north star: behavior is defined as explicit state first; the interface must
+ * express the **totality** of that definition — every stable condition the model allows,
+ * and nothing the model does not allow.
+ */
+declare const AEON_PRINCIPLE: "State is defined first. UI represents the totality of that definition.";
+/** Shorthand used in docs and APIs. */
+declare const UI_IS_FUNCTION_OF_STATE: "UI = f(state)";
+
+/** Part keys for compound components — scope + named parts for styling and docs. */
+declare function anatomy<const T extends readonly string[]>(scope: string, parts: T): Record<T[number], T[number]> & {
+    scope: typeof scope;
+};
+declare const buttonAnatomy: Record<"root" | "group" | "label" | "icon", "root" | "group" | "label" | "icon"> & {
+    scope: string;
+};
+declare const switchAnatomy: Record<"root" | "label" | "control" | "thumb" | "hiddenInput", "root" | "label" | "control" | "thumb" | "hiddenInput"> & {
+    scope: string;
+};
+declare const checkboxAnatomy: Record<"root" | "label" | "control" | "hiddenInput" | "indicator", "root" | "label" | "control" | "hiddenInput" | "indicator"> & {
+    scope: string;
+};
+declare const dialogAnatomy: Record<"root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger", "root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger"> & {
+    scope: string;
+};
+declare const tabsAnatomy: Record<"root" | "indicator" | "trigger" | "content" | "list", "root" | "indicator" | "trigger" | "content" | "list"> & {
+    scope: string;
+};
+declare const accordionAnatomy: Record<"root" | "item" | "itemTrigger" | "itemContent" | "itemIndicator", "root" | "item" | "itemTrigger" | "itemContent" | "itemIndicator"> & {
+    scope: string;
+};
+/** Async data region — track shows every lifecycle state; readout + actions mirror snapshot. */
+declare const asyncAnatomy: Record<"root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions", "root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions"> & {
+    scope: string;
+};
+/** Form field — orthogonal interaction × validation × submission (see STATES.md). */
+declare const fieldAnatomy: Record<"root" | "label" | "control" | "textarea" | "message" | "hint", "root" | "label" | "control" | "textarea" | "message" | "hint"> & {
+    scope: string;
+};
+/** Scroll viewport — overflow axis + edge position on data-aeon-state. */
+declare const scrollAnatomy: Record<"root" | "content" | "viewport", "root" | "content" | "viewport"> & {
+    scope: string;
+};
+/**
+ * Spatial play surface — universal mat + regions + entities (not a specific game).
+ * App logic names regions; entity labels come from compose `items`. See LAYOUT_COORDINATES.md.
+ */
+declare const playSurfaceAnatomy: Record<"root" | "mat" | "region" | "entity", "root" | "mat" | "region" | "entity"> & {
+    scope: string;
+};
+declare const selectAnatomy: Record<"root" | "icon" | "trigger" | "positioner" | "content" | "item" | "value", "root" | "icon" | "trigger" | "positioner" | "content" | "item" | "value"> & {
+    scope: string;
+};
+/** Typeahead listbox — extends select with filter input and empty state. */
+declare const comboboxAnatomy: Record<"root" | "icon" | "content" | "item" | "input" | "empty", "root" | "icon" | "content" | "item" | "input" | "empty"> & {
+    scope: string;
+};
+declare const popoverAnatomy: Record<"root" | "trigger" | "positioner" | "content" | "closeTrigger" | "arrow", "root" | "trigger" | "positioner" | "content" | "closeTrigger" | "arrow"> & {
+    scope: string;
+};
+declare const menuAnatomy: Record<"root" | "trigger" | "positioner" | "content" | "item" | "separator", "root" | "trigger" | "positioner" | "content" | "item" | "separator"> & {
+    scope: string;
+};
+declare const tooltipAnatomy: Record<"root" | "trigger" | "positioner" | "content" | "arrow", "root" | "trigger" | "positioner" | "content" | "arrow"> & {
+    scope: string;
+};
+declare const toastAnatomy: Record<"root" | "title" | "description" | "closeTrigger" | "viewport", "root" | "title" | "description" | "closeTrigger" | "viewport"> & {
+    scope: string;
+};
+/** Profile image — loaded / loading / error on root `data-aeon-state`. Badge = presence / status corner. */
+declare const avatarAnatomy: Record<"root" | "image" | "fallback" | "badge", "root" | "image" | "fallback" | "badge"> & {
+    scope: string;
+};
+/**
+ * Identity strip — avatar + primary/secondary text (items-market AvatarWithName).
+ * Presentational; compose into ProfileHeader / ListRow / AccountCluster.
+ */
+declare const identityAnatomy: Record<"root" | "title" | "avatar" | "subtitle" | "meta" | "trailing", "root" | "title" | "avatar" | "subtitle" | "meta" | "trailing"> & {
+    scope: string;
+};
+/**
+ * Profile header — dense account hero (not dating). Media optional; metrics + actions zones.
+ * Spatial: identity leading, metrics inline, actions trailing / bottom leading pair.
+ */
+declare const profileHeaderAnatomy: Record<"root" | "actions" | "identity" | "media" | "metrics" | "body", "root" | "actions" | "identity" | "media" | "metrics" | "body"> & {
+    scope: string;
+};
+/**
+ * Entry — compact multi-value content card (feed post, catalog listing, activity item).
+ * Universal layout only — not a social/marketplace niche.
+ * List stacks cards; Root is one card (idle | selected | muted).
+ * Zones: header (leading · heading · meta) · media · body · values · actions · footer.
+ */
+declare const entryAnatomy: Record<"values" | "root" | "title" | "list" | "actions" | "value" | "subtitle" | "meta" | "media" | "body" | "header" | "leading" | "heading" | "footer", "values" | "root" | "title" | "list" | "actions" | "value" | "subtitle" | "meta" | "media" | "body" | "header" | "leading" | "heading" | "footer"> & {
+    scope: string;
+};
+/**
+ * Metric strip — ultra-dense value/label chips (items-market im-stat cluster).
+ * Generic stats only — not wallet/currency product niches.
+ */
+declare const metricStripAnatomy: Record<"root" | "label" | "value" | "chip", "root" | "label" | "value" | "chip"> & {
+    scope: string;
+};
+/**
+ * List row — settings / account menu row (h-12 hit target, leading icon, trailing control).
+ */
+declare const listRowAnatomy: Record<"root" | "label" | "description" | "trailing" | "leading", "root" | "label" | "description" | "trailing" | "leading"> & {
+    scope: string;
+};
+/**
+ * Conversation — inbox / DM list row (universal messaging chrome, not dating).
+ * Leading avatar · title · preview · meta (time) · badge (unread).
+ * Item state: idle | unread | selected.
+ */
+declare const conversationAnatomy: Record<"root" | "title" | "item" | "badge" | "meta" | "body" | "leading" | "preview", "root" | "title" | "item" | "badge" | "meta" | "body" | "leading" | "preview"> & {
+    scope: string;
+};
+/**
+ * Thread — message stream. Items project mine | theirs | pending | failed.
+ */
+declare const threadAnatomy: Record<"root" | "list" | "item" | "meta" | "bubble" | "day", "root" | "list" | "item" | "meta" | "bubble" | "day"> & {
+    scope: string;
+};
+/**
+ * Composer — bottom compose chrome for threads (input + send).
+ * Root state: idle | sending | disabled | error.
+ */
+declare const composerAnatomy: Record<"root" | "actions" | "input" | "send", "root" | "actions" | "input" | "send"> & {
+    scope: string;
+};
+declare const separatorAnatomy: Record<"root", "root"> & {
+    scope: string;
+};
+/** Progress bar — idle / loading / complete on root `data-aeon-state`. */
+declare const progressAnatomy: Record<"root" | "label" | "track" | "range", "root" | "label" | "track" | "range"> & {
+    scope: string;
+};
+declare const radioGroupAnatomy: Record<"root" | "item" | "itemIndicator" | "itemControl" | "itemLabel", "root" | "item" | "itemIndicator" | "itemControl" | "itemLabel"> & {
+    scope: string;
+};
+declare const sliderAnatomy: Record<"root" | "thumb" | "track" | "range" | "valueText", "root" | "thumb" | "track" | "range" | "valueText"> & {
+    scope: string;
+};
+declare const pinInputAnatomy: Record<"root" | "input", "root" | "input"> & {
+    scope: string;
+};
+/**
+ * Bar — horizontal layout primitive for toolbars, headers, footers.
+ * Enforces safe flex behavior: no overlap, responsive collapse via overflow.
+ * Parts: root (flex row), leading, center, trailing, optional seam (sticky stack join).
+ * Drive sticky lifecycle with stickyBarMachine → data-aeon-state on root.
+ */
+declare const barAnatomy: Record<"root" | "trailing" | "leading" | "center" | "seam", "root" | "trailing" | "leading" | "center" | "seam"> & {
+    scope: string;
+};
+/**
+ * Panel — collapsible layout region for split views.
+ * Group lays out siblings; Root is expanded|collapsed; Label rails vertically when collapsed.
+ */
+declare const panelAnatomy: Record<"root" | "group" | "label" | "trigger" | "content", "root" | "group" | "label" | "trigger" | "content"> & {
+    scope: string;
+};
+/**
+ * App shell — layered application chrome (items-market MainLayout pattern).
+ * header / subheader / content / aside / footer / dock / scrim under root.
+ */
+declare const appShellAnatomy: Record<"root" | "content" | "header" | "footer" | "subheader" | "aside" | "dock" | "scrim", "root" | "content" | "header" | "footer" | "subheader" | "aside" | "dock" | "scrim"> & {
+    scope: string;
+};
+/**
+ * Content region — status-slotted body. Every contentRegionMachine state has a part.
+ * Pair with Async for fetch; use slots for idle/pending/empty/error/ready/loadingMore/success.
+ */
+declare const contentAnatomy: Record<"root" | "empty" | "body" | "toolbar" | "pending" | "error" | "success" | "sentinel", "root" | "empty" | "body" | "toolbar" | "pending" | "error" | "success" | "sentinel"> & {
+    scope: string;
+};
+/**
+ * Nav — navigational collection (top links, bottom tabs, side rail).
+ * Selection reuses tabsMachine; items project inactive|active|disabled.
+ */
+declare const navAnatomy: Record<"root" | "label" | "icon" | "indicator" | "item" | "badge", "root" | "label" | "icon" | "indicator" | "item" | "badge"> & {
+    scope: string;
+};
+/**
+ * ThemeSwitcher — mode toggle (light/dark) + theme preset selector.
+ * Parts: root, modes (button group), modeBtn, themeSelect, themeTrigger.
+ */
+declare const themeSwitcherAnatomy: Record<"root" | "modes" | "modeBtn" | "themeSelect" | "themeTrigger", "root" | "modes" | "modeBtn" | "themeSelect" | "themeTrigger"> & {
+    scope: string;
+};
+
+type AttrOptions = {
+    state?: string | string[];
+    disabled?: boolean;
+    focus?: boolean;
+    highlighted?: boolean;
+};
+/** Scope + part on the component root (e.g. accordion root). */
+declare function scopeAttrs(scope: string, part?: string, options?: AttrOptions): Record<string, unknown>;
+/** Part only — use on children inside a scoped root. */
+declare function partOnlyAttrs(part: string, options?: AttrOptions): Record<string, unknown>;
+/** Build data-aeon-* attributes for styling unstyled parts. */
+declare function partAttrs(scope: string, part: string, options?: AttrOptions): Record<string, unknown>;
+
+type AeonSnapshot<M extends AnyStateMachine> = SnapshotFrom<M>;
+type AeonActor<M extends AnyStateMachine> = ActorRefFrom<M>;
+/** Flatten nested state value for data-aeon-state attribute. */
+declare function stateToAttr(value: unknown): string;
+/**
+ * Primary visual face for parallel field charts — same hierarchy as Button/Dialog:
+ * one leaf on `data-aeon-state`, not a region dump.
+ * Priority: pending > invalid > dirty > idle.
+ */
+type FieldFace = 'idle' | 'dirty' | 'invalid' | 'pending';
+declare function fieldFace(value: unknown): FieldFace;
+/** Orthogonal field regions for advanced CSS (`data-aeon-interaction`, etc.). */
+declare function fieldRegions(value: unknown): {
+    interaction: string;
+    validation: string;
+    submission: string;
+};
+/** Read one region from a (possibly parallel) snapshot value. */
+declare function getRegionValue(value: unknown, region: string): unknown;
+/**
+ * Active path under a region — e.g. `{ deck: { ready: 'matched' } }` →
+ * `regionPath(v, 'deck')` → `['ready', 'matched']`.
+ */
+declare function regionPath(value: unknown, region: string): string[];
+/** Deepest active key under a region (`['ready','matched']` → `'matched'`). */
+declare function regionLeaf(value: unknown, region: string): string | undefined;
+/** True when the region path equals or ends with the given leaf / path prefix. */
+declare function regionMatches(value: unknown, region: string, match: string | readonly string[]): boolean;
+
+/** Stable conditions the machine may occupy — mutually exclusive at a given depth. */
+type AeonStateValue = string | {
+    [key: string]: AeonStateValue;
+};
+/** Events that may cause transitions. */
+type AeonEvent = {
+    type: string;
+} & Record<string, unknown>;
+/**
+ * Machine context at a snapshot. Presentation is derived from this plus the active
+ * state value — never the other way around.
+ */
+type AeonContext<T extends Record<string, unknown> = Record<string, unknown>> = T;
+/**
+ * Attribute contract for unstyled parts. `data-aeon-state` should enumerate the
+ * full stable condition (e.g. `open`, `checked`, `idle loading`) so styles and
+ * assistive tech reflect the complete machine definition, not a partial guess.
+ */
+interface AeonDataAttrs {
+    'data-aeon-scope': string;
+    'data-aeon-part': string;
+    'data-aeon-state'?: string;
+    'data-disabled'?: string;
+    'data-focus'?: string;
+    'data-highlighted'?: string;
+}
+
+/** Scroll axis overflow detected on a viewport element. */
+type ScrollOverflow = 'none' | 'x' | 'y' | 'both';
+interface ScrollSnapshot {
+    overflow: ScrollOverflow;
+    /** Space-separated value for data-aeon-state on scroll viewports. */
+    stateAttr: string;
+    atStartY: boolean;
+    atEndY: boolean;
+    betweenY: boolean;
+    atStartX: boolean;
+    atEndX: boolean;
+    betweenX: boolean;
+}
+/** Derive overflow + edge states from a scrollable element. */
+declare function getScrollSnapshot(el: HTMLElement): ScrollSnapshot;
+
+/**
+ * Responsive play-surface layout — logical coordinate plane + composition modes.
+ *
+ * Behavior stays in statecharts; **where** the user points is expressed in normalized
+ * coordinates (0–100) inside a measured region, independent of CSS grid vs overlay.
+ *
+ * @see docs/LAYOUT_COORDINATES.md
+ */
+/** Point on the normalized plane (percent of region width/height). */
+type NormPoint = {
+    readonly x: number;
+    readonly y: number;
+};
+/** Axis-aligned bounds on the normalized plane (inclusive). */
+type NormRect = {
+    readonly xMin: number;
+    readonly xMax: number;
+    readonly yMin: number;
+    readonly yMax: number;
+};
+/** DOM mapping: y increases upward (throws, dice) vs downward (top-left UI). */
+type NormOrigin = 'bottom-left' | 'top-left';
+declare const NORM_PLANE: {
+    readonly bottomLeft: "bottom-left";
+    readonly topLeft: "top-left";
+};
+/** How regions are composed at a breakpoint — product maps to CSS grid / absolute. */
+type LayoutComposition = 'split' | 'stack' | 'overlay';
+interface RegionLayoutSlot {
+    /** Logical region id (matches anatomy part or app constant). */
+    readonly region: string;
+    /** Grid area name / slot id for CSS `grid-template-areas`. */
+    readonly slot: string;
+    readonly zIndex?: number;
+}
+interface LayoutCompositionSpec {
+    readonly id: string;
+    readonly composition: LayoutComposition;
+    readonly regions: readonly RegionLayoutSlot[];
+    /** Interaction bounds per region in **that region's** normalized plane. */
+    readonly bounds?: Readonly<Record<string, NormRect>>;
+}
+type LayoutMode = 'compact' | 'wide';
+interface ResponsiveLayoutSpec {
+    readonly modes: {
+        readonly compact: LayoutCompositionSpec;
+        readonly wide: LayoutCompositionSpec;
+    };
+    /**
+     * Media query that selects `compact` when matched (default: phone portrait).
+     * When it does not match, mode is `wide`.
+     */
+    readonly compactMq?: string;
+}
+declare const DEFAULT_COMPACT_MQ = "(max-width: 39.99rem)";
+declare function clampNorm(point: NormPoint, bounds: NormRect): NormPoint;
+declare function normFromClient(rect: DOMRectReadOnly, clientX: number, clientY: number, options?: {
+    origin?: NormOrigin;
+    bounds?: NormRect;
+}): NormPoint;
+declare function clientFromNorm(rect: DOMRectReadOnly, point: NormPoint, options?: {
+    origin?: NormOrigin;
+}): {
+    clientX: number;
+    clientY: number;
+};
+/** Measure element; returns null if not connected. */
+declare function measureElement(el: Element | null | undefined): DOMRect | null;
+/** Prefer a dedicated region rect; fall back to mat when lane not mounted. */
+declare function resolveRegionRect(primary: DOMRect | null | undefined, fallback: DOMRect | null | undefined): DOMRect | null;
+declare function matchLayoutMode(spec: ResponsiveLayoutSpec, mq?: Pick<MediaQueryList, 'matches'>): LayoutMode;
+declare function getCompactMq(spec: ResponsiveLayoutSpec): MediaQueryList;
+declare function layoutCompositionForMode(spec: ResponsiveLayoutSpec, mode: LayoutMode): LayoutCompositionSpec;
+declare function regionBoundsForMode(spec: ResponsiveLayoutSpec, mode: LayoutMode, regionId: string): NormRect | undefined;
+/**
+ * Value for `data-aeon-layout-mode` on the mat root.
+ * Pair with `data-aeon-layout-composition` from the active spec.
+ */
+declare function layoutModeAttrs(mode: LayoutMode, composition: LayoutComposition): Record<string, string>;
+/** Spread a norm point inside bounds (keeps cluster off edges). */
+declare function insetNormCluster(point: NormPoint, bounds: NormRect, inset?: {
+    x?: number;
+    y?: number;
+}): NormPoint;
+
+type AeonColorMode = 'light' | 'dark';
+/** Class applied to `<html>` to enable theme-transition.css */
+declare const AEON_THEME_TRANSITION_CLASS = "aeon-theme-transition";
+declare function isAeonColorMode(value: string): value is AeonColorMode;
+/** Map next-themes / user prefs to Aeon `data-aeon-mode`. */
+declare function resolveAeonColorMode(theme: string | undefined, systemPrefersDark?: boolean): AeonColorMode;
+/**
+ * Keep `data-aeon-theme` / `data-aeon-mode` in sync with Tailwind `.dark` apps.
+ * Enables smooth transitions when paired with `@aeon-ui/core/theme-transition.css`.
+ */
+declare function syncAeonColorMode(root: HTMLElement, mode: AeonColorMode, options?: {
+    themeId?: string;
+    enableTransitionClass?: boolean;
+}): void;
+/** Cross-fade theme changes when View Transitions API is available. */
+declare function runAeonThemeTransition(apply: () => void): void;
+type AeonPalette = {
+    bg: string;
+    surface: string;
+    surfaceRaised: string;
+    border: string;
+    text: string;
+    muted: string;
+    accent: string;
+    accentDim: string;
+    danger: string;
+    dangerDim: string;
+    focusRing: string;
+    gridLine: string;
+};
+interface AeonThemeDefinition {
+    id: string;
+    label: string;
+    description: string;
+    light: AeonPalette;
+    dark: AeonPalette;
+}
+/**
+ * Register theme definitions. Call once at app init.
+ * Returns the registered themes array and lookup map.
+ */
+declare function registerAeonThemes(themes: AeonThemeDefinition[]): {
+    themes: AeonThemeDefinition[];
+    map: Record<string, AeonThemeDefinition>;
+    ids: string[];
+};
+declare function isAeonThemeId(value: string): boolean;
+declare function isAeonMode(value: string): value is AeonColorMode;
+/**
+ * Apply a theme + mode to `<html>`. Persists to localStorage.
+ */
+declare function applyAeonTheme(themeId: string, mode: AeonColorMode, themeMap?: Record<string, AeonThemeDefinition>): void;
+/**
+ * Read saved prefs or system preference, apply to `<html>`, return current values.
+ */
+declare function initAeonTheme(themeMap?: Record<string, AeonThemeDefinition>): {
+    themeId: string;
+    mode: AeonColorMode;
+};
+
+export { AEON_PRINCIPLE, AEON_THEME_TRANSITION_CLASS, type AeonActor, type AeonColorMode, type AeonContext, type AeonDataAttrs, type AeonEvent, type AeonPalette, type AeonSnapshot, type AeonStateValue, type AeonThemeDefinition, DEFAULT_COMPACT_MQ, type FieldFace, type LayoutComposition, type LayoutCompositionSpec, type LayoutMode, NORM_PLANE, type NormOrigin, type NormPoint, type NormRect, type RegionLayoutSlot, type ResponsiveLayoutSpec, type ScrollOverflow, type ScrollSnapshot, UI_IS_FUNCTION_OF_STATE, accordionAnatomy, anatomy, appShellAnatomy, applyAeonTheme, asyncAnatomy, avatarAnatomy, barAnatomy, buttonAnatomy, checkboxAnatomy, clampNorm, clientFromNorm, comboboxAnatomy, composerAnatomy, contentAnatomy, conversationAnatomy, dialogAnatomy, entryAnatomy, fieldAnatomy, fieldFace, fieldRegions, getCompactMq, getRegionValue, getScrollSnapshot, identityAnatomy, initAeonTheme, insetNormCluster, isAeonColorMode, isAeonMode, isAeonThemeId, layoutCompositionForMode, layoutModeAttrs, listRowAnatomy, matchLayoutMode, measureElement, menuAnatomy, metricStripAnatomy, navAnatomy, normFromClient, panelAnatomy, partAttrs, partOnlyAttrs, pinInputAnatomy, playSurfaceAnatomy, popoverAnatomy, profileHeaderAnatomy, progressAnatomy, radioGroupAnatomy, regionBoundsForMode, regionLeaf, regionMatches, regionPath, registerAeonThemes, resolveAeonColorMode, resolveRegionRect, runAeonThemeTransition, scopeAttrs, scrollAnatomy, selectAnatomy, separatorAnatomy, sliderAnatomy, stateToAttr, switchAnatomy, syncAeonColorMode, tabsAnatomy, themeSwitcherAnatomy, threadAnatomy, toastAnatomy, tooltipAnatomy };