@almadar/ui 2.14.0 → 2.15.0

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

@@ -0,0 +1,160 @@
+/**
+ * WizardContainer Component
+ *
+ * Multi-step wizard pattern with progress indicator.
+ * Composes Box, Typography, and Button atoms.
+ *
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+/** Form field definition for wizard sections */
+export interface WizardField {
+    id: string;
+    type: string;
+    label?: string;
+    required?: boolean;
+    repeatable?: boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+        isDefault?: boolean;
+    }>;
+    defaultValue?: unknown;
+    condition?: unknown[];
+    placeholder?: string;
+    entityField?: string;
+    minLength?: number;
+    maxLength?: number;
+    dataSource?: Record<string, unknown>;
+    displayFields?: string[];
+    searchConfig?: Record<string, unknown>;
+    hiddenCalculations?: Array<{
+        variable: string;
+        expression: unknown;
+        scope?: string;
+    }>;
+    signatureConfig?: Record<string, unknown>;
+    displayTemplate?: Record<string, unknown>;
+    lawReference?: Record<string, unknown>;
+    contextMenu?: string[];
+    calculated?: Record<string, unknown>;
+    readOnly?: boolean;
+    minDate?: unknown;
+    stats?: Array<{
+        label: string;
+        value: unknown;
+        icon?: string;
+    }>;
+    items?: Array<{
+        id: string;
+        label: string;
+        autoCheck?: unknown;
+    }>;
+    [key: string]: unknown;
+}
+/** Section within a wizard step */
+export interface WizardSection {
+    id: string;
+    title?: string;
+    description?: string;
+    fields?: WizardField[];
+    subsections?: WizardSection[];
+    condition?: unknown[];
+    repeatable?: boolean;
+    minItems?: number;
+    addButtonLabel?: string;
+    hiddenCalculations?: Array<{
+        variable: string;
+        expression: unknown;
+        scope?: string;
+    }>;
+    dataSource?: Record<string, unknown>;
+    readOnly?: boolean;
+    [key: string]: unknown;
+}
+/** Entity mapping configuration */
+export interface WizardEntityMapping {
+    entity: string;
+    mode: "search_or_create" | "create_multiple" | "select_one" | "update" | string;
+    parentField?: string;
+    idField?: string;
+    [key: string]: unknown;
+}
+/** Validation rule for wizard steps */
+export interface WizardValidationRule {
+    condition: unknown[];
+    message: string;
+}
+/** Law reference for compliance */
+export interface WizardLawReference {
+    law: string;
+    article: string;
+    description?: string;
+}
+export interface WizardStep {
+    /** Step identifier */
+    id?: string;
+    /** Tab identifier (schema-driven) */
+    tabId?: string;
+    /** Step title */
+    title?: string;
+    /** Step name (schema-driven, used as title if title not provided) */
+    name?: string;
+    /** Step description (optional) */
+    description?: string;
+    /** Step content (React component mode) */
+    content?: React.ReactNode;
+    /** Whether this step can be skipped */
+    optional?: boolean;
+    /** Custom validation for this step */
+    isValid?: () => boolean;
+    /** Form sections within this step */
+    sections?: WizardSection[];
+    /** Global variables required before entering this step */
+    globalVariablesRequired?: string[];
+    /** Global variables set by this step */
+    globalVariablesSet?: string[];
+    /** Local variables scoped to this step */
+    localVariables?: string[];
+    /** Entity mapping configuration */
+    entityMapping?: WizardEntityMapping;
+    /** Validation rules for this step */
+    validationRules?: WizardValidationRule[];
+    /** Law references for compliance */
+    lawReferences?: WizardLawReference[];
+    /** Phase of the inspection process */
+    phase?: string;
+    /** Context menu actions */
+    contextMenu?: string[];
+    /** Allow additional properties from schema */
+    [key: string]: unknown;
+}
+export interface WizardContainerProps {
+    /** Wizard steps */
+    steps: WizardStep[];
+    /** Current step index (controlled) - accepts unknown for generated code compatibility */
+    currentStep?: number | string | unknown;
+    /** Callback when step changes */
+    onStepChange?: (stepIndex: number) => void;
+    /** Callback when wizard is completed */
+    onComplete?: () => void;
+    /** Show progress indicator */
+    showProgress?: boolean;
+    /** Allow navigation to previous steps */
+    allowBack?: boolean;
+    /** Modal mode (compact header, no padding) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity type name (schema-driven) */
+    entity?: string;
+}
+/**
+ * WizardContainer - Multi-step wizard
+ */
+export declare const WizardContainer: React.FC<WizardContainerProps>;
+export default WizardContainer;

