@adia-ai/web-components 0.5.8 → 0.5.9

package/components/tooltip/tooltip.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/tooltip
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * 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.

package/components/tree/tree.css

@@ -133,7 +133,7 @@
      no chrome). Sits before the [slot="actions"] hover-revealed slot. */
   [slot="badge"] {
     flex-shrink: 0;
-    font-size: var(--tree-badge-size, var(--a-fine-size));
+    font-size: var(--tree-badge-size, var(--a-ui-xs));
     color: var(--tree-badge-fg, var(--tree-fg-muted));
     background: var(--tree-badge-bg, transparent);
     padding: 0 var(--tree-badge-px, var(--a-space-1));

package/components/tree/tree.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/tree
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * 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.
@@ -32,3 +32,20 @@ export class UITree extends UIElement {
   ): void;
   addEventListener(type: 'tree-select', listener: (ev: TreeSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export class UITreeItem extends UIElement {
+  /** Optional trailing badge text (count, label, etc.). Renders muted + small + right-aligned alongside the row, mirroring the nav-item-ui badge API. When empty, the badge slot stays empty.
+
+Added in §184 (v0.5.5, FEEDBACK-08 §1). */
+  badge: string;
+  /** Optional leading icon name (Phosphor). */
+  icon: string;
+  /** When true, the item's children render expanded. Single-instance state; the parent `<tree-ui>` toggles this on click + Enter/Space + ArrowRight/ArrowLeft per tree-view APG. */
+  open: boolean;
+  /** Reflects the currently-selected item. Exactly one tree-item is selected per `<tree-ui>` parent (managed by the parent). */
+  selected: boolean;
+  /** Primary text rendered in the row. */
+  text: string;
+  /** Stable value emitted in `tree-select` event detail. */
+  value: string;
+}

package/core/form.js

@@ -51,10 +51,25 @@ export class UIFormElement extends UIElement {
       pattern:   { type: String,  default: '', reflect: true },
       minlength: { type: Number,  default: null, reflect: true },
       maxlength: { type: Number,  default: null, reflect: true },
+      // §220 (v0.5.9, FEEDBACK-14 §3): declarative trailing-debounce on the
+      // `input` event. When `throttle > 0`, `scheduleThrottledInput()`
+      // collapses bursts of value changes to one trailing emission at
+      // `quiet+throttle` ms. `change` continues to fire unthrottled. Use
+      // `flushPendingInput()` from `change` / blur paths to guarantee the
+      // trailing `input` fires before `change`. Default `0` keeps the
+      // synchronous behavior for non-opted-in consumers. Pattern landed
+      // for `<slider-ui>` in v0.5.5 §184; this graduates it to the shared
+      // base so `<input-ui>`, `<textarea-ui>`, `<slider-ui>` all share
+      // the same semantics + parity for consumer code.
+      throttle:  { type: Number,  default: 0, reflect: true },
     };
   }
 
   #dirty = false;
+  // §220 (v0.5.9): shared trailing-debounce timer + pending value for the
+  // `throttle` property. See `scheduleThrottledInput()` + `flushPendingInput()`.
+  #inputTimer = null;
+  #pendingValue = undefined;
 
   // ── ElementInternals accessors ──
 
@@ -105,6 +120,81 @@ export class UIFormElement extends UIElement {
     return valid;
   }
 
+  // ── §220 (v0.5.9): shared throttle helpers ──
+  //
+  // Subclasses with `throttle > 0` get trailing-debounced `input`
+  // dispatch + a synchronous flush API. Pattern source: v0.5.5 §184
+  // slider; graduated to the base in v0.5.9 §220 for parity across
+  // `<input-ui>`, `<textarea-ui>`, `<slider-ui>`.
+  //
+  // Usage in a subclass:
+  //   #onInput = () => {
+  //     this.value = this.#textEl.textContent;
+  //     this.scheduleThrottledInput();
+  //   };
+  //   #onCommit = () => {
+  //     this.flushPendingInput();
+  //     this.dispatchEvent(new CustomEvent('change', {...}));
+  //   };
+
+  /**
+   * Schedule (or immediately dispatch) a trailing-debounced `input`
+   * CustomEvent. When `this.throttle > 0`, the dispatch is deferred and
+   * collapsed across calls within a `throttle`-ms window. When 0, fires
+   * synchronously (legacy behavior).
+   *
+   * @param {Object} [detail] — optional detail override. Defaults to
+   *   `{ value: this.value }`.
+   */
+  scheduleThrottledInput(detail = null) {
+    const t = Number(this.throttle) || 0;
+    const event = () => new CustomEvent('input', {
+      bubbles: true,
+      detail: detail || { value: this.value },
+    });
+    if (t > 0) {
+      if (this.#inputTimer != null) clearTimeout(this.#inputTimer);
+      this.#pendingValue = this.value;
+      this.#inputTimer = setTimeout(() => {
+        this.#inputTimer = null;
+        this.#pendingValue = undefined;
+        this.dispatchEvent(event());
+      }, t);
+      return;
+    }
+    this.dispatchEvent(event());
+  }
+
+  /**
+   * Synchronously flush a pending throttled `input` dispatch. No-op when
+   * no timer is pending. Call this from `change` / blur / explicit-commit
+   * paths so consumers see the trailing `input` BEFORE the commit.
+   *
+   * @param {Object} [detail] — optional detail override.
+   */
+  flushPendingInput(detail = null) {
+    if (this.#inputTimer == null) return;
+    clearTimeout(this.#inputTimer);
+    this.#inputTimer = null;
+    this.#pendingValue = undefined;
+    this.dispatchEvent(new CustomEvent('input', {
+      bubbles: true,
+      detail: detail || { value: this.value },
+    }));
+  }
+
+  /**
+   * Drop any pending throttled `input` dispatch without firing. Called
+   * automatically on `disconnected()` to avoid late dispatches after
+   * teardown. Subclasses overriding `disconnected()` should `super.disconnected()`.
+   */
+  dropPendingInput() {
+    if (this.#inputTimer == null) return;
+    clearTimeout(this.#inputTimer);
+    this.#inputTimer = null;
+    this.#pendingValue = undefined;
+  }
+
   // ── Constraint engine ──
 
   #runConstraints(val) {
@@ -216,6 +306,9 @@ export class UIFormElement extends UIElement {
     this.removeEventListener('invalid', this.#onInvalid);
     this.removeEventListener('input', this.#onInput);
     this.removeEventListener('blur', this.#onBlur, true);
+    // §220 (v0.5.9): drop any pending throttled `input` dispatch — the
+    // element is gone; no late emissions.
+    this.dropPendingInput();
   }
 
   // ── Form lifecycle callbacks ──

package/core/signals.d.ts

@@ -57,6 +57,34 @@ export function computed<T>(fn: () => T): ComputedSignal<T>;
  * Run `fn` inside a reactive context. Re-runs when any signal read during the
  * last run changes. Returns a disposer.
  *
+ * §221h (v0.5.9) — re-run scheduling notes. Re-runs are scheduled via
+ * `queueMicrotask` so multiple signal mutations in the same synchronous tick
+ * batch into ONE re-run. This is the same semantic the render scheduler in
+ * `core/element.js` uses. Two consequences worth knowing:
+ *
+ * 1. **Reads of mutated signals between write and re-run see the new value
+ *    immediately** — only effect re-execution is deferred:
+ *    ```
+ *    count.value = 1;
+ *    count.value;  // 1 (read returns new value)
+ *    // effect hasn't run yet
+ *    ```
+ *
+ * 2. **Test isolation requires awaiting two microtasks** — one for the
+ *    effect's own re-run + one for any downstream effects it schedules:
+ *    ```
+ *    const tick = () => new Promise(r => queueMicrotask(r));
+ *    count.value = 5;
+ *    await tick();   // primary effect runs
+ *    await tick();   // downstream effects flush
+ *    ```
+ *
+ * See [`USAGE.md` §221h](../USAGE.md#221h--effect-dispatch-timing-signals) for
+ * a worked example. The double-`queueMicrotask` test-flush idiom is the
+ * canonical fix; don't reach for `await Promise.resolve()` (single microtask
+ * window) or `setTimeout(_, 0)` (different task queue) — neither matches the
+ * scheduler's batching shape reliably.
+ *
  * @example
  *   const dispose = effect(() => console.log(count.value));
  *   // later

package/index.d.ts

@@ -265,7 +265,7 @@ declare global {
     'chart-ui':           import('./components/chart/chart.js').UIChart;
     'chart-legend-ui':    import('./components/chart-legend/chart-legend.js').UIChartLegend;
     'chat-thread-ui':     import('./components/chat-thread/chat-thread.js').UIChatThread;
-    'col-ui':             import('./components/col/col.js').UIColumn;
+    'col-ui':             import('./components/col/col.js').UICol;
     'command-ui':         import('./components/command/command.js').UICommand;
     'demo-toggle-ui':     import('./components/demo-toggle/demo-toggle.js').UIDemoToggle;
     'description-list-ui': import('./components/description-list/description-list.js').UIDescriptionList;
@@ -297,7 +297,7 @@ declare global {
     'popover-ui':         import('./components/popover/popover.js').UIPopover;
     'progress-ui':        import('./components/progress/progress.js').UIProgress;
     'progress-row-ui':    import('./components/progress-row/progress-row.js').UIProgressRow;
-    'richtext-ui':        import('./components/richtext/richtext.js').UIRichtext;
+    'richtext-ui':        import('./components/richtext/richtext.js').UIRichText;
     'row-ui':             import('./components/row/row.js').UIRow;
     'segment-ui':         import('./components/segment/segment.js').UISegment;
     'skeleton-ui':        import('./components/skeleton/skeleton.js').UISkeleton;

package/package.json

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

package/styles/colors/semantics.css

@@ -593,6 +593,12 @@
   --a-chrome-ring-subtle: oklch(0 0 0 / 0.3);
   --a-chrome-shadow-soft: oklch(0 0 0 / 0.2);
   --a-chrome-backdrop:    oklch(0 0 0 / 0.5);
+  /* §230-bundle (v0.5.9): canonical badge-on-chrome pair — light text +
+     dark semi-transparent surface. Used by primitives that overlay text
+     on unpredictable backgrounds (swatch badges, video controls, color
+     readouts). Must read against red / blue / dark / light underlays. */
+  --a-chrome-fg:         var(--a-chrome-light);
+  --a-chrome-bg:         oklch(0 0 0 / 0.4);
 
   /* ══════════════════════════════════════════════════════════════
      DATA PALETTE — 10 categorical series colors for charts

package/styles/tokens.css

@@ -83,9 +83,12 @@
      k=0 → sharp (clamped to min). k=2 → extra round (clamped to max). */
   --a-radius-min: 0.25rem;
   --a-radius-max: 1.25rem;
+  /* §230-bundle (v0.5.9): xs scale notch added for badge / sub-tile / inline-pill use cases needing smaller radius than `sm`. */
+  --a-radius-xs-k: 0.166;
   --a-radius-sm-k: 0.333;
   --a-radius-md-k: 0.666;
   --a-radius-lg-k: 1.000;
+  --a-radius-xs: clamp(var(--a-radius-min), calc(var(--a-radius-k) * var(--a-radius-max) * var(--a-radius-xs-k)), var(--a-radius-max));
   --a-radius-sm: clamp(var(--a-radius-min), calc(var(--a-radius-k) * var(--a-radius-max) * var(--a-radius-sm-k)), var(--a-radius-max));
   --a-radius-md: clamp(var(--a-radius-min), calc(var(--a-radius-k) * var(--a-radius-max) * var(--a-radius-md-k)), var(--a-radius-max));
   --a-radius-lg: clamp(var(--a-radius-min), calc(var(--a-radius-k) * var(--a-radius-max) * var(--a-radius-lg-k)), var(--a-radius-max));

package/styles/typography.css

@@ -313,11 +313,13 @@
   --a-ui-family: var(--a-font-family-ui);
   --a-ui-weight: var(--a-weight-medium);
   --a-ui-tiny: 10px;
+  --a-ui-xs: 12px;
   --a-ui-sm: 13px;
   --a-ui-md: 14px;
   --a-ui-lg: 15px;
   --a-ui-size: var(--a-ui-md);
   --a-ui-leading: 1;
+  --a-ui-line-height: var(--a-body-leading);  /* §230-bundle (v0.5.9): alias for prose-style line-height inside UI body copy (e.g. alert message text). 1.5 by default. Closes the alert.css orphaned reference. */
   --a-ui-tracking: var(--a-font-tracking-normal);
   --a-ui-case: normal;
   --a-ui-color: inherit;