@almadar/ui 5.79.1 → 5.80.0

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

@@ -0,0 +1,44 @@
+/**
+ * GridPicker Molecule Component
+ *
+ * Reusable emoji-picker-style chooser: a search box, a row of category filter
+ * chips, and a scrollable CSS-grid of fixed-size cells. Pure presentational —
+ * the host owns the item list and the selected value; the molecule just filters,
+ * highlights, and reports clicks via `onChange`.
+ */
+import React from 'react';
+/**
+ * Presentational item shape for a single grid cell. This is a UI-presentation
+ * type, intentionally local — it is NOT a domain/asset type from @almadar/core.
+ */
+export interface PickerItem {
+    /** Stable identity; emitted via `onChange`. */
+    id: string;
+    /** Human label — search term, cell title, and aria-label. */
+    label: string;
+    /** Category key used by the filter chips. */
+    category: string;
+}
+export type GridPickerCellSize = 16 | 32 | 48;
+export interface GridPickerProps {
+    /** Items to render as grid cells. */
+    items: PickerItem[];
+    /** Currently selected item id (controlled highlight). */
+    value?: string;
+    /** Fired with the clicked/selected item's id. */
+    onChange: (value: string) => void;
+    /**
+     * Category keys for the filter chip row. When omitted, the categories are
+     * derived from the items. An "All" chip is always prepended.
+     */
+    categories?: string[];
+    /** Placeholder for the search input. */
+    searchPlaceholder?: string;
+    /** Renders the visual content of a cell (e.g. an emoji glyph or an image). */
+    renderThumbnail: (item: PickerItem) => React.ReactNode;
+    /** Cell edge length in px. */
+    cellSize?: GridPickerCellSize;
+    /** Additional CSS classes applied to the root. */
+    className?: string;
+}
+export declare const GridPicker: React.FC<GridPickerProps>;

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

@@ -0,0 +1,113 @@
+/**
+ * Header Organism Component
+ *
+ * A header component for mobile/responsive layouts with menu toggle, brand, and user avatar.
+ * Styled to match the main Layout component's mobile header.
+ */
+import React from "react";
+import type { AssetUrl } from "@almadar/core";
+import type { IconInput } from "../atoms/index";
+import type { UiError } from '../atoms/types';
+export type HeaderLook = "hero" | "compact-bar" | "breadcrumb" | "contextual" | "editorial-banner";
+export interface HeaderNavigationItem {
+    label: string;
+    href?: string;
+    onClick?: () => void;
+    icon?: IconInput;
+    badge?: string | number;
+    active?: boolean;
+}
+export interface HeaderUserAvatar {
+    src?: AssetUrl;
+    alt?: string;
+    initials?: string;
+}
+export interface HeaderProps {
+    /**
+     * Logo/Brand content
+     */
+    logo?: React.ReactNode;
+    /**
+     * Logo image source
+     */
+    logoSrc?: AssetUrl;
+    /**
+     * Brand/App name
+     */
+    brandName?: string;
+    /**
+     * Navigation items (for desktop header variant)
+     */
+    navigationItems?: HeaderNavigationItem[];
+    /**
+     * Show menu toggle button
+     * @default true
+     */
+    showMenuToggle?: boolean;
+    /**
+     * Is menu open (for toggle icon)
+     */
+    isMenuOpen?: boolean;
+    /**
+     * Menu toggle callback
+     */
+    onMenuToggle?: () => void;
+    /**
+     * Show search input
+     * @default false
+     */
+    showSearch?: boolean;
+    /**
+     * Search placeholder
+     */
+    searchPlaceholder?: string;
+    /**
+     * Search callback
+     */
+    onSearch?: (value: string) => void;
+    /**
+     * User avatar configuration
+     */
+    userAvatar?: HeaderUserAvatar;
+    /**
+     * User name (display name or email)
+     */
+    userName?: string;
+    /**
+     * Callback when user avatar is clicked
+     */
+    onUserClick?: () => void;
+    /**
+     * Action buttons (right side)
+     */
+    actions?: React.ReactNode;
+    /**
+     * Sticky header
+     * @default true
+     */
+    sticky?: boolean;
+    /**
+     * Variant - mobile shows menu toggle, desktop shows full nav
+     * @default 'mobile'
+     */
+    variant?: "mobile" | "desktop";
+    /** Layer 2 visual treatment — orthogonal to the structural variant (which currently flips mobile vs desktop). */
+    look?: HeaderLook;
+    /**
+     * Callback when logo/brand is clicked
+     */
+    onLogoClick?: () => void;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Loading state indicator (closed circuit)
+     */
+    isLoading?: boolean;
+    /**
+     * Error state (closed circuit)
+     */
+    error?: UiError | null;
+}
+export declare const Header: React.FC<HeaderProps>;

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

