@almadar/ui 2.14.0 → 2.15.0

package/dist/components/molecules/RepeatableFormSection.d.ts

@@ -0,0 +1,58 @@
+/**
+ * RepeatableFormSection
+ *
+ * A form section that can be repeated multiple times.
+ * Used for collecting multiple entries (participants, findings, etc.)
+ *
+ * Enhanced with trackAddedInState for inspection audit trails.
+ *
+ * Event Contract:
+ * - Emits: UI:SECTION_ADDED { sectionType, index, addedInState? }
+ * - Emits: UI:SECTION_REMOVED { sectionType, index, itemId }
+ */
+import React from "react";
+export interface RepeatableItem {
+    id: string;
+    /** State in which this item was added (for audit trails) */
+    addedInState?: string;
+    /** Timestamp when item was added */
+    addedAt?: string;
+    [key: string]: unknown;
+}
+export interface RepeatableFormSectionProps {
+    /** Section type identifier */
+    sectionType: string;
+    /** Section title */
+    title: string;
+    /** Items in the section */
+    items: RepeatableItem[];
+    /** Render function for each item */
+    renderItem: (item: RepeatableItem, index: number) => React.ReactNode;
+    /** Minimum items required */
+    minItems?: number;
+    /** Maximum items allowed */
+    maxItems?: number;
+    /** Allow reordering */
+    allowReorder?: boolean;
+    /** Add button label */
+    addLabel?: string;
+    /** Empty state message */
+    emptyMessage?: string;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Add handler */
+    onAdd?: () => void;
+    /** Remove handler */
+    onRemove?: (itemId: string, index: number) => void;
+    /** Reorder handler */
+    onReorder?: (fromIndex: number, toIndex: number) => void;
+    /** Track the state in which items are added (for inspection audit) */
+    trackAddedInState?: boolean;
+    /** Current inspection state (used when trackAddedInState is true) */
+    currentState?: string;
+    /** Show audit metadata (addedInState, addedAt) */
+    showAuditInfo?: boolean;
+}
+export declare const RepeatableFormSection: React.FC<RepeatableFormSectionProps>;

package/dist/components/molecules/ScaledDiagram.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ScaledDiagram Molecule
+ *
+ * Wraps a fixed-size diagram (like JazariStateMachine / StateMachineView)
+ * and CSS-scales it to fit the parent container width.
+ *
+ * The diagram renders at its natural (large) size. We observe the content
+ * element and once the diagram is measured we apply transform:scale() with
+ * a corrected container height so surrounding layout flows correctly.
+ *
+ * Event Contract:
+ * - No events emitted (layout-only wrapper)
+ * - entityAware: false
+ */
+import React from 'react';
+export interface ScaledDiagramProps {
+    children: React.ReactNode;
+    className?: string;
+}
+export declare const ScaledDiagram: React.FC<ScaledDiagramProps>;

package/dist/components/molecules/SearchInput.d.ts

@@ -0,0 +1,60 @@
+/**
+ * SearchInput Molecule Component
+ *
+ * A search input component with icon, clear button, and loading state.
+ * Uses Input, Icon, Button, and Spinner atoms.
+ *
+ * Supports Query Singleton pattern via `query` prop for std/Search behavior.
+ */
+import React from 'react';
+export interface SearchInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    /**
+     * Search value (controlled mode)
+     */
+    value?: string;
+    /**
+     * Callback when search value changes
+     */
+    onSearch?: (value: string) => void;
+    /**
+     * Debounce delay in milliseconds
+     * @default 300
+     */
+    debounceMs?: number;
+    /**
+     * Show loading state
+     * @default false
+     */
+    isLoading?: boolean;
+    /**
+     * Placeholder text
+     * @default 'Search...'
+     */
+    placeholder?: string;
+    /**
+     * Show clear button
+     * @default true
+     */
+    clearable?: boolean;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Event name to dispatch on search (schema metadata, wired by trait)
+     * This is metadata used by the trait generator, not by the component.
+     */
+    event?: string;
+    /**
+     * Entity type for context-aware search.
+     * When provided, search events include entity context.
+     */
+    entity?: string;
+    /**
+     * Query singleton binding for state management.
+     * When provided, syncs search state with the query singleton.
+     * Example: "@TaskQuery"
+     */
+    query?: string;
+}
+export declare const SearchInput: React.FC<SearchInputProps>;

