@adia-ai/web-components 0.2.2 → 0.2.4

package/traits/drop-target.test.js

@@ -0,0 +1,241 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { dropTarget } from './drop-target.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './test-helpers.js';
+
+/**
+ * happy-dom's DragEvent constructor does NOT preserve the `dataTransfer`
+ * field passed via the init dict (verified at authoring time:
+ * `new DragEvent('dragover', { dataTransfer })` then `.dataTransfer`
+ * comes back as null). We synthesize the event by creating an Event,
+ * then defining `dataTransfer` as a non-enumerable read-only property —
+ * the trait reads it the same way the browser would.
+ */
+function fireDragEvent(host, type, dataTransfer = null) {
+  const ev = new Event(type, { bubbles: true, cancelable: true });
+  Object.defineProperty(ev, 'dataTransfer', {
+    value: dataTransfer,
+    writable: false,
+    configurable: true,
+  });
+  host.dispatchEvent(ev);
+  return ev;
+}
+
+function fakeDataTransfer({ types = [], items = [] } = {}) {
+  return {
+    types,
+    items,
+    files: items.filter((i) => i.kind === 'file').map((i) => i.file).filter(Boolean),
+    getData: () => '',
+    setData: () => {},
+  };
+}
+
+describe('drop-target', () => {
+  beforeEach(resetDOM);
+
+  it('sets data-drop-target-active on connect, removes on disconnect', () => {
+    const host = mountHost();
+    const inst = connectTrait(dropTarget, host);
+    expect(host.hasAttribute('data-drop-target-active')).toBe(true);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-drop-target-active')).toBe(false);
+  });
+
+  it('dragenter sets data-drop-target-over and dispatches drop-enter', () => {
+    const host = mountHost();
+    connectTrait(dropTarget, host);
+    const spy = spyEvent(host, 'drop-enter');
+    fireDragEvent(host, 'dragenter', fakeDataTransfer());
+    expect(host.hasAttribute('data-drop-target-over')).toBe(true);
+    expect(spy.count).toBe(1);
+  });
+
+  it('dragleave clears data-drop-target-over and dispatches drop-leave', () => {
+    const host = mountHost();
+    connectTrait(dropTarget, host);
+    const enterSpy = spyEvent(host, 'drop-enter');
+    const leaveSpy = spyEvent(host, 'drop-leave');
+    fireDragEvent(host, 'dragenter', fakeDataTransfer());
+    fireDragEvent(host, 'dragleave', fakeDataTransfer());
+    expect(host.hasAttribute('data-drop-target-over')).toBe(false);
+    expect(enterSpy.count).toBe(1);
+    expect(leaveSpy.count).toBe(1);
+  });
+
+  it('dragenter from descendant nesting only emits one drop-enter', () => {
+    const host = mountHost();
+    connectTrait(dropTarget, host);
+    const enterSpy = spyEvent(host, 'drop-enter');
+    const leaveSpy = spyEvent(host, 'drop-leave');
+    // Two enters (host then descendant) should produce ONE drop-enter
+    // and NOT clear the over-state when one matching leave fires.
+    fireDragEvent(host, 'dragenter', fakeDataTransfer());
+    fireDragEvent(host, 'dragenter', fakeDataTransfer());
+    fireDragEvent(host, 'dragleave', fakeDataTransfer());
+    expect(enterSpy.count).toBe(1);
+    expect(leaveSpy.count).toBe(0);
+    expect(host.hasAttribute('data-drop-target-over')).toBe(true);
+    // The matched leave finally clears.
+    fireDragEvent(host, 'dragleave', fakeDataTransfer());
+    expect(leaveSpy.count).toBe(1);
+    expect(host.hasAttribute('data-drop-target-over')).toBe(false);
+  });
+
+  it('dragover calls preventDefault when no accept filter is set', () => {
+    const host = mountHost();
+    connectTrait(dropTarget, host);
+    const ev = fireDragEvent(host, 'dragover', fakeDataTransfer({ types: ['text/plain'] }));
+    expect(ev.defaultPrevented).toBe(true);
+  });
+
+  it('dragover with empty accept attribute still accepts (preventDefault)', () => {
+    const host = mountHost('div', { 'data-drop-target-accepts': '' });
+    connectTrait(dropTarget, host);
+    const ev = fireDragEvent(host, 'dragover', fakeDataTransfer({ types: ['text/plain'] }));
+    expect(ev.defaultPrevented).toBe(true);
+  });
+
+  it('accepts="files" — accepts file drags, rejects non-file payloads', () => {
+    const host = mountHost('div', { 'data-drop-target-accepts': 'files' });
+    connectTrait(dropTarget, host);
+    const rejectedSpy = spyEvent(host, 'drop-rejected');
+
+    // File drag — Files token present → accepted
+    const fileEv = fireDragEvent(host, 'dragover', fakeDataTransfer({ types: ['Files'] }));
+    expect(fileEv.defaultPrevented).toBe(true);
+    expect(host.hasAttribute('data-drop-target-rejected')).toBe(false);
+
+    // Plain text drag — no Files → rejected, no preventDefault
+    const textEv = fireDragEvent(host, 'dragover', fakeDataTransfer({ types: ['text/plain'] }));
+    expect(textEv.defaultPrevented).toBe(false);
+    expect(host.getAttribute('data-drop-target-rejected')).toBe('files-only');
+    expect(rejectedSpy.count).toBe(1);
+    expect(rejectedSpy.last.reason).toBe('files-only');
+  });
+
+  it('accepts="image/png,image/jpeg" — rejects mismatched MIME types', () => {
+    const host = mountHost('div', { 'data-drop-target-accepts': 'image/png,image/jpeg' });
+    connectTrait(dropTarget, host);
+
+    // Direct text type → rejected
+    const textEv = fireDragEvent(host, 'dragover', fakeDataTransfer({ types: ['text/plain'] }));
+    expect(textEv.defaultPrevented).toBe(false);
+    expect(host.getAttribute('data-drop-target-rejected')).toBe('type');
+
+    // PNG file drag → accepted
+    const pngDt = fakeDataTransfer({
+      types: ['Files'],
+      items: [{ kind: 'file', type: 'image/png' }],
+    });
+    const pngEv = fireDragEvent(host, 'dragover', pngDt);
+    expect(pngEv.defaultPrevented).toBe(true);
+    expect(host.hasAttribute('data-drop-target-rejected')).toBe(false);
+
+    // PDF file drag → rejected
+    const pdfDt = fakeDataTransfer({
+      types: ['Files'],
+      items: [{ kind: 'file', type: 'application/pdf' }],
+    });
+    const pdfEv = fireDragEvent(host, 'dragover', pdfDt);
+    expect(pdfEv.defaultPrevented).toBe(false);
+    expect(host.getAttribute('data-drop-target-rejected')).toBe('type');
+  });
+
+  it('drop dispatches drop-receive with dataTransfer detail', () => {
+    const host = mountHost();
+    connectTrait(dropTarget, host);
+    const spy = spyEvent(host, 'drop-receive');
+    const dt = fakeDataTransfer({ types: ['text/plain'] });
+
+    fireDragEvent(host, 'dragenter', dt);
+    fireDragEvent(host, 'dragover', dt);
+    const dropEv = fireDragEvent(host, 'drop', dt);
+    expect(dropEv.defaultPrevented).toBe(true);
+    expect(spy.count).toBe(1);
+    expect(spy.last.dataTransfer).toBe(dt);
+  });
+
+  it('drop clears data-drop-target-over after firing drop-receive', () => {
+    const host = mountHost();
+    connectTrait(dropTarget, host);
+    const dt = fakeDataTransfer({ types: ['text/plain'] });
+    fireDragEvent(host, 'dragenter', dt);
+    expect(host.hasAttribute('data-drop-target-over')).toBe(true);
+    fireDragEvent(host, 'drop', dt);
+    expect(host.hasAttribute('data-drop-target-over')).toBe(false);
+  });
+
+  it('drop on rejected payload dispatches drop-rejected, not drop-receive', () => {
+    const host = mountHost('div', { 'data-drop-target-accepts': 'image/png' });
+    connectTrait(dropTarget, host);
+    const receiveSpy = spyEvent(host, 'drop-receive');
+    const rejectedSpy = spyEvent(host, 'drop-rejected');
+    const dt = fakeDataTransfer({ types: ['text/plain'] });
+
+    fireDragEvent(host, 'drop', dt);
+    expect(receiveSpy.count).toBe(0);
+    expect(rejectedSpy.count).toBe(1);
+    expect(rejectedSpy.last.reason).toBe('type');
+  });
+
+  it('respects [disabled] — no event, no over-state', () => {
+    const host = mountHost('div', { disabled: '' });
+    connectTrait(dropTarget, host);
+    const enterSpy = spyEvent(host, 'drop-enter');
+    const receiveSpy = spyEvent(host, 'drop-receive');
+
+    fireDragEvent(host, 'dragenter', fakeDataTransfer());
+    fireDragEvent(host, 'dragover', fakeDataTransfer());
+    fireDragEvent(host, 'drop', fakeDataTransfer());
+
+    expect(host.hasAttribute('data-drop-target-over')).toBe(false);
+    expect(enterSpy.count).toBe(0);
+    expect(receiveSpy.count).toBe(0);
+  });
+
+  it('disconnect removes listeners and clears managed attributes', () => {
+    const host = mountHost();
+    const inst = connectTrait(dropTarget, host);
+    fireDragEvent(host, 'dragenter', fakeDataTransfer());
+    expect(host.hasAttribute('data-drop-target-over')).toBe(true);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-drop-target-over')).toBe(false);
+    expect(host.hasAttribute('data-drop-target-active')).toBe(false);
+    expect(host.hasAttribute('data-drop-target-rejected')).toBe(false);
+
+    // Re-firing post-disconnect is a no-op.
+    const spy = spyEvent(host, 'drop-enter');
+    fireDragEvent(host, 'dragenter', fakeDataTransfer());
+    expect(spy.count).toBe(0);
+  });
+
+  it('clears data-drop-target-rejected when dragover later sees an accepted payload', () => {
+    const host = mountHost('div', { 'data-drop-target-accepts': 'image/png' });
+    connectTrait(dropTarget, host);
+
+    fireDragEvent(host, 'dragover', fakeDataTransfer({ types: ['text/plain'] }));
+    expect(host.getAttribute('data-drop-target-rejected')).toBe('type');
+
+    const pngDt = fakeDataTransfer({
+      types: ['Files'],
+      items: [{ kind: 'file', type: 'image/png' }],
+    });
+    fireDragEvent(host, 'dragover', pngDt);
+    expect(host.hasAttribute('data-drop-target-rejected')).toBe(false);
+  });
+
+  it('dispatches drop-rejected only once per rejection reason on consecutive dragover', () => {
+    const host = mountHost('div', { 'data-drop-target-accepts': 'image/png' });
+    connectTrait(dropTarget, host);
+    const rejectedSpy = spyEvent(host, 'drop-rejected');
+    const dt = fakeDataTransfer({ types: ['text/plain'] });
+
+    // Three consecutive dragover events with the same rejection reason
+    // should emit ONE drop-rejected, not three.
+    fireDragEvent(host, 'dragover', dt);
+    fireDragEvent(host, 'dragover', dt);
+    fireDragEvent(host, 'dragover', dt);
+    expect(rejectedSpy.count).toBe(1);
+  });
+});

