@almadar/ui 5.79.1 → 5.80.0

package/dist/components/core/molecules/EmptyState.d.ts

@@ -0,0 +1,29 @@
+import React from "react";
+import type { EventEmit } from "@almadar/core";
+import type { IconInput } from "../atoms/index";
+export type EmptyStateLook = "illustrated" | "icon-only" | "text-only" | "mascot";
+export interface EmptyStateProps {
+    /**
+     * Icon to display. Accepts either:
+     * - A Lucide icon component (LucideIcon)
+     * - A string icon name (e.g., "check-circle", "x-circle")
+     */
+    icon?: IconInput;
+    /** Primary text to display - use title or message (message is alias for backwards compat) */
+    title?: string;
+    /** Alias for title - used by schema patterns */
+    message?: string;
+    description?: string;
+    actionLabel?: string;
+    onAction?: () => void;
+    className?: string;
+    /** Destructive styling for confirmation dialogs */
+    destructive?: boolean;
+    /** Variant for color styling */
+    variant?: "default" | "success" | "error" | "warning" | "info";
+    /** Declarative action event — emits UI:{actionEvent} via eventBus when action button is clicked */
+    actionEvent?: EventEmit<Record<string, never>>;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant (which carries status color). */
+    look?: EmptyStateLook;
+}
+export declare const EmptyState: React.FC<EmptyStateProps>;

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

@@ -0,0 +1,54 @@
+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;
+}
+export default ErrorBoundary;

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

@@ -0,0 +1,14 @@
+import React from "react";
+import type { EventEmit } from "@almadar/core";
+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?: EventEmit<Record<string, never>>;
+}
+export declare const ErrorState: React.FC<ErrorStateProps>;

package/dist/components/core/molecules/FeatureGrid.d.ts

@@ -0,0 +1,19 @@
+/**
+ * FeatureGrid Molecule Component
+ *
+ * A responsive grid layout for displaying multiple FeatureCards.
+ * Composes SimpleGrid and FeatureCard molecules.
+ */
+import React from 'react';
+import { type FeatureCardProps } from '../../marketing/molecules/FeatureCard';
+export interface FeatureGridProps {
+    /** Array of feature card configurations */
+    items: FeatureCardProps[];
+    /** Number of grid columns */
+    columns?: 2 | 3 | 4 | 6;
+    /** Gap between grid items */
+    gap?: 'sm' | 'md' | 'lg';
+    /** Additional class names */
+    className?: string;
+}
+export declare const FeatureGrid: React.FC<FeatureGridProps>;

package/dist/components/core/molecules/FileTree.d.ts

@@ -0,0 +1,37 @@
+/**
+ * FileTree Molecule
+ *
+ * A filesystem tree navigator with folder expand/collapse, file-type icons,
+ * and click-to-select. Used by the Workspace tab to browse the agent's
+ * workspace directory.
+ *
+ * Follows atomic design: composes Box, Icon, Typography atoms.
+ */
+import React from 'react';
+export interface FileTreeNode {
+    /** File or directory name */
+    name: string;
+    /** Relative path from workspace root */
+    path: string;
+    /** 'file' or 'dir' */
+    type: 'file' | 'dir';
+    /** Children (only for directories) */
+    children?: FileTreeNode[];
+    /** File size in bytes (optional, for display) */
+    size?: number;
+    /** Detected language for syntax highlighting */
+    language?: string;
+}
+export interface FileTreeProps {
+    /** The tree data */
+    tree: FileTreeNode[];
+    /** Currently selected file path */
+    selectedPath?: string;
+    /** Called when a file is clicked */
+    onFileSelect?: (path: string) => void;
+    /** CSS class */
+    className?: string;
+    /** Indent size per level in px (default: 16) */
+    indent?: number;
+}
+export declare const FileTree: React.FC<FileTreeProps>;

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

