@almadar/shell-web 0.0.0-stage → 0.1.0

package/dist/ssr/index.d.cts

@@ -0,0 +1,487 @@
+import { EventPayload, BusEventSource, BusEventListener, Unsubscribe, EntityRow, A11yProps, SurfaceMode, SkeletonSpec } from '@almadar/core';
+import React from 'react';
+import { LucideIcon } from 'lucide-react';
+
+/**
+ * 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;
+};
+
+/**
+ * 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)
+ */
+
+/**
+ * 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;
+
+/**
+ * PatternTile Atom
+ *
+ * Mathematically correct Islamic geometric pattern tiles using the
+ * Polygons-in-Contact (PIC) method (Hankin 1925, formalized by Kaplan 2005).
+ *
+ * Construction: A regular polygon tiling is overlaid with star motifs.
+ * Each motif touches the enclosing polygon at EDGE MIDPOINTS only.
+ * Two rays emanate from each midpoint into the polygon at a specific
+ * CONTACT ANGLE (theta). Where rays from adjacent midpoints intersect,
+ * they form the star points. Gap tiles (squares, triangles) between
+ * polygons receive inferred geometry by extending boundary rays inward.
+ *
+ * Variants:
+ *   star8  — 8-fold star-and-cross on 4.8.8 tiling (theta = 67.5 deg)
+ *   star6  — 6-fold star on hexagonal tiling (theta = 60 deg)
+ *   khatam — 8-fold rosette with interlocking kites (theta = 72 deg)
+ *   star10 — 10-fold girih on decagonal tiling (theta = 72 deg)
+ *   star12 — 12-fold on dodecagonal tiling (theta = 75 deg)
+ *
+ * All tiles use stroke only (no fill), rendering as transparent overlays.
+ */
+
+type PatternVariant = 'star8' | 'star6' | 'khatam' | 'star10' | 'star12' | 'rosette-double' | 'rosette-filled' | 'seigaiha' | 'greek-key' | 'celtic-knot' | 'kolam' | 'arch' | 'arabesque-vine' | 'arabesque-net';
+
+interface YouTubePlayer {
+    destroy(): void;
+}
+interface YouTubePlayerOptions {
+    videoId: string;
+    playerVars: {
+        autoplay: 0 | 1;
+        controls: 0 | 1;
+        start: number;
+        rel: 0;
+    };
+    events: {
+        onReady: () => void;
+        onError: (event: {
+            data: number;
+        }) => void;
+        onStateChange: (event: {
+            data: number;
+        }) => void;
+    };
+}
+interface YouTubeApi {
+    Player: new (host: HTMLElement, options: YouTubePlayerOptions) => YouTubePlayer;
+}
+declare global {
+    interface Window {
+        YT?: YouTubeApi;
+        onYouTubeIframeAPIReady?: () => void;
+    }
+}
+
+/**
+ * Event Bus Types
+ *
+ * Re-exports from @almadar/core so every package agrees on the same
+ * bus event envelope. @almadar/ui no longer owns its own KFlowEvent —
+ * that type was folded into core's BusEvent.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Event bus context type.
+ *
+ * `emit` accepts `EventPayload` from `@almadar/core` — the canonical
+ * object shape (index signature over `EventPayloadValue`) that the bus
+ * envelope stores and listeners consume. Pattern-specific payload types
+ * from `@almadar/core/patterns` (`ItemActionPayload`, `SelectionChangePayload`,
+ * `FormSubmitPayload`, ...) are structural subtypes of `EventPayload`,
+ * so components can pass them in without casts.
+ */
+interface EventBusContextType {
+    /**
+     * Emit an event to all listeners.
+     *
+     * @param type - Event type identifier
+     * @param payload - Optional payload data (shape matches {@link EventPayload})
+     * @param source - Optional origin info (orbital/trait/...)
+     */
+    emit: (type: string, payload?: EventPayload, source?: BusEventSource) => void;
+    /**
+     * Subscribe to an event type.
+     *
+     * @param type - Event type to listen for
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    on: (type: string, listener: BusEventListener) => Unsubscribe;
+    /**
+     * Subscribe to an event type, but only fire once.
+     *
+     * @param type - Event type to listen for
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    once: (type: string, listener: BusEventListener) => Unsubscribe;
+    /**
+     * Check if there are any listeners for an event type.
+     *
+     * @param type - Event type to check
+     * @returns True if there are listeners
+     */
+    hasListeners: (type: string) => boolean;
+    /**
+     * Subscribe to ALL events regardless of type.
+     * Useful for verification, debugging, and analytics.
+     *
+     * @param listener - Callback function invoked for every emitted event
+     * @returns Unsubscribe function
+     */
+    onAny?: (listener: BusEventListener) => Unsubscribe;
+}
+
+declare global {
+    interface Window {
+        __kflowEventBus?: EventBusContextType | null;
+    }
+}
+
+/**
+ * EventBusProvider - React context provider for the event bus
+ *
+ * Provides a page-scoped event bus for trait communication.
+ * Each page has its own event bus instance.
+ *
+ * NOTE: Selection state has been moved to SelectionProvider.
+ * Use SelectionProvider for tracking selected entities.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extended context type for backward compatibility.
+ *
+ * @deprecated getSelectedEntity and clearSelectedEntity are deprecated.
+ * Use SelectionProvider and useSelection hook instead.
+ */
+interface EventBusContextTypeExtended extends EventBusContextType {
+    /** @deprecated Use useSelection from SelectionProvider instead. */
+    getSelectedEntity: () => EntityRow | null;
+    /** @deprecated Use useSelection from SelectionProvider instead. */
+    clearSelectedEntity: () => void;
+}
+declare global {
+    var __almadarUiEventBusContext: React.Context<EventBusContextTypeExtended | null> | undefined;
+}
+
+/**
+ * FeatureCard Molecule Component
+ *
+ * A card highlighting a feature with icon, title, description, and optional link.
+ * Composes Card, VStack, Icon, Typography, and Button atoms.
+ */
+
+/**
+ * FeatureCard — an icon-led card pairing a title and description to call out a
+ * single product feature.
+ *
+ * @capabilities feature highlight, benefit callout, product capability card, feature-grid tile
+ */
+interface FeatureCardProps extends A11yProps {
+    icon?: IconInput;
+    /** Feature title */
+    title: string;
+    /** Feature description */
+    description: string;
+    /** Optional link URL */
+    href?: string;
+    /** Label for the link button */
+    linkLabel?: string;
+    /** Card visual variant */
+    variant?: 'default' | 'bordered' | 'elevated' | 'interactive';
+    /** Card size affecting icon and spacing */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional class names */
+    className?: string;
+}
+declare const FeatureCard: React.FC<FeatureCardProps>;
+
+/**
+ * FeatureGrid Molecule Component
+ *
+ * A responsive grid layout for displaying multiple FeatureCards.
+ * Composes SimpleGrid and FeatureCard molecules.
+ */
+
+interface FeatureGridProps extends A11yProps {
+    /** Array of feature card configurations */
+    items: FeatureCardProps[];
+    /** Number of grid columns */
+    columns?: 2 | 3 | 4 | 6;
+    /** Gap between grid items */
+    gap?: 'sm' | 'md' | 'lg';
+    /** Additional class names */
+    className?: string;
+}
+declare const FeatureGrid: React.FC<FeatureGridProps>;
+
+/**
+ * SimpleGrid Component
+ *
+ * A simplified grid that automatically adjusts columns based on available space.
+ * Perfect for card layouts and item collections.
+ */
+
+type SimpleGridGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+interface SimpleGridProps extends A11yProps {
+    /** Minimum width of each child (e.g., 200, "200px", "15rem") */
+    minChildWidth?: number | string;
+    /** Maximum number of columns */
+    maxCols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Exact number of columns (disables auto-fit) */
+    cols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Gap between items */
+    gap?: SimpleGridGap;
+    /** Custom class name */
+    className?: string;
+    /** Children elements */
+    children: React.ReactNode;
+    /** Element id forwarded to the grid element. */
+    id?: string;
+    /** DOM attributes forwarded to the grid element (aria-*, data-*, role, id). */
+    [attr: `aria-${string}` | `data-${string}`]: string | number | boolean | undefined;
+}
+/**
+ * SimpleGrid - Auto-responsive grid layout
+ */
+declare const SimpleGrid: React.FC<SimpleGridProps>;
+
+/**
+ * Container — max-width centering wrapper (distinct from Box).
+ * Box controls padding/margin/bg/shadow on an arbitrary element.
+ * Container constrains page width and centers; use it at the layout level,
+ * not as a generic div replacement.
+ */
+
+type ContainerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+type ContainerPadding = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+interface ContainerProps extends A11yProps {
+    /** Maximum width */
+    size?: ContainerSize;
+    /** Alias for size (pattern compatibility) */
+    maxWidth?: ContainerSize;
+    /** Horizontal padding */
+    padding?: ContainerPadding;
+    /** Center horizontally */
+    center?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Children elements */
+    children?: React.ReactNode;
+    /** HTML element to render as */
+    as?: React.ElementType;
+}
+/**
+ * Container - Centers and constrains content width
+ */
+declare const Container: React.FC<ContainerProps>;
+
+/**
+ * StatDisplay Molecule
+ *
+ * A compact stat display: label + value + optional icon.
+ * Molecule-level replacement for the stats (StatCard) organism in behavior schemas.
+ * No entity prop, no data fetching, no hooks beyond icon resolution.
+ */
+
+type StatDisplayLook = 'elevated' | 'flat' | 'progress-backed' | 'gauge' | 'sparkline';
+interface StatDisplayProps extends A11yProps {
+    /** Display label (e.g., "Total", "Remaining") */
+    label: string;
+    /** Primary value (number or formatted string) */
+    value: number | string;
+    /** Optional denominator. >0 renders "value / max"; 0 or omitted hides the divider. */
+    max?: number;
+    /** Optional progress target. >0 renders a progress bar at value/target. */
+    target?: number;
+    /** Signed delta vs previous period. >0 renders ↑ green, <0 renders ↓ red, 0 hides. Polarity reversal via `trendPolarity`. */
+    trend?: number;
+    /** Controls whether `trend > 0` is "good" (default) or "bad". `lower-is-better` inverts the color logic. */
+    trendPolarity?: 'higher-is-better' | 'lower-is-better';
+    /** When `'percent'`, renders trend with a `%` suffix (e.g. `↓ 3.3%`); default is `'absolute'`. */
+    trendFormat?: 'absolute' | 'percent';
+    /** Optional inline sparkline data appended to the trend row. Length < 2 renders nothing. */
+    sparklineData?: readonly number[];
+    /** Event name emitted as `UI:{clickEvent}` with `{ metricLabel }` when the card is clicked. */
+    clickEvent?: string;
+    /** Prefix prepended to the formatted value (e.g. "≈ "). */
+    prefix?: string;
+    /** Suffix appended to the formatted value (e.g. " /mo", " ms"). */
+    suffix?: string;
+    /** Lucide icon name or component */
+    icon?: IconInput;
+    /** Icon background color class */
+    iconBg?: string;
+    /** Icon color class */
+    iconColor?: string;
+    /** Display format: "number", "currency", "percent" */
+    format?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Color variant */
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+    /** Compact mode (inline, no card wrapper) */
+    compact?: boolean;
+    /** Layer 2 visual treatment. */
+    look?: StatDisplayLook;
+    /** Content surface: `auto` paints the theme's surface behind this block unless it already sits on one (a card, dialog or another block); `none` opts out. */
+    surface?: SurfaceMode;
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Skeleton drawn while loading, and the shape an empty slot shows while this element's server render is in flight (`none` opts out). */
+    skeleton?: SkeletonSpec;
+    /** Error state */
+    error?: UiError | null;
+}
+declare const StatDisplay: React.FC<StatDisplayProps>;
+
+/**
+ * GradientDivider Molecule Component
+ *
+ * A horizontal line that fades from transparent at edges to primary color at center.
+ * Used between major sections for visual separation without hard background-color breaks.
+ */
+
+interface GradientDividerProps extends A11yProps {
+    /** Semantic palette token or a raw CSS color value. Defaults to 'primary'. */
+    color?: ColorToken | string;
+    /** Additional class names */
+    className?: string;
+}
+declare const GradientDivider: React.FC<GradientDividerProps>;
+
+/**
+ * AnimatedCounter Molecule Component
+ *
+ * Counts up to a target value once it scrolls into view, then eases between
+ * later value changes. Optional label below the number.
+ */
+
+interface AnimatedCounterProps extends A11yProps {
+    /** Target value. Strings may carry display affixes (e.g. "500+", "99.9%", "$1.2M"). */
+    value: string | number;
+    /** Label displayed below the number */
+    label?: string;
+    /** Animation duration in ms */
+    duration?: number;
+    /** Text displayed before the number */
+    prefix?: string;
+    /** Text displayed after the number */
+    suffix?: string;
+    /** "number" (locale grouping), "currency" (locale currency), "percent" (rounded %). Unset keeps the value's own decimals. */
+    format?: string;
+    /** Additional class names */
+    className?: string;
+}
+declare const AnimatedCounter: React.FC<AnimatedCounterProps>;
+
+/**
+ * GeometricPattern Molecule
+ *
+ * Composes PatternTile into reusable layout modes for Islamic geometric
+ * background decoration. Supports four modes:
+ *
+ *   background — full tiling fill behind content
+ *   left/right — pattern fades from one side toward the other
+ *   frame      — thin decorative strips above and below content
+ *
+ * Uses SVG <pattern> for efficient tiling and <mask> for fade effects.
+ * All rendering is pure SVG (SSR-safe, no browser APIs).
+ */
+
+interface GeometricPatternProps {
+    /** Which geometric tile design */
+    variant?: PatternVariant;
+    /** Layout mode */
+    mode?: 'background' | 'left' | 'right' | 'dual' | 'around' | 'frame';
+    /** Overall opacity (default: 0.06) */
+    opacity?: number;
+    /** Stroke color passed to PatternTile */
+    color?: string;
+    /** Tile scale multiplier (default: 1) */
+    scale?: number;
+    /** Stroke width passed to PatternTile */
+    strokeWidth?: number;
+    /** Content to wrap (used in frame mode) */
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const GeometricPattern: React.FC<GeometricPatternProps>;
+
+/**
+ * EdgeDecoration Molecule
+ *
+ * Standalone SVG decorative elements positioned on section edges.
+ * Unlike GeometricPattern (which tiles small units), these are large
+ * singular shapes placed at specific positions: left edge, right edge,
+ * or both.
+ *
+ * Variants:
+ *   arch       — Concentric pointed mihrab arches (half-circles opening inward)
+ *   vine       — Flowing arabesque scroll tendrils running vertically
+ *   lattice    — Fine curved diamond lattice mesh
+ *
+ * Each variant renders as an absolutely-positioned SVG on one or both
+ * sides of the parent container.
+ */
+
+type EdgeVariant = 'arch' | 'vine' | 'lattice';
+type EdgeSide = 'left' | 'right' | 'both';
+interface EdgeDecorationProps {
+    /** Which decorative element */
+    variant?: EdgeVariant;
+    /** Which side(s) to place the decoration */
+    side?: EdgeSide;
+    /** Overall opacity (default: 0.15) */
+    opacity?: number;
+    /** Semantic palette token or a raw CSS color value for the stroke. */
+    color?: ColorToken | string;
+    /** Stroke width */
+    strokeWidth?: number;
+    /** Width of the decoration area as percentage of container (default: 15) */
+    width?: number;
+    className?: string;
+}
+declare const EdgeDecoration: React.FC<EdgeDecorationProps>;
+
+export { AnimatedCounter, Container, EdgeDecoration, FeatureCard, FeatureGrid, GeometricPattern, GradientDivider, SimpleGrid, StatDisplay };
+export type { AnimatedCounterProps, EdgeDecorationProps, EdgeSide, EdgeVariant, FeatureCardProps, FeatureGridProps, GeometricPatternProps, GradientDividerProps };