bestax-mcp 1.16.2 → 1.16.4

package/data/bulma-classes.json

@@ -3615,25 +3615,69 @@
         "is-64x64": { "writes": [{ "prop": "size", "value": "64x64" }] },
         "is-96x96": { "writes": [{ "prop": "size", "value": "96x96" }] },
         "is-128x128": { "writes": [{ "prop": "size", "value": "128x128" }] },
-        "is-square": { "writes": [{ "prop": "size", "value": "square" }] }
-      },
-      "omits": {
-        "is-1by1": "`size` renders `has-ratio` beside it as well",
-        "is-5by4": "`size` renders `has-ratio` beside it as well",
-        "is-4by3": "`size` renders `has-ratio` beside it as well",
-        "is-3by2": "`size` renders `has-ratio` beside it as well",
-        "is-5by3": "`size` renders `has-ratio` beside it as well",
-        "is-16by9": "`size` renders `has-ratio` beside it as well",
-        "is-2by1": "`size` renders `has-ratio` beside it as well",
-        "is-3by1": "`size` renders `has-ratio` beside it as well",
-        "is-4by5": "`size` renders `has-ratio` beside it as well",
-        "is-3by4": "`size` renders `has-ratio` beside it as well",
-        "is-2by3": "`size` renders `has-ratio` beside it as well",
-        "is-3by5": "`size` renders `has-ratio` beside it as well",
-        "is-9by16": "`size` renders `has-ratio` beside it as well",
-        "is-1by2": "`size` renders `has-ratio` beside it as well",
-        "is-1by3": "`size` renders `has-ratio` beside it as well"
+        "is-square": { "writes": [{ "prop": "size", "value": "square" }] },
+        "is-1by1": {
+          "writes": [{ "prop": "size", "value": "1by1" }],
+          "rendersTag": "figure"
+        },
+        "is-5by4": {
+          "writes": [{ "prop": "size", "value": "5by4" }],
+          "rendersTag": "figure"
+        },
+        "is-4by3": {
+          "writes": [{ "prop": "size", "value": "4by3" }],
+          "rendersTag": "figure"
+        },
+        "is-3by2": {
+          "writes": [{ "prop": "size", "value": "3by2" }],
+          "rendersTag": "figure"
+        },
+        "is-5by3": {
+          "writes": [{ "prop": "size", "value": "5by3" }],
+          "rendersTag": "figure"
+        },
+        "is-16by9": {
+          "writes": [{ "prop": "size", "value": "16by9" }],
+          "rendersTag": "figure"
+        },
+        "is-2by1": {
+          "writes": [{ "prop": "size", "value": "2by1" }],
+          "rendersTag": "figure"
+        },
+        "is-3by1": {
+          "writes": [{ "prop": "size", "value": "3by1" }],
+          "rendersTag": "figure"
+        },
+        "is-4by5": {
+          "writes": [{ "prop": "size", "value": "4by5" }],
+          "rendersTag": "figure"
+        },
+        "is-3by4": {
+          "writes": [{ "prop": "size", "value": "3by4" }],
+          "rendersTag": "figure"
+        },
+        "is-2by3": {
+          "writes": [{ "prop": "size", "value": "2by3" }],
+          "rendersTag": "figure"
+        },
+        "is-3by5": {
+          "writes": [{ "prop": "size", "value": "3by5" }],
+          "rendersTag": "figure"
+        },
+        "is-9by16": {
+          "writes": [{ "prop": "size", "value": "9by16" }],
+          "rendersTag": "figure"
+        },
+        "is-1by2": {
+          "writes": [{ "prop": "size", "value": "1by2" }],
+          "rendersTag": "figure"
+        },
+        "is-1by3": {
+          "writes": [{ "prop": "size", "value": "1by3" }],
+          "rendersTag": "figure"
+        }
       },
+      "omits": {},
       "wrapsChildren": null,
       "folds": null,
       "absorbs": {

package/data/catalog.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "generatedFrom": {
     "package": "@allxsmith/bestax-bulma",
-    "version": "5.39.1"
+    "version": "5.41.0"
   },
   "docsBase": "https://bestax.io/docs",
   "categories": [
@@ -738,8 +738,8 @@
       "slug": "components/menu",
       "import": "import { Menu } from '@allxsmith/bestax-bulma';",
       "compound": true,
-      "propCount": 16,
-      "exampleCount": 6
+      "propCount": 22,
+      "exampleCount": 8
     },
     {
       "name": "Message",
@@ -1200,8 +1200,8 @@
       "slug": "components/treeview",
       "import": "import { TreeView } from '@allxsmith/bestax-bulma';",
       "compound": true,
-      "propCount": 20,
-      "exampleCount": 8
+      "propCount": 27,
+      "exampleCount": 9
     },
     {
       "name": "UnorderedList",
@@ -2080,6 +2080,10 @@
     "--bulma-menu-list-link-padding": ["Menu"],
     "--bulma-menu-nested-list-margin": ["Menu"],
     "--bulma-menu-nested-list-padding-left": ["Menu"],
+    "--bulma-menu-section-chevron-color": ["Menu"],
+    "--bulma-menu-section-chevron-duration": ["Menu"],
+    "--bulma-menu-section-chevron-size": ["Menu"],
+    "--bulma-menu-section-gap": ["Menu"],
     "--bulma-message-background-l": ["Message"],
     "--bulma-message-body-border-width": ["Message"],
     "--bulma-message-body-color": ["Message"],
@@ -2801,6 +2805,11 @@
       "path": "Menu.List",
       "purpose": "MenuList applies `menu-list` class only at the top level (not for nested lists)."
     },
+    "MenuSection": {
+      "component": "Menu",
+      "path": "Menu.Section",
+      "purpose": "A section of the menu that opens and closes: its heading is a button drawn like `Menu.Label`, and its `Menu.List` of links shows while it's open."
+    },
     "NavbarBrand": {
       "component": "Navbar",
       "path": "Navbar.Brand",

package/data/components/Image.json

@@ -97,7 +97,7 @@
           "name": "size",
           "type": "'16x16' | '24x24' | '32x32' | '48x48' | '64x64' | '96x96' | '128x128' | 'square' | '1by1' | '5by4' | '4by3' | '3by2' | '5by3' | '16by9' | '2by1' | '3by1' | '4by5' | '3by4' | '2by3' | '3by5' | '9by16' | '1by2' | '1by3'",
           "default": null,
-          "description": "Fixed size or aspect ratio modifier for the image container.",
+          "description": "Fixed size or aspect ratio modifier for the image container. A ratio (`16by9` and the rest) renders only its `is-<ratio>` class there. Bulma stretches an `<img>` inside to fill the ratio, but any other child, such as an `iframe`, fills it only with `className=\"has-ratio\"` of its own.",
           "required": false,
           "inherited": false,
           "deprecated": false

package/data/components/Menu.json

@@ -21,17 +21,25 @@
       "title": "Deeply Nested Menu",
       "code": "<Menu>\n  <Menu.Label>Levels</Menu.Label>\n  <Menu.List>\n    <Menu.Item href=\"#level-1\">\n      Level 1\n      <Menu.List>\n        <Menu.Item href=\"#level-2\">\n          Level 2\n          <Menu.List>\n            <Menu.Item href=\"#level-3\">Level 3</Menu.Item>\n          </Menu.List>\n        </Menu.Item>\n      </Menu.List>\n    </Menu.Item>\n  </Menu.List>\n</Menu>"
     },
+    {
+      "title": "Sections that open and close",
+      "code": "<nav aria-label=\"Documentation\">\n  <Menu>\n    <Menu.Section label=\"Getting started\">\n      <Menu.List>\n        <Menu.Item href=\"#installation\">Installation</Menu.Item>\n        <Menu.Item href=\"#quick-start\">Quick start</Menu.Item>\n      </Menu.List>\n    </Menu.Section>\n    <Menu.Section label=\"Components\" defaultOpen>\n      <Menu.List>\n        <Menu.Item href=\"#button\">Button</Menu.Item>\n        <Menu.Item href=\"#card\" active>\n          Card\n        </Menu.Item>\n        <Menu.Item href=\"#modal\">Modal</Menu.Item>\n      </Menu.List>\n    </Menu.Section>\n    <Menu.Section label=\"Form\">\n      <Menu.List>\n        <Menu.Item href=\"#input\">Input</Menu.Item>\n        <Menu.Item href=\"#select\">Select</Menu.Item>\n      </Menu.List>\n    </Menu.Section>\n  </Menu>\n</nav>"
+    },
+    {
+      "title": "Controlled sections",
+      "code": "function example() {\n  const groups = {\n    Components: ['Button', 'Card', 'Modal'],\n    Form: ['Input', 'Select'],\n  };\n  const [open, setOpen] = React.useState(['Components']);\n\n  return (\n    <>\n      <Buttons mb=\"3\">\n        <Button size=\"small\" onClick={() => setOpen(Object.keys(groups))}>\n          Open all\n        </Button>\n        <Button size=\"small\" onClick={() => setOpen([])}>\n          Close all\n        </Button>\n      </Buttons>\n      <Menu>\n        {Object.entries(groups).map(([label, links]) => (\n          <Menu.Section\n            key={label}\n            label={label}\n            open={open.includes(label)}\n            onOpenChange={isOpen =>\n              setOpen(current =>\n                isOpen ? [...current, label] : current.filter(l => l !== label)\n              )\n            }\n          >\n            <Menu.List>\n              {links.map(link => (\n                <Menu.Item key={link} href={`#${link.toLowerCase()}`}>\n                  {link}\n                </Menu.Item>\n              ))}\n            </Menu.List>\n          </Menu.Section>\n        ))}\n      </Menu>\n    </>\n  );\n}"
+    },
     {
       "title": "Forwarded ref",
       "code": "function example() {\n  const itemRef = React.useRef<HTMLAnchorElement>(null);\n\n  return (\n    <>\n      <Button mb=\"3\" onClick={() => itemRef.current?.focus()}>\n        Focus Customers\n      </Button>\n      <Menu>\n        <Menu.Label>General</Menu.Label>\n        <Menu.List>\n          <Menu.Item href=\"#dashboard\">Dashboard</Menu.Item>\n          <Menu.Item href=\"#customers\" ref={itemRef}>\n            Customers\n          </Menu.Item>\n        </Menu.List>\n      </Menu>\n    </>\n  );\n}"
     },
     {
       "title": "Compound (dot-notation) usage",
-      "code": "<Menu>\n  <Menu.Label>General</Menu.Label>\n  <Menu.List>\n    <Menu.Item active href=\"#dashboard\">\n      Dashboard\n    </Menu.Item>\n    <Menu.Item href=\"#customers\">Customers</Menu.Item>\n  </Menu.List>\n</Menu>"
+      "code": "<Menu>\n  <Menu.Label>General</Menu.Label>\n  <Menu.List>\n    <Menu.Item active href=\"#dashboard\">\n      Dashboard\n    </Menu.Item>\n    <Menu.Item href=\"#customers\">Customers</Menu.Item>\n  </Menu.List>\n  <Menu.Section label=\"Transactions\">\n    <Menu.List>\n      <Menu.Item href=\"#payments\">Payments</Menu.Item>\n      <Menu.Item href=\"#transfers\">Transfers</Menu.Item>\n    </Menu.List>\n  </Menu.Section>\n</Menu>"
     }
   ],
