@almadar/ui 2.13.3 → 2.15.0

package/dist/components/organisms/GraphCanvas.d.ts

@@ -0,0 +1,69 @@
+/**
+ * GraphCanvas Organism Component
+ *
+ * A force-directed graph visualization component for node-link data.
+ * Uses canvas (necessary for performant graph rendering) with atom wrappers.
+ *
+ * Orbital Component Interface Compliance:
+ * - Entity binding with auto-fetch when entity is a string
+ * - Event emission via useEventBus (UI:* events)
+ * - isLoading and error state props
+ * - className for external styling
+ */
+import React from "react";
+export interface GraphNode {
+    id: string;
+    label?: string;
+    group?: string;
+    color?: string;
+    size?: number;
+    /** Position (optional, computed if missing) */
+    x?: number;
+    y?: number;
+}
+export interface GraphEdge {
+    source: string;
+    target: string;
+    label?: string;
+    weight?: number;
+    color?: string;
+}
+export interface GraphAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface GraphCanvasProps {
+    /** Graph title */
+    title?: string;
+    /** Graph nodes */
+    nodes?: readonly GraphNode[];
+    /** Graph edges */
+    edges?: readonly GraphEdge[];
+    /** Canvas height */
+    height?: number;
+    /** Show node labels */
+    showLabels?: boolean;
+    /** Enable zoom/pan */
+    interactive?: boolean;
+    /** Enable node dragging */
+    draggable?: boolean;
+    /** Actions */
+    actions?: readonly GraphAction[];
+    /** On node click */
+    onNodeClick?: (node: GraphNode) => void;
+    /** Node click event */
+    nodeClickEvent?: string;
+    /** Layout algorithm */
+    layout?: "force" | "circular" | "grid";
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const GraphCanvas: React.FC<GraphCanvasProps>;

package/dist/components/organisms/Header.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Header Organism Component
+ *
+ * A header component for mobile/responsive layouts with menu toggle, brand, and user avatar.
+ * Styled to match the main Layout component's mobile header.
+ */
+import React from "react";
+import type { LucideIcon } from "lucide-react";
+export interface HeaderProps {
+    /**
+     * Logo/Brand content
+     */
+    logo?: React.ReactNode;
+    /**
+     * Logo image source
+     */
+    logoSrc?: string;
+    /**
+     * Brand/App name
+     */
+    brandName?: string;
+    /**
+     * Navigation items (for desktop header variant)
+     */
+    navigationItems?: Array<{
+        label: string;
+        href?: string;
+        onClick?: () => void;
+        icon?: LucideIcon;
+        badge?: string | number;
+        active?: boolean;
+    }>;
+    /**
+     * Show menu toggle button
+     * @default true
+     */
+    showMenuToggle?: boolean;
+    /**
+     * Is menu open (for toggle icon)
+     */
+    isMenuOpen?: boolean;
+    /**
+     * Menu toggle callback
+     */
+    onMenuToggle?: () => void;
+    /**
+     * Show search input
+     * @default false
+     */
+    showSearch?: boolean;
+    /**
+     * Search placeholder
+     */
+    searchPlaceholder?: string;
+    /**
+     * Search callback
+     */
+    onSearch?: (value: string) => void;
+    /**
+     * User avatar configuration
+     */
+    userAvatar?: {
+        src?: string;
+        alt?: string;
+        initials?: string;
+    };
+    /**
+     * User name (display name or email)
+     */
+    userName?: string;
+    /**
+     * Callback when user avatar is clicked
+     */
+    onUserClick?: () => void;
+    /**
+     * Action buttons (right side)
+     */
+    actions?: React.ReactNode;
+    /**
+     * Sticky header
+     * @default true
+     */
+    sticky?: boolean;
+    /**
+     * Variant - mobile shows menu toggle, desktop shows full nav
+     * @default 'mobile'
+     */
+    variant?: "mobile" | "desktop";
+    /**
+     * Callback when logo/brand is clicked
+     */
+    onLogoClick?: () => void;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Loading state indicator (closed circuit)
+     */
+    isLoading?: boolean;
+    /**
+     * Error state (closed circuit)
+     */
+    error?: Error | null;
+    /**
+     * Entity name for schema-driven auto-fetch (closed circuit)
+     */
+    entity?: string;
+}
+export declare const Header: React.FC<HeaderProps>;

package/dist/components/organisms/JazariStateMachine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * JazariStateMachine — Al-Jazari themed state machine diagram.
+ *
+ * Thin wrapper around StateMachineView that:
+ * 1. Extracts a state machine from an orbital schema (or accepts a trait directly)
+ * 2. Converts it to DomLayoutData via the visualizer lib
+ * 3. Applies Al-Jazari brass/gold/lapis color theme
+ * 4. Renders gear-shaped state nodes via the renderStateNode prop
+ */
+import React from 'react';
+import type { EntityDisplayProps } from './types';
+interface SmState {
+    name: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+    isFinal?: boolean;
+}
+interface SmTransition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: unknown;
+    effects?: unknown[];
+}
+interface SmStateMachine {
+    states: SmState[];
+    transitions: SmTransition[];
+}
+interface SmTrait {
+    name: string;
+    stateMachine?: SmStateMachine;
+    linkedEntity?: string;
+}
+interface SmEntity {
+    name: string;
+    fields?: Array<{
+        name: string;
+    }>;
+}
+interface SmOrbital {
+    entity?: SmEntity;
+    traits?: SmTrait[];
+}
+interface SmSchema {
+    orbitals?: SmOrbital[];
+}
+export interface JazariStateMachineProps extends EntityDisplayProps<SmSchema> {
+    /** Full schema — extracts first trait's state machine */
+    schema?: SmSchema;
+    /** Or pass a single trait directly */
+    trait?: SmTrait;
+    /** Which trait to visualize (default: 0) */
+    traitIndex?: number;
+    /** Override entity field labels */
+    entityFields?: string[];
+    /** Text direction (default: 'ltr') */
+    direction?: 'ltr' | 'rtl';
+}
+export declare const JazariStateMachine: React.FC<JazariStateMachineProps>;
+export {};

