@almadar/ui 2.13.3 → 2.15.0

package/dist/components/organisms/CardGrid.d.ts

@@ -0,0 +1,80 @@
+/**
+ * CardGrid Component
+ *
+ * A dumb, responsive grid specifically designed for card layouts.
+ * Uses CSS Grid auto-fit for automatic responsive columns.
+ *
+ * Data comes exclusively from the `entity` prop (injected by the runtime).
+ * All user interactions emit events via useEventBus. Never manages internal state
+ * for pagination, filtering, or search. All state is owned by the trait state machine.
+ */
+import React from 'react';
+import type { EntityDisplayProps } from './types';
+export type CardGridGap = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Action configuration for card items (schema-driven)
+ */
+export interface CardItemAction {
+    /** Action button label */
+    label: string;
+    /** Event to dispatch on click (schema metadata) */
+    event?: string;
+    /** Navigation URL - supports template interpolation like "/products/{{row.id}}" */
+    navigatesTo?: string;
+    /** Callback on click */
+    onClick?: (item: unknown) => void;
+    /** Action used by generated code - alternative to event */
+    action?: string;
+    /** Action placement - accepts string for compatibility with generated code */
+    placement?: 'card' | 'footer' | 'row' | string;
+    /** Button variant - accepts string for compatibility with generated code */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | string;
+}
+/**
+ * Field definition - can be a simple string or object with key/header or name/label
+ */
+export type FieldDef = string | {
+    key?: string;
+    header?: string;
+    name?: string;
+    label?: string;
+};
+export interface CardGridProps extends EntityDisplayProps {
+    /** Minimum width of each card (default: 280px) */
+    minCardWidth?: number;
+    /** Maximum number of columns */
+    maxCols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Gap between cards */
+    gap?: CardGridGap;
+    /** Align cards vertically in their cells */
+    alignItems?: 'start' | 'center' | 'end' | 'stretch';
+    /** Children elements (cards) - optional when using entity prop */
+    children?: React.ReactNode;
+    /** Fields to display - required for schema-driven rendering */
+    fields: readonly FieldDef[];
+    /** Alias for fields - backwards compatibility */
+    fieldNames?: readonly string[];
+    /** Alias for fields - backwards compatibility */
+    columns?: readonly FieldDef[];
+    /** Actions for each card item (schema-driven) */
+    itemActions?: readonly CardItemAction[];
+    /** Show total count in pagination */
+    showTotal?: boolean;
+    /** Show avatar/image field on cards */
+    showAvatar?: boolean;
+    /** Visual variant for the card grid */
+    variant?: string;
+    /** Entity field name containing an image URL to display as card thumbnail */
+    imageField?: string;
+}
+/**
+ * CardGrid - Responsive card collection layout
+ *
+ * Can be used in two ways:
+ * 1. With children: <CardGrid><Card>...</Card></CardGrid>
+ * 2. With entity data: <CardGrid entity={tasks} fields={['title', 'status']} />
+ *
+ * All data comes from the `entity` prop. Pagination display hints come from
+ * `page`, `pageSize`, and `totalCount` props (set by the trait via render-ui).
+ */
+export declare const CardGrid: React.FC<CardGridProps>;

