Skip to content

Add React components as a shadcn registry - #376

Open
Jeremy-Walton wants to merge 8 commits into
mainfrom
worktree-react-components
Open

Jeremy-Walton wants to merge 8 commits into
mainfrom
worktree-react-components

Conversation

@Jeremy-Walton

@Jeremy-Walton Jeremy-Walton commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Why?

React apps using Optics had to write and manage their components by hand. This adds them here as a shadcn registry, so apps copy typed components that match the current Optics classes and docs.

The components ship from the docs site (/r), not in the npm package, and the registry links resolve only after the first release deploys the docs.

What Changed

What changed in this PR?

  • Add 32 React components on Base UI and cva, published as a shadcn registry
  • Add a React Storybook at /react, composed into the docs under "React"
  • Add @base-ui/react, class-variance-authority, and shadcn in a new react/ workspace
  • Add yarn set-optics-version to bump the version everywhere, including each component
  • Type-check and build the React docs in CI, and add React checks to the PR template

Quality Assurance

  • Have you tagged the PR with the correct labels?
  • Have you validated the changes?
    • Have you run linters? (yarn sanity-check)
    • Have you run prettier?
    • Have you tried building the css?
    • Have you tried building storybook?
  • Have you updated any usage of changed tokens?
  • Did you add a component?
    • Have you added it to the dependency graph?
    • Have you added it to the docs?
    • Have you added a React component, or noted why not? (see react/README.md)
  • Did you update a component?
    • Have you updated the dependency graph?
    • Have you updated the docs?
    • Have you updated the React component in react/registry/optics/ui/, with its stories and MDX page, to match?
  • Did you change a React component?
    • Have you updated react/registry.json if its imports changed?
    • Have you checked it in the React Storybook? (yarn storybook:react)
  • Do you need to update the package version? Don't edit it by hand. Run yarn set-optics-version <version>, such as yarn set-optics-version 2.6.2. It sets the version in package.json, the .storybook/assets example pages, and every React component.
    • Have you run yarn set-optics-version <version>?
    • Have you adjusted the React components for this release?
  • Were any changes made to the top level optics.css file?
    • Were those changes reflected in the other top level files?

Screenshots

The React docs are composed into the main docs under "React". Each component page shows its Optics version, the shadcn install command, a playground, and every CSS variation. The code panel shows the JSX each story renders, with compound parts named like Alert.Root.

Button docs with the code panel open

Alert docs with the code panel open

Form docs with the code panel open

Jeremy-Walton and others added 6 commits November 5, 2026 17:34
Bring the components from optics-components-react into a react/
workspace. They ship as a shadcn registry, not in the npm package.

- 32 components on Base UI and cva, with kebab-case shadcn paths
- Split Alert.Flash from Alert.Root and Tabs.Nav from Tabs.List
- React Storybook, composed into the main Storybook under "React"
- build-docs publishes it to /react and the registry to /r
- Test that registry.json matches each file's imports

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each component gets an MDX page with the same sections and variations
as its CSS docs page, and an args-driven story file so every option is
in Controls.

- Code panel shows the JSX each story renders, named like Accordion.Root
- Reset Optics .tag styles on Prism tokens in code blocks
- Render MDX tables with remark-gfm
- Avatar renders a div by default, so a plain avatar has no hover state
- Layout components take only the options the CSS docs offer:
  align and gap on Cluster, Split, Stack; end and gap on Flank

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Plan: current status, next steps for review, PR, and release checks
- README: give components only the options their CSS docs offer, and
  copy the Accordion story and MDX pattern for new docs pages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each React component states the Optics version it was checked against,
and the PR template asks about the React component when a CSS
component changes.

- Line 1 of each component and its MDX page say the Optics version;
  the registry test checks they match
- PR template: React checks for added, updated, and changed components
- Boolean cva variants drop `false: null`
- lib/dialog.tsx shares the Modal and Confirm Dialog trigger and close
  handler, and replaces lib/invoker-commands.ts
- Layout stories share helpers; story args use component prop types
- Text Pair shares one size map; Form.Textarea and Form.Select share
  one native control
- Stop exporting unused part variants; drop an unused env override,
  empty registry dependencies, and a duplicate test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every Optics release sets all React components to the new version, and
the React parts now cover the variations the CSS docs show.

