@akonwi/mica 0.6.0 → 0.8.0

package/README.md

@@ -2,9 +2,11 @@
 
 **Custom elements. Native behavior. Nearly no JavaScript.**
 
-Mica is a front-end library built from custom element tags, native HTML
-elements, and CSS. No runtime, no build step, no framework. View source —
-there's nothing there but HTML and a stylesheet.
+Mica is a **progressive component library** of custom elements —
+progressive as in progressive enhancement: every component starts from
+markup that works, and each layer (CSS, the browser's native behavior, an
+optional JS module) enhances it. No runtime, no build step, no framework.
+View source — there's nothing there but HTML and a stylesheet.
 
 ```html
 <link rel="stylesheet" href="mica.css">
@@ -47,18 +49,18 @@ import "@akonwi/mica/mica.css";
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@akonwi/mica@0.2/mica.css">
 ```
 
-## The three tiers
+## Progressive by design
 
 Every component states where its behavior comes from
-(see [TIERS.md](TIERS.md)):
+(see [PROGRESSIVE.md](PROGRESSIVE.md)):
 
-- **Tier 0 — CSS is the behavior.** Layout primitives: `m-vstack`,
+- **CSS-only — CSS is the behavior.** Layout primitives: `m-vstack`,
   `m-hstack`, `m-zstack`, `m-center`, `m-box`, `m-grid`, `m-sidecar`,
   `m-switcher`, `m-reel`. Zero JS, work with JS disabled.
-- **Tier 1 — the browser is the behavior.** Styled native elements:
+- **Native behavior — the browser is the behavior.** Styled native elements:
   buttons, forms, `<dialog>`, `<details>` accordions, popover menus,
   tooltips, toasts. Delete the stylesheet and everything still works.
-- **Tier 2 — script, honestly.** Where accessibility genuinely requires
+- **JS-enhanced — script, honestly.** Where accessibility genuinely requires
   JS: `tabs.js`, `combobox.js`, `field.js` (declarative validation),
   `select.js`, `toast.js`. Each is a tiny standalone module that enhances
   working markup — never renders it. There is no shared runtime.
