@almadar/ui 2.45.0 → 2.46.1

package/dist/components/molecules/avl/avl-behavior-compose-types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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)
+ */
+import type { EntityPersistence, EventPayloadField } from '@almadar/core';
+import type { BehaviorLevel, BehaviorGlyphChild, BehaviorGlyphConnection } from './AvlBehaviorGlyph';
+import type { AvlEffectType } from '../../atoms/avl/types';
+/** Extended view level adding 'behavior' to the existing overview/expanded. */
+export type ComposeViewLevel = 'behavior' | 'overview' | 'expanded';
+/** An event that can be wired between behaviors. */
+export 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. */
+export 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. */
+export 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. */
+export 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[];
+}

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

@@ -19,7 +19,9 @@ import type { PreviewNodeData, EventEdgeData } from './avl-preview-types';
  * Build a React Flow graph for the overview level.
  * Each orbital gets one node showing its INIT transition's UI.
  */
-export declare function schemaToOverviewGraph(schema: OrbitalSchema, mockData?: Record<string, unknown[]>): {
+export declare function schemaToOverviewGraph(schema: OrbitalSchema, mockData?: Record<string, unknown[]>, behaviorMeta?: Record<string, {
+    layer: string;
+}>, layoutHint?: 'pipeline' | 'grid'): {
     nodes: Node<PreviewNodeData>[];
     edges: Edge<EventEdgeData>[];
 };

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

@@ -39,6 +39,12 @@ export 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. */
 export interface RenderUIEntry {
@@ -70,6 +76,8 @@ export 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). */

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

@@ -27,6 +27,9 @@ export { type ViewLevel, type PreviewNodeData, type EventEdgeData, type PatternE
 export { schemaToOverviewGraph, orbitalToExpandedGraph } from './avl-preview-converter';
 export { OrbPreviewNode, ScreenSizeContext } from './OrbPreviewNode';
 export { EventFlowEdge } from './EventFlowEdge';
+export { type ComposeViewLevel, type BehaviorComposeNodeData, type BehaviorWireEdgeData, type BehaviorCanvasEntry, type ConnectableEvent } from './avl-behavior-compose-types';
+export { BehaviorComposeNode } from './BehaviorComposeNode';
+export { behaviorsToComposeGraph, registryEntryToCanvasEntry, type BehaviorRegistryRecord } from './avl-behavior-compose-converter';
 export { Avl3DOrbitalNode, type Avl3DOrbitalNodeProps } from './Avl3DOrbitalNode';
 export { Avl3DCrossWire, type Avl3DCrossWireProps } from './Avl3DCrossWire';
 export { Avl3DEntityCore, type Avl3DEntityCoreProps } from './Avl3DEntityCore';

package/dist/components/molecules/avl/wire-validation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wire Validation
+ *
+ * Validates event wire compatibility between behaviors based on typed payloads.
+ * Used by FlowCanvas when the user drags between event handles.
+ */
+export interface PayloadField {
+    name: string;
+    type: string;
+    required?: boolean;
+}
+export interface WireValidationResult {
+    valid: boolean;
+    warnings: string[];
+}
+/**
+ * Validate that a wire between two event handles is payload-compatible.
+ *
+ * Rules:
+ * - If neither side declares a payload, the wire is valid (no data contract).
+ * - If source has payload but target doesn't, valid with info (data is unused).
+ * - If target expects required fields that source doesn't provide, warn.
+ * - If both have fields with the same name but different types, warn.
+ */
+export declare function validateWire(sourcePayload: PayloadField[] | undefined, targetPayload: PayloadField[] | undefined): WireValidationResult;
+/**
+ * Format payload fields into a tooltip string.
+ * Example: "{ data: object (req), query: string }"
+ */
+export declare function formatPayloadTooltip(fields: PayloadField[]): string;

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

@@ -14,6 +14,7 @@
 import React from 'react';
 import type { OrbitalSchema } from '@almadar/core';
 import type { ViewLevel, PreviewNodeData } from '../../molecules/avl/avl-preview-types';
+import type { ComposeViewLevel, BehaviorCanvasEntry, BehaviorWireEdgeData } from '../../molecules/avl/avl-behavior-compose-types';
 export interface FlowCanvasProps {
     schema: OrbitalSchema | string;
     mockData?: Record<string, unknown[]>;
@@ -49,6 +50,20 @@ export 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. */

package/dist/components/organisms/game/three/index.cjs

@@ -2844,6 +2844,7 @@ var Box = React21__default.default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -2908,6 +2909,7 @@ var Box = React21__default.default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/components/organisms/game/three/index.js

@@ -2820,6 +2820,7 @@ var Box = React21.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -2884,6 +2885,7 @@ var Box = React21.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/docs/index.cjs

@@ -2704,6 +2704,7 @@ var Box = React4__default.default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -2768,6 +2769,7 @@ var Box = React4__default.default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/docs/index.d.cts

@@ -53,6 +53,10 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     actionPayload?: Record<string, unknown>;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
     hoverEvent?: string;
+    /** Maximum width (CSS value, e.g., "550px", "80rem") */
+    maxWidth?: string;
+    /** Children elements */
+    children?: React.ReactNode;
 }
 /**
  * Box - Versatile container component with design tokens

package/dist/docs/index.js

@@ -2680,6 +2680,7 @@ var Box = React4.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -2744,6 +2745,7 @@ var Box = React4.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/marketing/index.cjs

@@ -2704,6 +2704,7 @@ var Box = React5__default.default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -2768,6 +2769,7 @@ var Box = React5__default.default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/marketing/index.d.cts

@@ -52,6 +52,10 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     actionPayload?: Record<string, unknown>;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
     hoverEvent?: string;
+    /** Maximum width (CSS value, e.g., "550px", "80rem") */
+    maxWidth?: string;
+    /** Children elements */
+    children?: React.ReactNode;
 }
 /**
  * Box - Versatile container component with design tokens

package/dist/marketing/index.js

@@ -2680,6 +2680,7 @@ var Box = React5.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -2744,6 +2745,7 @@ var Box = React5.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/providers/index.cjs

@@ -923,6 +923,7 @@ var Box = React114__namespace.default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -987,6 +988,7 @@ var Box = React114__namespace.default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/providers/index.js

@@ -877,6 +877,7 @@ var Box = React114__default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -941,6 +942,7 @@ var Box = React114__default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/runtime/index.cjs

@@ -1703,6 +1703,7 @@ var Box = React117__namespace.default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -1767,6 +1768,7 @@ var Box = React117__namespace.default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/dist/runtime/index.js

@@ -1657,6 +1657,7 @@ var Box = React117__default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
@@ -1721,6 +1722,7 @@ var Box = React117__default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest,
         children
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "2.45.0",
+  "version": "2.46.1",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",