@almadar/ui 2.19.2 → 2.20.1

package/dist/avl/index.d.cts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { OrbitalSchema } from '@almadar/core';
 
 /**
  * Almadar Visual Language (AVL) shared types.
@@ -311,4 +312,281 @@ declare function curveControlPoint(x1: number, y1: number, x2: number, y2: numbe
     cpy: number;
 };
 
-export { AVL_FIELD_TYPE_SHAPES, AVL_OPERATOR_COLORS, AvlApplication, type AvlApplicationProps, type AvlBaseProps, AvlBinding, type AvlBindingProps, AvlBindingRef, type AvlBindingRefProps, AvlClosedCircuit, type AvlClosedCircuitProps, type AvlClosedCircuitState, type AvlClosedCircuitTransition, AvlEffect, type AvlEffectProps, type AvlEffectType, AvlEmitListen, type AvlEmitListenProps, AvlEntity, type AvlEntityProps, AvlEvent, type AvlEventProps, AvlExprTree, type AvlExprTreeNode, type AvlExprTreeProps, AvlField, type AvlFieldProps, AvlFieldType, type AvlFieldTypeKind, type AvlFieldTypeProps, AvlGuard, type AvlGuardProps, AvlLiteral, type AvlLiteralProps, AvlOperator, type AvlOperatorNamespace, type AvlOperatorProps, AvlOrbital, type AvlOrbitalProps, AvlOrbitalUnit, type AvlOrbitalUnitPage, type AvlOrbitalUnitProps, type AvlOrbitalUnitTrait, AvlPage, 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, AvlTrait, type AvlTraitProps, AvlTransition, type AvlTransitionProps, arcPath, curveControlPoint, gridPositions, radialPositions, ringPositions };
+/**
+ * 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 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
+ */
+
+interface AvlCosmicZoomProps {
+    /** The orbital schema (parsed object or JSON string) */
+    schema: OrbitalSchema | string;
+    /** CSS class for the outer container */
+    className?: string;
+    /** Primary color for the visualization */
+    color?: string;
+    /** Enable animations (default: true) */
+    animated?: boolean;
+    /** Pre-select an orbital on mount */
+    initialOrbital?: string;
+    /** Pre-select a trait on mount */
+    initialTrait?: string;
+    /** Callback when zoom level changes */
+    onZoomChange?: (level: ZoomLevel, context: {
+        orbital?: string;
+        trait?: string;
+    }) => void;
+    /** Container width */
+    width?: number | string;
+    /** Container height */
+    height?: number | string;
+    /** Coverage data for verification overlay */
+    stateCoverage?: Record<string, 'covered' | 'uncovered' | 'partial'>;
+}
+declare const AvlCosmicZoom: React.FC<AvlCosmicZoomProps>;
+
+/**
+ * AVL Schema Parser
+ *
+ * Pure functions that transform an OrbitalSchema into structured data
+ * for each zoom level of the Cosmic Zoom visualization.
+ *
+ * Imports all types from @almadar/core.
+ *
+ * @packageDocumentation
+ */
+
+interface ApplicationOrbitalData {
+    name: string;
+    entityName: string;
+    fieldCount: number;
+    persistence: string;
+    traitNames: string[];
+    pageNames: string[];
+    position: {
+        x: number;
+        y: number;
+    };
+}
+interface CrossLink {
+    emitterOrbital: string;
+    listenerOrbital: string;
+    eventName: string;
+    emitterTrait: string;
+    listenerTrait: string;
+}
+interface ApplicationLevelData {
+    orbitals: ApplicationOrbitalData[];
+    crossLinks: CrossLink[];
+}
+interface FieldInfo {
+    name: string;
+    type: string;
+    required: boolean;
+    hasDefault: boolean;
+}
+interface OrbitalTraitInfo {
+    name: string;
+    stateCount: number;
+    eventCount: number;
+    transitionCount: number;
+    emits: string[];
+    listens: string[];
+}
+interface OrbitalPageInfo {
+    name: string;
+    route: string;
+}
+interface ExternalLink {
+    targetOrbital: string;
+    eventName: string;
+    direction: 'out' | 'in';
+    traitName: string;
+}
+interface OrbitalLevelData {
+    name: string;
+    entity: {
+        name: string;
+        fields: FieldInfo[];
+        persistence: string;
+    };
+    traits: OrbitalTraitInfo[];
+    pages: OrbitalPageInfo[];
+    externalLinks: ExternalLink[];
+}
+interface TraitStateInfo {
+    name: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+}
+interface TraitTransitionInfo {
+    from: string;
+    to: string;
+    event: string;
+    guard?: unknown;
+    effects: Array<{
+        type: string;
+        args: unknown[];
+    }>;
+    index: number;
+}
+interface TraitLevelData {
+    name: string;
+    linkedEntity: string;
+    states: TraitStateInfo[];
+    transitions: TraitTransitionInfo[];
+    emittedEvents: string[];
+    listenedEvents: string[];
+}
+interface ExprTreeNode {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: ExprTreeNode[];
+}
+interface SlotTarget {
+    name: string;
+    pattern: string;
+}
+interface TransitionLevelData {
+    from: string;
+    to: string;
+    event: string;
+    guard: ExprTreeNode | null;
+    effects: ExprTreeNode[];
+    slotTargets: SlotTarget[];
+}
+/**
+ * Parse the application-level view: all orbitals with cross-orbital links.
+ */
+declare function parseApplicationLevel(schema: OrbitalSchema): ApplicationLevelData;
+/**
+ * Parse a single orbital's detail view.
+ */
+declare function parseOrbitalLevel(schema: OrbitalSchema, orbitalName: string): OrbitalLevelData | null;
+/**
+ * Parse a trait's state machine for the detail view.
+ */
+declare function parseTraitLevel(schema: OrbitalSchema, orbitalName: string, traitName: string): TraitLevelData | null;
+/**
+ * Parse a single transition for the detail view.
+ */
+declare function parseTransitionLevel(schema: OrbitalSchema, orbitalName: string, traitName: string, transitionIndex: number): TransitionLevelData | null;
+
+/**
+ * AvlApplicationScene - Zoom Level 1
+ *
+ * Shows all orbitals in the application with cross-orbital
+ * emit/listen arrows. Each orbital is a clickable AvlOrbitalUnit.
+ */
+
+interface AvlApplicationSceneProps {
+    data: ApplicationLevelData;
+    color?: string;
+    onOrbitalClick?: (orbitalName: string, position: {
+        x: number;
+        y: number;
+    }) => void;
+}
+declare const AvlApplicationScene: React.FC<AvlApplicationSceneProps>;
+
+/**
+ * AvlOrbitalScene - Zoom Level 2
+ *
+ * Shows a single orbital: entity nucleus with fields,
+ * trait rings, page markers, and external connection arrows.
+ */
+
+interface AvlOrbitalSceneProps {
+    data: OrbitalLevelData;
+    color?: string;
+    /** Currently highlighted trait (before zooming in) */
+    highlightedTrait?: string | null;
+    onTraitClick?: (traitName: string, position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Called when a trait tab is hovered/selected (highlight without zoom) */
+    onTraitHighlight?: (traitName: string | null) => void;
+}
+declare const AvlOrbitalScene: React.FC<AvlOrbitalSceneProps>;
+
+/**
+ * AvlTraitScene - Zoom Level 3
+ *
+ * Shows a trait's state machine using ELK (elkjs) for automatic
+ * node and edge label placement. No label overlap.
+ */
+
+interface AvlTraitSceneProps {
+    data: TraitLevelData;
+    color?: string;
+    onTransitionClick?: (transitionIndex: number, position: {
+        x: number;
+        y: number;
+    }) => void;
+}
+declare const AvlTraitScene: React.FC<AvlTraitSceneProps>;
+
+/**
+ * AvlTransitionScene - Zoom Level 4
+ *
+ * Shows a single transition in detail as a vertical flow:
+ * FromState -> Event card -> Guard -> Effects -> ToState
+ *
+ * Labels are placed in cards between arrow segments,
+ * never overlapping the lines.
+ */
+
+interface AvlTransitionSceneProps {
+    data: TransitionLevelData;
+    color?: string;
+}
+declare const AvlTransitionScene: React.FC<AvlTransitionSceneProps>;
+
+/**
+ * AvlClickTarget
+ *
+ * Transparent SVG rect overlay that makes AVL atoms clickable.
+ * AVL atoms render <g> elements which don't natively support
+ * bounding-box click events. This wrapper adds an invisible
+ * rect with pointer events and optional hover glow.
+ *
+ * @packageDocumentation
+ */
+
+interface AvlClickTargetProps {
+    /** Bounding box position */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Click handler */
+    onClick: () => void;
+    /** Hover callback */
+    onHover?: (hovering: boolean) => void;
+    /** Cursor style (default: pointer) */
+    cursor?: string;
+    /** Glow color on hover */
+    glowColor?: string;
+    /** Accessible label */
+    label?: string;
+    /** Children (the AVL atoms to render on top) */
+    children: React.ReactNode;
+}
+declare const AvlClickTarget: React.FC<AvlClickTargetProps>;
+
+export { AVL_FIELD_TYPE_SHAPES, AVL_OPERATOR_COLORS, type ApplicationLevelData, AvlApplication, type AvlApplicationProps, AvlApplicationScene, type AvlApplicationSceneProps, type AvlBaseProps, AvlBinding, type AvlBindingProps, AvlBindingRef, type AvlBindingRefProps, AvlClickTarget, type AvlClickTargetProps, AvlClosedCircuit, type AvlClosedCircuitProps, type AvlClosedCircuitState, type AvlClosedCircuitTransition, AvlCosmicZoom, type AvlCosmicZoomProps, AvlEffect, type AvlEffectProps, type AvlEffectType, AvlEmitListen, type AvlEmitListenProps, AvlEntity, type AvlEntityProps, AvlEvent, type AvlEventProps, AvlExprTree, type AvlExprTreeNode, type AvlExprTreeProps, AvlField, type AvlFieldProps, AvlFieldType, type AvlFieldTypeKind, type AvlFieldTypeProps, AvlGuard, type AvlGuardProps, AvlLiteral, type AvlLiteralProps, AvlOperator, type AvlOperatorNamespace, type AvlOperatorProps, AvlOrbital, type AvlOrbitalProps, AvlOrbitalScene, type AvlOrbitalSceneProps, AvlOrbitalUnit, type AvlOrbitalUnitPage, type AvlOrbitalUnitProps, type AvlOrbitalUnitTrait, AvlPage, 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, AvlTrait, type AvlTraitProps, AvlTraitScene, type AvlTraitSceneProps, AvlTransition, type AvlTransitionProps, AvlTransitionScene, type AvlTransitionSceneProps, type CrossLink, type OrbitalLevelData, type TraitLevelData, type TransitionLevelData, type ZoomLevel, arcPath, curveControlPoint, gridPositions, parseApplicationLevel, parseOrbitalLevel, parseTraitLevel, parseTransitionLevel, radialPositions, ringPositions };

package/dist/avl/index.d.ts

@@ -31,3 +31,4 @@ export { AvlEmitListen, type AvlEmitListenProps } from '../components/molecules/
 export { AvlSlotMap, type AvlSlotMapProps, type AvlSlotMapSlot } from '../components/molecules/avl';
 export { AvlExprTree, type AvlExprTreeProps, type AvlExprTreeNode } from '../components/molecules/avl';
 export { ringPositions, arcPath, radialPositions, gridPositions, curveControlPoint } from '../components/molecules/avl';
+export { AvlCosmicZoom, type AvlCosmicZoomProps, AvlApplicationScene, type AvlApplicationSceneProps, AvlOrbitalScene, type AvlOrbitalSceneProps, 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';