@ponchia/ui 0.6.0 → 0.6.3

package/classes/classes.json

@@ -1,8 +1,8 @@
 {
-  "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
+  "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `groups[].base` is null for a parts-only namespace (no standalone base class — do NOT emit it). A modifier whose name contains `__` (e.g. `ui-spark__bar--pos`) attaches to THAT part, not the base host. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `behaviorAttributes` are the `data-bronto-*` wiring hooks the optional behaviors delegate on; `requiredAria` is the role/aria a generator must emit per component. `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
   "counts": {
-    "classes": 477,
-    "groups": 149
+    "classes": 529,
+    "groups": 161
   },
   "groups": {
     "ui-accordion": {
@@ -25,7 +25,7 @@
       ],
       "parts": [
         "ui-alert__body",
-        "ui-alert__dismiss",
+        "ui-alert__close",
         "ui-alert__title"
       ]
     },
@@ -220,6 +220,19 @@
       "modifiers": [],
       "parts": []
     },
+    "ui-bullet": {
+      "base": "ui-bullet",
+      "modifiers": [
+        "ui-bullet__measure--accent",
+        "ui-bullet__measure--neg",
+        "ui-bullet__measure--pos"
+      ],
+      "parts": [
+        "ui-bullet__label",
+        "ui-bullet__measure",
+        "ui-bullet__target"
+      ]
+    },
     "ui-button": {
       "base": "ui-button",
       "modifiers": [
@@ -292,6 +305,20 @@
       ],
       "parts": []
     },
+    "ui-code": {
+      "base": "ui-code",
+      "modifiers": [
+        "ui-code--numbered",
+        "ui-code__line--add",
+        "ui-code__line--hl",
+        "ui-code__line--remove"
+      ],
+      "parts": [
+        "ui-code__body",
+        "ui-code__head",
+        "ui-code__line"
+      ]
+    },
     "ui-combobox": {
       "base": "ui-combobox",
       "modifiers": [],
@@ -367,6 +394,11 @@
         "ui-crosshair__line"
       ]
     },
+    "ui-def": {
+      "base": "ui-def",
+      "modifiers": [],
+      "parts": []
+    },
     "ui-delta": {
       "base": "ui-delta",
       "modifiers": [
@@ -377,6 +409,23 @@
       ],
       "parts": []
     },
+    "ui-diff": {
+      "base": "ui-diff",
+      "modifiers": [
+        "ui-diff--split",
+        "ui-diff__row--add",
+        "ui-diff__row--context",
+        "ui-diff__row--remove"
+      ],
+      "parts": [
+        "ui-diff__code",
+        "ui-diff__head",
+        "ui-diff__hunk",
+        "ui-diff__ln",
+        "ui-diff__pane",
+        "ui-diff__row"
+      ]
+    },
     "ui-display": {
       "base": "ui-display",
       "modifiers": [],
@@ -487,6 +536,14 @@
         "ui-generated__label"
       ]
     },
+    "ui-glossary": {
+      "base": "ui-glossary",
+      "modifiers": [],
+      "parts": [
+        "ui-glossary__def",
+        "ui-glossary__term"
+      ]
+    },
     "ui-grid": {
       "base": "ui-grid",
       "modifiers": [],
@@ -602,6 +659,11 @@
       ],
       "parts": []
     },
+    "ui-marginnote": {
+      "base": "ui-marginnote",
+      "modifiers": [],
+      "parts": []
+    },
     "ui-mark": {
       "base": "ui-mark",
       "modifiers": [
@@ -654,7 +716,10 @@
         "ui-meter--warning"
       ],
       "parts": [
-        "ui-meter__fill"
+        "ui-meter__fill",
+        "ui-meter__label",
+        "ui-meter__row",
+        "ui-meter__value"
       ]
     },
     "ui-modal": {
@@ -886,6 +951,13 @@
       "modifiers": [],
       "parts": []
     },
+    "ui-sidenote": {
+      "base": "ui-sidenote",
+      "modifiers": [],
+      "parts": [
+        "ui-sidenote__ref"
+      ]
+    },
     "ui-sitefooter": {
       "base": "ui-sitefooter",
       "modifiers": [],
@@ -943,6 +1015,17 @@
         "ui-source-list__item"
       ]
     },
