@almadar/ui 2.13.3 → 2.15.0

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

@@ -0,0 +1,50 @@
+/**
+ * ConfirmDialog Component
+ *
+ * Confirmation dialog for destructive or important actions.
+ * Composes Modal molecule with Button atoms.
+ *
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+import { type ModalSize } from "../molecules/Modal";
+export type ConfirmDialogVariant = "danger" | "warning" | "info" | "default";
+export interface ConfirmDialogProps {
+    /** Whether the dialog is open (defaults to true when rendered by slot wrapper) */
+    isOpen?: boolean;
+    /** Callback when dialog is closed (injected by slot wrapper) */
+    onClose?: () => void;
+    /** Callback when action is confirmed (injected by slot wrapper) */
+    onConfirm?: () => void;
+    /** Dialog title */
+    title: string;
+    /** Dialog message/description */
+    message?: string | React.ReactNode;
+    /** Alias for message (schema compatibility) */
+    description?: string | React.ReactNode;
+    /** Confirm button text */
+    confirmText?: string;
+    /** Alias for confirmText (schema compatibility) */
+    confirmLabel?: string;
+    /** Cancel button text */
+    cancelText?: string;
+    /** Alias for cancelText (schema compatibility) */
+    cancelLabel?: string;
+    /** Dialog variant */
+    variant?: ConfirmDialogVariant;
+    /** Dialog size */
+    size?: ModalSize;
+    /** Loading state for confirm button */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * ConfirmDialog - Confirmation dialog for important actions
+ */
+export declare const ConfirmDialog: React.FC<ConfirmDialogProps>;
+export default ConfirmDialog;

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

@@ -0,0 +1,23 @@
+/**
+ * ContentRenderer Organism
+ *
+ * Renders rich content as a sequence of typed segments: markdown, code,
+ * orbital diagrams (via JazariStateMachine), and quiz blocks. Accepts
+ * either raw content string (auto-parsed) or pre-parsed segments.
+ *
+ * Event Contract:
+ * - Delegates to child components (CodeBlock -> UI:COPY_CODE)
+ * - entityAware: false
+ */
+import React from 'react';
+import { type ContentSegment } from '../../lib/parseContentSegments';
+import type { EntityDisplayProps } from './types';
+export interface ContentRendererProps extends EntityDisplayProps {
+    /** Raw content string — auto-parsed into segments */
+    content?: string;
+    /** Pre-parsed segments (overrides content) */
+    segments?: ContentSegment[];
+    /** Text direction for markdown */
+    direction?: 'rtl' | 'ltr';
+}
+export declare const ContentRenderer: React.FC<ContentRendererProps>;

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

@@ -0,0 +1,104 @@
+/**
+ * CustomPattern Component
+ *
+ * Renders freeform elements with Tailwind classes for custom UI designs.
+ * Uses Box with the `as` prop to render different element types.
+ * Supports nested children and the closed circuit pattern (action prop for events).
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+/**
+ * Allowed element types for custom patterns.
+ */
+export declare const ALLOWED_CUSTOM_COMPONENTS: readonly ["div", "span", "button", "a", "p", "h1", "h2", "h3", "h4", "h5", "h6", "header", "footer", "section", "article", "nav", "main", "aside", "ul", "ol", "li", "img", "label", "input", "form"];
+export type AllowedCustomComponent = (typeof ALLOWED_CUSTOM_COMPONENTS)[number];
+/**
+ * Check if a component name is allowed.
+ */
+export declare function isAllowedComponent(component: string): component is AllowedCustomComponent;
+/**
+ * Check if an element is interactive (requires action for closed circuit).
+ */
+export declare function isInteractiveElement(component: string): boolean;
+export interface CustomPatternProps {
+    /** Element type to render */
+    component: AllowedCustomComponent;
+    /** Tailwind classes */
+    className?: string;
+    /** Token path(s) for design token resolution */
+    token?: string | string[];
+    /** Text content (for leaf elements) */
+    content?: string;
+    /** Event to emit on click (REQUIRED for interactive elements) */
+    action?: string;
+    /** Event payload */
+    payload?: Record<string, unknown>;
+    /** Nested children patterns */
+    children?: React.ReactNode;
+    /** Image source (for img elements) */
+    src?: string;
+    /** Image alt text (for img elements) */
+    alt?: string;
+    /** Link href (for a elements) */
+    href?: string;
+    /** Open link in new tab */
+    external?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Additional HTML attributes */
+    htmlProps?: Record<string, unknown>;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name */
+    entity?: string;
+}
+/**
+ * Renders a custom element with Tailwind styling.
+ *
+ * Follows the closed circuit pattern - interactive elements emit events via action prop.
+ * Uses Box with `as` prop for all element types to comply with the design system.
+ *
+ * @example
+ * ```tsx
+ * <CustomPattern
+ *   component="button"
+ *   className="bg-blue-500 text-white px-4 py-2 rounded"
+ *   action="SUBMIT"
+ *   content="Submit"
+ * />
+ * ```
+ */
+export declare function CustomPattern({ component, className, content, action, payload, children, src, alt, href, external, disabled, htmlProps, }: CustomPatternProps): React.ReactElement | null;
+export declare namespace CustomPattern {
+    var displayName: string;
+}
+export interface CustomPatternConfig {
+    type: "custom";
+    component: AllowedCustomComponent;
+    className?: string;
+    token?: string | string[];
+    content?: string;
+    action?: string;
+    payload?: Record<string, unknown>;
+    children?: CustomPatternConfig[];
+    src?: string;
+    alt?: string;
+    href?: string;
+    external?: boolean;
+    disabled?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Check if a pattern config is a custom pattern.
+ */
+export declare function isCustomPatternConfig(config: unknown): config is CustomPatternConfig;
+/**
+ * Recursively render custom pattern configurations.
+ *
+ * Use this to render nested custom patterns from render_ui effects.
+ */
+export declare function renderCustomPattern(config: CustomPatternConfig, key?: string | number): React.ReactElement;
+export { ALLOWED_CUSTOM_COMPONENTS as CUSTOM_COMPONENT_TYPES };

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