@spaethtech/svelte-ui 0.3.1-dev.9.88889c6 → 0.4.0

package/.claude/skills/svelte-ui/SKILL.md

@@ -101,7 +101,9 @@ examples):
 - **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`
 - **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**
   (query-language parser/AST, `createGrid`, `DataGrid<T>`, `DataSet`).
-- **Overlays:** `Dialog` `Popup` `Menu` · `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
+- **Overlays:** `Dialog` (pure modal shell — BYO content; `width`/`height` accept any CSS value)
+  · `ConfirmDialog` (title + message + Confirm/Cancel, built on Dialog) · `Popup` `Menu` ·
+  `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
 - **Navigation:** `TabStrip` `SideBarMenu`
 - **Feedback:** `Alert` `Banner` `Badge` `Toaster` + `toast`
 - **Layout:** `Card` `CardHeader` `CardBody` `CardFooter`

package/dist/components/ConfirmDialog.svelte

@@ -0,0 +1,103 @@
+<script lang="ts">
+  import Dialog from "./Dialog.svelte";
+  import Card from "./Card.svelte";
+  import CardHeader from "./CardHeader.svelte";
+  import CardFooter from "./CardFooter.svelte";
+  import Button from "./Button.svelte";
+  import type { Snippet } from "svelte";
+  import type { Size } from "../types/sizes.js";
+  import type { Responsive } from "../types/responsive.js";
+
+  /**
+   * ConfirmDialog — the common title + message + Confirm/Cancel modal, built on the `Dialog` shell.
+   * It composes a `Card` (`CardHeader` title, body, `CardFooter` actions) inside `Dialog`, so it stays
+   * consistent with every other surface. Pass `children` to replace the message body with custom
+   * content (the header + footer stay). For a fully custom modal, use `Dialog` directly.
+   */
+  interface Props {
+    isOpen: boolean;
+    title?: string;
+    message?: string;
+    confirmText?: string;
+    cancelText?: string;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+    variant?: "danger" | "normal";
+    /** Density tier — forwarded to the Card / CardHeader / CardFooter. */
+    size?: Responsive<Size>;
+    showConfirm?: boolean;
+    showCancel?: boolean;
+    /** Allow dismissing by backdrop / Escape (default true). */
+    dismissible?: boolean;
+    /** Forwarded to the Dialog shell — any CSS value (default: content-sized, capped at 32rem). */
+    width?: string;
+    height?: string;
+    /** Custom body between header and footer (replaces `message`). */
+    children?: Snippet;
+  }
+
+  let {
+    isOpen = $bindable(),
+    title = "Dialog",
+    message,
+    confirmText = "Confirm",
+    cancelText = "Cancel",
+    onConfirm,
+    onCancel,
+    variant = "normal",
+    size = "md",
+    showConfirm = true,
+    showCancel = true,
+    dismissible = true,
+    width,
+    height,
+    children,
+  }: Props = $props();
+
+  function handleConfirm() {
+    onConfirm?.();
+    isOpen = false;
+  }
+  function handleCancel() {
+    onCancel?.();
+    isOpen = false;
+  }
+</script>
+
+<Dialog
+  bind:isOpen
+  {dismissible}
+  {width}
+  {height}
+  onClose={onCancel}
+  aria-label={title}
+>
+  <Card {size} class="w-full shadow-xl">
+    <CardHeader {size}>
+      <h3 class="text-lg font-medium [color:var(--ui-color-text)]">{title}</h3>
+    </CardHeader>
+
+    {#if children}
+      {@render children()}
+    {:else if message}
+      <p class="text-sm [color:color-mix(in_srgb,var(--ui-color-text)_70%,transparent)]">
+        {message}
+      </p>
+    {/if}
+
+    {#if showConfirm || showCancel}
+      <CardFooter {size}>
+        {#if showCancel}
+          <Button text={cancelText} onclick={handleCancel} variant="secondary" />
+        {/if}
+        {#if showConfirm}
+          <Button
+            text={confirmText}
+            onclick={handleConfirm}
+            variant={variant === "danger" ? "danger" : "primary"}
+          />
+        {/if}
+      </CardFooter>
+    {/if}
+  </Card>
+</Dialog>

package/dist/components/ConfirmDialog.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { Snippet } from "svelte";
+import type { Size } from "../types/sizes.js";
+import type { Responsive } from "../types/responsive.js";
+/**
+ * ConfirmDialog — the common title + message + Confirm/Cancel modal, built on the `Dialog` shell.
+ * It composes a `Card` (`CardHeader` title, body, `CardFooter` actions) inside `Dialog`, so it stays
+ * consistent with every other surface. Pass `children` to replace the message body with custom
+ * content (the header + footer stay). For a fully custom modal, use `Dialog` directly.
+ */
+interface Props {
+    isOpen: boolean;
+    title?: string;
+    message?: string;
+    confirmText?: string;
+    cancelText?: string;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+    variant?: "danger" | "normal";
+    /** Density tier — forwarded to the Card / CardHeader / CardFooter. */
+    size?: Responsive<Size>;
+    showConfirm?: boolean;
+    showCancel?: boolean;
+    /** Allow dismissing by backdrop / Escape (default true). */
+    dismissible?: boolean;
+    /** Forwarded to the Dialog shell — any CSS value (default: content-sized, capped at 32rem). */
+    width?: string;
+    height?: string;
+    /** Custom body between header and footer (replaces `message`). */
+    children?: Snippet;
+}
+declare const ConfirmDialog: import("svelte").Component<Props, {}, "isOpen">;
+type ConfirmDialog = ReturnType<typeof ConfirmDialog>;
+export default ConfirmDialog;

package/dist/components/Dialog.svelte

@@ -1,57 +1,58 @@
 <script lang="ts">
-  import Button from "./Button.svelte";
-  import Card from "./Card.svelte";
-  import CardHeader from "./CardHeader.svelte";
-  import CardFooter from "./CardFooter.svelte";
   import type { Snippet } from "svelte";
-  import type { Size } from "../types/sizes.js";
-  import type { Responsive } from "../types/responsive.js";
+  import type { HTMLAttributes } from "svelte/elements";
 
-  interface Props {
+  /**
+   * Dialog — a PURE modal shell (layout container). It owns only the modal mechanics: portals itself
+   * to <body>, locks background scroll, renders a dismissable backdrop, traps focus, and exposes the
+   * ARIA dialog role. It imposes NO content structure — put a `Card` (or anything) inside via
+   * `children`. For the common title + message + Confirm/Cancel pattern, use `ConfirmDialog`, which is
+   * built on this.
+   *
+   * `width` / `height` accept any CSS length: `"80%"`, `"80vw"`, `"60vh"`, `"400px"`, … (both default
+   * to content size, capped to the viewport minus a 1rem inset so the panel never runs off-screen).
+   */
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /** Whether the dialog is shown (bindable). */
     isOpen: boolean;
-    title?: string;
-    message?: string;
-    confirmText?: string;
-    cancelText?: string;
-    onConfirm?: () => void;
-    onCancel?: () => void;
-    variant?: "danger" | "normal";
-    /** Density tier — forwarded to the underlying Card / CardHeader / CardFooter. */
-    size?: Responsive<Size>;
-    showConfirm?: boolean;
-    showCancel?: boolean;
-    /** Allow dismissing by clicking the backdrop OR pressing Escape (default true). Set `false` for a
-     *  must-decide dialog (e.g. a destructive confirm) so only the buttons close it. */
+    /** Panel width — any CSS value (`80%`, `80vw`, `400px`). Default: auto, capped at `min(32rem, …)`. */
+    width?: string;
+    /** Panel height — any CSS value (`60%`, `60vh`, `300px`). Default: auto (content height). */
+    height?: string;
+    /** Allow dismissing via backdrop click / Escape (default true). Set false for a must-decide modal. */
     dismissible?: boolean;
+    /** Called when dismissed via backdrop / Escape (isOpen is also set false). */
+    onClose?: () => void;
+    /** Extra classes on the panel wrapper. */
+    class?: string;
     children?: Snippet;
   }
 
   let {
     isOpen = $bindable(),
-    title = "Dialog",
-    message,
-    confirmText = "Confirm",
-    cancelText = "Cancel",
-    onConfirm,
-    onCancel,
-    variant = "normal",
-    size = "md",
-    showConfirm = true,
-    showCancel = true,
+    width,
+    height,
     dismissible = true,
+    onClose,
+    class: cls = "",
     children,
+    ...rest
   }: Props = $props();
 
+  const FOCUSABLE =
+    'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+  let panelEl: HTMLElement | undefined = $state();
+  let previouslyFocused: HTMLElement | null = null;
+
   // Move the overlay to <body> so it's a real top-level layer — never a sibling of the trigger (which
-  // would perturb surrounding layout, e.g. flip a space-y `:last-child`) and never clipped by an
-  // ancestor's overflow/stacking context. This is what makes it an actual modal, not an inline box.
+  // would perturb surrounding layout) and never clipped by an ancestor's overflow/stacking context.
   function portal(node: HTMLElement) {
     document.body.appendChild(node);
     return { destroy: () => node.remove() };
   }
 
-  // Lock background scroll while open; pad by the scrollbar width so hiding it doesn't shift the page
-  // sideways. Restore exactly what was there on close/destroy.
+  // Lock background scroll while open; pad by the scrollbar width so hiding it doesn't shift the page.
   $effect(() => {
     if (!isOpen) return;
     const sbw = window.innerWidth - document.documentElement.clientWidth;
@@ -65,68 +66,86 @@
     };
   });
 
-  function handleConfirm() {
-    onConfirm?.();
-    isOpen = false;
-  }
-  function handleCancel() {
-    onCancel?.();
+  // Focus management: on open, remember what was focused and move focus into the panel; on close,
+  // restore it. (Tab-wrapping is handled in onKeydown.)
+  $effect(() => {
+    if (!isOpen) return;
+    previouslyFocused = document.activeElement as HTMLElement | null;
+    queueMicrotask(() => {
+      const first = panelEl?.querySelector<HTMLElement>(FOCUSABLE);
+      (first ?? panelEl)?.focus();
+    });
+    return () => previouslyFocused?.focus?.();
+  });
+
+  const panelStyle = $derived(
+    [
+      width ? `width:${width}` : "width:auto",
+      `max-width:${width ? "calc(100vw - 2rem)" : "min(32rem, calc(100vw - 2rem))"}`,
+      height ? `height:${height}` : null,
+      "max-height:calc(100vh - 2rem)",
+    ]
+      .filter(Boolean)
+      .join(";"),
+  );
+
+  function close() {
+    if (!dismissible) return;
+    onClose?.();
     isOpen = false;
   }
-  // Backdrop click / Escape only dismiss when allowed.
-  function dismiss() {
-    if (dismissible) handleCancel();
-  }
-  function handleBackdropClick(event: MouseEvent) {
-    if (event.target === event.currentTarget) dismiss();
+  function onBackdrop(event: MouseEvent) {
+    if (event.target === event.currentTarget) close();
   }
-  function handleKeydown(event: KeyboardEvent) {
-    if (isOpen && event.key === "Escape") dismiss();
+  function onKeydown(event: KeyboardEvent) {
+    if (!isOpen) return;
+    if (event.key === "Escape") {
+      close();
+      return;
+    }
+    if (event.key === "Tab" && panelEl) {
+      const items = [...panelEl.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(
+        (el) => el.offsetParent !== null,
+      );
+      if (items.length === 0) {
+        event.preventDefault();
+        panelEl.focus();
+        return;
+      }
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement;
+      if (event.shiftKey && (active === first || active === panelEl)) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
   }
 </script>
 
-<svelte:window on:keydown={handleKeydown} />
+<svelte:window on:keydown={onKeydown} />
 
 {#if isOpen}
+  <!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
   <div
     use:portal
-    class="fixed inset-0 bg-black/50 flex items-center justify-center z-[9999]"
-    onclick={handleBackdropClick}
-    onkeydown={handleKeydown}
-    role="dialog"
-    aria-modal="true"
-    tabindex="-1"
+    class="fixed inset-0 bg-black/50 flex items-center justify-center z-[9999] p-4"
+    onclick={onBackdrop}
+    role="presentation"
   >
-    <!-- The panel IS a Card — border + --ui-border-radius + padding + background come from Card, so a
-         Dialog stays consistent with every other surface; CardHeader/CardFooter give the title + action
-         rows their (inset) separators and spacing. `size` flows to all three. -->
-    <Card {size} class="max-w-md w-full mx-4 shadow-xl z-[10000]">
-      <CardHeader {size}>
-        <h3 class="text-lg font-medium [color:var(--ui-color-text)]">{title}</h3>
-      </CardHeader>
-
-      {#if children}
-        {@render children()}
-      {:else if message}
-        <p class="text-sm [color:color-mix(in_srgb,var(--ui-color-text)_70%,transparent)]">
-          {message}
-        </p>
-      {/if}
-
-      {#if showConfirm || showCancel}
-        <CardFooter {size}>
-          {#if showCancel}
-            <Button text={cancelText} onclick={handleCancel} variant="secondary" />
-          {/if}
-          {#if showConfirm}
-            <Button
-              text={confirmText}
-              onclick={handleConfirm}
-              variant={variant === "danger" ? "danger" : "primary"}
-            />
-          {/if}
-        </CardFooter>
-      {/if}
-    </Card>
+    <div
+      bind:this={panelEl}
+      class="overflow-auto z-[10000] {cls}"
+      style={panelStyle}
+      role="dialog"
+      aria-modal="true"
+      tabindex="-1"
+      {...rest}
+    >
+      {@render children?.()}
+    </div>
   </div>
 {/if}

package/dist/components/Dialog.svelte.d.ts

@@ -1,22 +1,28 @@
 import type { Snippet } from "svelte";
-import type { Size } from "../types/sizes.js";
-import type { Responsive } from "../types/responsive.js";
-interface Props {
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * Dialog — a PURE modal shell (layout container). It owns only the modal mechanics: portals itself
+ * to <body>, locks background scroll, renders a dismissable backdrop, traps focus, and exposes the
+ * ARIA dialog role. It imposes NO content structure — put a `Card` (or anything) inside via
+ * `children`. For the common title + message + Confirm/Cancel pattern, use `ConfirmDialog`, which is
+ * built on this.
+ *
+ * `width` / `height` accept any CSS length: `"80%"`, `"80vw"`, `"60vh"`, `"400px"`, … (both default
+ * to content size, capped to the viewport minus a 1rem inset so the panel never runs off-screen).
+ */
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /** Whether the dialog is shown (bindable). */
     isOpen: boolean;
-    title?: string;
-    message?: string;
-    confirmText?: string;
-    cancelText?: string;
-    onConfirm?: () => void;
-    onCancel?: () => void;
-    variant?: "danger" | "normal";
-    /** Density tier — forwarded to the underlying Card / CardHeader / CardFooter. */
-    size?: Responsive<Size>;
-    showConfirm?: boolean;
-    showCancel?: boolean;
-    /** Allow dismissing by clicking the backdrop OR pressing Escape (default true). Set `false` for a
-     *  must-decide dialog (e.g. a destructive confirm) so only the buttons close it. */
+    /** Panel width — any CSS value (`80%`, `80vw`, `400px`). Default: auto, capped at `min(32rem, …)`. */
+    width?: string;
+    /** Panel height — any CSS value (`60%`, `60vh`, `300px`). Default: auto (content height). */
+    height?: string;
+    /** Allow dismissing via backdrop click / Escape (default true). Set false for a must-decide modal. */
     dismissible?: boolean;
+    /** Called when dismissed via backdrop / Escape (isOpen is also set false). */
+    onClose?: () => void;
+    /** Extra classes on the panel wrapper. */
+    class?: string;
     children?: Snippet;
 }
 declare const Dialog: import("svelte").Component<Props, {}, "isOpen">;

package/dist/components/Query.svelte

@@ -14,7 +14,7 @@
   import Input from "./Input.svelte";
   import Button from "./Button.svelte";
   import Popup from "./Popup.svelte";
-  import Dialog from "./Dialog.svelte";
+  import ConfirmDialog from "./ConfirmDialog.svelte";
   import type { DataSet } from "../data/dataset.js";
   import type { Size } from "../types/sizes.js";
   import type { Responsive } from "../types/responsive.js";
@@ -227,7 +227,7 @@
   </ul>
 </Popup>
 
-<Dialog bind:isOpen={helpOpen} title="Query syntax" showConfirm={false} showCancel={false}>
+<ConfirmDialog bind:isOpen={helpOpen} title="Query syntax" showConfirm={false} showCancel={false}>
   <div class="max-h-[70vh] space-y-4 overflow-y-auto text-sm [color:var(--ui-color-text)]">
     <p>
       A filter is one or more conditions, <code class="font-mono">$column operator value</code>.
@@ -281,4 +281,4 @@ $ip|inet |= [10.0.0.0|inet..10.255.255.255|inet]
       values. Applies on <kbd class="rounded border px-1 {bc}">Enter</kbd>.
     </p>
   </div>
-</Dialog>
+</ConfirmDialog>

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { default as CardFooter } from "./components/CardFooter.svelte";
 export { default as Toaster } from "./components/Toast/Toaster.svelte";
 export { toast, getToasts, dismissToast, type ToastVariant, type ToastItem, } from "./components/Toast/toast.svelte.js";
 export { default as Dialog } from "./components/Dialog.svelte";
+export { default as ConfirmDialog } from "./components/ConfirmDialog.svelte";
 export { default as Input } from "./components/Input.svelte";
 export { default as NotesEditor } from "./components/NotesEditor.svelte";
 export { default as Rating } from "./components/Rating.svelte";

package/dist/index.js

@@ -12,6 +12,7 @@ export { default as CardFooter } from "./components/CardFooter.svelte";
 export { default as Toaster } from "./components/Toast/Toaster.svelte";
 export { toast, getToasts, dismissToast, } from "./components/Toast/toast.svelte.js";
 export { default as Dialog } from "./components/Dialog.svelte";
+export { default as ConfirmDialog } from "./components/ConfirmDialog.svelte";
 export { default as Input } from "./components/Input.svelte";
 export { default as NotesEditor } from "./components/NotesEditor.svelte";
 export { default as Rating } from "./components/Rating.svelte";

package/docs/components.md

@@ -142,12 +142,27 @@ dialog.
 
 ### Dialog
 
-Modal dialog with confirm/cancel and optional custom content.
+**Pure modal shell** — the mechanics only, no imposed content. Put a `Card` (or anything) inside via
+`children`. For the common confirm pattern use `ConfirmDialog` (below).
 
 - **Location**: `src/lib/components/Dialog.svelte`
+- **Props**: `isOpen` (bindable), `width` (any CSS value — `'80%'`, `'80vw'`, `'400px'`; default
+  auto, capped at `min(32rem, …)`), `height` (any CSS value; default auto), `dismissible` (default
+  `true`), `onClose`, `class`, `children` (snippet). Extra attributes (e.g. `aria-label`) spread onto
+  the panel.
+- **Features**: portals to `<body>`, background scroll-lock (scrollbar-width compensated), backdrop
+  + Escape dismiss, **focus trap** (initial focus in, Tab wraps, focus restored on close),
+  `role="dialog"` + `aria-modal`.
+
+### ConfirmDialog
+
+The common title + message + Confirm/Cancel modal, composed from a `Card` on top of the `Dialog`
+shell.
+
+- **Location**: `src/lib/components/ConfirmDialog.svelte`
 - **Props**: `isOpen` (bindable), `title`, `message`, `confirmText`, `cancelText`, `onConfirm`,
-  `onCancel`, `variant` (`'normal' | 'danger'`), `showConfirm`, `showCancel`, `children` (snippet)
-- **Features**: backdrop-click + ESC dismiss, theme-aware
+  `onCancel`, `variant` (`'normal' | 'danger'`), `size`, `showConfirm`, `showCancel`, `dismissible`,
+  `width`/`height` (forwarded to the shell), `children` (snippet — replaces `message` as the body).
 
 ### Popup
 

package/docs/usage.md

@@ -212,41 +212,64 @@ into a component's `icon` snippet — the library sizes and colors it:
 <Checkbox disabled />
 ```
 
