@cocoar/vue-ui 1.10.0 → 1.11.0

package/dist/composables/dragRegistry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Module-level registry that carries live item references across HTML5 drag-and-drop
+ * events. Used by {@link useDragDrop} to exchange payloads between independent Vue
+ * components — the browser's `DataTransfer` API only accepts strings, so we serialize
+ * a drag id there and keep the actual payload (with object identity preserved) here.
+ *
+ * Exported for advanced integrations that want to implement their own drag handlers
+ * while staying compatible with {@link useDragDrop}'s matching rules.
+ */
+export declare const DRAG_MIME = "application/x-coar-dnd";
+export interface DragEntry<T = unknown> {
+    /** Random drag-session id (stored in DataTransfer as a string). */
+    id: string;
+    /** Stable id of the source surface — used to detect self-drops. */
+    sourceId: string;
+    /** Public identifier the consumer gave the source via `dragId`, if any. */
+    fromId: string | null;
+    /** Optional drag group name. Only surfaces sharing a group accept each other's items. */
+    dragGroup: string | null;
+    /** The actual items being dragged. */
+    items: readonly T[];
+    /**
+     * Invoked by the drop target when it accepts the drop. The source uses this to
+     * emit its "items-removed" callback synchronously — avoiding the brief "duplicated
+     * items" window between `drop` on the target and `dragend` on the source.
+     */
+    onAcceptedBy?: (targetId: string, insertIndex: number | null) => void;
+    /** Flag set by a target on accept so the source's `dragend` can report `dropped: true`. */
+    consumed?: boolean;
+}
+export declare function registerDrag<T>(entry: DragEntry<T>): void;
+export declare function getDrag<T>(id: string): DragEntry<T> | undefined;
+/**
+ * Returns the drag session currently in flight — readable during `dragover`
+ * events, where the browser refuses to expose `DataTransfer.getData()`.
+ */
+export declare function getActiveDrag<T>(): DragEntry<T> | undefined;
+export declare function deleteDrag(id: string): void;
+//# sourceMappingURL=dragRegistry.d.ts.map

package/dist/composables/dragRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dragRegistry.d.ts","sourceRoot":"","sources":["../../src/composables/dragRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,SAAS,2BAA2B,CAAC;AAElD,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,yFAAyF;IACzF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sCAAsC;IACtC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACtE,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAKD,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAGzD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAE/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAE3D;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG3C"}

package/dist/composables/index.d.ts

@@ -0,0 +1,7 @@
+export { useVirtualList } from './useVirtualList';
+export type { UseVirtualListOptions, UseVirtualListReturn, VirtualRow, } from './useVirtualList';
+export { useDragDrop } from './useDragDrop';
+export type { UseDragDropOptions, UseDragDropReturn, DropPayload, } from './useDragDrop';
+export { DRAG_MIME, registerDrag, getDrag, getActiveDrag, deleteDrag, } from './dragRegistry';
+export type { DragEntry } from './dragRegistry';
+//# sourceMappingURL=index.d.ts.map

package/dist/composables/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/composables/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,UAAU,GACX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,OAAO,EACP,aAAa,EACb,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/composables/useDragDrop.d.ts

