@kenpan/zds-r8f3v1 0.2.0 → 0.3.0

package/guidelines/components/dialog.md

@@ -1,119 +1,196 @@
 # Dialog Component
 
-The Dialog component creates modal overlays for focused user interactions.
+**Purpose**: Display focused content that requires user attention or action. Use for confirmations, forms, and important messages.
 
-## When to Use
+**Import**:
+```tsx
+import { Dialog, DialogHeader, DialogFooter, Button } from '@kenpan/zds-r8f3v1'
+```
+
+## Props
+
+### Dialog Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | - | **Required**. Controls dialog visibility |
+| `onClose` | `() => void` | - | **Required**. Called when dialog should close |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Dialog width |
+| `children` | `ReactNode` | - | Dialog content |
 
-- **Confirmation dialogs** - Confirm destructive or irreversible actions
-- **Form dialogs** - Collect focused input from users
-- **Information dialogs** - Display important information that requires acknowledgment
-- **Selection dialogs** - Allow users to make a choice from options
+### DialogHeader Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | - | Header title |
+| `subtitle` | `string` | - | Optional subtitle |
+| `onClose` | `() => void` | - | Close button handler |
+| `icon` | `ReactNode` | - | Optional icon before title |
+
+### DialogFooter Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Footer content (usually buttons) |
+| `align` | `'left' \| 'right' \| 'center'` | `'right'` | Button alignment |
 
 ## Basic Usage
 
 ```tsx
-import { Dialog, DialogHeader, DialogContent, DialogFooter, Button } from '@kenpan/zds-r8f3v1'
+import { useState } from 'react'
+import { Dialog, DialogHeader, DialogFooter, Button } from '@kenpan/zds-r8f3v1'
+
+function MyComponent() {
+  const [open, setOpen] = useState(false)
 
-function ConfirmDialog({ open, onClose, onConfirm }) {
   return (
-    <Dialog open={open} onClose={onClose}>
-      <DialogHeader 
-        title="Delete Item" 
-        onClose={onClose}
-      />
-      <DialogContent>
-        Are you sure you want to delete this item? This action cannot be undone.
-      </DialogContent>
-      <DialogFooter>
-        <Button variant="secondary-gray" onClick={onClose}>
-          Cancel
-        </Button>
-        <Button variant="primary" color="destructive" onClick={onConfirm}>
-          Delete
-        </Button>
-      </DialogFooter>
-    </Dialog>
+    <>
+      <Button onClick={() => setOpen(true)}>Open Dialog</Button>
+      
+      <Dialog open={open} onClose={() => setOpen(false)}>
+        <DialogHeader 
+          title="Confirm Action" 
+          onClose={() => setOpen(false)} 
+        />
+        
+        <Box sx={{ p: 6 }}>
+          <Typography>Are you sure you want to continue?</Typography>
+        </Box>
+        
+        <DialogFooter>
+          <Button variant="secondary-gray" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            Confirm
+          </Button>
+        </DialogFooter>
+      </Dialog>
+    </>
   )
 }
 ```
 
-## Dialog Sizes
+## Sizes
 
 ```tsx
-// Small (400px) - Simple confirmations
-<Dialog size="sm">...</Dialog>
-
-// Medium (560px) - Default for most use cases
-<Dialog size="md">...</Dialog>
+<Dialog open={open} onClose={onClose} size="xs">  // 400px
+<Dialog open={open} onClose={onClose} size="sm">  // 480px
+<Dialog open={open} onClose={onClose} size="md">  // 560px (default)
+<Dialog open={open} onClose={onClose} size="lg">  // 640px
+<Dialog open={open} onClose={onClose} size="xl">  // 800px
+```
 
-// Large (720px) - Complex forms or content
-<Dialog size="lg">...</Dialog>
+## With Form
 
-// Full width (with padding)
-<Dialog fullWidth>...</Dialog>
+```tsx
+<Dialog open={open} onClose={onClose} size="lg">
+  <DialogHeader title="Create New Item" onClose={onClose} />
+  
+  <Box sx={{ p: 6 }}>
+    <Stack spacing={4}>
+      <InputField label="Name" placeholder="Enter name" />
+      <InputField label="Description" placeholder="Enter description" multiline rows={3} />
+    </Stack>
+  </Box>
+  
+  <DialogFooter>
+    <Button variant="secondary-gray" onClick={onClose}>Cancel</Button>
+    <Button variant="primary" onClick={handleSubmit}>Create</Button>
+  </DialogFooter>
+</Dialog>
 ```
 
