feat(bulma-ui): compound (dot-notation) sub-components for all parent/child families via shared withSubComponents helper

[allxsmith]

Pull Request

Description

Adds compound (dot-notation) sub-component access across the library and converges every compound parent onto one shared, typed attachment helper. Two commits:

1. refactor(bulma-ui) — new internal helper src/helpers/withSubComponents.ts that attaches statics by mutating the base component (identity-preserving — Modal's child.type === ModalCard check and Field's displayName-based child detection depend on it) and sets displayName on the parent. All 17 existing compound parents (Card, Navbar, Tabs, Modal, Message, Field, Media, Level, Hero, Panel, Pagination, Dropdown, Menu, Sidebar, Steps, Avatars, Figure) migrated off three divergent idioms (Object.assign / inline intersection types / *WithCompounds casts). Also fixes the named Media export, which previously lacked the statics in its type (only the default export had them).
2. feat(bulma-ui) — 10 new compound families, every existing named export unchanged (purely additive): Columns.Column, Grid.Cell, Table.Thead/.Tbody/.Tfoot/.Tr/.Th/.Td (exact export names), Buttons.Button/Buttons.LinkButton, Tags.Tag, OrderedList.Item, UnorderedList.Item, IconText.Icon, Checkboxes.Checkbox, Radios.Radio, and Field.Control (joining Field.Label/Field.Body).

Each new family ships with identity + dot-path render tests, a CompoundUsage story, and a ### Compound (dot-notation) usage live example on its API docs page. The skill catalog header now cites the new dot paths (Columns.Column, Table.Tr) and the layout-scaffold skill references mention them; catalog regenerated via pnpm gen:catalog.

• bulma-ui (@allxsmith/bestax-bulma)
• create-bestax (create-bestax)
• docs (@allxsmith/bestax-docs)
• Other (please specify): skills (generated catalog + layout-scaffold references), scripts/gen-component-catalog.mjs header text

Related Issue(s)

Refs #330 (follow-up: parity artifacts for the 17 pre-existing compound families + codifying the standard in CLAUDE.md)

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation
• Performance
• Build tooling
• Other (please describe):

Checklist

• My code follows the project style guidelines
• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works
• I have added/updated documentation as needed
• I have updated Storybook stories as needed (bulma-ui)
• My changes require a change to the documentation
• All new and existing tests passed
• Any relevant dependencies are updated
• If this PR changes commands, conventions, or package structure, the affected CLAUDE.md files are updated

Screenshots / Demos

// Before: separate imports required          // After: dot notation also works
<Columns>                                     <Columns>
  <Column>One</Column>                          <Columns.Column>One</Columns.Column>
</Columns>                                    </Columns>

<Table>
  <Table.Thead>
    <Table.Tr><Table.Th>Name</Table.Th></Table.Tr>
  </Table.Thead>
</Table>

Live examples render on each affected API docs page (the live-codeblock scope spreads the full library, so dot statics resolve in the browser preview).

Additional Context

• Full gate green locally: pnpm all (build, typecheck, tests + 99% coverage on all metrics, bundle:stats, lint, format:check, storybook build) and pnpm check:conformance; catalog freshness verified.
• Net release: one minor bump of @allxsmith/bestax-bulma (feat outranks the refactor patch).
• The helper is internal-only (not exported from src/index.ts), so no new public API beyond the statics themselves.
• CLAUDE.md convention updates are deliberately deferred to Compound component parity: identity tests, CompoundUsage stories, and live docs sections for pre-existing compound families #330 alongside the parity work.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NuJRpjY81Dzoo92ZooE8Xt

---

Generated by Claude Code

Summary by CodeRabbit

• New Features
  • Added dot-notation compound component access across layout, form, element, and navigation components, including Table.Tr, Columns.Column, Field.Control, and others.
  • Added Storybook examples demonstrating compound component composition.
• Documentation
  • Added usage guidance and examples for compound components throughout the component documentation.
  • Updated component catalog references with additional dot-notation examples.
• Tests
  • Added coverage validating compound component references, rendering, and ref forwarding.

[coderabbitai]

Walkthrough

Adds withSubComponents and applies it across Bulma UI components to expose compound subcomponents through dot notation. Adds tests, Storybook examples, and documentation for the resulting APIs.

Changes

Compound component foundation

