@xmesh/system-design 0.0.1

package/dist/lit/components/radio-group/index.css

@@ -0,0 +1,178 @@
+/* ============================================
+   xm-radio-group + xm-radio — single-choice group (Story 2.6).
+
+   Two BEM blocks in one file (multi-element component, AD-4):
+     • `radio-group` — the form-associated value owner (extends XmField). Lays
+       out the group label, the radiogroup options column, and the helper/error
+       row. Chrome semantics (disabled / error) mirror the field family.
+     • `radio` — a selectable, presentational child: the hairline circle + coral
+       dot + label. Value/selection/disabled are driven by the group.
+
+   Surface & ink (AD-13): both ride the inverse-surface card tier — label + radio
+   text are inverse-on-surface ink; the circle hairline is outline-variant. The
+   SELECTED radio fills its dot + ring with the single coral accent
+   (--md-sys-color-primary). Coral = selection only, never severity (AD-11). The
+   error string in the message row carries severity via the warn icon + copy.
+
+   BEM blocks: `radio-group` and `radio`. Both registered in
+   scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+/* ──────────────── radio-group block ──────────────── */
+.radio-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+  width: 100%;
+}
+
+.radio-group__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);
+}
+.radio-group__label-text {
+  letter-spacing: 0;
+}
+.radio-group__required {
+  color: var(--md-sys-color-primary);
+  font-weight: 700;
+  line-height: 1;
+}
+
+.radio-group__options {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+}
+
+.radio-group__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);
+}
+.radio-group__message--helper {
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+.radio-group__message--error {
+  color: var(--md-sys-color-inverse-on-surface);
+}
+.radio-group__error-icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  margin-top: 1px;
+  color: var(--md-sys-color-inverse-on-surface);
+}
+.radio-group__message-text {
+  flex: 1;
+  min-width: 0;
+  text-wrap: pretty;
+}
+
+/* ──────────────── radio block ──────────────── */
+/* Focus ring lives on the host (the focusable element) — the inner circle gets
+   the coral halo when the host is focus-visible. */
+:host(:focus-visible) {
+  outline: none;
+}
+:host(:focus-visible) .radio__circle {
+  border-color: var(--md-sys-color-primary);
+  box-shadow: var(--xm-state-focus-ring);
+}
+
+.radio {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  cursor: pointer;
+  user-select: none;
+}
+
+.radio__circle {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  border: 1px solid var(--md-sys-color-outline-variant);
+  border-radius: var(--md-sys-shape-corner-full);
+  background: transparent;
+  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);
+}
+.radio:hover .radio__circle {
+  border-color: var(--md-sys-color-outline);
+}
+
+/* The inner dot — hidden until selected, then coral. Fades in (opacity), not a
+   scale-in reveal (POLICIES.md rule 8: no scale-in). */
+.radio__dot {
+  width: 10px;
+  height: 10px;
+  border-radius: var(--md-sys-shape-corner-full);
+  background: var(--md-sys-color-primary);
+  opacity: 0;
+  transition: opacity var(--md-sys-motion-duration-short3)
+    var(--md-sys-motion-easing-standard);
+}
+
+.radio__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;
+}
+
+/* Selected — coral ring + visible dot. */
+.radio--checked .radio__circle {
+  border-color: var(--md-sys-color-primary);
+}
+.radio--checked .radio__dot {
+  opacity: 1;
+}
+.radio--checked:hover .radio__circle {
+  border-color: var(--md-sys-color-primary);
+}
+
+/* Disabled — reduced emphasis, hover reverted, no pointer. */
+.radio--disabled {
+  cursor: not-allowed;
+}
+.radio--disabled .radio__circle {
+  opacity: 0.45;
+  box-shadow: none;
+}
+.radio--disabled .radio__label {
+  color: var(--xm-color-inverse-on-surface-disabled);
+}
+.radio--disabled:hover .radio__circle {
+  border-color: var(--md-sys-color-outline-variant);
+}
+.radio--disabled.radio--checked:hover .radio__circle {
+  border-color: var(--md-sys-color-primary);
+}
+
+/* Group disabled cascades to the option text + label. */
+.radio-group--disabled .radio-group__label {
+  color: var(--xm-color-inverse-on-surface-disabled);
+}

package/dist/lit/components/radio-group/index.d.ts