-## DialogHeader
+## Confirmation Dialog
 
 ```tsx
-// Basic header with title
-<DialogHeader title="Edit Profile" onClose={handleClose} />
-
-// With supporting text
-<DialogHeader 
-  title="Import Data" 
-  supportingText="Upload a CSV file to import your data"
-  onClose={handleClose}
-/>
-
-// With icon
-<DialogHeader 
-  title="Warning" 
-  icon={<AlertIcon />}
-  onClose={handleClose}
-/>
+<Dialog open={open} onClose={onClose} size="sm">
+  <DialogHeader 
+    title="Delete Item?" 
+    onClose={onClose}
+  />
+  
+  <Box sx={{ p: 6 }}>
+    <Typography>
+      This action cannot be undone. The item will be permanently deleted.
+    </Typography>
+  </Box>
+  
+  <DialogFooter>
+    <Button variant="secondary-gray" onClick={onClose}>Cancel</Button>
+    <Button variant="primary" destructive onClick={handleDelete}>
+      Delete
+    </Button>
+  </DialogFooter>
+</Dialog>
 ```
 
-## DialogContent
+## With Icon in Header
 
 ```tsx
-// Standard content
-<DialogContent>
-  Your content here...
-</DialogContent>
-
-// With custom padding
-<DialogContent padding="none">
-  <Table />
-</DialogContent>
-
-// Scrollable content
-<DialogContent maxHeight={400}>
-  Long content that scrolls...
-</DialogContent>
+import { AlertTriangleIcon } from '@kenpan/zds-r8f3v1/icons'
+import { FeaturedIcon } from '@kenpan/zds-r8f3v1'
+
+<Dialog open={open} onClose={onClose} size="sm">
+  <DialogHeader 
+    title="Warning"
+    subtitle="Please review before continuing"
+    onClose={onClose}
+    icon={
+      <FeaturedIcon color="warning" size="lg" theme="light">
+        <AlertTriangleIcon />
+      </FeaturedIcon>
+    }
+  />
+  {/* ... */}
+</Dialog>
 ```
 
-## DialogFooter
+## Usage Guidelines
+
+### Do:
+- Use dialogs for focused tasks that require completion
+- Keep dialog content focused and minimal
+- Provide clear action buttons (Cancel/Confirm pattern)
+- Use appropriate size for content
+- Close dialog after action completion
+
+### Don't:
+- Don't nest dialogs inside other dialogs
+- Don't use dialogs for simple notifications (use Toast instead)
+- Don't put long forms in dialogs (use a page instead)
+- Don't forget to handle the close action
+- Don't use dialogs for navigation
 
+## Common Patterns
+
+### Alert/Warning Dialog
 ```tsx
-// Standard footer with cancel/confirm
-<DialogFooter>
-  <Button variant="secondary-gray" onClick={onClose}>Cancel</Button>
-  <Button variant="primary" onClick={onConfirm}>Confirm</Button>
-</DialogFooter>
-
-// Left-aligned action
-<DialogFooter leftAction={<Button variant="link-gray">Learn more</Button>}>
-  <Button variant="secondary-gray" onClick={onClose}>Cancel</Button>
-  <Button variant="primary" onClick={onConfirm}>Save</Button>
-</DialogFooter>
+<Dialog open={open} onClose={onClose} size="sm">
+  <DialogHeader title="Are you sure?" onClose={onClose} />
+  <Box sx={{ p: 6 }}>
+    <Alert color="warning">This action cannot be undone.</Alert>
+  </Box>
+  <DialogFooter>
+    <Button variant="secondary-gray" onClick={onClose}>Cancel</Button>
+    <Button variant="primary" destructive onClick={handleConfirm}>Proceed</Button>
+  </DialogFooter>
+</Dialog>
 ```
 
-## Best Practices
-
-1. **Clear titles** - Use action-oriented titles like "Delete Item?" not "Warning"
-2. **Concise content** - Keep dialog content brief and focused
-3. **Clear actions** - Primary action on the right, cancel on the left
-4. **Escape to close** - Always allow closing with Escape key
-5. **Focus management** - Focus should trap inside the dialog
-6. **Avoid nested dialogs** - Don't open dialogs from within dialogs
+### Info Dialog
+```tsx
+<Dialog open={open} onClose={onClose} size="md">
+  <DialogHeader 
+    title="About This Feature" 
+    subtitle="Learn how it works"
+    onClose={onClose} 
+  />
+  <Box sx={{ p: 6 }}>
+    <Typography>Detailed information here...</Typography>
+  </Box>
+  <DialogFooter>
+    <Button variant="primary" onClick={onClose}>Got it</Button>
+  </DialogFooter>
+</Dialog>
+```

package/guidelines/components/forms.md

@@ -1,151 +1,313 @@
 # Form Components
 
-ZDS provides a comprehensive set of form components for building accessible, user-friendly forms.
+**Purpose**: Collect user input through various form controls.
+
+**Import**:
+```tsx
+import { 
+  InputField, 
+  InputNumber,
+  InputSearch,
+  Checkbox, 
+  Radio, 
+  Switch, 
+  Slider 
+} from '@kenpan/zds-r8f3v1'
+```
 
 ## InputField
 
