@xmesh/system-design 0.0.1

package/dist/lit/components/data-table/index.css

@@ -0,0 +1,166 @@
+/* ============================================
+   Data table — the interactive sibling of <xm-table>.
+
+   Mirrors xm-table's static chrome (1px --md-sys-color-outline-variant
+   hairlines, sentence-case headers, numeric right-align + tabular figures,
+   number + unit carry a space "412 KB"), then layers in sort, paging, loading,
+   and empty states.
+
+   It sits on ONE surface family — surface* with ink --md-sys-color-on-surface
+   (AD-13). Region differentiation is the hairline rule + an optional
+   surface-container raise on the header, never a status hue (AD-11). No
+   --md-sys-color-error* anywhere; the single coral accent
+   (--md-sys-color-primary) marks the active sort.
+
+   BEM block: `data-table`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   Elements: __head, __row, __cell, __header-cell, __header-label, __sort,
+   __sort-icon, __footer, __pagination, __empty. Modifiers: __cell--end,
+   __cell--muted, __header-cell--end / --sortable / --active,
+   __row--skeleton / --empty.
+   ============================================ */
+
+.data-table {
+  width: 100%;
+  border-collapse: collapse;
+  background: transparent;
+  color: var(--md-sys-color-on-surface);
+  font-family: var(--md-sys-typescale-body-medium-font);
+  font-size: var(--md-sys-typescale-body-medium-size);
+  line-height: var(--md-sys-typescale-body-medium-line-height);
+  border: 1px solid var(--md-sys-color-outline-variant);
+  border-radius: var(--md-sys-shape-corner-medium);
+  overflow: hidden;
+}
+
+.data-table__head {
+  background: var(--md-sys-color-surface-container-low);
+}
+
+.data-table__header-cell {
+  text-align: start;
+  padding: 0;
+  border-bottom: 1px solid var(--md-sys-color-outline-variant);
+  color: var(--md-sys-color-on-surface);
+  font-family: var(--md-sys-typescale-label-large-font);
+  font-size: var(--md-sys-typescale-label-medium-size);
+  font-weight: 600;
+  letter-spacing: 0;
+  white-space: nowrap;
+}
+
+.data-table__header-label {
+  display: inline-block;
+}
+
+/* The static label sits with the same padding the sortable hit-area carries,
+   so sortable and inert headers align on a shared baseline. */
+.data-table__header-cell > .data-table__header-label {
+  padding: var(--s-3) var(--s-4);
+}
+
+/* Sortable header: a focusable in-cell control that fills the cell so the whole
+   header is the hit target. Hover/active swap real tokens — no filter/opacity. */
+.data-table__sort {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  box-sizing: border-box;
+  width: 100%;
+  padding: var(--s-3) var(--s-4);
+  cursor: pointer;
+  user-select: none;
+  color: inherit;
+  border-radius: var(--md-sys-shape-corner-small);
+  outline: none;
+}
+
+.data-table__header-cell--sortable .data-table__sort:hover {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity),
+    transparent
+  );
+}
+
+.data-table__header-cell--sortable .data-table__sort:active {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-on-surface) var(--md-sys-state-pressed-state-layer-opacity),
+    transparent
+  );
+}
+
+.data-table__header-cell--sortable .data-table__sort:focus-visible {
+  box-shadow: var(--xm-state-focus-ring);
+}
+
+/* The active sorted column reads in the coral accent — the only emphasis (AD-11). */
+.data-table__header-cell--active {
+  color: var(--md-sys-color-primary);
+}
+
+.data-table__sort-icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--md-sys-color-primary);
+}
+
+/* End-aligned (numeric) headers push their content to the trailing edge. */
+.data-table__header-cell--end .data-table__sort,
+.data-table__header-cell--end > .data-table__header-label {
+  justify-content: flex-end;
+  text-align: end;
+}
+
+.data-table__row + .data-table__row .data-table__cell {
+  border-top: 1px solid var(--md-sys-color-outline-variant);
+}
+
+.data-table__cell {
+  padding: var(--s-3) var(--s-4);
+  text-align: start;
+  vertical-align: middle;
+  color: var(--md-sys-color-on-surface);
+}
+
+.data-table__cell--muted {
+  color: var(--md-sys-color-on-surface-variant);
+}
+
+/* Numeric — right-aligned, tabular figures so digits line up; the unit carries
+   a space in the value ("412 KB"). Matches xm-table (NFR-22 / UX-DR4). */
+.data-table__header-cell--end,
+.data-table__cell--end {
+  text-align: end;
+  font-variant-numeric: tabular-nums;
+  font-feature-settings: "tnum" 1;
+}
+
+.data-table__row:not(.data-table__row--skeleton):not(.data-table__row--empty):hover
+  .data-table__cell {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity),
+    transparent
+  );
+}
+
+/* Loading rows host composed <xm-skeleton> lines on the same column grid; the
+   skeleton owns the gradient-free pulse (AD-12). No row hover under load. */
+.data-table__row--skeleton .data-table__cell {
+  padding-block: calc(var(--s-3) + 1px);
+}
+
+/* Empty: a single spanning cell hosting the composed <xm-empty-state>; never a
+   blank box (FR-161). The empty-state inherits the host on-* ink (AD-13). */
+.data-table__empty {
+  padding: var(--s-8) var(--s-4);
+  text-align: center;
+}
+
+/* Footer carries the composed <xm-pagination>, right-aligned under the grid. */
+.data-table__footer {
+  display: flex;
+  justify-content: flex-end;
+  padding-top: var(--s-3);
+}

