@almadar/ui 2.19.2 → 2.20.1

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

@@ -0,0 +1,17 @@
+/**
+ * AvlApplicationScene - Zoom Level 1
+ *
+ * Shows all orbitals in the application with cross-orbital
+ * emit/listen arrows. Each orbital is a clickable AvlOrbitalUnit.
+ */
+import React from 'react';
+import type { ApplicationLevelData } from './avl-schema-parser';
+export interface AvlApplicationSceneProps {
+    data: ApplicationLevelData;
+    color?: string;
+    onOrbitalClick?: (orbitalName: string, position: {
+        x: number;
+        y: number;
+    }) => void;
+}
+export declare const AvlApplicationScene: React.FC<AvlApplicationSceneProps>;

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

@@ -0,0 +1,31 @@
+/**
+ * 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
+ */
+import React from 'react';
+export 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;
+}
+export declare const AvlClickTarget: React.FC<AvlClickTargetProps>;

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

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { OrbitalSchema } from '@almadar/core';
+import { type ZoomLevel } from './avl-zoom-state';
+export 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'>;
+}
+export declare const AvlCosmicZoom: React.FC<AvlCosmicZoomProps>;

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

@@ -0,0 +1,15 @@
+/**
+ * AvlLegend - Compact legend showing AVL symbol definitions.
+ *
+ * Each scene passes the set of symbol types it uses, and
+ * the legend renders only those symbols with labels.
+ */
+import React from 'react';
+import type { ZoomLevel } from './avl-zoom-state';
+export interface AvlLegendProps {
+    level: ZoomLevel;
+    color?: string;
+    x?: number;
+    y?: number;
+}
+export declare const AvlLegend: React.FC<AvlLegendProps>;

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

@@ -0,0 +1,21 @@
+/**
+ * AvlOrbitalScene - Zoom Level 2
+ *
+ * Shows a single orbital: entity nucleus with fields,
+ * trait rings, page markers, and external connection arrows.
+ */
+import React from 'react';
+import type { OrbitalLevelData } from './avl-schema-parser';
+export 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;
+}
+export declare const AvlOrbitalScene: React.FC<AvlOrbitalSceneProps>;

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

@@ -0,0 +1,17 @@
+/**
+ * AvlTraitScene - Zoom Level 3
+ *
+ * Shows a trait's state machine using ELK (elkjs) for automatic
+ * node and edge label placement. No label overlap.
+ */
+import React from 'react';
+import type { TraitLevelData } from './avl-schema-parser';
+export interface AvlTraitSceneProps {
+    data: TraitLevelData;
+    color?: string;
+    onTransitionClick?: (transitionIndex: number, position: {
+        x: number;
+        y: number;
+    }) => void;
+}
+export declare const AvlTraitScene: React.FC<AvlTraitSceneProps>;

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

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+import React from 'react';
+import type { TransitionLevelData } from './avl-schema-parser';
+export interface AvlTransitionSceneProps {
+    data: TransitionLevelData;
+    color?: string;
+}
+export declare const AvlTransitionScene: React.FC<AvlTransitionSceneProps>;