-### Dialog
+### ConfirmDialog
+
+The common title + message + Confirm/Cancel modal (composed from a `Card` on the `Dialog` shell).
 
 ```svelte
 <script>
-  import { Dialog, Button, Input } from "@spaethtech/svelte-ui";
+  import { ConfirmDialog, Button } from "@spaethtech/svelte-ui";
 
-  let showDialog = $state(false);
+  let showConfirm = $state(false);
   let showDanger = $state(false);
 </script>
 
 <!-- Basic confirmation -->
-<Button text="Show Dialog" onclick={() => (showDialog = true)} />
-<Dialog
-  bind:isOpen={showDialog}
+<Button text="Show Dialog" onclick={() => (showConfirm = true)} />
+<ConfirmDialog
+  bind:isOpen={showConfirm}
   title="Confirm Action"
   message="Are you sure you want to proceed?"
   onConfirm={() => console.log("Confirmed")}
 />
 
-<!-- Danger variant -->
-<Dialog
+<!-- Danger + must-decide (no backdrop/Escape dismiss) -->
+<ConfirmDialog
   bind:isOpen={showDanger}
   title="Delete Item"
   message="This action cannot be undone!"
   variant="danger"
   confirmText="Delete"
+  dismissible={false}
   onConfirm={() => console.log("Deleted")}
 />
+```
 
