@simplysm/solid 13.0.55 → 13.0.56

package/dist/styles/patterns.styles.js

@@ -29,7 +29,13 @@ const fieldSurface = clsx(
   "rounded",
   "focus-within:border-primary-500 dark:focus-within:border-primary-400"
 );
-const inputBase = clsx("min-w-0 flex-1", "bg-transparent", "outline-none", textPlaceholder);
+const inputBase = clsx(
+  "min-w-0 flex-1",
+  "bg-transparent",
+  "outline-none",
+  "[text-decoration:inherit]",
+  textPlaceholder
+);
 export {
   fieldSurface,
   iconButtonBase,

package/dist/styles/patterns.styles.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../src/styles/patterns.styles.ts"],
-  "mappings": "AAAA,OAAO,UAAU;AACjB,SAAS,eAAe,aAAa,uBAAuB;AAGrD,MAAM,iBAAiB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,YAAY;AAGlB,MAAM,eAAe;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,YAAY,KAAK,kBAAkB,kBAAkB,gBAAgB,eAAe;",
+  "mappings": "AAAA,OAAO,UAAU;AACjB,SAAS,eAAe,aAAa,uBAAuB;AAGrD,MAAM,iBAAiB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,YAAY;AAGlB,MAAM,eAAe;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,MAAM,YAAY;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;",
   "names": []
 }

package/docs/data-components.md

