@duro-app/ui 0.15.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.15.2",
+  "version": "0.17.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -33,18 +33,35 @@
     "./reset.css": "./src/global-reset.css"
   },
   "peerDependencies": {
+    "@hookform/resolvers": "^5.0.0",
+    "effect": "^3.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "react-hook-form": "^7.55.0",
     "react-strict-dom": "^0.0.55"
   },
+  "peerDependenciesMeta": {
+    "react-hook-form": {
+      "optional": true
+    },
+    "@hookform/resolvers": {
+      "optional": true
+    },
+    "effect": {
+      "optional": true
+    }
+  },
   "dependencies": {
-    "@duro-app/tokens": "^0.15.2"
+    "@duro-app/tokens": "^0.17.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",
+    "@hookform/resolvers": "^5.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.0.0",
+    "effect": "^3.0.0",
+    "react-hook-form": "^7.55.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",
     "vite-plugin-babel": "^1.5.0",

package/src/components/ActionBar/ActionBar.tsx

@@ -13,6 +13,8 @@ export interface ActionBarProps {
   isEmphasized?: boolean
   /** Called when the clear/close button is pressed. */
   onClearSelection: () => void
+  /** Whether the bar can be dismissed. When false, the close button is hidden. @default true */
+  dismissible?: boolean
   /** Action buttons to display. */
   children: ReactNode
 }
@@ -22,6 +24,7 @@ function ActionBarInner({
   selectedLabel,
   isEmphasized = false,
   onClearSelection,
+  dismissible = true,
   children,
 }: ActionBarProps) {
   const container = useOverlayContainer()
@@ -42,21 +45,23 @@ function ActionBarInner({
       </html.span>
       <html.div style={[styles.separator, isEmphasized && styles.separatorEmphasized]} />
       <html.div style={styles.actions}>{children}</html.div>
-      <html.button
-        type="button"
-        aria-label="Clear selection"
-        onClick={onClearSelection}
-        style={[styles.closeButton, isEmphasized && styles.closeButtonEmphasized]}
-      >
-        <svg width={10} height={10} viewBox="0 0 10 10" fill="none" aria-hidden="true">
-          <path
-            d="M1 1l8 8M9 1l-8 8"
-            stroke="currentColor"
-            strokeWidth={1.5}
-            strokeLinecap="round"
-          />
-        </svg>
-      </html.button>
+      {dismissible && (
+        <html.button
+          type="button"
+          aria-label="Clear selection"
+          onClick={onClearSelection}
+          style={[styles.closeButton, isEmphasized && styles.closeButtonEmphasized]}
+        >
+          <svg width={10} height={10} viewBox="0 0 10 10" fill="none" aria-hidden="true">
+            <path
+              d="M1 1l8 8M9 1l-8 8"
+              stroke="currentColor"
+              strokeWidth={1.5}
+              strokeLinecap="round"
+            />
+          </svg>
+        </html.button>
+      )}
     </html.div>
   )
 

package/src/components/Button/Button.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Standard interactive button. For navigation (links styled as buttons), use LinkButton instead.',
+  whenToUse: [
+    'Triggering actions: submit, save, delete, open dialog',
+    'Primary and secondary actions in forms and toolbars',
+  ],
+  whenNotToUse: [
+    'Navigating to a URL — use LinkButton (renders <a>)',
+    'Toggling state — use Toggle',
+  ],
+  relatedTo: [
+    {component: 'LinkButton', relationship: 'LinkButton for navigation; Button for actions'},
+    {component: 'Toggle', relationship: 'Toggle for pressed/unpressed state'},
+  ],
+  example: `<Inline gap="sm">
+  <Button variant="primary" type="submit">Save</Button>
+  <Button variant="secondary">Cancel</Button>
+  <Button variant="danger">Delete</Button>
+</Inline>`,
+}

package/src/components/Checkbox/Checkbox.meta.ts

@@ -0,0 +1,21 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Checkbox input with optional visible label. Supports controlled and uncontrolled modes.',
+  whenToUse: [
+    'Boolean opt-in/opt-out (terms acceptance, feature toggle)',
+    'Multi-select from a list (inside a Fieldset)',
+  ],
+  whenNotToUse: [
+    'Binary toggle in settings — prefer Switch for on/off semantics',
+    'Selecting one of several options — use Select or ToggleGroup',
+  ],
+  relatedTo: [
+    {component: 'Switch', relationship: 'Switch for on/off settings; Checkbox for opt-in/selection'},
+    {component: 'Toggle', relationship: 'Toggle for toolbar actions; Checkbox for form input'},
+  ],
+  example: `<Checkbox name="terms" onChange={(e) => console.log(e.target.checked)}>
+  I agree to the terms and conditions
+</Checkbox>`,
+}

package/src/components/Cluster/Cluster.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Horizontal flex layout that WRAPS to the next line when items overflow.',
+  whenToUse: [
+    'Tags, badges, or chips that should wrap when they exceed the container width',
+    'Any set of inline elements with unknown/dynamic count',
+    'Filter pills, keyword lists, avatar groups',
+  ],
+  whenNotToUse: [
+    'Items that must stay on one line — use Inline',
+    'Vertical stacking — use Stack',
+  ],
+  relatedTo: [
+    {component: 'Inline', relationship: 'Same but does NOT wrap (nowrap)'},
+    {component: 'Stack', relationship: 'Vertical equivalent'},
+  ],
+  example: `<Cluster gap="xs">
+  <Badge>React</Badge>
+  <Badge>TypeScript</Badge>
+  <Badge>Design Systems</Badge>
+  <Badge>Accessibility</Badge>
+</Cluster>`,
+}