-<!-- Custom content -->
-<Dialog bind:isOpen={showDialog} title="Custom Content">
-  <div class="space-y-2">
-    <p>This is custom content</p>
-    <Input placeholder="Enter value" />
-  </div>
+### Dialog (shell)
+
+A pure modal shell — you supply the content. Use it for anything beyond the confirm pattern; size it
+with `width` / `height` (any CSS value).
+
+```svelte
+<script>
+  import { Dialog, Card, CardHeader, CardFooter, Button, Input } from "@spaethtech/svelte-ui";
+
+  let open = $state(false);
+</script>
+
+<Button text="Open" onclick={() => (open = true)} />
+
+<Dialog bind:isOpen={open} width="80vw" height="60vh">
+  <Card class="w-full h-full flex flex-col">
+    <CardHeader><h3 class="text-lg font-medium">Custom modal</h3></CardHeader>
+    <div class="flex-1 overflow-auto space-y-2">
+      <p>You own the Card — control its separator, variant, sizing, and body.</p>
+      <Input placeholder="Enter value" />
+    </div>
+    <CardFooter separator={false}>
+      <Button text="Close" variant="secondary" onclick={() => (open = false)} />
+    </CardFooter>
+  </Card>
 </Dialog>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.3.1-dev.9.88889c6",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"