@xmesh/system-design 0.0.1

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

@@ -0,0 +1,195 @@
+/*
+  snackbar/index.ts — Lit port of components/snackbar/index.jsx.
+
+  <xm-snackbar> — backend-error surface that lives at the bottom of
+  the chat pane. Three flavors (auth | server | generic) plus a
+  separate `static` mode for preview cards (no entry animation).
+
+  Properties:
+    kind            "auth" | "server" | "generic"   (default "generic")
+    code            optional code string ("401", "503", "ERR")
+    title           required heading string
+    message         required body string
+    primaryLabel    if present, primary button is rendered
+    secondaryLabel  defaults to "Dismiss"; the button only renders when
+                    a `dismiss` listener wants to receive the event
+    showDismiss     boolean — render the secondary/dismiss button
+    static          boolean — preview-only mode, suppresses animations
+
+  Events:
+    snackbar-primary    — primary action clicked (Retry / Open settings)
+    snackbar-dismiss    — secondary/dismiss action clicked
+
+  Light DOM. components/snackbar/index.css and components/primitives/index.css
+  must be loaded in the host page.
+
+  SNACK_PRESETS is also exported so previews can spread a preset onto
+  the element via JS.
+*/
+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, svg, nothing } from "lit";
+import { customElement, property } from "lit/decorators.js";
+export const SNACK_PRESETS = {
+    auth: {
+        kind: "auth",
+        code: "401",
+        title: "Access denied",
+        message: "Your API key was rejected. Open settings to update or replace the key.",
+        primaryLabel: "Open settings",
+        secondaryLabel: "Dismiss",
+    },
+    server: {
+        kind: "server",
+        code: "503",
+        title: "Server error",
+        message: "The model service is temporarily unavailable. Your message wasn't sent.",
+        primaryLabel: "Retry",
+        secondaryLabel: "Dismiss",
+    },
+    generic: {
+        kind: "generic",
+        code: "ERR",
+        title: "Something went wrong",
+        message: "We couldn't reach the backend. Check your connection and try again.",
+        primaryLabel: "Retry",
+        secondaryLabel: "Dismiss",
+    },
+};
+const SHELL = (size, strokeWidth, paths) => svg `
+  <svg width="${size}" height="${size}" viewBox="0 0 24 24"
+       fill="none" stroke="currentColor" stroke-width="${strokeWidth}"
+       stroke-linecap="round" stroke-linejoin="round" class="ds-icon">
+    ${paths}
+  </svg>
+`;
+const KIND_ICONS = {
+    auth: () => SHELL(18, 1.8, svg `
+    <rect x="4" y="10" width="16" height="11" rx="2" />
+    <path d="M8 10V7a4 4 0 0 1 8 0v3" />
+  `),
+    server: () => SHELL(18, 1.8, svg `
+    <rect x="3" y="4" width="18" height="7" rx="1.5" />
+    <rect x="3" y="13" width="18" height="7" rx="1.5" />
+    <path d="M7 7.5h.01M7 16.5h.01" />
+    <path d="M16 18l4-4M20 18l-4-4" />
+  `),
+    generic: () => SHELL(18, 1.8, svg `
+    <path d="M12 3l10 18H2L12 3z" />
+    <path d="M12 10v5M12 18.5v.01" />
+  `),
+};
+const RETRY_ICON = () => SHELL(13, 2, svg `
+  <path d="M3 12a9 9 0 0 1 15.5-6.3L21 8" />
+  <path d="M21 3v5h-5" />
+  <path d="M21 12a9 9 0 0 1-15.5 6.3L3 16" />
+  <path d="M3 21v-5h5" />
+`);
+let XmSnackbar = class XmSnackbar extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.kind = "generic";
+        this.code = "";
+        this.title = "";
+        this.message = "";
+        this.primaryLabel = "";
+        this.secondaryLabel = "Dismiss";
+        this.showDismiss = false;
+        this.static = false;
+        this._onPrimary = () => {
+            this.dispatchEvent(new CustomEvent("snackbar-primary", { bubbles: true, composed: true }));
+        };
+        this._onDismiss = () => {
+            this.dispatchEvent(new CustomEvent("snackbar-dismiss", { bubbles: true, composed: true }));
+        };
+    }
+    createRenderRoot() {
+        return this;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // Make the host transparent to flex/grid layout so the inner .snackbar
+        // is what the parent measures — matches the React tree where
+        // <Snackbar> renders the <div class="snackbar"> directly.
+        if (!this.style.display)
+            this.style.display = "contents";
+    }
+    render() {
+        const kind = KIND_ICONS[this.kind] ? this.kind : "generic";
+        const kindIcon = KIND_ICONS[kind];
+        const cls = `snackbar snackbar--${kind} ${this.static ? "snackbar--static" : ""}`
+            .replace(/\s+/g, " ").trim();
+        return html `
+      <div class="${cls}" role="alert" aria-live="assertive">
+        <span class="snackbar__icon" aria-hidden="true">${kindIcon()}</span>
+
+        <div class="snackbar__body">
+          <div class="snackbar__head">
+            ${this.code
+            ? html `<span class="snackbar__code mono">${this.code}</span>`
+            : nothing}
+            <span class="snackbar__title">${this.title}</span>
+          </div>
+          <div class="snackbar__msg">${this.message}</div>
+        </div>
+
+        <div class="snackbar__actions">
+          ${this.primaryLabel
+            ? html `
+                <button
+                  type="button"
+                  class="snackbar__btn snackbar__btn--primary"
+                  @click=${this._onPrimary}
+                >
+                  ${kind !== "auth" ? RETRY_ICON() : nothing}
+                  <span>${this.primaryLabel}</span>
+                </button>
+              `
+            : nothing}
+          ${this.showDismiss && this.secondaryLabel
+            ? html `
+                <button
+                  type="button"
+                  class="snackbar__btn snackbar__btn--ghost"
+                  @click=${this._onDismiss}
+                >
+                  ${this.secondaryLabel}
+                </button>
+              `
+            : nothing}
+        </div>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmSnackbar.prototype, "kind", void 0);
+__decorate([
+    property({ type: String })
+], XmSnackbar.prototype, "code", void 0);
+__decorate([
+    property({ type: String })
+], XmSnackbar.prototype, "title", void 0);
+__decorate([
+    property({ type: String })
+], XmSnackbar.prototype, "message", void 0);
+__decorate([
+    property({ type: String, attribute: "primary-label" })
+], XmSnackbar.prototype, "primaryLabel", void 0);
+__decorate([
+    property({ type: String, attribute: "secondary-label" })
+], XmSnackbar.prototype, "secondaryLabel", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "show-dismiss" })
+], XmSnackbar.prototype, "showDismiss", void 0);
+__decorate([
+    property({ type: Boolean })
+], XmSnackbar.prototype, "static", void 0);
+XmSnackbar = __decorate([
+    customElement("xm-snackbar")
+], XmSnackbar);

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

@@ -0,0 +1,41 @@
+/* ============================================
+   <xm-stack> — 1-D flex layout (vertical default).
+
+   The flex-stack primitive behind forms, sidebars, and action rows.
+   Slotted children are flex items (the <slot> is layout-transparent).
+   Gutter via gap="…" → --xm-gutter-* (the --s-N-aliased layout tier).
+
+   BEM block `stack`; modifiers --vertical / --horizontal, --gap-*,
+   --align-*, --justify-*. Registered in scripts/check-bem.sh
+   STRICT_BLOCKS.
+   ============================================ */
+
+.stack {
+  display: flex;
+  gap: var(--xm-gutter-md);
+  /* Inherited ink so currentColor in slotted content reads on the desk
+     surface (AD-13) — also satisfies the --md-sys-* token gate. */
+  color: var(--md-sys-color-on-surface);
+}
+
+.stack--vertical   { flex-direction: column; }
+.stack--horizontal { flex-direction: row; flex-wrap: nowrap; }
+
+:host([wrap]) .stack--horizontal { flex-wrap: wrap; }
+
+.stack--gap-none { gap: var(--xm-gutter-none); }
+.stack--gap-xs   { gap: var(--xm-gutter-xs); }
+.stack--gap-sm   { gap: var(--xm-gutter-sm); }
+.stack--gap-md   { gap: var(--xm-gutter-md); }
+.stack--gap-lg   { gap: var(--xm-gutter-lg); }
+.stack--gap-xl   { gap: var(--xm-gutter-xl); }
+
+.stack--align-start   { align-items: flex-start; }
+.stack--align-center  { align-items: center; }
+.stack--align-end     { align-items: flex-end; }
+.stack--align-stretch { align-items: stretch; }
+
+.stack--justify-start   { justify-content: flex-start; }
+.stack--justify-center  { justify-content: center; }
+.stack--justify-end     { justify-content: flex-end; }
+.stack--justify-between { justify-content: space-between; }

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

@@ -0,0 +1,20 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+type StackDirection = "vertical" | "horizontal";
+type StackGap = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+type StackAlign = "start" | "center" | "end" | "stretch";
+type StackJustify = "start" | "center" | "end" | "between";
+declare class XmStack extends LitElement {
+    direction: StackDirection;
+    gap: StackGap;
+    align: StackAlign;
+    justify: StackJustify;
+    wrap: boolean;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-stack": XmStack;
+    }
+}
+export {};

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

@@ -0,0 +1,103 @@
+/*
+  stack/index.ts — <xm-stack>, the 1-D flex layout primitive.
+
+  <xm-stack> — the flex-stack behind forms, sidebars, and action rows (which
+  today each re-implement `display:flex; flex-direction:column; gap:--s-N`
+  inline). Slotted children are flex items: the <slot> is layout-transparent,
+  so a child lays out as if it were a direct child of the stack container.
+
+  Authoring:
+    <xm-stack gap="md">            vertical stack (default)
+      <xm-field>…</xm-field>
+      <xm-field>…</xm-field>
+    </xm-stack>
+
+    <xm-stack direction="horizontal" justify="end" gap="sm">  action row
+      <xm-button variant="ghost">Cancel</xm-button>
+      <xm-button variant="primary">Save</xm-button>
+    </xm-stack>
+
+  Properties:
+    direction  "vertical" | "horizontal"                 (default "vertical")
+    gap        "none" | "xs" | "sm" | "md" | "lg" | "xl"  (default "md")
+               → --xm-gutter-* (aliases the --s-N scale)
+    align      "start" | "center" | "end" | "stretch"     (default "stretch")
+               cross-axis align-items
+    justify    "start" | "center" | "end" | "between"     (default "start")
+               main-axis justify-content
+    wrap       boolean — flex-wrap on horizontal stacks    (default false)
+
+  Shadow DOM; Lit from lit; sibling CSS via the
+  built-file-relative new URL(...). BEM block `stack`.
+*/
+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";
+// Resolve CSS relative to the *built* file:
+// lit/build/components/stack/index.js → ../stack/index.css.
+const STACK_CSS = new URL("../stack/index.css", import.meta.url).href;
+const DIRECTIONS = ["vertical", "horizontal"];
+const GAPS = ["none", "xs", "sm", "md", "lg", "xl"];
+const ALIGNS = ["start", "center", "end", "stretch"];
+const JUSTIFIES = ["start", "center", "end", "between"];
+let XmStack = class XmStack extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.direction = "vertical";
+        this.gap = "md";
+        this.align = "stretch";
+        this.justify = "start";
+        this.wrap = false;
+    }
+    render() {
+        const direction = DIRECTIONS.includes(this.direction)
+            ? this.direction
+            : "vertical";
+        const gap = GAPS.includes(this.gap) ? this.gap : "md";
+        const align = ALIGNS.includes(this.align)
+            ? this.align
+            : "stretch";
+        const justify = JUSTIFIES.includes(this.justify)
+            ? this.justify
+            : "start";
+        return html `
+      <link rel="stylesheet" href="${STACK_CSS}" />
+      <style>
+        :host {
+          display: block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div
+        class="stack stack--${direction} stack--gap-${gap} stack--align-${align} stack--justify-${justify}"
+      >
+        <slot></slot>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: String, reflect: true })
+], XmStack.prototype, "direction", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], XmStack.prototype, "gap", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], XmStack.prototype, "align", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], XmStack.prototype, "justify", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmStack.prototype, "wrap", void 0);
+XmStack = __decorate([
+    customElement("xm-stack")
+], XmStack);

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

