xertica-ui 2.5.2 → 2.6.0

package/components/ui/hover-card/hover-card.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as HoverCardStories from './hover-card.stories';
-
-<Meta of={HoverCardStories} />
-
-<Title />
-<Subtitle>A non-interactive floating panel for content previews.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Non-Interactive** — Use `HoverCard` only for read-only content previews. For interactive elements that require clicks inside the panel, use `Popover`.
-> - **Width Sizing** — Apply horizontal width constraints (e.g., `w-80`) to the `HoverCardContent` to ensure enough space for rich text or layouts.
-> - **Trigger Placement** — Use `asChild` on the `HoverCardTrigger` when wrapping a button or any styled primitive.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as HoverCardStories from './hover-card.stories';
+
+<Meta of={HoverCardStories} />
+
+<Title />
+<Subtitle>A non-interactive floating panel for content previews.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Non-Interactive** — Use `HoverCard` only for read-only content previews. For interactive elements that require clicks inside the panel, use `Popover`.
+> - **Width Sizing** — Apply horizontal width constraints (e.g., `w-80`) to the `HoverCardContent` to ensure enough space for rich text or layouts.
+> - **Trigger Placement** — Use `asChild` on the `HoverCardTrigger` when wrapping a button or any styled primitive.

package/components/ui/input/input.mdx

@@ -1,29 +1,29 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as InputStories from './input.stories';
-
-<Meta of={InputStories} />
-
-<Title />
-<Subtitle>Standard text field for single-line data entry.</Subtitle>
-
-<Description />
-
-<Primary />
-
-## Controls
-<Controls />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Relative Icon Pattern** — Search icons must be inside the input container using `absolute left-2.5` and `pl-9` on the input.
-> - **Labels** — Never skip labels for inputs unless they are redundant (like in a search-only header).
-> - **React Hook Form** — Always spread `{...field}` when using within a form controller.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as InputStories from './input.stories';
+
+<Meta of={InputStories} />
+
+<Title />
+<Subtitle>Standard text field for single-line data entry.</Subtitle>
+
+<Description />
+
+<Primary />
+
+## Controls
+<Controls />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Relative Icon Pattern** — Search icons must be inside the input container using `absolute left-2.5` and `pl-9` on the input.
+> - **Labels** — Never skip labels for inputs unless they are redundant (like in a search-only header).
+> - **React Hook Form** — Always spread `{...field}` when using within a form controller.

package/components/ui/input-otp/input-otp.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as InputOTPStories from './input-otp.stories';
-
-<Meta of={InputOTPStories} />
-
-<Title />
-<Subtitle>A specialized input for one-time passwords and verification codes.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Max Length Sync** — Ensure the `maxLength` prop on `InputOTP` matches the exact number of `InputOTPSlot` children.
-> - **Zero-Indexed Slots** — Each `InputOTPSlot` must have a unique `index` starting from 0.
-> - **Input Masking** — For numeric-only codes, add `pattern="[0-9]*"` to the `InputOTP` to optimize the mobile keyboard display.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as InputOTPStories from './input-otp.stories';
+
+<Meta of={InputOTPStories} />
+
+<Title />
+<Subtitle>A specialized input for one-time passwords and verification codes.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Max Length Sync** — Ensure the `maxLength` prop on `InputOTP` matches the exact number of `InputOTPSlot` children.
+> - **Zero-Indexed Slots** — Each `InputOTPSlot` must have a unique `index` starting from 0.
+> - **Input Masking** — For numeric-only codes, add `pattern="[0-9]*"` to the `InputOTP` to optimize the mobile keyboard display.

package/components/ui/label/label.mdx

@@ -1,25 +1,25 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as LabelStories from './label.stories';
-
-<Meta of={LabelStories} />
-
-<Title />
-<Subtitle>An accessible label component for form inputs.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Accessibility Link** — Always provide a valid `htmlFor` prop that matches the `id` of the associated input element.
-> - **Mandatory** — Never omit labels for form inputs; they are required for both UX and accessibility.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as LabelStories from './label.stories';
+
+<Meta of={LabelStories} />
+
+<Title />
+<Subtitle>An accessible label component for form inputs.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Accessibility Link** — Always provide a valid `htmlFor` prop that matches the `id` of the associated input element.
+> - **Mandatory** — Never omit labels for form inputs; they are required for both UX and accessibility.

package/components/ui/map/map.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as MapStories from './map.stories';
-
-<Meta of={MapStories} />
-
-<Title />
-<Subtitle>A powerful Google Maps integration with support for advanced markers and custom layers.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **API Configuration** — Ensure the `apiKey` is provided either via props or the `XerticaProvider` global context.
-> - **Explicit Dimensions** — Always set a `height` prop or use a CSS class with a defined height; maps will not render in containers with 0 height.
-> - **Coordinate Safety** — Use the `{ lat, lng }` format for all coordinates to ensure compatibility with the underlying Google Maps engine.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as MapStories from './map.stories';
+
+<Meta of={MapStories} />
+
+<Title />
+<Subtitle>A powerful Google Maps integration with support for advanced markers and custom layers.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **API Configuration** — Ensure the `apiKey` is provided either via props or the `XerticaProvider` global context.
+> - **Explicit Dimensions** — Always set a `height` prop or use a CSS class with a defined height; maps will not render in containers with 0 height.
+> - **Coordinate Safety** — Use the `{ lat, lng }` format for all coordinates to ensure compatibility with the underlying Google Maps engine.

