@titan-design/react-ui 0.1.0 → 0.2.5

package/src/components/ui/form-field/FormField.test.tsx

@@ -0,0 +1,280 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { FormField, FormSection, FormActions, FormRow } from './FormField'
+
+describe('FormField', () => {
+  it('renders label and children', () => {
+    render(
+      <FormField label="Email">
+        <input type="email" placeholder="Enter email" />
+      </FormField>
+    )
+    expect(screen.getByText('Email')).toBeInTheDocument()
+    expect(screen.getByPlaceholderText('Enter email')).toBeInTheDocument()
+  })
+
+  it('renders without a label', () => {
+    render(
+      <FormField>
+        <input placeholder="No label" />
+      </FormField>
+    )
+    expect(screen.getByPlaceholderText('No label')).toBeInTheDocument()
+  })
+
+  describe('required indicator', () => {
+    it('shows asterisk when isRequired is true', () => {
+      render(
+        <FormField label="Name" isRequired>
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('*')).toBeInTheDocument()
+    })
+
+    it('does not show asterisk when isRequired is false', () => {
+      render(
+        <FormField label="Name">
+          <input />
+        </FormField>
+      )
+      expect(screen.queryByText('*')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('helper and error text', () => {
+    it('renders helper text', () => {
+      render(
+        <FormField label="Email" helperText="We will never share your email.">
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('We will never share your email.')).toBeInTheDocument()
+    })
+
+    it('renders error message', () => {
+      render(
+        <FormField label="Password" errorMessage="Password is too short.">
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('Password is too short.')).toBeInTheDocument()
+    })
+
+    it('shows error message instead of helper text when both are provided', () => {
+      render(
+        <FormField
+          label="Email"
+          helperText="Enter a valid email"
+          errorMessage="Invalid email"
+        >
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('Invalid email')).toBeInTheDocument()
+      expect(screen.queryByText('Enter a valid email')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('disabled state', () => {
+    it('applies disabled styling when isDisabled is true', () => {
+      const { container } = render(
+        <FormField label="Name" isDisabled>
+          <input />
+        </FormField>
+      )
+      expect(container).toBeInTheDocument()
+    })
+  })
+
+  describe('label sizes', () => {
+    it('renders with sm label size', () => {
+      render(
+        <FormField label="Small Label" labelSize="sm">
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('Small Label')).toBeInTheDocument()
+    })
+
+    it('renders with md label size (default)', () => {
+      render(
+        <FormField label="Medium Label" labelSize="md">
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('Medium Label')).toBeInTheDocument()
+    })
+
+    it('renders with lg label size', () => {
+      render(
+        <FormField label="Large Label" labelSize="lg">
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('Large Label')).toBeInTheDocument()
+    })
+  })
+
+  describe('orientation', () => {
+    it('renders in vertical orientation (default)', () => {
+      const { container } = render(
+        <FormField label="Vertical" orientation="vertical">
+          <input />
+        </FormField>
+      )
+      expect(container).toBeInTheDocument()
+    })
+
+    it('renders in horizontal orientation', () => {
+      const { container } = render(
+        <FormField label="Horizontal" orientation="horizontal" labelWidth={120}>
+          <input />
+        </FormField>
+      )
+      expect(container).toBeInTheDocument()
+    })
+  })
+
+  describe('help content', () => {
+    it('renders help indicator when helpContent is provided', () => {
+      render(
+        <FormField label="API Key" helpContent="Found in settings">
+          <input />
+        </FormField>
+      )
+      expect(screen.getByText('API Key')).toBeInTheDocument()
+    })
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(
+        <FormField label="Email" isRequired helperText="Enter a valid email">
+          <input type="email" aria-label="Email" />
+        </FormField>
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it('has no accessibility violations with error', async () => {
+      const { container } = render(
+        <FormField label="Password" errorMessage="Too short">
+          <input type="password" aria-label="Password" />
+        </FormField>
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+})
+
+describe('FormSection', () => {
+  it('renders title and description', () => {
+    render(
+      <FormSection title="Personal Info" description="Enter your details">
+        <span>Form fields</span>
+      </FormSection>
+    )
+    expect(screen.getByText('Personal Info')).toBeInTheDocument()
+    expect(screen.getByText('Enter your details')).toBeInTheDocument()
+    expect(screen.getByText('Form fields')).toBeInTheDocument()
+  })
+
+  it('renders without title and description', () => {
+    render(
+      <FormSection>
+        <span>Just fields</span>
+      </FormSection>
+    )
+    expect(screen.getByText('Just fields')).toBeInTheDocument()
+  })
+
+  it('has group accessibility role', () => {
+    render(
+      <FormSection title="Section">
+        <span>Content</span>
+      </FormSection>
+    )
+    expect(screen.getByRole('group')).toBeInTheDocument()
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(
+        <FormSection title="Section" description="Description">
+          <span>Content</span>
+        </FormSection>
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+})
+
+describe('FormActions', () => {
+  it('renders children', () => {
+    render(
+      <FormActions>
+        <button>Cancel</button>
+        <button>Submit</button>
+      </FormActions>
+    )
+    expect(screen.getByText('Cancel')).toBeInTheDocument()
+    expect(screen.getByText('Submit')).toBeInTheDocument()
+  })
+
+  it('renders with different alignments', () => {
+    const { rerender } = render(
+      <FormActions align="left">
+        <button>Action</button>
+      </FormActions>
+    )
+    expect(screen.getByText('Action')).toBeInTheDocument()
+
+    rerender(
+      <FormActions align="center">
+        <button>Action</button>
+      </FormActions>
+    )
+    expect(screen.getByText('Action')).toBeInTheDocument()
+
+    rerender(
+      <FormActions align="between">
+        <button>Action</button>
+      </FormActions>
+    )
+    expect(screen.getByText('Action')).toBeInTheDocument()
+  })
+})
+
+describe('FormRow', () => {
+  it('renders children in a row', () => {
+    render(
+      <FormRow>
+        <span>Field 1</span>
+        <span>Field 2</span>
+      </FormRow>
+    )
+    expect(screen.getByText('Field 1')).toBeInTheDocument()
+    expect(screen.getByText('Field 2')).toBeInTheDocument()
+  })
+
+  it('renders with different gap sizes', () => {
+    const { rerender } = render(
+      <FormRow gap="sm">
+        <span>Field</span>
+      </FormRow>
+    )
+    expect(screen.getByText('Field')).toBeInTheDocument()
+
+    rerender(
+      <FormRow gap="lg">
+        <span>Field</span>
+      </FormRow>
+    )
+    expect(screen.getByText('Field')).toBeInTheDocument()
+  })
+})

package/src/components/ui/form-field/FormField.tsx

@@ -0,0 +1,308 @@
+import React from 'react'
+import { View, Text, type ViewProps } from 'react-native'
+import { cn } from '../../../utils/cn'
+
+export interface FormFieldProps extends ViewProps {
+  /** Label text */
+  label?: string
+  /** Whether the field is required */
+  isRequired?: boolean
+  /** Helper text shown below the input */
+  helperText?: string
+  /** Error message (replaces helper text when present) */
+  errorMessage?: string
+  /** Whether the field is disabled */
+  isDisabled?: boolean
+  /** Whether the field is read-only */
+  isReadOnly?: boolean
+  /** Help tooltip content */
+  helpContent?: React.ReactNode
+  /** Size of the label */
+  labelSize?: 'sm' | 'md' | 'lg'
+  /** Direction of the layout */
+  orientation?: 'vertical' | 'horizontal'
+  /** Label width (for horizontal layout) */
+  labelWidth?: number | string
+  /** Additional className */
+  className?: string
+  children?: React.ReactNode
+}
+
+const labelSizeStyles = {
+  sm: 'text-xs',
+  md: 'text-sm',
+  lg: 'text-base',
+}
+
+/**
+ * FormField component for wrapping form inputs with label, help text, and error states.
+ *
+ * @example
+ * // Basic usage
+ * <FormField label="Email" isRequired>
+ *   <Input placeholder="Enter your email" />
+ * </FormField>
+ *
+ * @example
+ * // With error
+ * <FormField
+ *   label="Password"
+ *   isRequired
+ *   errorMessage="Password must be at least 8 characters"
+ * >
+ *   <Input type="password" />
+ * </FormField>
+ *
+ * @example
+ * // Horizontal layout
+ * <FormField label="Name" orientation="horizontal" labelWidth={100}>
+ *   <Input />
+ * </FormField>
+ */
+export function FormField({
+  label,
+  isRequired = false,
+  helperText,
+  errorMessage,
+  isDisabled = false,
+  isReadOnly = false,
+  helpContent,
+  labelSize = 'sm',
+  orientation = 'vertical',
+  labelWidth,
+  className,
+  children,
+  ...props
+}: FormFieldProps) {
+  const isInvalid = !!errorMessage
+  const isHorizontal = orientation === 'horizontal'
+
+  // Generate unique IDs for accessibility
+  const fieldId = React.useId()
+  const helperId = `${fieldId}-helper`
+  const errorId = `${fieldId}-error`
+
+  return (
+    <View
+      className={cn(
+        'w-full',
+        isHorizontal && 'flex-row items-start',
+        isDisabled && 'opacity-50',
+        className
+      )}
+      {...props}
+    >
+      {/* Label Section */}
+      {label && (
+        <View
+          className={cn(
+            'flex-row items-center',
+            isHorizontal ? 'pt-2' : 'mb-1.5'
+          )}
+          style={isHorizontal && labelWidth ? { width: labelWidth as number } : undefined}
+        >
+          <Text
+            className={cn(
+              'font-medium text-text-primary',
+              labelSizeStyles[labelSize]
+            )}
+          >
+            {label}
+            {isRequired && (
+              <Text className="text-status-error ml-0.5">*</Text>
+            )}
+          </Text>
+
+          {helpContent && (
+            <View className="ml-1">
+              {/* Inline help indicator - could use HelpTip here */}
+              <Text className="text-text-tertiary text-xs">ℹ</Text>
+            </View>
+          )}
+        </View>
+      )}
+
+      {/* Input Section */}
+      <View className={cn(isHorizontal && 'flex-1')}>
+        {/* Clone children to pass accessibility props */}
+        {React.Children.map(children, (child) => {
+          if (React.isValidElement(child)) {
+            const childProps = child.props as Record<string, any>
+            return React.cloneElement(child as React.ReactElement<any>, {
+              accessibilityHint: errorMessage || helperText || childProps.accessibilityHint,
+              accessibilityState: {
+                ...childProps.accessibilityState,
+                disabled: isDisabled || childProps.accessibilityState?.disabled,
+                ...(isInvalid ? { invalid: true } : {}),
+              },
+              isDisabled: isDisabled || childProps.isDisabled,
+              isReadOnly: isReadOnly || childProps.isReadOnly,
+              isInvalid: isInvalid || childProps.isInvalid,
+            })
+          }
+          return child
+        })}
+
+        {/* Helper/Error Text */}
+        {(helperText || errorMessage) && (
+          <Text
+            id={isInvalid ? errorId : helperId}
+            className={cn(
+              'text-xs mt-1.5',
+              isInvalid ? 'text-status-error' : 'text-text-tertiary'
+            )}
+          >
+            {errorMessage || helperText}
+          </Text>
+        )}
+      </View>
+    </View>
+  )
+}
+
+export interface FormSectionProps extends ViewProps {
+  /** Section title */
+  title?: string
+  /** Section description */
+  description?: string
+  /** Additional className */
+  className?: string
+  children?: React.ReactNode
+}
+
+/**
+ * FormSection component for grouping related form fields.
+ *
+ * @example
+ * <FormSection title="Personal Information" description="Enter your basic details">
+ *   <FormField label="Name">
+ *     <Input />
+ *   </FormField>
+ *   <FormField label="Email">
+ *     <Input />
+ *   </FormField>
+ * </FormSection>
+ */
+export function FormSection({
+  title,
+  description,
+  className,
+  children,
+  ...props
+}: FormSectionProps) {
+  return (
+    <View
+      className={cn('w-full', className)}
+      accessibilityRole={'group' as any}
+      accessibilityLabel={title}
+      {...props}
+    >
+      {(title || description) && (
+        <View className="mb-4">
+          {title && (
+            <Text className="text-lg font-semibold text-text-primary">
+              {title}
+            </Text>
+          )}
+          {description && (
+            <Text className="text-sm text-text-secondary mt-1">
+              {description}
+            </Text>
+          )}
+        </View>
+      )}
+
+      <View className="gap-4">
+        {children}
+      </View>
+    </View>
+  )
+}
+
+export interface FormActionsProps extends ViewProps {
+  /** Alignment of actions */
+  align?: 'left' | 'center' | 'right' | 'between'
+  /** Additional className */
+  className?: string
+  children?: React.ReactNode
+}
+
+const alignStyles = {
+  left: 'justify-start',
+  center: 'justify-center',
+  right: 'justify-end',
+  between: 'justify-between',
+}
+
+/**
+ * FormActions component for form action buttons.
+ *
+ * @example
+ * <FormActions align="right">
+ *   <Button variant="ghost">Cancel</Button>
+ *   <Button>Submit</Button>
+ * </FormActions>
+ */
+export function FormActions({
+  align = 'right',
+  className,
+  children,
+  ...props
+}: FormActionsProps) {
+  return (
+    <View
+      className={cn(
+        'flex-row items-center gap-3 pt-4',
+        'border-t border-border-default mt-4',
+        alignStyles[align],
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </View>
+  )
+}
+
+export interface FormRowProps extends ViewProps {
+  /** Gap between items */
+  gap?: 'sm' | 'md' | 'lg'
+  /** Additional className */
+  className?: string
+  children?: React.ReactNode
+}
+
+const gapStyles = {
+  sm: 'gap-2',
+  md: 'gap-4',
+  lg: 'gap-6',
+}
+
+/**
+ * FormRow component for laying out multiple form fields horizontally.
+ *
+ * @example
+ * <FormRow>
+ *   <FormField label="First Name" className="flex-1">
+ *     <Input />
+ *   </FormField>
+ *   <FormField label="Last Name" className="flex-1">
+ *     <Input />
+ *   </FormField>
+ * </FormRow>
+ */
+export function FormRow({
+  gap = 'md',
+  className,
+  children,
+  ...props
+}: FormRowProps) {
+  return (
+    <View
+      className={cn('flex-row items-start', gapStyles[gap], className)}
+      {...props}
+    >
+      {children}
+    </View>
+  )
+}

package/src/components/ui/form-field/index.ts

@@ -0,0 +1,2 @@
+export { FormField, FormSection, FormActions, FormRow } from './FormField'
+export type { FormFieldProps, FormSectionProps, FormActionsProps, FormRowProps } from './FormField'