@almadar/ui 2.32.0 → 2.34.0

package/dist/components/molecules/avl/AvlBackwardEdge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AvlBackwardEdge — Dashed backward/retry transition edge.
+ *
+ * Uses CONNECTION_COLORS.backward styling: dashed, lighter color.
+ */
+import React from 'react';
+import { type EdgeProps } from '@xyflow/react';
+export declare const AvlBackwardEdge: React.FC<EdgeProps>;

package/dist/components/molecules/avl/AvlBindingEdge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AvlBindingEdge — Dotted violet binding edge with @ marker.
+ *
+ * Used for data binding connections. Dotted line at 1px with
+ * a small @ label at the midpoint.
+ */
+import React from 'react';
+import { type EdgeProps } from '@xyflow/react';
+export declare const AvlBindingEdge: React.FC<EdgeProps>;

package/dist/components/molecules/avl/AvlEventWireEdge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AvlEventWireEdge — React Flow edge for emit/listen event wiring.
+ *
+ * Dashed orange Bezier path with event name label at midpoint.
+ * Uses AVL CONNECTION_COLORS.emitListen styling.
+ */
+import React from 'react';
+import { type Edge, type EdgeProps } from '@xyflow/react';
+export interface AvlEventWireEdgeData extends Record<string, unknown> {
+    event: string;
+    compatible?: boolean;
+}
+export type AvlEventWireFlowEdge = Edge<AvlEventWireEdgeData, 'eventWire'>;
+export declare const AvlEventWireEdge: React.FC<EdgeProps<AvlEventWireFlowEdge>>;

package/dist/components/molecules/avl/AvlOrbitalNode.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AvlOrbitalNode — Single React Flow node type for the unified AVL canvas.
+ *
+ * Reads the current ZoomBand from context and renders the appropriate
+ * sub-component: SystemNode, ModuleCard, BehaviorView, or DetailView.
+ *
+ * Using a single node type (instead of switching types per zoom band)
+ * prevents React from unmounting/remounting nodes on zoom changes.
+ */
+import React from 'react';
+import type { NodeProps } from '@xyflow/react';
+export declare const AvlOrbitalNode: React.FC<NodeProps>;

package/dist/components/molecules/avl/AvlPageEdge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AvlPageEdge — Thin solid page-reference edge.
+ *
+ * Slate colored, 1px, used for page-to-trait references.
+ */
+import React from 'react';
+import { type EdgeProps } from '@xyflow/react';
+export declare const AvlPageEdge: React.FC<EdgeProps>;

package/dist/components/molecules/avl/AvlTransitionEdge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AvlTransitionEdge — React Flow edge for state machine transitions.
+ *
+ * Bezier path with event label at midpoint. Guard diamond and effect
+ * dot indicators shown inline. Forward transitions are solid dark,
+ * backward transitions are dashed lighter.
+ */
+import React from 'react';
+import { type Edge, type EdgeProps } from '@xyflow/react';
+export interface AvlTransitionEdgeData extends Record<string, unknown> {
+    event: string;
+    hasGuard?: boolean;
+    hasEffects?: boolean;
+}
+export type AvlTransitionFlowEdge = Edge<AvlTransitionEdgeData, 'transition'>;
+export declare const AvlTransitionEdge: React.FC<EdgeProps<AvlTransitionFlowEdge>>;

package/dist/components/molecules/avl/BehaviorView.d.ts

@@ -0,0 +1,12 @@
+/**
+ * BehaviorView — Full state machine for the behavior zoom band (1.0x-2.5x).
+ *
+ * Uses ELK layout from avl-elk-layout.ts. Renders AvlState, AvlTransitionLane,
+ * and AvlSwimLane inside an inline SVG within a React Flow node.
+ */
+import React from 'react';
+import type { AvlNodeData } from './avl-canvas-types';
+export interface BehaviorViewProps {
+    data: AvlNodeData;
+}
+export declare const BehaviorView: React.FC<BehaviorViewProps>;

