@duro-app/ui 0.23.0 → 0.25.0

package/src/components/Field/Field.tsx

@@ -1,21 +1,25 @@
-import {type ReactNode, useId, useMemo} from 'react'
+import {type ReactNode, Children, isValidElement, 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 type {LabelPosition, NecessityIndicator} from '../Form/FormContext'
 import {styles} from './styles.css'
 
 // --- Root ---
 interface RootProps {
   name?: string
   invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
   children: ReactNode
 }
 
 function Root({name, ...props}: RootProps) {
-  const insideForm = useFormContext()
-  if (name && insideForm) {
-    return <ControlledRoot name={name} {...props} />
+  const formCtx = useFormContext()
+  if (name && formCtx) {
+    return <ControlledRoot name={name} formCtx={formCtx} {...props} />
   }
   return <StaticRoot {...props} />
 }
@@ -23,11 +27,19 @@ function Root({name, ...props}: RootProps) {
 // Always calls useController — no conditional hooks
 function ControlledRoot({
   name,
+  formCtx,
   invalid: invalidProp = false,
+  required,
+  disabled,
+  labelPosition,
   children,
 }: {
   name: string
+  formCtx: NonNullable<ReturnType<typeof useFormContext>>
   invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
   children: ReactNode
 }) {
   const id = useId()
@@ -35,12 +47,20 @@ function ControlledRoot({
   const {field, fieldState} = useController({control, name})
   const invalid = invalidProp || !!fieldState.error
 
+  const effectiveDisabled = disabled ?? formCtx.disabled
+  const effectiveLabelPosition = labelPosition ?? formCtx.labelPosition
+  const effectiveNecessityIndicator = formCtx.necessityIndicator
+
   const ctx = useMemo(
     () => ({
       controlId: `${id}-control`,
       descriptionId: `${id}-description`,
       errorId: `${id}-error`,
       invalid,
+      required,
+      disabled: effectiveDisabled,
+      labelPosition: effectiveLabelPosition,
+      necessityIndicator: effectiveNecessityIndicator,
       field: {
         value: field.value,
         onChange: field.onChange,
@@ -53,6 +73,10 @@ function ControlledRoot({
     [
       id,
       invalid,
+      required,
+      effectiveDisabled,
+      effectiveLabelPosition,
+      effectiveNecessityIndicator,
       field.value,
       field.onChange,
       field.onBlur,
@@ -64,13 +88,25 @@ function ControlledRoot({
 
   return (
     <FieldContext.Provider value={ctx}>
-      <html.div style={styles.root}>{children}</html.div>
+      <FieldLayout labelPosition={effectiveLabelPosition}>{children}</FieldLayout>
     </FieldContext.Provider>
   )
 }
 
 // Current behavior, no RHF dependency
-function StaticRoot({invalid = false, children}: {invalid?: boolean; children: ReactNode}) {
+function StaticRoot({
+  invalid = false,
+  required,
+  disabled,
+  labelPosition = 'top',
+  children,
+}: {
+  invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
+  children: ReactNode
+}) {
   const id = useId()
   const ctx = useMemo(
     () => ({
@@ -78,17 +114,53 @@ function StaticRoot({invalid = false, children}: {invalid?: boolean; children: R
       descriptionId: `${id}-description`,
       errorId: `${id}-error`,
       invalid,
+      required,
+      disabled,
+      labelPosition,
     }),
-    [id, invalid],
+    [id, invalid, required, disabled, labelPosition],
   )
 
   return (
     <FieldContext.Provider value={ctx}>
-      <html.div style={styles.root}>{children}</html.div>
+      <FieldLayout labelPosition={labelPosition}>{children}</FieldLayout>
     </FieldContext.Provider>
   )
 }
 
+// --- FieldLayout ---
+// When labelPosition is 'side', separates Label from other children
+// and wraps the non-label children in a content column.
+function FieldLayout({
+  labelPosition,
+  children,
+}: {
+  labelPosition: LabelPosition
+  children: ReactNode
+}) {
+  if (labelPosition !== 'side') {
+    return <html.div style={styles.root}>{children}</html.div>
+  }
+
+  let labelNode: ReactNode = null
+  const rest: ReactNode[] = []
+
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && child.type === Label && !labelNode) {
+      labelNode = child
+    } else {
+      rest.push(child)
+    }
+  })
+
+  return (
+    <html.div style={styles.rootSide}>
+      {labelNode}
+      <html.div style={styles.fieldContent}>{rest}</html.div>
+    </html.div>
+  )
+}
+
 // --- Label ---
 interface LabelProps {
   children: ReactNode
@@ -96,9 +168,25 @@ interface LabelProps {
 
 function Label({children}: LabelProps) {
   const ctx = useFieldContext()
+  const isSide = ctx?.labelPosition === 'side'
+  const indicator = ctx?.necessityIndicator
+
   return (
-    <html.label for={ctx?.controlId} style={styles.label}>
+    <html.label
+      for={ctx?.controlId}
+      style={[styles.label, isSide && styles.labelSide]}
+    >
       {children}
+      {indicator === 'icon' && ctx?.required && (
+        <html.span style={styles.necessityIcon} aria-hidden={true}>
+          {' *'}
+        </html.span>
+      )}
+      {indicator === 'label' && (
+        <html.span style={styles.necessityLabel}>
+          {ctx?.required ? ' (required)' : ' (optional)'}
+        </html.span>
+      )}
     </html.label>
   )
 }

package/src/components/Field/FieldContext.ts

@@ -1,10 +1,15 @@
 import {createContext, useContext} from 'react'
+import type {LabelPosition, NecessityIndicator} from '../Form/FormContext'
 
 interface FieldContextValue {
   controlId: string
   descriptionId: string
   errorId: string
   invalid: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
+  necessityIndicator?: NecessityIndicator
   field?: {
     value: unknown
     onChange: (...event: unknown[]) => void

package/src/components/Field/styles.css.ts

@@ -9,11 +9,22 @@ export const styles = css.create({
     flexDirection: 'column',
     gap: spacing.xs,
   },
+  rootSide: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: spacing.md,
+  },
   label: {
     fontSize: typography.fontSizeSm,
     fontWeight: typography.fontWeightMedium,
     color: colors.text,
   },
+  labelSide: {
+    minWidth: 120,
+    paddingTop: spacing.sm,
+    flexShrink: 0,
+  },
   description: {
     fontSize: typography.fontSizeXs,
     color: colors.textMuted,
@@ -22,4 +33,19 @@ export const styles = css.create({
     fontSize: typography.fontSizeXs,
     color: colors.error,
   },
+  fieldContent: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacing.xs,
+    flex: 1,
+    minWidth: 0,
+  },
+  necessityIcon: {
+    color: colors.error,
+  },
+  necessityLabel: {
+    color: colors.textMuted,
+    fontWeight: typography.fontWeightNormal,
+    fontSize: typography.fontSizeXs,
+  },
 })

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

@@ -1,3 +1,4 @@
+import {useState} from 'react'
 import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn, userEvent, within} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
@@ -36,8 +37,19 @@ const FeedbackSchema = Schema.Struct({
   ),
 })
 
+const ProfileSchema = Schema.Struct({
+  name: Schema.String.pipe(
+    Schema.minLength(2, {message: () => 'Name must be at least 2 characters'}),
+  ),
+  email: Schema.String.pipe(
+    Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {message: () => 'Enter a valid email'}),
+  ),
+  bio: Schema.String,
+})
+
 const wrapStyles = css.create({
   wrap: {maxWidth: 400},
+  wrapWide: {maxWidth: 600},
 })
 
 // --- Stories ---
@@ -241,3 +253,266 @@ export const StandaloneFieldStillWorks: Story = {
     await expect(alert).toHaveTextContent('Manual error — no Form wrapper needed.')
   },
 }
+
+// --- New feature stories ---
+
+export const NecessityIndicatorIcon: Story = {
+  name: 'Necessity indicator — icon',
+  render: () => (
+    <html.div style={wrapStyles.wrap}>
+      <Form
+        schema={ProfileSchema}
+        defaultValues={{name: '', email: '', bio: ''}}
+        onSubmit={fn()}
+        necessityIndicator="icon"
+      >
+        <Fieldset.Root gap="md">
+          <Field.Root name="name" required>
+            <Field.Label>Full name</Field.Label>
+            <Input placeholder="Jane Doe" />
+            <Field.Error />
+          </Field.Root>
+
+          <Field.Root name="email" required>
+            <Field.Label>Email</Field.Label>
+            <Input type="email" placeholder="you@example.com" />
+            <Field.Error />
+          </Field.Root>
+
+          <Field.Root name="bio">
+            <Field.Label>Bio</Field.Label>
+            <Textarea placeholder="Tell us about yourself..." rows={3} />
+          </Field.Root>
+
+          <Button type="submit">Save</Button>
+        </Fieldset.Root>
+      </Form>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    // Required fields show asterisk
+    const nameLabel = canvas.getByText('Full name')
+    await expect(nameLabel.closest('label')?.textContent).toContain('*')
+
+    const emailLabel = canvas.getByText('Email')
+    await expect(emailLabel.closest('label')?.textContent).toContain('*')
+
+    // Optional field has no asterisk
+    const bioLabel = canvas.getByText('Bio')
+    await expect(bioLabel.closest('label')?.textContent).not.toContain('*')
+  },
+}
+
+export const NecessityIndicatorLabel: Story = {
+  name: 'Necessity indicator — label',
+  render: () => (
+    <html.div style={wrapStyles.wrap}>
+      <Form
+        schema={ProfileSchema}
+        defaultValues={{name: '', email: '', bio: ''}}
+        onSubmit={fn()}
+        necessityIndicator="label"
+      >
+        <Fieldset.Root gap="md">
+          <Field.Root name="name" required>
+            <Field.Label>Full name</Field.Label>
+            <Input placeholder="Jane Doe" />
+            <Field.Error />
+          </Field.Root>
+
+          <Field.Root name="email" required>
+            <Field.Label>Email</Field.Label>
+            <Input type="email" placeholder="you@example.com" />
+            <Field.Error />
+          </Field.Root>
+
+          <Field.Root name="bio">
+            <Field.Label>Bio</Field.Label>
+            <Textarea placeholder="Tell us about yourself..." rows={3} />
+          </Field.Root>
+
+          <Button type="submit">Save</Button>
+        </Fieldset.Root>
+      </Form>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    // Required fields show "(required)" — there are two
+    const requiredIndicators = canvas.getAllByText('(required)')
+    await expect(requiredIndicators).toHaveLength(2)
+
+    // Optional field shows "(optional)"
+    await expect(canvas.getByText('(optional)')).toBeInTheDocument()
+  },
+}
+
+export const FocusFirstInvalid: Story = {
+  name: 'Focus first invalid on submit',
+  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}) => {
+    // Submit the form with empty fields
+    const button = canvas.getByRole('button', {name: 'Log in'})
+    await userEvent.click(button)
+
+    // First invalid field (username) should be focused
+    const usernameInput = canvas.getByPlaceholderText('Enter username')
+    await expect(usernameInput).toHaveFocus()
+  },
+}
+
+export const FormDisabled: Story = {
+  name: 'Form disabled',
+  render: () => (
+    <html.div style={wrapStyles.wrap}>
+      <Form
+        schema={LoginSchema}
+        defaultValues={{username: 'johndoe', password: 'supersecret1'}}
+        onSubmit={fn()}
+        disabled
+      >
+        <Fieldset.Root gap="md">
+          <Field.Root name="username">
+            <Field.Label>Username</Field.Label>
+            <Input placeholder="Enter username" />
+          </Field.Root>
+
+          <Field.Root name="password">
+            <Field.Label>Password</Field.Label>
+            <Input type="password" placeholder="Enter password" />
+          </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')
+    await expect(usernameInput).toBeDisabled()
+    await expect(passwordInput).toBeDisabled()
+  },
+}
+
+export const LabelPositionSide: Story = {
+  name: 'Label position — side',
+  render: () => (
+    <html.div style={wrapStyles.wrapWide}>
+      <Form
+        schema={ProfileSchema}
+        defaultValues={{name: '', email: '', bio: ''}}
+        onSubmit={fn()}
+        labelPosition="side"
+        necessityIndicator="icon"
+      >
+        {({formState}) => (
+          <Fieldset.Root gap="md">
+            <Field.Root name="name" required>
+              <Field.Label>Full name</Field.Label>
+              <Input placeholder="Jane Doe" />
+              <Field.Error />
+            </Field.Root>
+
+            <Field.Root name="email" required>
+              <Field.Label>Email</Field.Label>
+              <Input type="email" placeholder="you@example.com" />
+              <Field.Description>We will never share your email.</Field.Description>
+              <Field.Error />
+            </Field.Root>
+
+            <Field.Root name="bio">
+              <Field.Label>Bio</Field.Label>
+              <Textarea placeholder="Tell us about yourself..." rows={3} />
+            </Field.Root>
+
+            <Button type="submit" disabled={!formState.isValid}>
+              Save profile
+            </Button>
+          </Fieldset.Root>
+        )}
+      </Form>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByPlaceholderText('Jane Doe')).toBeInTheDocument()
+    await expect(canvas.getByPlaceholderText('you@example.com')).toBeInTheDocument()
+  },
+}
+
+export const ServerValidationErrors: Story = {
+  name: 'Server validation errors',
+  render: () => {
+    function ServerErrorDemo() {
+      const [serverErrors, setServerErrors] = useState<
+        Partial<Record<'username' | 'password', string>>
+      >({})
+
+      return (
+        <html.div style={wrapStyles.wrap}>
+          <Form
+            schema={LoginSchema}
+            defaultValues={{username: '', password: ''}}
+            onSubmit={() => {
+              // Simulate server response with errors
+              setServerErrors({username: 'This username is already taken'})
+            }}
+            validationErrors={serverErrors}
+          >
+            <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">Register</Button>
+            </Fieldset.Root>
+          </Form>
+        </html.div>
+      )
+    }
+
+    return <ServerErrorDemo />
+  },
+  play: async ({canvas}) => {
+    const usernameInput = canvas.getByPlaceholderText('Enter username')
+    const passwordInput = canvas.getByPlaceholderText('Enter password')
+
+    // Fill valid values and submit
+    await userEvent.type(usernameInput, 'johndoe')
+    await userEvent.type(passwordInput, 'supersecret1')
+
+    const button = canvas.getByRole('button', {name: 'Register'})
+    await userEvent.click(button)
+
+    // Server error appears
+    const alert = await canvas.findByRole('alert')
+    await expect(alert).toHaveTextContent('This username is already taken')
+  },
+}

package/src/components/Form/Form.tsx

@@ -1,27 +1,48 @@
-import {type ReactNode, useCallback, useEffect, useRef} from 'react'
-import {html} from 'react-strict-dom'
+import {type ReactNode, useCallback, useEffect, useMemo, useRef} from 'react'
+import {css, html} from 'react-strict-dom'
 import {
   useForm,
   FormProvider,
   type UseFormReturn,
   type DefaultValues,
   type FieldValues,
+  type FieldErrors,
+  type Path,
 } from 'react-hook-form'
 import {effectTsResolver} from '@hookform/resolvers/effect-ts'
 import type {Schema} from 'effect'
-import {FormContext} from './FormContext'
+import {
+  FormContext,
+  type LabelPosition,
+  type NecessityIndicator,
+} from './FormContext'
 
 export interface FormProps<T extends FieldValues> {
   schema: Schema.Schema<T>
   defaultValues: DefaultValues<T>
   onSubmit: (data: T) => void | Promise<void>
+  disabled?: boolean
+  labelPosition?: LabelPosition
+  necessityIndicator?: NecessityIndicator
+  validationErrors?: Partial<Record<Path<T>, string>>
   children: ReactNode | ((methods: UseFormReturn<T>) => ReactNode)
 }
 
+const formStyles = css.create({
+  disabled: {
+    opacity: 0.5,
+    pointerEvents: 'none',
+  },
+})
+
 export function Form<T extends FieldValues>({
   schema,
   defaultValues,
   onSubmit,
+  disabled = false,
+  labelPosition = 'top',
+  necessityIndicator = false,
+  validationErrors,
   children,
 }: FormProps<T>) {
   const methods = useForm<T>({
@@ -31,13 +52,49 @@ export function Form<T extends FieldValues>({
     reValidateMode: 'onChange',
   })
 
+  // Sync server-side validation errors into RHF
+  const prevErrorKeysRef = useRef<string[]>([])
+  useEffect(() => {
+    const prevKeys = prevErrorKeysRef.current
+    const nextKeys = validationErrors ? Object.keys(validationErrors) : []
+
+    // Clear errors that were removed
+    for (const key of prevKeys) {
+      if (!nextKeys.includes(key)) {
+        methods.clearErrors(key as Path<T>)
+      }
+    }
+
+    // Set new errors
+    if (validationErrors) {
+      for (const [key, message] of Object.entries(validationErrors)) {
+        if (message) {
+          methods.setError(key as Path<T>, {type: 'server', message: message as string})
+        }
+      }
+    }
+
+    prevErrorKeysRef.current = nextKeys
+  }, [validationErrors, methods])
+
   const formRef = useRef<HTMLFormElement>(null)
+
+  const onInvalid = useCallback(
+    (errors: FieldErrors<T>) => {
+      const firstField = Object.keys(errors)[0]
+      if (firstField) {
+        methods.setFocus(firstField as Path<T>)
+      }
+    },
+    [methods],
+  )
+
   const handleSubmit = useCallback(
     (e: Event) => {
       e.preventDefault()
-      void methods.handleSubmit(onSubmit)()
+      void methods.handleSubmit(onSubmit, onInvalid)()
     },
-    [methods, onSubmit],
+    [methods, onSubmit, onInvalid],
   )
 
   useEffect(() => {
@@ -47,10 +104,19 @@ export function Form<T extends FieldValues>({
     return () => el.removeEventListener('submit', handleSubmit)
   }, [handleSubmit])
 
+  const formCtx = useMemo(
+    () => ({disabled, labelPosition, necessityIndicator}),
+    [disabled, labelPosition, necessityIndicator],
+  )
+
   return (
     <FormProvider {...methods}>
-      <FormContext.Provider value={true}>
-        <html.form ref={formRef}>
+      <FormContext.Provider value={formCtx}>
+        <html.form
+          ref={formRef}
+          aria-disabled={disabled || undefined}
+          style={disabled && formStyles.disabled}
+        >
           {typeof children === 'function' ? children(methods) : children}
         </html.form>
       </FormContext.Provider>

package/src/components/Form/FormContext.ts

@@ -1,6 +1,15 @@
 import {createContext, useContext} from 'react'
 
-export const FormContext = createContext(false)
+export type LabelPosition = 'top' | 'side'
+export type NecessityIndicator = 'icon' | 'label' | false
+
+export interface FormContextValue {
+  disabled: boolean
+  labelPosition: LabelPosition
+  necessityIndicator: NecessityIndicator
+}
+
+export const FormContext = createContext<FormContextValue | null>(null)
 
 export function useFormContext() {
   return useContext(FormContext)

package/src/components/Input/Input.tsx

@@ -59,6 +59,7 @@ export function Input({
   const effectiveOnChange = onChange ?? fieldCtx?.onChange
   const effectiveOnBlur = onBlur ?? fieldCtx?.onBlur
   const effectiveRef = ref ?? fieldCtx?.ref
+  const effectiveDisabled = disabled ?? ctx?.disabled
   const effectiveVariant = ctx?.invalid ? 'error' : variant
 
   // react-strict-dom omits web-only `pattern` from its types, but the
@@ -76,7 +77,7 @@ export function Input({
       autoComplete={autoComplete}
       value={effectiveValue}
       defaultValue={defaultValue}
-      disabled={disabled}
+      disabled={effectiveDisabled}
       aria-describedby={
         ctx ? `${ctx.descriptionId} ${ctx.invalid ? ctx.errorId : ''}`.trim() : undefined
       }