@xmesh/system-design 0.0.3 → 0.0.5

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

@@ -56,9 +56,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 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;
+import primitivesSheets from "../primitives/index.styles.js";
+import dataTableSheets from "./index.styles.js";
 const DEFAULT_PAGE_SIZE = 10;
+/**
+ * @fires xm-data-table-page-change - Fired when the page changes (`detail.page`).
+ * @fires xm-data-table-sort-change - Fired when the sort changes (`detail.key`, `detail.direction`).
+ * @fires xm-data-table-row-click - Fired when a clickable row is activated (`detail.row`, `detail.index`).
+ */
 let XmDataTable = class XmDataTable extends LitElement {
     constructor() {
         super(...arguments);
@@ -68,6 +73,17 @@ let XmDataTable = class XmDataTable extends LitElement {
         this.pageSize = DEFAULT_PAGE_SIZE;
         this.emptyHeading = "No data";
         this.emptyText = "";
+        /** Server/controlled mode (AD-14): the consumer owns sort + paging. The table
+            renders `rows` verbatim, never sorts/slices a copy, derives the page count
+            from `total-items` (not `rows.length`), and emits intents only. */
+        this.server = false;
+        /** Total item count for server-mode paging (pages = ceil(total-items/page-size)). */
+        this.totalItems = 0;
+        /** Controlled sort indicator for server mode (`{ key, direction }`); reflected,
+            never reordered locally. */
+        this.sort = null;
+        /** Make rows clickable — emits xm-data-table-row-click (AD-15). */
+        this.rowClick = false;
         this._sortKey = null;
         this._sortDirection = "asc";
         this._currentPage = 1;
@@ -84,6 +100,9 @@ let XmDataTable = class XmDataTable extends LitElement {
             }));
         };
     }
+    // Adopted from the build-generated sheets (scripts/gen-styles.mjs) — no
+    // runtime URL fetch (ADR 0012). Cascade order preserved from the old <link>s.
+    static { this.styles = [...primitivesSheets, ...dataTableSheets]; }
     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
