xertica-ui 2.5.2 → 2.6.0

package/components/ui/checkbox/checkbox.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as CheckboxStories from './checkbox.stories';
-
-<Meta of={CheckboxStories} />
-
-<Title />
-<Subtitle>A binary toggle for selecting one or multiple options.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Explicit Binding** — When using with React Hook Form, bind `checked` and `onCheckedChange` explicitly instead of spreading `{...field}`.
-> - **Accessibility** — Always pair with a `Label` linked via `id` and `htmlFor`.
-> - **Choice Type** — Use checkboxes for independent choices. For mutually exclusive options, use `RadioGroup`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as CheckboxStories from './checkbox.stories';
+
+<Meta of={CheckboxStories} />
+
+<Title />
+<Subtitle>A binary toggle for selecting one or multiple options.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Explicit Binding** — When using with React Hook Form, bind `checked` and `onCheckedChange` explicitly instead of spreading `{...field}`.
+> - **Accessibility** — Always pair with a `Label` linked via `id` and `htmlFor`.
+> - **Choice Type** — Use checkboxes for independent choices. For mutually exclusive options, use `RadioGroup`.

package/components/ui/collapsible/collapsible.mdx

@@ -1,25 +1,25 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as CollapsibleStories from './collapsible.stories';
-
-<Meta of={CollapsibleStories} />
-
-<Title />
-<Subtitle>A single expandable/collapsible content section.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Standalone Element** — Use `Collapsible` for individual sections. For multiple related sections with managed auto-close behavior, use `Accordion`.
-> - **Trigger Pattern** — Always use `asChild` on the `CollapsibleTrigger` when wrapping a button or custom element.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as CollapsibleStories from './collapsible.stories';
+
+<Meta of={CollapsibleStories} />
+
+<Title />
+<Subtitle>A single expandable/collapsible content section.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Standalone Element** — Use `Collapsible` for individual sections. For multiple related sections with managed auto-close behavior, use `Accordion`.
+> - **Trigger Pattern** — Always use `asChild` on the `CollapsibleTrigger` when wrapping a button or custom element.

package/components/ui/command/command.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as CommandStories from './command.stories';
-
-<Meta of={CommandStories} />
-
-<Title />
-<Subtitle>A search-driven command palette for executing actions via keyboard.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Keyboard Trigger** — Always register the `⌘K` or `Ctrl+K` shortcut when using `CommandDialog`.
-> - **Empty State** — Include a `CommandEmpty` component to handle cases with no search results.
-> - **Modal Closing** — Ensure the palette closes after a successfull `onSelect` action by updating the `open` state.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as CommandStories from './command.stories';
+
+<Meta of={CommandStories} />
+
+<Title />
+<Subtitle>A search-driven command palette for executing actions via keyboard.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Keyboard Trigger** — Always register the `⌘K` or `Ctrl+K` shortcut when using `CommandDialog`.
+> - **Empty State** — Include a `CommandEmpty` component to handle cases with no search results.
+> - **Modal Closing** — Ensure the palette closes after a successfull `onSelect` action by updating the `open` state.

package/components/ui/context-menu/context-menu.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as ContextMenuStories from './context-menu.stories';
-
-<Meta of={ContextMenuStories} />
-
-<Title />
-<Subtitle>A right-click or long-press menu for contextual actions.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Supplement, Don't Replace** — Context menus are hidden by default; always provide a visible UI control (like a button or meatball menu) for primary actions.
-> - **Visual Alignment** — Use the `inset` prop on items without icons to maintain consistent text alignment with neighbors that have icons or complex triggers.
-> - **Semantic Color** — Use `className="text-destructive"` for menu items that perform irreversible actions like "Delete".
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as ContextMenuStories from './context-menu.stories';
+
+<Meta of={ContextMenuStories} />
+
+<Title />
+<Subtitle>A right-click or long-press menu for contextual actions.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Supplement, Don't Replace** — Context menus are hidden by default; always provide a visible UI control (like a button or meatball menu) for primary actions.
+> - **Visual Alignment** — Use the `inset` prop on items without icons to maintain consistent text alignment with neighbors that have icons or complex triggers.
+> - **Semantic Color** — Use `className="text-destructive"` for menu items that perform irreversible actions like "Delete".