@@ -83,8 +85,8 @@ how. Nothing breaks; some things get plainer.
 mica itself (view source). The [demo](https://akonwi.io/mica/demo.html) is
 the whole library on one page.
 
-Read [VISION.md](VISION.md) for the philosophy and [TIERS.md](TIERS.md)
-for the tier system.
+Read [VISION.md](VISION.md) for the philosophy and
+[PROGRESSIVE.md](PROGRESSIVE.md) for how components are allowed to work.
 
 ## License
 

package/combobox.d.ts

@@ -0,0 +1,9 @@
+/* Type declarations for mica/combobox.js — side-effect module.
+ * Registers <m-combobox>: filterable input + listbox over native markup.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    "m-combobox": HTMLElement;
+  }
+}
+export {};

package/combobox.js

@@ -1,4 +1,4 @@
-/* mica/combobox.js — <m-combobox>: filterable input + listbox. Tier 2.
+/* mica/combobox.js — <m-combobox>: filterable input + listbox. JS-enhanced module.
  *
  * The no-JS state is a native <datalist> — real autocomplete, fully
  * functional, just unstylable. The module upgrades it into the ARIA
@@ -20,13 +20,16 @@ let uid = 0;
 class MCombobox extends HTMLElement {
   #input;
   #list;
+  #datalist;
+  #listId;
   #options = [];
   #active = -1;
+  #observer;
 
   connectedCallback() {
     this.#input = this.querySelector("input");
-    const datalist = this.querySelector("datalist");
-    if (!this.#input || !datalist) return;
+    this.#datalist = this.querySelector("datalist");
+    if (!this.#input || !this.#datalist) return;
 
     // disable the native popup; the module takes over
     this.#input.removeAttribute("list");
@@ -35,16 +38,49 @@ class MCombobox extends HTMLElement {
     this.#input.setAttribute("aria-autocomplete", "list");
     this.#input.autocomplete = "off";
 
-    const listId = `m-cb-${++uid}`;
+    this.#listId = `m-cb-${++uid}`;
     this.#list = document.createElement("div");
-    this.#list.id = listId;
+    this.#list.id = this.#listId;
     this.#list.setAttribute("role", "listbox");
     this.#list.hidden = true;
 
-    this.#options = [...datalist.options].map((o, i) => {
+    this.#buildOptions();
+    this.append(this.#list);
+    this.#input.setAttribute("aria-controls", this.#listId);
+
+    // Options may be rendered asynchronously (a search-backed combobox):
+    // rebuild the listbox whenever the author's datalist changes.
+    this.#observer = new MutationObserver(() => {
+      this.#buildOptions();
+      if (document.activeElement === this.#input) this.#openAndFilter();
+    });
+    this.#observer.observe(this.#datalist, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["value"],
+    });
+
+    this.#input.addEventListener("input", (e) => {
+      // ignore our own dispatched events from #choose — they'd reopen
+      if (e.isTrusted) this.#openAndFilter();
+    });
+    this.#input.addEventListener("keydown", (e) => this.#onKey(e));
+    this.addEventListener("focusout", (e) => {
+      if (!this.contains(e.relatedTarget)) this.#close();
+    });
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+  }
+
+  #buildOptions() {
+    this.#list.replaceChildren();
+    this.#options = [...this.#datalist.options].map((o, i) => {
       const d = document.createElement("div");
       d.setAttribute("role", "option");
-      d.id = `${listId}-${i}`;
+      d.id = `${this.#listId}-${i}`;
       d.textContent = o.value || o.textContent;
       // pointerdown so the input never loses focus
       d.addEventListener("pointerdown", (e) => {
@@ -58,17 +94,7 @@ class MCombobox extends HTMLElement {
       this.#list.append(d);
       return d;
     });
-    this.append(this.#list);
-    this.#input.setAttribute("aria-controls", listId);
-
-    this.#input.addEventListener("input", (e) => {
-      // ignore our own dispatched events from #choose — they'd reopen
-      if (e.isTrusted) this.#openAndFilter();
-    });
-    this.#input.addEventListener("keydown", (e) => this.#onKey(e));
-    this.addEventListener("focusout", (e) => {
-      if (!this.contains(e.relatedTarget)) this.#close();
-    });
+    this.#active = -1;
   }
 
   #visible() {
@@ -127,7 +153,15 @@ class MCombobox extends HTMLElement {
   }
 
   #choose(option) {
-    this.#input.value = option.textContent;
+    // Write through the native prototype setter: frameworks that patch
+    // the value property to track controlled inputs (React) only observe
+    // the change when it lands on the native setter.
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLInputElement.prototype,
+      "value",
+    )?.set;
+    if (setter) setter.call(this.#input, option.textContent);
+    else this.#input.value = option.textContent;
     this.#close();
     this.#input.dispatchEvent(new Event("input", { bubbles: true }));
     this.#input.dispatchEvent(new Event("change", { bubbles: true }));

package/drawer.d.ts

@@ -0,0 +1,5 @@
+/* Type declarations for mica/drawer.js — side-effect module.
+ * Swipe-to-dismiss drag physics for dialog[data-drawer] bottom sheets.
+ * No exports; sets :root[data-drawer-gestures] when active.
+ */
+export {};

package/drawer.js

@@ -1,4 +1,4 @@
-/* mica/drawer.js — Tier 2: swipe-to-dismiss for dialog[data-drawer]
+/* mica/drawer.js — JS-enhanced: swipe-to-dismiss for dialog[data-drawer]
  * bottom sheets on small screens.
  *
  * Enhances working markup, never replaces it: without this module the

package/field.d.ts

@@ -0,0 +1,10 @@
+/* Type declarations for mica/field.js — side-effect module.
+ * Registers <m-field>: declarative validation errors via <m-error match>.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    "m-field": HTMLElement;
+    "m-error": HTMLElement;
+  }
+}
+export {};

package/field.js

@@ -1,4 +1,4 @@
-/* mica/field.js — <m-field>: declarative validation errors. Tier 2.
+/* mica/field.js — <m-field>: declarative validation errors. JS-enhanced module.
  *
  * Enhances working light-DOM markup; never renders it. Without this
  * module, fields inside <m-field> fall back to native bubbles plus the

package/invoker.d.ts

@@ -0,0 +1,5 @@
+/* Type declarations for mica/invoker.js — side-effect module.
+ * Shims <button commandfor command> dialog commands where invoker
+ * commands aren't supported. No exports; installs nothing where native.
+ */
+export {};

package/mica.css

@@ -40,6 +40,13 @@
     --control-height: 2.25rem;
     --control-height-lg: 2.5rem;
 
+    /* Where toasts pin. App-level config — set once, all toasts obey:
+       bottom-right (default) | bottom-left | bottom-center |
+       top-right | top-left | top-center.
+       Read via container style queries (Baseline newly-available
+       2026-05); browsers without them keep the bottom-right default. */
+    --toast-position: bottom-right;
+
     --focus-ring-width: 2px;
     --focus-ring-offset: 2px;
     --focus-ring-color: var(--color-accent);
@@ -267,7 +274,7 @@
 }
 
 /* ------------------------------------------------------------------ *
- * Elements — Tier 1. Native elements styled directly; behavior is the
+ * Elements — native behavior. Native elements styled directly; behavior is the
  * browser's. Presentation APIs are attributes; user CSS still wins
  * because these rules live in a layer.
  * ------------------------------------------------------------------ */
