entasis 0.12.0 → 0.13.1

package/dist/components/Theme/helper.js

@@ -73,18 +73,40 @@ export const compileThemeBlockingScript = ({ value, colorScheme, themes, validTh
 };
 /** The custom property carrying how far the on-screen keyboard overlaps the layout viewport. */
 export const KEYBOARD_INSET_VARIABLE = '--keyboard-inset';
+/** The custom property carrying how far the visual viewport is scrolled into the layout viewport. */
+export const VISUAL_VIEWPORT_TOP_VARIABLE = '--visual-viewport-top';
 /**
- * Boot script that mirrors the viewport onto `<html>`: `--window-height` and `--window-width`,
- * and `--keyboard-inset`, the px height the on-screen keyboard (or any other browser UI that
+ * Boot script that mirrors the viewport onto `<html>`: `--window-height` and `--window-width`;
+ * `--keyboard-inset`, the px height the on-screen keyboard (or any other browser UI that
  * shrinks only the visual viewport) covers at the bottom of the layout viewport, `0px` without
- * one. A pinch zoom also shrinks the visual viewport, so the inset stays `0px` while it is
- * zoomed. Browsers that resize the layout viewport for the keyboard report no overlap either.
+ * one; and `--visual-viewport-top`, how far the visible area starts below the top of the layout
+ * viewport (iOS scrolls it down to bring a focused field above the keyboard). Fixed content
+ * padded by both stays inside what the user can see. A pinch zoom also shrinks and moves the
+ * visual viewport, so both stay `0px` while it is zoomed. Browsers that resize the layout
+ * viewport for the keyboard report no overlap either.
+ *
+ * The layout viewport is the larger of `innerHeight` and the root's `clientHeight`: iOS 26
+ * shrinks `innerHeight` with the keyboard, while the root keeps the height fixed content uses.
+ *
+ * On iOS it also adds `maximum-scale=1` to the viewport meta tag (unless it sets its own): Safari
+ * zooms the page into any text field below 16px when it takes focus and leaves it zoomed. iOS
+ * ignores the limit for the user's pinch zoom, so the page stays zoomable; other platforms would
+ * honour it, so they are left alone.
  * Written as a self-contained string because it runs before hydration.
  */
 export const compileViewportScript = () => /* js */ `
 (() => {
 	const visualViewport = window.visualViewport;
 	const root = document.documentElement;
+	const navigator = window.navigator;
+	const ios =
+		!!navigator &&
+		(/iP(hone|od|ad)/.test(navigator.userAgent) ||
+			(navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1));
+	const viewportMeta = ios ? document.querySelector?.('meta[name="viewport"]') : null;
+	if (viewportMeta && !/maximum-scale/.test(viewportMeta.content)) {
+		viewportMeta.content = viewportMeta.content + ', maximum-scale=1';
+	}
 	const setWindowHeight = () => {
 		const height = visualViewport?.height ?? window.innerHeight;
 		root.style.setProperty('--window-height', height + 'px');
@@ -94,11 +116,14 @@ export const compileViewportScript = () => /* js */ `
 	};
 	const setKeyboardInset = () => {
 		const zoomed = !!visualViewport && Math.abs(visualViewport.scale - 1) > 0.01;
+		const layoutHeight = Math.max(window.innerHeight, root.clientHeight || 0);
+		const top = visualViewport && !zoomed ? Math.max(0, Math.round(visualViewport.offsetTop)) : 0;
 		const inset =
 			visualViewport && !zoomed
-				? Math.max(0, Math.round(window.innerHeight - visualViewport.height - visualViewport.offsetTop))
+				? Math.max(0, Math.round(layoutHeight - visualViewport.height - visualViewport.offsetTop))
 				: 0;
 		root.style.setProperty('${KEYBOARD_INSET_VARIABLE}', inset + 'px');
+		root.style.setProperty('${VISUAL_VIEWPORT_TOP_VARIABLE}', top + 'px');
 	};
 	window.addEventListener('resize', setWindowHeight);
 	window.addEventListener('resize', setWindowWidth);

package/dist/components/Theme/index.d.ts

@@ -2,7 +2,7 @@ export { default as Theme } from './Theme.svelte';
 export { ThemeState, useDefaultColor, useTheme } from './theme.state.svelte.js';
 export type { ThemeProps } from './theme.props.js';
 export { defaultThemeSpacingScale, typeScalePresets, type ThemeDesignTokenMap, type ThemeDesignTokens, type ThemeRadius, type ThemeSpacing, type ThemeSpacingScale, type ThemeSpacingStep, type TypeScaleOptions, type TypeScalePreset, type TypeScaleRatio } from './theme.designTokens.js';
-export { themeTransitions, type ThemeTransition } from './themeTransition.js';
+export { resolveThemeTransition, themeTransitions, type ThemeTransition, type ThemeTransitionInput, type ThemeTransitionOptions } from './themeTransition.js';
 export { focusRing, selectedSoft, selectedSolid } from './theme.recipes.js';
 export { themePresetNames, themePresets, type ThemePreset, type ThemePresetName, type ThemePresetTokens } from './theme.presets.js';
 export { breakpoints, containerBreakpoints, resolveContainerBreakpoint, resolveResponsive, responsiveContainerClasses, responsiveVariables, type ContainerBreakpoint } from './responsive.js';

package/dist/components/Theme/index.js

