@gjsify/adwaita-web 0.31.0 → 0.32.0

package/src/elements/adw-checks.ts

@@ -0,0 +1,299 @@
+// <adw-checkbox> and <adw-radio> — the two form-control primitives, in ONE
+// module, for the same reason `scss/_checks.scss` is one partial: upstream
+// merges them (`refs/libadwaita/src/stylesheet/widgets/_checks.scss` has no
+// `_radio.scss` beside it), and everything but the corner radius, the glyph and
+// the group is shared. `refs/adwaita-web` split them into two files and the two
+// promptly drifted apart.
+//
+// WHAT LIVES IN `@gjsify/adwaita-core`, AND WHAT DOES NOT
+//
+// The checkbox has no core class: it is one boolean plus a third state, which
+// ADR 0004 calls out as too trivial to model. What IS core is the pair of
+// pieces a second renderer would otherwise re-invent:
+//
+//   - {@link RadioGroupState} — group exclusivity. The browser gives the inner
+//     `<input type="radio" name="…">` exclusivity for free, and STOPS THERE: it
+//     unchecks the sibling INPUT and leaves the sibling `<adw-radio>` host's
+//     `checked` attribute — the published state, and the selector
+//     `_checks.scss` paints from — stale, so a group left to the browser draws
+//     two selected radios. The shared state is what repaints the loser.
+//   - {@link resolveCheckState} — indeterminate outranks checked, which is read
+//     off the cascade in `_checks.scss:79-81` and is what `aria-checked` needs.
+//
+// WHAT IS NOT VERIFIABLE IN THIS TREE. `GtkCheckButton` is a GTK widget:
+// `refs/gtk` is EMPTY here and libadwaita vendors no `adw-checkbox.c`, so its
+// group semantics (`gtk_check_button_set_group`, whether a fresh group starts
+// with a member active) and the exact meaning of `GtkCheckButton:inconsistent`
+// are NOT verifiable and are not guessed at. Where a rule was needed the HTML
+// one is used and cited as such — clearing `indeterminate` on activation is the
+// HTML pre-click activation step, not a reading of GTK.
+//
+// NAMING. The state attribute is `checked`, not GtkCheckButton's `active`:
+// these elements wrap a real `<input>`, `checked` is the spelling every author
+// already writes, and it is what the stylesheet selects on. The published event
+// follows the attribute (`notify::checked`), not the GObject property.
+//
+// Attributes (both):
+//   checked       — boolean; reflects (and drives) the checked state.
+//   indeterminate — boolean; the third state, drawn as a dash. Outranks checked.
+//   disabled      — boolean; the control does not respond and is dimmed.
+//   label         — the text beside the indicator. When absent, the element's
+//                   existing child nodes become the label (so a server-rendered
+//                   `<adw-checkbox>Enable</adw-checkbox>` upgrades intact).
+// Attributes (<adw-radio> only):
+//   name          — the group. Exclusivity is scoped to it, exactly as `name`
+//                   scopes `<input type="radio">` — including the empty case:
+//                   HTML forms a radio button group only from a NON-EMPTY name,
+//                   so a nameless radio checks itself and unchecks nothing.
+//   value         — this member's value. Defaults to the label text, so a group
+//                   written without values still has distinguishable members.
+// Properties: checked / indeterminate / disabled / label (+ name / value).
+// Events:
+//   `notify::checked` (CustomEvent, bubbles, detail = { checked }) — fires on
+//     every change, programmatic included, on EVERY member a radio pick moves.
+//
+// A11Y: the inner input carries the role (native `checkbox` / `radio`) and an
+// explicit `aria-checked` derived from {@link resolveCheckState}, so the
+// indeterminate state announces as `mixed` for BOTH — HTML has a native mixed
+// checkbox (`input.indeterminate`) but no mixed radio.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_checks.scss
+// Reference: refs/adwaita-web/adwaita-web/scss/{_checkbox,_radio}.scss
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Copyright (c) 2025 csm (adwaita-web). MIT License.
+// Modifications: Implemented as Web Components for @gjsify/adwaita-web.
+
+import { RadioGroupState, resolveCheckState } from '@gjsify/adwaita-core';
+
+/**
+ * The document's radio groups. ONE registry, as global as a bare
+ * `<input type="radio" name="x">` outside a form is — two independent groups
+ * therefore need two names.
+ */
+const radioGroups = new RadioGroupState();
+
+/** The markup + state shared by `<adw-checkbox>` and `<adw-radio>`. */
+abstract class AdwCheckBase extends HTMLElement {
+    protected _input!: HTMLInputElement;
+    protected _indicator!: HTMLSpanElement;
+    protected _label!: HTMLSpanElement;
+    private _initialized = false;
+
+    /** `checkbox` or `radio` — the native control this element is built around. */
+    protected abstract get inputType(): 'checkbox' | 'radio';
+
+    /** What a click / Space / arrow key on the control means for this kind. */
+    protected abstract activate(): void;
+
+    /** Whether the control is checked. */
+    get checked(): boolean {
+        return this.hasAttribute('checked');
+    }
+
+    set checked(value: boolean) {
+        // `toggleAttribute` with a force flag is a no-op when the attribute
+        // already holds that state, so re-setting the current value mutates
+        // nothing and the notify never runs.
+        this.toggleAttribute('checked', !!value);
+    }
+
+    /** Whether the control is in the third, inconsistent state. */
+    get indeterminate(): boolean {
+        return this.hasAttribute('indeterminate');
+    }
+
+    set indeterminate(value: boolean) {
+        this.toggleAttribute('indeterminate', !!value);
+    }
+
+    /** Whether the control is inert. */
+    get disabled(): boolean {
+        return this.hasAttribute('disabled');
+    }
+
+    set disabled(value: boolean) {
+        this.toggleAttribute('disabled', !!value);
+    }
+
+    /** The label text beside the indicator. */
+    get label(): string {
+        return this.getAttribute('label') ?? this._label?.textContent ?? '';
+    }
+
+    set label(value: string) {
+        this.setAttribute('label', value);
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            this.onConnected();
+            return;
+        }
+        this._initialized = true;
+
+        // Captured BEFORE the element takes over its own children: a
+        // server-rendered `<adw-checkbox>Enable</adw-checkbox>` keeps its text.
+        const authored = [...this.childNodes];
+
+        this._input = document.createElement('input');
+        this._input.type = this.inputType;
+        this._input.className = 'adw-check-input';
+
+        this._indicator = document.createElement('span');
+        this._indicator.className = 'adw-check-indicator';
+
+        this._label = document.createElement('span');
+        this._label.className = 'adw-check-label';
+        const authoredLabel = this.getAttribute('label');
+        if (authoredLabel === null) this._label.append(...authored);
+        else this._label.textContent = authoredLabel;
+
+        this.replaceChildren(this._input, this._indicator, this._label);
+
+        // Keyboard (Space, and the arrow keys that move within a radio group)
+        // and a direct programmatic `input.click()` both surface as `change`.
+        this._input.addEventListener('change', () => this.activate());
+
+        // The indicator and the label cover the control; the input is 0x0, so
+        // every pointer click lands on one of them. A click that DID reach the
+        // input is already handled above — activating again would undo it.
+        this.addEventListener('click', (event) => {
+            if (this.disabled) return;
+            if (event.target === this._input) return;
+            this.activate();
+        });
+
+        this.onConnected();
+        this.render();
+    }
+
+    disconnectedCallback() {
+        this.onDisconnected();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        if (name === 'label') {
+            this._label.textContent = this.getAttribute('label') ?? '';
+        }
+        this.render();
+        if (name === 'checked') {
+            this.dispatchEvent(
+                new CustomEvent('notify::checked', { bubbles: true, detail: { checked: this.checked } }),
+            );
+        }
+    }
+
+    /** Extra wiring for a subclass on connect. */
+    protected onConnected(): void {}
+
+    /** Extra teardown for a subclass on disconnect. */
+    protected onDisconnected(): void {}
+
+    protected render(): void {
+        const state = resolveCheckState(this.checked, this.indeterminate);
+        this._input.checked = state === 'checked';
+        this._input.indeterminate = state === 'indeterminate';
+        // Explicit, because HTML has a native mixed CHECKBOX (the property
+        // above) but no mixed radio — this is the one spelling that announces
+        // the third state for both.
+        this._input.setAttribute('aria-checked', state === 'indeterminate' ? 'mixed' : String(state === 'checked'));
+        this._input.disabled = this.disabled;
+        this._label.hidden = this._label.childNodes.length === 0;
+    }
+}
+
+/** The Adwaita checkbox — `checkbutton > check` as a custom element. */
+export class AdwCheckbox extends AdwCheckBase {
+    static get observedAttributes() {
+        return ['checked', 'indeterminate', 'disabled', 'label'];
+    }
+
+    protected get inputType(): 'checkbox' {
+        return 'checkbox';
+    }
+
+    protected activate(): void {
+        // HTML's pre-click activation steps clear `indeterminate` before the
+        // toggle, so a user can always reach a definite state. That rule is the
+        // HTML spec's, not a reading of GtkCheckButton:inconsistent, whose
+        // behaviour is not verifiable in this tree.
+        this.indeterminate = false;
+        this.checked = !this.checked;
+    }
+}
+
+/** The Adwaita radio — `checkbutton > radio`, exclusive within its `name`. */
+export class AdwRadio extends AdwCheckBase {
+    private _unsubscribe: (() => void) | null = null;
+
+    static get observedAttributes() {
+        return ['checked', 'indeterminate', 'disabled', 'label', 'name', 'value'];
+    }
+
+    protected get inputType(): 'radio' {
+        return 'radio';
+    }
+
+    /** The group this member belongs to. */
+    get name(): string {
+        return this.getAttribute('name') ?? '';
+    }
+
+    set name(value: string) {
+        this.setAttribute('name', value);
+    }
+
+    /**
+     * This member's value. Falls back to the label text so a group authored
+     * without values still has members the group state can tell apart.
+     */
+    get value(): string {
+        return this.getAttribute('value') ?? this.label.trim();
+    }
+
+    set value(value: string) {
+        this.setAttribute('value', value);
+    }
+
+    protected activate(): void {
+        this.indeterminate = false;
+        // An UNNAMED radio is not in a group — HTML forms a radio button group
+        // only from a non-empty `name`, so a nameless one checks itself and
+        // never unchecks anything. Without this guard every nameless radio in
+        // the document would join one `''` group and fight over it.
+        if (this.name === '') {
+            this.checked = true;
+            return;
+        }
+        // The pick goes through the shared state, never straight onto this
+        // element: the member that LOSES the selection is a different element
+        // and only the state knows which one it is.
+        radioGroups.select(this.name, this.value);
+    }
+
+    protected onConnected(): void {
+        this._input.name = this.name;
+        if (this.name === '') return; // ungrouped — nothing to subscribe to
+        this._unsubscribe ??= radioGroups.subscribe((change) => {
+            if (change.name !== this.name) return;
+            this.checked = change.selected === this.value;
+        });
+        // A member declared checked seeds the group, so the first user pick
+        // knows what it is deselecting.
+        if (this.checked) radioGroups.select(this.name, this.value);
+    }
+
+    protected onDisconnected(): void {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+    }
+
+    protected render(): void {
+        super.render();
+        this._input.name = this.name;
+    }
+}
+
+customElements.define('adw-checkbox', AdwCheckbox);
+customElements.define('adw-radio', AdwRadio);

