xertica-ui 2.3.0 → 2.4.0

package/docs/architecture.md

@@ -1,306 +1,312 @@
-# Xertica UI — Architecture
-
-## Audit Date
-
-2026-05-20 (Post-Modularization + State Layer)
-
----
-
-## Summary of Changes
-
-The library underwent a **complete architectural modularization**. The flat `components/` directory was reorganized into a domain-driven structure, and a dedicated **state layer** was introduced via `features/`, `AuthContext`, TanStack React Query, and Zustand.
-
-### Component Domains
-
-| Domain      | Path                    | Contains                                                         |
-| ----------- | ----------------------- | ---------------------------------------------------------------- |
-| `ui`        | `components/ui/[name]/` | Design system primitives (Button, Card, Calendar, Chart, etc.)   |
-| `layout`    | `components/layout/`    | Sidebar, Header, SidebarPrimitive                                |
-| `blocks`    | `components/blocks/`    | High-level composed components built from `ui/` primitives       |
-| `assistant` | `components/assistant/` | XerticaAssistant, MarkdownMessage, CodeBlock, etc.               |
-| `brand`     | `components/brand/`     | XerticaLogo, ThemeToggle, LanguageSelector, XerticaProvider      |
-| `pages`     | `components/pages/`     | LoginPage, HomePage, TemplatePage, etc.                          |
-| `shared`    | `components/shared/`    | utils.ts, use-mobile.ts, layout-constants.ts, navigation.ts, **error-boundary.tsx**, **error-fallbacks.tsx** |
-
-### State Layer — `features/`
-
-Feature slices separate server state, client UI state, and mock data from the component tree.
-
-**Library source** (in this repo, used by Storybook and the showcase pages):
-
-```
-features/
-├── home/
-│   ├── data/mock.ts               ← typed mock data + async fetch functions (swap point for real API)
-│   ├── hooks/
-│   │   ├── useDashboardStats.ts   ← React Query (staleTime 5 min) — library-only
-│   │   ├── useTeamMembers.ts      ← React Query (staleTime 2 min) — library-only
-│   │   └── useFeatureCards.ts     ← React Query (staleTime 10 min)
-│   ├── store/dashboardStore.ts    ← Zustand (progress, slider, activeTab — UI-only)
-│   └── index.ts                   ← barrel
-└── assistant/
-    ├── data/mock.ts               ← AssistantConfig + fetchAssistantConfig (swap point)
-    ├── hooks/useAssistantConfig.ts ← React Query (staleTime 30 min)
-    └── index.ts                   ← barrel
-```
-
-**Scaffold template** (what `npx xertica-ui init` generates in a consumer project):
-
-```
-src/features/
-├── home/
-│   ├── data/mock.ts
-│   ├── hooks/useFeatureCards.ts   ← only useFeatureCards is scaffolded
-│   ├── store/dashboardStore.ts
-│   ├── ui/HomeContent.tsx
-│   └── index.ts
-└── assistant/
-    ├── data/mock.ts               ← exports getMockRichSuggestions() / getMockFeedbackOptions() factories
-    ├── hooks/useAssistantConfig.ts
-    └── index.ts
-```
-
-> `useDashboardStats` and `useTeamMembers` exist only in the library source where they power `TemplateContent.tsx`'s design-system showcase. They are NOT generated in the scaffold template. Consumer projects that need them must scaffold their own following the same pattern.
-
-All four hooks include the active **language** in their `queryKey` (`['home', 'feature-cards', language]`) so switching language triggers an automatic refetch in the new locale — see [`docs/i18n.md`](./i18n.md#language-aware-react-query-keys).
-
-**Swap pattern**: to connect a feature to a real API, replace only the `async function fetch*()` in `data/mock.ts`. The hook, the component, and the type contract remain unchanged.
-
-```ts
-// data/mock.ts — before (mock)
-export async function fetchTeamMembers(): Promise<TeamMember[]> {
-  await new Promise(resolve => setTimeout(resolve, 250));
-  return MOCK_TEAM_MEMBERS;
-}
-
-// data/mock.ts — after (real API)
-export async function fetchTeamMembers(): Promise<TeamMember[]> {
-  return fetch('/api/team/members').then(r => r.json());
-}
-```
-
-### i18n Layer
-
-Internationalization uses `i18next` + `react-i18next`. The setup is bootstrapped in `i18n.ts` (imported in `main.tsx`) and wired to `LanguageContext`:
-
-```
-i18n.ts                          ← configures i18next via import.meta.glob (auto-discovers new JSON files)
-locales/
-├── pt-BR/
-│   ├── common.json              ← shared action labels
-│   ├── nav.json                 ← navigation labels
-│   ├── errors.json              ← error boundary UI
-│   ├── languageSelector.json    ← language picker UI
-│   ├── themeToggle.json         ← theme toggle UI
-│   ├── pages/
-│   │   └── home.json, templates.json, login.json, resetPassword.json, verifyEmail.json,
-│   │       loginTemplate.json, formTemplate.json, dashboardTemplate.json, crudTemplate.json
-│   └── components/
-│       └── assistant.json, sidebar.json, media.json, projectCard.json, profileCard.json,
-│           notificationCard.json, activityCard.json, stats.json, team.json
-├── en/    ← same structure
-└── es/    ← same structure
-contexts/LanguageContext.tsx      ← setLanguage() calls i18n.changeLanguage() + persists to localStorage
-components/brand/language-selector/LanguageSelector.tsx  ← uses useLanguage() + useTranslation()
-```
-
-All page components use `useTranslation()` for UI strings. Mock data functions use `i18n.t()` (the instance) at query time so they respond to the active language.
-
-### ErrorBoundary Layer
-
-Three pre-configured wrappers for granular error isolation:
-
-```
-components/shared/
-├── error-boundary.tsx    ← ErrorBoundary class + AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary
-└── error-fallbacks.tsx   ← AppErrorFallback, PageErrorFallback, SectionErrorFallback
-```
-
-Placement in `App.tsx`:
-```
-AppErrorBoundary (outermost — before QueryClientProvider)
-  └─ QueryClientProvider
-      └─ ...providers...
-          └─ Router
-              └─ AuthProvider
-                  └─ PageErrorBoundary (wraps Routes/AuthGuard)
-                      └─ Suspense + Routes
-                          └─ Pages
-                              └─ SectionErrorBoundary (wraps data sections)
-```
-
-### AuthContext
-
-Authentication state lives in `contexts/AuthContext.tsx` and is consumed via `useAuth()`:
-
-```
-contexts/
-└── AuthContext.tsx    ← AuthProvider + useAuth() hook
-```
-
-`AuthProvider` must be rendered **inside** `<BrowserRouter>` (it uses `useNavigate`). It:
-- Hydrates session from `localStorage` on mount (`isLoading` flag prevents flash redirects)
-- Exposes `user`, `login(email, password) → boolean`, `logout()`
-- Redirects authenticated users away from auth-only pages automatically
-
-Page components (`HomePage`, `TemplatePage`) consume `useAuth()` directly — no `user`/`onLogout` prop drilling.
-
-### Lazy Loading
-
-All routes in `App.tsx` use `React.lazy()` + `<Suspense>`. Each page is a separate chunk loaded only when the route is first visited:
-
-```tsx
-const HomePage = React.lazy(() =>
-  import('./components/pages/home-page').then(m => ({ default: m.HomePage }))
-);
-```
-
-### Provider Stack
-
-```tsx
-<QueryClientProvider client={queryClient}>   // ← TanStack React Query
-  <ApiKeyProvider>
-    <GoogleMapsLoaderProvider>
-      <LanguageProvider>
-        <BrandColorsProvider>
-          <ThemeProvider>
-            <AssistenteProvider>
-              <LayoutProvider>
-                <Router>
-                  <AuthProvider>             // ← must be inside Router
-                    <Suspense fallback={null}>
-                      <AppRoutes />
-                    </Suspense>
-                  </AuthProvider>
-                </Router>
-              </LayoutProvider>
-            </AssistenteProvider>
-          </ThemeProvider>
-        </BrandColorsProvider>
-      </LanguageProvider>
-    </GoogleMapsLoaderProvider>
-  </ApiKeyProvider>
-</QueryClientProvider>
-```
-
-### blocks/ domain
-
-The `blocks/` domain contains **pre-composed patterns** built exclusively from `ui/` primitives. Unlike primitives, blocks encapsulate specific use-case logic and are ready to drop into dashboards and feature pages without additional composition.
-
-```
-components/blocks/
-└── card-patterns/
-    ├── ActivityCard.tsx      — activity feed with avatars and type badges
-    ├── ProfileCard.tsx       — user/member card with stats and actions
-    ├── ProjectCard.tsx       — project status with progress bar and member avatars
-    ├── QuickActionCard.tsx   — icon + title + description + action button
-    ├── NotificationCard.tsx  — notification list with unread indicators
-    ├── FeatureCard.tsx       — colored icon + title + badge + description + CTA
-    └── index.ts
-```
-
-All block components are exported from both `components/blocks/index.ts` and the root `components/index.ts` barrel.
-
-**Consumers can import from the root `xertica-ui` entrypoint (all components) or from granular subpath entries (v2, recommended for FSD/FDA projects).**
-
----
-
-## Subpath Exports (v2)
-
-The build system produces 7 distinct entry bundles from a multi-entry Vite `lib.entry` configuration. Each bundle maps to a `package.json` `exports` subpath:
-
-| Subpath                | Source entry                    | Contents                                                                   |
-| ---------------------- | ------------------------------- | -------------------------------------------------------------------------- |
-| `xertica-ui`           | `components/index.ts`           | Full barrel — all components                                               |
-| `xertica-ui/ui`        | `components/ui/index.ts`        | All UI primitives                                                          |
-| `xertica-ui/blocks`    | `components/blocks/index.ts`    | High-level composed patterns (ActivityCard, ProjectCard, etc.)             |
-| `xertica-ui/layout`    | `components/layout/index.ts`    | Sidebar, Header                                                            |
-| `xertica-ui/brand`     | `components/brand/index.ts`     | XerticaProvider, XerticaLogo, ThemeToggle, LanguageSelector, etc.          |
-| `xertica-ui/assistant` | `components/assistant/index.ts` | XerticaAssistant, MarkdownMessage, CodeBlock, etc.                         |
-| `xertica-ui/media`     | `components/media/index.ts`     | VideoPlayer, AudioPlayer, FloatingMediaWrapper                             |
-| `xertica-ui/hooks`     | `components/hooks/index.ts`     | useLayout, useTheme, useLanguage, useBrandColors, useAssistente, useApiKey |
-
-Each subpath exposes three fields in `exports`: `types` (`.d.ts`), `import` (ES module), `require` (UMD).
-
-> TypeScript consumers need `"moduleResolution": "bundler"` (or `"node16"` / `"nodenext"`) to resolve subpath exports.
-
----
-
-## Headless UI Pattern (v3)
-
-The library follows a **three-tier composability model** for its complex components. Each tier is a superset of the previous — consumers can choose the level of control they need.
-
-### Tier 1 — Monolithic API (drop-in)
-
-The default export. Zero configuration, full functionality. Ideal for rapid integration.
-
-```tsx
-import { Sidebar } from 'xertica-ui/layout';
-import { XerticaAssistant } from 'xertica-ui/assistant';
-import { RichTextEditor } from 'xertica-ui/ui';
-
-<Sidebar navigationGroups={groups} />
-<XerticaAssistant demoMode={true} />
-<RichTextEditor value={html} onChange={setHtml} />
-```
-
-### Tier 2 — Compound Components (structural control)
-
-Sub-components exposed as static properties on the main component. Consumers control layout and composition while the shared React Context handles state propagation.
-
-```tsx
-import { Sidebar } from 'xertica-ui/layout';
-
-<Sidebar.Root navigationGroups={groups}>
-  <Sidebar.Header logo={<MyLogo />} />
-  <Sidebar.Nav />
-  <Sidebar.Search search={searchConfig} />
-  <Sidebar.Footer showUser showSettings />
-</Sidebar.Root>;
-```
-
-Available compound components:
-
-| Component | Sub-components                                                                      |
-| --------- | ----------------------------------------------------------------------------------- |
-| `Sidebar` | `Sidebar.Root`, `Sidebar.Header`, `Sidebar.Nav`, `Sidebar.Search`, `Sidebar.Footer` |
-
-### Tier 3 — Headless Hooks (full control)
-
-Pure logic hooks with zero UI. Consumers bring their own markup, styling, and layout. The hook manages all state, refs, effects, and handlers.
-
-```tsx
-import { useSidebar } from 'xertica-ui/layout';
-import { useAssistant } from 'xertica-ui/assistant';
-import { useRichTextEditor } from 'xertica-ui/ui';
-
-// Full custom sidebar
-const { expanded, toggleExpanded, navigationGroups } = useSidebar({ defaultExpanded: true });
-
-// Full custom assistant
-const { mensagens, mensagem, setMensagem, handleEnviarMensagem } = useAssistant({ demoMode: true });
-
-// Full custom editor
-const { editorRef, activeFormats, execCommand, handleInput } = useRichTextEditor({
-  value,
-  onChange,
-});
-```
-
-### Available Headless Hooks
-
-| Hook                | Import                 | Description                                             |
-| ------------------- | ---------------------- | ------------------------------------------------------- |
-| `useSidebar`        | `xertica-ui/layout`    | Sidebar expansion, overflow detection, navigation state |
-| `useAssistant`      | `xertica-ui/assistant` | Full assistant state: messages, conversations, handlers |
-| `useRichTextEditor` | `xertica-ui/ui`        | Editor formatting state, search, link management        |
-
-### Design Principles
-
-1. **Hooks own all state** — No state lives in the presentational component; it is always delegated to the hook.
-2. **Backward compatible** — The Tier 1 monolithic API is unchanged. Existing consumers are unaffected.
-3. **Single source of truth** — The hook is the canonical implementation. The default component is a thin wrapper around it.
-4. **`useCallback` everywhere** — All handlers in hooks are memoized to prevent unnecessary re-renders in custom UIs.
-5. **TypeScript-first** — Every hook exports a `Props` interface and a `Return` interface for full type safety.
-
----
+# Xertica UI — Architecture
+
+## Audit Date
+
+2026-05-20 (Post-Modularization + State Layer)
+
+---
+
+## Summary of Changes
+
+The library underwent a **complete architectural modularization**. The flat `components/` directory was reorganized into a domain-driven structure, and a dedicated **state layer** was introduced via `features/`, `AuthContext`, TanStack React Query, and Zustand.
+
+### Component Domains
+
+| Domain      | Path                    | Contains                                                                                                     |
+| ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ui`        | `components/ui/[name]/` | Design system primitives (Button, Card, Calendar, Chart, etc.)                                               |
+| `layout`    | `components/layout/`    | Sidebar, Header, SidebarPrimitive                                                                            |
+| `blocks`    | `components/blocks/`    | High-level composed components built from `ui/` primitives                                                   |
+| `assistant` | `components/assistant/` | XerticaAssistant, MarkdownMessage, CodeBlock, etc.                                                           |
+| `brand`     | `components/brand/`     | XerticaLogo, ThemeToggle, LanguageSelector, XerticaProvider                                                  |
+| `pages`     | `components/pages/`     | LoginPage, HomePage, TemplatePage, etc.                                                                      |
+| `shared`    | `components/shared/`    | utils.ts, use-mobile.ts, layout-constants.ts, navigation.ts, **error-boundary.tsx**, **error-fallbacks.tsx** |
+
+### State Layer — `features/`
+
+Feature slices separate server state, client UI state, and mock data from the component tree.
+
+**Library source** (in this repo, used by Storybook and the showcase pages):
+
+```
+features/
+├── home/
+│   ├── data/mock.ts               ← typed mock data + async fetch functions (swap point for real API)
+│   ├── hooks/
+│   │   ├── useDashboardStats.ts   ← React Query (staleTime 5 min) — library-only
+│   │   ├── useTeamMembers.ts      ← React Query (staleTime 2 min) — library-only
+│   │   └── useFeatureCards.ts     ← React Query (staleTime 10 min)
+│   ├── store/dashboardStore.ts    ← Zustand (progress, slider, activeTab — UI-only)
+│   └── index.ts                   ← barrel
+└── assistant/
+    ├── data/mock.ts               ← AssistantConfig + fetchAssistantConfig (swap point)
+    ├── hooks/useAssistantConfig.ts ← React Query (staleTime 30 min)
+    └── index.ts                   ← barrel
+```
+
+**Scaffold template** (what `npx xertica-ui init` generates in a consumer project):
+
+```
+src/features/
+├── home/
+│   ├── data/mock.ts
+│   ├── hooks/useFeatureCards.ts   ← only useFeatureCards is scaffolded
+│   ├── store/dashboardStore.ts
+│   ├── ui/HomeContent.tsx
+│   └── index.ts
+└── assistant/
+    ├── data/mock.ts               ← exports getMockRichSuggestions() / getMockFeedbackOptions() factories
+    ├── hooks/useAssistantConfig.ts
+    └── index.ts
+```
+
+> `useDashboardStats` and `useTeamMembers` exist only in the library source where they power `TemplateContent.tsx`'s design-system showcase. They are NOT generated in the scaffold template. Consumer projects that need them must scaffold their own following the same pattern.
+
+All four hooks include the active **language** in their `queryKey` (`['home', 'feature-cards', language]`) so switching language triggers an automatic refetch in the new locale — see [`docs/i18n.md`](./i18n.md#language-aware-react-query-keys).
+
+**Swap pattern**: to connect a feature to a real API, replace only the `async function fetch*()` in `data/mock.ts`. The hook, the component, and the type contract remain unchanged.
+
+```ts
+// data/mock.ts — before (mock)
+export async function fetchTeamMembers(): Promise<TeamMember[]> {
+  await new Promise(resolve => setTimeout(resolve, 250));
+  return MOCK_TEAM_MEMBERS;
+}
+
+// data/mock.ts — after (real API)
+export async function fetchTeamMembers(): Promise<TeamMember[]> {
+  return fetch('/api/team/members').then(r => r.json());
+}
+```
+
+### i18n Layer
+
+Internationalization uses `i18next` + `react-i18next`. The setup is bootstrapped in `i18n.ts` (imported in `main.tsx`) and wired to `LanguageContext`:
+
+```
+i18n.ts                          ← configures i18next via import.meta.glob (auto-discovers new JSON files)
+locales/
+├── pt-BR/
+│   ├── common.json              ← shared action labels
+│   ├── nav.json                 ← navigation labels
+│   ├── errors.json              ← error boundary UI
+│   ├── languageSelector.json    ← language picker UI
+│   ├── themeToggle.json         ← theme toggle UI
+│   ├── pages/
+│   │   └── home.json, templates.json, login.json, resetPassword.json, verifyEmail.json,
+│   │       loginTemplate.json, formTemplate.json, dashboardTemplate.json, crudTemplate.json
+│   └── components/
+│       └── assistant.json, sidebar.json, media.json, projectCard.json, profileCard.json,
+│           notificationCard.json, activityCard.json, stats.json, team.json
+├── en/    ← same structure
+└── es/    ← same structure
+contexts/LanguageContext.tsx      ← setLanguage() calls i18n.changeLanguage() + persists to localStorage
+components/brand/language-selector/LanguageSelector.tsx  ← uses useLanguage() + useTranslation()
+```
+
+All page components use `useTranslation()` for UI strings. Mock data functions use `i18n.t()` (the instance) at query time so they respond to the active language.
+
+### ErrorBoundary Layer
+
+Three pre-configured wrappers for granular error isolation:
+
+```
+components/shared/
+├── error-boundary.tsx    ← ErrorBoundary class + AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary
+└── error-fallbacks.tsx   ← AppErrorFallback, PageErrorFallback, SectionErrorFallback
+```
+
+Placement in `App.tsx`:
+
+```
+AppErrorBoundary (outermost — before QueryClientProvider)
+  └─ QueryClientProvider
+      └─ ...providers...
+          └─ Router
+              └─ AuthProvider
+                  └─ PageErrorBoundary (wraps Routes/AuthGuard)
+                      └─ Suspense + Routes
+                          └─ Pages
+                              └─ SectionErrorBoundary (wraps data sections)
+```
+
+### AuthContext
+
+Authentication state lives in `contexts/AuthContext.tsx` and is consumed via `useAuth()`:
+
+```
+contexts/
+└── AuthContext.tsx    ← AuthProvider + useAuth() hook
+```
+
+`AuthProvider` must be rendered **inside** `<BrowserRouter>` (it uses `useNavigate`). It:
+
+- Hydrates session from `localStorage` on mount (`isLoading` flag prevents flash redirects)
+- Exposes `user`, `login(email, password) → boolean`, `logout()`
+- Redirects authenticated users away from auth-only pages automatically
+
+Page components (`HomePage`, `TemplatePage`) consume `useAuth()` directly — no `user`/`onLogout` prop drilling.
+
+### Lazy Loading
+
+All routes in `App.tsx` use `React.lazy()` + `<Suspense>`. Each page is a separate chunk loaded only when the route is first visited:
+
+```tsx
+const HomePage = React.lazy(() =>
+  import('./components/pages/home-page').then(m => ({ default: m.HomePage }))
+);
+```
+
+### Provider Stack
+
+```tsx
+<QueryClientProvider client={queryClient}>
+  {' '}
+  // ← TanStack React Query
+  <ApiKeyProvider>
+    <GoogleMapsLoaderProvider>
+      <LanguageProvider>
+        <BrandColorsProvider>
+          <ThemeProvider>
+            <AssistenteProvider>
+              <LayoutProvider>
+                <Router>
+                  <AuthProvider>
+                    {' '}
+                    // ← must be inside Router
+                    <Suspense fallback={null}>
+                      <AppRoutes />
+                    </Suspense>
+                  </AuthProvider>
+                </Router>
+              </LayoutProvider>
+            </AssistenteProvider>
+          </ThemeProvider>
+        </BrandColorsProvider>
+      </LanguageProvider>
+    </GoogleMapsLoaderProvider>
+  </ApiKeyProvider>
+</QueryClientProvider>
+```
+
+### blocks/ domain
+
+The `blocks/` domain contains **pre-composed patterns** built exclusively from `ui/` primitives. Unlike primitives, blocks encapsulate specific use-case logic and are ready to drop into dashboards and feature pages without additional composition.
+
+```
+components/blocks/
+└── card-patterns/
+    ├── ActivityCard.tsx      — activity feed with avatars and type badges
+    ├── ProfileCard.tsx       — user/member card with stats and actions
+    ├── ProjectCard.tsx       — project status with progress bar and member avatars
+    ├── QuickActionCard.tsx   — icon + title + description + action button
+    ├── NotificationCard.tsx  — notification list with unread indicators
+    ├── FeatureCard.tsx       — colored icon + title + badge + description + CTA
+    └── index.ts
+```
+
+All block components are exported from both `components/blocks/index.ts` and the root `components/index.ts` barrel.
+
+**Consumers can import from the root `xertica-ui` entrypoint (all components) or from granular subpath entries (v2, recommended for FSD/FDA projects).**
+
+---
+
+## Subpath Exports (v2)
+
+The build system produces 7 distinct entry bundles from a multi-entry Vite `lib.entry` configuration. Each bundle maps to a `package.json` `exports` subpath:
+
+| Subpath                | Source entry                    | Contents                                                                   |
+| ---------------------- | ------------------------------- | -------------------------------------------------------------------------- |
+| `xertica-ui`           | `components/index.ts`           | Full barrel — all components                                               |
+| `xertica-ui/ui`        | `components/ui/index.ts`        | All UI primitives                                                          |
+| `xertica-ui/blocks`    | `components/blocks/index.ts`    | High-level composed patterns (ActivityCard, ProjectCard, etc.)             |
+| `xertica-ui/layout`    | `components/layout/index.ts`    | Sidebar, Header                                                            |
+| `xertica-ui/brand`     | `components/brand/index.ts`     | XerticaProvider, XerticaLogo, ThemeToggle, LanguageSelector, etc.          |
+| `xertica-ui/assistant` | `components/assistant/index.ts` | XerticaAssistant, MarkdownMessage, CodeBlock, etc.                         |
+| `xertica-ui/media`     | `components/media/index.ts`     | VideoPlayer, AudioPlayer, FloatingMediaWrapper                             |
+| `xertica-ui/hooks`     | `components/hooks/index.ts`     | useLayout, useTheme, useLanguage, useBrandColors, useAssistente, useApiKey |
+
+Each subpath exposes three fields in `exports`: `types` (`.d.ts`), `import` (ES module), `require` (UMD).
+
+> TypeScript consumers need `"moduleResolution": "bundler"` (or `"node16"` / `"nodenext"`) to resolve subpath exports.
+
+---
+
+## Headless UI Pattern (v3)
+
+The library follows a **three-tier composability model** for its complex components. Each tier is a superset of the previous — consumers can choose the level of control they need.
+
+### Tier 1 — Monolithic API (drop-in)
+
+The default export. Zero configuration, full functionality. Ideal for rapid integration.
+
+```tsx
+import { Sidebar } from 'xertica-ui/layout';
+import { XerticaAssistant } from 'xertica-ui/assistant';
+import { RichTextEditor } from 'xertica-ui/ui';
+
+<Sidebar navigationGroups={groups} />
+<XerticaAssistant demoMode={true} />
+<RichTextEditor value={html} onChange={setHtml} />
+```
+
+### Tier 2 — Compound Components (structural control)
+
+Sub-components exposed as static properties on the main component. Consumers control layout and composition while the shared React Context handles state propagation.
+
+```tsx
+import { Sidebar } from 'xertica-ui/layout';
+
+<Sidebar.Root navigationGroups={groups}>
+  <Sidebar.Header logo={<MyLogo />} />
+  <Sidebar.Nav />
+  <Sidebar.Search search={searchConfig} />
+  <Sidebar.Footer showUser showSettings />
+</Sidebar.Root>;
+```
+
+Available compound components:
+
+| Component | Sub-components                                                                      |
+| --------- | ----------------------------------------------------------------------------------- |
+| `Sidebar` | `Sidebar.Root`, `Sidebar.Header`, `Sidebar.Nav`, `Sidebar.Search`, `Sidebar.Footer` |
+
+### Tier 3 — Headless Hooks (full control)
+
+Pure logic hooks with zero UI. Consumers bring their own markup, styling, and layout. The hook manages all state, refs, effects, and handlers.
+
+```tsx
+import { useSidebar } from 'xertica-ui/layout';
+import { useAssistant } from 'xertica-ui/assistant';
+import { useRichTextEditor } from 'xertica-ui/ui';
+
+// Full custom sidebar
+const { expanded, toggleExpanded, navigationGroups } = useSidebar({ defaultExpanded: true });
+
+// Full custom assistant
+const { mensagens, mensagem, setMensagem, handleEnviarMensagem } = useAssistant({ demoMode: true });
+
+// Full custom editor
+const { editorRef, activeFormats, execCommand, handleInput } = useRichTextEditor({
+  value,
+  onChange,
+});
+```
+
+### Available Headless Hooks
+
+| Hook                | Import                 | Description                                             |
+| ------------------- | ---------------------- | ------------------------------------------------------- |
+| `useSidebar`        | `xertica-ui/layout`    | Sidebar expansion, overflow detection, navigation state |
+| `useAssistant`      | `xertica-ui/assistant` | Full assistant state: messages, conversations, handlers |
+| `useRichTextEditor` | `xertica-ui/ui`        | Editor formatting state, search, link management        |
+
+### Design Principles
+
+1. **Hooks own all state** — No state lives in the presentational component; it is always delegated to the hook.
+2. **Backward compatible** — The Tier 1 monolithic API is unchanged. Existing consumers are unaffected.
+3. **Single source of truth** — The hook is the canonical implementation. The default component is a thin wrapper around it.
+4. **`useCallback` everywhere** — All handlers in hooks are memoized to prevent unnecessary re-renders in custom UIs.
+5. **TypeScript-first** — Every hook exports a `Props` interface and a `Return` interface for full type safety.
+
+---