@xmesh/system-design 0.0.1

package/dist/lit/components/tabs/index.js

@@ -0,0 +1,320 @@
+/*
+  tabs/index.ts — <xm-tabs> / <xm-tab> / <xm-tab-panel>.
+
+  A tab strip that switches panels. Three elements registered in one file
+  (the multi-element carve-out, xm-<name>-<part> naming):
+
+    <xm-tabs value="overview">
+      <xm-tab value="overview">Overview</xm-tab>
+      <xm-tab value="activity">Activity</xm-tab>
+      <xm-tab value="settings" disabled>Settings</xm-tab>
+
+      <xm-tab-panel value="overview">…</xm-tab-panel>
+      <xm-tab-panel value="activity">…</xm-tab-panel>
+      <xm-tab-panel value="settings">…</xm-tab-panel>
+    </xm-tabs>
+
+  xm-tabs   the tablist container + sliding coral indicator + panel host.
+            Owns the active value (uncontrolled-first), roving tabindex, the
+            WAI-ARIA horizontal tablist keymap, and the change event.
+  xm-tab    a single tab. Light DOM so the HOST carries role="tab" /
+            aria-selected / aria-controls / roving tabindex and is the focus
+            target.  Properties: value (String), disabled (Boolean).
+  xm-tab-panel  a single panel. Light DOM so the HOST carries role="tabpanel"
+            / aria-labelledby and is hidden when inactive. Property: value.
+
+  Keyboard (WAI-ARIA tablist, horizontal): ←/→ move active tab, Home/End jump
+  to first/last enabled tab, Enter/Space activate. Roving tabindex: only the
+  active tab is tabindex=0.
+
+  Event: change — { detail: { value }, bubbles, composed }; detail.value is the
+  activated tab's PRIMITIVE value (string), never the element.
+
+  Surface / ink (AD-13): a transparent strip tracing its host surface. On the
+  desk family active ink = on-surface, inactive = on-surface-variant; the coral
+  indicator is --md-sys-color-primary; hairline 1px baseline rule. Indicator
+  slide is short3 standard easing.
+
+  Shadow DOM (xm-tabs) / light DOM (xm-tab, xm-tab-panel); Lit from
+  lit; sibling CSS via the built-file-relative new URL(...).
+  BEM root block `tabs`.
+*/
+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 } from "lit";
+import { customElement, property, query } from "lit/decorators.js";
+// Resolve CSS relative to the *built* file:
+// lit/build/components/tabs/index.js → ../tabs/index.css.
+const TABS_CSS = new URL("../tabs/index.css", import.meta.url).href;
+let tabsSeq = 0;
+/* ─────────────────────────────────────────────────────────────
+   <xm-tab> — one tab. Light DOM: the host is the role="tab" target.
+   ─────────────────────────────────────────────────────────────*/
+let XmTab = class XmTab extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.value = "";
+        this.disabled = false;
+    }
+    createRenderRoot() {
+        return this;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (!this.hasAttribute("role"))
+            this.setAttribute("role", "tab");
+        // Route into <xm-tabs>'s named "tab" slot so panels (default slot) and
+        // tabs are projected into separate regions.
+        if (this.getAttribute("slot") !== "tab")
+            this.setAttribute("slot", "tab");
+    }
+    render() {
+        return html `<span class="tabs__label"><slot></slot></span>`;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmTab.prototype, "value", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmTab.prototype, "disabled", void 0);
+XmTab = __decorate([
+    customElement("xm-tab")
+], XmTab);
+/* ─────────────────────────────────────────────────────────────
+   <xm-tab-panel> — one panel. Light DOM: the host is role="tabpanel".
+   ─────────────────────────────────────────────────────────────*/
+let XmTabPanel = class XmTabPanel extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.value = "";
+    }
+    createRenderRoot() {
+        return this;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (!this.hasAttribute("role"))
+            this.setAttribute("role", "tabpanel");
+    }
+    render() {
+        return html `<slot></slot>`;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmTabPanel.prototype, "value", void 0);
+XmTabPanel = __decorate([
+    customElement("xm-tab-panel")
+], XmTabPanel);
+/* ─────────────────────────────────────────────────────────────
+   <xm-tabs> — the tablist container.
+   ─────────────────────────────────────────────────────────────*/
+let XmTabs = class XmTabs extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.value = "";
+        this.size = "md";
+        this._id = `xm-tabs-${++tabsSeq}`;
+        this._activeValue = "";
+        this._onResize = () => {
+            this._positionIndicator();
+        };
+        // Wire IDs / ARIA / roving tabindex / panel visibility, then place the
+        // coral indicator under the active tab.
+        this._sync = () => {
+            const tabs = this._tabs;
+            const panels = this._panels;
+            if (tabs.length === 0)
+                return;
+            const enabled = this._enabledTabs();
+            if (!this._activeValue ||
+                !enabled.some((t) => t.value === this._activeValue)) {
+                const first = enabled[0] ?? tabs[0];
+                this._activeValue = first ? first.value : "";
+            }
+            tabs.forEach((tab, i) => {
+                const active = tab.value === this._activeValue;
+                const tabId = `${this._id}-tab-${i}`;
+                const panelId = `${this._id}-panel-${i}`;
+                tab.id ||= tabId;
+                tab.classList.add("tabs__tab");
+                tab.classList.toggle("tabs__tab--active", active);
+                tab.classList.toggle("tabs__tab--disabled", tab.disabled);
+                tab.setAttribute("aria-selected", active ? "true" : "false");
+                tab.setAttribute("tabindex", active ? "0" : "-1");
+                if (tab.disabled)
+                    tab.setAttribute("aria-disabled", "true");
+                else
+                    tab.removeAttribute("aria-disabled");
+                const panel = panels.find((p) => p.value === tab.value);
+                if (panel) {
+                    panel.id ||= panelId;
+                    panel.classList.add("tabs__panel");
+                    tab.setAttribute("aria-controls", panel.id);
+                    panel.setAttribute("aria-labelledby", tab.id);
+                    panel.toggleAttribute("hidden", !active);
+                }
+            });
+            this._positionIndicator();
+        };
+        this._onClick = (event) => {
+            const path = event.composedPath();
+            const tab = path.find((n) => n instanceof HTMLElement && n.tagName === "XM-TAB");
+            if (tab && !tab.disabled)
+                this._activate(tab.value, false);
+        };
+        // WAI-ARIA horizontal tablist keymap on the roving-focus tablist.
+        this._onKeydown = (event) => {
+            const enabled = this._enabledTabs();
+            if (enabled.length === 0)
+                return;
+            const currentIndex = enabled.findIndex((t) => t.value === this._activeValue);
+            let nextIndex = currentIndex;
+            switch (event.key) {
+                case "ArrowRight":
+                    nextIndex = (currentIndex + 1) % enabled.length;
+                    break;
+                case "ArrowLeft":
+                    nextIndex = (currentIndex - 1 + enabled.length) % enabled.length;
+                    break;
+                case "Home":
+                    nextIndex = 0;
+                    break;
+                case "End":
+                    nextIndex = enabled.length - 1;
+                    break;
+                case "Enter":
+                case " ": {
+                    const path = event.composedPath();
+                    const tab = path.find((n) => n instanceof HTMLElement && n.tagName === "XM-TAB");
+                    if (tab && !tab.disabled) {
+                        event.preventDefault();
+                        this._activate(tab.value);
+                    }
+                    return;
+                }
+                default:
+                    return;
+            }
+            event.preventDefault();
+            const next = enabled[nextIndex];
+            if (next)
+                this._activate(next.value);
+        };
+    }
+    render() {
+        const size = ["xs", "sm", "md", "lg"].includes(this.size)
+            ? this.size
+            : "md";
+        return html `
+      <link rel="stylesheet" href="${TABS_CSS}" />
+      <style>
+        :host {
+          display: block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div class="tabs tabs--${size}">
+        <div
+          class="tabs__list"
+          role="tablist"
+          aria-orientation="horizontal"
+          @slotchange=${this._sync}
+          @keydown=${this._onKeydown}
+          @click=${this._onClick}
+        >
+          <slot name="tab" @slotchange=${this._sync}></slot>
+          <span class="tabs__indicator" aria-hidden="true"></span>
+        </div>
+        <div class="tabs__panels">
+          <slot @slotchange=${this._sync}></slot>
+        </div>
+      </div>
+    `;
+    }
+    firstUpdated() {
+        this._activeValue = this.value;
+        this._sync();
+    }
+    updated(changed) {
+        if (changed.has("value") && this.value !== this._activeValue) {
+            this._activeValue = this.value;
+            this._sync();
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        window.addEventListener("resize", this._onResize);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        window.removeEventListener("resize", this._onResize);
+    }
+    get _tabs() {
+        return Array.from(this.querySelectorAll("xm-tab"));
+    }
+    get _panels() {
+        return Array.from(this.querySelectorAll("xm-tab-panel"));
+    }
+    _enabledTabs() {
+        return this._tabs.filter((t) => !t.disabled);
+    }
+    _positionIndicator() {
+        const indicator = this._indicator;
+        const list = this._list;
+        if (!indicator || !list)
+            return;
+        const active = this._tabs.find((t) => t.value === this._activeValue);
+        if (!active) {
+            indicator.style.opacity = "0";
+            return;
+        }
+        const listRect = list.getBoundingClientRect();
+        const tabRect = active.getBoundingClientRect();
+        const left = tabRect.left - listRect.left + list.scrollLeft;
+        indicator.style.opacity = "1";
+        indicator.style.width = `${Math.round(tabRect.width)}px`;
+        indicator.style.transform = `translateX(${Math.round(left)}px)`;
+    }
+    _activate(value, focus = true) {
+        const tab = this._tabs.find((t) => t.value === value);
+        if (!tab || tab.disabled)
+            return;
+        const changed = value !== this._activeValue;
+        this._activeValue = value;
+        this.value = value;
+        this._sync();
+        if (focus)
+            tab.focus();
+        if (changed) {
+            const detail = { value };
+            this.dispatchEvent(new CustomEvent("change", {
+                detail,
+                bubbles: true,
+                composed: true,
+            }));
+        }
+    }
+};
+__decorate([
+    property({ type: String })
+], XmTabs.prototype, "value", void 0);
+__decorate([
+    property({ type: String })
+], XmTabs.prototype, "size", void 0);
+__decorate([
+    query(".tabs__list")
+], XmTabs.prototype, "_list", void 0);
+__decorate([
+    query(".tabs__indicator")
+], XmTabs.prototype, "_indicator", void 0);
+XmTabs = __decorate([
+    customElement("xm-tabs")
+], XmTabs);

