@spaethtech/svelte-ui 0.4.1-dev.13.042fac9 → 0.4.1-dev.14.d54aa31

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

@@ -101,9 +101,10 @@ 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` (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)
+- **Overlays:** `Dialog` (pure modal shell — BYO content; `width`/`height` take any CSS value;
+  `onShow(ctx)`/`onHide(ctx)` control focus — set `ctx.autoFocus` to a selector/element/`false`,
+  `ctx.restoreFocus` likewise) · `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

@@ -4,7 +4,7 @@
   import CardHeader from "./CardHeader.svelte";
   import CardFooter from "./CardFooter.svelte";
   import Button from "./Button.svelte";
-  import type { Snippet } from "svelte";
+  import type { ComponentProps, Snippet } from "svelte";
   import type { Size } from "../types/sizes.js";
   import type { Responsive } from "../types/responsive.js";
 
@@ -32,6 +32,9 @@
     /** Forwarded to the Dialog shell — any CSS value (default: content-sized, capped at 32rem). */
     width?: string;
     height?: string;
+    /** Forwarded to the Dialog shell — open/close hooks with the `autoFocus`/`restoreFocus` knobs. */
+    onShow?: ComponentProps<typeof Dialog>["onShow"];
+    onHide?: ComponentProps<typeof Dialog>["onHide"];
     /** Custom body between header and footer (replaces `message`). */
     children?: Snippet;
   }
@@ -51,6 +54,8 @@
     dismissible = true,
     width,
     height,
+    onShow,
+    onHide,
     children,
   }: Props = $props();
 
@@ -69,6 +74,8 @@
   {dismissible}
   {width}
   {height}
+  {onShow}
+  {onHide}
   onClose={onCancel}
   aria-label={title}
 >

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

@@ -1,4 +1,5 @@
-import type { Snippet } from "svelte";
+import Dialog from "./Dialog.svelte";
+import type { ComponentProps, Snippet } from "svelte";
 import type { Size } from "../types/sizes.js";
 import type { Responsive } from "../types/responsive.js";
 /**
@@ -25,6 +26,9 @@ interface Props {
     /** Forwarded to the Dialog shell — any CSS value (default: content-sized, capped at 32rem). */
     width?: string;
     height?: string;
+    /** Forwarded to the Dialog shell — open/close hooks with the `autoFocus`/`restoreFocus` knobs. */
+    onShow?: ComponentProps<typeof Dialog>["onShow"];
+    onHide?: ComponentProps<typeof Dialog>["onHide"];
     /** Custom body between header and footer (replaces `message`). */
     children?: Snippet;
 }

package/dist/components/Dialog.svelte

@@ -11,7 +11,27 @@
    *
    * `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).
+   *
+   * `onShow` / `onHide` fire on open / close. Each hands you a mutable focus knob preset to the
+   * default, so a handler that ignores it keeps built-in behavior:
+   *   onShow(ctx):  ctx.autoFocus is the default focusable selector — set a selector/element to focus
+   *                 something specific, or `false` to skip (focus stays on the panel).
+   *   onHide(ctx):  ctx.restoreFocus is the element focused before open — set `false` to skip
+   *                 restoration, or another element to focus on close.
    */
+  interface DialogShowContext {
+    /** The panel element (already mounted). */
+    panel: HTMLElement;
+    /** What to focus on open — preset to the default focusable selector. Set a CSS selector or an
+     *  element to focus something specific, or `false` to skip autofocus (focus stays on the panel). */
+    autoFocus: string | HTMLElement | false;
+  }
+  interface DialogHideContext {
+    /** Where focus returns on close — preset to the element focused before the dialog opened. Set
+     *  `false` to skip restoration, or another element to focus instead. */
+    restoreFocus: HTMLElement | null | false;
+  }
+
   interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
     /** Whether the dialog is shown (bindable). */
     isOpen: boolean;
@@ -23,6 +43,12 @@
     dismissible?: boolean;
     /** Called when dismissed via backdrop / Escape (isOpen is also set false). */
     onClose?: () => void;
+    /** Fires on open (after mount). `ctx.autoFocus` (default = the focusable selector) controls what
+     *  gets focused; mutate it to retarget or set `false` to skip. */
+    onShow?: (ctx: DialogShowContext) => void;
+    /** Fires on close. `ctx.restoreFocus` (default = the pre-open element) controls focus return;
+     *  mutate it to retarget or set `false` to skip. */
+    onHide?: (ctx: DialogHideContext) => void;
     /** Extra classes on the panel wrapper. */
     class?: string;
     children?: Snippet;
@@ -34,6 +60,8 @@
     height,
     dismissible = true,
     onClose,
+    onShow,
+    onHide,
     class: cls = "",
     children,
     ...rest
@@ -66,16 +94,27 @@
     };
   });
 
-  // Focus management: on open, remember what was focused and move focus into the panel; on close,
-  // restore it. (Tab-wrapping is handled in onKeydown.)
+  // Focus management. On open: remember what was focused, fire `onShow`, then focus per
+  // `ctx.autoFocus` (default = first focusable). On close: fire `onHide`, then restore per
+  // `ctx.restoreFocus` (default = the pre-open element). (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();
+      if (!panelEl) return;
+      const ctx: DialogShowContext = { panel: panelEl, autoFocus: FOCUSABLE };
+      onShow?.(ctx);
+      let target: HTMLElement | null;
+      if (ctx.autoFocus === false) target = panelEl;
+      else if (ctx.autoFocus instanceof HTMLElement) target = ctx.autoFocus;
+      else target = panelEl.querySelector<HTMLElement>(ctx.autoFocus) ?? panelEl;
+      target?.focus();
     });
-    return () => previouslyFocused?.focus?.();
+    return () => {
+      const ctx: DialogHideContext = { restoreFocus: previouslyFocused };
+      onHide?.(ctx);
+      if (ctx.restoreFocus) ctx.restoreFocus.focus?.();
+    };
   });
 
   const panelStyle = $derived(

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

@@ -9,7 +9,26 @@ import type { HTMLAttributes } from "svelte/elements";
  *
  * `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).
