@adia-ai/web-components 0.8.43 → 0.8.44

package/components/textarea/textarea.class.js

@@ -18,6 +18,7 @@
  */
 
 import { UIFormElement } from '../../core/form.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 export class UITextarea extends UIFormElement {
   static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per textarea.yaml
@@ -32,6 +33,10 @@ export class UITextarea extends UIFormElement {
   static template = () => null;
 
   #textEl = null;
+  // gh#1647: tracks the aria-label VALUE this element itself last derived
+  // from `label`/`placeholder` (undefined when none) — value-tracking
+  // guard ported from tag.class.js/select.class.js (gh#1644/#1646).
+  #lastAutoAriaLabel = undefined;
 
   connected() {
     super.connected();
@@ -82,7 +87,10 @@ export class UITextarea extends UIFormElement {
     const label = this.querySelector('[slot="label"]');
     if (label && this.label) label.setAttribute('label', this.label);
 
-    this.setAttribute('aria-label', this.label || this.placeholder || '');
+    // A11y (gh#1647): never clobber a consumer's own aria-label
+    // (value-tracking guard, gh#1644/#1646).
+    const ariaSource = this.label || this.placeholder || '';
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, ariaSource);
   }
 
   #onInput = () => {

package/components/tour/tour.d.ts

@@ -43,10 +43,20 @@ export class UITour extends UIElement {
 the spotlight + popover; setting to `false` tears down.
  */
   active: boolean;
+  /** Start the tour automatically when the element connects. Useful for
+first-run flows gated by a storage flag on the consumer side.
+ */
+  autoStart: boolean;
   /** Current step index (0-based). Setting this property advances the
 tour to that step (updating spotlight + popover position).
  */
   step: number;
+  /** Optional localStorage key. When set, the tour records its
+completion state (`"done"`) to that key on finish/skip — and
+refuses to auto-start on subsequent loads if the key is "done".
+Useful for "show this tour once per user" flows.
+ */
+  storageKey: string;
 
   addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/core/a11y.d.ts

@@ -0,0 +1,22 @@
+/**
+ * core/a11y.js — shared accessible-name authorship guard.
+ *
+ * See the runtime module's own JSDoc for the full contract and the usage
+ * pattern (gh#1644 / gh#1646 / gh#1647).
+ */
+
+/**
+ * Reconcile an auto-derived `aria-label` against a possible consumer
+ * override, using a value-tracking guard rather than a plain boolean flag.
+ *
+ * @param el - the host element.
+ * @param lastAuto - the value this component wrote last time (`undefined`
+ *   = no active auto-derived value, either never set or consumer-owned).
+ * @param source - the label this render would derive; falsy = no auto name.
+ * @returns the new `lastAuto` to store back in the caller's own field.
+ */
+export function syncAutoAriaLabel(
+  el: HTMLElement,
+  lastAuto: string | undefined,
+  source: string,
+): string | undefined;

package/core/a11y.js

@@ -0,0 +1,64 @@
+/**
+ * core/a11y.js — shared accessible-name authorship guard.
+ *
+ * Ports the value-tracking guard proven on `tag.class.js`'s
+ * `#syncAccessibleName` (gh#1644 / PR #1645) and `select.class.js`'s
+ * `labeledElsewhere` variant (gh#1646 / PR #1648) into one shared helper,
+ * so every primitive that derives its own `aria-label` doesn't need to
+ * reimplement the compare-against-what-we-last-wrote logic (gh#1647).
+ *
+ * A plain boolean "did we ever set it" flag isn't enough: a consumer can
+ * overwrite `aria-label` directly via `setAttribute` at any point BETWEEN
+ * renders, bypassing the flag entirely. This guard instead compares the
+ * CURRENT attribute value against the value THIS component last wrote —
+ * a mismatch means a consumer has taken ownership, and auto-derivation
+ * stops until the source value the caller passes in changes again.
+ *
+ * Per-component gating (e.g. select-ui's `labeledElsewhere` — don't
+ * auto-name when a visible `label` or `aria-labelledby` already names the
+ * element, or don't auto-name off a default/placeholder-only value) is
+ * the CALLER's job: resolve the source string to '' when no auto name
+ * should apply this render, and pass the real derived string otherwise.
+ * This helper only ever reconciles "what we'd write" against "what's
+ * there now, and did we write it" — it carries no per-component policy.
+ *
+ * Usage (per component):
+ *
+ *   import { syncAutoAriaLabel } from '../../core/a11y.js';
+ *
+ *   #lastAutoAriaLabel = undefined;
+ *
+ *   #syncAccessibleName() {
+ *     const source = <derive the label this render, or '' for none>;
+ *     this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, source);
+ *   }
+ *
+ * Call `#syncAccessibleName()` early in `render()`, before any other
+ * aria-* bookkeeping that might read the (possibly just-changed)
+ * `aria-label` attribute.
+ *
+ * @param {HTMLElement} el
+ * @param {string | undefined} lastAuto - the value this component wrote
+ *   last time (`undefined` = the component has never derived a name for
+ *   the CURRENT attribute value, either because it never has, or because
+ *   a consumer has since taken ownership).
+ * @param {string} source - the label the component would derive right
+ *   now. Empty string (or any other falsy value) means "no auto name" —
+ *   any auto-set label is removed.
+ * @returns {string | undefined} the new `lastAuto` value — store this
+ *   back into the caller's own private field.
+ */
+export function syncAutoAriaLabel(el, lastAuto, source) {
+  const current = el.getAttribute('aria-label');
+  if (lastAuto !== undefined && current !== lastAuto) {
+    lastAuto = undefined; // a consumer took ownership between renders
+  }
+  const authored = current !== null && lastAuto === undefined;
+  if (authored) return lastAuto;
+  if (source) {
+    if (current !== source) el.setAttribute('aria-label', source);
+    return source;
+  }
+  if (current !== null) el.removeAttribute('aria-label');
+  return undefined;
+}

package/core/anchor.js

@@ -127,11 +127,15 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
   };
 }
 
