Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,17 @@ Cross out all that don't apply with ~~ ~~ around it like ~~this~~
- [ ] 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?
- [ ] Do you need to update the package version?
- [ ] Did you update the example pages in `.storybook/assets`?
- [ ] 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?

Expand Down
4 changes: 4 additions & 0 deletions .github/workflows/linting.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ jobs:
run: yarn lint:js
- name: Run Stylelint
run: yarn lint:css
- name: Typecheck React components
run: yarn lint:react
- name: Run Prettier
run: yarn prettier-check
- name: Run Tests
Expand All @@ -39,3 +41,5 @@ jobs:
run: yarn build-docs:llms
- name: Build Storybook
run: yarn build-docs:storybook
- name: Build React Storybook and shadcn registry
run: yarn build-docs:react
3 changes: 3 additions & 0 deletions .npmignore
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ docs/
# Documentation
.storybook

# React components are installed with the shadcn CLI, not from this package.
/react/

# Tools and tests. Anchored to the root, so dist/tools (the contrast checker) is still published.
/tools/
/test/
Expand Down
10 changes: 10 additions & 0 deletions .storybook/main.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,16 @@ const config = {
},
],

// Storybook composition: the React components have their own Storybook in react/.
// `yarn build-docs` publishes it under /react on the docs site.
refs: (_config, { configType }) => ({
react: {
title: 'React',
url: configType === 'DEVELOPMENT' ? 'http://localhost:6007' : 'https://docs.optics.rolemodel.design/react',
expanded: false,
},
}),

core: {
disableTelemetry: true, // 👈 Disables telemetry
},
Expand Down
11 changes: 9 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@
"packageManager": "yarn@4.8.1",
"description": "Optics is a css package that provides base styles and components that can be integrated and customized in a variety of projects.",
"main": "dist/css/optics.css",
"workspaces": [
"react"
],
"bin": {
"optics-check-contrast": "dist/tools/check-contrast.cjs"
},
Expand All @@ -14,14 +17,18 @@
"build:css-min": "postcss 'src/optics*.css' -d dist/css --ext .min.css --env=minify",
"build:tokens": "node build_token_json --source=src/core/tokens --output=dist/tokens/tokens.json",
"build:files": "mkdir -p dist/css/addons; cp LICENSE README.md package.json dist/; cp -rL src/addons src/core src/components dist/css; cp -r src/tools dist",
"build-docs": "yarn build-docs:llms && yarn build-docs:storybook",
"build-docs": "yarn build-docs:llms && yarn build-docs:storybook && yarn build-docs:react",
"build-docs:llms": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON tools/build-llms-docs.mjs",
"build-docs:storybook": "storybook build --docs",
"build-docs:react": "yarn workspace @rolemodel/optics-react build-storybook && yarn workspace @rolemodel/optics-react build-registry",
"storybook": "yarn build-docs:llms && storybook dev -p 6006 --docs",
"lint": "yarn lint:js && yarn lint:css",
"storybook:react": "yarn workspace @rolemodel/optics-react storybook",
"set-optics-version": "node tools/set-optics-version.mjs",
"lint": "yarn lint:js && yarn lint:css && yarn lint:react",
"lint-fix": "yarn lint:js --fix && yarn lint:css --fix",
"lint:js": "eslint 'src/stories/**/*.js'",
"lint:css": "stylelint 'src/**/*.css'",
"lint:react": "yarn workspace @rolemodel/optics-react typecheck",
"prettier": "prettier -w .",
"prettier-check": "prettier -c .",
"sanity-check": "yarn lint && yarn prettier && yarn test && yarn build && yarn check-contrast && yarn build-docs && rm -rf ./dist && rm -rf ./storybook-static && rm -rf ./llms-docs",
Expand Down
31 changes: 31 additions & 0 deletions react/.storybook/main.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import { fileURLToPath } from 'node:url'
import type { StorybookConfig } from '@storybook/react-vite'
import remarkGfm from 'remark-gfm'

const config: StorybookConfig = {
stories: ['../stories/**/*.mdx', '../stories/**/*.stories.tsx'],
addons: [
{
name: '@storybook/addon-docs',
// GitHub-flavored Markdown, for the Parts and Props tables in the MDX pages.
options: { mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [remarkGfm] } } },
},
],
framework: '@storybook/react-vite',
core: { disableTelemetry: true },
features: { backgrounds: false },

async viteFinal(viteConfig) {
viteConfig.resolve ??= {}
viteConfig.resolve.alias = {
...viteConfig.resolve.alias,
'@': fileURLToPath(new URL('..', import.meta.url)),
}
// Same reason as the root Storybook: older targets make lightningcss try to polyfill light-dark().
viteConfig.build ??= {}
viteConfig.build.cssTarget = ['chrome123', 'edge123', 'firefox120', 'safari17.5', 'ios17.5']
return viteConfig
},
}

export default config
25 changes: 25 additions & 0 deletions react/.storybook/preview.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
@import '../../src/optics.css';
@import '../../src/addons/fonts/material_symbols_outlined_variable.css';
@import '../../src/addons/fonts/phosphor_icons.css';
@import '../../src/addons/fonts/tabler_icons.css';
@import '../../src/addons/fonts/feather_icons.css';
@import '../../src/addons/fonts/lucide_icons.css';

