@xmesh/system-design 0.0.1

package/dist/lit/components/expansion-panel/index.css

@@ -0,0 +1,120 @@
+/* ============================================
+   Expansion panel — collapsible disclosure with a rotating chevron.
+
+   <xm-expansion-panel> is a framed disclosure: a header button +
+   a collapsible body. The chevron rotates short4 / standard easing
+   on toggle (no spring, bounce, or scale-in; NFR-19).
+
+   Sits on one surface family (AD-13): surface-container-low frame,
+   ink --md-sys-color-on-surface, hairline 1px outline-variant
+   separators. No severity hue (AD-11). The chevron inherits ink via
+   currentColor.
+   ============================================ */
+
+.expansion-panel {
+  display: block;
+  border: 1px solid var(--md-sys-color-outline-variant);
+  border-radius: var(--md-sys-shape-corner-medium);
+  background: var(--md-sys-color-surface-container-low);
+  color: var(--md-sys-color-on-surface);
+  overflow: hidden;
+}
+
+.expansion-panel__header {
+  appearance: none;
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: var(--s-3);
+  box-sizing: border-box;
+  padding: var(--s-3) var(--s-4);
+  border: none;
+  background: transparent;
+  color: var(--md-sys-color-on-surface);
+  text-align: start;
+  cursor: pointer;
+  font-family: var(--md-sys-typescale-title-small-font);
+  font-size: var(--md-sys-typescale-title-small-size);
+  font-weight: 500;
+  line-height: 1.3;
+  transition: background var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard);
+}
+.expansion-panel__header:hover {
+  background: color-mix(in oklab, var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity), transparent);
+}
+.expansion-panel__header:focus { outline: none; }
+/* Inset focus ring so the accent halo stays inside the frame's rounded clip
+   rather than being cut off by overflow: hidden. Same 3px weight + coral
+   primary-container as --xm-state-focus-ring, just drawn inset. */
+.expansion-panel__header:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 3px var(--md-sys-color-primary-container);
+}
+
+.expansion-panel__heading {
+  flex: 1;
+  min-width: 0;
+}
+
+.expansion-panel__chevron {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: var(--md-sys-color-on-surface-variant);
+  transition: transform var(--md-sys-motion-duration-short4) var(--md-sys-motion-easing-standard);
+}
+.expansion-panel--open .expansion-panel__chevron {
+  transform: rotate(180deg);
+}
+
+/* Body — hidden when collapsed. A hairline separates it from the header
+   only while open. */
+/* Animated reveal: the body is a 1-row grid that transitions 1fr→0fr; the inner
+   wrapper has min-height:0 + overflow:hidden so the auto-height content can be
+   clipped to zero. This animates a content-sized body (which a plain
+   height/max-height can't) with short4 standard easing — no spring/scale. */
+.expansion-panel__body {
+  display: grid;
+  grid-template-rows: 1fr;
+  border-top: 1px solid var(--md-sys-color-outline-variant);
+  color: var(--md-sys-color-on-surface-variant);
+  font-family: var(--md-sys-typescale-body-large-font);
+  font-size: var(--md-sys-typescale-body-large-size);
+  line-height: var(--md-sys-typescale-body-large-line-height);
+  transition:
+    grid-template-rows var(--md-sys-motion-duration-short4) var(--md-sys-motion-easing-standard),
+    border-color var(--md-sys-motion-duration-short4) var(--md-sys-motion-easing-standard);
+}
+.expansion-panel__body-inner {
+  min-height: 0;
+  overflow: hidden;
+  padding: var(--s-3) var(--s-4) var(--s-4);
+}
+.expansion-panel__body.is-collapsed {
+  grid-template-rows: 0fr;
+  border-top-color: transparent;
+}
+.expansion-panel__body.is-collapsed .expansion-panel__body-inner {
+  /* Drop the vertical padding while collapsed so it doesn't hold the row open. */
+  padding-block: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .expansion-panel__body {
+    transition: none;
+  }
+}
+
+/* Disabled — shared reduced emphasis, non-interactive. The chevron carries its
+   own color, so mute it too or it stays at full emphasis on a disabled panel. */
+.expansion-panel--disabled .expansion-panel__header {
+  cursor: not-allowed;
+  color: var(--xm-color-on-surface-disabled);
+}
+.expansion-panel--disabled .expansion-panel__chevron {
+  color: var(--xm-color-on-surface-disabled);
+}
+.expansion-panel--disabled .expansion-panel__header:hover {
+  background: transparent;
+}

