@adia-ai/web-components 0.6.9 → 0.6.11

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.11] — 2026-05-20
+
+### Fixed
+- **`<canvas-ui>` — `.d.ts` hand-authored with full runtime API (claims-ui-v2 inbound FB-02 finding 2, P2).** Pre-fix: `canvas.d.ts` was 27-line codegen output declaring only `theme: string` + the `canvas-interaction` event listener — all 8 imperative runtime methods (`process`, `processAll`, `reset`, `pushVersion`, `back`, `forward`, `historyLength`, `historyIndex`) plus `getHTML()` were absent, forcing TS consumers to write `(canvas as any).processAll(...)`. The yaml/a2ui.json sidecar can only express declarative props per ADR-0027; codegen correctly skips imperative methods, but no compensating hand-authored layer existed. **Fix**: replaced `canvas.d.ts` with 63-line hand-authored declaration covering the full public API surface (each method documented with JSDoc matching the JS contract). Added `'canvas'` to the `HAND_AUTHORED_DTS` skip-set in `scripts/build/dts-codegen.mjs` with referencing comment so the next codegen run preserves the hand-authored file. Consumers post-upgrade can drop `(canvas as any).processAll(...)` casts entirely. Closes claims-ui-v2 inbound FEEDBACK-02 finding 2.
+
+## [0.6.10] — 2026-05-21
+
+### Added
+- **`<table-toolbar-ui>` — one-shot dev-mode `console.warn` when unknown opt-out attributes are set (claims-ui FB-04 enhancement).** Triggered by claims-ui FB-04 (RESPONSE-04, v0.6.9 §379): consumers writing `<table-toolbar-ui searchable>` (or `exportable` / `sortable` / `filterable` / `columns-visible`) thinking those attributes toggle visibility saw silent no-ops — the canonical attrs are `no-search` / `no-filter` / `no-sort` / `no-columns`. Pre-v0.6.10 behavior: the unknown attrs simply did nothing. Post-fix: a one-shot `console.warn` per element fires from `connected()`, names the unknown attrs, and points consumers at `npx adia-ai-doc table-toolbar` and the yaml SoT for the canonical reference. Pattern: warn-once-per-element via static `WeakSet` (`UITableToolbar._warnedUnknownAttrs`), matching the `tooltip-ui._warnedMissing` discipline. Scope: case-insensitive attrs starting with `search` / `export` / `sort` / `filter` / `column`, minus the 4 canonical opt-outs. Standard HTML/ARIA attrs (`id`, `class`, `role`, `aria-*`, `data-*`) are never flagged. Pinned by 12 new vitest cases in `table-toolbar.test.js`.
+
+### Internal
+- **`scripts/release/check-browser-safe.mjs` — strict-by-default + `/bin/` allowlist.** Flipped `STRICT = args.has('--strict')` → `STRICT = !args.has('--loose')` to match the convention shared by the other 6 release gates (`check:absolute-imports`, `check:no-self-import-css`, `check:scope-bare-descendants`, `check:lightningcss-build`, `check:rolldown-glob`, `check:with-css-pairing`). Paired with `/\/bin\//` added to `NODE_ONLY_PATTERNS` — silences the only pre-existing warning (`packages/web-components/bin/doc.mjs`, the `adia-ui-doc` CLI shipped v0.6.7). The CLI's `node:fs` / `node:path` / `node:url` imports are by design (#!/usr/bin/env node shebang); the broad `/bin/` pattern covers any future package-bin CLIs. Tracked at journal §378 as deferred-to-v0.6.10. No consumer-facing API change.
+
 ## [0.6.9] — 2026-05-21
 
 ### Fixed

package/components/canvas/canvas.d.ts

@@ -3,11 +3,16 @@
  *
  * @see https://ui-kit.exe.xyz/site/components/canvas
  *
- * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
- * run `npm run build:components`, then `npm run codegen:dts` to
- * regenerate; or hand-author this file fully if rich event types are
- * needed beyond what the yaml `events:` block can express.
+ * Hand-authored .d.ts (not codegen output). The yaml/a2ui.json sidecars
+ * describe declarative component props; canvas-ui's primary public API is
+ * a set of imperative runtime methods (`process`, `processAll`, `reset`,
+ * `pushVersion`, `back`, `forward`) which cannot be expressed in the yaml
+ * shape. Per ADR-0027, dts-codegen skips imperative methods — this file
+ * carries them by hand so TypeScript consumers don't need `(canvas as any)`
+ * casts. Keep this file in sync with `canvas.js` whenever the public API
+ * surface changes.
+ *
+ * Closes FB-02 finding 2 (claims-ui-v2 2026-05-20 cold-start).
  */
 
 import { UIElement } from '../../core/element.js';