@@ -331,3 +331,431 @@ interface PermissionItem<TModule = string> {
 ```
 
 **Cascading behavior:** Checking a parent checks all children. Unchecking `perms[0]` (base permission) automatically unchecks all other permissions for that item.
+
+---
+
+## CrudSheet
+
+Full-featured CRUD data sheet component. Wraps `DataSheet` with built-in search, filter form, inline editing, modal editing, Excel import/export, select mode, pagination, sorting, and topbar action integration. Uses compound component pattern with `CrudSheet.Column`, `CrudSheet.Filter`, `CrudSheet.Tools`, and `CrudSheet.Header`.
+
+```tsx
+import { CrudSheet, type SearchResult, type SortingDef } from "@simplysm/solid";
+
+interface User {
+  id?: number;
+  name: string;
+  email: string;
+  isDeleted?: boolean;
+}
+
+interface UserFilter {
+  keyword: string;
+}
+
+// Inline editing mode
+<CrudSheet<User, UserFilter>
+  search={async (filter, page, sorts) => {
+    const result = await api.getUsers(filter, page, sorts);
+    return { items: result.items, pageCount: result.pageCount };
+  }}
+  getItemKey={(item) => item.id}
+  persistKey="user-crud"
+  itemsPerPage={20}
+  filterInitial={{ keyword: "" }}
+  inlineEdit={{
+    newItem: () => ({ name: "", email: "" }),
+    submit: async (diffs) => { await api.saveUsers(diffs); },
+    deleteProp: "isDeleted",
+  }}
+>
+  <CrudSheet.Filter>
+    {(filter, setFilter) => (
+      <FormGroup.Item label="Keyword">
+        <TextInput value={filter.keyword} onValueChange={(v) => setFilter("keyword", v)} />
+      </FormGroup.Item>
+    )}
+  </CrudSheet.Filter>
+  <CrudSheet.Column key="name" header="Name" class="px-2 py-1">
+    {(ctx) => (
+      <TextInput value={ctx.item.name} onValueChange={(v) => ctx.setItem("name", v)} />
+    )}
+  </CrudSheet.Column>
+  <CrudSheet.Column key="email" header="Email" class="px-2 py-1">
+    {(ctx) => (
+      <TextInput value={ctx.item.email} onValueChange={(v) => ctx.setItem("email", v)} />
+    )}
+  </CrudSheet.Column>
+</CrudSheet>
+
+// Modal editing mode
+<CrudSheet<User, UserFilter>
+  search={async (filter, page, sorts) => {
+    return await api.getUsers(filter, page, sorts);
+  }}
+  getItemKey={(item) => item.id}
+  persistKey="user-modal-crud"
+  itemsPerPage={20}
+  modalEdit={{
+    editItem: async (item) => {
+      const result = await dialog.show((close) => <UserEditDialog item={item} onClose={close} />);
+      return result === true;
+    },
+    deleteItems: async (items) => {
+      if (!confirm("Delete selected items?")) return false;
+      await api.deleteUsers(items.map((i) => i.id!));
+      return true;
+    },
+  }}
+>
+  <CrudSheet.Column key="name" header="Name" editable class="px-2 py-1">
+    {(ctx) => <>{ctx.item.name}</>}
+  </CrudSheet.Column>
+  <CrudSheet.Column key="email" header="Email" class="px-2 py-1">
+    {(ctx) => <>{ctx.item.email}</>}
+  </CrudSheet.Column>
+</CrudSheet>
+
+// Select mode (for picker dialogs)
+<CrudSheet<User, UserFilter>
+  search={async (filter, page, sorts) => {
+    return await api.getUsers(filter, page, sorts);
+  }}
+  getItemKey={(item) => item.id}
+  persistKey="user-select"
+  itemsPerPage={20}
+  selectMode="multi"
+  onSelect={(result) => {
+    // result.items: selected User[]
+    // result.keys: selected (string | number)[]
+    onConfirm(result.items);
+  }}
+>
+  <CrudSheet.Column key="name" header="Name" class="px-2 py-1">
+    {(ctx) => <>{ctx.item.name}</>}
+  </CrudSheet.Column>
+</CrudSheet>
+```
+
+**CrudSheet Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `search` | `(filter: TFilter, page: number, sorts: SortingDef[]) => Promise<SearchResult<TItem>>` | **(required)** | Search function. `page=0` means no pagination |
+| `getItemKey` | `(item: TItem) => string \| number \| undefined` | **(required)** | Unique key extractor for diff tracking |
+| `persistKey` | `string` | - | LocalStorage key for column configuration |
+| `itemsPerPage` | `number` | - | Items per page (enables pagination when set) |
+| `editable` | `() => boolean` | `() => true` | Whether editing is allowed |
+| `itemEditable` | `(item: TItem) => boolean` | `() => true` | Per-item edit control (modal edit mode) |
+| `itemDeletable` | `(item: TItem) => boolean` | `() => true` | Per-item delete control |
+| `filterInitial` | `TFilter` | - | Initial filter state |
+| `items` | `TItem[]` | - | Controlled items (external state) |
+| `onItemsChange` | `(items: TItem[]) => void` | - | Items change callback (controlled mode) |
+| `inlineEdit` | `InlineEditConfig<TItem>` | - | Inline editing configuration (mutually exclusive with `modalEdit`) |
+| `modalEdit` | `ModalEditConfig<TItem>` | - | Modal editing configuration (mutually exclusive with `inlineEdit`) |
+| `excel` | `ExcelConfig<TItem>` | - | Excel download/upload configuration |
+| `selectMode` | `"single" \| "multi"` | - | Select mode (disables editing, shows selection UI) |
+| `onSelect` | `(result: SelectResult<TItem>) => void` | - | Select confirmation callback |
+| `hideAutoTools` | `boolean` | - | Hide auto-generated toolbar buttons |
+| `class` | `string` | - | CSS class |
+
+**InlineEditConfig:**
+
+```typescript
+interface InlineEditConfig<TItem> {
+  submit: (diffs: ArrayDiffs2Result<TItem>[]) => Promise<void>;
+  newItem: () => TItem;
+  deleteProp?: keyof TItem & string;
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `submit` | Save function receiving changed items (inserted/updated/deleted diffs) |
+| `newItem` | Factory function for creating new empty rows |
+| `deleteProp` | Property name for soft-delete flag (e.g., `"isDeleted"`) |
+
+**ModalEditConfig:**
+
+```typescript
+interface ModalEditConfig<TItem> {
+  editItem: (item?: TItem) => Promise<boolean>;
+  deleteItems?: (items: TItem[]) => Promise<boolean>;
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `editItem` | Open edit dialog. `undefined` = new item. Return `true` to refresh |
+| `deleteItems` | Delete selected items. Return `true` to refresh |
+
+**ExcelConfig:**
+
+```typescript
+interface ExcelConfig<TItem> {
+  download: (items: TItem[]) => Promise<void>;
+  upload?: (file: File) => Promise<void>;
+}
+```
+
+**SelectResult:**
+
+```typescript
+interface SelectResult<TItem> {
+  items: TItem[];
+  keys: (string | number)[];
+}
+```
+
+**Sub-components:**
+
+- `CrudSheet.Column` -- Column definition (extends `DataSheet.Column` props + `editable`)
+- `CrudSheet.Filter` -- Filter form render prop
+- `CrudSheet.Tools` -- Custom toolbar render prop
+- `CrudSheet.Header` -- Header area above filter
+
+**CrudSheet.Column Props:**
+
+Inherits all `DataSheet.Column` props (`key`, `header`, `width`, `fixed`, `hidden`, `sortable`, `resizable`, `class`, `headerContent`, `headerStyle`, `summary`, `tooltip`, `collapse`) plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `editable` | `boolean` | `false` | Wrap cell with edit link (modal edit mode only) |
+| `children` | `(ctx: CrudSheetCellContext<TItem>) => JSX.Element` | **(required)** | Cell render function |
+
+**CrudSheetCellContext:**
+
+```typescript
+interface CrudSheetCellContext<TItem> {
+  item: TItem;
+  index: number;
+  row: number;
+  depth: number;
+  setItem: <TKey extends keyof TItem>(key: TKey, value: TItem[TKey]) => void;
+}
+```
+
+`setItem` updates a specific field of the current row item (inline edit mode).
+
+**CrudSheet.Filter:**
+
+```tsx
+<CrudSheet.Filter>
+  {(filter, setFilter) => (
+    <FormGroup.Item label="Search">
+      <TextInput value={filter.keyword} onValueChange={(v) => setFilter("keyword", v)} />
+    </FormGroup.Item>
+  )}
+</CrudSheet.Filter>
+```
+
+Receives `filter` (store) and `setFilter` (`SetStoreFunction`) as render prop arguments.
+
+**CrudSheet.Tools:**
+
+```tsx
+<CrudSheet.Tools>
+  {(ctx) => (
+    <Button size="sm" onClick={() => ctx.refresh()}>Custom Refresh</Button>
+  )}
+</CrudSheet.Tools>
+```
+
+**CrudSheetContext (Tools render prop):**
+
+```typescript
+interface CrudSheetContext<TItem> {
+  items(): TItem[];
+  selectedItems(): TItem[];
+  page(): number;
+  sorts(): SortingDef[];
+  busy(): boolean;
+  hasChanges(): boolean;
+  save(): Promise<void>;
+  refresh(): Promise<void>;
+  addItem(): void;
+  setPage(page: number): void;
+  setSorts(sorts: SortingDef[]): void;
+}
+```
+
+**CrudSheet.Header:**
+
+```tsx
+<CrudSheet.Header>
+  <h2 class="p-2 text-lg font-bold">User Management</h2>
+</CrudSheet.Header>
+```
+
+Renders static content above the filter area.
+
+**Keyboard shortcuts:**
+- `Ctrl+S` -- Save (inline edit mode)
+- `Ctrl+Alt+L` -- Refresh
+
+**Topbar integration:** When used inside `Topbar.Container`, CrudSheet automatically registers Save and Refresh buttons in the topbar via `createTopbarActions`.
+
+---
+
+## CrudDetail
+
+CRUD detail form component for single-record editing. Provides load, save, soft-delete/restore, change detection, and topbar action integration. Works both as a standalone page component and inside a `Dialog` (modal mode).
+
+```tsx
+import { CrudDetail, type CrudDetailInfo } from "@simplysm/solid";
+import { FormTable, TextInput, NumberInput } from "@simplysm/solid";
+
+interface User {
+  id?: number;
+  name: string;
+  age: number;
+}
+
+// Page mode (standalone)
+<CrudDetail<User>
+  load={async () => {
+    const user = await api.getUser(userId);
+    return {
+      data: user,
+      info: { isNew: user.id == null, isDeleted: false, lastModifiedAt: user.updatedAt },
+    };
+  }}
+  submit={async (data) => {
+    await api.saveUser(data);
+    return true; // return true to trigger success notification + refresh/close
+  }}
+  toggleDelete={async (del) => {
+    await api.toggleDeleteUser(userId, del);
+    return true;
+  }}
+>
+  {(ctx) => (
+    <FormTable>
+      <tbody>
+        <tr>
+          <th>Name</th>
+          <td>
+            <TextInput value={ctx.data.name} onValueChange={(v) => ctx.setData("name", v)} />
+          </td>
+        </tr>
+        <tr>
+          <th>Age</th>
+          <td>
+            <NumberInput value={ctx.data.age} onValueChange={(v) => ctx.setData("age", v!)} />
+          </td>
+        </tr>
+      </tbody>
+    </FormTable>
+  )}
+</CrudDetail>
+
+// Modal mode (inside Dialog via useDialog)
+const dialog = useDialog();
+
+const handleEdit = async () => {
+  const result = await dialog.show<boolean>(
+    () => (
+      <CrudDetail<User>
+        load={async () => ({ data: user, info: { isNew: false, isDeleted: false } })}
+        submit={async (data) => { await api.saveUser(data); return true; }}
+      >
+        {(ctx) => (
+          <FormTable>
+            <tbody>
+              <tr>
+                <th>Name</th>
+                <td><TextInput value={ctx.data.name} onValueChange={(v) => ctx.setData("name", v)} /></td>
+              </tr>
+            </tbody>
+          </FormTable>
+        )}
+      </CrudDetail>
+    ),
+    { header: "Edit User", width: 500 },
+  );
+  if (result) { /* saved successfully */ }
+};
+
+// With custom tools and before/after slots
+<CrudDetail<User>
+  load={loadUser}
+  submit={saveUser}
+  editable={hasEditPermission()}
+  deletable={hasDeletePermission()}
+>
+  {(ctx) => (
+    <>
+      <CrudDetail.Tools>
+        <Button size="sm" variant="ghost" onClick={() => ctx.refresh()}>Custom Refresh</Button>
+      </CrudDetail.Tools>
+      <CrudDetail.Before>
+        <div class="p-2 bg-info-50">Info banner (outside form)</div>
+      </CrudDetail.Before>
+      <FormTable>
+        <tbody>
+          <tr>
+            <th>Name</th>
+            <td><TextInput value={ctx.data.name} onValueChange={(v) => ctx.setData("name", v)} /></td>
+          </tr>
+        </tbody>
+      </FormTable>
+      <CrudDetail.After>
+        <div class="p-2">Footer content (outside form)</div>
+      </CrudDetail.After>
+    </>
+  )}
+</CrudDetail>
+```
+
+**CrudDetail Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `load` | `() => Promise<{ data: TData; info: CrudDetailInfo }>` | **(required)** | Load function returning data and metadata |
+| `children` | `(ctx: CrudDetailContext<TData>) => JSX.Element` | **(required)** | Render prop receiving context |
+| `submit` | `(data: TData) => Promise<boolean \| undefined>` | - | Save function. Return `true` to trigger success notification |
+| `toggleDelete` | `(del: boolean) => Promise<boolean \| undefined>` | - | Soft-delete/restore function. `del=true` for delete, `false` for restore |
+| `editable` | `() => boolean` | `() => true` | Whether editing is allowed |
+| `deletable` | `() => boolean` | `() => true` | Whether delete/restore is allowed |
+| `data` | `TData` | - | Controlled data state |
+| `onDataChange` | `(data: TData) => void` | - | Data change callback (controlled mode) |
+| `class` | `string` | - | CSS class |
+
+**CrudDetailInfo:**
+
+```typescript
+interface CrudDetailInfo {
+  isNew: boolean;
+  isDeleted: boolean;
+  lastModifiedAt?: DateTime;
+  lastModifiedBy?: string;
+}
+```
+
+**CrudDetailContext (render prop argument):**
+
+```typescript
+interface CrudDetailContext<TData> {
+  data: TData;
+  setData: SetStoreFunction<TData>;
+  info: () => CrudDetailInfo;
+  busy: () => boolean;
+  hasChanges: () => boolean;
+  save: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+```
+
+**Sub-components:**
+- `CrudDetail.Tools` -- Custom toolbar buttons (rendered in the toolbar area)
+- `CrudDetail.Before` -- Content rendered before the form (outside `<form>`)
+- `CrudDetail.After` -- Content rendered after the form (outside `<form>`)
+
+**Page vs Modal mode:**
+- **Page mode**: Toolbar with Save/Refresh/Delete buttons appears at the top. When inside `Topbar.Container`, Save and Refresh are also registered in the topbar via `createTopbarActions`.
+- **Modal mode** (inside `useDialog`): Refresh button appears in the dialog header. Save/Delete buttons appear in the bottom bar. On save/delete success, the dialog closes with `true` as the return value.
+
+**Keyboard shortcuts:**
+- `Ctrl+S` -- Save
+- `Ctrl+Alt+L` -- Refresh
+
+**Change detection:** On refresh, if unsaved changes exist, a confirmation dialog is shown. On save, if no changes exist (and not a new record), an info notification is shown instead.

package/docs/disclosure.md

@@ -59,37 +59,56 @@ Animation is automatically disabled when `prefers-reduced-motion` is set.
 
 ## Dropdown
 
-Positioned dropdown popup. Position is determined relative to trigger element or absolute coordinates.
+Positioned dropdown popup using compound components. Trigger click auto-toggles open state.
 
 ```tsx
-import { Dropdown, Button } from "@simplysm/solid";
-import { createSignal } from "solid-js";
-
-const [open, setOpen] = createSignal(false);
-let triggerRef!: HTMLButtonElement;
+import { Dropdown, Button, List } from "@simplysm/solid";
+
+// Trigger/Content compound components
+<Dropdown>
+  <Dropdown.Trigger>
+    <Button>Open</Button>
+  </Dropdown.Trigger>
+  <Dropdown.Content>
+    <p class="p-3">Dropdown content</p>
+  </Dropdown.Content>
+</Dropdown>
 
-<Button ref={triggerRef} onClick={() => setOpen(!open())}>Open</Button>
-<Dropdown triggerRef={() => triggerRef} open={open()} onOpenChange={setOpen}>
-  <p class="p-3">Dropdown content</p>
+// Controlled open state
+<Dropdown open={open()} onOpenChange={setOpen}>
+  <Dropdown.Trigger>
+    <Button>Open</Button>
+  </Dropdown.Trigger>
+  <Dropdown.Content>
+    <p class="p-3">Dropdown content</p>
+  </Dropdown.Content>
 </Dropdown>
 
-// Context menu (absolute position)
+// Context menu (absolute position, no Trigger)
 <Dropdown position={{ x: 100, y: 200 }} open={menuOpen()} onOpenChange={setMenuOpen}>
-  <List inset>
-    <List.Item>Menu item 1</List.Item>
-    <List.Item>Menu item 2</List.Item>
-  </List>
+  <Dropdown.Content>
+    <List inset>
+      <List.Item>Menu item 1</List.Item>
+      <List.Item>Menu item 2</List.Item>
+    </List>
+  </Dropdown.Content>
 </Dropdown>
 ```
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `triggerRef` | `() => HTMLElement \| undefined` | - | Trigger element reference (mutually exclusive with position) |
-| `position` | `{ x: number; y: number }` | - | Absolute position (mutually exclusive with triggerRef) |
+| `position` | `{ x: number; y: number }` | - | Absolute position (context menu mode, no Trigger needed) |
 | `open` | `boolean` | - | Open state |
 | `onOpenChange` | `(open: boolean) => void` | - | State change callback |
 | `maxHeight` | `number` | `300` | Maximum height (px) |
+| `disabled` | `boolean` | - | Disabled state (Trigger click ignored) |
 | `keyboardNav` | `boolean` | - | Enable keyboard navigation (used by Select, etc.) |
+| `class` | `string` | - | Additional CSS class for popup |
+| `style` | `JSX.CSSProperties` | - | Inline style for popup |
+
+**Sub-components:**
+- `Dropdown.Trigger` -- Trigger element wrapper (click to toggle)
+- `Dropdown.Content` -- Dropdown popup content
 
 ---
 
@@ -106,28 +125,32 @@ import { createSignal } from "solid-js";
 const [open, setOpen] = createSignal(false);
 
 <Button onClick={() => setOpen(true)}>Open</Button>
-<Dialog
-  title="Dialog Title"
-  open={open()}
-  onOpenChange={setOpen}
-  closeOnBackdrop
-  width={600}
->
+<Dialog open={open()} onOpenChange={setOpen} closeOnBackdrop width={600}>
+  <Dialog.Header>Dialog Title</Dialog.Header>
   <div class="p-4">
     Dialog content
   </div>
 </Dialog>
 
+// With header action buttons
+<Dialog open={open()} onOpenChange={setOpen}>
+  <Dialog.Header>My Dialog</Dialog.Header>
+  <Dialog.Action>
+    <Button size="sm" variant="ghost">Help</Button>
+  </Dialog.Action>
+  <div class="p-4">Dialog content</div>
+</Dialog>
+
 // Floating mode (no backdrop)
-<Dialog
-  title="Notification"
-  open={open()}
-  onOpenChange={setOpen}
-  float
-  position="bottom-right"
->
+<Dialog open={open()} onOpenChange={setOpen} float position="bottom-right">
+  <Dialog.Header>Notification</Dialog.Header>
   <div class="p-4">Floating dialog</div>
 </Dialog>
+
+// No header (content only)
+<Dialog open={open()} onOpenChange={setOpen}>
+  <div class="p-4">Dialog without header</div>
+</Dialog>
 ```
 
 **Programmatic usage with `useDialog`:**
@@ -158,7 +181,7 @@ function MyPage() {
   const handleOpen = async () => {
     const result = await dialog.show<string>(
       () => <EditDialog />,
-      { title: "Edit Name", width: 400, closeOnBackdrop: true },
+      { header: "Edit Name", width: 400, closeOnBackdrop: true },
     );
     if (result != null) {
       // result is the value passed to dialogInstance.close()
@@ -176,8 +199,6 @@ function MyPage() {
 |------|------|---------|-------------|
 | `open` | `boolean` | - | Open state |
 | `onOpenChange` | `(open: boolean) => void` | - | State change callback |
-| `title` | `string` | **(required)** | Modal title |
-| `hideHeader` | `boolean` | - | Hide header |
 | `closable` | `boolean` | `true` | Show close button |
 | `closeOnBackdrop` | `boolean` | - | Close on backdrop click |
 | `closeOnEscape` | `boolean` | `true` | Close on Escape key |
@@ -190,19 +211,28 @@ function MyPage() {
 | `minWidth` | `number` | - | Minimum width (px) |
 | `minHeight` | `number` | - | Minimum height (px) |
 | `position` | `"bottom-right" \| "top-right"` | - | Fixed position |
-| `headerAction` | `JSX.Element` | - | Header action area |
 | `headerStyle` | `JSX.CSSProperties \| string` | - | Header style |
 | `canDeactivate` | `() => boolean` | - | Pre-close confirmation function |
 | `onCloseComplete` | `() => void` | - | Post-close animation callback |
 | `class` | `string` | - | Additional CSS class applied to the dialog element |
 
+**Sub-components:**
+- `Dialog.Header` -- Dialog title (renders as `<h5>`, sets `aria-labelledby` on the dialog)
+- `Dialog.Action` -- Header action area (rendered between header text and close button)
+
+> The header bar (including close button) is only rendered when `Dialog.Header` is present. If no `Dialog.Header` is provided, the dialog renders content only with no header bar.
+
 **useDialog API:**
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
 | `show` | `<T>(factory: () => JSX.Element, options: DialogShowOptions) => Promise<T \| undefined>` | Open dialog, returns result on close |
 
-`DialogShowOptions` accepts all Dialog props except `open`, `onOpenChange`, and `children`.
+`DialogShowOptions` accepts all Dialog props except `open`, `onOpenChange`, `onCloseComplete`, and `children`, plus:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `header` | `JSX.Element` | Dialog header content (renders inside `Dialog.Header`) |
 
 **useDialogInstance API:**