@adia-ai/web-components 0.2.4 → 0.3.0

package/README.md

@@ -64,12 +64,12 @@ web-components/
 │                     pages. Full contract in docs/specs/traits.md.
 │
 ├── a2ui/           — deprecation shim for one release
-│   └── index.js            Re-exports @adia-ai/a2ui-utils with a
+│   └── index.js            Re-exports @adia-ai/a2ui-runtime with a
 │                           one-time console.warn. Removed in 0.1.0.
 │                           All actual A2UI runtime code (renderer,
 │                           registry, streams, surface manifest,
 │                           wiring, dockables, controllers) lives in
-│                           `@adia-ai/a2ui-utils` at packages/a2ui/utils/.
+│                           `@adia-ai/a2ui-runtime` at packages/a2ui/runtime/.
 │
 └── styles/         — Global tokens and CSS layering
     ├── tokens.css              all --a-* design tokens
@@ -139,7 +139,7 @@ examples.
 ## A2UI runtime
 
 ```javascript
-import { A2UIRenderer } from '@adia-ai/a2ui-utils';
+import { A2UIRenderer } from '@adia-ai/a2ui-runtime';
 // (The old `@adia-ai/web-components/a2ui` subpath still resolves in 0.0.4
 // via a deprecation shim that prints a console.warn; removed in 0.1.0.)
 
@@ -198,7 +198,7 @@ the `streams` registry export from `core/data-stream.js`.
 
 Implementation: `core/data-stream.js` (~360 lines). Full
 attribute table + live demos:
-[`/site/components/chart#data-stream`](../../site/pages/components/chart/index.html).
+[`/site/components/chart#data-stream`](./components/chart/chart.html).
 
 ## Build
 

