@almadar/ui 5.111.0 → 5.113.0

package/dist/components/core/molecules/markdown/CodeBlock.d.ts

@@ -1,108 +0,0 @@
-/**
- * CodeBlock Molecule Component
- *
- * A syntax-highlighted code block with copy-to-clipboard functionality.
- * Preserves scroll position during re-renders.
- *
- * Event Contract:
- * - Emits: UI:COPY_CODE { language, success }
- */
-import React from 'react';
-import type { UiError } from '../../atoms/types';
-/**
- * The set of languages with a registered PrismLight grammar (above) plus the
- * `.orb`/`.lolo` grammars from `@almadar/syntax`. Authoritative: an unregistered
- * value renders as plain text, so this union mirrors the `registerLanguage`
- * calls exactly.
- */
-export declare const CODE_LANGUAGES: readonly ["text", "json", "javascript", "js", "typescript", "ts", "jsx", "tsx", "css", "markdown", "md", "bash", "shell", "sh", "yaml", "yml", "rust", "python", "py", "sql", "diff", "toml", "go", "graphql", "html", "xml", "orb", "lolo"];
-export type CodeLanguage = (typeof CODE_LANGUAGES)[number];
-/**
- * Narrow an arbitrary string (e.g. a markdown fence info-string) to a
- * `CodeLanguage`, falling back to `'text'` for any value without a registered
- * grammar — matching the highlighter's own plain-text fallback.
- */
-export declare function toCodeLanguage(value: string | undefined): CodeLanguage;
-export type CodeViewerMode = 'code' | 'diff';
-export interface DiffLine {
-    type: 'add' | 'added' | 'remove' | 'removed' | 'context' | 'unchanged';
-    content: string;
-    lineNumber?: number;
-}
-export interface CodeViewerAction {
-    label: string;
-    event?: string;
-    navigatesTo?: string;
-    variant?: 'primary' | 'secondary' | 'ghost';
-}
-export interface CodeViewerFile {
-    label: string;
-    code: string;
-    language?: CodeLanguage;
-}
-export interface CodeBlockProps {
-    /** The code content to display */
-    code?: string;
-    /** Programming language for syntax highlighting */
-    language?: CodeLanguage;
-    /** Show the copy button */
-    showCopyButton?: boolean;
-    /** Show the language badge */
-    showLanguageBadge?: boolean;
-    /** Maximum height before scrolling */
-    maxHeight?: string | number;
-    /** Enable brace-based code folding of multi-line `{}`/`[]` blocks (default: true). */
-    foldable?: boolean;
-    /** Additional CSS classes */
-    className?: string;
-    /**
-     * When true, render an editable surface that composes a transparent `Textarea`
-     * over a Prism-highlighted overlay. The overlay re-tokenizes on each keystroke
-     * (driven from a local mirror of the textarea value), so users see syntax-highlighted
-     * code while still being able to type. Folding is skipped in editable mode.
-     *
-     * History: GAP-51 first-cut shipped plain (no-highlighting) editable text;
-     * GAP-77 (2026-04-12) added the Prism overlay layer.
-     *
-     * Default: false (existing read-only behavior unchanged).
-     */
-    editable?: boolean;
-    /**
-     * GAP-51: called with the new code on every keystroke when `editable === true`.
-     * Consumers should debounce + parse downstream — `CodeBlock` does not.
-     */
-    onChange?: (code: string) => void;
-    /**
-     * GAP-80: line-level error/warning highlights for editable mode.
-     * Map of 1-based line number → severity. The overlay paints a colored
-     * background on each line: error = red, warning = yellow. Pass undefined
-     * (default) to disable. The consumer is responsible for computing the
-     * path → line map from the schema + validation results.
-     */
-    errorLines?: Map<number, 'error' | 'warning'>;
-    /** Title shown in the toolbar */
-    title?: string;
-    /** Diff or plain-code display mode */
-    mode?: CodeViewerMode;
-    /** Pre-computed diff lines */
-    diff?: readonly DiffLine[];
-    /** Old source text — generates diff when combined with newValue */
-    oldValue?: string;
-    /** New source text — generates diff when combined with oldValue */
-    newValue?: string;
-    /** Show line numbers in code / diff mode */
-    showLineNumbers?: boolean;
-    /** Enable word-wrap in code / diff mode */
-    wordWrap?: boolean;
-    /** Multiple files shown as tabs */
-    files?: readonly CodeViewerFile[];
-    /** Action badges in the toolbar */
-    actions?: readonly CodeViewerAction[];
-    /** Loading state */
-    isLoading?: boolean;
-    /** Error state */
-    error?: UiError | null;
-    /** Show copy button (viewer alias for showCopyButton) */
-    showCopy?: boolean;
-}
-export declare const CodeBlock: React.NamedExoticComponent<CodeBlockProps>;