package/dist/lit/components/text-field/index.css

@@ -0,0 +1,90 @@
+/* ============================================
+   xm-text-field — concrete control for XmField (Story 2.1).
+
+   The chrome (surface, border, radius, height, focus ring, label, helper/
+   error row, disabled/readonly) is owned by the XmField base — see
+   field/index.css. The native <input> rendered by this subclass is already
+   styled by the base's `.field__control input` rule (transparent, borderless,
+   full-bleed, inherits ink + type). So THIS file owns only the leading/trailing
+   affordance rails: the icon-left / icon-right slots and the prefix / suffix
+   inline units that flank the input inside the shared control wrapper.
+
+   Surface/ink: the field sits on the inverse-surface card tier, so all ink here
+   is inverse-on-surface (icons) or inverse-on-surface-muted (prefix/suffix
+   units) — matching the host surface (AD-13). No error color: severity is the base's
+   icon + copy in the message row (AD-11). Tokens only (AD-1).
+
+   BEM block: `text-field`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+/* ---------- Leading / trailing rails ----------
+   Flex children of the base's .field__control row, sitting on either side of
+   the input. Each collapses to zero width when its slots are empty, so the
+   input keeps its native edge padding when no affordance is authored. The
+   icon↔text gap rides the --s-N spacing scale to match the shared chrome. */
+.text-field__lead,
+.text-field__trail {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  flex-shrink: 0;
+  color: var(--md-sys-color-inverse-on-surface);
+}
+
+/* Empty rails contribute no inset — the inner pad-collapse below removes the
+   matching input padding so a field with no affordance looks untouched. */
+.text-field__lead:not(:has(*)),
+.text-field__trail:not(:has(*)) {
+  display: none;
+}
+
+/* When a leading rail is present it owns the leading inset; the input drops its
+   own left pad so the icon/prefix sits at the wrapper edge inset, and text
+   follows the rail's gap. Mirror on the trailing side. */
+.text-field__lead {
+  padding-left: var(--s-3);
+}
+.text-field__trail {
+  padding-right: var(--s-3);
+}
+.text-field__lead:not(:has(*)) + .text-field__input {
+  padding-left: var(--s-3);
+}
+
+/* ---------- Prefix / suffix inline units ----------
+   Static affordances like `$` or `KB` — quieter than the live value, so they
+   take the muted inverse ink. Slotted content inherits this via the rail color +
+   ::slotted override. */
+.text-field__lead ::slotted([slot="prefix"]),
+.text-field__trail ::slotted([slot="suffix"]) {
+  color: var(--xm-color-inverse-on-surface-muted);
+  font:
+    var(--md-sys-typescale-body-large-weight)
+    var(--md-sys-typescale-body-large-size) /
+    var(--md-sys-typescale-body-large-line-height)
+    var(--md-sys-typescale-body-large-font);
+  white-space: nowrap;
+}
+
+/* Icons inherit currentColor from the rail (inverse-on-surface), matching the
+   host card surface — never an accent or error hue. */
+.text-field__lead ::slotted([slot="icon-left"]),
+.text-field__trail ::slotted([slot="icon-right"]) {
+  display: inline-flex;
+  align-items: center;
+  color: inherit;
+}
+
+/* The input flexes to fill the gap between the rails. Its transparent /
+   borderless / type styling comes from the base; the rails set the inset, so
+   when a rail is present the input loses the matching native edge pad. */
+.text-field__input {
+  flex: 1;
+  min-width: 0;
+}
+.text-field__lead:has(*) + .text-field__input {
+  padding-left: var(--s-2);
+}
+.text-field__input:has(+ .text-field__trail:has(*)) {
+  padding-right: var(--s-2);
+}