package/components/fields/fields.a2ui.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Fields.json",
+  "title": "Fields",
+  "description": "Container for a group of <field-ui> children, laid out on a shared 6-column grid. Each <field-ui> spans the full row by default; opt into a narrower span via [rows=\"1..6\"]. Setting [inline] on the host propagates the inline mode to every direct <field-ui> child so a whole sub-form can switch label-position without per-field edits. The grid alignment lets siblings on the same row line up cleanly — consistent label columns + consistent control columns — without the wrap-flex jitter of <row-ui wrap>.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "columns": {
+      "description": "Number of grid columns the row uses. Defaults to 6 — common multiples (1/2/3/6) divide cleanly. <field-ui rows=\"N\"> spans `N` of these columns. Override per-instance for tighter 4-column or wider 12-column compositions.",
+      "type": "number",
+      "default": 6
+    },
+    "component": {
+      "const": "Fields"
+    },
+    "inline": {
+      "description": "Propagate the inline layout mode to every direct <field-ui> child. Equivalent to authoring `inline` on each child but drives the whole group from one place. Toggle is reactive — flipping the attribute on the host re-syncs all children.",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "description": "Don't wrap <field-ui> children in <row-ui wrap> when grid alignment is desired. row-ui is flex-wrap, which lets each field size to its content — labels and controls won't share a column with siblings.",
+        "severity": "high"
+      },
+      {
+        "description": "Don't set `inline` on individual <field-ui> children when the whole group should switch — set it on the parent <fields-ui> and let the propagation handle every child.",
+        "severity": "medium"
+      }
+    ],
+    "category": "form",
+    "events": {},
+    "examples": [
+      {
+        "description": "A 3-up stacked field row — Status / Priority / Group — each taking 2 of 6 columns. Equivalent to a Bootstrap \"col-md-4\" pattern (12-col grid, span 4) but with chat-ui's 6-col default.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Fields\",\n    \"children\": [\"status\", \"priority\", \"group\"]\n  },\n  { \"id\": \"status\",   \"component\": \"Field\", \"label\": \"Status\",   \"rows\": 2, \"children\": [\"status-sel\"] },\n  { \"id\": \"priority\", \"component\": \"Field\", \"label\": \"Priority\", \"rows\": 2, \"children\": [\"priority-sel\"] },\n  { \"id\": \"group\",    \"component\": \"Field\", \"label\": \"Group\",    \"rows\": 2, \"children\": [\"group-sel\"] },\n  { \"id\": \"status-sel\",   \"component\": \"Select\", \"value\": \"todo\" },\n  { \"id\": \"priority-sel\", \"component\": \"Select\", \"value\": \"0\" },\n  { \"id\": \"group-sel\",    \"component\": \"Select\", \"value\": \"\" }\n]",
+        "name": "three-up-stacked"
+      },
+      {
+        "description": "An inline form — every field renders label-beside-control. Single [inline] on the host drives all children.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Fields\",\n    \"inline\": true,\n    \"children\": [\"q\", \"kind\"]\n  },\n  { \"id\": \"q\",    \"component\": \"Field\", \"label\": \"Search\", \"children\": [\"q-input\"] },\n  { \"id\": \"kind\", \"component\": \"Field\", \"label\": \"Kind\",   \"children\": [\"kind-sel\"] },\n  { \"id\": \"q-input\", \"component\": \"Input\", \"type\": \"search\" },\n  { \"id\": \"kind-sel\", \"component\": \"Select\", \"value\": \"all\" }\n]",
+        "name": "inline-search-form"
+      }
+    ],
+    "keywords": [
+      "fields",
+      "form",
+      "grid",
+      "layout",
+      "group"
+    ],
+    "name": "UIFields",
+    "related": [
+      "field",
+      "input",
+      "select",
+      "textarea"
+    ],
+    "slots": {
+      "default": {
+        "description": "<field-ui> children. Non-field children (separators, headings) are placed in the grid too — span them by setting `style=\"grid-column: 1 / -1\"` for full-width content. Nested <fields-ui> works (an outer 6-col grid hosting inner 3-col grids inside a single cell)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "form": [
+        "fields",
+        "group",
+        "layout"
+      ]
+    },
+    "tag": "fields-ui",
+    "tokens": {
+      "--fields-column-gap": {
+        "description": "Override the column-gap independently of row-gap."
+      },
+      "--fields-gap": {
+        "description": "Gap between adjacent fields (row + column)."
+      },
+      "--fields-row-gap": {
+        "description": "Override the row-gap independently of column-gap."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/fields/fields.css

@@ -0,0 +1,60 @@
+@scope (fields-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --fields-gap:        var(--a-space-3);
+    --fields-row-gap:    var(--fields-gap);
+    --fields-column-gap: var(--fields-gap);
+  }
+
+  /* ── Base — 6-column grid ──
+     Children are placed into the grid by their [rows="N"] attr (pure
+     CSS, no JS). Default span (no attr) is the full row. The columns
+     count is configurable via [columns="N"] on the host — defaults
+     handle [columns] absent.
+
+     `minmax(0, 1fr)` is required so children with overflow content
+     (long labels, long select values) don't blow out the grid. */
+  :scope {
+    box-sizing: border-box;
+    display: grid;
+    grid-template-columns: repeat(var(--fields-columns, 6), minmax(0, 1fr));
+    column-gap: var(--fields-column-gap);
+    row-gap: var(--fields-row-gap);
+    align-items: start;
+  }
+
+  /* Per-instance column count from [columns="N"] — unrolled for the
+     common values 1..12. Beyond 12 the host can set
+     `--fields-columns: N` inline. */
+  :scope[columns="1"]  { --fields-columns: 1; }
+  :scope[columns="2"]  { --fields-columns: 2; }
+  :scope[columns="3"]  { --fields-columns: 3; }
+  :scope[columns="4"]  { --fields-columns: 4; }
+  :scope[columns="5"]  { --fields-columns: 5; }
+  :scope[columns="6"]  { --fields-columns: 6; }
+  :scope[columns="8"]  { --fields-columns: 8; }
+  :scope[columns="12"] { --fields-columns: 12; }
+
+  /* ── field-ui spans ──
+     `rows="N"` reads as "this field takes N grid cells". Without the
+     attr, the field spans the full row (`grid-column: 1 / -1`) so
+     authors can mix narrow + full-width fields without per-row
+     wrappers. The attribute is exposed up to 12 to cover larger
+     [columns] grids; 13+ also collapses to full-row. */
+  :scope > field-ui {
+    grid-column: 1 / -1;
+    min-width: 0; /* allow children to shrink within the cell */
+  }
+  :scope > field-ui[rows="1"]  { grid-column: span 1;  }
+  :scope > field-ui[rows="2"]  { grid-column: span 2;  }
+  :scope > field-ui[rows="3"]  { grid-column: span 3;  }
+  :scope > field-ui[rows="4"]  { grid-column: span 4;  }
+  :scope > field-ui[rows="5"]  { grid-column: span 5;  }
+  :scope > field-ui[rows="6"]  { grid-column: span 6;  }
+  :scope > field-ui[rows="7"]  { grid-column: span 7;  }
+  :scope > field-ui[rows="8"]  { grid-column: span 8;  }
+  :scope > field-ui[rows="9"]  { grid-column: span 9;  }
+  :scope > field-ui[rows="10"] { grid-column: span 10; }
+  :scope > field-ui[rows="11"] { grid-column: span 11; }
+  :scope > field-ui[rows="12"] { grid-column: span 12; }
+}

package/components/fields/fields.js

@@ -0,0 +1,96 @@
+/**
+ * fields-ui — Container for a group of <field-ui> children laid out
+ * on a shared grid.
+ *
+ *   <fields-ui>                                      <!-- 6-col grid -->
+ *     <field-ui label="Title">…</field-ui>           <!-- rows=6 (full row) -->
+ *     <field-ui label="Status"   rows="2">…</field-ui>
+ *     <field-ui label="Priority" rows="2">…</field-ui>
+ *     <field-ui label="Group"    rows="2">…</field-ui>
+ *   </fields-ui>
+ *
+ *   <fields-ui inline>            <!-- propagate inline to every child -->
+ *     <field-ui label="Search">…</field-ui>
+ *     <field-ui label="Kind">…</field-ui>
+ *   </fields-ui>
+ *
+ * The shared grid keeps siblings on the same row aligned. The [inline]
+ * attribute is mirrored onto every direct <field-ui> child so a whole
+ * sub-form switches layout mode from one host attribute. A small
+ * MutationObserver re-syncs when children are added/removed.
+ *
+ * Per-field column span is driven by the child's [rows="1..6"]
+ * attribute — pure CSS via attribute selectors in fields.css. The
+ * default span (no attr) is the full row.
+ */
+import { UIElement } from '../../core/element.js';
+
+class UIFields extends UIElement {
+  static properties = {
+    inline:  { type: Boolean, default: false, reflect: true },
+    columns: { type: Number,  default: 6,     reflect: true },
+  };
+
+  static template = () => null;
+
+  /** @type {MutationObserver | null} */
+  #mo = null;
+
+  connected() {
+    this.#syncInline();
+    this.#mo = new MutationObserver((records) => {
+      // Only re-sync on childList changes that involve direct <field-ui>
+      // children — attribute mutations on grandchildren aren't ours to
+      // care about.
+      for (const r of records) {
+        if (r.type !== 'childList') continue;
+        if (this.#hasFieldChild(r.addedNodes) || this.#hasFieldChild(r.removedNodes)) {
+          this.#syncInline();
+          return;
+        }
+      }
+    });
+    this.#mo.observe(this, { childList: true });
+  }
+
+  disconnected() {
+    this.#mo?.disconnect();
+    this.#mo = null;
+  }
+
+  render() {
+    // UIElement calls render() on attribute → property reflection. The
+    // inline attr's effect is propagation-to-children, not host markup.
+    this.#syncInline();
+  }
+
+  // ── Private ────────────────────────────────────────────────────
+
+  #syncInline() {
+    const inline = this.hasAttribute('inline');
+    for (const child of this.children) {
+      if (child.localName !== 'field-ui') continue;
+      if (inline) {
+        if (!child.hasAttribute('inline')) child.setAttribute('inline', '');
+      } else {
+        // Only remove if WE set it. We can't tell, so we always remove —
+        // that's the documented contract: <fields-ui inline> is the
+        // single source of truth for child inline-mode within the group.
+        if (child.hasAttribute('inline')) child.removeAttribute('inline');
+      }
+    }
+  }
+
+  /** @param {NodeList} nodes */
+  #hasFieldChild(nodes) {
+    for (const n of nodes) {
+      if (n.nodeType === 1 && /** @type {Element} */ (n).localName === 'field-ui') {
+        return true;
+      }
+    }
+    return false;
+  }
+}
+
+customElements.define('fields-ui', UIFields);
+export { UIFields };

