@xmesh/system-design 0.0.1

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

@@ -0,0 +1,166 @@
+/* ============================================
+   Artifact — Claude-style side-panel viewer.
+
+   Canvas-surface panel that lives in the artifact
+   column of chat.html, or standalone in
+   preview/artifact.html. Header (provider chip +
+   segmented eye/code toggle + title/sub +
+   action cluster) over a scrollable body.
+
+   The panel rides `surface-container-high` in both
+   themes — same family as the chat shell's sidebar/
+   topbar. Surface-rooted means text tokens come
+   from `on-surface*` (POLICIES rule 7a). The
+   primitives flip in light theme via
+   _primitives.css, so a single set of rules covers
+   both modes. Mirrors the .bubble.bot pattern.
+   ============================================ */
+
+.artifact {
+  background: var(--md-sys-color-surface-container-high);
+  border: 0;
+  border-left: 1px solid var(--md-sys-color-outline);
+  border-radius: 0;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  overflow: hidden;
+  color: var(--md-sys-color-on-surface);
+}
+
+/* ---------- Head ----------
+   Padding + min-height match preview/chat.html `.top` so the chat
+   topbar and artifact head render at identical heights when both
+   are visible. */
+.artifact__head {
+  display: flex;
+  align-items: center;
+  gap: var(--s-3);
+  padding: var(--s-3) var(--s-5);
+  min-height: 56px;
+  box-sizing: border-box;
+  flex-shrink: 0;
+  /* Hairline seam so the header reads as a band over the body instead of
+     floating; outline-variant is the soft internal divider weight. */
+  border-bottom: 1px solid var(--md-sys-color-outline-variant);
+}
+
+.artifact__head-left {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  flex-shrink: 0;
+}
+
+.artifact__head-mid {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-1);
+  min-width: 0;
+  flex: 1;
+}
+
+.artifact__head-right {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-1-5);
+  flex-shrink: 0;
+}
+
+.artifact__title {
+  font: 600 15px/1.2 var(--md-sys-typescale-body-large-font);
+  color: var(--md-sys-color-on-surface);
+  letter-spacing: -0.01em;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.artifact__sub {
+  font: 400 11px/1 var(--xm-typescale-mono-font);
+  color: var(--xm-color-on-surface-soft);
+  font-feature-settings: "tnum";
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-1-5);
+  flex-wrap: nowrap;
+  white-space: nowrap;
+}
+.artifact__sub > span { white-space: nowrap; }
+/* Inline middot dividers come from the .ds-sep primitive (primitives/index.css);
+   no per-component override needed. */
+
+/* ---------- View toggle (eye / code) ---------- */
+.artifact__view-toggle {
+  display: inline-flex;
+  align-items: center;
+  padding: var(--s-0-5);
+  background: color-mix(in oklab, var(--md-sys-color-on-surface) 8%, transparent);
+  border-radius: 8px;
+  gap: var(--s-0-5);
+}
+
+/* ---------- Body ---------- */
+.artifact__body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  scrollbar-gutter: stable;
+  /* Horizontal inset matches .artifact__head (--s-5) so the title and the
+     first line of body copy share one left edge. */
+  padding: var(--s-5) var(--s-5) var(--s-6);
+  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);
+  color: var(--md-sys-color-on-surface);
+}
+
+.artifact__body :where(h1, h2, h3, h4) {
+  color: var(--md-sys-color-on-surface);
+  letter-spacing: -0.01em;
+  margin: var(--s-4-5) 0 var(--s-2);
+}
+.artifact__body h1 { font: 600 20px/1.25 var(--md-sys-typescale-body-large-font); }
+.artifact__body h2 { font: 600 16px/1.3  var(--md-sys-typescale-body-large-font); }
+.artifact__body h3 { font: 600 14px/1.3  var(--md-sys-typescale-body-large-font); }
+.artifact__body :where(h1, h2, h3, h4):first-child { margin-top: 0; }
+
+.artifact__body p { margin: 0 0 var(--s-3); }
+.artifact__body ul,
+.artifact__body ol { margin: 0 0 var(--s-3); padding-left: var(--s-5-5); }
+.artifact__body li { margin: var(--s-1) 0; }
+.artifact__body strong { color: var(--md-sys-color-on-surface); font-weight: 600; }
+.artifact__body em { font-style: italic; color: var(--md-sys-color-on-surface); }
+.artifact__body code {
+  font: 500 12.5px/1.4 var(--xm-typescale-mono-font);
+  padding: 0;
+  background: transparent;
+  color: var(--md-sys-color-on-surface);
+}
+
+.artifact__body pre {
+  font: 500 12.5px/1.55 var(--xm-typescale-mono-font);
+  color: var(--md-sys-color-on-surface);
+  background: color-mix(in oklab, var(--md-sys-color-on-surface) 6%, transparent);
+  border: 1px solid color-mix(in oklab, var(--md-sys-color-on-surface) 10%, transparent);
+  border-radius: var(--md-sys-shape-corner-extra-small);
+  padding: var(--s-3) var(--s-4);
+  margin: var(--s-3) 0;
+  white-space: pre-wrap;
+  overflow-x: auto;
+  font-feature-settings: "tnum";
+}
+.artifact__body pre code {
+  font: inherit;
+  color: inherit;
+}
+
+.artifact__body blockquote {
+  margin: var(--s-3) 0;
+  padding-left: var(--s-3);
+  border-left: 2px solid color-mix(in oklab, var(--md-sys-color-on-surface) 30%, transparent);
+  color: var(--xm-color-on-surface-soft);
+  font-style: italic;
+}

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

