@ponchia/ui 0.6.11 → 0.6.12

package/docs/stability.md

@@ -1,4 +1,4 @@
-# Public API Stability
+# Public API stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
 patches are non-breaking. In practical terms: **PATCH releases (`0.6.x`) are
@@ -11,7 +11,7 @@ For the exhaustive package-manifest inventory — every `exports` key, every
 shipped `files` entry, and the generated artifact provenance map — see
 [package-contract.md](./package-contract.md).
 
-## Path To 1.0
+## Path to 1.0
 
 `1.0.0` is a stability declaration, not a catalog milestone. The package is
 ready for 1.0 when the existing public contract is boring to upgrade:
@@ -36,7 +36,7 @@ ready for 1.0 when the existing public contract is boring to upgrade:
   migration entry when machine-actionable, and the deprecate-one-minor policy
   has been followed or explicitly exempted for provably-unreferenced surface.
 
-### 1.0 Readiness Ledger
+### 1.0 readiness ledger
 
 This ledger is the release-candidate checklist. A row is ready only when the
 evidence column is green for the candidate commit; prose approval alone is not
@@ -51,6 +51,31 @@ enough.
 | Bundle budget has headroom | `check:dist`, `check:public-metadata`, `check:pack`, and the README size badge keep default bundle and tarball claims visible. | Budget increases are intentional, reviewed, and named in `CHANGELOG.md`; accidental growth fails before release. |
 | Deprecation history is clean | `check:migrations`, `check:release`, `check:versions`, `MIGRATIONS.json`, and this deprecation policy tie breaking changes to changelog and migration evidence. | No removal ships without either a deprecate-one-minor trail or an explicit BREAKING note for provably-unreferenced surface. |
 
+### Adoption evidence for 1.0
+
+This snapshot records product evidence as of 2026-07-10. Use three evidence
+classes:
+
+- **Downstream-proven:** A non-example app, site, report generator, or tool
+  imports the published surface and passes its own build or checks.
+- **Package-proven:** Packed examples, unit tests, browser tests, and type tests
+  prove compatibility, but no inspected non-example consumer imports the
+  surface.
+- **Speculative:** Neither downstream use nor a package-level executable proof
+  justifies freezing the surface into 1.0.
+
+Package-proven is necessary but does not establish demand. During the catalog
+freeze, do not expand package-only surfaces. Recheck this table against real
+consumer upgrades before the 1.0 release candidate.
+
+| Surface family | Current evidence | 1.0 disposition |
+| --- | --- | --- |
+| Core CSS, class recipes, vanilla behaviors, tokens, and Tailwind bridge | Downstream-proven across five inspected non-example app, site, and service consumers. | Stabilize names and behavior contracts. Use consumer upgrades as the release-candidate proof. |
+| Report, provenance, analytical CSS, annotations, glyphs, skins, workbench CSS, chart data, and Vega theme | Downstream-proven across four inspected report, site, dashboard, and tool consumers. | Keep opt-in. Stabilize the consumed paths; do not broaden the catalog during the freeze. |
+| Controlled non-`<dialog>` modal | Package-proven by stack, portal, late-node, focus, and cleanup regressions. No inspected non-example consumer initializes `initModal`. | Keep compatible through 0.6.x, but require a real consumer before declaring this alternative to native `<dialog>` stable in 1.0. |
+| React, Solid, Qwik, Svelte, and Vue lifecycle adapters | Package-proven by packed examples, types, and lifecycle tests. No inspected non-example consumer imports an adapter entrypoint. | Pre-1.0 candidate only. Freeze the adapter set and require downstream adoption before declaring all five stable in 1.0. |
+| Mermaid, D2, Shiki, Figma Variables, and the report-claims schema | Package-proven by generated-data, render, schema, and drift checks. No inspected non-example consumer currently supplies downstream proof for every path. | Keep compatible through 0.6.x, but decide each 1.0 contract from adoption evidence rather than generator coverage alone. |
+
 After 1.0, breaking changes move to majors. Until then, the table below is the
 current public-surface matrix and the release policy above still applies.
 
@@ -104,13 +129,13 @@ current public-surface matrix and the release policy above still applies.
 | Terms / glossary (`css/term.css`, `.ui-term`, `.ui-glossary`) | Stable additive | Term and glossary class names plus native-popover definition hooks are public. Opt-in, not in the default bundle. The host owns glossary content and terminology policy. |
 | Contents rail (`css/toc.css`, `.ui-toc*`) | Stable additive | TOC rail class/part names and current-section state classes are public. Opt-in, not in the default bundle. The host owns section observation and active-state updates. |
 | Tree outlines (`css/tree.css`, `.ui-tree*`) | Stable additive | Tree outline class names, depth styling, and native `<details>` composition are public. Opt-in, not in the default bundle. The host owns tree data, lazy loading, and selection state. |
