@akonwi/mica 0.2.1 → 0.3.0

package/mica.css

@@ -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);
@@ -1611,6 +1604,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;
+  }
 }
 
 /* ------------------------------------------------------------------ *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akonwi/mica",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Custom elements. Native behavior. Nearly no JavaScript.",
   "keywords": [
     "css",
@@ -27,7 +27,10 @@
     "./select.js": "./select.js",
     "./tabs.js": "./tabs.js",
     "./toast.js": "./toast.js",
-    "./combobox.js": "./combobox.js"
+    "./combobox.js": "./combobox.js",
+    "./types/react": {
+      "types": "./types/react.d.ts"
+    }
   },
   "files": [
     "mica.css",
@@ -37,7 +40,8 @@
     "select.js",
     "tabs.js",
     "toast.js",
-    "combobox.js"
+    "combobox.js",
+    "types/react.d.ts"
   ],
   "sideEffects": true,
   "devDependencies": {
@@ -51,4 +55,4 @@
     "snapshot:check": "bun tools/snapshot.ts --check",
     "snapshot:setup": "playwright install chromium webkit"
   }
-}
+}

package/types/react.d.ts

@@ -0,0 +1,64 @@
+// React JSX typings for mica's custom elements.
+//
+// React 19 supports custom elements natively; this file only teaches
+// TypeScript the tags and their styling attributes. It is the typed
+// mirror of the attribute selectors in mica.css — when an element or
+// attribute changes there, it changes here.
+//
+// Usage (tsconfig `include` or a triple-slash reference):
+//   /// <reference types="@akonwi/mica/types/react" />
+// or copy the file alongside a vendored mica.css.
+
+import type { DetailedHTMLProps, HTMLAttributes } from 'react'
+
+type Gap = 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+type Align = 'start' | 'center' | 'end' | 'stretch'
+type Justify = 'start' | 'center' | 'end' | 'between' | 'stretch'
+type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+type MicaElement<Extra = Record<never, never>> = DetailedHTMLProps<
+  HTMLAttributes<HTMLElement>,
+  HTMLElement
+> &
+  Extra
+
+type StackProps = {
+  gap?: Gap
+  align?: Align
+  justify?: Justify
+}
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      // layout
+      'm-vstack': MicaElement<StackProps>
+      'm-hstack': MicaElement<StackProps & { wrap?: boolean }>
+      'm-zstack': MicaElement
+      'm-center': MicaElement
+      'm-box': MicaElement
+      'm-grid': MicaElement<{ min?: Breakpoint; gap?: Gap }>
+      'm-sidecar': MicaElement<{ side?: 'start' | 'end'; gap?: Gap }>
+      'm-switcher': MicaElement<{ threshold?: Breakpoint; gap?: Gap }>
+      'm-reel': MicaElement<{ gap?: Gap }>
+      'm-frame': MicaElement<{
+        ratio?: 'square' | '16:9' | '9:16' | '4:3' | '3:2' | '2:1'
+      }>
+      'm-cover': MicaElement<{
+        gap?: Gap
+        pad?: 'none' | 'sm' | 'md' | 'lg' | 'xl'
+      }>
+
+      // components
+      'm-segmented': MicaElement
+      'm-tabs': MicaElement
+      'm-badge': MicaElement<{
+        variant?: 'primary' | 'success' | 'warning' | 'danger'
+        count?: boolean
+      }>
+      'm-field': MicaElement
+      'm-error': MicaElement<{ active?: boolean }>
+      'm-combobox': MicaElement
+    }
+  }
+}