@xmesh/system-design 0.0.1

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

@@ -0,0 +1,94 @@
+/* ============================================
+   Menu — an anchored dropdown of menu items.
+
+   The popover surface chrome (inverse-surface fill, inverse-on-surface ink,
+   hairline border, level3 elevation, edge-flip, open/close motion) is owned by
+   the composed <xm-overlay> in the `menu` tier. This file styles the list, the
+   trigger wrapper, and each <xm-menu-item> (a separate block, rendered in its
+   own shadow root).
+
+   All ink is inverse-on-surface (AD-13) — the popover stack ink. Item
+   hover/active uses a state layer mixed from the ink, not opacity tricks on the
+   real content. Disabled items take the shared reduced emphasis — never an
+   error hue (AD-11). Destructive actions are icon + copy.
+
+   BEM blocks: `menu` (root) + `menu-item` (the item, its own shadow root). Both
+   registered in scripts/check-bem.sh STRICT_BLOCKS.
+   Elements: menu__trigger, menu__list; menu-item__icon, menu-item__label.
+   Modifiers: menu-item--active, menu-item--disabled.
+   ============================================ */
+
+.menu__trigger {
+  display: inline-flex;
+  align-items: center;
+}
+
+.menu__list {
+  list-style: none;
+  margin: 0;
+  padding: var(--s-1);
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-0-5);
+  min-width: 180px;
+  outline: none;
+  color: var(--md-sys-color-inverse-on-surface);
+}
+
+/* ---------- Menu item (separate block / shadow root) ---------- */
+.menu-item {
+  display: flex;
+  align-items: center;
+  gap: var(--s-3);
+  padding: var(--s-2) var(--s-3);
+  border-radius: var(--md-sys-shape-corner-small);
+  color: var(--md-sys-color-inverse-on-surface);
+  font-family: var(--md-sys-typescale-body-medium-font);
+  font-size: var(--md-sys-typescale-body-medium-size);
+  line-height: var(--md-sys-typescale-body-medium-line-height);
+  cursor: pointer;
+  user-select: none;
+  transition: background var(--md-sys-motion-duration-short3)
+    var(--md-sys-motion-easing-standard);
+}
+
+/* Active (keyboard / hover) — a state layer mixed from the popover ink. */
+.menu-item--active {
+  background: color-mix(
+    in oklch,
+    var(--md-sys-color-inverse-on-surface) 10%,
+    transparent
+  );
+}
+
+.menu-item--disabled {
+  color: color-mix(
+    in oklch,
+    var(--md-sys-color-inverse-on-surface) 40%,
+    transparent
+  );
+  cursor: default;
+  pointer-events: none;
+}
+
+.menu-item__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: color-mix(
+    in oklch,
+    var(--md-sys-color-inverse-on-surface) 70%,
+    transparent
+  );
+}
+/* Collapse the icon column entirely when no icon is slotted so labels align. */
+.menu-item__icon.is-empty {
+  display: none;
+}
+
+.menu-item__label {
+  flex: 1;
+  min-width: 0;
+  text-wrap: pretty;
+}

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

@@ -0,0 +1,47 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+import type { OverlayPlacement } from "../overlay/index.js";
+export declare class XmMenu extends LitElement {
+    open: boolean;
+    placement: OverlayPlacement;
+    label: string;
+    private _activeIndex;
+    private _overlay;
+    private _triggerWrap;
+    private _list;
+    private readonly _listId;
+    private get _items();
+    private get _enabledIndexes();
+    render(): TemplateResult;
+    private _onTriggerClick;
+    private _onTriggerKeydown;
+    private _openMenu;
+    private _close;
+    private _onOverlayClose;
+    private _onListKeydown;
+    private _nextEnabled;
+    private _onItemsSlot;
+    private _onItemActivate;
+    private _onItemHover;
+    private _activateIndex;
+    private _syncItems;
+    private get _triggerEl();
+    private _wireTriggerAria;
+    protected updated(): void;
+}
+export declare class XmMenuItem extends LitElement {
+    value: string | number;
+    disabled: boolean;
+    active: boolean;
+    private _hasIcon;
+    render(): TemplateResult;
+    private _onIconSlot;
+    private _onClick;
+    private _onMouseMove;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-menu": XmMenu;
+        "xm-menu-item": XmMenuItem;
+    }
+}

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