@@ -1184,7 +1191,7 @@
     }
 
     /* grab handle — only when drawer.js is loaded (an affordance
-       without its behavior would fake interactivity; TIERS.md).
+       without its behavior would fake interactivity; PROGRESSIVE.md).
        the handle is the first flex item of the open sheet. */
     :where(:root[data-drawer-gestures])
       :where(dialog[data-drawer][open])::before {
@@ -1204,7 +1211,7 @@
   }
 
   /* scroll lock: the page must not scroll behind any modal dialog.
-     CSS-only best effort (→ no JS tier violation); iOS honors
+     CSS-only best effort (→ no faked-behavior violation); iOS honors
      overflow:hidden on the root for modern versions. */
   :where(html):has(:where(dialog:modal)) {
     overflow: hidden;
@@ -1384,7 +1391,7 @@
     }
   }
 
-  /* --- combobox: m-combobox + combobox.js (Tier 2) ------------------ *
+  /* --- combobox: m-combobox + combobox.js (JS-enhanced) ------------------ *
    * without the module: a native datalist — functional autocomplete.
    * with it: styled listbox, filtering, active-descendant keys.
    * positioned within the wrapper (no top layer) so it works everywhere.
@@ -1421,7 +1428,7 @@
     }
   }
 
-  /* --- tabs: m-tabs + tabs.js (Tier 2) ------------------------------ *
+  /* --- tabs: m-tabs + tabs.js (JS-enhanced) ------------------------------ *
    * without the module: inert nav, all panels visible in order —
    * complete content. with it: tablist semantics + roving focus.
    * shadcn segmented look: muted track, surface active tab.
@@ -1481,7 +1488,7 @@
     padding-block: var(--space-md);
   }
 
-  /* --- toast: display only (queueing/auto-dismiss are Tier 2) ------- *
+  /* --- toast: display only (queueing/auto-dismiss are JS-enhanced) ------- *
    * <m-toast popover="manual" role="status"> — manual so it survives
    * light dismiss and other popovers; role=status announces.
    * ------------------------------------------------------------------ */
@@ -1514,10 +1521,45 @@
       border-inline-start: 2px solid var(--color-warn);
     }
   }