@@ -18,6 +23,36 @@ export class UICanvas extends UIElement {
   /** Component property: theme. */
   theme: string;
 
+  /** Process a single A2UI message and apply it to the current surface. */
+  process(message: unknown): void;
+
+  /** Process an array of A2UI messages in order. */
+  processAll(messages: unknown[]): void;
+
+  /** Clear the canvas surface — discards all components. */
+  reset(): void;
+
+  /** Return the formatted innerHTML of the internal `<a2ui-root>`. */
+  getHTML(): string;
+
+  /**
+   * Save the given messages to the history stack (enables back/forward
+   * navigation). Truncates forward history if not at the newest version.
+   */
+  pushVersion(messages: unknown[]): void;
+
+  /** Navigate to the previous history version. Returns false if at oldest. */
+  back(): boolean;
+
+  /** Navigate to the next history version. Returns false if at newest. */
+  forward(): boolean;
+
+  /** Number of saved versions in the history stack. */
+  readonly historyLength: number;
+
+  /** Current position in the history stack (0-based). */
+  readonly historyIndex: number;
+
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UICanvas, ev: HTMLElementEventMap[K]) => unknown,

package/components/table-toolbar/class.js

@@ -138,10 +138,21 @@ export class UITableToolbar extends UIElement {
   #docListenerRaf = null;
   #sortIndicatorRafs = new Set();
 
+  // §381 (v0.6.10, slice F): one-shot dev-mode warning when consumers
+  // set common-but-unknown opt-out attributes (e.g. `searchable`,
+  // `exportable`, `sortable`) thinking they control table-toolbar
+  // visibility. Canonical attrs are `no-search` / `no-filter` /
+  // `no-sort` / `no-columns`. WeakSet pinned static so each element
+  // warns at most once even across reconnects.
+  static _warnedUnknownAttrs = new WeakSet();
+  static _CANONICAL_OPT_OUT_ATTRS = new Set(['no-search', 'no-filter', 'no-sort', 'no-columns']);
+  static _OPT_OUT_PREFIX_RE = /^(search|export|sort|filter|column)/i;
+
   // ── Lifecycle ────────────────────────────────────────────────────────────
 
   connected() {
     this.setAttribute('role', 'toolbar');
+    this.#warnUnknownOptOutAttrs();
     this.#stamp();
     this.#resolveTarget();
     this.#syncFromTarget();
@@ -165,6 +176,44 @@ export class UITableToolbar extends UIElement {
     this.#updateTitle();
   }
 
+  // ── Unknown opt-out attribute warning (§381, v0.6.10 slice F) ────────────
+
+  /**
+   * Warn once (per element) when the consumer sets attributes that look
+   * like opt-outs but aren't canonical. Triggered by claims-ui FB-04:
+   * consumers set `searchable` / `exportable` / `sortable` thinking they
+   * toggle visibility; the canonical attrs are `no-search`/`no-filter`/
+   * `no-sort`/`no-columns`. Silent no-op was the previous behavior —
+   * confusing UX. Pattern: warn-once-per-element via static WeakSet.
+   *
+   * Scope: attributes whose names start with `search`, `export`, `sort`,
+   * `filter`, `column` (case-insensitive). Canonical attrs are
+   * subtracted before the warn fires. Standard HTML/ARIA attrs (`id`,
+   * `class`, `role`, `aria-*`, `data-*`, etc.) are never flagged.
+   *
+   * Pinned by table-toolbar.test.js.
+   */
+  #warnUnknownOptOutAttrs() {
+    if (UITableToolbar._warnedUnknownAttrs.has(this)) return;
+    const unknowns = [];
+    for (const attr of this.attributes) {
+      const name = attr.name.toLowerCase();
+      if (UITableToolbar._CANONICAL_OPT_OUT_ATTRS.has(name)) continue;
+      if (!UITableToolbar._OPT_OUT_PREFIX_RE.test(name)) continue;
+      unknowns.push(name);
+    }
+    if (unknowns.length === 0) return;
+    UITableToolbar._warnedUnknownAttrs.add(this);
+    const list = unknowns.map((n) => `"${n}"`).join(', ');
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[table-toolbar-ui] Unknown opt-out attribute(s) ${list}. ` +
+      `Canonical opt-out attrs are: no-search, no-filter, no-sort, no-columns. ` +
+      `See packages/web-components/components/table-toolbar/table-toolbar.yaml ` +
+      `or run \`npx adia-ui-doc table-toolbar\` for the full attribute reference.`,
+    );
+  }
+
   // ── Target resolution ────────────────────────────────────────────────────
 
   #resolveTarget() {