package/traits/droppable-collection.js

@@ -0,0 +1,89 @@
+import { defineTrait } from './define.js';
+
+/**
+ * `droppable-collection` — coordinator over a tree of `droppable` children.
+ *
+ * Authored for the Tasks UI playground (docs/projects/tasks-playground/spec/).
+ * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'input-interaction').
+ *
+ * Pairs with `droppable` (per-target) and `draggable-list-item` (motion-
+ * positioning, the lifter). Represents a board / multi-column container
+ * whose immediate descendant droppables form a coordinated set:
+ *
+ *   <task-board-ui [droppable-collection]>
+ *     <task-column-ui [droppable] data-droppable-id="todo">…</task-column-ui>
+ *     <task-column-ui [droppable] data-droppable-id="doing">…</task-column-ui>
+ *     <task-column-ui [droppable] data-droppable-id="done">…</task-column-ui>
+ *   </task-board-ui>
+ *
+ * Responsibilities (pure DOM coordination — no shared module state):
+ *  1. Listen for `dnd-drop` events bubbling up from any droppable child.
+ *  2. Re-emit a single `dnd-collection-drop` on the collection host that
+ *     view code can subscribe to once instead of N column listeners.
+ *  3. Reflect the dragging state to the collection host so the board can
+ *     dim non-target columns or render group affordances.
+ *
+ * Coordination is via DOM events only (light-DOM, bubbles: true) so it
+ * remains observable from authoring code, no shared registry needed.
+ */
+
+const ATTR_ACTIVE = 'data-droppable-collection-active';
+const ATTR_DRAGGING = 'data-droppable-collection-dragging';
+
+export const droppableCollection = defineTrait({
+  name: 'droppable-collection',
+  category: 'input-interaction',
+  description: 'Coordinates droppable children; re-emits drops as dnd-collection-drop',
+  attributes: [ATTR_ACTIVE, ATTR_DRAGGING],
+  events: ['dnd-collection-drop'],
+  config: [],
+  setup({ host }) {
+    host.setAttribute(ATTR_ACTIVE, '');
+
+    function onLift() {
+      host.setAttribute(ATTR_DRAGGING, '');
+    }
+    function onDragEnd() {
+      host.removeAttribute(ATTR_DRAGGING);
+    }
+
+    /** @param {Event} e */
+    function onChildDrop(e) {
+      // Only react to drops that landed inside a child droppable of THIS
+      // collection — don't double-handle drops from a nested collection.
+      const target = /** @type {Element} */ (e.target);
+      if (!target || !host.contains(target)) return;
+      const detail = /** @type {CustomEvent} */ (e).detail;
+      if (!detail) return;
+
+      host.removeAttribute(ATTR_DRAGGING);
+      host.dispatchEvent(new CustomEvent('dnd-collection-drop', {
+        bubbles: true,
+        composed: false,
+        detail: {
+          source_id: detail.source_id,
+          source_index: detail.source_index,
+          source_container_id: detail.source_container_id,
+          target_container_id: detail.target_container_id,
+          target_index: detail.target_index,
+        },
+      }));
+    }
+
+    host.addEventListener('dnd-lift', onLift);
+    host.addEventListener('dnd-drop-cancel', onDragEnd);
+    // Listen for the TARGET-side event from the [droppable] trait, not the
+    // source-side `dnd-drop` from the lifter — those would arrive too late
+    // (the lifter dispatches on document, only the host re-emit reaches us)
+    // AND match this collection's own outbound `dnd-collection-drop` shape.
+    host.addEventListener('dnd-drop-receive', onChildDrop);
+
+    return () => {
+      host.removeEventListener('dnd-lift', onLift);
+      host.removeEventListener('dnd-drop-cancel', onDragEnd);
+      host.removeEventListener('dnd-drop-receive', onChildDrop);
+      host.removeAttribute(ATTR_ACTIVE);
+      host.removeAttribute(ATTR_DRAGGING);
+    };
+  },
+});