package/dist/components/organisms/book/BookChapterView.d.ts

@@ -0,0 +1,17 @@
+/**
+ * BookChapterView Organism
+ *
+ * Renders a single chapter: title + optional orbital diagram +
+ * rich content via ContentRenderer.
+ *
+ * Event Contract:
+ * - Delegates to ContentRenderer children
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../types';
+import type { BookChapter } from './types';
+export interface BookChapterViewProps extends EntityDisplayProps<BookChapter> {
+    chapter: BookChapter;
+    direction?: 'rtl' | 'ltr';
+}
+export declare const BookChapterView: React.FC<BookChapterViewProps>;

package/dist/components/organisms/book/BookCoverPage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * BookCoverPage Molecule
+ *
+ * Renders a book cover with title, subtitle, author, and optional image.
+ * Centered layout suitable for the first "page" of a BookViewer.
+ *
+ * Event Contract:
+ * - Emits: UI:BOOK_START
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../types';
+import type { BookData } from './types';
+export interface BookCoverPageProps extends EntityDisplayProps<BookData> {
+    title: string;
+    subtitle?: string;
+    author?: string;
+    coverImageUrl?: string;
+    direction?: 'rtl' | 'ltr';
+}
+export declare const BookCoverPage: React.FC<BookCoverPageProps>;

package/dist/components/organisms/book/BookNavBar.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BookNavBar Molecule
+ *
+ * Navigation bar for the BookViewer with prev/next, page indicator,
+ * print button, and TOC toggle.
+ *
+ * Event Contract:
+ * - Emits: UI:BOOK_PAGE_PREV, UI:BOOK_PAGE_NEXT, UI:BOOK_PRINT, UI:BOOK_SHOW_TOC
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../types';
+import type { BookData } from './types';
+export interface BookNavBarProps extends EntityDisplayProps<BookData> {
+    currentPage: number;
+    totalPages: number;
+    chapterTitle?: string;
+    direction?: 'rtl' | 'ltr';
+}
+export declare const BookNavBar: React.FC<BookNavBarProps>;

package/dist/components/organisms/book/BookTableOfContents.d.ts

@@ -0,0 +1,18 @@
+/**
+ * BookTableOfContents Molecule
+ *
+ * Renders a clickable table of contents grouped by parts.
+ * Highlights the current chapter.
+ *
+ * Event Contract:
+ * - Emits: UI:BOOK_NAVIGATE { chapterId }
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../types';
+import type { BookPart } from './types';
+export interface BookTableOfContentsProps extends EntityDisplayProps<BookPart> {
+    parts: BookPart[];
+    currentChapterId?: string;
+    direction?: 'rtl' | 'ltr';
+}
+export declare const BookTableOfContents: React.FC<BookTableOfContentsProps>;

package/dist/components/organisms/book/BookViewer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * BookViewer Organism
+ *
+ * Flippable book reader with cover, TOC, chapter views, and navigation.
+ * Supports RTL layout (Arabic), CSS slide transitions, and print mode.
+ *
+ * Page model:
+ *   0 = cover, 1 = TOC, 2+ = chapters (flattened from parts)
+ *
+ * Field mapping:
+ *   Entity data may use non-English field names (e.g. Arabic .orb schemas).
+ *   Pass a `fieldMap` prop to translate entity fields to canonical BookData.
+ *   Default: IDENTITY_BOOK_FIELDS (English field names, no translation).
+ *
+ * Event Contract:
+ * - Emits: UI:BOOK_PAGE_CHANGE { pageIndex, chapterId? }
+ * - Listens: UI:BOOK_START, UI:BOOK_NAVIGATE, UI:BOOK_PAGE_PREV/NEXT, UI:BOOK_PRINT, UI:BOOK_SHOW_TOC
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../types';
+import type { BookData, BookFieldMap } from './types';
+export interface BookViewerProps extends EntityDisplayProps<BookData | Record<string, unknown>> {
+    /** Initial page index (default: 0 = cover) */
+    initialPage?: number;
+    /** Field name translation map — a BookFieldMap object or locale key ("ar") */
+    fieldMap?: BookFieldMap | string;
+}
+export declare const BookViewer: React.FC<BookViewerProps>;

