@almadar/ui 2.14.0 → 2.15.1

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

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

@@ -0,0 +1,27 @@
+import React from "react";
+export type NumberStepperSize = "sm" | "md" | "lg";
+export interface NumberStepperProps {
+    /** Current value */
+    value?: number;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Step increment */
+    step?: number;
+    /** Size variant */
+    size?: NumberStepperSize;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Direct onChange callback */
+    onChange?: (value: number) => void;
+    /** Declarative event name for value changes */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** Additional CSS classes */
+    className?: string;
+    /** Accessible label */
+    label?: string;
+}
+export declare const NumberStepper: React.FC<NumberStepperProps>;

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

@@ -0,0 +1,66 @@
+/**
+ * Pagination Molecule Component
+ *
+ * A pagination component with page numbers, previous/next buttons, and ellipsis.
+ * Uses Button, Icon, Typography, and Input atoms.
+ */
+import React from "react";
+export interface PaginationProps {
+    /**
+     * Current page (1-indexed)
+     */
+    currentPage: number;
+    /**
+     * Total number of pages
+     */
+    totalPages: number;
+    /**
+     * Callback when page changes (optional - can be a no-op if not interactive)
+     */
+    onPageChange?: (page: number) => void;
+    /**
+     * Show page size selector
+     * @default false
+     */
+    showPageSize?: boolean;
+    /**
+     * Page size options
+     */
+    pageSizeOptions?: number[];
+    /**
+     * Current page size
+     */
+    pageSize?: number;
+    /**
+     * Callback when page size changes
+     */
+    onPageSizeChange?: (size: number) => void;
+    /**
+     * Show jump to page input
+     * @default false
+     */
+    showJumpToPage?: boolean;
+    /**
+     * Show total count
+     * @default false
+     */
+    showTotal?: boolean;
+    /**
+     * Total items count
+     */
+    totalItems?: number;
+    /**
+     * Maximum number of page buttons to show
+     * @default 7
+     */
+    maxVisiblePages?: number;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /** Declarative page change event — emits UI:{pageChangeEvent} with { page } */
+    pageChangeEvent?: string;
+    /** Declarative page size change event — emits UI:{pageSizeChangeEvent} with { pageSize } */
+    pageSizeChangeEvent?: string;
+}
+export declare const Pagination: React.FC<PaginationProps>;

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