@svgrid/grid 1.0.2 → 1.1.1

package/src/named-views.coverage.test.ts

@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  attachAutoSavedView,
+  createNamedViews,
+  localStorageViews,
+  memoryViews,
+  type ViewStorage,
+} from './named-views'
+import type { SvGridViewState } from './svgrid-wrapper.types'
+
+function fakeHost(initial: Partial<SvGridViewState> = {}) {
+  let state = { sorting: [], columnFilters: [], ...initial } as SvGridViewState
+  return {
+    getState: () => state,
+    setState: vi.fn((s: Partial<SvGridViewState>) => {
+      state = { ...state, ...s }
+    }),
+    set: (s: SvGridViewState) => {
+      state = s
+    },
+  }
+}
+
+describe('createNamedViews - list ordering and edge cases', () => {
+  it('lists views sorted by createdAt ascending', () => {
+    const store = memoryViews([
+      { name: 'late', state: {}, createdAt: 200 },
+      { name: 'early', state: {}, createdAt: 100 },
+    ])
+    const views = createNamedViews(fakeHost(), { storage: store })
+    expect(views.list().map((v) => v.name)).toEqual(['early', 'late'])
+  })
+
+  it('defaults to memory storage when none is passed', () => {
+    const views = createNamedViews(fakeHost({ sorting: [{ id: 'a', desc: true }] }))
+    views.save('only')
+    expect(views.has('only')).toBe(true)
+    expect(views.list()).toHaveLength(1)
+  })
+
+  it('rename returns false when the source name is unknown', () => {
+    const views = createNamedViews(fakeHost(), { storage: memoryViews() })
+    views.save('a')
+    expect(views.rename('missing', 'b')).toBe(false)
+    expect(views.list().map((v) => v.name)).toEqual(['a'])
+  })
+
+  it('load returns false and does not call setState for unknown name', () => {
+    const host = fakeHost()
+    const views = createNamedViews(host, { storage: memoryViews() })
+    host.setState.mockClear()
+    expect(views.load('nope')).toBe(false)
+    expect(host.setState).not.toHaveBeenCalled()
+  })
+
+  it('save captures the current host state snapshot', () => {
+    const host = fakeHost({ sorting: [{ id: 'z', desc: false }] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const v = views.save('snap')
+    expect(v.state).toMatchObject({ sorting: [{ id: 'z', desc: false }] })
+    expect(typeof v.createdAt).toBe('number')
+  })
+})
+
+describe('localStorageViews', () => {
+  beforeEach(() => localStorage.clear())
+  afterEach(() => localStorage.clear())
+
+  it('reads [] when the key is absent', () => {
+    const store = localStorageViews('svgrid:absent')
+    expect(store.read()).toEqual([])
+  })
+
+  it('round-trips views through localStorage', () => {
+    const store = localStorageViews('svgrid:rt')
+    const views = [{ name: 'x', state: {}, createdAt: 1 }]
+    store.write(views)
+    expect(store.read()).toEqual(views)
+    // raw JSON is actually present
+    expect(JSON.parse(localStorage.getItem('svgrid:rt')!)).toEqual(views)
+  })
+
+  it('returns [] for corrupt JSON', () => {
+    localStorage.setItem('svgrid:bad', '{not valid json')
+    expect(localStorageViews('svgrid:bad').read()).toEqual([])
+  })
+
+  it('returns [] when the stored value is not an array', () => {
+    localStorage.setItem('svgrid:obj', JSON.stringify({ foo: 'bar' }))
+    expect(localStorageViews('svgrid:obj').read()).toEqual([])
+  })
+
+  it('swallows write errors (quota / private mode)', () => {
+    const store = localStorageViews('svgrid:quota')
+    const spy = vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('quota', 'QuotaExceededError')
+    })
+    expect(() => store.write([{ name: 'a', state: {}, createdAt: 1 }])).not.toThrow()
+    spy.mockRestore()
+  })
+
+  it('works end-to-end as a NamedViews adapter', () => {
+    const views = createNamedViews(fakeHost({ sorting: [{ id: 'p', desc: true }] }), {
+      storage: localStorageViews('svgrid:adapter'),
+    })
+    views.save('persisted')
+    const reopened = createNamedViews(fakeHost(), {
+      storage: localStorageViews('svgrid:adapter'),
+    })
+    expect(reopened.has('persisted')).toBe(true)
+    expect(reopened.load('persisted')).toBe(true)
+  })
+})
+
+describe('attachAutoSavedView', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('restores an existing autosave slot on attach', () => {
+    const host = fakeHost()
+    const store: ViewStorage = memoryViews([
+      { name: '__autosave', state: { sorting: [{ id: 'restored', desc: true }] }, createdAt: 1 },
+    ])
+    const views = createNamedViews(host, { storage: store })
+    const off = attachAutoSavedView(host, views)
+    expect(host.setState).toHaveBeenCalledWith(
+      expect.objectContaining({ sorting: [{ id: 'restored', desc: true }] }),
+    )
+    off()
+  })
+
+  it('skips restore when skipRestore is set', () => {
+    const host = fakeHost()
+    const store = memoryViews([{ name: '__autosave', state: { sorting: [] }, createdAt: 1 }])
+    const views = createNamedViews(host, { storage: store })
+    const off = attachAutoSavedView(host, views, { skipRestore: true })
+    expect(host.setState).not.toHaveBeenCalled()
+    off()
+  })
+
+  it('saves when the state snapshot changes after an interval', () => {
+    const host = fakeHost({ sorting: [] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const off = attachAutoSavedView(host, views, { intervalMs: 500 })
+    expect(views.has('__autosave')).toBe(false)
+    // mutate the host state, then let the poller tick
+    host.set({ sorting: [{ id: 'new', desc: false }], columnFilters: [] } as SvGridViewState)
+    vi.advanceTimersByTime(500)
+    expect(views.has('__autosave')).toBe(true)
+    off()
+  })
+
+  it('does not save when the snapshot is unchanged', () => {
+    const host = fakeHost({ sorting: [] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const saveSpy = vi.spyOn(views, 'save')
+    const off = attachAutoSavedView(host, views, { intervalMs: 300 })
+    vi.advanceTimersByTime(900) // several ticks, no state change
+    expect(saveSpy).not.toHaveBeenCalled()
+    off()
+  })
+
+  it('uses a custom slot name', () => {
+    const host = fakeHost({ sorting: [] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const off = attachAutoSavedView(host, views, { name: 'mySlot', intervalMs: 200 })
+    host.set({ sorting: [{ id: 'q', desc: true }], columnFilters: [] } as SvGridViewState)
+    vi.advanceTimersByTime(200)
+    expect(views.has('mySlot')).toBe(true)
+    off()
+  })
+
+  it('clamps the interval to a minimum of 100ms', () => {
+    const host = fakeHost({ sorting: [] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const setIntervalSpy = vi.spyOn(globalThis, 'setInterval')
+    const off = attachAutoSavedView(host, views, { intervalMs: 5 })
+    expect(setIntervalSpy).toHaveBeenCalledWith(expect.any(Function), 100)
+    off()
+    setIntervalSpy.mockRestore()
+  })
+
+  it('recovers when getState throws inside the poll loop', () => {
+    let throwing = false
+    const host = {
+      getState: () => {
+        if (throwing) throw new Error('boom')
+        return { sorting: [], columnFilters: [] } as SvGridViewState
+      },
+      setState: vi.fn(),
+    }
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const saveSpy = vi.spyOn(views, 'save')
+    const off = attachAutoSavedView(host, views, { intervalMs: 200 })
+    throwing = true
+    expect(() => vi.advanceTimersByTime(400)).not.toThrow()
+    expect(saveSpy).not.toHaveBeenCalled()
+    off()
+  })
+
+  it('detach stops the polling interval', () => {
+    const host = fakeHost({ sorting: [] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const clearSpy = vi.spyOn(globalThis, 'clearInterval')
+    const off = attachAutoSavedView(host, views, { intervalMs: 200 })
+    off()
+    expect(clearSpy).toHaveBeenCalled()
+    clearSpy.mockRestore()
+  })
+})

package/src/named-views.ts

@@ -118,3 +118,51 @@ export function createNamedViews(
     },
   }
 }
+
+export type AutoSavedViewOptions = {
+  /** Slot name inside the NamedViews store. Default `'__autosave'`. */
+  name?: string
+  /** Sample interval in ms. Default 800. */
+  intervalMs?: number
+  /** Skip restore-on-mount (e.g. you already loaded a URL view first). */
+  skipRestore?: boolean
+}
+
+/**
+ * Attach an "always-save-current-layout" slot to a `NamedViews` manager.
+ * Restores once on attach (if a saved view exists under `name`) and
+ * polls `host.getState()` thereafter, saving when the JSON snapshot
+ * changes.
+ *
+ * Returns a `detach()` that stops polling - call it from `onDestroy`.
+ *
+ * ```ts
+ * const views = createNamedViews(api, { storage: localStorageViews('myapp:views') })
+ * const off = attachAutoSavedView(api, views)
+ * onDestroy(off)
+ * ```
+ *
+ * Distinct from a user-saved named view: the slot is a single, fixed
+ * name reserved for "what the user left the page looking at." The user
+ * can still call `views.save('Q3 review')` etc. through the same store.
+ */
+export function attachAutoSavedView(
+  host: ViewStateHost,
+  views: NamedViews,
+  opts: AutoSavedViewOptions = {},
+): () => void {
+  const name = opts.name ?? '__autosave'
+  if (!opts.skipRestore && views.has(name)) views.load(name)
+
+  const interval = Math.max(100, opts.intervalMs ?? 800)
+  let last = JSON.stringify(host.getState())
+  const handle = setInterval(() => {
+    let next: string
+    try { next = JSON.stringify(host.getState()) } catch { return }
+    if (next === last) return
+    last = next
+    views.save(name)
+  }, interval)
+
+  return () => clearInterval(handle)
+}

package/src/row-drag.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for the managed row-drag handlers produced by createRowDrag(ctx).
+ *
+ * createRowDrag is a factory closing over a mutable `ctx` handle and a
+ * module-level singleton "bus" that carries the dragged row between grids.
+ * Because the bus is shared, we can create TWO fake ctxs (two grids) and drive
+ * a genuine grid-to-grid move without mounting anything.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createRowDrag, rowDropZone } from './row-drag'
+
+type AnyCtx = Record<string, any>
+type Task = { id: number; title: string }
+
+function makeCtx(rows: Task[], props: AnyCtx = {}): AnyCtx {
+  return {
+    props,
+    internalData: rows,
+    get allRows() {
+      // allRows tracks internalData order; each Row wraps `.original`.
+      return (this.internalData as Task[]).map((r) => ({ original: r }))
+    },
+    rowDragActive: false,
+    rowDropIndex: null,
+    rowDropSide: null,
+  }
+}
+
+function fakeEvent(clientY = 0, rectTop = 0, rectHeight = 40): any {
+  return {
+    clientY,
+    preventDefault: vi.fn(),
+    stopPropagation: vi.fn(),
+    dataTransfer: { setData: vi.fn(), effectAllowed: '', dropEffect: '' },
+    currentTarget: {
+      getBoundingClientRect: () => ({ top: rectTop, height: rectHeight, bottom: rectTop + rectHeight, left: 0 }),
+    },
+  }
+}
+
+const P = { rowDragManaged: true }
+
+describe('createRowDrag - same-grid reorder', () => {
+  it('moves a dragged row after the drop target', () => {
+    const rows: Task[] = [
+      { id: 1, title: 'a' },
+      { id: 2, title: 'b' },
+      { id: 3, title: 'c' },
+      { id: 4, title: 'd' },
+    ]
+    const ctx = makeCtx(rows, { ...P })
+    const h = createRowDrag(ctx)
+
+    h.onRowDragStart(fakeEvent(), 0) // drag "a"
+    ctx.rowDropSide = 'after'
+    h.onRowDrop(fakeEvent(), 2) // drop after "c"
+
+    expect((ctx.internalData as Task[]).map((r) => r.title)).toEqual(['b', 'c', 'a', 'd'])
+  })
+
+  it('drops before the target when the side is "before"', () => {
+    const rows: Task[] = [
+      { id: 1, title: 'a' },
+      { id: 2, title: 'b' },
+      { id: 3, title: 'c' },
+    ]
+    const ctx = makeCtx(rows, { ...P })
+    const h = createRowDrag(ctx)
+    h.onRowDragStart(fakeEvent(), 2) // drag "c"
+    ctx.rowDropSide = 'before'
+    h.onRowDrop(fakeEvent(), 0) // before "a"
+    expect((ctx.internalData as Task[]).map((r) => r.title)).toEqual(['c', 'a', 'b'])
+  })
+})
+
+describe('createRowDrag - grid-to-grid', () => {
+  it('moves a row from source into target when groups match', () => {
+    const a = makeCtx([{ id: 1, title: 'a1' }, { id: 2, title: 'a2' }], { ...P, rowDragGroup: 'g' })
+    const b = makeCtx([{ id: 9, title: 'b1' }], { ...P, rowDragGroup: 'g', onRowDragEnd: vi.fn() })
+    const ha = createRowDrag(a)
+    const hb = createRowDrag(b)
+
+    ha.onRowDragStart(fakeEvent(), 1) // drag "a2" out of grid A
+    b.rowDropSide = 'before'
+    hb.onRowDrop(fakeEvent(), 0) // drop onto grid B before "b1"
+
+    expect((a.internalData as Task[]).map((r) => r.title)).toEqual(['a1'])
+    expect((b.internalData as Task[]).map((r) => r.title)).toEqual(['a2', 'b1'])
+    expect(b.props.onRowDragEnd).toHaveBeenCalledWith(
+      expect.objectContaining({ sameGrid: false, toIndex: 0, row: expect.objectContaining({ title: 'a2' }) }),
+    )
+  })
+
+  it('does NOT accept a drop when groups differ', () => {
+    const a = makeCtx([{ id: 1, title: 'a1' }, { id: 2, title: 'a2' }], { ...P, rowDragGroup: 'g' })
+    const b = makeCtx([{ id: 9, title: 'b1' }], { ...P, rowDragGroup: 'other' })
+    const ha = createRowDrag(a)
+    const hb = createRowDrag(b)
+
+    ha.onRowDragStart(fakeEvent(), 0)
+    const ev = fakeEvent()
+    hb.onRowDragOver(ev, 0)
+    expect(ev.preventDefault).not.toHaveBeenCalled() // over rejected
+    hb.onRowDrop(fakeEvent(), 0)
+    expect((b.internalData as Task[]).map((r) => r.title)).toEqual(['b1']) // unchanged
+    expect((a.internalData as Task[]).length).toBe(2) // source untouched
+  })
+
+  it('appends to the target on an empty-space (container) drop', () => {
+    const a = makeCtx([{ id: 1, title: 'a1' }, { id: 2, title: 'a2' }], { ...P, rowDragGroup: 'g' })
+    const b = makeCtx([{ id: 9, title: 'b1' }], { ...P, rowDragGroup: 'g' })
+    const ha = createRowDrag(a)
+    const hb = createRowDrag(b)
+    ha.onRowDragStart(fakeEvent(), 0) // drag "a1"
+    hb.onRowsContainerDrop(fakeEvent())
+    expect((b.internalData as Task[]).map((r) => r.title)).toEqual(['b1', 'a1'])
+    expect((a.internalData as Task[]).map((r) => r.title)).toEqual(['a2'])
+  })
+})
+
+describe('createRowDrag - disabled', () => {
+  it('is inert when rowDragManaged is off', () => {
+    const ctx = makeCtx([{ id: 1, title: 'a' }, { id: 2, title: 'b' }], {})
+    const h = createRowDrag(ctx)
+    h.onRowDragStart(fakeEvent(), 0)
+    ctx.rowDropSide = 'after'
+    h.onRowDrop(fakeEvent(), 1)
+    expect((ctx.internalData as Task[]).map((r) => r.title)).toEqual(['a', 'b'])
+  })
+})
+
+describe('rowDropZone (external drop target)', () => {
+  function dropOn(el: HTMLElement) {
+    const ev = new Event('drop', { bubbles: true, cancelable: true })
+    el.dispatchEvent(ev)
+  }
+
+  it('removes the dragged row from its source grid and calls onDrop', () => {
+    const a = makeCtx([{ id: 1, title: 'a1' }, { id: 2, title: 'a2' }], { ...P, rowDragGroup: 'g' })
+    const ha = createRowDrag(a)
+    ha.onRowDragStart(fakeEvent(), 0) // start dragging "a1"
+
+    const el = document.createElement('div')
+    const dropped: any[] = []
+    const action = rowDropZone(el, { group: 'g', onDrop: (e) => dropped.push(e) })
+    dropOn(el)
+
+    expect(dropped.length).toBe(1)
+    expect(dropped[0].row.title).toBe('a1')
+    expect((a.internalData as Task[]).map((r) => r.title)).toEqual(['a2']) // removed from source
+    action.destroy()
+  })
+
+  it('ignores drops when the group does not match', () => {
+    const a = makeCtx([{ id: 1, title: 'a1' }], { ...P, rowDragGroup: 'g' })
+    const ha = createRowDrag(a)
+    ha.onRowDragStart(fakeEvent(), 0)
+
+    const el = document.createElement('div')
+    const dropped: any[] = []
+    const action = rowDropZone(el, { group: 'other', onDrop: (e) => dropped.push(e) })
+    dropOn(el)
+
+    expect(dropped.length).toBe(0)
+    expect((a.internalData as Task[]).length).toBe(1) // untouched
+    action.destroy()
+  })
+})

package/src/row-drag.ts

@@ -0,0 +1,255 @@
+// Managed row dragging - reorder rows within a grid and move rows between
+// grids that share a `rowDragGroup`. "Managed" means the grid mutates its own
+// `internalData` on drop (splice out of the source, splice into the target) so
+// consumers get working drag-and-drop with zero wiring; an optional
+// `onRowDragEnd` callback lets them mirror the change into their own state.
+//
+// Cross-grid coordination rides on a module-level singleton (`bus`). Because
+// every SvGrid instance in a bundle shares this module, the source grid can
+// hand the target grid both the dragged row and a closure that removes it from
+// the source - the missing half of an HTML5 drag payload, which only carries
+// strings. Rows are matched by object identity, so this works without
+// `getRowId`.
+
+type RowDragBus = {
+  group: string | null;
+  gridId: number;
+  row: unknown;
+  removeFromSource: () => void;
+  sourceProps: { onRowDragEnd?: (e: RowDragEndEvent) => void };
+};
+
+export type RowDragEndEvent<TData = unknown> = {
+  row: TData;
+  toIndex: number;
+  sameGrid: boolean;
+  fromGridId: number;
+  toGridId: number;
+};
+
+// Shared across all grids in the bundle - this is what makes grid-to-grid work.
+let bus: RowDragBus | null = null;
+let gridSeq = 0;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createRowDrag<TFeatures, TData>(ctx: any) {
+  const gridId = ++gridSeq;
+
+  const managed = () => ctx.props.rowDragManaged === true;
+  const group = (): string | null => ctx.props.rowDragGroup ?? null;
+
+  function originalAt(rowIndex: number): unknown {
+    const r = ctx.allRows[rowIndex];
+    return r ? r.original : null;
+  }
+
+  // Can THIS grid accept the row currently on the bus? Same grid always may
+  // (a reorder); a different grid only when both opt into the same group.
+  function canAccept(): boolean {
+    if (!managed() || !bus) return false;
+    if (bus.gridId === gridId) return true;
+    return bus.group != null && bus.group === group();
+  }
+
+  function clearIndicators() {
+    ctx.rowDragActive = false;
+    ctx.rowDropIndex = null;
+    ctx.rowDropSide = null;
+  }
+
+  function emitEnd(row: unknown, toIndex: number, sameGrid: boolean, fromGridId: number) {
+    ctx.props.onRowDragEnd?.({
+      row,
+      toIndex,
+      sameGrid,
+      fromGridId,
+      toGridId: gridId,
+    } as RowDragEndEvent<TData>);
+  }
+
+  function onRowDragStart(e: DragEvent, rowIndex: number) {
+    if (!managed()) return;
+    const row = originalAt(rowIndex);
+    if (row == null) return;
+    bus = {
+      group: group(),
+      gridId,
+      row,
+      sourceProps: ctx.props,
+      removeFromSource: () => {
+        ctx.internalData = (ctx.internalData as unknown[]).filter((r) => r !== row);
+      },
+    };
+    ctx.rowDragActive = true;
+    try {
+      e.dataTransfer?.setData("text/plain", String(rowIndex));
+      if (e.dataTransfer) e.dataTransfer.effectAllowed = "move";
+    } catch {
+      // Some environments (tests) provide a partial dataTransfer.
+    }
+  }
+
+  function onRowDragOver(e: DragEvent, rowIndex: number) {
+    if (!canAccept()) return;
+    e.preventDefault();
+    if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+    ctx.rowDropIndex = rowIndex;
+    ctx.rowDropSide = e.clientY < rect.top + rect.height / 2 ? "before" : "after";
+  }
+
+  function onRowDragLeave(rowIndex: number) {
+    if (ctx.rowDropIndex === rowIndex) {
+      ctx.rowDropIndex = null;
+      ctx.rowDropSide = null;
+    }
+  }
+
+  function onRowDrop(e: DragEvent, rowIndex: number) {
+    if (!canAccept() || !bus) return;
+    e.preventDefault();
+    e.stopPropagation(); // don't let the tbody handler also fire (end-append)
+    const side = ctx.rowDropSide ?? "before";
+    const dragged = bus.row;
+    const target = originalAt(rowIndex);
+    const sourceGridId = bus.gridId;
+    const sameGrid = sourceGridId === gridId;
+    clearIndicators();
+
+    const data = (ctx.internalData as unknown[]).slice();
+    if (sameGrid) {
+      const from = data.indexOf(dragged);
+      if (from < 0) {
+        bus = null;
+        return;
+      }
+      data.splice(from, 1);
+    }
+    let to = target != null ? data.indexOf(target) : data.length;
+    if (to < 0) to = data.length;
+    if (side === "after") to += 1;
+    data.splice(to, 0, dragged);
+    ctx.internalData = data;
+    if (!sameGrid) bus.removeFromSource();
+    emitEnd(dragged, to, sameGrid, sourceGridId);
+    bus = null;
+  }
+
+  // Dropping in the empty area below the last row, or into an empty target
+  // grid, appends. Row-level drops call stopPropagation so this only fires for
+  // genuine empty-space drops.
+  function onRowsContainerDragOver(e: DragEvent) {
+    if (!canAccept()) return;
+    e.preventDefault();
+    if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+  }
+
+  function onRowsContainerDrop(e: DragEvent) {
+    if (!canAccept() || !bus) return;
+    e.preventDefault();
+    const dragged = bus.row;
+    const sourceGridId = bus.gridId;
+    const sameGrid = sourceGridId === gridId;
+    clearIndicators();
+
+    const data = (ctx.internalData as unknown[]).slice();
+    if (sameGrid) {
+      const from = data.indexOf(dragged);
+      if (from >= 0) data.splice(from, 1);
+    }
+    data.push(dragged);
+    ctx.internalData = data;
+    if (!sameGrid) bus.removeFromSource();
+    emitEnd(dragged, data.length - 1, sameGrid, sourceGridId);
+    bus = null;
+  }
+
+  function onRowDragEnd() {
+    clearIndicators();
+    bus = null;
+  }
+
+  return {
+    onRowDragStart,
+    onRowDragOver,
+    onRowDragLeave,
+    onRowDrop,
+    onRowsContainerDragOver,
+    onRowsContainerDrop,
+    onRowDragEnd,
+    rowDragGridId: gridId,
+  };
+}
+
+/** Options for the {@link rowDropZone} action. */
+export type RowDropZoneOptions<TData = unknown> = {
+  /**
+   * Only accept rows dragged from a grid with this `rowDragGroup`. Omit to
+   * accept a managed row drag from any grid.
+   */
+  group?: string;
+  /**
+   * Called when a managed row is dropped on the element. The row has already
+   * been removed from its source grid; add it to your own list/state here.
+   */
+  onDrop: (payload: { row: TData; fromGridId: number }) => void;
+  /** Class toggled on the element while a matching row is dragged over it. */
+  overClass?: string;
+};
+
+/**
+ * Svelte action turning ANY element into an external drop target for managed
+ * row dragging - a trash can, an "assign to" bucket, a second pane. Attach with
+ * `use:rowDropZone={{ group, onDrop }}`. On drop the dragged row is removed from
+ * its source grid and handed to `onDrop`.
+ *
+ * ```svelte
+ * <div use:rowDropZone={{ group: 'board', onDrop: (e) => archive(e.row) }}>Archive</div>
+ * ```
+ */
+export function rowDropZone<TData = unknown>(
+  node: HTMLElement,
+  options: RowDropZoneOptions<TData>,
+) {
+  let opts = options;
+  const cls = () => opts.overClass ?? "sv-grid-row-dropzone-over";
+
+  function matches(): boolean {
+    if (!bus) return false;
+    return opts.group == null || bus.group === opts.group;
+  }
+  function onOver(e: DragEvent) {
+    if (!matches()) return;
+    e.preventDefault();
+    if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+    node.classList.add(cls());
+  }
+  function onLeave() {
+    node.classList.remove(cls());
+  }
+  function onDrop(e: DragEvent) {
+    if (!matches() || !bus) return;
+    e.preventDefault();
+    e.stopPropagation();
+    node.classList.remove(cls());
+    const row = bus.row as TData;
+    const fromGridId = bus.gridId;
+    bus.removeFromSource();
+    bus = null;
+    opts.onDrop({ row, fromGridId });
+  }
+
+  node.addEventListener("dragover", onOver);
+  node.addEventListener("dragleave", onLeave);
+  node.addEventListener("drop", onDrop);
+  return {
+    update(next: RowDropZoneOptions<TData>) {
+      opts = next;
+    },
+    destroy() {
+      node.removeEventListener("dragover", onOver);
+      node.removeEventListener("dragleave", onLeave);
+      node.removeEventListener("drop", onDrop);
+    },
+  };
+}