create-bestax 4.2.11 → 4.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.2.11",
+  "version": "4.2.13",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -39,7 +39,9 @@
     "figures": "^6.1.0",
     "fs-extra": "^11.4.0",
     "prompts": "^2.4.2",
-    "@allxsmith/bestax-bulma": "^5.16.9"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@allxsmith/bestax-bulma": "^5.27.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
@@ -50,6 +52,7 @@
     "@types/prompts": "^2.4.9",
     "@types/wait-on": "^5.3.4",
     "jest": "^30.2.0",
+    "semver": "^7.8.5",
     "ts-jest": "^29.4.12",
     "typescript": "^6.0.3",
     "wait-on": "^9.1.0"
@@ -75,5 +78,5 @@
     "clean": "rimraf dist",
     "release": "npx semantic-release"
   },
-  "readme": "# create-bestax\n\n[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/create-bestax/latest)](https://socket.dev/npm/package/create-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nThe scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.\n\nPart of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.\n\n## Requirements\n\n- **Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the\n  CLI exits immediately with an explicit upgrade message.\n- npm 10 or newer (ships with Node 22), or yarn/pnpm.\n\n## Usage\n\n### Quick Start\n\n```bash\n# Using npm\nnpm create bestax@latest my-app\n\n# Using npx\nnpx create-bestax@latest my-app\n\n# Alternative naming\nnpm create bestax-bulma@latest my-app\n```\n\n### Interactive Mode\n\nRunning without arguments will prompt you for all options:\n\n```bash\nnpm create bestax@latest\n```\n\nYou'll be asked to:\n\n1. Enter a project name\n2. Select a framework (Vite or Vite + TypeScript)\n3. Choose a Bulma CSS flavor (Complete or Minimal)\n4. Select an icon library (Font Awesome, Material Icons, etc.)\n5. Choose whether to install the bestax AI skills into `.claude/skills/`\n\nEvery prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.\n\n### Command Line Options\n\n```bash\nnpm create bestax@latest [project-directory] [options]\n```\n\n**Arguments:**\n\n- `[project-directory]` - Optional project directory name\n\n**Options:**\n\n- `-t, --template <template>` - Template to use: `vite` or `vite-ts`  \n  **Default:** `vite`\n- `-b, --bulma <flavor>` - Bulma CSS flavor:\n  - `complete` - Full Bulma CSS with all components and helpers\n  - `prefixed` - Prefixed version for compatibility\n  - `no-helpers` - Without helper classes\n  - `no-helpers-prefixed` - Prefixed without helpers\n  - `no-dark-mode` - Without dark mode support  \n    **Default:** `complete`\n- `-i, --icon <library>` - Icon library:\n  - `none` - No icon library\n  - `fontawesome` - Font Awesome\n  - `mdi` - Material Design Icons\n  - `ionicons` - Ionicons\n  - `material-icons` - Material Icons\n  - `material-symbols` - Material Symbols  \n    **Default:** `none`\n- `--skills` / `--no-skills` - Install (or skip) the bestax AI skills into\n  `.claude/skills/` (with a `CLAUDE.md`) so a Claude Code session picks them up\n  automatically. When omitted you're prompted; with `-y` the default is to install.\n- `-y, --yes` - Skip prompts and use defaults or provided options.  \n  When used, the following defaults are selected unless overridden by flags:\n  - Template: `vite`\n  - Bulma flavor: `complete`\n  - Icon library: `none`\n  - AI skills: installed (pass `--no-skills` to opt out)\n\n**Example:**\n\n```bash\n# Create a TypeScript project with Font Awesome icons\nnpm create bestax@latest my-app -t vite-ts -i fontawesome -b complete\n\n# Use all defaults (skip prompts)\nnpm create bestax@latest my-app -y\n```\n\n## Templates\n\nAvailable templates:\n\n- `vite` - Vite + JavaScript\n- `vite-ts` - Vite + TypeScript\n\nEach template includes:\n\n- Pre-configured bestax-bulma integration (React 19)\n- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically\n- Icon library support (Font Awesome, Material Design, etc.)\n- Sample components demonstrating library usage\n- Development and build scripts\n\n## For AI Tools\n\nScaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax\nAgent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot\nbuild the bestax way from the start. The library also ships LLM-optimized docs:\n\n- [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot\n- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions\n- [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)\n\n## Development\n\n```bash\nnpm run build    # Build the CLI\nnpm run dev      # Watch mode\nnpm test         # Run tests\nnpm run lint     # Lint CLI source code\nnpm run typecheck # Type check CLI source code\n```\n\n**Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing.\n\n## Hardened by default\n\nA scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI.\n- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`create-bestax` can send one **anonymous** usage event after a successful\nscaffold — only if you opt in when asked (once, at the end of a scaffold). The\nevent is just the choices you made — template, Bulma flavor, icon library,\nskills, package manager — plus the CLI version, Node major version, and OS\nplatform; never names, IPs, machine IDs, paths, or file contents, and no\nidentifier exists that could link two events together. Opt out any time with\n`--no-telemetry`, `BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## Publishing\n\nThis package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.\n"
+  "readme": "# create-bestax\n\n[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/create-bestax/latest)](https://socket.dev/npm/package/create-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nThe scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.\n\nPart of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.\n\n## Requirements\n\n- **Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the\n  CLI exits immediately with an explicit upgrade message.\n- npm 10 or newer (ships with Node 22), or yarn/pnpm.\n\n## Usage\n\n### Quick Start\n\n```bash\n# Using npm\nnpm create bestax@latest my-app\n\n# Using npx\nnpx create-bestax@latest my-app\n\n# Alternative naming\nnpm create bestax-bulma@latest my-app\n```\n\n### Interactive Mode\n\nRunning without arguments will prompt you for all options:\n\n```bash\nnpm create bestax@latest\n```\n\nYou'll be asked to:\n\n1. Enter a project name (and, if that directory already holds files, confirm removing them;\n   nothing is removed until you have answered the last question)\n2. Select a framework (Vite or Vite + TypeScript)\n3. Choose a Bulma CSS flavor (Complete or Minimal)\n4. Select an icon library (Font Awesome, Material Icons, etc.)\n5. Choose whether to install the bestax AI skills into `.claude/skills/`\n\nEvery prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.\n\n### Command Line Options\n\n```bash\nnpm create bestax@latest [project-directory] [options]\n```\n\n**Arguments:**\n\n- `[project-directory]` - Optional project directory name. It also becomes the `package.json`\n  name, lower-cased the way `npm init` does and without a leading `_`, since npm rejects both.\n\n**Options:**\n\n- `-t, --template <template>` - Template to use: `vite` or `vite-ts`  \n  **Default:** `vite`\n- `-b, --bulma <flavor>` - Bulma CSS flavor:\n  - `complete` - Full Bulma CSS with all components and helpers\n  - `prefixed` - Prefixed version for compatibility\n  - `no-helpers` - Without helper classes\n  - `no-helpers-prefixed` - Prefixed without helpers\n  - `no-dark-mode` - Without dark mode support  \n    **Default:** `complete`\n- `-i, --icon <library>` - Icon library:\n  - `none` - No icon library\n  - `fontawesome` - Font Awesome\n  - `mdi` - Material Design Icons\n  - `ionicons` - Ionicons\n  - `material-icons` - Material Icons\n  - `material-symbols` - Material Symbols  \n    **Default:** `none`\n- `--skills` / `--no-skills` - Install (or skip) the bestax AI skills into\n  `.claude/skills/` (with a `CLAUDE.md`) so a Claude Code session picks them up\n  automatically. When omitted you're prompted; with `-y` the default is to install.\n- `-y, --yes` - Skip prompts and use defaults or provided options.  \n  When used, the following defaults are selected unless overridden by flags:\n  - Template: `vite`\n  - Bulma flavor: `complete`\n  - Icon library: `none`\n  - AI skills: installed (pass `--no-skills` to opt out)\n\n  `-y` never deletes files. If the target directory is not empty, the run stops, lists what is\n  there, and changes nothing; add `--overwrite` to empty it first. Earlier versions emptied the\n  directory under `-y` alone, so a script that relied on that now needs `--overwrite`.\n\n- `--overwrite` - Remove existing files if the target directory is not empty, without asking.\n  Every other flag is checked first, so a typo stops the run before anything is deleted.\n\n**Example:**\n\n```bash\n# Create a TypeScript project with Font Awesome icons\nnpm create bestax@latest my-app -t vite-ts -i fontawesome -b complete\n\n# Use all defaults (skip prompts)\nnpm create bestax@latest my-app -y\n```\n\n## Templates\n\nAvailable templates:\n\n- `vite` - Vite + JavaScript\n- `vite-ts` - Vite + TypeScript\n\nEach template includes:\n\n- Pre-configured bestax-bulma integration (React 19)\n- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically\n- Icon library support (Font Awesome, Material Design, etc.)\n- Sample components demonstrating library usage\n- Development and build scripts\n\n## For AI Tools\n\nScaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax\nAgent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot\nbuild the bestax way from the start. The library also ships LLM-optimized docs:\n\n- [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot\n- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions\n- [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)\n\n## Development\n\n```bash\nnpm run build    # Build the CLI\nnpm run dev      # Watch mode\nnpm test         # Run tests\nnpm run lint     # Lint CLI source code\nnpm run typecheck # Type check CLI source code\n```\n\n**Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing.\n\n## Hardened by default\n\nA scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI.\n- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`create-bestax` can send one **anonymous** usage event after a successful\nscaffold — only if you opt in when asked (once, at the end of a scaffold). The\nevent is just the choices you made — template, Bulma flavor, icon library,\nskills, package manager — plus the CLI version, Node major version, and OS\nplatform; never names, IPs, machine IDs, paths, or file contents, and no\nidentifier exists that could link two events together. Opt out any time with\n`--no-telemetry`, `BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## Publishing\n\nThis package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.\n"
 }

