@almadar/ui 2.13.3 → 2.15.0

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

@@ -0,0 +1,55 @@
+import React from 'react';
+import type { ReactNode, ErrorInfo } from 'react';
+export interface ErrorBoundaryProps {
+    /** Content to render when no error */
+    children: ReactNode;
+    /** Fallback UI when an error is caught — ReactNode or render function */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Additional CSS classes for the wrapper */
+    className?: string;
+    /** Called when an error is caught (for logging/telemetry) */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * ErrorBoundary — catches React render errors in child components.
+ *
+ * Uses `getDerivedStateFromError` and `componentDidCatch` to capture errors
+ * and render a fallback UI. Supports both static ReactNode fallbacks and
+ * render-function fallbacks that receive the error and a reset function.
+ *
+ * @example
+ * ```tsx
+ * // Static fallback
+ * <ErrorBoundary fallback={<Alert variant="error">Something broke</Alert>}>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ *
+ * // Render function fallback with reset
+ * <ErrorBoundary fallback={(error, reset) => (
+ *   <VStack>
+ *     <Typography>Error: {error.message}</Typography>
+ *     <Button onClick={reset}>Try Again</Button>
+ *   </VStack>
+ * )}>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ *
+ * // Default fallback (uses ErrorState molecule)
+ * <ErrorBoundary>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    static displayName: string;
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    private reset;
+    render(): ReactNode;
+    private renderFallback;
+}
+export default ErrorBoundary;

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

@@ -0,0 +1,13 @@
+import React from "react";
+export interface ErrorStateProps {
+    title?: string;
+    /** Error message to display */
+    message?: string;
+    /** Alias for message (schema compatibility) */
+    description?: string;
+    onRetry?: () => void;
+    className?: string;
+    /** Declarative retry event — emits UI:{retryEvent} via eventBus when retry button is clicked */
+    retryEvent?: string;
+}
+export declare const ErrorState: React.FC<ErrorStateProps>;

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

@@ -0,0 +1,54 @@
+/**
+ * FilterGroup Molecule Component
+ *
+ * A component for filtering entity data. Composes atoms (Button, Select, Badge, HStack)
+ * and follows the design system using CSS variables.
+ *
+ * Implements the Closed Circuit principle:
+ * - FilterGroup updates QuerySingleton filters via query prop
+ * - FilterGroup emits UI:FILTER events for trait state machines
+ * - entity-list/entity-cards read filtered data via query prop
+ *
+ * Supports Query Singleton pattern via `query` prop for std/Filter behavior.
+ */
+import React from "react";
+/** Filter definition from schema */
+export interface FilterDefinition {
+    field: string;
+    label: string;
+    /** Filter type - 'date' renders a date picker, 'date-range'/'daterange' renders two date pickers */
+    filterType?: "select" | "toggle" | "checkbox" | "date" | "daterange" | "date-range";
+    /** Alias for filterType (schema compatibility) */
+    type?: "select" | "toggle" | "checkbox" | "date" | "daterange" | "date-range";
+    /** Options for select/toggle filters */
+    options?: readonly string[];
+}
+export interface FilterGroupProps {
+    /** Entity name to filter */
+    entity: string;
+    /** Filter definitions from schema */
+    filters: readonly FilterDefinition[];
+    /** Callback when a filter changes - for EntityStore integration */
+    onFilterChange?: (field: string, value: string | null) => void;
+    /** Callback to clear all filters */
+    onClearAll?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Variant style */
+    variant?: "default" | "compact" | "pills" | "vertical";
+    /** Show filter icon */
+    showIcon?: boolean;
+    /**
+     * Query singleton binding for state management.
+     * When provided, syncs filter state with the query singleton.
+     * Example: "@TaskQuery"
+     */
+    query?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+}
+/**
+ * FilterGroup - Renders filter controls for entity data
+ * Uses atoms: Button, Select, Badge, HStack
+ */
+export declare const FilterGroup: React.FC<FilterGroupProps>;

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

@@ -0,0 +1,43 @@
+/**
+ * Flex Component
+ *
+ * A flexbox wrapper with all common flex properties exposed as props.
+ * More explicit than Stack for when you need full flex control.
+ */
+import React from 'react';
+export type FlexDirection = 'row' | 'row-reverse' | 'col' | 'col-reverse';
+export type FlexWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
+export type FlexAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+export type FlexJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+export type FlexGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export interface FlexProps {
+    /** Flex direction */
+    direction?: FlexDirection;
+    /** Flex wrap */
+    wrap?: FlexWrap;
+    /** Align items */
+    align?: FlexAlign;
+    /** Justify content */
+    justify?: FlexJustify;
+    /** Gap between items */
+    gap?: FlexGap;
+    /** Inline flex */
+    inline?: boolean;
+    /** Flex grow */
+    grow?: boolean | number;
+    /** Flex shrink */
+    shrink?: boolean | number;
+    /** Flex basis */
+    basis?: string | number;
+    /** Custom class name */
+    className?: string;
+    /** Children elements */
+    children: React.ReactNode;
+    /** HTML element to render as */
+    as?: React.ElementType;
+}
+/**
+ * Flex - Full-featured flexbox container
+ */
+export declare const Flex: React.FC<FlexProps>;
+export default Flex;

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

@@ -0,0 +1,25 @@
+/**
+ * FlipCard - A two-sided card with 3D flip animation.
+ *
+ * Pure presentational molecule: no entity binding, no event bus, no translations.
+ * Uses the FlipContainer atom for the 3D transform mechanics.
+ */
+import React from 'react';
+export interface FlipCardProps {
+    /** Content rendered on the front face */
+    front: React.ReactNode;
+    /** Content rendered on the back face */
+    back: React.ReactNode;
+    /** Controlled flip state */
+    flipped?: boolean;
+    /** Callback when the card is clicked to flip */
+    onFlip?: () => void;
+    /** Optional className for the outer container */
+    className?: string;
+    /** Card height as a Tailwind class (default: 'h-64') */
+    height?: string;
+}
+export declare const FlipCard: {
+    ({ front, back, flipped, onFlip, className, height, }: FlipCardProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

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

@@ -0,0 +1,69 @@
+/**
+ * FloatingActionButton Molecule Component
+ *
+ * A floating action button that can expand into multiple actions vertically.
+ * Uses Button atom.
+ */
+import React from "react";
+import type { LucideIcon } from "lucide-react";
+export interface FloatingAction {
+    /**
+     * Action ID
+     */
+    id: string;
+    /**
+     * Action label
+     */
+    label: string;
+    /**
+     * Action icon
+     */
+    icon: LucideIcon;
+    /**
+     * Action click handler
+     */
+    onClick?: () => void;
+    /** Event name to emit when clicked (for trait state machine integration) */
+    event?: string;
+    /**
+     * Action variant
+     */
+    variant?: "primary" | "secondary" | "success" | "danger" | "warning";
+}
+export interface FloatingActionButtonProps {
+    /**
+     * Single action (if only one action, button will directly trigger onClick)
+     */
+    action?: {
+        icon: LucideIcon;
+        onClick: () => void;
+        label?: string;
+        variant?: "primary" | "secondary" | "success" | "danger" | "warning";
+    };
+    /**
+     * Multiple actions (if provided, button will expand to show all actions)
+     */
+    actions?: FloatingAction[];
+    /**
+     * Icon name (simplified API for pattern compatibility)
+     */
+    icon?: string;
+    /**
+     * Click handler (simplified API for pattern compatibility)
+     */
+    onClick?: () => void;
+    /**
+     * Variant (simplified API for pattern compatibility)
+     */
+    variant?: "primary" | "secondary" | "success" | "danger" | "warning";
+    /**
+     * Button position
+     * @default 'bottom-right'
+     */
+    position?: "bottom-right" | "bottom-left" | "bottom-center" | "top-right" | "top-left" | "top-center" | string;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+export declare const FloatingActionButton: React.FC<FloatingActionButtonProps>;

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

@@ -0,0 +1,16 @@
+/**
+ * FormField Molecule Component
+ *
+ * A form field wrapper with label, hint, and error message support.
+ * **Atomic Design**: Composed using Label and Typography atoms.
+ */
+import React from 'react';
+export interface FormFieldProps {
+    label: string;
+    required?: boolean;
+    error?: string;
+    hint?: string;
+    className?: string;
+    children: React.ReactNode;
+}
+export declare const FormField: React.FC<FormFieldProps>;

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

@@ -0,0 +1,30 @@
+/**
+ * FormSectionHeader
+ *
+ * Header component for collapsible form sections.
+ * Provides consistent styling and interaction for section headers.
+ */
+import React from "react";
+export interface FormSectionHeaderProps {
+    /** Section title */
+    title: string;
+    /** Section subtitle */
+    subtitle?: string;
+    /** Whether section is collapsed */
+    isCollapsed?: boolean;
+    /** Toggle collapse handler (makes header clickable) */
+    onToggle?: () => void;
+    /** Badge text (e.g., "3 fields", "Required", "Complete") */
+    badge?: string;
+    /** Badge variant */
+    badgeVariant?: "default" | "primary" | "success" | "warning" | "danger";
+    /** Icon name to show before title */
+    icon?: string;
+    /** Whether section has validation errors */
+    hasErrors?: boolean;
+    /** Whether section is complete */
+    isComplete?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const FormSectionHeader: React.FC<FormSectionHeaderProps>;

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

@@ -0,0 +1,45 @@
+/**
+ * GraphView Molecule Component
+ *
+ * Pure presentational force-directed graph visualization using SVG.
+ * Entity-less, no event bus, no translations. Accepts raw nodes and edges.
+ *
+ * Uses a simple force simulation (repulsion + attraction + centering)
+ * to lay out nodes, then renders via SVG circles and lines.
+ */
+import React from 'react';
+export interface GraphViewNode {
+    id: string;
+    label?: string;
+    color?: string;
+    size?: number;
+    group?: string;
+}
+export interface GraphViewEdge {
+    source: string;
+    target: string;
+    color?: string;
+    label?: string;
+}
+export interface GraphViewProps {
+    /** Graph nodes */
+    nodes: GraphViewNode[];
+    /** Graph edges */
+    edges: GraphViewEdge[];
+    /** Callback when a node is clicked */
+    onNodeClick?: (node: GraphViewNode) => void;
+    /** Callback when a node is hovered (null on leave) */
+    onNodeHover?: (node: GraphViewNode | null) => void;
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /** Additional CSS classes */
+    className?: string;
+    /** Show node labels (default true) */
+    showLabels?: boolean;
+    /** Auto zoom-to-fit after layout settles (default true) */
+    zoomToFit?: boolean;
+}
+export declare const GraphView: React.FC<GraphViewProps>;
+export default GraphView;

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

@@ -0,0 +1,54 @@
+/**
+ * Grid Component
+ *
+ * A CSS Grid wrapper with responsive column support.
+ * Useful for creating multi-column layouts.
+ */
+import React from 'react';
+export type GridCols = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 'none';
+export type GridGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type GridAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+export type GridJustify = 'start' | 'center' | 'end' | 'stretch';
+export interface ResponsiveGridCols {
+    /** Base/mobile columns */
+    base?: GridCols;
+    /** Small screens (640px+) */
+    sm?: GridCols;
+    /** Medium screens (768px+) */
+    md?: GridCols;
+    /** Large screens (1024px+) */
+    lg?: GridCols;
+    /** Extra large screens (1280px+) */
+    xl?: GridCols;
+}
+export interface GridProps {
+    /** Number of columns (can be responsive object) */
+    cols?: GridCols | ResponsiveGridCols;
+    /** Number of rows */
+    rows?: number;
+    /** Gap between items */
+    gap?: GridGap;
+    /** Row gap (overrides gap for rows) */
+    rowGap?: GridGap;
+    /** Column gap (overrides gap for columns) */
+    colGap?: GridGap;
+    /** Align items on block axis */
+    alignItems?: GridAlign;
+    /** Justify items on inline axis */
+    justifyItems?: GridJustify;
+    /** Auto-flow direction */
+    flow?: 'row' | 'col' | 'row-dense' | 'col-dense';
+    /** Custom class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** Children elements */
+    children: React.ReactNode;
+    /** HTML element to render as */
+    as?: React.ElementType;
+}
+/**
+ * Grid - CSS Grid layout wrapper
+ */
+export declare const Grid: React.FC<GridProps>;
+export default Grid;

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

@@ -0,0 +1,24 @@
+/**
+ * InputGroup Molecule Component
+ *
+ * A component for grouping input with addons (icons, buttons, text).
+ * Uses Input, Button, Icon, and Typography atoms.
+ */
+import React from "react";
+import type { LucideIcon } from "lucide-react";
+import { InputProps } from "../atoms/Input";
+export interface InputGroupProps extends Omit<InputProps, "icon" | "iconRight"> {
+    /**
+     * Left addon (icon, button, or text)
+     */
+    leftAddon?: React.ReactNode | LucideIcon;
+    /**
+     * Right addon (icon, button, or text)
+     */
+    rightAddon?: React.ReactNode | LucideIcon;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+export declare const InputGroup: React.FC<InputGroupProps>;

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

@@ -0,0 +1,25 @@
+import React from "react";
+export interface LightboxImage {
+    src: string;
+    alt?: string;
+    caption?: string;
+}
+export interface LightboxProps {
+    /** Array of images to display */
+    images: LightboxImage[];
+    /** Current image index */
+    currentIndex?: number;
+    /** Whether the lightbox is open */
+    isOpen?: boolean;
+    /** Show image counter (e.g., "3 of 12") */
+    showCounter?: boolean;
+    /** Declarative close event name */
+    closeAction?: string;
+    /** Direct onClose callback */
+    onClose?: () => void;
+    /** Direct onIndexChange callback */
+    onIndexChange?: (index: number) => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Lightbox: React.FC<LightboxProps>;

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

@@ -0,0 +1,33 @@
+/**
+ * LineChart Molecule Component
+ *
+ * SVG-based line/area chart for time-series data.
+ * Pure UI molecule with no entity binding.
+ */
+import React from 'react';
+export interface ChartDataPoint {
+    date: string | Date;
+    value: number;
+    label?: string;
+}
+export interface LineChartProps {
+    /** Data points to plot */
+    data: ChartDataPoint[];
+    /** SVG viewBox width */
+    width?: number;
+    /** SVG viewBox height */
+    height?: number;
+    /** Show horizontal grid lines at 25/50/75% */
+    showGrid?: boolean;
+    /** Show value labels near data points */
+    showValues?: boolean;
+    /** Fill area under line with gradient */
+    showArea?: boolean;
+    /** Line stroke color */
+    lineColor?: string;
+    /** Area fill color (used for gradient) */
+    areaColor?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const LineChart: React.FC<LineChartProps>;

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

@@ -0,0 +1,7 @@
+import React from "react";
+export interface LoadingStateProps {
+    title?: string;
+    message?: string;
+    className?: string;
+}
+export declare const LoadingState: React.FC<LoadingStateProps>;

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

@@ -0,0 +1,40 @@
+import 'leaflet/dist/leaflet.css';
+export interface MapMarkerData {
+    /** Unique marker identifier */
+    id: string | number;
+    /** Latitude */
+    lat: number;
+    /** Longitude */
+    lng: number;
+    /** Label shown in popup */
+    label?: string;
+    /** Optional category for styling */
+    category?: string;
+}
+export interface MapViewProps {
+    /** Array of markers to display */
+    markers?: MapMarkerData[];
+    /** Map center latitude */
+    centerLat?: number;
+    /** Map center longitude */
+    centerLng?: number;
+    /** Zoom level (1-18, default 13) */
+    zoom?: number;
+    /** Height of the map container (default "400px") */
+    height?: string;
+    /** Callback when a marker is clicked (programmatic use) */
+    onMarkerClick?: (marker: MapMarkerData) => void;
+    /** Callback when the map is clicked (programmatic use) */
+    onMapClick?: (lat: number, lng: number) => void;
+    /** Event name dispatched via event bus when the map is clicked. Payload: { latitude, longitude } */
+    mapClickEvent?: string;
+    /** Event name dispatched via event bus when a marker is clicked. Payload: marker data */
+    markerClickEvent?: string;
+    /** Whether to show a pin at the clicked location */
+    showClickedPin?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Show attribution (default true) */
+    showAttribution?: boolean;
+}
+export declare function MapView({ markers, centerLat, centerLng, zoom, height, onMarkerClick, onMapClick, mapClickEvent, markerClickEvent, showClickedPin, className, showAttribution, }: MapViewProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,40 @@
+/**
+ * Menu Molecule Component
+ *
+ * A dropdown menu component with items, icons, dividers, and sub-menus.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from "react";
+import type { LucideIcon } from "lucide-react";
+export interface MenuItem {
+    /** Item ID (auto-generated from label if not provided) */
+    id?: string;
+    /** Item label */
+    label: string;
+    /** Item icon (LucideIcon or string name) */
+    icon?: LucideIcon | string;
+    /** Item badge */
+    badge?: string | number;
+    /** Disable item */
+    disabled?: boolean;
+    /** Item click handler */
+    onClick?: () => void;
+    /** Event name for pattern compatibility */
+    event?: string;
+    /** Variant for styling (pattern compatibility) */
+    variant?: "default" | "danger";
+    /** Sub-menu items */
+    subMenu?: MenuItem[];
+}
+export type MenuPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-start" | "top-end" | "bottom-start" | "bottom-end";
+export interface MenuProps {
+    /** Menu trigger element */
+    trigger: React.ReactNode;
+    /** Menu items */
+    items: MenuItem[];
+    /** Menu position */
+    position?: MenuPosition;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Menu: React.FC<MenuProps>;

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

@@ -0,0 +1,51 @@
+/**
+ * Meter Molecule
+ *
+ * A gauge/meter component for displaying a value within a range.
+ * Supports linear, radial, and segmented display modes.
+ * Pure molecule: no entity prop, no data fetching.
+ */
+import React from "react";
+export type MeterVariant = "linear" | "radial" | "segmented";
+export interface MeterThreshold {
+    value: number;
+    color: string;
+    label?: string;
+}
+export interface MeterAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface MeterProps {
+    /** Current value */
+    value: number;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Display label */
+    label?: string;
+    /** Unit suffix (e.g., '%', 'MB', 'credits') */
+    unit?: string;
+    /** Display variant */
+    variant?: MeterVariant;
+    /** Color thresholds */
+    thresholds?: readonly MeterThreshold[];
+    /** Number of segments (for segmented variant) */
+    segments?: number;
+    /** Show value text */
+    showValue?: boolean;
+    /** Size (for radial variant) */
+    size?: "sm" | "md" | "lg";
+    /** Actions */
+    actions?: readonly MeterAction[];
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Meter: React.FC<MeterProps>;

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

@@ -0,0 +1,28 @@
+/**
+ * Modal Molecule Component
+ *
+ * A modal dialog component with overlay, header, content, and footer.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from "react";
+export type ModalSize = "sm" | "md" | "lg" | "xl" | "full";
+export interface ModalProps {
+    /** Whether the modal is open (defaults to true when rendered by slot wrapper) */
+    isOpen?: boolean;
+    /** Callback when modal should close (injected by slot wrapper) */
+    onClose?: () => void;
+    title?: string;
+    /** Modal content (can be empty if using slot content) */
+    children?: React.ReactNode;
+    footer?: React.ReactNode;
+    size?: ModalSize;
+    showCloseButton?: boolean;
+    closeOnOverlayClick?: boolean;
+    closeOnEscape?: boolean;
+    className?: string;
+    /** Declarative close event — emits UI:{closeEvent} via eventBus when modal should close */
+    closeEvent?: string;
+    /** Enable swipe-down-to-close on mobile bottom sheet (default: true) */
+    swipeDownToClose?: boolean;
+}
+export declare const Modal: React.FC<ModalProps>;