package/dist/components/molecules/SidePanel.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SidePanel Molecule Component
+ *
+ * A side panel that slides in from the right (or left) with header and content.
+ * Uses Button, Typography atoms.
+ */
+import React from "react";
+export interface SidePanelProps {
+    /**
+     * Panel title
+     */
+    title: string;
+    /**
+     * Panel content
+     */
+    children: React.ReactNode;
+    /**
+     * Is panel open
+     */
+    isOpen: boolean;
+    /**
+     * On close handler
+     */
+    onClose: () => void;
+    /**
+     * Panel width
+     * @default 'w-96'
+     */
+    width?: string;
+    /**
+     * Panel position
+     * @default 'right'
+     */
+    position?: "left" | "right";
+    /**
+     * Show overlay on mobile
+     * @default true
+     */
+    showOverlay?: boolean;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /** Declarative close event — emits UI:{closeEvent} via eventBus when panel should close */
+    closeEvent?: string;
+}
+export declare const SidePanel: React.FC<SidePanelProps>;

package/dist/components/molecules/SimpleGrid.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SimpleGrid Component
+ *
+ * A simplified grid that automatically adjusts columns based on available space.
+ * Perfect for card layouts and item collections.
+ */
+import React from 'react';
+export type SimpleGridGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export interface SimpleGridProps {
+    /** Minimum width of each child (e.g., 200, "200px", "15rem") */
+    minChildWidth?: number | string;
+    /** Maximum number of columns */
+    maxCols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Exact number of columns (disables auto-fit) */
+    cols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Gap between items */
+    gap?: SimpleGridGap;
+    /** Custom class name */
+    className?: string;
+    /** Children elements */
+    children: React.ReactNode;
+}
+/**
+ * SimpleGrid - Auto-responsive grid layout
+ */
+export declare const SimpleGrid: React.FC<SimpleGridProps>;
+export default SimpleGrid;

