@byline/ui 6.8.0 → 6.10.0

package/README.md

@@ -1,8 +1,8 @@
 # @byline/ui
 
-Shared UI package for Byline CMS — the field-rendering primitives, form
-context and patch-emitting field widgets, the `BylineFieldServicesProvider`
-context, and other shared components consumed by the admin UI.
+Framework-independent React primitives for Byline CMS, including buttons,
+inputs, overlays, icons, and drag-and-drop components. CMS field widgets and
+document-editor forms belong to `@byline/admin`.
 
 This package is part of [Byline CMS](https://github.com/Byline-CMS/bylinecms.dev)
 — a developer-friendly, open-source headless CMS with versioning, editorial
@@ -22,8 +22,46 @@ change originates**: a change made here is ported upstream, a change made
 upstream is ported here. Either copy may be edited directly; neither is the sole
 source of truth.
 
-Byline-specific code (`admin/`, `dnd/`, `fields/`, `forms/`, `services/`, and
-`react.ts`) lives only in this package and has no upstream counterpart.
+Byline's `dnd/` components and `react.ts` entry point have no upstream counterpart.
+
+## Storybook
+
+Storybook lets you inspect and interact with the UI primitives without starting
+the CMS or a database. The stories are ported from the sibling UI kit and live
+beside their components in `src/**/*.stories.tsx`.
+
+After installing the workspace dependencies, run from the repository root:
+
+```sh
+pnpm storybook
+```
+
+Open <http://localhost:6007>. The preview includes the UI kit's reset, theme,
+typography, local fonts, drawer provider, and toast provider. Use the toolbar
+to switch between light and dark themes. The accessibility panel runs checks
+against the selected story; documentation pages and controls are also available.
+
+Build a static site with:
+
+```sh
+pnpm build-storybook
+```
+
+The output is `packages/ui/storybook-static/`, which is ignored by Git.
+Both commands also work with `pnpm --filter @byline/ui` before the command name.
+Port 6007 matches the sibling kit; stop its server before starting this one, or
+run `pnpm --filter @byline/ui storybook --port 6008` to use a different port.
+
+Configuration lives in `.storybook/main.ts` and `.storybook/preview.tsx`.
+Static preview assets live in `public/`, with font licences beside the fonts.
+The preview applies `.byline-ui` to the iframe body so portalled overlays inherit
+the same scoped styles as the stories. Story layout uses inline styles and does
+not require the web application's Tailwind configuration.
+
+When adding a story, import components from their local source modules and
+Storybook types from `@storybook/react-vite`. The package's `typecheck` command
+checks stories and configuration; the library build excludes story modules.
+Run the static build and inspect changed stories in the browser before merging.
 
 ## License
 

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "6.8.0",
+  "version": "6.10.0",
   "engines": {
     "node": ">=22.22.2"
   },
@@ -55,7 +55,7 @@
     "@dnd-kit/sortable": "^10.0.0",
     "clsx": "^2.1.1",
     "date-fns": "^4.4.0",
-    "motion": "^14.2.0",
+    "motion": "^14.5.0",
     "react-day-picker": "^10.0.2",
     "zod": "^4.6.7"
   },
@@ -64,22 +64,29 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
+    "@biomejs/biome": "2.6.2",
     "@rsbuild/plugin-react": "^2.1.1",
     "@rslib/core": "^1.0.3",
+    "@storybook/addon-a11y": "^10.6.3",
+    "@storybook/addon-docs": "^10.6.3",
+    "@storybook/addon-links": "^10.6.3",
+    "@storybook/addon-themes": "^10.6.3",
+    "@storybook/react-vite": "^10.6.3",
     "@types/node": "^26.6.5",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "@vitejs/plugin-react": "^6.1.2",
-    "chokidar": "^5.0.0",
+    "chokidar": "^6.0.0",
     "lightningcss-cli": "^1.33.0",
     "npm-run-all": "^4.1.5",
+    "prism-react-renderer": "^2.4.1",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
+    "storybook": "^10.6.3",
     "typescript": "^7.0.2",
     "typescript-plugin-css-modules": "^5.2.0",
-    "vite": "^8.3.4",
-    "vitest": "^5.0.4"
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
   },
   "publishConfig": {
     "access": "public",
@@ -96,7 +103,9 @@
     "build:code": "rslib build",
     "build:css": "lightningcss --bundle ./src/styles/reset.css ./src/styles/styles.css ./src/styles/typography.css --output-dir ./dist/styles",
     "typecheck": "tsc --noEmit",
-    "clean": "node scripts/clean.js node_modules dist build types .turbo",
+    "storybook": "storybook dev -p 6007 --no-open",
+    "build-storybook": "storybook build",
+    "clean": "node scripts/clean.js node_modules dist build types .turbo storybook-static",
     "lint": "biome check --write --unsafe --diagnostic-level=error",
     "skip:test": "vitest"
   }