-// Resolve a --popover-max-height declaration to px. The convention's consumers
-// declare px (JS-measured caps) or rem (stylesheet defaults); anything else
-// (calc, var chains, empty) returns NaN and the caller falls back to content
-// height. Kept deliberately narrow — this feeds a fit DECISION, not layout.
-function resolveLengthPx(raw) {
+// Resolve a px/rem CSS custom-property declaration to px. Originally scoped
+// to --popover-max-height (consumers declare px, JS-measured caps, or rem,
+// stylesheet defaults); exported (ADR-0076, table-toolbar-ui's stage-
+// resolution breakpoints, PLAN step 7) since a second, unrelated consumer
+// needs the identical px/rem-only resolution — anything else (calc, var
+// chains, empty) returns NaN and the caller falls back to its own default.
+// Kept deliberately narrow — this feeds a classification DECISION, not
+// layout, in both consumers.
+export function resolveLengthPx(raw) {
   const v = String(raw || '').trim();
   if (!v) return NaN;
   const m = /^(-?\d+(?:\.\d+)?)(px|rem)$/.exec(v);

package/core/element.js

@@ -91,7 +91,7 @@ function reflect(el, a, v, t) {
 }
 
 const parseAttr = (v, t) =>
-  t === Boolean ? v !== null : t === Number ? (v === null ? null : +v) : v;
+  t === Boolean ? v !== null && v !== 'false' : t === Number ? (v === null ? null : +v) : v;
 
 function adoptStyles(ctor) {
   if (Object.hasOwn(ctor, '_sa')) return;

package/custom-elements.json

@@ -1938,7 +1938,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided."
+              "description": "JSON array of {key, label, slot?, pct?, deemphasized?} legend items. Takes precedence over [for] when both are provided. `deemphasized` (REQ-R-007) mutes the row's swatch/label to the same muted-neutral tier chart-ui's own internal legend uses for a de-emphasized series (e.g. `composed@1:1`'s secondary line) — mirrored automatically from a `[for]`-bound chart's own `.legendData`, or settable explicitly here."
             },
             {
               "name": "shape",
@@ -1954,7 +1954,14 @@
                 "text": "string"
               },
               "default": "bottom",
-              "description": "Layout hint — drives flex-direction. Actual placement follows DOM order."
+              "description": "Layout hint — drives flex-direction. Actual placement follows DOM order. Superseded by a resolved `ratio` bucket (below) whenever one is in effect; this is the pre-ADR-0074 fallback for a legend with neither an explicit `ratio` nor a `[for]`-bound chart."
+            },
+            {
+              "name": "ratio",
+              "type": {
+                "text": "string"
+              },
+              "description": "Chart 2.0 legend layout bucket (ADR-0074, gh#1624 plan step 5, REQ-R-005): 3:2 renders a horizontal row, 1:1 a wrapped 2-column grid, 2:3 a vertical stacked list. An explicit value PINS the bucket regardless of any bound chart. Unset (default) auto-mirrors the `[for]`-bound chart's own resolved `data-ratio-resolved` bucket — the legend never runs its own container-query classification, since its own box is typically a thin strip with no studied aspect of its own. With neither a pin nor a bound chart, no bucket resolves and `position`'s flex-direction rules apply unchanged. The resolved bucket reflects read-only onto the host as `data-ratio-resolved`, mirroring chart-ui's own convention."
             },
             {
               "name": "interactive",
@@ -2077,6 +2084,13 @@
               },
               "description": "Chart size"
             },
