# Component Inventory

# Component Inventory

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## 1. Overview

<!-- GUIDANCE: Summarize the component library. How many components total? What's the coverage across categories? Who owns it? -->

**Total components:** {{N}}
**Library location:** `src/components/`
**Storybook:** `{{https://storybook.PROJECT_NAME.example.com}}`
**Design source:** `{{Figma file URL}}`
**Owner team:** `{{TEAM_NAME}}`

This inventory tracks every reusable component in **{{PROJECT_NAME}}**. It follows Atomic Design categorization: atoms → molecules → organisms → templates → pages.

---

## 2. Component Hierarchy Diagram

<!-- GUIDANCE: Update this diagram to show the actual component composition relationships in your system. -->

```mermaid
graph TB
    subgraph Pages
        PageLogin["LoginPage"]
        PageDashboard["DashboardPage"]
    end
    subgraph Templates
        TplAuth["AuthLayout"]
        TplApp["AppLayout"]
    end
    subgraph Organisms
        OrgNavbar["Navbar"]
        OrgSidebar["Sidebar"]
        OrgDataTable["DataTable"]
        OrgUserForm["UserForm"]
    end
    subgraph Molecules
        MolFormField["FormField"]
        MolCard["Card"]
        MolSearchBar["SearchBar"]
        MolDropdown["Dropdown"]
        MolPagination["Pagination"]
    end
    subgraph Atoms
        AtomButton["Button"]
        AtomInput["Input"]
        AtomBadge["Badge"]
        AtomSpinner["Spinner"]
        AtomAvatar["Avatar"]
        AtomIcon["Icon"]
    end

    Pages --> Templates
    Templates --> Organisms
    Organisms --> Molecules
    Molecules --> Atoms
```

**TODO:** Update diagram to reflect actual component tree.

---

## 3. Atoms (Primitive Components)

<!-- GUIDANCE: Add one entry per primitive component. Props table must be complete before marking as Done. -->

### 3.1 Button

| Property | Value |
|----------|-------|
| **Category** | Atom |
| **Status** | `{{Done | WIP | Planned | Deprecated}}` |
| **File path** | `src/components/ui/Button/Button.tsx` |
| **Storybook** | `{{URL}}` |
| **Design ref** | `{{Figma frame URL}}` |

**Props API:**

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'link'` | `'primary'` | No | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | No | Button size |
| `disabled` | `boolean` | `false` | No | Disables interaction |
| `loading` | `boolean` | `false` | No | Shows spinner, disables click |
| `leftIcon` | `ReactNode` | `undefined` | No | Icon before label |
| `rightIcon` | `ReactNode` | `undefined` | No | Icon after label |
| `onClick` | `(e: MouseEvent) => void` | `undefined` | No | Click handler |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | No | HTML button type |
| `fullWidth` | `boolean` | `false` | No | 100% width |

**Variants & States:** primary, secondary, ghost, danger, link × default, hover, focus, active, disabled, loading

**Accessibility:**
- Renders as `<button>` — never `<div>` or `<span>`
- `loading` state: `aria-busy="true"`, spinner has `aria-label="Loading"`
- `disabled`: `aria-disabled="true"`, not removed from tab order
- Focus ring: 2px offset, brand color

**Dependencies:** Icon component, Spinner component

---

### 3.2 Input

| Property | Value |
|----------|-------|
| **Category** | Atom |
| **Status** | `{{Status}}` |
| **File path** | `src/components/ui/Input/Input.tsx` |
| **Storybook** | `{{URL}}` |

**Props API:**

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'search' \| 'tel' \| 'url'` | `'text'` | No | Input type |
| `value` | `string` | — | Yes (controlled) | Input value |
| `onChange` | `(e: ChangeEvent) => void` | — | Yes | Change handler |
| `placeholder` | `string` | `''` | No | Placeholder text |
| `disabled` | `boolean` | `false` | No | Disabled state |
| `error` | `boolean` | `false` | No | Triggers error visual state |
| `errorMessage` | `string` | `undefined` | No | Error text (also sets `aria-describedby`) |
| `leftAdornment` | `ReactNode` | `undefined` | No | Icon or element left of input |
| `rightAdornment` | `ReactNode` | `undefined` | No | Icon or element right of input |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | No | Input height/font size |

**Variants & States:** default, focused, error, disabled, with-left-icon, with-right-icon

**Accessibility:**
- Must always be paired with `<label>` (use FormField molecule)
- Error: `aria-invalid="true"` + `aria-describedby` pointing to error message id
- Password: toggle visibility button must have `aria-label`

---

### 3.3 Badge

| Property | Value |
|----------|-------|
| **Category** | Atom |
| **Status** | `{{Status}}` |
| **File path** | `src/components/ui/Badge/Badge.tsx` |

**Props API:**

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `variant` | `'success' \| 'warning' \| 'error' \| 'info' \| 'neutral'` | `'neutral'` | No | Semantic color variant |
| `size` | `'sm' \| 'md'` | `'md'` | No | Badge size |
| `dot` | `boolean` | `false` | No | Shows colored dot instead of text |
| `children` | `ReactNode` | — | Yes | Badge content |

**TODO:** Add remaining atom components following the same pattern (Select, Checkbox, Radio, Toggle, Textarea, Avatar, Tooltip, Spinner, Divider).

---

## 4. Molecules (Composite Components)

