@adia-ai/web-components 0.2.3 → 0.2.4

package/traits/draggable-list-item.js

@@ -0,0 +1,279 @@
+import { defineTrait } from './define.js';
+
+/**
+ * `draggable-list-item` — pointer-driven list-reorder lifter.
+ *
+ * Authored for the Tasks UI playground (docs/projects/tasks-playground/spec/).
+ * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'motion-positioning').
+ *
+ * Different mental model than the existing `draggable` trait:
+ *
+ *   `draggable` (free-positioning):  pointer drag → mutate style.translate;
+ *                                    emits `drag-end {x, y}`.
+ *   `draggable-list-item` (reorder): pointer drag → lift the item, signal
+ *                                    drop targets to render affordances,
+ *                                    then on release the parent rewrites
+ *                                    the child order. The source DOES NOT
+ *                                    physically move during the drag —
+ *                                    only `data-draggable-list-item-lifting`
+ *                                    is reflected, with optional `opacity:
+ *                                    0.4` styling left to component CSS
+ *                                    (Atlassian Pragmatic DnD convention,
+ *                                    SPEC §6.5).
+ *
+ * Coordinates with sibling traits via document-scoped CustomEvents:
+ *   dispatch  `dnd-lift`                — on pointerdown + threshold cross
+ *   dispatch  `dnd-drop-target-change` — when hovered droppable changes
+ *   dispatch  `dnd-drop`               — on pointerup over a valid target
+ *   dispatch  `dnd-drop-cancel`        — on pointerup off-target / Esc
+ *
+ * `[droppable]` listens for `dnd-drop-target-change` and self-marks.
+ * `[droppable-collection]` listens for `dnd-drop` from any descendant
+ * droppable and re-emits `dnd-collection-drop`.
+ *
+ * Hit-testing is `document.elementFromPoint()` + closest `[data-droppable-id]`
+ * walk (no shared registry — DOM is the source of truth).
+ *
+ * Keyboard alternative is delivered by the sibling `keyboard-reorderable`
+ * trait (per WCAG 2.5.7) — both traits consume the shared `announcer-stage.js`
+ * aria-live regions so screen-reader narration is single-stream.
+ */
+
+import { announce } from './announcer-stage.js';
+
+// Drop-target-change announcements are debounced at 200 ms (per
+// a11y-live-region-drag-announcements.md research note); other phases
+// (lift / drop / cancel) announce immediately and supersede the pending
+// debounced message. The shared announcer-stage handles the actual
+// aria-live write; we just gate the call here.
+const DEBOUNCE_MS = 200;
+let debounceHandle = null;
+function announceDebounced(message) {
+  if (debounceHandle != null) clearTimeout(debounceHandle);
+  debounceHandle = setTimeout(() => {
+    debounceHandle = null;
+    announce(message, 'polite');
+  }, DEBOUNCE_MS);
+}
+function announceImmediate(message) {
+  if (debounceHandle != null) {
+    clearTimeout(debounceHandle);
+    debounceHandle = null;
+  }
+  announce(message, 'polite');
+}
+
+const ATTR_LIFTING = 'data-draggable-list-item-lifting';
+const ATTR_SOURCE_ID = 'data-draggable-list-item-id';
+const DRAG_THRESHOLD_PX = 4;
+
+/** @type {{ container: Element; index: number } | null} */
+function readSourceContext(host) {
+  const container = host.parentElement;
+  if (!container) return null;
+  const siblings = Array.from(container.children).filter((c) => c.matches?.('[data-draggable-list-item-id]'));
+  const index = siblings.indexOf(host);
+  return { container, index };
+}
+
+function readContainerId(el) {
+  // Walk up looking for the nearest `[data-droppable-id]`.
+  /** @type {Element | null} */
+  let cur = el;
+  while (cur && cur !== document.body) {
+    if (cur.hasAttribute?.('data-droppable-id')) return cur.getAttribute('data-droppable-id');
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+function dropTargetFromPoint(x, y) {
+  const el = document.elementFromPoint(x, y);
+  if (!el) return null;
+  /** @type {Element | null} */
+  let cur = el;
+  while (cur && cur !== document.body) {
+    if (cur.hasAttribute?.('data-droppable-id')) return cur;
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+function indexWithinTarget(target, x, y) {
+  // Compute the insertion index by counting how many sibling list-items
+  // start above the pointer's y. Cheap and good-enough for v1; a future
+  // pass can compute by midpoint of each child rect.
+  const items = Array.from(target.querySelectorAll('[data-draggable-list-item-id]'));
+  for (let i = 0; i < items.length; i++) {
+    const r = items[i].getBoundingClientRect();
+    if (y < r.top + r.height / 2) return i;
+  }
+  return items.length;
+}
+
+export const draggableListItem = defineTrait({
+  name: 'draggable-list-item',
+  category: 'motion-positioning',
+  description: 'Pointer drag for list reordering; emits dnd-lift/drop-target-change/drop/drop-cancel',
+  attributes: [ATTR_LIFTING, ATTR_SOURCE_ID],
+  events: ['dnd-lift', 'dnd-drop-target-change', 'dnd-drop', 'dnd-drop-cancel'],
+  config: [],
+  setup({ host }) {
+    let id = host.getAttribute(ATTR_SOURCE_ID);
+    if (!id) {
+      id = `dlitem-${crypto.randomUUID().slice(0, 8)}`;
+      host.setAttribute(ATTR_SOURCE_ID, id);
+    }
+
+    /** @type {{ x: number; y: number; pointerId: number; sourceCtx: ReturnType<typeof readSourceContext>; sourceContainerId: string | null } | null} */
+    let down = null;
+    let lifted = false;
+    /** @type {string | null} */
+    let lastTargetId = null;
+    let lastTargetIndex = -1;
+
+    function isDisabled() {
+      return host.hasAttribute('disabled') || host.getAttribute('aria-disabled') === 'true';
+    }
+
+    function reset() {
+      if (down && host.hasPointerCapture?.(down.pointerId)) {
+        try { host.releasePointerCapture(down.pointerId); } catch { /* ignore */ }
+      }
+      down = null;
+      lifted = false;
+      lastTargetId = null;
+      lastTargetIndex = -1;
+      host.removeAttribute(ATTR_LIFTING);
+      document.removeEventListener('keydown', onKeyDown, true);
+    }
+
+    function onPointerDown(e) {
+      if (isDisabled()) return;
+      if (e.button !== 0 && e.pointerType === 'mouse') return;
+
+      const sourceCtx = readSourceContext(host);
+      if (!sourceCtx) return;
+
+      down = {
+        x: e.clientX,
+        y: e.clientY,
+        pointerId: e.pointerId,
+        sourceCtx,
+        sourceContainerId: readContainerId(sourceCtx.container),
+      };
+      // Hold the pointer so we keep getting move/up even outside the host.
+      try { host.setPointerCapture(e.pointerId); } catch { /* ignore */ }
+      document.addEventListener('keydown', onKeyDown, true);
+    }
+
+    function onPointerMove(e) {
+      if (!down) return;
+      const dx = e.clientX - down.x;
+      const dy = e.clientY - down.y;
+
+      if (!lifted) {
+        if (Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+        lifted = true;
+        host.setAttribute(ATTR_LIFTING, '');
+        host.dispatchEvent(new CustomEvent('dnd-lift', {
+          bubbles: true,
+          composed: false,
+          detail: {
+            source_id: id,
+            source_index: down.sourceCtx.index,
+            source_container_id: down.sourceContainerId,
+          },
+        }));
+        announceImmediate(`Picked up item. Press arrow keys to navigate. Press Space to drop. Press Esc to cancel.`);
+      }
+
+      const targetEl = dropTargetFromPoint(e.clientX, e.clientY);
+      const targetId = targetEl?.getAttribute('data-droppable-id') ?? null;
+      const targetIdx = targetEl ? indexWithinTarget(targetEl, e.clientX, e.clientY) : -1;
+
+      if (targetId !== lastTargetId || targetIdx !== lastTargetIndex) {
+        lastTargetId = targetId;
+        lastTargetIndex = targetIdx;
+        document.dispatchEvent(new CustomEvent('dnd-drop-target-change', {
+          bubbles: true,
+          composed: false,
+          detail: {
+            source_id: id,
+            target_container_id: targetId,
+            target_index: targetIdx,
+            pointer: { x: e.clientX, y: e.clientY },
+          },
+        }));
+        if (targetId) announceDebounced(`Drop position ${targetIdx + 1} in ${targetId}.`);
+      }
+    }
+
+    function onPointerUp(e) {
+      if (!down) return;
+      if (!lifted) { reset(); return; }
+
+      const targetEl = dropTargetFromPoint(e.clientX, e.clientY);
+      const targetId = targetEl?.getAttribute('data-droppable-id') ?? null;
+
+      if (!targetId) {
+        document.dispatchEvent(new CustomEvent('dnd-drop-cancel', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: id, reason: 'off-target' },
+        }));
+        announceImmediate(`Drag cancelled. Item returned to its original position.`);
+      } else {
+        const targetIdx = indexWithinTarget(targetEl, e.clientX, e.clientY);
+        document.dispatchEvent(new CustomEvent('dnd-drop', {
+          bubbles: true,
+          composed: false,
+          detail: {
+            source_id: id,
+            source_index: down.sourceCtx.index,
+            source_container_id: down.sourceContainerId,
+            target_container_id: targetId,
+            target_index: targetIdx,
+          },
+        }));
+        announceImmediate(`Dropped item in ${targetId} at position ${targetIdx + 1}.`);
+      }
+      reset();
+    }
+
+    function onKeyDown(e) {
+      if (e.key === 'Escape' && lifted) {
+        document.dispatchEvent(new CustomEvent('dnd-drop-cancel', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: id, reason: 'esc' },
+        }));
+        announceImmediate(`Drag cancelled. Item returned to its original position.`);
+        reset();
+      }
+    }
+
+    host.addEventListener('pointerdown', onPointerDown);
+    host.addEventListener('pointermove', onPointerMove);
+    host.addEventListener('pointerup', onPointerUp);
+    host.addEventListener('pointercancel', () => {
+      if (lifted) {
+        document.dispatchEvent(new CustomEvent('dnd-drop-cancel', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: id, reason: 'pointer-cancel' },
+        }));
+      }
+      reset();
+    });
+
+    return () => {
+      host.removeEventListener('pointerdown', onPointerDown);
+      host.removeEventListener('pointermove', onPointerMove);
+      host.removeEventListener('pointerup', onPointerUp);
+      document.removeEventListener('keydown', onKeyDown, true);
+      reset();
+      host.removeAttribute(ATTR_SOURCE_ID);
+    };
+  },
+});

