@almadar/ui 2.45.0 → 2.46.1

package/dist/avl/index.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default from 'react';
-import { OrbitalSchema, UISlot, Expression } from '@almadar/core';
+import { OrbitalSchema, UISlot, Expression, EntityPersistence, EventPayloadField } from '@almadar/core';
 import { Node, Edge, NodeProps, EdgeProps } from '@xyflow/react';
 
 /**
@@ -851,6 +851,12 @@ interface PatternEventSource {
     path: string;
     /** Vertical position hint (0..1) for handle placement on the node. */
     positionHint: number;
+    /** Typed payload fields if this event carries data. */
+    payloadFields?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>;
 }
 /** A slot + pattern config pair extracted from a render-ui effect. */
 interface RenderUIEntry {
@@ -882,6 +888,8 @@ interface PreviewNodeData extends Record<string, unknown> {
      * to connect from the specific button/link to the target screen.
      */
     eventSources: PatternEventSource[];
+    /** Behavior layer for visual indicator (color band). */
+    layer?: string;
     /** State role for visual indicator. */
     stateRole?: 'initial' | 'terminal' | 'hub' | 'error' | 'default';
     /** All effect types on this transition (for overlay). */
@@ -938,7 +946,9 @@ interface EventEdgeData extends Record<string, unknown> {
  * 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[]>): {
+declare function schemaToOverviewGraph(schema: OrbitalSchema, mockData?: Record<string, unknown[]>, behaviorMeta?: Record<string, {
+    layer: string;
+}>, layoutHint?: 'pipeline' | 'grid'): {
     nodes: Node<PreviewNodeData>[];
     edges: Edge<EventEdgeData>[];
 };
@@ -980,6 +990,171 @@ declare const OrbPreviewNode: React__default.NamedExoticComponent<NodeProps>;
 
 declare const EventFlowEdge: React__default.NamedExoticComponent<EdgeProps>;
 
+/**
+ * AVL Behavior Compose Types
+ *
+ * Types for behavior-level composition canvas.
+ * At this level, each node represents a BEHAVIOR (not an orbital).
+ * A behavior is a higher-level unit: atom (1 orbital), molecule (1 orbital
+ * with composed traits), or organism (multiple orbitals).
+ *
+ * Three navigation levels:
+ *   Behavior (compose): One node per behavior showing AvlBehaviorGlyph
+ *   Overview: One node per orbital showing live UI (OrbPreviewNode)
+ *   Expanded: One node per UI state within an orbital (OrbPreviewNode)
+ */
+
+/** Extended view level adding 'behavior' to the existing overview/expanded. */
+type ComposeViewLevel = 'behavior' | 'overview' | 'expanded';
+/** An event that can be wired between behaviors. */
+interface ConnectableEvent {
+    /** Event name (e.g., "ADD_TO_CART"). */
+    event: string;
+    /** Typed payload fields if declared. */
+    payloadFields?: EventPayloadField[];
+    /** Vertical position hint (0..1) for handle placement on the node. */
+    positionHint: number;
+}
+/** Data for a BehaviorComposeNode in React Flow. */
+interface BehaviorComposeNodeData extends Record<string, unknown> {
+    /** Behavior name from registry (e.g., "std-cart"). */
+    behaviorName: string;
+    /** Composition level: atom, molecule, organism. */
+    level: BehaviorLevel;
+    /** Domain for color coding (e.g., "commerce"). */
+    domain?: string;
+    /** Layer classification (e.g., "Domain", "UI Patterns"). */
+    layer?: string;
+    /** Primary entity name (e.g., "CartItem"). */
+    entityName: string;
+    /** Number of states in the behavior. */
+    stateCount: number;
+    /** Number of entity fields. */
+    fieldCount?: number;
+    /** Persistence kind. */
+    persistence?: EntityPersistence;
+    /** Effect types used by this behavior. */
+    effectTypes?: AvlEffectType[];
+    /** Child behaviors for molecule/organism glyphs. */
+    children?: BehaviorGlyphChild[];
+    /** Connections between children (for organism glyphs). */
+    connections?: BehaviorGlyphConnection[];
+    /** Events this behavior can emit (source handles). */
+    connectableEvents: ConnectableEvent[];
+    /** Behaviors this is composable with (for palette hints). */
+    composableWith?: string[];
+    /** Names of orbitals produced by this behavior (for drill-down). */
+    orbitalNames: string[];
+}
+/** Edge data for behavior-level wiring. */
+interface BehaviorWireEdgeData extends Record<string, unknown> {
+    /** The event name displayed on the edge. */
+    event: string;
+    /** Source behavior name. */
+    sourceBehavior: string;
+    /** Target behavior name. */
+    targetBehavior: string;
+    /** Typed payload fields if declared. */
+    payloadFields?: EventPayloadField[];
+}
+/** Mapping from behavior name to its metadata + produced orbitals. */
+interface BehaviorCanvasEntry {
+    /** Behavior name (e.g., "std-cart"). */
+    behaviorName: string;
+    /** Composition level. */
+    level: BehaviorLevel;
+    /** Domain for color coding. */
+    domain?: string;
+    /** Layer classification. */
+    layer?: string;
+    /** Primary entity name. */
+    entityName: string;
+    /** Number of states. */
+    stateCount: number;
+    /** Number of entity fields. */
+    fieldCount?: number;
+    /** Persistence kind. */
+    persistence?: EntityPersistence;
+    /** Effect types used. */
+    effectTypes?: AvlEffectType[];
+    /** Child behaviors (molecule/organism). */
+    children?: BehaviorGlyphChild[];
+    /** Connections between children (organism). */
+    connections?: BehaviorGlyphConnection[];
+    /** Events available for wiring. */
+    connectableEvents: ConnectableEvent[];
+    /** Compatible behavior names. */
+    composableWith?: string[];
+    /** Orbital names produced by this behavior (for drill-down mapping). */
+    orbitalNames: string[];
+}
+
+/**
+ * BehaviorComposeNode
+ *
+ * React Flow custom node for behavior-level composition.
+ * Shows AvlBehaviorGlyph instead of live UI (OrbPreview).
+ * Each behavior is one compact node with event handles for wiring.
+ *
+ * This is the compose-level node. Double-clicking drills into
+ * the orbital-level view (OrbPreviewNode).
+ */
+
+declare const BehaviorComposeNode: React__default.NamedExoticComponent<NodeProps>;
+
+/**
+ * AVL Behavior Compose Converter
+ *
+ * Converts BehaviorCanvasEntry[] to React Flow nodes and edges
+ * for the behavior-level composition canvas.
+ *
+ * Parallel to avl-preview-converter.ts which works at the orbital level.
+ * This works one level higher: each node is a behavior (not an orbital).
+ */
+
+/**
+ * Build a React Flow graph for behavior-level composition.
+ * Each behavior entry becomes one BehaviorComposeNode.
+ */
+declare function behaviorsToComposeGraph(entries: BehaviorCanvasEntry[], wires: BehaviorWireEdgeData[], layoutHint?: 'pipeline' | 'grid'): {
+    nodes: Node<BehaviorComposeNodeData>[];
+    edges: Edge<BehaviorWireEdgeData>[];
+};
+/** Registry record shape (matches behaviors-registry.json entries). */
+interface BehaviorRegistryRecord {
+    name: string;
+    level: 'atom' | 'molecule' | 'organism';
+    family: string;
+    layer: string;
+    description: string;
+    complexity: {
+        states: number;
+        events: number;
+        transitions: number;
+    };
+    defaultEntity: {
+        name: string;
+        persistence?: string;
+        fields: Array<{
+            name: string;
+            type: string;
+            required?: boolean;
+        }>;
+    };
+    connectableEvents: string[];
+    eventPayloads: Record<string, Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>>;
+    composableWith: string[];
+}
+/**
+ * Convert a registry entry to a BehaviorCanvasEntry.
+ * Maps connectableEvents + eventPayloads into typed ConnectableEvent[].
+ */
+declare function registryEntryToCanvasEntry(entry: BehaviorRegistryRecord, orbitalNames: string[]): BehaviorCanvasEntry;
+
 /**
  * OrbInspector
  *
@@ -1057,6 +1232,20 @@ interface FlowCanvasProps {
         sourceTraitName?: string;
         targetTraitName?: string;
     }) => void;
+    /** Behavior layer metadata for node styling (layer color bands). */
+    behaviorMeta?: Record<string, {
+        layer: string;
+    }>;
+    /** Layout hint: 'pipeline' renders nodes left-to-right, 'grid' (default) uses sqrt-based grid. */
+    layoutHint?: 'pipeline' | 'grid';
+    /** Called when the user clicks a node in overview level (for composition hints). */
+    onNodeSelect?: (orbitalName: string) => void;
+    /** When 'behavior', shows behavior-level glyph nodes instead of orbital previews. */
+    composeLevel?: ComposeViewLevel;
+    /** Behavior entries for compose mode (only when composeLevel='behavior'). */
+    behaviorEntries?: BehaviorCanvasEntry[];
+    /** Event wires between behaviors (only when composeLevel='behavior'). */
+    behaviorWires?: BehaviorWireEdgeData[];
     /** @deprecated Use onNodeClick instead. Kept for AvlCosmicZoom compat. */
     onZoomChange?: (level: string, context: Record<string, string | undefined>) => void;
     /** @deprecated Not used in V3. */
@@ -1213,4 +1402,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, type EventEdgeData, EventFlowEdge, FlowCanvas, type FlowCanvasProps, type GlyphSize, type LayoutEdge, type LayoutNode, MiniStateMachine, ModuleCard, OrbInspector, type OrbInspectorProps, 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 };
+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 BehaviorCanvasEntry, BehaviorComposeNode, type BehaviorComposeNodeData, type BehaviorGlyphChild, type BehaviorGlyphConnection, type BehaviorLevel, type BehaviorRegistryRecord, BehaviorView, type BehaviorWireEdgeData, CONNECTION_COLORS, type ComposeViewLevel, type ConnectableEvent, 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, OrbInspector, type OrbInspectorProps, 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, behaviorsToComposeGraph, computeTraitLayout, computeZoomBand, curveControlPoint, edgePath, getStateRole, gridPositions, orbitalToExpandedGraph, parseApplicationLevel, parseOrbitalLevel, parseTraitLevel, parseTransitionLevel, radialPositions, registryEntryToCanvasEntry, ringPositions, schemaToFlowGraph, schemaToOverviewGraph, useZoomBand, zoomProgress };

package/dist/avl/index.d.ts

@@ -55,5 +55,8 @@ export { type ViewLevel, type PreviewNodeData, type EventEdgeData, type PatternE
 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 { type ComposeViewLevel, type BehaviorComposeNodeData, type BehaviorWireEdgeData, type BehaviorCanvasEntry, type ConnectableEvent } from '../components/molecules/avl/avl-behavior-compose-types';
+export { BehaviorComposeNode } from '../components/molecules/avl/BehaviorComposeNode';
+export { behaviorsToComposeGraph, registryEntryToCanvasEntry, type BehaviorRegistryRecord } from '../components/molecules/avl/avl-behavior-compose-converter';
 export { OrbInspector, type OrbInspectorProps } from '../components/organisms/avl/OrbInspector';
 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';