-  /* restacking motion always (inset-block-end); the entrance slide/fade
-     only where overlay transitions work — see the base popover note. */
+  /* --toast-position overrides (base = bottom-right). Style queries read
+     the token from the toast's parent; without support the default
+     corner stands — graceful. Stack offset feeds whichever block inset
+     is active; centers use inset-inline 0 + auto margins. */
+  @container style(--toast-position: bottom-left) {
+    :where(m-toast[popover]) {
+      inset: auto auto calc(var(--space-lg) + var(--m-toast-offset, 0px)) var(--space-lg);
+    }
+  }
+  @container style(--toast-position: bottom-center) {
+    :where(m-toast[popover]) {
+      inset: auto 0 calc(var(--space-lg) + var(--m-toast-offset, 0px)) 0;
+      margin-inline: auto;
+    }
+  }
+  @container style(--toast-position: top-right) {
+    :where(m-toast[popover]) {
+      inset: calc(var(--space-lg) + var(--m-toast-offset, 0px)) var(--space-lg) auto auto;
+    }
+  }
+  @container style(--toast-position: top-left) {
+    :where(m-toast[popover]) {
+      inset: calc(var(--space-lg) + var(--m-toast-offset, 0px)) auto auto var(--space-lg);
+    }
+  }
+  @container style(--toast-position: top-center) {
+    :where(m-toast[popover]) {
+      inset: calc(var(--space-lg) + var(--m-toast-offset, 0px)) 0 auto 0;
+      margin-inline: auto;
+    }
+  }
+
+  /* restacking motion always (both block insets — only the active one
+     ever changes); the entrance slide/fade only where overlay
+     transitions work — see the base popover note. */
   :where(m-toast[popover]:popover-open) {
-    transition: inset-block-end 0.15s;
+    transition:
+      inset-block-end 0.15s,
+      inset-block-start 0.15s;
   }
   @supports (overlay: auto) {
     :where(m-toast[popover]:popover-open) {
@@ -1525,6 +1567,7 @@
         opacity 0.1s,
         translate 0.1s,
         inset-block-end 0.15s,
+        inset-block-start 0.15s,
         overlay 0.1s allow-discrete,
         display 0.1s allow-discrete;
     }
@@ -1533,6 +1576,17 @@
         translate: 0 0.75rem;
       }
     }
+    /* top positions enter from above — must follow the base
+       @starting-style in source order to win at equal specificity */
+    @container style(--toast-position: top-right) or
+               style(--toast-position: top-left) or
+               style(--toast-position: top-center) {
+      @starting-style {
+        :where(m-toast[popover]:popover-open) {
+          translate: 0 -0.75rem;
+        }
+      }
+    }
   }
 
   /* --- tooltip: css-only, [data-tip] -------------------------------- *
@@ -1572,9 +1626,9 @@
   }
 
   /* --- validation errors ------------------------------------------- *
-   * Tier 1 (no JS): a generic <m-error> after a field shows when the
+   * No JS: a generic <m-error> after a field shows when the
    * field is :user-invalid. Submit attempts fall back to native bubbles.
-   * Tier 2 (mica/field.js): <m-field> suppresses bubbles and activates
+   * Enhanced (mica/field.js): <m-field> suppresses bubbles and activates
    * per-cause <m-error match="..."> messages. Rules below are all
    * zero-specificity; source order resolves them.
    * ------------------------------------------------------------------ */
@@ -1591,13 +1645,13 @@
     color: var(--color-danger-text);
   }
 
-  /* Tier-1 fallback: generic (matchless) error after user interaction */
+  /* no-JS fallback: generic (matchless) error after user interaction */
   :where(input:user-invalid, textarea:user-invalid, select:user-invalid)
     ~ :where(m-error:not([match])) {
     display: block;
   }
 
-  /* Tier 2: once m-field upgrades, the module owns visibility */
+  /* enhanced: once m-field upgrades, the module owns visibility */
   :where(m-field:defined) :where(m-error) {
     display: none;
   }