Layer / File(s)	Summary
Shared helper and coverage bulma-ui/src/helpers/withSubComponents.ts, bulma-ui/src/helpers/__tests__/withSubComponents.test.tsx	Adds withSubComponents, which attaches subcomponents, preserves identity, manages display names, and supports forward-ref components.
Component and layout wiring bulma-ui/src/components/*, bulma-ui/src/layout/*	Replaces manual static-property assignments and casts with withSubComponents exports while preserving existing component implementations.
New compound APIs bulma-ui/src/columns/*, bulma-ui/src/elements/*, bulma-ui/src/form/*, bulma-ui/src/grid/*	Exposes subcomponents such as Columns.Column, Table.Tr, Field.Control, and Grid.Cell, with Storybook examples demonstrating dot notation.
Compound API tests bulma-ui/src/**/__tests__/*	Verifies subcomponent identity and rendered DOM structure through compound-component access paths.
Documentation and catalogs docs/docs/api/*, scripts/gen-component-catalog.mjs, skills/*	Documents compound usage and updates catalog examples with additional dot-notation forms.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• allxsmith/bestax#330 — The PR implements the compound-component foundation and related parity artifacts described by this issue.

Possibly related PRs

• allxsmith/bestax#267 — Both changes update Columns.stories.tsx, connecting the compound-usage story with Storybook conformance metadata.

Suggested labels: deep-review

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the PR’s main change: introducing dot-notation subcomponents via withSubComponents across bulma-ui.
Description check	✅ Passed	The description follows the template closely, covering affected packages, change type, tests, docs, stories, demos, and context.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/bestax-compound-expressions-w7vdi7

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Preview Deployment

Preview URL: https://81e3c99c.bestax.pages.dev

[coderabbitai]

🧹 Nitpick comments (2)

bulma-ui/src/elements/__tests__/IconText.test.tsx (1)

187-197: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Prefer React Testing Library semantic queries over container.querySelector.

React Testing Library best practices strongly discourage using querySelector as it tightly couples tests to DOM structure. Consider refactoring this test to use semantic queries (getByText, getByLabelText) matching the pattern used in the rest of this test file.

♻️ Proposed refactor

-  test('renders an icon through the dot path', () => {
-    const { container } = render(
+  test('renders an icon through the dot path', () => {
+    render(
       <IconText>
         <IconText.Icon name="star" ariaLabel="star icon" />
         Starred
       </IconText>
     );
-    expect(container.querySelector('.icon-text')).toBeInTheDocument();
-    expect(container.querySelector('.icon')).toBeInTheDocument();
+    expect(screen.getByText('Starred').parentElement).toHaveClass('icon-text');
+    expect(screen.getByLabelText('star icon')).toHaveClass('icon');
   });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bulma-ui/src/elements/__tests__/IconText.test.tsx` around lines 187 - 197,
Refactor the test “renders an icon through the dot path” to replace both
container.querySelector assertions with React Testing Library semantic queries.
Use the existing accessible label for the icon and the rendered “Starred” text,
while preserving the assertions that the icon text component and icon are
present.

bulma-ui/src/grid/Grid.stories.tsx (1)

256-265: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use types from @storybook/react-vite and CSF3 format.

To align with the project's Storybook conventions and other files in this PR, please define the story using the CSF3 object format with the appropriate type from @storybook/react-vite (e.g., Story or StoryObj). As per coding guidelines: bulma-ui/src/**/*.stories.{ts,tsx}: Use types from @storybook/react-vite``.

♻️ Proposed refactor

-export const CompoundUsage = () => (
-  <Grid>
-    <Grid.Cell>
-      <Notification color="primary">Cell via dot notation</Notification>
-    </Grid.Cell>
-    <Grid.Cell>
-      <Notification color="info">Another cell via dot notation</Notification>
-    </Grid.Cell>
-  </Grid>
-);
+export const CompoundUsage: Story = {
+  render: () => (
+    <Grid>
+      <Grid.Cell>
+        <Notification color="primary">Cell via dot notation</Notification>
+      </Grid.Cell>
+      <Grid.Cell>
+        <Notification color="info">Another cell via dot notation</Notification>
+      </Grid.Cell>
+    </Grid>
+  ),
+};

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bulma-ui/src/grid/Grid.stories.tsx` around lines 256 - 265, Convert
CompoundUsage from the function story format to a CSF3 object story, and type it
with the appropriate Story or StoryObj type imported from `@storybook/react-vite`.
Preserve the existing Grid and Grid.Cell rendering content.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@bulma-ui/src/elements/__tests__/IconText.test.tsx`:
- Around line 187-197: Refactor the test “renders an icon through the dot path”
to replace both container.querySelector assertions with React Testing Library
semantic queries. Use the existing accessible label for the icon and the
rendered “Starred” text, while preserving the assertions that the icon text
component and icon are present.

In `@bulma-ui/src/grid/Grid.stories.tsx`:
- Around line 256-265: Convert CompoundUsage from the function story format to a
CSF3 object story, and type it with the appropriate Story or StoryObj type
imported from `@storybook/react-vite`. Preserve the existing Grid and Grid.Cell
rendering content.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 81034d2c-f662-4bc4-b7c0-dc7a3f675a25