package/src/components/accordion/accordion.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { ChevronDownIcon } from '../../icons/chevron-down-icon.js'
+import { Accordion as AccordionComponent } from './accordion.js'
+
+const meta: Meta = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Components',
+  component: AccordionComponent.Root,
+}
+
+export default meta
+
+type Story = StoryObj<typeof AccordionComponent.Root>
+
+/**
+ * NOTE: Accordions are very much context specific in terms of styling
+ * and so we apply very little styling to the default accordion component.
+ * Below is an example of a custom (albeit basic) styled accordion for demo
+ * purposes.
+ */
+export const Accordion: Story = {
+  args: {
+    defaultValue: ['item-1'],
+    className: 'accordion-root',
+  },
+  render: (args) => (
+    <div style={{ maxWidth: '600px', margin: '2rem auto' }}>
+      <style>
+        {`
+      .accordion-root {
+        border: 1px solid var(--gray-100);
+        border-radius: 6px;
+        padding: 12px 6px;
+        width: 300px;
+        background-color: white;
+        box-shadow: var(--shadow-md);
+      }
+  
+      .accordion-header {
+        border-radius: 6px;
+        padding: 12px;
+      }
+
+      .accordion-header:hover {
+        background-color: var(--gray-25);
+      }
+
+      .accordion-chevron {
+        transition: transform 300ms cubic-bezier(0.87, 0, 0.13, 1);
+      }
+
+      .accordion-trigger[data-panel-open] ~ .accordion-chevron {
+        transform: rotate(180deg);
+      }
+
+      .accordion-panel {
+        padding: 0 12px;
+      }
+
+      .dark .accordion-root {
+        border: 1px solid var(--gray-600);
+        background-color: var(--canvas-700);
+      }
+
+      .dark .accordion-header:hover {
+        background-color: var(--canvas-600);
+      }
+
+      
+    `}
+      </style>
+      <AccordionComponent.Root {...args}>
+        <nav>
+          <AccordionComponent.Item value="item-1" className="accordion-item">
+            <AccordionComponent.Header className="accordion-header">
+              <AccordionComponent.Trigger className="accordion-trigger">
+                Is it accessible?
+              </AccordionComponent.Trigger>
+              <ChevronDownIcon className="accordion-chevron" />
+            </AccordionComponent.Header>
+            <AccordionComponent.Panel className="accordion-panel">
+              <p>Yes. It adheres to the WAI-ARIA design pattern.</p>
+            </AccordionComponent.Panel>
+          </AccordionComponent.Item>
+
+          <AccordionComponent.Item value="item-2">
+            <AccordionComponent.Header className="accordion-header">
+              <AccordionComponent.Trigger className="accordion-trigger">
+                Is it unstyled?
+              </AccordionComponent.Trigger>
+              <ChevronDownIcon className="accordion-chevron" />
+            </AccordionComponent.Header>
+            <AccordionComponent.Panel className="accordion-panel">
+              <ul>
+                <li>Submenu Item One</li>
+                <li>Submenu Item Two</li>
+                <li>Submenu Item Three</li>
+              </ul>
+            </AccordionComponent.Panel>
+          </AccordionComponent.Item>
+
+          <AccordionComponent.Item value="item-3">
+            <AccordionComponent.Header className="accordion-header">
+              <AccordionComponent.Trigger className="accordion-trigger">
+                Can it be animated?
+              </AccordionComponent.Trigger>
+              <ChevronDownIcon className="accordion-chevron" />
+            </AccordionComponent.Header>
+            <AccordionComponent.Panel className="accordion-panel">
+              <p> Yes! You can animate the Accordion with CSS or JavaScript.</p>
+            </AccordionComponent.Panel>
+          </AccordionComponent.Item>
+        </nav>
+      </AccordionComponent.Root>
+    </div>
+  ),
+}

package/src/components/animation/fade-in-lift.stories.tsx