@@ -1,7 +1,7 @@
 export { default as Theme } from './Theme.svelte';
 export { ThemeState, useDefaultColor, useTheme } from './theme.state.svelte.js';
 export { defaultThemeSpacingScale, typeScalePresets } from './theme.designTokens.js';
-export { themeTransitions } from './themeTransition.js';
+export { resolveThemeTransition, themeTransitions } from './themeTransition.js';
 export { focusRing, selectedSoft, selectedSolid } from './theme.recipes.js';
 export { themePresetNames, themePresets } from './theme.presets.js';
 export { breakpoints, containerBreakpoints, resolveContainerBreakpoint, resolveResponsive, responsiveContainerClasses, responsiveVariables } from './responsive.js';

package/dist/components/Theme/theme.mcp.d.ts

@@ -1 +1 @@
-export declare const themeDescription = "\n# Theme\n\n`Theme` owns global theme selection, runtime design tokens, shared overlay state, and theme\ntransitions. Wrap the application once and use the `ThemeState` received by the children snippet.\nComponents below it read the same state with `useTheme()` from `entasis/theme`, called during\ncomponent initialisation; it throws when no `Theme` is above. For a palette computed at runtime,\nsee `generateColorPalette` in `entasis/color-palette`.\n\n## Runtime design tokens\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme, type ThemeDesignTokenMap } from 'entasis/theme';\n\n\tlet spacing = $state<'small' | 'normal' | 'large'>('normal');\n\tconst designTokens = $derived({\n\t\tlight: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'normal',\n\t\t\ttypeScale: 'default',\n\t\t\traisedWithBorder: true,\n\t\t\tdefaultColor: 'neutral'\n\t\t},\n\t\tdark: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'small',\n\t\t\ttypeScale: 'compact',\n\t\t\traisedWithBorder: false,\n\t\t\tdefaultColor: 'neutral'\n\t\t}\n\t} satisfies ThemeDesignTokenMap<readonly ['light', 'dark']>);\n</script>\n\n<Theme {designTokens} transition=\"radial-top-right\">\n\t{#snippet children(theme)}\n\t\t<button onclick={() => (spacing = spacing === 'small' ? 'large' : 'small')}>\n\t\t\tChange density\n\t\t</button>\n\t\t<button onclick={() => (theme.theme = theme.resolvedTheme === 'dark' ? 'light' : 'dark')}>\n\t\t\tToggle color scheme\n\t\t</button>\n\t{/snippet}\n</Theme>\n```\n\n`designTokens` is keyed by logical theme name and respects the `attribute` and `value` props.\nEleven presets ship as `themePresets` (`dense`, `compact`, `balanced`, `comfortable`, `spacious`,\n`sharp`, `rounded`, `display`, `editorial`, `glass`, `terminal`): `designTokens={{ light: themePresets.glass.tokens, dark: themePresets.glass.tokens }}`.\nChanging the controlled object updates already-rendered Tailwind utilities without rebuilding CSS.\n\n### ThemeDesignTokens\n\n- `spacing`: `'small' | 'normal' | 'large' | number`. Globally scales density.\n- `spacingScale`: partial overrides for the strictly increasing `xs`, `sm`, `md`, `lg`,\n  and `xl` spacing multipliers. Defaults to 1/1.5/2/3/4.\n- `radius`: `'none' | 'subtile' | 'small' | 'normal' | 'large' | 'round' | number`.\n  Controls take the full multiplier; surface steps (`lg` and up) stop at `large` (1.5\u00D7).\n- `typeScale`: `'compact' | 'default' | 'comfortable' | 'large' | TypeScaleOptions`.\n- `raisedWithBorder`: toggles the border used by `raised-*` utilities.\n- `defaultColor`: `Colors` role kit chrome inherits when a control omits `color`.\n  Defaults to `neutral`. Set `primary` to restore an accent-colored kit. Compiles the\n  current-color family (`--color`, `--color-readable`, muted/contrast/light/dark variants)\n  and `--default-color` onto the theme selector. Do not set `data-color` on `html`.\n- `focusColor`, `selectedColor`, `hoverColor`, `pressedColor`: the four `Colors` **state\n  roles**. They pin, for the whole theme, what a focus ring, a persistent selection and the\n  transient hover/pressed layer look like, independently of the role of the control the state\n  lands on. They compile `--color-focus`, `--color-selected` (plus its `-contrast`,\n  `-readable` and `-muted-readable` companions), `--color-hover` and\n  `--color-pressed` onto the theme selector. There is no `--color-selected-muted`: the soft\n  fill is a translucent tint of `--color-selected` at `--state-selected-opacity`, so it reads\n  on any surface. None is declared at `:root`: every use site\n  falls back to the matching current role (`ring-focus` is\n  `var(--color-focus, var(--color))`, `bg-selected-muted` tints\n  `var(--color-selected, var(--color))`, the state layer is\n  `var(--color-hover, currentColor)` and on `:active`\n  `var(--color-pressed, var(--color-hover, currentColor))`), so leaving them unset changes\n  nothing and `data-color` keeps moving the states with `--color`. Theme-level only: there is\n  no per-component override. An unknown role throws.\n\nComponent-level density remains a local variant. It selects utility classes whose values inherit\nthe active global spacing token.\n\nGenerated interfaces should use the public `xs | sm | md | lg | xl` vocabulary through component\nprops and named gap/padding utilities. `micro` and `layout-*` are internal recipe tokens. Prefer\nparent-owned gaps over child margins; do not emit arbitrary spacing or unsupported radius values.\n\n## Theme selection\n\nThe selection props wrap `svelte-themes`: `themes`, `defaultTheme`, `forcedTheme`,\n`systemTheme`, `syncColorScheme`, `transitionOnChange`, `storageKey`, `attribute`,\n`value`, and `colorScheme`. The default themes are light and dark, with system selection\nenabled. `systemTheme`, `syncColorScheme`, and `transitionOnChange` all default to\n`true`; they map onto the library's `enableSystem`, `enableColorScheme`, and\n`disableTransitionOnChange` options.\n\n`ThemeState` exposes `theme`, `resolvedTheme`, `themes`, and `systemTheme`. Assign\n`theme.theme` to switch themes. The optional `transition` prop applies a named view transition;\nunsupported browsers and reduced-motion users switch instantly.\n\n`spinnerVariant` sets the global default spinner animation. The children snippet is required.\n\n## Motion tokens\n\nMotion is a token scale like spacing and radius: five duration steps and four easing roles.\n`motion` retunes them app-wide; an omitted token keeps its default.\n\n| Duration   | Default |     | Easing role  | Default       |\n| ---------- | ------- | --- | ------------ | ------------- |\n| `instant`  | 0ms     |     | `standard`   | `cubicInOut`  |\n| `fast`     | 100ms   |     | `enter`      | `cubicOut`    |\n| `normal`   | 200ms   |     | `exit`       | `cubicIn`     |\n| `slow`     | 300ms   |     | `emphasized` | `backOut`     |\n| `slower`   | 500ms   |     |              |               |\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme motion={{ duration: { normal: 150, slow: 260 }, easing: { standard: 'quintOut' } }}>\n\t{@render children()}\n</Theme>\n```\n\nThe Tailwind plugin emits the same scale as CSS variables on `html` (`--duration-normal`,\n`--ease-standard`, ...) plus the matching `duration-*` / `ease-*` utilities, so CSS transitions\nand Svelte transitions read one set of numbers. The `motion` prop rewrites those variables on\n`html` at runtime and `designTokens.motion` rewrites them again per theme, layered over the prop;\n`ThemeState.motion` resolves through the same two rungs, so the utilities and the presets never\ndisagree. `ThemeState.transition` is a deprecated alias for its `normal` duration and `standard`\neasing. Reduced motion resolves every duration to 0 and collapses the `--duration-*` variables via\nthe `data-entasis-reduce-motion` attribute on `html`.\n\nComponents keep their own transition in a reserved `motion` slot on their theme, so the `theme`\nprop covers motion as well as classes:\n\n```svelte\n<script lang=\"ts\">\n\timport { Dialog } from 'entasis/dialog';\n</script>\n\n<Dialog theme={{ motion: { duration: 'fast', easing: 'emphasized' } }} title=\"Quick\">Body</Dialog>\n```\n\n## Component theme registry\n\n`components` sets app-wide component theme defaults without a wrapper component per component:\nit is keyed by theme name (`dialog`, `button`, ...) and each entry takes the same slots as that\ncomponent's `theme` prop, the `motion` slot included. A `set<Component>Theme` call in a subtree\nbeats the registry, and an instance `theme` prop beats both \u2014 per slot: each rung layers on the one\nbelow it, so a subtree that restyles one slot keeps the registry's others.\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme\n\tcomponents={{\n\t\tdialog: { motion: { duration: 'fast' }, content: { base: 'rounded-2xl' } },\n\t\tbutton: { root: { base: 'tracking-wide' } }\n\t}}\n>\n\t{@render children()}\n</Theme>\n```\n\n## Reduced motion\n\n`reduceMotion` forces reduced motion on (`true`) or off (`false`) for every entasis animation,\noverriding the OS `prefers-reduced-motion` setting; omit it to follow the OS. The live result is\nexposed as `ThemeState.preferReducesMotion` (reactive, so it updates when the OS setting changes)\nand mirrored as a `data-entasis-reduce-motion` attribute on `html` for CSS-only animations.\n\n```svelte\n<script>\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme reduceMotion>{@render children()}</Theme>\n```\n\n## Content Security Policy\n\n`nonce` is stamped on every `<script>` and `<style>` the Theme and the components below it\ninject: the theme and viewport boot scripts, the design-token stylesheet, the `transitionOnChange={false}`\nstyle, and the CDN loaders of PhoneInput, Map and Mermaid (the document print frame and Mermaid's own\nsvg `<style>` too). Drag-and-drop base styles are rules in the Tailwind plugin CSS, so nothing is\ninjected for them. Generate one nonce per request in `hooks.server.ts`, send it through `locals` to\n`<Theme nonce>`, and send the Content-Security-Policy header yourself with that same nonce.\nSvelteKit's `kit.csp` cannot be used for this: it generates its own nonce per request, exposes it\nonly as `%sveltekit.nonce%` in `app.html`, and has no option to take yours, so the header would\ncarry one nonce while the Theme's tags carry another. Leave `kit.csp` unset and put the nonce on\nSvelteKit's own inline tags in `transformPageChunk`:\n\n```ts\n// doc-fence: skip (needs nonce declared on the app's App.Locals)\n// src/hooks.server.ts\nimport type { Handle } from '@sveltejs/kit';\n\nexport const handle: Handle = async ({ event, resolve }) => {\n\tconst nonce = crypto.randomUUID();\n\tevent.locals.nonce = nonce;\n\tconst response = await resolve(event, {\n\t\t// Adds the nonce to SvelteKit's inline <script> and <style> tags; tags that already carry one\n\t\t// (the Theme's) are left alone.\n\t\ttransformPageChunk: ({ html }) =>\n\t\t\thtml.replace(/<(script|style)(?=[\\s>])(?![^>]*\\snonce=)/g, `<$1 nonce=\"${nonce}\"`)\n\t});\n\tresponse.headers.set(\n\t\t'content-security-policy',\n\t\t`script-src 'self' 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; style-src-attr 'unsafe-inline'`\n\t);\n\treturn response;\n};\n```\n\n```ts\n// doc-fence: skip (needs nonce declared on the app's App.Locals)\n// src/routes/+layout.server.ts\nimport type { LayoutServerLoad } from './$types';\n\nexport const load: LayoutServerLoad = ({ locals }) => ({ nonce: locals.nonce });\n```\n\n```svelte\n<!-- src/routes/+layout.svelte -->\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { data, children } = $props();\n</script>\n\n<Theme nonce={data.nonce}>\n\t{@render children()}\n</Theme>\n```\n\nServer-rendered `style` attributes (`style:` directives) are not covered by a nonce: allow them with\n`style-src-attr 'unsafe-inline'` (as above). `ThemeState.nonce` exposes the value to your own injected code.\n\n## Shadow DOM and portal containers\n\nDialogs, popovers, menus, tooltips and the floating-window layer mount in `document.body`. Inside a\nshadow root they mount in that root so adopted styles keep applying. `portalContainer` overrides both:\nan element or shadow root, or a function returning one for a container that is not rendered yet.\nA function that reads `$state` (as below) moves the floating-window layer in as soon as the container\nappears; a function over a plain variable is read each time a panel mounts, so the layer, which mounts\nwith the Theme, needs the container to exist by then.\nOutside presses and Escape are heard on the document a panel lives in, so a panel rendered into an\niframe's document dismisses correctly.\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n\tlet host = $state<HTMLElement>();\n</script>\n\n<div bind:this={host}></div>\n<Theme portalContainer={() => host}>\n\t{@render children()}\n</Theme>\n```\n\nWhen several Themes are mounted, the most recently mounted one that sets `portalContainer` wins.\n\n## Scroll lock and viewport variables\n\nA dialog or popover locks page scroll with a `data-entasis-scroll-lock` attribute on `<html>` and one\nrule in the Tailwind plugin CSS (`overflow: hidden`); nothing is written to inline styles, so a lock a\nthird-party library holds on the same element is neither overwritten nor released early. While\nlocked, the hidden scrollbar's room is kept with `scrollbar-gutter: stable` (the lock measures the\npage and pads the scrollbar's width instead where the gutter does not hold) unless the page already reserves a gutter, so there is no double gutter. Two variables\ndescribe the viewport for your own layout:\n\n- `--entasis-scrollbar-width`: set on `<html>` while locked, the width in px of the scrollbar the\n  lock hides (`0px` with overlay scrollbars). Add it to `position: fixed` bars:\n  `padding-inline-end: var(--entasis-scrollbar-width, 0px)`.\n- `--keyboard-inset`: the height in px the on-screen keyboard covers at the bottom of the layout\n  viewport, measured from the visual viewport (`0px` without a keyboard, while pinch-zoomed, and in\n  browsers that resize the layout viewport for the keyboard). Pin a bottom bar above the keyboard with\n  `bottom: var(--keyboard-inset)`.\n\n## Build-time boundary\n\nThe Tailwind plugin still generates color palettes and registers utility names, variants,\nkeyframes, and spinner CSS. Spacing, radius, typography scale, raised borders,\n`defaultColor` and the four state roles (`focusColor`, `selectedColor`, `hoverColor`,\n`pressedColor`) belong to `Theme.designTokens`; colors remain CSS variables and can be\noverridden directly. `ThemeState.defaultColor` exposes the active role. Kit chrome should\nresolve omitted `color` props with `useDefaultColor`.\n";
+export declare const themeDescription = "\n# Theme\n\n`Theme` owns global theme selection, runtime design tokens, shared overlay state, and theme\ntransitions. Wrap the application once and use the `ThemeState` received by the children snippet.\nComponents below it read the same state with `useTheme()` from `entasis/theme`, called during\ncomponent initialisation; it throws when no `Theme` is above. For a palette computed at runtime,\nsee `generateColorPalette` in `entasis/color-palette`.\n\n## Runtime design tokens\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme, type ThemeDesignTokenMap } from 'entasis/theme';\n\n\tlet spacing = $state<'small' | 'normal' | 'large'>('normal');\n\tconst designTokens = $derived({\n\t\tlight: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'normal',\n\t\t\ttypeScale: 'default',\n\t\t\traisedWithBorder: true,\n\t\t\tdefaultColor: 'neutral'\n\t\t},\n\t\tdark: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'small',\n\t\t\ttypeScale: 'compact',\n\t\t\traisedWithBorder: false,\n\t\t\tdefaultColor: 'neutral'\n\t\t}\n\t} satisfies ThemeDesignTokenMap<readonly ['light', 'dark']>);\n</script>\n\n<Theme {designTokens} transition=\"radial-top-right\">\n\t{#snippet children(theme)}\n\t\t<button onclick={() => (spacing = spacing === 'small' ? 'large' : 'small')}>\n\t\t\tChange density\n\t\t</button>\n\t\t<button onclick={() => (theme.theme = theme.resolvedTheme === 'dark' ? 'light' : 'dark')}>\n\t\t\tToggle color scheme\n\t\t</button>\n\t{/snippet}\n</Theme>\n```\n\n`designTokens` is keyed by logical theme name and respects the `attribute` and `value` props.\nEleven presets ship as `themePresets` (`dense`, `compact`, `balanced`, `comfortable`, `spacious`,\n`sharp`, `rounded`, `display`, `editorial`, `glass`, `terminal`): `designTokens={{ light: themePresets.glass.tokens, dark: themePresets.glass.tokens }}`.\nChanging the controlled object updates already-rendered Tailwind utilities without rebuilding CSS.\n\n### ThemeDesignTokens\n\n- `spacing`: `'small' | 'normal' | 'large' | number`. Globally scales density.\n- `spacingScale`: partial overrides for the strictly increasing `xs`, `sm`, `md`, `lg`,\n  and `xl` spacing multipliers. Defaults to 1/1.5/2/3/4.\n- `radius`: `'none' | 'subtile' | 'small' | 'normal' | 'large' | 'round' | number`.\n  Controls take the full multiplier; surface steps (`lg` and up) stop at `large` (1.5\u00D7).\n- `typeScale`: `'compact' | 'default' | 'comfortable' | 'large' | TypeScaleOptions`.\n- `raisedWithBorder`: toggles the border used by `raised-*` utilities.\n- `defaultColor`: `Colors` role kit chrome inherits when a control omits `color`.\n  Defaults to `neutral`. Set `primary` to restore an accent-colored kit. Compiles the\n  current-color family (`--color`, `--color-readable`, muted/contrast/light/dark variants)\n  and `--default-color` onto the theme selector. Do not set `data-color` on `html`.\n- `focusColor`, `selectedColor`, `hoverColor`, `pressedColor`: the four `Colors` **state\n  roles**. They pin, for the whole theme, what a focus ring, a persistent selection and the\n  transient hover/pressed layer look like, independently of the role of the control the state\n  lands on. They compile `--color-focus`, `--color-selected` (plus its `-contrast`,\n  `-readable` and `-muted-readable` companions), `--color-hover` and\n  `--color-pressed` onto the theme selector. There is no `--color-selected-muted`: the soft\n  fill is a translucent tint of `--color-selected` at `--state-selected-opacity`, so it reads\n  on any surface. None is declared at `:root`: every use site\n  falls back to the matching current role (`ring-focus` is\n  `var(--color-focus, var(--color))`, `bg-selected-muted` tints\n  `var(--color-selected, var(--color))`, the state layer is\n  `var(--color-hover, currentColor)` and on `:active`\n  `var(--color-pressed, var(--color-hover, currentColor))`), so leaving them unset changes\n  nothing and `data-color` keeps moving the states with `--color`. Theme-level only: there is\n  no per-component override. An unknown role throws.\n\nComponent-level density remains a local variant. It selects utility classes whose values inherit\nthe active global spacing token.\n\nGenerated interfaces should use the public `xs | sm | md | lg | xl` vocabulary through component\nprops and named gap/padding utilities. `micro` and `layout-*` are internal recipe tokens. Prefer\nparent-owned gaps over child margins; do not emit arbitrary spacing or unsupported radius values.\n\n## Theme selection\n\nThe selection props wrap `svelte-themes`: `themes`, `defaultTheme`, `forcedTheme`,\n`systemTheme`, `syncColorScheme`, `transitionOnChange`, `storageKey`, `attribute`,\n`value`, and `colorScheme`. The default themes are light and dark, with system selection\nenabled. `systemTheme`, `syncColorScheme`, and `transitionOnChange` all default to\n`true`; they map onto the library's `enableSystem`, `enableColorScheme`, and\n`disableTransitionOnChange` options.\n\n`ThemeState` exposes `theme`, `resolvedTheme`, `themes`, and `systemTheme`. Assign\n`theme.theme` to switch themes. The optional `transition` prop applies a named view transition;\nunsupported browsers and reduced-motion users switch instantly. Pass\n`{ type, duration, easing }` instead of a name to tune its timing, e.g.\n`transition={{ type: 'radial-top-right', duration: 600 }}` (duration in ms; grid and shutter steps\nscale with it).\n\n`spinnerVariant` sets the global default spinner animation. The children snippet is required.\n\n## Motion tokens\n\nMotion is a token scale like spacing and radius: five duration steps and four easing roles.\n`motion` retunes them app-wide; an omitted token keeps its default.\n\n| Duration   | Default |     | Easing role  | Default       |\n| ---------- | ------- | --- | ------------ | ------------- |\n| `instant`  | 0ms     |     | `standard`   | `cubicInOut`  |\n| `fast`     | 100ms   |     | `enter`      | `cubicOut`    |\n| `normal`   | 200ms   |     | `exit`       | `cubicIn`     |\n| `slow`     | 300ms   |     | `emphasized` | `backOut`     |\n| `slower`   | 500ms   |     |              |               |\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme motion={{ duration: { normal: 150, slow: 260 }, easing: { standard: 'quintOut' } }}>\n\t{@render children()}\n</Theme>\n```\n\nThe Tailwind plugin emits the same scale as CSS variables on `html` (`--duration-normal`,\n`--ease-standard`, ...) plus the matching `duration-*` / `ease-*` utilities, so CSS transitions\nand Svelte transitions read one set of numbers. The `motion` prop rewrites those variables on\n`html` at runtime and `designTokens.motion` rewrites them again per theme, layered over the prop;\n`ThemeState.motion` resolves through the same two rungs, so the utilities and the presets never\ndisagree. `ThemeState.transition` is a deprecated alias for its `normal` duration and `standard`\neasing. Reduced motion resolves every duration to 0 and collapses the `--duration-*` variables via\nthe `data-entasis-reduce-motion` attribute on `html`.\n\nComponents keep their own transition in a reserved `motion` slot on their theme, so the `theme`\nprop covers motion as well as classes:\n\n```svelte\n<script lang=\"ts\">\n\timport { Dialog } from 'entasis/dialog';\n</script>\n\n<Dialog theme={{ motion: { duration: 'fast', easing: 'emphasized' } }} title=\"Quick\">Body</Dialog>\n```\n\n## Component theme registry\n\n`components` sets app-wide component theme defaults without a wrapper component per component:\nit is keyed by theme name (`dialog`, `button`, ...) and each entry takes the same slots as that\ncomponent's `theme` prop, the `motion` slot included. A `set<Component>Theme` call in a subtree\nbeats the registry, and an instance `theme` prop beats both \u2014 per slot: each rung layers on the one\nbelow it, so a subtree that restyles one slot keeps the registry's others.\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme\n\tcomponents={{\n\t\tdialog: { motion: { duration: 'fast' }, content: { base: 'rounded-2xl' } },\n\t\tbutton: { root: { base: 'tracking-wide' } }\n\t}}\n>\n\t{@render children()}\n</Theme>\n```\n\n## Reduced motion\n\n`reduceMotion` forces reduced motion on (`true`) or off (`false`) for every entasis animation,\noverriding the OS `prefers-reduced-motion` setting; omit it to follow the OS. The live result is\nexposed as `ThemeState.preferReducesMotion` (reactive, so it updates when the OS setting changes)\nand mirrored as a `data-entasis-reduce-motion` attribute on `html` for CSS-only animations.\n\n```svelte\n<script>\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme reduceMotion>{@render children()}</Theme>\n```\n\n## Content Security Policy\n\n`nonce` is stamped on every `<script>` and `<style>` the Theme and the components below it\ninject: the theme and viewport boot scripts, the design-token stylesheet, the `transitionOnChange={false}`\nstyle, and the CDN loaders of PhoneInput, Map and Mermaid (the document print frame and Mermaid's own\nsvg `<style>` too). Drag-and-drop base styles are rules in the Tailwind plugin CSS, so nothing is\ninjected for them. Generate one nonce per request in `hooks.server.ts`, send it through `locals` to\n`<Theme nonce>`, and send the Content-Security-Policy header yourself with that same nonce.\nSvelteKit's `kit.csp` cannot be used for this: it generates its own nonce per request, exposes it\nonly as `%sveltekit.nonce%` in `app.html`, and has no option to take yours, so the header would\ncarry one nonce while the Theme's tags carry another. Leave `kit.csp` unset and put the nonce on\nSvelteKit's own inline tags in `transformPageChunk`:\n\n```ts\n// doc-fence: skip (needs nonce declared on the app's App.Locals)\n// src/hooks.server.ts\nimport type { Handle } from '@sveltejs/kit';\n\nexport const handle: Handle = async ({ event, resolve }) => {\n\tconst nonce = crypto.randomUUID();\n\tevent.locals.nonce = nonce;\n\tconst response = await resolve(event, {\n\t\t// Adds the nonce to SvelteKit's inline <script> and <style> tags; tags that already carry one\n\t\t// (the Theme's) are left alone.\n\t\ttransformPageChunk: ({ html }) =>\n\t\t\thtml.replace(/<(script|style)(?=[\\s>])(?![^>]*\\snonce=)/g, `<$1 nonce=\"${nonce}\"`)\n\t});\n\tresponse.headers.set(\n\t\t'content-security-policy',\n\t\t`script-src 'self' 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; style-src-attr 'unsafe-inline'`\n\t);\n\treturn response;\n};\n```\n\n```ts\n// doc-fence: skip (needs nonce declared on the app's App.Locals)\n// src/routes/+layout.server.ts\nimport type { LayoutServerLoad } from './$types';\n\nexport const load: LayoutServerLoad = ({ locals }) => ({ nonce: locals.nonce });\n```\n\n```svelte\n<!-- src/routes/+layout.svelte -->\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { data, children } = $props();\n</script>\n\n<Theme nonce={data.nonce}>\n\t{@render children()}\n</Theme>\n```\n\nServer-rendered `style` attributes (`style:` directives) are not covered by a nonce: allow them with\n`style-src-attr 'unsafe-inline'` (as above). `ThemeState.nonce` exposes the value to your own injected code.\n\n## Shadow DOM and portal containers\n\nDialogs, popovers, menus, tooltips and the floating-window layer mount in `document.body`. Inside a\nshadow root they mount in that root so adopted styles keep applying. `portalContainer` overrides both:\nan element or shadow root, or a function returning one for a container that is not rendered yet.\nA function that reads `$state` (as below) moves the floating-window layer in as soon as the container\nappears; a function over a plain variable is read each time a panel mounts, so the layer, which mounts\nwith the Theme, needs the container to exist by then.\nOutside presses and Escape are heard on the document a panel lives in, so a panel rendered into an\niframe's document dismisses correctly.\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n\tlet host = $state<HTMLElement>();\n</script>\n\n<div bind:this={host}></div>\n<Theme portalContainer={() => host}>\n\t{@render children()}\n</Theme>\n```\n\nWhen several Themes are mounted, the most recently mounted one that sets `portalContainer` wins.\n\n## Scroll lock and viewport variables\n\nA dialog or popover locks page scroll with a `data-entasis-scroll-lock` attribute on `<html>` and one\nrule in the Tailwind plugin CSS (`overflow: hidden`); nothing is written to inline styles, so a lock a\nthird-party library holds on the same element is neither overwritten nor released early. While\nlocked, the hidden scrollbar's room is kept with `scrollbar-gutter: stable` (the lock measures the\npage and pads the scrollbar's width instead where the gutter does not hold) unless the page already reserves a gutter, so there is no double gutter. Two variables\ndescribe the viewport for your own layout:\n\n- `--entasis-scrollbar-width`: set on `<html>` while locked, the width in px of the scrollbar the\n  lock hides (`0px` with overlay scrollbars). Add it to `position: fixed` bars:\n  `padding-inline-end: var(--entasis-scrollbar-width, 0px)`.\n- `--keyboard-inset`: the height in px the on-screen keyboard covers at the bottom of the layout\n  viewport, measured from the visual viewport (`0px` without a keyboard, while pinch-zoomed, and in\n  browsers that resize the layout viewport for the keyboard). Pin a bottom bar above the keyboard with\n  `bottom: var(--keyboard-inset)`.\n- `--visual-viewport-top`: how far in px the visible area starts below the top of the layout\n  viewport. iOS scrolls it down to bring a focused field above the keyboard, and fixed content then\n  starts above the screen; pad it by this to keep it visible (`0px` without a keyboard and while\n  pinch-zoomed). The layout viewport is the larger of `innerHeight` and the root's\n  `clientHeight`, because iOS 26 shrinks `innerHeight` along with the keyboard.\n\nOn iOS, the same script adds `maximum-scale=1` to the page's `<meta name=\"viewport\">` (when it\nsets no `maximum-scale` of its own). Safari otherwise zooms the page into any text field below\n16px when it takes focus and leaves it zoomed. iOS ignores the limit for the user's own pinch zoom,\nso the page stays zoomable; other platforms would honour it, so they are left alone.\n\n## Build-time boundary\n\nThe Tailwind plugin still generates color palettes and registers utility names, variants,\nkeyframes, and spinner CSS. Spacing, radius, typography scale, raised borders,\n`defaultColor` and the four state roles (`focusColor`, `selectedColor`, `hoverColor`,\n`pressedColor`) belong to `Theme.designTokens`; colors remain CSS variables and can be\noverridden directly. `ThemeState.defaultColor` exposes the active role. Kit chrome should\nresolve omitted `color` props with `useDefaultColor`.\n";