@@ -0,0 +1,126 @@
+/* ============================================
+   xm-switch — binary on/off toggle on XmField (Story 2.7).
+
+   Like xm-checkbox, this is a TOGGLE field: the track sits BESIDE the label, not
+   above it on the bordered text-field chrome. State machinery (disabled / focus /
+   form-association / change) is inherited from XmField; this file styles only the
+   track, the thumb, and the label row.
+
+   Surface & ink (AD-13): the switch rides the inverse-surface card tier shared by
+   every XmField sibling — the label is inverse-on-surface ink. The OFF-track is a
+   muted neutral (--xm-switch-track-off, AD-10 extension); the thumb is the MD3
+   outline ink (legible on the off-track). When ON, the track fills with the
+   single coral accent (--md-sys-color-primary) and the thumb flips to on-primary
+   ink. Coral = on, never severity (AD-11).
+
+   Motion (NFR-19 / UX-DR10): the thumb slides on translateX only — short4
+   standard easing, NO bounce / spring / scale.
+
+   BEM block: `switch`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   (Distinct from the legacy `ds-switch` CSS block.)
+   ============================================ */
+
+.switch {
+  display: inline-flex;
+  flex-direction: column;
+  gap: var(--s-1);
+}
+
+/* ---------- Control row — track + label, the focusable target ---------- */
+.switch__control {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  cursor: pointer;
+  user-select: none;
+  outline: none;
+}
+
+/* ---------- Track ---------- */
+.switch__track {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  width: 36px;
+  height: 20px;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  padding: var(--s-0-5);
+  border-radius: var(--md-sys-shape-corner-full);
+  background: var(--xm-switch-track-off);
+  transition:
+    background var(--md-sys-motion-duration-short4) var(--md-sys-motion-easing-standard),
+    box-shadow var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard);
+}
+
+/* Focus ring — the canonical 3px coral halo on the track. */
+.switch__control:focus-visible .switch__track {
+  box-shadow: var(--xm-state-focus-ring);
+}
+
+/* ---------- Thumb — slides on translateX only ---------- */
+.switch__thumb {
+  width: 16px;
+  height: 16px;
+  border-radius: var(--md-sys-shape-corner-full);
+  background: var(--md-sys-color-outline);
+  box-shadow: var(--xm-switch-thumb-shadow);
+  transform: translateX(0);
+  transition: transform var(--md-sys-motion-duration-short4)
+    var(--md-sys-motion-easing-standard),
+    background var(--md-sys-motion-duration-short4)
+    var(--md-sys-motion-easing-standard);
+}
+
+/* ---------- On — coral track, thumb slides + flips to on-primary ink ---------- */
+.switch--on .switch__track {
+  background: var(--md-sys-color-primary);
+}
+.switch--on .switch__thumb {
+  transform: translateX(16px);
+  background: var(--md-sys-color-on-primary);
+}
+
+/* ---------- Label ---------- */
+.switch__label {
+  color: var(--md-sys-color-inverse-on-surface);
+  font:
+    var(--md-sys-typescale-body-medium-weight)
+    var(--md-sys-typescale-body-medium-size) /
+    var(--md-sys-typescale-body-medium-line-height)
+    var(--md-sys-typescale-body-medium-font);
+  letter-spacing: 0;
+}
+/* Collapse the label gap when no label is slotted. */
+.switch__label:empty {
+  display: none;
+}
+
+/* ---------- Disabled — shared reduced emphasis, no pointer ---------- */
+.switch--disabled .switch__control {
+  cursor: not-allowed;
+}
+.switch--disabled .switch__track {
+  opacity: 0.45;
+  box-shadow: none;
+}
+.switch--disabled .switch__label {
+  color: var(--xm-color-inverse-on-surface-disabled);
+}
+
+/* ---------- Helper / error message row ----------
+   Severity is copy, not color — the error keeps the helper ink (rule 3a). */
+.switch__message {
+  padding-left: calc(var(--s-9) + var(--s-2));
+  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);
+}
+.switch__message--helper {
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+.switch__message--error {
+  color: var(--md-sys-color-inverse-on-surface);
+}

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

@@ -0,0 +1,17 @@
+import type { TemplateResult } from "lit";
+import { XmField } from "../field/index.js";
+export declare class XmSwitch extends XmField {
+    /** A switch submits checked-state ("on"/null), not text — declare it a toggle
+        so the form value is correct from first paint, before any user interaction
+        (the base seeds `_checked` from the `checked` attribute and `isToggle`
+        routes it through the toggle form-value branch). */
+    protected get isToggle(): boolean;
+    private _toggleSwitch;
+    private _onKeydown;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-switch": XmSwitch;
+    }
+}

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