@@ -0,0 +1,18 @@
+/**
+ * IconPicker Molecule Component
+ *
+ * Searchable grid of every lucide icon, built on `GridPicker`. The item set is
+ * enumerated once at module scope from the lucide-react exports and kebab-cased
+ * to match the canonical names `Icon` resolves, so each cell renders its real
+ * glyph via the family-aware `Icon` atom.
+ */
+import React from 'react';
+export interface IconPickerProps {
+    /** Currently selected icon name (kebab-case). */
+    value?: string;
+    /** Fired with the chosen icon's kebab-case name. */
+    onChange: (name: string) => void;
+    /** Additional CSS classes applied to the root. */
+    className?: string;
+}
+export declare const IconPicker: React.FC<IconPickerProps>;

package/dist/components/core/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/core/molecules/JazariStateMachine.d.ts

@@ -0,0 +1,34 @@
+/**
+ * JazariStateMachine — Al-Jazari themed state machine diagram.
+ *
+ * Thin wrapper around StateMachineView that:
+ * 1. Extracts a state machine from an orbital schema (or accepts a trait directly)
+ * 2. Converts it to DomLayoutData via the visualizer lib
+ * 3. Applies Al-Jazari brass/gold/lapis color theme
+ * 4. Renders gear-shaped state nodes via the renderStateNode prop
+ */
+import React from 'react';
+import type { OrbitalSchema, Trait as CoreTrait } from '@almadar/core';
+import type { UiError } from '../atoms/types';
+type SmTrait = CoreTrait;
+type SmSchema = OrbitalSchema;
+export interface JazariStateMachineProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+    /** Full schema — extracts first trait's state machine */
+    schema?: SmSchema;
+    /** Or pass a single trait directly */
+    trait?: SmTrait;
+    /** Which trait to visualize (default: 0) */
+    traitIndex?: number;
+    /** Override entity field labels */
+    entityFields?: string[];
+    /** Text direction (default: 'ltr') */
+    direction?: 'ltr' | 'rtl';
+}
+export declare const JazariStateMachine: React.FC<JazariStateMachineProps>;
+export {};

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

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { TraitConfigValue } from '@almadar/core';
+export interface JsonTreeEditorProps {
+    /** Current value (object / array / scalar). */
+    value: TraitConfigValue;
+    /** Fired with the next value on any edit. Unused in readonly mode. */
+    onChange: (next: TraitConfigValue) => void;
+    /** Additional CSS classes. */
+    className?: string;
+    /** Suppresses all edit controls — renders a read-only viewer. */
+    readonly?: boolean;
+}
+export declare const JsonTreeEditor: React.FC<JsonTreeEditorProps>;

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