@@ -1642,7 +1696,7 @@
 }
 
 /* ------------------------------------------------------------------ *
- * Layout primitives (Tier 0)
+ * Layout primitives (CSS-only)
  *
  * Mechanism: attributes only set custom properties; rules read custom
  * properties. `gap="lg"` and `style="--gap: 2.5rem"` are the same thing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akonwi/mica",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Custom elements. Native behavior. Nearly no JavaScript.",
   "keywords": [
     "css",
@@ -21,13 +21,34 @@
   "exports": {
     ".": "./mica.css",
     "./mica.css": "./mica.css",
-    "./invoker.js": "./invoker.js",
-    "./drawer.js": "./drawer.js",
-    "./field.js": "./field.js",
-    "./select.js": "./select.js",
-    "./tabs.js": "./tabs.js",
-    "./toast.js": "./toast.js",
-    "./combobox.js": "./combobox.js",
+    "./invoker.js": {
+      "types": "./invoker.d.ts",
+      "default": "./invoker.js"
+    },
+    "./drawer.js": {
+      "types": "./drawer.d.ts",
+      "default": "./drawer.js"
+    },
+    "./field.js": {
+      "types": "./field.d.ts",
+      "default": "./field.js"
+    },
+    "./select.js": {
+      "types": "./select.d.ts",
+      "default": "./select.js"
+    },
+    "./tabs.js": {
+      "types": "./tabs.d.ts",
+      "default": "./tabs.js"
+    },
+    "./toast.js": {
+      "types": "./toast.d.ts",
+      "default": "./toast.js"
+    },
+    "./combobox.js": {
+      "types": "./combobox.d.ts",
+      "default": "./combobox.js"
+    },
     "./types/react": {
       "types": "./types/react.d.ts"
     }
@@ -35,12 +56,19 @@
   "files": [
     "mica.css",
     "invoker.js",
+    "invoker.d.ts",
     "drawer.js",
+    "drawer.d.ts",
     "field.js",
+    "field.d.ts",
     "select.js",
+    "select.d.ts",
     "tabs.js",
+    "tabs.d.ts",
     "toast.js",
+    "toast.d.ts",
     "combobox.js",
+    "combobox.d.ts",
     "types/react.d.ts"
   ],
   "sideEffects": true,

package/select.d.ts

@@ -0,0 +1,5 @@
+/* Type declarations for mica/select.js — side-effect module.
+ * Aligns the open select picker with the selected option
+ * (alignItemWithTrigger). No exports; supplies --m-sel-index to CSS.
+ */
+export {};

package/select.js

@@ -1,6 +1,6 @@
 /* mica/select.js — align the open select picker so the selected option
  * overlays the trigger (macOS-native / Base UI `alignItemWithTrigger`
- * behavior). Tier 2, and about as small as a module can be:
+ * behavior). A JS-enhanced module, and about as small as a module can be:
  *
  * JS supplies exactly one datum — the selected index, as a custom
  * property. All geometry lives in mica.css (anchor positioning).

package/tabs.d.ts

@@ -0,0 +1,9 @@
+/* Type declarations for mica/tabs.js — side-effect module.
+ * Registers <m-tabs>: roving tabindex, arrow keys, aria-selected wiring.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    "m-tabs": HTMLElement;
+  }
+}
+export {};

package/tabs.js

@@ -1,4 +1,4 @@
-/* mica/tabs.js — <m-tabs>: accessible tabs. Tier 2.
+/* mica/tabs.js — <m-tabs>: accessible tabs. JS-enhanced module.
  *
  * Enhances working light-DOM markup; never renders it. Without this
  * module, the nav buttons are inert and every panel is visible in

package/toast.d.ts

@@ -0,0 +1,17 @@
+/* Type declarations for mica/toast.js.
+ * Importing registers <m-toast> (queueing, auto-dismiss, restacking) and
+ * exports the imperative spawner.
+ */
+export interface ToastOptions {
+  description?: string;
+  variant?: "success" | "warning" | "danger";
+  /** Auto-dismiss delay in ms; string accepted as attribute passthrough. */
+  duration?: number | string;
+}
+/** Create, show, and return an <m-toast> element. */
+export function toast(title: string, options?: ToastOptions): HTMLElement;
+declare global {
+  interface HTMLElementTagNameMap {
+    "m-toast": HTMLElement;
+  }
+}

package/toast.js

@@ -1,7 +1,7 @@
 /* mica/toast.js — toast stacking, auto-dismiss, and a spawn helper.
- * Tier 2.
+ * JS-enhanced module.
  *
- * Enhances the Tier-1 <m-toast> recipe (corner-pinned manual popovers).
+ * Enhances the no-JS <m-toast> recipe (corner-pinned manual popovers).
  * Declared toasts keep working without this module — it adds:
  *
  * - stacking: open toasts stack upward; JS ships one number per toast