package/templates/skills/bestax-custom-component/SKILL.md

@@ -58,6 +58,24 @@ so put helper props on the parent or on an element inside them, never invent the
 (`Card.*` sub-parts do take helper props, like `Table.*`/`Menu.*`/`Hero.*`.) Most "custom components" are a composition function — zero new styles.
 See `examples/stat-card.tsx` for a complete worked example.
 
+Rendering something only the browser knows (the reader's time zone, a `localStorage` value)?
+Wrap it in the library's `ClientOnly` rather than checking `typeof window`: it renders a fallback
+until the page has hydrated, so the server and client markup match. `references/api.md` has the
+details.
+
+A panel opened from a button (a filter form, share options, an inline edit) is `Popover`: use
+it rather than building one. It anchors the panel, moves focus in and back, and closes on
+Escape and outside presses.
+
+Building something else that floats (a command palette)? Render it through the library's
+`Portal` rather than `createPortal`: it renders nothing on the server and during hydration, so
+the server and client markup match. `references/api.md` has the details.
+
+Building some other overlay that holds focus until it is dismissed (a command palette)? Use the
+library's `useFocusTrap` rather than a hand-rolled Tab handler: it finds the tab stops the
+browser visits and hands focus back on close. `references/api.md` has the signature and a worked
+panel.
+
 ## The component spine
 
 Same shape the library itself uses, with all imports from the package. Every reusable
@@ -112,10 +130,8 @@ free. `references/api.md` documents the helpers.
 ## Styling ladder — use the lowest rung that works
 
 **Rung 1 — helper props only (default).** House rules: never `style={{}}`. Layout with
-`Block`/`Box` and `display="flex"`, `flexDirection`, `alignItems`, `justifyContent`. Flex
-layouts have **no `gap` helper** — space children with `m*`/`p*` margins instead (`Grid` and
-`Columns` take a `gap` prop). Before writing `style={{ … }}` anywhere, translate each
-declaration:
+`Block`/`Box` and `display="flex"`, `flexDirection`, `alignItems`, `justifyContent`, and space
+the children with `gap`. Before writing `style={{ … }}` anywhere, translate each declaration:
 
 | Inline style you're about to write       | Helper props instead                                                                                                                                           |
 | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -129,6 +145,7 @@ declaration:
 | `display: 'flex'` + flex properties      | same-named props: `display="flex"`, `flexDirection`, `justifyContent`, `alignItems`, `flexWrap`                                                                |
 | `height: '100%'` on a flex child         | `flexGrow="1"`                                                                                                                                                 |
 | `display: 'none'`                        | `visibility="hidden"`, or responsive `display*` props (`displayMobile`, `displayTablet`, …)                                                                    |
+| `gap: '1rem'` (flex or grid)             | `gap="2"`, or one axis: `columnGap`, `rowGap`; gap scale: `1`=0.5rem, `2`=1rem, `4`=2rem, half steps (`"1.5"`)                                                 |
 
 Spacing, typography, and flex helpers are on every component; `textColor`/`bgColor` are on
 the content components you'll compose with (`Box`, `Block`, `Title`, `Content`, `Card`, …) —

package/templates/skills/bestax-custom-component/examples/stat-card.tsx

@@ -55,6 +55,7 @@ export function StatCard({
       // Rung 1: layout entirely with helper props — no style={{}}, no CSS.
       display="flex"
       alignItems="center"
+      gap="2"
       p="4"
       {...rest}
     >
@@ -63,7 +64,6 @@ export function StatCard({
           name={icon}
           size="large"
           textColor={color}
-          mr="4"
           // Decorative: the label below already says it, so hide it from AT —
           // Icon otherwise emits its default aria-label="icon". (To *label* an
           // icon, use Icon's own camelCase `ariaLabel`; most components take
@@ -71,7 +71,6 @@ export function StatCard({
           aria-hidden="true"
         />
       )}
-      {/* No `gap` helper exists — space siblings with margin props (mr above). */}
       <div>
         {/* as="p": the sizes are visual scale, not document structure — a bare
             <Title size> renders a heading and breaks the page outline. */}

package/templates/skills/bestax-custom-component/references/api.md

@@ -32,14 +32,14 @@ on the root element with `mergeBulmaStyles(bulmaHelperStyles, style)`
 `BulmaClassesProps` is the union of all helper prop groups, composed from per-concern hooks
 that can also be used on their own:
 
-| Group      | Hook                   | Representative props                                                                                                             |
-| ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| Color      | `useColorClasses`      | `color`, `colorShade`, `backgroundColor`, `backgroundColorShade`                                                                 |
-| Spacing    | `useSpacingClasses`    | `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`                                                 |
-| Typography | `useTypographyClasses` | `textSize`, `textAlign`, `textTransform`, `textWeight`, `fontFamily` (+ responsive variants)                                     |
-| Visibility | `useVisibilityClasses` | `display`, `visibility` (+ per-viewport variants)                                                                                |
-| Flexbox    | `useFlexboxClasses`    | `flexDirection`, `flexWrap`, `justifyContent`, `alignItems`, `alignContent`, `alignSelf`, `flexGrow`, `flexShrink`               |
-| Other      | `useOtherClasses`      | `float`, `overflow`, `radius`, `shadow`, `interaction`, `cursor`, `skeleton`, `clearfix`, `relative`, `fullHeight`, `responsive` |
+| Group      | Hook                   | Representative props                                                                                                                                                             |
+| ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Color      | `useColorClasses`      | `color`, `colorShade`, `backgroundColor`, `backgroundColorShade`                                                                                                                 |
+| Spacing    | `useSpacingClasses`    | `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`, `gap`, `columnGap`, `rowGap`, `gapless`                                                        |
+| Typography | `useTypographyClasses` | `textSize`, `textAlign`, `textTransform`, `textWeight`, `fontFamily` (+ responsive variants)                                                                                     |
+| Visibility | `useVisibilityClasses` | `display`, `visibility` (+ per-viewport variants)                                                                                                                                |
+| Flexbox    | `useFlexboxClasses`    | `flexDirection`, `flexWrap`, `justifyContent`, `alignItems`, `alignContent`, `alignSelf`, `flexGrow`, `flexShrink`                                                               |
+| Other      | `useOtherClasses`      | `float`, `overflow`, `overflowX`, `overflowY`, `radius`, `shadow`, `interaction`, `cursor`, `skeleton`, `clearfix`, `pos`, `relative`, `fullHeight`, `aspectRatio`, `responsive` |
 
 Because the component destructures these into `bulmaHelperClasses`, callers get the full Bulma
 helper surface for free on every component built this way, and `rest` stays clean for DOM
@@ -68,13 +68,13 @@ de-dupes. Related exports:
 Re-exported through `useBulmaClasses`. Use them to type component-specific props and to drive
 Storybook `argTypes`/tests:
 
-`validColors`, `validColorShades`, `validSchemeColors`, `validSizes`, `validTextSizes`,
+`validColors`, `validColorShades`, `validSchemeColors`, `validSizes`, `validGaps`, `validTextSizes`,
 `validAlignments`, `validTextTransforms`, `validTextWeights`, `validFontFamilies`,
 `validDisplays`, `validVisibilities`, `validFlexDirections`, `validFlexWraps`,
 `validJustifyContents`, `validAlignContents`, `validAlignItems`, `validAlignSelfs`,
 `validFlexGrowShrink`, `validViewports`, `validFloats`, `validOverflows`,
-`validInteractions`, `validCursors`, `validRadii`, `validShadows`,
-`validResponsives`.
+`validAxisOverflows`, `validInteractions`, `validCursors`, `validRadii`,
+`validShadows`, `validResponsives`, `validPositions`, `validAspectRatios`.
 
 ```ts
 export type MyColor = (typeof validColors)[number];
@@ -94,6 +94,98 @@ overrides `--bulma-*` custom properties at runtime —
 which is exactly why component SCSS must register its vars via `cv.register-vars` rather than
 hard-coding values.
 
+## Browser-only content: `ClientOnly` / `useIsHydrated`
+
+- `<ClientOnly fallback?>` (`helpers/ClientOnly.tsx`) renders its children only after hydration,
+  and `fallback` on the server and while hydrating. Pass the children as a function to keep
+  browser-only expressions off the server. Use it rather than a `typeof window` check, which
+  makes the server and client markup differ.
+- `useIsHydrated()` (`helpers/useIsHydrated.ts`) is the hook underneath: `false` on the server and
+  during the hydrating render, `true` from the commit after.
+
+```tsx
+<ClientOnly fallback={<Skeleton variant="lines" lines={1} />}>
+  {() => (
+    <p>Times are in {Intl.DateTimeFormat().resolvedOptions().timeZone}.</p>
+  )}
+</ClientOnly>
+```
+
+## Floating content: `Portal`
+
+A panel anchored to the button that opens it is `Popover`, which already portals
+(`appendToBody`), traps focus and dismisses itself. `Portal` is for the overlays it doesn't
+cover.
+
+`<Portal container?>` (`helpers/portal.tsx`) renders its children into `document.body`, or into
+`container` (an element or a selector), so floating content escapes an ancestor's `overflow`,
+`transform` or stacking context. It renders nothing on the server and during hydration, so the
+first client render matches; `disabled` renders in place instead. Use it rather than calling
+`createPortal` yourself, which React's server renderer can't render.
+
+Focus follows the DOM, not the React tree: portaled content comes last in the Tab order, so move
+focus into it when it opens and back to its trigger when it closes. To trap portaled content,
+put the trap's ref on the element inside the `Portal`, as below with
+`useFocusTrap(panelRef, { active: open, restoreFocus: buttonRef })`. A focus trap doesn't cover
+what a `Portal` inside it renders, so render nested overlays inside the trapped element.
+
+```tsx
+{
+  open && (
+    <Portal>
+      <div ref={panelRef} role="dialog" aria-label="Filters" tabIndex={-1}>
+        …
+      </div>
+    </Portal>
+  );
+}
+```
+
+## Holding focus: `useFocusTrap`
+
+`useFocusTrap(ref, { active, initialFocusRef, restoreFocus })` (`helpers/useFocusTrap.ts`) moves
+focus into `ref` when `active` turns on, wraps Tab at the first and last tab stops (the ones the
+browser visits, so hidden, disabled, inert and `tabIndex={-1}` elements are skipped and a radio
+group counts once) and restores focus when it turns off. It handles Tab only: wire Escape to
+close. Pass the trigger's ref as `restoreFocus` for a panel opened from a button. It looks for
+the container again each time the component calling it renders, so `active` can follow `open`
+alone even when the panel mounts a render later, as portaled content can. The example below
+shows the hook's wiring; for a real filter panel opened from a button, use `Popover`, which does
+all of this.
+
+```tsx
+function FilterPanel({ children }: { children: React.ReactNode }) {
+  const [open, setOpen] = useState(false);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  useFocusTrap(panelRef, { active: open, restoreFocus: buttonRef });
+
+  return (
+    <>
+      <Button
+        ref={buttonRef}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        onClick={() => setOpen(o => !o)}
+      >
+        Filters
+      </Button>
+      {open && (
+        <div
+          ref={panelRef}
+          role="dialog"
+          aria-label="Filters"
+          tabIndex={-1}
+          onKeyDown={e => e.key === 'Escape' && setOpen(false)}
+        >
+          {children}
+        </div>
+      )}
+    </>
+  );
+}
+```
+
 ## SCSS utilities — from the `bulma` package
 
 ```scss

package/templates/skills/bestax-custom-component/references/component-catalog.md

@@ -1,5 +1,5 @@
 <!-- GENERATED by scripts/gen-component-catalog.mjs — do not edit by hand. -->
-<!-- Regenerate with `npm run gen:catalog`. Source: docs/docs/api/**. -->
+<!-- Regenerate with `pnpm gen:catalog`. Source: docs/docs/api/**. -->
 
 # Component catalog
 
@@ -37,7 +37,7 @@ instead of hand-writing markup.
 - Raw `*Base` form exports (`InputBase`, `SelectBase`, `TextAreaBase`, …) are
   escape-hatch variants of the convenience wrappers above them; see the Form docs.
 
-87 documented components. Generated from the API docs — every exported
+94 documented components. Generated from the API docs — every exported
 component is guaranteed to appear (the generator fails if one lacks an API page).
 
 ## Elements
@@ -58,6 +58,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Link](https://bestax.io/docs/api/elements/link) — The `Link` component renders a styled anchor (`<a>`) element with Bulma helper class integration.
 - [LinkButton](https://bestax.io/docs/api/elements/linkbutton) — The `LinkButton` component renders a `<button>` that visually looks like text or a link.
 - [ListItem](https://bestax.io/docs/api/elements/listitem) — The `ListItem` component renders a styled list item (`<li>`) element with Bulma helper class integration.
+- [Loader](https://bestax.io/docs/api/elements/loader) — The `Loader` component renders Bulma's `.loader`, a small spinning ring for inline loading states.
 - [Notification](https://bestax.io/docs/api/elements/notification) — The `Notification` component is a Bulma-styled alert/message area for providing feedback, warnings, or information to users.
 - [OrderedList](https://bestax.io/docs/api/elements/orderedlist) — The `OrderedList` component renders a styled ordered list (`<ol>`) element with Bulma helper class integration.
 - [Paragraph](https://bestax.io/docs/api/elements/paragraph) — The `Paragraph` component renders a styled `<p>` element with Bulma helper class integration.
@@ -82,6 +83,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Card](https://bestax.io/docs/api/components/card) — The `Card` component renders a Bulma-styled card with optional header, image, content, and footer.
 - [Carousel](https://bestax.io/docs/api/components/carousel) — The `Carousel` component provides an image/content slider with navigation arrows and indicators.
 - [Collapse](https://bestax.io/docs/api/components/collapse) — The `Collapse` component provides an expandable/collapsible content panel.
+- [Collapses](https://bestax.io/docs/api/components/collapses) — The `Collapses` component groups `Collapse` items into an accordion that keeps one item open at a time, or any number with `multiple`.
 - [Dialog](https://bestax.io/docs/api/components/dialog) — The `Dialog` component provides ready-made confirm and alert dialogs, so a destructive action stays one `await dialog.confirm()` call away.
 - [Dropdown](https://bestax.io/docs/api/components/dropdown) — The `Dropdown` component provides Bulma's versatile dropdown menu for your Bulma React UI.
 - [Loading](https://bestax.io/docs/api/components/loading) — The `Loading` component provides a loading overlay with a spinner animation.
@@ -91,6 +93,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Navbar](https://bestax.io/docs/api/components/navbar) — The `Navbar` component implements Bulma's powerful, responsive navigation bar for your Bulma React UI.
 - [Pagination](https://bestax.io/docs/api/components/pagination) — The `Pagination` component provides a flexible, composable Bulma pagination navigation for your Bulma React UI.
 - [Panel](https://bestax.io/docs/api/components/panel) — The `Panel` component implements Bulma's versatile panel block for React.
+- [Popover](https://bestax.io/docs/api/components/popover) — The `Popover` component opens a panel of interactive content, such as a filter form or a set of share options, anchored to the element that toggles it.
 - [Reveal](https://bestax.io/docs/api/components/reveal) — The `Reveal` component animates its content into view as it scrolls into the viewport, backed by `IntersectionObserver`.
 - [Sidebar](https://bestax.io/docs/api/components/sidebar) — The `Sidebar` component provides a slide-out navigation panel that appears from the left or right side of the screen.
 - [Steps](https://bestax.io/docs/api/components/steps) — The `Steps` component provides a multi-step progress indicator for wizard flows, checkout processes, or any multi-step workflow.
@@ -105,10 +108,11 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Checkboxes](https://bestax.io/docs/api/form/checkboxes) — The `Checkboxes` component wraps multiple `Checkbox` components in a Bulma-styled group.
 - [Control](https://bestax.io/docs/api/form/control) — The `Control` component is a Bulma-styled wrapper for form controls (`Input`, `Select`, `TextArea`, etc.), supporting icons (left/right), loading state…
 - [DateInput](https://bestax.io/docs/api/form/datetime/dateinput) — The `DateInput` component is a form input that opens a popover calendar for date selection.
+- [DateRangeInput](https://bestax.io/docs/api/form/datetime/daterangeinput) — The `DateRangeInput` component is a form input for a start and end date, picked from one popover calendar or typed into two segmented inputs.
 - [DateTimeInput](https://bestax.io/docs/api/form/datetime/datetimeinput) — The `DateTimeInput` combines a calendar and a time **wheel spinner** in a single popover — an iOS-style layout.
 - [Field](https://bestax.io/docs/api/form/field) — The `Field` component is a Bulma-styled form field container.
 - [File](https://bestax.io/docs/api/form/file) — The `File` component provides a Bulma-styled file input, supporting color, size, boxed/fullwidth/align styles, icons, "has name", and filename display.
-- [Input](https://bestax.io/docs/api/form/input) — The `Input` component provides a Bulma-styled text input, supporting colors, sizes, rounded corners, static/read-only state, hover/focus/loading states…
+- [Input](https://bestax.io/docs/api/form/input) — The `Input` component provides a Bulma-styled text input, supporting colors, sizes, rounded corners, static state, hover/focus/loading states…
 - [Numberinput](https://bestax.io/docs/api/form/numberinput) — The `Numberinput` component provides a number input with increment/decrement buttons.
 - [Radio](https://bestax.io/docs/api/form/radio) — The `Radio` component provides a Bulma-styled radio button input with flexible labels and helper classes.
 - [Radios](https://bestax.io/docs/api/form/radios) — The `Radios` component wraps multiple `Radio` components in a Bulma-styled group.
@@ -117,7 +121,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Slider](https://bestax.io/docs/api/form/slider) — The `Slider` component provides a range slider input for selecting values within a range.
 - [Switch](https://bestax.io/docs/api/form/switch) — The `Switch` component provides a toggle switch for boolean on/off states.
 - [Taginput](https://bestax.io/docs/api/form/taginput) — The `Taginput` component provides a tag/chip input field for managing multiple tags.
-- [TextArea](https://bestax.io/docs/api/form/textarea) — The `TextArea` component provides a Bulma-styled multi-line text input, supporting color, size, rounded corners, static/read-only state…
+- [TextArea](https://bestax.io/docs/api/form/textarea) — The `TextArea` component provides a Bulma-styled multi-line text input, supporting color, size, hover/focus/loading states, fixed size…
 - [TimeInput](https://bestax.io/docs/api/form/datetime/timeinput) — The `TimeInput` component is a form input that opens a popover spinner for time-of-day selection.
 
 ## Columns
@@ -141,9 +145,12 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 
 ## Helpers
 
+- [ClientOnly](https://bestax.io/docs/api/helpers/clientonly) — `ClientOnly` renders its children only in the browser, after hydration, and a `fallback` until then…
 - [ConfigProvider](https://bestax.io/docs/api/helpers/config) — The `ConfigProvider` component provides a React context for configuring global settings across all Bulma UI components.
+- [Portal](https://bestax.io/docs/api/helpers/portal) — `Portal` renders its children into another part of the page, `document.body` unless `container` says otherwise…
 - [Theme](https://bestax.io/docs/api/helpers/theme) — The `Theme` component provides a powerful way to customize Bulma's appearance using CSS custom properties (CSS variables).
-- [Valid value constants](https://bestax.io/docs/api/helpers/valid-values) — The `valid*` tuples enumerate the core accepted values for the shared Bulma helper props — public API for building prop types and validation.
+- [Valid value constants](https://bestax.io/docs/api/helpers/valid-values) — The helper tuples enumerate the core accepted values for the shared Bulma helper props — public API for building prop types and validation.
 - [classNames](https://bestax.io/docs/api/helpers/classnames) — `classNames` is a utility function for conditionally joining class names together.
 - [useBulmaClasses](https://bestax.io/docs/api/helpers/usebulmaclasses) — `useBulmaClasses` is a custom React hook that generates Bulma helper class strings from a set of props.
+- [useFocusTrap](https://bestax.io/docs/api/helpers/usefocustrap) — `useFocusTrap` keeps keyboard focus inside a container while it is active: focus moves in when the trap turns on…
 - [usePrefixedClassNames](https://bestax.io/docs/api/helpers/useprefixedclassnames) — `usePrefixedClassNames` builds a component class string that honors the `classPrefix` from `ConfigProvider` — the hook every bestax component uses for its own…

package/templates/skills/bestax-custom-component/references/library-contributor.md

@@ -159,6 +159,23 @@ Rules that keep components consistent:
   Run `pnpm exec prettier --write` on your new files (or `pnpm format` from the repo root) before
   `pnpm lint`. Copy snippets as a starting point, then let Prettier normalize them.
 
+- **Browser-only work waits for hydration.** A component that measures or reads browser-only
+  state while rendering uses `useIsHydrated` (`helpers/useIsHydrated.ts`) rather than a
+  `typeof document` check, so the first client render matches the server markup. Test that with
+  `renderToString` plus `hydrateRoot` and a `console.error` spy, as `ClientOnly.test.tsx` does.
+
+- **Floating content portals through `Portal`.** A new component that renders outside its own
+  place in the DOM uses `Portal` (`helpers/portal.tsx`) rather than its own `createPortal` and
+  `typeof document` check. `Portal` renders nothing on the server or during hydration, so the
+  first client render matches the server markup. Test that with `renderToString` plus
+  `hydrateRoot` and a `console.error` spy, as `portal.test.tsx` does.
+
+- **Focus management builds on `useFocusTrap`.** A new component that holds focus while it is
+  open uses `useFocusTrap` (`helpers/useFocusTrap.ts`) rather than its own Tab handler, so it
+  gets the same tab-stop rules (hidden, disabled, inert, radio groups, shadow roots) as the rest
+  of the library. It waits for hydration, so it also traps a container that only appears after
+  hydration.
+
 See `api.md` for the full helper API and `patterns.md` for the complete Dialog walkthrough.
 
 ## SCSS pattern (required)
@@ -223,6 +240,12 @@ Register **all** themable values — durations and offsets included — and pref
 tokens (`scheme-main`, `text`, `border`). When the component is themeable, add rows to
 `skills/bestax-theming/references/themeable-components.md` and `css-variables.md` in the same PR.
 
+The reduced-motion rule has to outrank every rule that starts the animation. On the same
+selector it wins by coming later; when the animation sits on a more specific selector, such as
+a state class (`.mycomponent.is-active`), make the stop `animation: none !important`. A styles
+test reads every animation out of each published stylesheet and fails on one that still plays
+under reduced motion.
+
 The canonical reference file is `bulma-ui/src/scss/components/_dialog.scss`.
 
 ## Stories

package/templates/skills/bestax-form/SKILL.md

@@ -94,7 +94,8 @@ All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Fiel
 | `Numberinput`                                           | Numeric input with increment/decrement, min/max, step, stepper.           |
 | `Rate`                                                  | Star rating; `max`, `precision` (half/quarter), custom icons, `disabled`. |
 | `Taginput`                                              | Tag/chip input; suggestions, confirm keys, closable tags.                 |
-| `DateInput` / `TimeInput` / `DateTimeInput` (+ `*Base`) | Date / time / datetime pickers.                                           |
+| `DateInput` / `TimeInput` / `DateTimeInput` (+ `*Base`) | Date / time / datetime pickers; month or year via `granularity`.          |
+| `DateRangeInput` (+ `*Base`)                            | Start and end date: `[Date \| null, Date \| null]`, one calendar.         |
 
 (`NumberInput` and `TagInput` also exist as deprecated aliases of `Numberinput`/`Taginput` —
 same components; prefer the lowercase-second-word spellings.)
@@ -103,18 +104,18 @@ same components; prefer the lowercase-second-word spellings.)
 
 Across the convenience inputs (`Input`, `Select`, `TextArea`, and similar):
 
-| Prop                             | Type                                                                  | Purpose                                                              |
-| -------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `color`                          | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'` | Visual state — use `'danger'` for errors, `'success'` for valid.     |
-| `size`                           | `'small' \| 'medium' \| 'large'`                                      | Input size.                                                          |
-| `value` / `onChange`             | controlled value + handler                                            | Standard React controlled inputs.                                    |
-| `defaultValue`                   | uncontrolled initial value                                            | When not controlling state.                                          |
-| `disabled`, `readOnly`           | `boolean`                                                             | Native states (`readOnly` on `*Base`).                               |
-| `label`                          | `ReactNode`                                                           | Field label (convenience components; auto-associated via `htmlFor`). |
-| `message`                        | `ReactNode`                                                           | Help / validation text rendered as `<p class="help">`.               |
-| `messageColor`                   | a Bulma color                                                         | Colors the help text (`'danger'` for errors).                        |
-| `iconLeftName` / `iconRightName` | `string`                                                              | Icon shortcuts; pair with `hasIconsLeft/Right`.                      |
-| `isLoading`                      | `boolean`                                                             | Loading indicator on the Control.                                    |
+| Prop                             | Type                                                                  | Purpose                                                                    |
+| -------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `color`                          | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'` | Visual state — use `'danger'` for errors, `'success'` for valid.           |
+| `size`                           | `'small' \| 'medium' \| 'large'`                                      | Input size.                                                                |
+| `value` / `onChange`             | controlled value + handler                                            | Standard React controlled inputs.                                          |
+| `defaultValue`                   | uncontrolled initial value                                            | When not controlling state.                                                |
+| `disabled`, `readOnly`           | `boolean`                                                             | Native states (`readOnly` on `*Base`).                                     |
+| `label`                          | `ReactNode`                                                           | Field label (convenience components; auto-associated via `htmlFor`).       |
+| `message`                        | `ReactNode`                                                           | Help / validation text rendered as `<p class="help">`.                     |
+| `messageColor`                   | a Bulma color                                                         | Colors the help text (`'danger'` for errors).                              |
+| `iconLeftName` / `iconRightName` | `string`                                                              | Icon shortcuts; pair with `hasIconsLeft/Right`.                            |
+| `isLoading`                      | `boolean`                                                             | Loading spinner on the Control; `Select` draws it in place of the chevron. |
 
 Plus the full Bulma **helper props** (`m`, `p`, `textColor`, `display`, …) on every component
 via `useBulmaClasses`.
@@ -130,8 +131,8 @@ The `label` prop on the single-control convenience inputs (`Input`, `Select`, `T
 generated one otherwise, and an explicit `labelProps={{ htmlFor }}` wins. The wiring only
 happens when the component renders its own `Field` (nested inside one, the `label` prop is
 dropped); the date/time pickers skip it in `inline` mode and `Taginput` skips it at
-`maxTags` (no visible input to label). The group inputs (`Checkboxes`, `Radios`, `Rate`)
-associate their `label` too, but group-style: the wrapper gets `role="group"`/`"radiogroup"`
+`maxTags` (no visible input to label). The group inputs (`Checkboxes`, `Radios`, `Rate`,
+`DateRangeInput`) associate their `label` too, but group-style: the wrapper gets `role="group"`/`"radiogroup"`
 and `aria-labelledby` pointing at the label. Composing `Field` + bases yourself also
 associates: `Field`'s own `label` wires to a single composed `InputBase`/`SelectBase`/
 `TextAreaBase` (skipped for `grouped`/`hasAddons`). Pass `labelProps={{ htmlFor }}` plus a
@@ -144,7 +145,17 @@ opt out — e.g. when the labeled `Field` wraps something that is not one of tho
   lines, auto-wrapping, built-in `message`/`messageColor`. Default to this.
 - **Composed** (`Field` + `Control` + `InputBase`) — when you need grouped controls, addons,
   multiple controls per field, or custom layout. The convenience components detect they're
-  already inside a `Field`/`Control` and won't double-wrap, so you can mix the two.
+  already inside a `Field`/`Control` and won't double-wrap, so you can mix the two. Inside a
+  `Control` they render no `Control` of their own, so set their Control-level props, such as
+  the icon props, `isLoading` and `controlSize`, on that `Control`: given to the input there,
+  they do nothing and warn in development. `Select` draws its own `isLoading`, so that one
+  stays on the `Select`. Inside a `Control` they render no `Field` either, so a convenience
+  input you place in a `Control` (for icons, say) takes its `label`, `horizontal` and class
+  name from a `Field` wrapped around that `Control`. Given `label`, `message`, `horizontal` or `fieldClassName` in a
+  `Control` with no `Field` around it, it renders its own `Field` inside the `.control`,
+  which Bulma's styles don't expect, and warns in development. `Autocomplete` and
+  `Numberinput` are the exception: in a bare `Control` they always render their own `Field`,
+  so give that `Control` a `Field` around it.
 
 ## Validation without a library
 
@@ -220,7 +231,7 @@ miss because Bulma has something that looks close:
 - **Confirmation** — `Toast`, not `Notification`/`Message`. Mount
   `<ToastContainer position="top-right" />` once at the app root, then call
   `toast.success('Demo booked')` from the submit handler (`.danger` for a failed submit). It
-  self-dismisses; a `Notification` is a static element you place and tear down yourself.
+  self-dismisses.
 - **"Are you sure?"** — `Dialog`, not `Modal`. Mount `<DialogContainer />` at the root, then
   `if (await dialog.confirm({ title: 'Delete this key?', message: '…', type: 'danger' })) …`.
   It resolves to a boolean, so a destructive action stays one `if` rather than a state machine.