package/dist/components/organisms/LayoutPatterns.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Layout Pattern Components
+ *
+ * Pattern wrappers for layout components that support recursive rendering
+ * of nested patterns via the `children` prop.
+ *
+ * These components bridge the shell's layout primitives (Stack, Box, Grid, etc.)
+ * with the pattern system's recursive rendering capability.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type StackGap, type StackAlign, type StackJustify } from '../atoms/Stack';
+import { type BoxPadding, type BoxBg, type BoxRounded, type BoxShadow } from '../atoms/Box';
+import { type GridCols, type GridGap, type ResponsiveGridCols } from '../molecules/Grid';
+import { type DividerVariant, type DividerOrientation } from '../atoms/Divider';
+/**
+ * Base props for all layout patterns with children support.
+ */
+export interface LayoutPatternProps {
+    /** Nested pattern configurations - rendered recursively */
+    children?: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name */
+    entity?: string;
+}
+export interface VStackPatternProps extends LayoutPatternProps {
+    /** Gap between children */
+    gap?: StackGap;
+    /** Cross-axis alignment */
+    align?: StackAlign;
+    /** Main-axis alignment */
+    justify?: StackJustify;
+}
+/**
+ * VStack pattern component.
+ *
+ * Renders children in a vertical stack with configurable spacing.
+ */
+export declare function VStackPattern({ gap, align, justify, className, style, children, }: VStackPatternProps): React.ReactElement;
+export declare namespace VStackPattern {
+    var displayName: string;
+}
+export interface HStackPatternProps extends LayoutPatternProps {
+    /** Gap between children */
+    gap?: StackGap;
+    /** Cross-axis alignment */
+    align?: StackAlign;
+    /** Main-axis alignment */
+    justify?: StackJustify;
+    /** Enable wrapping */
+    wrap?: boolean;
+}
+/**
+ * HStack pattern component.
+ *
+ * Renders children in a horizontal stack with configurable spacing.
+ */
+export declare function HStackPattern({ gap, align, justify, wrap, className, style, children, }: HStackPatternProps): React.ReactElement;
+export declare namespace HStackPattern {
+    var displayName: string;
+}
+export interface BoxPatternProps extends LayoutPatternProps {
+    /** Padding shorthand */
+    p?: BoxPadding;
+    /** Margin shorthand */
+    m?: BoxPadding;
+    /** Background color token */
+    bg?: BoxBg;
+    /** Show border */
+    border?: boolean;
+    /** Border radius */
+    radius?: BoxRounded;
+    /** Shadow level */
+    shadow?: BoxShadow;
+}
+/**
+ * Box pattern component.
+ *
+ * Generic styled container with theming support.
+ */
+export declare function BoxPattern({ p, m, bg, border, radius, shadow, className, style, children, }: BoxPatternProps): React.ReactElement;
+export declare namespace BoxPattern {
+    var displayName: string;
+}
+export interface GridPatternProps extends LayoutPatternProps {
+    /** Number of columns */
+    cols?: GridCols | ResponsiveGridCols;
+    /** Gap between cells */
+    gap?: GridGap;
+    /** Row gap override */
+    rowGap?: GridGap;
+    /** Column gap override */
+    colGap?: GridGap;
+}
+/**
+ * Grid pattern component.
+ *
+ * CSS Grid layout for multi-column content.
+ */
+export declare function GridPattern({ cols, gap, rowGap, colGap, className, style, children, }: GridPatternProps): React.ReactElement;
+export declare namespace GridPattern {
+    var displayName: string;
+}
+export interface CenterPatternProps extends LayoutPatternProps {
+    /** Minimum height */
+    minHeight?: string;
+}
+/**
+ * Center pattern component.
+ *
+ * Centers content horizontally and vertically.
+ */
+export declare function CenterPattern({ minHeight, className, style, children, }: CenterPatternProps): React.ReactElement;
+export declare namespace CenterPattern {
+    var displayName: string;
+}
+export interface SpacerPatternProps {
+    /** Size or 'flex' for flexible */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'flex';
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name */
+    entity?: string;
+}
+/**
+ * Spacer pattern component.
+ *
+ * Flexible space that expands or has fixed size.
+ */
+export declare function SpacerPattern({ size }: SpacerPatternProps): React.ReactElement;
+export declare namespace SpacerPattern {
+    var displayName: string;
+}
+export interface DividerPatternProps {
+    /** Orientation */
+    orientation?: DividerOrientation;
+    /** Line style */
+    variant?: DividerVariant;
+    /** Color token */
+    color?: string;
+    /** Spacing around divider */
+    spacing?: 'xs' | 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name */
+    entity?: string;
+}
+/**
+ * Divider pattern component.
+ *
+ * Visual separator between sections.
+ */
+export declare function DividerPattern({ orientation, variant, spacing, }: DividerPatternProps): React.ReactElement;
+export declare namespace DividerPattern {
+    var displayName: string;
+}
+export declare const LAYOUT_PATTERNS: {
+    readonly vstack: typeof VStackPattern;
+    readonly hstack: typeof HStackPattern;
+    readonly box: typeof BoxPattern;
+    readonly grid: typeof GridPattern;
+    readonly center: typeof CenterPattern;
+    readonly spacer: typeof SpacerPattern;
+    readonly divider: typeof DividerPattern;
+};