package/components/fields/fields.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './fields.js';
+import '../field/field.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('fields-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('registers the custom element', () => {
+    expect(customElements.get('fields-ui')).toBeDefined();
+  });
+
+  it('hosts <field-ui> children without altering them by default', () => {
+    const f = mount(`
+      <fields-ui>
+        <field-ui label="A"><input id="a" /></field-ui>
+        <field-ui label="B"><input id="b" /></field-ui>
+      </fields-ui>
+    `);
+    const fields = f.querySelectorAll('field-ui');
+    expect(fields).toHaveLength(2);
+    // Default — neither child has [inline] propagated.
+    expect(fields[0].hasAttribute('inline')).toBe(false);
+    expect(fields[1].hasAttribute('inline')).toBe(false);
+  });
+
+  it('propagates [inline] to every direct <field-ui> child on connect', async () => {
+    const f = mount(`
+      <fields-ui inline>
+        <field-ui label="A"><input id="a" /></field-ui>
+        <field-ui label="B"><input id="b" /></field-ui>
+      </fields-ui>
+    `);
+    await tick();
+    const fields = f.querySelectorAll('field-ui');
+    for (const child of fields) {
+      expect(child.hasAttribute('inline')).toBe(true);
+    }
+  });
+
+  it('removes inline from children when [inline] is removed from host', async () => {
+    const f = mount(`
+      <fields-ui inline>
+        <field-ui label="A"><input id="a" /></field-ui>
+        <field-ui label="B"><input id="b" /></field-ui>
+      </fields-ui>
+    `);
+    await tick();
+    f.removeAttribute('inline');
+    await tick();
+    const fields = f.querySelectorAll('field-ui');
+    for (const child of fields) {
+      expect(child.hasAttribute('inline')).toBe(false);
+    }
+  });
+
+  it('re-syncs inline when a new <field-ui> is appended later', async () => {
+    const f = mount(`<fields-ui inline></fields-ui>`);
+    await tick();
+    const child = document.createElement('field-ui');
+    child.setAttribute('label', 'Late');
+    f.appendChild(child);
+    // MutationObserver fires async — give it a microtask.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(child.hasAttribute('inline')).toBe(true);
+  });
+
+  it('does not propagate [inline] to non-field children', async () => {
+    const f = mount(`
+      <fields-ui inline>
+        <field-ui label="A"><input id="a" /></field-ui>
+        <span class="separator">—</span>
+      </fields-ui>
+    `);
+    await tick();
+    const span = f.querySelector('.separator');
+    expect(span.hasAttribute('inline')).toBe(false);
+  });
+});

package/components/fields/fields.yaml

