create-bestax 3.1.4 → 3.2.0

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

@@ -0,0 +1,395 @@
+# Reference: building a component inside the bestax monorepo
+
+You are inside the bestax monorepo — import helpers from relative paths
+(`../helpers/classNames`), not from the package. This is the full contributor pipeline for a
+custom "extra" component: React + TS, the Bulma v1 SCSS pattern, stories, tests, docs, and
+wiring. For **form** components (Field/Control/Input/etc.) use the `bestax-form` skill instead.
+
+## File layout
+
+Every custom component has five files. Mirror the existing names exactly (PascalCase TSX,
+`_kebab.scss` partial):
+
+```
+bulma-ui/src/components/MyComponent.tsx              # React + TS component
+bulma-ui/src/components/MyComponent.stories.tsx      # Storybook stories
+bulma-ui/src/components/__tests__/MyComponent.test.tsx  # Jest + RTL tests
+bulma-ui/src/scss/components/_mycomponent.scss       # SCSS partial
+docs/docs/api/components/mycomponent.md              # Docusaurus docs page
+```
+
+Then wire two index files (see **Wiring & build**).
+
+## Component template
+
+Components accept Bulma helper props via `BulmaClassesProps`, run them through
+`useBulmaClasses`, build their own classes with `usePrefixedClassNames`, and merge everything
+with `classNames`. Spread `rest` (the non-helper props) onto the DOM node.
+
+Use `forwardRef` when consumers need the DOM node (focus, measurement, observers) — typical
+for interactive extras, so this template uses it. Simpler wrappers in the library are plain
+function components; match the siblings in the target folder.
+
+```tsx
+import React, { forwardRef } from 'react';
+import { classNames, usePrefixedClassNames } from '../helpers/classNames';
+import { useBulmaClasses, BulmaClassesProps } from '../helpers/useBulmaClasses';
+
+export type MyComponentColor =
+  'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+
+/**
+ * Props for the MyComponent component.
+ *
+ * @property {MyComponentColor} [color] - Bulma color modifier.
+ * @property {'small' | 'medium' | 'large'} [size] - Size modifier.
+ * @property {boolean} [isActive] - Whether the component is active.
+ */
+export interface MyComponentProps
+  extends
+    Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>,
+    Omit<BulmaClassesProps, 'color'> {
+  color?: MyComponentColor;
+  size?: 'small' | 'medium' | 'large'; // element size union — never the spacing 'validSizes' constant ('0'…'6'|'auto')
+  isActive?: boolean;
+}
+
+/**
+ * MyComponent — short description of what it does.
+ *
+ * @example
+ * <MyComponent color="primary" size="large" isActive>Hello</MyComponent>
+ */
+export const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
+  ({ color, size, isActive, className, children, ...props }, ref) => {
+    // 1. Pull Bulma helper classes (m/p, text*, display, etc.) out of props.
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+
+    // 2. Build this component's own classes (respects the ConfigProvider classPrefix).
+    const mainClasses = usePrefixedClassNames('mycomponent', {
+      [`is-${color}`]: !!color,
+      [`is-${size}`]: !!size,
+      'is-active': !!isActive,
+    });
+
+    // 3. Merge: own classes + helper classes + caller className.
+    const combined = classNames(mainClasses, bulmaHelperClasses, className);
+
+    return (
+      <div ref={ref} className={combined} {...rest}>
+        {children}
+      </div>
+    );
+  }
+);
+
+MyComponent.displayName = 'MyComponent';
+
+export default MyComponent;
+```
+
+Rules that keep components consistent:
+
+- **Always `Omit<…, 'color'>`** from both `HTMLAttributes` and `BulmaClassesProps` when the
+  component exposes its own typed `color`, so the native/helper `color` doesn't collide.
+- **Never hand-build class strings.** Use `usePrefixedClassNames(base, conditionalMap)` so the
+  optional `classPrefix` from `ConfigProvider` is honored, then `classNames(...)` to merge.
+- **Spread `rest`, not `props`**, onto the DOM node — `useBulmaClasses` has already stripped the
+  helper props out of `rest`, so they don't leak to the DOM as invalid attributes.
+- **Set `displayName`** on `forwardRef` components (needed for tests and Storybook autodocs).
+- **Element sizing uses an inline `'small' | 'medium' | 'large'` union**, mapped to `is-small` /
+  `is-medium` / `is-large` (see `Tabs.tsx`, `Control.tsx`). Do **not** reach for the `validSizes`
+  constant — that one is `'0'…'6' | 'auto'` and exists for **spacing** helpers, not element size.
+- **Format before you lint.** The repo enforces Prettier and ESLint fails on unformatted code.
+  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.
+
+See `api.md` for the full helper API and `patterns.md` for the complete Dialog walkthrough.
+
+## SCSS pattern (required)
+
+This is the library's house convention — **the Bulma v1 CSS-variable pattern**. Do not write
+plain hard-coded CSS or homebrew `--mycomponent-*` variables. Import Bulma's utilities, declare
+SCSS vars with `!default`, register them as `--bulma-*` custom properties on the root selector
+with `cv.register-vars`, then consume them with `cv.getVar`. Prefix every selector with
+`iv.$class-prefix`.
+
+```scss
+// bulma-ui/src/scss/components/_mycomponent.scss
+@use 'bulma/sass/utilities/initial-variables' as iv;
+@use 'bulma/sass/utilities/css-variables' as cv;
+
+// 1. SCSS variables, overridable, referencing Bulma vars via cv.getVar.
+$mycomponent-radius: cv.getVar('radius') !default;
+$mycomponent-background: cv.getVar('scheme-main') !default;
+$mycomponent-color: cv.getVar('text') !default;
+$mycomponent-padding: 1rem !default;
+
+// 2. Register them as runtime --bulma-* custom properties on the root selector.
+.#{iv.$class-prefix}mycomponent {
+  @include cv.register-vars(
+    (
+      'mycomponent-radius': #{$mycomponent-radius},
+      'mycomponent-background': #{$mycomponent-background},
+      'mycomponent-color': #{$mycomponent-color},
+      'mycomponent-padding': #{$mycomponent-padding},
+    )
+  );
+}
+
+// 3. Consume via cv.getVar. Prefix every selector with iv.$class-prefix.
+.#{iv.$class-prefix}mycomponent {
+  background-color: cv.getVar('mycomponent-background');
+  border-radius: cv.getVar('mycomponent-radius');
+  color: cv.getVar('mycomponent-color');
+  padding: cv.getVar('mycomponent-padding');
+}
+
+// Color variants reuse Bulma's registered color vars.
+.#{iv.$class-prefix}mycomponent.#{iv.$class-prefix}is-primary {
+  background-color: cv.getVar('primary');
+  color: cv.getVar('primary-invert');
+}
+
+// Respect reduced-motion if you animate.
+@media (prefers-reduced-motion: reduce) {
+  .#{iv.$class-prefix}mycomponent {
+    animation: none;
+  }
+}
+```
+
+Why this matters: registering vars makes the component themeable at runtime (the docs site and
+`Theme`/`ConfigProvider` providers override `--bulma-*` properties), and the `iv.$class-prefix` keeps
+the component working when consumers opt into a class prefix to avoid collisions.
+
+Register **all** themable values — durations and offsets included — and prefer Bulma tokens
+(`cv.getVar('radius-rounded')`, never `9999px`); derive dark-mode-affected surfaces from scheme
+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 canonical reference file is `bulma-ui/src/scss/components/_dialog.scss`.
+
+## Stories
+
+`MyComponent.stories.tsx` beside the component. Use `tags: ['autodocs']` so the JSDoc becomes
+the docs page, declare `argTypes`, and write one named `function`-style render per variant.
+Give every argType a `description` — enforced by a jest meta-test.
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MyComponent } from './MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  title: 'Components/MyComponent',
+  component: MyComponent,
+  tags: ['autodocs'],
+  argTypes: {
+    color: {
+      control: 'select',
+      options: ['primary', 'link', 'info', 'success', 'warning', 'danger'],
+      description: 'Bulma color modifier applied to the component.',
+    },
+    isActive: {
+      control: 'boolean',
+      description: 'Whether the component renders in its active state.',
+    },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const Default: Story = {
+  render: function DefaultExample() {
+    return <MyComponent>Default</MyComponent>;
+  },
+};
+
+export const Colors: Story = {
+  render: function ColorsExample() {
+    return (
+      <>
+        <MyComponent color="primary">Primary</MyComponent>
+        <MyComponent color="danger">Danger</MyComponent>
+      </>
+    );
+  },
+};
+```
+
+## Tests
+
+`__tests__/MyComponent.test.tsx`, Jest + `@testing-library/react`. Cover render, each prop →
+class mapping, the helper-prop passthrough, ref forwarding, the ConfigProvider prefix, and any
+interaction/a11y.
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { createRef } from 'react';
+import { MyComponent } from '../MyComponent';
+import { ConfigProvider } from '../../helpers/Config';
+
+describe('MyComponent', () => {
+  it('renders children', () => {
+    render(<MyComponent>Hello</MyComponent>);
+    expect(screen.getByText('Hello')).toBeInTheDocument();
+  });
+
+  it('applies the color modifier', () => {
+    render(<MyComponent color="primary">x</MyComponent>);
+    expect(screen.getByText('x')).toHaveClass('mycomponent', 'is-primary');
+  });
+
+  it('passes Bulma helper props through', () => {
+    render(<MyComponent m="3">x</MyComponent>);
+    expect(screen.getByText('x')).toHaveClass('m-3');
+  });
+
+  it('forwards the ref', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<MyComponent ref={ref}>x</MyComponent>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it('applies classPrefix from ConfigProvider', () => {
+    const { container } = render(
+      <ConfigProvider classPrefix="bestax-">
+        <MyComponent>x</MyComponent>
+      </ConfigProvider>
+    );
+    const el = container.querySelector('.bestax-mycomponent');
+    expect(el).toBeInTheDocument();
+    expect(el).not.toHaveClass('mycomponent');
+  });
+});
+```
+
+## Docs page
+
+`docs/docs/api/components/mycomponent.md` — Overview, Import, a Props table, `Usage` with
+live examples, then Accessibility, Related Components, and Additional Resources. Live code
+blocks use the ` ```tsx live ` fence (Docusaurus live-codeblock). House rules:
+
+- Frontmatter `title:` **must equal the exported component name** — `gen-component-catalog.mjs`
+  parses it to build the skill catalog.
+- Headings are Title Case.
+- Every example gets one prose sentence explaining what it shows.
+- No inline `style={{}}` in examples — use helper props.
+
+````md
+---
+title: MyComponent
+sidebar_label: MyComponent
+---
+
+# MyComponent
+
+## Overview
+
+Short description of the component.
+
+## Import
+
+```tsx
+import { MyComponent } from '@allxsmith/bestax-bulma';
+```
+
+## Props
+
+| Prop       | Type                         | Default | Description           |
+| ---------- | ---------------------------- | ------- | --------------------- |
+| `color`    | `'primary' \| 'link' \| ...` | —       | Bulma color modifier. |
+| `isActive` | `boolean`                    | `false` | Active state.         |
+
+## Usage
+
+### Default
+
+A basic MyComponent with default styling.
+
+```tsx live
+<MyComponent>Hello</MyComponent>
+```
+
+## Accessibility
+
+Note roles, keyboard behavior, and reduced-motion handling.
+
+## Related Components
+
+- [`Tag`](../elements/tag.md) — for a small colored label instead.
+
+## Additional Resources
+
+- [Bulma documentation](https://bulma.io/documentation/)
+````
+
+> Note: the Docusaurus docs load the **built** dist CSS. After SCSS changes, run
+> `cd bulma-ui && pnpm build` before the new styles show up in the docs site (Storybook
+> compiles SCSS live and does not need this).
+
+## Wiring & build
+
+Two index files must be updated or the component won't ship:
+
+1. **Package export** — add to `bulma-ui/src/index.ts`, in the **components** group (the file
+   groups exports by directory — keep yours next to the other `./components/*` lines):
+   ```ts
+   export * from './components/MyComponent';
+   ```
+2. **SCSS bundle** — add to `bulma-ui/src/scss/components/_index.scss`:
+   ```scss
+   @use 'mycomponent';
+   ```
+
+Then build and verify:
+
+```sh
+cd bulma-ui
+pnpm exec prettier --write src/components/MyComponent.tsx src/scss/components/_mycomponent.scss
+pnpm lint
+pnpm test
+pnpm build      # compiles JS + the bestax/extras CSS bundles
+```
+
+Finally run `pnpm gen:catalog` from the repo root — CI's `gen:catalog:check` fails if the skill
+component catalog is stale.
+
+## Visually inspect it in a browser
+
+Types and unit tests don't see layout. **Render the component and actually look at it** before
+you call it done — spacing, padding, vertical centering, alignment, and every variant/state
+(colors, sizes, hover/active, dark mode). Visual bugs hide from `tsc` and `@testing-library`.
+
+1. Run a surface that renders it: `pnpm storybook` (compiles SCSS live) or the docs dev server.
+2. Open the component and inspect it. If a browser-automation tool (claude-in-chrome, Playwright)
+   is available, drive the browser and screenshot each variant; otherwise open it yourself and
+   eyeball it.
+3. Check the usual offenders:
+   - **Vertical centering of inline text** — `display: inline-block` + `line-height: 1` makes
+     text sit low. For chips/labels/buttons use `display: inline-flex; align-items: center;
+justify-content: center;` with a normal `line-height` (Bulma's `Tag` is the reference).
+   - Padding/gaps look balanced; nothing clips or overflows.
+   - Every color/size variant renders; dark mode is legible.
+
+Fix what you see, then re-inspect. A green test suite with a misaligned component is not done.
+
+## Checklist
+
+- [ ] **Checked the inventory first** — searched `src/index.ts` / docs / Storybook for an existing
+      match or synonym, and told the user (reuse/extend it, or confirm there's a genuine gap).
+- [ ] `MyComponent.tsx` — `Omit<…, 'color'>`, `useBulmaClasses`, `usePrefixedClassNames`,
+      `classNames`, spread `rest`; `forwardRef` + `displayName` when consumers need the node.
+- [ ] `_mycomponent.scss` — `@use` Bulma utilities, `$vars !default`, `cv.register-vars`,
+      `cv.getVar`, every selector prefixed with `iv.$class-prefix`.
+- [ ] `MyComponent.stories.tsx` — `tags: ['autodocs']`, `argTypes` (each with a `description`),
+      one story per variant.
+- [ ] `__tests__/MyComponent.test.tsx` — render, prop→class, helper passthrough, ref + ConfigProvider prefix test (required).
+- [ ] `docs/docs/api/components/mycomponent.md` — Overview / Import / Props / `tsx live` /
+      Accessibility / Related Components / Additional Resources; frontmatter `title:` = export name.
+- [ ] `src/index.ts` exports the component (in the `./components/*` group).
+- [ ] `scss/components/_index.scss` `@use`s the partial.
+- [ ] Themeable values registered; theming skill references updated in the same PR if applicable.
+- [ ] Prettier-formatted, then `pnpm lint && pnpm test && pnpm build` pass; `pnpm gen:catalog` run.
+- [ ] **Rendered and visually inspected in a browser** — centering/spacing/variants all look
+      right (not just green tests).

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

@@ -1,5 +1,8 @@
 # Reference: Dialog, the canonical worked example
 
+**Library-contributor worked example** — the in-monorepo counterpart to `examples/stat-card.tsx`;
+follow it together with `library-contributor.md`.
+
 `Dialog` is the library's reference implementation of the custom-component pattern. Read the
 real files alongside this:
 
@@ -121,8 +124,8 @@ Dialog also shows optional patterns you can borrow when relevant:
 - **Accessibility**: `role="alertdialog"`, Escape-to-cancel, and focus management on open.
 - **Body scroll lock** via a module-level ref count so chained/overlapping dialogs behave.
 
-These are not required for every component — start from the simple template in `SKILL.md` and
-add only what your component needs.
+These are not required for every component — start from the simple template in
+`library-contributor.md` and add only what your component needs.
 
 ## Other components worth reading for variety
 

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

@@ -96,6 +96,33 @@ and numeric shades `--bulma-<c>-00` … `--bulma-<c>-95`.
 | `--bulma-size-small` / `-normal` / `-medium` / `-large`                       | 0.75 / 1 / 1.25 / 1.5rem          | via `bulmaVars` |
 | `--bulma-weight-light/normal/medium/semibold/bold/extrabold`                  | 300 / 400 / 500 / 600 / 700 / 800 | via `bulmaVars` |
 
+## Extras component variables (Avatar / Avatars / Badge)
+
+These are registered on the component's **own selector** (`.avatar`, `.avatars`, `.badge` —
+`.bestax-avatar` etc. with the prefixed CSS flavor), not on `:root`. A value set on a wrapping
+ancestor — including `Theme`'s `bulmaVars` on a wrapping `Theme` — is only _inherited_ and
+always loses to the component-level declaration, so it will NOT take effect. Working overrides
+target the component's own element instead: redeclare on the component's own class in your CSS
+(mind the class prefix), e.g. `.avatar { --bulma-avatar-size: 3.5rem; }`, or pass a
+`className` and scope the override under it
+(`.avatar.big-avatar { --bulma-avatar-size: 3.5rem; }`), or set it via the component's `style`
+prop. Several default to core theme vars above, so they already flow through a custom theme.
+
+| Variable                                                          | Default                          |
+| ----------------------------------------------------------------- | -------------------------------- |
+| `--bulma-avatar-size`                                             | `48px`                           |
+| `--bulma-avatar-background` / `--bulma-avatar-color`              | `background` / `text`            |
+| `--bulma-avatar-weight`                                           | `weight-semibold`                |
+| `--bulma-avatar-rounded-radius`                                   | `radius-large`                   |
+| `--bulma-avatars-ring-color` / `--bulma-avatars-ring-width`       | `scheme-main` / `2px`            |
+| `--bulma-avatars-spacing`                                         | `0.75rem` (`sm` 0.5 / `lg` 1rem) |
+| `--bulma-badge-height` / `--bulma-badge-min-width`                | `1.25em` / `1.25em`              |
+| `--bulma-badge-padding` / `--bulma-badge-font-size`               | `0 0.4em` / `0.7rem`             |
+| `--bulma-badge-radius`                                            | `radius-rounded`                 |
+| `--bulma-badge-ring-color` / `--bulma-badge-ring-width`           | `scheme-main` / `2px`            |
+| `--bulma-badge-dot-size`                                          | `0.65em`                         |
+| `--bulma-badge-inset-circle` / `--bulma-badge-animation-duration` | `12%` / `1.4s`                   |
+
 ## Dark mode (`Theme colorMode`)
 
 Drive the light/dark scheme with the `Theme` component's **`colorMode`** prop —

package/templates/skills/bestax-theming/references/themeable-components.md

@@ -28,16 +28,18 @@ Shades (`colorShade` / `backgroundColorShade`): `00, 05, 10, … 95, invert, lig
 
 ## Component `color` / `size` props (verbatim unions)
 
-| Component      | `color` accepts                                                                                               | `size` accepts                       | Notes                                                                         |
-| -------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
-| `Button`       | `primary \| link \| info \| success \| warning \| danger \| white \| light \| dark \| black \| text \| ghost` | `small \| normal \| medium \| large` | adds `text`, `ghost`; also `isLight`, `isOutlined`, `isInverted`, `isRounded` |
-| `Notification` | the 17 `validColors`                                                                                          | —                                    | also `isLight`                                                                |
-| `Tag`          | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                  | `normal \| medium \| large`          | also `isRounded`, `isDelete`, `isHoverable`                                   |
-| `Box`          | `primary \| link \| info \| success \| warning \| danger`                                                     | —                                    | the 6 only; also `hasShadow`                                                  |
-| `Message`      | `primary \| link \| info \| success \| warning \| danger`                                                     | —                                    | the 6 only                                                                    |
-| `Input`        | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                  | `small \| medium \| large`           | also `isRounded`, `isStatic`                                                  |
-| `Title`        | — (no `color`; use `textColor`)                                                                               | `1 \| 2 \| 3 \| 4 \| 5 \| 6`         | also `isSpaced`                                                               |
-| `SubTitle`     | — (no `color`; use `textColor`)                                                                               | `1 \| 2 \| 3 \| 4 \| 5 \| 6`         | —                                                                             |
+| Component      | `color` accepts                                                                                               | `size` accepts                                                            | Notes                                                                         |
+| -------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `Button`       | `primary \| link \| info \| success \| warning \| danger \| white \| light \| dark \| black \| text \| ghost` | `small \| normal \| medium \| large`                                      | adds `text`, `ghost`; also `isLight`, `isOutlined`, `isInverted`, `isRounded` |
+| `Notification` | the 17 `validColors`                                                                                          | —                                                                         | also `isLight`                                                                |
+| `Tag`          | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                  | `normal \| medium \| large`                                               | also `isRounded`, `isDelete`, `isHoverable`                                   |
+| `Box`          | `primary \| link \| info \| success \| warning \| danger`                                                     | —                                                                         | the 6 only; also `hasShadow`                                                  |
+| `Message`      | `primary \| link \| info \| success \| warning \| danger`                                                     | —                                                                         | the 6 only                                                                    |
+| `Input`        | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                  | `small \| medium \| large`                                                | also `isRounded`, `isStatic`                                                  |
+| `Avatar`       | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                  | `16x16 \| 24x24 \| 32x32 \| 48x48 \| 64x64 \| 96x96 \| 128x128 \| number` | initials/icon background (auto-derived from `name` when unset); also `shape`  |
+| `Badge`        | `primary \| link \| info \| success \| warning \| danger \| black \| dark \| light \| white`                  | —                                                                         | pill background; default `danger`                                             |
+| `Title`        | — (no `color`; use `textColor`)                                                                               | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                                              | also `isSpaced`                                                               |
+| `SubTitle`     | — (no `color`; use `textColor`)                                                                               | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                                              | —                                                                             |
 
 The 6 brand colors (`primary, link, info, success, warning, danger`) are the ones a custom theme
 recolors via the HSL trios (see `css-variables.md`). The greyscale and `white`/`light`/`dark`