@almadar/ui 5.79.1 → 5.80.0

package/dist/components/core/organisms/Form.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Form Organism Component
+ *
+ * A form container component with submit/reset handling.
+ * Supports both children-based and schema-based form generation.
+ * Renders correct input types based on field definitions including relations.
+ *
+ * Extended for inspection forms with:
+ * - Conditional field visibility via S-expressions
+ * - Hidden calculations that emit GLOBAL_VARIABLE_SET events
+ * - Violation triggers that emit VIOLATION_DETECTED events
+ * - Nested sections with collapsible support
+ */
+import React from "react";
+import type { EntityRow, EventKey, FieldValue, JsonObject } from "@almadar/core";
+import { type SelectOption } from "../atoms/Select";
+import { type RelationOption } from "../molecules/RelationSelect";
+import type { OrbitalEntity } from "@almadar/core";
+import type { IconInput } from "../atoms/Icon";
+import { type SExpr } from "@almadar/evaluator";
+import type { UiError } from '../atoms/types';
+/**
+ * S-Expression type for conditional logic (re-export from @almadar/evaluator)
+ */
+export type SExpression = SExpr;
+/**
+ * Form-specific evaluation context
+ */
+export interface FormEvaluationContext {
+    formValues: EntityRow;
+    globalVariables: Record<string, FieldValue>;
+    localVariables?: Record<string, FieldValue>;
+    entity?: EntityRow;
+}
+/**
+ * Hidden calculation definition
+ */
+export interface HiddenCalculation {
+    variableName: string;
+    expression: SExpression;
+    triggerFields: string[];
+}
+/**
+ * Violation definition
+ */
+export interface ViolationDefinition {
+    law: string;
+    article: string;
+    actionType: "measure" | "admin" | "penalty";
+    message: string;
+}
+/**
+ * Violation trigger definition
+ */
+export interface ViolationTrigger {
+    condition: SExpression;
+    violation: ViolationDefinition;
+    fieldId?: string;
+}
+/**
+ * Form section definition for nested sections
+ */
+export interface FormSection {
+    id: string;
+    title: string;
+    condition?: SExpression;
+    fields: SchemaField[];
+    collapsible?: boolean;
+}
+/**
+ * Form tab definition for tabbed inspection forms
+ */
+export interface FormTabDefinition {
+    /** Unique tab identifier */
+    id: string;
+    /** Tab display label */
+    label: string;
+    /** Icon for the tab */
+    icon?: IconInput;
+    /** Sections within this tab */
+    sections: FormSection[];
+    /** Condition for showing/hiding the entire tab */
+    condition?: SExpression;
+    /** Badge count or text to display on tab */
+    badge?: string | number;
+    /** Whether this tab has validation errors */
+    hasErrors?: boolean;
+}
+/**
+ * Relation configuration for foreign key fields
+ */
+export interface RelationConfig {
+    /** Target entity name (e.g., 'User', 'Project') */
+    entity: string;
+    /** Field on target entity to display (defaults to 'name') */
+    displayField?: string;
+    /** Cardinality: one-to-one or one-to-many */
+    cardinality?: "one" | "many";
+}
+/**
+ * Schema field definition
+ * Supports both 'name' and 'field' for compatibility with different schema formats
+ */
+export interface SchemaField {
+    /** Field name (primary) */
+    name?: string;
+    /** Field name (alias for compatibility) */
+    field?: string;
+    /** Display label */
+    label?: string;
+    /** Field type (string, number, email, date, boolean, enum, relation, etc.) */
+    type?: string;
+    /** Input type for rendering (text, select, textarea, checkbox, etc.) */
+    inputType?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether field is required */
+    required?: boolean;
+    /** Default value */
+    defaultValue?: FieldValue;
+    /** Options for select/enum fields - accepts readonly for generated const arrays */
+    options?: readonly SelectOption[];
+    /** Enum values (alternative to options, just strings) - accepts readonly for generated const arrays */
+    values?: readonly string[];
+    /** Relation configuration for foreign key references */
+    relation?: RelationConfig;
+    /** Minimum value (for number) or length (for string) */
+    min?: number;
+    /** Maximum value or length */
+    max?: number;
+    /** Pattern for validation */
+    pattern?: string;
+    /** Validation rules */
+    validation?: JsonObject;
+    /** Whether field is readonly (displays value but cannot edit) */
+    readonly?: boolean;
+    /** Whether field is disabled (alternative to readonly for compatibility) */
+    disabled?: boolean;
+}
+/**
+ * Form is the ONE EXCEPTION to the "no internal state" rule for organisms.
+ * It manages local `formData` state for field input tracking.
+ * See EntityDisplayProps in ./types.ts for documentation.
+ */
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit"> {
+    /** Form fields (traditional React children) */
+    children?: React.ReactNode;
+    /** Submit event name for trait dispatch (emitted via eventBus as UI:{onSubmit}) */
+    onSubmit?: string;
+    /** Cancel event name for trait dispatch (emitted via eventBus as UI:{onCancel}) */
+    onCancel?: string;
+    /** Form layout */
+    layout?: "vertical" | "horizontal" | "inline";
+    /** Gap between fields */
+    gap?: "sm" | "md" | "lg";
+    /** Additional CSS classes */
+    className?: string;
+    /** Entity type name or schema object. When OrbitalEntity, fields are auto-derived if not provided. */
+    entity?: string | OrbitalEntity | EntityRow | readonly EntityRow[];
+    /**
+     * Form mode — 'create' for new records, 'edit' for updating existing.
+     * Accepts `string` so schema-driven callers (whose `config.mode` is typed
+     * as `string` per the trait's declared config block) compile cleanly. The
+     * runtime treats anything other than 'edit' as 'create'.
+     */
+    mode?: "create" | "edit" | string;
+    /** Fields definition (schema format) - accepts readonly for generated const arrays */
+    fields: readonly Readonly<SchemaField>[];
+    /** Initial form data */
+    initialData?: EntityRow;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+    /** Submit button label */
+    submitLabel?: string;
+    /** Cancel button label (if provided, shows cancel button) */
+    cancelLabel?: string;
+    /** Show cancel button (defaults to true for schema forms) */
+    showCancel?: boolean;
+    /** Show submit button (defaults to true for schema forms). Set false when a parent atom owns the submit action externally (e.g. wizard footers). */
+    showSubmit?: boolean;
+    /** Form title (used by ModalSlot to extract title) */
+    title?: string;
+    /** Event to dispatch on successful submit (defaults to 'SAVE') */
+    submitEvent?: EventKey;
+    /** Event to dispatch on cancel (defaults to 'CANCEL') */
+    cancelEvent?: EventKey;
+    /** Data for relation fields: { fieldName: RelationOption[] } */
+    relationsData?: Record<string, readonly RelationOption[]>;
+    /** Loading state for relation data: { fieldName: boolean } */
+    relationsLoading?: Record<string, boolean>;
+    /** Map of fieldId → S-expression condition for conditional field display (boolean true means enabled but config loaded separately) */
+    conditionalFields?: Record<string, SExpression> | boolean;
+    /** Hidden calculations that emit GLOBAL_VARIABLE_SET on field change (boolean true means enabled but config loaded separately) */
+    hiddenCalculations?: HiddenCalculation[] | boolean;
+    /** Violation conditions that emit VIOLATION_DETECTED when met (boolean true means enabled but config loaded separately) */
+    violationTriggers?: ViolationTrigger[] | boolean;
+    /** Context for S-expression evaluation */
+    evaluationContext?: FormEvaluationContext;
+    /** Nested form sections with optional conditions */
+    sections?: FormSection[];
+    /** Callback when any field value changes */
+    onFieldChange?: (change: {
+        fieldId: string;
+        value: FieldValue | undefined;
+        formValues: Record<string, FieldValue | undefined>;
+    }) => void;
+    /** Config path for form configuration (schema-driven) */
+    configPath?: string;
+    /** Whether the form supports repeatable entries */
+    repeatable?: boolean;
+}
+export declare const Form: React.FC<FormProps>;

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