+ *
+ * `onShow` / `onHide` fire on open / close. Each hands you a mutable focus knob preset to the
+ * default, so a handler that ignores it keeps built-in behavior:
+ *   onShow(ctx):  ctx.autoFocus is the default focusable selector — set a selector/element to focus
+ *                 something specific, or `false` to skip (focus stays on the panel).
+ *   onHide(ctx):  ctx.restoreFocus is the element focused before open — set `false` to skip
+ *                 restoration, or another element to focus on close.
  */
+interface DialogShowContext {
+    /** The panel element (already mounted). */
+    panel: HTMLElement;
+    /** What to focus on open — preset to the default focusable selector. Set a CSS selector or an
+     *  element to focus something specific, or `false` to skip autofocus (focus stays on the panel). */
+    autoFocus: string | HTMLElement | false;
+}
+interface DialogHideContext {
+    /** Where focus returns on close — preset to the element focused before the dialog opened. Set
+     *  `false` to skip restoration, or another element to focus instead. */
+    restoreFocus: HTMLElement | null | false;
+}
 interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
     /** Whether the dialog is shown (bindable). */
     isOpen: boolean;
@@ -21,6 +40,12 @@ interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
     dismissible?: boolean;
     /** Called when dismissed via backdrop / Escape (isOpen is also set false). */
     onClose?: () => void;
+    /** Fires on open (after mount). `ctx.autoFocus` (default = the focusable selector) controls what
+     *  gets focused; mutate it to retarget or set `false` to skip. */
+    onShow?: (ctx: DialogShowContext) => void;
+    /** Fires on close. `ctx.restoreFocus` (default = the pre-open element) controls focus return;
+     *  mutate it to retarget or set `false` to skip. */
+    onHide?: (ctx: DialogHideContext) => void;
     /** Extra classes on the panel wrapper. */
     class?: string;
     children?: Snippet;

package/docs/components.md

@@ -148,8 +148,13 @@ dialog.
 - **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.
+  `true`), `onClose`, `onShow`, `onHide`, `class`, `children` (snippet). Extra attributes (e.g.
+  `aria-label`) spread onto the panel.
+- **Focus control**: `onShow(ctx)` fires on open — `ctx.autoFocus` is preset to the default focusable
+  selector; set it to a **CSS selector / element** to focus something specific, or **`false`** to
+  skip (focus stays on the panel). `onHide(ctx)` mirrors it with `ctx.restoreFocus` (preset to the
+  pre-open element; set `false` to skip restoring focus, or another element). A handler that ignores
+  the knob keeps the built-in behavior.
 - **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`.
@@ -162,7 +167,8 @@ shell.
 - **Location**: `src/lib/components/ConfirmDialog.svelte`
 - **Props**: `isOpen` (bindable), `title`, `message`, `confirmText`, `cancelText`, `onConfirm`,
   `onCancel`, `variant` (`'normal' | 'danger'`), `size`, `showConfirm`, `showCancel`, `dismissible`,
-  `width`/`height` (forwarded to the shell), `children` (snippet — replaces `message` as the body).
+  `width`/`height`/`onShow`/`onHide` (forwarded to the shell), `children` (snippet — replaces
+  `message` as the body).
 
 ### Popup
 

package/docs/usage.md

@@ -273,6 +273,21 @@ with `width` / `height` (any CSS value).
 </Dialog>
 ```
 
+**Controlling focus.** The shell focuses the first focusable element on open and restores focus on
+close. Override via `onShow` / `onHide` — each hands you a mutable knob (default preserved if you
+ignore it):
+
+```svelte
+<Dialog
+  bind:isOpen={open}
+  onShow={(ctx) => (ctx.autoFocus = "[data-focus-me]")}
+  onHide={(ctx) => (ctx.restoreFocus = false)}
+>
+  <!-- ctx.autoFocus: CSS selector | element | false (skip). Default = first focusable. -->
+  <!-- ctx.restoreFocus: element | false (skip). Default = the element focused before open.  -->
+</Dialog>
+```
+
 ### Badge
 
 ```svelte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.4.1-dev.13.042fac9",
+  "version": "0.4.1-dev.14.d54aa31",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"