package/dist/components/organisms/List.d.ts

@@ -0,0 +1,78 @@
+/**
+ * List Organism Component
+ *
+ * A beautifully designed, scannable list view.
+ *
+ * Design inspiration: Linear, Notion, Apple Reminders
+ * - Soft, harmonious color palette
+ * - Refined typography with proper hierarchy
+ * - Subtle shadows and depth
+ * - Delightful hover micro-interactions
+ * - Elegant status indicators
+ *
+ * Closed Circuit Compliance (Dumb Organism):
+ * - Receives ALL data via props (no internal fetch)
+ * - Emits events via useEventBus (UI:SELECT, UI:DESELECT, UI:VIEW)
+ * - Never listens to events — only emits
+ * - No internal search/filter state — trait provides filtered data
+ */
+import React from "react";
+import type { LucideIcon } from "lucide-react";
+import { type MenuItem } from "../molecules/Menu";
+import type { EntityDisplayProps } from "./types";
+export interface ListItem {
+    id: string;
+    title?: string;
+    description?: string;
+    icon?: LucideIcon;
+    avatar?: {
+        src?: string;
+        alt?: string;
+        initials?: string;
+    };
+    badge?: string | number;
+    metadata?: React.ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+    completed?: boolean;
+    [key: string]: unknown;
+    _fields?: Record<string, unknown>;
+}
+export interface SchemaItemAction {
+    label: string;
+    /** Event to dispatch on click */
+    event?: string;
+    navigatesTo?: string;
+    /** Action placement - accepts all common placement values */
+    placement?: "row" | "bulk" | "card" | "footer" | string;
+    action?: string;
+    variant?: "primary" | "secondary" | "ghost" | "danger" | "default";
+    /** Click handler from generated code */
+    onClick?: (row: unknown) => void;
+}
+/**
+ * Field definition - can be a simple string or object with key/header or name/label
+ */
+export type FieldDef = string | {
+    key?: string;
+    header?: string;
+    name?: string;
+    label?: string;
+};
+export interface ListProps extends EntityDisplayProps {
+    /** Entity type name for display */
+    entityType?: string;
+    selectable?: boolean;
+    /** Item actions - schema-driven or function-based */
+    itemActions?: ((item: ListItem) => MenuItem[]) | readonly SchemaItemAction[];
+    showDividers?: boolean;
+    variant?: "default" | "card";
+    emptyMessage?: string;
+    renderItem?: (item: ListItem, index: number) => React.ReactNode;
+    children?: React.ReactNode;
+    /** Fields to display - accepts string[] or {key, header}[] for unified interface */
+    fields: readonly FieldDef[];
+    /** Alias for fields - backwards compatibility */
+    fieldNames?: readonly string[];
+}
+export declare const List: React.FC<ListProps>;