package/dist/components/organisms/book/index.d.ts

@@ -0,0 +1,7 @@
+export { BookViewer, type BookViewerProps } from './BookViewer';
+export { BookChapterView, type BookChapterViewProps } from './BookChapterView';
+export { BookCoverPage, type BookCoverPageProps } from './BookCoverPage';
+export { BookTableOfContents, type BookTableOfContentsProps } from './BookTableOfContents';
+export { BookNavBar, type BookNavBarProps } from './BookNavBar';
+export type { BookData, BookPart, BookChapter, BookFieldMap } from './types';
+export { mapBookData, resolveFieldMap, IDENTITY_BOOK_FIELDS, AR_BOOK_FIELDS } from './types';

package/dist/components/organisms/book/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * BookViewer shared types
+ *
+ * Field names are canonical English. When entity data arrives from a
+ * schema with non-English field names (e.g. Arabic .orb), a field map
+ * translates them before passing to BookViewer. See `mapBookData()`.
+ */
+export interface BookData {
+    title: string;
+    subtitle?: string;
+    author?: string;
+    coverImageUrl?: string;
+    direction?: 'rtl' | 'ltr';
+    parts: BookPart[];
+}
+export interface BookPart {
+    title: string;
+    chapters: BookChapter[];
+}
+export interface BookChapter {
+    id: string;
+    title: string;
+    content: string;
+    orbitalSchema?: unknown;
+}
+/**
+ * Maps raw entity field names to canonical BookData field names.
+ * Each key is a canonical field, each value is the entity field name.
+ *
+ * @example
+ * ```ts
+ * // Arabic schema
+ * const AR_BOOK_FIELDS: BookFieldMap = {
+ *   title: 'العنوان',
+ *   subtitle: 'العنوان_الفرعي',
+ *   author: 'المؤلف',
+ *   coverImageUrl: 'صورة_الغلاف',
+ *   direction: 'الاتجاه',
+ *   parts: 'الأجزاء',
+ *   partTitle: 'العنوان',
+ *   chapters: 'الفصول',
+ *   chapterId: 'المعرف',
+ *   chapterTitle: 'العنوان',
+ *   chapterContent: 'المحتوى',
+ *   chapterOrbitalSchema: 'المخطط_المداري',
+ * };
+ * ```
+ */
+export interface BookFieldMap {
+    title: string;
+    subtitle: string;
+    author: string;
+    coverImageUrl: string;
+    direction: string;
+    parts: string;
+    partTitle: string;
+    chapters: string;
+    chapterId: string;
+    chapterTitle: string;
+    chapterContent: string;
+    chapterOrbitalSchema: string;
+}
+/** Identity map — entity already uses canonical English field names */
+export declare const IDENTITY_BOOK_FIELDS: BookFieldMap;
+/** Arabic field map for الأمة_الرقمية schema */
+export declare const AR_BOOK_FIELDS: BookFieldMap;
+/**
+ * Resolves a fieldMap prop to a BookFieldMap object.
+ * Accepts a BookFieldMap object directly, a locale string key ("ar"),
+ * or undefined (defaults to identity/English).
+ */
+export declare function resolveFieldMap(fieldMap: BookFieldMap | string | undefined): BookFieldMap;
+/**
+ * Maps a raw entity record to a typed BookData using a field map.
+ * Pass `IDENTITY_BOOK_FIELDS` for English schemas, `AR_BOOK_FIELDS` for Arabic, etc.
+ */
+export declare function mapBookData(raw: Record<string, unknown>, fields?: BookFieldMap): BookData;

