@rozie-ui/data-table-lit 0.5.0 → 0.7.0

package/src/FilterText.ts

@@ -1,6 +1,7 @@
 import { LitElement, css, html } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { SignalWatcher, signal } from '@lit-labs/preact-signals';
+import { rozieAttr } from '@rozie/runtime-lit';
 
 @customElement('rozie-filter-text')
 export default class FilterText extends SignalWatcher(LitElement) {
@@ -24,17 +25,24 @@ export default class FilterText extends SignalWatcher(LitElement) {
    * `(columnId, value) => void` — apply the column filter (Enter / blur applies, Escape clears). Null-guarded at call sites.
    */
   @property({ type: Function }) setFilter: ((...args: any[]) => any) | null = null;
+  /**
+   * The column's human header, forwarded by the `#filter` slot scope — used as the control's accessible name in place of the internal column id.
+   */
+  @property({ type: String, reflect: true }) columnLabel: string = '';
   private _draft = signal('');
+  private _touched = signal(false);
+private __rozieFirstUpdateDone = false;
 
   private _disconnectCleanups: Array<() => void> = [];
   // Re-parenting guard: set true once the deferred teardown has actually
   // run (a genuine un-mount), so a subsequent reconnect knows to re-arm.
   private _rozieTornDown = false;
 
-  firstUpdated(): void {
-    // Seed the draft once at setup from the incoming value (setup-once, NOT in the
-    // template). Normalize null/undefined to '' so the input value binds to a string.
-    this._draft.value = this.value != null ? String(this.value) : '';
+  updated(changedProperties: Map<string, unknown>): void {
+    if (this.__rozieFirstUpdateDone && (changedProperties.has('value'))) { const __watchVal = (() => this.value)(); (() => {
+      this._touched.value = false;
+    })(); }
+    this.__rozieFirstUpdateDone = true;
   }
 
   disconnectedCallback(): void {
@@ -49,23 +57,45 @@ export default class FilterText extends SignalWatcher(LitElement) {
 
   render() {
     return html`
-<input class="rdt-col-filter" part="col-filter" type="text" aria-label=${this.columnId} .value=${this._draft.value} @input=${($event: InputEvent & { currentTarget: HTMLInputElement; target: HTMLInputElement }) => { this.onInput($event); }} @keydown=${($event: KeyboardEvent & { currentTarget: HTMLInputElement; target: HTMLInputElement }) => { this.onKeydown($event); }} @blur=${($event: FocusEvent & { currentTarget: HTMLInputElement; target: HTMLInputElement }) => { this.onBlur(); }} data-rozie-s-18cbb44e />
+<input class="rdt-col-filter" part="col-filter" type="text" aria-label=${rozieAttr(this.a11yLabel())} .value=${this.draftValue()} @input=${($event: InputEvent & { currentTarget: HTMLInputElement; target: HTMLInputElement }) => { this.onInput($event); }} @keydown=${($event: KeyboardEvent & { currentTarget: HTMLInputElement; target: HTMLInputElement }) => { this.onKeydown($event); }} @blur=${($event: FocusEvent & { currentTarget: HTMLInputElement; target: HTMLInputElement }) => { this.onBlur(); }} data-rozie-s-18cbb44e />
 `;
   }
 
+  // ── C-08 + N-04: the draft is DERIVED from `$props.value`, with a `touched` latch ────────
+  //
+  // C-08 — this component mounts once per rendered filter row and is NOT remounted when the
+  // filter changes, and its draft was seeded setup-once. So a programmatic reset (a "Clear
+  // filters" button, `setFilter(id, '')` from another control, a consumer writing
+  // `columnFilters` directly) moved the real filter while this input went on displaying the old
+  // text: the UI stated a filter that was no longer applied. `FilterSelect` was never affected —
+  // it reads `$props.value` live through `selectValue()`, which is the pattern adopted here.
+  //
+  // N-04 — the setup-once seed was ALSO wrong on Angular from the start: the emitter places
+  // setup-once statements in the CONSTRUCTOR, where an `input()` signal still returns its
+  // DEFAULT, because Angular sets inputs after construction. Measured on the sibling EditorDate,
+  // which opened empty on angular for every row while vue and lit seeded correctly. A derived
+  // read is correct on all six by construction, with no flash and no per-target branch.
+  //
+  // `touched` is what stops the live read from overwriting the user mid-type; the watch clears
+  // it, so an OUTSIDE change always wins and the input follows it. `@input` never moves
+  // `$props.value` (nothing is applied until Enter/blur), so the two can never fight.
+  draftValue = () => this._touched.value ? this._draft.value : this.value != null ? String(this.value) : '';
+
   // Untyped handler param neutralizes to `any`, so reading e.target.value typechecks
   // ×6 (the global-filter idiom). Never inline `$data.x = $event.target.value`.
   onInput = (e: any) => {
   this._draft.value = e && e.target ? e.target.value : '';
+  this._touched.value = true;
 };
 
   // setFilter is a Function prop (default null) — guard before calling.
   applyFilter = () => {
-  this.setFilter && this.setFilter(this.columnId, this._draft.value);
+  this.setFilter && this.setFilter(this.columnId, this.draftValue());
 };
 
   clearFilter = () => {
   this._draft.value = '';
+  this._touched.value = false;
   this.setFilter && this.setFilter(this.columnId, '');
 };
 
@@ -82,4 +112,15 @@ export default class FilterText extends SignalWatcher(LitElement) {
   onBlur = () => {
   this.applyFilter();
 };
+
+  // C-11 — the accessible name must be the column's HUMAN header, not its internal id.
+  // `columnId` is a lookup key (`unit_price`, `col_3`); a screen reader announcing it is
+  // reading an implementation detail aloud. table-core keeps the authored header on
+  // `column.columnDef.header`, which is a string for every declarative `<Column header>`;
+  // a header rendered by a function has no static text, so fall back to the id rather
+  // than invent one.
+  a11yLabel = () => {
+  if (typeof this.columnLabel === 'string' && this.columnLabel !== '') return this.columnLabel;
+  return this.columnId;
+};
 }

package/src/GroupBar.ts

@@ -25,6 +25,18 @@ export default class GroupBar extends SignalWatcher(LitElement) {
   border-color: var(--rdt-group-drop-zone-border-over, rgba(37, 99, 235, 0.7));
   background: var(--rdt-group-drop-zone-bg-over, rgba(37, 99, 235, 0.08));
 }
+.rdt-group-token-add[data-rozie-s-546c469a] {
+  font: inherit;
+  color: inherit;
+  border: none;
+  background: none;
+  cursor: pointer;
+}
+.rdt-group-token-add[data-rozie-s-546c469a]:focus-visible,
+.rdt-group-drop-zone[data-rozie-s-546c469a] [data-group-token][data-rozie-s-546c469a]:focus-visible {
+  outline: var(--rdt-focus-ring, 2px solid #2563eb);
+  outline-offset: 1px;
+}
 .rdt-group-drop-hint[data-rozie-s-546c469a] {
   opacity: 0.55;
   font-size: 0.8125em;
@@ -107,12 +119,12 @@ export default class GroupBar extends SignalWatcher(LitElement) {
     return html`
 <div class="rdt-group-bar" data-rozie-s-546c469a>
   
-  ${repeat<any>(this.groupableColumns, (col, _idx) => col.id, (col, _idx) => html`<span class="rdt-group-token" part="group-token" draggable="true" @dragstart=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onChipDragStart($event, col.id); }} @dragend=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDragEnd(); }} data-rozie-s-546c469a>${rozieDisplay(col.label)}</span>`)}
+  ${repeat<any>(this.groupableColumns, (col, _idx) => col.id, (col, _idx) => html`<button class="rdt-group-token rdt-group-token-add" type="button" part="group-token" draggable="true" aria-pressed=${rozieAttr(this.grouping.indexOf(col.id) !== -1 ? 'true' : 'false')} aria-label=${rozieAttr('Group by ' + col.label)} @dragstart=${($event: Event & { currentTarget: HTMLButtonElement; target: HTMLButtonElement }) => { this.onChipDragStart($event, col.id); }} @dragend=${($event: Event & { currentTarget: HTMLButtonElement; target: HTMLButtonElement }) => { this.onDragEnd(); }} @click=${($event: MouseEvent & { currentTarget: HTMLButtonElement; target: HTMLButtonElement }) => { this.toggleKey(col.id); }} data-rozie-s-546c469a>${rozieDisplay(col.label)}</button>`)}
 
   
-  <span class="${Object.entries({ "rdt-group-drop-zone": true, 'is-over': this._isOver.value }).filter(([, v]) => v).map(([k]) => k).join(' ')}" data-group-drop-zone="" @dragover=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDragOver($event); }} @dragleave=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDragLeave($event); }} @drop=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDrop($event); }} data-rozie-s-546c469a>
+  <span class="${Object.entries({ "rdt-group-drop-zone": true, 'is-over': this._isOver.value }).filter(([, v]) => v).map(([k]) => k).join(' ')}" data-group-drop-zone="" role="list" aria-label="Active grouping" @dragover=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDragOver($event); }} @dragleave=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDragLeave($event); }} @drop=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDrop($event); }} data-rozie-s-546c469a>
     
-    ${!this.grouping.length ? html`<span class="rdt-group-drop-hint" data-rozie-s-546c469a>Drag columns here to group</span>` : nothing}${repeat<any>(this.grouping, (gk, _idx) => gk, (gk, _idx) => html`<span class="${Object.entries({ "rdt-group-token": true, 'is-drop-target': this._dragKind.value === 'token' && this._dropKey.value === gk && this._draggingId.value !== gk }).filter(([, v]) => v).map(([k]) => k).join(' ')}" part="group-token" data-group-token="" draggable="true" @dragstart=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onTokenDragStart($event, gk); }} @dragover=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onTokenDragOver($event, gk); }} @dragend=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDragEnd(); }} data-rozie-s-546c469a>
+    ${!this.grouping.length ? html`<span class="rdt-group-drop-hint" data-rozie-s-546c469a>Drag columns here to group</span>` : nothing}${repeat<any>(this.grouping, (gk, _idx) => gk, (gk, _idx) => html`<span class="${Object.entries({ "rdt-group-token": true, 'is-drop-target': this._dragKind.value === 'token' && this._dropKey.value === gk && this._draggingId.value !== gk }).filter(([, v]) => v).map(([k]) => k).join(' ')}" part="group-token" data-group-token="" draggable="true" role="listitem" tabindex="0" aria-label=${rozieAttr(this.labelFor(gk) + ' grouping, position ' + (this.grouping.indexOf(gk) + 1) + ' of ' + this.grouping.length + '. Alt+Arrow to reorder, Delete to remove.')} @dragstart=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onTokenDragStart($event, gk); }} @dragover=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onTokenDragOver($event, gk); }} @dragend=${($event: Event & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onDragEnd(); }} @keydown=${($event: KeyboardEvent & { currentTarget: HTMLSpanElement; target: HTMLSpanElement }) => { this.onTokenKeydown($event, gk); }} data-rozie-s-546c469a>
       ${rozieDisplay(this.labelFor(gk))}
       <button class="rdt-group-token-remove" type="button" aria-label=${rozieAttr('Remove ' + this.labelFor(gk) + ' grouping')} @click=${($event: MouseEvent & { currentTarget: HTMLButtonElement; target: HTMLButtonElement }) => { this.removeKey(gk); }} data-rozie-s-546c469a>×</button>
     </span>`)}