@@ -0,0 +1,386 @@
+/*
+  menu/index.ts — <xm-menu> + <xm-menu-item>, an anchored dropdown menu.
+
+  Composes the xm-overlay foundation (Story 1.4) for positioning, top-layer
+  stacking, outside-click + Esc dismiss, and focus-restore — it does NOT
+  hand-roll z-index, anchoring math, or focus handling. The overlay runs in the
+  `menu` tier (tooltip < menu < dialog). We drive it through its PUBLIC API only
+  (mode / tier / placement / .anchor / .opener / show / hide / xm-overlay-close)
+  and never reach into its shadow root (AD-12).
+
+  Behaviour (FR-144):
+    • clicking the trigger opens an anchored popover of <xm-menu-item> children
+    • clicking the trigger again, clicking outside, or selecting an item closes
+    • keyboard follows the WAI-ARIA `menu` pattern (APG): ↑/↓ move the active
+      item, Home/End jump to first/last, Enter/Space activate, Esc closes;
+      disabled items are skipped (AD-9a)
+
+  Events (AD-8 / AD-8a):
+    xm-menu-select  detail.value = the activated item's primitive value
+    close           bare native-style name, fired on every close path
+    both bubbles:true, composed:true.
+
+  Esc is owned by the overlay's innermost-only handler (stopPropagation), so a
+  menu nested in a dialog closes only the menu (AD-5a). Focus restores to the
+  trigger on close (delegated to the overlay via .opener).
+
+  Severity is never expressed by hue here (AD-11): a destructive item uses icon +
+  copy, never a status color.
+
+  Authoring:
+    <xm-menu>
+      <xm-button slot="trigger">Actions</xm-button>
+      <xm-menu-item value="rename">Rename</xm-menu-item>
+      <xm-menu-item value="duplicate">
+        <xm-copy-icon slot="icon-left" size="16"></xm-copy-icon>
+        Duplicate
+      </xm-menu-item>
+      <xm-menu-item value="archive" disabled>Archive</xm-menu-item>
+    </xm-menu>
+
+  Shadow DOM. Depends on xm-overlay + tokens (AD-12). 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, query, state } from "lit/decorators.js";
+const MENU_CSS = new URL("../menu/index.css", import.meta.url).href;
+let menuSeq = 0;
+let XmMenu = class XmMenu extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.open = false;
+        this.placement = "bottom-start";
+        this.label = "";
+        this._activeIndex = -1;
+        this._listId = `xm-menu-${++menuSeq}`;
+        // ── Open / close ──────────────────────────────────────────────────────
+        this._onTriggerClick = () => {
+            if (this.open)
+                this._close("api");
+            else
+                this._openMenu();
+        };
+        this._onTriggerKeydown = (e) => {
+            if (this.open)
+                return;
+            if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+                e.preventDefault();
+                this._openMenu(0);
+            }
+            else if (e.key === "ArrowUp") {
+                e.preventDefault();
+                this._openMenu(this._enabledIndexes.length - 1);
+            }
+        };
+        this._onOverlayClose = () => {
+            // Overlay self-dismissed (Esc / backdrop). Sync + emit our close once.
+            if (this.open) {
+                this.open = false;
+                this._activeIndex = -1;
+                this._syncItems();
+                this.dispatchEvent(new CustomEvent("close", {
+                    bubbles: true,
+                    composed: true,
+                    detail: { reason: "overlay" },
+                }));
+            }
+        };
+        // ── Keyboard (APG menu) ───────────────────────────────────────────────
+        this._onListKeydown = (e) => {
+            const enabled = this._enabledIndexes;
+            switch (e.key) {
+                case "ArrowDown":
+                    e.preventDefault();
+                    this._activeIndex = this._nextEnabled(this._activeIndex, 1);
+                    this._syncItems();
+                    break;
+                case "ArrowUp":
+                    e.preventDefault();
+                    this._activeIndex = this._nextEnabled(this._activeIndex, -1);
+                    this._syncItems();
+                    break;
+                case "Home":
+                    e.preventDefault();
+                    this._activeIndex = enabled[0] ?? -1;
+                    this._syncItems();
+                    break;
+                case "End":
+                    e.preventDefault();
+                    this._activeIndex = enabled[enabled.length - 1] ?? -1;
+                    this._syncItems();
+                    break;
+                case "Enter":
+                case " ":
+                    e.preventDefault();
+                    this._activateIndex(this._activeIndex);
+                    break;
+                case "Tab":
+                    // Let focus leave; close without committing.
+                    this._close("tab");
+                    break;
+                // Esc handled by the overlay (innermost-only, stopPropagation).
+            }
+        };
+        // ── Selection ─────────────────────────────────────────────────────────
+        this._onItemsSlot = () => {
+            // Re-stamp ids + index so active-descendant + selection stay aligned.
+            this._syncItems();
+        };
+        this._onItemActivate = (e) => {
+            const item = e.target;
+            const index = this._items.indexOf(item);
+            if (index !== -1)
+                this._activateIndex(index);
+        };
+        this._onItemHover = (e) => {
+            const item = e.target;
+            const index = this._items.indexOf(item);
+            if (index !== -1 && !item.disabled) {
+                this._activeIndex = index;
+                this._syncItems();
+            }
+        };
+        this._wireTriggerAria = (e) => {
+            const slot = e.target;
+            const el = slot.assignedElements()[0];
+            if (el) {
+                el.setAttribute("aria-haspopup", "menu");
+                el.setAttribute("aria-expanded", this.open ? "true" : "false");
+                el.setAttribute("aria-controls", this._listId);
+            }
+        };
+    }
+    get _items() {
+        const slot = this.renderRoot.querySelector(".menu__list slot:not([name])");
+        if (!slot)
+            return [];
+        return slot
+            .assignedElements({ flatten: true })
+            .filter((el) => el instanceof XmMenuItem);
+    }
+    get _enabledIndexes() {
+        return this._items
+            .map((it, i) => (it.disabled ? -1 : i))
+            .filter((i) => i !== -1);
+    }
+    render() {
+        const activeId = this._activeIndex >= 0 ? `${this._listId}-item-${this._activeIndex}` : "";
+        return html `
+      <link rel="stylesheet" href="${MENU_CSS}" />
+      <style>
+        :host { display: inline-flex; }
+      </style>
+      <span
+        class="menu__trigger"
+        @click=${this._onTriggerClick}
+        @keydown=${this._onTriggerKeydown}
+      >
+        <slot name="trigger" @slotchange=${this._wireTriggerAria}></slot>
+      </span>
+
+      <xm-overlay
+        mode="non-modal"
+        tier="menu"
+        placement=${this.placement}
+        label=${this.label || "Menu"}
+        @xm-overlay-close=${this._onOverlayClose}
+      >
+        <ul
+          class="menu__list"
+          id=${this._listId}
+          role="menu"
+          aria-label=${this.label || "Menu"}
+          aria-activedescendant=${activeId}
+          tabindex="-1"
+          @keydown=${this._onListKeydown}
+          @xm-menu-item-activate=${this._onItemActivate}
+          @xm-menu-item-hover=${this._onItemHover}
+        >
+          <slot @slotchange=${this._onItemsSlot}></slot>
+        </ul>
+      </xm-overlay>
+    `;
+    }
+    _openMenu(landOn) {
+        if (this.open)
+            return;
+        this.open = true;
+        const enabled = this._enabledIndexes;
+        this._activeIndex =
+            landOn !== undefined ? enabled[landOn] ?? enabled[0] ?? -1 : -1;
+        this.updateComplete.then(() => {
+            // Guard the deferred open: a click-to-close (or Esc) before this microtask
+            // would otherwise re-open an orphaned popover.
+            if (!this.open)
+                return;
+            const ov = this._overlay;
+            const trigger = this._triggerEl;
+            if (ov && trigger) {
+                ov.anchor = trigger;
+                ov.opener = trigger;
+                ov.show();
+            }
+            this._syncItems();
+            // Move DOM focus into the list so arrow keys are captured and the APG
+            // roving model works. Wait a frame so the popover is shown + laid out
+            // (showPopover runs in the overlay's own update, after ours); focusing a
+            // not-yet-shown popover element would no-op.
+            requestAnimationFrame(() => {
+                if (this.open)
+                    this._list?.focus();
+            });
+        });
+    }
+    _close(reason) {
+        if (!this.open)
+            return;
+        this.open = false;
+        this._activeIndex = -1;
+        const ov = this._overlay;
+        if (ov?.open)
+            ov.hide("api");
+        this._syncItems();
+        this.dispatchEvent(new CustomEvent("close", {
+            bubbles: true,
+            composed: true,
+            detail: { reason },
+        }));
+    }
+    _nextEnabled(from, dir) {
+        const n = this._items.length;
+        if (n === 0)
+            return -1;
+        let i = from;
+        for (let step = 0; step < n; step++) {
+            i = (i + dir + n) % n;
+            if (!this._items[i]?.disabled)
+                return i;
+        }
+        return from;
+    }
+    _activateIndex(index) {
+        const item = this._items[index];
+        if (!item || item.disabled)
+            return;
+        this.dispatchEvent(new CustomEvent("xm-menu-select", {
+            bubbles: true,
+            composed: true,
+            detail: { value: item.value },
+        }));
+        this._close("select");
+    }
+    // Push the menu's active index + a stable id down onto each item so the
+    // active item paints its state layer and the list's active-descendant points
+    // at a real element id.
+    _syncItems() {
+        this._items.forEach((it, i) => {
+            it.id = `${this._listId}-item-${i}`;
+            it.active = this.open && i === this._activeIndex;
+        });
+    }
+    get _triggerEl() {
+        const slot = this.renderRoot.querySelector('slot[name="trigger"]');
+        return slot?.assignedElements()[0] ?? this._triggerWrap;
+    }
+    updated() {
+        const trigger = this._triggerEl;
+        if (trigger)
+            trigger.setAttribute("aria-expanded", this.open ? "true" : "false");
+    }
+};
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmMenu.prototype, "open", void 0);
+__decorate([
+    property({ type: String })
+], XmMenu.prototype, "placement", void 0);
+__decorate([
+    property({ type: String })
+], XmMenu.prototype, "label", void 0);
+__decorate([
+    state()
+], XmMenu.prototype, "_activeIndex", void 0);
+__decorate([
+    query("xm-overlay")
+], XmMenu.prototype, "_overlay", void 0);
+__decorate([
+    query(".menu__trigger")
+], XmMenu.prototype, "_triggerWrap", void 0);
+__decorate([
+    query(".menu__list")
+], XmMenu.prototype, "_list", void 0);
+XmMenu = __decorate([
+    customElement("xm-menu")
+], XmMenu);
+export { XmMenu };
+let XmMenuItem = class XmMenuItem extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.value = "";
+        this.disabled = false;
+        this.active = false;
+        this._hasIcon = false;
+        this._onIconSlot = (e) => {
+            const slot = e.target;
+            this._hasIcon = slot.assignedElements().length > 0;
+        };
+        this._onClick = () => {
+            if (this.disabled)
+                return;
+            this.dispatchEvent(new CustomEvent("xm-menu-item-activate", { bubbles: true, composed: true }));
+        };
+        this._onMouseMove = () => {
+            if (this.disabled)
+                return;
+            this.dispatchEvent(new CustomEvent("xm-menu-item-hover", { bubbles: true, composed: true }));
+        };
+    }
+    render() {
+        const cls = [
+            "menu-item",
+            this.active ? "menu-item--active" : "",
+            this.disabled ? "menu-item--disabled" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        return html `
+      <link rel="stylesheet" href="${MENU_CSS}" />
+      <style>
+        :host { display: block; }
+      </style>
+      <div
+        class="${cls}"
+        role="menuitem"
+        aria-disabled=${this.disabled ? "true" : "false"}
+        @click=${this._onClick}
+        @mousemove=${this._onMouseMove}
+      >
+        <span class="menu-item__icon ${this._hasIcon ? "" : "is-empty"}"
+          ><slot name="icon-left" @slotchange=${this._onIconSlot}></slot
+        ></span>
+        <span class="menu-item__label"><slot></slot></span>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmMenuItem.prototype, "value", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmMenuItem.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmMenuItem.prototype, "active", void 0);
+__decorate([
+    state()
+], XmMenuItem.prototype, "_hasIcon", void 0);
+XmMenuItem = __decorate([
+    customElement("xm-menu-item")
+], XmMenuItem);
+export { XmMenuItem };

package/dist/lit/components/navigation-drawer/index.css

@@ -0,0 +1,114 @@
+/* ============================================
+   <xm-navigation-drawer> — side navigation panel.
+
+   Surface / ink (AD-13): the INVERSE-SURFACE family (the card stack) —
+   panel background var(--md-sys-color-inverse-surface), ink
+   var(--md-sys-color-inverse-on-surface), directional drawer shadow
+   var(--xm-elevation-drawer). Hairline 1px borders only.
+
+   Hosts light-DOM xm-sidebar-item children. Those items reference the desk
+   surface roles (--md-sys-color-on-surface / -variant / -container-lowest); to
+   keep AD-12 (no reaching into their shadow root) while making them read on
+   the inverse-surface panel, the panel REMAPS those role custom properties to
+   their inverse equivalents at the panel scope. Custom properties inherit, so
+   the items pick up the right ink/hover automatically.
+
+   Modal mode is a native <dialog> in EDGE layout (showModal gives focus-trap +
+   inert for free; ::backdrop is the scrim). Persistent mode is a static panel;
+   collapsed mode is an icon rail. Slide-in is short4 emphasized-decelerate.
+
+   BEM block `nav-drawer`; elements `__dialog` `__panel`; modifiers `--open`
+   `--collapsed` `--modal` `--persistent`.
+   ============================================ */
+
+.nav-drawer__panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-1);
+  box-sizing: border-box;
+  width: 280px;
+  height: 100%;
+  padding: var(--s-3);
+  background: var(--md-sys-color-inverse-surface);
+  color: var(--md-sys-color-inverse-on-surface);
+  border-inline-end: 1px solid var(--md-sys-color-outline-variant);
+  box-shadow: var(--xm-elevation-drawer);
+  overflow-y: auto;
+
+  /* Remap the desk surface roles to the card-stack equivalents so slotted
+     xm-sidebar-item children (which use these roles) read on inverse-surface.
+     This is token-level composition, not reaching into the item's shadow. */
+  --md-sys-color-on-surface: var(--md-sys-color-inverse-on-surface);
+  --md-sys-color-on-surface-variant: var(--xm-color-inverse-on-surface-muted);
+  --md-sys-color-surface-container-lowest: color-mix(
+    in oklab,
+    var(--md-sys-color-inverse-on-surface) 8%,
+    var(--md-sys-color-inverse-surface)
+  );
+}
+
+/* ---------- Modal: native <dialog> in edge layout ---------- */
+.nav-drawer__dialog {
+  margin: 0;
+  inset-block: 0;
+  inset-inline-start: 0;
+  height: 100dvh;
+  max-height: 100dvh;
+  max-width: 92vw;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  overflow: hidden;
+}
+.nav-drawer__dialog::backdrop {
+  background: var(--md-sys-color-scrim);
+  opacity: 0.5;
+}
+.nav-drawer__dialog .nav-drawer__panel {
+  border-radius: 0;
+  /* Slide-in: panel translates from the leading edge on open. */
+  transform: translateX(-100%);
+  transition: transform var(--md-sys-motion-duration-short4)
+    var(--md-sys-motion-easing-emphasized-decelerate);
+}
+.nav-drawer__dialog[open] .nav-drawer__panel {
+  transform: translateX(0);
+}
+
+/* ---------- Persistent panel ---------- */
+.nav-drawer--persistent .nav-drawer__panel {
+  border-radius: var(--md-sys-shape-corner-medium);
+  height: auto;
+  /* Slide + collapse on open/close. Width animates to 0 so the closed drawer
+     yields its layout space (not just translated off-screen). */
+  transition:
+    width var(--md-sys-motion-duration-short4) var(--md-sys-motion-easing-emphasized-decelerate),
+    transform var(--md-sys-motion-duration-short4) var(--md-sys-motion-easing-emphasized-decelerate),
+    opacity var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard);
+}
+
+/* Closed persistent drawer: collapse to zero width, slide out, and hide so its
+   slotted (focusable) children leave the tab order — `aria-hidden` alone would
+   leave focusable descendants inside a hidden region (an a11y anti-pattern). */
+.nav-drawer--persistent:not(.nav-drawer--open) .nav-drawer__panel {
+  width: 0;
+  padding-inline: 0;
+  transform: translateX(-100%);
+  opacity: 0;
+  overflow: hidden;
+  visibility: hidden;
+  border-inline-end-color: transparent;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .nav-drawer--persistent .nav-drawer__panel {
+    transition: none;
+  }
+}
+
+/* ---------- Collapsed icon rail ---------- */
+.nav-drawer--collapsed .nav-drawer__panel {
+  width: 64px;
+  align-items: center;
+  padding-inline: var(--s-2);
+}

package/dist/lit/components/navigation-drawer/index.d.ts

@@ -0,0 +1,29 @@
+import { LitElement } from "lit";
+import type { PropertyValues, TemplateResult } from "lit";
+declare class XmNavigationDrawer extends LitElement {
+    static shadowRootOptions: ShadowRootInit;
+    open: boolean;
+    collapsed: boolean;
+    modal: boolean;
+    label: string;
+    private _dialog;
+    private _restoreFocusTo;
+    private _wasOpen;
+    render(): TemplateResult;
+    protected updated(changed: PropertyValues<this>): void;
+    disconnectedCallback(): void;
+    private _activateModal;
+    private _deactivateModal;
+    private _onDialogCancel;
+    private _onDialogClose;
+    private _onDialogClick;
+    private _emitClose;
+    private _restoreFocus;
+    private _deepActiveElement;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-navigation-drawer": XmNavigationDrawer;
+    }
+}
+export {};