- `yarn set-optics-version:react` sets each component and MDX page to
  the root package.json version; the registry test fails until they match
- PR template: run it with a version bump; drop the per-component bump
- Pagination.Link `shape`, Navbar.Content `render`, Form.Control
  `indeterminate`, TableContainer, and Frame `inlineSize`
- Form label, hint, and error render plain elements outside a Form.Group
- Icon packs through setIconPack() in lib/icon-pack.ts, adapted from
  experiment/restructure; Icon takes `duotone` and `weight="thin"`
- Storybook toolbar to switch icon packs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`yarn set-optics-version <version>` bumps package.json, the
.storybook/assets example pages, and every React component and MDX
page, so a version bump is one step.

- Move the script to tools/ and take the version as an argument
- PR template prompts for the command instead of a hand edit
- Test failure message names the command with the version

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Jeremy-Walton Jeremy-Walton added Components Changes to a component Repository Change Changes to the repository that don't affect the package code labels Nov 9, 2026
@Jeremy-Walton Jeremy-Walton self-assigned this Nov 9, 2026
The plan's work is done, and its one open convention moves to the
React README. The launch file only served one local setup and would
clash with an untracked launch file in the main checkout.

- README: use Base UI's render prop to change a part's element

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Jeremy-Walton
Jeremy-Walton requested review from BenEinwechter, dallasbpeters and zoopmaster and a balanced review from Copilot and removed request for zoopmaster November 9, 2026 21:01

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved icon-pack incompatibilities, incorrect toast timing, and accessibility and duplicate-ID defects cause missing controls, premature visual dismissal, and broken interactions in supported configurations and examples.

10 open issues
What changed in this PR

Adds 32 typed React components as a shadcn registry served from the Optics documentation site, rather than bundled in the npm package. A dedicated React Storybook provides installation guidance, interactive examples, and API documentation.

Changes:

  • Adds React components using Optics styles, Base UI behavior, and cva variants.
  • Composes the React Storybook into the existing documentation.
  • Adds workspace dependencies, registry validation, and synchronized version-update tooling.
  • Integrates React type-checking, documentation builds, and contributor checks.

This pull request requires changes. Unresolved moderate findings affect icon-pack compatibility, toast timing, disabled-control behavior, RTL tooltip styling, and example correctness and accessibility.