@@ -210,6 +222,67 @@ export default class GroupBar extends SignalWatcher(LitElement) {
   this.applyGrouping && this.applyGrouping(this.grouping.filter((k: any) => k !== key));
 };
 
+  // ── C-04: the keyboard half of the group bar ────────────────────────────────────────────
+  // DECLARED AFTER removeKey ON PURPOSE: toggleKey and onTokenKeydown call it, and the React
+  // emitter lowers each to a useCallback whose dependency array is evaluated EAGERLY — declared
+  // above removeKey, every React GroupBar died at mount with a TDZ ReferenceError (measured in
+  // quick 260922-mkb; the same 87-02 ordering lesson as onEditorDropinKeyDown).
+  // Native HTML5 drag-and-drop was the SOLE input path for both adding and reordering, on
+  // elements with no tabindex, no role and no click/keydown handler. Remove and Clear were real
+  // `<button>`s, so a keyboard user could UNGROUP but could never group or reorder — the bar was
+  // a one-way door. HTML5 DnD has no keyboard equivalent by construction, so a parallel,
+  // explicitly-keyboard path is the only fix; both halves write through the SAME
+  // `applyGrouping` funnel the drop handler uses, so there is one ordering rule, not two.
+  //
+  // The palette chips become real `<button>`s (Enter/Space for free, focusable for free) rather
+  // than spans with `tabindex` + a hand-rolled key handler — the same reasoning that already
+  // made Remove and Clear buttons. A `<button draggable="true">` keeps the existing pointer
+  // path working unchanged.
+  //
+  // Reorder is Alt+Arrow on a grouping token, not plain Arrow: the tokens sit in a toolbar that
+  // a user also arrows THROUGH, and stealing bare arrows would trap them. Alt is the modifier
+  // Windows/macOS list reordering conventionally uses.
+  toggleKey = (id: any) => {
+  if (!id) return;
+  if (this.grouping.indexOf(id) !== -1) {
+    this.removeKey(id);
+    return;
+  }
+  this.applyGrouping && this.applyGrouping(this.grouping.concat([id]));
+};
+
+  // Move a grouping key one position left/right. No-op at the ends (never wraps: a wrap would
+  // make a held key cycle forever with no signal that the end was reached).
+  moveKey = (key: any, delta: any) => {
+  const cur = this.grouping;
+  const from = cur.indexOf(key);
+  if (from === -1) return;
+  const to = from + delta;
+  if (to < 0 || to >= cur.length) return;
+  const next = cur.slice();
+  next.splice(from, 1);
+  next.splice(to, 0, key);
+  this.applyGrouping && this.applyGrouping(next);
+};
+
+  onTokenKeydown = (e: any, gk: any) => {
+  if (!e) return;
+  const key = e.key;
+  if (key === 'Delete' || key === 'Backspace') {
+    e.preventDefault();
+    this.removeKey(gk);
+    return;
+  }
+  if (!e.altKey) return;
+  if (key === 'ArrowLeft') {
+    e.preventDefault();
+    this.moveKey(gk, -1);
+  } else if (key === 'ArrowRight') {
+    e.preventDefault();
+    this.moveKey(gk, 1);
+  }
+};
+
   clearAll = () => {
   this.clearGrouping && this.clearGrouping();
 };