package/components/ui/map/map.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { createRoot } from 'react-dom/client';
+import DOMPurify from 'dompurify';
 import { cn } from '../../shared/utils';
 import { useGoogleMapsLoader } from '../google-maps-loader';
 import { useMapLayers, MapLayersConfig } from '../map-layers';
@@ -405,7 +406,11 @@ const MapContent = React.forwardRef<HTMLDivElement, MapProps & { apiKey: string
                   <div className="flex items-center justify-center rotate-45">
                     {markerData.iconSvg ? (
                       <div
-                        dangerouslySetInnerHTML={{ __html: markerData.iconSvg }}
+                        dangerouslySetInnerHTML={{
+                          __html: DOMPurify.sanitize(markerData.iconSvg, {
+                            USE_PROFILES: { svg: true, svgFilters: true },
+                          }),
+                        }}
                         style={{ color: iconColor, width: 16, height: 16, fill: 'currentColor' }}
                       />
                     ) : (

package/components/ui/menubar/menubar.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as MenubarStories from './menubar.stories';
-
-<Meta of={MenubarStories} />
-
-<Title />
-<Subtitle>A desktop-style horizontal menu bar with multiple persistent dropdowns.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Power User Focus** — Menubar is intended for technical tools and editors. For standard dashboards, prefer a `Sidebar` or `NavigationMenu`.
-> - **Shortcuts** — Use `MenubarShortcut` to display keyboard shortcuts, ensuring they are right-aligned within the item.
-> - **Visual Alignment** — Use the `inset` prop for items that do not have leading icons to keep text aligned with neighbors that do.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as MenubarStories from './menubar.stories';
+
+<Meta of={MenubarStories} />
+
+<Title />
+<Subtitle>A desktop-style horizontal menu bar with multiple persistent dropdowns.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Power User Focus** — Menubar is intended for technical tools and editors. For standard dashboards, prefer a `Sidebar` or `NavigationMenu`.
+> - **Shortcuts** — Use `MenubarShortcut` to display keyboard shortcuts, ensuring they are right-aligned within the item.
+> - **Visual Alignment** — Use the `inset` prop for items that do not have leading icons to keep text aligned with neighbors that do.

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

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as NavigationMenuStories from './navigation-menu.stories';
-
-<Meta of={NavigationMenuStories} />
-
-<Title />
-<Subtitle>A horizontal navigation bar with rich dropdown menus.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Secondary Navigation** — `NavigationMenu` is best used for horizontal header links or marketing site navigation. For the primary dashboard left-rail, use the `Sidebar`.
-> - **Portal Rendering** — Menus are rendered in a portal. Ensure `XerticaProvider` is present at the root to handle theme and layout consistency.
-> - **Link Pattern** — Wrap custom links in `NavigationMenuLink` to inherit proper hover and active states.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as NavigationMenuStories from './navigation-menu.stories';
+
+<Meta of={NavigationMenuStories} />
+
+<Title />
+<Subtitle>A horizontal navigation bar with rich dropdown menus.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Secondary Navigation** — `NavigationMenu` is best used for horizontal header links or marketing site navigation. For the primary dashboard left-rail, use the `Sidebar`.
+> - **Portal Rendering** — Menus are rendered in a portal. Ensure `XerticaProvider` is present at the root to handle theme and layout consistency.
+> - **Link Pattern** — Wrap custom links in `NavigationMenuLink` to inherit proper hover and active states.

package/components/ui/notification-badge/notification-badge.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as NotificationBadgeStories from './notification-badge.stories';
-
-<Meta of={NotificationBadgeStories} />
-
-<Title />
-<Subtitle>A compact overlay indicator for counts and attention cues.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Positioning** — Always use `relative` on the trigger parent and `absolute` with negative offsets (e.g., `-top-1 -right-1`) on the badge for proper alignment.
-> - **Zero Handling** — When the count is 0, avoid rendering the component entirely to keep the UI clean.
-> - **Max Display** — Large numbers are automatically truncated with a `+` suffix based on the `max` prop (defaults to 99).
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as NotificationBadgeStories from './notification-badge.stories';
+
+<Meta of={NotificationBadgeStories} />
+
+<Title />
+<Subtitle>A compact overlay indicator for counts and attention cues.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Positioning** — Always use `relative` on the trigger parent and `absolute` with negative offsets (e.g., `-top-1 -right-1`) on the badge for proper alignment.
+> - **Zero Handling** — When the count is 0, avoid rendering the component entirely to keep the UI clean.
+> - **Max Display** — Large numbers are automatically truncated with a `+` suffix based on the `max` prop (defaults to 99).

package/components/ui/page-header/page-header.mdx

@@ -1,44 +1,44 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as PageHeaderStories from './page-header.stories';
-
-<Meta of={PageHeaderStories} />
-
-<Title />
-<Subtitle>Standard header component for page content and sections.</Subtitle>
-
-The `PageHeader` is used at the top of the content area to provide context (title and subtitle), back navigation, and primary page actions. It helps visually separate the global application header (Top Bar) from context-specific page actions.
-
-<Primary />
-
-## Properties
-
-<Controls />
-
----
-
-## Usage Patterns
-
-### With Back Button
-Essential for sub-views, edit lists, or sequential flows.
-
-<Canvas of={PageHeaderStories.WithBackButton} />
-
-### With Actions
-Allows for adding action buttons (Create, Save, Export) to the right side in an organized manner.
-
-<Canvas of={PageHeaderStories.WithActions} />
-
-### Isolated Typography
-Auxiliary components to build custom headers while maintaining visual style.
-
-<Canvas of={PageHeaderStories.Typography} />
-
----
-
-## AI Integration Guide
-
-> [!IMPORTANT]
-> - **Mandatory Standard** — The `PageHeader` is the **required standard** for all pages in the Xertica UI library. Never use raw `h2` or `div` for page titles.
-> - **H1 Hierarchy** — The `PageHeader` renders an `h1`. Ensure there is only ONE per page to maintain proper SEO structure.
-> - **Navigation** — Use `backHref` for direct links or `onBack` to trigger programmatic events when clicking the back button.
-> - **Differentiation** — Never confuse the `PageHeader` with the global `Header`. The `Header` is the global top bar with Breadcrumbs and Profile; the `PageHeader` is the internal title of your content.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as PageHeaderStories from './page-header.stories';
+
+<Meta of={PageHeaderStories} />
+
+<Title />
+<Subtitle>Standard header component for page content and sections.</Subtitle>
+
+The `PageHeader` is used at the top of the content area to provide context (title and subtitle), back navigation, and primary page actions. It helps visually separate the global application header (Top Bar) from context-specific page actions.
+
+<Primary />
+
+## Properties
+
+<Controls />
+
+---
+
+## Usage Patterns
+
+### With Back Button
+Essential for sub-views, edit lists, or sequential flows.
+
+<Canvas of={PageHeaderStories.WithBackButton} />
+
+### With Actions
+Allows for adding action buttons (Create, Save, Export) to the right side in an organized manner.
+
+<Canvas of={PageHeaderStories.WithActions} />
+
+### Isolated Typography
+Auxiliary components to build custom headers while maintaining visual style.
+
+<Canvas of={PageHeaderStories.Typography} />
+
+---
+
+## AI Integration Guide
+
+> [!IMPORTANT]
+> - **Mandatory Standard** — The `PageHeader` is the **required standard** for all pages in the Xertica UI library. Never use raw `h2` or `div` for page titles.
+> - **H1 Hierarchy** — The `PageHeader` renders an `h1`. Ensure there is only ONE per page to maintain proper SEO structure.
+> - **Navigation** — Use `backHref` for direct links or `onBack` to trigger programmatic events when clicking the back button.
+> - **Differentiation** — Never confuse the `PageHeader` with the global `Header`. The `Header` is the global top bar with Breadcrumbs and Profile; the `PageHeader` is the internal title of your content.

package/components/ui/pagination/pagination.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as PaginationStories from './pagination.stories';
-
-<Meta of={PaginationStories} />
-
-<Title />
-<Subtitle>Navigate through large datasets with ease.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Placement** — Always place pagination controls directly below the data table or grid they control, preferably within the same card container.
-> - **Active State** — Clearly mark the current page with the `isActive` prop.
-> - **Interaction Mode** — Use `onClick` for client-side state management and `href` for standard URL-based navigation.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as PaginationStories from './pagination.stories';
+
+<Meta of={PaginationStories} />
+
+<Title />
+<Subtitle>Navigate through large datasets with ease.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Placement** — Always place pagination controls directly below the data table or grid they control, preferably within the same card container.
+> - **Active State** — Clearly mark the current page with the `isActive` prop.
+> - **Interaction Mode** — Use `onClick` for client-side state management and `href` for standard URL-based navigation.

package/components/ui/popover/popover.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as PopoverStories from './popover.stories';
-
-<Meta of={PopoverStories} />
-
-<Title />
-<Subtitle>A floating panel anchored to a trigger for interactive content.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Interactive Content** — Unlike tooltips, popovers are designed for interactive content (forms, calendars).
-> - **Anatomy** — Use `PopoverTrigger asChild` with a `Button` for proper accessibility and behavior.
-> - **Lazy Rendering** — Popover content is only rendered when opened.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as PopoverStories from './popover.stories';
+
+<Meta of={PopoverStories} />
+
+<Title />
+<Subtitle>A floating panel anchored to a trigger for interactive content.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Interactive Content** — Unlike tooltips, popovers are designed for interactive content (forms, calendars).
+> - **Anatomy** — Use `PopoverTrigger asChild` with a `Button` for proper accessibility and behavior.
+> - **Lazy Rendering** — Popover content is only rendered when opened.