@@ -0,0 +1,109 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+/** Payload surfaced to `canDrop` checks and the `onDropAccept` callback. */
+export interface DropPayload<T> {
+    /** The items being dropped. */
+    items: readonly T[];
+    /** Public identifier of the source surface, if it set `dragId`. */
+    fromId: string | null;
+    /** Drag group of the source surface. */
+    fromGroup: string | null;
+    /** True when the source and target are the same surface (drag within one list). */
+    fromSelf: boolean;
+}
+export interface UseDragDropOptions<T> {
+    /** Public identifier for this surface. Auto-generated per instance if not set. */
+    dragId?: MaybeRefOrGetter<string | undefined>;
+    /**
+     * Shared name linking compatible surfaces. Items can only cross between surfaces
+     * with the same `dragGroup`. A surface without a group still accepts self-drops.
+     */
+    dragGroup?: MaybeRefOrGetter<string | undefined>;
+    /**
+     * Whitelist of source `dragId`s this surface accepts items from. When set, drops
+     * are only accepted if the source's `dragId` is listed. Unset = accept from any
+     * surface in the same `dragGroup`.
+     */
+    dragAccept?: MaybeRefOrGetter<string[] | undefined>;
+    /**
+     * Runtime target validation. Called on `dragover` and `drop`. Return `false`
+     * to refuse the drop — the cursor shows "not allowed" and nothing happens.
+     */
+    canDrop?: (payload: DropPayload<T>) => boolean;
+    /** Fired after `startDrag` succeeds. */
+    onDragStart?: (items: readonly T[]) => void;
+    /**
+     * Fired on `dragend` (whether the drop was accepted or cancelled). `dropped` is
+     * `true` when some target consumed the payload.
+     */
+    onDragEnd?: (payload: {
+        items: readonly T[];
+        dropped: boolean;
+    }) => void;
+    /**
+     * Fired on this surface when it accepts a drop. Consumers update their own
+     * source-of-truth here (append items, insert at `insertIndex`, etc.).
+     */
+    onDropAccept?: (payload: DropPayload<T> & {
+        insertIndex: number | null;
+    }) => void;
+    /**
+     * Fired on the *source* surface when another target consumed its payload.
+     * Consumers update their own source-of-truth here (remove the items).
+     * Fires synchronously inside the target's `drop`, before the source's `dragend`.
+     */
+    onItemsRemove?: (payload: {
+        items: readonly T[];
+        toGroup: string | null;
+    }) => void;
+}
+export interface UseDragDropReturn<T> {
+    /** Stable instance id — use it when you need to distinguish surfaces externally. */
+    instanceId: string;
+    /** `true` while a compatible drag is hovering this surface (clears on leave/drop). */
+    isDragOver: Ref<boolean>;
+    /** `true` while this surface is the source of an in-flight drag. */
+    isDragging: Ref<boolean>;
+    /**
+     * Call from a `@dragstart` handler on a draggable element. Pass the payload you
+     * want to transfer. Returns `true` if the drag was registered, `false` if the
+     * event had no `dataTransfer` or items was empty.
+     */
+    startDrag(event: DragEvent, items: readonly T[]): boolean;
+    /** Call from a `@dragend` handler on the draggable element. Cleans up the session. */
+    endDrag(): void;
+    /** Call from the drop container's `@dragover`. */
+    onDragOver(event: DragEvent): void;
+    /** Call from the drop container's `@dragleave`. */
+    onDragLeave(event: DragEvent): void;
+    /**
+     * Call from the drop container's (or an inner drop target's) `@drop`. Pass an
+     * optional `insertIndex` to tell consumers where the drop landed (null = append).
+     */
+    onDrop(event: DragEvent, context?: {
+        insertIndex?: number | null;
+    }): void;
+}
+/**
+ * Framework-agnostic HTML5 drag-and-drop primitive used across Cocoar UI
+ * components. Decouples "what is being dragged" (your items) from the
+ * registration bookkeeping (group matching, whitelists, runtime validation,
+ * source-side cleanup).
+ *
+ * Usage:
+ * ```ts
+ * const dnd = useDragDrop<Row>({
+ *   dragGroup: 'rows',
+ *   onDropAccept: ({ items }) => { rows.value = [...rows.value, ...items] },
+ *   onItemsRemove: ({ items }) => {
+ *     const keep = new Set(rows.value); items.forEach(i => keep.delete(i));
+ *     rows.value = [...keep];
+ *   },
+ * })
+ *
+ * // In template:
+ * // <div draggable @dragstart="dnd.startDrag($event, [row])" @dragend="dnd.endDrag">
+ * // <div @dragover="dnd.onDragOver" @dragleave="dnd.onDragLeave" @drop="dnd.onDrop">
+ * ```
+ */
+export declare function useDragDrop<T>(opts?: UseDragDropOptions<T>): UseDragDropReturn<T>;
+//# sourceMappingURL=useDragDrop.d.ts.map