/* Prism marks JSX tags with .tag, which picks up the Optics .tag component styles. */
pre .token.tag {
display: inline;
padding: 0;
border-radius: 0;
background-color: transparent;
font-size: inherit;
font-weight: inherit;
letter-spacing: inherit;
line-height: inherit;
user-select: text;
white-space: inherit;
}

.sbdocs-preview .docs-story {
background-color: var(--op-color-background);
color: var(--op-color-on-background);
}
64 changes: 64 additions & 0 deletions react/.storybook/preview.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
import type { Decorator, Preview } from '@storybook/react-vite'

import { setIconPack } from '../registry/optics/lib/icon-pack'
import './preview.css'

// The code panel names each component by its displayName. Name compound parts the way they are written,
// so the code reads `<Accordion.Root>` and not `<AccordionRoot>`.
const components = import.meta.glob<Record<string, unknown>>('../registry/optics/ui/*.tsx', { eager: true })
for (const exports of Object.values(components)) {
for (const [exportName, value] of Object.entries(exports)) {
if (!value || typeof value !== 'object') continue
for (const [part, component] of Object.entries(value)) {
if (typeof component === 'function') Object.assign(component, { displayName: `${exportName}.${part}` })
}
}
}

const withThemeMode: Decorator = (Story, context) => {
document.documentElement.setAttribute('data-theme-mode', context.globals.theme)
return <Story />
}

const withIconPack: Decorator = (Story, context) => {
setIconPack(context.globals.iconPack)
return <Story />
}

const preview: Preview = {
parameters: {
layout: 'centered',
docs: {
toc: { headingSelector: 'h2, h3', title: 'On this page' },
// Show the JSX each story renders, with the current args, instead of the story's source.
source: { type: 'dynamic', excludeDecorators: true },
},
options: {
storySort: { order: ['Introduction', 'Components', 'Layout'] },
},
},
globalTypes: {
theme: {
description: 'Global theme mode for components',
toolbar: {
title: 'Theme',
icon: 'circlehollow',
items: ['light', 'dark'],
dynamicTitle: true,
},
},
iconPack: {
description: 'Icon pack for Icon (setIconPack)',
toolbar: {
title: 'Icon pack',
icon: 'star',
items: ['material-symbols', 'phosphor', 'tabler', 'feather', 'lucide'],
dynamicTitle: true,
},
},
},
initialGlobals: { theme: 'light', iconPack: 'material-symbols' },
decorators: [withThemeMode, withIconPack],
}

export default preview
20 changes: 20 additions & 0 deletions react/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Optics React

React components for Optics, published as a [shadcn registry](https://ui.shadcn.com/docs/registry). They are not part of the `@rolemodel/optics` npm package. User docs: [stories/Introduction.mdx](stories/Introduction.mdx).

## Commands

Run from the repo root:

- `yarn storybook:react` — React Storybook on port 6007. The root Storybook (`yarn storybook`) shows it under "React" while both run.
- `yarn lint:react` — typecheck
- `yarn build-docs:react` — build the Storybook into `storybook-static/react/` and the registry into `storybook-static/r/`
- `yarn test` — includes a check that `registry.json` matches the component imports
- `yarn set-optics-version <version>` — bump the Optics version in `package.json`, the `.storybook/assets` example pages, and every React component and MDX page. Then adjust any component the release changed.

## Add a component

1. Add `registry/optics/ui/<name>.tsx`. Line 1 is `// Optics version: X.Y.Z`, and its MDX page says the same version. Both match the root `package.json` version (`yarn test` checks this). Import other registry files as `@/registry/optics/ui/<name>`, so the shadcn CLI can rewrite the path on install. Give it only the options its CSS docs page offers; don't add new ones. To let a part render a different element, use Base UI's `render` prop (`useRender` for plain elements), not `asChild` or `as`.
2. Add an item to [registry.json](registry.json). List each registry file it imports in `registryDependencies` as a full `https://docs.optics.rolemodel.design/r/<name>.json` URL.
3. Add `stories/<name>.stories.tsx` and `stories/<name>.mdx`. Copy the pattern in [accordion.stories.tsx](stories/accordion.stories.tsx) and [accordion.mdx](stories/accordion.mdx): one args-driven `render`, one story per variation on the CSS docs page, and an MDX page with the same sections as the CSS docs.
- The code panel shows the JSX each story returns. Return library components directly, not through local helper components, and pass `undefined` instead of `false` so only real props show.
29 changes: 29 additions & 0 deletions react/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
{
"name": "@rolemodel/optics-react",
"private": true,
"type": "module",
"scripts": {
"storybook": "storybook dev -p 6007 --no-open",
"build-storybook": "storybook build -o ../storybook-static/react",
"build-registry": "shadcn build -o ../storybook-static/r",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"@base-ui/react": "^1.9.0",
"class-variance-authority": "^0.7.1"
},
"devDependencies": {
"@storybook/addon-docs": "^10.6.3",
"@storybook/react-vite": "^10.6.3",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"@vitejs/plugin-react": "^6.2.1",
"react": "19.1.1",
"react-dom": "19.1.1",
"remark-gfm": "^4.0.1",
"shadcn": "^4.23.0",
"storybook": "^10.6.3",
"typescript": "^6.0.3",
"vite": "^8.1.4"
}
}
Loading
Loading