@@ -0,0 +1,26 @@
+import React from "react";
+import type { AssetUrl } from "@almadar/core";
+export interface LightboxImage {
+    src?: AssetUrl;
+    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/core/molecules/LikertScale.d.ts

@@ -0,0 +1,34 @@
+import React from "react";
+import type { EventEmit } from "@almadar/core";
+export type LikertScaleSize = "sm" | "md" | "lg";
+export type LikertScaleVariant = "radios" | "buttons";
+export interface LikertOption {
+    /** Underlying value bound to the option */
+    value: number | string;
+    /** Visible label below (radios) or inside (buttons) the control */
+    label: string;
+}
+export interface LikertScaleProps {
+    /** Optional row prompt above the scale */
+    question?: string;
+    /** Scale points (defaults to a 5-point agree/disagree set) */
+    options?: LikertOption[];
+    /** Selected value (controlled) */
+    value?: number | string | null;
+    /** Change callback */
+    onChange?: (value: number | string) => void;
+    /** Event name dispatched via event bus on change. Payload: { value: number | string } */
+    changeEvent?: EventEmit<{
+        value: number | string;
+    }>;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Size variant */
+    size?: LikertScaleSize;
+    /** Visual variant: classic radios or pill segmented buttons */
+    variant?: LikertScaleVariant;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const DEFAULT_LIKERT_OPTIONS: LikertOption[];
+export declare const LikertScale: React.ForwardRefExoticComponent<LikertScaleProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/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/core/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/core/molecules/MapView.d.ts

@@ -0,0 +1,70 @@
+import type { EventEmit } from '@almadar/core';
+export type 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 MapRouteWaypoint {
+    lat: number;
+    lng: number;
+}
+export interface MapRouteData {
+    /** Unique route identifier */
+    id: string | number;
+    /** Ordered waypoints rendered as a polyline */
+    waypoints: MapRouteWaypoint[];
+    /** Stroke color (CSS color). Defaults to a theme-aware accent. */
+    color?: string;
+    /** Stroke weight in pixels (default 4) */
+    weight?: number;
+    /** Stroke opacity 0..1 (default 0.8) */
+    opacity?: number;
+    /** Optional dashed pattern (e.g. "8 4") */
+    dashArray?: string;
+    /** Label shown in a popup at the midpoint */
+    label?: string;
+}
+export interface MapViewProps {
+    /** Array of markers to display */
+    markers?: MapMarkerData[];
+    /** Routes (polylines with optional popups) drawn over the tile layer */
+    routes?: MapRouteData[];
+    /** 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?: EventEmit<{
+        latitude: number;
+        longitude: number;
+    }>;
+    /** Event name dispatched via event bus when a marker is clicked. Payload: full MapMarkerData spread. */
+    markerClickEvent?: EventEmit<MapMarkerData>;
+    /** Whether to show a pin at the clicked location */
+    showClickedPin?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Show attribution (default true) */
+    showAttribution?: boolean;
+}
+/**
+ * Server-safe wrapper. Renders an empty Box on the server (or until the
+ * lazy implementation finishes loading on the client) so SSR never reaches
+ * the leaflet code.
+ */
+export declare function MapView(props: MapViewProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,35 @@
+import React from "react";
+import type { EventEmit } from '@almadar/core';
+export interface MatrixRow {
+    id: string;
+    label: string;
+}
+export interface MatrixColumn {
+    value: number | string;
+    label: string;
+}
+export interface MatrixQuestionProps {
+    /** Optional title rendered above the matrix */
+    title?: string;
+    /** Question rows */
+    rows: MatrixRow[];
+    /** Column definitions; defaults to 5-point Likert */
+    columns?: MatrixColumn[];
+    /** Selected value per row, keyed by rowId */
+    values?: Record<string, number | string>;
+    /** Change handler invoked with rowId and selected column value */
+    onChange?: (rowId: string, value: number | string) => void;
+    /** Event name dispatched via event bus when a row's value changes. Payload: { rowId, value } */
+    changeEvent?: EventEmit<{
+        rowId: string;
+        value: number | string;
+    }>;
+    /** Disable all inputs */
+    disabled?: boolean;
+    /** Visual size */
+    size?: 'sm' | 'md';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const DEFAULT_MATRIX_COLUMNS: MatrixColumn[];
+export declare const MatrixQuestion: React.FC<MatrixQuestionProps>;

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

@@ -0,0 +1,44 @@
+/**
+ * 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 { IconInput } from "../atoms/index";
+export interface MenuItem {
+    /** Item ID (auto-generated from label if not provided) */
+    id?: string;
+    /** Item label */
+    label: string;
+    /** Item icon (Lucide icon name or component) */
+    icon?: IconInput;
+    /** 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;
+    /** Optional slot rendered above the items. */
+    header?: React.ReactNode;
+    /** Optional slot rendered below the items. */
+    footer?: React.ReactNode;
+}
+export declare const Menu: React.FC<MenuProps>;

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

@@ -0,0 +1,52 @@
+/**
+ * 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";
+import type { UiError } from '../atoms/types';
+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?: UiError | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Meter: React.FC<MeterProps>;

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

@@ -0,0 +1,36 @@
+/**
+ * Modal Molecule Component
+ *
+ * A modal dialog component with overlay, header, content, and footer.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from "react";
+import type { EventEmit } from "@almadar/core";
+export type ModalSize = "sm" | "md" | "lg" | "xl" | "full";
+/**
+ * Layer 2 visual treatment for the modal pattern — orthogonal to the semantic
+ * `size` (which conveys content scale).
+ */
+export type ModalLook = "centered-card" | "top-sheet" | "side-drawer" | "full-screen";
+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?: EventEmit<Record<string, never>>;
+    /** Enable swipe-down-to-close on mobile bottom sheet (default: true) */
+    swipeDownToClose?: boolean;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: ModalLook;
+}
+export declare const Modal: React.FC<ModalProps>;

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

@@ -0,0 +1,67 @@
+/**
+ * Navigation Organism Component
+ *
+ * A navigation component with items, active indicators, icons, and badges.
+ * Uses Menu, ButtonGroup molecules and Button, Icon, Badge, Typography, Divider atoms.
+ */
+import React from 'react';
+import type { IconInput } from '../atoms/index';
+import type { UiError } from '../atoms/types';
+export interface NavigationItem {
+    /**
+     * Item ID
+     */
+    id: string;
+    /**
+     * Item label
+     */
+    label: string;
+    /**
+     * Item icon
+     */
+    icon?: IconInput;
+    /**
+     * Item badge
+     */
+    badge?: string | number;
+    /**
+     * Item href
+     */
+    href?: string;
+    /**
+     * Item click handler
+     */
+    onClick?: () => void;
+    /**
+     * Is active
+     */
+    isActive?: boolean;
+    /**
+     * Disable item
+     */
+    disabled?: boolean;
+    /**
+     * Sub-menu items
+     */
+    subMenu?: NavigationItem[];
+}
+export interface NavigationProps {
+    /**
+     * Navigation items
+     */
+    items: NavigationItem[];
+    /**
+     * Navigation orientation
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+}
+export declare const Navigation: React.FC<NavigationProps>;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { TraitConfigValue } from '@almadar/core';
+export interface NodeSlotEditorProps {
+    /** Current node-slot value (a render-ui pattern config, or nothing). */
+    value: TraitConfigValue | undefined;
+    /** Fired with the next value. */
+    onChange: (next: TraitConfigValue) => void;
+    /** Additional CSS classes. */
+    className?: string;
+}
+/**
+ * NodeSlotEditor — edits a `node` config slot (e.g. `children`/`hud`/`debugPanel`).
+ * A node slot renders a nested render-ui pattern, so this picks the pattern TYPE
+ * from the known-pattern registry and edits that pattern's props as a tree — instead
+ * of the read-only "edit in source" fallback. Self-contained `@almadar/ui` atoms.
+ */
+export declare const NodeSlotEditor: React.FC<NodeSlotEditorProps>;