@akonwi/mica 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akonwi/mica",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Custom elements. Native behavior. Nearly no JavaScript.",
   "keywords": [
     "css",
@@ -55,6 +55,22 @@
     },
     "./types/react": {
       "types": "./types/react.d.ts"
+    },
+    "./header.js": {
+      "types": "./header.d.ts",
+      "default": "./header.js"
+    },
+    "./sidebar.js": {
+      "types": "./sidebar.d.ts",
+      "default": "./sidebar.js"
+    },
+    "./breadcrumbs.js": {
+      "types": "./breadcrumbs.d.ts",
+      "default": "./breadcrumbs.js"
+    },
+    "./table.js": {
+      "types": "./table.d.ts",
+      "default": "./table.js"
     }
   },
   "files": [
@@ -76,7 +92,15 @@
     "combobox.js",
     "combobox.d.ts",
     "types/react.d.ts",
-    "THIRD_PARTY_LICENSES.md"
+    "THIRD_PARTY_LICENSES.md",
+    "header.js",
+    "header.d.ts",
+    "sidebar.js",
+    "sidebar.d.ts",
+    "breadcrumbs.js",
+    "breadcrumbs.d.ts",
+    "table.js",
+    "table.d.ts"
   ],
   "sideEffects": true,
   "devDependencies": {
@@ -93,6 +117,13 @@
     "docs:serve": "bun run docs:build && bun tools/serve.ts",
     "snapshot": "bun tools/snapshot.ts",
     "snapshot:check": "bun tools/snapshot.ts --check",
-    "snapshot:setup": "playwright install chromium webkit"
+    "snapshot:setup": "playwright install chromium webkit",
+    "header:check": "bun tools/header-check.ts",
+    "sidebar:check": "bun tools/sidebar-check.ts",
+    "navigation-menu:check": "bun tools/navigation-menu-check.ts",
+    "bottom-navigation:check": "bun tools/bottom-navigation-check.ts",
+    "breadcrumbs:check": "bun tools/breadcrumbs-check.ts",
+    "data-table:check": "bun tools/data-table-check.ts",
+    "callout:check": "bun tools/callout-check.ts"
   }
 }

package/sidebar.d.ts

@@ -0,0 +1,11 @@
+export interface MSidebarLayoutElement extends HTMLElement {
+  open(): void;
+  close(): void;
+  toggle(): void;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "m-sidebar": HTMLElement;
+    "m-sidebar-layout": MSidebarLayoutElement;
+  }
+}

package/sidebar.js