package/dist/lit/components/expansion-panel/index.d.ts

@@ -0,0 +1,22 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+declare class XmExpansionPanel extends LitElement {
+    open: boolean;
+    heading: string;
+    disabled: boolean;
+    value: string;
+    name: string;
+    private _uid;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _onSiblingOpen;
+    private _toggle;
+    private _onHeaderClick;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-expansion-panel": XmExpansionPanel;
+    }
+}
+export {};

package/dist/lit/components/expansion-panel/index.js

@@ -0,0 +1,174 @@
+/*
+  expansion-panel/index.ts — <xm-expansion-panel>.
+
+  Collapsible disclosure: a header button + a body that shows/hides on
+  toggle, with a chevron that rotates short4 / standard easing.
+
+  Authoring:
+    <xm-expansion-panel heading="Routing" open>
+      The planner reads routing.yaml and falls back to JSON.
+    </xm-expansion-panel>
+
+    <!-- Slotted header for richer content -->
+    <xm-expansion-panel>
+      <span slot="header">Advanced <xm-badge count="2">…</xm-badge></span>
+      …body…
+    </xm-expansion-panel>
+
+  Properties:
+    open      boolean       — INITIAL open state (uncontrolled-first, AD-6);
+                              the panel owns it thereafter
+    heading   string        — header text (or use slot="header")
+    disabled  boolean       — non-interactive, reduced emphasis
+    value     string|number — identity for host bookkeeping
+    name      string        — single-open group key: panels sharing a `name`
+                              auto-collapse siblings on open (the documented
+                              grouping). Omit the name (or give unique names)
+                              to allow several open at once (multiple mode).
+
+  Events:
+    change   bubbles+composed. detail.open: boolean. (Bare native-mirroring
+             name per AD-8; the panel owns its state per AD-6.)
+
+  Header is a real <button> with aria-expanded + aria-controls; the body is
+  aria-labelledby the header. Shadow DOM; 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 { LitElement, html } from "lit";
+import { customElement, property } from "lit/decorators.js";
+const PANEL_CSS = new URL("../expansion-panel/index.css", import.meta.url).href;
+const COORDINATION_EVENT = "xm-expansion-panel-open";
+let panelInstance = 0;
+let XmExpansionPanel = class XmExpansionPanel extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.open = false;
+        this.heading = "";
+        this.disabled = false;
+        this.value = "";
+        this.name = "";
+        this._uid = `expansion-panel-${++panelInstance}`;
+        this._onSiblingOpen = (e) => {
+            if (!this.name)
+                return;
+            if (e.detail.source === this)
+                return;
+            if (e.detail.name === this.name && this.open) {
+                this.open = false;
+            }
+        };
+        this._onHeaderClick = () => {
+            this._toggle();
+        };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // Single-open coordination: listen on the document for sibling opens of
+        // the same `name` and collapse when another panel in the group opens.
+        document.addEventListener(COORDINATION_EVENT, this._onSiblingOpen);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        document.removeEventListener(COORDINATION_EVENT, this._onSiblingOpen);
+    }
+    _toggle() {
+        if (this.disabled)
+            return;
+        this.open = !this.open;
+        if (this.open && this.name) {
+            document.dispatchEvent(new CustomEvent(COORDINATION_EVENT, {
+                detail: { name: this.name, source: this },
+            }));
+        }
+        this.dispatchEvent(new CustomEvent("change", {
+            detail: { open: this.open },
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    render() {
+        const cls = [
+            "expansion-panel",
+            this.open && "expansion-panel--open",
+            this.disabled && "expansion-panel--disabled",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const headerId = `${this._uid}-header`;
+        const bodyId = `${this._uid}-body`;
+        return html `
+      <link rel="stylesheet" href="${PANEL_CSS}" />
+      <style>
+        :host {
+          display: block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div class="${cls}">
+        <button
+          id="${headerId}"
+          class="expansion-panel__header"
+          type="button"
+          aria-expanded=${this.open ? "true" : "false"}
+          aria-controls="${bodyId}"
+          ?disabled=${this.disabled}
+          @click=${this._onHeaderClick}
+        >
+          <span class="expansion-panel__heading">
+            ${this.heading ? this.heading : html `<slot name="header"></slot>`}
+          </span>
+          <span class="expansion-panel__chevron" aria-hidden="true">
+            <svg
+              viewBox="0 0 24 24"
+              width="18"
+              height="18"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            >
+              <polyline points="6 9 12 15 18 9" />
+            </svg>
+          </span>
+        </button>
+        <div
+          id="${bodyId}"
+          role="region"
+          aria-labelledby="${headerId}"
+          class="expansion-panel__body ${this.open ? "" : "is-collapsed"}"
+          ?inert=${!this.open}
+        >
+          <div class="expansion-panel__body-inner">
+            <slot></slot>
+          </div>
+        </div>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmExpansionPanel.prototype, "open", void 0);
+__decorate([
+    property({ type: String })
+], XmExpansionPanel.prototype, "heading", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmExpansionPanel.prototype, "disabled", void 0);
+__decorate([
+    property({ type: String })
+], XmExpansionPanel.prototype, "value", void 0);
+__decorate([
+    property({ type: String })
+], XmExpansionPanel.prototype, "name", void 0);
+XmExpansionPanel = __decorate([
+    customElement("xm-expansion-panel")
+], XmExpansionPanel);

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

@@ -0,0 +1,223 @@
+/* ============================================
+   XmField — abstract form-field chrome.
+
+   The base renders label / control wrapper / helper-or-error row; the
+   subclass drops only its concrete control into the control wrapper
+   (AD-7). One shared control height per `size` so a field lines up beside
+   a button of the same size (NFR-22). Surface is the card tier
+   (inverse-surface) with inverse-on-surface ink (AD-13). Severity is the
+   error icon + copy in the message row — never an error color, never a red
+   field (AD-11 / rule 3a).
+
+   Sizes mirror the button height ramp so fields snap to buttons:
+     .field--xs   22px control
+     .field--sm   26px control
+     .field--md   32px control   (default)
+     .field--lg   42px control
+
+   BEM block: `field`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+  width: 100%;
+}
+
+/* ---------- Label row ---------- */
+.field__label {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-1);
+  color: var(--md-sys-color-inverse-on-surface);
+  font:
+    var(--md-sys-typescale-label-large-weight)
+    var(--md-sys-typescale-label-large-size) /
+    var(--md-sys-typescale-label-large-line-height)
+    var(--md-sys-typescale-label-large-font);
+  cursor: default;
+}
+.field__label-text {
+  letter-spacing: 0;
+}
+.field__required {
+  color: var(--md-sys-color-primary);
+  font-weight: 700;
+  line-height: 1;
+}
+
+/* ---------- Control wrapper ----------
+   The wrapper carries the shared chrome: surface, border, radius, height,
+   focus ring. The concrete control (slotted or shadow-rendered by the
+   subclass) sits inside and inherits ink + type. */
+.field__control {
+  position: relative;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  box-sizing: border-box;
+  border: 1px solid var(--md-sys-color-outline-variant);
+  border-radius: var(--md-sys-shape-corner-button);
+  background: var(--md-sys-color-inverse-surface);
+  color: var(--md-sys-color-inverse-on-surface);
+  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);
+  transition:
+    border-color var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard),
+    box-shadow var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard),
+    background var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard);
+}
+.field__control:hover {
+  border-color: var(--md-sys-color-outline);
+}
+
+/* Focus — ring is the canonical visualization; outline suppressed. The wrapper
+   reacts to KEYBOARD focus of the inner control via :has(:focus-visible) so the
+   coral ring shows on tab-in but not on a plain pointer click (matches the
+   :focus-visible intent in the spec while still reacting to the slotted/native
+   control nested inside the wrapper). */
+.field__control:has(:focus-visible) {
+  outline: none;
+  border-color: var(--md-sys-color-primary);
+  box-shadow: var(--xm-state-focus-ring);
+}
+
+/* Style whatever native control a subclass slots OR shadow-renders so the
+   chrome owns the box and the control is a transparent, borderless,
+   full-bleed inner. Two selector sets are required: ::slotted() matches a
+   light-DOM `slot="control"` child; the scoped descendant set matches a
+   control a subclass renders into shadow DOM via renderControl(). Without
+   the descendant set a UA-default input fill shows through (a dark box on
+   the light card surface) — the surface/ink foot-gun. */
+.field__control ::slotted(input),
+.field__control ::slotted(textarea),
+.field__control ::slotted(select),
+.field__control input,
+.field__control textarea,
+.field__control select {
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+  appearance: none;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  padding: 0 var(--s-3);
+  height: 100%;
+  box-sizing: border-box;
+}
+.field__control ::slotted(input)::placeholder,
+.field__control ::slotted(textarea)::placeholder,
+.field__control input::placeholder,
+.field__control textarea::placeholder {
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+
+/* ---------- Sizes — shared control height ---------- */
+.field--xs .field__control { min-height: 22px; }
+.field--sm .field__control { min-height: 26px; }
+.field--md .field__control { min-height: 32px; }
+.field--lg .field__control { min-height: 42px; }
+
+.field--xs .field__control ::slotted(input),
+.field--xs .field__control ::slotted(select) { padding: 0 var(--s-2); }
+
+/* ---------- Loading ----------
+   The control region is swapped for the spinner; the wrapper keeps its box
+   so the field height does not jump (AD-9a). */
+.field__loading {
+  display: inline-flex;
+  align-items: center;
+  justify-content: flex-start;
+  width: 100%;
+  height: 100%;
+  padding: 0 var(--s-3);
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+.field--loading .field__control {
+  cursor: progress;
+}
+
+/* ---------- Disabled ----------
+   Shared reduced emphasis, cursor, reverted hover; never an error color. */
+.field--disabled {
+  cursor: not-allowed;
+}
+/* No opacity on the control: it would dim the VALUE text (which inherits
+   .field__control's color) below AA. Swap the ink to the disabled token so
+   the value stays legible; the box is muted by its border + container. */
+.field--disabled .field__control {
+  cursor: not-allowed;
+  color: var(--xm-color-inverse-on-surface-disabled);
+  box-shadow: none;
+}
+.field--disabled .field__control:hover {
+  border-color: var(--md-sys-color-outline-variant);
+}
+.field--disabled .field__control ::slotted(input)::placeholder,
+.field--disabled .field__control ::slotted(textarea)::placeholder,
+.field--disabled .field__control input::placeholder,
+.field--disabled .field__control textarea::placeholder {
+  color: var(--xm-color-inverse-on-surface-disabled);
+}
+.field--disabled .field__label {
+  color: var(--xm-color-inverse-on-surface-disabled);
+}
+
+/* ---------- Readonly ----------
+   Value visible but not editable; still focusable. Stays on the card
+   (inverse-surface) family — a faint inverse-on-surface wash over the same
+   surface reads as inert without swapping in the desk surface family. */
+.field--readonly .field__control {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-inverse-on-surface) 5%,
+    var(--md-sys-color-inverse-surface)
+  );
+  border-color: var(--md-sys-color-outline-variant);
+}
+.field--readonly .field__control:hover {
+  border-color: var(--md-sys-color-outline-variant);
+}
+
+/* ---------- Helper / error message row ----------
+   Severity is icon + copy. The error keeps the same ink as the helper —
+   the icon and string carry the severity, not a color (AD-11 / rule 3a). */
+.field__message {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--s-1);
+  min-height: 1em;
+  font:
+    var(--md-sys-typescale-body-small-weight)
+    var(--md-sys-typescale-body-small-size) /
+    var(--md-sys-typescale-body-small-line-height)
+    var(--md-sys-typescale-body-small-font);
+}
+.field__message--helper {
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+.field__message--error {
+  color: var(--md-sys-color-inverse-on-surface);
+}
+.field__message--empty {
+  min-height: 0;
+}
+.field__error-icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  margin-top: 1px;
+  color: var(--md-sys-color-inverse-on-surface);
+}
+.field__message-text {
+  flex: 1;
+  min-width: 0;
+  text-wrap: pretty;
+}

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

