@almadar/ui 4.50.21 → 4.51.0

package/dist/avl/index.d.cts

@@ -1,7 +1,8 @@
 import * as React from 'react';
 import React__default from 'react';
-import { OrbitalSchema, UISlot, Expression, EntityPersistence, EventPayloadField, ThemeDefinition } from '@almadar/core';
+import { OrbitalSchema, UISlot, Expression, EntityPersistence, EventPayloadField, EventPayload, ThemeDefinition } from '@almadar/core';
 import { Node, Edge, NodeProps, EdgeProps } from '@xyflow/react';
+import { useDraggable } from '@dnd-kit/core';
 
 /**
  * Almadar Visual Language (AVL) shared types.
@@ -1176,6 +1177,149 @@ interface BehaviorRegistryRecord {
  */
 declare function registryEntryToCanvasEntry(entry: BehaviorRegistryRecord, orbitalNames: string[]): BehaviorCanvasEntry;
 
+/**
+ * useCanvasDnd — drag/drop primitives for the AVL canvas surface.
+ *
+ * Shares the sensor stack + collision waterfall with `useDataDnd` (both
+ * import from `hooks/useAlmadarDndCollision`); diverges on drop semantics
+ * because palette → canvas is a cursor-resolved tree insert, not a
+ * sortable-list reorder.
+ *
+ * Pointer-sensor based so it works inside React Flow nodes (the native
+ * HTML5 DnD path was swallowed by React Flow's pan/zoom handlers).
+ *
+ * Event contract (defaults — overridable via `CanvasDndProvider.onDrop`):
+ *   - On drag start: emits `UI:DRAG_START` { kind, data }
+ *   - On drag end:   emits `UI:DRAG_END`   { kind, data }
+ *   - On 'pattern' drop:   emits `UI:PATTERN_DROP`  { patternType, containerNode, parentPath?, index? }
+ *   - On 'behavior' drop:  emits `UI:BEHAVIOR_DROP` { behaviorName, containerNode }
+ *
+ * The `onDrop` callback lets consumers route OTHER payload kinds (e.g.
+ * `'pattern-instance'` for in-canvas reorder of an existing pattern) to
+ * their own bus events or schema mutations. Reorder semantics belong in
+ * the consumer because they touch the SExpr tree directly — this primitive
+ * only resolves payload + target + cursor and hands them off.
+ */
+
+/**
+ * Drag kinds the canvas understands. Open-ended `string` so consumers can
+ * introduce new kinds (e.g. `'pattern-instance'` for in-canvas reorder of an
+ * existing pattern) without touching this file — the provider's defaults
+ * cover `'pattern'` and `'behavior'`; everything else routes through the
+ * consumer's `onDrop`.
+ */
+type CanvasDragKind = 'pattern' | 'behavior' | (string & {});
+/**
+ * Payload carried by a draggable. For `'pattern'` tiles `data` is
+ * `{ type: string }`, for `'behavior'` tiles `{ name: string }`. For consumer
+ * kinds (e.g. `'pattern-instance'`) the shape is whatever the consumer
+ * agrees on with its own `onDrop`.
+ */
+interface CanvasDragPayload {
+    kind: CanvasDragKind;
+    data: EventPayload;
+}
+/**
+ * Orbital/trait/transition context a drop will mutate.
+ *
+ * Has an explicit `[key: string]: string | undefined` index signature so it
+ * structurally matches `EventPayload` — required because we pass the whole
+ * object as a field on the `UI:PATTERN_DROP` payload.
+ */
+interface CanvasContainerNode {
+    orbitalName?: string;
+    traitName?: string;
+    transitionEvent?: string;
+    [key: string]: string | undefined;
+}
+/** Drop-target metadata stored on each droppable's `data` field. */
+interface CanvasDropTarget {
+    /**
+     * `l1` = outer orbital frame (overview level).
+     * `l2` = render-ui slot inside an expanded orbital.
+     * `wrapper` = page-level catch-all fired when nothing inner caught the drop.
+     */
+    level: 'l1' | 'l2' | 'wrapper' | (string & {});
+    /** Full or partial container context this drop will mutate. */
+    containerNode: CanvasContainerNode;
+    /**
+     * Optional resolver called at drop time to derive `parentPath` + `index`
+     * from the pointer's final client position. L2 slots use this to walk the
+     * DOM under their `contentRef` and find the nearest `data-accepts-children`
+     * container plus the cursor-relative insertion index.
+     */
+    resolvePath?: (cursor: {
+        x: number;
+        y: number;
+    }) => {
+        parentPath: string;
+        index: number;
+    } | null;
+}
+interface CanvasDropEvent {
+    payload: CanvasDragPayload;
+    target: CanvasDropTarget;
+    /** Final pointer client position, when dnd-kit could compute it. */
+    cursor: {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Resolved insertion path/index from `target.resolvePath(cursor)`. Null
+     * when the target has no resolver or the cursor was unavailable.
+     */
+    resolved: {
+        parentPath: string;
+        index: number;
+    } | null;
+}
+interface UseCanvasDraggableArgs {
+    /** Unique id (per-tile). dnd-kit uses this to track the active drag. */
+    id: string;
+    payload: CanvasDragPayload;
+    disabled?: boolean;
+}
+interface UseCanvasDraggableResult {
+    setNodeRef: (node: HTMLElement | null) => void;
+    attributes: ReturnType<typeof useDraggable>['attributes'];
+    listeners: ReturnType<typeof useDraggable>['listeners'];
+    isDragging: boolean;
+    /** Spread on the tile — live transform + grab cursor + touch-action. */
+    style: React__default.CSSProperties;
+}
+declare function useCanvasDraggable({ id, payload, disabled, }: UseCanvasDraggableArgs): UseCanvasDraggableResult;
+interface UseCanvasDroppableArgs {
+    id: string;
+    target: CanvasDropTarget;
+    /** Which drag kinds this zone accepts. Defaults to ['pattern','behavior']. */
+    accepts?: readonly CanvasDragKind[];
+    disabled?: boolean;
+}
+interface UseCanvasDroppableResult {
+    setNodeRef: (node: HTMLElement | null) => void;
+    isOver: boolean;
+}
+declare function useCanvasDroppable({ id, target, accepts, disabled, }: UseCanvasDroppableArgs): UseCanvasDroppableResult;
+interface CanvasDndProviderProps {
+    children: React__default.ReactNode;
+    /**
+     * Override the default drop behavior. The default emits `UI:PATTERN_DROP`
+     * / `UI:BEHAVIOR_DROP` based on payload kind. Pass an `onDrop` to route
+     * additional kinds (e.g. `'pattern-instance'` reorder) elsewhere, or to
+     * mutate schema directly without going through the bus.
+     *
+     * Return `true` from `onDrop` to suppress the default emit; return
+     * `false`/`undefined` to fall through to defaults after running your code.
+     */
+    onDrop?: (drop: CanvasDropEvent) => boolean | void;
+}
+/**
+ * Wraps a canvas subtree in one DndContext + sensors + collision waterfall.
+ * Every `useCanvasDraggable` / `useCanvasDroppable` inside this provider
+ * participates in the same drag session.
+ */
+declare function CanvasDndProvider({ children, onDrop }: CanvasDndProviderProps): React__default.ReactElement;
+
 /**
  * OrbInspector
  *
@@ -1544,4 +1688,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, AvlOrbitalsCosmicZoom, type AvlOrbitalsCosmicZoomProps, 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 };
+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, AvlOrbitalsCosmicZoom, type AvlOrbitalsCosmicZoomProps, 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 CanvasContainerNode, CanvasDndProvider, type CanvasDndProviderProps, type CanvasDragKind, type CanvasDragPayload, type CanvasDropEvent, type CanvasDropTarget, 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 UseCanvasDraggableArgs, type UseCanvasDraggableResult, type UseCanvasDroppableArgs, type UseCanvasDroppableResult, 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, useCanvasDraggable, useCanvasDroppable, useZoomBand, zoomProgress };

package/dist/avl/index.d.ts

@@ -55,6 +55,7 @@ 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 { CanvasDndProvider, useCanvasDraggable, useCanvasDroppable, type CanvasDragKind, type CanvasDragPayload, type CanvasContainerNode, type CanvasDropTarget, type CanvasDropEvent, type CanvasDndProviderProps, type UseCanvasDraggableArgs, type UseCanvasDraggableResult, type UseCanvasDroppableArgs, type UseCanvasDroppableResult, } from '../components/molecules/avl/useCanvasDnd';
 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';