@almadar/ui 2.14.0 → 2.15.0

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

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