@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/fx-CmQjnHmT.d.ts

@@ -0,0 +1,371 @@
+import { A11yProps, Asset, AssetUrl, ScenePos } from '@almadar/core';
+import React__default from 'react';
+import { LucideIcon } from 'lucide-react';
+
+type BadgeVariant = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral";
+type BadgeSize = "sm" | "md" | "lg";
+interface BadgeProps extends Omit<React__default.HTMLAttributes<HTMLSpanElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    /** Numeric count or amount to display in badge */
+    amount?: number;
+    /** Badge label text (alternative to children for schema-driven rendering).
+     *  Numeric values are auto-coerced to string for rendering — common case
+     *  is unread counts, error counts, status codes, etc. */
+    label?: string | number;
+    /** Lucide icon component or canonical kebab-case icon name string */
+    icon?: IconInput;
+    /** Asset image rendered as the badge icon; takes precedence over icon when provided. */
+    iconAsset?: Asset;
+    /** When set, renders a small X button on the right of the badge that
+     *  invokes this handler — turns the badge into a removable chip.
+     *  Used by the TagInput molecule and other "list of removable values"
+     *  surfaces.
+     *  @offByDefault */
+    onRemove?: () => void;
+    /** Accessible label for the remove button. Defaults to "Remove". */
+    removeLabel?: string;
+}
+declare const Badge: React__default.ForwardRefExoticComponent<BadgeProps & React__default.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * Cross-cutting atom-level prop shapes shared across the design system.
+ */
+
+/**
+ * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
+ * names that every component in the design system understands.  Prefer this
+ * over a bare `string` for any `color` or `variant` prop.
+ */
+type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
+/**
+ * Concrete error-state shape read by display components (`error.message`,
+ * occasionally `error.stack`). Structurally assignable from the global `Error`,
+ * so existing call sites passing an `Error` keep working — this just gives the
+ * pattern extractor a readable field schema instead of the opaque `Error` global.
+ */
+type UiError = {
+    message: string;
+    name?: string;
+    code?: string;
+    stack?: string;
+};
+/**
+ * A labelled link/CTA used by marketing molecules (HeroSection, CTABanner,
+ * PricingCard) for their primary/secondary call-to-action props.
+ */
+type LinkAction = {
+    label: string;
+    href: string;
+};
+/** An image with its required alt text. */
+type ImageSource = {
+    src: AssetUrl;
+    alt: string;
+};
+/** A 2D point in canvas/layout coordinates. */
+type Point = {
+    x: number;
+    y: number;
+};
+/** A 2D rectangle in canvas coordinates (`w`/`h` = width/height). */
+type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** A badge colour a field's `colorMap` may name (`destructive` is the shadcn alias of `danger`). */
+type BadgeColor = BadgeVariant | 'destructive';
+/** How a display field renders: `h3`/`h4` is the record's title, `badge` a
+ *  status pill, `progress` a progress bar, `body` a prose block. */
+type DisplayFieldVariant = 'h3' | 'h4' | 'overline' | 'avatar' | 'body' | 'caption' | 'badge' | 'small' | 'progress';
+/** How a display field's value is formatted. */
+type DisplayFieldFormat = 'date' | 'time' | 'datetime' | 'currency' | 'number' | 'boolean' | 'percent';
+/**
+ * One field of a record shown by a data display (DataGrid, DataList, List,
+ * CardGrid, DetailPanel, Timeline). Every slot a field fills — title, badge,
+ * progress, date — is declared here; nothing is inferred from its name or value.
+ */
+interface DisplayField {
+    /** Entity field name (dot-notation supported) */
+    name: string;
+    /** Display label (the `name` as written if omitted) */
+    label?: string;
+    /** Icon shown beside the field */
+    icon?: IconInput;
+    /** Rendering variant */
+    variant?: DisplayFieldVariant;
+    /** Value format */
+    format?: DisplayFieldFormat;
+    /** Badge colour per exact value (for `variant: 'badge'`); unmapped values are neutral */
+    colorMap?: Readonly<Record<string, BadgeColor>>;
+    /** Display text per exact value (e.g. `in_progress` → "In progress"); unmapped values show as stored */
+    labels?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Icon Atom Component
+ *
+ * Renders an icon from the active icon family (Layer 1 Iconography axis —
+ * see lib/iconFamily.ts). Canonical names are lucide kebab-case; the resolver
+ * dispatches to phosphor / tabler / fa-solid when `--icon-family` selects them,
+ * re-rendering automatically on theme switch.
+ *
+ * Supports two APIs:
+ * - `icon` prop: Pass a LucideIcon component directly (bypasses family resolver
+ *   — used for direct lucide component refs, stays in lucide regardless of theme)
+ * - `name` prop: Pass a canonical kebab-case name (family-aware, swaps on theme)
+ */
+
+type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type IconAnimation = 'spin' | 'pulse' | 'none';
+
+/**
+ * Canonical icon-input type: a Lucide component reference OR a canonical
+ * kebab-case icon name string. The single source of truth for every
+ * icon-bearing prop across `@almadar/ui` — pattern-sync's parser maps this
+ * union to the `icon` config type, so the factory inspector renders an
+ * IconPicker and a string name resolves via `resolveIcon`. Never declare an
+ * icon prop as `React.ReactNode` (it collapses to a non-editable `node`).
+ */
+type IconInput = LucideIcon | string;
+/**
+ * Resolve an icon name to a Lucide icon component.
+ * Supports all 1500+ Lucide icons by kebab-case or PascalCase name; each icon loads on demand.
+ * Falls back to the help glyph if not found.
+ */
+declare function resolveIcon(name: string): LucideIcon;
+interface IconProps extends A11yProps {
+    /**
+     * Lucide icon component (preferred for type-safe usage), OR a canonical
+     * kebab-case icon name string — a string is treated exactly like `name` so
+     * trait/factory authors can pass an icon by name through the `icon` prop.
+     */
+    icon?: IconInput;
+    /** Icon name as string (resolved from iconMap) */
+    name?: string;
+    /** Size of the icon */
+    size?: IconSize;
+    /** Semantic palette token or an arbitrary Tailwind color class. */
+    color?: ColorToken | string;
+    /** Animation type */
+    animation?: IconAnimation;
+    /** Additional CSS classes */
+    className?: string;
+    /** Icon stroke width - uses theme default if not specified */
+    strokeWidth?: number;
+    /** Inline style */
+    style?: React__default.CSSProperties;
+}
+declare const Icon: React__default.FC<IconProps>;
+
+/**
+ * fx — the shared transient-effect contract (type-only module + pure helpers).
+ *
+ * One `FxItem` descriptor feeds BOTH render substrates: `draw-fx-layer` (game
+ * molecules — world-space, painted on the canvas) and `fx-overlay` (core
+ * molecules — screen-space, DOM/CSS). The substrate is NAME-BLIND: an item's
+ * look comes entirely from its resolved typed fields (color/size/shape/…),
+ * never from a kind→look table inside a component. The effect-kind vocabulary
+ * (`hit`, `explosion`, `correct-burst`, …) is declared by the CONSUMER — a
+ * board, lab, or themed organism — as an `FxPreset[]` table in its own `.lolo`
+ * config; `resolveFxView` merges the matching row under the item's own fields.
+ *
+ * Lifetime is owned by the fx mechanic (`std-fx-particles`): `ttl` decays every
+ * `tickMs` and removal is authoritative. Renderers derive smooth per-frame
+ * progress from `bornAt` (epoch ms, stamped at spawn) against the paint clock,
+ * falling back to the stepped `1 − ttl/maxTtl` fraction when `bornAt` is absent
+ * or no clock is running. Sub-particle scatter is seeded from the item `id` —
+ * deterministic, no `Math.random` at paint time.
+ */
+
+/** Which render substrate an fx entry belongs to. */
+type FxSpace = 'world' | 'screen';
+/** The screen-space render kinds `fx-overlay` can play — component capability, not domain vocabulary. */
+type FxOverlayKind = 'confetti' | 'flash' | 'shake' | 'sparkle' | 'float-text' | 'streak-glow';
+/** The procedural world-space recipes `draw-fx-layer` can paint — component capability, not domain vocabulary. */
+type FxProceduralShape = 'spark' | 'ring' | 'puff' | 'streak';
+/**
+ * One live transient effect — a row of the fx mechanic's `fx` entity list.
+ * Only `id`/`type`/`x`/`ttl` are guaranteed; everything else is optional so the
+ * 13 pre-existing producer emit sites keep compiling unchanged.
+ */
+interface FxItem {
+    /** Stable identity — the render key and the deterministic scatter seed. */
+    id: string;
+    /** Effect-kind key into the consumer-declared `FxPreset[]` table. */
+    type: string;
+    /** Canonical scene position; when absent the renderer derives it from `x`/`z`/`y`. */
+    position?: ScenePos;
+    /** Scene x in world units. */
+    x: number;
+    /** Ground-plane row in world units (2D boards paint it as screen y). */
+    z?: number;
+    /** Vertical axis in world units (3D height; 2D fallback row). */
+    y?: number;
+    /** Floating text painted with the effect (damage numbers, "+1", …). */
+    message?: string;
+    /** Remaining lifetime in mechanic ticks — the authoritative removal clock. */
+    ttl: number;
+    /** Spawn-time ttl (stamped by the mechanic when absent); grounds the fade fraction. */
+    maxTtl?: number;
+    /** Spawn timestamp in epoch ms (stamped by the mechanic) — enables smooth paint-clock progress. */
+    bornAt?: number;
+    /** Render substrate routing; default `world`. */
+    space?: FxSpace;
+    /** Screen-space render kind (`fx-overlay` vocabulary); ignored by the world layer. */
+    effect?: FxOverlayKind;
+    /** Primary color; renderer defaults apply when absent. */
+    color?: string;
+    /** Size in world units (canvas) / relative scale (overlay). */
+    size?: number;
+    /** Drift velocity along scene x, world-units/sec (render hint — the mechanic never integrates). */
+    vx?: number;
+    /** Drift velocity along the vertical axis, world-units/sec. */
+    vy?: number;
+    /** Drift velocity along the ground-plane row, world-units/sec. */
+    vz?: number;
+    /** Sub-particle count override (procedural burst / confetti). */
+    particleCount?: number;
+    /** Sprite-sheet animation name (e.g. "burst") — used when the resolved look is a sprite atlas. */
+    animation?: string;
+}
+/**
+ * One row of a consumer-declared effect vocabulary: the look + recipe for one
+ * fx `type`. Item fields always win over the preset row (`resolveFxView`).
+ */
+interface FxPreset {
+    /** The effect-kind key this row styles. */
+    type: string;
+    /** Primary color. */
+    color?: string;
+    /** Secondary color (ring stroke / puff core accents). */
+    color2?: string;
+    /** Size in world units (canvas) / relative scale (overlay). */
+    size?: number;
+    /** Procedural recipe when no vector art or sprite matches. Default `spark`. */
+    shape?: FxProceduralShape;
+    /** Sub-particle count for the procedural recipe. */
+    count?: number;
+    /** Glow strength — soft shadow blur in world units around procedural particles. */
+    glow?: number;
+    /** Downward acceleration in world-units/sec² applied to the drift. */
+    gravity?: number;
+    /** Default drift velocities, world-units/sec. */
+    vx?: number;
+    vy?: number;
+    vz?: number;
+    /** Render substrate routing for this kind. */
+    space?: FxSpace;
+    /** Screen-space render kind for this kind. */
+    effect?: FxOverlayKind;
+    /** Sub-particle count for screen-space kinds (confetti/sparkle). */
+    particleCount?: number;
+    /** Sprite-sheet animation name to play when this preset resolves to a sprite atlas. */
+    animation?: string;
+}
+/**
+ * A screen-space fx entry as `fx-overlay` consumes it — the same mechanic rows,
+ * filtered to `space == "screen"`. Deliberately carries NO `ScenePos`: overlay
+ * coordinates are viewport fractions, and the absence of a core `ScenePos` is
+ * what keeps `fx-overlay` out of the canvas-drawable capability.
+ */
+interface FxOverlayItem {
+    /** Stable identity — the mount key that starts the CSS animation, and the scatter seed. */
+    id: string;
+    /** Effect-kind key (consumer vocabulary); display comes from `effect` + style fields. */
+    type: string;
+    /** Overlay render kind; default `sparkle`. */
+    effect?: FxOverlayKind;
+    /** Floating text (`float-text`). */
+    message?: string;
+    /** Primary color. */
+    color?: string;
+    /** Relative scale multiplier. */
+    size?: number;
+    /** Horizontal viewport fraction 0..1; default 0.5. */
+    x?: number;
+    /** Vertical viewport fraction 0..1 (`z` wins, then `y`); default 0.4. */
+    z?: number;
+    y?: number;
+    /** Remaining lifetime in mechanic ticks — removal unmounts the node. */
+    ttl: number;
+    /** Spawn-time ttl; animation duration = maxTtl × tickMs. */
+    maxTtl?: number;
+    /** Spawn timestamp in epoch ms. */
+    bornAt?: number;
+    /** Render substrate routing; `world` entries are skipped defensively. */
+    space?: FxSpace;
+    /** Particle count for confetti/sparkle. */
+    particleCount?: number;
+    /** Drift velocities (unused by the DOM overlay; present so mechanic rows pass through untouched). */
+    vx?: number;
+    vy?: number;
+    vz?: number;
+}
+/** An `FxItem` with its preset row merged in — what the expanders consume. */
+interface FxView extends FxItem {
+    /** Procedural recipe (preset-only field). */
+    shape?: FxProceduralShape;
+    /** Sub-particle count (preset-only field). */
+    count?: number;
+    /** Glow strength (preset-only field). */
+    glow?: number;
+    /** Downward acceleration (preset-only field). */
+    gravity?: number;
+    /** Secondary color (preset-only field). */
+    color2?: string;
+}
+/** Merge the matching preset row UNDER the item's own fields (item wins). Unknown `type` → the item as-is. */
+declare function resolveFxView(item: FxItem, presets?: FxPreset[]): FxView;
+/** The derived lifetime view of one fx entry at one instant. */
+interface FxLifecycle {
+    /** Total lifetime in ms (`maxTtl × tickMs`). */
+    lifeMs: number;
+    /** Elapsed ms since spawn (smooth via `bornAt`, else stepped from ttl). */
+    ageMs: number;
+    /** 0..1 elapsed fraction, clamped. */
+    progress: number;
+    /** 1..0 remaining fraction — the fade envelope. */
+    fade: number;
+}
+/**
+ * Derive per-frame progress. `epochNowMs > 0` + `bornAt` → smooth wall-clock
+ * age; otherwise the stepped `1 − ttl/maxTtl` fraction (correct at every
+ * mechanic tick, coarse between them).
+ */
+declare function fxLifecycle(item: {
+    ttl: number;
+    maxTtl?: number;
+    bornAt?: number;
+}, epochNowMs: number, tickMs: number): FxLifecycle;
+/** Deterministic 0..1 hash of `seed` + `salt` — the scatter randomness (FNV-1a + avalanche; no `Math.random`). */
+declare function fxHash01(seed: string, salt: number): number;
+/** One confetti particle's CSS-animation parameters. */
+interface ConfettiParticle {
+    id: number;
+    color: string;
+    /** Origin as % of container width. */
+    left: number;
+    /** Animation delay ms. */
+    delay: number;
+    /** Launch angle in degrees. */
+    angle: number;
+    /** Travel distance in px. */
+    distance: number;
+    /** Total rotation in degrees. */
+    rotation: number;
+    /** Particle size in px. */
+    size: number;
+}
+declare const CONFETTI_COLORS: string[];
+/** Build a deterministic burst — same `seed` → same particles. */
+declare function createConfettiParticles(count: number, seed: string): ConfettiParticle[];
+/** The confetti burst keyframes (per-particle travel via CSS custom props). */
+declare const CONFETTI_BURST_KEYFRAMES = "\n@keyframes confetti-burst {\n  0% {\n    opacity: 1;\n    transform: translate(0, 0) rotate(0deg) scale(1);\n  }\n  70% {\n    opacity: 1;\n  }\n  100% {\n    opacity: 0;\n    transform: translate(var(--confetti-tx), var(--confetti-ty)) rotate(var(--confetti-rotate)) scale(0.5);\n  }\n}\n";
+
+export { Badge as B, CONFETTI_BURST_KEYFRAMES as C, CONFETTI_COLORS as f, Icon as q, createConfettiParticles as v, fxHash01 as w, fxLifecycle as x, resolveFxView as y, resolveIcon as z };
+export type { DisplayField as D, FxItem as F, IconInput as I, LinkAction as L, Point as P, Rect as R, UiError as U, FxPreset as a, BadgeColor as b, BadgeProps as c, BadgeSize as d, BadgeVariant as e, ColorToken as g, ConfettiParticle as h, DisplayFieldFormat as i, DisplayFieldVariant as j, FxLifecycle as k, FxOverlayItem as l, FxOverlayKind as m, FxProceduralShape as n, FxSpace as o, FxView as p, IconAnimation as r, IconProps as s, IconSize as t, ImageSource as u };