@xmesh/system-design 0.0.1

package/dist/lit/components/sidebar-item/index.js

@@ -0,0 +1,105 @@
+/*
+  sidebar-item/index.ts — Lit port of components/sidebar-item/index.jsx.
+
+  <xm-sidebar-item> — chat-list row in the sidebar.
+
+  Properties:
+    title       string  — row label
+    layout      "row" | "stacked"            (default "row")
+    active      boolean
+    hover       boolean — preview-only force state
+    showDot     boolean — render the leading accent dot in row layout
+    collapsed   boolean — render the 4px stripe rail (icon-only mode)
+
+  Click events:
+    Listen for native `click` on the element. The component renders a
+    role="button" div that fires the standard click event; consumers can
+    do `el.addEventListener("click", …)` or `@click` from a parent.
+
+  Light DOM. Existing components/sidebar-item/index.css owns all visuals.
+*/
+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";
+let XmSidebarItem = class XmSidebarItem extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.title = "";
+        this.layout = "row";
+        this.active = false;
+        this.hover = false;
+        this.showDot = false;
+        this.collapsed = false;
+    }
+    createRenderRoot() {
+        return this;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // Make the host transparent to flex layout so the inner .sidebar-item
+        // is what the parent panel measures — matches the React tree where
+        // <SidebarItem> renders the <div class="sidebar-item"> directly.
+        if (!this.style.display)
+            this.style.display = "contents";
+    }
+    render() {
+        if (this.collapsed) {
+            const cls = `sidebar-item sidebar-item--collapsed ${this.active ? "is-active" : ""}`
+                .replace(/\s+/g, " ").trim();
+            return html `
+        <div
+          class="${cls}"
+          role="button"
+          tabindex="0"
+          title="${this.title}"
+        ></div>
+      `;
+        }
+        const stateClass = [
+            this.active && "is-active",
+            this.hover && "is-hover",
+            this.showDot && "has-dot",
+        ].filter(Boolean).join(" ");
+        const cls = `sidebar-item sidebar-item--${this.layout} ${stateClass}`
+            .replace(/\s+/g, " ").trim();
+        if (this.layout === "stacked") {
+            return html `
+        <div class="${cls}" role="button" tabindex="0" title="${this.title}">
+          <span class="sidebar-item__title">${this.title}</span>
+        </div>
+      `;
+        }
+        return html `
+      <div class="${cls}" role="button" tabindex="0" title="${this.title}">
+        <span class="sidebar-item__dot" aria-hidden="${this.showDot ? "false" : "true"}"></span>
+        <span class="sidebar-item__title">${this.title}</span>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmSidebarItem.prototype, "title", void 0);
+__decorate([
+    property({ type: String })
+], XmSidebarItem.prototype, "layout", void 0);
+__decorate([
+    property({ type: Boolean })
+], XmSidebarItem.prototype, "active", void 0);
+__decorate([
+    property({ type: Boolean })
+], XmSidebarItem.prototype, "hover", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "show-dot" })
+], XmSidebarItem.prototype, "showDot", void 0);
+__decorate([
+    property({ type: Boolean })
+], XmSidebarItem.prototype, "collapsed", void 0);
+XmSidebarItem = __decorate([
+    customElement("xm-sidebar-item")
+], XmSidebarItem);

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

@@ -0,0 +1,81 @@
+/* ============================================
+   Skeleton — gradient-free loading placeholder.
+
+   The pulse is a calm OPACITY animation on a neutral surface fill — a
+   color-mix between two surface-container tiers. There is NO shimmer /
+   sweep gradient anywhere (FR-147 / A10): the snackbar scrim is the
+   system's only sanctioned gradient. The animation honors
+   prefers-reduced-motion.
+
+   The fill is neutral chrome — no accent, no severity hue (AD-11). It
+   sits on the host surface family it's placed in; the surface-container
+   tiers read on both the desk and the inverse card stack, in both themes
+   (AD-13).
+
+   BEM block: `skeleton`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   Elements: __shape (one placeholder), __line (a text line). Modifiers:
+   --line / --block / --circle.
+   ============================================ */
+
+.skeleton {
+  display: block;
+  width: 100%;
+}
+
+/* Line variant stacks its text lines with a consistent gap. */
+.skeleton--line {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+}
+
+.skeleton__shape {
+  display: block;
+  /* Neutral fill — a color-mix between two surface-container tiers. This is
+     a flat fill, NOT a gradient: there is no shimmer sweep, no linear- /
+     radial-gradient. The pulse comes from the opacity animation below. */
+  background: color-mix(
+    in oklch,
+    var(--md-sys-color-surface-container-high) 60%,
+    var(--md-sys-color-surface-container-highest)
+  );
+  border-radius: var(--md-sys-shape-corner-small);
+  /* Calm pulse: alternate opacity, slow tempo, standard easing. */
+  animation: skeleton-pulse var(--md-sys-motion-duration-extra-long2)
+    var(--md-sys-motion-easing-standard) infinite alternate;
+}
+
+/* A single text line — height from the body typescale, full width by default
+   (the element narrows the last line of a paragraph via inline width). */
+.skeleton__line {
+  height: 0.85em;
+  width: 100%;
+}
+
+/* Block — arbitrary rectangle (card / image placeholder). */
+.skeleton--block .skeleton__shape {
+  height: 120px;
+  border-radius: var(--md-sys-shape-corner-medium);
+}
+
+/* Circle — avatar / icon placeholder. */
+.skeleton--circle .skeleton__shape {
+  width: 40px;
+  height: 40px;
+  border-radius: var(--md-sys-shape-corner-full);
+}
+
+@keyframes skeleton-pulse {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0.45;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton__shape {
+    animation: none;
+  }
+}

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

@@ -0,0 +1,19 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+export type SkeletonVariant = "line" | "block" | "circle";
+export declare class XmSkeleton extends LitElement {
+    variant: SkeletonVariant;
+    width: string;
+    height: string;
+    lines: number;
+    radius: string;
+    render(): TemplateResult;
+    private _renderShape;
+    private _renderLines;
+    private _shapeStyle;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-skeleton": XmSkeleton;
+    }
+}

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

@@ -0,0 +1,119 @@
+/*
+  skeleton/index.ts — <xm-skeleton>, gradient-free loading placeholder.
+
+  Shows the structure of content while data loads. Three shapes via `variant`:
+    line   — a text line (repeatable via `lines` for a paragraph)
+    block  — a rectangular block (card / image placeholder)
+    circle — a circular avatar / icon placeholder
+
+  The loading PULSE is gradient-free (AC-2, the headline constraint): it is a
+  calm opacity animation on a neutral surface fill (a color-mix between two
+  surface-container tiers). There is NO shimmer / sweep gradient anywhere — the
+  snackbar scrim is the system's only sanctioned gradient. The pulse respects
+  `prefers-reduced-motion` (CSS disables the animation).
+
+  The placeholder is decorative: it carries `aria-hidden="true"`. The HOST that
+  owns the loading state carries `aria-busy` — the skeleton does not announce.
+
+  Authoring:
+    <xm-skeleton variant="line" lines="3"></xm-skeleton>
+    <xm-skeleton variant="block" width="100%" height="160px"></xm-skeleton>
+    <xm-skeleton variant="circle" width="40px"></xm-skeleton>
+
+  Properties:
+    variant   "line" | "block" | "circle"   (default "line")
+    width     CSS length for the shape (block/circle/line)
+    height    CSS length (block); line/circle derive their own height
+    lines     number of text lines (line variant only; default 1)
+    radius    CSS length override for corner rounding (block variant)
+
+  Shadow DOM. Depends only on tokens — no overlay, no primitives (AD-12).
+  Reused by xm-data-table loading rows (Epic 6, FR-161): a row of line/block
+  placeholders composes from these variants.
+*/
+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 SKELETON_CSS = new URL("../skeleton/index.css", import.meta.url).href;
+let XmSkeleton = class XmSkeleton extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.variant = "line";
+        this.width = "";
+        this.height = "";
+        this.lines = 1;
+        this.radius = "";
+    }
+    render() {
+        const v = this.variant === "block" || this.variant === "circle"
+            ? this.variant
+            : "line";
+        const cls = `skeleton skeleton--${v}`;
+        return html `
+      <link rel="stylesheet" href="${SKELETON_CSS}" />
+      <style>
+        :host { display: block; }
+        :host([hidden]) { display: none; }
+      </style>
+      <div class="${cls}" aria-hidden="true">
+        ${v === "line" ? this._renderLines() : this._renderShape()}
+      </div>
+    `;
+    }
+    _renderShape() {
+        const style = this._shapeStyle();
+        return html `<span class="skeleton__shape" style=${style}></span>`;
+    }
+    _renderLines() {
+        const count = Math.max(1, Math.floor(this.lines) || 1);
+        const lines = Array.from({ length: count }, (_v, i) => {
+            // The last line of a paragraph runs short for a natural ragged edge.
+            const isLast = i === count - 1 && count > 1;
+            const w = this.width || (isLast ? "62%" : "100%");
+            return html `<span
+        class="skeleton__shape skeleton__line"
+        style="width:${w};"
+      ></span>`;
+        });
+        return html `${lines}`;
+    }
+    _shapeStyle() {
+        const parts = [];
+        if (this.width)
+            parts.push(`width:${this.width};`);
+        if (this.variant === "circle") {
+            // A circle is square: height tracks width unless given explicitly.
+            parts.push(`height:${this.height || this.width || "40px"};`);
+        }
+        else if (this.height) {
+            parts.push(`height:${this.height};`);
+        }
+        if (this.radius)
+            parts.push(`border-radius:${this.radius};`);
+        return parts.join("");
+    }
+};
+__decorate([
+    property({ type: String })
+], XmSkeleton.prototype, "variant", void 0);
+__decorate([
+    property({ type: String })
+], XmSkeleton.prototype, "width", void 0);
+__decorate([
+    property({ type: String })
+], XmSkeleton.prototype, "height", void 0);
+__decorate([
+    property({ type: Number })
+], XmSkeleton.prototype, "lines", void 0);
+__decorate([
+    property({ type: String })
+], XmSkeleton.prototype, "radius", void 0);
+XmSkeleton = __decorate([
+    customElement("xm-skeleton")
+], XmSkeleton);
+export { XmSkeleton };

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

@@ -0,0 +1,171 @@
+/* ============================================
+   xm-slider — draggable range slider on XmField (Story 2.8).
+
+   Extends XmField for chrome but renders its own layout (the bordered text-field
+   box is wrong for a slider): a label row (label + optional value), a track row
+   (rail + active fill + thumb), and the helper/error row. State machinery
+   (disabled / form-association / focus / ARIA) is inherited; this file styles the
+   track, fill, thumb, label, and value.
+
+   Surface & ink (AD-13): the slider rides the inverse-surface card tier — label +
+   value are inverse-on-surface ink. The active (filled) portion + the thumb are
+   the single coral accent (--md-sys-color-primary). The inactive rail, track
+   height, and thumb size are --xm-slider-* extensions (AD-10). Coral = the filled
+   value, never severity (AD-11). The error string carries severity via the warn
+   icon + copy.
+
+   Motion (NFR-19): fill/thumb position is layout-driven; the focus ring + hover
+   transition short3 standard, no bounce.
+
+   BEM block: `slider`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+.slider {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+  width: 100%;
+}
+
+/* ---------- Label row — field label + optional value ---------- */
+.slider__label-row {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--s-2);
+}
+.slider__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);
+}
+.slider__label-text {
+  letter-spacing: 0;
+}
+.slider__required {
+  color: var(--md-sys-color-primary);
+  font-weight: 700;
+  line-height: 1;
+}
+.slider__value {
+  color: var(--md-sys-color-inverse-on-surface);
+  font:
+    var(--md-sys-typescale-label-medium-weight)
+    var(--md-sys-typescale-label-medium-size) /
+    var(--md-sys-typescale-label-medium-line-height)
+    var(--md-sys-typescale-label-medium-font);
+  font-variant-numeric: tabular-nums;
+}
+
+/* ---------- Track — rail + active fill + thumb ---------- */
+.slider__track {
+  position: relative;
+  display: flex;
+  align-items: center;
+  height: var(--xm-slider-thumb-size);
+  /* Inset the interactive box by half a thumb so the thumb (positioned by its
+     center at left:fraction) never overflows the field width. The rail/fill and
+     the pointer math all share this same inset coordinate space. */
+  margin: 0 calc(var(--xm-slider-thumb-size) / 2);
+  cursor: pointer;
+  touch-action: none;
+}
+
+.slider__rail {
+  position: absolute;
+  left: 0;
+  right: 0;
+  height: var(--xm-slider-track-height);
+  border-radius: var(--md-sys-shape-corner-full);
+  background: var(--xm-slider-track-inactive);
+}
+
+.slider__fill {
+  position: absolute;
+  left: 0;
+  height: var(--xm-slider-track-height);
+  border-radius: var(--md-sys-shape-corner-full);
+  background: var(--md-sys-color-primary);
+}
+
+.slider__thumb {
+  position: absolute;
+  top: 50%;
+  width: var(--xm-slider-thumb-size);
+  height: var(--xm-slider-thumb-size);
+  margin-left: calc(var(--xm-slider-thumb-size) / -2);
+  transform: translateY(-50%);
+  border-radius: var(--md-sys-shape-corner-full);
+  background: var(--md-sys-color-primary);
+  box-shadow: var(--xm-slider-thumb-shadow);
+  outline: none;
+  cursor: grab;
+  transition: box-shadow var(--md-sys-motion-duration-short3)
+    var(--md-sys-motion-easing-standard);
+}
+.slider__thumb:active {
+  cursor: grabbing;
+}
+
+/* Focus ring — the canonical 3px coral halo on the thumb. */
+.slider__thumb:focus-visible {
+  box-shadow:
+    var(--xm-slider-thumb-shadow),
+    var(--xm-state-focus-ring);
+}
+
+/* ---------- Disabled — shared reduced emphasis ---------- */
+.slider--disabled .slider__track {
+  cursor: not-allowed;
+}
+.slider--disabled .slider__thumb {
+  cursor: not-allowed;
+  box-shadow: none;
+}
+.slider--disabled .slider__rail,
+.slider--disabled .slider__fill,
+.slider--disabled .slider__thumb {
+  opacity: 0.45;
+}
+.slider--disabled .slider__label,
+.slider--disabled .slider__value {
+  color: var(--xm-color-inverse-on-surface-disabled);
+}
+
+/* ---------- Helper / error message row ----------
+   Severity is the warn icon + copy, not a color (rule 3a). */
+.slider__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);
+}
+.slider__message--helper {
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+.slider__message--error {
+  color: var(--md-sys-color-inverse-on-surface);
+}
+.slider__error-icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  margin-top: 1px;
+  color: var(--md-sys-color-inverse-on-surface);
+}
+.slider__message-text {
+  flex: 1;
+  min-width: 0;
+  text-wrap: pretty;
+}

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

@@ -0,0 +1,36 @@
+import type { PropertyValues, TemplateResult } from "lit";
+import { XmField } from "../field/index.js";
+export declare class XmSlider extends XmField {
+    min: number;
+    max: number;
+    step: number;
+    /** Show the current numeric value as a label beside the track. */
+    showValue: boolean;
+    /** Optional unit appended to the displayed value (e.g. "%", "px"). */
+    unit: string;
+    private _track;
+    private _dragging;
+    connectedCallback(): void;
+    /** Typed live read; the inherited string `value` stays in sync. */
+    get valueAsNumber(): number;
+    private get _num();
+    private get _fraction();
+    private _clampSnap;
+    private _setValue;
+    private _commit;
+    private _valueFromClientX;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    private _focusThumb;
+    private _onKeydown;
+    private _onBlur;
+    protected updated(changed: PropertyValues<this>): void;
+    private get _valueText();
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-slider": XmSlider;
+    }
+}