package/traits/droppable-collection.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { droppableCollection } from './droppable-collection.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './test-helpers.js';
+
+// Minimal smoke coverage. The droppable-collection trait coordinates
+// child droppables of the docs/projects/tasks-playground/ DnD model;
+// the cases below verify only the trait's own surface (schema, attribute
+// lifecycle, child-drop re-emission) so the verify:traits gate stays
+// green. End-to-end multi-column behavior belongs in the playground tests.
+
+describe('droppable-collection', () => {
+  beforeEach(resetDOM);
+
+  it('schema shape is defined', () => {
+    expect(droppableCollection.schema.name).toBe('droppable-collection');
+    expect(droppableCollection.schema.category).toBe('input-interaction');
+    expect(droppableCollection.schema.description.length).toBeGreaterThanOrEqual(11);
+    expect(droppableCollection.schema.events).toContain('dnd-collection-drop');
+  });
+
+  it('connect sets data-droppable-collection-active', () => {
+    const host = mountHost('div');
+    connectTrait(droppableCollection, host);
+    expect(host.hasAttribute('data-droppable-collection-active')).toBe(true);
+  });
+
+  it('disconnect clears its attributes', () => {
+    const host = mountHost('div');
+    const inst = droppableCollection();
+    inst.connect(host);
+    host.setAttribute('data-droppable-collection-dragging', '');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-droppable-collection-active')).toBe(false);
+    expect(host.hasAttribute('data-droppable-collection-dragging')).toBe(false);
+  });
+
+  it('re-emits a child dnd-drop-receive as dnd-collection-drop on the host', () => {
+    // The collection listens for the TARGET-side `dnd-drop-receive` (emitted
+    // by the [droppable] trait on its host), NOT the source-side `dnd-drop`
+    // (emitted by the lifter on document). The two events are deliberately
+    // distinct names so that the target re-emit doesn't bubble back into
+    // the lifter's document-level listener and recurse.
+    const host = mountHost('div');
+    const child = document.createElement('div');
+    host.appendChild(child);
+    connectTrait(droppableCollection, host);
+
+    const spy = spyEvent(host, 'dnd-collection-drop');
+    child.dispatchEvent(new CustomEvent('dnd-drop-receive', {
+      bubbles: true,
+      composed: false,
+      detail: {
+        source_id: 't-1',
+        source_index: 0,
+        source_container_id: 'col-a',
+        target_container_id: 'col-b',
+        target_index: 2,
+      },
+    }));
+
+    expect(spy.count).toBe(1);
+    expect(spy.last).toMatchObject({
+      source_id: 't-1',
+      target_container_id: 'col-b',
+      target_index: 2,
+    });
+    spy.cleanup();
+  });
+
+  it('does NOT react to the source-side dnd-drop (would recurse)', () => {
+    // Regression guard: a source-side `dnd-drop` bubbling up from a child
+    // must NOT trigger `dnd-collection-drop`. Only the target-side
+    // `dnd-drop-receive` is the trigger.
+    const host = mountHost('div');
+    const child = document.createElement('div');
+    host.appendChild(child);
+    connectTrait(droppableCollection, host);
+
+    const spy = spyEvent(host, 'dnd-collection-drop');
+    child.dispatchEvent(new CustomEvent('dnd-drop', {
+      bubbles: true,
+      composed: false,
+      detail: { source_id: 't-1', target_container_id: 'col-b', target_index: 0 },
+    }));
+    expect(spy.count).toBe(0);
+    spy.cleanup();
+  });
+
+  it('reflects dragging state from dnd-lift / dnd-drop-cancel', () => {
+    const host = mountHost('div');
+    connectTrait(droppableCollection, host);
+
+    host.dispatchEvent(new CustomEvent('dnd-lift', { bubbles: true, detail: {} }));
+    expect(host.hasAttribute('data-droppable-collection-dragging')).toBe(true);
+
+    host.dispatchEvent(new CustomEvent('dnd-drop-cancel', { bubbles: true, detail: {} }));
+    expect(host.hasAttribute('data-droppable-collection-dragging')).toBe(false);
+  });
+});