@@ -0,0 +1,108 @@
+/**
+ * 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 { UiError } from '../atoms/types';
+import { type BoxPadding, type BoxBg, type BoxRounded, type BoxShadow } from '../atoms/Box';
+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?: UiError | null;
+    /** Entity name */
+    entity?: 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 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?: UiError | 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?: UiError | 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 box: typeof BoxPattern;
+    readonly spacer: typeof SpacerPattern;
+    readonly divider: typeof DividerPattern;
+};

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

@@ -0,0 +1,81 @@
+/**
+ * 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 { AssetUrl, EventKey, FieldValue, EntityRow } from "@almadar/core";
+import type { IconInput } from "../atoms/Icon";
+import { type MenuItem } from "../molecules/Menu";
+import type { DisplayStateProps } from "./types";
+export type ListItem = {
+    id: string;
+    title?: string;
+    description?: string;
+    icon?: IconInput;
+    avatar?: {
+        src?: AssetUrl;
+        alt?: string;
+        initials?: string;
+    };
+    badge?: string | number;
+    metadata?: React.ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+    completed?: boolean;
+    _fields?: Record<string, FieldValue | undefined>;
+};
+export interface SchemaItemAction {
+    label: string;
+    /** Event to dispatch on click */
+    event?: EventKey;
+    navigatesTo?: string;
+    /** Action placement - accepts all common placement values */
+    placement?: "row" | "bulk" | "card" | "footer" | string;
+    /** Alternate event-dispatch field (same semantics as `event`) — generated code emits `UI:{action}` on click */
+    action?: EventKey;
+    variant?: "primary" | "secondary" | "ghost" | "danger" | "default";
+    /** Click handler from generated code */
+    onClick?: (row: EntityRow) => 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 DisplayStateProps {
+    /** Entity data (single record or collection). */
+    entity?: EntityRow | readonly EntityRow[];
+    /** 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/core/organisms/MasterDetail.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { DisplayStateProps } from './types';
+import type { EntityRow } from '@almadar/core';
+export interface MasterDetailProps<T extends EntityRow & {
+    id: string | number;
+} = EntityRow & {
+    id: string | number;
+}> extends DisplayStateProps {
+    /** Entity rows to display in the master list (collection cardinality). */
+    entity?: readonly EntityRow[];
+    /** 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 EntityRow & {
+    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/core/organisms/MediaGallery.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 { AssetUrl, EventEmit } from "@almadar/core";
+import type { DisplayStateProps } from "./types";
+import type { EntityRow } from "@almadar/core";
+export type MediaItem = EntityRow & {
+    /** Unique identifier */
+    id: string;
+    /** Media URL */
+    src: AssetUrl;
+    /** Alt text */
+    alt?: string;
+    /** Thumbnail URL (defaults to src) */
+    thumbnail?: AssetUrl;
+    /** 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 DisplayStateProps {
+    /** Entity rows to display (collection cardinality). */
+    entity?: readonly EntityRow[];
+    /** 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?: EventEmit<{
+        selection: 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/core/organisms/ModalSlot.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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';
+import type { UiError } from '../atoms/types';
+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?: UiError | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Source trait name for qualified event emission */
+    sourceTrait?: 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/core/organisms/NotifyListener.d.ts

@@ -0,0 +1,15 @@
+/**
+ * NotifyListener Component
+ *
+ * Listens for UI:NOTIFY events on the event bus and renders toast notifications.
+ * Mount once at the app root level (inside EventBusProvider).
+ *
+ * The compiler transpiles `notify("message", severity)` effects into
+ * `eventBus.emit('UI:NOTIFY', { message, severity })` calls.
+ * This component picks those up and renders them as Toast overlays.
+ */
+import React from 'react';
+export declare function NotifyListener(): React.ReactElement | null;
+export declare namespace NotifyListener {
+    var displayName: string;
+}

package/dist/components/core/organisms/SegmentRenderer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SegmentRenderer Organism Component
+ *
+ * Renders a parsed array of LessonSegments — markdown, code, quizzes,
+ * activation prompts, connections, reflections, Bloom questions.
+ * The `visualization` segment type is passed through as a no-op unless the
+ * caller provides `onRenderVisualization` (future extensibility hook).
+ *
+ * Event Contract:
+ * - Delegates to child molecules: UI:SAVE_ACTIVATION, UI:SAVE_REFLECTION, UI:ANSWER_BLOOM
+ * - entityAware: false
+ */
+import React from 'react';
+import { type CodeSimulationOutput } from './CodeRunnerPanel';
+import type { LessonSegment, LessonUserProgress, InteractiveOrbitalType } from '../molecules/parseLessonSegments';
+export type { LessonSegment, LessonUserProgress, CodeSimulationOutput };
+export interface SegmentRendererProps {
+    /** Parsed lesson segments (see `parseLessonSegments`) */
+    segments: LessonSegment[];
+    /** Additional CSS classes for the root container */
+    className?: string;
+    /** CSS classes for the outer wrapping div */
+    containerClassName?: string;
+    /** User progress for restoring activation/reflection state */
+    userProgress?: LessonUserProgress;
+    /**
+     * Simulate executing runnable code blocks. Omit to render runnable blocks
+     * as read-only. Real execution is a future track.
+     */
+    onRunCodeSimulation?: (code: string, language: string) => Promise<CodeSimulationOutput>;
+    /**
+     * Optional render slot for `visualization` segment types. When not provided,
+     * visualization segments are silently skipped. Callers can wire this to any
+     * custom component or orbital generator.
+     */
+    onRenderVisualization?: (type: InteractiveOrbitalType, description: string, index: number) => React.ReactNode;
+}
+export declare const SegmentRenderer: React.FC<SegmentRendererProps>;

package/dist/components/core/organisms/StatCard.d.ts

@@ -0,0 +1,65 @@
+import React from "react";
+import type { IconInput } from "../atoms/Icon";
+import type { DisplayStateProps } from "./types";
+import type { EntityRow } from "@almadar/core";
+/**
+ * Schema metric definition
+ * Supports both computed metrics (with field) and static metrics (with value)
+ */
+export interface MetricDefinition {
+    /** Field name for computed metrics (optional if value is provided) */
+    field?: string;
+    /** Display label */
+    label: string;
+    /** Static value for display (alternative to field-based computation) */
+    value?: string | number;
+    /** Icon name or component for display */
+    icon?: IconInput;
+    /** Value format (e.g., 'currency', 'percent', 'number') */
+    format?: "currency" | "percent" | "number" | string;
+}
+export interface StatCardProps extends DisplayStateProps {
+    /** Entity data (single record or collection) used to compute metrics. */
+    entity?: EntityRow | readonly EntityRow[];
+    /** Main label */
+    label?: string;
+    /** Title (alias for label) */
+    title?: string;
+    /** Primary value - accepts array from generated code (will use first element or length) */
+    value?: string | number | (string | number | undefined)[];
+    /** Previous value for comparison */
+    previousValue?: number;
+    /** Current value as number for trend calculation */
+    currentValue?: number;
+    /** Manual trend percentage (overrides calculation) */
+    trend?: number;
+    /** Trend direction (overrides calculation) */
+    trendDirection?: "up" | "down" | "neutral";
+    /** Whether up is good (green) or bad (red) */
+    invertTrend?: boolean;
+    /** Icon to display (Lucide component or icon name string) */
+    icon?: IconInput;
+    /** Icon background color */
+    iconBg?: string;
+    /** Icon color */
+    iconColor?: string;
+    /** Subtitle or description */
+    subtitle?: string;
+    /** Action button */
+    action?: {
+        label: string;
+        /** Event to dispatch via event bus (for trait state machine integration) */
+        event?: string;
+        /** Navigation URL - supports template interpolation */
+        navigatesTo?: string;
+        /** Legacy onClick callback */
+        onClick?: () => void;
+    };
+    /** Metrics to display (schema format) - accepts readonly for compatibility with generated const arrays */
+    metrics?: readonly MetricDefinition[];
+    /** Compact display mode */
+    compact?: boolean;
+    /** Sparkline data points for an inline trend chart */
+    sparklineData?: readonly number[];
+}
+export declare const StatCard: React.FC<StatCardProps>;