entasis 0.7.1 → 0.9.0

package/README.md

@@ -320,7 +320,13 @@ Snippet props: `size` (px number or CSS length, default `1lh`), `color` (a role
 
 - `pnpm dev` runs the documentation site with a page per component under `/components/<name>`.
 - `.claude/skills/entasis/` (mirrored in `.agents/skills/entasis/`) holds the coding-agent skill: import conventions, per-component references, theming notes.
-- Each component folder ships a `*.mcp.ts` description used by the MCP integration.
+- Each component folder ships a `*.mcp.ts` description, served by the MCP server the docs site runs at
+  `https://entasis.beynar.workers.dev/mcp` (one `components` tool that returns a component's documentation).
+  Add it to a project for Claude Code with:
+
+  ```bash
+  claude mcp add --transport http --scope project entasis https://entasis.beynar.workers.dev/mcp
+  ```
 
 ## Releasing
 

package/dist/components/AppShell/appShell.theme.js

@@ -42,8 +42,8 @@ const defaultPage = cva({
         variant: {
             admin: 'bg-surface [--page-shell-chrome:var(--color-surface-canvas)] [--page-shell-surface:var(--color-surface)]',
             floating: 'bg-surface-canvas [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface-canvas)] [--page-shell-chrome-inline-gap:0.5rem] [--page-shell-chrome-block-gap:0.5rem] [--page-shell-header-top-radius:var(--radius-lg)] [--page-shell-header-bottom-radius:var(--radius-lg)] [--page-shell-footer-top-radius:var(--radius-lg)] [--page-shell-footer-bottom-radius:var(--radius-lg)] [--page-shell-chrome-border:var(--color-neutral-muted)] [--page-shell-chrome-shadow:var(--elevation-1)]',
-            inset: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[display-state=hidden]/sidebar-wrapper:border-transparent md:group-data-[display-state=hidden]/sidebar-wrapper:shadow-none',
-            split: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[display-state=hidden]/sidebar-wrapper:border-transparent md:group-data-[display-state=hidden]/sidebar-wrapper:shadow-none',
+            inset: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[page-flush=true]/sidebar-wrapper:border-transparent md:group-data-[page-flush=true]/sidebar-wrapper:shadow-none',
+            split: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[page-flush=true]/sidebar-wrapper:border-transparent md:group-data-[page-flush=true]/sidebar-wrapper:shadow-none',
             // The frame already owns the radius, border and elevation, so the page inside it is flat,
             // and its header chrome is the same surface as the content: the white column is one
             // piece whose only corners are the frame's own.

package/dist/components/FloatingWindow/FloatingWindow.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
 	import { createBindableValue } from '../../utils/state.svelte.js';
-	import { crossfade, scale } from 'svelte/transition';
+	import { crossfade, fade, scale } from 'svelte/transition';
 	import { easingFunctions } from '../../transitions/easingFunctions.js';
 	import Button from '../Button/Button.svelte';
 	import { minusIcon } from '../Icons/minus.js';
@@ -32,6 +32,7 @@
 		minimizable = true,
 		closable = true,
 		closeOnEscape = true,
+		backdrop = false,
 		position = $bindable(),
 		dimensions = $bindable({ width: 480, height: 320 }),
 		class: className,
@@ -116,6 +117,9 @@
 		get closeOnEscape() {
 			return closeOnEscape;
 		},
+		get backdrop() {
+			return backdrop;
+		},
 		get position() {
 			return position;
 		},
@@ -202,6 +206,26 @@
 	};
 </script>
 
+{#if backdrop && openState.value && !minimized && windowState.position}
+	<!-- Portaled into the window layer one index below the window; it fades on the window's own
+		 enter / exit timing, so minimizing lifts it while the window flies to the dock. -->
+	<div
+		{@attach windowState.theme.floatingWindows.portal}
+		data-slot="floating-window-backdrop"
+		aria-hidden="true"
+		class={classes.backdrop()}
+		style:z-index={windowState.backdropZIndex}
+		in:fade={{
+			duration: enter.in.duration ?? 0,
+			easing: easingFunctions[enter.in.easing ?? 'cubicOut']
+		}}
+		out:fade={{
+			duration: exit.out.duration ?? 0,
+			easing: easingFunctions[exit.out.easing ?? 'cubicOut']
+		}}
+	></div>
+{/if}
+
 {#if openState.value && !minimized && windowState.position}
 	<div
 		{@attach windowState.theme.floatingWindows.portal}
@@ -214,7 +238,7 @@
 		bind:this={ref}
 		{id}
 		role="dialog"
-		aria-modal="false"
+		aria-modal={backdrop ? 'true' : 'false'}
 		aria-labelledby={`${id}-title`}
 		aria-keyshortcuts={draggable
 			? 'Alt+ArrowUp Alt+ArrowRight Alt+ArrowDown Alt+ArrowLeft'

package/dist/components/FloatingWindow/floatingWindow.dock.svelte.js

@@ -5,6 +5,11 @@ const DOCK_ITEM_WIDTH = 176;
 const DOCK_ITEM_HEIGHT = 36;
 const DOCK_GAP = 8;
 const DOCK_INLINE_GAP = 8;
+const DOCK_DRAG_ACTIVATION = Object.freeze({
+    distancePx: 4,
+    touchDelayMs: 300,
+    touchTolerancePx: 8
+});
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
 export class FloatingWindowDockState {
     windowState;
@@ -98,6 +103,10 @@ export class FloatingWindowDockState {
     };
     drag = createPointerDrag({
         disabled: () => !this.windowState.draggable || !this.windowState.minimized,
+        // The item is the title button's container, not a handle: a press that never travels must
+        // keep the pointer on the button, or its click lands on the item and never restores.
+        capture: 'on-activate',
+        activation: () => DOCK_DRAG_ACTIVATION,
         onStart: (payload) => this.startMove(payload),
         onMove: (payload) => this.updateMove(payload),
         onEnd: (payload) => this.endMove(payload)
@@ -115,8 +124,8 @@ export class FloatingWindowDockState {
         return Math.max(1, Math.floor((availableLength - DOCK_INLINE_GAP * 2 + DOCK_GAP) / (itemLength + DOCK_GAP)));
     }
     startMove(payload) {
-        if (payload.event.target instanceof Element &&
-            payload.event.target.closest('[data-floating-window-dock-actions]')) {
+        if (payload.startTarget instanceof Element &&
+            payload.startTarget.closest('[data-floating-window-dock-actions]')) {
             return false;
         }
         this.windowState.activateSurface('dock');

package/dist/components/FloatingWindow/floatingWindow.mcp.d.ts

@@ -1 +1 @@
-export declare const floatingWindowDescription = "\n# FloatingWindow Component\n\nFloatingWindow renders a non-modal, portaled utility window that can be moved, resized, minimized into a configurable viewport-edge dock, restored, and closed. Multiple windows inside the same Theme provider coordinate their z-order and stack independently by dock placement. The Theme keeps floating windows below modal Dialog surfaces, so an open window remains mounted behind a dialog and returns unchanged when the dialog closes.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n  import { Button } from '../Button/index.ts';\n  import { FloatingWindow } from './index.ts';\n\n  let open = $state(false);\n</script>\n\n<Button onclick={() => (open = true)}>Open notes</Button>\n\n<FloatingWindow bind:open title=\"Notes\">\n  <p>Window content remains interactive alongside the page.</p>\n</FloatingWindow>\n```\n\n## Props\n\n- **id**: string - Stable DOM id. Generated when omitted.\n- **open**: boolean (default: true) - Bindable rendered state.\n- **defaultOpen**: boolean (default: true) - Initial state when open is not provided.\n- **minimized**: boolean (default: false) - Bindable docked state.\n- **dockPlacement**: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'left-top' | 'left-bottom' | 'right-top' | 'right-bottom' (default: 'bottom-left') - Edge and alignment used by the minimized dock. Top and bottom placements stack horizontally; left and right placements use a vertical title bar and stack vertically.\n- **title**: Slot<FloatingWindowPayload> (required) - Window title as text or a snippet.\n- **children**: Slot<FloatingWindowPayload> - Main content.\n- **dragFrom**: 'header' | 'window' (default: 'header') - Restricts dragging to the header or allows any non-interactive surface to start a drag.\n- **draggable**: boolean (default: true) - Enables pointer dragging.\n- **resizable**: boolean (default: true) - Enables four edge and four corner resize handles.\n- **minimizable**: boolean (default: true) - Shows the minimize control.\n- **closable**: boolean (default: true) - Shows the close control.\n- **closeOnEscape**: boolean (default: true) - Closes the topmost expanded floating window when Escape is pressed.\n- **position**: { x: number; y: number } - Bindable viewport-relative top-left position. The first render is centered when omitted.\n- **dimensions**: { width: number; height: number; min?: [width, height]; max?: [width, height] } (default: 480 x 320, minimum 280 x 160) - Bindable pixel dimensions and optional constraint tuples. Maximum dimensions remain additionally constrained to the viewport.\n- **class**: string - Additional classes on the visible window.\n- **theme**: FloatingWindowThemeProps - Per-instance theme overrides.\n- **ref**: HTMLDivElement - Bindable reference to the visible window or minimized dock item.\n- **onOpenChange**: (open: boolean) => void - Runs once for each library-requested state change.\n- **onAfterOpen**: (payload) => void - Runs after the open transition finishes.\n- **onAfterClose**: (payload) => void - Runs after the close transition finishes.\n- **onMinimize**: (payload) => void - Runs after minimize state updates.\n- **onRestore**: (payload) => void - Runs after restore state updates.\n- **onMove**: ({ position, window }) => void - Runs when a move commits.\n- **onResize**: ({ dimensions, window }) => void - Runs when a pointer or keyboard resize commits.\n\n## Dragging\n\nHeader dragging is the default because it preserves text selection and content interactions. With `dragFrom=\"window\"`, buttons, links, inputs, editable content, resize handles, and descendants marked `data-floating-window-no-drag` remain excluded from drag starts.\n\n## Accessibility\n\n- The expanded surface uses a non-modal `dialog` role and is labelled by its title.\n- Close, minimize, and restore controls are native Entasis buttons with accessible labels.\n- Edge resize handles use `separator` semantics and support arrow-key resizing; hold Shift for a larger step.\n- Opening focuses the non-modal window, closing restores focus to its previous owner, and only the topmost expanded floating window handles Escape.\n- Alt+Arrow moves the focused window; hold Shift for a larger step.\n- Corner handles are pointer-only because a diagonal separator has no valid ARIA orientation.\n- The component does not trap focus or hide page content because it is explicitly non-modal.\n\n## Theme Parts\n\n- **root**: Floating window surface and drag/resize states.\n- **header**: Default title bar and drag handle.\n- **title**: Header title.\n- **actions**: Header control group.\n- **control**: Header and dock icon buttons.\n- **scrollArea**: Flexible ScrollArea root that owns body scrolling.\n- **content**: Padded content inside the ScrollArea viewport.\n- **resizeHandle**: Edge and corner handles by direction.\n- **dockItem**: Minimized surface.\n- **dockTitle**: Full-width restore button in the dock item.\n- **dockTitleText**: Truncated title text and lateral writing direction.\n- **dockActions**: Dock restore and close controls.\n\n## Motion\n\n- **motion** theme slot, keyed by `phase`: `flight` times the crossfade between window and\n  dock pill, `enter` / `exit` the scale fallback when there is no counterpart.\n- Only `duration` / `easing` (plus the fallback's `scale` / `opacity`) are read.\n- Ladder: `<Theme components={{ 'floating-window': { motion } }}>` \u2192\n  `setFloatingWindowTheme({ motion })` \u2192 `theme.motion`. Read once, at mount.\n";
+export declare const floatingWindowDescription = "\n# FloatingWindow Component\n\nFloatingWindow renders a portaled utility window, non-modal unless `backdrop` is set, that can be moved, resized, minimized into a configurable viewport-edge dock, restored, and closed. Multiple windows inside the same Theme provider coordinate their z-order and stack independently by dock placement. The Theme keeps floating windows below modal Dialog surfaces, so an open window remains mounted behind a dialog and returns unchanged when the dialog closes.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n  import { Button } from '../Button/index.ts';\n  import { FloatingWindow } from './index.ts';\n\n  let open = $state(false);\n</script>\n\n<Button onclick={() => (open = true)}>Open notes</Button>\n\n<FloatingWindow bind:open title=\"Notes\">\n  <p>Window content remains interactive alongside the page.</p>\n</FloatingWindow>\n```\n\n## Props\n\n- **id**: string - Stable DOM id. Generated when omitted.\n- **open**: boolean (default: true) - Bindable rendered state.\n- **defaultOpen**: boolean (default: true) - Initial state when open is not provided.\n- **minimized**: boolean (default: false) - Bindable docked state.\n- **dockPlacement**: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'left-top' | 'left-bottom' | 'right-top' | 'right-bottom' (default: 'bottom-left') - Edge and alignment used by the minimized dock. Top and bottom placements stack horizontally; left and right placements use a vertical title bar and stack vertically.\n- **title**: Slot<FloatingWindowPayload> (required) - Window title as text or a snippet.\n- **children**: Slot<FloatingWindowPayload> - Main content.\n- **dragFrom**: 'header' | 'window' (default: 'header') - Restricts dragging to the header or allows any non-interactive surface to start a drag.\n- **draggable**: boolean (default: true) - Enables pointer dragging.\n- **resizable**: boolean (default: true) - Enables four edge and four corner resize handles.\n- **minimizable**: boolean (default: true) - Shows the minimize control.\n- **closable**: boolean (default: true) - Shows the close control.\n- **closeOnEscape**: boolean (default: true) - Closes the topmost expanded floating window when Escape is pressed.\n- **backdrop**: boolean (default: false) - Dims the page behind the expanded window and makes it modal like a Dialog: Tab stays inside, the rest of the page is inert, and page scroll is locked. Minimizing into the dock lifts all of it; restoring brings it back. Clicking the backdrop does nothing: close with the close control or Escape.\n- **position**: { x: number; y: number } - Bindable viewport-relative top-left position. The first render is centered when omitted.\n- **dimensions**: { width: number; height: number; min?: [width, height]; max?: [width, height] } (default: 480 x 320, minimum 280 x 160) - Bindable pixel dimensions and optional constraint tuples. Maximum dimensions remain additionally constrained to the viewport.\n- **class**: string - Additional classes on the visible window.\n- **theme**: FloatingWindowThemeProps - Per-instance theme overrides.\n- **ref**: HTMLDivElement - Bindable reference to the visible window or minimized dock item.\n- **onOpenChange**: (open: boolean) => void - Runs once for each library-requested state change.\n- **onAfterOpen**: (payload) => void - Runs after the open transition finishes.\n- **onAfterClose**: (payload) => void - Runs after the close transition finishes.\n- **onMinimize**: (payload) => void - Runs after minimize state updates.\n- **onRestore**: (payload) => void - Runs after restore state updates.\n- **onMove**: ({ position, window }) => void - Runs when a move commits.\n- **onResize**: ({ dimensions, window }) => void - Runs when a pointer or keyboard resize commits.\n\n## Dragging\n\nHeader dragging is the default because it preserves text selection and content interactions. With `dragFrom=\"window\"`, buttons, links, inputs, editable content, resize handles, and descendants marked `data-floating-window-no-drag` remain excluded from drag starts.\n\n## Accessibility\n\n- The expanded surface uses a `dialog` role labelled by its title: `aria-modal=\"false\"`, or `\"true\"` with `backdrop`.\n- Close, minimize, and restore controls are native Entasis buttons with accessible labels.\n- Edge resize handles use `separator` semantics and support arrow-key resizing; hold Shift for a larger step.\n- Opening focuses the window, closing restores focus to its previous owner, and only the topmost expanded floating window handles Escape.\n- Alt+Arrow moves the focused window; hold Shift for a larger step.\n- Corner handles are pointer-only because a diagonal separator has no valid ARIA orientation.\n- Without `backdrop` it does not trap focus or hide page content. With it, Tab and Shift+Tab stay inside the window, every sibling subtree up to `<body>` is `inert` (other windows and dock items included), and page scroll is locked, until the window closes or is minimized.\n\n## Theme Parts\n\n- **backdrop**: Page dim behind a window opened with `backdrop`, one layer below the window.\n- **root**: Floating window surface and drag/resize states.\n- **header**: Default title bar and drag handle.\n- **title**: Header title.\n- **actions**: Header control group.\n- **control**: Header and dock icon buttons.\n- **scrollArea**: Flexible ScrollArea root that owns body scrolling.\n- **content**: Padded content inside the ScrollArea viewport.\n- **resizeHandle**: Edge and corner handles by direction.\n- **dockItem**: Minimized surface.\n- **dockTitle**: Full-width restore button in the dock item.\n- **dockTitleText**: Truncated title text and lateral writing direction.\n- **dockActions**: Dock restore and close controls.\n\n## Motion\n\n- **motion** theme slot, keyed by `phase`: `flight` times the crossfade between window and\n  dock pill, `enter` / `exit` the scale fallback when there is no counterpart.\n- Only `duration` / `easing` (plus the fallback's `scale` / `opacity`) are read.\n- The backdrop fades on the `enter` / `exit` timings.\n- Ladder: `<Theme components={{ 'floating-window': { motion } }}>` \u2192\n  `setFloatingWindowTheme({ motion })` \u2192 `theme.motion`. Read once, at mount.\n";

package/dist/components/FloatingWindow/floatingWindow.mcp.js

@@ -1,7 +1,7 @@
 export const floatingWindowDescription = `
 # FloatingWindow Component
 
-FloatingWindow renders a non-modal, portaled utility window that can be moved, resized, minimized into a configurable viewport-edge dock, restored, and closed. Multiple windows inside the same Theme provider coordinate their z-order and stack independently by dock placement. The Theme keeps floating windows below modal Dialog surfaces, so an open window remains mounted behind a dialog and returns unchanged when the dialog closes.
+FloatingWindow renders a portaled utility window, non-modal unless \`backdrop\` is set, that can be moved, resized, minimized into a configurable viewport-edge dock, restored, and closed. Multiple windows inside the same Theme provider coordinate their z-order and stack independently by dock placement. The Theme keeps floating windows below modal Dialog surfaces, so an open window remains mounted behind a dialog and returns unchanged when the dialog closes.
 
 ## Basic Usage
 
@@ -35,6 +35,7 @@ FloatingWindow renders a non-modal, portaled utility window that can be moved, r
 - **minimizable**: boolean (default: true) - Shows the minimize control.
 - **closable**: boolean (default: true) - Shows the close control.
 - **closeOnEscape**: boolean (default: true) - Closes the topmost expanded floating window when Escape is pressed.
+- **backdrop**: boolean (default: false) - Dims the page behind the expanded window and makes it modal like a Dialog: Tab stays inside, the rest of the page is inert, and page scroll is locked. Minimizing into the dock lifts all of it; restoring brings it back. Clicking the backdrop does nothing: close with the close control or Escape.
 - **position**: { x: number; y: number } - Bindable viewport-relative top-left position. The first render is centered when omitted.
 - **dimensions**: { width: number; height: number; min?: [width, height]; max?: [width, height] } (default: 480 x 320, minimum 280 x 160) - Bindable pixel dimensions and optional constraint tuples. Maximum dimensions remain additionally constrained to the viewport.
 - **class**: string - Additional classes on the visible window.
@@ -54,16 +55,17 @@ Header dragging is the default because it preserves text selection and content i
 
 ## Accessibility
 
-- The expanded surface uses a non-modal \`dialog\` role and is labelled by its title.
+- The expanded surface uses a \`dialog\` role labelled by its title: \`aria-modal="false"\`, or \`"true"\` with \`backdrop\`.
 - Close, minimize, and restore controls are native Entasis buttons with accessible labels.
 - Edge resize handles use \`separator\` semantics and support arrow-key resizing; hold Shift for a larger step.
-- Opening focuses the non-modal window, closing restores focus to its previous owner, and only the topmost expanded floating window handles Escape.
+- Opening focuses the window, closing restores focus to its previous owner, and only the topmost expanded floating window handles Escape.
 - Alt+Arrow moves the focused window; hold Shift for a larger step.
 - Corner handles are pointer-only because a diagonal separator has no valid ARIA orientation.
-- The component does not trap focus or hide page content because it is explicitly non-modal.
+- Without \`backdrop\` it does not trap focus or hide page content. With it, Tab and Shift+Tab stay inside the window, every sibling subtree up to \`<body>\` is \`inert\` (other windows and dock items included), and page scroll is locked, until the window closes or is minimized.
 
 ## Theme Parts
 
+- **backdrop**: Page dim behind a window opened with \`backdrop\`, one layer below the window.
 - **root**: Floating window surface and drag/resize states.
 - **header**: Default title bar and drag handle.
 - **title**: Header title.
@@ -82,6 +84,7 @@ Header dragging is the default because it preserves text selection and content i
 - **motion** theme slot, keyed by \`phase\`: \`flight\` times the crossfade between window and
   dock pill, \`enter\` / \`exit\` the scale fallback when there is no counterpart.
 - Only \`duration\` / \`easing\` (plus the fallback's \`scale\` / \`opacity\`) are read.
+- The backdrop fades on the \`enter\` / \`exit\` timings.
 - Ladder: \`<Theme components={{ 'floating-window': { motion } }}>\` →
   \`setFloatingWindowTheme({ motion })\` → \`theme.motion\`. Read once, at mount.
 `;

package/dist/components/FloatingWindow/floatingWindow.props.d.ts

@@ -66,6 +66,12 @@ export type FloatingWindowProps = WithAttachments<{
     closable?: boolean;
     /** Closes the topmost expanded floating window when Escape is pressed. */
     closeOnEscape?: boolean;
+    /**
+     * Dims the page behind the expanded window and makes the window modal, like a Dialog: Tab
+     * stays inside, the rest of the page is inert, and page scroll is locked. Minimizing into the
+     * dock lifts all of it; restoring brings it back.
+     */
+    backdrop?: boolean;
     /** Bindable viewport-relative top-left position in pixels. Defaults to centered. */
     position?: FloatingWindowPosition;
     /** Bindable width and height in pixels, with optional [width, height] constraint tuples. */

package/dist/components/FloatingWindow/floatingWindow.state.svelte.d.ts

@@ -12,6 +12,7 @@ type FloatingWindowStateOptions = {
     minimizable: boolean;
     closable: boolean;
     closeOnEscape: boolean;
+    backdrop: boolean;
     position?: FloatingWindowPosition;
     dimensions: FloatingWindowDimensions;
     onOpenChange?: (open: boolean) => void;
@@ -61,6 +62,8 @@ export declare class FloatingWindowState extends FloatingWindowState_base {
     windowDrag: Attachment<HTMLElement>;
     resize(direction: FloatingWindowResizeDirection): Attachment<HTMLElement>;
     activateSurface(type: FloatingWindowSurface): void;
+    /** The index reserved just below the window when it activated with a backdrop. */
+    get backdropZIndex(): number;
     bringToFront(): void;
     close(): void;
     minimize(): void;

package/dist/components/FloatingWindow/floatingWindow.state.svelte.js

@@ -4,6 +4,7 @@ import { createPointerDrag } from '../../utils/pointerDrag.js';
 import { withOptions } from '../../utils/state.svelte.js';
 import { useTheme } from '../Theme/theme.state.svelte.js';
 import { useFocusScope } from '../../utils/useFocusScope.svelte.js';
+import { useScrollLock } from '../../utils/useScrollLock.svelte.js';
 import { FloatingWindowDockState } from './floatingWindow.dock.svelte.js';
 import { FLOATING_WINDOW_VIEWPORT_GAP, FloatingWindowGeometry } from './floatingWindow.geometry.js';
 const KEYBOARD_STEP = 10;
@@ -25,17 +26,20 @@ export class FloatingWindowState extends withOptions() {
     viewportHeight = $state(0);
     geometry;
     docking;
-    // Non-modal: focus lands on the window when it opens and returns to the opener on close.
+    // Focus lands on the window when it opens and returns to the opener on close. Non-modal by
+    // default; with a backdrop the window is modal like a Dialog: Tab stays inside and every
+    // sibling subtree up to <body> is inert.
     focusScope = useFocusScope({
         isActive: () => this.open && !this.minimized,
-        trap: () => false,
+        trap: () => this.backdrop,
+        inertSiblings: () => this.backdrop,
         initialFocus: () => 'container'
     });
     // Escape is dispatched by the shared layer stack to the topmost layer only.
     layer = this.theme.layers.register({
         kind: 'floating-window',
         isOpen: () => this.open && !this.minimized,
-        isModal: () => false,
+        isModal: () => this.backdrop,
         dismissOnEscape: () => this.closeOnEscape && this.closable && this.theme.floatingWindows.isTopWindow(this.id),
         onDismiss: () => this.close(),
         state: this
@@ -47,6 +51,12 @@ export class FloatingWindowState extends withOptions() {
     resizeAttachments = plainMap();
     constructor(options) {
         super(options);
+        useScrollLock({ isActive: () => this.backdrop && this.open && !this.minimized });
+        // A backdrop switched on while the window is open needs the index below it reserved.
+        $effect(() => {
+            if (this.backdrop && this.open && !this.minimized)
+                untrack(() => this.bringToFront());
+        });
         this.geometry = new FloatingWindowGeometry(this);
         this.docking = new FloatingWindowDockState(this);
         if (typeof window !== 'undefined') {
@@ -153,7 +163,11 @@ export class FloatingWindowState extends withOptions() {
         return attachment;
     }
     activateSurface(type) {
-        this.zIndex = this.theme.floatingWindows.activate(this.id, type);
+        this.zIndex = this.theme.floatingWindows.activate(this.id, type, type === 'window' && this.backdrop);
+    }
+    /** The index reserved just below the window when it activated with a backdrop. */
+    get backdropZIndex() {
+        return this.zIndex - 1;
     }
     bringToFront() {
         this.activateSurface(this.minimized ? 'dock' : 'window');

package/dist/components/FloatingWindow/floatingWindow.theme.d.ts

@@ -32,6 +32,7 @@ export declare const floatingWindowTheme: {
             };
         };
     }>;
+    backdrop: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
         dragFrom: {
             header: string;
@@ -129,6 +130,7 @@ export declare const setFloatingWindowTheme: (theme: InferComponentTheme<{
             };
         };
     }>;
+    backdrop: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
         dragFrom: {
             header: string;
@@ -224,6 +226,7 @@ export declare const useFloatingWindowTheme: import("../../utils/cva/theme.js").
             };
         };
     }>;
+    backdrop: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
         dragFrom: {
             header: string;

package/dist/components/FloatingWindow/floatingWindow.theme.js

@@ -24,7 +24,7 @@ const defaultFloatingWindow = cva({
     }
 });
 const defaultFloatingWindowHeader = cva({
-    base: 'border-neutral-muted flex h-9 shrink-0 items-center gap-sm border-b px-md select-none',
+    base: 'border-neutral-muted flex h-9 shrink-0 items-center gap-sm border-b px-md-concentric select-none',
     variants: {
         draggable: {
             true: 'cursor-move touch-none',
@@ -66,17 +66,19 @@ const defaultFloatingWindowResizeHandle = cva({
     }
 });
 const defaultFloatingWindowDockItem = cva({
-    base: 'bg-surface-floating text-neutral pointer-events-auto fixed flex touch-none items-center overflow-hidden lift-4 ring-1 ring-neutral-muted',
+    base: 'bg-surface-floating text-neutral pointer-events-auto fixed flex touch-none items-center overflow-hidden lift-4 ring-1 ring-neutral-muted [--dock-radius:min(var(--radius-xl),calc(var(--spacing)*3))]',
     variants: {
         orientation: {
             horizontal: 'h-9 flex-row',
             vertical: 'w-9 flex-col'
         },
         side: {
-            top: 'rounded-t-none rounded-b-xl',
-            right: 'rounded-r-none rounded-l-xl',
-            bottom: 'rounded-t-xl rounded-b-none',
-            left: 'rounded-r-xl rounded-l-none'
+            // The window's step, capped at a third of the 36px (`spacing × 9`) item: any rounder and a
+            // round theme turns the tab into a pill. At that cap `md` padding always clears the corner.
+            top: 'rounded-[var(--dock-radius)] rounded-t-none',
+            right: 'rounded-[var(--dock-radius)] rounded-r-none',
+            bottom: 'rounded-[var(--dock-radius)] rounded-b-none',
+            left: 'rounded-[var(--dock-radius)] rounded-l-none'
         },
         dragging: {
             true: 'cursor-grabbing select-none',
@@ -89,8 +91,13 @@ const defaultFloatingWindowDockItem = cva({
         dragging: false
     }
 });
+// `!static`: the title is the pill's drag and restore surface, so its hover / press overlay (the
+// Button's `state-layer` ::before) anchors to the fixed dock item instead of the button and tints
+// the whole pill, clipped by its rounded overflow. The dock controls keep their own overlay.
+// `active:translate-none` drops the Button's press nudge: any `translate` but `none`, 0 included,
+// makes the title the anchor of its own overlay again and pulls the press tint back inside it.
 const defaultFloatingWindowDockTitle = cva({
-    base: '!min-w-0 !flex-1 !rounded-none !text-xs !font-medium',
+    base: '!static active:translate-none !min-w-0 !flex-1 !rounded-none !text-xs !font-medium',
     variants: {
         orientation: {
             horizontal: '!h-full !w-auto !justify-start !px-md !text-left',
@@ -135,6 +142,11 @@ const defaultFloatingWindowDockActions = cva({
 // The window and its dock pill are two halves of one crossfade: `flight` times the
 // shared transform between them, `enter` / `exit` the scale fallback used when there
 // is no counterpart to fly to. Only `duration` / `easing` are read from each.
+// The page dim behind a window opened with `backdrop`: the same wash as Dialog's backdrop, so a
+// modal window and a modal dialog dim the page alike.
+const defaultFloatingWindowBackdrop = cva({
+    base: 'fixed inset-0 bg-neutral/40 backdrop-blur-xs'
+});
 export const defaultFloatingWindowMotion = motion({
     base: {
         in: { x: 0, y: 0, scale: 0.97, opacity: 0 },
@@ -153,6 +165,7 @@ export const defaultFloatingWindowMotion = motion({
 });
 export const floatingWindowTheme = {
     motion: defaultFloatingWindowMotion,
+    backdrop: defaultFloatingWindowBackdrop,
     root: defaultFloatingWindow,
     header: defaultFloatingWindowHeader,
     title: defaultFloatingWindowTitle,

package/dist/components/Form/File/FileInput.svelte

@@ -9,6 +9,9 @@
 	import { useFileInputTheme } from './fileInput.theme.js';
 	import { slide } from 'svelte/transition';
 	import Slot from '../../Slot/Slot.svelte';
+	import { fileIcon } from '../../Icons/file.js';
+	import { plusIcon } from '../../Icons/plus.js';
+	import { xIcon } from '../../Icons/x.js';
 	import { useI18n } from '../../../i18n/context.svelte.js';
 
 	let {
@@ -153,20 +156,7 @@
 	/>
 	{#if dropzone.files.length === 0}
 		<div transition:slide class={classes.placeholder({ class: placeholderClass, size: rest.size })}>
-			<svg
-				xmlns="http://www.w3.org/2000/svg"
-				width="40"
-				height="40"
-				viewBox="0 0 24 24"
-				fill="none"
-				stroke="currentColor"
-				stroke-width="2"
-				stroke-linecap="round"
-				stroke-linejoin="round"
-			>
-				<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
-				<polyline points="14 2 14 8 20 8" />
-			</svg>
+			{@render fileIcon({ size: 40 })}
 			{#if resolvedPlaceholder}
 				<span class="mt-2">{resolvedPlaceholder}</span>
 			{/if}
@@ -192,20 +182,7 @@
 							</div>
 							<Button variant="ghost" size="small" squared onclick={() => dropzone.removeFile(fil)}>
 								{#snippet prefix()}
-									<svg
-										xmlns="http://www.w3.org/2000/svg"
-										width="16"
-										height="16"
-										viewBox="0 0 24 24"
-										fill="none"
-										stroke="currentColor"
-										stroke-width="2"
-										stroke-linecap="round"
-										stroke-linejoin="round"
-									>
-										<line x1="18" y1="6" x2="6" y2="18" />
-										<line x1="6" y1="6" x2="18" y2="18" />
-									</svg>
+									{@render xIcon({ size: 16 })}
 								{/snippet}
 							</Button>
 						</Slot>
@@ -214,20 +191,7 @@
 				{#if mode === 'multiple' && dropzone.files.length > 0 && dropzone.files.length < maxFiles}
 					<Button variant="soft" color="primary" fullWidth onclick={() => dropzone.open()}>
 						{#snippet prefix()}
-							<svg
-								xmlns="http://www.w3.org/2000/svg"
-								width="16"
-								height="16"
-								viewBox="0 0 24 24"
-								fill="none"
-								stroke="currentColor"
-								stroke-width="2"
-								stroke-linecap="round"
-								stroke-linejoin="round"
-							>
-								<line x1="12" y1="5" x2="12" y2="19" />
-								<line x1="5" y1="12" x2="19" y2="12" />
-							</svg>
+							{@render plusIcon({ size: 16 })}
 						{/snippet}
 						{Number.isFinite(maxFiles)
 							? t.addMoreFiles(dropzone.files.length, maxFiles)

package/dist/components/Form/Form/form.state.svelte.d.ts

@@ -634,6 +634,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -1405,6 +1406,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2210,6 +2212,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2981,6 +2984,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {

package/dist/components/Form/Form/visibility.d.ts

@@ -3349,6 +3349,7 @@ export declare function prepareInputProps(input: FormFieldInput, size: Sizes, la
     focused?: boolean | undefined;
     i18n?: Partial<import("../../../i18n/en.js").Messages> | undefined;
     separators?: boolean | undefined;
+    alignItemWithTrigger?: boolean | undefined;
     triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes | undefined;
     display?: string;
 } | {
@@ -8972,6 +8973,7 @@ export declare function prepareInputProps(input: FormFieldInput, size: Sizes, la
     focused?: boolean | undefined;
     i18n?: Partial<import("../../../i18n/en.js").Messages> | undefined;
     separators?: boolean | undefined;
+    alignItemWithTrigger?: boolean | undefined;
     triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes | undefined;
     display?: string;
 } | {

package/dist/components/Form/MultiStepForm/multiStepForm.state.svelte.d.ts

@@ -614,6 +614,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -1385,6 +1386,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2190,6 +2192,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2961,6 +2964,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {

package/dist/components/Form/Select/Select.svelte

@@ -30,6 +30,7 @@
 		visible,
 		items,
 		separators = true,
+		alignItemWithTrigger = true,
 		triggerAttrs,
 		label,
 		...rest
@@ -37,6 +38,9 @@
 	if (value === undefined) value = untrack(() => defaultValue);
 
 	const id = $props.id();
+	let valueEl = $state<HTMLElement | null>(null);
+	let listEl = $state<HTMLDivElement | null>(null);
+	let viewportEl = $state<HTMLDivElement | null>(null);
 	const t = $derived(useI18n(i18n));
 
 	const field = createFieldState({
@@ -105,6 +109,18 @@
 		},
 		set triggerEl(_) {
 			// field.node is owned by the bind:this below.
+		},
+		get alignItemWithTrigger() {
+			return alignItemWithTrigger;
+		},
+		get valueEl() {
+			return valueEl;
+		},
+		get listEl() {
+			return listEl;
+		},
+		get viewportEl() {
+			return viewportEl;
 		}
 	});
 
@@ -121,6 +137,7 @@
 	fitTrigger
 	position="bottom"
 	ref={field.node?.parentElement}
+	positionPanel={select.positionPanel}
 	size="small"
 	transition={{
 		in: { scale: 1, opacity: 0 },
@@ -143,7 +160,13 @@
 			event.preventDefault();
 		}}
 	>
-		<ScrollArea scrollOnEdges type="auto" class="flex max-h-[240px] flex-col">
+		<ScrollArea
+			bind:ref={listEl}
+			bind:viewportRef={viewportEl}
+			scrollOnEdges
+			type="auto"
+			class="flex max-h-[240px] flex-col"
+		>
 			{#each select.renderGroups as group, groupIndex (groupIndex)}
 				{#if separators && groupIndex > 0}
 					<div role="separator" class={classes.separator({ size })}></div>
@@ -230,7 +253,10 @@
 					triggerAttrs?.onblur?.(event);
 				}}
 			>
-				<span class={classes.value({ size, placeholder: !select.selectedOption })}>
+				<span
+					bind:this={valueEl}
+					class={classes.value({ size, placeholder: !select.selectedOption })}
+				>
 					{select.selectedOption?.label ?? placeholder ?? t.selectOption}
 				</span>
 				{@render caretDownIcon({ class: classes.triggerIcon({ size }) })}