package/src/helpers/columnDefUtils.ts

@@ -108,4 +108,76 @@ const collectGroupableLeafDefs = (defs: any): any[] => {
   return out
 }
 
-export { isSafeKey, wrapAggregationFn, collectNestedDefs, indexDefsById, collectGroupableLeafDefs }
+// ── E-03: the `editor` union is FOUR built-ins plus the 'custom' gate ────────────────────
+// `editorTypeOf` falls through to the plain text `<input>` for ANY unrecognised value, so a
+// consumer writing `editor="date"` — a value the comparison page and the root README both
+// advertised as a fifth built-in until the 260910 audit corrected them — got a text box with
+// no error, no warning, and no hint that `EditorDate` is a DROP-IN reached through
+// `editor="custom"` + an `#editor` fill. Same for any typo. The silent degradation was the
+// defect; the docs half is already corrected.
+//
+// Pure and message-returning rather than warning in place, so the contract (which values are
+// accepted, and what a rejected one is told) is unit-testable; `columnBuilders.rzts` owns the
+// latch and the console.warn.
+const EDITOR_KINDS = ['text', 'number', 'select', 'checkbox', 'custom']
+const editorKindWarning = (id: any, editor: any): string | null => {
+  if (editor == null) return null
+  if (typeof editor === 'string' && EDITOR_KINDS.indexOf(editor) !== -1) return null
+  return (
+    '[rozie-data-table] column "' + String(id) + '": editor="' + String(editor) + '" is not a ' +
+    'built-in editor. The built-ins are text | number | select | checkbox; anything else needs ' +
+    'editor="custom" plus an #editor slot fill (that is how <EditorDate> is used). Falling back ' +
+    'to the text input.'
+  )
+}
+
+
+// ── C-09: is this column spec EQUIVALENT to the one already registered? ──────────────────
+// `<Column>`'s re-register `$watch` keys on `$props.editorOptions`, `$props.aggregationFn` and
+// `$props.validate` — all reference types. The documented wiring for them is an INLINE literal
+// (`:editorOptions="[{ value: 'a' }, …]"`, `:validate="(v) => v !== ''"`), and an inline
+// literal is a NEW identity on every consumer render. So the watch fired every render,
+// `registerColumn` whole-object-replaced `$data.colReg`, the parent's re-feed watch keys on
+// `$data.colReg`, the re-feed re-rendered the parent, and the next render produced a new
+// identity again: not a slow path, a feedback loop.
+//
+// Equality is by VALUE, with functions compared on identity first and `toString()` second.
+// Source-text comparison is the point rather than a shortcut: an inline arrow re-created each
+// render has a different identity and identical source, which is exactly the case that has to
+// stop churning, while a genuinely different validator has different source and still
+// re-registers. Depth-bounded so a consumer object graph with a cycle cannot hang the compare.
+const columnSpecsEquivalent = (a: any, b: any, depth?: number): boolean => {
+  const d = typeof depth === 'number' ? depth : 0
+  if (a === b) return true
+  if (d > 4) return false
+  const ta = typeof a
+  const tb = typeof b
+  if (ta !== tb) return false
+  if (ta === 'function') {
+    try {
+      return String(a) === String(b)
+    } catch (err) {
+      return false
+    }
+  }
+  if (ta === 'number') return a !== a && b !== b   // NaN === NaN, for this purpose
+  if (a === null || b === null || ta !== 'object') return false
+  const aArr = Array.isArray(a)
+  if (aArr !== Array.isArray(b)) return false
+  if (aArr) {
+    if (a.length !== b.length) return false
+    for (let i = 0; i < a.length; i++) if (!columnSpecsEquivalent(a[i], b[i], d + 1)) return false
+    return true
+  }
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  if (ka.length !== kb.length) return false
+  for (let i = 0; i < ka.length; i++) {
+    const k = ka[i]
+    if (!Object.prototype.hasOwnProperty.call(b, k)) return false
+    if (!columnSpecsEquivalent(a[k], b[k], d + 1)) return false
+  }
+  return true
+}
+
+export { isSafeKey, wrapAggregationFn, collectNestedDefs, indexDefsById, collectGroupableLeafDefs, EDITOR_KINDS, editorKindWarning, columnSpecsEquivalent }