package/dist/components/organisms/MasterDetail.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MasterDetail Component
+ *
+ * A layout pattern that shows a list/table of entities.
+ * This is a thin wrapper around DataTable that accepts master-detail specific props.
+ *
+ * The `entity` prop carries the data array (injected by the runtime).
+ * The "detail" part is typically rendered separately via another render_ui effect
+ * to a sidebar or detail panel when an item is selected.
+ */
+import React from 'react';
+import type { EntityDisplayProps } from './types';
+export interface MasterDetailProps<T extends {
+    id: string | number;
+} = {
+    id: string | number;
+}> extends EntityDisplayProps<T> {
+    /** Fields to show in the master list (maps to DataTable columns) */
+    masterFields: readonly string[];
+    /** Fields for detail view (passed through but typically handled by separate render_ui) */
+    detailFields?: readonly string[];
+    /** Loading state (alias for isLoading) */
+    loading?: boolean;
+}
+export declare function MasterDetail<T extends {
+    id: string | number;
+}>({ entity, masterFields, detailFields: _detailFields, // Captured but not used here - detail handled separately
+loading: externalLoading, isLoading: externalIsLoading, error: externalError, className, ...rest }: MasterDetailProps<T>): React.ReactElement;
+export declare namespace MasterDetail {
+    var displayName: string;
+}
+export default MasterDetail;

package/dist/components/organisms/MediaGallery.d.ts