package/traits/draggable-list-item.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { draggableListItem } from './draggable-list-item.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
+
+// Minimal smoke coverage. The draggable-list-item trait is the pointer
+// driver for the docs/projects/tasks-playground/ DnD model. The cases
+// below exercise only its own surface (schema, attribute lifecycle,
+// id assignment, idempotent disconnect). Full pointer-flow tests need a
+// laid-out DOM with sibling droppables and live elementFromPoint —
+// those belong with the playground integration suite, not the trait
+// gate.
+
+describe('draggable-list-item', () => {
+  beforeEach(resetDOM);
+
+  it('schema shape is defined', () => {
+    expect(draggableListItem.schema.name).toBe('draggable-list-item');
+    expect(draggableListItem.schema.category).toBe('motion-positioning');
+    expect(draggableListItem.schema.description.length).toBeGreaterThanOrEqual(11);
+    expect(draggableListItem.schema.events).toContain('dnd-lift');
+    expect(draggableListItem.schema.events).toContain('dnd-drop');
+  });
+
+  it('connect assigns an id + sets the host attribute', () => {
+    const host = mountHost('div');
+    connectTrait(draggableListItem, host);
+    expect(host.getAttribute('data-draggable-list-item-id')).toBeTruthy();
+  });
+
+  it('disconnect clears its attributes', () => {
+    const host = mountHost('div');
+    const inst = draggableListItem();
+    inst.connect(host);
+    host.setAttribute('data-draggable-list-item-lifting', '');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-draggable-list-item-lifting')).toBe(false);
+    expect(host.hasAttribute('data-draggable-list-item-id')).toBe(false);
+  });
+
+  it('reconnect with the same host does not throw', () => {
+    const host = mountHost('div');
+    const inst = draggableListItem();
+    inst.connect(host);
+    inst.disconnect(host);
+    expect(() => {
+      const inst2 = draggableListItem();
+      inst2.connect(host);
+      inst2.disconnect(host);
+    }).not.toThrow();
+  });
+});