-Text input with label, helper text, and validation states.
+Text input with label, hint, and validation support.
 
-```tsx
-import { InputField } from '@kenpan/zds-r8f3v1'
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Field label |
+| `placeholder` | `string` | - | Placeholder text |
+| `hint` | `string` | - | Helper text below input |
+| `error` | `boolean` | `false` | Show error state |
+| `errorMessage` | `string` | - | Error message text |
+| `disabled` | `boolean` | `false` | Disable input |
+| `required` | `boolean` | `false` | Mark as required |
+| `value` | `string` | - | Controlled value |
+| `onChange` | `(e) => void` | - | Change handler |
+| `multiline` | `boolean` | `false` | Textarea mode |
+| `rows` | `number` | - | Textarea rows |
 
-// Basic usage
+### Examples
+
+```tsx
+// Basic input
 <InputField 
   label="Email" 
-  placeholder="Enter your email"
-  supportingText="We'll never share your email"
+  placeholder="Enter your email" 
+/>
+
+// With hint
+<InputField 
+  label="Password" 
+  type="password"
+  hint="Must be at least 8 characters" 
 />
 
-// With error state
+// With error
 <InputField 
   label="Email" 
-  error
-  supportingText="Please enter a valid email"
+  error 
+  errorMessage="Please enter a valid email" 
 />
 
-// With leading/trailing icons
+// Textarea
 <InputField 
-  label="Search" 
-  leadingIcon={<SearchIcon />}
+  label="Description" 
+  multiline 
+  rows={4}
+  placeholder="Enter description..." 
 />
 
-// Password input
+// Controlled
+const [value, setValue] = useState('')
 <InputField 
-  label="Password" 
-  type="password"
+  label="Name" 
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
 />
 ```
 
-## Checkbox
+## InputNumber
+
+Numeric input with increment/decrement buttons.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Field label |
+| `value` | `number` | - | Controlled value |
+| `onChange` | `(value: number) => void` | - | Value change handler |
+| `min` | `number` | - | Minimum value |
+| `max` | `number` | - | Maximum value |
+| `step` | `number` | `1` | Increment step |
+| `disabled` | `boolean` | `false` | Disable input |
+
+### Example
 
 ```tsx
-import { Checkbox } from '@kenpan/zds-r8f3v1'
+const [quantity, setQuantity] = useState(1)
+
+<InputNumber 
+  label="Quantity"
+  value={quantity}
+  onChange={setQuantity}
+  min={1}
+  max={100}
+/>
+```
+
+## InputSearch
+
+Search input with clear button.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string` | `'Search...'` | Placeholder text |
+| `value` | `string` | - | Controlled value |
+| `onChange` | `(value: string) => void` | - | Value change handler |
+| `onSearch` | `(value: string) => void` | - | Search submit handler |
+| `onClear` | `() => void` | - | Clear handler |
+
+### Example
+
+```tsx
+const [search, setSearch] = useState('')
+
+<InputSearch 
+  placeholder="Search items..."
+  value={search}
+  onChange={setSearch}
+  onSearch={(val) => console.log('Search:', val)}
+/>
+```
+
+## Checkbox
+
+Checkbox with label and optional description.
+
+### Props
 
-// Basic checkbox
-<Checkbox label="Accept terms" />
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Checkbox label |
+| `description` | `string` | - | Additional description |
+| `checked` | `boolean` | - | Controlled checked state |
+| `onChange` | `(e) => void` | - | Change handler |
+| `disabled` | `boolean` | `false` | Disable checkbox |
+| `indeterminate` | `boolean` | `false` | Indeterminate state |
+
+### Examples
+
+```tsx
+// Basic
+<Checkbox label="Accept terms and conditions" />
 
 // With description
 <Checkbox 
-  label="Subscribe to newsletter" 
-  description="Receive weekly updates about new features"
+  label="Email notifications" 
+  description="Receive updates about your account"
 />
 
 // Controlled
+const [checked, setChecked] = useState(false)
 <Checkbox 
-  checked={isChecked} 
-  onChange={(e) => setIsChecked(e.target.checked)}
   label="Remember me"
+  checked={checked}
+  onChange={(e) => setChecked(e.target.checked)}
 />
-
-// Indeterminate (for "select all" patterns)
-<Checkbox indeterminate label="Select all items" />
 ```
 
 ## Radio
 
