@adia-ai/web-components 0.8.22 → 0.8.24

package/components/list/list.css

@@ -107,18 +107,21 @@
   }
 
   /* Anatomy (header-row model):
-     row 1 = icon (col 1) · text/title (col 2) · action (col 3), all aligned
-     on the title row. row 2 = description, spanning col 2 / -1 (under the
+     row 1 = text/title (col 2) · action (col 3), aligned on the title row.
+     icon (col 1) spans both rows, centered on the whole item (gh#558).
+     row 2 = description, spanning col 2 / -1 (under the
      action) so multi-line supporting text uses the full content width rather
-     than being boxed into col 2 beside the action. For icon+text-only items
-     there is a single row, so `grid-row: 1` is identical to the old `1 / -1`.
+     than being boxed into col 2 beside the action.
      `[slot="content"]` (used when consumer provides custom rendering)
      spans all columns. */
   :scope {
     box-sizing: border-box;
     display: grid;
     grid-template-columns: auto 1fr;
-    column-gap: var(--list-item-gap-column);
+    /* NO column-gap (gh#524): an iconless item's empty auto track still
+       charges the gap, indenting content behind a ghost cell. The
+       icon-to-text spacing rides the icon's own margin-inline-end
+       instead, so a zero-width track costs zero. */
     row-gap: var(--list-item-gap-row);
     font-size: var(--list-item-font-size);
     color: var(--list-item-text-color);
@@ -141,6 +144,21 @@
     grid-row: 1;
     align-self: center;
     color: var(--list-item-icon-color);
+    /* carries the old column-gap (gh#524) */
+    margin-inline-end: var(--list-item-gap-column);
+  }
+  /* Two-line items center the glyph on the WHOLE item (gh#558) — Material's
+     two-line convention; pinned to row 1 it hung above the item center.
+     The span must be explicit (`span 2`): with no grid-template-rows the
+     explicit grid has zero rows, so `1 / -1` collapses back to one row.
+     Scoped by :has() so single-line items don't mint an empty second row
+     (which would charge row-gap below the content). */
+  :scope:has([slot="description"]) [slot="icon"] {
+    grid-row: 1 / span 2;
+  }
+  /* An empty stamped icon span must not resurrect the ghost track. */
+  :scope [slot="icon"]:empty {
+    display: none;
   }
 
   :scope [slot="text"] {
@@ -177,6 +195,8 @@
     grid-template-columns: auto 1fr auto;
   }
   :scope [slot="action"] {
+    /* carries the old column-gap on the trailing side (gh#524) */
+    margin-inline-start: var(--list-item-gap-column);
     grid-column: 3;
     grid-row: 1;
     align-self: center;

package/components/modal/modal.class.js

@@ -51,6 +51,11 @@ export class UIModal extends UIElement {
   #closeTimer = null;
   #dialogRef = null;
 
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['x'];
+
   static properties = {
     text:      { type: String,  default: '', reflect: true },
     size:      { type: String,  default: 'md', reflect: true },

package/components/modal/modal.yaml

@@ -79,6 +79,8 @@ tokens:
     description: Override surface border radius
   --modal-shadow:
     description: Override surface box shadow
+requiredIcons:
+  - x
 a2ui:
   rules:
     - >-

package/components/nav-group/nav-group.class.js

@@ -30,6 +30,11 @@ import { anchorPopover } from '../../core/anchor.js';
 import { logicalSlotted } from '../../core/logical-children.js';
 
 export class UINavGroup extends UIElement {
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['caret-right'];
+
   static properties = {
     text:        { type: String,  default: '',    reflect: true },
     icon:        { type: String,  default: '',    reflect: true },
@@ -48,6 +53,14 @@ export class UINavGroup extends UIElement {
   #popover = null;
   #anchorCleanup = null;
   #headerEl = null;
+  // gh#501 — the gh#459 ruling ("the group CONTAINING the selected route
+  // fills") self-enforces: watch descendant nav-item [selected] flips and
+  // membership changes so the header glyph fills without consumer wiring.
+  // Targets ONLY the weight sync — a full render() from the observer loops:
+  // render's textContent writes are themselves subtree childList mutations.
+  // Stable ref for symmetric disconnect.
+  #onChildSelection = () => this.#syncHeaderWeight();
+  #selectionObserver = null;
 
   #onHeaderKey = (e) => {
     if (!this.collapsible) return;
@@ -80,6 +93,21 @@ export class UINavGroup extends UIElement {
     }
 
     this.#headerEl?.addEventListener('keydown', this.#onHeaderKey);
+
+    // gh#501 — fill-on-child-selection needs no consumer wiring: observe
+    // [selected] flips on descendants + child list churn. Watching the
+    // whole subtree includes this host's own [selected], which render()
+    // reads anyway; render() writes only the icon's [weight], which the
+    // attributeFilter excludes, so the observer can't feed back.
+    if (!this.#selectionObserver) {
+      this.#selectionObserver = new MutationObserver(this.#onChildSelection);
+      this.#selectionObserver.observe(this, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['selected'],
+      });
+    }
   }
 
   render() {
@@ -99,9 +127,27 @@ export class UINavGroup extends UIElement {
     // path; [open] keeps driving aria-expanded only. A state-driven weight
     // swap, not a CSS color change, since Phosphor ships filled/regular as
     // distinct SVGs.
+    this.#syncHeaderWeight();
+  }
+
+  // Own [selected] OR any selected descendant item (gh#501) — the ruling's
+  // "group CONTAINING the selected route", self-enforcing. Skips the write
+  // when the weight is already right so the observer path stays quiet.
+  #syncHeaderWeight() {
+    const containsSelection =
+      this.hasAttribute('selected') || !!this.querySelector('nav-item-ui[selected]');
+    // Reflect contains-selection for CSS (gh#522): the icon COLOR half of
+    // the selection language keys on this host attribute — weight alone
+    // read as an unselected white glyph beside nav-item's primary one.
+    // The observer's attributeFilter is ['selected'], so this write on
+    // the host cannot feed back.
+    if (containsSelection !== this.hasAttribute('data-selected-within')) {
+      this.toggleAttribute('data-selected-within', containsSelection);
+    }
     const iconEl = this.querySelector('[slot="header"] [slot="icon"] icon-ui');
-    if (iconEl)
-      iconEl.setAttribute('weight', this.hasAttribute('selected') ? 'fill' : 'regular');
+    if (!iconEl) return;
+    const weight = containsSelection ? 'fill' : 'regular';
+    if (iconEl.getAttribute('weight') !== weight) iconEl.setAttribute('weight', weight);
   }
 
   showPopover() {
@@ -165,5 +211,7 @@ export class UINavGroup extends UIElement {
     this.#anchorCleanup?.();
     this.#anchorCleanup = null;
     this.#popover?.hidePopover?.();
+    this.#selectionObserver?.disconnect();
+    this.#selectionObserver = null;
   }
 }

package/components/nav-group/nav-group.css

@@ -14,6 +14,7 @@
     --nav-group-fg-hover:      var(--a-fg-strong);
     --nav-group-fg-muted:      var(--a-fg-muted);
     --nav-group-fg-selected:   var(--a-fg-strong);
+    --nav-group-icon-fg-selected: var(--md-sys-color-primary); /* one selection color with --nav-item-accent (gh#522) */
     --nav-group-bg-hover:      var(--a-bg-muted);
     --nav-group-icon-size:     calc(var(--nav-group-row-height) - var(--a-space-2));
     --nav-group-badge-size:    var(--a-ui-sm);
@@ -52,10 +53,18 @@
   /* Selected-look header treatment keys on [selected] — the CSS half of
      gh issue 459 (PR 460 corrected the icon weight): the group CONTAINING
      the selected route reads strong; a merely-expanded group does not. */
-  :scope[selected] > [slot="header"],
-  :scope[selected] > [slot="header"] [slot="icon"] {
+  :scope[selected] > [slot="header"] {
     color: var(--nav-group-fg-selected);
   }
+  /* Icon color = the SELECTION color, one language with nav-item's accent
+     glyph (gh#522, operator ruling 2026-07-30): filled + primary whenever
+     this group is selected OR contains the selected route.
+     [data-selected-within] is reflected by #syncHeaderWeight (gh#501) so
+     the JS-detected contains-selection state is CSS-addressable. */
+  :scope[selected] > [slot="header"] [slot="icon"],
+  :scope[data-selected-within] > [slot="header"] [slot="icon"] {
+    color: var(--nav-group-icon-fg-selected);
+  }
 
   /* Header row */
   [slot="header"] {

package/components/nav-group/nav-group.yaml

@@ -81,6 +81,8 @@ states:
 
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-right
 a2ui:
   rules:
     - >-

package/components/pagination/pagination.yaml

@@ -64,6 +64,9 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-left
+  - caret-right
 a2ui:
   rules:
     - rule: 'Renders below tables, card grids, or list views for paginated data. Emits page-change events.'

package/components/progress-row/progress-row.class.js

@@ -91,8 +91,16 @@ export class UIProgressRow extends UIElement {
     this.#labelEl.textContent = this.label;
     this.#labelEl.hidden = !this.label;
 
-    this.#metaEl.textContent = this.meta;
-    this.#metaEl.hidden = !this.meta;
+    // The [meta] ATTR owns the text when set. When it's absent, authored
+    // [slot="meta"] content — e.g. meta text with a trailing delta badge
+    // (gh#502) — is left intact instead of being wiped + hidden; only a
+    // genuinely empty meta element hides.
+    if (this.meta) {
+      this.#metaEl.textContent = this.meta;
+      this.#metaEl.hidden = false;
+    } else {
+      this.#metaEl.hidden = !this.#metaEl.hasChildNodes();
+    }
 
     if (this.value != null && this.value >= 0) {
       this.#progressEl.setAttribute('value', String(this.value));

package/components/richtext/richtext.css

@@ -96,6 +96,13 @@
     width: 100%;
     max-width: var(--richtext-max-width);
     padding: var(--richtext-py) var(--richtext-px);
+    /* Body spec set ONCE at the container (gh#546): p was pinned to
+       --richtext-body-size while li/ul had no font rule and inherited the
+       HOST page's larger base — chat-rendered lists read bigger than the
+       paragraph beside them. Everything now inherits this; headings/code
+       still override explicitly. */
+    font-size: var(--richtext-body-size);
+    line-height: var(--richtext-body-leading);
   }
 
   /* [flush] — paragraph-grade embedding (yaml `flush` prop): drop the

package/components/select/select.a2ui.json

@@ -106,6 +106,11 @@
       "type": "string",
       "default": ""
     },
+    "no-radio": {
+      "description": "Suppress the single-select radio indicator on option rows (gh#498). For menu-shaped switchers — workspace or user identity menus — where the trigger already shows the committed value and a per-row radio reads as redundant selection language. Rows keep their layout and aria-selected state; the trigger and selected-row weight carry the signal. No effect under [multiple]. IMPLIED by [mark] — a mark declares an identity switcher, which is always menu-shaped (gh#498 reopen: per-instance opt-outs proved forgettable).",
+      "type": "boolean",
+      "default": false
+    },
     "open": {
       "description": "Whether the listbox is open",
       "type": "boolean",

package/components/select/select.class.js

@@ -26,8 +26,8 @@ export class UISelect extends UIFormElement {
   // across all defined elements. Audited by check-required-icons.mjs
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
   // SPEC-040: [multiple] mode stamps <tag-ui> chips (own `x`), checkbox
-  // indicator (`check`), and search-input prefix (`magnifying-glass`).
-  static requiredIcons = ['caret-down', 'check', 'x', 'magnifying-glass'];
+  // indicator (`check`).
+  static requiredIcons = ['caret-down', 'check', 'x'];
 
   // §225 (v0.5.9, FEEDBACK-10 §3): once-per-element console.warn dedup when
   // consumer authors children that aren't native <option>/<optgroup>. The
@@ -53,6 +53,10 @@ export class UISelect extends UIFormElement {
     searchable:  { type: Boolean, default: false, reflect: true },
     freeText:    { type: Boolean, default: false, reflect: true, attribute: 'free-text' },
     divider:     { type: Boolean, default: false, reflect: true },
+    // gh#498 — suppress the single-select radio indicator for menu-shaped
+    // switchers (workspace/user identity menus) where the trigger already
+    // carries the committed value; rows keep layout + aria-selected.
+    noRadio:     { type: Boolean, default: false, reflect: true, attribute: 'no-radio' },
     // §184 (v0.5.5, FEEDBACK-08 §7): optional caption beneath the
     // trigger, wired to aria-describedby on the host.
     hint:        { type: String,  default: '', reflect: true },
@@ -817,11 +821,22 @@ export class UISelect extends UIFormElement {
         // Single-select mirrors the multi structure with a RADIO indicator
         // (operator ruling 2026-07-27) — selection is carried by the
         // indicator, not a row tint; CSS keys off [data-single-option].
+        // [no-radio] (gh#498) drops only the dot: identity-switcher menus
+        // read the committed value from the trigger, so the per-row radio
+        // is redundant there; row layout + aria-selected are unchanged.
+        // [mark] IMPLIES it (gh#498 reopen, 2026-07-30): mark declares an
+        // identity switcher, and the first fix proved per-instance
+        // attributes get forgotten — the playground got [no-radio], the
+        // site chrome switcher shipped radios anyway. The semantic
+        // attribute is the reliable signal; [no-radio] remains for
+        // markless menus.
         el.setAttribute('data-single-option', '');
-        const dot = document.createElement('span');
-        dot.setAttribute('data-radio', '');
-        dot.setAttribute('aria-hidden', 'true');
-        el.appendChild(dot);
+        if (!(this.noRadio || this.mark)) {
+          const dot = document.createElement('span');
+          dot.setAttribute('data-radio', '');
+          dot.setAttribute('aria-hidden', 'true');
+          el.appendChild(dot);
+        }
         const label = document.createElement('span');
         label.setAttribute('data-option-label', '');
         if (lead) label.innerHTML = `${lead}${escapeHTML(opt.label)}`;
@@ -1053,11 +1068,15 @@ export class UISelect extends UIFormElement {
 
   #applyFilter() {
     if (!this.#listbox) return;
-    const q = this.#query.toLowerCase();
+    // Underscores normalize to spaces on BOTH sides (gh#538): IANA-style
+    // labels ("America/Los_Angeles") must match the query a human types
+    // ("los angeles") — and vice versa.
+    const norm = (t) => t.toLowerCase().replace(/_/g, ' ');
+    const q = norm(this.#query);
     const opts = this.#listbox.querySelectorAll('[role="option"]');
     let anyVisible = false;
     for (const opt of opts) {
-      const label = (opt.textContent || '').toLowerCase();
+      const label = norm(opt.textContent || '');
       const match = !q || label.includes(q);
       if (match) {
         opt.removeAttribute('data-filtered-out');

package/components/select/select.yaml

@@ -74,6 +74,19 @@ props:
     type: boolean
     default: false
     reflect: true
+  no-radio:
+    description: >-
+      Suppress the single-select radio indicator on option rows (gh#498).
+      For menu-shaped switchers — workspace or user identity menus — where
+      the trigger already shows the committed value and a per-row radio
+      reads as redundant selection language. Rows keep their layout and
+      aria-selected state; the trigger and selected-row weight carry the
+      signal. No effect under [multiple]. IMPLIED by [mark] — a mark
+      declares an identity switcher, which is always menu-shaped
+      (gh#498 reopen: per-instance opt-outs proved forgettable).
+    type: boolean
+    default: false
+    reflect: true
   error:
     description: Validation error message
     type: string
@@ -261,7 +274,6 @@ requiredIcons:
   - caret-down
   - check               # checkbox indicator on each option in [multiple] mode
   - x                   # chip dismiss + clear-all affordance ([multiple] + [clearable])
-  - magnifying-glass    # search-input prefix ([searchable])
 a2ui:
   rules:
     - >-

package/components/stat/stat.js

@@ -8,6 +8,7 @@
  * Trend: up, down, neutral (colors the change badge accordingly)
  */
 
+import { defineIfFree } from '../../core/register.js';
 import { UIElement } from '../../core/element.js';
 
 class UIStat extends UIElement {
@@ -119,6 +120,8 @@ class UIStat extends UIElement {
     this.#iconEl = null;
   }
 }
-customElements.define('stat-ui', UIStat);
+// defineIfFree (gh#534): the prod bundle + module graph load in parallel;
+// second registration must no-op, not throw.
+defineIfFree('stat-ui', UIStat);
 
 export { UIStat };

package/components/stepper/stepper.css

@@ -13,20 +13,24 @@
   :where(:scope) {
     /* ── Circle ── */
     --stepper-size:            2rem;
-    --stepper-bg:              var(--md-sys-color-neutral-background);
-    --stepper-border:          var(--md-sys-color-neutral-outline);
-    --stepper-fg:              var(--a-fg-muted);
+    /* Operator stepper system (2026-07-30): next = transparent circle on a
+       low-emphasis outline; current = filled primary; completed = tonal
+       primary-container with a primary glyph. Borders on the two emphasized
+       states are transparent — the fill IS the affordance. */
+    --stepper-bg:              transparent;
+    --stepper-border:          var(--md-sys-color-neutral-outline-variant);
+    --stepper-fg:              var(--md-sys-color-neutral-on-surface-variant);
     --stepper-font:            var(--a-ui-sm);
     --stepper-weight:          var(--a-weight-medium);
     --stepper-border-size:     2px;
 
-    --stepper-bg-active:       var(--md-sys-color-neutral-background);
-    --stepper-border-active:   var(--md-sys-color-primary);
-    --stepper-fg-active:       var(--md-sys-color-primary);
+    --stepper-bg-active:       var(--md-sys-color-primary);
+    --stepper-border-active:   transparent;
+    --stepper-fg-active:       var(--md-sys-color-primary-on-primary);
 
-    --stepper-bg-done:         var(--md-sys-color-primary);
-    --stepper-border-done:     var(--md-sys-color-primary);
-    --stepper-fg-done:         var(--md-sys-color-primary-on-primary);
+    --stepper-bg-done:         var(--md-sys-color-primary-container);
+    --stepper-border-done:     transparent;
+    --stepper-fg-done:         var(--md-sys-color-primary);
 
     --stepper-line:            var(--md-sys-color-neutral-outline-variant);
     --stepper-line-done:       var(--md-sys-color-primary);
@@ -69,20 +73,20 @@
        co-located item legitimately reads parent tokens (the same
        scope pattern as menu-item-ui inside menu-ui's popover). */
     --stepper-item-size:           var(--stepper-size, 2rem);
-    --stepper-item-bg:             var(--stepper-bg, var(--md-sys-color-neutral-background));
-    --stepper-item-border:         var(--stepper-border, var(--md-sys-color-neutral-outline));
-    --stepper-item-fg:             var(--stepper-fg, var(--a-fg-muted));
+    --stepper-item-bg:             var(--stepper-bg, transparent);
+    --stepper-item-border:         var(--stepper-border, var(--md-sys-color-neutral-outline-variant));
+    --stepper-item-fg:             var(--stepper-fg, var(--md-sys-color-neutral-on-surface-variant));
     --stepper-item-font:           var(--stepper-font, var(--a-ui-sm));
     --stepper-item-weight:         var(--stepper-weight, var(--a-weight-medium));
     --stepper-item-border-size:    var(--stepper-border-size, 2px);
 
-    --stepper-item-bg-active:      var(--stepper-bg-active, var(--md-sys-color-neutral-background));
-    --stepper-item-border-active:  var(--stepper-border-active, var(--md-sys-color-primary));
-    --stepper-item-fg-active:      var(--stepper-fg-active, var(--md-sys-color-primary));
+    --stepper-item-bg-active:      var(--stepper-bg-active, var(--md-sys-color-primary));
+    --stepper-item-border-active:  var(--stepper-border-active, transparent);
+    --stepper-item-fg-active:      var(--stepper-fg-active, var(--md-sys-color-primary-on-primary));
 
-    --stepper-item-bg-done:        var(--stepper-bg-done, var(--md-sys-color-primary));
-    --stepper-item-border-done:    var(--stepper-border-done, var(--md-sys-color-primary));
-    --stepper-item-fg-done:        var(--stepper-fg-done, var(--md-sys-color-primary-on-primary));
+    --stepper-item-bg-done:        var(--stepper-bg-done, var(--md-sys-color-primary-container));
+    --stepper-item-border-done:    var(--stepper-border-done, transparent);
+    --stepper-item-fg-done:        var(--stepper-fg-done, var(--md-sys-color-primary));
 
     --stepper-item-line:           var(--stepper-line, var(--md-sys-color-neutral-outline-variant));
     --stepper-item-line-done:      var(--stepper-line-done, var(--md-sys-color-primary));
@@ -99,7 +103,8 @@
     --stepper-item-label-weight:   var(--a-weight-medium);
     --stepper-item-label-size:     var(--a-ui-size);
     --stepper-item-label-fg:       var(--md-sys-color-neutral-on-surface);
-    --stepper-item-pending-fg:     var(--a-fg-muted);
+    --stepper-item-label-fg-done:  var(--md-sys-color-neutral-on-surface-variant);
+    --stepper-item-pending-fg:     var(--md-sys-color-neutral-on-surface-variant);
     --stepper-item-desc-fg:        var(--md-sys-color-neutral-on-surface-variant);
     --stepper-item-desc-size:      var(--a-ui-sm);
 
@@ -181,7 +186,7 @@
   }
 
   :scope[status="completed"] [slot="label"] {
-    color: var(--stepper-item-label-fg);
+    color: var(--stepper-item-label-fg-done);
   }
 
   /* Pending label */

package/components/swiper/swiper.class.js

@@ -37,6 +37,11 @@
 import { UIElement } from '../../core/element.js';
 
 export class UISwiper extends UIElement {
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['caret-left', 'caret-right'];
+
   static properties = {
     autoplay:          { type: Boolean, default: false, reflect: true },
     interval:          { type: Number,  default: 5000,  reflect: true },

package/components/swiper/swiper.yaml

@@ -95,6 +95,9 @@ states:
   description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-left
+  - caret-right
 a2ui:
   rules:
     - rule: 'Horizontal slide carousel with touch + arrow nav. Hosts arbitrary children as slides.'

package/components/table/table.a2ui.json

@@ -14,7 +14,7 @@
   ],
   "properties": {
     "columns": {
-      "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.",
+      "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\">).",
       "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "component": {
@@ -39,6 +39,11 @@
       "type": "boolean",
       "default": false
     },
+    "frameless": {
+      "description": "Drop the table's outer 1px perimeter and nothing else (gh#511) — row dividers are untouched (the perimeter is split onto its own --table-perimeter token, defaulting to --table-border). For card-composed tables: the card owns the frame, so the table's square perimeter otherwise renders a doubled edge (flush bleed) or a stray inner box (with content above). Standalone tables keep their chrome by default. Theming path without the attribute: set --table-perimeter to transparent per instance.",
+      "type": "boolean",
+      "default": false
+    },
     "loading": {
       "description": "Renders N ghost skeleton rows in place of the body data (count derived from `paginate` if set, else 5). Header + columns stay intact so the table layout is preserved while data fetches. Sets aria-busy=\"true\" on the host. Data updates are deferred until loading is set back to false.",
       "type": "boolean",
@@ -74,6 +79,15 @@
       "type": "boolean",
       "default": false
     },
+    "valign": {
+      "description": "Vertical alignment of body-cell content. 'center' (default) keeps today's behavior — every cell centers on the row's cross-axis, which reads well for single-line rows. 'top' aligns each cell's content to the top of its padding box instead, so tall/wrapped rows (a [wrap] title column, a stacked identity cell) share one first-line scan anchor across the row rather than each cell floating at a different vertical center (gh#505). Per-column `valign` in the columns[] array (or <col-def valign=\"…\">) overrides the host per-column — e.g. keep a checkbox column centered while data cells top-align. Header cells always stay centered regardless of this prop (single-line by contract) — the checkbox/expand structural columns also default to centered under [valign=\"top\"] since they're not part of columns[].",
+      "type": "string",
+      "enum": [
+        "top",
+        "center"
+      ],
+      "default": "center"
+    },
     "wrap": {
       "description": "Allow body-cell content to wrap onto multiple lines. Default is single-line with ellipsis truncation (matches the row convention shared by <select-ui> + <nav-item-ui>); long unbreakable strings clip gracefully rather than rewrapping the row. With [wrap], row height auto-grows to fit wrapped content. For surgical opt-in on a single column, set [data-wrap] on the cell / col-def instead.",
       "type": "boolean",

package/components/table/table.class.js

@@ -22,6 +22,7 @@
  *   selectable — enable row selection via checkboxes
  *   striped    — alternate row background
  *   density    — 'compact' | 'standard' | 'comfortable'
+ *   valign     — 'center' (default) | 'top' — body-cell vertical alignment (gh#505)
  *   paginate   — rows per page (0 = no pagination)
  *   loading    — show loading overlay
  *   search     — global search filter string
@@ -33,7 +34,7 @@
  *
  * JS API:
  *   .columns = [{key, label, type, width, minWidth, maxWidth, flex,
- *                sortable, filterable, resizable, pinned, hidden,
+ *                sortable, filterable, resizable, pinned, hidden, valign,
  *                accessor, format, render, sortFn, sortDescFirst,
  *                filterType, filterFn, aggregate, meta}]
  *   .data    = [{...}, ...]
@@ -111,6 +112,10 @@ export class UITable extends UIElement {
     selectable: { type: Boolean, default: false, reflect: true },
     expandable: { type: Boolean, default: false, reflect: true },
     striped:    { type: Boolean, default: false, reflect: true },
+    valign:     { type: String,  default: 'center', reflect: true },
+    // gh#511 — drop the outer perimeter only (row dividers stay); the
+    // card+bleed composition's "let the container own the frame" knob.
+    frameless:  { type: Boolean, default: false, reflect: true },
     wrap:       { type: Boolean, default: false, reflect: true },
     raw:        { type: Boolean, default: false, reflect: true },
     density:    { type: String,  default: 'standard', reflect: true },
@@ -412,6 +417,7 @@ export class UITable extends UIElement {
         resizable: el.hasAttribute('resizable'),
         filterable: el.hasAttribute('filterable'),
         filterType: el.getAttribute('filter-type') || null,
+        valign:    el.getAttribute('valign') || null,        // 'top' | 'center' | null (inherit host)
       };
 
       const w = el.getAttribute('width');
@@ -896,6 +902,13 @@ export class UITable extends UIElement {
         cell.dataset.align = typeDef.align;
       }
 
+      // Vertical alignment — per-column override of the host [valign] (gh#505).
+      // Only stamped when the column explicitly opts in; unset falls through
+      // to the host's --table-valign token.
+      if (col.valign) {
+        cell.dataset.valign = col.valign;
+      }
+
       // Pinned
       if (col.pinned) {
         cell.setAttribute('data-pinned', col.pinned);