@@ -0,0 +1,80 @@
+import type React from 'react'
+
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Section } from '../section/section.js'
+import { FadeInLift } from './fade-in-lift.js'
+
+const meta: Meta<typeof FadeInLift> = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Animation/FadeInLift',
+  component: FadeInLift,
+}
+
+export default meta
+
+type Story = StoryObj<typeof FadeInLift>
+
+const DivDemo = (): React.JSX.Element => {
+  return (
+    <div style={{ marginLeft: '4rem', marginBottom: '4rem' }}>
+      <Section style={{ height: '100vh' }}>
+        <FadeInLift
+          as="div"
+          duration={1}
+          delay={0.5}
+          style={{
+            width: '400px',
+            height: '400px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: 'var(--primary-500)',
+          }}
+        >
+          <p style={{ color: 'black' }}>Fade me in 1!</p>
+        </FadeInLift>
+      </Section>
+      <Section style={{ height: '100vh' }}>
+        <FadeInLift
+          as="span"
+          duration={1}
+          delay={0.2}
+          style={{
+            width: '400px',
+            height: '400px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: 'var(--secondary-500)',
+          }}
+        >
+          <p style={{ color: 'black' }}>Fade me in 2!</p>
+        </FadeInLift>
+      </Section>
+      <Section style={{ height: '100vh' }}>
+        <FadeInLift
+          duration={1}
+          delay={0.2}
+          style={{
+            width: '400px',
+            height: '400px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: 'var(--yellow-500)',
+          }}
+        >
+          <p style={{ color: 'black' }}>Fade me in 3!</p>
+        </FadeInLift>
+      </Section>
+    </div>
+  )
+}
+
+export const Default: Story = {
+  render: () => <DivDemo />,
+}

package/src/components/avatar/avatar.stories.tsx

@@ -0,0 +1,39 @@
+import type React from 'react'
+
+import type { Meta } from '@storybook/react-vite'
+
+import { Avatar as AvatarComponent } from './avatar.js'
+
+const meta: Meta = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Components',
+  component: AvatarComponent,
+}
+
+export default meta
+
+export const Avatar = (): React.JSX.Element => (
+  <div
+    style={{
+      maxWidth: '300px',
+      margin: '2rem auto',
+      display: 'flex',
+      gap: '24px',
+      alignItems: 'center',
+      justifyContent: 'center',
+    }}
+  >
+    <div style={{ height: '28px', width: '28px' }}>
+      <AvatarComponent initials="AB" />
+    </div>
+    <div style={{ height: '34px', width: '34px' }}>
+      <AvatarComponent initials="AB" />
+    </div>
+    <div style={{ height: '40px', width: '40px' }}>
+      <AvatarComponent initials="AB" />
+    </div>
+  </div>
+)