package/dist/components/molecules/Skeleton.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+export type SkeletonVariant = 'header' | 'table' | 'form' | 'card' | 'text';
+export interface SkeletonProps {
+    /** The skeleton variant to render */
+    variant?: SkeletonVariant;
+    /** Number of rows for table/text variants */
+    rows?: number;
+    /** Number of columns for table variant */
+    columns?: number;
+    /** Number of fields for form variant */
+    fields?: number;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * Skeleton — loading placeholder with 5 variants for Suspense fallbacks.
+ *
+ * Variants: `header`, `table`, `form`, `card`, `text`.
+ * Used as fallback content inside `<Suspense>` boundaries.
+ *
+ * @example
+ * ```tsx
+ * <Suspense fallback={<Skeleton variant="table" rows={8} columns={5} />}>
+ *   <DataTable entity="Task" />
+ * </Suspense>
+ *
+ * <Suspense fallback={<Skeleton variant="form" fields={6} />}>
+ *   <Form entity="Task" />
+ * </Suspense>
+ * ```
+ */
+export declare function Skeleton({ variant, rows, columns, fields, className, }: SkeletonProps): React.ReactElement;
+export declare namespace Skeleton {
+    var displayName: string;
+}

package/dist/components/molecules/SortableList.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SortableList Molecule
+ *
+ * A list where items can be dragged to reorder via drag handles.
+ * Uses useDragReorder for drag state management and useEventBus for event emission.
+ * Shows a drop indicator line at the target position during drag.
+ */
+import React from 'react';
+export interface SortableListProps<T = Record<string, unknown>> {
+    items: T[];
+    renderItem: (item: T, index: number) => React.ReactNode;
+    reorderEvent: string;
+    reorderPayload?: Record<string, unknown>;
+    dragHandlePosition?: 'left' | 'right';
+    className?: string;
+}
+export declare const SortableList: <T = Record<string, unknown>>(props: SortableListProps<T>) => React.ReactElement;

package/dist/components/molecules/StarRating.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+export type StarRatingSize = "sm" | "md" | "lg";
+export type StarRatingPrecision = "full" | "half";
+export interface StarRatingProps {
+    /** Current rating value */
+    value?: number;
+    /** Maximum number of stars */
+    max?: number;
+    /** Read-only display mode */
+    readOnly?: boolean;
+    /** Full or half-star precision */
+    precision?: StarRatingPrecision;
+    /** Star size */
+    size?: StarRatingSize;
+    /** Declarative event name for rating changes */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** Direct onChange callback */
+    onChange?: (value: number) => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Accessible label */
+    label?: string;
+}
+export declare const StarRating: React.FC<StarRatingProps>;

package/dist/components/molecules/StatDisplay.d.ts

@@ -0,0 +1,37 @@
+/**
+ * StatDisplay Molecule
+ *
+ * A compact stat display: label + value + optional icon.
+ * Molecule-level replacement for the stats (StatCard) organism in behavior schemas.
+ * No entity prop, no data fetching, no hooks beyond icon resolution.
+ */
+import React from 'react';
+export interface StatDisplayProps {
+    /** Display label (e.g., "Total", "Remaining") */
+    label: string;
+    /** Primary value (number or formatted string) */
+    value: number | string;
+    /** Maximum value (renders as "value / max") */
+    max?: number;
+    /** Lucide icon name or React node */
+    icon?: React.ReactNode;
+    /** Icon background color class */
+    iconBg?: string;
+    /** Icon color class */
+    iconColor?: string;
+    /** Display format: "number", "currency", "percent" */
+    format?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Color variant */
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+    /** Compact mode (inline, no card wrapper) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+}
+export declare const StatDisplay: React.FC<StatDisplayProps>;

package/dist/components/molecules/SwipeableRow.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SwipeableRow Molecule
+ *
+ * Wraps a list item to reveal action buttons on horizontal swipe.
+ * Swipe left to reveal right actions, swipe right to reveal left actions.
+ * Uses useSwipeGesture for gesture detection and useEventBus for event emission.
+ */
+import React from 'react';
+export interface SwipeAction {
+    label: string;
+    icon?: string;
+    variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+    event: string;
+    eventPayload?: Record<string, unknown>;
+}
+export interface SwipeableRowProps {
+    leftActions?: SwipeAction[];
+    rightActions?: SwipeAction[];
+    threshold?: number;
+    children: React.ReactNode;
+    itemData?: Record<string, unknown>;
+    className?: string;
+}
+export declare const SwipeableRow: React.FC<SwipeableRowProps>;

package/dist/components/molecules/Tabs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tabs Molecule Component
+ *
+ * A tabbed interface component with keyboard navigation and badge support.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from 'react';
+import type { LucideIcon } from 'lucide-react';
+export interface TabItem {
+    /** Tab ID */
+    id: string;
+    /** Tab label */
+    label: string;
+    /** Tab content - optional for event-driven tabs */
+    content?: React.ReactNode;
+    /** Tab icon */
+    icon?: LucideIcon;
+    /** Tab badge */
+    badge?: string | number;
+    /** Disable tab */
+    disabled?: boolean;
+    /** Event to emit when tab is clicked (for trait state machine integration) */
+    event?: string;
+    /** Whether this tab is currently active (for controlled tabs) */
+    active?: boolean;
+}
+export interface TabsProps {
+    /** Tab items */
+    items?: TabItem[];
+    /** Tab items (alias for items - used by generated code) */
+    tabs?: TabItem[];
+    /** Default active tab ID */
+    defaultActiveTab?: string;
+    /** Controlled active tab ID */
+    activeTab?: string;
+    /** Callback when tab changes */
+    onTabChange?: (tabId: string) => void;
+    /** Tab variant */
+    variant?: 'default' | 'pills' | 'underline';
+    /** Tab orientation */
+    orientation?: 'horizontal' | 'vertical';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Tabs: React.FC<TabsProps>;

package/dist/components/molecules/Toast.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Toast Molecule Component
+ *
+ * A toast notification component with auto-dismiss and action buttons.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from "react";
+export type ToastVariant = "success" | "error" | "info" | "warning";
+export interface ToastProps {
+    /** Toast variant */
+    variant?: ToastVariant;
+    /** Toast message */
+    message: string;
+    /** Toast title (optional) */
+    title?: string;
+    /** Auto-dismiss duration in milliseconds (0 = no auto-dismiss) */
+    duration?: number;
+    /** Show dismiss button */
+    dismissible?: boolean;
+    /** Callback when toast is dismissed */
+    onDismiss?: () => void;
+    /** Action button label */
+    actionLabel?: string;
+    /** Action button click handler */
+    onAction?: () => void;
+    /** Badge count (optional) */
+    badge?: string | number;
+    /** Additional CSS classes */
+    className?: string;
+    /** Declarative dismiss event — emits UI:{dismissEvent} via eventBus when toast is dismissed */
+    dismissEvent?: string;
+    /** Declarative action event — emits UI:{actionEvent} via eventBus when action button is clicked */
+    actionEvent?: string;
+}
+export declare const Toast: React.FC<ToastProps>;

package/dist/components/molecules/Tooltip.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tooltip Molecule Component
+ *
+ * A tooltip component with position variants and delay options.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from 'react';
+export type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipProps {
+    /** Tooltip content */
+    content: React.ReactNode;
+    /** Tooltip trigger element (ReactElement or ReactNode that will be wrapped in span) */
+    children: React.ReactNode;
+    /** Tooltip position */
+    position?: TooltipPosition;
+    /** Show delay in milliseconds */
+    delay?: number;
+    /** Hide delay in milliseconds */
+    hideDelay?: number;
+    /** Show arrow */
+    showArrow?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Tooltip: React.FC<TooltipProps>;

package/dist/components/molecules/UploadDropZone.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+export interface UploadDropZoneProps {
+    /** Accepted MIME types (e.g., "image/*", "application/pdf") */
+    accept?: string;
+    /** Max file size in bytes */
+    maxSize?: number;
+    /** Max number of files */
+    maxFiles?: number;
+    /** Label text */
+    label?: string;
+    /** Description text below label */
+    description?: string;
+    /** Icon name (Lucide string) */
+    icon?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Declarative event name for file selection */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** Direct onFiles callback */
+    onFiles?: (files: File[]) => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const UploadDropZone: React.FC<UploadDropZoneProps>;

package/dist/components/molecules/ViolationAlert.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ViolationAlert
+ *
+ * Displays inspection violations with law references and action types.
+ * Used in inspection forms to show detected compliance violations.
+ *
+ * Action Types:
+ * - measure: Corrective measure required (warning)
+ * - admin: Administrative action (error)
+ * - penalty: Penalty proceedings (error, severe)
+ */
+import React from "react";
+export interface ViolationRecord {
+    /** Unique violation identifier */
+    id: string;
+    /** Law reference (e.g., "ZVPOT-1") */
+    law: string;
+    /** Article reference (e.g., "14/1") */
+    article: string;
+    /** Violation message */
+    message: string;
+    /** Action type determines severity */
+    actionType: "measure" | "admin" | "penalty";
+    /** Administrative action reference (e.g., "ZVPOT-1 234/1-4") */
+    adminAction?: string;
+    /** Penalty action reference (e.g., "ZVPOT-1 240/1-9") */
+    penaltyAction?: string;
+    /** Field that triggered this violation */
+    fieldId?: string;
+    /** Tab/form where violation occurred */
+    tabId?: string;
+}
+export interface ViolationAlertProps {
+    /** Violation data */
+    violation: ViolationRecord;
+    /** Visual severity (derived from actionType if not specified) */
+    severity?: "warning" | "error";
+    /** Dismissible alert */
+    dismissible?: boolean;
+    /** Dismiss handler */
+    onDismiss?: () => void;
+    /** Navigate to the field that caused violation */
+    onNavigateToField?: (fieldId: string) => void;
+    /** Compact display mode */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ViolationAlert: React.FC<ViolationAlertProps>;

package/dist/components/molecules/WizardNavigation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * WizardNavigation Component
+ *
+ * Navigation buttons for multi-step wizards.
+ * Includes Back, Next, and Complete buttons with proper state handling.
+ *
+ * Emits events via useEventBus for trait integration.
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+export interface WizardNavigationProps {
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Total number of steps */
+    totalSteps: number;
+    /** Whether the current step is valid (enables Next/Complete) */
+    isValid?: boolean;
+    /** Show the Back button */
+    showBack?: boolean;
+    /** Show the Next button */
+    showNext?: boolean;
+    /** Show the Complete button (on last step) */
+    showComplete?: boolean;
+    /** Custom label for Back button */
+    backLabel?: string;
+    /** Custom label for Next button */
+    nextLabel?: string;
+    /** Custom label for Complete button */
+    completeLabel?: string;
+    /** Event to emit on Back click */
+    onBack?: string;
+    /** Event to emit on Next click */
+    onNext?: string;
+    /** Event to emit on Complete click */
+    onComplete?: string;
+    /** Direct callback for Back (alternative to event) */
+    onBackClick?: () => void;
+    /** Direct callback for Next (alternative to event) */
+    onNextClick?: () => void;
+    /** Direct callback for Complete (alternative to event) */
+    onCompleteClick?: () => void;
+    /** Compact mode (smaller padding) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * WizardNavigation - Wizard navigation buttons
+ */
+export declare const WizardNavigation: React.FC<WizardNavigationProps>;
+export default WizardNavigation;

package/dist/components/molecules/WizardProgress.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WizardProgress Component
+ *
+ * Step progress indicator for multi-step wizards.
+ * Shows current step, completed steps, and allows navigation to completed steps.
+ *
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+/**
+ * Step info needed by WizardProgress.
+ * Compatible with WizardContainer's WizardStep (subset of fields).
+ */
+export interface WizardProgressStep {
+    /** Step identifier */
+    id: string;
+    /** Step title */
+    title: string;
+    /** Step description (optional) */
+    description?: string;
+}
+export interface WizardProgressProps {
+    /** Step definitions (compatible with WizardContainer's WizardStep) */
+    steps: WizardProgressStep[];
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Callback when a completed step is clicked */
+    onStepClick?: (stepIndex: number) => void;
+    /** Allow clicking on completed steps to navigate back */
+    allowNavigation?: boolean;
+    /** Compact mode (smaller, no titles) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Declarative step click event — emits UI:{stepClickEvent} with { stepIndex } */
+    stepClickEvent?: string;
+}
+/**
+ * WizardProgress - Step progress indicator
+ */
+export declare const WizardProgress: React.FC<WizardProgressProps>;
+export default WizardProgress;

package/dist/components/molecules/game/ActionButtons.d.ts

@@ -0,0 +1,34 @@
+import * as React from 'react';
+export interface ActionButtonConfig {
+    /** Unique identifier */
+    id: string;
+    /** Display label */
+    label?: string;
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Button variant */
+    variant?: 'primary' | 'secondary' | 'ghost' | string;
+}
+/** Event Contract:
+ *  Emits: UI:ACTION
+ */
+export interface ActionButtonsProps {
+    /** Button configurations */
+    buttons: ActionButtonConfig[];
+    /** Called when a button is pressed/released */
+    onAction?: (id: string, pressed: boolean) => void;
+    /** Declarative event name emitted on action via useEventBus */
+    actionEvent?: string;
+    /** Layout variant */
+    layout?: 'horizontal' | 'vertical' | 'diamond';
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+    /** Disabled state */
+    disabled?: boolean;
+}
+export declare function ActionButtons({ buttons, onAction, actionEvent, layout, size, className, disabled, }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ActionButtons {
+    var displayName: string;
+}