package/dist/components/organisms/avl/avl-schema-parser.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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
+ */
+import type { OrbitalSchema } from '@almadar/core';
+export interface ApplicationOrbitalData {
+    name: string;
+    entityName: string;
+    fieldCount: number;
+    persistence: string;
+    traitNames: string[];
+    pageNames: string[];
+    position: {
+        x: number;
+        y: number;
+    };
+}
+export interface CrossLink {
+    emitterOrbital: string;
+    listenerOrbital: string;
+    eventName: string;
+    emitterTrait: string;
+    listenerTrait: string;
+}
+export interface ApplicationLevelData {
+    orbitals: ApplicationOrbitalData[];
+    crossLinks: CrossLink[];
+}
+export interface FieldInfo {
+    name: string;
+    type: string;
+    required: boolean;
+    hasDefault: boolean;
+}
+export interface OrbitalTraitInfo {
+    name: string;
+    stateCount: number;
+    eventCount: number;
+    transitionCount: number;
+    emits: string[];
+    listens: string[];
+}
+export interface OrbitalPageInfo {
+    name: string;
+    route: string;
+}
+export interface ExternalLink {
+    targetOrbital: string;
+    eventName: string;
+    direction: 'out' | 'in';
+    traitName: string;
+}
+export interface OrbitalLevelData {
+    name: string;
+    entity: {
+        name: string;
+        fields: FieldInfo[];
+        persistence: string;
+    };
+    traits: OrbitalTraitInfo[];
+    pages: OrbitalPageInfo[];
+    externalLinks: ExternalLink[];
+}
+export interface TraitStateInfo {
+    name: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+}
+export interface TraitTransitionInfo {
+    from: string;
+    to: string;
+    event: string;
+    guard?: unknown;
+    effects: Array<{
+        type: string;
+        args: unknown[];
+    }>;
+    index: number;
+}
+export interface TraitLevelData {
+    name: string;
+    linkedEntity: string;
+    states: TraitStateInfo[];
+    transitions: TraitTransitionInfo[];
+    emittedEvents: string[];
+    listenedEvents: string[];
+}
+export interface ExprTreeNode {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: ExprTreeNode[];
+}
+export interface SlotTarget {
+    name: string;
+    pattern: string;
+}
+export 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.
+ */
+export declare function parseApplicationLevel(schema: OrbitalSchema): ApplicationLevelData;
+/**
+ * Parse a single orbital's detail view.
+ */
+export declare function parseOrbitalLevel(schema: OrbitalSchema, orbitalName: string): OrbitalLevelData | null;
+/**
+ * Parse a trait's state machine for the detail view.
+ */
+export declare function parseTraitLevel(schema: OrbitalSchema, orbitalName: string, traitName: string): TraitLevelData | null;
+/**
+ * Parse a single transition for the detail view.
+ */
+export declare function parseTransitionLevel(schema: OrbitalSchema, orbitalName: string, traitName: string, transitionIndex: number): TransitionLevelData | null;

package/dist/components/organisms/avl/avl-zoom-state.d.ts

@@ -0,0 +1,60 @@
+/**
+ * AVL Cosmic Zoom State Machine
+ *
+ * useReducer-based state machine managing which zoom level is displayed,
+ * what is selected, and animation state.
+ *
+ * @packageDocumentation
+ */
+export type ZoomLevel = 'application' | 'orbital' | 'trait' | 'transition';
+export interface ZoomState {
+    level: ZoomLevel;
+    selectedOrbital: string | null;
+    selectedTrait: string | null;
+    selectedTransition: number | null;
+    animating: boolean;
+    animationDirection: 'in' | 'out';
+    animationTarget: {
+        x: number;
+        y: number;
+        scale: number;
+    } | null;
+}
+export type ZoomAction = {
+    type: 'ZOOM_INTO_ORBITAL';
+    orbital: string;
+    targetPosition: {
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'ZOOM_INTO_TRAIT';
+    trait: string;
+    targetPosition: {
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'ZOOM_INTO_TRANSITION';
+    transitionIndex: number;
+    targetPosition: {
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'ZOOM_OUT';
+} | {
+    type: 'ANIMATION_COMPLETE';
+} | {
+    type: 'RESET';
+} | {
+    type: 'SWITCH_TRAIT';
+    trait: string;
+};
+export declare const initialZoomState: ZoomState;
+export declare function zoomReducer(state: ZoomState, action: ZoomAction): ZoomState;
+export interface BreadcrumbSegment {
+    label: string;
+    level: ZoomLevel;
+}
+export declare function getBreadcrumbs(state: ZoomState): BreadcrumbSegment[];

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

@@ -0,0 +1,14 @@
+/**
+ * AVL Organisms - Interactive orbital visualizations.
+ *
+ * @packageDocumentation
+ */
+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';
+export { AvlLegend, type AvlLegendProps } from './AvlLegend';
+export { parseApplicationLevel, parseOrbitalLevel, parseTraitLevel, parseTransitionLevel, type ApplicationLevelData, type OrbitalLevelData, type TraitLevelData, type TransitionLevelData, type CrossLink, type ExprTreeNode, } from './avl-schema-parser';
+export { zoomReducer, initialZoomState, getBreadcrumbs, type ZoomLevel, type ZoomState, type ZoomAction, type BreadcrumbSegment, } from './avl-zoom-state';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "2.19.2",
+  "version": "2.20.1",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -117,6 +117,7 @@
     "@almadar/patterns": ">=2.0.0",
     "@almadar/runtime": ">=2.0.0",
     "clsx": "^2.1.0",
+    "elkjs": "0.11.1",
     "leaflet": "1.9.4",
     "lucide-react": "^0.344.0",
     "react-leaflet": "^4.2.1",