xertica-ui 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -7,6 +7,29 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.0.5] — 2026-05-12
+
+### Added
+
+- **`llms-compact.txt`** — novo arquivo de referência compacto para LLMs, sintetizando todos os componentes em formato reduzido ideal para contextos de tokens limitados.
+- **`docs/decision-tree.md`** — guia de árvore de decisão para agentes de IA selecionarem o componente correto com base nos requisitos da UI.
+- **`templates/CLAUDE.md`** — `CLAUDE.md` agora é scaffolded automaticamente em projetos criados via `npx xertica-ui@latest init`, fornecendo contexto arquitetural (FSD/FDA, subpath imports, tokens semânticos) para Claude Code e outros assistentes de IA.
+- **Storybook stories** — adicionadas stories interativas para Accordion, AlertDialog, Button, Checkbox, Dialog, Input, Switch, Tabs, HomePage e TemplatePage.
+- **`components/pages/home-page/home-page.mdx`** e **`template-page.mdx`** — novas entradas de documentação MDX para as page components.
+
+### Changed
+
+- **`guidelines/Guidelines.md`** — reescrita completa do guia de arquitetura FSD/FDA: maior detalhamento de responsabilidades por camada, convenções de import e fluxo de adição de novas rotas.
+- **`components.json`** — atualização completa do registro de componentes, cobrindo todos os 97 componentes com metadados de subpath, props e variantes.
+- **`llms.txt`** — seção de subpath imports e mapeamento de camadas FSD/FDA atualizados.
+- **`vite.config.ts`** — ajustes no build multi-entry para garantir correta emissão dos arquivos CJS/ESM.
+
+### Fixed
+
+- **`npx xertica-ui init` usa versão em cache** — documentado que o npx armazena pacotes em cache localmente sem TTL curto. Sempre use `npx xertica-ui@latest init` para garantir a versão mais recente. O `templates/CLAUDE.md` scaffolded no projeto gerado inclui essa orientação.
+
+---
+
 ## [2.0.3] — 2026-05-11
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 > **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.
 