package/src/helpers/dateValue.ts

@@ -0,0 +1,55 @@
+// dateValue.ts — C-07. The ISO-date coercion `EditorDate` binds its native
+// `<input type="date">` to. Pure and sigil-free (no $props/$data/...), so it is unit-testable
+// and identical across all six leaves (helpers/ is vendored into each one by codegen).
+//
+// `EditorDate` seeded its draft with `String($props.value)` while its own `docs:` string —
+// which ships as JSDoc in every leaf `.d.ts` — promised "String-coerced to an ISO
+// `YYYY-MM-DD` string". `String()` is not that. A native date input accepts ONLY
+// `YYYY-MM-DD` and silently renders BLANK for anything else, so every ordinary way of
+// holding a date in a model produced an empty editor with no error:
+//   a `Date` object          -> "Mon Sep 21 2026 00:00:00 GMT-0700 (…)"  -> blank
+//   an ISO datetime string   -> "2026-09-21T00:00:00.000Z"               -> blank
+//   an epoch number          -> "1789084800000"                          -> blank
+//   a localised string       -> "09/21/2026"                             -> blank
+// Only a value that was ALREADY `YYYY-MM-DD` worked, i.e. the one case needing no coercion.
+
+/**
+ * Coerce an arbitrary cell value to the `YYYY-MM-DD` string a native date input accepts.
+ * Returns `''` for anything that cannot be read as a date — which is what the input shows for
+ * "no date", so an unparseable value degrades to empty rather than to a broken control.
+ */
+const toIsoDateString = (v: unknown): string => {
+  if (v == null || v === '') return ''
+
+  // Already the target format.
+  if (typeof v === 'string') {
+    const s = v.trim()
+    if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return s
+    // An ISO datetime: take the DATE PART AS WRITTEN. Parsing it and re-formatting from local
+    // parts shifts the day for anyone west of UTC ('2026-09-21T00:00:00Z' would render as the
+    // 20th in UTC-5), which is the classic off-by-one this branch exists to avoid.
+    const iso = /^(\d{4}-\d{2}-\d{2})T/.exec(s)
+    if (iso) return iso[1]
+    return fromDate(new Date(s))
+  }
+
+  if (typeof v === 'number') return Number.isFinite(v) ? fromDate(new Date(v)) : ''
+  if (typeof v === 'object' && typeof (v as Date).getTime === 'function') return fromDate(v as Date)
+  return ''
+}
+
+/**
+ * Format a Date as `YYYY-MM-DD` from its LOCAL parts. Local, not UTC: the input renders a
+ * calendar day, and `toISOString()` would show the previous day for anyone west of UTC on a
+ * midnight-local value.
+ */
+const fromDate = (d: Date): string => {
+  const t = d.getTime()
+  if (!Number.isFinite(t)) return ''
+  const y = d.getFullYear()
+  const m = d.getMonth() + 1
+  const day = d.getDate()
+  return String(y).padStart(4, '0') + '-' + String(m).padStart(2, '0') + '-' + String(day).padStart(2, '0')
+}
+
+export { toIsoDateString }

