@adia-ai/web-components 0.2.3 → 0.2.5

package/traits/drop-target.js

@@ -0,0 +1,223 @@
+import { defineTrait } from './define.js';
+
+/**
+ * Declarative drop zone — wires the host into the HTML5 drag-and-drop
+ * pipeline so a sibling `draggable` / `drag-ghost` source (or a native
+ * file drag from the OS) can land on it.
+ *
+ * Lifecycle:
+ *   dragenter → set data-drop-target-over, dispatch `drop-enter`
+ *   dragover  → conditionally call preventDefault() per the
+ *               `data-drop-target-accepts` filter (calling preventDefault
+ *               is the platform's own "this target accepts" signal —
+ *               without it the browser shows a reject cursor + the
+ *               subsequent `drop` event never fires)
+ *   dragleave → clear data-drop-target-over, dispatch `drop-leave`
+ *   drop      → dispatch `drop-receive` with { dataTransfer, draggable };
+ *               consumer is responsible for processing the payload
+ *
+ * Accept filter (`data-drop-target-accepts`):
+ *   ""        → accepts anything
+ *   "files"   → only file drops (e.dataTransfer.types.includes('Files'))
+ *   "<csv>"   → only the listed MIME types (image/png, application/json…)
+ *
+ * When a payload is rejected the trait does NOT call preventDefault, so
+ * the cursor shows reject. It also sets `data-drop-target-rejected`
+ * with a short reason ("type" | "files-only") so consumers can style
+ * the rejection feedback (red flash, alert toast, etc.) and dispatches
+ * a `drop-rejected` event so reactive code can respond.
+ */
+
+const FILES_TYPE = 'Files';
+
+function parseAcceptList(raw) {
+  if (raw == null) return null; // attribute absent → accept anything
+  const trimmed = String(raw).trim();
+  if (trimmed === '') return null; // empty string → accept anything
+
+  // Special token: only file drops.
+  if (trimmed.toLowerCase() === 'files') return { mode: 'files' };
+
+  // Otherwise: csv MIME list. Split, trim, lowercase for case-insensitive
+  // compare against dataTransfer.types (which are already lowercase per spec).
+  const list = trimmed
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+
+  if (list.length === 0) return null;
+  return { mode: 'mime', list };
+}
+
+function evaluateAccept(dataTransfer, parsed) {
+  // null / no constraint → accept anything.
+  if (!parsed) return { ok: true };
+  if (!dataTransfer) return { ok: false, reason: 'no-data' };
+
+  // dataTransfer.types is a DOMStringList (also indexable like an array).
+  // Coerce to a real array for set-membership checks.
+  const types = Array.from(dataTransfer.types || []);
+
+  if (parsed.mode === 'files') {
+    return types.includes(FILES_TYPE)
+      ? { ok: true }
+      : { ok: false, reason: 'files-only' };
+  }
+
+  if (parsed.mode === 'mime') {
+    // dataTransfer carries 'Files' for OS-level file drags AND the file's
+    // MIME type once the file objects are inspected. We accept either:
+    // a literal type match, or a 'Files' drag whose first item matches.
+    const lowerTypes = types.map((t) => t.toLowerCase());
+
+    // Direct MIME type match (e.g., 'text/plain' from a text drag).
+    if (parsed.list.some((m) => lowerTypes.includes(m))) {
+      return { ok: true };
+    }
+
+    // OS file drag: inspect the items list for file-kind entries.
+    if (lowerTypes.includes(FILES_TYPE.toLowerCase()) && dataTransfer.items) {
+      const items = Array.from(dataTransfer.items);
+      const fileItem = items.find((it) => it.kind === 'file');
+      if (fileItem && parsed.list.includes(fileItem.type.toLowerCase())) {
+        return { ok: true };
+      }
+    }
+
+    return { ok: false, reason: 'type' };
+  }
+
+  return { ok: true };
+}
+
+export const dropTarget = defineTrait({
+  name: 'drop-target',
+  category: 'motion-positioning',
+  description: 'Declarative drop zone: hit-testing, accept-reject, drag-over feedback',
+  attributes: ['data-drop-target-active', 'data-drop-target-over', 'data-drop-target-rejected'],
+  events: ['drop-enter', 'drop-leave', 'drop-receive', 'drop-rejected'],
+  config: ['data-drop-target-accepts'],
+  setup({ host }) {
+    // dragenter/dragleave fire for descendants too — track depth so we
+    // only flip data-drop-target-over off when the pointer truly leaves
+    // the host's subtree, not when it crosses into a child element.
+    let enterDepth = 0;
+
+    function isDisabled() {
+      return host.hasAttribute('disabled');
+    }
+
+    function readAccepts() {
+      return parseAcceptList(host.getAttribute('data-drop-target-accepts'));
+    }
+
+    function clearOver() {
+      enterDepth = 0;
+      host.removeAttribute('data-drop-target-over');
+      host.removeAttribute('data-drop-target-rejected');
+    }
+
+    function onDragEnter(e) {
+      if (isDisabled()) return;
+      enterDepth++;
+      if (enterDepth === 1) {
+        host.setAttribute('data-drop-target-over', '');
+        host.dispatchEvent(new CustomEvent('drop-enter', {
+          bubbles: true,
+          detail: { dataTransfer: e.dataTransfer },
+        }));
+      }
+    }
+
+    function onDragOver(e) {
+      if (isDisabled()) return;
+
+      const parsed = readAccepts();
+      const verdict = evaluateAccept(e.dataTransfer, parsed);
+
+      if (verdict.ok) {
+        // preventDefault on dragover is the platform contract: "this target
+        // accepts this payload". Without it, the drop event never fires
+        // and the cursor shows the reject icon.
+        e.preventDefault();
+        if (host.hasAttribute('data-drop-target-rejected')) {
+          host.removeAttribute('data-drop-target-rejected');
+        }
+      } else {
+        // No preventDefault — cursor shows reject. Surface the reason so
+        // CSS can theme the rejection (red flash, etc.).
+        if (host.getAttribute('data-drop-target-rejected') !== verdict.reason) {
+          host.setAttribute('data-drop-target-rejected', verdict.reason);
+          host.dispatchEvent(new CustomEvent('drop-rejected', {
+            bubbles: true,
+            detail: { reason: verdict.reason, dataTransfer: e.dataTransfer },
+          }));
+        }
+      }
+    }
+
+    function onDragLeave() {
+      if (isDisabled()) return;
+      enterDepth = Math.max(0, enterDepth - 1);
+      if (enterDepth === 0) {
+        host.removeAttribute('data-drop-target-over');
+        host.removeAttribute('data-drop-target-rejected');
+        host.dispatchEvent(new CustomEvent('drop-leave', { bubbles: true }));
+      }
+    }
+
+    function onDrop(e) {
+      if (isDisabled()) return;
+
+      const parsed = readAccepts();
+      const verdict = evaluateAccept(e.dataTransfer, parsed);
+
+      if (!verdict.ok) {
+        // Defensive — drop should not have fired (no preventDefault on
+        // dragover would have suppressed it), but a programmatic dispatch
+        // can still land here. Treat as rejection.
+        host.setAttribute('data-drop-target-rejected', verdict.reason);
+        host.dispatchEvent(new CustomEvent('drop-rejected', {
+          bubbles: true,
+          detail: { reason: verdict.reason, dataTransfer: e.dataTransfer },
+        }));
+        clearOver();
+        return;
+      }
+
+      // preventDefault on the drop itself stops the browser's default
+      // behavior (e.g., navigating to a dropped file's URL).
+      e.preventDefault();
+
+      // The 'draggable' detail field is best-effort — only populated when
+      // the drag started from another element in the same document, since
+      // OS file drags carry no source element.
+      const draggable = e.dataTransfer?.types?.includes?.('text/x-source-id')
+        ? document.getElementById(e.dataTransfer.getData('text/x-source-id'))
+        : null;
+
+      host.dispatchEvent(new CustomEvent('drop-receive', {
+        bubbles: true,
+        detail: { dataTransfer: e.dataTransfer, draggable },
+      }));
+
+      clearOver();
+    }
+
+    host.setAttribute('data-drop-target-active', '');
+    host.addEventListener('dragenter', onDragEnter);
+    host.addEventListener('dragover', onDragOver);
+    host.addEventListener('dragleave', onDragLeave);
+    host.addEventListener('drop', onDrop);
+
+    return () => {
+      host.removeEventListener('dragenter', onDragEnter);
+      host.removeEventListener('dragover', onDragOver);
+      host.removeEventListener('dragleave', onDragLeave);
+      host.removeEventListener('drop', onDrop);
+      host.removeAttribute('data-drop-target-active');
+      host.removeAttribute('data-drop-target-over');
+      host.removeAttribute('data-drop-target-rejected');
+    };
+  },
+});

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);
+  });
+});