-[![npm version](https://img.shields.io/badge/npm-2.0.3-blue)](https://www.npmjs.com/package/xertica-ui)
+[![npm version](https://img.shields.io/badge/npm-2.0.5-blue)](https://www.npmjs.com/package/xertica-ui)
 [![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
 
 ---
@@ -31,6 +31,8 @@ npm run dev
 
 The CLI scaffolds a complete Vite + React + TypeScript project with Portuguese UI localization and English AI-ready documentation.
 
+> **Note:** Always use `@latest` with npx. Without it, npx may execute a locally cached older version instead of fetching the latest from the registry.
+
 ---
 
 ## 📦 Installation as a Library

package/bin/cli.ts

@@ -18,7 +18,7 @@ const program = new Command();
 program
     .name('xertica-ui')
     .description('CLI to initialize Xertica UI projects')
-    .version('2.0.3');
+    .version('2.0.5');
 
 program
     .command('init')
@@ -83,6 +83,7 @@ program
                 'eslint.config.js',
                 '.env.example',
                 'guidelines',
+                'CLAUDE.md',
             ];
 
             for (const file of rootFilesToCopy) {

package/components/assistant/markdown-message/markdown-message.mdx

@@ -15,7 +15,7 @@ import * as MarkdownMessageStories from './markdown-message.stories';
 ## Usage
 
 ```tsx
-import { MarkdownMessage } from 'xertica-ui';
+import { MarkdownMessage } from 'xertica-ui/assistant';
 
 <MarkdownMessage content="**Hello!** Here is a `code` example." />
 ```

package/components/brand/language-selector/language-selector.mdx

@@ -15,7 +15,7 @@ import * as LanguageSelectorStories from './language-selector.stories';
 ## Usage
 
 ```tsx
-import { LanguageSelector } from 'xertica-ui';
+import { LanguageSelector } from 'xertica-ui/brand';
 
 <LanguageSelector />
 ```

package/components/brand/theme-toggle/theme-toggle.mdx

@@ -15,7 +15,7 @@ import * as ThemeToggleStories from './theme-toggle.stories';
 ## Usage
 
 ```tsx
-import { ThemeToggle } from 'xertica-ui';
+import { ThemeToggle } from 'xertica-ui/brand';
 
 <ThemeToggle />
 ```

package/components/brand/xertica-logo/xertica-logo.mdx

@@ -12,7 +12,7 @@ import { Meta, Title, Subtitle, Description } from '@storybook/addon-docs/blocks
 `XerticaLogo` renders the complete Xertica brand identity — the X symbol alongside the wordmark text. It adapts to different backgrounds through its `variant` prop and supports a direct `color` override for edge cases.
 
 ```tsx
-import { XerticaLogo } from 'xertica-ui';
+import { XerticaLogo } from 'xertica-ui/brand';
 
 <XerticaLogo className="h-8 w-auto" />
 ```

package/components/brand/xertica-provider/xertica-provider.mdx

@@ -14,7 +14,7 @@ The `XerticaProvider` is a lightweight root wrapper that orchestrates essential
 **It MUST be placed at the root of your application.**
 
 ```tsx
-import { XerticaProvider } from 'xertica-ui';
+import { XerticaProvider } from 'xertica-ui/brand';
 import 'xertica-ui/style.css'; // Don't forget the global styles
 
 function App() {

package/components/brand/xertica-xlogo/xertica-xlogo.mdx

@@ -12,7 +12,7 @@ import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
 `XerticaXLogo` renders only the X-symbol portion of the Xertica identity. It shares the same prop API as `XerticaLogo` and is the preferred choice wherever horizontal space is constrained.
 
 ```tsx
-import { XerticaXLogo } from 'xertica-ui';
+import { XerticaXLogo } from 'xertica-ui/brand';
 
 <XerticaXLogo className="h-8 w-8" />
 ```

package/components/index.ts

@@ -34,6 +34,12 @@ export type {
 // ============================================================================
 
 export { TemplatePage } from './pages/template-page';
+export { HomePage } from './pages/home-page';
+export { LoginPage } from './pages/login-page';
+export { HomeContent } from './pages/home-content';
+export { ForgotPasswordPage } from './pages/forgot-password-page';
+export { VerifyEmailPage } from './pages/verify-email-page';
+export { ResetPasswordPage } from './pages/reset-password-page';
 
 // UI Components - All available via /components/ui/index.ts
 export * from './ui';

package/components/layout/header/header.mdx

@@ -94,7 +94,7 @@ The `Header` ensures a navigation area is **never empty**:
 
 ### Developer Integration Guide
 ```tsx
-import { Header } from 'xertica-ui';
+import { Header } from 'xertica-ui/layout';
 import { Home, Settings, Users } from 'lucide-react';
 
 export function MyLayout({ children }) {

package/components/layout/sidebar/sidebar.mdx

@@ -76,7 +76,8 @@ The expansion state is automatically persisted in a cookie (`sidebar_state`), en
 The Sidebar should ideally be synchronized with the `useLayout()` hook to ensure the main application container adjusts its padding accordingly.
 
 ```tsx
-import { Sidebar, useLayout } from 'xertica-ui';
+import { Sidebar } from 'xertica-ui/layout';
+import { useLayout } from 'xertica-ui/hooks';
 
 const { sidebarExpanded, toggleSidebar, sidebarWidth } = useLayout();
 

package/components/media/floating-media-wrapper.mdx

@@ -17,8 +17,8 @@ import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
 Position and size are persisted to `localStorage` per `playerId`, so the user's floating window survives page navigation.
 
 ```tsx
-import { FloatingMediaWrapper } from 'xertica-ui';
-import { VideoPlayer } from 'xertica-ui';
+import { FloatingMediaWrapper } from 'xertica-ui/media';
+import { VideoPlayer } from 'xertica-ui/media';
 
 function MyPage() {
   const [isFloating, setIsFloating] = React.useState(false);

package/components/pages/forgot-password-page/ForgotPasswordPage.tsx

@@ -38,10 +38,8 @@ export function ForgotPasswordPage() {
     setIsLoading(false);
   };
 
-  const handleSocialLogin = (provider: string) => {
-    // Simulate social/SSO login
-    console.log(`Login with ${provider}`);
-    // Here real integration with each provider would be implemented
+  const handleSocialLogin = (_provider: string) => {
+    // Wire your SSO/social provider integration here
   };
 
   return (

package/components/pages/home-content/HomeContent.tsx

@@ -63,7 +63,7 @@ export function HomeContent({ user, onLogout, onSettings }: HomeContentProps) {
       style={{
         paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : SIDEBAR_COLLAPSED_WIDTH
       }}
-      className={`flex-1 flex flex-col overflow-hidden transition-all duration-300 bg-red-500`}
+      className="flex-1 flex flex-col overflow-hidden transition-all duration-300"
     >
       <Header
         showThemeToggle={true}

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

@@ -60,4 +60,4 @@ import { HomeContent } from 'xertica-ui';
 > - **Context requirement** — `HomeContent` calls `useLayout()` at the top level. It must always be a descendant of `XerticaProvider` (or a bare `LayoutProvider`).
 > - **Feature cards** — The card grid is currently hardcoded to the "Template CLI" feature. To add cards, fork the component and extend the `grid` section.
 > - **Breadcrumbs** — Breadcrumb labels are resolved via a local `labelTranslations` map and `getRouteByPath`. Ensure your route definitions include a `label` field for correct breadcrumb rendering.
-> - **Background color** — The outer container currently uses `bg-red-500` as a development placeholder. Override it with `className` or remove it before shipping.
+> - **Background color** — The outer container uses `bg-muted` from the design system tokens. Override with `className` if a different background is needed.

package/components/pages/home-page/HomePage.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { HomePage } from './HomePage';
+import { MemoryRouter } from 'react-router-dom';
+import { LayoutProvider } from '../../../contexts/LayoutContext';
+import React from 'react';
+
+const meta: Meta<typeof HomePage> = {
+  title: 'Pages/HomePage',
+  component: HomePage,
+  decorators: [
+    (Story) => (
+      <MemoryRouter initialEntries={['/home']}>
+        <LayoutProvider>
+          <Story />
+        </LayoutProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof HomePage>;
+
+export const Default: Story = {
+  args: {
+    user: { email: 'ariel@xertica.com' },
+    onLogout: () => {},
+  },
+};
+
+export const NoUser: Story = {
+  args: {
+    user: null,
+    onLogout: () => {},
+  },
+};

package/components/pages/home-page/HomePage.tsx

@@ -78,9 +78,8 @@ export function HomePage({ user, onLogout }: HomePageProps) {
         responseGenerator={gerarResposta}
         richSuggestions={richSuggestions}
         feedbackOptions={feedbackOptions}
-        onEvaluation={(messageId, type, reason) => {
-          console.log(`Evaluation received: ${type} on message ${messageId}. Reason: ${reason}`);
-          // Here you would implement logic to save to the backend
+        onEvaluation={() => {
+          // Wire your feedback persistence logic here
         }}
       />
     </div>

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

@@ -0,0 +1,56 @@
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+import * as HomePageStories from './HomePage.stories';
+
+<Meta of={HomePageStories} />
+
+<Title>HomePage</Title>
+<Subtitle>Full application shell — Sidebar, HomeContent, and XerticaAssistant composed together.</Subtitle>
+
+---
+
+## Overview
+
+`HomePage` is the root authenticated page. It assembles the three major layout pillars:
+
+- **Sidebar** — primary navigation, collapsible, synced via `LayoutContext`.
+- **HomeContent** — dashboard area with breadcrumb header and feature card grid.
+- **XerticaAssistant** — floating AI assistant panel, toggled via `LayoutContext`.
+
+All three components communicate through `LayoutContext` — sidebar width, expanded state, and assistant visibility are synchronized automatically.
+
+**Requires:** `LayoutContext` (provided by `XerticaProvider`), React Router v6.
+
+---
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `user` | `{ email: string } \| null` | Yes | Currently authenticated user. Passed to Sidebar and HomeContent for display. |
+| `onLogout` | `() => void` | Yes | Called when the user triggers logout from the Sidebar or Header. |
+
+---
+
+## Composition
+
+```tsx
+import { HomePage } from 'xertica-ui';
+
+// Inside your router:
+<Route
+  path="/home"
+  element={<HomePage user={currentUser} onLogout={handleLogout} />}
+/>
+```
+
+`XerticaProvider` must wrap the app root — it initializes `LayoutContext` which all three pillars depend on.
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Top-level only** — `HomePage` is a full-screen layout component. Do not nest it inside other layouts.
+> - **No logic here** — Keep business logic in `HomeContent` or lower-level components. `HomePage` is a composition shell only.
+> - **LayoutContext required** — All child components (`Sidebar`, `HomeContent`, `XerticaAssistant`) call `useLayout()`. This component must always be a descendant of `XerticaProvider`.
+> - **Extend via HomeContent** — To add dashboard sections, edit `HomeContent` — not `HomePage`.

package/components/pages/login-page/LoginPage.tsx

@@ -56,11 +56,8 @@ export function LoginPage({ onLogin }: LoginPageProps) {
     setIsLoading(false);
   };
 
-  const handleSocialLogin = (provider: string) => {
-    // Simulate social/SSO login
-    console.log(`Login with ${provider}`);
-    // Here real integration with each provider would be implemented
-    // For now, simulate a successful login
+  const handleSocialLogin = (_provider: string) => {
+    // Wire your SSO/social provider integration here
     onLogin('social@user.com', 'social-auth');
   };
 

package/components/pages/reset-password-page/reset-password-page.mdx

@@ -36,11 +36,15 @@ import { ResetPasswordPage } from 'xertica-ui';
 
 ## Password Strength Levels
 
+The strength meter is based purely on length:
+
 | Level | Criteria |
 |---|---|
 | `weak` | Fewer than 6 characters |
-| `medium` | 6+ characters with mixed casing or numbers |
-| `strong` | 8+ characters with uppercase, lowercase, numbers, and symbols |
+| `medium` | 6–9 characters |
+| `strong` | 10 or more characters |
+
+The meter is visual-only. Enforce your own policy server-side.
 
 ---
 

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

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { TemplatePage } from './TemplatePage';
+import { MemoryRouter } from 'react-router-dom';
+import { LayoutProvider } from '../../../contexts/LayoutContext';
+import React from 'react';
+
+const meta: Meta<typeof TemplatePage> = {
+  title: 'Pages/TemplatePage',
+  component: TemplatePage,
+  decorators: [
+    (Story) => (
+      <MemoryRouter initialEntries={['/template']}>
+        <LayoutProvider>
+          <Story />
+        </LayoutProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TemplatePage>;
+
+export const Default: Story = {
+  args: {
+    user: { email: 'ariel@xertica.com' },
+    onLogout: () => {},
+  },
+};
+
+export const NoUser: Story = {
+  args: {
+    user: null,
+    onLogout: () => {},
+  },
+};

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

@@ -57,7 +57,9 @@ export function TemplatePage({ user, onLogout }: TemplatePageProps) {
       <XerticaAssistant
         isExpanded={assistenteExpanded}
         onToggle={toggleAssistente}
-        onEvaluation={(id, type, reason) => console.log('Feedback:', id, type, reason)}
+        onEvaluation={() => {
+          // Wire your feedback persistence logic here
+        }}
       />
     </div>
   );

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

@@ -0,0 +1,54 @@
+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 component kitchen-sink — the canonical layout reference for Xertica UI.</Subtitle>
+
+---
+
+## Overview
+
+`TemplatePage` is the reference implementation of the full application layout. It assembles:
+
+- **Sidebar** — primary navigation, synchronized via `LayoutContext`.
+- **TemplateContent** — kitchen-sink showcase of all Xertica UI components (forms, tables, charts, dialogs, etc.).
+- **XerticaAssistant** — floating AI assistant panel.
+
+Use this page as the canonical reference when building new authenticated layouts. It demonstrates correct usage of `useLayout()`, sidebar synchronization, and assistant integration.
+
+**Requires:** `LayoutContext` (provided by `XerticaProvider`), React Router v6.
+
+---
+
+## 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';
+
+// Inside your router:
+<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. Copy its structure when creating new pages.
+> - **Top-level only** — This is a full-screen layout component. Do not nest it inside other layouts.
+> - **Extend via TemplateContent** — To change the showcased components, edit `TemplateContent`. `TemplatePage` itself is a composition shell only.
+> - **LayoutContext required** — All child components call `useLayout()`. Always ensure `XerticaProvider` wraps the app root.

package/components/pages/verify-email-page/VerifyEmailPage.tsx

@@ -40,10 +40,8 @@ export function VerifyEmailPage() {
     setTimeout(() => setResendSuccess(false), 3000);
   };
 
-  const handleSocialLogin = (provider: string) => {
-    // Simulate social/SSO login
-    console.log(`Login with ${provider}`);
-    // Here real integration with each provider would be implemented
+  const handleSocialLogin = (_provider: string) => {
+    // Wire your SSO/social provider integration here
   };
 
   return (

package/components/ui/accordion/accordion.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from 'storybook/test';
 import {
   Accordion,
   AccordionContent,
@@ -73,4 +74,29 @@ export const Multiple: Story = {
       </AccordionItem>
     </Accordion>
   ),
-};
+};
+
+export const ExpandCollapse: Story = {
+  args: { type: 'single', collapsible: true },
+  render: (args) => (
+    <Accordion {...args} className="w-full max-w-[500px]">
+      <AccordionItem value="item-1">
+        <AccordionTrigger>Is it accessible?</AccordionTrigger>
+        <AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2">
+        <AccordionTrigger>Is it animated?</AccordionTrigger>
+        <AccordionContent>Yes. It is animated by default.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const triggers = canvas.getAllByRole('button');
+    await expect(triggers[0]).toHaveAttribute('aria-expanded', 'false');
+    await userEvent.click(triggers[0]);
+    await expect(triggers[0]).toHaveAttribute('aria-expanded', 'true');
+    await userEvent.click(triggers[0]);
+    await expect(triggers[0]).toHaveAttribute('aria-expanded', 'false');
+  },
+};

package/components/ui/alert-dialog/alert-dialog.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from 'storybook/test';
 import {
   AlertDialog,
   AlertDialogAction,
@@ -51,3 +52,32 @@ export const Default: Story = {
     </AlertDialog>
   ),
 };
+
+export const ConfirmAction: Story = {
+  render: () => (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="destructive">Delete</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+          <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction>Delete</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Only test the trigger — AlertDialog content renders in a portal outside canvasElement
+    const trigger = canvas.getByRole('button', { name: 'Delete' });
+    await expect(trigger).toBeInTheDocument();
+    await expect(trigger).not.toBeDisabled();
+    await userEvent.click(trigger);
+    await expect(trigger).toBeInTheDocument();
+  },
+};

package/components/ui/button/button.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from 'storybook/test';
 import { Button } from './button';
 import { Plus, Trash2, Settings, ArrowRight } from 'lucide-react';
 import React from 'react';
@@ -135,3 +136,25 @@ export const Loading: Story = {
     </Button>
   ),
 };
+
+export const Clickable: Story = {
+  args: { children: 'Click me' },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole('button', { name: 'Click me' });
+    await expect(button).toBeInTheDocument();
+    await expect(button).not.toBeDisabled();
+    await userEvent.click(button);
+    await expect(button).toBeInTheDocument();
+  },
+};
+
+export const DisabledState: Story = {
+  args: { children: 'Disabled', disabled: true },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole('button', { name: 'Disabled' });
+    await expect(button).toBeDisabled();
+    await expect(button).toHaveAttribute('disabled');
+  },
+};

package/components/ui/checkbox/checkbox.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from 'storybook/test';
 import { Checkbox } from './checkbox';
 import { Label } from '../label';
 import React from 'react';
@@ -80,4 +81,22 @@ export const Sizes: Story = {
       </div>
     </div>
   ),
-};
+};
+
+export const Toggle: Story = {
+  render: () => (
+    <div className="flex items-center space-x-2">
+      <Checkbox id="play-check" />
+      <Label htmlFor="play-check">Accept terms</Label>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const checkbox = canvas.getByRole('checkbox');
+    await expect(checkbox).not.toBeChecked();
+    await userEvent.click(checkbox);
+    await expect(checkbox).toBeChecked();
+    await userEvent.click(checkbox);
+    await expect(checkbox).not.toBeChecked();
+  },
+};

package/components/ui/dialog/dialog.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from 'storybook/test';
 import {
   Dialog,
   DialogBody,
@@ -141,3 +142,32 @@ export const WithScrollableBody: Story = {
     </Dialog>
   ),
 };
+
+export const OpenClose: Story = {
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline">Open Dialog</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Confirm action</DialogTitle>
+          <DialogDescription>Are you sure you want to proceed?</DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <Button type="submit">Confirm</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Only test the trigger — Dialog content renders in a portal outside canvasElement
+    const trigger = canvas.getByRole('button', { name: 'Open Dialog' });
+    await expect(trigger).toBeInTheDocument();
+    await expect(trigger).not.toBeDisabled();
+    await userEvent.click(trigger);
+    // Verify trigger received the click (dialog state managed by Radix portal)
+    await expect(trigger).toBeInTheDocument();
+  },
+};