@vuu-ui/vuu-utils 4.0.1 → 4.1.0

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.1",
+  "version": "4.1.0",
   "author": "heswell",
   "main": "./src/index.js",
   "license": "Apache-2.0",
@@ -14,15 +14,15 @@
     "@salt-ds/core": "1.74.0"
   },
   "devDependencies": {
-    "@dnd-kit/react": "^0.1.21",
-    "@vuu-ui/vuu-data-types": "4.0.1",
-    "@vuu-ui/vuu-table-types": "4.0.1",
-    "@vuu-ui/vuu-filter-types": "4.0.1",
-    "@vuu-ui/vuu-protocol-types": "4.0.1"
+    "@dnd-kit/react": "^0.5.0",
+    "@vuu-ui/vuu-data-types": "4.1.0",
+    "@vuu-ui/vuu-table-types": "4.1.0",
+    "@vuu-ui/vuu-filter-types": "4.1.0",
+    "@vuu-ui/vuu-protocol-types": "4.1.0"
   },
   "peerDependencies": {
     "@internationalized/date": "^3.0.0",
-    "@vuu-ui/vuu-filter-parser": "4.0.1",
+    "@vuu-ui/vuu-filter-parser": "4.1.0",
     "clsx": "^2.0.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3"

package/src/vendor/@dnd-kit/abstract/index.d.ts

@@ -57,6 +57,8 @@ interface Input$2<T extends Data = Data> {
  * @template T - The type of data associated with the entity.
  */
 declare class Entity<T extends Data = Data, U extends DragDropManager<any, any> = DragDropManager<any, any>> {
+    #private;
+    static pendingIdChanges: Map<Entity, UniqueIdentifier> | null;
     /**
      * Creates a new instance of the `Entity` class.
      *
@@ -68,14 +70,12 @@ declare class Entity<T extends Data = Data, U extends DragDropManager<any, any>
      * The manager that controls the drag and drop operations.
      */
     accessor manager: U | undefined;
-    /**
-     * The unique identifier of the entity.
-     */
-    accessor id: UniqueIdentifier;
+    get id(): UniqueIdentifier;
+    set id(value: UniqueIdentifier);
     /**
      * The data associated with the entity.
      */
-    accessor data: Data;
+    accessor data: T;
     /**
      * A boolean indicating whether the entity is disabled.
      */
@@ -247,10 +247,7 @@ declare abstract class Plugin<T extends DragDropManager<any, any> = DragDropMana
      * @param callback - The effect callback to register
      * @returns A function to dispose of the effect
      */
-    protected registerEffect(callback: () => void): {
-        (): void;
-        [Symbol.dispose](): void;
-    };
+    protected registerEffect(callback: () => void): CleanupFunction;
     /**
      * Destroys a plugin instance and cleans up its resources.
      *
@@ -371,7 +368,7 @@ declare function configure<T extends PluginConstructor<any, any, any>, V extends
  * @param plugin - The plugin constructor to configure
  * @returns A function that takes options and returns a plugin descriptor
  */
-declare function configurator<T extends PluginConstructor<any, any, any>>(plugin: T): (options: InferPluginOptions<T>) => PluginDescriptor<any, any, T>;
+declare function configurator<T extends PluginConstructor<any, any, any>>(plugin: T): (options: InferPluginOptions<T>) => PluginDescriptor<any, Plugin<any, InferPluginOptions<T>>, T>;
 /**
  * Normalizes a plugin constructor or descriptor into a descriptor.
  *
@@ -418,6 +415,12 @@ declare class Status {
      * @returns true if no drag operation is in progress
      */
     get idle(): boolean;
+    /**
+     * Checks if the status is initialization-pending.
+     *
+     * @returns true if a drag operation is about to start
+     */
+    get initializationPending(): boolean;
     /**
      * Checks if the status is initializing.
      *
@@ -506,7 +509,9 @@ declare class DragOperation<T extends Draggable, U extends Droppable> implements
     /**
      * Gets the source draggable entity.
      *
-     * @returns The current draggable entity or the previous one if the current is not found
+     * @returns The current draggable entity, falling back to the previous
+     * instance to bridge the gap when React unmounts and remounts a sortable
+     * during reparenting (e.g. moving an item between columns).
      */
     get source(): T | null;
     /**
@@ -668,6 +673,7 @@ interface Input$1<T extends Data = Data> extends Input$2<T> {
     sensors?: Sensors;
     modifiers?: Modifiers;
     alignment?: Alignment;
+    plugins?: Plugins;
 }
 /**
  * Possible status values for a draggable entity.
@@ -692,7 +698,7 @@ type DraggableStatus = 'idle' | 'dragging' | 'dropping';
  * - Status tracking during drag operations
  */
 declare class Draggable<T extends Data = Data, U extends DragDropManager<any, any> = DragDropManager<any, any>> extends Entity<T, U> {
-    constructor({ modifiers, type, sensors, ...input }: Input$1<T>, manager: U | undefined);
+    constructor({ modifiers, type, sensors, plugins, effects, ...input }: Input$1<T>, manager: U | undefined);
     /** The type of the draggable entity */
     accessor type: Type | undefined;
     /** The sensors associated with the draggable entity */
@@ -701,6 +707,12 @@ declare class Draggable<T extends Data = Data, U extends DragDropManager<any, an
     accessor modifiers: Modifiers | undefined;
     /** The alignment of the draggable entity */
     alignment: Alignment | undefined;
+    /** Per-entity plugin configuration descriptors */
+    plugins: Plugins | undefined;
+    /**
+     * Look up per-entity options for a given plugin constructor.
+     */
+    pluginConfig<P extends PluginConstructor>(plugin: P): PluginDescriptor<any, any, P>['options'] | undefined;
     /** The current status of the draggable entity */
     accessor status: DraggableStatus;
     /**
@@ -915,6 +927,38 @@ declare class Droppable<T extends Data = Data, U extends DragDropManager<any, an
     get isDropTarget(): boolean;
 }
 
+declare class ActivationController<E extends Event> extends AbortController {
+    private constraints;
+    private onActivate;
+    activated: boolean;
+    constructor(constraints: ActivationConstraints<E> | undefined, onActivate: (event: E) => void);
+    onEvent(event: E): void;
+    activate(event: E): void;
+    abort(event?: E): void;
+}
+interface ActivationConstraintOptions {
+}
+declare abstract class ActivationConstraint<E extends Event = Event, O extends ActivationConstraintOptions = ActivationConstraintOptions> {
+    #private;
+    protected options: O;
+    set controller(controller: ActivationController<E>);
+    constructor(options: O);
+    /**
+     * Called when the activation is triggered.
+     */
+    activate(event: E): void;
+    /**
+     * Called when the activation is aborted.
+     */
+    abstract abort(event?: E): void;
+    /**
+     * Called when an input event is received by the sensor.
+     * Returns `true` if this event triggers activation immediately.
+     */
+    abstract onEvent(event: E): void;
+}
+type ActivationConstraints<E extends Event> = ActivationConstraint<E>[];
+
 /**
  * Provides actions for controlling drag and drop operations.
  *
@@ -1119,41 +1163,42 @@ declare class Monitor<T extends Events> {
     protected dispatch<U extends keyof T>(name: U, ...args: any[]): void;
 }
 /**
- * Type definition for drag and drop events.
+ * Map of drag and drop event objects, keyed by event name.
+ * Follows the same pattern as the DOM's `WindowEventMap`.
  *
  * @template T - The type of draggable entities
  * @template U - The type of droppable entities
  * @template V - The type of drag and drop manager
  */
-type DragDropEvents<T extends Draggable, U extends Droppable, V extends DragDropManager<T, U>> = {
+type DragDropEventMap<T extends Draggable, U extends Droppable, V extends DragDropManager<T, U>> = {
     /** Event fired when collisions are detected */
-    collision(event: Preventable<{
+    collision: Preventable<{
         collisions: Collisions;
-    }>, manager: V): void;
+    }>;
     /** Event fired before a drag operation starts */
-    beforedragstart(event: Preventable<{
+    beforedragstart: Preventable<{
         operation: DragOperationSnapshot<T, U>;
         nativeEvent?: Event;
-    }>, manager: V): void;
+    }>;
     /** Event fired when a drag operation starts */
-    dragstart(event: {
+    dragstart: {
         cancelable: false;
         operation: DragOperationSnapshot<T, U>;
         nativeEvent?: Event;
-    }, manager: V): void;
+    };
     /** Event fired when a drag operation moves */
-    dragmove(event: Preventable<{
+    dragmove: Preventable<{
         operation: DragOperationSnapshot<T, U>;
         to?: Coordinates;
         by?: Coordinates;
         nativeEvent?: Event;
-    }>, manager: V): void;
+    }>;
     /** Event fired when a drag operation hovers over a droppable */
-    dragover(event: Preventable<{
+    dragover: Preventable<{
         operation: DragOperationSnapshot<T, U>;
-    }>, manager: V): void;
+    }>;
     /** Event fired when a drag operation ends */
-    dragend(event: {
+    dragend: {
         operation: DragOperationSnapshot<T, U>;
         nativeEvent?: Event;
         canceled: boolean;
@@ -1161,8 +1206,26 @@ type DragDropEvents<T extends Draggable, U extends Droppable, V extends DragDrop
             resume(): void;
             abort(): void;
         };
-    }, manager: V): void;
+    };
+};
+/**
+ * Map of drag and drop event handler signatures, keyed by event name.
+ * Each handler receives the event object and the manager instance.
+ * Derived from `DragDropEventMap`.
+ *
+ * @template T - The type of draggable entities
+ * @template U - The type of droppable entities
+ * @template V - The type of drag and drop manager
+ */
+type DragDropEventHandlers<T extends Draggable, U extends Droppable, V extends DragDropManager<T, U>> = {
+    [K in keyof DragDropEventMap<T, U, V>]: (event: DragDropEventMap<T, U, V>[K], manager: V) => void;
 };
+type CollisionEvent<T extends Draggable = Draggable, U extends Droppable = Droppable, V extends DragDropManager<T, U> = DragDropManager<T, U>> = DragDropEventMap<T, U, V>['collision'];
+type BeforeDragStartEvent<T extends Draggable = Draggable, U extends Droppable = Droppable, V extends DragDropManager<T, U> = DragDropManager<T, U>> = DragDropEventMap<T, U, V>['beforedragstart'];
+type DragStartEvent<T extends Draggable = Draggable, U extends Droppable = Droppable, V extends DragDropManager<T, U> = DragDropManager<T, U>> = DragDropEventMap<T, U, V>['dragstart'];
+type DragMoveEvent<T extends Draggable = Draggable, U extends Droppable = Droppable, V extends DragDropManager<T, U> = DragDropManager<T, U>> = DragDropEventMap<T, U, V>['dragmove'];
+type DragOverEvent<T extends Draggable = Draggable, U extends Droppable = Droppable, V extends DragDropManager<T, U> = DragDropManager<T, U>> = DragDropEventMap<T, U, V>['dragover'];
+type DragEndEvent<T extends Draggable = Draggable, U extends Droppable = Droppable, V extends DragDropManager<T, U> = DragDropManager<T, U>> = DragDropEventMap<T, U, V>['dragend'];
 /**
  * Monitors and dispatches drag and drop events.
  *
@@ -1170,7 +1233,7 @@ type DragDropEvents<T extends Draggable, U extends Droppable, V extends DragDrop
  * @template U - The type of droppable entities
  * @template V - The type of drag and drop manager
  */
-declare class DragDropMonitor<T extends Draggable, U extends Droppable, V extends DragDropManager<T, U>> extends Monitor<DragDropEvents<T, U, V>> {
+declare class DragDropMonitor<T extends Draggable, U extends Droppable, V extends DragDropManager<T, U>> extends Monitor<DragDropEventHandlers<T, U, V>> {
     private manager;
     /**
      * Creates a new drag and drop monitor.
@@ -1184,7 +1247,7 @@ declare class DragDropMonitor<T extends Draggable, U extends Droppable, V extend
      * @param type - The type of event to dispatch
      * @param event - The event data to dispatch
      */
-    dispatch<Key extends keyof DragDropEvents<T, U, V>>(type: Key, event: Parameters<DragDropEvents<T, U, V>[Key]>[0]): void;
+    dispatch<Key extends keyof DragDropEventMap<T, U, V>>(type: Key, event: DragDropEventMap<T, U, V>[Key]): void;
 }
 
 /**
@@ -1203,10 +1266,29 @@ interface Renderer {
     get rendering(): Promise<void>;
 }
 
+/**
+ * A value that can be provided as-is or as a function that receives defaults.
+ *
+ * @example
+ * // As a plain array (replaces defaults)
+ * plugins: [MyPlugin]
+ *
+ * // As a function (receives defaults)
+ * plugins: (defaults) => [...defaults, MyPlugin]
+ */
+type Customizable<T> = T | ((defaults: T) => T);
+/**
+ * Resolves a customizable value by applying it to defaults.
+ *
+ * @param value - A value or function that receives defaults
+ * @param defaults - The default value to use when undefined, or to pass to a function
+ * @returns The resolved value
+ */
+declare function resolveCustomizable<T>(value: Customizable<T> | undefined, defaults: T): T;
 type DragDropManagerInput<T extends DragDropManager<any, any>> = {
-    plugins?: Plugins<T>;
-    sensors?: Sensors<T>;
-    modifiers?: Modifiers<T>;
+    plugins?: Customizable<Plugins<T>>;
+    sensors?: Customizable<Sensors<T>>;
+    modifiers?: Customizable<Modifiers<T>>;
     renderer?: Renderer;
 };
 /**
@@ -1276,4 +1358,4 @@ declare class DragDropManager<T extends Draggable, U extends Droppable> {
     destroy: () => void;
 }
 
-export { type Collision, type CollisionDetector, CollisionPriority, CollisionType, CorePlugin, type Data, DragActions, type DragDropEvents, DragDropManager, type DragDropManagerInput, type DragOperationSnapshot as DragOperation, Status as DragOperationStatus, Draggable, type Input$1 as DraggableInput, Droppable, type Input as DroppableInput, Entity, Modifier, type ModifierConstructor, type Modifiers, Plugin, type PluginConstructor, type PluginDescriptor, type PluginOptions, PluginRegistry, type Plugins, type Renderer, Sensor, type SensorConstructor, type SensorDescriptor, type SensorOptions, type Sensors, type Type, type UniqueIdentifier, configurator, configure, descriptor, sortCollisions };
+export { ActivationConstraint, type ActivationConstraints, ActivationController, type BeforeDragStartEvent, type Collision, type CollisionDetector, type CollisionEvent, CollisionPriority, CollisionType, CorePlugin, type Customizable, type Data, DragActions, type DragDropEventHandlers, type DragDropEventMap, DragDropManager, type DragDropManagerInput, type DragEndEvent, type DragMoveEvent, type DragOperationSnapshot as DragOperation, Status as DragOperationStatus, type DragOverEvent, type DragStartEvent, Draggable, type Input$1 as DraggableInput, Droppable, type Input as DroppableInput, Entity, Modifier, type ModifierConstructor, type Modifiers, Plugin, type PluginConstructor, type PluginDescriptor, type PluginOptions, PluginRegistry, type Plugins, type Renderer, Sensor, type SensorConstructor, type SensorDescriptor, type SensorOptions, type Sensors, type Type, type UniqueIdentifier, configurator, configure, descriptor, resolveCustomizable, sortCollisions };