@@ -0,0 +1,37 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+import "../button/index.js";
+type ArtifactView = "preview" | "code";
+declare class XmArtifact extends LitElement {
+    title: string;
+    sub: string[] | null;
+    subCsv: string;
+    view: ArtifactView;
+    showRefresh: boolean;
+    showClose: boolean;
+    private _bodies;
+    private _uid;
+    createRenderRoot(): HTMLElement | DocumentFragment;
+    connectedCallback(): void;
+    /**
+     * Imperatively set the preview/code body nodes from a host. Replaces any
+     * authored or previously-set bodies. Used by <xm-chat-shell> to hand the
+     * panel its slot content; the chat shell can't author them as direct
+     * children of the lit-rendered <xm-artifact> tag without the snapshot
+     * timing race that this method sidesteps.
+     */
+    setBodies(preview: ChildNode[], code: ChildNode[]): void;
+    private _setView;
+    private _onTabKeydown;
+    private _onRefresh;
+    private _onClose;
+    private _subItems;
+    render(): TemplateResult;
+    updated(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-artifact": XmArtifact;
+    }
+}
+export {};

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

@@ -0,0 +1,294 @@
+/*
+  artifact/index.ts — Lit port of components/artifact/index.jsx.
+
+  <xm-artifact> — Claude-style side-panel viewer.
+
+  Authoring:
+    <xm-artifact title="..." sub-csv="Document,MD" show-refresh show-close>
+      <div data-view="preview">  ...html body for preview... </div>
+      <div data-view="code">     ...html body for code...    </div>
+    </xm-artifact>
+
+    The component shows whichever child matches the active `view`.
+    Children without a data-view attribute are treated as `preview`
+    (single-body case).
+
+  Properties:
+    title          string
+    sub            string[]                — preferred (set via JS)
+    sub-csv        string                  — comma-separated convenience
+                                              attribute for static HTML
+    view           "preview" | "code"      — controlled when host listens
+                                              for `view-change`; otherwise
+                                              local state from initial value
+    showRefresh    boolean                 — render the refresh button
+    showClose      boolean                 — render the close button
+
+  Events:
+    view-change    detail: { view: "preview" | "code" }
+    refresh
+    close
+
+  Light DOM. components/artifact/index.css + components/button/index.css +
+  components/primitives/index.css must be loaded in the host page.
+*/
+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, state } from "lit/decorators.js";
+// Side-effect import: registers <xm-button> for use in the head toolbar.
+import "../button/index.js";
+const ICON_EYE = (size = 14) => svg `
+  <svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none"
+       stroke="currentColor" stroke-width="1.8" stroke-linecap="round"
+       stroke-linejoin="round" class="ds-icon">
+    <path d="M2 12s4-7 10-7 10 7 10 7-4 7-10 7S2 12 2 12z" />
+    <circle cx="12" cy="12" r="3" />
+  </svg>
+`;
+const ICON_CODE = (size = 14) => svg `
+  <svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none"
+       stroke="currentColor" stroke-width="1.9" stroke-linecap="round"
+       stroke-linejoin="round" class="ds-icon">
+    <polyline points="16 18 22 12 16 6" />
+    <polyline points="8 6 2 12 8 18" />
+  </svg>
+`;
+const ICON_REFRESH = () => svg `
+  <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+       stroke="currentColor" stroke-width="1.8" stroke-linecap="round"
+       stroke-linejoin="round" class="ds-icon">
+    <path d="M21 12a9 9 0 1 1-3-6.7" />
+    <path d="M21 4v5h-5" />
+  </svg>
+`;
+const ICON_CLOSE = () => svg `
+  <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+       stroke="currentColor" stroke-width="2" stroke-linecap="round"
+       stroke-linejoin="round" class="ds-icon">
+    <path d="M6 6l12 12M18 6L6 18" />
+  </svg>
+`;
+let artifactInstance = 0;
+let XmArtifact = class XmArtifact extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.title = "";
+        this.sub = null;
+        this.subCsv = "";
+        this.view = "preview";
+        this.showRefresh = false;
+        this.showClose = false;
+        this._bodies = { preview: [], code: [] };
+        this._uid = `artifact-${++artifactInstance}`;
+        this._setView = (v) => {
+            if (this.view === v)
+                return;
+            // Always update internal state; consumers that prefer "controlled" mode
+            // can still listen for view-change to react.
+            this.view = v;
+            this.dispatchEvent(new CustomEvent("view-change", { detail: { view: v }, bubbles: true, composed: true }));
+        };
+        this._onTabKeydown = (e) => {
+            const k = e.key;
+            if (k !== "ArrowLeft" && k !== "ArrowRight" && k !== "Home" && k !== "End")
+                return;
+            e.preventDefault();
+            const next = k === "Home" ? "preview" :
+                k === "End" ? "code" :
+                    this.view === "preview" ? "code" : "preview";
+            this._setView(next);
+            // Move focus to the newly-selected tab once render lands.
+            requestAnimationFrame(() => {
+                this.querySelector(`.artifact__view-btn[data-view="${next}"]`)?.focus();
+            });
+        };
+        this._onRefresh = () => {
+            this.dispatchEvent(new CustomEvent("refresh", { bubbles: true, composed: true }));
+        };
+        this._onClose = () => {
+            this.dispatchEvent(new CustomEvent("close", { bubbles: true, composed: true }));
+        };
+    }
+    createRenderRoot() {
+        return this;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // Make the host transparent to the parent's grid/flex layout so the
+        // inner <section class="artifact"> behaves as the direct child. This
+        // matters for selectors like `.chat-shell__artifact-slot > .artifact`
+        // in components/chat/index.css.
+        if (!this.style.display)
+            this.style.display = "contents";
+        // Snapshot authored bodies by data-view; remove from DOM so lit's
+        // render() doesn't replace them mid-flight. We re-attach in updated().
+        const preview = [];
+        const code = [];
+        for (const child of Array.from(this.childNodes)) {
+            if (child.nodeType !== Node.ELEMENT_NODE) {
+                if (child.nodeType === Node.TEXT_NODE && !child.textContent?.trim()) {
+                    // strip whitespace-only text — they'd otherwise bucket into preview
+                    continue;
+                }
+                preview.push(child);
+                continue;
+            }
+            const v = child.getAttribute("data-view");
+            if (v === "code")
+                code.push(child);
+            else
+                preview.push(child);
+        }
+        for (const n of [...preview, ...code])
+            n.remove();
+        this._bodies = { preview, code };
+    }
+    /**
+     * Imperatively set the preview/code body nodes from a host. Replaces any
+     * authored or previously-set bodies. Used by <xm-chat-shell> to hand the
+     * panel its slot content; the chat shell can't author them as direct
+     * children of the lit-rendered <xm-artifact> tag without the snapshot
+     * timing race that this method sidesteps.
+     */
+    setBodies(preview, code) {
+        this._bodies = { preview: preview.slice(), code: code.slice() };
+        this.requestUpdate();
+    }
+    _subItems() {
+        if (Array.isArray(this.sub) && this.sub.length)
+            return this.sub;
+        if (this.subCsv)
+            return this.subCsv.split(",").map((s) => s.trim()).filter(Boolean);
+        return [];
+    }
+    render() {
+        const sub = this._subItems();
+        const v = this.view === "code" ? "code" : "preview";
+        const previewTabId = `${this._uid}-tab-preview`;
+        const codeTabId = `${this._uid}-tab-code`;
+        const bodyId = `${this._uid}-body`;
+        return html `
+      <section class="artifact" aria-label="${this.title || "Artifact"}">
+        <header class="artifact__head">
+          <div class="artifact__head-left">
+            <div
+              class="artifact__view-toggle"
+              role="tablist"
+              aria-label="Artifact view"
+              @keydown=${this._onTabKeydown}
+            >
+              <xm-button
+                id="${previewTabId}"
+                variant="ghost"
+                size="sm"
+                icon-only
+                ?selected=${v === "preview"}
+                role="tab"
+                data-view="preview"
+                aria-selected="${v === "preview"}"
+                aria-controls="${bodyId}"
+                tabindex="${v === "preview" ? 0 : -1}"
+                class="artifact__view-btn"
+                title="Preview"
+                @click=${() => this._setView("preview")}
+              >${ICON_EYE()}</xm-button>
+              <xm-button
+                id="${codeTabId}"
+                variant="ghost"
+                size="sm"
+                icon-only
+                ?selected=${v === "code"}
+                role="tab"
+                data-view="code"
+                aria-selected="${v === "code"}"
+                aria-controls="${bodyId}"
+                tabindex="${v === "code" ? 0 : -1}"
+                class="artifact__view-btn"
+                title="Source"
+                @click=${() => this._setView("code")}
+              >${ICON_CODE()}</xm-button>
+            </div>
+          </div>
+
+          <div class="artifact__head-mid">
+            ${this.title
+            ? html `<span class="artifact__title">${this.title}</span>`
+            : nothing}
+            ${sub.length
+            ? html `<span class="artifact__sub">
+                  ${sub.map((s, i) => html `
+                    ${i > 0 ? html `<span class="ds-sep">·</span>` : nothing}
+                    <span>${s}</span>
+                  `)}
+                </span>`
+            : nothing}
+          </div>
+
+          <div class="artifact__head-right">
+            ${this.showClose
+            ? html `<xm-button
+                       variant="ghost"
+                       size="sm"
+                       icon-only
+                       aria-label="Close artifact"
+                       title="Close"
+                       @click=${this._onClose}
+                     >${ICON_CLOSE()}</xm-button>`
+            : nothing}
+          </div>
+        </header>
+
+        <div
+          id="${bodyId}"
+          role="tabpanel"
+          aria-labelledby="${v === "code" ? codeTabId : previewTabId}"
+          class="artifact__body scroll-canvas"
+          data-mount="body"
+        ></div>
+      </section>
+    `;
+    }
+    updated() {
+        const host = this.querySelector('[data-mount="body"]');
+        if (!host)
+            return;
+        const v = this.view === "code" ? "code" : "preview";
+        const wanted = this._bodies[v] || [];
+        // _bodies is the source of truth — the arrays still reference any
+        // currently-mounted nodes, since appendChild moves rather than copies.
+        // Just clear the host and re-mount the active view.
+        while (host.firstChild)
+            host.firstChild.remove();
+        for (const n of wanted)
+            host.appendChild(n);
+    }
+};
+__decorate([
+    property({ type: String })
+], XmArtifact.prototype, "title", void 0);
+__decorate([
+    property({ attribute: false })
+], XmArtifact.prototype, "sub", void 0);
+__decorate([
+    property({ type: String, attribute: "sub-csv" })
+], XmArtifact.prototype, "subCsv", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], XmArtifact.prototype, "view", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "show-refresh" })
+], XmArtifact.prototype, "showRefresh", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "show-close" })
+], XmArtifact.prototype, "showClose", void 0);
+__decorate([
+    state()
+], XmArtifact.prototype, "_bodies", void 0);
+XmArtifact = __decorate([
+    customElement("xm-artifact")
+], XmArtifact);

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

