@almadar/ui 2.14.0 → 2.15.1

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

@@ -0,0 +1,67 @@
+import React from "react";
+import { LucideIcon } from "lucide-react";
+import { EntityDisplayProps } from "./types";
+export interface Column<T> {
+    key: keyof T | string;
+    header: string;
+    /** Alias for key (used by compiler-generated fields) */
+    name?: string;
+    /** Alias for header (used by compiler-generated fields) */
+    label?: string;
+    width?: string;
+    sortable?: boolean;
+    render?: (value: unknown, row: T, index: number) => React.ReactNode;
+}
+export interface RowAction<T> {
+    label: string;
+    icon?: LucideIcon;
+    onClick: (row: T) => void;
+    variant?: "default" | "danger";
+    show?: (row: T) => boolean;
+    event?: string;
+}
+export interface DataTableProps<T extends {
+    id: string | number;
+}> extends EntityDisplayProps<T> {
+    /** Fields to display - accepts string[] or Column[] for unified interface. Alias for columns */
+    fields: readonly Column<T>[] | readonly string[];
+    /** Columns can be Column objects or simple string field names */
+    columns?: readonly Column<T>[] | readonly string[];
+    /** Item actions from generated code - maps to rowActions */
+    itemActions?: readonly {
+        label: string;
+        event?: string;
+        navigatesTo?: string;
+        action?: string;
+        placement?: "row" | "bulk" | string;
+        icon?: LucideIcon;
+        variant?: "default" | "primary" | "secondary" | "ghost" | "danger" | string;
+        onClick?: (row: T) => void;
+    }[];
+    emptyIcon?: LucideIcon;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    emptyAction?: {
+        label: string;
+        event?: string;
+    };
+    selectable?: boolean;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    rowActions?: readonly RowAction<T>[];
+    bulkActions?: ReadonlyArray<{
+        label: string;
+        icon?: LucideIcon;
+        onClick: (selectedRows: T[]) => void;
+        variant?: "default" | "danger";
+    }>;
+    headerActions?: React.ReactNode;
+    /** Show total count in pagination */
+    showTotal?: boolean;
+}
+export declare function DataTable<T extends {
+    id: string | number;
+}>({ fields, columns, entity, itemActions, isLoading, error, emptyIcon, emptyTitle, emptyDescription, emptyAction, selectable, selectedIds, sortBy, sortDirection, searchable, searchValue, searchPlaceholder, page, pageSize, totalCount, rowActions: externalRowActions, bulkActions, headerActions, showTotal, className, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace DataTable {
+    var displayName: string;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * DetailPanel Organism Component
+ *
+ * Composes atoms and molecules to create a professional detail view.
+ *
+ * Data is provided by the runtime via the `entity` prop.
+ * See EntityDisplayProps in ./types.ts for base prop contract.
+ */
+import React from "react";
+import type { LucideIcon } from "lucide-react";
+import type { EntityDisplayProps } from "./types";
+export interface DetailField {
+    label: string;
+    value: React.ReactNode;
+    icon?: LucideIcon;
+    copyable?: boolean;
+}
+export interface DetailSection {
+    title: string;
+    fields: (DetailField | string)[];
+}
+/**
+ * Action definition for DetailPanel
+ */
+export interface DetailPanelAction {
+    label: string;
+    icon?: LucideIcon;
+    onClick?: () => void;
+    /** Event to emit via event bus */
+    event?: string;
+    /** Navigation URL */
+    navigatesTo?: string;
+    /** Button variant (primary for main action, others for secondary) */
+    variant?: "primary" | "secondary" | "ghost" | "danger";
+}
+/**
+ * Field definition for unified interface - can be a simple string, key/header object, or typed object
+ */
+export type FieldDef = string | {
+    key: string;
+    header?: string;
+} | {
+    name: string;
+    type: string;
+};
+export interface DetailPanelProps extends EntityDisplayProps {
+    title?: string;
+    subtitle?: string;
+    status?: {
+        label: string;
+        variant?: "default" | "success" | "warning" | "danger" | "info";
+    };
+    avatar?: React.ReactNode;
+    sections?: readonly DetailSection[];
+    /** Unified actions array - first action with variant='primary' is the main action */
+    actions?: readonly DetailPanelAction[];
+    footer?: React.ReactNode;
+    slideOver?: boolean;
+    /** Fields to display - accepts string[], {key, header}[], or DetailField[] */
+    fields: readonly (FieldDef | DetailField)[];
+    /** Alias for fields - backwards compatibility */
+    fieldNames?: readonly string[];
+    /** Initial data for edit mode (passed by compiler) */
+    initialData?: Record<string, unknown> | unknown;
+    /** Display mode (passed by compiler) */
+    mode?: string;
+    /** Panel position (for drawer/sidebar placement) */
+    position?: "left" | "right";
+    /** Panel width (CSS value, e.g., '400px', '50%') */
+    width?: string;
+    /** Entity ID for fetching specific entity */
+    entityId?: string;
+    /** Display fields (alias for fields) */
+    displayFields?: readonly string[];
+    /** Show actions flag */
+    showActions?: boolean;
+}
+export declare const DetailPanel: React.FC<DetailPanelProps>;

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

@@ -0,0 +1,60 @@
+/**
+ * DocumentViewer Organism Component
+ *
+ * A document viewer for displaying PDFs, documents, and rich text content.
+ * Uses iframe for PDF rendering (necessary) and atoms for all surrounding UI.
+ *
+ * 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 DocumentType = "pdf" | "text" | "html" | "markdown";
+export interface DocumentAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface DocumentViewerProps {
+    /** Document title */
+    title?: string;
+    /** Document URL (for PDF/external documents) */
+    src?: string;
+    /** Document content (for text/html/markdown) */
+    content?: string;
+    /** Document type */
+    documentType?: DocumentType;
+    /** Current page (for multi-page documents) */
+    currentPage?: number;
+    /** Total pages */
+    totalPages?: number;
+    /** Viewer height */
+    height?: number | string;
+    /** Show toolbar */
+    showToolbar?: boolean;
+    /** Show download button */
+    showDownload?: boolean;
+    /** Show print button */
+    showPrint?: boolean;
+    /** Actions */
+    actions?: readonly DocumentAction[];
+    /** Multiple documents (tabbed view) */
+    documents?: readonly {
+        label: string;
+        src?: string;
+        content?: string;
+        documentType?: DocumentType;
+    }[];
+    /** 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 DocumentViewer: React.FC<DocumentViewerProps>;

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

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

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

@@ -0,0 +1,206 @@
+/**
+ * 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 SelectOption } from "../atoms/Select";
+import { type RelationOption } from "../molecules/RelationSelect";
+import type { OrbitalEntity } from "@almadar/core";
+import { type SExpr } from "@almadar/evaluator";
+/**
+ * S-Expression type for conditional logic (re-export from @almadar/evaluator)
+ */
+export type SExpression = SExpr;
+/**
+ * Form-specific evaluation context
+ */
+export interface FormEvaluationContext {
+    formValues: Record<string, unknown>;
+    globalVariables: Record<string, unknown>;
+    localVariables?: Record<string, unknown>;
+    entity?: Record<string, unknown>;
+}
+/**
+ * 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 name for the tab (from Icon component) */
+    icon?: string;
+    /** 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?: unknown;
+    /** 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?: Record<string, unknown>;
+    /** 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 | readonly Record<string, unknown>[];
+    /** Form mode - 'create' for new records, 'edit' for updating existing */
+    mode?: "create" | "edit";
+    /** Fields definition (schema format) - accepts readonly for generated const arrays */
+    fields: readonly Readonly<SchemaField>[];
+    /** Initial form data */
+    initialData?: Record<string, unknown> | unknown;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | 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;
+    /** Form title (used by ModalSlot to extract title) */
+    title?: string;
+    /** Event to dispatch on successful submit (defaults to 'SAVE') */
+    submitEvent?: string;
+    /** Event to dispatch on cancel (defaults to 'CANCEL') */
+    cancelEvent?: string;
+    /** Entity ID binding for edit mode (triggers initialData from selectedEntity in compiled code) */
+    entityId?: string;
+    /** 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 - accepts flexible types from generated code */
+    evaluationContext?: FormEvaluationContext | Record<string, unknown>;
+    /** Nested form sections with optional conditions */
+    sections?: FormSection[];
+    /** Callback when any field value changes */
+    onFieldChange?: (change: {
+        fieldId: string;
+        value: unknown;
+        formValues: Record<string, unknown>;
+    }) => 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/organisms/FormSection.d.ts

@@ -0,0 +1,41 @@
+import React from "react";
+import type { EntityDisplayProps } from "./types";
+export interface FormSectionProps extends EntityDisplayProps {
+    /** Section title */
+    title?: string;
+    /** Section description */
+    description?: string;
+    /** Form fields */
+    children: React.ReactNode;
+    /** Collapsible */
+    collapsible?: boolean;
+    /** Default collapsed state */
+    defaultCollapsed?: boolean;
+    /** Use card wrapper */
+    card?: boolean;
+    /** Grid columns for fields */
+    columns?: 1 | 2 | 3;
+    /** Entity ID for fetching specific entity */
+    entityId?: string;
+}
+export declare const FormSection: React.FC<FormSectionProps>;
+/**
+ * Form layout with multiple sections
+ */
+export interface FormLayoutProps extends EntityDisplayProps {
+    children: React.ReactNode;
+    /** Show section dividers */
+    dividers?: boolean;
+}
+export declare const FormLayout: React.FC<FormLayoutProps>;
+/**
+ * Form actions bar (submit/cancel buttons)
+ */
+export interface FormActionsProps extends EntityDisplayProps {
+    children: React.ReactNode;
+    /** Sticky at bottom */
+    sticky?: boolean;
+    /** Alignment */
+    align?: "left" | "right" | "between" | "center";
+}
+export declare const FormActions: React.FC<FormActionsProps>;

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>;