@@ -0,0 +1,120 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIFields
+tag: fields-ui
+component: Fields
+category: form
+version: 1
+description: >-
+  Container for a group of <field-ui> children, laid out on a shared
+  6-column grid. Each <field-ui> spans the full row by default; opt
+  into a narrower span via [rows="1..6"]. Setting [inline] on the host
+  propagates the inline mode to every direct <field-ui> child so a
+  whole sub-form can switch label-position without per-field edits.
+  The grid alignment lets siblings on the same row line up cleanly —
+  consistent label columns + consistent control columns — without
+  the wrap-flex jitter of <row-ui wrap>.
+props:
+  inline:
+    description: >-
+      Propagate the inline layout mode to every direct <field-ui>
+      child. Equivalent to authoring `inline` on each child but
+      drives the whole group from one place. Toggle is reactive —
+      flipping the attribute on the host re-syncs all children.
+    type: boolean
+    default: false
+    reflect: true
+  columns:
+    description: >-
+      Number of grid columns the row uses. Defaults to 6 — common
+      multiples (1/2/3/6) divide cleanly. <field-ui rows="N"> spans
+      `N` of these columns. Override per-instance for tighter
+      4-column or wider 12-column compositions.
+    type: number
+    default: 6
+    reflect: true
+slots:
+  default:
+    description: >-
+      <field-ui> children. Non-field children (separators, headings)
+      are placed in the grid too — span them by setting `style="grid-column:
+      1 / -1"` for full-width content. Nested <fields-ui> works (an
+      outer 6-col grid hosting inner 3-col grids inside a single cell).
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens:
+  --fields-gap:
+    description: Gap between adjacent fields (row + column).
+  --fields-row-gap:
+    description: Override the row-gap independently of column-gap.
+  --fields-column-gap:
+    description: Override the column-gap independently of row-gap.
+a2ui:
+  rules: []
+anti_patterns:
+  - description: >-
+      Don't wrap <field-ui> children in <row-ui wrap> when grid
+      alignment is desired. row-ui is flex-wrap, which lets each
+      field size to its content — labels and controls won't share
+      a column with siblings.
+    severity: high
+  - description: >-
+      Don't set `inline` on individual <field-ui> children when the
+      whole group should switch — set it on the parent <fields-ui>
+      and let the propagation handle every child.
+    severity: medium
+examples:
+  - name: three-up-stacked
+    description: >-
+      A 3-up stacked field row — Status / Priority / Group — each
+      taking 2 of 6 columns. Equivalent to a Bootstrap "col-md-4"
+      pattern (12-col grid, span 4) but with chat-ui's 6-col default.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Fields",
+          "children": ["status", "priority", "group"]
+        },
+        { "id": "status",   "component": "Field", "label": "Status",   "rows": 2, "children": ["status-sel"] },
+        { "id": "priority", "component": "Field", "label": "Priority", "rows": 2, "children": ["priority-sel"] },
+        { "id": "group",    "component": "Field", "label": "Group",    "rows": 2, "children": ["group-sel"] },
+        { "id": "status-sel",   "component": "Select", "value": "todo" },
+        { "id": "priority-sel", "component": "Select", "value": "0" },
+        { "id": "group-sel",    "component": "Select", "value": "" }
+      ]
+  - name: inline-search-form
+    description: >-
+      An inline form — every field renders label-beside-control. Single
+      [inline] on the host drives all children.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Fields",
+          "inline": true,
+          "children": ["q", "kind"]
+        },
+        { "id": "q",    "component": "Field", "label": "Search", "children": ["q-input"] },
+        { "id": "kind", "component": "Field", "label": "Kind",   "children": ["kind-sel"] },
+        { "id": "q-input", "component": "Input", "type": "search" },
+        { "id": "kind-sel", "component": "Select", "value": "all" }
+      ]
+keywords:
+  - fields
+  - form
+  - grid
+  - layout
+  - group
+synonyms:
+  form:
+    - fields
+    - group
+    - layout
+related:
+  - field
+  - input
+  - select
+  - textarea

package/components/index.js

@@ -56,6 +56,7 @@ export { UITag } from './tag/tag.js';
 export { UISwatch } from './swatch/swatch.js';
 export { UICol }   from './col/col.js';
 export { UIField } from './field/field.js';
+export { UIFields } from './fields/fields.js';
 export { UIRow }   from './row/row.js';
 export { UIGrid }  from './grid/grid.js';
 export { UIStack } from './stack/stack.js';

package/components/inspector/inspector.js

@@ -1,5 +1,5 @@
 import { UIElement } from '../../core/element.js';
-import { registry } from '@adia-ai/a2ui-utils';
+import { registry } from '@adia-ai/a2ui-runtime';
 import '../tabs/tabs.js';
 import '../tabs/tab.js';
 import '../code/code.js';

package/core/streams-bridge.js

@@ -12,7 +12,7 @@
  * the dependency direction is web-components → a2ui-utils, not the
  * reverse. The bridge duck-types the renderer (it needs `.process()`,
  * nothing else), so it works with any A2UI-protocol consumer — the