package/dist/components/core/molecules/markdown/MarkdownContent.d.ts

@@ -1,26 +0,0 @@
-/**
- * MarkdownContent Molecule Component
- *
- * Renders markdown content with support for GFM (GitHub Flavored Markdown)
- * and math equations (KaTeX). Handles inline code only — fenced code blocks
- * should be parsed out and rendered with CodeBlock component.
- *
- * Event Contract:
- * - No events emitted (display-only component)
- * - entityAware: false
- *
- * NOTE: react-markdown's `components` override API requires native HTML
- * elements — this is the same library-boundary exception as `<iframe>` in
- * DocumentViewer and `<svg>` in JazariStateMachine/StateMachineView.
- */
-import React from 'react';
-import 'katex/dist/katex.min.css';
-export interface MarkdownContentProps {
-    /** The markdown content to render */
-    content: string;
-    /** Text direction (defaults to ltr; `ltr` is first so the generated config seeds it) */
-    direction?: 'ltr' | 'rtl';
-    /** Additional CSS classes */
-    className?: string;
-}
-export declare const MarkdownContent: React.NamedExoticComponent<MarkdownContentProps>;

package/dist/components/core/molecules/markdown/index.d.ts

@@ -1,2 +0,0 @@
-export { MarkdownContent, type MarkdownContentProps } from './MarkdownContent';
-export { CodeBlock, type CodeBlockProps, type CodeLanguage } from './CodeBlock';

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

@@ -1,44 +0,0 @@
-/**
- * parseLessonSegments — parses lesson markdown with embedded learning-science
- * XML-style tags into a typed Segment array.
- *
- * Supported tags: <activate>, <connect>, <reflect>, <bloom level="...">,
- * <question>/<answer>, <visualize type="..." description="..." />.
- *
- * Tags may be open (unclosed) — the parser falls back to consuming content
- * until the next recognised tag, a section heading (`\n\n#`), or end-of-input.
- */
-import type { BloomLevel } from './BloomQuizBlock';
-import { type MixedSegment } from './lessonSegmentUtils';
-export type InteractiveOrbitalType = 'chart' | 'simulation' | 'math' | 'physics' | 'biology' | 'chemistry' | 'probability';
-export type LessonSegment = MixedSegment | {
-    type: 'quiz';
-    question: string;
-    answer: string;
-} | {
-    type: 'activate';
-    question: string;
-} | {
-    type: 'connect';
-    content: string;
-} | {
-    type: 'reflect';
-    prompt: string;
-} | {
-    type: 'bloom';
-    level: BloomLevel;
-    question: string;
-    answer: string;
-} | {
-    type: 'visualization';
-    visualizationType: InteractiveOrbitalType;
-    description: string;
-};
-/** User progress state passed into SegmentRenderer. */
-export interface LessonUserProgress {
-    activationResponse?: string;
-    reflectionNotes?: string[];
-    bloomAnswered?: Record<number, boolean>;
-}
-/** Parse a lesson string into typed segments. Returns `[]` when input is empty. */
-export declare function parseLessonSegments(lesson: string | undefined): LessonSegment[];

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

@@ -1,63 +0,0 @@
-/**
- * useDataDnd — shared drag-drop machinery for DataList + DataGrid.
- *
- * Both primitives expose six identical drag-drop props:
- *   - dragGroup?:      string   items in this container announce this group when picked up
- *   - accepts?:        string   this container accepts drops whose dragGroup matches (or "*" for any)
- *   - sortable?:       boolean  enable in-container reorder
- *   - dropEvent?:      EventKey bus event on cross-container drop: { id, sourceGroup, targetGroup, newIndex }
- *   - reorderEvent?:   EventKey bus event on in-container reorder: { id, oldIndex, newIndex }
- *   - dndItemIdField?: string   row field used as the @dnd-kit draggable id (default "id")
- *
- * Architecture
- *   - A container that opts in via any dnd prop becomes a "zone".
- *   - The first ancestor zone in the tree creates the DndContext (the "root").
- *   - Inner zones detect the root via React context and skip creating their own.
- *   - The root's onDragEnd reads source + target zone metadata off the dragged
- *     item and the drop target, dispatches to the bus accordingly.
- */
-import React from 'react';
-import { type UniqueIdentifier } from '@dnd-kit/core';
-import type { EntityRow, EventKey } from '@almadar/core';
-export interface DataDndProps {
-    /**
-     * Event emitted N times per drop (one per item in each affected zone) so
-     * the trait can persist new positions for every item — not just the moved
-     * one. Required for stable sort-by-position because setting only the
-     * dragged item's position creates collisions with the (unchanged) others.
-     * Payload: { id : string, position : number }.
-     */
-    positionEvent?: EventKey;
-    dragGroup?: string;
-    accepts?: string;
-    sortable?: boolean;
-    dropEvent?: EventKey;
-    reorderEvent?: EventKey;
-    dndItemIdField?: string;
-    /**
-     * Mark this container as the DnD root for its subtree. Use on an outer
-     * container (e.g. a data-grid hosting inner data-lists) when the container
-     * itself is NOT a drop target or sortable, but descendant zones need to
-     * share one DndContext so items can be dragged between them. Inner zones
-     * with `accepts` / `dragGroup` / `sortable` detect this root and skip
-     * creating their own DndContext.
-     */
-    dndRoot?: boolean;
-}
-interface UseDataDndArgs extends DataDndProps {
-    items: readonly EntityRow[];
-    layout: 'list' | 'grid';
-}
-interface UseDataDndResult {
-    enabled: boolean;
-    /** True when this container is a sortable zone (own items are draggable). False in dndRoot-only mode. */
-    isZone: boolean;
-    wrapContainer: (children: React.ReactNode) => React.ReactNode;
-    SortableItem: React.FC<{
-        id: UniqueIdentifier;
-        children: React.ReactNode;
-    }>;
-    orderedItems: readonly EntityRow[];
-}
-export declare function useDataDnd(args: UseDataDndArgs): UseDataDndResult;
-export {};

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