📥 Commits

Reviewing files that changed from the base of the PR and between dd2c479 and e7dc08b.

📒 Files selected for processing (65)

• bulma-ui/src/columns/Columns.stories.tsx
• bulma-ui/src/columns/Columns.tsx
• bulma-ui/src/columns/__tests__/Columns.test.tsx
• bulma-ui/src/components/Avatars.tsx
• bulma-ui/src/components/Card.tsx
• bulma-ui/src/components/Dropdown.tsx
• bulma-ui/src/components/Menu.tsx
• bulma-ui/src/components/Message.tsx
• bulma-ui/src/components/Modal.tsx
• bulma-ui/src/components/Navbar.tsx
• bulma-ui/src/components/Pagination.tsx
• bulma-ui/src/components/Panel.tsx
• bulma-ui/src/components/Sidebar.tsx
• bulma-ui/src/components/Steps.tsx
• bulma-ui/src/components/Tabs.tsx
• bulma-ui/src/elements/Buttons.stories.tsx
• bulma-ui/src/elements/Buttons.tsx
• bulma-ui/src/elements/Figure.tsx
• bulma-ui/src/elements/IconText.stories.tsx
• bulma-ui/src/elements/IconText.tsx
• bulma-ui/src/elements/OrderedList.stories.tsx
• bulma-ui/src/elements/OrderedList.tsx
• bulma-ui/src/elements/Table.stories.tsx
• bulma-ui/src/elements/Table.tsx
• bulma-ui/src/elements/Tags.stories.tsx
• bulma-ui/src/elements/Tags.tsx
• bulma-ui/src/elements/UnorderedList.stories.tsx
• bulma-ui/src/elements/UnorderedList.tsx
• bulma-ui/src/elements/__tests__/Buttons.test.tsx
• bulma-ui/src/elements/__tests__/IconText.test.tsx
• bulma-ui/src/elements/__tests__/OrderedList.test.tsx
• bulma-ui/src/elements/__tests__/Table.test.tsx
• bulma-ui/src/elements/__tests__/Tags.test.tsx
• bulma-ui/src/elements/__tests__/UnorderedList.test.tsx
• bulma-ui/src/form/Checkboxes.stories.tsx
• bulma-ui/src/form/Checkboxes.tsx
• bulma-ui/src/form/Field.stories.tsx
• bulma-ui/src/form/Field.tsx
• bulma-ui/src/form/Radios.stories.tsx
• bulma-ui/src/form/Radios.tsx
• bulma-ui/src/form/__tests__/Checkboxes.test.tsx
• bulma-ui/src/form/__tests__/Field.test.tsx
• bulma-ui/src/form/__tests__/Radios.test.tsx
• bulma-ui/src/grid/Grid.stories.tsx
• bulma-ui/src/grid/Grid.tsx
• bulma-ui/src/grid/__tests__/Grid.test.tsx
• bulma-ui/src/helpers/__tests__/withSubComponents.test.tsx
• bulma-ui/src/helpers/withSubComponents.ts
• bulma-ui/src/layout/Hero.tsx
• bulma-ui/src/layout/Level.tsx
• bulma-ui/src/layout/Media.tsx
• docs/docs/api/columns/columns.md
• docs/docs/api/elements/buttons.md
• docs/docs/api/elements/icontext.md
• docs/docs/api/elements/orderedlist.md
• docs/docs/api/elements/table.md
• docs/docs/api/elements/tags.md
• docs/docs/api/elements/unorderedlist.md
• docs/docs/api/form/checkboxes.md
• docs/docs/api/form/field.md
• docs/docs/api/form/radios.md
• docs/docs/api/grid/grid.md
• scripts/gen-component-catalog.mjs
• skills/bestax-custom-component/references/component-catalog.md
• skills/bestax-layout-scaffold/references/layout-components.md

[allxsmith]

@claude deep review

[claude]

Claude finished @allxsmith's task in 4m 17s —— View job

---

Deep review

• Gather context (PR description, diff, CodeRabbit review)
• Read withSubComponents helper and its tests
• Review migrated existing compound parents (Card, Modal, Field, Sidebar, etc.) for identity-preservation correctness
• Review new compound families (Columns, Table, Buttons, Tags, lists, IconText, Checkboxes, Radios, Field.Control)
• Check TypeScript typing correctness of the helper across ref-forwarding components
• Check docs/stories consistency
• Post final review

Setup note: this sandbox's git fetch/pnpm install require interactive approval that wasn't available in this run, so I reviewed by reading the checked-out branch directly rather than running pnpm all/tests. Nothing below depends on that — it's all confirmed by tracing the render logic.

