@titan-design/react-ui 0.2.6 → 0.3.0

package/src/components/ui/stack/Stack.stories.tsx

@@ -34,7 +34,7 @@ type Story = StoryObj<typeof Stack>
 
 function Box({ children }: { children: string }) {
   return (
-    <View className="rounded bg-primary-500 px-4 py-2">
+    <View className="rounded bg-brand-primary px-4 py-2">
       <Text className="text-sm text-white">{children}</Text>
     </View>
   )
@@ -85,13 +85,13 @@ export const WithAlignment: Story = {
 
       <Text className="text-sm font-medium text-neutral-400">align=&quot;center&quot;</Text>
       <HStack gap={2} align="center">
-        <View className="rounded bg-primary-500 px-4 py-1">
+        <View className="rounded bg-brand-primary px-4 py-1">
           <Text className="text-sm text-white">Short</Text>
         </View>
-        <View className="rounded bg-primary-500 px-4 py-4">
+        <View className="rounded bg-brand-primary px-4 py-4">
           <Text className="text-sm text-white">Tall</Text>
         </View>
-        <View className="rounded bg-primary-500 px-4 py-2">
+        <View className="rounded bg-brand-primary px-4 py-2">
           <Text className="text-sm text-white">Medium</Text>
         </View>
       </HStack>

package/src/components/ui/tabs/Tabs.tsx

@@ -100,8 +100,8 @@ export function TabList({ children, className }: TabListProps) {
 
   const variantStyles = {
     line: orientation === 'horizontal'
-      ? 'border-b border-border-default'
-      : 'border-r border-border-default',
+      ? 'border-b border-border'
+      : 'border-r border-border',
     enclosed: 'bg-surface-raised rounded-lg p-1',
     'soft-rounded': 'bg-surface-raised rounded-full p-1',
   }

package/src/components/ui/toolbar-button/ToolbarButton.stories.tsx

@@ -319,7 +319,7 @@ export const CompactMode: Story = {
             onPress={() => setIsCompact(!isCompact)}
           />
         </View>
-        <View className="h-px bg-border-default" />
+        <View className="h-px bg-border" />
         <ToolbarButtonGroup gap="sm">
           <ToolbarButton
             label="Filter"

package/src/components/ui/toolbar-button/ToolbarButton.tsx

@@ -231,7 +231,7 @@ export function ToolbarButton({
             <View
               className={cn(
                 'absolute z-50 top-full left-0 mt-1',
-                'rounded-lg shadow-lg border border-border-default',
+                'rounded-lg shadow-lg border border-border',
                 'min-w-[150px] overflow-hidden',
                 `bg-[${MENU_BG}]`
               )}

package/src/examples/react-hook-form/ControlledFields.tsx

@@ -0,0 +1,171 @@
+import { View, Text } from 'react-native'
+import {
+  Controller,
+  type Control,
+  type FieldPath,
+  type FieldValues,
+  type RegisterOptions,
+} from 'react-hook-form'
+import { FormField } from '../../components/ui/form-field'
+import { Input } from '../../components/ui/input'
+import { Select, type SelectOption } from '../../components/ui/select'
+import { Checkbox } from '../../components/ui/checkbox'
+import { RadioGroup, Radio } from '../../components/ui/radio'
+
+/**
+ * Reusable react-hook-form adapters for the styled form primitives.
+ *
+ * Each adapter follows the canonical RHF `Controller` render-prop idiom: the
+ * library owns the value/validation state and hands it to the already-styled
+ * controlled component through `field` + `fieldState`. None of the components'
+ * public APIs are touched — this is pure wiring a consumer would write.
+ */
+interface BaseControlledProps<T extends FieldValues> {
+  /** The `control` object returned by `useForm`. */
+  control: Control<T>
+  /** The field name — type-checked against the form's value shape. */
+  name: FieldPath<T>
+  /** RHF validation rules (required, pattern, validate, ...). */
+  rules?: Omit<
+    RegisterOptions<T, FieldPath<T>>,
+    'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'
+  >
+  /** Visible field label. */
+  label?: string
+  /** Marks the field as required in the UI. */
+  isRequired?: boolean
+}
+
+export interface ControlledInputProps<T extends FieldValues> extends BaseControlledProps<T> {
+  placeholder?: string
+}
+
+/** `FormField` + `Input` driven by RHF. Surfaces validation via `errorMessage`. */
+export function ControlledInput<T extends FieldValues>({
+  control,
+  name,
+  rules,
+  label,
+  isRequired,
+  placeholder,
+}: ControlledInputProps<T>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      render={({ field, fieldState }) => (
+        <FormField label={label} isRequired={isRequired} errorMessage={fieldState.error?.message}>
+          <Input
+            value={(field.value as string | undefined) ?? ''}
+            onChangeText={field.onChange}
+            onBlur={field.onBlur}
+            placeholder={placeholder}
+          />
+        </FormField>
+      )}
+    />
+  )
+}
+
+export interface ControlledSelectProps<T extends FieldValues> extends BaseControlledProps<T> {
+  options: SelectOption[]
+  placeholder?: string
+}
+
+/** `FormField` + `Select` (single-select) driven by RHF. */
+export function ControlledSelect<T extends FieldValues>({
+  control,
+  name,
+  rules,
+  label,
+  isRequired,
+  options,
+  placeholder,
+}: ControlledSelectProps<T>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      render={({ field, fieldState }) => (
+        <FormField label={label} isRequired={isRequired} errorMessage={fieldState.error?.message}>
+          <Select
+            value={(field.value as string | null | undefined) ?? null}
+            onChange={field.onChange}
+            options={options}
+            placeholder={placeholder}
+          />
+        </FormField>
+      )}
+    />
+  )
+}
+
+/** `Checkbox` (boolean) driven by RHF, with an inline error message. */
+export function ControlledCheckbox<T extends FieldValues>({
+  control,
+  name,
+  rules,
+  label,
+}: BaseControlledProps<T>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      render={({ field, fieldState }) => (
+        <View className="gap-1">
+          <Checkbox
+            label={label}
+            isChecked={Boolean(field.value)}
+            onCheckedChange={field.onChange}
+            isInvalid={!!fieldState.error}
+          />
+          {fieldState.error && (
+            <Text className="text-xs text-status-error">{fieldState.error.message}</Text>
+          )}
+        </View>
+      )}
+    />
+  )
+}
+
+export interface ControlledRadioGroupProps<T extends FieldValues> extends BaseControlledProps<T> {
+  options: SelectOption[]
+}
+
+/** `RadioGroup` + `Radio` options driven by RHF, with an inline error message. */
+export function ControlledRadioGroup<T extends FieldValues>({
+  control,
+  name,
+  rules,
+  label,
+  options,
+}: ControlledRadioGroupProps<T>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      render={({ field, fieldState }) => (
+        <View className="gap-1">
+          <RadioGroup
+            label={label}
+            value={(field.value as string | null | undefined) ?? null}
+            onChange={field.onChange}
+          >
+            {options.map((option) => (
+              <Radio key={option.value} value={option.value}>
+                {option.label}
+              </Radio>
+            ))}
+          </RadioGroup>
+          {fieldState.error && (
+            <Text className="text-xs text-status-error">{fieldState.error.message}</Text>
+          )}
+        </View>
+      )}
+    />
+  )
+}

package/src/examples/react-hook-form/ReactHookForm.stories.tsx

@@ -0,0 +1,51 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { RhfContactForm, type ContactFormValues } from './RhfContactForm'
+
+/**
+ * Examples showing how a consumer drives the styled form primitives
+ * (`FormField`, `Input`, `Select`, `Checkbox`, `Radio`) with
+ * [react-hook-form](https://react-hook-form.com/) using the canonical
+ * `Controller` render-prop idiom. See `ControlledFields.tsx` for the adapters.
+ */
+const meta: Meta<typeof RhfContactForm> = {
+  title: 'Examples/React Hook Form',
+  component: RhfContactForm,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'react-hook-form owns value + validation state and hands it to the ' +
+          'already-styled controlled components via `Controller`. No component ' +
+          'API is modified — this is pure integration wiring.',
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof RhfContactForm>
+
+/** A complete form: type, select, pick a plan, accept terms, then submit. */
+export const ContactForm: Story = {
+  render: function Render() {
+    const [submitted, setSubmitted] = React.useState<ContactFormValues | null>(null)
+    return (
+      <View style={{ gap: 16 }}>
+        <RhfContactForm onSubmit={setSubmitted} />
+        {submitted && (
+          <Text className="text-sm text-text-secondary">
+            Submitted: {JSON.stringify(submitted)}
+          </Text>
+        )}
+      </View>
+    )
+  },
+}
+
+/** Submitting empty surfaces per-field validation errors from RHF rules. */
+export const ValidationErrors: Story = {
+  render: () => <RhfContactForm />,
+}

package/src/examples/react-hook-form/ReactHookForm.test.tsx

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { RhfContactForm } from './RhfContactForm'
+
+describe('react-hook-form integration', () => {
+  it('submits the collected values from every controlled component', async () => {
+    // Arrange
+    const onSubmit = vi.fn()
+    render(<RhfContactForm onSubmit={onSubmit} />)
+
+    // Act
+    fireEvent.change(screen.getByPlaceholderText('Ada Lovelace'), {
+      target: { value: 'Grace Hopper' },
+    })
+    fireEvent.click(screen.getByText('Select a role...'))
+    fireEvent.click(screen.getByText('Designer'))
+    fireEvent.click(screen.getByText('Pro'))
+    fireEvent.click(screen.getByRole('checkbox'))
+    fireEvent.click(screen.getByText('Submit'))
+
+    // Assert
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(onSubmit.mock.calls[0][0]).toEqual({
+      fullName: 'Grace Hopper',
+      role: 'designer',
+      plan: 'pro',
+      acceptedTerms: true,
+    })
+  })
+
+  it('surfaces validation errors and blocks submit when required fields are empty', async () => {
+    // Arrange
+    const onSubmit = vi.fn()
+    render(<RhfContactForm onSubmit={onSubmit} />)
+
+    // Act
+    fireEvent.click(screen.getByText('Submit'))
+
+    // Assert
+    expect(await screen.findByText('Full name is required')).toBeInTheDocument()
+    expect(screen.getByText('Please choose a role')).toBeInTheDocument()
+    expect(screen.getByText('Please pick a plan')).toBeInTheDocument()
+    expect(screen.getByText('You must accept the terms')).toBeInTheDocument()
+    expect(onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('clears a field error once the value becomes valid', async () => {
+    // Arrange
+    render(<RhfContactForm />)
+    fireEvent.click(screen.getByText('Submit'))
+    expect(await screen.findByText('Full name is required')).toBeInTheDocument()
+
+    // Act
+    fireEvent.change(screen.getByPlaceholderText('Ada Lovelace'), {
+      target: { value: 'Katherine Johnson' },
+    })
+
+    // Assert
+    await waitFor(() => expect(screen.queryByText('Full name is required')).not.toBeInTheDocument())
+  })
+})

package/src/examples/react-hook-form/RhfContactForm.tsx

@@ -0,0 +1,99 @@
+import { View } from 'react-native'
+import { useForm, type SubmitHandler } from 'react-hook-form'
+import { Button, ButtonText } from '../../components/ui/button'
+import { type SelectOption } from '../../components/ui/select'
+import {
+  ControlledInput,
+  ControlledSelect,
+  ControlledCheckbox,
+  ControlledRadioGroup,
+} from './ControlledFields'
+
+export interface ContactFormValues {
+  fullName: string
+  role: string
+  plan: string
+  acceptedTerms: boolean
+}
+
+const roleOptions: SelectOption[] = [
+  { value: 'engineer', label: 'Engineer' },
+  { value: 'designer', label: 'Designer' },
+  { value: 'manager', label: 'Manager' },
+]
+
+const planOptions: SelectOption[] = [
+  { value: 'free', label: 'Free' },
+  { value: 'pro', label: 'Pro' },
+]
+
+const defaultValues: ContactFormValues = {
+  fullName: '',
+  role: '',
+  plan: '',
+  acceptedTerms: false,
+}
+
+export interface RhfContactFormProps {
+  /** Called with validated form values on a successful submit. */
+  onSubmit?: SubmitHandler<ContactFormValues>
+}
+
+/**
+ * End-to-end example wiring the styled form primitives to react-hook-form.
+ *
+ * Demonstrates the `Controller` idiom across `FormField`, `Input`, `Select`,
+ * `Checkbox`, and `Radio` — a single `useForm` instance owns state, validation,
+ * and submission. No component API is modified.
+ */
+export function RhfContactForm({ onSubmit }: RhfContactFormProps) {
+  const { control, handleSubmit } = useForm<ContactFormValues>({
+    defaultValues,
+  })
+
+  const handleValid: SubmitHandler<ContactFormValues> = (values) => {
+    onSubmit?.(values)
+  }
+
+  return (
+    <View className="gap-4" style={{ maxWidth: 360 }}>
+      <ControlledInput
+        control={control}
+        name="fullName"
+        label="Full name"
+        isRequired
+        placeholder="Ada Lovelace"
+        rules={{ required: 'Full name is required' }}
+      />
+
+      <ControlledSelect
+        control={control}
+        name="role"
+        label="Role"
+        isRequired
+        options={roleOptions}
+        placeholder="Select a role..."
+        rules={{ required: 'Please choose a role' }}
+      />
+
+      <ControlledRadioGroup
+        control={control}
+        name="plan"
+        label="Plan"
+        options={planOptions}
+        rules={{ required: 'Please pick a plan' }}
+      />
+
+      <ControlledCheckbox
+        control={control}
+        name="acceptedTerms"
+        label="I accept the terms and conditions"
+        rules={{ required: 'You must accept the terms' }}
+      />
+
+      <Button onPress={handleSubmit(handleValid)}>
+        <ButtonText>Submit</ButtonText>
+      </Button>
+    </View>
+  )
+}

package/src/stories/PresetShowcase.stories.tsx

@@ -24,7 +24,7 @@ function PresetSwitcher({
   onSwitch: (name: string) => void
 }) {
   return (
-    <View className="flex-row items-center gap-3 p-4 bg-surface-elevated rounded-lg border border-border-default">
+    <View className="flex-row items-center gap-3 p-4 bg-surface-elevated rounded-lg border border-border">
       <Text className="text-text-secondary text-sm font-medium">Active Preset:</Text>
       {Object.keys(presets).map((name) => (
         <Pressable
@@ -33,7 +33,7 @@ function PresetSwitcher({
           className={`px-4 py-2 rounded-md border ${
             activePreset === name
               ? 'bg-brand-primary border-brand-primary'
-              : 'bg-surface-base border-border-default web:hover:bg-interactive-hover'
+              : 'bg-surface-base border-border web:hover:bg-interactive-hover'
           }`}
         >
           <Text
@@ -272,7 +272,7 @@ function TypographyShowcase() {
       </Section>
 
       <Section title="Monospace Font (font-mono)">
-        <View className="bg-surface-elevated rounded-lg p-4 border border-border-default">
+        <View className="bg-surface-elevated rounded-lg p-4 border border-border">
           <Text className="text-sm text-text-primary font-mono">
             {'const theme = applyThemePreset(audiobookPreset)'}
           </Text>
@@ -368,13 +368,13 @@ function ColorPaletteShowcase() {
 
       <Section title="Text Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border-default">
+          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border">
             <Text className="text-xs font-mono font-medium text-text-primary">text-primary</Text>
           </View>
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border-default">
+          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border">
             <Text className="text-xs font-mono font-medium text-text-secondary">text-secondary</Text>
           </View>
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border-default">
+          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-elevated border border-border">
             <Text className="text-xs font-mono font-medium text-text-tertiary">text-tertiary</Text>
           </View>
         </View>
@@ -382,25 +382,25 @@ function ColorPaletteShowcase() {
 
       <Section title="Surface Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <ColorSwatch label="surface-base" className="bg-surface-base border border-border-default" textClass="text-text-primary" />
-          <ColorSwatch label="surface-elevated" className="bg-surface-elevated border border-border-default" textClass="text-text-primary" />
-          <ColorSwatch label="surface-raised" className="bg-surface-raised border border-border-default" textClass="text-text-primary" />
-          <ColorSwatch label="surface-overlay" className="bg-surface-overlay border border-border-default" textClass="text-text-primary" />
-          <ColorSwatch label="surface-input" className="bg-surface-input border border-border-default" textClass="text-text-primary" />
+          <ColorSwatch label="surface-base" className="bg-surface-base border border-border" textClass="text-text-primary" />
+          <ColorSwatch label="surface-elevated" className="bg-surface-elevated border border-border" textClass="text-text-primary" />
+          <ColorSwatch label="surface-raised" className="bg-surface-raised border border-border" textClass="text-text-primary" />
+          <ColorSwatch label="surface-overlay" className="bg-surface-overlay border border-border" textClass="text-text-primary" />
+          <ColorSwatch label="surface-input" className="bg-surface-input border border-border" textClass="text-text-primary" />
         </View>
       </Section>
 
       <Section title="Background Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <ColorSwatch label="background-base" className="bg-background-base border border-border-default" textClass="text-text-primary" />
-          <ColorSwatch label="background-default" className="bg-background-default border border-border-default" textClass="text-text-primary" />
-          <ColorSwatch label="background-subtle" className="bg-background-subtle border border-border-default" textClass="text-text-primary" />
+          <ColorSwatch label="background-base" className="bg-background-base border border-border" textClass="text-text-primary" />
+          <ColorSwatch label="background-default" className="bg-background-default border border-border" textClass="text-text-primary" />
+          <ColorSwatch label="background-subtle" className="bg-background-subtle border border-border" textClass="text-text-primary" />
         </View>
       </Section>
 
       <Section title="Border Colors">
         <View className="flex-row gap-3 flex-wrap">
-          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-border-default">
+          <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-border">
             <Text className="text-xs font-mono font-medium text-text-primary">border-default</Text>
           </View>
           <View className="rounded-lg p-3 min-w-[120px] min-h-[60px] justify-end bg-surface-base border-2 border-border-subtle">

package/src/theme/config.completeness.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { darkThemeCSSVars, lightThemeCSSVars } from './config'
+
+/**
+ * Drift guard for the token codegen source (TD-05.08).
+ *
+ * `config.ts` (darkThemeCSSVars / lightThemeCSSVars) is the source that
+ * `tokens-css.ts` renders into `dist/tokens.css`. It must stay a complete,
+ * value-accurate mirror of the `:root` / `.light` custom properties in
+ * `global.css`; otherwise the generated stylesheet silently drifts from the
+ * design system (the exact gap this ticket closed). This test fails if
+ * global.css gains a `:root` var that config.ts does not cover, or if any
+ * shared var's value diverges.
+ */
+
+const themeDir = path.dirname(fileURLToPath(import.meta.url))
+const css = readFileSync(path.join(themeDir, 'global.css'), 'utf8')
+
+/**
+ * global.css :root vars intentionally excluded from the codegen source.
+ * Empty today — every :root var is mirrored. Add a var here (with a reason)
+ * only if it is genuinely prototype-irrelevant, rather than silently skipping.
+ */
+const CODEGEN_ALLOWLIST = new Set<string>([])
+
+function parseVarBlock(header: RegExp): Map<string, string> {
+  const match = css.match(header)
+  if (!match) throw new Error(`could not locate CSS block for ${header}`)
+  const vars = new Map<string, string>()
+  for (const line of match[1].split('\n')) {
+    const declaration = line.match(/^\s*(--[a-z0-9-]+):\s*(.+?);\s*$/i)
+    if (declaration) vars.set(declaration[1], declaration[2].trim())
+  }
+  return vars
+}
+
+const globalDark = parseVarBlock(/:root\s*\{([\s\S]*?)\n\s*\}/)
+const globalLight = parseVarBlock(/\.light,\s*\n?\s*:root\.light\s*\{([\s\S]*?)\n\s*\}/)
+
+const cases = [
+  ['dark', globalDark, darkThemeCSSVars as Record<string, string>],
+  ['light', globalLight, lightThemeCSSVars as Record<string, string>],
+] as const
+
+describe('token codegen completeness (config.ts vs global.css)', () => {
+  it('parses both global.css theme blocks', () => {
+    expect(globalDark.size).toBeGreaterThan(90)
+    expect(globalLight.size).toBe(globalDark.size)
+  })
+
+  for (const [mode, globalVars, cfg] of cases) {
+    it(`${mode}: config covers every global.css :root var with the exact value`, () => {
+      const missing: string[] = []
+      const mismatched: string[] = []
+      for (const [name, value] of globalVars) {
+        if (CODEGEN_ALLOWLIST.has(name)) continue
+        if (!(name in cfg)) {
+          missing.push(name)
+        } else if (cfg[name] !== value) {
+          mismatched.push(`${name}: global='${value}' config='${cfg[name]}'`)
+        }
+      }
+      expect(missing, 'global.css vars missing from config.ts codegen source').toEqual([])
+      expect(mismatched, 'value drift between config.ts and global.css').toEqual([])
+    })
+
+    it(`${mode}: config emits no var absent from global.css`, () => {
+      const extra = Object.keys(cfg).filter(
+        (name) => !globalVars.has(name) && !CODEGEN_ALLOWLIST.has(name),
+      )
+      expect(extra, 'config.ts vars not present in global.css :root').toEqual([])
+    })
+  }
+})