package/src/components/Field/Field.meta.ts

@@ -0,0 +1,37 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Compound form field with label, description, and error display. Inside Form, auto-binds to react-hook-form via name prop. Works standalone with manual invalid prop.',
+  whenToUse: [
+    'Any form input that needs a label and/or error message',
+    'Standalone labeled input (without Form) with manual error display',
+  ],
+  whenNotToUse: [
+    'Bare input without label — use Input directly (rare)',
+  ],
+  anatomy: {
+    required: ['Root'],
+    optional: ['Label', 'Description', 'Error'],
+  },
+  relatedTo: [
+    {component: 'Form', relationship: 'Field.Root auto-binds when name matches schema key'},
+    {component: 'Input', relationship: 'Place Input inside Field.Root'},
+    {component: 'Textarea', relationship: 'Place Textarea inside Field.Root'},
+    {component: 'Select', relationship: 'Place Select inside Field.Root'},
+  ],
+  example: `// Inside Form (auto-binds validation)
+<Field.Root name="email">
+  <Field.Label>Email</Field.Label>
+  <Input type="email" placeholder="you@example.com" />
+  <Field.Description>We'll never share your email.</Field.Description>
+  <Field.Error />
+</Field.Root>
+
+// Standalone (manual error)
+<Field.Root invalid>
+  <Field.Label>Email</Field.Label>
+  <Input variant="error" />
+  <Field.Error>This email is already taken.</Field.Error>
+</Field.Root>`,
+}

package/src/components/Field/Field.tsx

@@ -1,15 +1,67 @@
 import {type ReactNode, useId, useMemo} from 'react'
 import {html} from 'react-strict-dom'
+import {useFormContext as useRHFFormContext, useController} from 'react-hook-form'
 import {FieldContext, useFieldContext} from './FieldContext'
+import {useFormContext} from '../Form/FormContext'
 import {styles} from './styles.css'
 
 // --- Root ---
 interface RootProps {
+  name?: string
   invalid?: boolean
   children: ReactNode
 }
 