package/dist/components/organisms/component-registry.generated.d.ts

@@ -0,0 +1,9 @@
+import type React from 'react';
+/**
+ * Maps component names to actual React components.
+ * Generated from @almadar/patterns component-mapping.json.
+ *
+ * Pattern wrappers (ButtonPattern, VStackPattern, etc.) adapt the raw component
+ * API to the render-ui config format. Direct components are used when no wrapper exists.
+ */
+export declare const COMPONENT_REGISTRY: Record<string, React.ComponentType<any>>;

package/dist/components/organisms/debug/RuntimeDebugger.d.ts

@@ -0,0 +1,19 @@
+import './RuntimeDebugger.css';
+export interface RuntimeDebuggerProps {
+    /** Initial position */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Initial collapsed state */
+    defaultCollapsed?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Display mode: floating (fixed overlay) or inline (block element) */
+    mode?: 'floating' | 'inline';
+    /** Default active tab id */
+    defaultTab?: string;
+    /** Raw schema for EventDispatcherTab payload extraction */
+    schema?: Record<string, unknown>;
+}
+export declare function RuntimeDebugger({ position, defaultCollapsed, className, mode, defaultTab, schema, }: RuntimeDebuggerProps): import("react/jsx-runtime").JSX.Element | null;
+export declare namespace RuntimeDebugger {
+    var displayName: string;
+}

package/dist/components/organisms/debug/hooks/useDebugData.d.ts

@@ -0,0 +1,25 @@
+import { type TraitDebugInfo } from '../../../../lib/traitRegistry';
+import { type TickExecution } from '../../../../lib/tickRegistry';
+import { type GuardEvaluation } from '../../../../lib/guardRegistry';
+import { type EntitySnapshot } from '../../../../lib/entityDebug';
+import { type DebugEvent } from '../../../../lib/debugRegistry';
+import { type VerificationCheck, type TransitionTrace, type BridgeHealth, type VerificationSummary } from '../../../../lib/verificationRegistry';
+export interface DebugData {
+    traits: TraitDebugInfo[];
+    ticks: TickExecution[];
+    guards: GuardEvaluation[];
+    events: DebugEvent[];
+    entitySnapshot: EntitySnapshot | null;
+    verification: {
+        checks: VerificationCheck[];
+        transitions: TransitionTrace[];
+        bridge: BridgeHealth | null;
+        summary: VerificationSummary;
+    };
+    lastUpdate: number;
+}
+/**
+ * Hook that aggregates data from all debug registries.
+ * Subscribes to changes and polls entity snapshots.
+ */
+export declare function useDebugData(): DebugData;

package/dist/components/organisms/debug/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Debug Organism Components
+ *
+ * Runtime debugging and verification tools for KFlow applications.
+ *
+ * @packageDocumentation
+ */
+export { RuntimeDebugger, type RuntimeDebuggerProps } from './RuntimeDebugger';
+export { useDebugData, type DebugData } from './hooks/useDebugData';
+export { VerificationTab } from './tabs/VerificationTab';
+export { TransitionTimeline } from './tabs/TransitionTimeline';
+export { ServerBridgeTab } from './tabs/ServerBridgeTab';
+export { EventDispatcherTab } from './tabs/EventDispatcherTab';