package/dist/composables/useDragDrop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDragDrop.d.ts","sourceRoot":"","sources":["../../src/composables/useDragDrop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAUpE,4EAA4E;AAC5E,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,+BAA+B;IAC/B,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IACpB,mEAAmE;IACnE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wCAAwC;IACxC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mFAAmF;IACnF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,kFAAkF;IAClF,MAAM,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD;;;;OAIG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAEpD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IAE/C,wCAAwC;IACxC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC;IAC5C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACzE;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG;QAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,CAAC;IAClF;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,CAAC;CACpF;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,oEAAoE;IACpE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAGzB;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,OAAO,CAAC;IAC1D,sFAAsF;IACtF,OAAO,IAAI,IAAI,CAAC;IAGhB,kDAAkD;IAClD,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACnC,mDAAmD;IACnD,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3E;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,GAAE,kBAAkB,CAAC,CAAC,CAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CA6HrF"}

package/dist/composables/useVirtualList.d.ts

@@ -0,0 +1,52 @@
+import { MaybeRefOrGetter, Ref, ComputedRef } from 'vue';
+/** Options for {@link useVirtualList}. */
+export interface UseVirtualListOptions {
+    /** Total number of items in the virtual list. */
+    count: MaybeRefOrGetter<number>;
+    /**
+     * Row height in pixels — either a fixed number, or a function that returns
+     * the height for a given index. Reactive: if you pass a ref, changes invalidate
+     * the offset cache automatically.
+     */
+    itemSize: MaybeRefOrGetter<number | ((index: number) => number)>;
+    /** Rows rendered above/below the viewport as a scroll buffer. Default 5. */
+    overscan?: MaybeRefOrGetter<number>;
+    /** The scrollable element — typically a template ref on the scrolling container. */
+    scrollElement: Ref<HTMLElement | null>;
+}
+/** One positioned row produced by the virtualizer. */
+export interface VirtualRow {
+    /** Position in the underlying list (0 .. count - 1). */
+    index: number;
+    /** Pixel offset from the top of the spacer. */
+    start: number;
+    /** Row height in pixels. */
+    size: number;
+}
+export interface UseVirtualListReturn {
+    /** Slice of rows currently inside the viewport + overscan window. */
+    virtualRows: ComputedRef<VirtualRow[]>;
+    /** Total pixel height of the full list — use this for the scroll spacer. */
+    totalSize: ComputedRef<number>;
+    /** Programmatically scroll an index into view. */
+    scrollToIndex(index: number, align?: 'auto' | 'start' | 'center' | 'end'): void;
+    /** Inspect the precomputed offset for an index (debug/tests). */
+    offsetFor(index: number): number;
+}
+/**
+ * Minimal fixed-viewport virtualizer. Keeps a cumulative offset table so both
+ * fixed and per-index heights are O(log n) per scroll event, without any
+ * external dependencies.
+ *
+ * Usage:
+ * ```ts
+ * const scrollEl = useTemplateRef('scroll')
+ * const { virtualRows, totalSize, scrollToIndex } = useVirtualList({
+ *   count: () => items.length,
+ *   itemSize: 32,
+ *   scrollElement: scrollEl,
+ * })
+ * ```
+ */
+export declare function useVirtualList(opts: UseVirtualListOptions): UseVirtualListReturn;
+//# sourceMappingURL=useVirtualList.d.ts.map

package/dist/composables/useVirtualList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualList.d.ts","sourceRoot":"","sources":["../../src/composables/useVirtualList.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,GAAG,EACR,KAAK,WAAW,EACjB,MAAM,KAAK,CAAC;AAEb,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,KAAK,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC;;;;OAIG;IACH,QAAQ,EAAE,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC;IACjE,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACpC,oFAAoF;IACpF,aAAa,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACxC;AAED,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,WAAW,EAAE,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;IACvC,4EAA4E;IAC5E,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/B,kDAAkD;IAClD,aAAa,CACX,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAC1C,IAAI,CAAC;IACR,iEAAiE;IACjE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CA0KhF"}