package/dist/components/organisms/Chart.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Chart Organism Component
+ *
+ * A data visualization component supporting bar, line, pie, and area chart types.
+ * Composes atoms and molecules for layout, uses CSS variables for theming.
+ *
+ * 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";
+export type ChartType = "bar" | "line" | "pie" | "area" | "donut";
+export interface ChartDataPoint {
+    label: string;
+    value: number;
+    color?: string;
+}
+export interface ChartSeries {
+    name: string;
+    data: readonly ChartDataPoint[];
+    color?: string;
+}
+export interface ChartAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface ChartProps {
+    /** Chart title */
+    title?: string;
+    /** Chart subtitle / description */
+    subtitle?: string;
+    /** Chart type */
+    chartType?: ChartType;
+    /** Data series */
+    series?: readonly ChartSeries[];
+    /** Simple data (single series shorthand) */
+    data?: readonly ChartDataPoint[];
+    /** Chart height in px */
+    height?: number;
+    /** Show legend */
+    showLegend?: boolean;
+    /** Show values on chart */
+    showValues?: boolean;
+    /** Actions for chart interactions */
+    actions?: readonly ChartAction[];
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Chart: React.FC<ChartProps>;

package/dist/components/organisms/CodeViewer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * CodeViewer Organism Component
+ *
+ * A code/diff viewer with syntax highlighting and line numbers.
+ * Composes atoms and molecules for layout. Uses pre/code elements
+ * which are semantically necessary for code display.
+ *
+ * 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";
+export type CodeViewerMode = "code" | "diff";
+export interface DiffLine {
+    type: "add" | "remove" | "context";
+    content: string;
+    lineNumber?: number;
+}
+export interface CodeViewerAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface CodeViewerProps {
+    /** Viewer title */
+    title?: string;
+    /** Code content */
+    code?: string;
+    /** Language for display label */
+    language?: string;
+    /** Diff lines (for diff mode) */
+    diff?: readonly DiffLine[];
+    /** Old value (for generating diff) */
+    oldValue?: string;
+    /** New value (for generating diff) */
+    newValue?: string;
+    /** Display mode */
+    mode?: CodeViewerMode;
+    /** Show line numbers */
+    showLineNumbers?: boolean;
+    /** Show copy button */
+    showCopy?: boolean;
+    /** Enable word wrap */
+    wordWrap?: boolean;
+    /** Max height before scrolling */
+    maxHeight?: number | string;
+    /** Multiple files (tabbed view) */
+    files?: readonly {
+        label: string;
+        code: string;
+        language?: string;
+    }[];
+    /** Actions */
+    actions?: readonly CodeViewerAction[];
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const CodeViewer: React.FC<CodeViewerProps>;

package/dist/components/organisms/ComponentPatterns.d.ts

@@ -0,0 +1,453 @@
+/**
+ * Component Pattern Wrappers
+ *
+ * Pattern wrappers for atomic UI components that can be rendered via render_ui.
+ * These bridge the shell's atomic components with the pattern system.
+ *
+ * Interactive components emit events via useEventBus for the closed circuit pattern.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type ButtonVariant, type ButtonSize } from '../atoms/Button';
+import { type BadgeVariant } from '../atoms/Badge';
+import { type AlertVariant } from '../molecules/Alert';
+import { type MapViewProps } from '../molecules/MapView';
+/**
+ * Base closed circuit props required by all organism components.
+ */
+interface ClosedCircuitProps {
+    className?: string;
+    isLoading?: boolean;
+    error?: Error | null;
+    entity?: string;
+}
+export interface ButtonPatternProps extends ClosedCircuitProps {
+    label: string;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    disabled?: boolean;
+    onClick?: string;
+    event?: string;
+    icon?: string;
+    iconPosition?: 'left' | 'right';
+    className?: string;
+}
+/**
+ * Button pattern that emits events via the event bus.
+ */
+export declare function ButtonPattern({ label, variant, size, disabled, onClick, event, icon, iconPosition, className, }: ButtonPatternProps): React.ReactElement;
+export declare namespace ButtonPattern {
+    var displayName: string;
+}
+export interface IconButtonPatternProps extends ClosedCircuitProps {
+    icon: string;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    onClick?: string;
+    ariaLabel?: string;
+    className?: string;
+}
+/**
+ * Icon-only button pattern.
+ */
+export declare function IconButtonPattern({ icon, variant, size, onClick, ariaLabel, className, }: IconButtonPatternProps): React.ReactElement;
+export declare namespace IconButtonPattern {
+    var displayName: string;
+}
+export interface LinkPatternProps extends ClosedCircuitProps {
+    label: string;
+    href?: string;
+    external?: boolean;
+    onClick?: string;
+    className?: string;
+}
+/**
+ * Link pattern for navigation.
+ */
+export declare function LinkPattern({ label, href, external, onClick, className, }: LinkPatternProps): React.ReactElement;
+export declare namespace LinkPattern {
+    var displayName: string;
+}
+export interface TextPatternProps extends ClosedCircuitProps {
+    content: string;
+    variant?: 'body' | 'caption' | 'overline';
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    weight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+    className?: string;
+}
+/**
+ * Text pattern for typography.
+ */
+export declare function TextPattern({ content, variant, size, weight, color, align, className, }: TextPatternProps): React.ReactElement;
+export declare namespace TextPattern {
+    var displayName: string;
+}
+export interface HeadingPatternProps extends ClosedCircuitProps {
+    content: string;
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+    className?: string;
+}
+/**
+ * Heading pattern.
+ */
+export declare function HeadingPattern({ content, level, size, className, }: HeadingPatternProps): React.ReactElement;
+export declare namespace HeadingPattern {
+    var displayName: string;
+}
+export interface BadgePatternProps extends ClosedCircuitProps {
+    label: string;
+    variant?: BadgeVariant;
+    size?: 'sm' | 'md';
+    className?: string;
+}
+/**
+ * Badge pattern for status/counts.
+ */
+export declare function BadgePattern({ label, variant, size, className, }: BadgePatternProps): React.ReactElement;
+export declare namespace BadgePattern {
+    var displayName: string;
+}
+export interface AvatarPatternProps extends ClosedCircuitProps {
+    src?: string;
+    alt?: string;
+    name?: string;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    className?: string;
+}
+/**
+ * Avatar pattern.
+ */
+export declare function AvatarPattern({ src, alt, name, size, className, }: AvatarPatternProps): React.ReactElement;
+export declare namespace AvatarPattern {
+    var displayName: string;
+}
+export interface IconPatternProps extends ClosedCircuitProps {
+    name: string;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    color?: string;
+    className?: string;
+}
+/**
+ * Icon pattern.
+ */
+export declare function IconPattern({ name, size, color, className, }: IconPatternProps): React.ReactElement;
+export declare namespace IconPattern {
+    var displayName: string;
+}
+export interface ImagePatternProps extends ClosedCircuitProps {
+    src: string;
+    alt: string;
+    width?: number | string;
+    height?: number | string;
+    objectFit?: 'cover' | 'contain' | 'fill';
+    fallback?: string;
+    className?: string;
+}
+/**
+ * Image pattern.
+ */
+export declare function ImagePattern({ src, alt, width, height, objectFit, className, }: ImagePatternProps): React.ReactElement;
+export declare namespace ImagePattern {
+    var displayName: string;
+}
+export interface CardPatternProps extends ClosedCircuitProps {
+    title?: string;
+    subtitle?: string;
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+    shadow?: 'none' | 'sm' | 'md' | 'lg';
+    onClick?: string;
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Card pattern.
+ */
+export declare function CardPattern({ title, subtitle, padding, shadow, onClick, className, children, }: CardPatternProps): React.ReactElement;
+export declare namespace CardPattern {
+    var displayName: string;
+}
+export interface ProgressBarPatternProps extends ClosedCircuitProps {
+    value: number;
+    max?: number;
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger';
+    size?: 'sm' | 'md' | 'lg';
+    showLabel?: boolean;
+    className?: string;
+}
+/**
+ * Progress bar pattern.
+ */
+export declare function ProgressBarPattern({ value, max, variant, size, showLabel, className, }: ProgressBarPatternProps): React.ReactElement;
+export declare namespace ProgressBarPattern {
+    var displayName: string;
+}
+export interface SpinnerPatternProps extends ClosedCircuitProps {
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+    color?: string;
+    className?: string;
+}
+/**
+ * Spinner pattern.
+ */
+export declare function SpinnerPattern({ size, className, }: SpinnerPatternProps): React.ReactElement;
+export declare namespace SpinnerPattern {
+    var displayName: string;
+}
+export interface InputPatternProps extends ClosedCircuitProps {
+    value?: string;
+    placeholder?: string;
+    inputType?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
+    disabled?: boolean;
+    /** Field-level validation error message */
+    fieldError?: string;
+    onChange?: string;
+    onBlur?: string;
+    className?: string;
+}
+/**
+ * Input pattern.
+ */
+export declare function InputPattern({ value, placeholder, inputType, disabled, fieldError, onChange, onBlur, className, }: InputPatternProps): React.ReactElement;
+export declare namespace InputPattern {
+    var displayName: string;
+}
+export interface TextareaPatternProps extends ClosedCircuitProps {
+    value?: string;
+    placeholder?: string;
+    rows?: number;
+    disabled?: boolean;
+    /** Field-level validation error message */
+    fieldError?: string;
+    onChange?: string;
+    className?: string;
+}
+/**
+ * Textarea pattern.
+ */
+export declare function TextareaPattern({ value, placeholder, rows, disabled, fieldError, onChange, className, }: TextareaPatternProps): React.ReactElement;
+export declare namespace TextareaPattern {
+    var displayName: string;
+}
+export interface SelectPatternProps extends ClosedCircuitProps {
+    value?: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Field-level validation error message */
+    fieldError?: string;
+    onChange?: string;
+    className?: string;
+}
+/**
+ * Select pattern.
+ */
+export declare function SelectPattern({ value, options, placeholder, disabled, fieldError, onChange, className, }: SelectPatternProps): React.ReactElement;
+export declare namespace SelectPattern {
+    var displayName: string;
+}
+export interface CheckboxPatternProps extends ClosedCircuitProps {
+    checked?: boolean;
+    label?: string;
+    disabled?: boolean;
+    onChange?: string;
+    className?: string;
+}
+/**
+ * Checkbox pattern.
+ */
+export declare function CheckboxPattern({ checked, label, disabled, onChange, className, }: CheckboxPatternProps): React.ReactElement;
+export declare namespace CheckboxPattern {
+    var displayName: string;
+}
+export interface RadioPatternProps extends ClosedCircuitProps {
+    value: string;
+    checked?: boolean;
+    name?: string;
+    label?: string;
+    disabled?: boolean;
+    onChange?: string;
+    className?: string;
+}
+/**
+ * Radio pattern.
+ */
+export declare function RadioPattern({ value, checked, name, label, disabled, onChange, className, }: RadioPatternProps): React.ReactElement;
+export declare namespace RadioPattern {
+    var displayName: string;
+}
+export interface LabelPatternProps extends ClosedCircuitProps {
+    text: string;
+    htmlFor?: string;
+    required?: boolean;
+    className?: string;
+}
+/**
+ * Label pattern.
+ */
+export declare function LabelPattern({ text, htmlFor, required, className, }: LabelPatternProps): React.ReactElement;
+export declare namespace LabelPattern {
+    var displayName: string;
+}
+export interface AlertPatternProps extends ClosedCircuitProps {
+    message: string;
+    title?: string;
+    variant?: AlertVariant;
+    dismissible?: boolean;
+    onDismiss?: string;
+    className?: string;
+}
+/**
+ * Alert pattern.
+ */
+export declare function AlertPattern({ message, title, variant, dismissible, onDismiss, className, }: AlertPatternProps): React.ReactElement;
+export declare namespace AlertPattern {
+    var displayName: string;
+}
+export interface TooltipPatternProps extends ClosedCircuitProps {
+    content: string;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Tooltip pattern.
+ */
+export declare function TooltipPattern({ content, position, className, children, }: TooltipPatternProps): React.ReactElement;
+export declare namespace TooltipPattern {
+    var displayName: string;
+}
+export interface PopoverPatternProps extends ClosedCircuitProps {
+    content: React.ReactNode;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    trigger?: 'click' | 'hover';
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Popover pattern.
+ */
+export declare function PopoverPattern({ content, position, trigger, className, children, }: PopoverPatternProps): React.ReactElement;
+export declare namespace PopoverPattern {
+    var displayName: string;
+}
+export interface MenuPatternProps extends ClosedCircuitProps {
+    items: Array<{
+        label: string;
+        event: string;
+        icon?: string;
+        disabled?: boolean;
+        variant?: 'default' | 'danger';
+    }>;
+    trigger?: React.ReactNode;
+    position?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+    className?: string;
+}
+/**
+ * Menu pattern.
+ */
+export declare function MenuPattern({ items, trigger, position, className, }: MenuPatternProps): React.ReactElement;
+export declare namespace MenuPattern {
+    var displayName: string;
+}
+export interface AccordionPatternProps extends ClosedCircuitProps {
+    items: Array<{
+        title: string;
+        content: React.ReactNode;
+    }>;
+    multiple?: boolean;
+    defaultOpen?: number[];
+    className?: string;
+}
+/**
+ * Accordion pattern.
+ */
+export declare function AccordionPattern({ items, multiple, defaultOpen, className, }: AccordionPatternProps): React.ReactElement;
+export declare namespace AccordionPattern {
+    var displayName: string;
+}
+export interface ContainerPatternProps extends ClosedCircuitProps {
+    maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Container pattern.
+ */
+export declare function ContainerPattern({ maxWidth, padding, className, children, }: ContainerPatternProps): React.ReactElement;
+export declare namespace ContainerPattern {
+    var displayName: string;
+}
+export interface SimpleGridPatternProps extends ClosedCircuitProps {
+    minChildWidth?: string;
+    gap?: 'xs' | 'sm' | 'md' | 'lg';
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Simple grid pattern.
+ */
+export declare function SimpleGridPattern({ minChildWidth, gap, className, children, }: SimpleGridPatternProps): React.ReactElement;
+export declare namespace SimpleGridPattern {
+    var displayName: string;
+}
+export interface FloatButtonPatternProps extends ClosedCircuitProps {
+    icon: string;
+    onClick?: string;
+    position?: 'bottom-right' | 'bottom-left' | 'bottom-center';
+    variant?: 'primary' | 'secondary';
+    className?: string;
+}
+/**
+ * Floating action button pattern.
+ */
+export declare function FloatButtonPattern({ icon, onClick, position, variant, className, }: FloatButtonPatternProps): React.ReactElement;
+export declare namespace FloatButtonPattern {
+    var displayName: string;
+}
+export type MapViewPatternProps = Omit<MapViewProps, 'onMapClick' | 'onMarkerClick'> & ClosedCircuitProps;
+/**
+ * Map view pattern. Passes through all MapView props.
+ * Event dispatch is handled internally by MapView via mapClickEvent/markerClickEvent.
+ */
+export declare function MapViewPattern({ markers, centerLat, centerLng, zoom, height, mapClickEvent, markerClickEvent, showClickedPin, className, showAttribution, }: MapViewPatternProps): React.ReactElement;
+export declare namespace MapViewPattern {
+    var displayName: string;
+}
+export declare const COMPONENT_PATTERNS: {
+    readonly button: typeof ButtonPattern;
+    readonly 'icon-button': typeof IconButtonPattern;
+    readonly link: typeof LinkPattern;
+    readonly text: typeof TextPattern;
+    readonly heading: typeof HeadingPattern;
+    readonly badge: typeof BadgePattern;
+    readonly avatar: typeof AvatarPattern;
+    readonly icon: typeof IconPattern;
+    readonly image: typeof ImagePattern;
+    readonly card: typeof CardPattern;
+    readonly 'progress-bar': typeof ProgressBarPattern;
+    readonly spinner: typeof SpinnerPattern;
+    readonly input: typeof InputPattern;
+    readonly textarea: typeof TextareaPattern;
+    readonly select: typeof SelectPattern;
+    readonly checkbox: typeof CheckboxPattern;
+    readonly radio: typeof RadioPattern;
+    readonly label: typeof LabelPattern;
+    readonly alert: typeof AlertPattern;
+    readonly tooltip: typeof TooltipPattern;
+    readonly popover: typeof PopoverPattern;
+    readonly menu: typeof MenuPattern;
+    readonly accordion: typeof AccordionPattern;
+    readonly container: typeof ContainerPattern;
+    readonly 'simple-grid': typeof SimpleGridPattern;
+    readonly 'float-button': typeof FloatButtonPattern;
+    readonly 'map-view': typeof MapViewPattern;
+};
+export {};