@almadar/ui 2.14.0 → 2.15.1

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

@@ -0,0 +1,24 @@
+/**
+ * ProgressDots Molecule Component
+ *
+ * Step indicator dots for multi-step flows.
+ * Pure UI molecule with no entity binding.
+ */
+import React from 'react';
+export type DotState = 'active' | 'complete' | 'pending';
+export type DotSize = 'sm' | 'md' | 'lg';
+export interface ProgressDotsProps {
+    /** Total number of dots */
+    count: number;
+    /** Current active index (0-based) */
+    currentIndex: number;
+    /** Custom state resolver per dot index */
+    getState?: (index: number) => DotState;
+    /** Callback when a dot is clicked */
+    onDotClick?: (index: number) => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Dot size */
+    size?: DotSize;
+}
+export declare const ProgressDots: React.FC<ProgressDotsProps>;

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

@@ -0,0 +1,21 @@
+/**
+ * PullToRefresh Molecule Component
+ *
+ * Wrapper that adds pull-to-refresh gesture to children.
+ * Shows a spinner indicator as the user pulls down, and emits
+ * a refresh event via the event bus when the threshold is met.
+ */
+import React from 'react';
+export interface PullToRefreshProps {
+    /** Event name to emit on refresh (emitted as UI:{refreshEvent}) */
+    refreshEvent: string;
+    /** Payload to include with the refresh event */
+    refreshPayload?: Record<string, unknown>;
+    /** Pull distance threshold to trigger refresh in px (default: 60) */
+    threshold?: number;
+    /** Content to wrap */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const PullToRefresh: React.FC<PullToRefreshProps>;

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

@@ -0,0 +1,20 @@
+/**
+ * QuizBlock Molecule Component
+ *
+ * A collapsible Q&A block for embedded quiz questions in content.
+ * Shows the question with a reveal button for the answer.
+ *
+ * Event Contract:
+ * - No events emitted (self-contained interaction)
+ * - entityAware: false
+ */
+import React from 'react';
+export interface QuizBlockProps {
+    /** The quiz question */
+    question: string;
+    /** The quiz answer (revealed on toggle) */
+    answer: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const QuizBlock: React.FC<QuizBlockProps>;

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

@@ -0,0 +1,48 @@
+/**
+ * RelationSelect Molecule Component
+ *
+ * A searchable select component for relation fields.
+ * Allows users to search and select from related entities.
+ *
+ * Composed from: Box, HStack, VStack, Input, Button, Spinner, Typography atoms
+ */
+import React from "react";
+export interface RelationOption {
+    /** The value to store (typically the ID) */
+    value: string;
+    /** The display label */
+    label: string;
+    /** Optional description */
+    description?: string;
+    /** Whether this option is disabled */
+    disabled?: boolean;
+}
+export interface RelationSelectProps {
+    /** Current value (ID) */
+    value?: string;
+    /** Callback when value changes */
+    onChange?: (value: string | undefined) => void;
+    /** Available options - accepts readonly for compatibility with generated const arrays */
+    options: readonly RelationOption[];
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Whether the field is disabled */
+    disabled?: boolean;
+    /** Whether data is loading */
+    isLoading?: boolean;
+    /** Error message */
+    error?: string;
+    /** Allow clearing the selection */
+    clearable?: boolean;
+    /** Name attribute for forms */
+    name?: string;
+    /** Additional CSS classes */
+    className?: string;
+    /** Search placeholder */
+    searchPlaceholder?: string;
+    /** Empty state message */
+    emptyMessage?: string;
+}
+export declare const RelationSelect: React.FC<RelationSelectProps>;

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