torch-glare 2.5.5 → 2.6.0

package/docs/components/badge-field.md

@@ -1,712 +0,0 @@
----
-title: BadgeField
-description: Interactive input field with tag selection, search filtering, and keyboard navigation for multi-select scenarios.
-component: true
-group: Data Display
-keywords: [badge, field, tags, multi-select, input, chips, tokens, autocomplete]
----
-
-# BadgeField
-
-An advanced tag selection input component that combines badges with search functionality. Features keyboard navigation, filtering, and multi-select capabilities with a popover dropdown.
-
-## Installation
-
-TORCH Glare is a copy-in library: the CLI copies this component's source into your project
-(you do **not** install it from the npm package). Run `init` once, then `add`:
-
-```bash
-npx torch-glare@latest init
-npx torch-glare@latest add BadgeField
-```
-
-`add` also copies any components, hooks, and utilities that `BadgeField` depends on.
-
-## Imports
-
-```typescript
-import { BadgeField } from '@/components/BadgeField'
-import type { Tag } from '@/hooks/useTagSelection'
-```
-
-## Basic Usage
-
-```tsx
-import { BadgeField } from '@/components/BadgeField'
-import { useState } from 'react'
-
-export function BasicBadgeField() {
-  const [tags] = useState([
-    { id: '1', name: 'React', isSelected: false, variant: 'blue' },
-    { id: '2', name: 'TypeScript', isSelected: false, variant: 'purple' },
-    { id: '3', name: 'Next.js', isSelected: false, variant: 'slate' },
-  ])
-
-  return (
-    <BadgeField
-      tags={tags}
-      placeholder="Select technologies..."
-      size="M"
-    />
-  )
-}
-```
-
-## Examples
-
-### Technology Stack Selector
-
-Select multiple technologies with search.
-
-```tsx
-export function TechnologySelector() {
-  const [selectedTags, setSelectedTags] = useState<Tag[]>([])
-
-  const allTags: Tag[] = [
-    { id: '1', name: 'React', isSelected: false, variant: 'blue' },
-    { id: '2', name: 'TypeScript', isSelected: false, variant: 'purple' },
-    { id: '3', name: 'Next.js', isSelected: false, variant: 'slate' },
-    { id: '4', name: 'Tailwind CSS', isSelected: false, variant: 'green' },
-    { id: '5', name: 'Node.js', isSelected: false, variant: 'green' },
-    { id: '6', name: 'PostgreSQL', isSelected: false, variant: 'blue' },
-    { id: '7', name: 'MongoDB', isSelected: false, variant: 'green' },
-    { id: '8', name: 'GraphQL', isSelected: false, variant: 'purple' },
-    { id: '9', name: 'REST API', isSelected: false, variant: 'gray' },
-    { id: '10', name: 'Docker', isSelected: false, variant: 'blue' },
-  ]
-
-  return (
-    <div className="max-w-2xl">
-      <label className="block mb-2 font-medium">
-        Select Your Tech Stack
-      </label>
-
-      <BadgeField
-        tags={allTags}
-        placeholder="Search technologies..."
-        size="M"
-        onValueChange={setSelectedTags}
-      />
-
-      <div className="mt-4">
-        <p className="text-sm text-content-presentation-global-secondary">
-          Selected: {selectedTags.length} technologies
-        </p>
-      </div>
-    </div>
-  )
-}
-```
-
-### Category Filter
-
-Filter content by multiple categories.
-
-```tsx
-export function CategoryFilter() {
-  const categories: Tag[] = [
-    { id: 'design', name: 'Design', isSelected: false, variant: 'purple' },
-    { id: 'development', name: 'Development', isSelected: false, variant: 'blue' },
-    { id: 'marketing', name: 'Marketing', isSelected: false, variant: 'yellow' },
-    { id: 'sales', name: 'Sales', isSelected: false, variant: 'green' },
-    { id: 'support', name: 'Support', isSelected: false, variant: 'orange' },
-    { id: 'hr', name: 'Human Resources', isSelected: false, variant: 'rose' },
-    { id: 'finance', name: 'Finance', isSelected: false, variant: 'slate' },
-  ]
-
-  const [selectedCategories, setSelectedCategories] = useState<Tag[]>([])
-
-  return (
-    <div className="space-y-4">
-      <div>
-        <h3 className="font-semibold mb-2">Filter by Category</h3>
-        <BadgeField
-          tags={categories}
-          placeholder="Select categories to filter..."
-          size="M"
-          onValueChange={setSelectedCategories}
-        />
-      </div>
-
-      <div className="p-4 border rounded-lg">
-        <h4 className="font-medium mb-2">Filtered Results</h4>
-        {selectedCategories.length === 0 ? (
-          <p className="text-sm text-content-presentation-global-secondary">
-            Select categories to filter results
-          </p>
-        ) : (
-          <p className="text-sm">
-            Showing results for: {selectedCategories.map(c => c.name).join(', ')}
-          </p>
-        )}
-      </div>
-    </div>
-  )
-}
-```
-
-### Skills Selector
-
-Multi-select skills for job applications or profiles.
-
-```tsx
-export function SkillsSelector() {
-  const skills: Tag[] = [
-    { id: 'js', name: 'JavaScript', isSelected: false, variant: 'yellow' },
-    { id: 'ts', name: 'TypeScript', isSelected: false, variant: 'blue' },
-    { id: 'react', name: 'React', isSelected: false, variant: 'blue' },
-    { id: 'vue', name: 'Vue.js', isSelected: false, variant: 'green' },
-    { id: 'angular', name: 'Angular', isSelected: false, variant: 'red' },
-    { id: 'node', name: 'Node.js', isSelected: false, variant: 'green' },
-    { id: 'python', name: 'Python', isSelected: false, variant: 'blue' },
-    { id: 'java', name: 'Java', isSelected: false, variant: 'orange' },
-    { id: 'go', name: 'Go', isSelected: false, variant: 'green' },
-    { id: 'rust', name: 'Rust', isSelected: false, variant: 'orange' },
-    { id: 'sql', name: 'SQL', isSelected: false, variant: 'slate' },
-    { id: 'nosql', name: 'NoSQL', isSelected: false, variant: 'green' },
-    { id: 'aws', name: 'AWS', isSelected: false, variant: 'yellow' },
-    { id: 'azure', name: 'Azure', isSelected: false, variant: 'blue' },
-    { id: 'gcp', name: 'Google Cloud', isSelected: false, variant: 'blue' },
-  ]
-
-  const [selectedSkills, setSelectedSkills] = useState<Tag[]>([])
-
-  return (
-    <form className="max-w-2xl space-y-4">
-      <div>
-        <label className="block mb-2 font-medium">
-          Your Skills
-          <span className="text-content-presentation-global-secondary text-sm ml-2">
-            (Select all that apply)
-          </span>
-        </label>
-
-        <BadgeField
-          tags={skills}
-          placeholder="Type to search skills..."
-          size="M"
-          onValueChange={setSelectedSkills}
-        />
-      </div>
-
-      <div className="p-4 bg-background-presentation-global-secondary rounded-lg">
-        <h4 className="font-medium mb-2">Selected Skills ({selectedSkills.length})</h4>
-        {selectedSkills.length > 0 ? (
-          <div className="flex flex-wrap gap-2">
-            {selectedSkills.map(skill => (
-              <span key={skill.id} className="text-sm">
-                {skill.name}
-              </span>
-            ))}
-          </div>
-        ) : (
-          <p className="text-sm text-content-presentation-global-secondary">
-            No skills selected yet
-          </p>
-        )}
-      </div>
-    </form>
-  )
-}
-```
-
-### Project Tags
-
-Tag management for projects with custom variants.
-
-```tsx
-export function ProjectTags() {
-  const projectTags: Tag[] = [
-    { id: '1', name: 'High Priority', isSelected: false, variant: 'red' },
-    { id: '2', name: 'In Progress', isSelected: false, variant: 'blue' },
-    { id: '3', name: 'Completed', isSelected: false, variant: 'green' },
-    { id: '4', name: 'On Hold', isSelected: false, variant: 'yellow' },
-    { id: '5', name: 'Needs Review', isSelected: false, variant: 'purple' },
-    { id: '6', name: 'Client Approval', isSelected: false, variant: 'purple' },
-    { id: '7', name: 'Internal', isSelected: false, variant: 'gray' },
-    { id: '8', name: 'External', isSelected: false, variant: 'slate' },
-    { id: '9', name: 'Urgent', isSelected: false, variant: 'orange' },
-    { id: '10', name: 'Can Wait', isSelected: false, variant: 'green' },
-  ]
-
-  const [projectData, setProjectData] = useState({
-    name: '',
-    description: '',
-    tags: [] as Tag[]
-  })
-
-  return (
-    <form className="max-w-2xl space-y-4">
-      <div>
-        <label className="block mb-2">Project Name</label>
-        <InputField
-          value={projectData.name}
-          onChange={(e) => setProjectData({ ...projectData, name: e.target.value })}
-          placeholder="Enter project name"
-        />
-      </div>
-
-      <div>
-        <label className="block mb-2">Description</label>
-        <TextAreaInput
-          value={projectData.description}
-          onChange={(e) => setProjectData({ ...projectData, description: e.target.value })}
-          placeholder="Enter project description"
-          rows={3}
-        />
-      </div>
-
-      <div>
-        <label className="block mb-2">Tags</label>
-        <BadgeField
-          tags={projectTags}
-          placeholder="Add project tags..."
-          size="M"
-          onValueChange={(tags) => setProjectData({ ...projectData, tags })}
-        />
-      </div>
-
-      <Button variant="PrimeStyle">Create Project</Button>
-    </form>
-  )
-}
-```
-
-### Different Sizes
-
-BadgeField in various sizes.
-
-```tsx
-export function BadgeFieldSizes() {
-  const tags: Tag[] = [
-    { id: '1', name: 'Small', isSelected: false, variant: 'blue' },
-    { id: '2', name: 'Medium', isSelected: false, variant: 'green' },
-    { id: '3', name: 'Large', isSelected: false, variant: 'purple' },
-  ]
-
-  return (
-    <div className="space-y-6">
-      <div>
-        <label className="block mb-2 text-sm">Extra Small (XS)</label>
-        <BadgeField tags={tags} size="XS" placeholder="XS size..." />
-      </div>
-
-      <div>
-        <label className="block mb-2">Small (S)</label>
-        <BadgeField tags={tags} size="S" placeholder="S size..." />
-      </div>
-
-      <div>
-        <label className="block mb-2">Medium (M)</label>
-        <BadgeField tags={tags} size="M" placeholder="M size..." />
-      </div>
-    </div>
-  )
-}
-```
-
-### With Icons and Actions
-
-Badge field with custom icons and action buttons.
-
-```tsx
-export function BadgeFieldWithIcon() {
-  const tags: Tag[] = [
-    { id: '1', name: 'JavaScript', isSelected: false, variant: 'yellow' },
-    { id: '2', name: 'Python', isSelected: false, variant: 'blue' },
-    { id: '3', name: 'Ruby', isSelected: false, variant: 'red' },
-  ]
-
-  return (
-    <BadgeField
-      tags={tags}
-      size="M"
-      placeholder="Select programming languages..."
-      icon={<i className="ri-code-line"></i>}
-      actionButton={
-        <ActionButton size="S" title="Clear all">
-          <i className="ri-close-line"></i>
-        </ActionButton>
-      }
-    />
-  )
-}
-```
-
-### With Error State
-
-Display validation errors. `errorMessage` turns on the field's negative border.
-
-```tsx
-export function BadgeFieldWithError() {
-  const [tags, setTags] = useState<Tag[]>([])
-  const [error, setError] = useState('')
-
-  const availableTags: Tag[] = [
-    { id: '1', name: 'Option 1', isSelected: false, variant: 'blue' },
-    { id: '2', name: 'Option 2', isSelected: false, variant: 'green' },
-    { id: '3', name: 'Option 3', isSelected: false, variant: 'purple' },
-  ]
-
-  const handleChange = (newTags: Tag[]) => {
-    setTags(newTags)
-    if (newTags.length === 0) {
-      setError('Please select at least one option')
-    } else if (newTags.length > 3) {
-      setError('Maximum 3 options allowed')
-    } else {
-      setError('')
-    }
-  }
-
-  return (
-    <div>
-      <label className="block mb-2">
-        Required Selection
-        <span className="text-red-500 ml-1">*</span>
-      </label>
-
-      <BadgeField
-        tags={availableTags}
-        size="M"
-        placeholder="Select options (1-3)..."
-        onValueChange={handleChange}
-        errorMessage={error}
-        toolTipSide="right"
-      />
-    </div>
-  )
-}
-```
-
-### Email Recipients
-
-Tag-style email recipient selector.
-
-```tsx
-export function EmailRecipients() {
-  const contacts: Tag[] = [
-    { id: '1', name: 'john@example.com', isSelected: false, variant: 'blue' },
-    { id: '2', name: 'jane@example.com', isSelected: false, variant: 'green' },
-    { id: '3', name: 'team@example.com', isSelected: false, variant: 'purple' },
-    { id: '4', name: 'support@example.com', isSelected: false, variant: 'slate' },
-  ]
-
-  const [recipients, setRecipients] = useState<Tag[]>([])
-
-  return (
-    <form className="max-w-2xl space-y-4">
-      <div>
-        <label className="block mb-2">To:</label>
-        <BadgeField
-          tags={contacts}
-          placeholder="Add recipients..."
-          size="M"
-          onValueChange={setRecipients}
-          icon={<i className="ri-user-add-line"></i>}
-        />
-      </div>
-
-      <div>
-        <label className="block mb-2">Subject:</label>
-        <InputField placeholder="Email subject" />
-      </div>
-
-      <div>
-        <label className="block mb-2">Message:</label>
-        <TextAreaInput placeholder="Type your message..." rows={6} />
-      </div>
-
-      <Button variant="PrimeStyle" disabled={recipients.length === 0}>
-        <i className="ri-send-plane-line mr-2"></i>
-        Send to {recipients.length} recipient{recipients.length !== 1 ? 's' : ''}
-      </Button>
-    </form>
-  )
-}
-```
-
-### RTL Support
-
-Pass `dir="rtl"` (and a translated `addLabel`) to mirror the field for right-to-left languages.
-
-```tsx
-export function RtlBadgeField() {
-  const tags: Tag[] = [
-    { id: '1', name: 'إلكترونيات', isSelected: false, variant: 'blue' },
-    { id: '2', name: 'كتب', isSelected: false, variant: 'green' },
-    { id: '3', name: 'ملابس', isSelected: false, variant: 'purple' },
-  ]
-
-  const [selected, setSelected] = useState<Tag[]>([])
-
-  return (
-    <div dir="rtl">
-      <BadgeField
-        dir="rtl"
-        tags={tags}
-        onValueChange={setSelected}
-        addLabel="إضافة"
-        placeholder="اختر وسماً"
-      />
-    </div>
-  )
-}
-```
-
-## API Reference
-
-### BadgeField Props
-
-Extends all Input element props (except size and variant).
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| tags | `Tag[]` | **Required** | Available tags to select from |
-| onValueChange | `(tags: Tag[]) => void` | - | Callback when selection changes |
-| size | `'XS' \| 'S' \| 'M'` | `'M'` | Field size |
-| variant | `'PresentationStyle'` | `'PresentationStyle'` | Visual variant |
-| icon | `ReactNode` | - | Leading icon |
-| errorMessage | `string` | - | Marks the field invalid — any non-undefined value turns on the negative border |
-| onTable | `boolean` | `false` | Table-specific styling |
-| toolTipSide | `ToolTipSide` | - | **Deprecated, ignored.** The error tooltip was removed; an invalid field is shown by its border alone |
-| label | `string` | - | Field label |
-| required | `boolean` | `false` | Required indicator |
-| theme | `Themes` | - | Theme override |
-| actionButton | `ReactNode` | - | Trailing action button |
-| addLabel | `string` | `'add'` | Label for the add action shown in the field |
-| dir | `string` | `'ltr'` | Reading direction (`'rtl'` for right-to-left) |
-| placeholder | `string` | - | Input placeholder text |
-
-### Tag Type
-
-```typescript
-interface Tag {
-  id: string
-  name: string
-  isSelected: boolean
-  variant?: string
-  value?: string
-  [key: string]: any
-}
-```
-
-## Keyboard Navigation
-
-BadgeField includes comprehensive keyboard support:
-
-| Key | Action |
-|-----|--------|
-| `ArrowDown` | Move focus to next tag in dropdown |
-| `ArrowUp` | Move focus to previous tag in dropdown |
-| `ArrowLeft` | Move focus to previous selected tag |
-| `ArrowRight` | Move focus to next selected tag |
-| `Enter` | Select the focused tag from the dropdown |
-| `Delete` / `Backspace` | Remove the focused selected tag |
-| `Escape` | Close dropdown |
-| `Tab` | Close dropdown and move to next field |
-
-## Styling
-
-### Default Styles
-
-- **Container**: Flex wrap with gap
-- **Input**: Grows to fill available space
-- **Badges**: Displayed inline with remove capability
-- **Dropdown**: Popover with filtered tags
-- **Focus**: Ring indicator on focused badges
-
-### Customization
-
-```tsx
-// Custom width
-<BadgeField className="w-full max-w-md" />
-
-// Custom dropdown styling
-<PopoverContent className="max-h-64 overflow-y-auto" />
-```
-
-## TypeScript Types
-
-```typescript
-interface BadgeFieldProps
-  extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'variant'> {
-  size?: 'XS' | 'S' | 'M'
-  variant?: 'PresentationStyle'
-  icon?: ReactNode
-  errorMessage?: string
-  onTable?: boolean
-  toolTipSide?: ToolTipSide
-  label?: string
-  required?: boolean
-  theme?: Themes
-  actionButton?: ReactNode
-  tags: Tag[]
-  onValueChange?: (tags: Tag[]) => void
-  addLabel?: string
-}
-
-interface Tag {
-  id: string
-  name: string
-  isSelected: boolean
-  variant?: string
-  value?: string
-  [key: string]: any
-}
-```
-
-## Common Patterns
-
-### Controlled Component
-
-```tsx
-function ControlledBadgeField() {
-  const [selectedTags, setSelectedTags] = useState<Tag[]>([])
-
-  return (
-    <BadgeField
-      tags={allTags}
-      onValueChange={setSelectedTags}
-      placeholder="Select tags..."
-    />
-  )
-}
-```
-
-### Form Integration
-
-```tsx
-function FormWithBadgeField() {
-  const { register, setValue, watch } = useForm()
-  const selectedTags = watch('tags', [])
-
-  return (
-    <form>
-      <BadgeField
-        tags={availableTags}
-        onValueChange={(tags) => setValue('tags', tags)}
-        {...register('tags', { required: true })}
-      />
-    </form>
-  )
-}
-```
-
-## Testing
-
-```typescript
-import { render, screen, fireEvent } from '@testing-library/react'
-import { BadgeField } from '@/components/BadgeField'
-
-describe('BadgeField', () => {
-  const mockTags = [
-    { id: '1', name: 'Tag 1', isSelected: false, variant: 'blue' },
-    { id: '2', name: 'Tag 2', isSelected: false, variant: 'green' },
-  ]
-
-  it('renders placeholder', () => {
-    render(
-      <BadgeField tags={mockTags} placeholder="Select tags" />
-    )
-
-    expect(screen.getByPlaceholderText('Select tags')).toBeInTheDocument()
-  })
-
-  it('shows dropdown on focus', () => {
-    render(<BadgeField tags={mockTags} />)
-
-    const input = screen.getByRole('textbox')
-    fireEvent.focus(input)
-
-    expect(screen.getByText('Tag 1')).toBeInTheDocument()
-    expect(screen.getByText('Tag 2')).toBeInTheDocument()
-  })
-
-  it('filters tags on search', () => {
-    render(<BadgeField tags={mockTags} />)
-
-    const input = screen.getByRole('textbox')
-    fireEvent.change(input, { target: { value: 'Tag 1' } })
-
-    expect(screen.getByText('Tag 1')).toBeInTheDocument()
-    expect(screen.queryByText('Tag 2')).not.toBeInTheDocument()
-  })
-
-  it('calls onValueChange when tag selected', () => {
-    const handleChange = jest.fn()
-    render(
-      <BadgeField tags={mockTags} onValueChange={handleChange} />
-    )
-
-    const input = screen.getByRole('textbox')
-    fireEvent.focus(input)
-    fireEvent.click(screen.getByText('Tag 1'))
-
-    // Selecting a tag emits it with isSelected: true
-    expect(handleChange).toHaveBeenCalledWith([
-      expect.objectContaining({ id: '1', isSelected: true }),
-    ])
-  })
-
-  it('removes tag on unselect', () => {
-    const handleChange = jest.fn()
-    render(
-      <BadgeField tags={mockTags} onValueChange={handleChange} />
-    )
-
-    // Select tag
-    fireEvent.focus(screen.getByRole('textbox'))
-    fireEvent.click(screen.getByText('Tag 1'))
-
-    // Remove tag
-    const removeButton = screen.getByRole('button', { name: 'Remove badge' })
-    fireEvent.click(removeButton)
-
-    expect(handleChange).toHaveBeenLastCalledWith([])
-  })
-})
-```
-
-## Accessibility
-
-- **Keyboard Navigation**: Full keyboard support
-- **ARIA Labels**: Proper labels for screen readers
-- **Focus Management**: Clear focus indicators
-- **Screen Reader**: Announces selected/removed tags
-- **Error Messages**: Invalid fields are marked with the negative border token
-- **Tab Order**: Logical tab navigation
-
-## Performance
-
-- **Filtered Search**: Efficient tag filtering
-- **Click Outside**: Optimized outside click detection
-- **Memoization**: Selected tags memoized
-- **Virtual Scrolling**: Consider for 100+ tags
-- **Bundle Size**: ~4 KB gzipped (with dependencies)
-
-## Migration Guide
-
-### From Multi-Select
-
-```tsx
-// Before: Standard multi-select
-<select multiple>
-  <option value="1">Tag 1</option>
-  <option value="2">Tag 2</option>
-</select>
-
-// After: BadgeField
-<BadgeField tags={tags} onValueChange={handleChange} />
-```
-
-## Best Practices
-
-1. **Tag Limits**: Consider max selected tags for UX
-2. **Search Placeholder**: Provide helpful search hints
-3. **Error Handling**: Show clear validation errors
-4. **Loading States**: Handle async tag loading
-5. **Empty States**: Show message when no tags available
-6. **Mobile UX**: Ensure touch-friendly targets
-7. **Performance**: Virtualize for large tag lists (100+)
-8. **Accessibility**: Always provide clear labels