@@ -0,0 +1,61 @@
+/**
+ * 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";
+/**
+ * Layer 2 visual treatment for the filter-group pattern — orthogonal to the
+ * semantic `variant` (which conveys layout / role).
+ */
+export type FilterGroupLook = "toolbar" | "chips" | "pills" | "popover-trigger" | "inline-column-header";
+/** Filter definition from schema */
+export interface FilterDefinition {
+    field: string;
+    label: string;
+    /** Filter type - 'text' free-text input, 'date' renders a date picker, 'date-range'/'daterange' renders two date pickers */
+    filterType?: "text" | "select" | "toggle" | "checkbox" | "date" | "daterange" | "date-range";
+    /** Alias for filterType (schema compatibility) */
+    type?: "text" | "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;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: FilterGroupLook;
+}
+/**
+ * FilterGroup - Renders filter controls for entity data
+ * Uses atoms: Button, Select, Badge, HStack
+ */
+export declare const FilterGroup: React.FC<FilterGroupProps>;

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

@@ -0,0 +1,43 @@
+/**
+ * Flex — full-surface flexbox primitive (distinct from Stack).
+ * Stack covers the 95% case (VStack/HStack with gap/align/justify).
+ * Flex exposes direction, wrap, grow, shrink, basis individually; use it
+ * when you need those extra axes or inline-flex behavior.
+ */
+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/core/molecules/FlipCard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * FlipCard — two-sided card molecule with front/back faces (distinct from FlipContainer).
+ * FlipContainer is the raw 3D-transform atom; FlipCard wraps it with card styling,
+ * absolute face positioning, and `front`/`back` ReactNode props for lolo consumers.
+ */
+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/core/molecules/FloatingActionButton.d.ts

@@ -0,0 +1,83 @@
+/**
+ * FloatingActionButton Molecule Component
+ *
+ * A floating action button that can expand into multiple actions vertically.
+ * Uses Button atom.
+ *
+ * Props mirror Button's `action`/`actionPayload` convention so a schema can
+ * declare `{ type: "floating-action-button", action: "INIT", icon: "plus" }`
+ * and have the FAB emit `UI:INIT` via the event bus on click — same shape
+ * any other clickable surface uses.
+ */
+import React from "react";
+import type { EventKey, EventPayload } from "@almadar/core";
+import type { IconInput } from "../atoms/index";
+export interface FloatingAction {
+    /**
+     * Action ID
+     */
+    id: string;
+    /**
+     * Action label
+     */
+    label: string;
+    /**
+     * Action icon — Lucide icon name or component
+     */
+    icon: IconInput;
+    /**
+     * 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 {
+    /**
+     * Declarative event name. When set, clicking the FAB emits `UI:{action}`
+     * via the event bus and (if also provided) calls `onClick`. Mirrors the
+     * Button atom's `action` prop so schemas can write
+     * `{ type: "floating-action-button", action: "INIT" }` uniformly.
+     */
+    action?: EventKey;
+    /**
+     * Payload to include with the dispatched action event.
+     */
+    actionPayload?: EventPayload;
+    /**
+     * Multiple actions. When provided, the button expands to show all of them.
+     */
+    actions?: FloatingAction[];
+    /**
+     * Icon: a canonical icon name string (resolved by Button) or a Lucide component.
+     */
+    icon?: IconInput;
+    /**
+     * Optional direct click handler. Runs after the action emit when both are
+     * present.
+     */
+    onClick?: () => void;
+    /**
+     * Visual variant.
+     */
+    variant?: "primary" | "secondary" | "success" | "danger" | "warning";
+    /**
+     * Optional label shown via `aria-label` (visually hidden in single-action
+     * mode; rendered as a tooltip beside expanded actions in multi-action mode).
+     */
+    label?: string;
+    /**
+     * 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/core/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/core/molecules/FormSection.d.ts

@@ -0,0 +1,39 @@
+import React from "react";
+import type { DisplayStateProps } from "../organisms/types";
+export interface FormSectionProps extends DisplayStateProps {
+    /** Section title */
+    title?: string;
+    /** Section description */
+    description?: string;
+    /** Form fields */
+    children: React.ReactNode;
+    /** Collapsible */
+    collapsible?: boolean;
+    /** Default collapsed state */
+    defaultCollapsed?: boolean;
+    /** Use card wrapper */
+    card?: boolean;
+    /** Grid columns for fields */
+    columns?: 1 | 2 | 3;
+}
+export declare const FormSection: React.FC<FormSectionProps>;
+/**
+ * Form layout with multiple sections
+ */
+export interface FormLayoutProps extends DisplayStateProps {
+    children: React.ReactNode;
+    /** Show section dividers */
+    dividers?: boolean;
+}
+export declare const FormLayout: React.FC<FormLayoutProps>;
+/**
+ * Form actions bar (submit/cancel buttons)
+ */
+export interface FormActionsProps extends DisplayStateProps {
+    children: React.ReactNode;
+    /** Sticky at bottom */
+    sticky?: boolean;
+    /** Alignment */
+    align?: "left" | "right" | "between" | "center";
+}
+export declare const FormActions: React.FC<FormActionsProps>;

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