+    "ui-spark": {
+      "base": "ui-spark",
+      "modifiers": [
+        "ui-spark__bar--accent",
+        "ui-spark__bar--neg",
+        "ui-spark__bar--pos"
+      ],
+      "parts": [
+        "ui-spark__bar"
+      ]
+    },
     "ui-spinner": {
       "base": "ui-spinner",
       "modifiers": [],
@@ -1063,7 +1146,6 @@
         "ui-table--comfortable",
         "ui-table--dense",
         "ui-table--lined",
-        "ui-table--loading",
         "ui-table--selectable"
       ],
       "parts": [
@@ -1075,7 +1157,9 @@
     },
     "ui-table-wrap": {
       "base": "ui-table-wrap",
-      "modifiers": [],
+      "modifiers": [
+        "ui-table-wrap--loading"
+      ],
       "parts": []
     },
     "ui-tabs": {
@@ -1098,13 +1182,23 @@
       "modifiers": [],
       "parts": []
     },
+    "ui-term": {
+      "base": "ui-term",
+      "modifiers": [],
+      "parts": []
+    },
     "ui-textarea": {
       "base": "ui-textarea",
       "modifiers": [],
       "parts": []
     },
+    "ui-textref": {
+      "base": "ui-textref",
+      "modifiers": [],
+      "parts": []
+    },
     "ui-themetoggle": {
-      "base": "ui-themetoggle",
+      "base": null,
       "modifiers": [],
       "parts": [
         "ui-themetoggle__button",
@@ -1143,6 +1237,15 @@
       ],
       "parts": []
     },
+    "ui-toc": {
+      "base": "ui-toc",
+      "modifiers": [],
+      "parts": [
+        "ui-toc__link",
+        "ui-toc__list",
+        "ui-toc__title"
+      ]
+    },
     "ui-tool-call": {
       "base": "ui-tool-call",
       "modifiers": [],
@@ -1174,6 +1277,16 @@
         "ui-tour-note__title"
       ]
     },