@@ -0,0 +1,135 @@
+/* Optional sidebar shell enhancement. The panel, dialog, controls, and all
+ * icons are authored HTML. Only the same panel is moved into the native
+ * dialog on narrow containers; no UI or navigation is generated. */
+class MSidebarLayout extends HTMLElement {
+  #cleanup;
+  #actions;
+  #refresh;
+  static observedAttributes = ['collapse'];
+  attributeChangedCallback() { this.#refresh?.(); }
+  open() { this.#actions?.open(); }
+  close() { this.#actions?.close(); }
+  toggle() { this.#actions?.toggle(); }
+
+  connectedCallback() {
+    queueMicrotask(() => {
+      if (!this.isConnected || this.#cleanup) return;
+      const sidebar = this.querySelector(':scope > m-sidebar');
+      const main = this.querySelector(':scope > [data-sidebar-main]');
+      const dialog = this.querySelector(':scope > dialog[data-sidebar-dialog]');
+      if (!sidebar?.id || !main || !dialog || !('showModal' in dialog) || dialog.open || dialog.children.length) return;
+      const triggers = [...main.querySelectorAll('button[data-sidebar-toggle]')].filter(b => b.getAttribute('aria-controls') === sidebar.id);
+      const closers = [...sidebar.querySelectorAll('button[data-sidebar-close]')];
+      if (!triggers.length || !closers.length) return;
+      const originalExpanded = triggers.map(b => b.getAttribute('aria-expanded'));
+      const controller = new AbortController();
+      const { signal } = controller;
+      let mobile = false;
+      let rail = false;
+      let canRail = false;
+      let opener = triggers[0];
+      const focusable = 'a[href],button:not(:disabled),summary';
+      const closePopovers = () => sidebar.querySelectorAll('[popover]:popover-open').forEach(p => p.hidePopover());
+      const update = () => {
+        this.toggleAttribute('data-m-sidebar-mobile', mobile);
+        this.toggleAttribute('data-m-sidebar-rail', rail && canRail && !mobile);
+        this.toggleAttribute('data-m-sidebar-can-rail', canRail && !mobile);
+        for (const button of triggers) button.setAttribute('aria-expanded', String(mobile ? dialog.open : !(rail && canRail)));
+      };
+      const setRail = value => {
+        closePopovers();
+        const active = document.activeElement;
+        rail = value && canRail;
+        update();
+        if (sidebar.contains(active) && active instanceof HTMLElement && !active.getClientRects().length) triggers[0].focus();
+      };
+      const open = () => {
+        if (mobile) {
+          if (!dialog.open) dialog.showModal();
+          update();
+        } else setRail(false);
+      };
+      const close = () => {
+        if (mobile) {
+          closePopovers();
+          if (dialog.open) dialog.close();
+          update();
+        } else setRail(true);
+      };
+      const toggle = () => mobile ? (dialog.open ? close() : open()) : setRail(!rail);
+      const measure = () => {
+        const active = document.activeElement;
+        // Icon collapse is explicitly requested and requires named, authored
+        // icons. Invalid icon anatomy falls back to the expanded desktop panel.
+        const items = [...sidebar.querySelectorAll('[data-sidebar-item]')].filter(e => !e.closest('[data-sidebar-subnav], [popover]'));
+        canRail = this.getAttribute('collapse') === 'icon' && items.length > 0 && items.every(e => e.querySelector('[data-sidebar-icon]') && (e.hasAttribute('aria-label') || e.hasAttribute('aria-labelledby')));
+        const nextMobile = this.getBoundingClientRect().width < 44 * parseFloat(getComputedStyle(document.documentElement).fontSize);
+        if (nextMobile !== mobile || sidebar.parentElement !== (nextMobile ? dialog : this)) {
+          const hadSidebarFocus = sidebar.contains(active);
+          closePopovers();
+          if (dialog.open) dialog.close();
+          mobile = nextMobile;
+          if (mobile) dialog.append(sidebar);
+          else this.insertBefore(sidebar, main);
+          update();
+          if (hadSidebarFocus && active instanceof HTMLElement) {
+            if (mobile) opener.focus();
+            else {
+              // Preserve a focused nested link when returning to desktop.
+              if (active.closest('[data-sidebar-subnav]')) rail = false;
+              update();
+              if (active.matches('[data-sidebar-close]')) sidebar.querySelector(focusable)?.focus();
+              else active.focus();
+            }
+          } else if (!mobile && triggers.includes(active) && !canRail) sidebar.querySelector(focusable)?.focus();
+        } else update();
+      };
+      for (const button of triggers) button.addEventListener('click', () => { opener = button; toggle(); }, { signal });
+      for (const button of closers) button.addEventListener('click', close, { signal });
+      dialog.addEventListener('close', () => {
+        update();
+        // WebKit can leave focus on body after closing a modal that contained
+        // a popover. Preserve router-assigned focus elsewhere in the page.
+        if (mobile && (document.activeElement === document.body || dialog.contains(document.activeElement))) opener.focus();
+      }, { signal });
+      dialog.addEventListener('click', event => {
+        if (event.target !== dialog) return;
+        const r = dialog.getBoundingClientRect();
+        if (event.clientX < r.left || event.clientX > r.right || event.clientY < r.top || event.clientY > r.bottom) close();
+      }, { signal });
+      sidebar.addEventListener('click', event => {
+        const summary = event.target.closest('summary');
+        if (summary && rail && !mobile) {
+          event.preventDefault();
+          setRail(false);
+          summary.parentElement.open = true;
+        }
+        const link = event.target.closest('a[href]');
+        if (link && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey) queueMicrotask(() => { if (!event.defaultPrevented && mobile) close(); });
+      }, { signal });
+      const observer = new ResizeObserver(measure);
+      observer.observe(this);
+      window.addEventListener('resize', measure, { signal, passive: true });
+      this.#actions = { open, close, toggle };
+      this.#refresh = measure;
+      this.#cleanup = () => {
+        controller.abort();
+        observer.disconnect();
+        closePopovers();
+        if (dialog.open) dialog.close();
+        this.insertBefore(sidebar, main);
+        for (const name of ['ready', 'mobile', 'rail', 'can-rail']) this.removeAttribute(`data-m-sidebar-${name}`);
+        triggers.forEach((b, i) => originalExpanded[i] === null ? b.removeAttribute('aria-expanded') : b.setAttribute('aria-expanded', originalExpanded[i]));
+      };
+      this.setAttribute('data-m-sidebar-ready', '');
+      measure();
+    });
+  }
+
+  disconnectedCallback() {
+    this.#cleanup?.();
+    this.#cleanup = this.#actions = this.#refresh = undefined;
+  }
+}
+
+if (!customElements.get('m-sidebar-layout')) customElements.define('m-sidebar-layout', MSidebarLayout);

package/table.d.ts

@@ -0,0 +1,5 @@
+/** Optional visual overflow indicators; native scrolling works without JS. */
+declare global {
+  interface HTMLElementTagNameMap { "m-table-scroll": HTMLElement; }
+}
+export {};

package/table.js

@@ -0,0 +1,59 @@
+/** Optional overflow indicators. Authored rows, selection, sorting, and paging
+ * remain application-owned. The native scroll region works without this module. */
+class MicaTableScroll extends HTMLElement {
+  connectedCallback() {
+    this._abort?.abort();
+    this._resize?.disconnect();
+    this._mutation?.disconnect();
+    this._abort = new AbortController();
+    this._update = () => {
+      cancelAnimationFrame(this._frame);
+      this._frame = requestAnimationFrame(() => this._measure());
+    };
+    this.addEventListener('scroll', this._update, { capture: true, passive: true, signal: this._abort.signal });
+    window.addEventListener('resize', this._update, { signal: this._abort.signal });
+    this._resize = new ResizeObserver(this._update);
+    this._observe = () => {
+      this._resize.disconnect();
+      this._resize.observe(this);
+      const region = this.querySelector(':scope > [data-table-region]');
+      if (region) this._resize.observe(region);
+      const table = region?.querySelector('table');
+      if (table) this._resize.observe(table);
+      this._update();
+    };
+    this._mutation = new MutationObserver(this._observe);
+    this._mutation.observe(this, { subtree: true, childList: true, attributes: true, attributeFilter: ['hidden', 'data-state', 'dir'] });
+    this._observe();
+  }
+  _measure() {
+    const region = this.querySelector(':scope > [data-table-region]');
+    const table = region?.querySelector('table');
+    if (!region || !table) return;
+    const r = region.getBoundingClientRect(), t = table.getBoundingClientRect();
+    const overflow = !region.hasAttribute('data-state') && region.scrollWidth > region.clientWidth + 1;
+    this.toggleAttribute('data-m-overflow-left', overflow && t.left < r.left - 1);
+    this.toggleAttribute('data-m-overflow-right', overflow && t.right > r.right + 1);
+    let left = 0, right = 0;
+    const rtl = getComputedStyle(region).direction === 'rtl';
+    for (const cell of table.querySelectorAll('thead [data-table-sticky]')) {
+      if (getComputedStyle(cell).position !== 'sticky' || !cell.getClientRects().length) continue;
+      const c = cell.getBoundingClientRect();
+      if (rtl) right = Math.max(right, r.right - c.left);
+      else left = Math.max(left, c.right - r.left);
+    }
+    this.style.setProperty('--m-table-edge-left', `${left}px`);
+    this.style.setProperty('--m-table-edge-right', `${right}px`);
+  }
+  disconnectedCallback() {
+    this._abort?.abort();
+    this._resize?.disconnect();
+    this._mutation?.disconnect();
+    cancelAnimationFrame(this._frame);
+    this.removeAttribute('data-m-overflow-left');
+    this.removeAttribute('data-m-overflow-right');
+    this.style.removeProperty('--m-table-edge-left');
+    this.style.removeProperty('--m-table-edge-right');
+  }
+}
+if (!customElements.get('m-table-scroll')) customElements.define('m-table-scroll', MicaTableScroll);

package/tabs.d.ts

@@ -1,5 +1,6 @@
 /* Type declarations for mica/tabs.js — side-effect module.
- * Registers <m-tabs>: roving tabindex, arrow keys, aria-selected wiring.
+ * Registers <m-tabs>: roving tabindex, arrow keys, aria-selected wiring,
+ * selected-tab reveal, and directional overflow markers.
  */
 declare global {
   interface HTMLElementTagNameMap {

package/tabs.js

@@ -3,7 +3,8 @@
  * Enhances working light-DOM markup; never renders it. Without this
  * module, the nav buttons are inert and every panel is visible in
  * order — complete, readable content. With it: real tablist semantics,
- * roving tabindex, arrow-key navigation, automatic activation.
+ * roving tabindex, arrow-key navigation, automatic activation, and
+ * selected-tab reveal with position-aware overflow markers.
  *
  *   <m-tabs>
  *     <nav>
@@ -23,10 +24,43 @@ let uid = 0;
 class MTabs extends HTMLElement {
   #tabs = [];
   #panels = [];
+  #nav = null;
+  #overflowing = false;
+  #resizeObserver = null;
+  #revealFrame = null;
+  #onScroll = () => this.#syncOverflow();
+  #cancelReveal = () => {
+    if (this.#revealFrame !== null) cancelAnimationFrame(this.#revealFrame);
+    this.#revealFrame = null;
+  };
+  #onClick = (event) => {
+    const tab = event.target instanceof Element ? event.target.closest("button") : null;
+    const index = this.#tabs.indexOf(tab);
+    if (index === -1) return;
+    this.select(index);
+    this.#reveal(index);
+  };
+  #onKeyDown = (event) => {
+    const n = this.#tabs.length;
+    const current = this.#tabs.findIndex(
+      (tab) => tab.getAttribute("aria-selected") === "true",
+    );
+    let next = null;
+    if (event.key === "ArrowRight") next = (current + 1) % n;
+    else if (event.key === "ArrowLeft") next = (current - 1 + n) % n;
+    else if (event.key === "Home") next = 0;
+    else if (event.key === "End") next = n - 1;
+    if (next === null) return;
+    event.preventDefault();
+    this.select(next); // automatic activation, radix-style
+    this.#tabs[next].focus({ preventScroll: true });
+    this.#reveal(next);
+  };
 
   connectedCallback() {
     const nav = this.querySelector(":scope > nav");
     if (!nav) return;
+    this.#nav = nav;
     this.#tabs = [...nav.querySelectorAll("button")];
     const sections = [...this.querySelectorAll(":scope > section")];
     this.#panels = this.#tabs.map((b, i) => {
@@ -44,29 +78,117 @@ class MTabs extends HTMLElement {
         panel.setAttribute("aria-labelledby", tab.id);
         panel.tabIndex = 0;
       }
-      tab.addEventListener("click", () => this.select(i));
     });
 
-    nav.addEventListener("keydown", (e) => {
-      const n = this.#tabs.length;
-      const current = this.#tabs.findIndex(
-        (t) => t.getAttribute("aria-selected") === "true",
-      );
-      let next = null;
-      if (e.key === "ArrowRight") next = (current + 1) % n;
-      else if (e.key === "ArrowLeft") next = (current - 1 + n) % n;
-      else if (e.key === "Home") next = 0;
-      else if (e.key === "End") next = n - 1;
-      if (next === null) return;
-      e.preventDefault();
-      this.select(next); // automatic activation, radix-style
-      this.#tabs[next].focus();
-    });
+    nav.addEventListener("click", this.#onClick);
+    nav.addEventListener("keydown", this.#onKeyDown);
+    nav.addEventListener("pointerdown", this.#cancelReveal, { passive: true });
+    nav.addEventListener("wheel", this.#cancelReveal, { passive: true });
 
     const initial = this.#tabs.findIndex(
       (t) => t.hasAttribute("selected") || t.getAttribute("aria-selected") === "true",
     );
     this.select(initial === -1 ? 0 : initial);
+
+    nav.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#resizeObserver = new ResizeObserver(() => this.#measureOverflow());
+    this.#resizeObserver.observe(nav);
+    this.#tabs.forEach((tab) => this.#resizeObserver.observe(tab));
+    this.#measureOverflow();
+  }
+
+  disconnectedCallback() {
+    this.#nav?.removeEventListener("click", this.#onClick);
+    this.#nav?.removeEventListener("keydown", this.#onKeyDown);
+    this.#nav?.removeEventListener("pointerdown", this.#cancelReveal);
+    this.#nav?.removeEventListener("wheel", this.#cancelReveal);
+    this.#nav?.removeEventListener("scroll", this.#onScroll);
+    this.#resizeObserver?.disconnect();
+    this.#cancelReveal();
+    for (const property of [
+      "--m-tabs-overflow-start-gutter",
+      "--m-tabs-overflow-end-gutter",
+      "--m-tabs-overflow-start",
+      "--m-tabs-overflow-end",
+    ]) this.#nav?.style.removeProperty(property);
+    this.#nav = null;
+    this.#resizeObserver = null;
+  }
+
+  #measureOverflow() {
+    const nav = this.#nav;
+    if (!nav) return;
+    const style = getComputedStyle(nav);
+    const gap = Number.parseFloat(style.columnGap) || 0;
+    const padding = (Number.parseFloat(style.paddingInlineStart) || 0) +
+      (Number.parseFloat(style.paddingInlineEnd) || 0);
+    const tabsWidth = this.#tabs.reduce(
+      (width, tab) => width + tab.getBoundingClientRect().width,
+      padding + gap * Math.max(0, this.#tabs.length - 1),
+    );
+    this.#overflowing = tabsWidth > nav.clientWidth + 1;
+    this.#syncOverflow();
+  }
+
+  #syncOverflow() {
+    const nav = this.#nav;
+    if (!nav) return;
+    const offset = Math.abs(nav.scrollLeft);
+    const max = nav.scrollWidth - nav.clientWidth;
+    const start = this.#overflowing && offset > 1;
+    const end = this.#overflowing && offset < max - 1;
+    nav.style.setProperty("--m-tabs-overflow-start", String(start ? 1 : 0));
+    nav.style.setProperty("--m-tabs-overflow-end", String(end ? 1 : 0));
+    nav.style.setProperty(
+      "--m-tabs-overflow-start-gutter",
+      start ? "var(--space-md)" : "0px",
+    );
+    nav.style.setProperty(
+      "--m-tabs-overflow-end-gutter",
+      end ? "var(--space-md)" : "0px",
+    );
+  }
+
+  #reveal(index) {
+    const nav = this.#nav;
+    if (!nav || !this.#tabs[index]) return;
+    this.#cancelReveal();
+    const durations = getComputedStyle(nav, "::before").transitionDuration.split(",");
+    const duration = durations.reduce((longest, value) => {
+      const time = Number.parseFloat(value) * (value.trim().endsWith("ms") ? 1 : 1000);
+      return Math.max(longest, time);
+    }, 0);
+    // Follow the moving gutters through their transition, plus two frames
+    // for the scroll event that activates the newly exposed marker.
+    const settleAt = performance.now() + duration + 34;
+    let firstFrame = true;
+    const reveal = (now) => {
+      const nav = this.#nav;
+      const tab = this.#tabs[index];
+      if (!nav || !tab) return;
+      const navRect = nav.getBoundingClientRect();
+      const tabRect = tab.getBoundingClientRect();
+      const beforeStyle = getComputedStyle(nav, "::before");
+      const afterStyle = getComputedStyle(nav, "::after");
+      const before = Math.max(0,
+        (Number.parseFloat(beforeStyle.inlineSize) || 0) +
+        (Number.parseFloat(beforeStyle.marginInlineEnd) || 0));
+      const after = Math.max(0,
+        (Number.parseFloat(afterStyle.inlineSize) || 0) +
+        (Number.parseFloat(afterStyle.marginInlineStart) || 0));
+      const rtl = getComputedStyle(nav).direction === "rtl";
+      const left = navRect.left + (rtl ? after : before);
+      const right = navRect.right - (rtl ? before : after);
+      if (tabRect.left < left) nav.scrollBy({ left: tabRect.left - left });
+      else if (tabRect.right > right) nav.scrollBy({ left: tabRect.right - right });
+      if (firstFrame) {
+        this.#syncOverflow();
+        firstFrame = false;
+      }
+      if (now < settleAt) this.#revealFrame = requestAnimationFrame(reveal);
+      else this.#revealFrame = null;
+    };
+    this.#revealFrame = requestAnimationFrame(reveal);
   }
 
   select(index) {

package/types/react.d.ts

@@ -51,7 +51,13 @@ declare module 'react' {
 
       // components
       'm-segmented': MicaElement
-      'm-tabs': MicaElement
+      'm-sidebar': MicaElement
+      'm-sidebar-layout': MicaElement<{ variant?: 'docked' | 'inset'; collapse?: 'icon' }>
+      'm-table-scroll': MicaElement
+      'm-breadcrumb-overflow': MicaElement
+      'm-header': MicaElement<{ align?: 'start' | 'end' }>
+      'm-stepper': MicaElement
+      'm-tabs': MicaElement<{ variant?: 'underline' }>
       'm-badge': MicaElement<{
         variant?: 'primary' | 'success' | 'warning' | 'danger'
         count?: boolean
@@ -60,6 +66,8 @@ declare module 'react' {
         blobatar?: string
         contained?: boolean
       }>
+      'm-callout': MicaElement<{ variant?: 'neutral' | 'success' | 'warning' | 'danger' }>
+      'm-skeleton': MicaElement
       'm-toast': MicaElement<{
         popover?: 'manual'
         variant?: 'success' | 'warning' | 'danger'