-  "accessibility": "- The root `Menu` renders as `<aside class=\"menu\">`. A menu that's navigation is better inside a\n  `<nav>` with an `aria-label`, which gives assistive tech a navigation landmark to jump to.\n- Every `Menu.List` has `role=\"list\"`, nested ones included. That's the role a `<ul>` already has,\n  set again for Safari, whose WebKit stops exposing a `<ul>` as a list once its markers are hidden,\n  as Bulma's reset hides them, unless the role is written out.\n- `Menu.Item active` sets `aria-current=\"page\"` on the element `as` renders, the link by\n  default, so the current item isn't only a color. An `aria-current` you pass wins: a menu of\n  sections on one page can say `\"location\"`, and `aria-current={false}` turns it off.\n- Use semantic nesting (`Menu.List` inside `Menu.Item`) for submenus.\n- Give each item an `href`, a router link through `as`, or `as=\"button\"`, so the keyboard can\n  reach it.\n- `Menu.Item as=\"button\"` defaults to `type=\"button\"`, so a menu item inside a form doesn't\n  submit it. Pass `type=\"submit\"` or `type=\"reset\"` and yours is used instead; any other value\n  renders `type=\"button\"`.\n- In forced colors (Windows' contrast themes), the browser replaces Bulma's fill and text color\n  for the active item along with every other color, so bestax's stylesheet marks an\n  `is-active` or `is-selected` item with a bar in the system's highlight color along its start\n  edge there instead. The item's text, and an icon or a tag inside it, keep the colors your\n  contrast theme gives them. That rule ships in `bestax.css` and `extras.css`, not in Bulma's\n  own stylesheet.\n\n:::note\nFor router integrations, pass the correct `as` and `to`/`href` props to `Menu.Item`.\n:::",
-  "related": ["Panel", "Sidebar", "TreeView", "useBulmaClasses"],
+  "accessibility": "- The root `Menu` renders as `<aside class=\"menu\">`. A menu that's navigation is better inside a\n  `<nav>` with an `aria-label`, which gives assistive tech a navigation landmark to jump to.\n- Every `Menu.List` has `role=\"list\"`, nested ones included. That's the role a `<ul>` already has,\n  set again for Safari, whose WebKit stops exposing a `<ul>` as a list once its markers are hidden,\n  as Bulma's reset hides them, unless the role is written out.\n- `Menu.Item active` sets `aria-current=\"page\"` on the element `as` renders, the link by\n  default, so the current item isn't only a color. An `aria-current` you pass wins: a menu of\n  sections on one page can say `\"location\"`, and `aria-current={false}` turns it off.\n- Use semantic nesting (`Menu.List` inside `Menu.Item`) for submenus.\n- Give each item an `href`, a router link through `as`, or `as=\"button\"`, so the keyboard can\n  reach it.\n- `Menu.Item as=\"button\"` defaults to `type=\"button\"`, so a menu item inside a form doesn't\n  submit it. Pass `type=\"submit\"` or `type=\"reset\"` and yours is used instead; any other value\n  renders `type=\"button\"`.\n- In forced colors (Windows' contrast themes), the browser replaces Bulma's fill and text color\n  for the active item along with every other color, so bestax's stylesheet marks an\n  `is-active` or `is-selected` item with a bar in the system's highlight color along its start\n  edge there instead. The item's text, and an icon or a tag inside it, keep the colors your\n  contrast theme gives them. That rule ships in `bestax.css` and `extras.css`, not in Bulma's\n  own stylesheet.\n\nFor `Menu.Section`, a section that opens and closes:\n\n- It follows APG's\n  [Disclosure Navigation Menu example](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/).\n  The heading is a `<button type=\"button\">` with `aria-expanded`, and `aria-controls` naming the\n  wrapper around its list. Enter and Space open and close it, as they do any button, and it\n  doesn't submit a form it sits in.\n- The links under it are ordinary links. Each is its own tab stop, and there's no roving focus or\n  arrow-key handling, which is a tree's model rather than navigation's. They keep their `href`,\n  so a link still opens in a new tab, and `active` still sets `aria-current=\"page\"`.\n- A closed section's list is `hidden` and `inert`, so it isn't drawn, Tab skips its links, and\n  assistive tech and find-in-page don't reach them. `inert` keeps the links out of reach even if a\n  stylesheet sets `display` on the list and shows it. The list stays in the page, so\n  `aria-controls` always names an element that exists, and a section that starts closed is\n  already closed in the server's HTML, before any script runs.\n- Open the section that holds the current page, with `defaultOpen` or `open`, so the link marked\n  `aria-current` can be seen and reached.\n- When the app closes a section while focus is on one of its links, as a sidebar that keeps only\n  the current route's section open does after a link is followed, focus moves to that section's\n  heading. Without that, the browser drops focus to the page, and the next Tab starts from the\n  top.\n- `label` is the button's content and its accessible name. Keep links and other buttons out of\n  it.\n- In forced colors the chevron stays visible, since it's drawn as a border, and the focus ring\n  takes the system's text color. In a right-to-left page the chevron sits at the left end of the\n  heading and points left while closed. It turns with a short transition, which stops when the\n  reader asks for reduced motion.\n\n:::note\nFor router integrations, pass the correct `as` and `to`/`href` props to `Menu.Item`.\n:::",
+  "related": ["Collapse", "Panel", "Sidebar", "TreeView", "useBulmaClasses"],
   "storybook": "https://bestax.io/storybook/?path=/story/components-menu--basic",
   "summary": "The `Menu` component provides Bulma's vertical navigation menu: a simple, accessible sidebar or section menu for your Bulma React UI.",
   "import": "import { Menu } from '@allxsmith/bestax-bulma';",
@@ -241,9 +249,97 @@
       ],
       "catchAll": "Remaining props of the element or component selected by as (default <a>) and Bulma helper props",
       "types": []
+    },
+    {
+      "path": "Menu.Section",
+      "summary": "A section of the menu that opens and closes: its heading is a button drawn like `Menu.Label`, and its `Menu.List` of links shows while it's open. It's APG's disclosure navigation, for a sidebar of link groups: the links stay ordinary links, each its own tab stop, and a closed section's list is `hidden` and `inert`, so Tab and assistive tech skip it. It goes directly in `Menu`, holding a `Menu.List`. Closing it while focus is on one of its links moves focus to its heading.",
+      "component": null,
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "Additional CSS classes for the wrapping `<div>`.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "label",
+          "type": "React.ReactNode",
+          "default": null,
+          "description": "**Required.** The section's heading, drawn like `Menu.Label` inside the button that opens and closes it. Keep links and buttons out of it, since it's inside one.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "children",
+          "type": "React.ReactNode",
+          "default": null,
+          "description": "The `Menu.List` of links the section shows while it's open. The section itself goes directly in `Menu`, beside its labels and lists: inside a `Menu.Item` it would render inside the item's link, and inside a `Menu.List` it wouldn't be a list item.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "default": null,
+          "description": "Controlled open state. If provided, the section is controlled, and its button only reports through `onOpenChange`.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "default": "false",
+          "description": "Initial open state for uncontrolled usage. Open the section that holds the current page, so the reader sees where they are.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "onOpenChange",
+          "type": "(open: boolean) => void",
+          "default": null,
+          "description": "Called with the state the button asks for (`true` to open) each time it is clicked or activated with Enter or Space, in every mode. Pair it with `open` to let the button drive a controlled section.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        }
+      ],
+      "extraProps": [],
+      "catchAll": "All standard <div> attributes and Bulma helper props",
+      "types": []
     }
   ],
   "cssVars": [
+    {
+      "css": "--bulma-menu-section-gap",
+      "sass": "$menu-section-gap",
+      "default": "0.375em",
+      "scope": "root"
+    },
+    {
+      "css": "--bulma-menu-section-chevron-size",
+      "sass": "$menu-section-chevron-size",
+      "default": "1em",
+      "scope": "root"
+    },
+    {
+      "css": "--bulma-menu-section-chevron-color",
+      "sass": "$menu-section-chevron-color",
+      "default": "currentColor",
+      "scope": "root"
+    },
+    {
+      "css": "--bulma-menu-section-chevron-duration",
+      "sass": "$menu-section-chevron-duration",
+      "default": "var(--bulma-duration)",
+      "scope": "root"
+    },
     {
       "css": "--bulma-menu-item-h",
       "sass": "$menu-item-h",

package/data/components/TreeView.json

@@ -23,7 +23,11 @@
     },
     {
       "title": "Folders That Load",
-      "code": "function example() {\n  interface Folder {\n    id: string;\n    name: string;\n    hasFolders: boolean;\n  }\n\n  // A pretend server: each folder holds two more, three levels down.\n  const listFolders = (id: string) =>\n    new Promise<Folder[]>(resolve =>\n      setTimeout(\n        () =>\n          resolve(\n            ['a', 'b'].map(name => ({\n              id: `${id}/${name}`,\n              name: `Folder ${name.toUpperCase()}`,\n              hasFolders: id.split('/').length < 3,\n            }))\n          ),\n        800\n      )\n    );\n\n  const [expanded, setExpanded] = useState<string[]>([]);\n  const [loaded, setLoaded] = useState<Record<string, Folder[]>>({});\n\n  function changeOpen(next: string[]) {\n    setExpanded(next);\n    for (const id of next) {\n      if (!loaded[id]) {\n        listFolders(id).then(found =>\n          setLoaded(current => ({ ...current, [id]: found }))\n        );\n      }\n    }\n  }\n\n  const items = (folders: Folder[]): React.ReactNode =>\n    folders.map(folder => (\n      <TreeView.Item\n        key={folder.id}\n        value={folder.id}\n        label={folder.name}\n        icon=\"folder\"\n        hasChildren={folder.hasFolders}\n      >\n        {loaded[folder.id]\n          ? items(loaded[folder.id])\n          : expanded.includes(folder.id) && (\n              <TreeView.Item\n                value={`${folder.id}:loading`}\n                label=\"Loading…\"\n                disabled\n              />\n            )}\n      </TreeView.Item>\n    ));\n\n  return (\n    <TreeView\n      aria-label=\"Folders\"\n      expanded={expanded}\n      onExpandedChange={changeOpen}\n    >\n      {items([\n        { id: 'home', name: 'Home', hasFolders: true },\n        { id: 'shared', name: 'Shared', hasFolders: true },\n      ])}\n    </TreeView>\n  );\n}"
+      "code": "function example() {\n  interface Folder {\n    id: string;\n    name: string;\n    hasFolders: boolean;\n  }\n\n  // A pretend server: each folder holds two more, three levels down.\n  const listFolders = (id: string, fail: boolean) =>\n    new Promise<Folder[]>((resolve, reject) =>\n      setTimeout(() => {\n        if (fail) {\n          reject(new Error(`Couldn't reach ${id}`));\n          return;\n        }\n        resolve(\n          ['a', 'b'].map(name => ({\n            id: `${id}/${name}`,\n            name: `Folder ${name.toUpperCase()}`,\n            hasFolders: id.split('/').length < 3,\n          }))\n        );\n      }, 800)\n    );\n\n  const [expanded, setExpanded] = useState<string[]>([]);\n  // A folder's children, or how loading them is going.\n  const [found, setFound] = useState<\n    Record<string, Folder[] | 'loading' | 'error'>\n  >({});\n  // Shared fails the first time, so there's a Retry to press.\n  const [sharedFails, setSharedFails] = useState(true);\n\n  function load(id: string) {\n    const fail = id === 'shared' && sharedFails;\n    if (fail) setSharedFails(false);\n    setFound(current => ({ ...current, [id]: 'loading' }));\n    listFolders(id, fail).then(\n      folders => setFound(current => ({ ...current, [id]: folders })),\n      () => setFound(current => ({ ...current, [id]: 'error' }))\n    );\n  }\n\n  function changeOpen(next: string[]) {\n    setExpanded(next);\n    for (const id of next) {\n      if (!found[id]) load(id);\n    }\n  }\n\n  const items = (folders: Folder[]): React.ReactNode =>\n    folders.map(folder => {\n      const state = found[folder.id];\n      return (\n        <TreeView.Item\n          key={folder.id}\n          value={folder.id}\n          label={folder.name}\n          icon=\"folder\"\n          hasChildren={folder.hasFolders}\n          isLoading={state === 'loading'}\n          loadError={\n            state === 'error' ? `Couldn't load ${folder.name}` : undefined\n          }\n          onRetry={() => load(folder.id)}\n        >\n          {Array.isArray(state) && items(state)}\n        </TreeView.Item>\n      );\n    });\n\n  return (\n    <TreeView\n      aria-label=\"Folders\"\n      expanded={expanded}\n      onExpandedChange={changeOpen}\n    >\n      {items([\n        { id: 'home', name: 'Home', hasFolders: true },\n        { id: 'shared', name: 'Shared', hasFolders: true },\n      ])}\n    </TreeView>\n  );\n}"
+    },
+    {
+      "title": "Folders That Load",
+      "code": "<TreeView\n  aria-label=\"Dossiers\"\n  loadingLabel=\"Chargement…\"\n  retryLabel=\"Réessayer\"\n  loadingAnnouncement={name => `Chargement de ${name}`}\n  loadedAnnouncement={name => `${name} chargé`}\n>\n  {/* … */}\n</TreeView>"
     },
     {
       "title": "An Outline With Expand All and Collapse All",
@@ -38,8 +42,15 @@
       "code": "<TreeView\n  aria-label=\"Files\"\n  selectionMode=\"single\"\n  defaultSelected=\"src/App.tsx\"\n  defaultExpanded={['src']}\n>\n  <TreeView.Item value=\"src\" label=\"src\" icon=\"folder\">\n    <TreeView.Item value=\"src/index.ts\" label=\"index.ts\" icon=\"file\" />\n    <TreeView.Item value=\"src/App.tsx\" label=\"App.tsx\" icon=\"file\" />\n    <TreeView.Item value=\"src/legacy.ts\" label=\"legacy.ts\" disabled />\n  </TreeView.Item>\n  <TreeView.Item value=\"package.json\" label=\"package.json\" icon=\"file\" />\n</TreeView>"
     }
   ],