package/dist/lit/components/text-field/index.d.ts

@@ -0,0 +1,17 @@
+import type { TemplateResult } from "lit";
+import { XmField } from "../field/index.js";
+export type TextFieldType = "text" | "email" | "password" | "number" | "search" | "url" | "tel";
+export declare class XmTextField extends XmField {
+    /** Native input type — single-line text variants only. */
+    type: TextFieldType;
+    /** Native placeholder — shown when the live value is empty. */
+    placeholder: string;
+    private _onInput;
+    private _onChange;
+    protected renderControl(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-text-field": XmTextField;
+    }
+}

package/dist/lit/components/text-field/index.js

@@ -0,0 +1,101 @@
+/*
+  text-field/index.ts — the first concrete XmField subclass (Epic 2 Story 2.1).
+
+  <xm-text-field> — single-line text input. It extends the abstract XmField
+  base (lit/components/field), so the chrome — label row, control wrapper at
+  the shared size height, helper/error row, required marker, focus ring,
+  disabled/readonly/loading rendering, ARIA wiring, form association, and the
+  uncontrolled-first value lifecycle — is NOT re-implemented here (AD-7). The
+  subclass supplies ONLY the concrete control: a native <input> projected into
+  the base's control wrapper via renderControl(), plus the type/prefix/suffix
+  and icon-left/icon-right affordances.
+
+  Authoring:
+    <xm-text-field
+      label="Email"
+      type="email"
+      placeholder="you@example.com"
+      helper="We never share it."
+      required
+    >
+      <xm-search-icon slot="icon-left"></xm-search-icon>
+      <span slot="suffix">KB</span>
+    </xm-text-field>
+
+  Value ownership is uncontrolled-first (AD-6): the `value` attribute seeds the
+  initial value once; the field then owns its live state. The base's emitInput /
+  emitChange fire bubbling + composed `input` (per keystroke) and `change`
+  (on commit: blur / Enter / native change) with detail.value, and mirror the
+  value into ElementInternals for xm-form (AD-6a/AD-8a).
+
+  Shadow DOM. The native <input> rendered here is ALREADY styled by the base's
+  `.field__control input` rule (transparent / borderless / full-bleed / inherits
+  ink + type) — so this component's CSS owns only the prefix/suffix/icon slots,
+  never the input box. Lit is a bare `import` (peer dep).
+*/
+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 { html, nothing } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { XmField } from "../field/index.js";
+// Resolve CSS relative to the *built* file:
+// lit/build/components/text-field/index.js → ../text-field/index.css.
+const TEXT_FIELD_CSS = new URL("../text-field/index.css", import.meta.url).href;
+let XmTextField = class XmTextField extends XmField {
+    constructor() {
+        super(...arguments);
+        /** Native input type — single-line text variants only. */
+        this.type = "text";
+        /** Native placeholder — shown when the live value is empty. */
+        this.placeholder = "";
+        this._onInput = (e) => {
+            this.emitInput(e.target.value);
+        };
+        this._onChange = (e) => {
+            this.emitChange(e.target.value);
+        };
+    }
+    renderControl() {
+        const a = this.controlAria;
+        return html `
+      <link rel="stylesheet" href="${TEXT_FIELD_CSS}" />
+      <span class="text-field__lead">
+        <slot name="icon-left"></slot>
+        <slot name="prefix"></slot>
+      </span>
+      <input
+        class="text-field__input"
+        id=${a.id}
+        type=${this.type}
+        .value=${this._value}
+        placeholder=${this.placeholder || nothing}
+        name=${this.name || nothing}
+        aria-describedby=${a.describedBy ?? nothing}
+        aria-invalid=${a.invalid ?? "false"}
+        ?required=${this.required}
+        ?disabled=${this.effectiveDisabled}
+        ?readonly=${this.readonly}
+        @input=${this._onInput}
+        @change=${this._onChange}
+      />
+      <span class="text-field__trail">
+        <slot name="suffix"></slot>
+        <slot name="icon-right"></slot>
+      </span>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmTextField.prototype, "type", void 0);
+__decorate([
+    property({ type: String })
+], XmTextField.prototype, "placeholder", void 0);
+XmTextField = __decorate([
+    customElement("xm-text-field")
+], XmTextField);
+export { XmTextField };

package/dist/lit/components/textarea/index.css

@@ -0,0 +1,55 @@
+/* ============================================
+   xm-textarea — multi-line concrete control for XmField (Story 2.2).
+
+   The chrome (surface, border, radius, focus ring, label, helper/error row,
+   disabled/readonly) is owned by the XmField base — see field/index.css. The
+   only delta from xm-text-field is the multi-line <textarea>: it is taller
+   than one control row, so the control wrapper must stop vertically centering
+   its child and let the textarea own its own block size.
+
+   The native <textarea> rendered here is already styled transparent /
+   borderless / full-bleed / inherits-ink by the base's `.field__control
+   textarea` rule. So THIS file only:
+     • un-centers the control wrapper for a multi-row box,
+     • sets the textarea's own vertical padding + resize behavior,
+     • caps the auto-grow height.
+
+   Surface/ink: rides the inverse-surface card tier — ink is inverse-on-surface,
+   placeholder is on-surface-variant (matching the host surface, AD-13). No
+   error color — severity is the base's icon + copy (AD-11). Tokens only (AD-1).
+
+   BEM block: `textarea`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+/* The control wrapper centers a single-line input; a textarea needs the box to
+   start at the top and stretch, so the field-level control wrapper is realigned
+   when it hosts this block. Scoped under the block so it never leaks to other
+   fields. */
+.textarea {
+  display: block;
+  width: 100%;
+}
+
+/* The native <textarea> — already transparent/borderless/inheriting via the
+   base rule. Here we own the multi-line geometry: top-aligned text, vertical
+   pad on the --s-N scale, and the resize affordance. */
+.textarea__control {
+  display: block;
+  width: 100%;
+  min-width: 0;
+  /* Override the base `.field__control textarea { height: 100% }` rule — a
+     textarea owns its own block size from `rows` / scrollHeight, not the
+     single-line wrapper height. */
+  height: auto;
+  align-self: stretch;
+  padding: var(--s-2) var(--s-3);
+  resize: vertical;
+  line-height: var(--md-sys-typescale-body-large-line-height);
+}
+
+/* Auto-grow disables the manual resize handle — the box tracks its content up
+   to the capped max-height instead. */
+.textarea__control--auto-grow {
+  resize: none;
+  overflow-y: auto;
+}

package/dist/lit/components/textarea/index.d.ts

@@ -0,0 +1,26 @@
+import type { PropertyValues, TemplateResult } from "lit";
+import { XmField } from "../field/index.js";
+export declare class XmTextarea extends XmField {
+    /** Initial visible height in text rows. */
+    rows: number;
+    /** Native placeholder — shown when the live value is empty. */
+    placeholder: string;
+    /** Grow the textarea height with content up to `maxRows` (no scroll jitter). */
+    autoGrow: boolean;
+    /** Cap for auto-grow, in rows. Beyond it the textarea scrolls. */
+    maxRows: number;
+    private _textarea;
+    protected updated(changed: PropertyValues<this>): void;
+    private _onInput;
+    private _onChange;
+    /** Reset then snap to scrollHeight, clamped to maxRows. Reading scrollHeight
+        after a height reset is the only reliable shrink-and-grow measurement;
+        it's a single synchronous layout read per input, not an animation. */
+    private _resize;
+    protected renderControl(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-textarea": XmTextarea;
+    }
+}