package/dist/components/organisms/debug/tabs/EntitiesTab.d.ts

@@ -0,0 +1,13 @@
+/**
+ * EntitiesTab - Displays entity snapshots
+ * Uses existing component library atoms/molecules.
+ */
+import type { EntitySnapshot } from '../../../../lib/entityDebug';
+interface EntitiesTabProps {
+    snapshot: EntitySnapshot | null;
+}
+export declare function EntitiesTab({ snapshot }: EntitiesTabProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EntitiesTab {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/EventDispatcherTab.d.ts

@@ -0,0 +1,16 @@
+/**
+ * EventDispatcherTab - Fire events into the state machine from the debug panel
+ *
+ * Shows available transitions per trait based on current state,
+ * lets users click to fire events, and displays a compact transition log.
+ */
+import type { TraitDebugInfo } from '../../../../lib/traitRegistry';
+interface EventDispatcherTabProps {
+    traits: TraitDebugInfo[];
+    schema?: Record<string, unknown>;
+}
+export declare function EventDispatcherTab({ traits, schema }: EventDispatcherTabProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EventDispatcherTab {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/EventFlowTab.d.ts

@@ -0,0 +1,9 @@
+import type { DebugEvent } from '../../../../lib/debugRegistry';
+interface EventFlowTabProps {
+    events: DebugEvent[];
+}
+export declare function EventFlowTab({ events }: EventFlowTabProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EventFlowTab {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/GuardsPanel.d.ts

@@ -0,0 +1,9 @@
+import type { GuardEvaluation } from '../../../../lib/guardRegistry';
+interface GuardsPanelProps {
+    guards: GuardEvaluation[];
+}
+export declare function GuardsPanel({ guards }: GuardsPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace GuardsPanel {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/ServerBridgeTab.d.ts

@@ -0,0 +1,9 @@
+import type { BridgeHealth } from '../../../../lib/verificationRegistry';
+interface ServerBridgeTabProps {
+    bridge: BridgeHealth | null;
+}
+export declare function ServerBridgeTab({ bridge }: ServerBridgeTabProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ServerBridgeTab {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/TicksTab.d.ts

@@ -0,0 +1,13 @@
+/**
+ * TicksTab - Displays tick execution timing and status
+ * Uses existing component library atoms/molecules.
+ */
+import type { TickExecution } from '../../../../lib/tickRegistry';
+interface TicksTabProps {
+    ticks: TickExecution[];
+}
+export declare function TicksTab({ ticks }: TicksTabProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TicksTab {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/TraitsTab.d.ts

@@ -0,0 +1,13 @@
+/**
+ * TraitsTab - Displays active traits and their state machines
+ * Uses existing component library atoms/molecules.
+ */
+import type { TraitDebugInfo } from '../../../../lib/traitRegistry';
+interface TraitsTabProps {
+    traits: TraitDebugInfo[];
+}
+export declare function TraitsTab({ traits }: TraitsTabProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TraitsTab {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/TransitionTimeline.d.ts

@@ -0,0 +1,9 @@
+import type { TransitionTrace } from '../../../../lib/verificationRegistry';
+interface TransitionTimelineProps {
+    transitions: TransitionTrace[];
+}
+export declare function TransitionTimeline({ transitions }: TransitionTimelineProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TransitionTimeline {
+    var displayName: string;
+}
+export {};

package/dist/components/organisms/debug/tabs/VerificationTab.d.ts

@@ -0,0 +1,10 @@
+import type { VerificationCheck, VerificationSummary } from '../../../../lib/verificationRegistry';
+interface VerificationTabProps {
+    checks: VerificationCheck[];
+    summary: VerificationSummary;
+}
+export declare function VerificationTab({ checks, summary }: VerificationTabProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace VerificationTab {
+    var displayName: string;
+}
+export {};