## Build & Development Commands

* **Install dependencies**

  ```bash
  npm install
  # or
  pnpm install
  ```
* **Start the dev server**

  ```bash
  npm run dev
  ```

  Uses Vite under the hood; supports hot-reload and error overlays.
* **Build for production**

  ```bash
  npm run build
  ```

  Outputs to `dist/` with optimized bundles.
* **Preview production build**

  ```bash
  npm run preview
  ```

  Spins up a local static server for your production files.
* **Type-check only**

  ```bash
  npm run type-check
  ```

  Runs `tsc --noEmit` to catch stray type errors.
* **Lint & format**

  ```bash
  npm run lint
  npm run format
  ```

  * `lint` runs ESLint with your project rules.
  * `format` applies Prettier based on your config.

## Testing Guidelines

* **Run the full test suite**

  ```bash
  npm run test
  ```

  Uses Vitest with the DOM environment.
* **Watch mode**

  ```bash
  npm run test:watch
  ```

  Automatically re-runs affected tests on file save.
* **Coverage report**

  ```bash
  npm run test:coverage
  ```

  Must maintain ≥ 80 % coverage on statements, branches, functions, and lines.
* **Where to put tests**

  * Co-locate unit tests next to implementation:
    `MyComponent.tsx` ↔️ `MyComponent.test.tsx`
  * Integration / e2e tests in `tests/` with clear folder structure.
* **Recommended tools**

  * [Vitest](https://vitest.dev/) for unit + integration testing.
  * [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) for DOM-focused component tests.
  * [msw](https://mswjs.io/) for API-level mocking/stubbing.

## Code Style & Guidelines

* **Formatting**

  * 2 spaces for indentation
  * Single quotes for JS/TS
  * Max line length 100 chars (soft wrap)
  * Trailing commas in multiline objects/arrays
* **Imports & modules**

  1. Node core modules
  2. External dependencies (sorted alphabetically)
  3. Absolute imports (`@/…`)
  4. Relative imports (`./…`)
  5. Styles & assets
* **Components**

  * Functional components only; prefer hooks over classes
  * One component per file (PascalCase filenames)
  * Props and state fully typed
  * Split complex logic into custom hooks under `src/hooks/`
* **Styling**

  * Use Daisy UI and suppliment with Tailwind CSS with utility classes
  * Leverage daisy UI for core components or your design-system primitives
  * Avoid “magic” values; prefer tokens (spacing, color, typography)
* **Iconography**

  * Use Lucide React icons for all icon needs 
  * Install with npm install lucide-react 
  * Import individual icons to keep bundle size minimal:

```ts import { Home, User } from 'lucide-react'; Control size via props (<Home size={24} />) and color via Tailwind classes (text-primary) ``` * **Data fetching**

  * Use TanStack Query (`useQuery`/`useMutation`)
  * Centralize API clients in `src/api/`
  * Always handle loading, error, and empty states
* **Error handling**

  * Surface errors via UI toast or inline messages
  * Log unexpected errors to console with context
* **Performance**

  * Memoize expensive calculations with `useMemo`
  * Wrap stable callbacks in `useCallback`
  * Virtualize long lists (`react-window`, `react-virtual`)

## Documentation Guidelines

* **README.md**

  * Project overview, key features, how to get started
  * Development workflow (commands, env vars)
  * Link to design system / storybook
* **In-code docs**

  * Use JSDoc/TSDoc for all public functions and hooks
  * Document default prop values and throw conditions
* **Storybook**

  * Maintain stories for all UI components under `src/stories/`
  * Include “play” examples showing key interactions
* **CHANGELOG**

  * Follow [Keep a Changelog](https://keepachangelog.com/) style
  * Tag releases in Git (even if local) with semantic versioning
* **API reference**

  * Auto-generate via TypeDoc or similar into a `/docs/api` site
  * Include code snippets for common use cases

Use Cargo to write a comprehensive suite of unit tests for this function