+    "ui-tree": {
+      "base": "ui-tree",
+      "modifiers": [],
+      "parts": [
+        "ui-tree__branch",
+        "ui-tree__label",
+        "ui-tree__leaf",
+        "ui-tree__summary"
+      ]
+    },
     "ui-visually-hidden": {
       "base": "ui-visually-hidden",
       "modifiers": [],
@@ -1197,7 +1310,7 @@
     "ui-alert--success",
     "ui-alert--warning",
     "ui-alert__body",
-    "ui-alert__dismiss",
+    "ui-alert__close",
     "ui-alert__title",
     "ui-animate-dot",
     "ui-animate-fade",
@@ -1284,6 +1397,13 @@
     "ui-breadcrumb__item",
     "ui-break-after",
     "ui-break-before",
+    "ui-bullet",
+    "ui-bullet__label",
+    "ui-bullet__measure",
+    "ui-bullet__measure--accent",
+    "ui-bullet__measure--neg",
+    "ui-bullet__measure--pos",
+    "ui-bullet__target",
     "ui-button",
     "ui-button--danger",
     "ui-button--ghost",
@@ -1313,6 +1433,14 @@
     "ui-citation--chip",
     "ui-cluster",
     "ui-cluster--between",
+    "ui-code",
+    "ui-code--numbered",
+    "ui-code__body",
+    "ui-code__head",
+    "ui-code__line",
+    "ui-code__line--add",
+    "ui-code__line--hl",
+    "ui-code__line--remove",
     "ui-combobox",
     "ui-combobox__empty",
     "ui-combobox__input",
@@ -1351,11 +1479,23 @@
     "ui-crosshair__line",
     "ui-crosshair__line--x",
     "ui-crosshair__line--y",
+    "ui-def",
     "ui-delta",
     "ui-delta--down",
     "ui-delta--flat",
     "ui-delta--invert",
     "ui-delta--up",
+    "ui-diff",
+    "ui-diff--split",
+    "ui-diff__code",
+    "ui-diff__head",
+    "ui-diff__hunk",
+    "ui-diff__ln",
+    "ui-diff__pane",
+    "ui-diff__row",
+    "ui-diff__row--add",
+    "ui-diff__row--context",
+    "ui-diff__row--remove",
     "ui-display",
     "ui-divider",
     "ui-dot",
@@ -1393,6 +1533,9 @@
     "ui-file",
     "ui-generated",
     "ui-generated__label",
+    "ui-glossary",
+    "ui-glossary__def",
+    "ui-glossary__term",
     "ui-grid",
     "ui-hint",
     "ui-hint--error",
@@ -1443,6 +1586,7 @@
     "ui-link",
     "ui-link--arrow",
     "ui-link--cta",
+    "ui-marginnote",
     "ui-mark",
     "ui-mark--accent",
     "ui-mark--box",
@@ -1469,6 +1613,9 @@
     "ui-meter--success",
     "ui-meter--warning",
     "ui-meter__fill",
+    "ui-meter__label",
+    "ui-meter__row",
+    "ui-meter__value",
     "ui-modal",
     "ui-modal--drawer",
     "ui-modal__body",
@@ -1550,6 +1697,8 @@
     "ui-shortcut",
     "ui-shortcut__sep",
     "ui-sidebar",
+    "ui-sidenote",
+    "ui-sidenote__ref",
     "ui-sitefooter",
     "ui-sitefooter__links",
     "ui-siteheader",
@@ -1569,6 +1718,11 @@
     "ui-source-card__title",
     "ui-source-list",
     "ui-source-list__item",
+    "ui-spark",
+    "ui-spark__bar",
+    "ui-spark__bar--accent",
+    "ui-spark__bar--neg",
+    "ui-spark__bar--pos",
     "ui-spinner",
     "ui-spotlight",
     "ui-spotlight--ring",
@@ -1617,9 +1771,9 @@
     "ui-table--comfortable",
     "ui-table--dense",
     "ui-table--lined",
-    "ui-table--loading",
     "ui-table--selectable",
     "ui-table-wrap",
+    "ui-table-wrap--loading",
     "ui-table__empty",
     "ui-table__select",
     "ui-table__sort",
@@ -1630,7 +1784,9 @@
     "ui-tag",
     "ui-tag--accent",
     "ui-tags",
+    "ui-term",
     "ui-textarea",
+    "ui-textref",
     "ui-themetoggle__button",
     "ui-themetoggle__label",
     "ui-themetoggle__prefix",
@@ -1649,6 +1805,10 @@
     "ui-toast-stack--assertive",
     "ui-toast__close",
     "ui-toast__title",
+    "ui-toc",
+    "ui-toc__link",
+    "ui-toc__list",
+    "ui-toc__title",
     "ui-tool-call",
     "ui-tool-call__body",
     "ui-tool-call__name",
@@ -1661,6 +1821,11 @@
     "ui-tour-note__body",
     "ui-tour-note__step",
     "ui-tour-note__title",
+    "ui-tree",
+    "ui-tree__branch",
+    "ui-tree__label",
+    "ui-tree__leaf",
+    "ui-tree__summary",
     "ui-visually-hidden",
     "ui-vt"
   ],
@@ -1741,10 +1906,10 @@
     },
     {
       "name": "--value",
-      "on": ".ui-meter__fill, .ui-progress__bar",
+      "on": ".ui-meter, .ui-progress",
       "type": "number 0..100",
       "example": "92",
-      "note": "measured value as a percentage — set on the fill element, not its track parent"
+      "note": "measured value as a UNITLESS number 0..100 (registered <number>, never a %). Set it on the meter/progress host — it inherits to the __fill/__bar. Prefer attrs.meter(value)/attrs.progress(value) from @ponchia/ui/classes, which sets it plus role + aria-valuenow/min/max together."
     },
     {
       "name": "--icon-mask",
@@ -1776,6 +1941,64 @@
       "required": true,
       "note": "REQUIRED — the view-transition-name; .ui-vt is inert (no transition) without it"
     },
