@almadar/ui 5.111.0 → 5.113.0

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

@@ -1,105 +0,0 @@
-/**
- * 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";
-import type { AssetUrl, EventKey, EventPayload, JsonValue } from "@almadar/core";
-import type { UiError } from "../atoms/types";
-/**
- * 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?: EventKey;
-    /** Event payload */
-    payload?: EventPayload;
-    /** Nested children patterns */
-    children?: React.ReactNode;
-    /** Image source (for img elements) */
-    src?: AssetUrl;
-    /** 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?: React.HTMLAttributes<HTMLElement>;
-    /** Loading state */
-    isLoading?: boolean;
-    /** Error state */
-    error?: UiError | 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?: EventKey;
-    payload?: EventPayload;
-    children?: CustomPatternConfig[];
-    src?: AssetUrl;
-    alt?: string;
-    href?: string;
-    external?: boolean;
-    disabled?: boolean;
-}
-/**
- * Check if a pattern config is a custom pattern.
- */
-export declare function isCustomPatternConfig(config: JsonValue | CustomPatternConfig): 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/core/organisms/DataTable.d.ts

@@ -1,79 +0,0 @@
-import React from "react";
-import type { EventKey } from "@almadar/core";
-import type { IconInput } from "../atoms/Icon";
-import { DisplayStateProps } from "./types";
-import type { EntityRow, FieldValue } from "@almadar/core";
-export type EntityTableLook = "dense" | "spacious" | "striped" | "borderless" | "card-rows";
-export interface Column<T> {
-    /** Column identity. Optional because `name` is an accepted alias; the
-     * compiler emits `{ name, label }` columns and `normalizeColumns` fills
-     * `key`/`header` from the aliases, so a column needs (`key` OR `name`) and
-     * (`header` OR `label`), not literally `key`+`header`. */
-    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: FieldValue | undefined, row: T, index: number) => React.ReactNode;
-}
-export interface RowAction<T> {
-    label: string;
-    icon?: IconInput;
-    onClick: (row: T) => void;
-    variant?: "default" | "danger";
-    show?: (row: T) => boolean;
-    event?: string;
-}
-export interface DataTableEmptyAction {
-    label: string;
-    event?: string;
-}
-export interface DataTableProps<T extends EntityRow & {
-    id: string | number;
-}> extends DisplayStateProps {
-    /** Entity rows to display (collection cardinality). */
-    entity?: readonly EntityRow[];
-    /** 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?: EventKey;
-        placement?: "row" | "bulk" | string;
-        icon?: IconInput;
-        variant?: "default" | "primary" | "secondary" | "ghost" | "danger" | string;
-        onClick?: (row: T) => void;
-    }[];
-    emptyIcon?: IconInput;
-    emptyTitle?: string;
-    emptyDescription?: string;
-    emptyAction?: DataTableEmptyAction;
-    selectable?: boolean;
-    searchable?: boolean;
-    searchPlaceholder?: string;
-    rowActions?: readonly RowAction<T>[];
-    bulkActions?: ReadonlyArray<{
-        label: string;
-        icon?: IconInput;
-        onClick: (selectedRows: T[]) => void;
-        variant?: "default" | "danger";
-    }>;
-    headerActions?: React.ReactNode;
-    /** Show total count in pagination */
-    showTotal?: boolean;
-    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
-    look?: EntityTableLook;
-}
-export declare function DataTable<T extends EntityRow & {
-    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, look, }: DataTableProps<T>): React.JSX.Element;
-export declare namespace DataTable {
-    var displayName: string;
-}

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

@@ -1,80 +0,0 @@
-/**
- * DetailPanel Organism Component
- *
- * Composes atoms and molecules to create a professional detail view.
- *
- * Data is provided by the runtime via the `entity` prop.
- * Extends DisplayStateProps (see ./types.ts) and declares `entity?: EntityRow`.
- */
-import React from "react";
-import type { EntityRow } from "@almadar/core";
-import type { IconInput } from "../atoms/Icon";
-import type { DisplayStateProps } from "./types";
-export interface DetailField {
-    label: string;
-    value: React.ReactNode;
-    icon?: IconInput;
-    copyable?: boolean;
-}
-export interface DetailSection {
-    title: string;
-    fields: (DetailField | string)[];
-}
-/**
- * Action definition for DetailPanel
- */
-export interface DetailPanelAction {
-    label: string;
-    icon?: IconInput;
-    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 DetailPanelStatus {
-    label: string;
-    variant?: "default" | "success" | "warning" | "danger" | "info";
-}
-export interface DetailPanelProps extends DisplayStateProps {
-    /** RECORD-cardinality: renders ONE record (see body collapse below). */
-    entity?: EntityRow;
-    title?: string;
-    subtitle?: string;
-    status?: DetailPanelStatus;
-    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?: EntityRow;
-    /** 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;
-    /** Display fields (alias for fields) */
-    displayFields?: readonly string[];
-    /** Show actions flag */
-    showActions?: boolean;
-}
-export declare const DetailPanel: React.FC<DetailPanelProps>;

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

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

@@ -1,214 +0,0 @@
-/**
- * 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

@@ -1,108 +0,0 @@
-/**
- * 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;
-};