@@ -0,0 +1,57 @@
+/**
+ * MediaGallery Organism Component
+ *
+ * A gallery component for displaying images and media in a grid layout.
+ * Supports lightbox viewing, selection, and upload interactions.
+ *
+ * Orbital Component Interface Compliance:
+ * - Entity binding with auto-fetch when entity is a string
+ * - Event emission via useEventBus (UI:* events)
+ * - isLoading and error state props
+ * - className for external styling
+ */
+import React from "react";
+import type { EntityDisplayProps } from "./types";
+export interface MediaItem {
+    /** Unique identifier */
+    id: string;
+    /** Media URL */
+    src: string;
+    /** Alt text */
+    alt?: string;
+    /** Thumbnail URL (defaults to src) */
+    thumbnail?: string;
+    /** Media type */
+    mediaType?: "image" | "video";
+    /** Caption */
+    caption?: string;
+    /** File size */
+    fileSize?: string;
+}
+export interface MediaGalleryAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface MediaGalleryProps extends EntityDisplayProps<MediaItem> {
+    /** Gallery title */
+    title?: string;
+    /** Media items */
+    items?: readonly MediaItem[];
+    /** Column count */
+    columns?: 2 | 3 | 4 | 5 | 6;
+    /** Enable item selection */
+    selectable?: boolean;
+    /** Selected item IDs */
+    selectedItems?: readonly string[];
+    /** Event name emitted when selection changes (emitted as UI:{selectionEvent}) */
+    selectionEvent?: string;
+    /** Show upload button */
+    showUpload?: boolean;
+    /** Actions */
+    actions?: readonly MediaGalleryAction[];
+    /** Aspect ratio for thumbnails */
+    aspectRatio?: "square" | "landscape" | "portrait";
+}
+export declare const MediaGallery: React.FC<MediaGalleryProps>;

package/dist/components/organisms/Meter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Meter Organism Component
+ *
+ * A gauge/meter component for displaying a value within a range.
+ * Supports linear, radial, and segmented display modes.
+ *
+ * Orbital Component Interface Compliance:
+ * - Entity binding with auto-fetch when entity is a string
+ * - Event emission via useEventBus (UI:* events)
+ * - isLoading and error state props
+ * - className for external styling
+ */
+import React from "react";
+export type MeterVariant = "linear" | "radial" | "segmented";
+export interface MeterThreshold {
+    value: number;
+    color: string;
+    label?: string;
+}
+export interface MeterAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface MeterProps {
+    /** Current value */
+    value: number;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Display label */
+    label?: string;
+    /** Unit suffix (e.g., '%', 'MB', 'credits') */
+    unit?: string;
+    /** Display variant */
+    variant?: MeterVariant;
+    /** Color thresholds */
+    thresholds?: readonly MeterThreshold[];
+    /** Number of segments (for segmented variant) */
+    segments?: number;
+    /** Show value text */
+    showValue?: boolean;
+    /** Size (for radial variant) */
+    size?: "sm" | "md" | "lg";
+    /** Actions */
+    actions?: readonly MeterAction[];
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Meter: React.FC<MeterProps>;

package/dist/components/organisms/ModalSlot.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ModalSlot Component
+ *
+ * Wraps modal slot content in a proper Modal component.
+ * Used by trait-driven pages to display modal UI from render_ui effects.
+ *
+ * Handles:
+ * - Auto-open when content is present
+ * - Dispatches CLOSE/CANCEL events when closed
+ * - Extracts title from Form components
+ */
+import React from 'react';
+export interface ModalSlotProps {
+    /** Content to display in the modal */
+    children?: React.ReactNode;
+    /** Override modal title (extracted from children if not provided) */
+    title?: string;
+    /** Modal size */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    /** Custom class name */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+}
+/**
+ * ModalSlot - Wrapper for modal slot content
+ *
+ * Automatically shows modal when children are present,
+ * and dispatches close events when modal is dismissed.
+ */
+export declare const ModalSlot: React.FC<ModalSlotProps>;