<!-- GUIDANCE: More complex components composed of atoms. Focus on the composition and API surface. -->

### 4.1 FormField

| Property | Value |
|----------|-------|
| **Category** | Molecule |
| **Status** | `{{Status}}` |
| **File path** | `src/components/ui/FormField/FormField.tsx` |
| **Composes** | Input, Label, ErrorMessage, HelpText |

**Props API:**

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `label` | `string` | — | Yes | Visible label text |
| `htmlFor` | `string` | — | Yes | Links label to input id |
| `error` | `string` | `undefined` | No | Error message text |
| `helpText` | `string` | `undefined` | No | Helper text below input |
| `required` | `boolean` | `false` | No | Shows required indicator |
| `children` | `ReactNode` | — | Yes | Input component |

**Accessibility:** Label always associated with input via `htmlFor`/`id` pair.

---

### 4.2 Card

| Property | Value |
|----------|-------|
| **Category** | Molecule |
| **Status** | `{{Status}}` |
| **File path** | `src/components/ui/Card/Card.tsx` |

**Props API:**

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `variant` | `'default' \| 'bordered' \| 'elevated'` | `'default'` | No | Visual style |
| `padding` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | No | Internal padding |
| `as` | `ElementType` | `'div'` | No | Polymorphic render element |
| `children` | `ReactNode` | — | Yes | Card content |

**Sub-components:** `Card.Header`, `Card.Body`, `Card.Footer`

**TODO:** Add remaining molecule components: Modal, Dropdown, Table, Pagination, Toast, SearchBar, Breadcrumb, Tabs, Accordion, DatePicker.

---

## 5. Organisms (Complex Components)

<!-- GUIDANCE: Full UI sections composed of molecules and atoms. These are feature-aware but not page-specific. -->

### 5.1 DataTable

| Property | Value |
|----------|-------|
| **Category** | Organism |
| **Status** | `{{Status}}` |
| **File path** | `src/components/features/DataTable/DataTable.tsx` |
| **Dependencies** | Table (molecule), Pagination, SearchBar, Spinner, Badge |

**Features:**
- Sortable columns (client + server-side)
- Pagination (configurable page sizes)
- Row selection (single + multi)
- Column visibility toggle
- Export action slot
- Loading skeleton state
- Empty state slot
- Row action slot (per-row dropdown)

**TODO:** Document full props API for DataTable.

---

### 5.2 Navigation / Sidebar

| Property | Value |
|----------|-------|
| **Category** | Organism |
| **Status** | `{{Status}}` |
| **File path** | `src/components/layouts/Sidebar/Sidebar.tsx` |

**TODO:** Add remaining organism components.

---

## 6. Shared Hooks / Composables Inventory

<!-- GUIDANCE: List all shared hooks that are used across multiple components or features. -->

| Hook | File | Purpose | Used By |
|------|------|---------|---------|
| `useDebounce` | `src/hooks/useDebounce.ts` | Debounce value changes | SearchBar, Input |
| `useLocalStorage` | `src/hooks/useLocalStorage.ts` | Persistent local state | Theme, preferences |
| `useMediaQuery` | `src/hooks/useMediaQuery.ts` | Responsive breakpoint checks | Layout components |
| `useClickOutside` | `src/hooks/useClickOutside.ts` | Close on outside click | Dropdown, Modal |
| `useFocusTrap` | `src/hooks/useFocusTrap.ts` | Trap focus inside element | Modal, Drawer |
| `useToast` | `src/hooks/useToast.ts` | Trigger toast notifications | Global |
| `usePermission` | `src/hooks/usePermission.ts` | Check user permissions | Auth-gated components |
| `{{HOOK_NAME}}` | `{{PATH}}` | `{{PURPOSE}}` | `{{CONSUMERS}}` |

---

## 7. Third-Party Component Usage

<!-- GUIDANCE: Document any third-party UI libraries used and the wrapping strategy. -->

| Package | Version | Components Used | Wrapping Strategy |
|---------|---------|-----------------|-------------------|
| `{{@radix-ui/react-dialog}}` | `{{1.x}}` | Modal base | Wrapped in `src/components/ui/Modal` — custom styling |
| `{{@radix-ui/react-select}}` | `{{2.x}}` | Select base | Wrapped in `src/components/ui/Select` |
| `{{react-hook-form}}` | `{{7.x}}` | Form state | Used directly + FormField wrapper |
| `{{recharts}}` | `{{2.x}}` | Charts | Wrapped in `src/components/charts/` |

**Policy:** Never use third-party components directly in feature code — always wrap in local component to control API surface and allow future swap.

---

## 8. Component Deprecation Process

<!-- GUIDANCE: Define the lifecycle stages and how deprecation is communicated to the team. -->

```
Active → Deprecated (soft) → Deprecated (hard) → Removed
```

| Stage | Action Required |
|-------|----------------|
| **Deprecated (soft)** | Add `@deprecated` JSDoc comment, console warning in dev, migration guide in Storybook |
| **Deprecated (hard)** | TypeScript `@deprecated` annotation triggers IDE warning, added to removal milestone |
| **Removed** | Delete component, update CHANGELOG, run codemod if available |

**Deprecation notice minimum period:** 2 sprint cycles before hard removal.

**TODO:** Link to CHANGELOG.md for tracked deprecations.

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Frontend Lead | | | |
| Design System Owner | | | |