@@ -0,0 +1,35 @@
+import { LitElement } from "lit";
+import type { PropertyValues, TemplateResult } from "lit";
+import { XmField } from "../field/index.js";
+export declare class XmRadio extends LitElement {
+    /** The primitive value this radio contributes to the group when selected. */
+    value: string;
+    /** Own disabled — OR'd with the group's disabled by the group. */
+    disabled: boolean;
+    /** Driven by the group; never set directly by authors. */
+    checked: boolean;
+    /** Effective disabled the group computes (group OR own). */
+    groupDisabled: boolean;
+    get effectiveDisabled(): boolean;
+    render(): TemplateResult;
+}
+export declare class XmRadioGroup extends XmField {
+    private get _radios();
+    private get _enabledRadios();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues<this>): void;
+    /** Reflect the group's selected value + disabled onto each child, and set the
+        roving tabindex (selected, else first enabled, is the only tab stop). */
+    private _syncRadios;
+    private _select;
+    private _onClick;
+    private _onKeydown;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-radio": XmRadio;
+        "xm-radio-group": XmRadioGroup;
+    }
+}

package/dist/lit/components/radio-group/index.js

@@ -0,0 +1,292 @@
+/*
+  radio-group/index.ts — <xm-radio-group> + <xm-radio> (Story 2.6).
+
+  A multi-element component (AD-4 / NFR-4): one folder, two custom elements.
+
+    <xm-radio-group label="Plan" value="pro" name="plan">
+      <xm-radio value="free">Free</xm-radio>
+      <xm-radio value="pro">Pro</xm-radio>
+      <xm-radio value="team" disabled>Team</xm-radio>
+    </xm-radio-group>
+
+  Value ownership lives on the GROUP, never the children (AD-6a / AD-12): the
+  group extends XmField, so it owns the chrome (label / helper / error / disabled)
+  AND the form association — xm-form reads the GROUP's public `value` getter, not
+  any radio's shadow root. An <xm-radio> is a presentational, selectable child:
+  it renders the coral ring/dot + label and reports `role="radio"` + aria-checked,
+  but it does not register itself with the form.
+
+  Keyboard (radiogroup APG, AD-9a): roving tabindex — only the selected (else the
+  first enabled) radio is in the tab order. Inside the group ↑/↓/←/→ move AND
+  select the next/previous enabled radio (wrapping), Home/End jump to first/last
+  enabled, Space selects the focused radio. Selection commits emit `change` with
+  detail.value = the selected radio's PRIMITIVE value (AD-8a).
+
+  Disabled is OR-propagated (AD-6a): a radio is disabled if the GROUP is disabled
+  OR the radio sets its own `disabled` — neither can re-enable the other.
+
+  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, nothing } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { XmField } from "../field/index.js";
+const RADIO_CSS = new URL("../radio-group/index.css", import.meta.url).href;
+const PRIMITIVES_CSS = new URL("../primitives/index.css", import.meta.url).href;
+/* ── <xm-radio> — selectable, presentational child ──────────────────── */
+let XmRadio = class XmRadio extends LitElement {
+    constructor() {
+        super(...arguments);
+        /** The primitive value this radio contributes to the group when selected. */
+        this.value = "";
+        /** Own disabled — OR'd with the group's disabled by the group. */
+        this.disabled = false;
+        /** Driven by the group; never set directly by authors. */
+        this.checked = false;
+        /** Effective disabled the group computes (group OR own). */
+        this.groupDisabled = false;
+    }
+    get effectiveDisabled() {
+        return this.disabled || this.groupDisabled;
+    }
+    render() {
+        const cls = [
+            "radio",
+            this.checked ? "radio--checked" : "",
+            this.effectiveDisabled ? "radio--disabled" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        return html `
+      <link rel="stylesheet" href="${PRIMITIVES_CSS}" />
+      <link rel="stylesheet" href="${RADIO_CSS}" />
+      <style>
+        :host {
+          display: inline-flex;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <span class="${cls}">
+        <span class="radio__circle" aria-hidden="true">
+          <span class="radio__dot"></span>
+        </span>
+        <span class="radio__label"><slot></slot></span>
+      </span>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmRadio.prototype, "value", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmRadio.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmRadio.prototype, "checked", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: "group-disabled" })
+], XmRadio.prototype, "groupDisabled", void 0);
+XmRadio = __decorate([
+    customElement("xm-radio")
+], XmRadio);
+export { XmRadio };
+/* ── <xm-radio-group> — the form-associated value owner ─────────────── */
+let XmRadioGroup = class XmRadioGroup extends XmField {
+    constructor() {
+        super(...arguments);
+        this._onClick = (e) => {
+            if (this.effectiveDisabled)
+                return;
+            const radio = e.target.closest("xm-radio");
+            if (radio && this._radios.includes(radio))
+                this._select(radio);
+        };
+        this._onKeydown = (e) => {
+            if (this.effectiveDisabled)
+                return;
+            const enabled = this._enabledRadios;
+            if (enabled.length === 0)
+                return;
+            const current = e.target.closest("xm-radio");
+            const curIdx = current ? enabled.indexOf(current) : -1;
+            switch (e.key) {
+                case "ArrowDown":
+                case "ArrowRight": {
+                    e.preventDefault();
+                    const next = enabled[(curIdx + 1 + enabled.length) % enabled.length];
+                    if (next)
+                        this._select(next);
+                    break;
+                }
+                case "ArrowUp":
+                case "ArrowLeft": {
+                    e.preventDefault();
+                    const prev = enabled[(curIdx - 1 + enabled.length) % enabled.length];
+                    if (prev)
+                        this._select(prev);
+                    break;
+                }
+                case "Home": {
+                    e.preventDefault();
+                    const first = enabled[0];
+                    if (first)
+                        this._select(first);
+                    break;
+                }
+                case "End": {
+                    e.preventDefault();
+                    const last = enabled[enabled.length - 1];
+                    if (last)
+                        this._select(last);
+                    break;
+                }
+                case " ":
+                case "Spacebar": {
+                    e.preventDefault();
+                    if (current)
+                        this._select(current);
+                    break;
+                }
+            }
+        };
+    }
+    get _radios() {
+        return Array.from(this.querySelectorAll("xm-radio"));
+    }
+    get _enabledRadios() {
+        return this._radios.filter((r) => !r.disabled && !this.effectiveDisabled);
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener("keydown", this._onKeydown);
+        this.addEventListener("click", this._onClick);
+        // Radios may upgrade after the group connects; sync on the next frame.
+        this.updateComplete.then(() => this._syncRadios());
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener("keydown", this._onKeydown);
+        this.removeEventListener("click", this._onClick);
+    }
+    updated(changed) {
+        super.updated?.(changed);
+        this._syncRadios();
+    }
+    /** Reflect the group's selected value + disabled onto each child, and set the
+        roving tabindex (selected, else first enabled, is the only tab stop). */
+    _syncRadios() {
+        const radios = this._radios;
+        if (radios.length === 0)
+            return;
+        const selected = radios.find((r) => r.value === this._value) ?? null;
+        const firstEnabled = radios.find((r) => !r.disabled && !this.effectiveDisabled);
+        const tabTarget = selected && !selected.disabled ? selected : firstEnabled;
+        for (const r of radios) {
+            r.groupDisabled = this.effectiveDisabled;
+            r.checked = r === selected;
+            r.setAttribute("role", "radio");
+            r.setAttribute("aria-checked", r.checked ? "true" : "false");
+            if (r.effectiveDisabled)
+                r.setAttribute("aria-disabled", "true");
+            else
+                r.removeAttribute("aria-disabled");
+            const focusable = r === tabTarget && !r.effectiveDisabled;
+            r.tabIndex = focusable ? 0 : -1;
+        }
+    }
+    _select(radio, focus = true) {
+        if (radio.effectiveDisabled)
+            return;
+        if (radio.value === this._value) {
+            if (focus)
+                radio.focus();
+            return;
+        }
+        this._value = radio.value;
+        this.internals.setFormValue(this._value);
+        this._syncRadios();
+        if (focus)
+            radio.focus();
+        this.dispatchEvent(new CustomEvent("change", {
+            bubbles: true,
+            composed: true,
+            detail: { value: radio.value },
+        }));
+    }
+    render() {
+        const cls = [
+            "radio-group",
+            this.effectiveDisabled ? "radio-group--disabled" : "",
+            this.isError ? "radio-group--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="${RADIO_CSS}" />
+      <style>
+        :host {
+          display: block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div class="${cls}">
+        ${this.label
+            ? html `<span class="radio-group__label" id="${ctrl.id}-label">
+              <span class="radio-group__label-text">${this.label}</span>
+              ${this.required
+                ? html `<span class="radio-group__required" aria-hidden="true"
+                    >*</span
+                  >`
+                : nothing}
+            </span>`
+            : nothing}
+
+        <div
+          class="radio-group__options"
+          role="radiogroup"
+          aria-labelledby="${this.label ? `${ctrl.id}-label` : nothing}"
+          aria-label="${this.label ? nothing : "Options"}"
+          aria-describedby="${helperText ? ctrl.describedBy : nothing}"
+          aria-invalid="${ctrl.invalid ?? nothing}"
+          aria-required="${ctrl.required ?? nothing}"
+        >
+          <slot @slotchange=${() => this._syncRadios()}></slot>
+        </div>
+
+        ${helperText
+            ? html `<div
+              class="radio-group__message ${this.isError
+                ? "radio-group__message--error"
+                : "radio-group__message--helper"}"
+              id="${ctrl.describedBy}"
+              role=${this.isError ? "alert" : nothing}
+            >
+              ${this.isError
+                ? html `<span class="radio-group__error-icon" aria-hidden="true">
+                    <xm-warn-icon size="14"></xm-warn-icon>
+                  </span>`
+                : nothing}
+              <span class="radio-group__message-text">${helperText}</span>
+            </div>`
+            : nothing}
+      </div>
+    `;
+    }
+};
+XmRadioGroup = __decorate([
+    customElement("xm-radio-group")
+], XmRadioGroup);
+export { XmRadioGroup };

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

