@almadar/ui 5.79.1 → 5.79.2

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

@@ -0,0 +1,185 @@
+/**
+ * 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 { EventKey, EventPayload } from '@almadar/core';
+import type { UiError } from '../atoms/types';
+import { type ButtonProps } from '../atoms/Button';
+import { type AlertVariant } from '../molecules/Alert';
+/**
+ * Base closed circuit props required by all organism components.
+ */
+interface ClosedCircuitProps {
+    className?: string;
+    isLoading?: boolean;
+    error?: UiError | null;
+    entity?: string;
+}
+/**
+ * Props for {@link ButtonPattern}. A thin pass-through over the Button
+ * atom: accepts every Button prop plus wrapper-level aliases for the
+ * `.orb` schema convention (`action`/`event`/`onClick` as string
+ * event names, `iconPosition` for left/right icon placement).
+ *
+ * Anything not explicitly named is forwarded to `<Button>` via rest-spread,
+ * so a future Button prop lands automatically without needing a wrapper
+ * edit. This is the contract that fixes VG17: `action: EventKey` flows
+ * through to Button, which owns both `UI:{action}` emit AND the
+ * `data-testid="action-{NAME}"` attribute the verifier selects on.
+ */
+export interface ButtonPatternProps extends Omit<ButtonProps, 'onClick'>, ClosedCircuitProps {
+    /** Legacy alias for {@link ButtonProps.action} (string event name). */
+    onClick?: EventKey;
+    /** Legacy alias for {@link ButtonProps.action}. */
+    event?: EventKey;
+    /** Icon placement — maps to Button's `icon` (left) or `iconRight` (right). */
+    iconPosition?: 'left' | 'right';
+}
+/**
+ * Button pattern — thin pass-through to the Button atom.
+ *
+ * Prior to VG17 this wrapper owned a local event-bus emit and
+ * hand-enumerated only a narrow slice of props, silently dropping
+ * every prop outside that list (including the Pre-Phase `action:
+ * EventKey`). The atom already handles emit + data-testid via its
+ * `action` prop, so the wrapper simply forwards everything.
+ */
+export declare function ButtonPattern({ action, onClick, event, icon, iconPosition, ...rest }: ButtonPatternProps): React.ReactElement;
+export declare namespace ButtonPattern {
+    var displayName: string;
+}
+export interface IconButtonPatternProps extends Omit<ButtonProps, 'onClick'>, ClosedCircuitProps {
+    icon: string;
+    ariaLabel?: string;
+    /** Legacy alias for {@link ButtonProps.action}. */
+    onClick?: EventKey;
+    /** Legacy alias for {@link ButtonProps.action}. */
+    event?: EventKey;
+}
+/**
+ * Icon-only button pattern — pass-through to the Button atom with a
+ * mandatory icon and optional aria-label. Same VG17 fix as
+ * {@link ButtonPattern}: `action` forwards to the atom, which owns the
+ * emit + data-testid.
+ */
+export declare function IconButtonPattern({ action, onClick, event, icon, ariaLabel, variant, ...rest }: IconButtonPatternProps): React.ReactElement;
+export declare namespace IconButtonPattern {
+    var displayName: string;
+}
+export interface LinkPatternProps extends ClosedCircuitProps {
+    label: string;
+    href?: string;
+    external?: boolean;
+    /** Event key emitted on click (intercepts native navigation when set). */
+    action?: EventKey;
+    /** Legacy alias for action. */
+    onClick?: EventKey;
+    /** Legacy alias for action. */
+    event?: EventKey;
+    /** Payload for the dispatched event. */
+    actionPayload?: EventPayload;
+    className?: string;
+}
+/**
+ * Link pattern for navigation. When an event key is provided via
+ * `action` / `onClick` / `event`, intercepts the native `<a>`
+ * navigation and emits `UI:{action}` with the `href` in the payload.
+ * Sets `data-testid="action-{NAME}"` so the verifier's click-path
+ * gate can select it symmetrically with Button.
+ */
+export declare function LinkPattern({ label, href, external, action, onClick, event, actionPayload, 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 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 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 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 declare const COMPONENT_PATTERNS: {
+    readonly button: typeof ButtonPattern;
+    readonly 'icon-button': typeof IconButtonPattern;
+    readonly link: typeof LinkPattern;
+    readonly text: typeof TextPattern;
+    readonly image: typeof ImagePattern;
+    readonly label: typeof LabelPattern;
+    readonly alert: typeof AlertPattern;
+    readonly 'float-button': typeof FloatButtonPattern;
+};
+export {};

package/dist/components/core/organisms/CustomPattern.d.ts

@@ -0,0 +1,105 @@
+/**
+ * CustomPattern Component
+ *
+ * Renders freeform elements with Tailwind classes for custom UI designs.
+ * Uses Box with the `as` prop to render different element types.
+ * Supports nested children and the closed circuit pattern (action prop for events).
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import type { AssetUrl, EventKey, EventPayload, JsonValue } from "@almadar/core";
+import type { UiError } from "../atoms/types";
+/**
+ * Allowed element types for custom patterns.
+ */
+export declare const ALLOWED_CUSTOM_COMPONENTS: readonly ["div", "span", "button", "a", "p", "h1", "h2", "h3", "h4", "h5", "h6", "header", "footer", "section", "article", "nav", "main", "aside", "ul", "ol", "li", "img", "label", "input", "form"];
+export type AllowedCustomComponent = (typeof ALLOWED_CUSTOM_COMPONENTS)[number];
+/**
+ * Check if a component name is allowed.
+ */
+export declare function isAllowedComponent(component: string): component is AllowedCustomComponent;
+/**
+ * Check if an element is interactive (requires action for closed circuit).
+ */
+export declare function isInteractiveElement(component: string): boolean;
+export interface CustomPatternProps {
+    /** Element type to render */
+    component: AllowedCustomComponent;
+    /** Tailwind classes */
+    className?: string;
+    /** Token path(s) for design token resolution */
+    token?: string | string[];
+    /** Text content (for leaf elements) */
+    content?: string;
+    /** Event to emit on click (REQUIRED for interactive elements) */
+    action?: EventKey;
+    /** Event payload */
+    payload?: EventPayload;
+    /** Nested children patterns */
+    children?: React.ReactNode;
+    /** Image source (for img elements) */
+    src?: AssetUrl;
+    /** Image alt text (for img elements) */
+    alt?: string;
+    /** Link href (for a elements) */
+    href?: string;
+    /** Open link in new tab */
+    external?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Additional HTML attributes */
+    htmlProps?: React.HTMLAttributes<HTMLElement>;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+    /** Entity name */
+    entity?: string;
+}
+/**
+ * Renders a custom element with Tailwind styling.
+ *
+ * Follows the closed circuit pattern - interactive elements emit events via action prop.
+ * Uses Box with `as` prop for all element types to comply with the design system.
+ *
+ * @example
+ * ```tsx
+ * <CustomPattern
+ *   component="button"
+ *   className="bg-blue-500 text-white px-4 py-2 rounded"
+ *   action="SUBMIT"
+ *   content="Submit"
+ * />
+ * ```
+ */
+export declare function CustomPattern({ component, className, content, action, payload, children, src, alt, href, external, disabled, htmlProps, }: CustomPatternProps): React.ReactElement | null;
+export declare namespace CustomPattern {
+    var displayName: string;
+}
+export interface CustomPatternConfig {
+    type: "custom";
+    component: AllowedCustomComponent;
+    className?: string;
+    token?: string | string[];
+    content?: string;
+    action?: EventKey;
+    payload?: EventPayload;
+    children?: CustomPatternConfig[];
+    src?: AssetUrl;
+    alt?: string;
+    href?: string;
+    external?: boolean;
+    disabled?: boolean;
+}
+/**
+ * Check if a pattern config is a custom pattern.
+ */
+export declare function isCustomPatternConfig(config: JsonValue | CustomPatternConfig): config is CustomPatternConfig;
+/**
+ * Recursively render custom pattern configurations.
+ *
+ * Use this to render nested custom patterns from render_ui effects.
+ */
+export declare function renderCustomPattern(config: CustomPatternConfig, key?: string | number): React.ReactElement;
+export { ALLOWED_CUSTOM_COMPONENTS as CUSTOM_COMPONENT_TYPES };

package/dist/components/core/organisms/DataTable.d.ts

@@ -0,0 +1,75 @@
+import React from "react";
+import type { EventKey } from "@almadar/core";
+import type { IconInput } from "../atoms/Icon";
+import { DisplayStateProps } from "./types";
+import type { EntityRow, FieldValue } from "@almadar/core";
+export type EntityTableLook = "dense" | "spacious" | "striped" | "borderless" | "card-rows";
+export interface Column<T> {
+    key: keyof T | string;
+    header: string;
+    /** Alias for key (used by compiler-generated fields) */
+    name?: string;
+    /** Alias for header (used by compiler-generated fields) */
+    label?: string;
+    width?: string;
+    sortable?: boolean;
+    render?: (value: FieldValue | undefined, row: T, index: number) => React.ReactNode;
+}
+export interface RowAction<T> {
+    label: string;
+    icon?: IconInput;
+    onClick: (row: T) => void;
+    variant?: "default" | "danger";
+    show?: (row: T) => boolean;
+    event?: string;
+}
+export interface DataTableEmptyAction {
+    label: string;
+    event?: string;
+}
+export interface DataTableProps<T extends EntityRow & {
+    id: string | number;
+}> extends DisplayStateProps {
+    /** Entity rows to display (collection cardinality). */
+    entity?: readonly EntityRow[];
+    /** Fields to display - accepts string[] or Column[] for unified interface. Alias for columns */
+    fields: readonly Column<T>[] | readonly string[];
+    /** Columns can be Column objects or simple string field names */
+    columns?: readonly Column<T>[] | readonly string[];
+    /** Item actions from generated code - maps to rowActions */
+    itemActions?: readonly {
+        label: string;
+        event?: string;
+        navigatesTo?: string;
+        action?: EventKey;
+        placement?: "row" | "bulk" | string;
+        icon?: IconInput;
+        variant?: "default" | "primary" | "secondary" | "ghost" | "danger" | string;
+        onClick?: (row: T) => void;
+    }[];
+    emptyIcon?: IconInput;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    emptyAction?: DataTableEmptyAction;
+    selectable?: boolean;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    rowActions?: readonly RowAction<T>[];
+    bulkActions?: ReadonlyArray<{
+        label: string;
+        icon?: IconInput;
+        onClick: (selectedRows: T[]) => void;
+        variant?: "default" | "danger";
+    }>;
+    headerActions?: React.ReactNode;
+    /** Show total count in pagination */
+    showTotal?: boolean;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: EntityTableLook;
+}
+export declare function DataTable<T extends EntityRow & {
+    id: string | number;
+}>({ fields, columns, entity, itemActions, isLoading, error, emptyIcon, emptyTitle, emptyDescription, emptyAction, selectable, selectedIds, sortBy, sortDirection, searchable, searchValue, searchPlaceholder, page, pageSize, totalCount, rowActions: externalRowActions, bulkActions, headerActions, showTotal, className, look, }: DataTableProps<T>): React.JSX.Element;
+export declare namespace DataTable {
+    var displayName: string;
+}

package/dist/components/core/organisms/DetailPanel.d.ts

@@ -0,0 +1,80 @@
+/**
+ * DetailPanel Organism Component
+ *
+ * Composes atoms and molecules to create a professional detail view.
+ *
+ * Data is provided by the runtime via the `entity` prop.
+ * Extends DisplayStateProps (see ./types.ts) and declares `entity?: EntityRow`.
+ */
+import React from "react";
+import type { EntityRow } from "@almadar/core";
+import type { IconInput } from "../atoms/Icon";
+import type { DisplayStateProps } from "./types";
+export interface DetailField {
+    label: string;
+    value: React.ReactNode;
+    icon?: IconInput;
+    copyable?: boolean;
+}
+export interface DetailSection {
+    title: string;
+    fields: (DetailField | string)[];
+}
+/**
+ * Action definition for DetailPanel
+ */
+export interface DetailPanelAction {
+    label: string;
+    icon?: IconInput;
+    onClick?: () => void;
+    /** Event to emit via event bus */
+    event?: string;
+    /** Navigation URL */
+    navigatesTo?: string;
+    /** Button variant (primary for main action, others for secondary) */
+    variant?: "primary" | "secondary" | "ghost" | "danger";
+}
+/**
+ * Field definition for unified interface - can be a simple string, key/header object, or typed object
+ */
+export type FieldDef = string | {
+    key: string;
+    header?: string;
+} | {
+    name: string;
+    type: string;
+};
+export interface DetailPanelStatus {
+    label: string;
+    variant?: "default" | "success" | "warning" | "danger" | "info";
+}
+export interface DetailPanelProps extends DisplayStateProps {
+    /** RECORD-cardinality: renders ONE record (see body collapse below). */
+    entity?: EntityRow;
+    title?: string;
+    subtitle?: string;
+    status?: DetailPanelStatus;
+    avatar?: React.ReactNode;
+    sections?: readonly DetailSection[];
+    /** Unified actions array - first action with variant='primary' is the main action */
+    actions?: readonly DetailPanelAction[];
+    footer?: React.ReactNode;
+    slideOver?: boolean;
+    /** Fields to display - accepts string[], {key, header}[], or DetailField[] */
+    fields: readonly (FieldDef | DetailField)[];
+    /** Alias for fields - backwards compatibility */
+    fieldNames?: readonly string[];
+    /** Initial data for edit mode (passed by compiler) */
+    initialData?: EntityRow;
+    /** Display mode (passed by compiler) */
+    mode?: string;
+    /** Panel position (for drawer/sidebar placement) */
+    position?: "left" | "right";
+    /** Panel width (CSS value, e.g., '400px', '50%') */
+    width?: string;
+    /** Display fields (alias for fields) */
+    displayFields?: readonly string[];
+    /** Show actions flag */
+    showActions?: boolean;
+}
+export declare const DetailPanel: React.FC<DetailPanelProps>;

package/dist/components/core/organisms/DrawerSlot.d.ts

@@ -0,0 +1,40 @@
+/**
+ * DrawerSlot Component
+ *
+ * Wraps drawer slot content in a proper Drawer component.
+ * Used by trait-driven pages to display drawer UI from render_ui effects.
+ *
+ * Handles:
+ * - Auto-open when content is present
+ * - Dispatches CLOSE/CANCEL events when closed
+ * - Extracts title from Form or DetailPanel components
+ * - Configurable position and size
+ */
+import React from 'react';
+import { DrawerPosition, DrawerSize } from '../molecules/Drawer';
+import type { UiError } from '../atoms/types';
+export interface DrawerSlotProps {
+    /** Content to display in the drawer */
+    children?: React.ReactNode;
+    /** Override drawer title (extracted from children if not provided) */
+    title?: string;
+    /** Drawer position */
+    position?: DrawerPosition;
+    /** Drawer size */
+    size?: DrawerSize;
+    /** Custom class name */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+}
+/**
+ * DrawerSlot - Wrapper for drawer slot content
+ *
+ * Automatically shows drawer when children are present,
+ * and dispatches close events when drawer is dismissed.
+ */
+export declare const DrawerSlot: React.FC<DrawerSlotProps>;