@almadar/ui 2.0.0 → 2.0.1

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,76 @@
+/**
+ * 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
+ */
+export type FieldDef = string | {
+    key: string;
+    header?: 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,43 @@
+/**
+ * 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.
+ *
+ * When `entity` prop is provided without `data`, automatically fetches data
+ * using the useEntityList hook.
+ *
+ * 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';
+export interface MasterDetailProps<T extends {
+    id: string | number;
+} = {
+    id: string | number;
+}> {
+    /** Entity type name - when provided without data, auto-fetches from API */
+    entity?: string;
+    /** 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[];
+    /** Data array - if not provided and entity is set, data is auto-fetched */
+    data?: readonly T[] | T[];
+    /** Loading state */
+    loading?: boolean;
+    /** Loading state alias */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Additional class name */
+    className?: string;
+}
+export declare function MasterDetail<T extends {
+    id: string | number;
+}>({ entity, masterFields, detailFields: _detailFields, // Captured but not used here - detail handled separately
+data: externalData, 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,66 @@
+/**
+ * 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";
+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 {
+    /** Gallery title */
+    title?: string;
+    /** Media items */
+    items?: readonly MediaItem[];
+    /** Schema-driven data */
+    data?: readonly Record<string, unknown>[];
+    /** Column count */
+    columns?: 2 | 3 | 4 | 5 | 6;
+    /** Enable item selection */
+    selectable?: boolean;
+    /** Selected item IDs */
+    selectedItems?: readonly string[];
+    /** Selection change callback */
+    onSelectionChange?: (ids: string[]) => void;
+    /** Show upload button */
+    showUpload?: boolean;
+    /** Actions */
+    actions?: readonly MediaGalleryAction[];
+    /** Aspect ratio for thumbnails */
+    aspectRatio?: "square" | "landscape" | "portrait";
+    /** 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 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>;

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

@@ -0,0 +1,68 @@
+/**
+ * Navigation Organism Component
+ *
+ * A navigation component with items, active indicators, icons, and badges.
+ * Uses Menu, ButtonGroup molecules and Button, Icon, Badge, Typography, Divider atoms.
+ */
+import React from 'react';
+import type { LucideIcon } from 'lucide-react';
+export interface NavigationItem {
+    /**
+     * Item ID
+     */
+    id: string;
+    /**
+     * Item label
+     */
+    label: string;
+    /**
+     * Item icon
+     */
+    icon?: LucideIcon;
+    /**
+     * Item badge
+     */
+    badge?: string | number;
+    /**
+     * Item href
+     */
+    href?: string;
+    /**
+     * Item click handler
+     */
+    onClick?: () => void;
+    /**
+     * Is active
+     */
+    isActive?: boolean;
+    /**
+     * Disable item
+     */
+    disabled?: boolean;
+    /**
+     * Sub-menu items
+     */
+    subMenu?: NavigationItem[];
+}
+export interface NavigationProps {
+    /**
+     * Navigation items
+     */
+    items: NavigationItem[];
+    /**
+     * Navigation orientation
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+}
+export declare const Navigation: React.FC<NavigationProps>;

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

@@ -0,0 +1,48 @@
+/**
+ * OrbitalVisualization Component
+ *
+ * Visualizes KFlow schemas as atomic orbitals based on complexity.
+ * Uses CSS 3D transforms for lightweight rendering without Three.js.
+ *
+ * Orbital Types (based on complexity score):
+ * - 1s (1-3): Simple sphere - Red
+ * - 2s (4-8): Larger sphere - Orange
+ * - 2p (9-15): Dumbbell shape - Yellow
+ * - 3s (16-25): Sphere with node - Green
+ * - 3p (26-40): Complex dumbbell - Blue
+ * - 3d (41-60): Cloverleaf - Indigo
+ * - 4f (61+): Multi-lobe - Violet
+ */
+import React from "react";
+export interface OrbitalVisualizationProps {
+    /** Full KFlow schema object */
+    schema?: {
+        dataEntities?: unknown[];
+        ui?: {
+            pages?: {
+                sections?: unknown[];
+            }[];
+        };
+        traits?: unknown[];
+    };
+    /** Direct complexity override (1-100+) */
+    complexity?: number;
+    /** Size of the visualization */
+    size?: "sm" | "md" | "lg" | "xl";
+    /** Show complexity label */
+    showLabel?: boolean;
+    /** Animation enabled */
+    animated?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+}
+export declare const OrbitalVisualization: React.FC<OrbitalVisualizationProps>;
+export default OrbitalVisualization;

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

@@ -0,0 +1,59 @@
+import React from "react";
+import { LucideIcon } from "lucide-react";
+export interface PageBreadcrumb {
+    label: string;
+    href?: string;
+}
+/**
+ * Schema-based action definition
+ */
+export interface SchemaAction {
+    label: string;
+    /** Navigate to URL when clicked */
+    navigatesTo?: string;
+    /** Custom click handler */
+    onClick?: () => void;
+    /** Event to dispatch via event bus (for trait state machine integration) */
+    event?: string;
+    variant?: "primary" | "secondary" | "ghost" | "danger";
+    icon?: LucideIcon;
+    loading?: boolean;
+    disabled?: boolean;
+}
+export interface PageHeaderProps {
+    /** Page title - accepts unknown to handle generated code accessing dynamic entity data */
+    title?: string | number | unknown;
+    /** Optional subtitle/description */
+    subtitle?: string | number | unknown;
+    /** Show back button */
+    showBack?: boolean;
+    /** Event to emit when back is clicked (default: BACK) */
+    backEvent?: string;
+    /** Breadcrumbs */
+    breadcrumbs?: readonly PageBreadcrumb[];
+    /** Status badge */
+    status?: {
+        label: string;
+        variant?: "default" | "success" | "warning" | "danger" | "info";
+    };
+    /** Actions array - first action with variant='primary' (or first action) is the main action */
+    actions?: readonly Readonly<SchemaAction>[];
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Tabs for sub-navigation */
+    tabs?: ReadonlyArray<{
+        label: string;
+        value: string;
+        count?: number;
+    }>;
+    activeTab?: string;
+    onTabChange?: (value: string) => void;
+    /** Custom content in the header */
+    children?: React.ReactNode;
+    className?: string;
+}
+export declare const PageHeader: React.FC<PageHeaderProps>;

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

@@ -0,0 +1,44 @@
+/**
+ * Section Component
+ *
+ * A semantic section wrapper with optional title, description, and action.
+ * Perfect for grouping related content with consistent spacing.
+ */
+import React from 'react';
+export type SectionPadding = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+export type SectionVariant = 'default' | 'card' | 'bordered' | 'filled';
+export interface SectionProps {
+    /** Section title */
+    title?: string;
+    /** Section subtitle/description */
+    description?: string;
+    /** Action element (e.g., button, link) */
+    action?: React.ReactNode;
+    /** Padding amount */
+    padding?: SectionPadding;
+    /** Visual variant */
+    variant?: SectionVariant;
+    /** Show divider below header */
+    divider?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Children elements */
+    children: React.ReactNode;
+    /** Header custom class name */
+    headerClassName?: string;
+    /** Content custom class name */
+    contentClassName?: string;
+    /** HTML element to render as */
+    as?: React.ElementType;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+}
+/**
+ * Section - Semantic content grouping with header
+ */
+export declare const Section: React.FC<SectionProps>;
+export default Section;