package/traits/droppable.js

@@ -0,0 +1,125 @@
+import { defineTrait } from './define.js';
+
+/**
+ * `droppable` — marks an element as a drop target for `draggable-list-item`.
+ *
+ * Authored for the Tasks UI playground (docs/projects/tasks-playground/spec/).
+ * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'input-interaction').
+ *
+ * Pairs with `draggable-list-item` (motion-positioning) which lifts a list
+ * item and emits `dnd-lift` / `dnd-drop-target-change` / `dnd-drop` /
+ * `dnd-drop-cancel` ON THE DOCUMENT. This trait observes the drag in
+ * flight and emits target-side events ON THE HOST:
+ *
+ *   `dnd-drop-enter`    pointer entered this droppable
+ *   `dnd-drop-leave`    pointer left this droppable
+ *   `dnd-drop-receive`  the drop landed here (source-side `dnd-drop`
+ *                       on the document is the lifter's "release"
+ *                       signal; the target-side event MUST be named
+ *                       differently or it bubbles back to the
+ *                       document and re-triggers this same listener
+ *                       in an infinite loop)
+ *
+ * Coordination: pure DOM events (light-DOM, bubbles: true). No shared
+ * runtime state. The dragging item dispatches `dnd-drop-target-change`
+ * with the candidate target id; the targeted droppable receives a
+ * synthetic `dnd-drop-enter` from a tiny internal coordinator.
+ *
+ * For v1 the coordinator is a single shared module-level Map keyed by
+ * `data-droppable-id`. Future versions may promote to a registry trait.
+ */
+
+const ATTR_ID = 'data-droppable-id';
+const ATTR_OVER = 'data-droppable-over';
+const ATTR_VALID = 'data-droppable-valid';
+
+/** @type {Map<string, HTMLElement>} */
+const REGISTRY = new Map();
+/** @type {string | null} */
+let CURRENT_TARGET_ID = null;
+
+export const droppable = defineTrait({
+  name: 'droppable',
+  category: 'input-interaction',
+  description: 'Marks an element as a drop target for draggable-list-item; emits dnd-drop-enter / leave / receive',
+  attributes: [ATTR_ID, ATTR_OVER, ATTR_VALID],
+  events: ['dnd-drop-enter', 'dnd-drop-leave', 'dnd-drop-receive'],
+  config: [],
+  setup({ host }) {
+    // Assign a stable id for the registry. Authoring code may set it
+    // explicitly via the attribute; otherwise generate.
+    let id = host.getAttribute(ATTR_ID);
+    if (!id) {
+      id = `drop-${crypto.randomUUID().slice(0, 8)}`;
+      host.setAttribute(ATTR_ID, id);
+    }
+    REGISTRY.set(id, host);
+
+    // Listen for drag-in-flight signals on the document so this droppable
+    // knows when it should self-mark as the target.
+    function onTargetChange(/** @type {CustomEvent} */ e) {
+      const detail = e.detail;
+      const isMe = detail && detail.target_container_id === id;
+      if (isMe && CURRENT_TARGET_ID !== id) {
+        CURRENT_TARGET_ID = id;
+        host.setAttribute(ATTR_OVER, '');
+        host.dispatchEvent(new CustomEvent('dnd-drop-enter', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: detail.source_id, pointer_position: detail.pointer ?? { x: 0, y: 0 } },
+        }));
+      } else if (!isMe && CURRENT_TARGET_ID === id) {
+        CURRENT_TARGET_ID = null;
+        host.removeAttribute(ATTR_OVER);
+        host.dispatchEvent(new CustomEvent('dnd-drop-leave', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: detail?.source_id ?? null },
+        }));
+      }
+    }
+
+    function onDrop(/** @type {CustomEvent} */ e) {
+      const detail = e.detail;
+      if (!detail || detail.target_container_id !== id) return;
+      host.removeAttribute(ATTR_OVER);
+      CURRENT_TARGET_ID = null;
+      host.dispatchEvent(new CustomEvent('dnd-drop-receive', {
+        bubbles: true,
+        composed: false,
+        detail: {
+          source_id: detail.source_id,
+          source_index: detail.source_index,
+          source_container_id: detail.source_container_id,
+          target_container_id: id,
+          target_index: detail.target_index,
+        },
+      }));
+    }
+
+    function onDragEnd() {
+      // Whatever happened, reset the over state.
+      host.removeAttribute(ATTR_OVER);
+      if (CURRENT_TARGET_ID === id) CURRENT_TARGET_ID = null;
+    }
+
+    document.addEventListener('dnd-drop-target-change', onTargetChange);
+    document.addEventListener('dnd-drop', onDrop);
+    document.addEventListener('dnd-drop-cancel', onDragEnd);
+
+    return () => {
+      document.removeEventListener('dnd-drop-target-change', onTargetChange);
+      document.removeEventListener('dnd-drop', onDrop);
+      document.removeEventListener('dnd-drop-cancel', onDragEnd);
+      REGISTRY.delete(id);
+      host.removeAttribute(ATTR_ID);
+      host.removeAttribute(ATTR_OVER);
+      host.removeAttribute(ATTR_VALID);
+    };
+  },
+});
+
+/** Internal: lookup a droppable host by id. Used by `draggable-list-item`. */
+export function getDroppable(id) {
+  return REGISTRY.get(id) ?? null;
+}