package/dist/components/molecules/avl/DetailView.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DetailView — Transition specification card for the detail zoom band (2.5x-5.0x).
+ *
+ * Renders a spec card with: from/to AvlState nodes, AvlEvent trigger,
+ * AvlGuard diamond, numbered AvlEffect icons with binding paths,
+ * and AvlFieldType shapes.
+ */
+import React from 'react';
+import type { AvlNodeData } from './avl-canvas-types';
+export interface DetailViewProps {
+    data: AvlNodeData;
+}
+export declare const DetailView: React.FC<DetailViewProps>;

package/dist/components/molecules/avl/MiniStateMachine.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MiniStateMachine — Inline simplified state machine for the ModuleCard.
+ *
+ * Renders a compact left-to-right flow of AvlState nodes connected
+ * by AvlTransition arrows, with AvlEffect icons below.
+ * No ELK layout needed — uses simple horizontal positioning.
+ */
+import React from 'react';
+import type { TraitLevelData } from '../../organisms/avl/avl-schema-parser';
+export interface MiniStateMachineProps {
+    data: TraitLevelData;
+    className?: string;
+}
+export declare const MiniStateMachine: React.FC<MiniStateMachineProps>;

package/dist/components/molecules/avl/ModuleCard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ModuleCard — Structured card for the module zoom band (0.4x-1.0x).
+ *
+ * Renders AVL primitives inside a card container:
+ * - Entity section: AvlEntity glyph + AvlPersistence + AvlFieldType grid
+ * - Trait sections: MiniStateMachine per trait + AvlEffect icons + emit/listen indicators
+ * - Pages section: AvlPage squares with route labels
+ */
+import React from 'react';
+import type { AvlNodeData } from './avl-canvas-types';
+export interface ModuleCardProps {
+    data: AvlNodeData;
+}
+export declare const ModuleCard: React.FC<ModuleCardProps>;

package/dist/components/molecules/avl/SystemNode.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SystemNode — Compact orbital node for the system zoom band (0.1x-0.4x).
+ *
+ * Renders miniature AVL primitives: entity glyph, field-type dots,
+ * state chain (role-colored dots), and page squares.
+ */
+import React from 'react';
+import type { AvlNodeData } from './avl-canvas-types';
+export interface SystemNodeProps {
+    data: AvlNodeData;
+}
+export declare const SystemNode: React.FC<SystemNodeProps>;

package/dist/components/molecules/avl/avl-canvas-types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AVL Canvas Types
+ *
+ * Types for the unified AVL + Flow canvas. These define the data shapes
+ * for React Flow nodes and edges that render AVL primitives.
+ */
+import type { FieldInfo, OrbitalTraitInfo, OrbitalPageInfo, ExternalLink, TraitLevelData } from '../../organisms/avl/avl-schema-parser';
+/** The four zoom bands of the unified AVL canvas. */
+export type ZoomBand = 'system' | 'module' | 'behavior' | 'detail';
+/** Thresholds for zoom band transitions (React Flow viewport zoom). */
+export declare const ZOOM_BAND_THRESHOLDS: {
+    readonly system: readonly [0.1, 0.4];
+    readonly module: readonly [0.4, 1];
+    readonly behavior: readonly [1, 2.5];
+    readonly detail: readonly [2.5, 5];
+};
+/** Data carried by every orbital node in the unified canvas. */
+export interface AvlNodeData extends Record<string, unknown> {
+    orbitalName: string;
+    entityName: string;
+    persistence: string;
+    fields: FieldInfo[];
+    traits: OrbitalTraitInfo[];
+    pages: OrbitalPageInfo[];
+    traitDetails: Record<string, TraitLevelData>;
+    externalLinks: ExternalLink[];
+}
+/** Edge kind determines visual style. */
+export type AvlEdgeKind = 'eventWire' | 'page';
+/** Data carried by edges in the unified canvas. */
+export interface AvlEdgeData extends Record<string, unknown> {
+    edgeKind: AvlEdgeKind;
+    event?: string;
+    fromTrait?: string;
+    toTrait?: string;
+}