package/dist/components/Theme/theme.mcp.js

@@ -98,7 +98,10 @@ enabled. \`systemTheme\`, \`syncColorScheme\`, and \`transitionOnChange\` all de
 
 \`ThemeState\` exposes \`theme\`, \`resolvedTheme\`, \`themes\`, and \`systemTheme\`. Assign
 \`theme.theme\` to switch themes. The optional \`transition\` prop applies a named view transition;
-unsupported browsers and reduced-motion users switch instantly.
+unsupported browsers and reduced-motion users switch instantly. Pass
+\`{ type, duration, easing }\` instead of a name to tune its timing, e.g.
+\`transition={{ type: 'radial-top-right', duration: 600 }}\` (duration in ms; grid and shutter steps
+scale with it).
 
 \`spinnerVariant\` sets the global default spinner animation. The children snippet is required.
 
@@ -291,6 +294,16 @@ describe the viewport for your own layout:
   viewport, measured from the visual viewport (\`0px\` without a keyboard, while pinch-zoomed, and in
   browsers that resize the layout viewport for the keyboard). Pin a bottom bar above the keyboard with
   \`bottom: var(--keyboard-inset)\`.
+- \`--visual-viewport-top\`: how far in px the visible area starts below the top of the layout
+  viewport. iOS scrolls it down to bring a focused field above the keyboard, and fixed content then
+  starts above the screen; pad it by this to keep it visible (\`0px\` without a keyboard and while
+  pinch-zoomed). The layout viewport is the larger of \`innerHeight\` and the root's
+  \`clientHeight\`, because iOS 26 shrinks \`innerHeight\` along with the keyboard.
+
+On iOS, the same script adds \`maximum-scale=1\` to the page's \`<meta name="viewport">\` (when it
+sets no \`maximum-scale\` of its own). Safari otherwise zooms the page into any text field below
+16px when it takes focus and leaves it zoomed. iOS ignores the limit for the user's own pinch zoom,
+so the page stays zoomable; other platforms would honour it, so they are left alone.
 
 ## Build-time boundary
 

package/dist/components/Theme/theme.props.d.ts

@@ -2,7 +2,7 @@ import type { Snippet } from 'svelte';
 import type { SvelteThemeProps } from 'svelte-themes';
 import type { SpinnerVariant } from '../Spinner/spinner.props.js';
 import type { ThemeState } from './theme.state.svelte.js';
-import type { ThemeTransition } from './themeTransition.js';
+import type { ThemeTransitionInput } from './themeTransition.js';
 import type { ThemeDesignTokenMap } from './theme.designTokens.js';
 import type { DeepPartial, MotionTokens } from '../../tailwind/scales.js';
 import type { ComponentThemeRegistry } from '../../utils/cva/theme.js';
@@ -28,8 +28,11 @@ export type ThemeProps<T extends readonly string[] = readonly string[]> = Omit<S
     spinnerVariant?: SpinnerVariant;
     /** Runtime design tokens keyed by logical theme name. */
     designTokens?: ThemeDesignTokenMap<T>;
-    /** View transition used when ThemeState.theme changes. Omit for an instant change. */
-    transition?: ThemeTransition;
+    /**
+     * View transition used when ThemeState.theme changes: a variation name, or
+     * `{ type, duration, easing }` to tune its timing (duration in ms). Omit for an instant change.
+     */
+    transition?: ThemeTransitionInput;
     /**
      * Forces reduced motion on (`true`) or off (`false`) for every entasis animation.
      * Omit to follow the user's OS reduced-motion setting.

package/dist/components/Theme/theme.state.svelte.d.ts

@@ -10,7 +10,7 @@ import { LayerStack } from '../../utils/layers.svelte.js';
 import { HoverIntentGroup } from '../../utils/hoverIntent.js';
 import type { TooltipOptions } from '../Tooltip/tooltip.props.js';
 import type { ConfirmationHost } from '../Confirmation/confirmation.state.svelte.js';
-import { type ThemeTransition } from './themeTransition.js';
+import { type ThemeTransitionInput } from './themeTransition.js';
 import { ThemeFloatingWindows } from './theme.floatingWindows.js';
 import type { Colors } from '../../types/theme.js';
 import { type PortalContainerSource } from '../../attachments/portal.js';
@@ -26,7 +26,7 @@ type EventPayload = {
 type ThemeEventListener = (event: never) => void;
 interface ThemeOptions {
     readonly spinnerVariant: SpinnerVariant;
-    readonly themeTransition?: ThemeTransition;
+    readonly themeTransition?: ThemeTransitionInput;
     readonly defaultColor?: Colors;
     readonly reduceMotion?: boolean;
     /** The partial scale passed as `<Theme motion>`; `motion` below is the resolved one. */

package/dist/components/Theme/theme.state.svelte.js

@@ -1,6 +1,6 @@
 import { createBindableStateClass } from '../../utils/state.svelte.js';
 import { getContext, onDestroy, onMount, setContext, tick } from 'svelte';
-import { browser } from '$app/environment';
+import { BROWSER as browser } from 'esm-env';
 import { MediaQuery } from 'svelte/reactivity';
 import { resolveResponsive } from './responsive.js';
 import { resolveMotionTokens } from '../../tailwind/scales.js';

package/dist/components/Theme/themeTransition.d.ts

@@ -1,3 +1,16 @@
 export declare const themeTransitions: readonly ["radial-top-left", "radial-top-right", "radial-bottom-left", "radial-bottom-right", "line-top", "line-right", "line-bottom", "line-left", "shutter-top", "shutter-right", "shutter-bottom", "shutter-left", "random-grid", "column-grid-left", "column-grid-right"];
 export type ThemeTransition = (typeof themeTransitions)[number];
-export declare function updateThemeWithTransition(transition: ThemeTransition | undefined, update: () => void | Promise<void>): void;
+/** A theme transition with its timing tuned. Left out, each keeps the variation's own value. */
+export type ThemeTransitionOptions = {
+    /** The variation. */
+    type: ThemeTransition;
+    /** Length of the whole reveal in ms; grid and shutter steps scale with it. */
+    duration?: number;
+    /** CSS easing of the reveal. Grid variations step from cell to cell whatever the easing. */
+    easing?: string;
+};
+/** A variation name, or the variation with its duration and easing. */
+export type ThemeTransitionInput = ThemeTransition | ThemeTransitionOptions;
+/** The options form of a transition input. */
+export declare function resolveThemeTransition(transition: ThemeTransitionInput | undefined): ThemeTransitionOptions | undefined;
+export declare function updateThemeWithTransition(input: ThemeTransitionInput | undefined, update: () => void | Promise<void>): void;

package/dist/components/Theme/themeTransition.js

@@ -15,6 +15,12 @@ export const themeTransitions = [
     'column-grid-left',
     'column-grid-right'
 ];
+/** The options form of a transition input. */
+export function resolveThemeTransition(transition) {
+    if (!transition)
+        return undefined;
+    return typeof transition === 'string' ? { type: transition } : transition;
+}
 const radialOrigins = {
     'radial-top-left': '0% 0%',
     'radial-top-right': '100% 0%',
@@ -32,14 +38,23 @@ const SHUTTER_PHASES_PER_BAND = 3;
 const SHUTTER_START_INTERVAL = 1;
 const SHUTTER_PHASE_DURATION = 50;
 let activeTransitionId = 0;
-export function updateThemeWithTransition(transition, update) {
+export function updateThemeWithTransition(input, update) {
+    const options = resolveThemeTransition(input);
+    const transition = options?.type;
     if (!canAnimateThemeChange(transition)) {
         void update();
         return;
     }
     const root = document.documentElement;
     const transitionId = ++activeTransitionId;
-    const animation = createThemeTransitionAnimation(transition);
+    const variation = createThemeTransitionAnimation(transition);
+    const animation = {
+        ...variation,
+        duration: options?.duration !== undefined && Number.isFinite(options.duration) && options.duration >= 0
+            ? options.duration
+            : variation.duration,
+        easing: options?.easing ?? variation.easing
+    };
     root.dataset.entasisThemeTransition = transition;
     let viewTransition;
     try {