package/components/ui/dialog/dialog.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as DialogStories from './dialog.stories';
-
-<Meta of={DialogStories} />
-
-<Title />
-<Subtitle>A modal overlay for critical confirmations and data entry.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Accessibility** — `DialogTitle` is required. `DialogTrigger` should always use `asChild` with a `Button`.
-> - **Modal Flow** — Use dialogs for supplementary tasks. For irreversible destructive actions, use `AlertDialog`.
-> - **Mobile** — For mobile-first interfaces, consider using `Drawer` instead of `Dialog`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as DialogStories from './dialog.stories';
+
+<Meta of={DialogStories} />
+
+<Title />
+<Subtitle>A modal overlay for critical confirmations and data entry.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Accessibility** — `DialogTitle` is required. `DialogTrigger` should always use `asChild` with a `Button`.
+> - **Modal Flow** — Use dialogs for supplementary tasks. For irreversible destructive actions, use `AlertDialog`.
+> - **Mobile** — For mobile-first interfaces, consider using `Drawer` instead of `Dialog`.

package/components/ui/drawer/drawer.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as DrawerStories from './drawer.stories';
-
-<Meta of={DrawerStories} />
-
-<Title />
-<Subtitle>A bottom-aligned panel optimized for mobile interactions.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Mobile First** — Drawers are best suited for mobile screens. For desktop side panels, use the `Sheet` component.
-> - **Accessibility** — Always include a `DrawerTitle` to ensure proper screen reader support.
-> - **Content Centering** — Wrap internal content in a centered container (e.g., `mx-auto w-full max-w-sm`) for better layout on wider screens.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as DrawerStories from './drawer.stories';
+
+<Meta of={DrawerStories} />
+
+<Title />
+<Subtitle>A bottom-aligned panel optimized for mobile interactions.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Mobile First** — Drawers are best suited for mobile screens. For desktop side panels, use the `Sheet` component.
+> - **Accessibility** — Always include a `DrawerTitle` to ensure proper screen reader support.
+> - **Content Centering** — Wrap internal content in a centered container (e.g., `mx-auto w-full max-w-sm`) for better layout on wider screens.

package/components/ui/dropdown-menu/dropdown-menu.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as DropdownMenuStories from './dropdown-menu.stories';
-
-<Meta of={DropdownMenuStories} />
-
-<Title />
-<Subtitle>A triggered contextual menu for grouped actions.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Trigger Pattern** — Always use `asChild` on `<DropdownMenuTrigger>` when wrapping a `<Button>`.
-> - **Destructive Items** — Danger actions must use `text-destructive` and be separated by a `<DropdownMenuSeparator>`.
-> - **Alignment** — Usually, table row actions use `align="end"` to keep the menu within the viewport.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as DropdownMenuStories from './dropdown-menu.stories';
+
+<Meta of={DropdownMenuStories} />
+
+<Title />
+<Subtitle>A triggered contextual menu for grouped actions.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Trigger Pattern** — Always use `asChild` on `<DropdownMenuTrigger>` when wrapping a `<Button>`.
+> - **Destructive Items** — Danger actions must use `text-destructive` and be separated by a `<DropdownMenuSeparator>`.
+> - **Alignment** — Usually, table row actions use `align="end"` to keep the menu within the viewport.