package/dist/lit/components/data-table/index.d.ts

@@ -0,0 +1,55 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+import type { TableColumn, TableRow } from "../table/index.js";
+export interface DataTableColumn extends TableColumn {
+    sortable?: boolean;
+    /** Raw value to sort this column by, when the displayed cell is a formatted
+        string the table can't compare correctly on its own (e.g. "412 KB" must
+        sort as 421888, "2 min ago" as a timestamp). Returns the primitive used
+        for comparison; the displayed cell (`row[key]`) is unchanged. Without it,
+        number cells sort by magnitude and string cells sort lexically. */
+    sortValue?: (row: TableRow) => string | number | null | undefined;
+}
+export type { TableRow };
+export type SortDirection = "asc" | "desc";
+export interface DataTableSortChangeDetail {
+    key: string;
+    direction: SortDirection;
+}
+export interface DataTablePageChangeDetail {
+    page: number;
+}
+export declare class XmDataTable extends LitElement {
+    columns: DataTableColumn[];
+    rows: TableRow[];
+    loading: boolean;
+    pageSize: number;
+    emptyHeading: string;
+    emptyText: string;
+    private _sortKey;
+    private _sortDirection;
+    private _currentPage;
+    willUpdate(changed: Map<string, unknown>): void;
+    render(): TemplateResult;
+    private _renderTable;
+    private _renderHeaderCell;
+    private _renderDataRows;
+    private _renderSkeletonRows;
+    private _renderEmptyRow;
+    private _renderFooter;
+    private _isEmpty;
+    private _isNumericCol;
+    private _effectivePageSize;
+    private _pageCount;
+    private _sortedRows;
+    private _pagedRows;
+    private _compare;
+    private _toggleSort;
+    private _onHeaderKey;
+    private _onPageChange;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-data-table": XmDataTable;
+    }
+}

package/dist/lit/components/data-table/index.js