-| Controlled-modal focus trap (`initModal`, `useModal`, `data-bronto-modal`) | Stable additive | For the `.ui-modal.is-open` (non-`<dialog>`) path: the `data-bronto-modal` opt-in marker, the `inert`-based focus trap + focus-return, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; the behavior never changes visibility. The native `<dialog>` path (`initDialog`) is the default and gets the trap for free. |
+| Controlled-modal focus trap (`initModal`, `useModal`, `data-bronto-modal`) | Stable additive | For the `.ui-modal.is-open` (non-`<dialog>`) path: the `data-bronto-modal` opt-in marker, stack-aware `inert` ownership, focus-return, late-background trapping, owned portaled-popover admission, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; closing a parent suspends still-open controlled descendants until the parent reopens. The native `<dialog>` path (`initDialog`) remains the default. |
 | Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |
 | Agent and migration data (`llms.txt`, `MIGRATIONS.json`) | Stable additive | `llms.txt` stays shipped as the offline agent entrypoint. `MIGRATIONS.json` stays a machine-readable migration map for breaking renames/removals. New migration entries are additive; removal of a migration record requires the same breaking-change discipline as the surface it describes. |
 | Generated docs shipped in npm | Stable paths | Exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
 | Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |
 
-## Deprecation Policy
+## Deprecation policy
 
 Public surface (`.ui-*` classes, `data-bronto-*` attributes, `cls`/token keys,
 behavior signatures, and exported schema values) is removed on a
@@ -126,7 +151,7 @@ A token/class/attribute that is provably referenced by no shipped CSS,
 component, behavior, or doc may skip that window and be removed with a BREAKING
 entry plus migration note; there is no working call-site to keep alive.
 
-## Trust Boundary
+## Trust boundary
 
 Behaviors assume trusted application markup. If a delegated root includes
 untrusted CMS or user HTML, sanitize it first or do not initialize behaviors on

package/docs/usage.md

@@ -377,6 +377,16 @@ also gives the overlay `role="dialog"` + `aria-modal="true"` and dev-warns if it
 has no accessible name (add `aria-label`/`aria-labelledby`). A drawer is a modal
 that enters from an edge — same rule.
 
+Controlled modals share one document-level stack. Opening a sibling portal
+modal makes the previous modal inert and keeps only the new top modal
+interactive; closing it restores focus into the previous modal. An
+`initPopover()` trigger inside the top modal may target a panel portaled
+elsewhere in the document: while that panel is open, it joins the live modal
+tree and owns Escape without releasing unrelated background content. Background
+nodes added after the modal opens are trapped too. If a controlled parent modal
+closes while a descendant still carries `is-open`, the descendant is suspended
+with the parent and resumes if the parent reopens.
+
 **Scroll-lock is not automatic on either path.** Neither the native `<dialog>`
 nor the `is-open` path freezes the background — the page behind an open modal can
 still scroll. If that matters, toggle a lock yourself while the modal is open

package/llms.txt

@@ -45,7 +45,7 @@ the path changes from source `css/` to built `dist/css/`:
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
 <!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.11/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "type": "module",
   "description": "CSS-first identity and UI layer for services, tools, sites, and reports — works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
   "keywords": [

package/tokens/figma.variables.json

@@ -2030,12 +2030,12 @@
           "type": "FLOAT",
           "sourceCssVariable": "--text-2xs",
           "valuesByMode": {
-            "global": 0.68
+            "global": 0.72
           },
           "$extensions": {
             "com.ponchia.css": {
               "variable": "--text-2xs",
-              "value": "0.68rem"
+              "value": "0.72rem"
             }
           },
           "unit": "rem"

package/tokens/index.js

@@ -40,7 +40,7 @@ export const cssVars = {
     '--display': 'var(--dot-font)',
     '--display-weight': '700',
     '--display-weight-strong': '800',
-    '--text-2xs': '0.68rem',
+    '--text-2xs': '0.72rem',
     '--text-xs': '0.76rem',
     '--text-sm': '0.86rem',
     '--text-base': '0.95rem',

package/tokens/index.json

@@ -20,7 +20,7 @@
       "--display": "var(--dot-font)",
       "--display-weight": "700",
       "--display-weight-strong": "800",
-      "--text-2xs": "0.68rem",
+      "--text-2xs": "0.72rem",
       "--text-xs": "0.76rem",
       "--text-sm": "0.86rem",
       "--text-base": "0.95rem",
@@ -165,7 +165,7 @@
       "display": "var(--dot-font)",
       "display-weight": "700",
       "display-weight-strong": "800",
-      "text-2xs": "0.68rem",
+      "text-2xs": "0.72rem",
       "text-xs": "0.76rem",
       "text-sm": "0.86rem",
       "text-base": "0.95rem",

package/tokens/resolved.json

@@ -147,7 +147,7 @@
     "--display": "'Doto', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace",
     "--display-weight": "700",
     "--display-weight-strong": "800",
-    "--text-2xs": "0.68rem",
+    "--text-2xs": "0.72rem",
     "--text-xs": "0.76rem",
     "--text-sm": "0.86rem",
     "--text-base": "0.95rem",

package/tokens/tokens.dtcg.json

@@ -117,7 +117,7 @@
     "text": {
       "2xs": {
         "$type": "dimension",
-        "$value": "0.68rem"
+        "$value": "0.72rem"
       },
       "xs": {
         "$type": "dimension",