package/components/ui/empty/empty.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as EmptyStories from './empty.stories';
-
-<Meta of={EmptyStories} />
-
-<Title />
-<Subtitle>A composite zero-state container for no-data scenarios.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Composable Pattern** — Always use the sub-components (`EmptyIcon`, `EmptyTitle`, etc.) to build the empty state.
-> - **Icon Sizing** — Use `size-10` for standard and `size-8` for compact views.
-> - **Contextual CTA** — Use `EmptyAction` only when a corrective user action is possible.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as EmptyStories from './empty.stories';
+
+<Meta of={EmptyStories} />
+
+<Title />
+<Subtitle>A composite zero-state container for no-data scenarios.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Composable Pattern** — Always use the sub-components (`EmptyIcon`, `EmptyTitle`, etc.) to build the empty state.
+> - **Icon Sizing** — Use `size-10` for standard and `size-8` for compact views.
+> - **Contextual CTA** — Use `EmptyAction` only when a corrective user action is possible.

package/components/ui/file-upload/file-upload.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as FileUploadStories from './file-upload.stories';
-
-<Meta of={FileUploadStories} />
-
-<Title />
-<Subtitle>A drag-and-drop file uploader with type and size validation.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Validation** — Always use `accept` and `maxSize` to restrict file types and sizes as early as possible.
-> - **Form Integration** — Use the `onFilesChange` callback to manually update form states (e.g., using `field.onChange` in React Hook Form).
-> - **UX** — For the best experience, specify a clear maximum width for the dropzone container.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as FileUploadStories from './file-upload.stories';
+
+<Meta of={FileUploadStories} />
+
+<Title />
+<Subtitle>A drag-and-drop file uploader with type and size validation.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Validation** — Always use `accept` and `maxSize` to restrict file types and sizes as early as possible.
+> - **Form Integration** — Use the `onFilesChange` callback to manually update form states (e.g., using `field.onChange` in React Hook Form).
+> - **UX** — For the best experience, specify a clear maximum width for the dropzone container.

package/components/ui/form/form.mdx

@@ -1,20 +1,20 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as FormStories from './form.stories';
-
-<Meta of={FormStories} />
-
-<Title />
-<Subtitle>A powerful form system built on react-hook-form and Zod.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Schema-First** — Always define your form schema using `Zod` before implementing the UI components.
-> - **Unified Wrappers** — Use `FormItem`, `FormLabel`, and `FormControl` for every field to ensure automatic ARIA linking and consistent spacing.
-> - **Validation Messages** — `FormMessage` automatically picks up validation errors from the current form context — never render errors manually.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as FormStories from './form.stories';
+
+<Meta of={FormStories} />
+
+<Title />
+<Subtitle>A powerful form system built on react-hook-form and Zod.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Schema-First** — Always define your form schema using `Zod` before implementing the UI components.
+> - **Unified Wrappers** — Use `FormItem`, `FormLabel`, and `FormControl` for every field to ensure automatic ARIA linking and consistent spacing.
+> - **Validation Messages** — `FormMessage` automatically picks up validation errors from the current form context — never render errors manually.

package/components/ui/google-maps-loader/google-maps-loader.mdx