package/traits/draggable.js

@@ -24,11 +24,21 @@ export const draggable = defineTrait({
       startX = e.clientX;
       startY = e.clientY;
 
-      // Parse current translate values
+      // Parse current translate values. The trait writes to `style.translate`
+      // (independent of `transform` in the modern CSS model). Read translate
+      // first so subsequent drags pick up the current position, then fall back
+      // to the transform matrix for callers that nudged via `transform`.
       const style = getComputedStyle(host);
-      const matrix = new DOMMatrixReadOnly(style.transform);
-      originX = matrix.m41;
-      originY = matrix.m42;
+      const t = style.translate;
+      if (t && t !== 'none') {
+        const parts = t.split(/\s+/).map(parseFloat);
+        originX = parts[0] || 0;
+        originY = parts[1] || 0;
+      } else {
+        const matrix = new DOMMatrixReadOnly(style.transform);
+        originX = matrix.m41;
+        originY = matrix.m42;
+      }
 
       host.setPointerCapture(e.pointerId);
       host.setAttribute('data-draggable-dragging', '');

package/traits/draggable.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { draggable } from './draggable.js';
-import { mountHost, connectTrait, spyEvent, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './test-helpers.js';
 
 function pointer(host, type, x, y) {
   const ev = new PointerEvent(type, { clientX: x, clientY: y, pointerId: 1, bubbles: true });

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