package/src/themes/base.css

@@ -1,9 +1,9 @@
 /*
  * @rozie-ui/data-table — base token reference.
  *
- * This file is the PUBLIC token reference. It declares 18 `--rozie-data-table-*`
- * tokens and wires each onto the short internal `--rdt-*` token the component's
- * scoped `<style>` actually reads. The component reads 82 internal `--rdt-*`
+ * This file is the PUBLIC token reference. It wires each of the 18 public
+ * `--rozie-data-table-*` tokens, with its default, onto the short internal `--rdt-*`
+ * token the component's scoped `<style>` actually reads. The component reads 82 internal `--rdt-*`
  * tokens in total, each with an inline `var(--rdt-x, <fallback>)` default, so the
  * table renders ZERO-CONFIG without importing this file.
  *
@@ -12,12 +12,17 @@
  * max-height. It does NOT reach every cosmetic value. 58 of the 82 internal tokens
  * have no public counterpart today, including the grid active-cell ring, the range
  * highlight, the fill handle, the invalid-cell outline, the group tokens, the filter
- * row, the per-header column ⋯ menu, most of the pagination bar (only
+ * row, the per-header column ⋯ menu (its panel is a composed @rozie-ui/popover, so its
+ * background, border and shadow follow --rozie-popover-bg, --rozie-popover-border and
+ * --rozie-popover-shadow, set at the same ancestor), most of the pagination bar (only
  * --rozie-data-table-control-border-color, --rozie-data-table-radius, and
  * --rozie-data-table-disabled-opacity are public — its background, padding, and
  * status-text size are not), and the chrome column widths. Those remain internal
  * and may be renamed; a design system that needs them should set the `--rdt-*`
- * name directly and accept that it is not yet a stable API. One Lit-specific rule: set
+ * name directly and accept that it is not yet a stable API. Those two counts are
+ * `<DataTable>`'s own; the sibling `<GroupBar>` reads 9 further internal tokens
+ * (`--rdt-group-drop-zone-*`, `--rdt-group-drop-marker`, `--rdt-focus-ring`), none of
+ * them public and all of them likewise inline-defaulted. One Lit-specific rule: set
  * the public tokens at or ABOVE the `<rozie-data-table>` element (`:root`, a wrapper, or
  * the element itself), never on the `.rozie-data-table` / `.rozie-data-table-wrap`
  * classes — on that target both of those render inside the component's shadow root,
@@ -35,96 +40,112 @@
  * `.rozie-data-table` / `.rozie-data-table-wrap` element). See
  * themes/shadcn.css, themes/material.css and themes/bootstrap.css for the
  * design-system bridges.
+ *
+ * WHERE THE DEFAULTS LIVE. Every default below is the FALLBACK of the `var()` that reads the
+ * public token, on the table's own elements — not a declaration of the token. Nothing in this
+ * file (or in a bridge) sets a `--rozie-data-table-*` token, so a value set on ANY ancestor
+ * (`:root`, `.dark`, a wrapper) or on the table itself reaches the table by plain inheritance,
+ * and the default applies only while no scope sets it. (A value an element declares for itself
+ * always beats one it would inherit, whatever the selector's specificity — which is why a
+ * declared default, anywhere on the path to the table, would shadow some ancestor's value.) A
+ * design-system bridge is the same mapping with the design system's variable as the fallback,
+ * so that variable too is resolved AT the table and follows the nearest theme scope — a
+ * `.dark` or `data-bs-theme` wrapper, not only `<html>`. The rule sits under `:where()` (zero
+ * specificity) so a bridge's copy wins in either import order; it also names the Lit host
+ * element `rozie-data-table`, the only element of that leaf a document stylesheet can reach.
  */