@@ -1,84 +0,0 @@
-/**
- * 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 { EventKey, EventPayload } from "@almadar/core";
-import type { DisplayStateProps } from './types';
-import type { EntityRow } from '@almadar/core';
-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?: EventKey;
-    /** Navigation URL - supports template interpolation like "/products/{{row.id}}" */
-    navigatesTo?: string;
-    /** Callback on click */
-    onClick?: (item: EventPayload) => void;
-    /** Action used by generated code - alternative to event */
-    action?: EventKey;
-    /** 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 DisplayStateProps {
-    /** Entity data (single record or collection). */
-    entity?: EntityRow | readonly EntityRow[];
-    /** 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/core/organisms/ChatBar.d.ts

@@ -1,31 +0,0 @@
-/**
- * ChatBar Organism
- *
- * The always-visible bottom chat bar. A single-row input surface for talking
- * to the agent: status icon, optional context badge, text input, and a
- * status-driven action button (Send / Pause+Stop / Resume / Retry).
- *
- * The agent's activity stream lives in the dedicated Trace tab (see
- * SubagentTracePanel). ChatBar emits generic EventBus events
- * (`UI:CHAT_SEND`, `UI:ELEMENT_SELECTED`, plus the declarative `UI:*` actions
- * the Button atom raises) — it owns no app-specific state.
- */
-import React from 'react';
-import type { DisplayStateProps } from './types';
-export type ChatBarStatus = 'idle' | 'running' | 'paused' | 'complete' | 'error';
-export interface ChatBarProps extends DisplayStateProps {
-    /** Pipeline status */
-    status?: ChatBarStatus;
-    /** Currently active gate label, e.g. "Gate 2: State machines" */
-    activeGate?: string;
-    /** JEPA validity probability 0-1 */
-    jepaValidity?: number;
-    /** Input placeholder text */
-    placeholder?: string;
-    /** Agent context description */
-    context?: string;
-}
-export declare function ChatBar({ status, activeGate, jepaValidity, placeholder, context, className, }: ChatBarProps): React.ReactElement;
-export declare namespace ChatBar {
-    var displayName: string;
-}

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

@@ -1,42 +0,0 @@
-/**
- * CodeRunnerPanel Organism Component
- *
- * Editable code block with Run/Reset buttons and simulated terminal output.
- * Real execution is a future concern; callers supply a simulation function via
- * `onRun`. Emits `UI:RUN_CODE { language, exitCode }` on every run attempt.
- *
- * Event Contract:
- * - Emits: UI:RUN_CODE { language, exitCode, error? }
- * - entityAware: false
- */
-import React from 'react';
-export interface CodeSimulationOutput {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-    testResults: Array<{
-        input: string;
-        expectedOutput: string;
-        actualOutput: string;
-        passed: boolean;
-    }>;
-}
-export interface CodeRunnerPanelProps {
-    /** Initial code content */
-    code: string;
-    /** Programming language for syntax highlighting */
-    language: string;
-    /** Whether the panel allows running (false = read-only code block) */
-    runnable?: boolean;
-    /**
-     * Simulate executing the code. Omit to render a read-only block.
-     * Real execution is a separate future track — this callback supplies
-     * deterministic simulated output for UI feedback.
-     */
-    onRun?: (code: string) => Promise<CodeSimulationOutput>;
-    /** Event name to emit on run (emitted as `UI:<runEvent>`). Defaults to 'RUN_CODE'. */
-    runEvent?: string;
-    /** Additional CSS classes */
-    className?: string;
-}
-export declare const CodeRunnerPanel: React.FC<CodeRunnerPanelProps>;

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

@@ -1,185 +0,0 @@
-/**
- * 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 {};