+Radio button groups for mutually exclusive options.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Radio label |
+| `value` | `string` | - | Radio value |
+| `checked` | `boolean` | - | Checked state |
+| `onChange` | `(e) => void` | - | Change handler |
+| `disabled` | `boolean` | `false` | Disable radio |
+
+### Example
+
 ```tsx
-import { Radio, RadioGroup } from '@kenpan/zds-r8f3v1'
+const [selected, setSelected] = useState('option1')
 
-<RadioGroup value={value} onChange={handleChange}>
-  <Radio value="option1" label="Option 1" />
-  <Radio value="option2" label="Option 2" />
-  <Radio value="option3" label="Option 3" description="With description" />
+<RadioGroup value={selected} onChange={(e) => setSelected(e.target.value)}>
+  <Radio label="Option 1" value="option1" />
+  <Radio label="Option 2" value="option2" />
+  <Radio label="Option 3" value="option3" />
 </RadioGroup>
 ```
 
 ## Switch
 
-```tsx
-import { Switch } from '@kenpan/zds-r8f3v1'
+Toggle switch for on/off states.
 
-// Basic toggle
-<Switch label="Enable notifications" />
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Switch label |
+| `checked` | `boolean` | - | Controlled checked state |
+| `onChange` | `(e) => void` | - | Change handler |
+| `disabled` | `boolean` | `false` | Disable switch |
+| `size` | `'sm' \| 'md'` | `'md'` | Switch size |
 
-// With switch text (on/off labels)
-<Switch label="Dark mode" switchText />
+### Examples
+
+```tsx
+// Basic
+<Switch label="Enable notifications" />
 
 // Controlled
+const [enabled, setEnabled] = useState(false)
 <Switch 
-  checked={enabled} 
+  label="Dark mode"
+  checked={enabled}
   onChange={(e) => setEnabled(e.target.checked)}
-  label="Active"
 />
 ```
 
 ## Slider
 
+Range slider for numeric values.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Slider label |
+| `value` | `number` | - | Controlled value |
+| `onChange` | `(value: number) => void` | - | Value change handler |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `disabled` | `boolean` | `false` | Disable slider |
+| `showValue` | `boolean` | `true` | Show current value |
+
+### Example
+
 ```tsx
-import { Slider } from '@kenpan/zds-r8f3v1'
+const [volume, setVolume] = useState(50)
 
-// Single value
 <Slider 
-  value={50} 
-  onChange={(e, value) => setValue(value)}
+  label="Volume"
+  value={volume}
+  onChange={setVolume}
   min={0}
   max={100}
 />
+```
 
-// Range (dual handles)
-<Slider 
-  value={[20, 80]} 
-  onChange={(e, value) => setRange(value)}
-  mode="dual"
-/>
+## Form Layout Patterns
 
-// With labels
-<Slider 
-  value={50}
-  showLabels
-  labels={['Low', 'Medium', 'High']}
-/>
+### Vertical Form
+
+```tsx
+<Stack spacing={4}>
+  <InputField label="First Name" placeholder="Enter first name" />
+  <InputField label="Last Name" placeholder="Enter last name" />
+  <InputField label="Email" type="email" placeholder="Enter email" />
+  <Button variant="primary" fullWidth>Submit</Button>
+</Stack>
 ```
 
-## DatePicker
+### Inline Form Fields
 
 ```tsx
-import { DatePicker } from '@kenpan/zds-r8f3v1'
+<Stack direction="row" spacing={4}>
+  <InputField label="First Name" sx={{ flex: 1 }} />
+  <InputField label="Last Name" sx={{ flex: 1 }} />
+</Stack>
+```
 
-// Single date
-<DatePicker 
-  label="Select date"
-  value={date}
-  onChange={setDate}
-/>
+### Form with Validation
+
+```tsx
+const [email, setEmail] = useState('')
+const [error, setError] = useState(false)
+
+const validateEmail = (value) => {
+  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+  setError(!isValid)
+}
 
-// Date range
-<DatePicker 
-  label="Select range"
-  mode="range"
-  value={[startDate, endDate]}
-  onChange={setDateRange}
+<InputField 
+  label="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+  onBlur={() => validateEmail(email)}
+  error={error}
+  errorMessage="Please enter a valid email address"
 />
 ```
 
-## Form Layout Best Practices
+## Usage Guidelines
+
+### Do:
+- Always provide labels for form fields
+- Use appropriate input types (email, password, number)
+- Provide helpful hints for complex fields
+- Show clear error messages
+- Use controlled components for form state
 
-1. **Labels above inputs** - Place labels above form fields for better scanning
-2. **Helper text** - Use supportingText for additional context
-3. **Error messages** - Show inline validation errors near the field
-4. **Required indicators** - Mark required fields clearly
-5. **Logical grouping** - Group related fields together
-6. **Progressive disclosure** - Show advanced options only when needed
+### Don't:
+- Don't use placeholders as labels
+- Don't hide required field indicators
+- Don't use generic error messages
+- Don't nest form controls