-.rozie-data-table-wrap,
-.rozie-data-table {
-  /* These public tokens aren't read directly by a CSS var() inside this
-     component's own scoped <style> — that is by design. This is the public
-     surface; the "Wire the PUBLIC tokens..." block further down assigns each
-     one onto the short internal --rdt-* custom property the component
-     actually reads. */
+:where(.rozie-data-table-wrap, .rozie-data-table, rozie-data-table) {
+  /* ─────────────────────────────────────────────────────────────────────────
+   * Wire the PUBLIC tokens onto the INTERNAL `--rdt-*` the component reads, each
+   * with its default as the fallback. The public tokens are not read by a CSS var()
+   * inside the component's own scoped <style> — that is by design: this block is the
+   * public surface, and a bridge re-declares the lines it maps with the design
+   * system's variable in place of the default. (The component still renders
+   * zero-config without this file via its own inline `var(--rdt-x, <fallback>)`
+   * defaults.) A public token read by several lines carries the same default in each.
+   * ───────────────────────────────────────────────────────────────────────── */
 
   /* ── palette (the few values most consumers will set) ───────────────────── */
-  --rozie-data-table-fg: inherit;
-  --rozie-data-table-accent: #0066cc;
-  --rozie-data-table-border-color: rgba(0, 0, 0, 0.08);
-  --rozie-data-table-control-border-color: rgba(0, 0, 0, 0.2);
-  --rozie-data-table-radius: 4px;
+  /* `currentColor` for `color` is the inherited text colour: the table takes its
+     container's colour unless the token is set. The accent is read through the two tokens
+     that default to it — the selection checkboxes (next line) and the resize grip while
+     dragging — so it follows an accent set on any ancestor. */
+  --rdt-color: var(--rozie-data-table-fg, currentColor);
+  --rdt-select-accent: var(--rozie-data-table-select-accent, var(--rozie-data-table-accent, #0066cc));
+  --rdt-border: 1px solid var(--rozie-data-table-border-color, rgba(0, 0, 0, 0.08));
+  --rdt-filter-border: 1px solid var(--rozie-data-table-control-border-color, rgba(0, 0, 0, 0.2));
+  --rdt-filter-radius: var(--rozie-data-table-radius, 4px);
 
   /* ── typography / cell metrics ──────────────────────────────────────────── */
-  --rozie-data-table-font: 14px system-ui, sans-serif;
-  --rozie-data-table-cell-padding: 0.5rem 0.75rem;
+  --rdt-font: var(--rozie-data-table-font, 14px system-ui, sans-serif);
+  --rdt-cell-padding: var(--rozie-data-table-cell-padding, 0.5rem 0.75rem);
 
   /* ── header ─────────────────────────────────────────────────────────────── */
   /* OPAQUE (was rgba(0,0,0,0.03)): a translucent header lets the scrolling body bleed
      through in sticky mode. #f7f7f7 ≈ the old 3%-black tint over white, but solid —
      matching the opaque header backgrounds the design-system themes already ship. */
-  --rozie-data-table-header-bg: #f7f7f7;
-  --rozie-data-table-header-weight: 600;
+  --rdt-header-bg: var(--rozie-data-table-header-bg, #f7f7f7);
+  --rdt-header-weight: var(--rozie-data-table-header-weight, 600);
 
   /* ── sort indicator ─────────────────────────────────────────────────────── */
-  --rozie-data-table-sort-indicator-opacity: 0.7;
+  --rdt-sort-ind-opacity: var(--rozie-data-table-sort-indicator-opacity, 0.7);
 
   /* ── resize handle ──────────────────────────────────────────────────────── */
-  --rozie-data-table-resize-grip-color: rgba(0, 0, 0, 0.12);
-  --rozie-data-table-resize-grip-active: var(--rozie-data-table-accent);
+  /* The grip while dragging defaults to the accent, resolved at the table. */
+  --rdt-resize-grip-color: var(--rozie-data-table-resize-grip-color, rgba(0, 0, 0, 0.12));
+  --rdt-resize-grip-active: var(--rozie-data-table-resize-grip-active, var(--rozie-data-table-accent, #0066cc));
 
   /* ── pin controls ───────────────────────────────────────────────────────── */
-  --rozie-data-table-pin-active-bg: rgba(0, 0, 0, 0.1);
+  --rdt-pin-btn-active-bg: var(--rozie-data-table-pin-active-bg, rgba(0, 0, 0, 0.1));
 
   /* ── column-visibility menu ─────────────────────────────────────────────── */
-  --rozie-data-table-menu-bg: #fff;
-  --rozie-data-table-menu-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
-
-  /* ── selection checkboxes ───────────────────────────────────────────────── */
-  --rozie-data-table-select-accent: var(--rozie-data-table-accent);
+  --rdt-colvis-menu-bg: var(--rozie-data-table-menu-bg, #fff);
+  --rdt-colvis-menu-shadow: var(--rozie-data-table-menu-shadow, 0 2px 8px rgba(0, 0, 0, 0.12));
+  --rdt-colvis-menu-border: 1px solid var(--rozie-data-table-border-color, rgba(0, 0, 0, 0.08));
+  --rdt-colvis-menu-radius: var(--rozie-data-table-radius, 4px);
+  --rdt-colvis-summary-border: 1px solid var(--rozie-data-table-control-border-color, rgba(0, 0, 0, 0.2));
+  --rdt-colvis-summary-radius: var(--rozie-data-table-radius, 4px);
 
   /* ── disabled pagination controls ──────────────────────────────────────── */
-  --rozie-data-table-disabled-opacity: 0.4;
-
-  /* ── virtual scroll (row windowing) ─────────────────────────────────────── */
-  /* Read with NO fallback at its one use site (`max-height: var(--rozie-data-table-max-height);`
-     on `.rdt-scroll`) — when unset the property is invalid at computed-value
-     time and the rule behaves as if `max-height` were never declared there,
-     i.e. `none` (unbounded). Declaring `none` here is the render-neutral
-     equivalent of that unset behavior, made explicit and overridable. */
-  --rozie-data-table-max-height: none;
-
-  /* ─────────────────────────────────────────────────────────────────────────
-   * Wire the PUBLIC tokens onto the INTERNAL `--rdt-*` the component reads. A
-   * bridge only needs to remap the public tokens above; these passthroughs do
-   * the rest. (The component still renders zero-config without this file via its
-   * own inline `var(--rdt-x, <fallback>)` defaults.)
-   * ───────────────────────────────────────────────────────────────────────── */
-  --rdt-font: var(--rozie-data-table-font);
-  --rdt-color: var(--rozie-data-table-fg);
-  --rdt-cell-padding: var(--rozie-data-table-cell-padding);
-  --rdt-border: 1px solid var(--rozie-data-table-border-color);
-  --rdt-header-bg: var(--rozie-data-table-header-bg);
-  --rdt-header-weight: var(--rozie-data-table-header-weight);
-  --rdt-sort-ind-opacity: var(--rozie-data-table-sort-indicator-opacity);
-
-  --rdt-filter-border: 1px solid var(--rozie-data-table-control-border-color);
-  --rdt-filter-radius: var(--rozie-data-table-radius);
-  --rdt-page-btn-border: 1px solid var(--rozie-data-table-control-border-color);
-  --rdt-page-btn-radius: var(--rozie-data-table-radius);
-  --rdt-page-btn-disabled-opacity: var(--rozie-data-table-disabled-opacity);
-  --rdt-page-size-border: 1px solid var(--rozie-data-table-control-border-color);
-  --rdt-page-size-radius: var(--rozie-data-table-radius);
-
-  --rdt-resize-grip-color: var(--rozie-data-table-resize-grip-color);
-  --rdt-resize-grip-active: var(--rozie-data-table-resize-grip-active);
-
-  --rdt-pin-btn-border: 1px solid var(--rozie-data-table-control-border-color);
-  --rdt-pin-btn-radius: var(--rozie-data-table-radius);
-  --rdt-pin-btn-active-bg: var(--rozie-data-table-pin-active-bg);
+  --rdt-page-btn-disabled-opacity: var(--rozie-data-table-disabled-opacity, 0.4);
+  --rdt-page-btn-border: 1px solid var(--rozie-data-table-control-border-color, rgba(0, 0, 0, 0.2));
+  --rdt-page-btn-radius: var(--rozie-data-table-radius, 4px);
+  --rdt-page-size-border: 1px solid var(--rozie-data-table-control-border-color, rgba(0, 0, 0, 0.2));
+  --rdt-page-size-radius: var(--rozie-data-table-radius, 4px);
+}
 
-  --rdt-colvis-summary-border: 1px solid var(--rozie-data-table-control-border-color);
-  --rdt-colvis-summary-radius: var(--rozie-data-table-radius);
-  --rdt-colvis-menu-border: 1px solid var(--rozie-data-table-border-color);
-  --rdt-colvis-menu-radius: var(--rozie-data-table-radius);
-  --rdt-colvis-menu-bg: var(--rozie-data-table-menu-bg);
-  --rdt-colvis-menu-shadow: var(--rozie-data-table-menu-shadow);
+/* The same defaults, once more, as private `--rdt-ds-*` values on the document root — for the
+   Lit leaf only. Inside a shadow root (and a Lit table nested in another component's shadow
+   root is out of reach of every document selector, the host element's included) the
+   component's own `:host` wiring reads each public token with `var(--rdt-ds-<token>)` as its
+   fallback, and only an INHERITED value can get there. A bridge declares the same names at
+   `:root`, which is how its skin reaches a Lit table no selector can match. Internal: not a
+   stable API. */
+:where(:root) {
+  --rdt-ds-fg: currentColor;
+  --rdt-ds-select-accent: #0066cc;
+  --rdt-ds-border-color: rgba(0, 0, 0, 0.08);
+  --rdt-ds-control-border-color: rgba(0, 0, 0, 0.2);
+  --rdt-ds-radius: 4px;
+  --rdt-ds-font: 14px system-ui, sans-serif;
+  --rdt-ds-cell-padding: 0.5rem 0.75rem;
+  --rdt-ds-header-bg: #f7f7f7;
+  --rdt-ds-header-weight: 600;
+  --rdt-ds-sort-indicator-opacity: 0.7;
+  --rdt-ds-resize-grip-color: rgba(0, 0, 0, 0.12);
+  --rdt-ds-resize-grip-active: #0066cc;
+  --rdt-ds-pin-active-bg: rgba(0, 0, 0, 0.1);
+  --rdt-ds-menu-bg: #fff;
+  --rdt-ds-menu-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
+  --rdt-ds-disabled-opacity: 0.4;
+}
 
-  --rdt-select-accent: var(--rozie-data-table-select-accent);
+/* ── virtual scroll (row windowing) ─────────────────────────────────────── */
+/* Read with NO fallback at its one use site (`max-height: var(--rozie-data-table-max-height);`
+   on `.rdt-scroll`) — when unset the property is invalid at computed-value time and the rule
+   behaves as if `max-height` were never declared there, i.e. `none` (unbounded). No bridge
+   maps it, so its default is declared, at zero specificity on the document root: `none` is
+   the render-neutral equivalent of that unset behavior, made explicit and overridable. */
+:where(:root) {
+  --rozie-data-table-max-height: none;
 }