@almadar/ui 2.34.2 → 2.35.0

package/dist/avl/index.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default from 'react';
-import { OrbitalSchema } from '@almadar/core';
+import { OrbitalSchema, UISlot, Expression } from '@almadar/core';
 import { Node, Edge, NodeProps, EdgeProps } from '@xyflow/react';
 
 /**
@@ -820,43 +820,209 @@ declare const AvlPageEdge: React__default.FC<EdgeProps>;
 declare const AvlBindingEdge: React__default.FC<EdgeProps>;
 
 /**
- * AVL Cosmic Zoom State Machine
+ * AVL Preview Types
  *
- * useReducer-based state machine managing which zoom level is displayed,
- * what is selected, and animation state.
+ * Types for the V3 FlowCanvas: UI projection mode.
+ * Nodes show rendered UI thumbnails, edges show events.
+ * Two levels: overview (one node per orbital) and expanded (one node per UI state).
  *
- * @packageDocumentation
+ * Uses @almadar/core types for schema-level constructs.
  */
-type ZoomLevel = 'application' | 'orbital' | 'trait' | 'transition';
+
+/** The two navigation levels of the FlowCanvas. */
+type ViewLevel = 'overview' | 'expanded';
+/**
+ * An interactive element inside a render-ui pattern that fires an event.
+ * For example, a button with `event: "CHECKOUT"` is an event source.
+ * These are used to draw edges from the specific trigger element to the
+ * target screen, making the prototype flow concrete.
+ */
+interface PatternEventSource {
+    /** The event name fired by this element (e.g., "CHECKOUT"). */
+    event: string;
+    /** The pattern type of the trigger element (e.g., "button", "link", "icon-button"). */
+    patternType: string;
+    /** Human label if available (e.g., "Checkout", "Submit"). */
+    label?: string;
+    /**
+     * Path within the pattern tree (e.g., "children.2" means third child).
+     * Used to position the handle near the trigger element.
+     */
+    path: string;
+    /** Vertical position hint (0..1) for handle placement on the node. */
+    positionHint: number;
+}
+/** A slot + pattern config pair extracted from a render-ui effect. */
+interface RenderUIEntry {
+    slot: UISlot | string;
+    pattern: Record<string, unknown>;
+}
+/** Data for a preview node (used at both overview and expanded levels). */
+interface PreviewNodeData extends Record<string, unknown> {
+    /** Orbital this node belongs to. */
+    orbitalName: string;
+    /** Trait name (only at expanded level). */
+    traitName?: string;
+    /** State name after this transition fires (expanded level). */
+    stateName?: string;
+    /** Event that triggers this transition (expanded level). */
+    transitionEvent?: string;
+    /** From state (expanded level). */
+    fromState?: string;
+    /** To state (expanded level). */
+    toState?: string;
+    /**
+     * Render-ui patterns extracted from the transition's effects.
+     * Each entry is a slot + pattern config pair.
+     */
+    patterns: RenderUIEntry[];
+    /**
+     * Interactive elements within the patterns that fire events.
+     * Each one becomes a source handle on the node, allowing edges
+     * to connect from the specific button/link to the target screen.
+     */
+    eventSources: PatternEventSource[];
+    /** State role for visual indicator. */
+    stateRole?: 'initial' | 'terminal' | 'hub' | 'error' | 'default';
+    /** All effect types on this transition (for overlay). */
+    effectTypes?: string[];
+    /** Guard expression (for overlay). */
+    guard?: Expression | null;
+    entityName?: string;
+    persistence?: string;
+    fieldCount?: number;
+    traitCount?: number;
+    pageRoutes?: string[];
+}
+/** Data for event flow edges. */
+interface EventEdgeData extends Record<string, unknown> {
+    /** The event name displayed on the edge. */
+    event: string;
+    /** Source state name (expanded level). */
+    fromState?: string;
+    /** Target state name (expanded level). */
+    toState?: string;
+    /** Whether this is a backward/retry transition. */
+    isBackward?: boolean;
+    /** Whether this is a cross-orbital event wire (overview level). */
+    isCrossOrbital?: boolean;
+    /** Source trait (for cross-orbital wires). */
+    fromTrait?: string;
+    /** Target trait (for cross-orbital wires). */
+    toTrait?: string;
+    /**
+     * The pattern type that triggers this event (e.g., "button").
+     * Displayed on the edge label for context.
+     */
+    triggerPatternType?: string;
+    /** The trigger element's label (e.g., "Checkout"). */
+    triggerLabel?: string;
+}
+
+/**
+ * AVL Preview Converter
+ *
+ * Extracts render-ui pattern configs from OrbitalSchema transitions
+ * and builds React Flow graphs for the two FlowCanvas levels:
+ *   - Overview: one node per orbital (INIT transition UI)
+ *   - Expanded: one node per UI state within an orbital
+ *
+ * Key feature: detects interactive elements (buttons, links) inside
+ * patterns that fire events. These become per-element source handles
+ * so edges connect from the specific trigger element to the target screen.
+ *
+ * Uses @almadar/core types for schema-level constructs.
+ */
+
+/**
+ * Build a React Flow graph for the overview level.
+ * Each orbital gets one node showing its INIT transition's UI.
+ */
+declare function schemaToOverviewGraph(schema: OrbitalSchema, mockData?: Record<string, unknown[]>): {
+    nodes: Node<PreviewNodeData>[];
+    edges: Edge<EventEdgeData>[];
+};
+/**
+ * Build a React Flow graph for the expanded level.
+ * Each transition with a render-ui effect gets a node.
+ * Edges connect from the specific button/pattern that fires the event
+ * to the target screen node.
+ */
+declare function orbitalToExpandedGraph(schema: OrbitalSchema, orbitalName: string, mockData?: Record<string, unknown[]>): {
+    nodes: Node<PreviewNodeData>[];
+    edges: Edge<EventEdgeData>[];
+};
 
 /**
- * FlowCanvas — Unified AVL + Flow canvas organism.
+ * OrbPreviewNode
  *
- * One React Flow canvas with continuous semantic zoom. AVL primitives
- * render inside React Flow nodes. The ZoomBandContext drives node
- * rendering at different zoom levels.
+ * React Flow node that renders a real OrbPreview inside it.
+ * The canvas is always live and editable (like Figma). Clicking any
+ * rendered UI element selects its pattern and shows props in the
+ * TransitionPanel. No edit mode toggle needed.
  *
- * Replaces both AvlCosmicZoom (SVG viewer) and OrbitalFlow (Flow editor).
+ * The header is the drag handle for React Flow. The content area
+ * passes clicks through to the pattern elements.
+ */
+
+declare const OrbPreviewNode: React__default.NamedExoticComponent<NodeProps>;
+
+/**
+ * EventFlowEdge
+ *
+ * React Flow edge for the V3 FlowCanvas. Shows the event name and
+ * optionally the trigger element (button label) that fires it.
+ *
+ * When the edge originates from a specific event source handle,
+ * the label shows "Button Label \u2192 EVENT" to make the connection
+ * between UI element and transition clear.
+ */
+
+declare const EventFlowEdge: React__default.NamedExoticComponent<EdgeProps>;
+
+/**
+ * FlowCanvas — V3 UI Projection Canvas
+ *
+ * The canvas IS the app. Nodes show rendered UI thumbnails from
+ * render-ui effects. Edges show events connecting screens.
+ *
+ * Two navigation levels:
+ *   Level 1 (Overview): One node per orbital showing INIT UI
+ *   Level 2 (Expanded): One node per UI state within an orbital
+ *
+ * Double-click to expand an orbital. Click a node for code callback.
+ * Escape to go back. AVL overlays on hover (future).
  */
 
 interface FlowCanvasProps {
     schema: OrbitalSchema | string;
+    mockData?: Record<string, unknown[]>;
     className?: string;
-    color?: string;
-    animated?: boolean;
     width?: number | string;
     height?: number | string;
-    onZoomChange?: (level: ZoomLevel, context: {
-        orbital?: string;
+    onNodeClick?: (context: {
+        level: ViewLevel | 'code';
+        orbital: string;
         trait?: string;
+        transition?: string;
     }) => void;
+    onLevelChange?: (level: ViewLevel, orbital?: string) => void;
+    initialOrbital?: string;
+    /** @deprecated Use onNodeClick instead. Kept for AvlCosmicZoom compat. */
+    onZoomChange?: (level: string, context: Record<string, string | undefined>) => void;
+    /** @deprecated Not used in V3. */
     focusTarget?: {
-        type: 'orbital' | 'trait';
+        type: string;
         name: string;
     };
-    initialOrbital?: string;
+    /** @deprecated Not used in V3. */
+    color?: string;
+    /** @deprecated Not used in V3. */
+    animated?: boolean;
+    /** @deprecated Not used in V3. */
     initialTrait?: string;
-    stateCoverage?: Record<string, 'covered' | 'uncovered' | 'partial'>;
+    /** @deprecated Not used in V3. */
+    stateCoverage?: Record<string, string>;
 }
 declare const FlowCanvas: React__default.FC<FlowCanvasProps>;
 
@@ -887,11 +1053,21 @@ interface ZoomLegendProps {
 declare const ZoomLegend: React__default.FC<ZoomLegendProps>;
 
 /**
- * AvlCosmicZoom — Interactive Zoomable Orbital Visualization
+ * AVL Cosmic Zoom State Machine
+ *
+ * useReducer-based state machine managing which zoom level is displayed,
+ * what is selected, and animation state.
+ *
+ * @packageDocumentation
+ */
+type ZoomLevel = 'application' | 'orbital' | 'trait' | 'transition';
+
+/**
+ * AvlCosmicZoom — Interactive Orbital Visualization
  *
- * V3: Delegates to FlowCanvas, which renders AVL primitives inside
- * React Flow nodes with continuous semantic zoom. The Props interface
- * is preserved for backward compatibility with callers.
+ * V3: Delegates to FlowCanvas. Nodes are live OrbPreview renders
+ * of each orbital/transition. Two-level navigation (overview + expanded).
+ * Props interface preserved for backward compatibility with callers.
  */
 
 interface AvlCosmicZoomProps {
@@ -988,4 +1164,4 @@ interface AvlClickTargetProps {
 }
 declare const AvlClickTarget: React__default.FC<AvlClickTargetProps>;
 
-export { AVL_FIELD_TYPE_SHAPES, AVL_OPERATOR_COLORS, type ApplicationLevelData, AvlApplication, type AvlApplicationProps, AvlBackwardEdge, type AvlBaseProps, AvlBehaviorGlyph, type AvlBehaviorGlyphProps, AvlBinding, AvlBindingEdge, type AvlBindingProps, AvlBindingRef, type AvlBindingRefProps, AvlClickTarget, type AvlClickTargetProps, AvlClosedCircuit, type AvlClosedCircuitProps, type AvlClosedCircuitState, type AvlClosedCircuitTransition, AvlCosmicZoom, type AvlCosmicZoomProps, type AvlEdgeData, AvlEffect, type AvlEffectProps, type AvlEffectType, AvlEmitListen, type AvlEmitListenProps, AvlEntity, type AvlEntityProps, AvlEvent, type AvlEventProps, AvlEventWireEdge, type AvlEventWireEdgeData, AvlExprTree, type AvlExprTreeNode, type AvlExprTreeProps, AvlField, type AvlFieldProps, AvlFieldType, type AvlFieldTypeKind, type AvlFieldTypeProps, AvlGuard, type AvlGuardProps, AvlLiteral, type AvlLiteralProps, type AvlNodeData, AvlOperator, type AvlOperatorNamespace, type AvlOperatorProps, AvlOrbital, AvlOrbitalNode, type AvlOrbitalProps, AvlOrbitalUnit, type AvlOrbitalUnitPage, type AvlOrbitalUnitProps, type AvlOrbitalUnitTrait, AvlPage, AvlPageEdge, type AvlPageProps, AvlPersistence, type AvlPersistenceKind, type AvlPersistenceProps, AvlSExpr, type AvlSExprProps, AvlSlotMap, type AvlSlotMapProps, type AvlSlotMapSlot, AvlState, AvlStateMachine, type AvlStateMachineProps, type AvlStateMachineState, type AvlStateMachineTransition, type AvlStateProps, AvlSwimLane, type AvlSwimLaneProps, AvlTrait, type AvlTraitProps, AvlTraitScene, type AvlTraitSceneProps, AvlTransition, AvlTransitionEdge, type AvlTransitionEdgeData, AvlTransitionLane, type AvlTransitionLaneProps, type AvlTransitionProps, AvlTransitionScene, type AvlTransitionSceneProps, type BehaviorGlyphChild, type BehaviorGlyphConnection, type BehaviorLevel, BehaviorView, CONNECTION_COLORS, type CrossLink, DOMAIN_COLORS, DetailView, EFFECT_CATEGORY_COLORS, EFFECT_TYPE_TO_CATEGORY, type EffectCategory, type ElkLayout, FlowCanvas, type FlowCanvasProps, type GlyphSize, type LayoutEdge, type LayoutNode, MiniStateMachine, ModuleCard, type OrbitalLevelData, STATE_COLORS, type StateRole, SystemNode, type TraitLevelData, type TransitionLevelData, ZOOM_BAND_THRESHOLDS, type ZoomBand, ZoomBandContext, ZoomBreadcrumb, type ZoomBreadcrumbProps, ZoomLegend, type ZoomLegendProps, type ZoomLevel, arcPath, computeTraitLayout, computeZoomBand, curveControlPoint, edgePath, getStateRole, gridPositions, parseApplicationLevel, parseOrbitalLevel, parseTraitLevel, parseTransitionLevel, radialPositions, ringPositions, schemaToFlowGraph, useZoomBand, zoomProgress };
+export { AVL_FIELD_TYPE_SHAPES, AVL_OPERATOR_COLORS, type ApplicationLevelData, AvlApplication, type AvlApplicationProps, AvlBackwardEdge, type AvlBaseProps, AvlBehaviorGlyph, type AvlBehaviorGlyphProps, AvlBinding, AvlBindingEdge, type AvlBindingProps, AvlBindingRef, type AvlBindingRefProps, AvlClickTarget, type AvlClickTargetProps, AvlClosedCircuit, type AvlClosedCircuitProps, type AvlClosedCircuitState, type AvlClosedCircuitTransition, AvlCosmicZoom, type AvlCosmicZoomProps, type AvlEdgeData, AvlEffect, type AvlEffectProps, type AvlEffectType, AvlEmitListen, type AvlEmitListenProps, AvlEntity, type AvlEntityProps, AvlEvent, type AvlEventProps, AvlEventWireEdge, type AvlEventWireEdgeData, AvlExprTree, type AvlExprTreeNode, type AvlExprTreeProps, AvlField, type AvlFieldProps, AvlFieldType, type AvlFieldTypeKind, type AvlFieldTypeProps, AvlGuard, type AvlGuardProps, AvlLiteral, type AvlLiteralProps, type AvlNodeData, AvlOperator, type AvlOperatorNamespace, type AvlOperatorProps, AvlOrbital, AvlOrbitalNode, type AvlOrbitalProps, AvlOrbitalUnit, type AvlOrbitalUnitPage, type AvlOrbitalUnitProps, type AvlOrbitalUnitTrait, AvlPage, AvlPageEdge, type AvlPageProps, AvlPersistence, type AvlPersistenceKind, type AvlPersistenceProps, AvlSExpr, type AvlSExprProps, AvlSlotMap, type AvlSlotMapProps, type AvlSlotMapSlot, AvlState, AvlStateMachine, type AvlStateMachineProps, type AvlStateMachineState, type AvlStateMachineTransition, type AvlStateProps, AvlSwimLane, type AvlSwimLaneProps, AvlTrait, type AvlTraitProps, AvlTraitScene, type AvlTraitSceneProps, AvlTransition, AvlTransitionEdge, type AvlTransitionEdgeData, AvlTransitionLane, type AvlTransitionLaneProps, type AvlTransitionProps, AvlTransitionScene, type AvlTransitionSceneProps, type BehaviorGlyphChild, type BehaviorGlyphConnection, type BehaviorLevel, BehaviorView, CONNECTION_COLORS, type CrossLink, DOMAIN_COLORS, DetailView, EFFECT_CATEGORY_COLORS, EFFECT_TYPE_TO_CATEGORY, type EffectCategory, type ElkLayout, type EventEdgeData, EventFlowEdge, FlowCanvas, type FlowCanvasProps, type GlyphSize, type LayoutEdge, type LayoutNode, MiniStateMachine, ModuleCard, OrbPreviewNode, type OrbitalLevelData, type PatternEventSource, type PreviewNodeData, type RenderUIEntry, STATE_COLORS, type StateRole, SystemNode, type TraitLevelData, type TransitionLevelData, type ViewLevel, ZOOM_BAND_THRESHOLDS, type ZoomBand, ZoomBandContext, ZoomBreadcrumb, type ZoomBreadcrumbProps, ZoomLegend, type ZoomLegendProps, type ZoomLevel, arcPath, computeTraitLayout, computeZoomBand, curveControlPoint, edgePath, getStateRole, gridPositions, orbitalToExpandedGraph, parseApplicationLevel, parseOrbitalLevel, parseTraitLevel, parseTransitionLevel, radialPositions, ringPositions, schemaToFlowGraph, schemaToOverviewGraph, useZoomBand, zoomProgress };

package/dist/avl/index.d.ts

@@ -51,4 +51,8 @@ export { AvlBackwardEdge } from '../components/molecules/avl/AvlBackwardEdge';
 export { AvlPageEdge } from '../components/molecules/avl/AvlPageEdge';
 export { AvlBindingEdge } from '../components/molecules/avl/AvlBindingEdge';
 export { computeTraitLayout, edgePath, type LayoutNode, type LayoutEdge, type ElkLayout } from '../components/molecules/avl/avl-elk-layout';
+export { type ViewLevel, type PreviewNodeData, type EventEdgeData, type PatternEventSource, type RenderUIEntry } from '../components/molecules/avl/avl-preview-types';
+export { schemaToOverviewGraph, orbitalToExpandedGraph } from '../components/molecules/avl/avl-preview-converter';
+export { OrbPreviewNode } from '../components/molecules/avl/OrbPreviewNode';
+export { EventFlowEdge } from '../components/molecules/avl/EventFlowEdge';
 export { FlowCanvas, type FlowCanvasProps, ZoomBreadcrumb, type ZoomBreadcrumbProps, ZoomLegend, type ZoomLegendProps, AvlCosmicZoom, type AvlCosmicZoomProps, AvlTraitScene, type AvlTraitSceneProps, AvlTransitionScene, type AvlTransitionSceneProps, AvlClickTarget, type AvlClickTargetProps, parseApplicationLevel, parseOrbitalLevel, parseTraitLevel, parseTransitionLevel, type ApplicationLevelData, type OrbitalLevelData, type TraitLevelData, type TransitionLevelData, type CrossLink, type ZoomLevel, } from '../components/organisms/avl';