xertica-ui 2.2.1 → 2.4.0

package/docs/state-management.md

@@ -1,289 +1,289 @@
-# State Management — Xertica UI
-
-Projects scaffolded with `xertica-ui init` use a layered state strategy:
-
-| Layer | Tool | Responsibility |
-|---|---|---|
-| **Server state** | TanStack React Query v5 | Data that originates from an API — fetching, caching, background refetch, loading/error |
-| **Client UI state** | Zustand v5 | State that lives only in the browser — filters, toggles, form controls, selected tab |
-| **Auth state** | `AuthContext` | Current user session, login, logout |
-| **Layout state** | `LayoutContext` / `useLayout()` | Sidebar width/expanded, assistant expanded |
-| **Local component state** | `useState` | Ephemeral state that does not need to outlive the component (dialogs, inline edits) |
-
----
-
-## Features Slice Structure
-
-All server data and client UI state lives in `src/features/<domain>/`. The scaffold template (`npx xertica-ui init`) generates the following structure:
-
-```
-src/features/
-├── home/
-│   ├── data/
-│   │   └── mock.ts              ← types + mock data + async fetch functions
-│   ├── hooks/
-│   │   └── useFeatureCards.ts   ← React Query hook (language-aware)
-│   ├── store/
-│   │   └── dashboardStore.ts    ← Zustand store
-│   ├── ui/
-│   │   └── HomeContent.tsx      ← page content component
-│   └── index.ts                 ← barrel (re-exports everything)
-└── assistant/
-    ├── data/
-    │   └── mock.ts              ← AssistantConfig + fetchAssistantConfig + factory functions
-    ├── hooks/
-    │   └── useAssistantConfig.ts ← React Query hook (language-aware)
-    └── index.ts
-```
-
-> The library source (`xertica-ui` package) contains additional hooks (`useDashboardStats`, `useTeamMembers`) for the design-system showcase pages. These are not generated in the scaffold template.
-
-### Adding a New Feature
-
-1. Create `features/<name>/data/mock.ts` with your types and mock fetch functions
-2. Create `features/<name>/hooks/use<Name>.ts` wrapping the fetch function in `useQuery`
-3. Create `features/<name>/store/<name>Store.ts` for any client-side UI state
-4. Re-export from `features/<name>/index.ts`
-5. Consume in your component via the hook
-
----
-
-## React Query (Server State)
-
-### Setup
-
-`QueryClientProvider` is placed at the root of the provider stack, outside `XerticaProvider`:
-
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      retry: 1,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
-
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <XerticaProvider>
-        <Router>...</Router>
-      </XerticaProvider>
-    </QueryClientProvider>
-  );
-}
-```
-
-### Writing a Hook
-
-Hooks that return translated strings must include the active **language** in their `queryKey`. This gives each locale its own cache slot — switching language creates a new cache key, triggers a refetch in the new language, and switching back is an instant cache hit.
-
-```ts
-// features/home/hooks/useTeamMembers.ts
-import { useQuery } from '@tanstack/react-query';
-import { useLanguage } from 'xertica-ui/hooks';
-import { fetchTeamMembers, type TeamMember } from '../data/mock';
-
-export function useTeamMembers() {
-  const { language } = useLanguage(); // ← current locale from LanguageContext
-  return useQuery<TeamMember[]>({
-    queryKey: ['home', 'team-members', language], // ← language as third element
-    queryFn: fetchTeamMembers,
-    staleTime: 2 * 60 * 1000, // 2 min
-  });
-}
-```
-
-> **Note:** Do not export a named `*_KEY` constant. The key now includes `language`, which is only available at hook call-time, making a module-level constant impossible. Keep the key inlined in the hook.
-
-### Consuming in a Component
-
-```tsx
-import { useTeamMembers } from '../../../features/home';
-
-export function TeamTable() {
-  const { data: members = [], isLoading, isError } = useTeamMembers();
-
-  if (isLoading) return <Skeleton />;
-  if (isError) return <ErrorState />;
-
-  return (
-    <Table>
-      <TableBody>
-        {members.map(m => (
-          <TableRow key={m.id}>
-            <TableCell>{m.name}</TableCell>
-            <TableCell>{m.email}</TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-### Connecting to a Real API
-
-Replace only the `fetch*` function in `data/mock.ts` — the hook and component stay unchanged:
-
-```ts
-// features/home/data/mock.ts
-
-// Before (mock)
-export async function fetchTeamMembers(): Promise<TeamMember[]> {
-  await new Promise(resolve => setTimeout(resolve, 250));
-  return MOCK_TEAM_MEMBERS;
-}
-
-// After (real API)
-export async function fetchTeamMembers(): Promise<TeamMember[]> {
-  const res = await fetch('/api/team/members');
-  if (!res.ok) throw new Error('Failed to fetch team members');
-  return res.json();
-}
-```
-
-### staleTime Reference
-
-| Hook | staleTime | Rationale |
-|---|---|---|
-| `useFeatureCards` | 10 min | Feature list is nearly static |
-| `useAssistantConfig` | 30 min | Config changes very rarely |
-
-> Library-internal showcase hooks (`useDashboardStats` — 5 min, `useTeamMembers` — 2 min) are not generated in the scaffold template but follow the same language-aware pattern.
-
----
-
-## Zustand (Client UI State)
-
-Zustand manages state that never needs to be fetched from a server — filters, tab selections, progress bars, switch toggles, and other UI controls.
-
-### Writing a Store
-
-```ts
-// features/home/store/dashboardStore.ts
-import { create } from 'zustand';
-
-interface DashboardStore {
-  activeTab: string;
-  setActiveTab: (tab: string) => void;
-  progress: number;
-  setProgress: (value: number) => void;
-}
-
-export const useDashboardStore = create<DashboardStore>(set => ({
-  activeTab: 'overview',
-  setActiveTab: tab => set({ activeTab: tab }),
-  progress: 45,
-  setProgress: value => set({ progress: value }),
-}));
-```
-
-### Consuming in a Component
-
-```tsx
-import { useDashboardStore } from '../../../features/home';
-
-function ProgressSection() {
-  // Subscribe only to the slice you need — avoids unnecessary re-renders
-  const progress = useDashboardStore(s => s.progress);
-  const setProgress = useDashboardStore(s => s.setProgress);
-
-  return <Progress value={progress} onChange={setProgress} />;
-}
-```
-
-### When to Use Zustand vs useState
-
-| Use `useState` | Use `useDashboardStore` (Zustand) |
-|---|---|
-| Dialog open/closed | Active filter tab |
-| Rename input value | Slider value shared across sections |
-| Hover state | Switch enabled state |
-| Single-component toggle | Any state that must survive component unmount |
-
----
-
-## AuthContext
-
-Authentication state is managed by a dedicated context — not React Query and not Zustand.
-
-### Setup
-
-`AuthProvider` must be inside `<Router>` because it uses `useNavigate`:
-
-```tsx
-<Router>
-  <AuthProvider>
-    <AppRoutes />
-  </AuthProvider>
-</Router>
-```
-
-### Hook
-
-```tsx
-import { useAuth } from '../app/context/AuthContext';
-
-function MyComponent() {
-  const { user, isLoading, login, logout } = useAuth();
-
-  if (isLoading) return null; // waiting for localStorage hydration
-
-  return user ? (
-    <button onClick={logout}>Sign out {user.email}</button>
-  ) : (
-    <button onClick={() => login('user@example.com', 'password')}>Sign in</button>
-  );
-}
-```
-
-### `isLoading` Flag
-
-On first render, `AuthProvider` reads `localStorage` asynchronously. Until it resolves, `isLoading` is `true`. Route guards check this flag before deciding to redirect:
-
-```tsx
-function ProtectedRoute({ children }) {
-  const { user, isLoading } = useAuth();
-  if (isLoading) return null;      // render nothing until hydrated
-  if (!user) return <Navigate to="/login" replace />;
-  return <>{children}</>;
-}
-```
-
----
-
-## Decision Tree
-
-```
-Need data from a server or async function?
-  └─ YES → React Query (useQuery in features/*/hooks/)
-      └─ Is it mock data? → Use features/*/data/mock.ts fetch function
-      └─ Is it a real API? → Replace fetch function body, keep everything else
-
-State is browser-only (no server involved)?
-  └─ Shared across multiple components → Zustand (features/*/store/)
-  └─ Used by a single component → useState
-
-Authentication / current user?
-  └─ useAuth() from AuthContext
-
-Sidebar width / assistant panel?
-  └─ useLayout() from xertica-ui/hooks
-```
-
----
-
-## AI Rules
-
-- **Never hardcode mock data in components** — all data arrays (team members, stats, feature cards, assistant suggestions) must live in `features/*/data/mock.ts`
-- **Never call `fetch` directly inside a component** — always wrap in a React Query hook in `features/*/hooks/`
-- **Never use `useState` for server data** — `useState([])` + `useEffect(() => fetch(...))` is the old pattern; use `useQuery` instead
-- **`QueryClientProvider` goes outside `XerticaProvider`** — it must be the outermost provider so all nested providers can use React Query if needed
-- **`AuthProvider` goes inside `<Router>`** — it uses `useNavigate` which requires a Router ancestor
-- **Use `staleTime`** — always set a `staleTime` appropriate to how often the data changes; never leave it at the default `0` (which re-fetches on every focus)
-- **Zustand selectors prevent re-renders** — always subscribe with a selector: `useDashboardStore(s => s.progress)` instead of `const store = useDashboardStore()`
-- **`isLoading` from `useAuth()` prevents flash redirects** — always check `isLoading` in route guards before reading `user`
+# State Management — Xertica UI
+
+Projects scaffolded with `xertica-ui init` use a layered state strategy:
+
+| Layer                     | Tool                            | Responsibility                                                                          |
+| ------------------------- | ------------------------------- | --------------------------------------------------------------------------------------- |
+| **Server state**          | TanStack React Query v5         | Data that originates from an API — fetching, caching, background refetch, loading/error |
+| **Client UI state**       | Zustand v5                      | State that lives only in the browser — filters, toggles, form controls, selected tab    |
+| **Auth state**            | `AuthContext`                   | Current user session, login, logout                                                     |
+| **Layout state**          | `LayoutContext` / `useLayout()` | Sidebar width/expanded, assistant expanded                                              |
+| **Local component state** | `useState`                      | Ephemeral state that does not need to outlive the component (dialogs, inline edits)     |
+
+---
+
+## Features Slice Structure
+
+All server data and client UI state lives in `src/features/<domain>/`. The scaffold template (`npx xertica-ui init`) generates the following structure:
+
+```
+src/features/
+├── home/
+│   ├── data/
+│   │   └── mock.ts              ← types + mock data + async fetch functions
+│   ├── hooks/
+│   │   └── useFeatureCards.ts   ← React Query hook (language-aware)
+│   ├── store/
+│   │   └── dashboardStore.ts    ← Zustand store
+│   ├── ui/
+│   │   └── HomeContent.tsx      ← page content component
+│   └── index.ts                 ← barrel (re-exports everything)
+└── assistant/
+    ├── data/
+    │   └── mock.ts              ← AssistantConfig + fetchAssistantConfig + factory functions
+    ├── hooks/
+    │   └── useAssistantConfig.ts ← React Query hook (language-aware)
+    └── index.ts
+```
+
+> The library source (`xertica-ui` package) contains additional hooks (`useDashboardStats`, `useTeamMembers`) for the design-system showcase pages. These are not generated in the scaffold template.
+
+### Adding a New Feature
+
+1. Create `features/<name>/data/mock.ts` with your types and mock fetch functions
+2. Create `features/<name>/hooks/use<Name>.ts` wrapping the fetch function in `useQuery`
+3. Create `features/<name>/store/<name>Store.ts` for any client-side UI state
+4. Re-export from `features/<name>/index.ts`
+5. Consume in your component via the hook
+
+---
+
+## React Query (Server State)
+
+### Setup
+
+`QueryClientProvider` is placed at the root of the provider stack, outside `XerticaProvider`:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 1,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <XerticaProvider>
+        <Router>...</Router>
+      </XerticaProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### Writing a Hook
+
+Hooks that return translated strings must include the active **language** in their `queryKey`. This gives each locale its own cache slot — switching language creates a new cache key, triggers a refetch in the new language, and switching back is an instant cache hit.
+
+```ts
+// features/home/hooks/useTeamMembers.ts
+import { useQuery } from '@tanstack/react-query';
+import { useLanguage } from 'xertica-ui/hooks';
+import { fetchTeamMembers, type TeamMember } from '../data/mock';
+
+export function useTeamMembers() {
+  const { language } = useLanguage(); // ← current locale from LanguageContext
+  return useQuery<TeamMember[]>({
+    queryKey: ['home', 'team-members', language], // ← language as third element
+    queryFn: fetchTeamMembers,
+    staleTime: 2 * 60 * 1000, // 2 min
+  });
+}
+```
+
+> **Note:** Do not export a named `*_KEY` constant. The key now includes `language`, which is only available at hook call-time, making a module-level constant impossible. Keep the key inlined in the hook.
+
+### Consuming in a Component
+
+```tsx
+import { useTeamMembers } from '../../../features/home';
+
+export function TeamTable() {
+  const { data: members = [], isLoading, isError } = useTeamMembers();
+
+  if (isLoading) return <Skeleton />;
+  if (isError) return <ErrorState />;
+
+  return (
+    <Table>
+      <TableBody>
+        {members.map(m => (
+          <TableRow key={m.id}>
+            <TableCell>{m.name}</TableCell>
+            <TableCell>{m.email}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+### Connecting to a Real API
+
+Replace only the `fetch*` function in `data/mock.ts` — the hook and component stay unchanged:
+
+```ts
+// features/home/data/mock.ts
+
+// Before (mock)
+export async function fetchTeamMembers(): Promise<TeamMember[]> {
+  await new Promise(resolve => setTimeout(resolve, 250));
+  return MOCK_TEAM_MEMBERS;
+}
+
+// After (real API)
+export async function fetchTeamMembers(): Promise<TeamMember[]> {
+  const res = await fetch('/api/team/members');
+  if (!res.ok) throw new Error('Failed to fetch team members');
+  return res.json();
+}
+```
+
+### staleTime Reference
+
+| Hook                 | staleTime | Rationale                     |
+| -------------------- | --------- | ----------------------------- |
+| `useFeatureCards`    | 10 min    | Feature list is nearly static |
+| `useAssistantConfig` | 30 min    | Config changes very rarely    |
+
+> Library-internal showcase hooks (`useDashboardStats` — 5 min, `useTeamMembers` — 2 min) are not generated in the scaffold template but follow the same language-aware pattern.
+
+---
+
+## Zustand (Client UI State)
+
+Zustand manages state that never needs to be fetched from a server — filters, tab selections, progress bars, switch toggles, and other UI controls.
+
+### Writing a Store
+
+```ts
+// features/home/store/dashboardStore.ts
+import { create } from 'zustand';
+
+interface DashboardStore {
+  activeTab: string;
+  setActiveTab: (tab: string) => void;
+  progress: number;
+  setProgress: (value: number) => void;
+}
+
+export const useDashboardStore = create<DashboardStore>(set => ({
+  activeTab: 'overview',
+  setActiveTab: tab => set({ activeTab: tab }),
+  progress: 45,
+  setProgress: value => set({ progress: value }),
+}));
+```
+
+### Consuming in a Component
+
+```tsx
+import { useDashboardStore } from '../../../features/home';
+
+function ProgressSection() {
+  // Subscribe only to the slice you need — avoids unnecessary re-renders
+  const progress = useDashboardStore(s => s.progress);
+  const setProgress = useDashboardStore(s => s.setProgress);
+
+  return <Progress value={progress} onChange={setProgress} />;
+}
+```
+
+### When to Use Zustand vs useState
+
+| Use `useState`          | Use `useDashboardStore` (Zustand)             |
+| ----------------------- | --------------------------------------------- |
+| Dialog open/closed      | Active filter tab                             |
+| Rename input value      | Slider value shared across sections           |
+| Hover state             | Switch enabled state                          |
+| Single-component toggle | Any state that must survive component unmount |
+
+---
+
+## AuthContext
+
+Authentication state is managed by a dedicated context — not React Query and not Zustand.
+
+### Setup
+
+`AuthProvider` must be inside `<Router>` because it uses `useNavigate`:
+
+```tsx
+<Router>
+  <AuthProvider>
+    <AppRoutes />
+  </AuthProvider>
+</Router>
+```
+
+### Hook
+
+```tsx
+import { useAuth } from '../app/context/AuthContext';
+
+function MyComponent() {
+  const { user, isLoading, login, logout } = useAuth();
+
+  if (isLoading) return null; // waiting for localStorage hydration
+
+  return user ? (
+    <button onClick={logout}>Sign out {user.email}</button>
+  ) : (
+    <button onClick={() => login('user@example.com', 'password')}>Sign in</button>
+  );
+}
+```
+
+### `isLoading` Flag
+
+On first render, `AuthProvider` reads `localStorage` asynchronously. Until it resolves, `isLoading` is `true`. Route guards check this flag before deciding to redirect:
+
+```tsx
+function ProtectedRoute({ children }) {
+  const { user, isLoading } = useAuth();
+  if (isLoading) return null; // render nothing until hydrated
+  if (!user) return <Navigate to="/login" replace />;
+  return <>{children}</>;
+}
+```
+
+---
+
+## Decision Tree
+
+```
+Need data from a server or async function?
+  └─ YES → React Query (useQuery in features/*/hooks/)
+      └─ Is it mock data? → Use features/*/data/mock.ts fetch function
+      └─ Is it a real API? → Replace fetch function body, keep everything else
+
+State is browser-only (no server involved)?
+  └─ Shared across multiple components → Zustand (features/*/store/)
+  └─ Used by a single component → useState
+
+Authentication / current user?
+  └─ useAuth() from AuthContext
+
+Sidebar width / assistant panel?
+  └─ useLayout() from xertica-ui/hooks
+```
+
+---
+
+## AI Rules
+
+- **Never hardcode mock data in components** — all data arrays (team members, stats, feature cards, assistant suggestions) must live in `features/*/data/mock.ts`
+- **Never call `fetch` directly inside a component** — always wrap in a React Query hook in `features/*/hooks/`
+- **Never use `useState` for server data** — `useState([])` + `useEffect(() => fetch(...))` is the old pattern; use `useQuery` instead
+- **`QueryClientProvider` goes outside `XerticaProvider`** — it must be the outermost provider so all nested providers can use React Query if needed
+- **`AuthProvider` goes inside `<Router>`** — it uses `useNavigate` which requires a Router ancestor
+- **Use `staleTime`** — always set a `staleTime` appropriate to how often the data changes; never leave it at the default `0` (which re-fetches on every focus)
+- **Zustand selectors prevent re-renders** — always subscribe with a selector: `useDashboardStore(s => s.progress)` instead of `const store = useDashboardStore()`
+- **`isLoading` from `useAuth()` prevents flash redirects** — always check `isLoading` in route guards before reading `user`