@almadar/ui 2.0.0 → 2.0.1

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

@@ -0,0 +1,39 @@
+/**
+ * Popover Molecule Component
+ *
+ * A popover component with position variants and click/hover triggers.
+ * Uses Button, Typography, and Icon atoms.
+ */
+import React from "react";
+export type PopoverPosition = "top" | "bottom" | "left" | "right";
+export type PopoverTrigger = "click" | "hover";
+export interface PopoverProps {
+    /**
+     * Popover content
+     */
+    content: React.ReactNode;
+    /**
+     * Popover trigger element (ReactElement or ReactNode that will be wrapped in span)
+     */
+    children: React.ReactNode;
+    /**
+     * Popover position
+     * @default 'bottom'
+     */
+    position?: PopoverPosition;
+    /**
+     * Trigger type
+     * @default 'click'
+     */
+    trigger?: PopoverTrigger;
+    /**
+     * Show arrow
+     * @default true
+     */
+    showArrow?: boolean;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+export declare const Popover: React.FC<PopoverProps>;

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/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/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/StatBadge.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+export interface StatBadgeProps {
+    /** Stat label */
+    label: string;
+    /** Current value (defaults to 0 if not provided) */
+    value?: number | string;
+    /** Maximum value (for bar/hearts format) */
+    max?: number;
+    /** Data source entity name (for schema config) */
+    source?: string;
+    /** Field name in the source (for schema config) */
+    field?: string;
+    /** Display format */
+    format?: 'number' | 'hearts' | 'bar' | 'text' | string;
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg' | string;
+    /** Visual variant */
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function StatBadge({ label, value, max, format, icon, size, variant, className, source: _source, field: _field, }: StatBadgeProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace StatBadge {
+    var displayName: string;
+}