package/components/table-toolbar/table-toolbar.test.js

@@ -0,0 +1,152 @@
+/**
+ * table-toolbar-ui tests
+ *
+ * Pinning the §381 (v0.6.10 slice F) one-shot dev-mode warning for
+ * unknown opt-out attributes. Triggered by claims-ui FB-04: consumers
+ * set `searchable` / `exportable` / `sortable` thinking they toggle
+ * visibility; canonical attrs are `no-search`/`no-filter`/`no-sort`/
+ * `no-columns`. Previous behavior: silent no-op.
+ *
+ * Contract:
+ *   1. Unknown attrs matching /^(search|export|sort|filter|column)/i
+ *      → console.warn fires once per element with the attr names listed
+ *   2. Canonical attrs (no-search/no-filter/no-sort/no-columns) → no warn
+ *   3. Unrelated attrs (id, class, role, aria-*, data-*) → no warn
+ *   4. Multiple unknown attrs in one declaration → single warn (one warn
+ *      per element, all unknown attrs in the message)
+ *   5. Repeated reconnects of the same element → still one warn total
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import '../../core/element.js';
+import './table-toolbar.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('table-toolbar-ui — unknown opt-out attribute warning (§381 / FB-04)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('warns when an unknown `searchable` attribute is set', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui searchable></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0][0];
+    expect(msg).toContain('[table-toolbar-ui]');
+    expect(msg).toContain('"searchable"');
+    expect(msg).toContain('no-search');
+    warn.mockRestore();
+  });
+
+  it('warns when an unknown `exportable` attribute is set', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui exportable></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0][0];
+    expect(msg).toContain('"exportable"');
+    warn.mockRestore();
+  });
+
+  it('warns when an unknown `sortable` attribute is set', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui sortable></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain('"sortable"');
+    warn.mockRestore();
+  });
+
+  it('warns when an unknown `filterable` attribute is set', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui filterable></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain('"filterable"');
+    warn.mockRestore();
+  });
+
+  it('warns when an unknown `columns-visible` attribute is set', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui columns-visible></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain('"columns-visible"');
+    warn.mockRestore();
+  });
+
+  it('does NOT warn on canonical no-search', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui no-search></table-toolbar-ui>');
+    await tick();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('does NOT warn on canonical no-filter / no-sort / no-columns', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui no-filter no-sort no-columns></table-toolbar-ui>');
+    await tick();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('does NOT warn on unrelated attributes (id, class, role, aria-*, data-*)', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui id="x" class="y" role="toolbar" aria-label="z" data-test="ok"></table-toolbar-ui>');
+    await tick();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('does NOT warn on canonical attrs even when placeholder is also set', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui no-search no-sort placeholder="Find..."></table-toolbar-ui>');
+    await tick();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('emits a single warn that names all unknown opt-out attrs', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui searchable exportable sortable></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0][0];
+    expect(msg).toContain('"searchable"');
+    expect(msg).toContain('"exportable"');
+    expect(msg).toContain('"sortable"');
+    warn.mockRestore();
+  });
+
+  it('warns at most once per element across reconnects', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const el = mount('<table-toolbar-ui searchable></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    // Disconnect + reconnect.
+    el.remove();
+    document.body.appendChild(el);
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1); // unchanged
+    warn.mockRestore();
+  });
+
+  it('mixes canonical + unknown — names only the unknown in the warning', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mount('<table-toolbar-ui no-search searchable></table-toolbar-ui>');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0][0];
+    expect(msg).toContain('"searchable"');
+    expect(msg).not.toContain('"no-search"');
+    warn.mockRestore();
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",