xertica-ui 2.2.1 → 2.4.0

package/docs/components/error-boundary.md

@@ -1,191 +1,201 @@
-# ErrorBoundary — Xertica UI
-
-React Error Boundaries catch JavaScript errors in the component tree, log them, and render a fallback UI instead of crashing the application. Xertica UI ships a single reusable `ErrorBoundary` class with **three pre-configured wrapper variants** covering every granularity of protection.
-
----
-
-## Import
-
-```tsx
-// Pre-configured wrappers (recommended)
-import {
-  AppErrorBoundary,
-  PageErrorBoundary,
-  SectionErrorBoundary,
-} from '@/components/shared/error-boundary';
-
-// Base class (for custom fallbacks)
-import { ErrorBoundary } from '@/components/shared/error-boundary';
-import type { FallbackProps } from '@/components/shared/error-boundary';
-```
-
----
-
-## The Three Variants
-
-| Variant | Fallback UI | Placement | Purpose |
-|---|---|---|---|
-| `AppErrorBoundary` | Full-screen, inline-styled | Outside `QueryClientProvider`, wraps entire `App` | Catches provider/context crashes; works even if Tailwind/CSS fails |
-| `PageErrorBoundary` | Half-height, Tailwind-styled | Wraps `<Routes>` / `<AuthGuard>` inside the router | Catches lazy-chunk load failures and page render errors; app chrome stays alive |
-| `SectionErrorBoundary` | Compact inline badge | Wraps individual sections (table, chart, assistant) | Catches isolated data-rendering errors; page layout stays intact |
-
----
-
-## Provider Stack Placement
-
-```tsx
-<AppErrorBoundary>                          {/* ← catches: provider init, context crashes */}
-  <QueryClientProvider client={queryClient}>
-    <XerticaProvider>
-      <Router>
-        <AuthProvider>
-          <PageErrorBoundary>              {/* ← catches: lazy chunk failures, route renders */}
-            <Suspense fallback={null}>
-              <Routes>
-                <Route path="/home" element={
-                  <ProtectedRoute>
-                    <HomePage />           {/* ← page internals */}
-                  </ProtectedRoute>
-                } />
-              </Routes>
-            </Suspense>
-          </PageErrorBoundary>
-        </AuthProvider>
-      </Router>
-    </XerticaProvider>
-  </QueryClientProvider>
-</AppErrorBoundary>
-```
-
----
-
-## Props
-
-### `AppErrorBoundary` / `PageErrorBoundary` / `SectionErrorBoundary`
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | — | **Required.** Content to protect |
-| `onError` | `(error: Error, info: React.ErrorInfo) => void` | — | Called when an error is caught. Wire to Sentry, Datadog, etc. |
-| `resetKeys` | `unknown[]` | — | When any value in this array changes, the boundary auto-resets. Pass `[location.pathname]` to reset on navigation |
-
-### Base `ErrorBoundary`
-
-Same props plus:
-
-| Prop | Type | Description |
-|---|---|---|
-| `fallback` | `React.ComponentType<FallbackProps>` | **Required.** The component to render when an error is caught |
-
-### `FallbackProps` interface
-
-```ts
-interface FallbackProps {
-  error: Error;   // The caught error
-  reset: () => void; // Call to clear the error and re-render children
-}
-```
-
----
-
-## Usage Examples
-
-### Protecting a data table section
-
-```tsx
-import { SectionErrorBoundary } from '@/components/shared/error-boundary';
-
-function TeamSection() {
-  return (
-    <SectionErrorBoundary>
-      <TeamDataTable />
-    </SectionErrorBoundary>
-  );
-}
-```
-
-### Resetting on route change
-
-```tsx
-import { PageErrorBoundary } from '@/components/shared/error-boundary';
-import { useLocation } from 'react-router-dom';
-
-function AppRoutes() {
-  const location = useLocation();
-  return (
-    <PageErrorBoundary resetKeys={[location.pathname]}>
-      <Suspense fallback={null}>
-        <Routes>{/* ... */}</Routes>
-      </Suspense>
-    </PageErrorBoundary>
-  );
-}
-```
-
-### Logging to an error monitoring service
-
-```tsx
-import { AppErrorBoundary } from '@/components/shared/error-boundary';
-import * as Sentry from '@sentry/react';
-
-<AppErrorBoundary onError={(error, info) => Sentry.captureException(error, { extra: info })}>
-  <App />
-</AppErrorBoundary>
-```
-
-### Custom fallback with base `ErrorBoundary`
-
-```tsx
-import { ErrorBoundary } from '@/components/shared/error-boundary';
-import type { FallbackProps } from '@/components/shared/error-boundary';
-
-function MyFallback({ error, reset }: FallbackProps) {
-  return (
-    <div role="alert">
-      <p>Erro: {error.message}</p>
-      <button onClick={reset}>Tentar novamente</button>
-    </div>
-  );
-}
-
-<ErrorBoundary fallback={MyFallback}>
-  <MyComponent />
-</ErrorBoundary>
-```
-
----
-
-## Fallback UIs
-
-### `AppErrorFallback`
-- Full-screen centered layout using **inline styles** (no Tailwind dependency)
-- Shows a destructive info icon, error title, and message
-- Two buttons: "Tentar novamente" (calls `reset()`) and "Ir para o início" (`window.location.assign('/')`)
-- In `DEV` mode: displays the full error stack trace in a `<pre>` block
-
-### `PageErrorFallback`
-- Uses Tailwind / xertica-ui token classes
-- Centered within the page content area (sidebar and header remain visible)
-- Triangle warning icon + descriptive message
-- Same two action buttons
-
-### `SectionErrorFallback`
-- Compact `rounded-lg` card with `destructive/30` border
-- Circle info icon + short message
-- Single "Tentar novamente" button
-- In `DEV` mode: shows `error.message` in a mono paragraph
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **ALWAYS** place `<AppErrorBoundary>` as the **outermost** element in `App.tsx`, before `QueryClientProvider`. If the query client itself crashes, the app must still show something.
-> - **ALWAYS** place `<PageErrorBoundary>` around `<Routes>` / `<AuthGuard>`. This is the primary protection against lazy-chunk load failures (network errors, chunk not found).
-> - **USE** `<SectionErrorBoundary>` around any section that fetches data or renders complex content (tables, charts, the assistant panel, embedded maps). An error in one section must not crash the page.
-> - **DO NOT** place `<AppErrorBoundary>` inside `<Router>` — it must be outside the router so `AppErrorFallback` can use `window.location.assign` (not `useNavigate`).
-> - **DO NOT** use `try/catch` as a substitute for `ErrorBoundary` — try/catch does not catch render-time errors in React component trees. Both are needed for different error classes.
-> - **Pass `onError`** to the `AppErrorBoundary` in production to send errors to Sentry, Datadog, or another observability service.
-> - **Pass `resetKeys={[location.pathname]}`** to `PageErrorBoundary` if you want errors to auto-clear when the user navigates to a different route.
-> - Error boundaries do **not** catch: errors in event handlers (use try/catch there), async errors outside render (use React Query's `onError`), errors in server-side rendering, and errors thrown in the boundary itself.
+# ErrorBoundary — Xertica UI
+
+React Error Boundaries catch JavaScript errors in the component tree, log them, and render a fallback UI instead of crashing the application. Xertica UI ships a single reusable `ErrorBoundary` class with **three pre-configured wrapper variants** covering every granularity of protection.
+
+---
+
+## Import
+
+```tsx
+// Pre-configured wrappers (recommended)
+import {
+  AppErrorBoundary,
+  PageErrorBoundary,
+  SectionErrorBoundary,
+} from '@/components/shared/error-boundary';
+
+// Base class (for custom fallbacks)
+import { ErrorBoundary } from '@/components/shared/error-boundary';
+import type { FallbackProps } from '@/components/shared/error-boundary';
+```
+
+---
+
+## The Three Variants
+
+| Variant                | Fallback UI                  | Placement                                           | Purpose                                                                         |
+| ---------------------- | ---------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `AppErrorBoundary`     | Full-screen, inline-styled   | Outside `QueryClientProvider`, wraps entire `App`   | Catches provider/context crashes; works even if Tailwind/CSS fails              |
+| `PageErrorBoundary`    | Half-height, Tailwind-styled | Wraps `<Routes>` / `<AuthGuard>` inside the router  | Catches lazy-chunk load failures and page render errors; app chrome stays alive |
+| `SectionErrorBoundary` | Compact inline badge         | Wraps individual sections (table, chart, assistant) | Catches isolated data-rendering errors; page layout stays intact                |
+
+---
+
+## Provider Stack Placement
+
+```tsx
+<AppErrorBoundary>
+  {' '}
+  {/* ← catches: provider init, context crashes */}
+  <QueryClientProvider client={queryClient}>
+    <XerticaProvider>
+      <Router>
+        <AuthProvider>
+          <PageErrorBoundary>
+            {' '}
+            {/* ← catches: lazy chunk failures, route renders */}
+            <Suspense fallback={null}>
+              <Routes>
+                <Route
+                  path="/home"
+                  element={
+                    <ProtectedRoute>
+                      <HomePage /> {/* ← page internals */}
+                    </ProtectedRoute>
+                  }
+                />
+              </Routes>
+            </Suspense>
+          </PageErrorBoundary>
+        </AuthProvider>
+      </Router>
+    </XerticaProvider>
+  </QueryClientProvider>
+</AppErrorBoundary>
+```
+
+---
+
+## Props
+
+### `AppErrorBoundary` / `PageErrorBoundary` / `SectionErrorBoundary`
+
+| Prop        | Type                                            | Default | Description                                                                                                       |
+| ----------- | ----------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `children`  | `ReactNode`                                     | —       | **Required.** Content to protect                                                                                  |
+| `onError`   | `(error: Error, info: React.ErrorInfo) => void` | —       | Called when an error is caught. Wire to Sentry, Datadog, etc.                                                     |
+| `resetKeys` | `unknown[]`                                     | —       | When any value in this array changes, the boundary auto-resets. Pass `[location.pathname]` to reset on navigation |
+
+### Base `ErrorBoundary`
+
+Same props plus:
+
+| Prop       | Type                                 | Description                                                   |
+| ---------- | ------------------------------------ | ------------------------------------------------------------- |
+| `fallback` | `React.ComponentType<FallbackProps>` | **Required.** The component to render when an error is caught |
+
+### `FallbackProps` interface
+
+```ts
+interface FallbackProps {
+  error: Error; // The caught error
+  reset: () => void; // Call to clear the error and re-render children
+}
+```
+
+---
+
+## Usage Examples
+
+### Protecting a data table section
+
+```tsx
+import { SectionErrorBoundary } from '@/components/shared/error-boundary';
+
+function TeamSection() {
+  return (
+    <SectionErrorBoundary>
+      <TeamDataTable />
+    </SectionErrorBoundary>
+  );
+}
+```
+
+### Resetting on route change
+
+```tsx
+import { PageErrorBoundary } from '@/components/shared/error-boundary';
+import { useLocation } from 'react-router-dom';
+
+function AppRoutes() {
+  const location = useLocation();
+  return (
+    <PageErrorBoundary resetKeys={[location.pathname]}>
+      <Suspense fallback={null}>
+        <Routes>{/* ... */}</Routes>
+      </Suspense>
+    </PageErrorBoundary>
+  );
+}
+```
+
+### Logging to an error monitoring service
+
+```tsx
+import { AppErrorBoundary } from '@/components/shared/error-boundary';
+import * as Sentry from '@sentry/react';
+
+<AppErrorBoundary onError={(error, info) => Sentry.captureException(error, { extra: info })}>
+  <App />
+</AppErrorBoundary>;
+```
+
+### Custom fallback with base `ErrorBoundary`
+
+```tsx
+import { ErrorBoundary } from '@/components/shared/error-boundary';
+import type { FallbackProps } from '@/components/shared/error-boundary';
+
+function MyFallback({ error, reset }: FallbackProps) {
+  return (
+    <div role="alert">
+      <p>Erro: {error.message}</p>
+      <button onClick={reset}>Tentar novamente</button>
+    </div>
+  );
+}
+
+<ErrorBoundary fallback={MyFallback}>
+  <MyComponent />
+</ErrorBoundary>;
+```
+
+---
+
+## Fallback UIs
+
+### `AppErrorFallback`
+
+- Full-screen centered layout using **inline styles** (no Tailwind dependency)
+- Shows a destructive info icon, error title, and message
+- Two buttons: "Tentar novamente" (calls `reset()`) and "Ir para o início" (`window.location.assign('/')`)
+- In `DEV` mode: displays the full error stack trace in a `<pre>` block
+
+### `PageErrorFallback`
+
+- Uses Tailwind / xertica-ui token classes
+- Centered within the page content area (sidebar and header remain visible)
+- Triangle warning icon + descriptive message
+- Same two action buttons
+
+### `SectionErrorFallback`
+
+- Compact `rounded-lg` card with `destructive/30` border
+- Circle info icon + short message
+- Single "Tentar novamente" button
+- In `DEV` mode: shows `error.message` in a mono paragraph
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **ALWAYS** place `<AppErrorBoundary>` as the **outermost** element in `App.tsx`, before `QueryClientProvider`. If the query client itself crashes, the app must still show something.
+> - **ALWAYS** place `<PageErrorBoundary>` around `<Routes>` / `<AuthGuard>`. This is the primary protection against lazy-chunk load failures (network errors, chunk not found).
+> - **USE** `<SectionErrorBoundary>` around any section that fetches data or renders complex content (tables, charts, the assistant panel, embedded maps). An error in one section must not crash the page.
+> - **DO NOT** place `<AppErrorBoundary>` inside `<Router>` — it must be outside the router so `AppErrorFallback` can use `window.location.assign` (not `useNavigate`).
+> - **DO NOT** use `try/catch` as a substitute for `ErrorBoundary` — try/catch does not catch render-time errors in React component trees. Both are needed for different error classes.
+> - **Pass `onError`** to the `AppErrorBoundary` in production to send errors to Sentry, Datadog, or another observability service.
+> - **Pass `resetKeys={[location.pathname]}`** to `PageErrorBoundary` if you want errors to auto-clear when the user navigates to a different route.
+> - Error boundaries do **not** catch: errors in event handlers (use try/catch there), async errors outside render (use React Query's `onError`), errors in server-side rendering, and errors thrown in the boundary itself.