@@ -0,0 +1,151 @@
+/* ============================================
+   xm-select — single-select dropdown for XmField (Story 2.3).
+
+   Composes XmField (chrome) + xm-overlay (anchored listbox). This file styles
+   ONLY the bespoke parts: the closed control (a full-bleed <button> inside the
+   base's .field__control wrapper), the chevron, and the listbox panel content
+   projected into the overlay. Positioning / elevation of the panel surface is
+   owned by xm-overlay; here we style the option rows inside it.
+
+   Surface & ink (AD-13):
+     • Closed control rides the inverse-surface card tier → inverse-on-surface
+       ink, inverse-on-surface-muted for the placeholder.
+     • The listbox rows sit on the overlay's inverse-surface panel → ink stays
+       inverse-on-surface; hover uses the MD3 state layer.
+     • The SELECTED option tints with the coral primary-container and pairs
+       on-primary-container ink (matching that surface). Coral = selection only,
+       never severity (AD-11).
+
+   BEM block: `select`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+/* ---------- Closed control — full-bleed button in the field wrapper ---------- */
+.select__control {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  appearance: none;
+  border: none;
+  outline: none;
+  background: transparent;
+  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);
+  padding: 0 var(--s-3);
+  text-align: left;
+  cursor: pointer;
+}
+.select__control:disabled {
+  cursor: not-allowed;
+}
+
+/* ---------- Value / placeholder ---------- */
+.select__value {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.select__value--placeholder {
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+
+/* ---------- Chevron — rotates on open (short3, standard) ---------- */
+.select__chevron {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--md-sys-color-inverse-on-surface);
+  transition: transform var(--md-sys-motion-duration-short3)
+    var(--md-sys-motion-easing-standard);
+}
+.select__chevron--open {
+  transform: rotate(180deg);
+}
+
+/* ---------- Listbox panel content (inside the overlay) ---------- */
+.select__listbox {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-0-5);
+  min-width: 180px;
+  max-height: 320px;
+  overflow-y: auto;
+}
+
+/* ---------- Option rows ---------- */
+.select__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;
+}
+.select__option-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.select__option-check {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--md-sys-color-primary);
+}
+
+/* Active (keyboard / pointer hover) — the MD3 state layer over the panel ink. */
+.select__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 + on-primary-container ink (AD-13). */
+.select__option--selected {
+  background: var(--md-sys-color-primary-container);
+  color: var(--md-sys-color-on-primary-container);
+}
+.select__option--selected .select__option-check {
+  color: var(--md-sys-color-on-primary-container);
+}
+/* Selected AND active — keep the coral identity, lift slightly via the state
+   layer so the keyboard focus is still legible on the tint. */
+.select__option--selected.select__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)
+  );
+}
+
+/* Disabled option — reduced emphasis, no pointer. */
+.select__option--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}