@@ -0,0 +1,106 @@
+import { LitElement } from "lit";
+import type { PropertyValues, TemplateResult } from "lit";
+export type FieldSize = "xs" | "sm" | "md" | "lg";
+export interface FieldControlAria {
+    id: string;
+    /** undefined when there is no helper/error text — so a control's
+        aria-describedby never points at an empty message node. */
+    describedBy: string | undefined;
+    invalid: "true" | undefined;
+    required: "true" | undefined;
+}
+/**
+ * Abstract chrome + lifecycle base for every xmesh form field.
+ *
+ * Subclasses register with `@customElement("xm-<name>")`; XmField itself is
+ * never registered (it is not a usable element on its own).
+ */
+export declare abstract class XmField extends LitElement {
+    static formAssociated: boolean;
+    static shadowRootOptions: ShadowRootInit;
+    label: string;
+    helper: string;
+    /** Severity copy. Non-empty ⇒ the field is in error (icon + copy, never color). */
+    error: string;
+    size: FieldSize;
+    required: boolean;
+    disabled: boolean;
+    readonly: boolean;
+    loading: boolean;
+    /** Form-control name — mirrors native <input name>. */
+    name: string;
+    /** INITIAL value (uncontrolled-first, AD-6): the `value` attribute seeds the
+        live state once, then never overrides user input. Mapped from attribute
+        `value` so authors write `<xm-text-field value="…">`. */
+    initialValue: string;
+    /** INITIAL checked for toggle subclasses; mapped from attribute `checked`. */
+    initialChecked: boolean;
+    /** Live value state — seeded from `initialValue`, then owned by the field. */
+    protected _value: string;
+    /** Live checked state (toggle subclasses) — seeded from `initialChecked`. */
+    protected _checked: boolean;
+    /** True once a toggle subclass has declared itself, so the form value is
+        submitted as checked-state rather than text. Set eagerly by overriding
+        `isToggle`, or lazily on the first `emitToggle`. */
+    protected _toggle: boolean;
+    /** OR-propagated disabled flag a future xm-form sets — never re-enables a
+        self-disabled field (AD-6a / AD-9a). */
+    private _formDisabled;
+    protected readonly internals: ElementInternals;
+    private readonly _seq;
+    private readonly _controlId;
+    private readonly _describedById;
+    private _valueSeeded;
+    protected _dirty: boolean;
+    constructor();
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** Whether this field submits checked-state (toggle) rather than text. Toggle
+        subclasses (checkbox / radio / switch) override this to return `true` so
+        their form value is correct from first paint — before any interaction —
+        and is never inferred from `initialChecked` (a declaratively-checked text
+        field must NOT be treated as a toggle, and an untouched unchecked toggle
+        must submit `null`, not `""`). */
+    protected get isToggle(): boolean;
+    /** Effective disabled = own disabled OR a future xm-form down-propagation.
+        OR semantics: neither source can re-enable what the other disabled. */
+    protected get effectiveDisabled(): boolean;
+    /** Non-interactive whenever disabled (either source), readonly, or loading. */
+    protected get nonInteractive(): boolean;
+    protected get isError(): boolean;
+    /** True when the message row has helper or error copy to describe. */
+    protected get hasMessage(): boolean;
+    /** Public read contract for xm-form (AD-6a/AD-12): live value, no shadow reach. */
+    get value(): string;
+    /** Programmatic reset support — setting `value` after first paint updates live state. */
+    set value(next: string);
+    /** Public read contract for toggle subclasses (AD-6a). */
+    get checked(): boolean;
+    set checked(next: boolean);
+    /** Down-propagation hook: xm-form (Story 2.10) sets this; it OR's with the
+        field's own disabled and can never re-enable a self-disabled field. */
+    setFormDisabled(disabled: boolean): void;
+    /** Per-keystroke / per-drag live update. Updates live state, syncs the form
+        value, and emits a composed, bubbling `input` with a typed primitive detail. */
+    protected emitInput(value: string): void;
+    /** Commit. Same payload shape as input; fire on blur / Enter / native change. */
+    protected emitChange(value: string): void;
+    /** Toggle commit — marks the field a toggle and emits `detail.checked` (AD-8a). */
+    protected emitToggle(checked: boolean): void;
+    private _syncFormValue;
+    /**
+     * The ARIA hooks the chrome wires. Subclasses set `id`, `aria-describedby`,
+     * `aria-invalid`, and `aria-required` on their control element from these so
+     * the rendered label associates with the control and the error string is
+     * announced (NFR-13 / UX-DR7).
+     */
+    protected get controlAria(): FieldControlAria;
+    /**
+     * Subclasses override to render their concrete control directly into shadow
+     * DOM. The default projects whatever the author slots as `slot="control"`,
+     * so a subclass can also author the control as a light-DOM child. Either
+     * path keeps the chrome on the base (AD-7).
+     */
+    protected renderControl(): TemplateResult;
+    render(): TemplateResult;
+}