@@ -0,0 +1,116 @@
+/*
+  switch/index.ts — <xm-switch>, a binary on/off toggle on XmField (Story 2.7).
+
+  Shares the checkbox's toggle machinery: it subclasses XmField and overrides
+  render() for an inline track+thumb+label row (the bordered text-field chrome is
+  wrong for a compact toggle), while reusing ALL of the base's state machinery —
+  effectiveDisabled / nonInteractive, emitToggle (which owns live _checked state,
+  the form value, and the bubbling+composed `change` with detail.checked), the
+  controlAria hooks, and the helper/error message row. Nothing about disabled /
+  focus / form-association is re-implemented (AD-7).
+
+  The on-track is the single coral accent (--md-sys-color-primary); the thumb
+  slides on translateX only — short3–short4 standard easing, NO bounce / spring /
+  scale (NFR-19 / UX-DR10). Coral signals on, never severity (AD-11).
+
+  Authoring:
+    <xm-switch checked>Email notifications</xm-switch>
+    <xm-switch disabled>Locked setting</xm-switch>
+
+  Keyboard: Space toggles when focused; label/track click toggles. role="switch"
+  + aria-checked. 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 { html, nothing } from "lit";
+import { customElement } from "lit/decorators.js";
+import { XmField } from "../field/index.js";
+const SWITCH_CSS = new URL("../switch/index.css", import.meta.url).href;
+const PRIMITIVES_CSS = new URL("../primitives/index.css", import.meta.url).href;
+let XmSwitch = class XmSwitch extends XmField {
+    constructor() {
+        super(...arguments);
+        this._toggleSwitch = () => {
+            if (this.nonInteractive)
+                return;
+            this.emitToggle(!this._checked);
+        };
+        this._onKeydown = (event) => {
+            if (event.key === " " || event.key === "Spacebar") {
+                event.preventDefault();
+                this._toggleSwitch();
+            }
+        };
+    }
+    /** A switch submits checked-state ("on"/null), not text — declare it a toggle
+        so the form value is correct from first paint, before any user interaction
+        (the base seeds `_checked` from the `checked` attribute and `isToggle`
+        routes it through the toggle form-value branch). */
+    get isToggle() {
+        return true;
+    }
+    render() {
+        const cls = [
+            "switch",
+            this._checked ? "switch--on" : "",
+            this.effectiveDisabled ? "switch--disabled" : "",
+            this.isError ? "switch--error" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const helperText = this.isError ? this.error : this.helper;
+        const ctrl = this.controlAria;
+        return html `
+      <link rel="stylesheet" href="${PRIMITIVES_CSS}" />
+      <link rel="stylesheet" href="${SWITCH_CSS}" />
+      <style>
+        :host {
+          display: inline-block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div class="${cls}">
+        <div
+          class="switch__control"
+          id="${ctrl.id}"
+          role="switch"
+          aria-checked="${this._checked ? "true" : "false"}"
+          aria-describedby="${helperText ? ctrl.describedBy : nothing}"
+          aria-invalid="${ctrl.invalid ?? nothing}"
+          aria-required="${ctrl.required ?? nothing}"
+          aria-disabled="${this.effectiveDisabled ? "true" : nothing}"
+          tabindex="${this.effectiveDisabled ? -1 : 0}"
+          @click=${this._toggleSwitch}
+          @keydown=${this._onKeydown}
+        >
+          <span class="switch__track" aria-hidden="true">
+            <span class="switch__thumb"></span>
+          </span>
+          <span class="switch__label"><slot></slot></span>
+        </div>
+
+        ${helperText
+            ? html `<div
+              class="switch__message ${this.isError
+                ? "switch__message--error"
+                : "switch__message--helper"}"
+              id="${ctrl.describedBy}"
+              role=${this.isError ? "alert" : nothing}
+            >
+              ${helperText}
+            </div>`
+            : nothing}
+      </div>
+    `;
+    }
+};
+XmSwitch = __decorate([
+    customElement("xm-switch")
+], XmSwitch);
+export { XmSwitch };