@akonwi/mica 0.2.2 → 0.4.0

package/README.md

@@ -12,8 +12,8 @@ there's nothing there but HTML and a stylesheet.
 <m-vstack gap="lg">
   <h1>That's it</h1>
   <m-hstack gap="sm">
-    <button class="primary">Save</button>
-    <button class="ghost">Cancel</button>
+    <button data-variant="primary">Save</button>
+    <button data-variant="ghost">Cancel</button>
   </m-hstack>
 </m-vstack>
 ```

package/drawer.js

@@ -1,5 +1,5 @@
-/* mica/drawer.js — Tier 2: swipe-to-dismiss for dialog.drawer bottom
- * sheets on small screens.
+/* mica/drawer.js — Tier 2: swipe-to-dismiss for dialog[data-drawer]
+ * bottom sheets on small screens.
  *
  * Enhances working markup, never replaces it: without this module the
  * drawer opens/closes via buttons and Esc; with it, the mobile sheet
@@ -16,6 +16,7 @@
 const SHEET = matchMedia("(max-width: 40rem)");
 const CLOSE_DISTANCE = 1 / 3; // of sheet height
 const CLOSE_VELOCITY = 0.6; // px/ms, downward flick
+const DRAWER = "dialog:is([data-drawer], .drawer)";
 
 document.documentElement.setAttribute("data-drawer-gestures", "");
 
@@ -23,13 +24,13 @@ document.addEventListener("pointerdown", (down) => {
   if (!SHEET.matches) return;
   const dialog =
     down.target instanceof Element &&
-    down.target.closest("dialog.drawer[open]");
+    down.target.closest(`${DRAWER}[open]`);
   if (!dialog) return;
   if (down.target.closest("button, a, input, select, textarea")) return;
 
   // start only from the header or the top (handle) strip
   const rect = dialog.getBoundingClientRect();
-  const inHeader = down.target.closest("dialog.drawer > header");
+  const inHeader = down.target.closest(`${DRAWER} > header`);
   if (!inHeader && down.clientY - rect.top > 32) return;
 
   let dy = 0;

package/mica.css

@@ -268,8 +268,8 @@
 
 /* ------------------------------------------------------------------ *
  * Elements — Tier 1. Native elements styled directly; behavior is the
- * browser's. Variants are classes: any collision with app CSS resolves
- * in the user's favor because these live in a layer.
+ * browser's. Presentation APIs are attributes; user CSS still wins
+ * because these rules live in a layer.
  * ------------------------------------------------------------------ */
 @layer mica.elements {
   /* --- button (and things dressed as buttons) ---------------------- */
@@ -298,8 +298,8 @@
       background: var(--neutral-4);
     }
 
-    /* variants */
-    &:where(.primary) {
+    /* Class selectors remain aliases for the former class-based API. */
+    &:where([data-variant="primary"], .primary) {
       background: var(--color-primary);
       border-color: transparent;
       color: var(--color-on-primary);
@@ -316,7 +316,7 @@
          secondary button when primary is near-black */
     }
 
-    &:where(.danger) {
+    &:where([data-variant="danger"], .danger) {
       background: var(--color-danger);
       border-color: transparent;
       color: var(--color-on-danger);
@@ -333,9 +333,9 @@
     }
 
     /* deliberately zero rest affordance — a ghost is invisible until
-       hover/focus. use .ghost for toolbars and icon rows, not as the
-       lone action on a page. */
-    &:where(.ghost) {
+       hover/focus. use data-variant="ghost" for toolbars and icon rows,
+       not as the lone action on a page. */
+    &:where([data-variant="ghost"], .ghost) {
       background: transparent;
       border-color: transparent;
 
@@ -348,11 +348,11 @@
     }
 
     /* sizes (shadcn: h-8 px-3 / h-10 px-6, text-sm throughout) */
-    &:where(.small) {
+    &:where([data-size="small"], .small) {
       block-size: var(--control-height-sm);
       padding-inline: var(--space-sm);
     }
-    &:where(.large) {
+    &:where([data-size="large"], .large) {
       block-size: var(--control-height-lg);
       padding-inline: var(--space-lg);
     }
@@ -572,7 +572,7 @@
     }
   }
 
-  :where(input[type="checkbox"]:not(.switch)) {
+  :where(input[type="checkbox"]:not(.switch, [role="switch"])) {
     &:checked {
       background-image: var(--check-glyph);
     }
@@ -644,16 +644,9 @@
     border-inline-start: 1px solid var(--color-border-strong);
   }
 
-  :where(m-segmented) > :where(label) > :where(input[type="radio"]) {
-    position: absolute;
-    inline-size: 1px;
-    block-size: 1px;
-    margin: -1px;
-    padding: 0;
-    overflow: hidden;
-    clip-path: inset(50%);
-    white-space: nowrap;
-  }
+  /* The radio itself is hidden but focusable and announced — the label
+     is the visible control. Shares the one hiding rule at the end of
+     this layer (see "visually hidden"). */
 
   :where(m-segmented) > :where(label):has(> input:checked) {
     background: var(--color-primary);
@@ -675,8 +668,9 @@
 
   /* switch: a checkbox wearing a track; the thumb is a positioned
      gradient (pseudo-elements don't render on inputs). square, per the
-     design language — a solid linear-gradient block */
-  :where(input[type="checkbox"].switch) {
+     design language — a solid linear-gradient block. .switch remains
+     an alias for the former class-based API. */
+  :where(input[type="checkbox"]:is([role="switch"], .switch)) {
     inline-size: 2.25rem;
     border-color: transparent;
     border-radius: var(--radius-sm);
@@ -1088,8 +1082,9 @@
 
   /* drawer (shadcn sheet anatomy): inline-end panel, fade + 2.5rem
      nudge rather than a full slide; no section dividers; footer pinned
-     to the bottom with stacked actions */
-  :where(dialog.drawer) {
+     to the bottom with stacked actions. .drawer remains an alias for
+     the former class-based API. */
+  :where(dialog[data-drawer], dialog.drawer) {
     margin-inline: auto 0;
     margin-block: 0;
     /* full height WITHOUT an explicit block-size: the UA gives
@@ -1109,23 +1104,24 @@
     scale: 1;
     translate: 2.5rem 0;
   }
-  :where(dialog.drawer[open]) {
+  :where(dialog[data-drawer][open], dialog.drawer[open]) {
     translate: 0 0;
   }
   /* unconditional (survives the exit, like the rest of composition) */
-  :where(dialog.drawer) > :where(:not(header, footer, button.close)) {
+  :where(dialog[data-drawer], dialog.drawer)
+    > :where(:not(header, footer, button.close)) {
     font-size: inherit; /* panel runs 12/relaxed throughout */
   }
   @starting-style {
-    :where(dialog.drawer[open]) {
+    :where(dialog[data-drawer][open], dialog.drawer[open]) {
       translate: 2.5rem 0;
     }
   }
 
-  :where(dialog.drawer) > :where(header) {
+  :where(dialog[data-drawer], dialog.drawer) > :where(header) {
     border-block-end: 0;
   }
-  :where(dialog.drawer) > :where(footer) {
+  :where(dialog[data-drawer], dialog.drawer) > :where(footer) {
     margin-block-start: auto;
     flex-direction: column;
     align-items: stretch;
@@ -1140,7 +1136,7 @@
      nav bars). Explicit 100svh gapped behind the collapsed toolbar and
      100dvh lagged in the top layer — don't reintroduce heights here. */
   @media (max-width: 40rem) {
-    :where(dialog.drawer) {
+    :where(dialog[data-drawer], dialog.drawer) {
       inset-block: auto 0;       /* release the UA's top anchor… */
       margin-block: 0;           /* …so height resolves from content */
       block-size: auto;          /* content height, like vaul */
@@ -1171,14 +1167,14 @@
       translate: 0 100%;
       opacity: 1;
     }
-    :where(dialog.drawer[open]) {
+    :where(dialog[data-drawer][open], dialog.drawer[open]) {
       translate: 0 0;
       box-shadow:
         0 4rem 0 0 var(--color-surface-overlay),
         0 0 0 100vmax oklch(0 0 0 / 0.4);
     }
     @starting-style {
-      :where(dialog.drawer[open]) {
+      :where(dialog[data-drawer][open], dialog.drawer[open]) {
         translate: 0 100%;
         box-shadow:
           0 4rem 0 0 var(--color-surface-overlay),
@@ -1187,14 +1183,15 @@
     }
     /* the box-shadow scrim replaces ::backdrop here; keep the native
        backdrop clear so they don't double up or flash on the iOS cut. */
-    :where(dialog.drawer[open])::backdrop {
+    :where(dialog[data-drawer][open], dialog.drawer[open])::backdrop {
       background: oklch(0 0 0 / 0);
     }
 
     /* grab handle — only when drawer.js is loaded (an affordance
        without its behavior would fake interactivity; TIERS.md).
        the handle is the first flex item of the open sheet. */
-    :where(:root[data-drawer-gestures]) :where(dialog.drawer[open])::before {
+    :where(:root[data-drawer-gestures])
+      :where(dialog[data-drawer][open], dialog.drawer[open])::before {
       content: "";
       align-self: center;
       flex-shrink: 0;
@@ -1204,7 +1201,8 @@
       background: var(--color-border-strong);
       border-radius: var(--radius-full);
     }
-    :where(:root[data-drawer-gestures]) :where(dialog.drawer) > :where(header) {
+    :where(:root[data-drawer-gestures])
+      :where(dialog[data-drawer], dialog.drawer) > :where(header) {
       touch-action: none; /* the drag surface must own its touches */
     }
   }
@@ -1365,7 +1363,7 @@
         color: var(--color-on-accent);
       }
 
-      &.danger {
+      &:is([data-variant="danger"], .danger) {
         color: var(--color-danger-text);
 
         &:hover:not(:disabled, [aria-disabled="true"]),
@@ -1510,14 +1508,14 @@
       color: var(--color-text-muted);
     }
 
-    /* status edge variants */
-    &:where(.success) {
+    /* Status classes remain aliases for the former class-based API. */
+    &:where([data-variant="success"], .success) {
       border-inline-start: 2px solid var(--color-success);
     }
-    &:where(.danger) {
+    &:where([data-variant="danger"], .danger) {
       border-inline-start: 2px solid var(--color-danger);
     }
-    &:where(.warn) {
+    &:where([data-variant="warning"], .warn) {
       border-inline-start: 2px solid var(--color-warn);
     }
   }
@@ -1611,6 +1609,41 @@
   :where(m-error[active]) {
     display: block;
   }
+
+  /* --- visually hidden: off-screen, still announced ------------------ *
+   *
+   * The one utility mica ships, and an accessibility primitive rather
+   * than a style: content that assistive tech must reach but sighted
+   * users must not see. `display: none` and `inline-size: 0` would drop
+   * it from the accessibility tree; this keeps a 1px box in flow-ish
+   * and clips it away.
+   *
+   * An attribute, not a class: `class` stays the app's, `data-*` is
+   * valid HTML and needs no React `HTMLAttributes` augmentation, and
+   * `.visually-hidden`/`.sr-only` are the most copy-pasted names in
+   * accessibility — a consumer arriving with their own copy is the
+   * likely case. Lives at the end of this layer, not a new one, because
+   * the layer list is a published contract; being last lets it beat the
+   * element rules it is applied to (`caption`, `legend`, headings).
+   *
+   *   <caption data-visually-hidden>Standings</caption>
+   *   <a href="#main" data-visually-hidden="focusable">Skip to content</a>
+   *
+   * The `focusable` variant is the skip-link primitive: hidden until it
+   * takes focus, then it simply stops being hidden — no undo rule, so
+   * the element keeps whatever styling the app gave it. */
+  [data-visually-hidden]:not([data-visually-hidden="focusable"]),
+  [data-visually-hidden="focusable"]:not(:focus, :focus-within),
+  :where(m-segmented) > :where(label) > :where(input[type="radio"]) {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
 }
 
 /* ------------------------------------------------------------------ *
@@ -1843,8 +1876,8 @@
 
   /* --- m-cover: fill the viewport, center the principal element ---- *
    * The principal element (h1 by default, or mark one child with
-   * .principal) is vertically centered; children before it pin to the
-   * top, children after it pin to the bottom.                         */
+   * data-principal) is vertically centered; children before it pin to
+   * the top, children after it pin to the bottom.                     */
   m-cover {
     display: flex;
     flex-direction: column;
@@ -1860,9 +1893,11 @@
 
     & > * { margin-block: 0; }
 
-    & > :is(h1, .principal) { margin-block: auto; }
+    & > :is(h1, [data-principal], .principal) { margin-block: auto; }
 
-    /* an explicit .principal wins over the h1 default */
-    &:has(> .principal) > h1:not(.principal) { margin-block: 0; }
+    /* An explicit marker wins over the h1 default. .principal remains
+       an alias for the former class-based API. */
+    &:has(> :is([data-principal], .principal))
+      > h1:not([data-principal], .principal) { margin-block: 0; }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akonwi/mica",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Custom elements. Native behavior. Nearly no JavaScript.",
   "keywords": [
     "css",
@@ -55,4 +55,4 @@
     "snapshot:check": "bun tools/snapshot.ts --check",
     "snapshot:setup": "playwright install chromium webkit"
   }
-}
+}

package/toast.js

@@ -6,10 +6,11 @@
  *
  * - stacking: open toasts stack upward; JS ships one number per toast
  *   (--m-toast-offset), CSS owns the geometry and the reflow motion
- * - auto-dismiss: `duration` attribute in ms (default 5000, "0" = sticky),
- *   paused while hovered
+ * - auto-dismiss: `data-duration` attribute in ms (default 5000,
+ *   "0" = sticky), paused while hovered
  * - toast(title, { description, variant, duration }): spawns the same
- *   recipe markup, shows it, and removes it after dismissal
+ *   recipe markup (`variant`: success, warning, or danger), shows it,
+ *   and removes it after dismissal
  */
 
 const GAP = 8;
@@ -30,8 +31,10 @@ function restack() {
 }
 
 function startTimer(el) {
-  const ms = el.hasAttribute("duration")
-    ? Number(el.getAttribute("duration"))
+  const duration =
+    el.getAttribute("data-duration") ?? el.getAttribute("duration");
+  const ms = duration !== null
+    ? Number(duration)
     : DEFAULT_DURATION;
   if (!ms) return;
   timers.set(el, setTimeout(() => el.hidePopover(), ms));
@@ -74,10 +77,15 @@ document.addEventListener(
 export function toast(title, { description = "", variant = "", duration } = {}) {
   const el = document.createElement("div");
   el.popover = "manual";
+  // Keep the generated class for consumers of the former API while
+  // emitting the attribute vocabulary used by declared toasts.
   el.className = `toast${variant ? ` ${variant}` : ""}`;
+  if (variant) {
+    el.setAttribute("data-variant", variant === "warn" ? "warning" : variant);
+  }
   el.setAttribute("role", "status");
   el.dataset.ephemeral = "";
-  if (duration !== undefined) el.setAttribute("duration", String(duration));
+  if (duration !== undefined) el.setAttribute("data-duration", String(duration));
 
   const x = document.createElement("button");
   x.className = "close";