package/dist/components/molecules/avl/avl-elk-layout.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AVL ELK Layout
+ *
+ * Shared ELK-based layout engine for state machines. Extracted from
+ * AvlTraitScene so both the V2 scene renderer and the V3 BehaviorView
+ * can share the same layout computation.
+ */
+import { type StateRole } from '../../atoms/avl/types';
+import type { TraitLevelData } from '../../organisms/avl/avl-schema-parser';
+export interface LayoutNode {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+    role: StateRole;
+    transitionCount: number;
+}
+export interface LayoutEdge {
+    id: string;
+    from: string;
+    to: string;
+    event: string;
+    effects: Array<{
+        type: string;
+    }>;
+    guard: boolean;
+    guardExpr?: string;
+    index: number;
+    labelX: number;
+    labelY: number;
+    labelW: number;
+    labelH: number;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    isSelf: boolean;
+    isBackward: boolean;
+}
+export interface ElkLayout {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    width: number;
+    height: number;
+}
+export declare function stateWidth(transitionCount: number): number;
+export declare const STATE_H = 40;
+export declare function computeTraitLayout(data: TraitLevelData): Promise<ElkLayout>;
+export declare function edgePath(points: Array<{
+    x: number;
+    y: number;
+}>): string;

package/dist/components/molecules/avl/avl-flow-converter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AVL Flow Converter
+ *
+ * Converts an OrbitalSchema into React Flow nodes and edges
+ * for the unified AVL canvas. Reuses the existing AVL schema parser.
+ */
+import type { Node, Edge } from '@xyflow/react';
+import type { OrbitalSchema } from '@almadar/core';
+import type { AvlNodeData, AvlEdgeData } from './avl-canvas-types';
+/**
+ * Transform an OrbitalSchema into React Flow nodes and edges.
+ * Pre-parses all orbital and trait details for responsive zoom.
+ */
+export declare function schemaToFlowGraph(schema: OrbitalSchema): {
+    nodes: Node<AvlNodeData>[];
+    edges: Edge<AvlEdgeData>[];
+};

package/dist/components/molecules/avl/avl-story-schemas.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared test schemas for AVL V3 Storybook stories.
+ *
+ * Uses real behavior functions from @almadar/std to generate
+ * OrbitalSchemas with actual state machines, fields, and pages.
+ */
+import type { OrbitalSchema } from '@almadar/core';
+/**
+ * Clinic schema: 2 orbitals with real state machines.
+ * - PatientOrbital (std-wizard): multi-step form with 5 fields
+ * - QueueEntryOrbital (std-browse): data grid with 4 fields
+ */
+export declare const CLINIC_SCHEMA: OrbitalSchema;
+/**
+ * Task manager schema: 3 orbitals for a richer multi-module story.
+ * - TaskOrbital (std-browse): task list
+ * - TimerOrbital (std-timer): countdown timer
+ * - ArchiveOrbital (std-confirmation): archive confirmation
+ */
+export declare const TASK_SCHEMA: OrbitalSchema;
+/** Pre-computed React Flow graph for the clinic schema. */
+export declare const CLINIC_GRAPH: {
+    nodes: import("@xyflow/react").Node<import("./avl-canvas-types").AvlNodeData>[];
+    edges: import("@xyflow/react").Edge<import("./avl-canvas-types").AvlEdgeData>[];
+};
+/** Pre-computed React Flow graph for the task schema. */
+export declare const TASK_GRAPH: {
+    nodes: import("@xyflow/react").Node<import("./avl-canvas-types").AvlNodeData>[];
+    edges: import("@xyflow/react").Edge<import("./avl-canvas-types").AvlEdgeData>[];
+};
+/** First orbital's detail for ModuleCard/SystemNode stories. */
+export declare const CLINIC_FIRST_ORBITAL: import("../../organisms/avl").OrbitalLevelData | null;
+/** First trait detail for BehaviorView/DetailView stories. */
+export declare function getClinicFirstTrait(): import("../../organisms/avl").TraitLevelData | null;

