@akonwi/mica 0.5.0 → 0.7.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

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.
  * ------------------------------------------------------------------ */
@@ -979,7 +986,7 @@
      command="close" aria-label="Close">✕</button> (or wrap it in a
      method=dialog form). absolute is safe: the dialog is positioned.
      shared with toasts (popovertarget/popovertargetaction=hide there). */
-  :where(dialog, [popover].toast) > :where(button.close) {
+  :where(dialog, m-toast[popover]) > :where(button.close) {
     position: absolute;
     inset-block-start: var(--space-sm);
     inset-inline-end: var(--space-sm);
@@ -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,11 +1488,11 @@
     padding-block: var(--space-md);
   }
 
-  /* --- toast: display only (queueing/auto-dismiss are Tier 2) ------- *
-   * <div popover="manual" class="toast" role="status"> — manual so it
-   * survives light dismiss and other popovers; role=status announces.
+  /* --- 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.
    * ------------------------------------------------------------------ */
-  :where([popover].toast) {
+  :where(m-toast[popover]) {
     position-area: none; /* not anchored — pinned to the corner */
     /* --m-toast-offset comes from toast.js when stacking; 0 without it */
     inset: auto var(--space-lg) calc(var(--space-lg) + var(--m-toast-offset, 0px)) auto;
@@ -1504,35 +1511,82 @@
       color: var(--color-text-muted);
     }
 
-    &:where([data-variant="success"]) {
+    &:where([variant="success"]) {
       border-inline-start: 2px solid var(--color-success);
     }
-    &:where([data-variant="danger"]) {
+    &:where([variant="danger"]) {
       border-inline-start: 2px solid var(--color-danger);
     }
-    &:where([data-variant="warning"]) {
+    &:where([variant="warning"]) {
       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. */
-  :where([popover].toast:popover-open) {
-    transition: inset-block-end 0.15s;
+  /* --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,
+      inset-block-start 0.15s;
   }
   @supports (overlay: auto) {
-    :where([popover].toast:popover-open) {
+    :where(m-toast[popover]:popover-open) {
       transition:
         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;
     }
     @starting-style {
-      :where([popover].toast:popover-open) {
+      :where(m-toast[popover]:popover-open) {
         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.5.0",
+  "version": "0.7.0",
   "description": "Custom elements. Native behavior. Nearly no JavaScript.",
   "keywords": [
     "css",
@@ -21,13 +21,13 @@
   "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 +35,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,12 +1,12 @@
 /* mica/toast.js — toast stacking, auto-dismiss, and a spawn helper.
- * Tier 2.
+ * JS-enhanced module.
  *
- * Enhances the Tier-1 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
  *   (--m-toast-offset), CSS owns the geometry and the reflow motion
- * - auto-dismiss: `data-duration` attribute in ms (default 5000,
+ * - auto-dismiss: `duration` attribute in ms (default 5000,
  *   "0" = sticky), paused while hovered
  * - toast(title, { description, variant, duration }): spawns the same
  *   recipe markup (`variant`: success, warning, or danger), shows it,
@@ -20,7 +20,7 @@ const open = [];
 const timers = new WeakMap();
 
 const isToast = (el) =>
-  el instanceof HTMLElement && el.matches("[popover].toast");
+  el instanceof HTMLElement && el.matches("m-toast[popover]");
 
 function restack() {
   let offset = 0;
@@ -31,8 +31,7 @@ function restack() {
 }
 
 function startTimer(el) {
-  const duration =
-    el.getAttribute("data-duration") ?? el.getAttribute("duration");
+  const duration = el.getAttribute("duration");
   const ms = duration !== null
     ? Number(duration)
     : DEFAULT_DURATION;
@@ -75,13 +74,12 @@ document.addEventListener(
 );
 
 export function toast(title, { description = "", variant = "", duration } = {}) {
-  const el = document.createElement("div");
+  const el = document.createElement("m-toast");
   el.popover = "manual";
-  el.className = "toast";
-  if (variant) el.setAttribute("data-variant", variant);
+  if (variant) el.setAttribute("variant", variant);
   el.setAttribute("role", "status");
   el.dataset.ephemeral = "";
-  if (duration !== undefined) el.setAttribute("data-duration", String(duration));
+  if (duration !== undefined) el.setAttribute("duration", String(duration));
 
   const x = document.createElement("button");
   x.className = "close";

package/types/react.d.ts

@@ -56,6 +56,11 @@ declare module 'react' {
         variant?: 'primary' | 'success' | 'warning' | 'danger'
         count?: boolean
       }>
+      'm-toast': MicaElement<{
+        popover?: 'manual'
+        variant?: 'success' | 'warning' | 'danger'
+        duration?: string | number
+      }>
       'm-field': MicaElement
       'm-error': MicaElement<{ active?: boolean }>
       'm-combobox': MicaElement