@@ -105,11 +124,18 @@ let XmDataTable = class XmDataTable extends LitElement {
                 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")) {
+        // Controlled sort (server mode, AD-14): reflect the `sort` prop as the
+        // indicator; the table never reorders locally.
+        if (this.server && changed.has("sort")) {
+            this._sortKey = this.sort?.key ?? null;
+            this._sortDirection = this.sort?.direction ?? "asc";
+        }
+        // Client mode only: re-clamp the active page when the dataset/page size
+        // shrinks so the slice is never out of bounds (e.g. after a filter swaps
+        // `rows`). In server mode the consumer owns paging — never clamp or emit a
+        // page-change the user didn't cause, and never derive paging from
+        // `rows.length` (AD-14).
+        if (!this.server && (changed.has("rows") || changed.has("pageSize"))) {
             const pages = this._pageCount();
             const clamped = Math.min(Math.max(this._currentPage, 1), pages);
             if (clamped !== this._currentPage) {
@@ -124,8 +150,6 @@ let XmDataTable = class XmDataTable extends LitElement {
     }
     render() {
         return html `
-      <link rel="stylesheet" href="${PRIMITIVES_CSS}" />
-      <link rel="stylesheet" href="${DATA_TABLE_CSS}" />
       <style>
         :host {
           display: block;
@@ -201,21 +225,37 @@ let XmDataTable = class XmDataTable extends LitElement {
     }
     _renderDataRows() {
         const slice = this._pagedRows();
-        return html `${slice.map((row) => html `
-        <tr class="data-table__row">
+        const clickable = this.rowClick;
+        return html `${slice.map((row, index) => {
+            const rowCls = `data-table__row${clickable ? " data-table__row--clickable" : ""}`;
+            return html `
+        <tr
+          class="${rowCls}"
+          tabindex=${clickable ? "0" : nothing}
+          @click=${clickable
+                ? (e) => this._onRowClick(e, row, index)
+                : nothing}
+          @keydown=${clickable
+                ? (e) => this._onRowKey(e, row, index)
+                : nothing}
+        >
           ${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>`;
-        })}
+                const numeric = this._isNumericCol(col);
+                const cls = [
+                    "data-table__cell",
+                    numeric && "data-table__cell--end",
+                    col.mono && "data-table__cell--mono",
+                    col.muted && "data-table__cell--muted",
+                ]
+                    .filter(Boolean)
+                    .join(" ");
+                // Formatter output is text (Lit auto-escapes) — never markup (ADR 0008).
+                const value = col.format ? col.format(row[col.key], row) : row[col.key] ?? "";
+                return html `<td class="${cls}">${value}</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;
@@ -273,7 +313,12 @@ let XmDataTable = class XmDataTable extends LitElement {
     }
     // ── State helpers ───────────────────────────────────────────────
     _isEmpty() {
-        return !this.loading && this.rows.length === 0;
+        if (this.loading)
+            return false;
+        // Server mode: "empty" means the consumer's total is 0 — never `rows.length`.
+        // A transient empty page (rows momentarily empty while a page loads, with
+        // total-items > 0) must NOT collapse to the empty state or hide the pager (AD-14).
+        return this.server ? this.totalItems === 0 : this.rows.length === 0;
     }
     _isNumericCol(col) {
         if (col.align === "end")
@@ -287,7 +332,10 @@ let XmDataTable = class XmDataTable extends LitElement {
         return Number.isFinite(n) && n > 0 ? n : DEFAULT_PAGE_SIZE;
     }
     _pageCount() {
-        return Math.max(1, Math.ceil(this.rows.length / this._effectivePageSize()));
+        // Server mode derives the page count from the consumer's total item count,
+        // never from the single rendered page in `rows` (AD-14).
+        const count = this.server ? this.totalItems : this.rows.length;
+        return Math.max(1, Math.ceil(count / this._effectivePageSize()));
     }
     // Sort the FULL dataset (non-destructive copy), THEN slice the active page.
     _sortedRows() {
@@ -304,6 +352,10 @@ let XmDataTable = class XmDataTable extends LitElement {
         return [...this.rows].sort((a, b) => this._compare(valueOf(a), valueOf(b)) * dir);
     }
     _pagedRows() {
+        // Server mode: render the consumer-supplied page verbatim — no client
+        // sort, no client slice (AD-14, counters SM-C2).
+        if (this.server)
+            return this.rows;
         const size = this._effectivePageSize();
         const start = (this._currentPage - 1) * size;
         return this._sortedRows().slice(start, start + size);
@@ -333,23 +385,45 @@ let XmDataTable = class XmDataTable extends LitElement {
     _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 nextDirection = this._sortKey === col.key && this._sortDirection === "asc" ? "desc" : "asc";
+        const detail = { key: col.key, direction: nextDirection };
+        // Client mode applies the sort locally (uncontrolled). Server mode emits
+        // only — the consumer drives the `sort` prop, which reflects back as the
+        // indicator (AD-14); the table never reorders locally.
+        if (!this.server) {
+            this._sortKey = detail.key;
+            this._sortDirection = detail.direction;
         }
-        const detail = {
-            key: this._sortKey,
-            direction: this._sortDirection,
-        };
         this.dispatchEvent(new CustomEvent("xm-data-table-sort-change", {
             detail,
             bubbles: true,
             composed: true,
         }));
     }
+    _onRowClick(e, row, index) {
+        // Don't fire when the activation originates on an interactive descendant (AD-15).
+        const interactive = e.composedPath().some((t) => t instanceof Element &&
+            t !== e.currentTarget &&
+            t.matches?.('a[href],button,input,select,textarea,' +
+                '[role="button"],[role="link"],[role="checkbox"],[role="switch"],[role="menuitem"],[role="tab"],' +
+                '[tabindex]:not([tabindex="-1"])'));
+        if (interactive)
+            return;
+        this._emitRowClick(row, index);
+    }
+    _onRowKey(e, row, index) {
+        if (e.key === "Enter" || e.key === " " || e.key === "Spacebar") {
+            e.preventDefault();
+            this._emitRowClick(row, index);
+        }
+    }
+    _emitRowClick(row, index) {
+        this.dispatchEvent(new CustomEvent("xm-data-table-row-click", {
+            detail: { row, index },
+            bubbles: true,
+            composed: true,
+        }));
+    }
     _onHeaderKey(e, col) {
         if (e.key === "Enter" || e.key === " " || e.key === "Spacebar") {
             e.preventDefault();
@@ -375,6 +449,18 @@ __decorate([
 __decorate([
     property({ type: String, attribute: "empty-text" })
 ], XmDataTable.prototype, "emptyText", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmDataTable.prototype, "server", void 0);
+__decorate([
+    property({ type: Number, attribute: "total-items" })
+], XmDataTable.prototype, "totalItems", void 0);
+__decorate([
+    property({ attribute: false })
+], XmDataTable.prototype, "sort", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "row-click" })
+], XmDataTable.prototype, "rowClick", void 0);
 __decorate([
     state()
 ], XmDataTable.prototype, "_sortKey", void 0);

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

@@ -0,0 +1,198 @@
+// GENERATED by scripts/gen-styles.mjs — do not edit. Source: lit/components/data-table/index.css
+// SSR-safe: constructable stylesheets need the DOM, so in a non-DOM context
+// (Node/SSR import) this exports [] instead of throwing. The CSS self-declares
+// the @layer order so the override contract holds even without ./base (AD-2).
+let sheets = [];
+if (typeof CSSStyleSheet !== "undefined") {
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(`@layer reset, base, tokens, components, utilities;
+@layer components {
+/* ============================================
+   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);
+}
+
+/* Monospace/tabular cells (per-column \`mono\`) — IDs, hashes, code-like values. */
+.data-table__cell--mono {
+  font-family: var(--xm-typescale-mono-font);
+  font-size: var(--xm-typescale-mono-size);
+  font-weight: var(--xm-typescale-mono-weight);
+  line-height: var(--xm-typescale-mono-line-height);
+  font-variant-numeric: tabular-nums;
+}
+
+/* Clickable rows (row-click, AD-15) — keyboard-focusable; pointer + focus ring. */
+.data-table__row--clickable {
+  cursor: pointer;
+}
+.data-table__row--clickable:focus-visible {
+  outline: none;
+  box-shadow: var(--xm-state-focus-ring);
+}
+
+/* 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);
+}
+
+}`);
+  sheets = [sheet];
+}
+export default sheets;

package/dist/lit/components/date-range/index.d.ts

@@ -4,7 +4,11 @@ export interface DateRangeChangeDetail {
     from: string | null;
     to: string | null;
 }
+/**
+ * @fires xm-date-range-change - Fired when the selected date range changes.
+ */
 export declare class XmDateRange extends LitElement {
+    static styles: CSSStyleSheet[];
     from: string | null;
     to: string | null;
     placeholder: string;

package/dist/lit/components/date-range/index.js

@@ -53,7 +53,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { LitElement, html, svg, nothing } from "lit";
 import { customElement, property, state, query } from "lit/decorators.js";
-const DR_CSS = new URL("../date-range/index.css", import.meta.url).href;
+import dateRangeSheets from "./index.styles.js";
 let drSeq = 0;
 const PRESETS = [
     { id: "today", label: "Today" },
@@ -146,6 +146,9 @@ const SHORT_FMT = new Intl.DateTimeFormat(undefined, {
     day: "numeric",
     year: "numeric",
 });
+/**
+ * @fires xm-date-range-change - Fired when the selected date range changes.
+ */
 let XmDateRange = class XmDateRange extends LitElement {
     constructor() {
         super(...arguments);
@@ -179,6 +182,9 @@ let XmDateRange = class XmDateRange extends LitElement {
             }
         };
     }
+    // Adopted from the build-generated sheets (scripts/gen-styles.mjs) — no
+    // runtime URL fetch (ADR 0012). Cascade order preserved from the old <link>s.
+    static { this.styles = [...dateRangeSheets]; }
     connectedCallback() {
         super.connectedCallback();
         document.addEventListener("pointerdown", this._onDocPointer, true);
@@ -430,7 +436,6 @@ let XmDateRange = class XmDateRange extends LitElement {
         const labelId = `${this._id}-title`;
         const triggerCls = `date-range__trigger${this.open ? " date-range__trigger--open" : ""}`;
         return html `
-      <link rel="stylesheet" href="${DR_CSS}" />
       <style>
         :host { display: inline-block; }
         :host([hidden]) { display: none; }