+    {
+      "name": "--v",
+      "on": ".ui-spark__bar",
+      "type": "number 0..1",
+      "example": "0.7",
+      "required": true,
+      "note": "REQUIRED — the normalised bar height (0..1). The host normalises; Bronto only paints. A bar with no --v collapses to the 1px floor. Pair every spark with a host-written role=\"img\" + aria-label."
+    },
+    {
+      "name": "--sidenote-width",
+      "on": ".ui-sidenote, .ui-marginnote",
+      "type": "length",
+      "example": "12rem",
+      "note": "width of the floated margin note on wide viewports (default 12rem). The container must reserve a matching inline-end gutter — see docs/sidenote.md."
+    },
+    {
+      "name": "--textref-highlight",
+      "on": ".ui-textref",
+      "type": "color",
+      "example": "var(--accent-soft)",
+      "note": "the ::target-text highlight wash for the matched cited sentence (default var(--accent-soft)). The host builds the #:~:text= href; Bronto owns the paint — see docs/textref.md."
+    },
+    {
+      "name": "--v",
+      "on": ".ui-bullet__measure",
+      "type": "number 0..1",
+      "example": "0.62",
+      "required": true,
+      "note": "REQUIRED — the normalised measure (0..1). The host normalises; Bronto only paints. A measure with no --v collapses to the 2px floor. Pair every bullet with a host-written role=\"img\" + aria-label."
+    },
+    {
+      "name": "--t",
+      "on": ".ui-bullet__target",
+      "type": "number 0..1",
+      "example": "0.9",
+      "note": "the normalised target tick position (0..1). Omit to drop the target mark."
+    },
+    {
+      "name": "--band-lo",
+      "on": ".ui-bullet",
+      "type": "number 0..1",
+      "example": "0.5",
+      "note": "the lower qualitative-band boundary (0..1, default 0.5). Bands are grayscale by Few-design — meaning lives in the required aria-label."
+    },
+    {
+      "name": "--band-hi",
+      "on": ".ui-bullet",
+      "type": "number 0..1",
+      "example": "0.8",
+      "note": "the upper qualitative-band boundary (0..1, default 0.8). Must be ≥ --band-lo."
+    },
+    {
+      "name": "--toc-top",
+      "on": ".ui-toc",
+      "type": "length",
+      "example": "1rem",
+      "note": "the sticky inset from the top of the scroll container (default var(--space-md))."
+    },
     {
       "name": "--stack-gap",
       "on": ".ui-stack",
@@ -1818,6 +2041,20 @@
       "example": "50%",
       "note": "min width of the main child before the two stack (default 60%)"
     },