package/src/components/badge/badge.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { capitalize } from '../../utils/capitalize.js'
+import { intent } from '../@types/shared.js'
+import { Badge } from './badge.js'
+
+type Story = StoryObj<typeof Badge>
+
+const AllIntents = (): React.JSX.Element => {
+  return (
+    <div style={{ maxWidth: '800px', margin: '2rem auto' }}>
+      {intent.map((i) => {
+        return (
+          <div
+            key={i}
+            style={{
+              marginBottom: '12px',
+            }}
+          >
+            <Badge key={`${i}`} intent={i}>{`${capitalize(i)}`}</Badge>
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+export const Intents: Story = {
+  render: () => <AllIntents />,
+}
+
+const meta: Meta<typeof Badge> = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Components/Badge',
+  component: Badge,
+}
+
+export default meta

package/src/components/button/button-group.stories.tsx

@@ -0,0 +1,44 @@
+import type React from 'react'
+import { useState } from 'react'
+
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { ButtonGroup as ButtonGroupComponent, ButtonGroupItem } from './button-group.js'
+
+const meta: Meta<typeof ButtonGroupComponent> = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Components/Button',
+  component: ButtonGroupComponent,
+}
+
+export default meta
+
+type Story = StoryObj<typeof ButtonGroupComponent>
+
+const ButtonGroupDemo = (): React.JSX.Element => {
+  const [value, setValue] = useState<string | string[]>('one')
+  const handleOnValueChange = (value: string | string[]) => {
+    setValue(value)
+  }
+  return (
+    <div style={{ maxWidth: '600px', margin: '2rem auto' }}>
+      <ButtonGroupComponent
+        type="single"
+        expandToFit={true}
+        value={value as string}
+        onValueChange={handleOnValueChange}
+      >
+        <ButtonGroupItem value="one">One</ButtonGroupItem>
+        <ButtonGroupItem value="two">Two</ButtonGroupItem>
+        <ButtonGroupItem value="three">Three</ButtonGroupItem>
+      </ButtonGroupComponent>
+    </div>
+  )
+}
+
+export const ButtonGroup: Story = {
+  render: () => <ButtonGroupDemo />,
+}

package/src/components/button/button-intents.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { capitalize } from '../../utils/capitalize.js'
+import { intent } from '../@types/shared.js'
+import { variant } from './@types/button.js'
+import { Button } from './button.js'
+
+type Story = StoryObj<typeof Button>
+
+const AllIntents = (): React.JSX.Element => {
+  return (
+    <>
+      <div
+        style={{
+          maxWidth: '1100px',
+          margin: '2rem auto',
+          padding: '2rem',
+          borderRadius: '6px',
+          backgroundColor: 'var(--background)',
+        }}
+      >
+        {intent.map((i) => {
+          return (
+            <div
+              key={i}
+              style={{
+                display: 'grid',
+                gridTemplateColumns: 'repeat(5, minmax(0, 1fr)',
+                gap: '32px',
+                marginBottom: '32px',
+              }}
+            >
+              {variant.map((v) => {
+                return (
+                  <Button
+                    key={`${i}-${v}`}
+                    intent={i}
+                    variant={v}
+                  >{`${capitalize(i)} ${v}`}</Button>
+                )
+              })}
+            </div>
+          )
+        })}
+      </div>
+      <div
+        className="dark"
+        style={{
+          maxWidth: '1100px',
+          margin: '2rem auto',
+          padding: '2rem',
+          borderRadius: '6px',
+          backgroundColor: 'var(--theme-800)',
+        }}
+      >
+        {intent.map((i) => {
+          return (
+            <div
+              key={i}
+              style={{
+                display: 'grid',
+                gridTemplateColumns: 'repeat(5, minmax(0, 1fr)',
+                gap: '32px',
+                marginBottom: '32px',
+              }}
+            >
+              {variant.map((v) => {
+                return (
+                  <Button
+                    key={`${i}-${v}`}
+                    intent={i}
+                    variant={v}
+                  >{`${capitalize(i)} ${v}`}</Button>
+                )
+              })}
+            </div>
+          )
+        })}
+      </div>
+    </>
+  )
+}
+
+export const ButtonIntents: Story = {
+  render: () => <AllIntents />,
+}
+
+const meta: Meta<typeof Button> = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Components/Button',
+  component: Button,
+}
+
+export default meta

package/src/components/button/button-overrides.stories.tsx

@@ -0,0 +1,59 @@
+import type React from 'react'
+
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Button } from './button.js'
+
+type Story = StoryObj<typeof Button>
+
+const AllOverrides = (): React.JSX.Element => {
+  return (
+    <>
+      <div style={{ maxWidth: '600px', margin: '2rem auto' }}>
+        <div
+          style={{
+            width: '300px',
+            padding: '1rem',
+            borderRadius: '8px',
+            border: '1px solid var(--stroke-primary)',
+            backgroundColor: 'var(--gray-25)',
+          }}
+        >
+          <Button className="not-dark" variant="filled" size="sm" style={{ marginRight: '1rem' }}>
+            Force Light
+          </Button>
+        </div>
+      </div>
+      <div className="dark" style={{ maxWidth: '600px', margin: '2rem auto' }}>
+        <div
+          style={{
+            width: '300px',
+            padding: '1rem',
+            borderRadius: '8px',
+            border: '1px solid var(--stroke-primary)',
+            backgroundColor: 'var(--canvas-800)',
+          }}
+        >
+          <Button variant="filled" size="sm" style={{ marginRight: '1rem' }}>
+            Force Dark
+          </Button>
+        </div>
+      </div>
+    </>
+  )
+}
+
+export const ButtonOverrides: Story = {
+  render: () => <AllOverrides />,
+}
+
+const meta: Meta<typeof Button> = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Components/Button',
+  component: Button,
+}
+
+export default meta

package/src/components/button/button-test.stories.tsx

@@ -0,0 +1,59 @@
+import type React from 'react'
+
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Button } from './button.js'
+
+type Story = StoryObj<typeof Button>
+
+const AllTests = (): React.JSX.Element => {
+  return (
+    <>
+      <div style={{ maxWidth: '600px', margin: '2rem auto' }}>
+        <div
+          style={{
+            width: '300px',
+            padding: '1rem',
+            borderRadius: '8px',
+            border: '1px solid var(--stroke-primary)',
+            backgroundColor: 'var(--gray-25)',
+          }}
+        >
+          <Button className="not-dark" variant="outlined" size="md" style={{ marginRight: '1rem' }}>
+            Force Light
+          </Button>
+        </div>
+      </div>
+      <div className="dark" style={{ maxWidth: '600px', margin: '2rem auto' }}>
+        <div
+          style={{
+            width: '300px',
+            padding: '1rem',
+            borderRadius: '8px',
+            border: '1px solid var(--stroke-primary)',
+            backgroundColor: 'var(--primary-800)',
+          }}
+        >
+          <Button variant="outlined" size="md" style={{ marginRight: '1rem' }}>
+            Force Dark
+          </Button>
+        </div>
+      </div>
+    </>
+  )
+}
+
+export const ButtonTests: Story = {
+  render: () => <AllTests />,
+}
+
+const meta: Meta<typeof Button> = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Components/Button',
+  component: Button,
+}
+
+export default meta