@@ -0,0 +1,31 @@
+/**
+ * FormSectionHeader
+ *
+ * Header component for collapsible form sections.
+ * Provides consistent styling and interaction for section headers.
+ */
+import React from "react";
+import type { IconInput } from "../atoms/index";
+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";
+    /** Lucide icon name or component to show before title */
+    icon?: IconInput;
+    /** 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/core/molecules/GradientDivider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GradientDivider Molecule Component
+ *
+ * A horizontal line that fades from transparent at edges to primary color at center.
+ * Used between major sections for visual separation without hard background-color breaks.
+ */
+import React from 'react';
+import type { ColorToken } from '../atoms/types';
+export interface GradientDividerProps {
+    /** Semantic palette token or a raw CSS color value. Defaults to 'primary'. */
+    color?: ColorToken | string;
+    /** Additional class names */
+    className?: string;
+}
+export declare const GradientDivider: React.FC<GradientDividerProps>;

package/dist/components/core/molecules/GraphCanvas.d.ts

@@ -0,0 +1,83 @@
+/**
+ * GraphCanvas Organism Component
+ *
+ * A force-directed graph visualization component for node-link data.
+ * Uses canvas (necessary for performant graph rendering) with atom wrappers.
+ *
+ * Orbital Component Interface Compliance:
+ * - Entity binding with auto-fetch when entity is a string
+ * - Event emission via useEventBus (UI:* events)
+ * - isLoading and error state props
+ * - className for external styling
+ */
+import React from "react";
+import type { EventEmit, EventPayload } from "@almadar/core";
+import type { UiError } from '../atoms/types';
+export type GraphNode = EventPayload & {
+    id: string;
+    label?: string;
+    group?: string;
+    color?: string;
+    size?: number;
+    /** Position (optional, computed if missing) */
+    x?: number;
+    y?: number;
+};
+export interface GraphEdge {
+    source: string;
+    target: string;
+    label?: string;
+    weight?: number;
+    color?: string;
+}
+export interface GraphAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface GraphCanvasProps {
+    /** Graph title */
+    title?: string;
+    /** Graph nodes */
+    nodes?: readonly GraphNode[];
+    /** Graph edges */
+    edges?: readonly GraphEdge[];
+    /** Canvas height */
+    height?: number;
+    /** Show node labels */
+    showLabels?: boolean;
+    /** Enable zoom/pan */
+    interactive?: boolean;
+    /** Enable node dragging */
+    draggable?: boolean;
+    /** Actions */
+    actions?: readonly GraphAction[];
+    /** On node click */
+    onNodeClick?: (node: GraphNode) => void;
+    /** On node double-click (e.g. to drill in) */
+    onNodeDoubleClick?: (node: GraphNode) => void;
+    /** Node click event */
+    nodeClickEvent?: EventEmit<{
+        id: string;
+    }>;
+    /** Currently selected node id (rendered emphasized) */
+    selectedNodeId?: string;
+    /** Force-sim repulsion strength between nodes (larger ⇒ more spread out) */
+    repulsion?: number;
+    /** Force-sim target edge length (larger ⇒ more spread out) */
+    linkDistance?: number;
+    /** Minimum empty gap (px) enforced between node edges so nodes never overlap. */
+    nodeSpacing?: number;
+    /** Base opacity for links when nothing is hovered (kept faint so dense graphs stay readable; incident links brighten on hover). */
+    linkOpacity?: number;
+    /** Layout algorithm */
+    layout?: "force" | "circular" | "grid";
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const GraphCanvas: React.FC<GraphCanvasProps>;

package/dist/components/core/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 type 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/core/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;