+            {
+              "name": "ratio",
+              "type": {
+                "text": "string"
+              },
+              "description": "Chart 2.0 aspect-ratio bucket (ADR-0074). Unset (default) auto-snaps to the nearest of the three studied ratios by comparing the chart's own live box aspect against two midpoint boundaries (5:4 between 3:2/1:1, 4:5 between 1:1/2:3) — never interpolated; the resolved bucket reflects onto the host as `data-ratio-resolved`. Setting `ratio` explicitly pins that bucket regardless of the box's actual aspect, overriding the auto-snap. Orthogonal to `size` (overall scale) and `type`/`color` (ADR-0064's family axis) — this attribute lands the grammar + snap plumbing only; per-type studied renderings per bucket are later waves (gh#1624 plan steps 2-4)."
+            },
             {
               "name": "smooth",
               "type": {
@@ -2108,6 +2122,22 @@
               "default": "false",
               "description": "Show a skeleton placeholder instead of the chart body. Set to true while data is being fetched; clear once data arrives. Preserves the element's aspect-ratio dimensions so the skeleton occupies the same space the chart will fill. Parity with stat-ui[loading] and table-ui[loading] (§FB-12, v0.6.27)."
             },
+            {
+              "name": "y-min",
+              "type": {
+                "text": "number"
+              },
+              "default": "null",
+              "description": "Pins the value-axis domain floor for cartesian types (bar, line, area, scatter, multi-line, stacked-bar, grouped-bar, composed). Unset (default, null) already floors a positive series at 0 (the pre-1690 behavior, unchanged) — a migrating d3 consumer's own \"pin the floor to 0\" habit is the built-in default, not something to configure. Pin `y-min` explicitly for three OTHER cases: (1) zooming a narrow window — e.g. `y-min=\"0.9\" y-max=\"1\"` magnifies a percent series clustered near 92-95%, which reads flatter against the full auto-scaled [0,1] domain; (2) a mixed-sign series, where the unpinned floor never goes below 0 and negative values clip at the axis; (3) aligning two charts to one shared scale for a fair comparison. N/A for radial/part-to-whole types (pie, donut, radar, radial-bar, gauge, funnel, treemap, sankey, segments, sparkline) — those never read a shared linear value axis, so this prop is a no-op there (gh#1690). A datum outside the pinned domain is CLAMPED to the nearest edge for rendering (the value label/tooltip still shows the real value) rather than escaping the plot box."
+            },
+            {
+              "name": "y-max",
+              "type": {
+                "text": "number"
+              },
+              "default": "null",
+              "description": "Pins the value-axis domain ceiling for cartesian types (bar, line, area, scatter, multi-line, stacked-bar, grouped-bar, composed). Unset (default, null) keeps today's auto-scale ceiling (the data max). Pairs with `yMin` to pin the full domain; either may be set alone. N/A for radial/part-to-whole types — see `yMin` (gh#1690). A datum outside the pinned domain is CLAMPED to the nearest edge for rendering (the value label/tooltip still shows the real value) rather than escaping the plot box."
+            },
             {
               "name": "x",
               "type": {
@@ -4564,6 +4594,13 @@
               "default": "wide",
               "description": "Aspect ratio"
             },
+            {
+              "name": "data",
+              "type": {
+                "text": "string"
+              },
+              "description": "Cell data as a JSON array of `{ r, c, v, label? }` objects, or set the `.data` property directly with an already-parsed array. Parsed on connect if the attribute is present and `.data` hasn't already been set programmatically."
+            },
             {
               "name": "color-scheme",
               "type": {
@@ -6566,14 +6603,6 @@
               "default": "false",
               "description": "Allow interactive creation/deletion of connections via drag"
             },
-            {
-              "name": "port-size",
-              "type": {
-                "text": "number"
-              },
-              "default": "10",
-              "description": "Port indicator dot size in pixels"
-            },
             {
               "name": "port-size",
               "type": {
@@ -6590,14 +6619,6 @@
               "default": "false",
               "description": "View-only mode; disables drag/edit while keeping connections visible"
             },
-            {
-              "name": "show-ports",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Show port indicator dots. Defaults to true when editable"
-            },
             {
               "name": "show-ports",
               "type": {
@@ -6606,14 +6627,6 @@
               "default": "false",
               "description": "Show port indicators"
             },
-            {
-              "name": "stroke-width",
-              "type": {
-                "text": "number"
-              },
-              "default": "2",
-              "description": "Stroke width in pixels"
-            },
             {
               "name": "stroke-width",
               "type": {
@@ -9890,7 +9903,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Header / companion bar for a sibling table-ui. Renders an optional leading [slot=\"scope\"] region, title + count badge, an optional \"Showing X–Y of N\" range summary, filter / sort / columns popovers, a search input, an optional page-size select, and a trailing [slot=\"actions\"] region — all wired to the target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop next to (or above) any table-ui to add the standard data-grid toolbar without re-implementing search, filter, sort, column visibility, or pagination summary/page-size. Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi-select (searchable when ≥ 12 options), id-like keys → free-text contains. The column descriptor's `filter` field overrides the auto-detect: `'select'` forces multi-select even on high-cardinality columns; `'text'` forces a contains input even on small enums.",
+          "description": "Header / companion bar for a sibling table-ui. Renders an optional leading [slot=\"scope\"] region, title + count badge, an optional \"Showing X–Y of N\" range summary, filter / sort / columns popovers, a search input, an optional [slot=\"actions-leading\"] region, an optional page-size select, and a trailing [slot=\"actions\"] region — all wired to the target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop next to (or above) any table-ui to add the standard data-grid toolbar without re-implementing search, filter, sort, column visibility, or pagination summary/page-size. Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi-select (searchable when ≥ 12 options), id-like keys → free-text contains. The column descriptor's `filter` field overrides the auto-detect: `'select'` forces multi-select even on high-cardinality columns; `'text'` forces a contains input even on small enums.",
           "name": "UITableToolbar",
           "tagName": "table-toolbar-ui",
           "superclass": {
@@ -9991,6 +10004,21 @@
               "default": "false",
               "description": "Hide the search input. Search is shown by default; set to opt out."
             },
+            {
+              "name": "stage",
+              "type": {
+                "text": "string"
+              },
+              "description": "Explicit compaction-stage override (ADR-0076). Unset (the default, empty string) means auto-snap: the toolbar's own inline-size container query picks the nearest stage from its live width against the three --table-toolbar-bp-* breakpoints, snapping discretely, never interpolating. Setting stage explicitly pins that stage's rendering regardless of the container's actual width — overriding the container query, mirroring chart-ui's ratio override shape. Primary use: visual-eval fixtures that need a deterministic stage without resizing a real container, and a consumer embedding the toolbar inside a known-narrow panel who wants to skip auto-detection entirely. All four stages' CSS is now live (ADR-0076): search-tight steps the search field down (step 2); icon-only drops control labels and compacts/hides the range summary (steps 3+4); overflow collapses Filter/Sort/Columns into one \"More\" trigger routed through the same menu-ui/menu-item-ui pattern used elsewhere in the corpus (step 5). The resolved stage — the pin if set, otherwise the live width classification — also reflects onto the host as `data-stage-resolved` (step 7, informational only, mirrors chart-ui's `data-ratio-resolved` convention — never drives table-toolbar's own rendering, which stays 100% CSS-driven)."
+            },
+            {
+              "name": "chrome-only",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Suppress all four native controls/search at once (filter, sort, columns, search) as additive sugar over noFilter/noSort/noColumns/ noSearch (ADR-0076, ADIA2-9123). Precedence is pure, absolute OR — while set, all four stay off regardless of any individual no-* attribute's own value, with no partial re-enable path; to re-enable one control, remove chrome-only entirely and set the other three no-* attributes explicitly instead. The four granular attributes are not deprecated or removed — they remain the independently-addressable shipped API; chrome-only never replaces them, it's a convenience preset on top."
+            },
             {
               "name": "placeholder",
               "type": {
@@ -10013,9 +10041,17 @@
               "name": "scope",
               "description": "Leading region rendered BEFORE the [text]/[count] title cluster — e.g. a scope/view-switcher menu (an org's teams, a saved view). Positioning is CSS by DOM order, mirroring how [slot=\"actions\"] is a real, author-fillable insertion point rather than template-stamped content."
             },
+            {
+              "name": "empty",
+              "description": "Renders in place of the range-summary text — the same [data-summary] region — when [range-total] is EXPLICITLY present and equal to \"0\" (checked via hasAttribute, never the computed value alone, so an unset range-total during loading never flashes this content; ADR-0076, REQ-E-001). Mutually exclusive with a positive [range-total]: the normal \"Showing X-Y of N\" text always wins whenever range-total is a positive number. Empty (the default) preserves today's exact behavior — [data-summary] hides on a confirmed range-total=\"0\" exactly as before this slot existed. Plain author-supplied markup (text, an empty-state-ui composite, an icon+text pair) — table-toolbar does not template or constrain its shape. Naming matches chart-ui's own existing `empty` slot convention."
+            },
+            {
+              "name": "actions-leading",
+              "description": "Region rendered AFTER the search input and BEFORE the native page-size select (gh#1649) — for app-owned trigger buttons (e.g. custom Filter / Columns triggers that open the consumer's own drawer instead of the native filter/columns popovers) that must land ahead of the page-size select rather than after it, unlike [slot=\"actions\"]. Same real-insertion-point pattern as [slot=\"scope\"] / [slot=\"actions\"] — positioning is CSS by DOM order, not a template stamp. Empty (the default) has zero footprint on existing consumers."
+            },
             {
               "name": "actions",
-              "description": "Trailing action area — primary buttons (e.g. \"New row\") rendered after the search input."
+              "description": "Trailing action area — primary buttons (e.g. \"New row\") rendered after the search input, [slot=\"actions-leading\"], and the page-size select."
             }
           ],
           "events": [
@@ -10088,7 +10124,7 @@
                 "text": "array"
               },
               "default": "[]",
-              "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign=\"top\">); col-def also accepts `meta` as a JSON attribute (gh#925) — e.g. <col-def type=\"badge\" meta='{\"variants\":{\"Online\":\"success\"}}'> — so cell-type meta (badge variant maps, currency codes) is expressible in static HTML."
+              "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign=\"top\">); col-def also accepts `meta` as a JSON attribute (gh#925) — e.g. <col-def type=\"badge\" meta='{\"variants\":{\"Online\":\"success\"}}'> — so cell-type meta (badge variant maps, currency codes) is expressible in static HTML. Truncation contract for `render` cells (gh#1681) — a `render(value, row, cell, dataIndex)` function's returned markup isn't guaranteed to be a bare <span>/<a> the way built-in cell types are, so single-line ellipsis truncation isn't automatic; set `data-truncate` on whichever rendered element (any tag, including a custom element) should single-line-ellipsis to opt it into the same contract built-in cells get for free. `[wrap]` (host) / `[data-wrap]` (per-column) override it back to multi-line, matching built-in cells."
             },
             {
               "name": "data",
@@ -10145,6 +10181,14 @@
               "default": "false",
               "description": "Show checkbox column for row selection. Select-all checkbox in header. Shift+click for"
             },
+            {
+              "name": "clickable-rows",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Renders body rows with `cursor: pointer`. `row-click` fires unconditionally whether or not a listener is attached, so the cursor can't be inferred from listener presence — set this explicitly when row-click behavior is wired up (master-detail, open-flyout, navigation) so rows read as actionable."
+            },
             {
               "name": "sortable",
               "type": {