-function Root({invalid = false, children}: RootProps) {
+function Root({name, ...props}: RootProps) {
+  const insideForm = useFormContext()
+  if (name && insideForm) {
+    return <ControlledRoot name={name} {...props} />
+  }
+  return <StaticRoot {...props} />
+}
+
+// Always calls useController — no conditional hooks
+function ControlledRoot({
+  name,
+  invalid: invalidProp = false,
+  children,
+}: {
+  name: string
+  invalid?: boolean
+  children: ReactNode
+}) {
+  const id = useId()
+  const {control} = useRHFFormContext()
+  const {field, fieldState} = useController({control, name})
+  const invalid = invalidProp || !!fieldState.error
+
+  const ctx = useMemo(
+    () => ({
+      controlId: `${id}-control`,
+      descriptionId: `${id}-description`,
+      errorId: `${id}-error`,
+      invalid,
+      field: {
+        value: field.value,
+        onChange: field.onChange,
+        onBlur: field.onBlur,
+        ref: field.ref,
+        name: field.name,
+      },
+      errorMessage: fieldState.error?.message,
+    }),
+    [id, invalid, field.value, field.onChange, field.onBlur, field.ref, field.name, fieldState.error],
+  )
+
+  return (
+    <FieldContext.Provider value={ctx}>
+      <html.div style={styles.root}>{children}</html.div>
+    </FieldContext.Provider>
+  )
+}
+
+// Current behavior, no RHF dependency
+function StaticRoot({invalid = false, children}: {invalid?: boolean; children: ReactNode}) {
   const id = useId()
   const ctx = useMemo(
     () => ({
@@ -63,11 +115,12 @@ interface ErrorProps {
 
 function Error({children}: ErrorProps) {
   const ctx = useFieldContext()
-  if (!ctx?.invalid && !children) return null
+  const content = children ?? ctx?.errorMessage
+  if (!ctx?.invalid && !content) return null
 
   return (
     <html.span id={ctx?.errorId} role="alert" style={styles.error}>
-      {children}
+      {content}
     </html.span>
   )
 }

package/src/components/Field/FieldContext.ts

@@ -5,8 +5,18 @@ interface FieldContextValue {
   descriptionId: string
   errorId: string
   invalid: boolean
+  field?: {
+    value: unknown
+    onChange: (...event: unknown[]) => void
+    onBlur: () => void
+    ref: React.RefCallback<unknown>
+    name: string
+  }
+  errorMessage?: string
 }
 
+export type {FieldContextValue}
+
 export const FieldContext = createContext<FieldContextValue | null>(null)
 
 export function useFieldContext() {

package/src/components/Fieldset/Fieldset.meta.ts

@@ -0,0 +1,38 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Groups related form controls with consistent gap spacing and an optional legend. Supports disabled cascade.',
+  whenToUse: [
+    'Grouping related fields within a form (e.g., "Personal Info", "Address")',
+    'Applying consistent vertical gap between form fields',
+  ],
+  whenNotToUse: [
+    'Non-form content grouping — use Stack or Card',
+  ],
+  anatomy: {
+    required: ['Root'],
+    optional: ['Legend'],
+  },
+  relatedTo: [
+    {component: 'Form', relationship: 'Fieldset.Root goes inside Form'},
+    {component: 'Field', relationship: 'Field.Root goes inside Fieldset.Root'},
+    {component: 'Stack', relationship: 'Similar vertical spacing, but Fieldset has form semantics'},
+  ],
+  example: `<Form schema={schema} defaultValues={defaults} onSubmit={onSubmit}>
+  <Fieldset.Root gap="md">
+    <Fieldset.Legend>Account Details</Fieldset.Legend>
+    <Field.Root name="email">
+      <Field.Label>Email</Field.Label>
+      <Input type="email" />
+      <Field.Error />
+    </Field.Root>
+    <Field.Root name="password">
+      <Field.Label>Password</Field.Label>
+      <Input type="password" />
+      <Field.Error />
+    </Field.Root>
+    <Button type="submit">Create account</Button>
+  </Fieldset.Root>
+</Form>`,
+}

package/src/components/Form/Form.meta.ts

@@ -0,0 +1,38 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Form wrapper with Effect Schema validation and react-hook-form integration. Provides FormContext to child Field components.',
+  whenToUse: [
+    'Any form that needs validation',
+    'Multi-field forms with submit handling',
+  ],
+  whenNotToUse: [
+    'Single standalone field without validation — use Field.Root directly',
+    'Non-form interactive UIs — use individual components',
+  ],
+  relatedTo: [
+    {component: 'Field', relationship: 'Field.Root auto-binds to Form via name prop'},
+    {component: 'Fieldset', relationship: 'Groups fields visually within a Form'},
+  ],
+  example: `import {Schema} from 'effect'
+
+const MySchema = Schema.Struct({
+  email: Schema.String.pipe(
+    Schema.pattern(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/, {message: () => 'Invalid email'}),
+  ),
+})
+
+<Form schema={MySchema} defaultValues={{email: ''}} onSubmit={handleSubmit}>
+  {({formState}) => (
+    <Fieldset.Root gap="md">
+      <Field.Root name="email">
+        <Field.Label>Email</Field.Label>
+        <Input type="email" />
+        <Field.Error />
+      </Field.Root>
+      <Button type="submit" disabled={!formState.isValid}>Submit</Button>
+    </Fieldset.Root>
+  )}
+</Form>`,
+}

package/src/components/Form/Form.stories.tsx

@@ -0,0 +1,252 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, userEvent, within} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {Schema} from 'effect'
+import {Form} from './Form'
+import {Field} from '../Field/Field'
+import {Input} from '../Input/Input'
+import {Textarea} from '../Textarea/Textarea'
+import {Fieldset} from '../Fieldset/Fieldset'
+import {Button} from '../Button/Button'
+
+const meta: Meta = {
+  title: 'Components/Form',
+}
+
+export default meta
+type Story = StoryObj
+
+// --- Schemas ---
+
+const LoginSchema = Schema.Struct({
+  username: Schema.String.pipe(
+    Schema.minLength(3, {message: () => 'Username must be at least 3 characters'}),
+  ),
+  password: Schema.String.pipe(
+    Schema.minLength(8, {message: () => 'Password must be at least 8 characters'}),
+  ),
+})
+
+const FeedbackSchema = Schema.Struct({
+  email: Schema.String.pipe(
+    Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {message: () => 'Enter a valid email address'}),
+  ),
+  message: Schema.String.pipe(
+    Schema.minLength(10, {message: () => 'Message must be at least 10 characters'}),
+  ),
+})
+
+const wrapStyles = css.create({
+  wrap: {maxWidth: 400},
+})
+
+// --- Stories ---
+
+export const Default: Story = {
+  render: () => {
+    const handleSubmit = fn()
+    return (
+      <html.div style={wrapStyles.wrap}>
+        <Form
+          schema={LoginSchema}
+          defaultValues={{username: '', password: ''}}
+          onSubmit={handleSubmit}
+        >
+          {({formState}) => (
+            <Fieldset.Root gap="md">
+              <Field.Root name="username">
+                <Field.Label>Username</Field.Label>
+                <Input placeholder="Enter username" />
+                <Field.Description>3-32 characters</Field.Description>
+                <Field.Error />
+              </Field.Root>
+
+              <Field.Root name="password">
+                <Field.Label>Password</Field.Label>
+                <Input type="password" placeholder="Enter password" />
+                <Field.Error />
+              </Field.Root>
+
+              <Button type="submit" disabled={!formState.isValid}>
+                Log in
+              </Button>
+            </Fieldset.Root>
+          )}
+        </Form>
+      </html.div>
+    )
+  },
+  play: async ({canvas}) => {
+    // Submit button starts disabled (empty fields are invalid)
+    const button = canvas.getByRole('button', {name: 'Log in'})
+    await expect(button).toBeDisabled()
+
+    // Labels and inputs rendered
+    await expect(canvas.getByText('Username')).toBeInTheDocument()
+    await expect(canvas.getByText('Password')).toBeInTheDocument()
+    await expect(canvas.getByPlaceholderText('Enter username')).toBeInTheDocument()
+    await expect(canvas.getByPlaceholderText('Enter password')).toBeInTheDocument()
+  },
+}
+
+export const ValidationOnBlur: Story = {
+  name: 'Validation — on blur',
+  render: () => (
+    <html.div style={wrapStyles.wrap}>
+      <Form
+        schema={LoginSchema}
+        defaultValues={{username: '', password: ''}}
+        onSubmit={fn()}
+      >
+        <Fieldset.Root gap="md">
+          <Field.Root name="username">
+            <Field.Label>Username</Field.Label>
+            <Input placeholder="Enter username" />
+            <Field.Error />
+          </Field.Root>
+
+          <Field.Root name="password">
+            <Field.Label>Password</Field.Label>
+            <Input type="password" placeholder="Enter password" />
+            <Field.Error />
+          </Field.Root>
+
+          <Button type="submit">Log in</Button>
+        </Fieldset.Root>
+      </Form>
+    </html.div>
+  ),
+  play: async ({canvas, step}) => {
+    const usernameInput = canvas.getByPlaceholderText('Enter username')
+    const passwordInput = canvas.getByPlaceholderText('Enter password')
+
+    await step('No errors before interaction', async () => {
+      expect(canvas.queryByRole('alert')).not.toBeInTheDocument()
+    })
+
+    await step('Type short username then blur — error appears', async () => {
+      await userEvent.type(usernameInput, 'ab')
+      await userEvent.tab() // blur
+      const alert = await canvas.findByRole('alert')
+      await expect(alert).toHaveTextContent('Username must be at least 3 characters')
+    })
+
+    await step('Fix username by typing more — error clears (reValidateMode: onChange)', async () => {
+      await userEvent.type(usernameInput, 'c') // now "abc"
+      expect(canvas.queryByText('Username must be at least 3 characters')).not.toBeInTheDocument()
+    })
+
+    await step('Blur empty password — error appears', async () => {
+      await userEvent.click(passwordInput)
+      await userEvent.tab()
+      const alerts = canvas.getAllByRole('alert')
+      const pwAlert = alerts.find((el) => el.textContent?.includes('Password'))
+      await expect(pwAlert).toBeDefined()
+    })
+  },
+}
+
+export const WithTextarea: Story = {
+  name: 'With Textarea',
+  render: () => (
+    <html.div style={wrapStyles.wrap}>
+      <Form
+        schema={FeedbackSchema}
+        defaultValues={{email: '', message: ''}}
+        onSubmit={fn()}
+      >
+        {({formState}) => (
+          <Fieldset.Root gap="md">
+            <Field.Root name="email">
+              <Field.Label>Email</Field.Label>
+              <Input type="email" placeholder="you@example.com" />
+              <Field.Error />
+            </Field.Root>
+
+            <Field.Root name="message">
+              <Field.Label>Message</Field.Label>
+              <Textarea placeholder="Tell us what you think..." rows={4} />
+              <Field.Description>At least 10 characters</Field.Description>
+              <Field.Error />
+            </Field.Root>
+
+            <Button type="submit" disabled={!formState.isValid}>
+              Send feedback
+            </Button>
+          </Fieldset.Root>
+        )}
+      </Form>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByPlaceholderText('you@example.com')).toBeInTheDocument()
+    await expect(canvas.getByPlaceholderText('Tell us what you think...')).toBeInTheDocument()
+
+    const button = canvas.getByRole('button', {name: 'Send feedback'})
+    await expect(button).toBeDisabled()
+  },
+}
+
+export const SuccessfulSubmit: Story = {
+  name: 'Successful submit',
+  render: () => {
+    const onSubmit = fn()
+    return (
+      <html.div style={wrapStyles.wrap}>
+        <Form
+          schema={LoginSchema}
+          defaultValues={{username: '', password: ''}}
+          onSubmit={onSubmit}
+        >
+          <Fieldset.Root gap="md">
+            <Field.Root name="username">
+              <Field.Label>Username</Field.Label>
+              <Input placeholder="Enter username" />
+              <Field.Error />
+            </Field.Root>
+
+            <Field.Root name="password">
+              <Field.Label>Password</Field.Label>
+              <Input type="password" placeholder="Enter password" />
+              <Field.Error />
+            </Field.Root>
+
+            <Button type="submit">Log in</Button>
+          </Fieldset.Root>
+        </Form>
+      </html.div>
+    )
+  },
+  play: async ({canvas}) => {
+    const usernameInput = canvas.getByPlaceholderText('Enter username')
+    const passwordInput = canvas.getByPlaceholderText('Enter password')
+
+    // Fill valid values
+    await userEvent.type(usernameInput, 'johndoe')
+    await userEvent.type(passwordInput, 'supersecret1')
+
+    // No errors should be present
+    expect(canvas.queryByRole('alert')).not.toBeInTheDocument()
+  },
+}
+
+export const StandaloneFieldStillWorks: Story = {
+  name: 'Standalone Field (no Form)',
+  render: () => (
+    <html.div style={wrapStyles.wrap}>
+      <Field.Root invalid>
+        <Field.Label>Email</Field.Label>
+        <Input variant="error" placeholder="Enter email" />
+        <Field.Error>Manual error — no Form wrapper needed.</Field.Error>
+      </Field.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    // Standalone usage still works without Form context
+    const input = canvas.getByPlaceholderText('Enter email')
+    await expect(input).toHaveAttribute('aria-invalid', 'true')
+
+    const alert = canvas.getByRole('alert')
+    await expect(alert).toHaveTextContent('Manual error — no Form wrapper needed.')
+  },
+}