@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/ui/.image-gallery-modal.md

@@ -1,52 +1,59 @@
-<!-- source-hash: 341cf101c715d69c78742d89d5203380 -->
-A reusable full-screen image gallery modal component with keyboard navigation, thumbnail controls, and error handling for unsupported image formats like HEIC.
+<!-- source-hash: 7ceb686fa07cb2b79511a1e43f5bce1a -->
+A full-screen image gallery modal component with keyboard navigation, prev/next controls, and an image counter. Extracted as a reusable component from the TMCG event detail page.
 
 ## Key Components
 
-- **ImageGalleryModal**: Main component that renders a full-screen modal with image navigation
-- **Navigation Controls**: Previous/next buttons with chevron icons (only shown when multiple images exist)
-- **Keyboard Support**: Arrow keys for navigation, Escape to close
-- **Image Counter**: Shows current position in gallery (e.g., "3 / 10")
-- **Error Handling**: Graceful fallback for unsupported formats with download option
+### `ImageGalleryModal`
+The primary export — a React client component wrapping the base `Modal` with gallery-specific behavior.
+
+**Props (`ImageGalleryModalProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `images` | `string[]` | Array of image URLs to display |
+| `isOpen` | `boolean` | Controls modal visibility |
+| `onClose` | `() => void` | Callback fired on close or `Escape` key |
+| `initialIndex` | `number` | Starting image index (default: `0`) |
+
+**Features:**
+- **Keyboard navigation** — `ArrowLeft`, `ArrowRight` to navigate; `Escape` to close
+- **Prev/Next buttons** — conditionally rendered based on current index boundaries
+- **Image counter** — shown when gallery has more than one image (e.g. `2 / 5`)
+- **Error handling** — gracefully handles unsupported formats (HEIC) with a download fallback
+- **Index reset** — resets to `initialIndex` each time the modal opens
 
 ## Usage Example
 
 ```typescript
 import { ImageGalleryModal } from './image-gallery-modal';
 
-function EventPhotos() {
-  const [isGalleryOpen, setIsGalleryOpen] = useState(false);
-  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
-  
-  const images = [
-    '/photos/event1.jpg',
-    '/photos/event2.png',
-    '/photos/event3.heic'
-  ];
-
-  const openGallery = (index: number) => {
-    setSelectedImageIndex(index);
-    setIsGalleryOpen(true);
-  };
+const screenshots = [
+  'https://cdn.example.com/img1.jpg',
+  'https://cdn.example.com/img2.jpg',
+  'https://cdn.example.com/img3.heic',
+];
+
+export function EventDetail() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [startIndex, setStartIndex] = useState(0);
 
   return (
-    <div>
-      {images.map((image, index) => (
-        <img 
-          key={index}
-          src={image} 
-          onClick={() => openGallery(index)}
-          className="cursor-pointer"
+    <>
+      {screenshots.map((src, i) => (
+        <img
+          key={src}
+          src={src}
+          onClick={() => { setStartIndex(i); setIsOpen(true); }}
         />
       ))}
-      
+
       <ImageGalleryModal
-        images={images}
-        isOpen={isGalleryOpen}
-        onClose={() => setIsGalleryOpen(false)}
-        initialIndex={selectedImageIndex}
+        images={screenshots}
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        initialIndex={startIndex}
       />
-    </div>
+    </>
   );
 }
 ```

package/src/components/ui/.image-uploader.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 7a3018246d0e272d26eee450458f6d52 -->
+A client-side React component that renders a drag-and-drop / click-to-upload image input with preview, replace, and remove functionality. Wraps a hidden `<input type="file">` with validation, loading states, and accessible keyboard interaction.
+
+## Key Components
+
+- **`ImageUploader`** — Main export. Renders the dropzone or image preview depending on whether `value` is set.
+- **`ActionIconButton`** — Internal button used for the "Replace" and "Remove" overlay actions on the image preview.
+- **`formatSize(bytes)`** — Utility that formats a byte count as a human-readable `KB`/`MB` string.
+- **`matchesAccept(file, accept)`** — Validates a `File` against an `accept` string (MIME types and extensions).
+
+## Key Props (`ImageUploaderProps`)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | Current image URL; triggers preview state when set |
+| `onChange` | `(file: File) => void` | Called with the selected/dropped `File` after validation |
+| `onRemove` | `() => void` | Shows trash icon when provided; called on click |
+| `accept` | `string` | Accepted MIME types/extensions. Default: `"image/*"` |
+| `maxSize` | `number` | Max file size in bytes. Default: 25 MB |
+| `aspectRatio` | `string` | CSS aspect-ratio override (e.g. `"16 / 9"`) |
+| `loading` | `boolean` | Shows spinner overlay and disables interaction |
+| `error` | `string` | External error message (internal validation errors take precedence) |
+
+## Usage Example
+
+```typescript
+import { ImageUploader } from "@/components/ui/image-uploader"
+import { useState } from "react"
+
+export function CoverImageField() {
+  const [imageUrl, setImageUrl] = useState<string | undefined>()
+
+  const handleChange = async (file: File) => {
+    const url = await uploadToStorage(file) // your upload logic
+    setImageUrl(url)
+  }
+
+  return (
+    <ImageUploader
+      value={imageUrl}
+      onChange={handleChange}
+      onRemove={() => setImageUrl(undefined)}
+      aspectRatio="16 / 9"
+      maxSize={5 * 1024 * 1024} // 5 MB
+      fieldLabel="Cover Image"
+      label="Upload a cover photo"
+      description="Click or drag and drop"
+    />
+  )
+}
+```
+
+> **Note:** `onChange` receives the raw `File` — the consumer is responsible for uploading it to a server or object storage and updating `value` with the resulting URL.

package/src/components/ui/.index.md

@@ -1,46 +1,52 @@
-<!-- source-hash: 1176d6ee91af39908dd46ef426fa860c -->
-Centralized component export index file providing a unified import interface for the Flamingo UI component library. This file serves as the main entry point for accessing all UI, layout, navigation, and feedback components throughout the application.
+<!-- source-hash: 69fabf50cc24470b1828f706f8765a69 -->
+Central barrel export file for the UI kit library, re-exporting all client-side UI components organized by category (form inputs, layout, navigation, feedback, tables, chat, and more).
 
 ## Key Components
 
-### UI Components
-- **Form Controls**: `Button`, `Input`, `Checkbox`, `Select`, `Switch`, `RadioGroup`, `DatePicker`
-- **Content Display**: `Card`, `Badge`, `InfoCard`, `StatusBadge`, `ProgressBar`
-- **Data Entry**: `Autocomplete`, `TagsInput`, `Textarea`, `AllowedDomainsInput`
-- **Loading States**: `ContentLoader`, `PageLoader`, `Skeleton`, `CircularProgress`
-
-### Layout Components
-- **Modals & Dialogs**: `Dialog`, `AlertDialog`, `Modal`, `Sheet`
-- **Structure**: `Tabs`, `Separator`, `AspectRatio`, `ImageGalleryModal`
-
-### Navigation Components
-- **Menus**: `DropdownMenu`, `NavigationMenu`, `Menubar`, `ActionsMenu`
-- **Organization**: `Accordion`, `Breadcrumb`, `TabNavigation`
-
-### Specialized Components
-- **Tables**: `Table`, `TableRow`, `TableCell`, `CursorPagination`
-- **Business Logic**: `DeviceCard`, `OrganizationCard`, `ServiceCard`, `BrandAssociationGrid`
-- **Icons**: Custom icon exports from Lucide React
+Organized into the following categories:
+
+| Category | Notable Exports |
+|---|---|
+| **Form / Input** | `Button`, `Input`, `Select`, `Checkbox`, `DatePicker`, `TagsInput`, `RadioGroup`, `Switch` |
+| **Layout** | `Dialog`, `Modal`, `ModalV2`, `Sheet`, `Drawer`, `Tabs`, `Separator` |
+| **Navigation** | `Accordion`, `Breadcrumb`, `DropdownMenu`, `NavigationMenu`, `TabNavigation` |
+| **Feedback** | `Alert`, `Badge`, `Progress`, `StatusBadge`, `Toaster`, `StatusIndicator` |
+| **Table** | `Table`, `TableRow`, `TableCell`, `TableHeader`, `TableEmptyState`, `TableTimestampCell` |
+| **Query Report** | `QueryReportTable`, `deriveColumns`, `exportToCSV` |
+| **DataTable** | Headless TanStack Table-based replacement for legacy `Table` |
+| **Pagination** | `CursorPagination`, `CursorPaginationSimple` |
+| **Search / Filter** | `SearchInput`, `FilterList`, `TagSearchInput`, `TagKeyValueFilter` |
+| **Chat / Layout** | `chat`, `ListPageLayout`, `PageContainer`, `PageLayout` |
+| **Ticket** | `TicketStatusTag`, `AssigneeDropdown`, `TicketNoteCard`, `SimpleMarkdownRenderer` |
+| **Media / Upload** | `FileUpload`, `ImageUploader`, `MediaTypeSelector` |
+| **Misc** | `FloatingTooltip`, `TruncateText`, `CircularProgress`, `Skeleton`, `Slider` |
 
 ## Usage Example
 
 ```typescript
-import { 
-  Button, 
-  Card, 
-  Input, 
-  Dialog,
+import {
+  Button,
+  Input,
+  Select,
   Table,
-  StatusBadge 
-} from '@/components/ui'
+  TableRow,
+  TableCell,
+  CursorPagination,
+  StatusBadge,
+  QueryReportTable,
+  deriveColumns,
+} from '@your-org/ui-kit'
+
+function DeviceTable({ data, pagination }) {
+  const columns = deriveColumns(data)
 
-function MyComponent() {
   return (
-    <Card>
-      <Input placeholder="Search..." />
-      <Button variant="primary">Submit</Button>
-      <StatusBadge status="active" />
-    </Card>
+    <>
+      <QueryReportTable columns={columns} rows={data} />
+      <CursorPagination {...pagination} />
+    </>
   )
 }
-```
+```
+
+> **Note:** This file is marked `"use client"` — all exported components are client-side only and require a React environment with client rendering support (e.g. Next.js App Router).

package/src/components/ui/.info-card.md

@@ -1,41 +1,41 @@
-<!-- source-hash: 3ca2d06c5ec6b892b020bb391b10787d -->
-A React component that renders structured information in a card format with support for icons, copyable values, dotted leaders, and optional progress indicators.
+<!-- source-hash: 871aa5b6b708ec48977c99b3cc86ea5f -->
+A reusable card component for displaying structured key-value information with optional title, subtitle, progress bar, and clipboard copy support.
 
 ## Key Components
 
-- **`InfoCardData`** - Interface defining the card's data structure including title, items, and progress
-- **`InfoCardProps`** - Component props interface with data and optional className
-- **`InfoCard`** - Main component that renders a dark-themed information card with:
-  - Optional title with icon
-  - Optional subtitle
-  - List of label-value pairs with dotted leaders
-  - Copyable values with clipboard functionality
-  - Optional progress bar at the bottom
+- **`InfoCard`** — Main exported component that renders a styled card with title, subtitle, info items, and an optional progress bar
+- **`InfoCardValueRow`** — Internal component rendering a single label/value row with a divider and optional copy-to-clipboard button
+- **`InfoCardData`** — Interface defining the card's data shape including items, optional progress config, and display metadata
+- **`InfoCardProps`** — Component props interface accepting `data` and an optional `className`
 
 ## Usage Example
 
 ```typescript
-import { InfoCard } from './components/info-card'
-import { ServerIcon } from './icons'
+import { InfoCard } from './info-card'
 
-const cardData = {
-  title: "System Status",
-  subtitle: "Current metrics",
-  icon: <ServerIcon className="w-5 h-5" />,
-  items: [
-    { label: "Status", value: "Online", copyable: false },
-    { label: "IP Address", value: "192.168.1.100", copyable: true },
-    { label: "Ports", value: ["80", "443", "8080"], copyable: true }
-  ],
-  progress: {
-    value: 75,
-    warningThreshold: 80,
-    criticalThreshold: 90,
-    inverted: false
-  }
-}
-
-<InfoCard data={cardData} className="w-full max-w-md" />
+// Basic usage with copyable values and progress bar
+<InfoCard
+  data={{
+    title: "Server Details",
+    subtitle: "Production Node",
+    icon: <ServerIcon />,
+    items: [
+      { label: "IP Address", value: "192.168.1.100", copyable: true },
+      { label: "Tags", value: ["web", "prod"], copyable: false },
+    ],
+    progress: {
+      value: 85,
+      warningThreshold: 70,
+      criticalThreshold: 90,
+      inverted: false,
+    },
+  }}
+  className="max-w-sm"
+/>
 ```
 
-The component automatically handles array values by displaying multiple rows, shows dotted leaders between labels and values, and provides one-click copying for designated fields.
+## Notes
+
+- Multi-value items (arrays) render each value as a separate row, with the label shown only on the first row
+- The progress bar supports `inverted` mode where high values are treated as healthy (green) and low values as critical (red)
+- Copy state resets automatically via the `useCopyToClipboard` hook, toggling between a copy and check icon

package/src/components/ui/.info-row.md

@@ -1,36 +1,40 @@
-<!-- source-hash: 9d6e7a15dea73a9757bb7224faf5fbe6 -->
-A reusable React component that displays key-value pairs in a horizontal layout with a decorative divider line between the label and value.
+<!-- source-hash: 841435ad2eb230c8516130a8d58de981 -->
+A reusable UI component that renders a single labeled row with a value, connected by a horizontal dotted separator line — commonly used for displaying key-value metadata in detail panels or cards.
 
 ## Key Components
 
-- **InfoRow**: Main component that renders a label-value pair with optional icon
-- **InfoRowProps**: TypeScript interface defining the component's props:
-  - `label`: Display text for the left side
-  - `value`: Display text for the right side  
-  - `icon`: Optional React node (typically an icon) displayed after the value
+### `InfoRow`
+A client-side React component that accepts the following props:
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | ✅ | Left-aligned label text |
+| `value` | `string` | ✅ | Right-aligned value text |
+| `icon` | `React.ReactNode` | ❌ | Optional icon rendered inline after the value |
 
 ## Usage Example
 
 ```typescript
-import { InfoRow } from './info-row'
-import { CheckIcon } from 'lucide-react'
-
-// Basic usage
-<InfoRow label="Status" value="Active" />
-
-// With icon
-<InfoRow 
-  label="Email Verified" 
-  value="Yes" 
-  icon={<CheckIcon className="w-4 h-4 text-green-500" />} 
-/>
-
-// Multiple rows for a details section
-<div className="space-y-2">
-  <InfoRow label="Name" value="John Doe" />
-  <InfoRow label="Role" value="Administrator" />
-  <InfoRow label="Last Login" value="2 hours ago" />
-</div>
+import { InfoRow } from "@/components/info-row"
+import { Globe } from "lucide-react"
+
+export function DeviceDetails() {
+  return (
+    <div className="flex flex-col gap-2">
+      <InfoRow label="Hostname" value="workstation-01" />
+      <InfoRow label="IP Address" value="192.168.1.100" />
+      <InfoRow
+        label="Status"
+        value="Online"
+        icon={<Globe className="w-4 h-4 text-green-400" />}
+      />
+    </div>
+  )
+}
 ```
 
-The component features a clean design with DM Sans typography, ellipsis overflow handling, and a subtle gray divider line that automatically fills the available space between the label and value.
+## Layout Behavior
+
+- **Label** — left side, truncates with ellipsis on overflow
+- **Separator** — flexible `1px` horizontal line that fills available space between label and value
+- **Value + Icon** — right side, truncates with ellipsis, icon rendered inline after text

package/src/components/ui/.input-trigger.md

@@ -0,0 +1,44 @@
+<!-- source-hash: c9b91d56212a5346e7a50d8e42269480 -->
+A `forwardRef`-wrapped button component styled to match Input fields, designed to trigger popups, popovers, dropdowns, and custom calendars while maintaining visual consistency with other form elements.
+
+## Key Components
+
+### `InputTriggerProps`
+Extends `React.ButtonHTMLAttributes<HTMLButtonElement>` (omitting `children`) with:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `selectedLabel` | `React.ReactNode` | Displayed when a value is selected |
+| `placeholder` | `string` | Shown when no value is selected |
+| `startIcon` | `React.ReactNode` | Icon rendered on the left |
+| `endIcon` | `React.ReactNode` | Icon rendered on the right (e.g. chevron) |
+| `invalid` | `boolean` | Applies error border styling |
+
+### `InputTrigger`
+A `forwardRef` button that:
+- Renders `placeholder` text (muted) when `selectedLabel` is `undefined`, `null`, or `""`
+- Applies `data-invalid` for error states and `data-[state=open]` accent border when open
+- Supports disabled, hover, and active visual states via Tailwind utility classes
+
+## Usage Example
+
+```typescript
+import { InputTrigger } from "./input-trigger";
+import { CalendarIcon, ChevronDownIcon } from "lucide-react";
+
+// Inside a Radix Popover
+<Popover>
+  <PopoverTrigger asChild>
+    <InputTrigger
+      selectedLabel={selectedDate ? format(selectedDate, "PPP") : undefined}
+      placeholder="Pick a date"
+      startIcon={<CalendarIcon size={16} />}
+      endIcon={<ChevronDownIcon size={16} />}
+      invalid={!!formErrors.date}
+    />
+  </PopoverTrigger>
+  <PopoverContent>...</PopoverContent>
+</Popover>
+```
+
+> **When to use:** Triggers for popovers, custom calendars, or `ActionsMenuDropdown`. Use `<Select>` for flat-list selection, and `<Button>` for page-level CTAs.

package/src/components/ui/.input.md

@@ -1,47 +1,53 @@
-<!-- source-hash: 5636f32d922f68d1e7189e5dc4be59af -->
-A comprehensive input component built on React's forwardRef pattern that supports adornments, validation states, and preview modes with consistent Flamingo design system styling.
+<!-- source-hash: deeae07a7913733b844e875487c55c37 -->
+A client-side input component built with `React.forwardRef`, supporting labels, validation states, adornments, loading indicators, and a special range slider variant.
 
 ## Key Components
 
-- **Input** - Main forwardRef component extending `HTMLInputElement` attributes
-- **InputProps** - Interface defining component props including validation and adornment options
-- **cn** - Utility function for conditional class name merging
+- **`Input`** — Main exported component extending native `HTMLInputElement` attributes
+- **`InputProps`** — Interface adding `invalid`, `startAdornment`, `endAdornment`, `label`, `error`, `errorVariant`, and `loading` props
+- **`invalidBorderClasses`** — Tailwind class map for `"error"` (red) and `"warning"` (yellow) border states
+- **`FieldWrapper`** — Wraps the input with optional label and error message rendering
 
-Key props:
-- `invalid` - Applies red error styling for validation states
-- `startAdornment`/`endAdornment` - React nodes displayed at input edges
-- `preview` - Non-interactive display mode showing current value
+## Behavior Notes
+
+- **Range type** renders a styled slider without borders or adornments; still supports `label` via `FieldWrapper`
+- **`loading`** replaces `endAdornment` with a spinning `Loader2` icon
+- **`isInvalid`** is derived from either the `invalid` prop or a truthy `error` string
+- Autofill background override applied via `-webkit-box-shadow` hack for consistent theming
 
 ## Usage Example
 
 ```typescript
-import { Input } from "./input";
-import { Search, Lock } from "lucide-react";
-
-// Basic input
-<Input placeholder="Enter your email" />
-
-// With validation
-<Input 
-  type="email" 
-  invalid={!isValidEmail} 
-  placeholder="email@example.com" 
+// Basic input with label and error
+<Input
+  label="Email"
+  type="email"
+  placeholder="you@example.com"
+  error="Invalid email address"
+  errorVariant="error"
 />
 
-// With adornments
+// Input with adornments and loading state
 <Input
-  type="search"
-  placeholder="Search..."
-  startAdornment={<Search size={16} />}
-  endAdornment="⌘K"
+  label="Search"
+  startAdornment={<SearchIcon />}
+  loading={isFetching}
+  placeholder="Search tickets..."
 />
 
-// Preview mode (read-only display)
+// Range slider
 <Input
-  preview
-  value="john@example.com"
-  startAdornment={<Lock size={16} />}
+  type="range"
+  label="Volume"
+  min={0}
+  max={100}
+  defaultValue={50}
 />
-```
 
-The component automatically handles three rendering modes: basic input, input with adornments (wrapped in label), and preview mode with non-interactive styling. All modes support the Flamingo dark theme with proper focus states and accessibility features.
+// Warning variant
+<Input
+  label="Username"
+  error="Username already taken"
+  errorVariant="warning"
+/>
+```

package/src/components/ui/.markdown-editor.md

@@ -0,0 +1,57 @@
+<!-- source-hash: ffc5aef958faee68b30051c7f83e0b1e -->
+A full-featured, theme-aware Markdown editor component wrapping `@uiw/react-md-editor` with Flamingo design system styling, file upload support, and auto-scroll during resize.
+
+## Key Components
+
+### `MarkdownEditor` (default export)
+The primary editor component. Dynamically loads the underlying `MDEditor` (SSR-safe) and injects scoped CSS overrides to match Flamingo's design tokens.
+
+### `MarkdownEditorStyles`
+Internal component that injects `<style>` into `document.head` once on mount, applying Flamingo theme variables to all `.w-md-editor-*` selectors.
+
+### `MarkdownEditorProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | Controlled markdown content |
+| `onChange` | `(markdown: string) => void` | Change callback |
+| `placeholder` | `string` | Editor placeholder text |
+| `disabled` | `boolean` | Disables editing |
+| `height` | `number` | Initial height in px (default: `600`) |
+| `minHeight` | `number` | Minimum height in px (default: `100`) |
+| `onUploadFile` | `(file: File) => Promise<string>` | Upload handler; shows upload button when provided |
+| `onFileUploaded` | `(url, filename) => void` | Post-upload callback |
+| `renderPreview` | `(source: string) => ReactNode` | Custom preview renderer |
+
+## Usage Example
+
+```typescript
+import { MarkdownEditor } from "./markdown-editor"
+
+function MyForm() {
+  const [content, setContent] = useState("# Hello")
+
+  const handleUpload = async (file: File): Promise<string> => {
+    const formData = new FormData()
+    formData.append("file", file)
+    const res = await fetch("/api/upload", { method: "POST", body: formData })
+    const { url } = await res.json()
+    return url
+  }
+
+  return (
+    <MarkdownEditor
+      value={content}
+      onChange={setContent}
+      placeholder="Write something..."
+      height={400}
+      onUploadFile={handleUpload}
+      onFileUploaded={(url, name) => console.log("Uploaded:", name, url)}
+    />
+  )
+}
+```
+
+**Notable behaviors:**
+- Pasting an image from clipboard triggers `onUploadFile` automatically
+- Uploaded files are inserted as `![name](url)` (images) or `[name](url)` (other)
+- The resize drag handle triggers an auto-scroll RAF loop to prevent viewport lock during resize

package/src/components/ui/.modal-v2.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 4e95a6a9f9ef814174b92059833949dc -->
+Accessible modal dialog component with keyboard navigation, backdrop click-to-close, and scroll locking. Built with React context to share close functionality across sub-components.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `ModalV2` | Root modal container — manages open state, Escape key handling, and body scroll lock |
+| `ModalV2Header` | Header row with close button (desktop only); consumes `ModalContext` for `onClose` |
+| `ModalV2Title` | Styled `<h2>` heading for the modal title |
+| `ModalV2Content` | Scrollable content area with `overflow-y-auto` |
+| `ModalV2Footer` | Flex row container for action buttons |
+
+## Usage Example
+
+```typescript
+import {
+  ModalV2,
+  ModalV2Header,
+  ModalV2Title,
+  ModalV2Content,
+  ModalV2Footer,
+} from "@/components/modal-v2"
+
+function ExampleModal() {
+  const [isOpen, setIsOpen] = React.useState(false)
+
+  return (
+    <ModalV2 isOpen={isOpen} onClose={() => setIsOpen(false)}>
+      <ModalV2Header>
+        <ModalV2Title>Confirm Action</ModalV2Title>
+      </ModalV2Header>
+      <ModalV2Content>
+        <p>Are you sure you want to proceed?</p>
+      </ModalV2Content>
+      <ModalV2Footer>
+        <button onClick={() => setIsOpen(false)}>Cancel</button>
+        <button onClick={handleConfirm}>Confirm</button>
+      </ModalV2Footer>
+    </ModalV2>
+  )
+}
+```
+
+## Behavior Notes
+
+- **Escape key** closes the modal automatically while open
+- **Backdrop click** dismisses via the overlay `div`
+- **Body scroll** is locked (`overflow: hidden`) while open and restored on close
+- **Close button** renders only on `md+` breakpoints; mobile relies on backdrop/Escape
+- All sub-components forward refs to their underlying DOM elements