# Component Library

Located in `frontend/components/ds/`.

## Core

| Component | File | Notes |
|-----------|------|-------|
| Button | `Button.tsx` | variants: default, outline, ghost, danger, success |
| Input / Textarea / Label / FieldError | `Input.tsx` | Form primitives |
| Card family | `Card.tsx` | Card, Header, Title, Description, Content |
| Badge | `Badge.tsx` | tones: default, primary, success, warning, danger, info |
| Dialog / ConfirmDialog | `Dialog.tsx` | Modal + confirm |
| PageHeader | `Page.tsx` | Title + actions |
| DataTable | `Page.tsx` | Simple enterprise table |
| Empty / Loading / Error | `Page.tsx` | Standard states |
| StatCard | `Page.tsx` | Dashboard KPI |
| DatePicker / JalaliDateText | `DatePicker.tsx` | Shamsi calendar only; value is Gregorian ISO for APIs |
| Select / FormField / Checkbox / MoneyInput | `FormControls.tsx` | Styled `<select>`, labeled checkbox, LTR decimal input for voucher lines |
| Drawer | `Drawer.tsx` | RTL slide-over for edit forms (currencies, cost centers, projects, COA accounts) |
| Tabs / TableToolbar / Breadcrumbs / Skeleton / Pagination | `NavChrome.tsx` | List chrome + navigation |

Import via `@/components/ds`.

## Healthcare extension (`frontend/components/healthcare/ui/`)

See [healthcare-design-system.md](healthcare-design-system.md). Uses global DS + `--health-accent*` tokens. Portal shells in `HealthcarePortalShell`, public chrome in `PublicHealthcareLayout`.

## Dates

- Never use native `type="date"` (Gregorian browser picker) in Accounting.
- Always use `DatePicker` for input and `JalaliDateText` / `formatJalali` for display.
- API payloads remain `YYYY-MM-DD` Gregorian.

## Money

- Always use `MoneyInput` from `@/components/ds` for amount / price / debit / credit fields.
- Display uses thousand separators (`1,500,000`); RHF/API values stay plain (`1500000`).
- Helpers: `formatMoney`, `formatMoneyGrouped`, `parseMoneyInput` in `frontend/lib/utils.ts`.
- Never show raw ungrouped numbers in tables — use `formatMoney(...)`.

## Parties & items (AJAX)

- Party fields: `PartyCombobox` (`frontend/components/accounting/EntityCombobox.tsx`) — loads customers/suppliers from AR/AP.
- Line items: `ItemCombobox` — loads `/api/v1/ops/items` (کارت کالا).
- Free-text party/item entry is not allowed on operational invoices/orders when master data exists.

## Accounting helpers

- `CompletionScoreboard` — `frontend/components/accounting/CompletionScoreboard.tsx` (reads `lib/accounting-scoreboard.ts`).
- Scoreboard doc: `docs/frontend/completion-scoreboard.md`.