- * actual `A2UIRenderer` from `@adia-ai/a2ui-utils`, a custom renderer,
+ * actual `A2UIRenderer` from `@adia-ai/a2ui-runtime`, a custom renderer,
  * or a test stub.
  *
  * Contract:

package/package.json

@@ -1,25 +1,32 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.2.4",
-  "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-utils.",
+  "version": "0.3.0",
+  "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "exports": {
-    ".":              "./index.js",
-    "./css":          "./index.css",
-    "./core":         "./core/index.js",
-    "./core/*":       "./core/*.js",
-    "./components":   "./components/index.js",
+    ".": "./index.js",
+    "./css": "./index.css",
+    "./core": "./core/index.js",
+    "./core/*": "./core/*.js",
+    "./components": "./components/index.js",
     "./components/*": "./components/*/*.js",
-    "./styles/*":     "./styles/*",
-    "./traits":       "./traits/index.js",
-    "./traits/*":     "./traits/*.js",
+    "./styles/*": "./styles/*",
+    "./traits": "./traits/index.js",
+    "./traits/*": "./traits/*.js",
     "./package.json": "./package.json"
   },
   "files": [
     "core/",
     "components/",
+    "!components/**/*.html",
+    "!components/**/*.examples.js",
     "styles/",
+    "!styles/**/*.html",
+    "!styles/**/*.examples.js",
     "traits/",
+    "!traits/**/*.html",
+    "!traits/**/*.examples.js",
+    "!traits/_api-table.js",
     "index.js",
     "index.css"
   ],
@@ -30,7 +37,7 @@
     "./core/provider.js"
   ],
   "dependencies": {
-    "@adia-ai/a2ui-utils": "^0.2.0"
+    "@adia-ai/a2ui-runtime": "^0.3.0"
   },
   "publishConfig": {
     "access": "public",

package/styles/components.css

@@ -54,6 +54,7 @@
 @import "../components/swatch/swatch.css";
 @import "../components/col/col.css";
 @import "../components/field/field.css";
+@import "../components/fields/fields.css";
 @import "../components/row/row.css";
 @import "../components/grid/grid.css";
 @import "../components/stack/stack.css";

package/styles/typography.css

@@ -256,7 +256,7 @@
 
   /* section — h2/h3, major division within content */
   --a-section-family: var(--a-font-family-heading);
-  --a-section-weight: var(--a-weight-normal);
+  --a-section-weight: var(--a-weight-semibold);
   --a-section-sm: 16px;
   --a-section-md: 17px;
   --a-section-lg: 19px;

package/traits/_catalog.json

@@ -599,7 +599,9 @@
         "dnd-drop",
         "dnd-drop-cancel"
       ],