package/src/elements/adw-clamp.ts

@@ -1,27 +1,97 @@
-// <adw-clamp> — Constrains its child to a maximum width and centers it.
-// Attributes: maximum-size (px, default 600), tightening-threshold (unused;
-//   accepted for API parity with Adw.Clamp).
+// <adw-clamp> — Constrains its children to a maximum width and centers them.
+// Attributes: maximum-size (px, default 600), tightening-threshold (px, default 400).
+//
+// The clamp is NOT a `max-width`, which is what this element used to be. Adwaita
+// eases the child from "all the available width" into the cap across a tightening
+// region, and stamps a `small`/`medium`/`large` class on it — the arithmetic lives
+// in `@gjsify/adwaita-core` (`clampAllocate`) so this element and the NativeScript
+// widget produce the same width for the same viewport.
+//
+// The cap now sits on the CHILDREN, not on this element. The element has to keep
+// reporting the AVAILABLE width — it is what the curve is evaluated against — and
+// an element that caps itself reports the capped width back to its own
+// ResizeObserver, which is a feedback loop, not a measurement.
+//
+// `childMin` is passed as 0 rather than measured. libadwaita's
+// `lower = MAX (…, child_min)` says a child is never squeezed below its own
+// minimum, and the browser already applies that rule at the other end: `min-width`
+// wins over `max-width` (CSS 2.1 §10.4), so a child that declares a minimum keeps
+// it whatever cap this element writes. A child that declares none has a minimum of
+// 0, which is the value passed here — measuring `min-content` per child on every
+// resize would cost a synchronous reflow to arrive at the same layout.
+//
+// Reference: refs/libadwaita/src/adw-clamp-layout.c (child_size_from_clamp, allocate)
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/clamp.md
-// Reference: refs/libadwaita (Adw.Clamp)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { ADW_CLAMP_DEFAULTS, ADW_CLAMP_SIZE_CLASSES, clampAllocate, normalizeClampSize } from '@gjsify/adwaita-core';
+
 export class AdwClamp extends HTMLElement {
+    private _resize: ResizeObserver | null = null;
+    private _mutations: MutationObserver | null = null;
+
     static get observedAttributes() {
-        return ['maximum-size'];
+        return ['maximum-size', 'tightening-threshold'];
     }
 
     connectedCallback() {
-        this._sync();
+        // ResizeObserver delivers an initial observation on observe(), so the
+        // first allocation lands before paint without a separate seeding pass.
+        this._resize = new ResizeObserver(() => this._allocate());
+        this._resize.observe(this);
+        // Children appended AFTER connect are clamped too. Without this they
+        // would keep whatever width they came with — the same "evaluated once at
+        // connect time" bug the toolbar view's empty-bar handling still has.
+        this._mutations = new MutationObserver(() => this._allocate());
+        this._mutations.observe(this, { childList: true });
+        this._allocate();
+    }
+
+    disconnectedCallback() {
+        this._resize?.disconnect();
+        this._resize = null;
+        this._mutations?.disconnect();
+        this._mutations = null;
     }
 
     attributeChangedCallback() {
-        this._sync();
+        this._allocate();
     }
 
-    private _sync() {
-        const max = parseFloat(this.getAttribute('maximum-size') || '600');
-        this.style.maxWidth = `${max}px`;
+    private _allocate(): void {
+        const params = {
+            maximumSize: normalizeClampSize(this.getAttribute('maximum-size'), ADW_CLAMP_DEFAULTS.maximumSize),
+            tighteningThreshold: normalizeClampSize(
+                this.getAttribute('tightening-threshold'),
+                ADW_CLAMP_DEFAULTS.tighteningThreshold,
+            ),
+            childMin: 0,
+            childNat: 0,
+        };
+
+        const available = this.clientWidth;
+        const children = Array.from(this.children) as HTMLElement[];
+
+        // No box yet (disconnected, or measured before the first layout). GTK's
+        // equivalent is `for_size = -1`, where the child reports its natural size
+        // rather than being squeezed to nothing — so leave the children alone
+        // instead of capping them at 0 and collapsing the page.
+        if (available <= 0) {
+            for (const child of children) {
+                child.style.maxWidth = '';
+                child.style.marginInline = '';
+                for (const cls of ADW_CLAMP_SIZE_CLASSES) child.classList.remove(cls);
+            }
+            return;
+        }
+
+        const { childSize, sizeClass } = clampAllocate(available, params);
+        for (const child of children) {
+            child.style.maxWidth = `${childSize}px`;
+            child.style.marginInline = 'auto';
+            for (const cls of ADW_CLAMP_SIZE_CLASSES) child.classList.toggle(cls, cls === sizeClass);
+        }
     }
 }
 

package/src/elements/adw-combo-row.ts

@@ -17,7 +17,7 @@
 //   title/subtitle text column added to match Adw.ComboRow; the selection state
 //   machine composed from @gjsify/adwaita-core.
 
-import { ComboState } from '@gjsify/adwaita-core';
+import { ComboState, deriveRowLabels, normalizeComboOptions } from '@gjsify/adwaita-core';
 
 export class AdwComboRow extends HTMLElement {
     private _select!: HTMLSelectElement;
@@ -46,8 +46,10 @@ export class AdwComboRow extends HTMLElement {
 
         const items: string[] = JSON.parse(this.getAttribute('items') || '[]');
         // Seed the headless state BEFORE subscribing, so building the initial DOM
-        // below is not driven by a change notification.
-        this._state.setOptions(items.map((item) => ({ label: item, value: item })));
+        // below is not driven by a change notification. The string→descriptor
+        // mapping is core's: `<adw-drop-down>` had its own, richer copy, so the
+        // two selectors accepted different option vocabularies.
+        this._state.setOptions(normalizeComboOptions(items));
         this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
         const selectedIdx = this._state.selectedIndex;
 
@@ -114,10 +116,16 @@ export class AdwComboRow extends HTMLElement {
     }
 
     private _renderText() {
-        this._titleEl.textContent = this.getAttribute('title') ?? '';
-        const subtitle = this.getAttribute('subtitle') ?? '';
-        this._subtitleEl.textContent = subtitle;
-        this._subtitleEl.hidden = subtitle.length === 0;
+        // The `string_is_not_empty` label rule, from core — this block was one of
+        // six hand-rolled copies, all of which omitted the TITLE half.
+        const labels = deriveRowLabels({
+            title: this.getAttribute('title'),
+            subtitle: this.getAttribute('subtitle'),
+        });
+        this._titleEl.textContent = labels.title;
+        this._titleEl.hidden = !labels.titleVisible;
+        this._subtitleEl.textContent = labels.subtitle;
+        this._subtitleEl.hidden = !labels.subtitleVisible;
     }
 }
 

package/src/elements/adw-data-grid.ts

@@ -51,46 +51,36 @@
 // Responsive: the grid scrolls horizontally within its OWN container on narrow
 //   viewports (it never overflows the page); it sits inside an <adw-card>/boxed
 //   surface and follows light + dark via the adwaita-web CSS variables.
+// The derivations are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004):
+// the column tracks, the cell classes, the two normalisers, the cell text and
+// the activation rule. `@gjsify/adwaita-nativescript` renders the same widget
+// over `GridLayout` `ItemSpec`s — NativeScript has no subgrid — so the TRACK
+// rule is emitted as a renderer-neutral descriptor and only the mapping onto
+// `grid-template-columns` stays here. `@gjsify/adwaita-core/conformance`'s
+// `DATA_GRID_*_VECTORS` is the table both ports are held to.
 // Reference: Gtk.Grid usage in the Buchhaltung BWA view (native financial grid).
 // Reference: refs/libadwaita/src/stylesheet/_colors.scss (separator / card tokens).
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-/** Horizontal alignment of a column's header + cells. */
-export type AdwDataGridAlign = 'start' | 'end' | 'center';
-
-/** Accounting row emphasis. `normal` is the default plain data row. */
-export type AdwDataGridRowVariant = 'normal' | 'section' | 'subtotal' | 'total';
-
-/** A column descriptor — what to read (`key`), how to label + align it. */
-export interface AdwDataGridColumn {
-    /** The row-object key this column renders. */
-    key: string;
-    /** Header text (defaults to `key`). */
-    label?: string;
-    /** 'start' | 'end' | 'center'. Defaults to 'start' (or 'end' when numeric). */
-    align?: AdwDataGridAlign;
-    /** Fixed CSS track size (e.g. '80px', '6rem') — pins the column width. */
-    width?: string;
-    /** Fractional track weight (→ `<flex>fr`) — lets the column grow. */
-    flex?: number;
-    /** Render cells in a monospace family (tabular figures apply regardless). */
-    monospace?: boolean;
-    /** Convenience: right-align + tabular-nums (numeric columns of figures). */
-    numeric?: boolean;
-}
-
-/** A row: cell values keyed by column key + optional accounting metadata. */
-export interface AdwDataGridRow {
-    /** Accounting emphasis. Default 'normal'. */
-    variant?: AdwDataGridRowVariant;
-    /** Make just this row clickable (overrides the element-level flag). */
-    interactive?: boolean;
-    /** Cell values keyed by column key (pre-formatted strings, or numbers). */
-    [key: string]: string | number | boolean | AdwDataGridRowVariant | undefined;
-}
-
-const VARIANTS: ReadonlySet<string> = new Set(['normal', 'section', 'subtotal', 'total']);
+import {
+    dataGridCellText,
+    dataGridColumnClasses,
+    dataGridRowInteractive,
+    dataGridTrackTemplate,
+    dataGridTracks,
+    normalizeDataGridColumns,
+    normalizeDataGridVariant,
+} from '@gjsify/adwaita-core';
+import type { AdwDataGridColumn, AdwDataGridRow } from '@gjsify/adwaita-core';
+
+export type {
+    AdwDataGridAlign,
+    AdwDataGridCellValue,
+    AdwDataGridColumn,
+    AdwDataGridRow,
+    AdwDataGridRowVariant,
+} from '@gjsify/adwaita-core';
 
 export class AdwDataGrid extends HTMLElement {
     private _captionEl!: HTMLDivElement;
@@ -110,7 +100,7 @@ export class AdwDataGrid extends HTMLElement {
     }
 
     set columns(value: ReadonlyArray<AdwDataGridColumn>) {
-        this._columns = normalizeColumns(value);
+        this._columns = normalizeDataGridColumns(value);
         if (this._initialized) this._render();
     }
 
@@ -163,7 +153,7 @@ export class AdwDataGrid extends HTMLElement {
         this._scrollEl.appendChild(this._tableEl);
 
         // Seed from JSON attributes only when the properties were not set.
-        if (this._columns.length === 0) this._columns = this._parseJsonAttr('columns', normalizeColumns);
+        if (this._columns.length === 0) this._columns = this._parseJsonAttr('columns', normalizeDataGridColumns);
         if (this._rows.length === 0) this._rows = this._parseJsonAttr('rows', (v) => (Array.isArray(v) ? v : []));
 
         this.replaceChildren(this._captionEl, this._scrollEl);
@@ -173,7 +163,7 @@ export class AdwDataGrid extends HTMLElement {
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
         if (!this._initialized) return;
         if (name === 'columns') {
-            this._columns = this._parseJsonAttr('columns', normalizeColumns);
+            this._columns = this._parseJsonAttr('columns', normalizeDataGridColumns);
             this._render();
         } else if (name === 'rows') {
             this._rows = this._parseJsonAttr('rows', (v) => (Array.isArray(v) ? (v as AdwDataGridRow[]) : []));
@@ -204,28 +194,21 @@ export class AdwDataGrid extends HTMLElement {
         this._captionEl.hidden = caption.length === 0;
     }
 
-    /** The CSS `grid-template-columns` value derived from the column descriptors. */
+    /**
+     * The CSS `grid-template-columns` value derived from the column descriptors.
+     *
+     * The DERIVATION is core's (`dataGridTracks`), because NativeScript needs the
+     * same one for its `ItemSpec`s and can do nothing with a CSS string; the
+     * mapping onto CSS text — including the `minmax(0px, 1fr)` slack track whose
+     * `0px` must keep its unit to round-trip through the CSSOM — is
+     * `dataGridTrackTemplate`.
+     */
     private _trackTemplate(): string {
-        const anyExplicit = this._columns.some((c) => c.width !== undefined || c.flex !== undefined);
-        return this._columns
-            .map((column, index) => {
-                if (column.width !== undefined) return column.width;
-                if (column.flex !== undefined) return `${column.flex}fr`;
-                // With no explicit sizing anywhere, the first (label) column
-                // absorbs slack so trailing numeric columns hug the right edge.
-                // `0px` (not `0`) is the CSSOM-canonical form so it round-trips.
-                if (!anyExplicit && index === 0) return 'minmax(0px, 1fr)';
-                return 'auto';
-            })
-            .join(' ');
+        return dataGridTrackTemplate(dataGridTracks(this._columns));
     }
 
     private _columnClasses(column: AdwDataGridColumn): string {
-        const align: AdwDataGridAlign = column.align ?? (column.numeric ? 'end' : 'start');
-        const classes = ['adw-data-grid-cell', `align-${align}`];
-        if (column.numeric) classes.push('numeric');
-        if (column.monospace) classes.push('mono');
-        return classes.join(' ');
+        return dataGridColumnClasses(column).join(' ');
     }
 
     private _render(): void {
@@ -253,7 +236,7 @@ export class AdwDataGrid extends HTMLElement {
         const elementInteractive = this.hasAttribute('interactive');
 
         this._rows.forEach((rowData, index) => {
-            const variant = normalizeVariant(rowData.variant);
+            const variant = normalizeDataGridVariant(rowData.variant);
             const row = document.createElement('div');
             row.className = `adw-data-grid-row variant-${variant}`;
             row.setAttribute('role', 'row');
@@ -266,25 +249,21 @@ export class AdwDataGrid extends HTMLElement {
                 cell.className = 'adw-data-grid-cell align-start section-cell';
                 cell.setAttribute('role', 'cell');
                 cell.style.gridColumn = '1 / -1';
-                cell.textContent = cellText(rowData[firstKey]);
+                cell.textContent = dataGridCellText(rowData[firstKey]);
                 row.appendChild(cell);
             } else {
                 for (const column of this._columns) {
                     const cell = document.createElement('div');
                     cell.className = this._columnClasses(column);
                     cell.setAttribute('role', 'cell');
-                    cell.textContent = cellText(rowData[column.key]);
+                    cell.textContent = dataGridCellText(rowData[column.key]);
                     row.appendChild(cell);
                 }
             }
 
             // A row is clickable only when it is a plain data row AND either the
             // element opts everything in or the row opts itself in.
-            const rowInteractive =
-                variant === 'normal' &&
-                rowData.interactive !== false &&
-                (rowData.interactive === true || elementInteractive);
-            if (rowInteractive) {
+            if (dataGridRowInteractive(variant, rowData.interactive, elementInteractive)) {
                 row.classList.add('interactive');
                 row.tabIndex = 0;
                 row.addEventListener('click', () => this._activate(index, rowData));
@@ -305,31 +284,4 @@ export class AdwDataGrid extends HTMLElement {
     }
 }
 
-/** Coerce a cell value to display text — pre-formatted strings pass through. */
-function cellText(value: string | number | boolean | AdwDataGridRowVariant | undefined): string {
-    if (value === undefined || value === null) return '';
-    return String(value);
-}
-
-/** Clamp an arbitrary variant to the known set (unknown → 'normal'). */
-function normalizeVariant(variant: unknown): AdwDataGridRowVariant {
-    return typeof variant === 'string' && VARIANTS.has(variant) ? (variant as AdwDataGridRowVariant) : 'normal';
-}
-
-/** Normalise raw column descriptors to a stable list (drops malformed entries). */
-function normalizeColumns(raw: unknown): AdwDataGridColumn[] {
-    if (!Array.isArray(raw)) return [];
-    return raw
-        .filter((c): c is AdwDataGridColumn => typeof c === 'object' && c !== null && 'key' in c)
-        .map((c) => ({
-            key: String(c.key),
-            label: c.label !== undefined ? String(c.label) : undefined,
-            align: c.align,
-            width: c.width !== undefined ? String(c.width) : undefined,
-            flex: typeof c.flex === 'number' ? c.flex : undefined,
-            monospace: c.monospace === true,
-            numeric: c.numeric === true,
-        }));
-}
-
 customElements.define('adw-data-grid', AdwDataGrid);