-  "accessibility": "`TreeView` follows the [APG Tree View Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).\n\n- **Roles:** the root is a `<ul role=\"tree\">`, each item an `<li role=\"treeitem\">`, and an open\n  parent's children sit in a `<ul role=\"group\">` inside it. A closed item's children have no\n  markup.\n- **A name:** a tree needs one, from `aria-label` or `aria-labelledby`, and a development build\n  warns when it has neither. Each item is named by `aria-labelledby` pointing at its own label, and\n  declares its `aria-level`, which VoiceOver needs according to\n  [GitHub's testing](https://github.blog/engineering/user-experience/considerations-for-making-a-tree-view-component-accessible/).\n  `aria-expanded` is on parents only.\n- **One tab stop, with real focus:** one item holds `tabIndex={0}` and the rest `-1`, and focus\n  moves from item to item, rather than through `aria-activedescendant`. When focus comes into the\n  tree, it lands on the selected item, or in a checkbox tree on the first checked item on the page.\n  Without one, it lands where focus last was, or on the first item. If the item holding the stop\n  goes away, its nearest ancestor on the page takes it, and focus goes too if it had focus.\n- **Selection:** a `single` tree marks each enabled item `aria-selected`, `true` or `false`. A\n  `checkbox` tree marks `aria-checked` on every item, `true`, `false` or `mixed`, disabled ones\n  included, and adds `aria-multiselectable=\"true\"` to the tree. A tree never has both, and a tree\n  with no `selectionMode` has neither. Selection doesn't follow focus.\n- **The box** is a [`Checkbox`](https://bestax.io/docs/api/form/checkbox) inside an `aria-hidden` span, with\n  `tabIndex={-1}`, so it's neither a tab stop nor a second thing for a screen reader to read. The\n  item's `aria-checked` is what a screen reader hears.\n- **Disabled items** are `aria-disabled` and stay reachable from the arrow keys, Home, End and\n  typing, so a screen reader user finds them. They're never selected, checked, opened or closed.\n  One that's already open stays open, so what's under it is still reachable.\n\nEnter and Space do the item's one thing, which depends on the mode:\n\n| Key   | No `selectionMode`       | `single`         | `checkbox`               |\n| ----- | ------------------------ | ---------------- | ------------------------ |\n| Enter | Opens or closes a parent | Selects the item | Opens or closes a parent |\n| Space | Opens or closes a parent | Selects the item | Checks or unchecks it    |\n\nThe rest work the same in every mode:\n\n| Key        | What it does                                                                              |\n| ---------- | ----------------------------------------------------------------------------------------- |\n| Down, Up   | The next or previous item on the page, without wrapping                                   |\n| Right      | Opens a closed parent, and focus stays. On an open parent, moves to its first child       |\n| Left       | Closes an open parent. Otherwise moves to its parent                                      |\n| Home, End  | The first item, and the last one on the page                                              |\n| `*`        | Opens every closed parent beside the focused item, itself included. Focus stays           |\n| Characters | Moves to the next item whose label starts with what's typed, several characters adding up |\n| Tab        | Leaves the tree                                                                           |\n\n- **Right to left:** Right and Left swap in a right-to-left page, and the chevron points to the\n  left while closed.\n- **Keys it leaves alone:** anything with Control, Alt or Meta held, anything while an input method\n  is composing, and Escape, so it reaches a Modal or Popover around the tree. An item's own\n  `onKeyDown` runs first, and calling `preventDefault()` there keeps the tree from acting on the\n  key.\n- **Clicks:** the chevron only opens and closes. The rest of the row does the item's one thing:\n  opens or closes it with no `selectionMode`, selects it (and opens or closes a parent) in a\n  `single` tree, and checks it in a `checkbox` tree. A click moves focus and the tab stop to the\n  item.\n- **Not for site navigation:** APG's own\n  [navigation tree example](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/)\n  says \"A pattern more suited for typical site navigation with expandable groups of links is the\n  disclosure pattern\", and a tree's items aren't links. Keep a sidebar on [`Menu`](https://bestax.io/docs/api/components/menu).\n- **Focus and the selected look differ:** the focus ring sits outside the row, so it shows on the\n  selected fill as well as on a plain row.\n- **Forced colors:** in Windows high contrast mode the selected row is the system's Highlight and\n  HighlightText, a disabled row is GrayText, and the focus ring, the chevrons and the guide lines\n  stay visible, since they're outlines and borders. A mixed box keeps its dash.\n- **Motion:** the chevron turns with a short transition, which stops when the reader asks for\n  reduced motion.",
-  "related": ["Checkbox", "Collapse", "Menu", "Sidebar", "useBulmaClasses"],
+  "accessibility": "`TreeView` follows the [APG Tree View Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).\n\n- **Roles:** the root is a `<ul role=\"tree\">`, each item an `<li role=\"treeitem\">`, and an open\n  parent's children sit in a `<ul role=\"group\">` inside it. A closed item's children have no\n  markup.\n- **A name:** a tree needs one, from `aria-label` or `aria-labelledby`, and a development build\n  warns when it has neither. Each item is named by `aria-labelledby` pointing at its own label, and\n  declares its `aria-level`, which VoiceOver needs according to\n  [GitHub's testing](https://github.blog/engineering/user-experience/considerations-for-making-a-tree-view-component-accessible/).\n  `aria-expanded` is on parents only.\n- **One tab stop, with real focus:** one item holds `tabIndex={0}` and the rest `-1`, and focus\n  moves from item to item, rather than through `aria-activedescendant`. When focus comes into the\n  tree, it lands on the selected item, or in a checkbox tree on the first checked item on the page.\n  Without one, it lands where focus last was, or on the first item. If the item holding the stop\n  goes away, its nearest ancestor on the page takes it, and focus goes too if it had focus.\n- **Selection:** a `single` tree marks each enabled item `aria-selected`, `true` or `false`. A\n  `checkbox` tree marks `aria-checked` on every item, `true`, `false` or `mixed`, disabled ones\n  included, and adds `aria-multiselectable=\"true\"` to the tree. A tree never has both, and a tree\n  with no `selectionMode` has neither. Selection doesn't follow focus.\n- **The box** is a [`Checkbox`](https://bestax.io/docs/api/form/checkbox) inside an `aria-hidden` span, with\n  `tabIndex={-1}`, so it's neither a tab stop nor a second thing for a screen reader to read. The\n  item's `aria-checked` is what a screen reader hears.\n- **Disabled items** are `aria-disabled` and stay reachable from the arrow keys, Home, End and\n  typing, so a screen reader user finds them. They're never selected, checked, opened or closed.\n  One that's already open stays open, so what's under it is still reachable.\n- **A loading item's row** is a `treeitem` that says Loading…, marked `aria-disabled` and reached\n  the way a disabled item is, so a screen reader user who moves into the folder hears what's\n  happening. It has no value: it's never selected or checked, it has no `aria-selected` or\n  `aria-checked`, and a checkbox tree doesn't count it. If it goes with focus on it, focus moves to\n  the item it was loading for. Bulma's loader turns in its chevron's place, hidden from assistive\n  tech.\n- **A failed load's row** is a `treeitem` named by its message and the Retry button's text, such\n  as \"Couldn't load src Retry\". Enter, Space or a click on the row calls `onRetry`, in every mode.\n  The button is drawn inside an `aria-hidden` span and takes no focus, the way an item's box is,\n  so the tree keeps its one tab stop, and nothing in the message should be a link or a button\n  either. A retry that starts loading keeps the same row, so focus stays on it. With no `onRetry`,\n  the row is disabled and shows the message alone.\n- **Announcements:** a visually hidden `role=\"status\"` region with `aria-live=\"polite\"` sits right\n  after the tree, one for the whole tree, from the moment it mounts, so a screen reader is already\n  listening when something is written into it. It says \"Loading src\" when an open item starts\n  loading, a failed load's message, and \"src loaded\" when the loading row or a failed load's row\n  goes with the item still open.\n  The name is the item's label as a screen reader reads it. A closed item, or one in a closed\n  branch, says nothing. Each announcement is written a moment after the change and cleared soon\n  after, so the page doesn't keep a second copy of the text.\n\nEnter and Space do the item's one thing, which depends on the mode:\n\n| Key   | No `selectionMode`       | `single`         | `checkbox`               |\n| ----- | ------------------------ | ---------------- | ------------------------ |\n| Enter | Opens or closes a parent | Selects the item | Opens or closes a parent |\n| Space | Opens or closes a parent | Selects the item | Checks or unchecks it    |\n\nOn a failed load's row, both retry, whatever the mode. The rest work the same in every mode:\n\n| Key        | What it does                                                                              |\n| ---------- | ----------------------------------------------------------------------------------------- |\n| Down, Up   | The next or previous item on the page, without wrapping                                   |\n| Right      | Opens a closed parent, and focus stays. On an open parent, moves to its first child       |\n| Left       | Closes an open parent. Otherwise moves to its parent                                      |\n| Home, End  | The first item, and the last one on the page                                              |\n| `*`        | Opens every closed parent beside the focused item, itself included. Focus stays           |\n| Characters | Moves to the next item whose label starts with what's typed, several characters adding up |\n| Tab        | Leaves the tree                                                                           |\n\n- **Right to left:** Right and Left swap in a right-to-left page, and the chevron points to the\n  left while closed.\n- **Keys it leaves alone:** anything with Control, Alt or Meta held, anything while an input method\n  is composing, and Escape, so it reaches a Modal or Popover around the tree. An item's own\n  `onKeyDown` runs first, and calling `preventDefault()` there keeps the tree from acting on the\n  key.\n- **Clicks:** the chevron only opens and closes. The rest of the row does the item's one thing:\n  opens or closes it with no `selectionMode`, selects it (and opens or closes a parent) in a\n  `single` tree, and checks it in a `checkbox` tree. A click moves focus and the tab stop to the\n  item.\n- **Not for site navigation:** APG's own\n  [navigation tree example](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/)\n  says \"A pattern more suited for typical site navigation with expandable groups of links is the\n  disclosure pattern\", and a tree's items aren't links. Keep a sidebar on [`Menu`](https://bestax.io/docs/api/components/menu),\n  whose `Menu.Section` is that disclosure pattern.\n- **Focus and the selected look differ:** the focus ring sits outside the row, so it shows on the\n  selected fill as well as on a plain row.\n- **Forced colors:** in Windows high contrast mode the selected row is the system's Highlight and\n  HighlightText, a disabled row or a loading one is GrayText, and the focus ring, the chevrons and\n  the guide lines stay visible, since they're outlines and borders. A mixed box keeps its dash, and\n  the loader's ring stays open.\n- **Motion:** the chevron turns with a short transition, and the loader spins. Both stop when the\n  reader asks for reduced motion, and the loader stays drawn.",
+  "related": [
+    "Checkbox",
+    "Collapse",
+    "Loader",
+    "Menu",
+    "Sidebar",
+    "useBulmaClasses"
+  ],
   "storybook": "https://bestax.io/storybook/?path=/story/components-treeview--default",
   "summary": "The `TreeView` component renders a tree of items you browse and pick from, the way a file explorer works: one tab stop, the arrow keys to move, and Right and Left to open and close. It's the APG Tree View pattern, drawn to look like Bulma's menu. It isn't for site navigation: items aren't links, and a sidebar whose sections open and close is `Menu`'s job. The root owns which items are open, through `expanded`, `defaultExpanded` and `onExpandedChange`. `selectionMode` picks one of three trees. With `none`, nothing is picked. With `single`, one item is, and `selected` says which. With `checkbox`, each item has a box, a check reaches every enabled item under it, closed branches included, and a parent with some of its items checked is mixed. `selected` is read in a `single` tree only, and `checked` in a `checkbox` tree only. Selection never follows focus. Disabled items stay reachable from the keys, so a screen reader finds them. The tree needs a name, from `aria-label` or `aria-labelledby`, and a development build warns when it has neither.",
   "import": "import { TreeView } from '@allxsmith/bestax-bulma';",