package/dist/components/molecules/avl/avl-zoom-band.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AVL Zoom Band
+ *
+ * Continuous semantic zoom for the unified AVL canvas.
+ * React Flow nodes read the current zoom band from context
+ * and switch their rendering accordingly.
+ */
+import { type ZoomBand } from './avl-canvas-types';
+/** Determine which zoom band the current viewport zoom falls into. */
+export declare function computeZoomBand(zoom: number): ZoomBand;
+/**
+ * Compute progress (0..1) within a zoom band.
+ * Useful for crossfade transitions between bands.
+ */
+export declare function zoomProgress(zoom: number, band: ZoomBand): number;
+/** Context providing the current zoom band to all node components. */
+export declare const ZoomBandContext: import("react").Context<ZoomBand>;
+/** Hook to read the current zoom band. */
+export declare function useZoomBand(): ZoomBand;

package/dist/components/molecules/avl/index.d.ts

@@ -8,6 +8,21 @@ export { AvlTransitionLane, type AvlTransitionLaneProps, type AvlTransitionLaneE
 export { AvlSwimLane, type AvlSwimLaneProps } from './AvlSwimLane';
 export { AvlBehaviorGlyph, type AvlBehaviorGlyphProps, type BehaviorLevel, type GlyphSize, type BehaviorGlyphChild, type BehaviorGlyphConnection, DOMAIN_COLORS } from './AvlBehaviorGlyph';
 export { ringPositions, arcPath, radialPositions, gridPositions, curveControlPoint } from './avl-layout';
+export { type ZoomBand, type AvlNodeData, type AvlEdgeData, type AvlEdgeKind, ZOOM_BAND_THRESHOLDS } from './avl-canvas-types';
+export { computeZoomBand, zoomProgress, useZoomBand, ZoomBandContext } from './avl-zoom-band';
+export { schemaToFlowGraph } from './avl-flow-converter';
+export { computeTraitLayout, edgePath, stateWidth, STATE_H, type LayoutNode, type LayoutEdge, type ElkLayout } from './avl-elk-layout';
+export { SystemNode, type SystemNodeProps } from './SystemNode';
+export { MiniStateMachine, type MiniStateMachineProps } from './MiniStateMachine';
+export { ModuleCard, type ModuleCardProps } from './ModuleCard';
+export { BehaviorView, type BehaviorViewProps } from './BehaviorView';
+export { DetailView, type DetailViewProps } from './DetailView';
+export { AvlOrbitalNode } from './AvlOrbitalNode';
+export { AvlTransitionEdge, type AvlTransitionEdgeData, type AvlTransitionFlowEdge } from './AvlTransitionEdge';
+export { AvlEventWireEdge, type AvlEventWireEdgeData, type AvlEventWireFlowEdge } from './AvlEventWireEdge';
+export { AvlBackwardEdge } from './AvlBackwardEdge';
+export { AvlPageEdge } from './AvlPageEdge';
+export { AvlBindingEdge } from './AvlBindingEdge';
 export { Avl3DOrbitalNode, type Avl3DOrbitalNodeProps } from './Avl3DOrbitalNode';
 export { Avl3DCrossWire, type Avl3DCrossWireProps } from './Avl3DCrossWire';
 export { Avl3DEntityCore, type Avl3DEntityCoreProps } from './Avl3DEntityCore';

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

@@ -78,4 +78,3 @@ export { TeamCard, type TeamCardProps } from './TeamCard';
 export { ShowcaseCard, type ShowcaseCardProps } from './ShowcaseCard';
 export { GeometricPattern, type GeometricPatternProps } from './GeometricPattern';
 export { EdgeDecoration, type EdgeDecorationProps, type EdgeVariant, type EdgeSide } from './EdgeDecoration';
-export * from './flow';

package/dist/components/organisms/avl/AvlCosmicZoom.d.ts

@@ -1,15 +1,13 @@
 /**
- * AvlCosmicZoom - Interactive Zoomable Orbital Visualization
+ * AvlCosmicZoom — Interactive Zoomable Orbital Visualization
  *
- * The host organism that owns the SVG viewport and delegates to
- * scene renderers at each zoom level. Manages animation, pan/zoom,
- * and breadcrumb navigation.
- *
- * @packageDocumentation
+ * 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.
  */
 import React from 'react';
 import type { OrbitalSchema } from '@almadar/core';
-import { type ZoomLevel } from './avl-zoom-state';
+import type { ZoomLevel } from './avl-zoom-state';
 export interface AvlCosmicZoomProps {
     /** The orbital schema (parsed object or JSON string) */
     schema: OrbitalSchema | string;
@@ -34,5 +32,10 @@ export interface AvlCosmicZoomProps {
     height?: number | string;
     /** Coverage data for verification overlay */
     stateCoverage?: Record<string, 'covered' | 'uncovered' | 'partial'>;
+    /** Dynamic focus target. Changes animate the zoom to the specified orbital/trait. */
+    focusTarget?: {
+        type: 'orbital' | 'trait';
+        name: string;
+    };
 }
 export declare const AvlCosmicZoom: React.FC<AvlCosmicZoomProps>;

package/dist/components/organisms/avl/FlowCanvas.d.ts

@@ -0,0 +1,32 @@
+/**
+ * FlowCanvas — Unified AVL + Flow canvas organism.
+ *
+ * One React Flow canvas with continuous semantic zoom. AVL primitives
+ * render inside React Flow nodes. The ZoomBandContext drives node
+ * rendering at different zoom levels.
+ *
+ * Replaces both AvlCosmicZoom (SVG viewer) and OrbitalFlow (Flow editor).
+ */
+import React from 'react';
+import type { OrbitalSchema } from '@almadar/core';
+import type { ZoomLevel } from './avl-zoom-state';
+export interface FlowCanvasProps {
+    schema: OrbitalSchema | string;
+    className?: string;
+    color?: string;
+    animated?: boolean;
+    width?: number | string;
+    height?: number | string;
+    onZoomChange?: (level: ZoomLevel, context: {
+        orbital?: string;
+        trait?: string;
+    }) => void;
+    focusTarget?: {
+        type: 'orbital' | 'trait';
+        name: string;
+    };
+    initialOrbital?: string;
+    initialTrait?: string;
+    stateCoverage?: Record<string, 'covered' | 'uncovered' | 'partial'>;
+}
+export declare const FlowCanvas: React.FC<FlowCanvasProps>;

package/dist/components/organisms/avl/ZoomBreadcrumb.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ZoomBreadcrumb — HTML overlay showing current zoom band context.
+ *
+ * Positioned absolute top-left of the FlowCanvas.
+ * Shows AVL primitive icons inline with breadcrumb segments.
+ */
+import React from 'react';
+import type { ZoomBand } from '../../molecules/avl/avl-canvas-types';
+export interface ZoomBreadcrumbProps {
+    band: ZoomBand;
+    applicationName?: string;
+    orbitalName?: string;
+    traitName?: string;
+    eventName?: string;
+}
+export declare const ZoomBreadcrumb: React.FC<ZoomBreadcrumbProps>;

package/dist/components/organisms/avl/ZoomLegend.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ZoomLegend — Collapsible HTML overlay showing AVL primitives
+ * relevant to the current zoom band.
+ */
+import React from 'react';
+import type { ZoomBand } from '../../molecules/avl/avl-canvas-types';
+export interface ZoomLegendProps {
+    band: ZoomBand;
+}
+export declare const ZoomLegend: React.FC<ZoomLegendProps>;

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

@@ -1,11 +1,14 @@
 /**
  * AVL Organisms - Interactive orbital visualizations.
  *
+ * V3: FlowCanvas is the primary organism. AvlCosmicZoom delegates to it.
+ *
  * @packageDocumentation
  */
+export { FlowCanvas, type FlowCanvasProps } from './FlowCanvas';
+export { ZoomBreadcrumb, type ZoomBreadcrumbProps } from './ZoomBreadcrumb';
+export { ZoomLegend, type ZoomLegendProps } from './ZoomLegend';
 export { AvlCosmicZoom, type AvlCosmicZoomProps } from './AvlCosmicZoom';
-export { AvlApplicationScene, type AvlApplicationSceneProps } from './AvlApplicationScene';
-export { AvlOrbitalScene, type AvlOrbitalSceneProps } from './AvlOrbitalScene';
 export { AvlTraitScene, type AvlTraitSceneProps } from './AvlTraitScene';
 export { AvlTransitionScene, type AvlTransitionSceneProps } from './AvlTransitionScene';
 export { AvlClickTarget, type AvlClickTargetProps } from './AvlClickTarget';