@almadar/ui 4.50.22 → 4.51.0

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

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ */
+import React from 'react';
+import { useDraggable as dndKitUseDraggable } from '@dnd-kit/core';
+import type { EventPayload } from '@almadar/core';
+/**
+ * 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`.
+ */
+export 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`.
+ */
+export 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.
+ */
+export interface CanvasContainerNode {
+    orbitalName?: string;
+    traitName?: string;
+    transitionEvent?: string;
+    [key: string]: string | undefined;
+}
+/** Drop-target metadata stored on each droppable's `data` field. */
+export 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;
+}
+export 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;
+}
+export interface UseCanvasDraggableArgs {
+    /** Unique id (per-tile). dnd-kit uses this to track the active drag. */
+    id: string;
+    payload: CanvasDragPayload;
+    disabled?: boolean;
+}
+export interface UseCanvasDraggableResult {
+    setNodeRef: (node: HTMLElement | null) => void;
+    attributes: ReturnType<typeof dndKitUseDraggable>['attributes'];
+    listeners: ReturnType<typeof dndKitUseDraggable>['listeners'];
+    isDragging: boolean;
+    /** Spread on the tile — live transform + grab cursor + touch-action. */
+    style: React.CSSProperties;
+}
+export declare function useCanvasDraggable({ id, payload, disabled, }: UseCanvasDraggableArgs): UseCanvasDraggableResult;
+export interface UseCanvasDroppableArgs {
+    id: string;
+    target: CanvasDropTarget;
+    /** Which drag kinds this zone accepts. Defaults to ['pattern','behavior']. */
+    accepts?: readonly CanvasDragKind[];
+    disabled?: boolean;
+}
+export interface UseCanvasDroppableResult {
+    setNodeRef: (node: HTMLElement | null) => void;
+    isOver: boolean;
+}
+export declare function useCanvasDroppable({ id, target, accepts, disabled, }: UseCanvasDroppableArgs): UseCanvasDroppableResult;
+export interface CanvasDndProviderProps {
+    children: React.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.
+ */
+export declare function CanvasDndProvider({ children, onDrop }: CanvasDndProviderProps): React.ReactElement;

package/dist/hooks/useAlmadarDndCollision.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared DnD primitives — sensor config + collision waterfall.
+ *
+ * Both the row-reorder primitive (`useDataDnd` in DataList/DataGrid) and the
+ * canvas-insert primitive (`useCanvasDnd` in AVL OrbPreviewNode) need
+ * identical pointer activation behavior and the same multi-container
+ * collision strategy. Centralizing them here keeps the two hooks from
+ * drifting and gives a single tunable spot when DnD ergonomics need a tweak.
+ *
+ * Activation: `distance: 5` on the PointerSensor so a small accidental
+ * tremor doesn't fire a drag — matches the threshold dnd-kit's own examples
+ * use for grab-and-drag interactions.
+ *
+ * Collision waterfall (run in order, first non-empty wins):
+ *   1. pointerWithin     — catches the empty zones + clean hover-over-zone case
+ *   2. rectIntersection  — falls back when the pointer is in margin/padding
+ *   3. closestCorners    — last resort over the items in whichever zone won
+ */
+import { type CollisionDetection, type SensorDescriptor, type SensorOptions } from '@dnd-kit/core';
+export declare const ALMADAR_DND_ACTIVATION_DISTANCE = 5;
+/**
+ * Returns the canonical sensor stack used by every Almadar DnD primitive.
+ *
+ * @param withSortableKeyboard - when true, the KeyboardSensor uses
+ *   `sortableKeyboardCoordinates` (correct for sortable lists). Defaults to
+ *   true so `useDataDnd` keeps its current behavior; `useCanvasDnd` doesn't
+ *   need it (no sortable rows) so it can pass false.
+ */
+export declare function useAlmadarDndSensors(withSortableKeyboard?: boolean): SensorDescriptor<SensorOptions>[];
+/**
+ * Multi-container collision waterfall.
+ * pointerWithin → rectIntersection → closestCorners.
+ */
+export declare const almadarDndCollisionDetection: CollisionDetection;

package/dist/providers/index.cjs

@@ -21318,6 +21318,31 @@ var init_DashboardLayout = __esm({
     NavLink.displayName = "NavLink";
   }
 });
+function useAlmadarDndSensors(withSortableKeyboard = true) {
+  return core$1.useSensors(
+    core$1.useSensor(core$1.PointerSensor, {
+      activationConstraint: { distance: ALMADAR_DND_ACTIVATION_DISTANCE }
+    }),
+    core$1.useSensor(
+      core$1.KeyboardSensor,
+      withSortableKeyboard ? { coordinateGetter: sortable.sortableKeyboardCoordinates } : void 0
+    )
+  );
+}
+var ALMADAR_DND_ACTIVATION_DISTANCE, almadarDndCollisionDetection;
+var init_useAlmadarDndCollision = __esm({
+  "hooks/useAlmadarDndCollision.ts"() {
+    "use client";
+    ALMADAR_DND_ACTIVATION_DISTANCE = 5;
+    almadarDndCollisionDetection = (args) => {
+      const pw = core$1.pointerWithin(args);
+      if (pw.length > 0) return pw;
+      const ri = core$1.rectIntersection(args);
+      if (ri.length > 0) return ri;
+      return core$1.closestCorners(args);
+    };
+  }
+});
 function useDataDnd(args) {
   const {
     dragGroup,
@@ -21413,25 +21438,8 @@ function useDataDnd(args) {
       dndLog.debug("zone:unregister", { zoneId, group: meta.group });
     };
   }, [parentRoot, isRoot, zoneId, meta]);
-  const sensors = core$1.useSensors(
-    core$1.useSensor(core$1.PointerSensor, { activationConstraint: { distance: 5 } }),
-    core$1.useSensor(core$1.KeyboardSensor, { coordinateGetter: sortable.sortableKeyboardCoordinates })
-  );
-  const collisionDetection = React81__namespace.default.useCallback((args2) => {
-    const pointerCollisions = core$1.pointerWithin(args2);
-    if (pointerCollisions.length > 0) {
-      dndLog.debug("collision:pointerWithin", { count: pointerCollisions.length, ids: pointerCollisions.map((c) => c.id) });
-      return pointerCollisions;
-    }
-    const rectCollisions = core$1.rectIntersection(args2);
-    if (rectCollisions.length > 0) {
-      dndLog.debug("collision:rectIntersection", { count: rectCollisions.length, ids: rectCollisions.map((c) => c.id) });
-      return rectCollisions;
-    }
-    const cornerCollisions = core$1.closestCorners(args2);
-    dndLog.debug("collision:closestCorners", { count: cornerCollisions.length, ids: cornerCollisions.map((c) => c.id) });
-    return cornerCollisions;
-  }, []);
+  const sensors = useAlmadarDndSensors(true);
+  const collisionDetection = almadarDndCollisionDetection;
   const findZoneByItem = React81__namespace.default.useCallback(
     (id) => {
       for (const z of zonesRef.current.values()) {
@@ -21768,6 +21776,7 @@ var init_useDataDnd = __esm({
   "components/molecules/useDataDnd.tsx"() {
     "use client";
     init_useEventBus();
+    init_useAlmadarDndCollision();
     init_Box();
     dndLog = logger.createLogger("almadar:ui:dnd");
     RootCtx = React81__namespace.default.createContext(null);

package/dist/providers/index.js

@@ -36,8 +36,8 @@ import langToml from 'react-syntax-highlighter/dist/esm/languages/prism/toml.js'
 import langGo from 'react-syntax-highlighter/dist/esm/languages/prism/go.js';
 import langGraphql from 'react-syntax-highlighter/dist/esm/languages/prism/graphql.js';
 import { isInlineTrait } from '@almadar/core';
-import { useSensors, useSensor, PointerSensor, KeyboardSensor, pointerWithin, rectIntersection, closestCorners, DndContext, useDroppable } from '@dnd-kit/core';
-import { sortableKeyboardCoordinates, useSortable, arrayMove, SortableContext, rectSortingStrategy, verticalListSortingStrategy } from '@dnd-kit/sortable';
+import { DndContext, pointerWithin, rectIntersection, closestCorners, useSensors, useSensor, PointerSensor, KeyboardSensor, useDroppable } from '@dnd-kit/core';
+import { useSortable, arrayMove, sortableKeyboardCoordinates, SortableContext, rectSortingStrategy, verticalListSortingStrategy } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { Handle, Position } from '@xyflow/react';
 import { getPatternDefinition, getComponentForPattern as getComponentForPattern$1 } from '@almadar/patterns';
@@ -21272,6 +21272,31 @@ var init_DashboardLayout = __esm({
     NavLink.displayName = "NavLink";
   }
 });
+function useAlmadarDndSensors(withSortableKeyboard = true) {
+  return useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: { distance: ALMADAR_DND_ACTIVATION_DISTANCE }
+    }),
+    useSensor(
+      KeyboardSensor,
+      withSortableKeyboard ? { coordinateGetter: sortableKeyboardCoordinates } : void 0
+    )
+  );
+}
+var ALMADAR_DND_ACTIVATION_DISTANCE, almadarDndCollisionDetection;
+var init_useAlmadarDndCollision = __esm({
+  "hooks/useAlmadarDndCollision.ts"() {
+    "use client";
+    ALMADAR_DND_ACTIVATION_DISTANCE = 5;
+    almadarDndCollisionDetection = (args) => {
+      const pw = pointerWithin(args);
+      if (pw.length > 0) return pw;
+      const ri = rectIntersection(args);
+      if (ri.length > 0) return ri;
+      return closestCorners(args);
+    };
+  }
+});
 function useDataDnd(args) {
   const {
     dragGroup,
@@ -21367,25 +21392,8 @@ function useDataDnd(args) {
       dndLog.debug("zone:unregister", { zoneId, group: meta.group });
     };
   }, [parentRoot, isRoot, zoneId, meta]);
-  const sensors = useSensors(
-    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
-    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
-  );
-  const collisionDetection = React81__default.useCallback((args2) => {
-    const pointerCollisions = pointerWithin(args2);
-    if (pointerCollisions.length > 0) {
-      dndLog.debug("collision:pointerWithin", { count: pointerCollisions.length, ids: pointerCollisions.map((c) => c.id) });
-      return pointerCollisions;
-    }
-    const rectCollisions = rectIntersection(args2);
-    if (rectCollisions.length > 0) {
-      dndLog.debug("collision:rectIntersection", { count: rectCollisions.length, ids: rectCollisions.map((c) => c.id) });
-      return rectCollisions;
-    }
-    const cornerCollisions = closestCorners(args2);
-    dndLog.debug("collision:closestCorners", { count: cornerCollisions.length, ids: cornerCollisions.map((c) => c.id) });
-    return cornerCollisions;
-  }, []);
+  const sensors = useAlmadarDndSensors(true);
+  const collisionDetection = almadarDndCollisionDetection;
   const findZoneByItem = React81__default.useCallback(
     (id) => {
       for (const z of zonesRef.current.values()) {
@@ -21722,6 +21730,7 @@ var init_useDataDnd = __esm({
   "components/molecules/useDataDnd.tsx"() {
     "use client";
     init_useEventBus();
+    init_useAlmadarDndCollision();
     init_Box();
     dndLog = createLogger("almadar:ui:dnd");
     RootCtx = React81__default.createContext(null);

package/dist/runtime/index.cjs

@@ -21087,6 +21087,31 @@ var init_DashboardLayout = __esm({
     NavLink.displayName = "NavLink";
   }
 });
+function useAlmadarDndSensors(withSortableKeyboard = true) {
+  return core$1.useSensors(
+    core$1.useSensor(core$1.PointerSensor, {
+      activationConstraint: { distance: ALMADAR_DND_ACTIVATION_DISTANCE }
+    }),
+    core$1.useSensor(
+      core$1.KeyboardSensor,
+      withSortableKeyboard ? { coordinateGetter: sortable.sortableKeyboardCoordinates } : void 0
+    )
+  );
+}
+var ALMADAR_DND_ACTIVATION_DISTANCE, almadarDndCollisionDetection;
+var init_useAlmadarDndCollision = __esm({
+  "hooks/useAlmadarDndCollision.ts"() {
+    "use client";
+    ALMADAR_DND_ACTIVATION_DISTANCE = 5;
+    almadarDndCollisionDetection = (args) => {
+      const pw = core$1.pointerWithin(args);
+      if (pw.length > 0) return pw;
+      const ri = core$1.rectIntersection(args);
+      if (ri.length > 0) return ri;
+      return core$1.closestCorners(args);
+    };
+  }
+});
 function useDataDnd(args) {
   const {
     dragGroup,
@@ -21182,25 +21207,8 @@ function useDataDnd(args) {
       dndLog.debug("zone:unregister", { zoneId, group: meta.group });
     };
   }, [parentRoot, isRoot, zoneId, meta]);
-  const sensors = core$1.useSensors(
-    core$1.useSensor(core$1.PointerSensor, { activationConstraint: { distance: 5 } }),
-    core$1.useSensor(core$1.KeyboardSensor, { coordinateGetter: sortable.sortableKeyboardCoordinates })
-  );
-  const collisionDetection = React80__namespace.default.useCallback((args2) => {
-    const pointerCollisions = core$1.pointerWithin(args2);
-    if (pointerCollisions.length > 0) {
-      dndLog.debug("collision:pointerWithin", { count: pointerCollisions.length, ids: pointerCollisions.map((c) => c.id) });
-      return pointerCollisions;
-    }
-    const rectCollisions = core$1.rectIntersection(args2);
-    if (rectCollisions.length > 0) {
-      dndLog.debug("collision:rectIntersection", { count: rectCollisions.length, ids: rectCollisions.map((c) => c.id) });
-      return rectCollisions;
-    }
-    const cornerCollisions = core$1.closestCorners(args2);
-    dndLog.debug("collision:closestCorners", { count: cornerCollisions.length, ids: cornerCollisions.map((c) => c.id) });
-    return cornerCollisions;
-  }, []);
+  const sensors = useAlmadarDndSensors(true);
+  const collisionDetection = almadarDndCollisionDetection;
   const findZoneByItem = React80__namespace.default.useCallback(
     (id) => {
       for (const z of zonesRef.current.values()) {
@@ -21537,6 +21545,7 @@ var init_useDataDnd = __esm({
   "components/molecules/useDataDnd.tsx"() {
     "use client";
     init_useEventBus();
+    init_useAlmadarDndCollision();
     init_Box();
     dndLog = logger.createLogger("almadar:ui:dnd");
     RootCtx = React80__namespace.default.createContext(null);

package/dist/runtime/index.js

@@ -36,8 +36,8 @@ import langToml from 'react-syntax-highlighter/dist/esm/languages/prism/toml.js'
 import langGo from 'react-syntax-highlighter/dist/esm/languages/prism/go.js';
 import langGraphql from 'react-syntax-highlighter/dist/esm/languages/prism/graphql.js';
 import { isCircuitEvent, schemaToIR, getPage, clearSchemaCache as clearSchemaCache$1, isEntityCall, isInlineTrait } from '@almadar/core';
-import { useSensors, useSensor, PointerSensor, KeyboardSensor, pointerWithin, rectIntersection, closestCorners, DndContext, useDroppable } from '@dnd-kit/core';
-import { sortableKeyboardCoordinates, useSortable, arrayMove, SortableContext, rectSortingStrategy, verticalListSortingStrategy } from '@dnd-kit/sortable';
+import { DndContext, pointerWithin, rectIntersection, closestCorners, useSensors, useSensor, PointerSensor, KeyboardSensor, useDroppable } from '@dnd-kit/core';
+import { useSortable, arrayMove, sortableKeyboardCoordinates, SortableContext, rectSortingStrategy, verticalListSortingStrategy } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { Handle, Position } from '@xyflow/react';
 import { getPatternDefinition, getComponentForPattern as getComponentForPattern$1 } from '@almadar/patterns';
@@ -21041,6 +21041,31 @@ var init_DashboardLayout = __esm({
     NavLink.displayName = "NavLink";
   }
 });
+function useAlmadarDndSensors(withSortableKeyboard = true) {
+  return useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: { distance: ALMADAR_DND_ACTIVATION_DISTANCE }
+    }),
+    useSensor(
+      KeyboardSensor,
+      withSortableKeyboard ? { coordinateGetter: sortableKeyboardCoordinates } : void 0
+    )
+  );
+}
+var ALMADAR_DND_ACTIVATION_DISTANCE, almadarDndCollisionDetection;
+var init_useAlmadarDndCollision = __esm({
+  "hooks/useAlmadarDndCollision.ts"() {
+    "use client";
+    ALMADAR_DND_ACTIVATION_DISTANCE = 5;
+    almadarDndCollisionDetection = (args) => {
+      const pw = pointerWithin(args);
+      if (pw.length > 0) return pw;
+      const ri = rectIntersection(args);
+      if (ri.length > 0) return ri;
+      return closestCorners(args);
+    };
+  }
+});
 function useDataDnd(args) {
   const {
     dragGroup,
@@ -21136,25 +21161,8 @@ function useDataDnd(args) {
       dndLog.debug("zone:unregister", { zoneId, group: meta.group });
     };
   }, [parentRoot, isRoot, zoneId, meta]);
-  const sensors = useSensors(
-    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
-    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
-  );
-  const collisionDetection = React80__default.useCallback((args2) => {
-    const pointerCollisions = pointerWithin(args2);
-    if (pointerCollisions.length > 0) {
-      dndLog.debug("collision:pointerWithin", { count: pointerCollisions.length, ids: pointerCollisions.map((c) => c.id) });
-      return pointerCollisions;
-    }
-    const rectCollisions = rectIntersection(args2);
-    if (rectCollisions.length > 0) {
-      dndLog.debug("collision:rectIntersection", { count: rectCollisions.length, ids: rectCollisions.map((c) => c.id) });
-      return rectCollisions;
-    }
-    const cornerCollisions = closestCorners(args2);
-    dndLog.debug("collision:closestCorners", { count: cornerCollisions.length, ids: cornerCollisions.map((c) => c.id) });
-    return cornerCollisions;
-  }, []);
+  const sensors = useAlmadarDndSensors(true);
+  const collisionDetection = almadarDndCollisionDetection;
   const findZoneByItem = React80__default.useCallback(
     (id) => {
       for (const z of zonesRef.current.values()) {
@@ -21491,6 +21499,7 @@ var init_useDataDnd = __esm({
   "components/molecules/useDataDnd.tsx"() {
     "use client";
     init_useEventBus();
+    init_useAlmadarDndCollision();
     init_Box();
     dndLog = createLogger("almadar:ui:dnd");
     RootCtx = React80__default.createContext(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "4.50.22",
+  "version": "4.51.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "sideEffects": [