@@ -159,6 +170,42 @@
           "inherited": false,
           "deprecated": false
         },
+        {
+          "name": "loadingLabel",
+          "type": "string",
+          "default": "'Loading…'",
+          "description": "What the row in a loading item's group says. In your app's language.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "retryLabel",
+          "type": "string",
+          "default": "'Retry'",
+          "description": "The Retry button's text on a failed load's row. In your app's language.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "loadingAnnouncement",
+          "type": "(name: string) => string",
+          "default": null,
+          "description": "What the live region says when an open item starts loading, built from the item's name. In your app's language. Default: `` `Loading ${name}` ``.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "loadedAnnouncement",
+          "type": "(name: string) => string",
+          "default": null,
+          "description": "What the live region says when that load finishes. In your app's language. Default: `` `${name} loaded` ``.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
         {
           "name": "className",
           "type": "string",
@@ -251,6 +298,33 @@
           "inherited": false,
           "deprecated": false
         },
+        {
+          "name": "isLoading",
+          "type": "boolean",
+          "default": "false",
+          "description": "Its children are on their way. While it's open, its group ends in a row that says so, and the tree's live region says it's loading, then that it's loaded once this goes back to `false`. A parent only: pair it with `hasChildren`, or with the children it already has.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "loadError",
+          "type": "React.ReactNode",
+          "default": null,
+          "description": "Its children didn't load. While it's open, its group ends in a row with this message, and a Retry button when there's an `onRetry`, and the live region reads the message out, so name the item in it (\"Couldn't load src\"), then says it's loaded once this goes with the item still open. A parent only, like `isLoading`. Nothing in it should be a link or a button: the row is what's pressed. `isLoading` wins while both are given.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "onRetry",
+          "type": "() => void",
+          "default": null,
+          "description": "Called by the Retry button on a failed load's row, and by Enter or Space there. Set `isLoading` while the retry runs, so the live region says it's loading, and reads the message out again if it fails again. The same message passed a second time with no loading between is no change the tree can see.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
         {
           "name": "disabled",
           "type": "boolean",

package/data/components/useFocusTrap.json

@@ -23,8 +23,8 @@
   "storybook": "https://bestax.io/storybook/?path=/story/helpers-usefocustrap--default",
   "summary": "`useFocusTrap` keeps keyboard focus inside a container while it is active: focus moves in when the trap turns on, Tab and Shift+Tab wrap between the first and…",
   "import": "import { useFocusTrap } from '@allxsmith/bestax-bulma';",
-  "api": "```ts\nfunction useFocusTrap(\n  containerRef: RefObject<HTMLElement | null>,\n  options?: UseFocusTrapOptions\n): void;\n\ninterface UseFocusTrapOptions {\n  active?: boolean;\n  initialFocusRef?: RefObject<HTMLElement | null>;\n  restoreFocus?: boolean | RefObject<HTMLElement | null>;\n}\n```\n\n### Parameters\n\n| Parameter                 | Type                                          | Default | Description                                                                                                                                       |\n| ------------------------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `containerRef`            | `RefObject<HTMLElement \\| null>`              | —       | The element focus stays inside.                                                                                                                   |\n| `options.active`          | `boolean`                                     | `true`  | Whether the trap is on. Turning it on moves focus in; turning it off (or unmounting) releases Tab and restores focus.                             |\n| `options.initialFocusRef` | `RefObject<HTMLElement \\| null>`              | —       | An element inside the container that can take focus, focused when the trap turns on; otherwise the first tab stop, then the container.            |\n| `options.restoreFocus`    | `boolean` \\| `RefObject<HTMLElement \\| null>` | `true`  | Where focus goes when the trap turns off: `true` for the element focused when it turned on, a ref for that element, `false` to leave focus alone. |\n\nIt returns nothing. On the server it does nothing, and the container renders as written.",
-  "doc": "# useFocusTrap\n\n## Overview\n\n`useFocusTrap` keeps keyboard focus inside a container while it is active: focus moves in when the trap turns on, Tab and Shift+Tab wrap between the first and last tab stops, and focus goes back where it came from when the trap turns off.\n\nUse it for your own floating or modal content, such as a command palette or a custom overlay. `Modal`, `Dialog`, `Sidebar`, `Popover` and the date and time pickers already manage focus themselves, and a panel opened from a button is what [`Popover`](https://bestax.io/docs/api/components/popover) is for.\n\n---\n\n## Import\n\n```tsx\nimport { useFocusTrap } from '@allxsmith/bestax-bulma';\n```\n\n---\n\n## Usage\n\n### A panel opened from a button\n\nPass a ref to the container and turn the trap on with the panel. Give the container `tabIndex={-1}` so it can hold focus itself when nothing inside can. Open the panel below, then Tab past Cancel or Shift+Tab past the input: focus wraps, skipping the disabled button.\n\n```tsx live\nfunction example() {\n  const [open, setOpen] = useState(false);\n  const buttonRef = React.useRef<HTMLButtonElement>(null);\n  const panelRef = React.useRef<HTMLDivElement>(null);\n  useFocusTrap(panelRef, { active: open, restoreFocus: buttonRef });\n\n  return (\n    <>\n      <Button\n        ref={buttonRef}\n        aria-haspopup=\"dialog\"\n        aria-expanded={open}\n        aria-controls=\"filters-panel\"\n        onClick={() => setOpen(o => !o)}\n      >\n        Filters\n      </Button>\n      {open && (\n        <div\n          ref={panelRef}\n          id=\"filters-panel\"\n          role=\"dialog\"\n          aria-label=\"Filters\"\n          tabIndex={-1}\n          onKeyDown={e => {\n            if (e.key !== 'Escape') return;\n            e.preventDefault();\n            setOpen(false);\n          }}\n        >\n          <Box mt=\"3\">\n            <Input label=\"Name contains\" />\n            <Buttons>\n              <Button color=\"primary\" onClick={() => setOpen(false)}>\n                Apply\n              </Button>\n              <Button disabled>Export</Button>\n              <Button onClick={() => setOpen(false)}>Cancel</Button>\n            </Buttons>\n          </Box>\n        </div>\n      )}\n    </>\n  );\n}\n```\n\nThe trap doesn't close anything. Escape, a click outside and the buttons that dismiss the panel are the component's to handle, as the `onKeyDown` above does. Its `preventDefault()` marks the Escape used, so a [`Modal`](https://bestax.io/docs/api/components/modal) or [`Sidebar`](https://bestax.io/docs/api/components/sidebar) around the panel stays open for the next one.\n\n### Where focus starts\n\nOn its own the trap focuses the first tab stop inside the container, or the container when there is none. `initialFocusRef` picks a specific element inside the container instead, such as the search box of a command palette. The element has to be able to take focus, so a heading needs `tabIndex={-1}`. When focusing it doesn't put focus inside the container, because the ref is empty or its element is outside, disabled, hidden or can't take focus, the trap starts on the first tab stop as it would without the ref.\n\n```tsx\nconst searchRef = useRef<HTMLInputElement>(null);\nuseFocusTrap(paletteRef, { active: open, initialFocusRef: searchRef });\n```\n\n### Where focus goes back to\n\n`restoreFocus` decides where focus lands when the trap turns off, whether because `active` went `false`, the container left the page or the component unmounted.\n\n- `true` (the default) returns it to the element that had focus when the trap turned on.\n- A ref sends it to that element instead. Prefer this for a panel opened from a button: some browsers don't focus a button when it is clicked, and content that focuses itself as it mounts (an `autoFocus` input) takes focus before the trap can see where it came from.\n- `false` leaves focus alone.\n\nFocus only moves back while the trap still holds it. If a click has already put focus on something else outside the container, it stays there.\n\n### With portals\n\nA trapped panel is often rendered through a portal, at the end of `document.body`, and a portaled panel can mount a render after the trap turns on: once the page has hydrated, or once a target held in state exists. The trap waits for hydration and looks for its container again each time the component calling it renders, so it attaches to the panel once the panel is there.\n\nPut the ref on the element inside the [`Portal`](https://bestax.io/docs/api/helpers/portal), so the trap holds the portaled content itself. The panel below is declared inside a box that clips its overflow and portals into an element after it, as in the Portal page's [container example](https://bestax.io/docs/api/helpers/portal#into-a-container). Open it, then Tab past Cancel: focus wraps inside the panel, and Escape or either button closes it and returns focus to Share.\n\n```tsx live\nfunction example() {\n  const [open, setOpen] = useState(false);\n  const [target, setTarget] = useState<HTMLElement | null>(null);\n  const buttonRef = React.useRef<HTMLButtonElement>(null);\n  const panelRef = React.useRef<HTMLDivElement>(null);\n  useFocusTrap(panelRef, { active: open, restoreFocus: buttonRef });\n\n  return (\n    <>\n      <Box overflow=\"clipped\">\n        <Button\n          ref={buttonRef}\n          aria-haspopup=\"dialog\"\n          aria-expanded={open}\n          aria-controls=\"share-panel\"\n          onClick={() => setOpen(o => !o)}\n        >\n          Share\n        </Button>\n        {open && target && (\n          <Portal container={target}>\n            <div\n              ref={panelRef}\n              id=\"share-panel\"\n              role=\"dialog\"\n              aria-label=\"Share\"\n              tabIndex={-1}\n              onKeyDown={e => {\n                if (e.key !== 'Escape') return;\n                e.preventDefault();\n                setOpen(false);\n              }}\n            >\n              <Box mt=\"3\">\n                <Input label=\"Email\" type=\"email\" />\n                <Buttons>\n                  <Button color=\"primary\" onClick={() => setOpen(false)}>\n                    Send\n                  </Button>\n                  <Button onClick={() => setOpen(false)}>Cancel</Button>\n                </Buttons>\n              </Box>\n            </div>\n          </Portal>\n        )}\n      </Box>\n      <div ref={setTarget} />\n    </>\n  );\n}\n```\n\nThe other way round doesn't work: a portal rendered _inside_ the trapped container puts its content somewhere else in the DOM, outside the container, where Tab from the trap can't reach it and the trap doesn't hold focus. Render a nested overlay inside the container, or give it a trap of its own.\n\n### Which elements are tab stops\n\nThe trap wraps at the first and last elements the browser's Tab would visit, taken in document order:\n\n- links with an `href`, buttons, inputs other than `type=\"hidden\"`, selects and text areas\n- the areas with an `href` of an image map whose image is shown, taken where the `<map>` sits\n- frames: `<iframe>`, `<embed>` and `<object>`\n- `<audio>` and `<video>` with `controls`\n- the summary of a `<details>`, which stays a stop while the details is closed\n- an editable region (`contentEditable`), counted once rather than once per editable element inside it\n- anything with a `tabIndex` of `0` or more\n- the content of an open shadow root inside the container, such as a web component's own controls, with anything slotted into it taken where its slot is\n\nWithin those, what the browser's Tab skips is skipped here too, so none of it can become an end of the trap and let Tab walk out of the container:\n\n- a negative `tabIndex`, such as the unfocused items of a roving-tabindex grid\n- disabled controls, including those inside a disabled `<fieldset>`\n- anything not rendered: `hidden`, `display: none` on the element or an ancestor (for slotted content, an ancestor of its slot counts), `visibility: hidden`, the content of a closed `<details>`, and a child of an open shadow root's host that no slot takes\n- anything inside an `inert` subtree\n- all but one button of a radio group: the checked one, or the first when none is checked\n- every button of a radio group whose checked button is outside the container, because a group is every button that shares its name, form owner and tree (the page, or one shadow root), not only the ones in the container\n\n### When Tab leaves anyway\n\nA browser can leave out a stop the page has, such as links when its settings say to. When a Tab the trap let through still takes focus out of the container, the trap sends it back to the other end. If the container is the last thing on the page, there is nothing outside for focus to land on and the browser can take it to its own toolbar instead, so avoid ending a trap with a link.\n\nOnly Tab is watched. A click or a script that moves focus out of the container is left alone, and the next Tab starts from wherever focus went. Pulling focus back from a click is modal behaviour, and a modal also has to block the page behind it; [`Modal`](https://bestax.io/docs/api/components/modal) does both. For a non-modal panel, close it when focus or a click goes elsewhere.\n\n### What the trap can't see into\n\nSome elements move focus among parts of their own, and the trap sees them as one stop:\n\n- A frame's content is its own document. Once focus is inside, Tab moves through the frame without the trap seeing it, and Tab from the frame's last stop goes on to whatever follows the frame. At the end of the trap, that is outside it: follow a frame with another stop.\n- A native date or time input has a stop for each field. At the edge of the trap, Tab wraps instead of visiting the later fields. Keep it away from the edges, or follow it with another stop.\n- A closed shadow root can't be looked into. The trap sees its host and the host's own children, but not the stops inside the root or which of those children a slot takes. A child that no slot takes isn't rendered and can't take focus, so if it ends up as the trap's first or last stop, turning the trap on or wrapping Tab to it leaves focus where it was. Keep a closed-root host away from the trap's edges, or give it no children that a slot doesn't take.\n- A scrollable region with nothing focusable inside is a stop in some browsers and not in others. Give it `tabIndex={0}` so it is one everywhere, which also lets keyboard users scroll it.\n\n### What the trap takes on trust\n\n- A browser can visit an image map's areas where the `<map>` sits or where its image is. The trap takes them where the map is, so keep the map right after its image, where the two agree.\n- A positive `tabIndex` changes the order the browser's Tab visits, but not the trap's ends, which stay the first and last stops in document order. Where the two disagree, a Tab past the browser's end is let through and then sent to the trap's end instead, which can be the very element it left, so focus seems stuck. Keep positive `tabIndex` out of a trap.\n- The trap listens for Tab on the container. Content inside that stops a Tab keydown from propagating keeps it from the trap, so that Tab isn't wrapped, and focus it takes out isn't sent back.\n\n### Nested traps\n\nThe trap listens for Tab on its container, so a trap inside another one handles Tab first and the outer trap stands aside. A panel that opens a second panel inside it keeps focus in the inner one.\n\n---\n\n## API\n\n```ts\nfunction useFocusTrap(\n  containerRef: RefObject<HTMLElement | null>,\n  options?: UseFocusTrapOptions\n): void;\n\ninterface UseFocusTrapOptions {\n  active?: boolean;\n  initialFocusRef?: RefObject<HTMLElement | null>;\n  restoreFocus?: boolean | RefObject<HTMLElement | null>;\n}\n```\n\n### Parameters\n\n| Parameter                 | Type                                          | Default | Description                                                                                                                                       |\n| ------------------------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `containerRef`            | `RefObject<HTMLElement \\| null>`              | —       | The element focus stays inside.                                                                                                                   |\n| `options.active`          | `boolean`                                     | `true`  | Whether the trap is on. Turning it on moves focus in; turning it off (or unmounting) releases Tab and restores focus.                             |\n| `options.initialFocusRef` | `RefObject<HTMLElement \\| null>`              | —       | An element inside the container that can take focus, focused when the trap turns on; otherwise the first tab stop, then the container.            |\n| `options.restoreFocus`    | `boolean` \\| `RefObject<HTMLElement \\| null>` | `true`  | Where focus goes when the trap turns off: `true` for the element focused when it turned on, a ref for that element, `false` to leave focus alone. |\n\nIt returns nothing. On the server it does nothing, and the container renders as written.\n\n---\n\n## Accessibility\n\n- Trap focus in content that asks for the reader's attention until it is dismissed: a dialog, a command palette, a panel with its own controls. Content a reader should be able to Tab past, such as a tooltip or a disclosure, shouldn't be trapped.\n- Pair the trap with a way out. The trap handles Tab only, so wire Escape (and any close button) to turn it off.\n- Give the container a role and an accessible name (`role=\"dialog\"` with `aria-label` or `aria-labelledby`), and give the button that opens it `aria-haspopup`, `aria-expanded` and `aria-controls`.\n- Return focus to the element that opened the content when it closes. The default does, and a ref to the trigger makes it reliable.\n- The trap is for the keyboard. It doesn't hide the rest of the page from screen readers or pointers, and it doesn't pull focus back from a click; for fully modal content, use [`Modal`](https://bestax.io/docs/api/components/modal), which sets `aria-modal`.\n\n---\n\n## Related Components\n\n- [`Modal`](https://bestax.io/docs/api/components/modal): A modal overlay with its own focus management.\n- [`Dialog`](https://bestax.io/docs/api/components/dialog): Ready-made confirm and alert dialogs.\n\n---\n\n## Additional Resources\n\n- [Storybook: useFocusTrap Stories](https://bestax.io/storybook/?path=/story/helpers-usefocustrap--default)\n- [WAI-ARIA Authoring Practices: Dialog (Modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)",
+  "api": "```ts\nfunction useFocusTrap(\n  containerRef: RefObject<HTMLElement | null>,\n  options?: UseFocusTrapOptions\n): void;\n\ninterface UseFocusTrapOptions {\n  active?: boolean;\n  initialFocusRef?: RefObject<HTMLElement | null>;\n  restoreFocus?: boolean | RefObject<HTMLElement | null>;\n}\n```\n\n### Parameters\n\n| Parameter                 | Type                                          | Default | Description                                                                                                                                             |\n| ------------------------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `containerRef`            | `RefObject<HTMLElement \\| null>`              | —       | The element focus stays inside.                                                                                                                         |\n| `options.active`          | `boolean`                                     | `true`  | Whether the trap is on. Turning it on moves focus in; turning it off (or unmounting) releases Tab and restores focus.                                   |\n| `options.initialFocusRef` | `RefObject<HTMLElement \\| null>`              | —       | An element inside the container that can take focus, focused when the trap turns on; otherwise the first tab stop that takes focus, then the container. |\n| `options.restoreFocus`    | `boolean` \\| `RefObject<HTMLElement \\| null>` | `true`  | Where focus goes when the trap turns off: `true` for the element focused when it turned on, a ref for that element, `false` to leave focus alone.       |\n\nIt returns nothing. On the server it does nothing, and the container renders as written.",
+  "doc": "# useFocusTrap\n\n## Overview\n\n`useFocusTrap` keeps keyboard focus inside a container while it is active: focus moves in when the trap turns on, Tab and Shift+Tab wrap between the first and last tab stops, and focus goes back where it came from when the trap turns off.\n\nUse it for your own floating or modal content, such as a command palette or a custom overlay. `Modal`, `Dialog`, `Sidebar`, `Popover` and the date and time pickers already manage focus themselves, and a panel opened from a button is what [`Popover`](https://bestax.io/docs/api/components/popover) is for.\n\n---\n\n## Import\n\n```tsx\nimport { useFocusTrap } from '@allxsmith/bestax-bulma';\n```\n\n---\n\n## Usage\n\n### A panel opened from a button\n\nPass a ref to the container and turn the trap on with the panel. Give the container `tabIndex={-1}` so it can hold focus itself when nothing inside can. Open the panel below, then Tab past Cancel or Shift+Tab past the input: focus wraps, skipping the disabled button.\n\n```tsx live\nfunction example() {\n  const [open, setOpen] = useState(false);\n  const buttonRef = React.useRef<HTMLButtonElement>(null);\n  const panelRef = React.useRef<HTMLDivElement>(null);\n  useFocusTrap(panelRef, { active: open, restoreFocus: buttonRef });\n\n  return (\n    <>\n      <Button\n        ref={buttonRef}\n        aria-haspopup=\"dialog\"\n        aria-expanded={open}\n        aria-controls=\"filters-panel\"\n        onClick={() => setOpen(o => !o)}\n      >\n        Filters\n      </Button>\n      {open && (\n        <div\n          ref={panelRef}\n          id=\"filters-panel\"\n          role=\"dialog\"\n          aria-label=\"Filters\"\n          tabIndex={-1}\n          onKeyDown={e => {\n            if (e.key !== 'Escape') return;\n            e.preventDefault();\n            setOpen(false);\n          }}\n        >\n          <Box mt=\"3\">\n            <Input label=\"Name contains\" />\n            <Buttons>\n              <Button color=\"primary\" onClick={() => setOpen(false)}>\n                Apply\n              </Button>\n              <Button disabled>Export</Button>\n              <Button onClick={() => setOpen(false)}>Cancel</Button>\n            </Buttons>\n          </Box>\n        </div>\n      )}\n    </>\n  );\n}\n```\n\nThe trap doesn't close anything. Escape, a click outside and the buttons that dismiss the panel are the component's to handle, as the `onKeyDown` above does. Its `preventDefault()` marks the Escape used, so a [`Modal`](https://bestax.io/docs/api/components/modal) or [`Sidebar`](https://bestax.io/docs/api/components/sidebar) around the panel stays open for the next one.\n\n### Where focus starts\n\nOn its own the trap focuses the first tab stop inside the container that takes focus, or the container when none does. `initialFocusRef` picks a specific element inside the container instead, such as the search box of a command palette. The element has to be able to take focus, so a heading needs `tabIndex={-1}`. When focusing it doesn't put focus inside the container, because the ref is empty or its element is outside, disabled, hidden or can't take focus, the trap starts on the first tab stop as it would without the ref.\n\n```tsx\nconst searchRef = useRef<HTMLInputElement>(null);\nuseFocusTrap(paletteRef, { active: open, initialFocusRef: searchRef });\n```\n\n### Where focus goes back to\n\n`restoreFocus` decides where focus lands when the trap turns off, whether because `active` went `false`, the container left the page or the component unmounted.\n\n- `true` (the default) returns it to the element that had focus when the trap turned on.\n- A ref sends it to that element instead. Prefer this for a panel opened from a button: some browsers don't focus a button when it is clicked, and content that focuses itself as it mounts (an `autoFocus` input) takes focus before the trap can see where it came from.\n- `false` leaves focus alone.\n\nFocus only moves back while the trap still holds it. If a click has already put focus on something else outside the container, it stays there.\n\n### With portals\n\nA trapped panel is often rendered through a portal, at the end of `document.body`, and a portaled panel can mount a render after the trap turns on: once the page has hydrated, or once a target held in state exists. The trap waits for hydration and looks for its container again each time the component calling it renders, so it attaches to the panel once the panel is there.\n\nPut the ref on the element inside the [`Portal`](https://bestax.io/docs/api/helpers/portal), so the trap holds the portaled content itself. The panel below is declared inside a box that clips its overflow and portals into an element after it, as in the Portal page's [container example](https://bestax.io/docs/api/helpers/portal#into-a-container). Open it, then Tab past Cancel: focus wraps inside the panel, and Escape or either button closes it and returns focus to Share.\n\n```tsx live\nfunction example() {\n  const [open, setOpen] = useState(false);\n  const [target, setTarget] = useState<HTMLElement | null>(null);\n  const buttonRef = React.useRef<HTMLButtonElement>(null);\n  const panelRef = React.useRef<HTMLDivElement>(null);\n  useFocusTrap(panelRef, { active: open, restoreFocus: buttonRef });\n\n  return (\n    <>\n      <Box overflow=\"clipped\">\n        <Button\n          ref={buttonRef}\n          aria-haspopup=\"dialog\"\n          aria-expanded={open}\n          aria-controls=\"share-panel\"\n          onClick={() => setOpen(o => !o)}\n        >\n          Share\n        </Button>\n        {open && target && (\n          <Portal container={target}>\n            <div\n              ref={panelRef}\n              id=\"share-panel\"\n              role=\"dialog\"\n              aria-label=\"Share\"\n              tabIndex={-1}\n              onKeyDown={e => {\n                if (e.key !== 'Escape') return;\n                e.preventDefault();\n                setOpen(false);\n              }}\n            >\n              <Box mt=\"3\">\n                <Input label=\"Email\" type=\"email\" />\n                <Buttons>\n                  <Button color=\"primary\" onClick={() => setOpen(false)}>\n                    Send\n                  </Button>\n                  <Button onClick={() => setOpen(false)}>Cancel</Button>\n                </Buttons>\n              </Box>\n            </div>\n          </Portal>\n        )}\n      </Box>\n      <div ref={setTarget} />\n    </>\n  );\n}\n```\n\nThe other way round doesn't work: a portal rendered _inside_ the trapped container puts its content somewhere else in the DOM, outside the container, where Tab from the trap can't reach it and the trap doesn't hold focus. Render a nested overlay inside the container, or give it a trap of its own.\n\n### Which elements are tab stops\n\nThe trap wraps at the first and last elements the browser's Tab would visit, taken in document order:\n\n- links with an `href`, buttons, inputs other than `type=\"hidden\"`, selects and text areas\n- the areas with an `href` of an image map whose image is shown, taken where the `<map>` sits\n- frames: `<iframe>`, `<embed>` and `<object>`\n- `<audio>` and `<video>` with `controls`\n- the summary of a `<details>`, which stays a stop while the details is closed\n- an editable region (`contentEditable`), counted once rather than once per editable element inside it\n- anything with a `tabIndex` of `0` or more\n- the content of an open shadow root inside the container, such as a web component's own controls, with anything slotted into it taken where its slot is\n\nWithin those, what the browser's Tab skips is skipped here too, so none of it can become an end of the trap and let Tab walk out of the container:\n\n- a negative `tabIndex`, such as the unfocused items of a roving-tabindex grid\n- disabled controls, including those inside a disabled `<fieldset>`\n- anything not rendered: `hidden`, `display: none` on the element or an ancestor (for slotted content, an ancestor of its slot counts), `visibility: hidden`, the content of a closed `<details>`, and a child of an open shadow root's host that no slot takes\n- anything inside an `inert` subtree\n- all but one button of a radio group: the checked one, or the first when none is checked\n- every button of a radio group whose checked button is outside the container, because a group is every button that shares its name, form owner and tree (the page, or one shadow root), not only the ones in the container\n\n### When Tab leaves anyway\n\nA browser can leave out a stop the page has, such as links when its settings say to. When a Tab the trap let through still takes focus out of the container, the trap sends it back to the other end. If the container is the last thing on the page, there is nothing outside for focus to land on and the browser can take it to its own toolbar instead, so avoid ending a trap with a link.\n\nA browser can also refuse focus to a stop. An `<object>` or `<embed>` with nothing to show is the common one, such as an `<object>` whose file failed to load, and which of them a browser refuses differs between browsers and with what has loaded, so the trap doesn't guess. Whenever it moves focus, as it turns on, when Tab wraps, and when it sends a Tab back in, it passes over a stop that doesn't take focus for the next one, and falls back to the container when none does.\n\nA refused stop at an end of the trap is the one case that still gets out. The trap can't tell it will be refused, so a Tab toward it is left to the browser, which goes past it and out of the container the way it goes past a skipped link. Focus comes back only when there's something outside for it to land on, so don't end a trap that sits last on the page with an `<object>` or `<embed>` that may have nothing to show, any more than with a link.\n\nOnly Tab is watched. A click or a script that moves focus out of the container is left alone, and the next Tab starts from wherever focus went. Pulling focus back from a click is modal behaviour, and a modal also has to block the page behind it; [`Modal`](https://bestax.io/docs/api/components/modal) does both. For a non-modal panel, close it when focus or a click goes elsewhere.\n\n### What the trap can't see into\n\nSome elements move focus among parts of their own, and the trap sees them as one stop:\n\n- A frame's content is its own document. Once focus is inside, Tab moves through the frame without the trap seeing it, and Tab from the frame's last stop goes on to whatever follows the frame. At the end of the trap, that is outside it: follow a frame with another stop.\n- A native date or time input has a stop for each field. At the edge of the trap, Tab wraps instead of visiting the later fields. Keep it away from the edges, or follow it with another stop.\n- A closed shadow root can't be looked into. The trap sees its host and the host's own children, but not the stops inside the root or which of those children a slot takes. A child that no slot takes isn't rendered and can't take focus, so the trap passes over it when it moves focus, as it does any stop the browser refuses. At an end of the trap it's a refused stop like any other, so keep a closed-root host away from the trap's edges, or give it no children that a slot doesn't take.\n- A scrollable region with nothing focusable inside is a stop in some browsers and not in others. Give it `tabIndex={0}` so it is one everywhere, which also lets keyboard users scroll it.\n\n### What the trap takes on trust\n\n- A browser can visit an image map's areas where the `<map>` sits or where its image is. The trap takes them where the map is, so keep the map right after its image, where the two agree.\n- A positive `tabIndex` changes the order the browser's Tab visits, but not the trap's ends, which stay the first and last stops in document order. Where the two disagree, a Tab past the browser's end is let through and then sent to the trap's end instead, which can be the very element it left, so focus seems stuck. Keep positive `tabIndex` out of a trap.\n- The trap listens for Tab on the container. Content inside that stops a Tab keydown from propagating keeps it from the trap, so that Tab isn't wrapped, and focus it takes out isn't sent back.\n\n### Nested traps\n\nThe trap listens for Tab on its container, so a trap inside another one handles Tab first and the outer trap stands aside. A panel that opens a second panel inside it keeps focus in the inner one.\n\n---\n\n## API\n\n```ts\nfunction useFocusTrap(\n  containerRef: RefObject<HTMLElement | null>,\n  options?: UseFocusTrapOptions\n): void;\n\ninterface UseFocusTrapOptions {\n  active?: boolean;\n  initialFocusRef?: RefObject<HTMLElement | null>;\n  restoreFocus?: boolean | RefObject<HTMLElement | null>;\n}\n```\n\n### Parameters\n\n| Parameter                 | Type                                          | Default | Description                                                                                                                                             |\n| ------------------------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `containerRef`            | `RefObject<HTMLElement \\| null>`              | —       | The element focus stays inside.                                                                                                                         |\n| `options.active`          | `boolean`                                     | `true`  | Whether the trap is on. Turning it on moves focus in; turning it off (or unmounting) releases Tab and restores focus.                                   |\n| `options.initialFocusRef` | `RefObject<HTMLElement \\| null>`              | —       | An element inside the container that can take focus, focused when the trap turns on; otherwise the first tab stop that takes focus, then the container. |\n| `options.restoreFocus`    | `boolean` \\| `RefObject<HTMLElement \\| null>` | `true`  | Where focus goes when the trap turns off: `true` for the element focused when it turned on, a ref for that element, `false` to leave focus alone.       |\n\nIt returns nothing. On the server it does nothing, and the container renders as written.\n\n---\n\n## Accessibility\n\n- Trap focus in content that asks for the reader's attention until it is dismissed: a dialog, a command palette, a panel with its own controls. Content a reader should be able to Tab past, such as a tooltip or a disclosure, shouldn't be trapped.\n- Pair the trap with a way out. The trap handles Tab only, so wire Escape (and any close button) to turn it off.\n- Give the container a role and an accessible name (`role=\"dialog\"` with `aria-label` or `aria-labelledby`), and give the button that opens it `aria-haspopup`, `aria-expanded` and `aria-controls`.\n- Return focus to the element that opened the content when it closes. The default does, and a ref to the trigger makes it reliable.\n- The trap is for the keyboard. It doesn't hide the rest of the page from screen readers or pointers, and it doesn't pull focus back from a click; for fully modal content, use [`Modal`](https://bestax.io/docs/api/components/modal), which sets `aria-modal`.\n\n---\n\n## Related Components\n\n- [`Modal`](https://bestax.io/docs/api/components/modal): A modal overlay with its own focus management.\n- [`Dialog`](https://bestax.io/docs/api/components/dialog): Ready-made confirm and alert dialogs.\n\n---\n\n## Additional Resources\n\n- [Storybook: useFocusTrap Stories](https://bestax.io/storybook/?path=/story/helpers-usefocustrap--default)\n- [WAI-ARIA Authoring Practices: Dialog (Modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)",
   "parts": [],
   "cssVars": []
 }

package/data/skills/bestax-layout-scaffold/SKILL.md

@@ -110,8 +110,18 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   other: `<TreeView aria-label="Files" selectionMode="single">` with `selected`/`onSelectedChange`
   picks one, and `selectionMode="checkbox"` with `checked`/`onCheckedChange` draws boxes with
   mixed parents, where a parent's value checks its whole branch. Map the data with a recursive
-  function, and render an item's children whether it's open or not. Its items aren't links, so
-  the app's sidebar and any list of pages stay on `Menu` with `Menu.Item href`.
+  function, and render an item's children whether it's open or not. A folder that loads when it
+  opens takes `hasChildren`, `isLoading` while its children are on their way, and
+  `loadError="Couldn't load src"` with `onRetry` when the load fails, setting `isLoading` again
+  while the retry runs: the tree draws the Loading… and Retry rows and announces them, so don't
+  hand-write a placeholder item. Its items aren't
+  links, so the app's sidebar and any list of pages stay on `Menu` with `Menu.Item href`.
+- **A sidebar whose groups of links open and close is `Menu.Section`**, one per group, directly
+  in `Menu` (never inside a `Menu.Item` or `Menu.List`):
+  `<Menu.Section label="Components" defaultOpen>` around that group's `Menu.List`, with
+  `defaultOpen` on the group holding the current page (or `open`/`onOpenChange` to hold the state).
+  Its heading is a real button with `aria-expanded`, and its links stay links, each a tab stop.
+  Not `TreeView`, and not a `Collapse` inside a hand-written `<li>`.
 - Link lists (footer nav, sidebars): a bare `UnorderedList` of `ListItem`s is already
   marker-less and flush — Bulma's reset unstyles `ul` — so no prop or CSS is needed;
   bullets appear only inside `Content`.

package/data/skills/bestax-layout-scaffold/references/layout-components.md

@@ -267,11 +267,13 @@ https://bestax.io/docs/guides/features/routing.
 
 ## Menu
 
-`<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`.
+`<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`,
+`Menu.Section`.
 
-| Prop        | Type                                                                                                                                                                                |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Menu.Item` | `active?` (the current page: `is-active` plus `aria-current="page"`, so don't add your own), `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus |
+| Prop           | Type                                                                                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Menu.Item`    | `active?` (the current page: `is-active` plus `aria-current="page"`, so don't add your own), `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus                                             |
+| `Menu.Section` | `label` (the heading, a `ReactNode`), `defaultOpen?`, or `open?` with `onOpenChange?(open)` to hold the state yourself, as `Collapse` does; its child is the group's `Menu.List`, and a closed section's links are out of reach |
 
 ```tsx
 <Menu>
@@ -285,6 +287,34 @@ https://bestax.io/docs/guides/features/routing.
 </Menu>
 ```
 
+A sidebar whose groups of links open and close (a docs sidebar, an admin app's sections) puts each
+group's `Menu.List` in a `Menu.Section`. Its heading is a real button drawn like `Menu.Label`, with
+`aria-expanded` and a chevron, and its links stay ordinary links, each a tab stop. Open the
+section that holds the current page. A section goes directly in `Menu`, never inside a `Menu.Item`
+(it would render inside the item's link) or a `Menu.List` (it isn't a list item). Don't build this
+from `TreeView` (its items aren't links) or from a `Collapse` in a hand-written `<li>` (its trigger
+is a `div` with `role="button"`).
+
+```tsx
+<nav aria-label="Documentation">
+  <Menu>
+    <Menu.Section label="Getting started">
+      <Menu.List>
+        <Menu.Item href="/docs/install">Installation</Menu.Item>
+      </Menu.List>
+    </Menu.Section>
+    <Menu.Section label="Components" defaultOpen>
+      <Menu.List>
+        <Menu.Item href="/docs/button" active>
+          Button
+        </Menu.Item>
+        <Menu.Item href="/docs/card">Card</Menu.Item>
+      </Menu.List>
+    </Menu.Section>
+  </Menu>
+</nav>
+```
+
 ## Card
 
 `<Card>` for catalog/grid items. Use the props form (`header`, `image`, `footer`) or the compound

package/data/skills/bestax-migrate/references/bulma-classes/component-map.md

@@ -272,7 +272,8 @@ go straight inside `Breadcrumb`, and `<figure className="image is-64x64"><img sr
   one, so the `<ul>` carries nothing and the `.breadcrumb` needs an `aria-label` of its own.
 - `Image` renders its `<img>` from `src` and `alt`, so the `<img>` carries nothing else, and
   `is-rounded` on it becomes `isRounded`. The `.image` keeps its own attributes. A ratio
-  (`is-4by3`) stays a class, since `size` would add `has-ratio` as well. Around anything else (an
+  (`is-4by3`) becomes `size` too. `Image` renders a ratio on a `<figure>`, so a `<figure>` needs no
+  `as` there and a `<div>` keeps `as="div"`. Around anything else (an
   `<img>` with more attributes, an `<iframe>`), `Image` renders its children as given, so the
   `.image` converts around them and they stay as written, as long as they're HTML elements written
   out. An empty `.image` stays markup, since `Image` would render an `<img>` of its own, and so does

package/data/skills/bestax-migrate/references/bulma-classes/prop-map.md

@@ -103,7 +103,8 @@ renders the same `<h2>`.
 | the `<select>` inside `.select`                                              | `is-hovered`, `is-focused`                                                                                                                       | `isHovered`, `isFocused`                                                                          |
 | `.hero` → `Hero`                                                             | `is-primary`, `is-link`, `is-info`, `is-success`, `is-warning`, `is-danger`, `is-black`, `is-white`, `is-light`, `is-dark`                       | `color`                                                                                           |
 | `.hero` → `Hero`                                                             | `is-small`, `is-medium`, `is-large`, `is-fullheight`, `is-fullheight-with-navbar`                                                                | `size`                                                                                            |
-| `.image` → `Image`                                                           | `is-16x16`, `is-24x24`, `is-32x32`, `is-48x48`, `is-64x64`, `is-96x96`, `is-128x128`, `is-square`                                                | `size` (a ratio such as `is-4by3` stays a class, since `size` would add `has-ratio`)              |
+| `.image` → `Image`                                                           | `is-16x16`, `is-24x24`, `is-32x32`, `is-48x48`, `is-64x64`, `is-96x96`, `is-128x128`, `is-square`                                                | `size`                                                                                            |
+| `.image` → `Image`                                                           | `is-{ratio}`, for each of the Ratios under Helper classes (`is-16by9`), but not `is-square` (see below)                                          | `size`, on the `<figure>` it renders with no `as` (see below)                                     |
 | the `<img>` inside `.image`                                                  | `is-rounded`                                                                                                                                     | `isRounded`                                                                                       |
 | `.icon` → `Icon`                                                             | `is-small`, `is-medium`, `is-large`                                                                                                              | `size`                                                                                            |
 | `.tabs` → `Tabs`                                                             | `is-centered`, `is-right`, `is-left`                                                                                                             | `align`                                                                                           |
@@ -130,6 +131,16 @@ renders the same `<h2>`.
 | `.tag` → `Tag`                                                               | `is-light`, `is-rounded`, `is-hoverable`                                                                                                         | `isLight`, `isRounded`, `isHoverable`                                                             |
 | `.tag` → `Tag`                                                               | `is-medium`, `is-large`                                                                                                                          | `size`                                                                                            |
 
+`is-square` sits with the fixed sizes, not the ratios. Bulma sizes it like `is-1by1`, but `Image`
+renders `size="square"` on a `<div>`, as it does a fixed size. So
+`<figure className="image is-square">` becomes `<Image as="figure" size="square">`, while
+`<figure className="image is-1by1">` becomes `<Image size="1by1">`.
+
+A ratio converts to identical markup only on a bestax-bulma whose `Image` writes nothing but the
+ratio class on its container. An older one also writes `has-ratio` there, which Bulma reads only
+on a child, so the page looks the same, unless that `.image` sits inside another ratio `.image`,
+which then stretches it to fill. Upgrade bestax-bulma, or keep that ratio as a class.
+
 `Progress` takes `value` and `max` as numbers: `value="40"` becomes `value={40}`. An
 expression (`value={percent}`) carries over as written, so if it holds a string the migrated
 file fails to typecheck while still rendering the same; wrap it in `Number(…)`. `Delete`
@@ -232,8 +243,8 @@ Some classes stay put because of how bestax renders them:
 ## Classes that stay classes
 
 Color shades (`has-text-primary-65`), the `-touch` and `-only` breakpoints of text size and
-alignment, Grid and `.image` modifiers away from their own element, an `.image` ratio, v1's
-`marginless` and `paddingless` (the rules of `m-0` and `p-0` under other names), and the Bulma
-helpers bestax has no prop for (`is-display-*`, `is-visibility-*`, `is-float-*`, `is-clear-*`,
-…) stay in `className`. They render exactly as before. An `.image` size or ratio away from its
-`.image` also gets a `modifier:image` TODO, since Bulma styles it only there.
+alignment, Grid and `.image` modifiers away from their own element, v1's `marginless` and
+`paddingless` (the rules of `m-0` and `p-0` under other names), and the Bulma helpers bestax has
+no prop for (`is-display-*`, `is-visibility-*`, `is-float-*`, `is-clear-*`, …) stay in
+`className`. They render exactly as before. An `.image` size or ratio away from its `.image` also
+gets a `modifier:image` TODO, since Bulma styles it only there.

package/data/skills/bestax-migrate/references/bulma-classes/unmappables.md

@@ -400,7 +400,8 @@ Run on an HTML page (`bestax-migrate bulma-classes page.html`, or a folder with
 codemod writes a module beside the page and runs everything above on it, so a page gets the same
 TODOs its markup would as JSX. What a component can't carry gets an `html-*` rule. TODOs about the
 whole page sit above the component, the rest above its `return`, and each ends with the page and
-the line it came from (`(index.html:42)`). The page itself stays as it was, so the code a TODO
+the line it came from (`(index.html:42)`), or every line, for a TODO several elements share
+(`(index.html:42, 57)`). The page itself stays as it was, so the code a TODO
 points at is still there to read. A rule names only a tag, an attribute or a fixed word, never
 anything the page says.
 
@@ -414,6 +415,11 @@ A component renders into the `<body>` of the app's own document, so nothing in t
   it into the head; React 18 leaves it in the body, so use `document.title` in an effect there.
 - **`html-head:meta`**: `charset` and `viewport` go once in the app's `index.html`. A page's own
   (a description, Open Graph tags) go where the app sets each page's head.
+- **`html-head:csp`**: a `<meta http-equiv="Content-Security-Policy">`. Its policy was written for
+  what the page loads, and copied into `index.html` as it is, it can block what the app loads
+  instead: a Vite dev server runs an inline script for React's fast refresh and opens a socket for
+  hot reloading, and the build serves the app's own scripts, styles and fonts. Write the app's own
+  policy, best sent as a response header, and try it under both the dev server and the build.
 - **`html-head:link`**: icons, preconnects and preloads are app-wide, so keep them in
   `index.html`; a `canonical` is per page.
 - **`html-head:style`**: the `<style>` block was dropped. Move its rules into the app's stylesheet.
@@ -586,7 +592,9 @@ read for the burger, a carousel and a theme toggle too, and its TODO names the f
   app loads paints the right one, and the toggle's state starts from what it wrote. The
   bestax-theming skill covers `Theme` and `colorMode`, and its `examples/dark-mode.tsx` has the
   script and the app's side.
-- **`html-script:json-ld`** is structured data for search engines. Render it where the app sets
+- **`html-script:json-ld`** is structured data for search engines. Data about the whole site, or
+  about a single-page app's one page, goes in the app's `index.html` as it is, where a crawler that
+  runs no JavaScript still reads it. Data that differs from page to page goes where the app sets
   each page's head, as
   `<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />`.
 - **`html-script`**: any other inline script, or a `<script type>` that isn't code (a template,
@@ -604,8 +612,9 @@ The app's document has its own `<html>` and `<body>`, which a component can't re
   bestax's `Navbar` adds none there, whatever its `fixed` says.
 - **`html-document:data-theme`**, **`html-document:theme-dark`**, **`html-document:theme-light`**:
   the page's color scheme. Put it on the `<html>` in `index.html`, where the first paint has it.
-  `<Theme colorMode="dark">` writes `data-theme` on `<html>` too, but from an effect, after a
-  first frame in the visitor's OS scheme, so keep it for a scheme the visitor switches.
+  For a scheme the visitor switches, `Theme colorMode` writes the choice only after that paint,
+  so write a saved one before it too, as `html-script:theme` says and the bestax-theming skill's
+  `examples/dark-mode.tsx` does.
 - **`html-document:lang`**, **`html-document:dir`**: set them on the `<html>` in `index.html`.
 - **`html-document:class`**: the page's own classes on `<html>` or `<body>`. Put them on the
   app's own `<body>` (or `<html>`), or on an element around the page's content if the styles
@@ -656,6 +665,12 @@ than `this`. A `<body onload>` becomes an effect.
 - **`html-attr:name`**: an attribute JSX can't write (`@click`, `:class`, `x-on:click`), or one the
   element already had under another spelling, was left out. A framework's directive is code to port
   into the component.
+- **`html-attr:stray`**: a stray character in a tag, with no letter or digit in it (`\` in
+  `<figure class="image" \>`, a typo for `/>`), which the browser read as the name of an empty
+  attribute. It was left out, so there is nothing to port; delete it from the page too.
+- **`html-attr:ignored`**: an attribute HTML gives the element no meaning for, so the browser
+  ignored it, and React's types reject it there: `type` on a `<textarea>`. It was left out, so the
+  module typechecks. Nothing reads it, unless a stylesheet or script of the page's selects on it.
 - **`html-attr:unknown`**: an attribute React has no prop for by that name, written as it was.
   React renders it. Whether a TypeScript build takes it depends on the element (React's types
   list `valign` on a `<td>` and not on a `<th>`), so the TODO doesn't say; what to do depends on

package/data/skills/bestax-optimize/references/modular-build.md

@@ -107,8 +107,9 @@ Notes:
   @use '@allxsmith/bestax-bulma/scss/components/tabs' as bestax-tabs;
   ```
 
-- The `menu` partial **extends** stock Bulma menu (it keeps the active item marked in forced
-  colors, Windows' contrast themes), so an app using `Menu` needs both, in either order:
+- The `menu` partial **extends** stock Bulma menu (it draws `Menu.Section`'s heading and chevron,
+  and keeps the active item marked in forced colors, Windows' contrast themes), so an app using
+  `Menu` needs both, in either order:
 
   ```scss
   @use 'bulma/sass/components/menu';

package/data/skills/bestax-theming/references/css-variables.md

@@ -462,6 +462,17 @@ Declared on the compound `.button.link-button` — see the compound-selector exc
 `--bulma-loading-overlay-opacity-opaque`, `--bulma-loading-text-color`,
 `--bulma-loading-text-size`
 
+### Menu
+
+`Menu.Section`'s, declared on the root, `.menu`, where Bulma declares its own `--bulma-menu-*`:
+the room between a section heading's words and its chevron, and the chevron's box, color and
+turn. The heading itself reads Bulma's label variables (`--bulma-menu-label-color`,
+`--bulma-menu-label-font-size`, `--bulma-menu-label-letter-spacing`,
+`--bulma-menu-label-spacing`), so retheming the menu's labels restyles section headings too.
+
+`--bulma-menu-section-chevron-color`, `--bulma-menu-section-chevron-duration`,
+`--bulma-menu-section-chevron-size`, `--bulma-menu-section-gap`
+
 ### Notification
 
 `--bulma-notification-delete-padding-inline-end` is the end padding of a notification with a close

package/data/skills.json

@@ -64,7 +64,7 @@
         {
           "id": "layout-components",
           "file": "references/layout-components.md",
-          "bytes": 17448
+          "bytes": 18956
         }
       ],
       "examples": [
@@ -103,17 +103,17 @@
         {
           "id": "bulma-classes-component-map",
           "file": "references/bulma-classes/component-map.md",
-          "bytes": 29661
+          "bytes": 29733
         },
         {
           "id": "bulma-classes-prop-map",
           "file": "references/bulma-classes/prop-map.md",
-          "bytes": 36213
+          "bytes": 37225
         },
         {
           "id": "bulma-classes-unmappables",
           "file": "references/bulma-classes/unmappables.md",
-          "bytes": 49495
+          "bytes": 50861
         },
         {
           "id": "css-migration",
@@ -162,7 +162,7 @@
         {
           "id": "modular-build",
           "file": "references/modular-build.md",
-          "bytes": 12025
+          "bytes": 12075
         }
       ],
       "examples": []
@@ -176,7 +176,7 @@
         {
           "id": "css-variables",
           "file": "references/css-variables.md",
-          "bytes": 44975
+          "bytes": 45565
         },
         {
           "id": "themeable-components",

package/dist/bulma-classes.d.ts

@@ -34,6 +34,12 @@ export interface Modifier {
         name: string;
         value: string;
     };
+    /**
+     * The tag the component renders with this class's prop and no `as`, in
+     * place of the root's own (`Image` puts a ratio on a <figure>). Only one
+     * such class converts on an element.
+     */
+    rendersTag?: string;
 }
 export interface RootRecord {
     status: 'mapped' | 'todo' | 'plain' | 'fold';

package/dist/bulma-classes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bulma-classes.d.ts","sourceRoot":"","sources":["../src/bulma-classes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAC7C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,EAAE,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACpC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;OAGG;IACH,aAAa,EAAE,KAAK,GAAG,IAAI,CAAC;IAC5B,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC1B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,6DAA6D;IAC7D,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,gFAAgF;IAChF,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,mEAAmE;IACnE,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/B,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mEAAmE;IACnE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,KAAK;IACpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACpC,sEAAsE;IACtE,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,OAAO;IACtB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,4CAA4C;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,OAAO;AACjB,6CAA6C;AAC3C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACvC,oDAAoD;GAClD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE;AAC3D,wEAAwE;GACtE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,MAAM,MAAM,OAAO,GACf;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kEAAkE;IAClE,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AACH,4CAA4C;GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AACjC,kEAAkE;GAChE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE;AACvD,uEAAuE;GACrE;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpB,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC7C;AAuGD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAYnD;AAkDD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CA0YR;AA0BD;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExC;AAsID,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAM,GACxD,MAAM,CA2IR"}
+{"version":3,"file":"bulma-classes.d.ts","sourceRoot":"","sources":["../src/bulma-classes.ts"],"names":[],"mappings":"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"}

package/dist/bulma-classes.js

@@ -112,9 +112,16 @@ function listTags(tags) {
         ? `${named.slice(0, -1).join(', ')} or ${named[named.length - 1]}`
         : named[0];
 }
-function reaches(entry) {
+function reaches(entry, retagged) {
+    // The tag it renders with no `as`: the one a class picks, else its own.
+    const plain = retagged
+        ? `<${retagged}> with these classes`
+        : `<${entry.tag}>`;
     if (entry.as === 'any')
-        return `<${entry.tag}>, or any tag through \`as\``;
+        return `${plain}, or any tag through \`as\``;
+    if (retagged && entry.as) {
+        return `${plain}, or ${listTags(entry.as)} through \`as\``;
+    }
     if (entry.sizeDrivesTag && entry.as) {
         return `the heading its \`size\` names (<${entry.tag}> with none), or ${listTags(entry.as)} through \`as\``;
     }
@@ -300,6 +307,8 @@ export function lookupClasses(table, input, tag) {
         write.prop,
         { value: write.value ?? true, token: root ?? '' },
     ]));
+    /** The one class that picks the component's tag, as the codemod takes it. */
+    let retaggedBy;
     const claiming = [
         ...tokens.filter(token => !own(table.replaced, token)),
         ...tokens.filter(token => own(table.replaced, token)),
@@ -320,9 +329,16 @@ export function lookupClasses(table, input, tag) {
                 stays(token, `\`${taken.prop}\` is already set by \`${writes.get(taken.prop).token}\``);
                 continue;
             }
+            // Only one class picks the tag, as only one sets a prop.
+            if (modifier.rendersTag && retaggedBy) {
+                stays(token, `\`${retaggedBy}\` already picks the tag`);
+                continue;
+            }
             for (const write of modifier.writes) {
                 writes.set(write.prop, { value: write.value ?? true, token });
             }
+            if (modifier.rendersTag)
+                retaggedBy = token;
             // A class the component renders from an attribute of the element
             // inside (`is-multiple` beside a `<select multiple>`).
             const paired = Object.entries(entry.absorbs?.pairs ?? {}).find(([, pairedToken]) => pairedToken === token)?.[0];
@@ -451,15 +467,26 @@ export function lookupClasses(table, input, tag) {
         });
     }
     const size = writes.get('size')?.value;
-    const renders = entry.sizeDrivesTag && tag !== 'p' && typeof size === 'string'
-        ? `h${size}`
-        : entry.tag;
+    // A class whose prop puts the component on another tag when no `as` is
+    // given (`Image`'s ratios on a <figure>).
+    const retagged = retaggedBy
+        ? own(entry.modifiers, retaggedBy)?.rendersTag
+        : undefined;
+    const renders = retagged ??
+        (entry.sizeDrivesTag && tag !== 'p' && typeof size === 'string'
+            ? `h${size}`
+            : entry.tag);
     const reachable = !tag ||
         renders === tag ||
         entry.as === 'any' ||
         (Array.isArray(entry.as) && entry.as.includes(tag));
     if (!reachable) {
-        return result({ kind: 'wrong-tag', target, tag, reaches: reaches(entry) });
+        return result({
+            kind: 'wrong-tag',
+            target,
+            tag,
+            reaches: reaches(entry, retagged),
+        });
     }
     // A `className` it's given replaces its own class, so a class left over
     // keeps the element as markup.
@@ -488,7 +515,7 @@ export function lookupClasses(table, input, tag) {
         return result({
             kind: 'component',
             target,
-            renders: reaches(entry),
+            renders: reaches(entry, retagged),
             ...about,
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bestax-mcp",
-  "version": "1.16.2",
+  "version": "1.16.4",
   "mcpName": "io.github.allxsmith/bestax-mcp",
   "description": "MCP server for @allxsmith/bestax-bulma — component props, examples, CSS variables and agent skills, served offline from a version-pinned index",
   "type": "module",
@@ -42,7 +42,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
     "zod": "^4.4.3",
-    "@allxsmith/bestax-bulma": "^5.39.1"
+    "@allxsmith/bestax-bulma": "^5.41.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",