@@ -0,0 +1,390 @@
+/*
+  data-table/index.ts — <xm-data-table>, the interactive sibling of <xm-table>.
+
+  <xm-table> (Story 5.5) is the dumb, static, hairline-ruled grid. <xm-data-table>
+  is the interactive layer that wraps the SAME column/row model with:
+
+    • header-click + keyboard sort (Story 6.1)
+    • client-side paging via composed <xm-pagination> (Story 6.2)
+    • a loading state of composed <xm-skeleton> rows (Story 6.2)
+    • an empty state of a composed <xm-empty-state> (Story 6.2)
+
+  It consumes the EXACT TableColumn / TableRow shapes that <xm-table> exports, so a
+  data-table and a static table read as one system. The cell rendering mirrors
+  xm-table's numeric discipline (right-align + tabular figures, unit carries a
+  space "412 KB") rather than fighting it.
+
+  Authoring:
+    const dt = document.querySelector("xm-data-table");
+    dt.columns = [
+      { key: "name", label: "File name" },
+      { key: "size", label: "Size", numeric: true },   // or align: "end"
+      { key: "calls", label: "Calls", numeric: true, sortable: true },
+    ];
+    dt.rows = [ { name: "schema.json", size: "412 KB", calls: 412 }, … ];
+    dt.addEventListener("xm-data-table-sort-change", (e) => e.detail);  // {key, direction}
+    dt.addEventListener("xm-data-table-page-change", (e) => e.detail);  // {page}
+
+  Properties:
+    columns    DataTableColumn[]  — { key, label, sortable?, align?, numeric?, muted? }
+    rows       TableRow[]         — plain objects keyed by column key
+    loading    boolean            — render skeleton rows (overrides empty + data)
+    page-size  number             — rows per page (default 10)
+    empty-heading / empty-text    — copy for the composed empty-state
+
+  Events (both bubbles + composed; AD-8 / AD-8a typed payloads):
+    xm-data-table-sort-change  detail = { key: string, direction: 'asc' | 'desc' }
+    xm-data-table-page-change  detail = { page: number }
+
+  Server-mode boundary (FR-162, DEFERRED): v1 sorts and pages a COPY of the
+  in-memory `rows` array, smooth up to the ~500-row client ceiling (NFR-18). The
+  props-in / events-out API is deliberately uncontrolled-first so a future server
+  mode can take over: a consumer reacting to sort-change / page-change and swapping
+  `rows` drives server ordering/paging WITHOUT an API break. Virtualization is also
+  deferred — no virtual-list dependency here.
+
+  Composition (AD-12): the sort indicator is a `primitives` icon; paging, loading,
+  and empty chrome are nested <xm-pagination> / <xm-skeleton> / <xm-empty-state>
+  elements. This component never re-implements their markup and never reaches into
+  their shadow roots. Shadow DOM; Lit from lit.
+*/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { LitElement, html, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+const DATA_TABLE_CSS = new URL("../data-table/index.css", import.meta.url).href;
+const PRIMITIVES_CSS = new URL("../primitives/index.css", import.meta.url).href;
+const DEFAULT_PAGE_SIZE = 10;
+let XmDataTable = class XmDataTable extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.columns = [];
+        this.rows = [];
+        this.loading = false;
+        this.pageSize = DEFAULT_PAGE_SIZE;
+        this.emptyHeading = "No data";
+        this.emptyText = "";
+        this._sortKey = null;
+        this._sortDirection = "asc";
+        this._currentPage = 1;
+        this._onPageChange = (e) => {
+            const detail = e.detail;
+            const page = detail?.page ?? 1;
+            if (page === this._currentPage)
+                return;
+            this._currentPage = page;
+            this.dispatchEvent(new CustomEvent("xm-data-table-page-change", {
+                detail: { page },
+                bubbles: true,
+                composed: true,
+            }));
+        };
+    }
+    willUpdate(changed) {
+        // Allow declarative JSON in attributes for static HTML authoring (mirrors
+        // xm-table); the @property is attribute:false, so set .columns/.rows as a
+        // string and we parse it here. A malformed string must not throw out of the
+        // reactive update and break render — keep the prior value on a parse error.
+        if (changed.has("columns") && typeof this.columns === "string") {
+            try {
+                this.columns = JSON.parse(this.columns);
+            }
+            catch {
+                this.columns = changed.get("columns") ?? [];
+            }
+        }
+        if (changed.has("rows") && typeof this.rows === "string") {
+            try {
+                this.rows = JSON.parse(this.rows);
+            }
+            catch {
+                this.rows = changed.get("rows") ?? [];
+            }
+        }
+        // Re-clamp the active page whenever the dataset or page size shrinks so the
+        // current slice is never out of bounds (e.g. after a filter swaps `rows`).
+        // The clamp moves the page silently from the consumer's view, so emit a
+        // page-change so a server-mode consumer can reconcile (uncontrolled-out).
+        if (changed.has("rows") || changed.has("pageSize")) {
+            const pages = this._pageCount();
+            const clamped = Math.min(Math.max(this._currentPage, 1), pages);
+            if (clamped !== this._currentPage) {
+                this._currentPage = clamped;
+                this.dispatchEvent(new CustomEvent("xm-data-table-page-change", {
+                    detail: { page: clamped },
+                    bubbles: true,
+                    composed: true,
+                }));
+            }
+        }
+    }
+    render() {
+        return html `
+      <link rel="stylesheet" href="${PRIMITIVES_CSS}" />
+      <link rel="stylesheet" href="${DATA_TABLE_CSS}" />
+      <style>
+        :host {
+          display: block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      ${this._renderTable()} ${this._renderFooter()}
+    `;
+    }
+    // ── Body-state resolver (FR-161): loading wins, else empty, else paged data.
+    _renderTable() {
+        return html `
+      <table class="data-table" aria-busy=${this.loading ? "true" : nothing}>
+        <thead class="data-table__head">
+          <tr class="data-table__row">
+            ${this.columns.map((col) => this._renderHeaderCell(col))}
+          </tr>
+        </thead>
+        <tbody>
+          ${this.loading
+            ? this._renderSkeletonRows()
+            : this._isEmpty()
+                ? this._renderEmptyRow()
+                : this._renderDataRows()}
+        </tbody>
+      </table>
+    `;
+    }
+    _renderHeaderCell(col) {
+        const numeric = this._isNumericCol(col);
+        const sortable = Boolean(col.sortable) && !this.loading;
+        const active = this._sortKey === col.key;
+        const cls = [
+            "data-table__header-cell",
+            numeric && "data-table__header-cell--end",
+            sortable && "data-table__header-cell--sortable",
+            sortable && active && "data-table__header-cell--active",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const ariaSort = !active
+            ? "none"
+            : this._sortDirection === "asc"
+                ? "ascending"
+                : "descending";
+        if (!sortable) {
+            // No aria-sort on a non-sortable header — aria-sort="none" would tell AT
+            // the column IS sortable but currently unsorted, which is misleading.
+            return html `<th class="${cls}" scope="col">
+        <span class="data-table__header-label">${col.label}</span>
+      </th>`;
+        }
+        return html `<th class="${cls}" scope="col" aria-sort=${ariaSort}>
+      <span
+        class="data-table__sort"
+        role="button"
+        tabindex="0"
+        @click=${() => this._toggleSort(col)}
+        @keydown=${(e) => this._onHeaderKey(e, col)}
+      >
+        <span class="data-table__header-label">${col.label}</span>
+        ${active
+            ? html `<span class="data-table__sort-icon" aria-hidden="true">
+              ${this._sortDirection === "asc"
+                ? html `<xm-sort-asc-icon size="14"></xm-sort-asc-icon>`
+                : html `<xm-sort-desc-icon size="14"></xm-sort-desc-icon>`}
+            </span>`
+            : nothing}
+      </span>
+    </th>`;
+    }
+    _renderDataRows() {
+        const slice = this._pagedRows();
+        return html `${slice.map((row) => html `
+        <tr class="data-table__row">
+          ${this.columns.map((col) => {
+            const numeric = this._isNumericCol(col);
+            const cls = [
+                "data-table__cell",
+                numeric && "data-table__cell--end",
+                col.muted && "data-table__cell--muted",
+            ]
+                .filter(Boolean)
+                .join(" ");
+            return html `<td class="${cls}">${row[col.key] ?? ""}</td>`;
+        })}
+        </tr>
+      `)}`;
+    }
+    // Loading: one skeleton row per page-size, each cell a composed <xm-skeleton>
+    // line laid on the same column grid. The skeleton owns its gradient-free pulse;
+    // the data-table only places the elements (AD-12).
+    _renderSkeletonRows() {
+        const rowCount = Math.max(1, Math.min(this._effectivePageSize(), 8));
+        const cols = this.columns.length || 1;
+        const rows = Array.from({ length: rowCount }, () => 0);
+        return html `${rows.map(() => html `
+        <tr class="data-table__row data-table__row--skeleton">
+          ${Array.from({ length: cols }, () => 0).map(() => html `<td class="data-table__cell">
+              <xm-skeleton variant="line" width="72%"></xm-skeleton>
+            </td>`)}
+        </tr>
+      `)}`;
+    }
+    // Empty: a single full-width cell hosting the composed <xm-empty-state>. Never
+    // a blank box (FR-161). Consumers can override copy/action via the `empty` /
+    // `empty-action` slots without forking the component.
+    _renderEmptyRow() {
+        const span = this.columns.length || 1;
+        return html `
+      <tr class="data-table__row data-table__row--empty">
+        <td class="data-table__cell data-table__empty" colspan=${span}>
+          <slot name="empty">
+            <xm-empty-state heading=${this.emptyHeading} icon="xm-search-icon">
+              ${this.emptyText
+            ? html `${this.emptyText}`
+            : nothing}
+              <slot name="empty-action" slot="action"></slot>
+            </xm-empty-state>
+          </slot>
+        </td>
+      </tr>
+    `;
+    }
+    // Compose <xm-pagination> when there is more than one page (and not loading /
+    // empty). Re-surface its inner event as the table's own xm-data-table-page-change.
+    _renderFooter() {
+        if (this.loading || this._isEmpty())
+            return nothing;
+        const pages = this._pageCount();
+        if (pages <= 1)
+            return nothing;
+        return html `
+      <div class="data-table__footer">
+        <xm-pagination
+          class="data-table__pagination"
+          page=${this._currentPage}
+          total=${pages}
+          @xm-pagination-page-change=${this._onPageChange}
+        ></xm-pagination>
+      </div>
+    `;
+    }
+    // ── State helpers ───────────────────────────────────────────────
+    _isEmpty() {
+        return !this.loading && this.rows.length === 0;
+    }
+    _isNumericCol(col) {
+        if (col.align === "end")
+            return true;
+        if (col.align === "start")
+            return false;
+        return Boolean(col.numeric);
+    }
+    _effectivePageSize() {
+        const n = Math.floor(this.pageSize);
+        return Number.isFinite(n) && n > 0 ? n : DEFAULT_PAGE_SIZE;
+    }
+    _pageCount() {
+        return Math.max(1, Math.ceil(this.rows.length / this._effectivePageSize()));
+    }
+    // Sort the FULL dataset (non-destructive copy), THEN slice the active page.
+    _sortedRows() {
+        if (this._sortKey === null)
+            return this.rows;
+        const key = this._sortKey;
+        const col = this.columns.find((c) => c.key === key);
+        const dir = this._sortDirection === "asc" ? 1 : -1;
+        // Use the column's sortValue accessor when provided (the only correct way to
+        // sort a formatted string like "412 KB"); otherwise compare the raw cell.
+        const valueOf = col?.sortValue
+            ? (row) => col.sortValue(row)
+            : (row) => row[key];
+        return [...this.rows].sort((a, b) => this._compare(valueOf(a), valueOf(b)) * dir);
+    }
+    _pagedRows() {
+        const size = this._effectivePageSize();
+        const start = (this._currentPage - 1) * size;
+        return this._sortedRows().slice(start, start + size);
+    }
+    // Comparison: real numbers compare by magnitude; everything else compares as
+    // text with locale-numeric collation (so "item 2" < "item 10"). A formatted
+    // string like "412 KB" is NOT reverse-engineered into a number — that is the
+    // column's `sortValue` accessor's job (a unit-blind parse mis-orders "88 MB"
+    // vs "412 KB"). Nullish/empty values sort to the end of an ascending order.
+    _compare(a, b) {
+        const aNil = a === null || a === undefined || a === "";
+        const bNil = b === null || b === undefined || b === "";
+        if (aNil && bNil)
+            return 0;
+        if (aNil)
+            return 1;
+        if (bNil)
+            return -1;
+        if (typeof a === "number" && typeof b === "number")
+            return a - b;
+        return String(a).localeCompare(String(b), undefined, {
+            numeric: true,
+            sensitivity: "base",
+        });
+    }
+    // ── Interaction ─────────────────────────────────────────────────
+    _toggleSort(col) {
+        if (!col.sortable)
+            return;
+        if (this._sortKey === col.key) {
+            this._sortDirection = this._sortDirection === "asc" ? "desc" : "asc";
+        }
+        else {
+            this._sortKey = col.key;
+            this._sortDirection = "asc";
+        }
+        const detail = {
+            key: this._sortKey,
+            direction: this._sortDirection,
+        };
+        this.dispatchEvent(new CustomEvent("xm-data-table-sort-change", {
+            detail,
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    _onHeaderKey(e, col) {
+        if (e.key === "Enter" || e.key === " " || e.key === "Spacebar") {
+            e.preventDefault();
+            this._toggleSort(col);
+        }
+    }
+};
+__decorate([
+    property({ attribute: false })
+], XmDataTable.prototype, "columns", void 0);
+__decorate([
+    property({ attribute: false })
+], XmDataTable.prototype, "rows", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmDataTable.prototype, "loading", void 0);
+__decorate([
+    property({ type: Number, attribute: "page-size" })
+], XmDataTable.prototype, "pageSize", void 0);
+__decorate([
+    property({ type: String, attribute: "empty-heading" })
+], XmDataTable.prototype, "emptyHeading", void 0);
+__decorate([
+    property({ type: String, attribute: "empty-text" })
+], XmDataTable.prototype, "emptyText", void 0);
+__decorate([
+    state()
+], XmDataTable.prototype, "_sortKey", void 0);
+__decorate([
+    state()
+], XmDataTable.prototype, "_sortDirection", void 0);
+__decorate([
+    state()
+], XmDataTable.prototype, "_currentPage", void 0);
+XmDataTable = __decorate([
+    customElement("xm-data-table")
+], XmDataTable);
+export { XmDataTable };