@@ -0,0 +1,171 @@
+/* ============================================
+   xm-autocomplete — filtering select for XmField (Story 2.4).
+
+   Same composition as xm-select: XmField (chrome) + xm-overlay (anchored
+   listbox). This file styles ONLY the bespoke parts — the text-input control
+   row + chevron, the option rows + match highlight, and the inline no-match
+   empty-state. Positioning / elevation of the panel surface is owned by
+   xm-overlay.
+
+   Surface & ink (AD-13): control + panel ride the inverse-surface card tier →
+   inverse-on-surface ink, on-surface-variant placeholder. The SELECTED option
+   tints coral primary-container + on-primary-container ink. The match highlight
+   carries coral ink AND an underline so the cue survives grayscale — color is
+   never the sole carrier (NFR-15). Coral = selection / match, never severity
+   (AD-11).
+
+   BEM block: `autocomplete`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+/* ---------- Control row — text input + chevron in the field wrapper ---------- */
+.autocomplete__control {
+  display: flex;
+  align-items: center;
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+  height: 100%;
+}
+
+/* The native <input> is already transparent / full-bleed via the base
+   `.field__control input` rule; here only the trailing chevron needs room. */
+.autocomplete__input {
+  flex: 1;
+  min-width: 0;
+}
+
+.autocomplete__chevron {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  padding-right: var(--s-3);
+  color: var(--md-sys-color-inverse-on-surface);
+  transition: transform var(--md-sys-motion-duration-short3)
+    var(--md-sys-motion-easing-standard);
+}
+.autocomplete__chevron--open {
+  transform: rotate(180deg);
+}
+
+/* ---------- Listbox panel content (inside the overlay) ---------- */
+.autocomplete__listbox {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-0-5);
+  min-width: 220px;
+  max-height: 320px;
+  overflow-y: auto;
+}
+
+.autocomplete__option {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  padding: var(--s-2) var(--s-3);
+  border-radius: var(--md-sys-shape-corner-small);
+  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);
+  cursor: pointer;
+  user-select: none;
+}
+.autocomplete__option-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.autocomplete__option-check {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--md-sys-color-primary);
+}
+
+/* Match highlight — coral ink + underline (dual cue, NFR-15). Background stays
+   transparent so it reads on both the panel ink and the selected coral tint. */
+.autocomplete__mark {
+  background: transparent;
+  color: var(--md-sys-color-primary);
+  font-weight: 600;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+/* Active (keyboard / hover) — MD3 state layer over the panel ink. */
+.autocomplete__option--active {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-inverse-on-surface)
+      var(--md-sys-state-hover-state-layer-opacity),
+    transparent
+  );
+}
+
+/* Selected — coral primary-container tint + paired ink (AD-13). */
+.autocomplete__option--selected {
+  background: var(--md-sys-color-primary-container);
+  color: var(--md-sys-color-on-primary-container);
+}
+.autocomplete__option--selected .autocomplete__option-check {
+  color: var(--md-sys-color-on-primary-container);
+}
+.autocomplete__option--selected .autocomplete__mark {
+  color: var(--md-sys-color-on-primary-container);
+}
+.autocomplete__option--selected.autocomplete__option--active {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-on-primary-container)
+      var(--md-sys-state-hover-state-layer-opacity),
+    var(--md-sys-color-primary-container)
+  );
+}
+
+.autocomplete__option--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* ---------- No-match empty-state (inline; → xm-empty-state in Epic 4) ---------- */
+.autocomplete__empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  gap: var(--s-1);
+  padding: var(--s-5) var(--s-4);
+  min-width: 220px;
+}
+.autocomplete__empty-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: var(--s-1);
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+.autocomplete__empty-title {
+  margin: 0;
+  color: var(--md-sys-color-inverse-on-surface);
+  font:
+    var(--md-sys-typescale-title-small-weight)
+    var(--md-sys-typescale-title-small-size) /
+    var(--md-sys-typescale-title-small-line-height)
+    var(--md-sys-typescale-title-small-font);
+}
+.autocomplete__empty-copy {
+  margin: 0;
+  color: var(--xm-color-inverse-on-surface-muted);
+  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);
+}