File Description
tools/​set-optics-version.mjs Synchronizes package, example, component, and documentation versions.
test/​react/​registry.test.cjs Checks registry dependencies and component version consistency.
react/​tsconfig.json Configures strict React TypeScript checks.
react/​stories/​tooltip.stories.tsx Demonstrates tooltip positions and trigger types.
react/​stories/​tooltip.mdx Documents tooltip behavior and customization.
react/​stories/​text-pair.stories.tsx Demonstrates text-pair sizing and inline layouts.
react/​stories/​text-pair.mdx Documents title/subtitle composition.
react/​stories/​tag.stories.tsx Demonstrates tag variants and optional buttons.
react/​stories/​tag.mdx Documents tag composition and removal controls.
react/​stories/​tabs.stories.tsx Demonstrates navigation tabs and interactive panels.
react/​stories/​tabs.mdx Documents both tab composition patterns.
react/​stories/​table.mdx Documents table variants, sticky sections, and pagination.
react/​stories/​switch.stories.tsx Demonstrates switches; instance-specific IDs are needed to prevent misdirected labels.
react/​stories/​switch.mdx Documents switches; duplicate story mounts produce conflicting input IDs.
react/​stories/​stack.stories.tsx Demonstrates vertical-stack alignment variations.
react/​stories/​stack.mdx Documents stack layout controls.
react/​stories/​split.stories.tsx Demonstrates distributed-row alignment.
react/​stories/​split.mdx Documents split layout controls.
react/​stories/​spinner.stories.tsx Demonstrates spinner sizes.
react/​stories/​spinner.mdx Documents loading indicators and accessible labels.
react/​stories/​sidebar.stories.tsx Demonstrates drawer, compact, and rail configurations.
react/​stories/​sidebar.mdx Documents sidebar sizing and content placement.
react/​stories/​side-panel.stories.tsx Demonstrates panel sections, borders, and padding.
react/​stories/​side-panel.mdx Documents panel composition and scrolling.
react/​stories/​segmented-control.stories.tsx Demonstrates radio segments, sizes, and icons.
react/​stories/​segmented-control.mdx Documents segmented-control structure and behavior.
react/​stories/​pagination.stories.tsx Demonstrates page links and page-size selection.
react/​stories/​pagination.mdx Documents pagination composition.
react/​stories/​navbar.stories.tsx Demonstrates branding and navigation alignment.
react/​stories/​navbar.mdx Documents navbar composition.
react/​stories/​modal.stories.tsx Demonstrates native dialogs; examples need explicit accessible names.
react/​stories/​modal.mdx Documents modal behavior and browser requirements.
react/​stories/​layout-helpers.tsx Shares layout-demo content and controls.
react/​stories/​Introduction.mdx Explains setup, registry installation, and component ownership.
react/​stories/​icon.mdx Documents icon packs, SVGs, and styling variants.
react/​stories/​grid.stories.tsx Demonstrates grid columns and spacing.
react/​stories/​grid.mdx Documents grid layout properties.
react/​stories/​frame.stories.tsx Demonstrates aspect ratios and width constraints.
react/​stories/​frame.mdx Documents frame sizing and media behavior.
react/​stories/​form.mdx Documents form controls, grouping, and validation.
react/​stories/​flank.stories.tsx Demonstrates asymmetric layouts and avatar compositions.
react/​stories/​flank.mdx Documents flank behavior and spacing.
react/​stories/​divider.stories.tsx Demonstrates separator orientation, thickness, and spacing.
react/​stories/​divider.mdx Documents divider properties and semantics.
react/​stories/​content-header.stories.tsx Demonstrates header content, sections, and actions.
react/​stories/​content-header.mdx Documents structured header parts.
react/​stories/​confirm-dialog.stories.tsx Demonstrates confirmation actions; needs unique instance IDs and an accessible dialog name.
react/​stories/​confirm-dialog.mdx Documents confirmation dialogs; duplicate mounts cause invokers to target the wrong instance.
react/​stories/​cluster.stories.tsx Demonstrates wrapping-row alignment.
react/​stories/​cluster.mdx Documents cluster layout behavior.
react/​stories/​card.stories.tsx Demonstrates card sections, padding, and shadows.
react/​stories/​card.mdx Documents card composition and styling.
react/​stories/​button.stories.tsx Demonstrates button styles, states, and render targets.
react/​stories/​button.mdx Documents button properties and variations.
react/​stories/​button-group.stories.tsx Demonstrates grouped buttons and toolbars.
react/​stories/​button-group.mdx Documents button-group composition.
react/​stories/​breadcrumbs.stories.tsx Demonstrates breadcrumb sizes and separators.
react/​stories/​breadcrumbs.mdx Documents breadcrumb navigation composition.
react/​stories/​badge.stories.tsx Demonstrates badge variants and notification placement.
react/​stories/​badge.mdx Documents badges and notifications.
react/​stories/​avatar.stories.tsx Demonstrates avatar images, fallbacks, sizes, and links.
react/​stories/​avatar.mdx Documents avatar composition and variants.
react/​stories/​alert.stories.tsx Demonstrates alerts and toasts; generated examples need escaped title and description literals.
react/​stories/​alert.mdx Documents alerts, dismissal, and toast setup.
react/​stories/​accordion.stories.tsx Demonstrates disclosure configurations and grouping.
react/​stories/​accordion.mdx Documents accordion parts and behavior.
react/​registry/​optics/​ui/​tooltip.tsx Adds portaled Base UI tooltips.
react/​registry/​optics/​ui/​tooltip.module.css Styles tooltip popups and arrows; physical side offsets need RTL correction.
react/​registry/​optics/​ui/​text-pair.tsx Adds title/subtitle sizing and inline layouts.
react/​registry/​optics/​ui/​tag.tsx Adds tag containers, variants, and labels.
react/​registry/​optics/​ui/​tabs.tsx Adds panel tabs and navigation links; disabled links must suppress navigation and activation.
react/​registry/​optics/​ui/​table.tsx Adds table variants and sticky containers.
react/​registry/​optics/​ui/​switch.tsx Adds styled native checkbox switches.
react/​registry/​optics/​ui/​stack.tsx Adds vertical-stack layout properties.
react/​registry/​optics/​ui/​split.tsx Adds distributed-row layouts.
react/​registry/​optics/​ui/​spinner.tsx Adds loading indicators with status text.
react/​registry/​optics/​ui/​sidebar.tsx Adds sidebar sizes and content positioning.
react/​registry/​optics/​ui/​side-panel.tsx Adds panel sections and padding variants.
react/​registry/​optics/​ui/​segmented-control.tsx Adds grouped native radio options.
react/​registry/​optics/​ui/​pagination.tsx Adds pagination links and dividers.
react/​registry/​optics/​ui/​navbar.tsx Adds navbar branding and content sections.
react/​registry/​optics/​ui/​modal.tsx Adds native modal parts; the default close glyph needs supported-pack compatibility.
react/​registry/​optics/​ui/​icon.tsx Adds font and inline-SVG icons.
react/​registry/​optics/​ui/​grid.tsx Adds grid column and spacing variants.
react/​registry/​optics/​ui/​frame.tsx Adds aspect-ratio and width controls.
react/​registry/​optics/​ui/​flank.tsx Adds asymmetric two-item layouts.
react/​registry/​optics/​ui/​divider.tsx Adds separator orientation, thickness, and spacing.
react/​registry/​optics/​ui/​content-header.tsx Adds compound page-header sections.
react/​registry/​optics/​ui/​confirm-dialog.tsx Adds native confirmation-dialog components.
react/​registry/​optics/​ui/​cluster.tsx Adds wrapping-row layout properties.
react/​registry/​optics/​ui/​card.tsx Adds card sections and styling variants.
react/​registry/​optics/​ui/​button.tsx Maps button properties to Optics variants and Base UI behavior.
react/​registry/​optics/​ui/​button-group.tsx Adds a styled button-group container.
react/​registry/​optics/​ui/​breadcrumbs.tsx Adds breadcrumb parts; the default separator needs supported-pack compatibility.
react/​registry/​optics/​ui/​badge.tsx Adds badge variants and notification positioning.
react/​registry/​optics/​ui/​avatar.tsx Adds styled avatars; interactive roots need disabled semantics and activation suppression.
react/​registry/​optics/​ui/​alert.tsx Adds alerts and toasts; dismissal timing and both close-button glyphs need correction.
react/​registry/​optics/​ui/​accordion.tsx Adds native disclosures; the default marker needs pack-aware resolution.
react/​registry/​optics/​lib/​icon-pack.ts Resolves glyph names for supported icon packs.
react/​registry/​optics/​lib/​flex-utilities.ts Shares alignment and spacing variants.
react/​registry/​optics/​lib/​dialog.tsx Shares dialog trigger and close behavior.
react/​README.md Documents contributor workflows and component conventions.
react/​package.json Defines React dependencies and workspace scripts.
react/​.storybook/​preview.tsx Configures themes, icon packs, and source display.
react/​.storybook/​preview.css Loads Optics styles and adjusts documentation presentation.
react/​.storybook/​main.ts Configures React stories, MDX tables, and aliases.
package.json Adds the React workspace and build, validation, and version commands.
.storybook/​main.js Composes the React Storybook into existing documentation.
.npmignore Excludes React sources from npm publication.
.github/​workflows/​linting.yml Adds React type-checking and documentation/registry builds.
.github/​pull_request_template.md Adds React maintenance, validation, and version-update checks.

Review effort: Balanced

Comment thread react/registry/optics/ui/accordion.tsx Resolved
Comment thread react/registry/optics/ui/alert.tsx Resolved
Comment thread react/registry/optics/ui/alert.tsx Resolved
Comment thread react/registry/optics/ui/avatar.tsx Resolved
Comment thread react/registry/optics/ui/modal.tsx Resolved
Comment thread react/stories/modal.stories.tsx Resolved
Comment thread react/stories/switch.stories.tsx Resolved
- Resolve built-in close and arrow icons for the selected icon pack
- Let Base UI time flash toasts and slide them with a transition
- Make disabled linked avatars leave the tab order and ignore clicks
- Give story dialogs accessible names and per-instance ids

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@dallasbpeters dallasbpeters left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! :shipit:

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Components Changes to a component Repository Change Changes to the repository that don't affect the package code

Development

Successfully merging this pull request may close these issues.

3 participants