xertica-ui 2.5.0 → 2.5.2

package/components/pages/template-content/template-content.mdx

@@ -1,61 +1,61 @@
-import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
-
-<Meta title="Pages/TemplateContent" />
-
-<Title>TemplateContent</Title>
-<Subtitle>Kitchen-sink showcase and CLI starter template demonstrating the full Xertica UI component set.</Subtitle>
-
----
-
-## Overview
-
-`TemplateContent` is a comprehensive living demo that assembles the majority of Xertica UI primitives into a single scrollable page. It serves two purposes:
-
-1. **Development reference** - Shows the correct composition patterns for every major component.
-2. **CLI starter** - Acts as the baseline when scaffolding a new application page.
-
-It includes interactive showcases for cards, tabs, forms, tables, dialogs, alerts, progress, sliders, maps, headers, and sidebars.
-
-```tsx
-import { TemplateContent } from 'xertica-ui';
-
-{ path: '/template', element: <TemplateContent /> }
-```
-
----
-
-## Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `user` | `{ name?: string; email?: string; avatar?: string } \| null` | - | Currently authenticated user for the header. |
-| `onLogout` | `() => void` | - | Logout handler forwarded to the header. |
-| `onSettings` | `() => void` | - | Settings handler forwarded to the header. |
-
----
-
-## Layout Dependency
-
-`TemplateContent` uses optional layout state. When wrapped in `XerticaProvider`, it synchronizes sidebar width, expanded state, and layout controls. Without the provider, it renders with local fallback sidebar state.
-
-React Router is still required because the showcase uses `Link` and `useNavigate`.
-
----
-
-## Sidebar Showcase
-
-`TemplateContent` includes an embedded, interactive `Sidebar` preview with controls for:
-
-- Toggling footer sections.
-- Adjusting sidebar width via a `Slider`.
-- Switching between `variant="assistant"` and `variant="default"` modes.
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Reference first** - Before building a new page, check `TemplateContent` for the correct composition pattern.
-> - **Provider fallback** - `TemplateContent` renders without `XerticaProvider`, but the provider is recommended for synchronized layout state.
-> - **Router requirement** - React Router is still required for navigation hooks and links.
-> - **Map section** - The Maps showcase requires a valid `googleMapsApiKey` passed to `XerticaProvider`.
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+
+<Meta title="Pages/TemplateContent" />
+
+<Title>TemplateContent</Title>
+<Subtitle>Kitchen-sink showcase and CLI starter template demonstrating the full Xertica UI component set.</Subtitle>
+
+---
+
+## Overview
+
+`TemplateContent` is a comprehensive living demo that assembles the majority of Xertica UI primitives into a single scrollable page. It serves two purposes:
+
+1. **Development reference** - Shows the correct composition patterns for every major component.
+2. **CLI starter** - Acts as the baseline when scaffolding a new application page.
+
+It includes interactive showcases for cards, tabs, forms, tables, dialogs, alerts, progress, sliders, maps, headers, and sidebars.
+
+```tsx
+import { TemplateContent } from 'xertica-ui';
+
+{ path: '/template', element: <TemplateContent /> }
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `user` | `{ name?: string; email?: string; avatar?: string } \| null` | - | Currently authenticated user for the header. |
+| `onLogout` | `() => void` | - | Logout handler forwarded to the header. |
+| `onSettings` | `() => void` | - | Settings handler forwarded to the header. |
+
+---
+
+## Layout Dependency
+
+`TemplateContent` uses optional layout state. When wrapped in `XerticaProvider`, it synchronizes sidebar width, expanded state, and layout controls. Without the provider, it renders with local fallback sidebar state.
+
+React Router is still required because the showcase uses `Link` and `useNavigate`.
+
+---
+
+## Sidebar Showcase
+
+`TemplateContent` includes an embedded, interactive `Sidebar` preview with controls for:
+
+- Toggling footer sections.
+- Adjusting sidebar width via a `Slider`.
+- Switching between `variant="assistant"` and `variant="default"` modes.
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Reference first** - Before building a new page, check `TemplateContent` for the correct composition pattern.
+> - **Provider fallback** - `TemplateContent` renders without `XerticaProvider`, but the provider is recommended for synchronized layout state.
+> - **Router requirement** - React Router is still required for navigation hooks and links.
+> - **Map section** - The Maps showcase requires a valid `googleMapsApiKey` passed to `XerticaProvider`.

package/components/pages/template-page/TemplatePage.stories.tsx

@@ -1,32 +1,32 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import { TemplatePage } from './TemplatePage';
-import { MemoryRouter } from 'react-router-dom';
-import { LayoutProvider } from '../../../contexts/LayoutContext';
-import { AuthProvider } from '../../../contexts/AuthContext';
-import React from 'react';
-
-const meta: Meta<typeof TemplatePage> = {
-  title: 'Pages/TemplatePage',
-  component: TemplatePage,
-  decorators: [
-    Story => (
-      <MemoryRouter initialEntries={['/template']}>
-        <AuthProvider>
-          <LayoutProvider>
-            <Story />
-          </LayoutProvider>
-        </AuthProvider>
-      </MemoryRouter>
-    ),
-  ],
-  parameters: {
-    layout: 'fullscreen',
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof TemplatePage>;
-
-export const Default: Story = {};
-
-export const NoUser: Story = {};
+import type { Meta, StoryObj } from '@storybook/react';
+import { TemplatePage } from './TemplatePage';
+import { MemoryRouter } from 'react-router-dom';
+import { LayoutProvider } from '../../../contexts/LayoutContext';
+import { AuthProvider } from '../../../contexts/AuthContext';
+import React from 'react';
+
+const meta: Meta<typeof TemplatePage> = {
+  title: 'Pages/TemplatePage',
+  component: TemplatePage,
+  decorators: [
+    Story => (
+      <MemoryRouter initialEntries={['/template']}>
+        <AuthProvider>
+          <LayoutProvider>
+            <Story />
+          </LayoutProvider>
+        </AuthProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TemplatePage>;
+
+export const Default: Story = {};
+
+export const NoUser: Story = {};

package/components/pages/template-page/template-page.mdx

@@ -1,53 +1,53 @@
-import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
-import * as TemplatePageStories from './TemplatePage.stories';
-
-<Meta of={TemplatePageStories} />
-
-<Title>TemplatePage</Title>
-<Subtitle>Full application shell with the component kitchen-sink reference.</Subtitle>
-
----
-
-## Overview
-
-`TemplatePage` is the reference implementation of the full application layout. It assembles:
-
-- **Sidebar** - Primary navigation.
-- **TemplateContent** - Kitchen-sink showcase of Xertica UI components.
-- **XerticaAssistant** - Floating AI assistant panel.
-
-When `XerticaProvider` is present, the page synchronizes sidebar width, sidebar expansion, and assistant visibility through `LayoutContext`. Without the provider, it renders with local fallback layout state.
-
-**Requires:** React Router v6. `XerticaProvider` is recommended for app-level synchronization.
-
----
-
-## Props
-
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `user` | `{ email: string } \| null` | Yes | Currently authenticated user. Passed to Sidebar for avatar and user menu display. |
-| `onLogout` | `() => void` | Yes | Called when the user triggers logout from the Sidebar. |
-
----
-
-## Composition
-
-```tsx
-import { TemplatePage } from 'xertica-ui';
-
-<Route
-  path="/template"
-  element={<TemplatePage user={currentUser} onLogout={handleLogout} />}
-/>
-```
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Reference implementation** - Use `TemplatePage` as the primary reference for assembling complex layouts.
-> - **Top-level only** - This is a full-screen layout component. Do not nest it inside other layouts.
-> - **Provider fallback** - The page renders without `XerticaProvider`, but the provider is recommended for synchronized app layout.
-> - **Extend via TemplateContent** - To change showcased components, edit `TemplateContent`.
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+import * as TemplatePageStories from './TemplatePage.stories';
+
+<Meta of={TemplatePageStories} />
+
+<Title>TemplatePage</Title>
+<Subtitle>Full application shell with the component kitchen-sink reference.</Subtitle>
+
+---
+
+## Overview
+
+`TemplatePage` is the reference implementation of the full application layout. It assembles:
+
+- **Sidebar** - Primary navigation.
+- **TemplateContent** - Kitchen-sink showcase of Xertica UI components.
+- **XerticaAssistant** - Floating AI assistant panel.
+
+When `XerticaProvider` is present, the page synchronizes sidebar width, sidebar expansion, and assistant visibility through `LayoutContext`. Without the provider, it renders with local fallback layout state.
+
+**Requires:** React Router v6. `XerticaProvider` is recommended for app-level synchronization.
+
+---
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `user` | `{ email: string } \| null` | Yes | Currently authenticated user. Passed to Sidebar for avatar and user menu display. |
+| `onLogout` | `() => void` | Yes | Called when the user triggers logout from the Sidebar. |
+
+---
+
+## Composition
+
+```tsx
+import { TemplatePage } from 'xertica-ui';
+
+<Route
+  path="/template"
+  element={<TemplatePage user={currentUser} onLogout={handleLogout} />}
+/>
+```
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Reference implementation** - Use `TemplatePage` as the primary reference for assembling complex layouts.
+> - **Top-level only** - This is a full-screen layout component. Do not nest it inside other layouts.
+> - **Provider fallback** - The page renders without `XerticaProvider`, but the provider is recommended for synchronized app layout.
+> - **Extend via TemplateContent** - To change showcased components, edit `TemplateContent`.

package/components/shared/error-boundary.stories.tsx

@@ -1,114 +1,114 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import React, { useState } from 'react';
-import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary } from './error-boundary';
-
-// ── Crash helper ─────────────────────────────────────────────────────────────
-// A component that throws on the next render when `shouldCrash` is true.
-// Used in every story to demonstrate real boundary behaviour.
-
-function Crashable({ shouldCrash, label }: { shouldCrash: boolean; label: string }) {
-  if (shouldCrash) throw new Error(`Simulated crash in: ${label}`);
-  return (
-    <div className="flex items-center justify-center p-8 rounded-[var(--radius-lg)] border border-border bg-card text-card-foreground">
-      <p className="text-sm text-muted-foreground">
-        ✅ <strong>{label}</strong> — rendering normally. Click the button to simulate a crash.
-      </p>
-    </div>
-  );
-}
-
-// ── Wrapper that controls crash state ────────────────────────────────────────
-
-function CrashController({
-  Boundary,
-  label,
-}: {
-  Boundary: React.ComponentType<{ children: React.ReactNode }>;
-  label: string;
-}) {
-  const [crashed, setCrashed] = useState(false);
-
-  return (
-    <div className="space-y-4">
-      <button
-        onClick={() => setCrashed(true)}
-        disabled={crashed}
-        className="inline-flex items-center px-4 py-2 text-sm rounded-[var(--radius-button)] bg-destructive text-destructive-foreground hover:bg-destructive/90 disabled:opacity-40 disabled:cursor-not-allowed"
-      >
-        Simulate crash
-      </button>
-
-      <Boundary>
-        <Crashable shouldCrash={crashed} label={label} />
-      </Boundary>
-    </div>
-  );
-}
-
-// ── Meta ──────────────────────────────────────────────────────────────────────
-
-const meta: Meta = {
-  title: 'Shared/ErrorBoundary',
-  parameters: {
-    layout: 'padded',
-    docs: {
-      description: {
-        component:
-          'Three pre-configured ErrorBoundary variants for root, page, and section-level error isolation. Click "Simulate crash" to see each fallback UI.',
-      },
-    },
-  },
-};
-
-export default meta;
-
-// ── Stories ───────────────────────────────────────────────────────────────────
-
-export const App: StoryObj = {
-  name: 'AppErrorBoundary (root fallback)',
-  render: () => <CrashController Boundary={AppErrorBoundary} label="App-level component" />,
-  parameters: {
-    docs: {
-      description: {
-        story:
-          '`AppErrorBoundary` renders a full-screen fallback using only inline styles — no Tailwind dependency — so it works even if the design system itself fails to load.',
-      },
-    },
-  },
-};
-
-export const Page: StoryObj = {
-  name: 'PageErrorBoundary (route fallback)',
-  render: () => <CrashController Boundary={PageErrorBoundary} label="Page component" />,
-  parameters: {
-    docs: {
-      description: {
-        story:
-          '`PageErrorBoundary` shows a half-height Tailwind-styled fallback. The sidebar, header, and other chrome remain visible — only the page content area is replaced.',
-      },
-    },
-  },
-};
-
-export const Section: StoryObj = {
-  name: 'SectionErrorBoundary (inline fallback)',
-  render: () => (
-    <div className="space-y-6 max-w-2xl">
-      <p className="text-sm text-muted-foreground">
-        Each card below is independently wrapped. Crashing one does not affect the others.
-      </p>
-
-      {(['Team table', 'Chart', 'Assistant panel'] as const).map(label => (
-        <CrashController key={label} Boundary={SectionErrorBoundary} label={label} />
-      ))}
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          '`SectionErrorBoundary` renders a compact inline fallback. Multiple independent sections on the same page can each fail in isolation.',
-      },
-    },
-  },
-};
+import type { Meta, StoryObj } from '@storybook/react';
+import React, { useState } from 'react';
+import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary } from './error-boundary';
+
+// ── Crash helper ─────────────────────────────────────────────────────────────
+// A component that throws on the next render when `shouldCrash` is true.
+// Used in every story to demonstrate real boundary behaviour.
+
+function Crashable({ shouldCrash, label }: { shouldCrash: boolean; label: string }) {
+  if (shouldCrash) throw new Error(`Simulated crash in: ${label}`);
+  return (
+    <div className="flex items-center justify-center p-8 rounded-[var(--radius-lg)] border border-border bg-card text-card-foreground">
+      <p className="text-sm text-muted-foreground">
+        ✅ <strong>{label}</strong> — rendering normally. Click the button to simulate a crash.
+      </p>
+    </div>
+  );
+}
+
+// ── Wrapper that controls crash state ────────────────────────────────────────
+
+function CrashController({
+  Boundary,
+  label,
+}: {
+  Boundary: React.ComponentType<{ children: React.ReactNode }>;
+  label: string;
+}) {
+  const [crashed, setCrashed] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      <button
+        onClick={() => setCrashed(true)}
+        disabled={crashed}
+        className="inline-flex items-center px-4 py-2 text-sm rounded-[var(--radius-button)] bg-destructive text-destructive-foreground hover:bg-destructive/90 disabled:opacity-40 disabled:cursor-not-allowed"
+      >
+        Simulate crash
+      </button>
+
+      <Boundary>
+        <Crashable shouldCrash={crashed} label={label} />
+      </Boundary>
+    </div>
+  );
+}
+
+// ── Meta ──────────────────────────────────────────────────────────────────────
+
+const meta: Meta = {
+  title: 'Shared/ErrorBoundary',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Three pre-configured ErrorBoundary variants for root, page, and section-level error isolation. Click "Simulate crash" to see each fallback UI.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const App: StoryObj = {
+  name: 'AppErrorBoundary (root fallback)',
+  render: () => <CrashController Boundary={AppErrorBoundary} label="App-level component" />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`AppErrorBoundary` renders a full-screen fallback using only inline styles — no Tailwind dependency — so it works even if the design system itself fails to load.',
+      },
+    },
+  },
+};
+
+export const Page: StoryObj = {
+  name: 'PageErrorBoundary (route fallback)',
+  render: () => <CrashController Boundary={PageErrorBoundary} label="Page component" />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`PageErrorBoundary` shows a half-height Tailwind-styled fallback. The sidebar, header, and other chrome remain visible — only the page content area is replaced.',
+      },
+    },
+  },
+};
+
+export const Section: StoryObj = {
+  name: 'SectionErrorBoundary (inline fallback)',
+  render: () => (
+    <div className="space-y-6 max-w-2xl">
+      <p className="text-sm text-muted-foreground">
+        Each card below is independently wrapped. Crashing one does not affect the others.
+      </p>
+
+      {(['Team table', 'Chart', 'Assistant panel'] as const).map(label => (
+        <CrashController key={label} Boundary={SectionErrorBoundary} label={label} />
+      ))}
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`SectionErrorBoundary` renders a compact inline fallback. Multiple independent sections on the same page can each fail in isolation.',
+      },
+    },
+  },
+};