@ticatec/topside-elements 1.0.0

package/dist/overlay/dialog/README.md

@@ -0,0 +1,540 @@
+# Dialog
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `DialogCloseConfirm`, `closeConfirm`, `confirmHandler`, `enableConfirm`, `onClose` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A flexible modal dialog system built with Svelte 5, offering stack-based management, a Promise API, draggable dialogs, configurable action buttons, and close confirmation. Exposes three things: `Dialog` (the base customizable dialog component), `CommonDialog` (simplified confirm/cancel wrapper), and `dialogManager` (a global stack controller that auto-mounts and returns `Promise<ModalResult>`).
+
+## Features
+
+- **Stack-based management**: the controller maintains a stack, so multiple dialogs can be open simultaneously
+- **Promise API**: `dialogManager.show(component, params)` returns `Promise<ModalResult>` — callers can `await` the close result
+- **Auto-mount**: the controller mounts `DialogBoard` to `document.body` on first `show` call — no need to manually place `<DialogBoard/>` in your app root
+- **Global imperative API**: `window.Dialog.show(component, params)` works too, so any code (services, stores, utilities) can trigger a dialog
+- **Multiple dialog types**: `Dialog`, `CommonDialog`, and `dialogManager` for different scenarios
+- **Draggable**: drag the title bar to reposition the dialog
+- **Action buttons**: configurable button actions; returning `true` auto-closes
+- **Close confirmation**: optional confirmation before closing (useful for unsaved changes)
+- **ESC to close**: ESC closes the dialog (picker ESC handling takes precedence automatically)
+- **Lifecycle hooks**: `onclose` callback + Promise resolve, both carrying a `ModalResult`
+- **Customizable styling**: flexible theming and sizing via inline styles
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Dialog, { dialogManager, CommonDialog, ModalResult } from "@ticatec/topside-elements/Dialog";
+```
+
+## Setup
+
+**New projects need no setup.** The controller auto-mounts to `document.body` the first time you call `dialogManager.show(...)`.
+
+> **Legacy compatibility**: if you previously placed `<DialogBoard/>` in your app root, you can leave it or remove it. When multiple boards coexist, only the first one to mount actually renders the stack — dialogs are never duplicated.
+
+## Two usage modes
+
+### Mode 1: Imperative (recommended)
+
+Wrap the dialog content in a Svelte component (a `<Dialog>` shell plus your form fields), then call `dialogManager.show` and `await` the result.
+
+**Dialog component** (receives `user` as initial data, `onSave` as the save callback):
+
+```svelte
+<!-- UserDetailsDialog.svelte -->
+<script lang="ts">
+  import Dialog from "@ticatec/topside-elements/Dialog";
+  import FormContainer, {Row, CellField} from "@ticatec/topside-elements/FlexRowForm";
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+  import RadioButton from "@ticatec/topside-elements/RadioButton";
+  import OptionsSelect from "@ticatec/topside-elements/OptionsSelect";
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+  import type {ButtonAction} from "@ticatec/topside-elements/types";
+
+  let {user, onSave}: { user: any, onSave?: (data: any) => Promise<boolean> } = $props();
+
+  let name = $state(user?.name ?? "");
+  let gender = $state(user?.gender ?? "M");
+  let birthday = $state(user?.birthday);
+  let occupation = $state(user?.occupation ?? "dev");
+  let email = $state(user?.email ?? "");
+  let bio = $state(user?.bio ?? "");
+
+  const genderOptions = [
+    {code: "M", text: "Male"},
+    {code: "F", text: "Female"},
+    {code: "O", text: "Other"}
+  ];
+
+  const occupationOptions = [
+    {code: "dev", text: "Engineer"},
+    {code: "design", text: "Designer"},
+    {code: "pm", text: "Product Manager"}
+  ];
+
+  // Returning true from the handler auto-closes the dialog with MR_OK
+  const actions: ButtonAction[] = [
+    {
+      label: "Save",
+      type: "primary",
+      handler: async () => {
+        const ok = await onSave?.({name, gender, birthday, occupation, email, bio});
+        return ok;
+      }
+    }
+  ];
+</script>
+
+<Dialog title="User Details" {actions} width="500px">
+  <FormContainer>
+    <Row>
+      <CellField label="Name" span={12} required>
+        <TextEditor bind:value={name} placeholder="Enter name"/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="Gender" span={12}>
+        {#each genderOptions as opt}
+          <RadioButton label={opt.text} value={opt.code} bind:group={gender}/>
+        {/each}
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="Birthday" span={12}>
+        <DatePicker bind:value={birthday}/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="Occupation" span={12}>
+        <OptionsSelect bind:value={occupation} options={occupationOptions}/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="Email" span={12}>
+        <TextEditor bind:value={email} placeholder="example@domain.com"/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="Bio" span={12}>
+        <MemoEditor bind:value={bio} rows={4}/>
+      </CellField>
+    </Row>
+  </FormContainer>
+</Dialog>
+```
+
+**Caller** (`await dialogManager.show` to get the close result):
+
+```svelte
+<script lang="ts">
+  import {dialogManager, ModalResult} from "@ticatec/topside-elements/Dialog";
+  import UserDetailsDialog from "./UserDetailsDialog.svelte";
+
+  async function editUser(user: any) {
+    const result = await dialogManager.show(UserDetailsDialog, {
+      user,
+      onSave: async (data) => {
+        await api.updateUser(data);
+        return true;  // returning true makes the Dialog action handler return true, triggering close
+      }
+    });
+    if (result === ModalResult.MR_OK) {
+      await refreshList();
+    }
+  }
+</script>
+
+<button onclick={() => editUser(currentUser)}>Edit</button>
+```
+
+You can also use the global `window.Dialog` (useful from non-Svelte modules like services / stores):
+
+```typescript
+const result = await window.Dialog.show(MyDialog, { foo: "bar" });
+```
+
+> **`window.Dialog.showModal` is deprecated**: retained as a compatibility alias that internally delegates to `show` but discards the Promise. Existing code keeps working; new code should use `show`.
+
+### Mode 2: Direct render
+
+If you don't want the stack / Promise and just want to conditionally render a dialog inline, you can use `<Dialog>` directly:
+
+```svelte
+<script>
+  import Dialog, { ModalResult } from "@ticatec/topside-elements/Dialog";
+
+  let showDialog = $state(false);
+
+  function handleClose(result) {
+    console.log("Dialog closed with:", result);
+    showDialog = false;
+  }
+</script>
+
+{#if showDialog}
+  <Dialog
+    title="My Dialog"
+    onclose={handleClose}
+    width="500px"
+    height="300px"
+  >
+    <p>Dialog content...</p>
+  </Dialog>
+{/if}
+```
+
+In direct-render mode there is no `dialogId` context, so `close()` invokes `onclose` itself.
+
+## Components Overview
+
+### Dialog
+
+The base dialog component with full customization. Works in both modes.
+
+### CommonDialog
+
+A simplified wrapper with a built-in confirm button — convenient for confirm/cancel flows.
+
+### dialogManager
+
+The global stack controller. Maintains the dialog stack and exposes `show` / `resolveWith`.
+
+## Dialog Component
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | Title-bar text |
+| `width` | `string` | `'unset'` | Dialog width (CSS value) |
+| `height` | `string` | `'unset'` | Dialog height (CSS value) |
+| `actions` | `ButtonActions \| null` | `null` | Action button array. Use `null` entries as separators |
+| `beforeClose` | `BeforeClose \| null` | `null` | Confirmation function called before closing (when result is `MR_CANCEL` or `MR_CLOSE`). Should return `Promise<boolean>` |
+| `content$style` | `string` | `''` | Custom inline styles for the content area |
+| `hideClose` | `boolean` | `false` | When `true`, hides the close (X) icon in the title bar |
+| `closeAction` | `ButtonAction \| null` | `null` | Override the default close button (label, type, etc.). The handler is always wired to internal close |
+| `onclose` | `OnClose \| null` | `null` | Callback when dialog closes. Receives a `ModalResult` (see [Modal Results](#modal-results)) |
+| `dialog$style` | `string` | `''` | Custom inline styles for the dialog container |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `close(result: ModalResult)` | Programmatically close the dialog with a result. Call via `bind:this` |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `onclose` | Fires when the dialog closes. Receives `ModalResult.MR_OK` / `MR_CANCEL` / `MR_CLOSE` |
+
+## CommonDialog Component
+
+Simplified wrapper that automatically provides a "Confirm" button. Works in both modes.
+
+### Basic Usage
+
+```svelte
+<script>
+  import { CommonDialog } from "@ticatec/topside-elements/Dialog";
+
+  let showDialog = $state(false);
+
+  async function handleConfirm() {
+    console.log("Confirmed!");
+    return true; // returning true auto-closes
+  }
+
+  function handleClose(result) {
+    console.log("Dialog result:", result);
+    showDialog = false;
+  }
+</script>
+
+{#if showDialog}
+  <CommonDialog
+    title="Confirm Action"
+    onconfirm={handleConfirm}
+    onclose={handleClose}
+    width="400px"
+  >
+    <p>Are you sure you want to proceed?</p>
+  </CommonDialog>
+{/if}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | Dialog title |
+| `width` | `string` | `'unset'` | Dialog width |
+| `height` | `string` | `'unset'` | Dialog height |
+| `beforeClose` | `BeforeClose \| null` | `null` | Close confirmation function |
+| `content$style` | `string` | `''` | Content area styles |
+| `confirmable` | `boolean` | `true` | Enable/disable the confirm button |
+| `onconfirm` | `(() => Promise<any>) \| null` | `null` | Confirm button handler |
+| `confirmText` | `string \| null` | `null` | Custom confirm button text (defaults to i18n "Confirm") |
+| `onclose` | `OnClose \| null` | `null` | Close callback receiving `ModalResult` |
+
+## Global API
+
+### `dialogManager.show(component, params): Promise<ModalResult>`
+
+Opens a dialog, passing `params` as props to `component`. The Promise resolves when the dialog closes, with the user's close result.
+
+```typescript
+import { dialogManager, ModalResult } from "@ticatec/topside-elements/Dialog";
+
+const result = await dialogManager.show(MyDialog, {
+  title: "Example",
+  onclose: (r) => console.log("closed:", r)  // you can also get the result here
+});
+```
+
+### `window.Dialog.show(component, params): Promise<ModalResult>`
+
+Same as above but attached to `window`, so non-Svelte modules (services / stores / utilities) can call it. `window.Dialog` is set at module load — ready before the first call.
+
+### `window.Dialog.showModal(component, params): void`
+
+**Deprecated.** Compatibility alias that discards the Promise return value. New code should use `show`.
+
+## Action Buttons
+
+### Button Configuration
+
+```typescript
+type ButtonAction = {
+  label: string;
+  type?: "primary" | "secondary" | "danger";
+  disabled?: boolean;
+  handler?: (event: MouseEvent) => Promise<boolean> | boolean;
+};
+
+type ButtonActions = (ButtonAction | null)[];
+```
+
+Actions returning `true` automatically close the dialog and resolve with `ModalResult.MR_OK`. Use `null` entries as separators in the button row.
+
+### Example
+
+```svelte
+<script>
+  const actions = [
+    {
+      label: "Delete",
+      type: "danger",
+      handler: async () => {
+        const ok = await confirmDelete();
+        if (ok) {
+          await deleteItem();
+          return true; // close
+        }
+        return false; // keep open
+      }
+    },
+    null, // separator
+    {
+      label: "Save",
+      type: "primary",
+      disabled: !isValid,
+      handler: async () => {
+        await saveData();
+        return true;
+      }
+    }
+  ];
+</script>
+```
+
+## Close Confirmation
+
+Add confirmation before closing with unsaved changes (triggered on X click / ESC / Cancel button):
+
+```svelte
+<script>
+  import { ModalResult } from "@ticatec/topside-elements/Dialog";
+  import messageBox from "@ticatec/topside-elements/MessageBox";
+
+  let originalData = JSON.stringify(data);
+
+  const beforeClose = async () => {
+    const hasChanges = JSON.stringify(data) !== originalData;
+    if (hasChanges) {
+      return await messageBox.showConfirm("You have unsaved changes. Close anyway?", { title: "Confirm Close" })
+        === ModalResult.MR_OK;
+    }
+    return true;
+  };
+</script>
+
+<Dialog {beforeClose}>
+  <!-- content -->
+</Dialog>
+```
+
+## Modal Results
+
+`ModalResult` is shared with `MessageBox`:
+
+```typescript
+enum ModalResult {
+  MR_OK = 1,     // user confirmed (clicked an action that returned true)
+  MR_CANCEL = 2, // user cancelled (clicked Cancel / X / ESC)
+  MR_CLOSE = 3   // programmatic close (currently unused — reserved for distinguishing X from Cancel)
+}
+```
+
+### Handling Results
+
+```svelte
+<script>
+  import { ModalResult } from "@ticatec/topside-elements/Dialog";
+
+  function handleDialogClose(result) {
+    if (result === ModalResult.MR_OK) {
+      console.log("User confirmed");
+    } else {
+      console.log("User cancelled");
+    }
+  }
+</script>
+```
+
+## Stack Behavior
+
+The controller maintains a stack internally; every `show` pushes a new entry:
+
+```typescript
+// Two dialogs open at once — the second one stacks on top
+await dialogManager.show(Dialog, { title: "Bottom" });
+await dialogManager.show(Dialog, { title: "Top" });
+```
+
+Each entry holds its own Promise resolver, independent of the others. Native `<dialog>` top-layer rendering guarantees the topmost dialog is always visually on top — no manual z-index management. Closing a stacked dialog resolves its Promise with the appropriate result, and the controller pops the entry.
+
+## Dialog Sizing and Positioning
+
+### Responsive Sizing
+
+```svelte
+<!-- Fixed size -->
+<Dialog width="500px" height="400px">
+
+<!-- Responsive size -->
+<Dialog width="90vw" height="80vh">
+
+<!-- Auto size with max constraints -->
+<Dialog
+  width="min(800px, 90vw)"
+  height="min(600px, 80vh)"
+>
+```
+
+### Custom Styling
+
+```svelte
+<Dialog
+  dialog$style="border-radius: 12px; box-shadow: 0 20px 40px rgba(0,0,0,0.3);"
+  content$style="padding: 2rem; background: #f9f9f9;"
+>
+```
+
+## Validation and Error Handling
+
+Building on the `UserDetailsDialog` from [Mode 1](#mode-1-imperative-recommended), just add validation logic to the action handler:
+
+```svelte
+<script lang="ts">
+  // ... same field declarations as Mode 1 ...
+
+  let errors = $state<Record<string, string>>({});
+
+  function validate(): boolean {
+    errors = {};
+    if (!name) errors.name = "Name is required";
+    if (!email) errors.email = "Email is required";
+    else if (!email.includes("@")) errors.email = "Invalid email";
+    return Object.keys(errors).length === 0;
+  }
+
+  const actions: ButtonAction[] = [
+    {
+      label: "Save",
+      type: "primary",
+      handler: async () => {
+        if (!validate()) return false;  // validation failed → keep open
+        try {
+          await onSave?.({name, gender, birthday, occupation, email, bio});
+          return true;                   // success → close and resolve MR_OK
+        } catch (e) {
+          console.error("Save failed:", e);
+          return false;
+        }
+      }
+    }
+  ];
+</script>
+
+<!-- Pass error down to fields -->
+<CellField label="Name" span={12} required>
+  <TextEditor bind:value={name} placeholder="Enter name" error={errors.name}/>
+</CellField>
+```
+
+Key points:
+- Handler returns `false` → dialog stays open
+- Handler returns `true` (or omits return) → close and `resolve(MR_OK)`
+- Handler throws → catch it yourself, otherwise the Promise rejects and the caller's `await` throws
+
+## Best Practices
+
+1. **Prefer the imperative API (`dialogManager.show`)**: it returns a Promise, makes result handling ergonomic, and works from services / stores.
+2. **No need to manually mount `DialogBoard`**: the controller auto-mounts. Existing `<DialogBoard/>` placements in legacy code can stay or be removed.
+3. **Return `false` from action handlers** to keep the dialog open (e.g., when validation fails).
+4. **Use `beforeClose` for dirty forms** — show a MessageBox asking if the user really wants to leave unsaved changes.
+5. **Pick appropriate sizes** — 400–600px for simple dialogs, 700–900px for form dialogs, responsive sizing for mobile.
+6. **Stacking is supported, but don't overuse it**: multiple simultaneous dialogs can confuse users. Reach for it when genuinely needed.
+
+## TypeScript Support
+
+The `window.Dialog` type is injected via a `declare global` inside the package — usually no extra setup is needed. If autocomplete isn't working, add the declaration manually:
+
+```typescript
+import type { IDialog } from "@ticatec/topside-elements/Dialog";
+
+declare global {
+  interface Window {
+    Dialog: IDialog;
+  }
+}
+```
+
+## Migration Guide (from the previous version)
+
+| Old API | New API | Notes |
+|---|---|---|
+| `<DialogBoard/>` in app root | nothing | Controller auto-mounts; legacy placement can stay |
+| `window.Dialog.showModal(Component, params)` | `window.Dialog.show(Component, params)` or `dialogManager.show(...)` | `showModal` still works (compat alias) but discards the Promise |
+| `ModalResult.Ok` / `ModalResult.Cancel` | `ModalResult.MR_OK` / `ModalResult.MR_CANCEL` | Enum unified with MessageBox |
+| `onclose(result)` callback | `onclose(result)` + `await dialogManager.show(...)` | Both supported; Promise is the new way |
+
+## Related Components
+
+- [MessageBox](../message-box/README.md) — Global modal for confirmations and acknowledged messages
+- [Toast](../toast/README.md) — Non-blocking transient notifications
+- [Indicator](../indicator/README.md) — Full-screen loading spinner
+- [Drawer](../drawer/README.md) — Slide-out side panel
+- [ContextMenu](../context-menu/README.md) — Right-click menu with keyboard navigation
+- [Tooltip](../tooltip/README.md) — Hover-based contextual hints