withSubComponents helper — looks solid

bulma-ui/src/helpers/withSubComponents.ts mutates and returns the same function object via Object.assign, which is exactly what identity checks like child.type === ModalCard (Modal.tsx:334-337) and child.type === CardHeader (Card.tsx:82-88, still valid since CardHeaderCompound = withSubComponents(CardHeader, {...}) returns the same CardHeader reference) depend on. Verified this across Modal, Card, Field, and the forwardRef case (Sidebar/Control) — all consistent. The helper's own tests (withSubComponents.test.tsx) cover identity, static attachment, displayName behavior, and the forwardRef case well.

Bug: IconText's dot-notation form produces different (broken) markup than the prop-based form

bulma-ui/src/elements/IconText.tsx:79-96:

return (
  <span className={iconTextClasses} {...rest}>
    {items ? (
      ...
    ) : (
      <>
        {iconProps && <Icon {...iconProps} />}
        {children && <span>{children}</span>}
      </>
    )}
  </span>
);

The prop-based API (<IconText iconProps={...}>Star</IconText>) renders Icon and the text <span> as siblings directly under .icon-text — correct per Bulma's .icon-text flex layout spec.

But the new dot-notation form (<IconText><IconText.Icon .../>Starred</IconText>) doesn't pass iconProps at all — everything arrives via children. Since iconProps is undefined, the iconProps && <Icon .../> branch renders nothing, and the whole children (including IconText.Icon) falls into {children && <span>{children}</span>}. That means the actual DOM is:

<span class="icon-text">
  <span>
    <span class="icon">...</span>
    Starred
  </span>
</span>

i.e. Icon and the text end up nested inside an extra wrapping <span> instead of being direct flex children of .icon-text. This breaks Bulma's icon/text alignment and spacing (.icon-text relies on being a flex container of its direct children).

This isn't just a theoretical edge case — it's the shape used in the new test (bulma-ui/src/elements/__tests__/IconText.test.tsx:187-197), the story (IconText.stories.tsx:311-317), and the live docs example (docs/docs/api/elements/icontext.md:265-270), so the shipped "recommended" dot-notation usage renders incorrect markup. The existing test only asserts .icon-text and .icon are present in the document (container.querySelector), which doesn't catch the extra wrapper — that's also why CodeRabbit's suggestion to switch to getByText(...).parentElement semantic queries would have caught this if applied literally (that assertion would fail as written, since Icon's parent is the inner <span>, not .icon-text).

Fix: IconTextComponent needs to render raw compound children (IconText.Icon + text) as direct children of .icon-text, the same way Buttons/Tags/Columns/etc. do, rather than routing everything through the iconProps/children-wrapped-in-<span> branch built for the legacy single-icon API. Fix this →

Everything else checked out

• Table, Buttons, Tags, Columns, Grid, Checkboxes/Radios, OrderedList/UnorderedList, Field.Control: all render children straight through, so no equivalent double-wrap risk — dot-notation composition matches the plain import composition exactly.
• No circular-import issues between Field/Control/Checkboxes/Radios.
• CodeRabbit's two nitpicks are reasonable but low-severity style/consistency items (RTL semantic queries in IconText.test.tsx, CSF3 object format for Grid.stories.tsx's CompoundUsage) — worth picking up, not blocking.

Summary

One real, user-facing correctness bug (IconText dot-notation markup), otherwise the withSubComponents convergence is careful and correctly preserves the identity invariants the codebase depends on.

[claude]

Deep review — 0 finding(s)

#	Severity	Area	Finding	Location
—	—	—	No blocking defects found.	—

Overall: This is a genuinely clean refactor-plus-additive-feature. The new withSubComponents helper mutates the base component in place and returns the same object, which correctly preserves every identity check in the library (child.type === ModalCard/CardHeader/TabsContent/MenuList) and Field's displayName-based child detection — I verified this by grepping all .type === / displayName === sites and running the affected suites (268 tests pass across Modal, Card, Tabs, Field, Checkboxes, Radios, Table, Buttons, Media). Typecheck is clean, the named Media export type bug is properly fixed, and no file lost a default export or introduced a parent-child import cycle. The riskiest surface — the shared helper touching 17 compound families at once — is well covered by the new identity/dot-path tests and the forwardRef case, so the human's attention only needs a light pass on whether the 11 new CompoundUsage stories/docs read well.

🏄 Total glass, dude — 28 components all paddling out on one clean helper, every === identity wave still lands, nothing wipes out. Ship it and catch the next set.

[github-actions]

🎉 This PR is included in version 5.7.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 3.5.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