package/traits/droppable.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { droppable } from './droppable.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
+
+// Minimal smoke coverage. The droppable trait is authored against the
+// docs/projects/tasks-playground/ DnD coordinator and assumes a sibling
+// `draggable-list-item` trait dispatches `dnd:drop-target-change` /
+// `dnd:drop` on the document. The cases below only exercise the trait's
+// own surface (schema, attribute lifecycle, registry entry, cleanup) so
+// the verify:traits gate stays green; the higher-fidelity DnD-flow tests
+// belong with the Tasks UI initiative that owns the coordinator.
+
+describe('droppable', () => {
+  beforeEach(resetDOM);
+
+  it('schema shape is defined', () => {
+    expect(droppable.schema.name).toBe('droppable');
+    expect(droppable.schema.category).toBe('input-interaction');
+    expect(droppable.schema.description.length).toBeGreaterThanOrEqual(11);
+    expect(droppable.schema.events).toContain('dnd-drop-enter');
+    // Source-side `dnd-drop` (on document, from the lifter) and target-side
+    // `dnd-drop-receive` (on host) MUST be distinct names — sharing the name
+    // recurses infinitely when the host event bubbles back to the document.
+    expect(droppable.schema.events).toContain('dnd-drop-receive');
+    expect(droppable.schema.events).not.toContain('dnd-drop');
+  });
+
+  it('connect assigns an id + sets the host attribute', () => {
+    const host = mountHost('div');
+    connectTrait(droppable, host);
+    expect(host.getAttribute('data-droppable-id')).toBeTruthy();
+  });
+
+  it('disconnect removes the over attribute if set', () => {
+    const host = mountHost('div');
+    const inst = droppable();
+    inst.connect(host);
+    host.setAttribute('data-droppable-over', '');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-droppable-over')).toBe(false);
+  });
+
+  it('reconnect with the same host does not throw', () => {
+    const host = mountHost('div');
+    const inst = droppable();
+    inst.connect(host);
+    inst.disconnect(host);
+    expect(() => {
+      const inst2 = droppable();
+      inst2.connect(host);
+      inst2.disconnect(host);
+    }).not.toThrow();
+  });
+});