+    {
+      "name": "--sidebar-gap",
+      "on": ".ui-sidebar",
+      "type": "length",
+      "example": "1.5rem",
+      "note": "gap between the sidebar and the main child (default var(--space-md))"
+    },
+    {
+      "name": "--switcher-gap",
+      "on": ".ui-switcher",
+      "type": "length",
+      "example": "1.5rem",
+      "note": "gap between switcher children in both row and column states (default var(--space-md))"
+    },
     {
       "name": "--switcher-min",
       "on": ".ui-switcher",
@@ -1844,7 +2081,7 @@
       "on": ".ui-ratio",
       "type": "ratio",
       "example": "4 / 3",
-      "note": "intrinsic aspect ratio of the box (default 16 / 9)"
+      "note": "intrinsic aspect ratio of the box (default 16 / 9). Give .ui-ratio EXACTLY ONE child — only :first-child is sized to fill; a second child silently breaks the ratio. For a caption/overlay, position it absolutely inside the single child"
     },
     {
       "name": "--app-rail",
@@ -1852,6 +2089,439 @@
       "type": "length",
       "example": "16rem",
       "note": "width of the app-shell sidebar rail column (default 14rem)"
+    },
+    {
+      "name": "--container",
+      "on": ".ui-container",
+      "type": "length",
+      "example": "72rem",
+      "note": "max inline width of the default page frame, border-box (default 72rem)"
+    },
+    {
+      "name": "--container-narrow",
+      "on": ".ui-container--narrow",
+      "type": "length",
+      "example": "44rem",
+      "note": "max inline width of the narrow page frame (default 44rem)"
+    },
+    {
+      "name": "--container-wide",
+      "on": ".ui-container--wide",
+      "type": "length",
+      "example": "82rem",
+      "note": "max inline width of the wide page frame (default 82rem)"
+    },
+    {
+      "name": "--av-size",
+      "on": ".ui-avatar",
+      "type": "length",
+      "example": "2.6rem",
+      "note": "avatar box size; the initials font-size derives from it (default 2.2rem; --sm 1.5rem, --lg 3.2rem)"
+    },
+    {
+      "name": "--dotmatrix-cols",
+      "on": ".ui-dotmatrix",
+      "type": "number",
+      "example": "8",
+      "note": "columns in the dot grid — the density knob (default 12)"
+    },
+    {
+      "name": "--dotmatrix-gap",
+      "on": ".ui-dotmatrix",
+      "type": "length",
+      "example": "0.3rem",
+      "note": "gap between dots (default 0.5rem; set 0 with --dotmatrix-dot-radius:0 to fuse the dots)"
+    },
+    {
+      "name": "--dotmatrix-dot",
+      "on": ".ui-dotmatrix",
+      "type": "length",
+      "example": "0.5rem",
+      "note": "fixed dot length for intrinsic sizing (default minmax(0, 1fr) — fluid to the container)"
+    },
+    {
+      "name": "--dotmatrix-dot-radius",
+      "on": ".ui-dotmatrix",
+      "type": "length",
+      "example": "0",
+      "note": "dot corner radius (default 50% = round; 0 = square pixels)"
+    },
+    {
+      "name": "--dotmatrix-glow",
+      "on": ".ui-dotmatrix",
+      "type": "length",
+      "example": "2px",
+      "note": "phosphor bloom radius around lit cells (default 0 = off)"
+    },
+    {
+      "name": "--dotmatrix-pulse-min",
+      "on": ".ui-dotmatrix",
+      "type": "number",
+      "example": "0.4",
+      "note": "opacity floor the --pulse animation dips to (default 0.55)"
+    },
+    {
+      "name": "--dotmatrix-reveal-step",
+      "on": ".ui-dotmatrix",
+      "type": "time",
+      "example": "5ms",
+      "note": "per-cell scan cadence for the reveal animation (default 3ms)"
+    },
+    {
+      "name": "--ds-box",
+      "on": ".ui-dotspinner",
+      "type": "length",
+      "example": "2.6rem",
+      "note": "dot-spinner box size (default 1.6rem; the --lg modifier sets 2.6rem)"
+    },
+    {
+      "name": "--ds-dot",
+      "on": ".ui-dotspinner",
+      "type": "length",
+      "example": "0.42rem",
+      "note": "dot-spinner dot size (default 0.26rem)"
+    },
+    {
+      "name": "--crosshair-color",
+      "on": ".ui-crosshair",
+      "type": "color",
+      "example": "var(--accent)",
+      "note": "crosshair rule + badge colour (default var(--accent); the --muted modifier uses --line-strong)"
+    },
+    {
+      "name": "--connector-color",
+      "on": ".ui-connector",
+      "type": "color",
+      "example": "var(--accent)",
+      "note": "leader-line stroke + label colour (default var(--line-strong); the --muted/--accent modifiers reset it)"
+    },
+    {
+      "name": "--connector-width",
+      "on": ".ui-connector",
+      "type": "number",
+      "example": "2",
+      "note": "leader-line stroke width (default 1.5)"
+    },
+    {
+      "name": "--mark-color",
+      "on": ".ui-mark",
+      "type": "color",
+      "example": "var(--accent)",
+      "note": "hand-drawn mark colour; a tone modifier sets it (no base default — each draw style falls back to --line-strong)"
+    },
+    {
+      "name": "--spot-pad",
+      "on": ".ui-spotlight",
+      "type": "length",
+      "example": "12px",
+      "note": "padding between the spotlit target and the cutout edge (default 8px)"
+    },
+    {
+      "name": "--spot-radius",
+      "on": ".ui-spotlight",
+      "type": "length",
+      "example": "12px",
+      "note": "spotlight cutout corner radius (default var(--radius-md))"
+    },
+    {
+      "name": "--spot-backdrop",
+      "on": ".ui-spotlight",
+      "type": "color",
+      "example": "color-mix(in srgb, #000 70%, transparent)",
+      "note": "the dimming backdrop colour outside the cutout (default 55% black)"
+    }
+  ],
+  "rootAttributes": [
+    {
+      "name": "data-theme",
+      "on": ":root",
+      "values": [
+        "light",
+        "dark"
+      ],
+      "note": "colour theme. Unset follows the OS via prefers-color-scheme; set it to force one."
+    },
+    {
+      "name": "data-density",
+      "on": ":root or any subtree",
+      "values": [
+        "compact",
+        "comfortable"
+      ],
+      "note": "spacing-scale preset (the middle scale is the default when unset). Scoped per-subtree, unlike the others."
+    },
+    {
+      "name": "data-surface",
+      "on": ":root",
+      "values": [
+        "oled"
+      ],
+      "note": "opt into a true-black surface ramp for OLED. Unset = the standard elevated dark base."
+    },
+    {
+      "name": "data-contrast",
+      "on": ":root",
+      "values": [
+        "high"
+      ],
+      "note": "raise contrast of lines/text for low-vision or glare. Unset = the standard ramp."
+    },
+    {
+      "name": "data-bronto-skin",
+      "on": ":root",
+      "values": [
+        "amber-crt",
+        "phosphor-green",
+        "e-ink"
+      ],
+      "note": "opt-in display colorway — requires @ponchia/ui/css/skins.css. Unset (the design target) = the default Nothing aesthetic."
+    },
+    {
+      "name": "--accent",
+      "on": ":root or a theme root",
+      "values": [
+        "<color>"
+      ],
+      "note": "the single brand knob; the accent family derives from it. Re-brand at :root/[data-theme] (a subtree override is only a partial re-brand). See docs/theming.md."
+    }
+  ],
+  "behaviorAttributes": [
+    {
+      "name": "data-bronto-open",
+      "on": "a trigger (button/link)",
+      "value": "id of the target <dialog>",
+      "behavior": "initDialog",
+      "note": "click calls showModal() on the named <dialog>; focus returns to the trigger on every close path"
+    },
+    {
+      "name": "data-bronto-close",
+      "on": "a button inside a <dialog>",
+      "behavior": "initDialog",
+      "note": "click closes the nearest enclosing <dialog>"
+    },
+    {
+      "name": "data-bronto-dialog-light",
+      "on": "a <dialog>",
+      "behavior": "initDialog",
+      "note": "opt into backdrop light-dismiss (click the backdrop to close)"
+    },
+    {
+      "name": "data-bronto-modal",
+      "on": "a controlled (non-<dialog>) .ui-modal overlay",
+      "behavior": "initModal",
+      "note": "inert focus-trap + .is-open toggling for a modal that is not a native <dialog>; needs an accessible name"
+    },
+    {
+      "name": "data-bronto-menu",
+      "on": "a native <details> dropdown",
+      "behavior": "initMenu",
+      "note": "adds outside-click / Escape close affordances to a <details>-based .ui-menu"
+    },
+    {
+      "name": "data-bronto-popover",
+      "on": "a trigger",
+      "value": "id of the .ui-popover panel",
+      "behavior": "initPopover",
+      "note": "collision-aware NON-modal popover (no focus trap); top-layer via the native popover attr when present, else an .is-open class. Author an accessible name on the panel."
+    },
+    {
+      "name": "data-bronto-command",
+      "on": "a .ui-command palette host wrapping its input",
+      "behavior": "initCommand",
+      "note": "wires the filter input + active-option keyboard model"
+    },
+    {
+      "name": "data-bronto-dismiss",
+      "on": "a button",
+      "value": "optional CSS selector of the ancestor to remove",
+      "behavior": "dismissible",
+      "note": "click removes the nearest matching ancestor (or, with no value, the nearest [data-bronto-dismissible])"
+    },
+    {
+      "name": "data-bronto-disclosure",
+      "on": "a trigger",
+      "value": "id of the element it toggles",
+      "behavior": "initDisclosure",
+      "note": "toggles the named element + keeps aria-expanded in sync"
+    },
+    {
+      "name": "data-bronto-tabs",
+      "on": "a .ui-tabs group host",
+      "behavior": "initTabs",
+      "note": "adds the WAI-ARIA Tabs keyboard model (roving tabindex, Arrow/Home/End, aria-selected, panel hidden sync) over .ui-tab[data-tab] / .ui-tabs__panel[data-panel]. Without it the CSS tabs are mouse-only with no roving focus."
+    },
+    {
+      "name": "data-bronto-theme-toggle",
+      "on": "a .ui-themetoggle__button (or any control)",
+      "value": "optional 'light' | 'dark' to force a specific theme instead of toggling",
+      "behavior": "initThemeToggle",
+      "note": "click toggles or sets data-theme on <html> and persists it; without it the button is inert. Pair with applyStoredTheme() before paint to avoid a flash."
+    },
+    {
+      "name": "data-bronto-validate",
+      "on": "a <form>",
+      "behavior": "initFormValidation",
+      "note": "progressive-enhancement validation: suppresses native bubbles, writes validationMessage into the field error slot, builds the error summary. With JS off the form still validates natively."
+    },
+    {
+      "name": "data-bronto-error",
+      "on": "an empty error slot inside a .ui-field (canonical: <p class=\"ui-hint\" data-bronto-error>)",
+      "behavior": "initFormValidation",
+      "note": "the dedicated per-field error node initFormValidation fills + links via aria-describedby (and unlinks when the field is valid). Preferred over borrowing the .ui-hint help slot."
+    },
+    {
+      "name": "data-bronto-error-summary",
+      "on": "a .ui-error-summary inside the form",
+      "behavior": "initFormValidation",
+      "note": "on an invalid submit, filled with role=alert + tabindex=-1 in-page links to each bad field and focused."
+    },
+    {
+      "name": "data-bronto-combobox",
+      "on": "a .ui-combobox host (wrapping the input + listbox)",
+      "behavior": "initCombobox",
+      "note": "editable combobox with a filtered listbox (APG pattern). The input needs a real accessible name (a placeholder does not count — it warns)."
+    },
+    {
+      "name": "data-bronto-combobox-live",
+      "on": "the [data-bronto-combobox] host",
+      "behavior": "initCombobox",
+      "note": "opt-in: a MutationObserver re-reads option nodes in place for async/replaced results, instead of a full re-init. Off by default."
+    },
+    {
+      "name": "data-bronto-sortable",
+      "on": "a .ui-table <table>",
+      "behavior": "initTableSort",
+      "note": "click a header .ui-table__sort button to sort; numeric columns via data-sort=\"num\" or .is-num cells. Use data-sort-value on a cell for a canonical sort key (accepts a European decimal comma)."
+    },
+    {
+      "name": "data-bronto-select",
+      "on": "a row checkbox inside a [data-bronto-sortable] table",
+      "behavior": "initTableSort",
+      "note": "toggling it sets the row aria-selected and syncs the header select-all state; emits bronto:selectionchange."
+    },
+    {
+      "name": "data-bronto-select-all",
+      "on": "the header checkbox of a [data-bronto-sortable] table",
+      "behavior": "initTableSort",
+      "note": "toggles every [data-bronto-select] row box; goes indeterminate on a partial selection."
+    },
+    {
+      "name": "data-bronto-dismissible",
+      "on": "the ancestor a [data-bronto-dismiss] button removes",
+      "behavior": "dismissible",
+      "note": "marks the default removal target when the dismiss button has no selector value. A cancelable bronto:dismiss fires first."
+    },
+    {
+      "name": "data-bronto-legend",
+      "on": "a .ui-legend host",
+      "behavior": "initLegend",
+      "note": "each .ui-legend__item is a <button aria-pressed>; clicking flips aria-pressed + .is-inactive and dispatches bronto:legend:toggle { series, active }. The host runs the actual series show/hide."
+    },
+    {
+      "name": "data-bronto-crosshair",
+      "on": "a plot containing a .ui-crosshair overlay",
+      "behavior": "initCrosshair",
+      "note": "tracks the pointer, sets --crosshair-x/y on the overlay, and emits bronto:crosshair:move { x, y, fx, fy }. Reports WHERE the pointer is — it does not map pixels to data."
+    },
+    {
+      "name": "data-bronto-connector",
+      "on": "a .ui-connector SVG overlay",
+      "value": "via child data-from / data-to (element ids), optional data-shape / data-*-side",
+      "behavior": "initConnectors",
+      "note": "draws + keeps leader lines in sync between the referenced elements; re-routes on resize/scroll."
+    },
+    {
+      "name": "data-bronto-spotlight",
+      "on": "a .ui-spotlight overlay",
+      "value": "via data-target (id of the element to highlight)",
+      "behavior": "initSpotlight",
+      "note": "measures the target and sets --spot-x/y/w/h on the overlay, re-placing on resize/scroll. Positioning only — not a tour engine."
+    },
+    {
+      "name": "data-bronto-carousel",
+      "on": "a carousel host containing a .ui-carousel__viewport",
+      "behavior": "initCarousel",
+      "note": "scroll-snap carousel with prev/next + a status counter; the lightbox dialog uses it too."
+    },
+    {
+      "name": "data-bronto-carousel-prev",
+      "on": "a control inside [data-bronto-carousel]",
+      "behavior": "initCarousel",
+      "note": "the previous-slide button."
+    },
+    {
+      "name": "data-bronto-carousel-next",
+      "on": "a control inside [data-bronto-carousel]",
+      "behavior": "initCarousel",
+      "note": "the next-slide button."
+    },
+    {
+      "name": "data-bronto-carousel-loop",
+      "on": "the [data-bronto-carousel] host",
+      "behavior": "initCarousel",
+      "note": "wrap from the last slide back to the first (and vice-versa)."
+    },
+    {
+      "name": "data-bronto-carousel-label",
+      "on": "the [data-bronto-carousel] host",
+      "value": "accessible name for the carousel region",
+      "behavior": "initCarousel",
+      "note": "names the scroll region (defaults to \"Carousel\")."
+    },
+    {
+      "name": "data-bronto-carousel-current",
+      "on": "a .ui-carousel__slide",
+      "behavior": "initCarousel",
+      "note": "marks the slide to start on (defaults to the first)."
+    },
+    {
+      "name": "data-bronto-glyph",
+      "on": "a placeholder element",
+      "value": "glyph name (see GLYPH_NAMES)",
+      "behavior": "initDotGlyph",
+      "note": "expands into a .ui-dotmatrix dot grid; an unknown name is left untouched + warns."
+    },
+    {
+      "name": "data-bronto-glyph-label",
+      "on": "a [data-bronto-glyph] placeholder",
+      "value": "accessible label",
+      "behavior": "initDotGlyph",
+      "note": "exposes the glyph as role=\"img\" with this name; omit for a decorative (aria-hidden) glyph."
+    },
+    {
+      "name": "data-bronto-glyph-solid",
+      "on": "a [data-bronto-glyph] placeholder",
+      "behavior": "initDotGlyph",
+      "note": "render a square, gapless pixel glyph (more legible at small sizes) instead of the dot look."
+    },
+    {
+      "name": "data-bronto-glyph-anim",
+      "on": "a [data-bronto-glyph] placeholder",
+      "value": "'reveal' | 'pulse'",
+      "behavior": "initDotGlyph",
+      "note": "decorative entrance/idle animation (honours prefers-reduced-motion)."
+    }
+  ],
+  "requiredAria": [
+    {
+      "on": ".ui-progress",
+      "require": "role=\"progressbar\" + aria-valuenow/min/max (determinate); role=\"progressbar\" + aria-busy=\"true\" and NO aria-valuenow (indeterminate)",
+      "helper": "attrs.progress(value) / attrs.progress()"
+    },
+    {
+      "on": ".ui-meter",
+      "require": "role=\"meter\" + aria-valuenow/min/max. Caveat: role=\"meter\" has uneven AT support (notably older Safari/VoiceOver), so do NOT rely on it alone — the visible .ui-meter__label + .ui-meter__value carry the meaning and are the real channel (REQUIRED for a labelled meter)",
+      "helper": "attrs.meter(value)"
+    },
+    {
+      "on": ".ui-dotbar",
+      "require": "role=\"progressbar\" + aria-valuenow/min/max (determinate); role=\"progressbar\" + aria-busy=\"true\" and NO aria-valuenow (indeterminate). The <i> segments are decorative — mark the host or segments aria-hidden so AT reads the value, not eight empty spans",
+      "helper": "attrs.dotbar(value) / attrs.dotbar()"
+    },
+    {
+      "on": ".ui-error-summary",
+      "require": "role=\"alert\" + tabindex=\"-1\" on the hand-authored summary so it is announced and focusable when validation fails",
+      "helper": "initFormValidation wires this for the dynamic summary; a static summary needs it hand-set"
     }
   ]
 }