-      "config": []
+      "config": [
+        "data-draggable-list-item-ghost"
+      ]
     },
     {
       "name": "drop-target",

package/traits/draggable-list-item.js

@@ -3,7 +3,7 @@ import { defineTrait } from './define.js';
 /**
  * `draggable-list-item` — pointer-driven list-reorder lifter.
  *
- * Authored for the Tasks UI playground (docs/projects/tasks-playground/spec/).
+ * Authored for the Tasks UI playground (apps/tasks/spec/).
  * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'motion-positioning').
  *
  * Different mental model than the existing `draggable` trait:
@@ -65,6 +65,8 @@ function announceImmediate(message) {
 
 const ATTR_LIFTING = 'data-draggable-list-item-lifting';
 const ATTR_SOURCE_ID = 'data-draggable-list-item-id';
+const ATTR_GHOST = 'data-draggable-list-item-ghost';
+const ATTR_GHOST_ACTIVE = 'data-draggable-list-item-ghost-active';
 const DRAG_THRESHOLD_PX = 4;
 
 /** @type {{ container: Element; index: number } | null} */
@@ -99,16 +101,80 @@ function dropTargetFromPoint(x, y) {
   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();
+/**
+ * Compute the column-relative insertion index at pointer (x, y) within
+ * a vertical-list droppable target. The returned index is in
+ * POST-REMOVAL coordinates — i.e., it counts items as if the dragging
+ * source had already been removed from the list.
+ *
+ * Why post-removal: the consumer's command (Move/Reorder) splices the
+ * source out FIRST, then splices in at `to_position`. If the trait
+ * counted the source in pre-removal coordinates, downward intra-list
+ * drags would land one slot too far (the source's current slot
+ * disappears post-removal, shifting indices down by one). Pre-removal
+ * cross-list drags happen to be immune, but the math is identical.
+ *
+ * Items are filtered to DIRECT CHILDREN with the trait's id attribute —
+ * not descendants — to keep nested droppables from poisoning the count.
+ * Zero-layout items (display:none, off-flow) are skipped.
+ *
+ * @param {Element} target — the droppable container ([data-droppable-id])
+ * @param {number} _x — pointer client X (unused for vertical-list math; kept for future horizontal-list support)
+ * @param {number} y — pointer client Y
+ * @param {string | null} sourceId — the dragging source's data-draggable-list-item-id; this item is
+ *   skipped while counting so the result is in post-removal coordinates
+ * @returns {number} insertion index in [0, count_after_removal]
+ */
+function indexWithinTarget(target, _x, y, sourceId) {
+  // Find all `[data-draggable-list-item-id]` descendants whose nearest
+  // `[data-droppable-id]` ancestor IS the target. This supports both
+  // structural patterns:
+  //   • Items as DIRECT children of the droppable host
+  //     (e.g. `<list-section data-droppable-id> <task-row-ui>...`).
+  //   • Items nested inside an intermediate container
+  //     (e.g. `<task-column-ui data-droppable-id> <div class="col-list">
+  //     <task-card-ui>...` — the column's CSS owns chrome on the host
+  //     while cards live in a flow-styled inner list).
+  //
+  // The closest-ancestor filter keeps nested droppables from poisoning
+  // the count: a child droppable's items have a different closest
+  // `[data-droppable-id]`, so they're skipped here.
+  //
+  // Pre-filter to source-skipped, layout-having items so we know which
+  // is truly last in post-removal coordinates.
+  const visible = [];
+  const candidates = target.querySelectorAll('[data-draggable-list-item-id]');
+  for (const child of candidates) {
+    if (child.closest('[data-droppable-id]') !== target) continue;
+    if (sourceId && child.getAttribute('data-draggable-list-item-id') === sourceId) continue;
+    const r = child.getBoundingClientRect();
+    if (r.height === 0 && r.width === 0) continue;
+    visible.push(r);
+  }
+  if (visible.length === 0) return 0;
+
+  for (let i = 0; i < visible.length; i++) {
+    const r = visible[i];
+    // Standard midline test (Pragmatic-DnD / Linear / Notion convention):
+    // cursor above this item's mid-line → insert before it; below → fall
+    // through to the next item. After the loop, if no hit, drop after
+    // all items (cursor was below every mid-line).
+    //
+    // History: v0.2.5 introduced a "last-item generous zone" that
+    // returned `visible.length` whenever the cursor was anywhere ON the
+    // last item — meant to make the 3-item-list "drop on last to send
+    // it to the bottom" gesture more permissive. Reverted: it broke the
+    // common "drop between second-to-last and last" path (hovering the
+    // last item's upper-half no longer resolved to "before last"). With
+    // the v0.2.6 indicator-visibility upgrade (3 px stroke + terminal
+    // caps + accent glow) the lower-half-targets-end behavior is now
+    // visually obvious, so the standard midline test reads cleanly
+    // without the carve-out.
     if (y < r.top + r.height / 2) return i;
   }
-  return items.length;
+  // Cursor is below every item's midline (and below last's top — only
+  // possible if the section has padding-bottom and cursor is in that gap).
+  return visible.length;
 }
 
 export const draggableListItem = defineTrait({
@@ -117,7 +183,12 @@ export const draggableListItem = defineTrait({
   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: [],
+  // Opt-in: when present, the trait renders a positioned clone of the
+  // host that follows the cursor during the drag (Pragmatic-DnD style
+  // ghost preview). Backward-compatible — absent = no ghost, current
+  // behavior. Style the ghost via consumer CSS using the
+  // [data-draggable-list-item-ghost-active] attribute.
+  config: [ATTR_GHOST],
   setup({ host }) {
     let id = host.getAttribute(ATTR_SOURCE_ID);
     if (!id) {
@@ -131,6 +202,61 @@ export const draggableListItem = defineTrait({
     /** @type {string | null} */
     let lastTargetId = null;
     let lastTargetIndex = -1;
+    /** @type {HTMLElement | null} */
+    let ghost = null;
+
+    function makeGhost() {
+      if (!host.hasAttribute(ATTR_GHOST)) return;
+      const r = host.getBoundingClientRect();
+      ghost = /** @type {HTMLElement} */ (host.cloneNode(true));
+      // Strip everything that could trigger interactive state on the clone:
+      // - trait IDs (registry hygiene)
+      // - tabindex (would attract focus when appended to body, painting
+      //   a focus-visible outline that double-traces the ghost)
+      // - aria-* state (clone is presentational; the source remains the
+      //   accessible focus target during drag)
+      // - data-selected (visual selection state belongs to the source)
+      // - id (no DOM-id duplicates)
+      ghost.removeAttribute(ATTR_SOURCE_ID);
+      ghost.removeAttribute(ATTR_LIFTING);
+      ghost.removeAttribute('data-keyboard-reorderable-id');
+      ghost.removeAttribute('data-keyboard-reorderable-lifting');
+      ghost.removeAttribute('data-selected');
+      ghost.removeAttribute('id');
+      ghost.removeAttribute('tabindex');
+      ghost.removeAttribute('aria-selected');
+      ghost.setAttribute('aria-hidden', 'true');
+      Object.assign(ghost.style, {
+        position: 'fixed',
+        left: `${r.left}px`,
+        top: `${r.top}px`,
+        width: `${r.width}px`,
+        margin: '0',
+        pointerEvents: 'none',
+        // Belt-and-suspenders: explicitly suppress outline + animation
+        // so the cloned element never paints a focus ring or competes
+        // with the consumer's [data-…-ghost-active] CSS for animation.
+        outline: 'none',
+        // Top-layer-ish; avoid 2147483647 to leave room for genuine top-layer
+        // surfaces (toasts, dialogs that may fire during drag).
+        zIndex: '10000',
+        transition: 'none',
+      });
+      ghost.setAttribute(ATTR_GHOST_ACTIVE, '');
+      document.body.appendChild(ghost);
+    }
+
+    function moveGhost(x, y) {
+      if (!ghost || !down) return;
+      // Translate the ghost by the cursor delta from the original pointerdown
+      // so the cursor stays at the same relative position inside the ghost.
+      ghost.style.translate = `${x - down.x}px ${y - down.y}px`;
+    }
+
+    function removeGhost() {
+      if (ghost?.parentNode) ghost.parentNode.removeChild(ghost);
+      ghost = null;
+    }
 
     function isDisabled() {
       return host.hasAttribute('disabled') || host.getAttribute('aria-disabled') === 'true';
@@ -145,7 +271,54 @@ export const draggableListItem = defineTrait({
       lastTargetId = null;
       lastTargetIndex = -1;
       host.removeAttribute(ATTR_LIFTING);
+      removeGhost();
+      // Always remove the keydown listener — even on disconnect — so a
+      // disposed trait can never keep firing Esc-cancel handlers against
+      // stale closures.
       document.removeEventListener('keydown', onKeyDown, true);
+      // Always remove the document-level fallback listeners too. They
+      // catch the case where pointerup fires outside the host's bounds
+      // and pointer capture didn't deliver it (browser quirks under
+      // tab-blur, popup-open, focus-loss). Re-armed on the next lift.
+      document.removeEventListener('pointerup', onDocPointerUp, true);
+      document.removeEventListener('pointercancel', onDocPointerCancel, true);
+      window.removeEventListener('blur', onWindowBlur);
+    }
+
+    /**
+     * Pointer-event safety net — if the host's own pointerup doesn't
+     * fire (browser bug, focus loss mid-drag, popup steals events),
+     * the document-level handler catches the release and runs the
+     * same cancel-or-drop logic. Idempotent with the host handler:
+     * whichever fires first runs reset(); the other is gated by the
+     * `down=null` short-circuit.
+     */
+    function onDocPointerUp(e) {
+      if (!down || down.pointerId !== e.pointerId) return;
+      onPointerUp(e);
+    }
+    function onDocPointerCancel(e) {
+      if (!down || down.pointerId !== e.pointerId) return;
+      if (lifted) {
+        document.dispatchEvent(new CustomEvent('dnd-drop-cancel', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: id, reason: 'pointer-cancel' },
+        }));
+      }
+      reset();
+    }
+    /** Window blur during a drag → cancel. Covers Cmd-Tab / popup-blocker / fullscreen escape. */
+    function onWindowBlur() {
+      if (!down) return;
+      if (lifted) {
+        document.dispatchEvent(new CustomEvent('dnd-drop-cancel', {
+          bubbles: true,
+          composed: false,
+          detail: { source_id: id, reason: 'blur' },
+        }));
+      }
+      reset();
     }
 
     function onPointerDown(e) {
@@ -165,6 +338,13 @@ export const draggableListItem = defineTrait({
       // 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);
+      // Document-level safety net for pointerup / pointercancel. Capture
+      // phase (true) so we beat any consumer that calls stopPropagation.
+      // host's own pointerup/cancel still fire normally; whichever lands
+      // first runs the cleanup, the other no-ops via the down-null guard.
+      document.addEventListener('pointerup', onDocPointerUp, true);
+      document.addEventListener('pointercancel', onDocPointerCancel, true);
+      window.addEventListener('blur', onWindowBlur);
     }
 
     function onPointerMove(e) {
@@ -176,6 +356,12 @@ export const draggableListItem = defineTrait({
         if (Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
         lifted = true;
         host.setAttribute(ATTR_LIFTING, '');
+        // Stamp the ghost preview AFTER setting the lifting attribute so
+        // the host's lifted state (opacity, etc.) is captured in the
+        // clone snapshot — except: we explicitly removed ATTR_LIFTING from
+        // the clone in makeGhost() so the ghost itself renders as a
+        // non-lifted card. Net effect: source dims, ghost looks "alive".
+        makeGhost();
         host.dispatchEvent(new CustomEvent('dnd-lift', {
           bubbles: true,
           composed: false,
@@ -188,9 +374,12 @@ export const draggableListItem = defineTrait({
         announceImmediate(`Picked up item. Press arrow keys to navigate. Press Space to drop. Press Esc to cancel.`);
       }
 
+      // Update the ghost on every move (cheap — single style write).
+      moveGhost(e.clientX, e.clientY);
+
       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;
+      const targetIdx = targetEl ? indexWithinTarget(targetEl, e.clientX, e.clientY, id) : -1;
 
       if (targetId !== lastTargetId || targetIdx !== lastTargetIndex) {
         lastTargetId = targetId;
@@ -224,7 +413,7 @@ export const draggableListItem = defineTrait({
         }));
         announceImmediate(`Drag cancelled. Item returned to its original position.`);
       } else {
-        const targetIdx = indexWithinTarget(targetEl, e.clientX, e.clientY);
+        const targetIdx = indexWithinTarget(targetEl, e.clientX, e.clientY, id);
         document.dispatchEvent(new CustomEvent('dnd-drop', {
           bubbles: true,
           composed: false,
@@ -253,10 +442,7 @@ export const draggableListItem = defineTrait({
       }
     }
 
-    host.addEventListener('pointerdown', onPointerDown);
-    host.addEventListener('pointermove', onPointerMove);
-    host.addEventListener('pointerup', onPointerUp);
-    host.addEventListener('pointercancel', () => {
+    function onHostPointerCancel() {
       if (lifted) {
         document.dispatchEvent(new CustomEvent('dnd-drop-cancel', {
           bubbles: true,
@@ -265,13 +451,20 @@ export const draggableListItem = defineTrait({
         }));
       }
       reset();
-    });
+    }
+
+    host.addEventListener('pointerdown', onPointerDown);
+    host.addEventListener('pointermove', onPointerMove);
+    host.addEventListener('pointerup', onPointerUp);
+    host.addEventListener('pointercancel', onHostPointerCancel);
 
     return () => {
       host.removeEventListener('pointerdown', onPointerDown);
       host.removeEventListener('pointermove', onPointerMove);
       host.removeEventListener('pointerup', onPointerUp);
-      document.removeEventListener('keydown', onKeyDown, true);
+      host.removeEventListener('pointercancel', onHostPointerCancel);
+      // reset() removes the document-level + keydown + window-blur
+      // listeners and the host-level lifting/ghost state.
       reset();
       host.removeAttribute(ATTR_SOURCE_ID);
     };

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

@@ -3,7 +3,7 @@ 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
+// driver for the apps/tasks/ 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 —

package/traits/droppable-collection.js

@@ -3,7 +3,7 @@ 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/).
+ * Authored for the Tasks UI playground (apps/tasks/spec/).
  * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'input-interaction').
  *
  * Pairs with `droppable` (per-target) and `draggable-list-item` (motion-

package/traits/droppable-collection.test.js

@@ -3,7 +3,7 @@ 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;
+// child droppables of the apps/tasks/ 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.

package/traits/droppable.js

@@ -3,7 +3,7 @@ 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/).
+ * Authored for the Tasks UI playground (apps/tasks/spec/).
  * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'input-interaction').
  *
  * Pairs with `draggable-list-item` (motion-positioning) which lifts a list
@@ -57,24 +57,35 @@ export const droppable = defineTrait({
 
     // Listen for drag-in-flight signals on the document so this droppable
     // knows when it should self-mark as the target.
+    //
+    // Bug guard (2026-05-04): per-host attribute is the source of truth.
+    // The previous implementation gated the leave branch on a shared
+    // module variable CURRENT_TARGET_ID, which made the result dependent
+    // on listener-execution order — when the target swap fired and the
+    // NEW target's listener ran before the OLD target's, the old one
+    // saw CURRENT_TARGET_ID already moved and skipped clearing its
+    // ATTR_OVER, leaving multiple columns visually marked as the drop
+    // target. Per-host hasAttribute() is independent of order.
     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;
+      if (!detail) return;
+      const isMe = detail.target_container_id === id;
+      const wasOver = host.hasAttribute(ATTR_OVER);
+      if (isMe && !wasOver) {
         host.setAttribute(ATTR_OVER, '');
+        CURRENT_TARGET_ID = id;
         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;
+      } else if (!isMe && wasOver) {
         host.removeAttribute(ATTR_OVER);
+        if (CURRENT_TARGET_ID === id) CURRENT_TARGET_ID = null;
         host.dispatchEvent(new CustomEvent('dnd-drop-leave', {
           bubbles: true,
           composed: false,
-          detail: { source_id: detail?.source_id ?? null },
+          detail: { source_id: detail.source_id ?? null },
         }));
       }
     }

package/traits/droppable.test.js

@@ -3,7 +3,7 @@ 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
+// apps/tasks/ 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

package/traits/keyboard-reorderable.js

@@ -3,7 +3,7 @@ import { defineTrait } from './define.js';
 /**
  * `keyboard-reorderable` — keyboard alternative to `draggable-list-item`.
  *
- * Authored for the Tasks UI playground (docs/projects/tasks-playground/spec/).
+ * Authored for the Tasks UI playground (apps/tasks/spec/).
  * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'keyboard-navigation').
  *
  * Implements the WCAG 2.5.7 single-pointer alternative + ARIA 1.1

package/traits/keyboard-reorderable.test.js

@@ -4,7 +4,7 @@ import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
 
 // Minimal smoke coverage. Keyboard-reorderable is the WCAG 2.5.7 +
 // ARIA 1.1 alternative to draggable-list-item for the
-// docs/projects/tasks-playground/ DnD model. Cases below verify
+// apps/tasks/ DnD model. Cases below verify
 // only the trait's own surface (schema, attribute lifecycle, id
 // assignment, tabindex injection). Multi-container keyboard flow
 // belongs in the playground integration suite.