@@ -1,68 +1,68 @@
-import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
-
-<Meta title="System/GoogleMapsLoader" />
-
-<Title>GoogleMapsLoader</Title>
-<Subtitle>Async Google Maps API loader with deduplication and React context.</Subtitle>
-
----
-
-## Overview
-
-`GoogleMapsLoaderProvider` lazily loads the Google Maps JavaScript SDK once and shares the loading state across the component tree through React context. When you use `XerticaProvider` with a `googleMapsApiKey`, this provider is included automatically — you do not need to add it separately.
-
-```tsx
-// Automatically wired when using XerticaProvider:
-import { XerticaProvider } from 'xertica-ui/brand';
-
-<XerticaProvider googleMapsApiKey={import.meta.env.VITE_GOOGLE_MAPS_KEY}>
-  <App />
-</XerticaProvider>
-```
-
-For standalone usage without `XerticaProvider`:
-
-```tsx
-import { GoogleMapsLoaderProvider } from 'xertica-ui';
-
-<GoogleMapsLoaderProvider apiKey={import.meta.env.VITE_GOOGLE_MAPS_KEY}>
-  <YourMapComponent />
-</GoogleMapsLoaderProvider>
-```
-
----
-
-## Exports
-
-| Export | Type | Description |
-|---|---|---|
-| `GoogleMapsLoaderProvider` | Component | Context provider that loads the Maps SDK. |
-| `useGoogleMapsLoader` | Hook | Returns `{ isLoaded, loadError }` for the current load state. |
-| `reloadGoogleMaps` | Function | Imperatively retriggers the Maps SDK load (e.g., after an API key change). |
-
----
-
-## `useGoogleMapsLoader`
-
-```tsx
-import { useGoogleMapsLoader } from 'xertica-ui';
-
-function MyMap() {
-  const { isLoaded, loadError } = useGoogleMapsLoader();
-
-  if (loadError) return <p>Failed to load Google Maps.</p>;
-  if (!isLoaded) return <p>Loading map…</p>;
-
-  return <div id="map" className="h-64 w-full" />;
-}
-```
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **API Key** — Always pass the key via an environment variable (`import.meta.env.VITE_GOOGLE_MAPS_KEY`). Never hardcode it in source.
-> - **Single provider** — Mount `GoogleMapsLoaderProvider` once at the root (or rely on `XerticaProvider`). Multiple providers on the same page will cause duplicate script injection.
-> - **Guard rendering** — Always check `isLoaded` before instantiating `new google.maps.Map(...)` to avoid "google is not defined" errors.
-> - **`SimpleMap` shortcut** — For basic map display, prefer `<SimpleMap />` over wiring the loader manually.
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+
+<Meta title="System/GoogleMapsLoader" />
+
+<Title>GoogleMapsLoader</Title>
+<Subtitle>Async Google Maps API loader with deduplication and React context.</Subtitle>
+
+---
+
+## Overview
+
+`GoogleMapsLoaderProvider` lazily loads the Google Maps JavaScript SDK once and shares the loading state across the component tree through React context. When you use `XerticaProvider` with a `googleMapsApiKey`, this provider is included automatically — you do not need to add it separately.
+
+```tsx
+// Automatically wired when using XerticaProvider:
+import { XerticaProvider } from 'xertica-ui/brand';
+
+<XerticaProvider googleMapsApiKey={import.meta.env.VITE_GOOGLE_MAPS_KEY}>
+  <App />
+</XerticaProvider>
+```
+
+For standalone usage without `XerticaProvider`:
+
+```tsx
+import { GoogleMapsLoaderProvider } from 'xertica-ui';
+
+<GoogleMapsLoaderProvider apiKey={import.meta.env.VITE_GOOGLE_MAPS_KEY}>
+  <YourMapComponent />
+</GoogleMapsLoaderProvider>
+```
+
+---
+
+## Exports
+
+| Export | Type | Description |
+|---|---|---|
+| `GoogleMapsLoaderProvider` | Component | Context provider that loads the Maps SDK. |
+| `useGoogleMapsLoader` | Hook | Returns `{ isLoaded, loadError }` for the current load state. |
+| `reloadGoogleMaps` | Function | Imperatively retriggers the Maps SDK load (e.g., after an API key change). |
+
+---
+
+## `useGoogleMapsLoader`
+
+```tsx
+import { useGoogleMapsLoader } from 'xertica-ui';
+
+function MyMap() {
+  const { isLoaded, loadError } = useGoogleMapsLoader();
+
+  if (loadError) return <p>Failed to load Google Maps.</p>;
+  if (!isLoaded) return <p>Loading map…</p>;
+
+  return <div id="map" className="h-64 w-full" />;
+}
+```
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **API Key** — Always pass the key via an environment variable (`import.meta.env.VITE_GOOGLE_MAPS_KEY`). Never hardcode it in source.
+> - **Single provider** — Mount `GoogleMapsLoaderProvider` once at the root (or rely on `XerticaProvider`). Multiple providers on the same page will cause duplicate script injection.
+> - **Guard rendering** — Always check `isLoaded` before instantiating `new google.maps.Map(...)` to avoid "google is not defined" errors.
+> - **`SimpleMap` shortcut** — For basic map display, prefer `<SimpleMap />` over wiring the loader manually.