entasis 0.7.1 → 0.8.0

package/dist/components/Sidebar/sidebar.views.svelte.js

@@ -0,0 +1,303 @@
+import { untrack } from 'svelte';
+import { easingFunctions } from '../../transitions/easingFunctions.js';
+import { createPointerDrag } from '../../utils/pointerDrag.js';
+import { createBindableValue } from '../../utils/state.svelte.js';
+/** The header and footer props a view can set; together they are the panel's chrome. */
+const chromeProps = [
+    'header',
+    'headerButton',
+    'search',
+    'headerMenu',
+    'footerButton',
+    'footerMenu',
+    'footer'
+];
+/** The view and its ancestors, nearest first. A missing parent or a parent cycle ends the chain. */
+export const viewChain = (views, id) => {
+    const chain = [];
+    for (let key = id; key !== undefined && key in views;) {
+        if (chain.includes(key))
+            break;
+        chain.push(key);
+        key = views[key].parent;
+    }
+    return chain;
+};
+/**
+ * Resolves one header or footer prop for a view: the nearest view in the chain that sets it
+ * (`null` counts, and clears it), else the Sidebar. `owner` names where it came from, so two
+ * views share the slot exactly when it resolves to the same owner.
+ */
+export const resolveSlot = (views, id, slot, root) => {
+    const owner = viewChain(views, id).find((key) => views[key][slot] !== undefined);
+    const value = owner === undefined ? root[slot] : views[owner][slot];
+    return { owner: owner ?? null, value: (value ?? undefined) };
+};
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const cssLength = (value) => typeof value === 'number' ? `${value}px` : (value ?? '0px');
+export class SidebarViewsState {
+    options;
+    swipe = $state(null);
+    rtl = $state(false);
+    #selected;
+    #shown;
+    #lastChange = {
+        direction: 'none'
+    };
+    constructor(options) {
+        this.options = options;
+        this.#selected = createBindableValue(() => options.view, (view) => options.setViewProp(view), () => options.defaultView);
+        // A committed swipe lets go once the view it asked for is on screen; any other view change
+        // (a route, a parent update) ends the swipe on the spot.
+        $effect(() => {
+            const swipe = this.swipe;
+            if (!swipe)
+                return;
+            const current = this.current;
+            if ((swipe.settled && current === swipe.to) ||
+                (current !== swipe.from && current !== swipe.to))
+                this.swipe = null;
+        });
+        this.#shown = untrack(() => this.current);
+    }
+    get enabled() {
+        return !!this.options.views && Object.keys(this.options.views).length > 0;
+    }
+    /** The view on screen: the selected one when it exists, else `defaultView`, else the first. */
+    get current() {
+        const views = this.options.views;
+        if (!views)
+            return undefined;
+        const selected = this.#selected.value;
+        if (selected !== undefined && selected in views)
+            return selected;
+        const fallback = this.options.defaultView;
+        return fallback !== undefined && fallback in views ? fallback : Object.keys(views)[0];
+    }
+    depth(id) {
+        return this.options.views ? viewChain(this.options.views, id).length - 1 : 0;
+    }
+    parentOf(id) {
+        const parent = this.options.views?.[id]?.parent;
+        return parent !== undefined && parent in (this.options.views ?? {}) ? parent : undefined;
+    }
+    labelOf(id) {
+        return this.options.views?.[id]?.label;
+    }
+    /**
+     * The last change of the current view and its direction, read by the layer transitions when
+     * they start. Deeper slides forward and shallower slides back; at one depth (sections), the
+     * later view in `views` is forward, like pages in order.
+     */
+    get lastChange() {
+        const to = this.current;
+        if (to === this.#shown)
+            return this.#lastChange;
+        const from = this.#shown;
+        this.#shown = to;
+        if (from === undefined || to === undefined) {
+            this.#lastChange = { from, to, direction: 'none' };
+            return this.#lastChange;
+        }
+        const order = Object.keys(this.options.views ?? {});
+        const delta = this.depth(to) - this.depth(from) || order.indexOf(to) - order.indexOf(from);
+        this.#lastChange = { from, to, direction: delta < 0 ? 'back' : 'forward' };
+        return this.#lastChange;
+    }
+    setView = (view) => {
+        if (!this.options.views || !(view in this.options.views) || view === this.current)
+            return;
+        this.#selected.value = view;
+        this.options.onViewChange?.(view);
+    };
+    /** A view's body. */
+    body(view) {
+        const entry = this.options.views?.[view];
+        return { items: entry?.items, content: entry?.content };
+    }
+    /** A view's header and footer props, each from the nearest view that sets it, else the Sidebar. */
+    chrome(view) {
+        const chrome = {};
+        for (const prop of chromeProps) {
+            const { value } = resolveSlot(this.options.views ?? {}, view, prop, this.options.root);
+            if (value != null)
+                Object.assign(chrome, { [prop]: value });
+        }
+        return chrome;
+    }
+    /**
+     * The layers a stage renders, bottom first. Outside a swipe that is the current view alone;
+     * during one it is the parent under the view being swiped away. Two views that share a layer
+     * key collapse to one layer that never moves: the panel's key is where its chrome comes from,
+     * so views with the same header and footer keep one panel and only their bodies slide.
+     */
+    layers(kind) {
+        const current = this.current;
+        if (current === undefined)
+            return [];
+        const swipe = this.swipe;
+        const entries = swipe
+            ? [
+                { view: swipe.to, role: 'under' },
+                { view: swipe.from, role: 'over' }
+            ]
+            : [{ view: current }];
+        const layers = [];
+        for (const entry of entries) {
+            const key = kind === 'body' ? entry.view : this.#chromeKey(entry.view);
+            const shared = layers.find((layer) => layer.key === key);
+            if (shared)
+                shared.role = undefined;
+            else
+                layers.push({ key, ...entry });
+        }
+        return layers;
+    }
+    #chromeKey(view) {
+        const views = this.options.views ?? {};
+        return chromeProps
+            .map((prop) => resolveSlot(views, view, prop, this.options.root).owner ?? '')
+            .join('|');
+    }
+    /**
+     * A swipe layer's drag position, as `translate` / `opacity` styles; empty at rest. The view
+     * under the finger stays opaque and follows it; its parent comes from `travel` toward the
+     * start and from `opacity`, the same way the view motion brings a view in.
+     */
+    swipeStyle(role, travel, opacity) {
+        const swipe = this.swipe;
+        if (!swipe || !role)
+            return {};
+        const sign = this.rtl ? -1 : 1;
+        const rest = `calc(${cssLength(travel)} * ${-sign})`;
+        const progress = swipe.width ? swipe.offset / swipe.width : 0;
+        if (swipe.phase === 'drag') {
+            if (role === 'over')
+                return {
+                    translate: `${swipe.offset * sign}px`,
+                    opacity: 1 - (1 - opacity) * progress
+                };
+            return {
+                translate: `calc(${cssLength(travel)} * ${-sign * (1 - progress)})`,
+                opacity: opacity + (1 - opacity) * progress
+            };
+        }
+        // Settling: a committed view leaves to the inline end; a cancelled parent returns under it.
+        if (role === 'over')
+            return swipe.phase === 'commit' ? { translate: `${100 * sign}%`, opacity } : {};
+        return swipe.phase === 'cancel' ? { translate: rest, opacity } : {};
+    }
+    get canSwipeBack() {
+        const current = this.current;
+        return this.options.isMobile && current !== undefined && !!this.parentOf(current);
+    }
+    /**
+     * The mobile drawer dismisses on a swipe toward its own edge. When going back points the same
+     * way (a right drawer in LTR, a left one in RTL), the view body keeps the gesture.
+     */
+    get ownsDrawerSwipe() {
+        return this.canSwipeBack && (this.rtl ? -1 : 1) === (this.options.side === 'right' ? 1 : -1);
+    }
+    /** Called by the body stage once a settling swipe has had its motion duration. */
+    settleSwipe() {
+        const swipe = this.swipe;
+        if (!swipe || swipe.phase === 'drag')
+            return;
+        if (swipe.phase === 'cancel' || this.current === swipe.to)
+            this.swipe = null;
+        else
+            swipe.settled = true;
+        // ponytail: a controlled `view` that ignores `onViewChange` leaves the swipe parked off
+        // screen until some view change lands; fine for a consumer bug, revisit if one shows up.
+    }
+    /** Back swipe on the view body: toward the inline end, anywhere on the body, mobile only. */
+    swipeAttachment = (node) => {
+        this.rtl = getComputedStyle(node).direction === 'rtl';
+        let candidate = false;
+        let sign = 1;
+        let lastX = 0;
+        let lastTime = 0;
+        let velocity = 0;
+        const release = (cancelled, timeStamp) => {
+            candidate = false;
+            const swipe = this.swipe;
+            if (swipe?.phase !== 'drag')
+                return;
+            // A long stationary hold is not a flick: the last velocity sample may be stale.
+            if (timeStamp - lastTime > 100)
+                velocity = 0;
+            const commit = !cancelled && (velocity > 0.4 || (swipe.offset > swipe.width * 0.35 && velocity > -0.2));
+            swipe.phase = commit ? 'commit' : 'cancel';
+            if (commit)
+                this.setView(swipe.to);
+        };
+        return createPointerDrag({
+            disabled: () => !this.canSwipeBack || this.swipe !== null,
+            // The body is a region full of rows, not a handle: a press that never travels keeps its click.
+            capture: 'on-activate',
+            onDown: ({ event }) => {
+                candidate = true;
+                this.rtl = getComputedStyle(node).direction === 'rtl';
+                sign = this.rtl ? -1 : 1;
+                lastX = event.clientX;
+                lastTime = event.timeStamp;
+                velocity = 0;
+            },
+            // Horizontal toward the inline end, clearly more than vertical: anything else is a scroll.
+            shouldActivate: ({ deltaX, deltaY }) => {
+                if (!candidate)
+                    return false;
+                const forward = deltaX * sign;
+                if (forward > 8 && forward > Math.abs(deltaY) * 1.5)
+                    return true;
+                if (Math.abs(deltaX) > 8 || Math.abs(deltaY) > 8)
+                    candidate = false;
+                return false;
+            },
+            onStart: () => {
+                const from = this.current;
+                const to = from === undefined ? undefined : this.parentOf(from);
+                if (from === undefined || to === undefined)
+                    return false;
+                this.swipe = { from, to, phase: 'drag', offset: 0, width: node.offsetWidth };
+            },
+            onMove: ({ event, deltaX }) => {
+                const swipe = this.swipe;
+                if (swipe?.phase !== 'drag')
+                    return;
+                swipe.offset = clamp(deltaX * sign, 0, swipe.width);
+                const elapsed = event.timeStamp - lastTime;
+                if (elapsed >= 8) {
+                    velocity = ((event.clientX - lastX) * sign) / elapsed;
+                    lastX = event.clientX;
+                    lastTime = event.timeStamp;
+                }
+            },
+            onEnd: ({ event }) => release(false, event.timeStamp),
+            onCancel: ({ event }) => release(true, event.timeStamp)
+        })(node);
+    };
+}
+/**
+ * Pager motion between views. Forward, the new view comes from the inline end and the old one
+ * leaves to the start, side by side, each travelling the motion's `x` and fading along the whole
+ * way; back mirrors it. A layer a swipe put in place is already where it belongs, so it enters
+ * and leaves without motion.
+ */
+export const sidebarViewTransition = (node, { phase, direction, motion }) => {
+    if (phase === 'out')
+        node.style.pointerEvents = 'none';
+    const side = phase === 'in' ? motion.in : motion.out;
+    const duration = side.duration ?? 0;
+    if (node.dataset.swipe || direction === 'none' || duration === 0)
+        return { duration: 0 };
+    const travel = cssLength(side.x);
+    const rest = side.opacity ?? 0;
+    const rtl = getComputedStyle(node).direction === 'rtl' ? -1 : 1;
+    const sign = rtl * (direction === 'back' ? -1 : 1) * (phase === 'in' ? 1 : -1);
+    return {
+        duration,
+        easing: easingFunctions[side.easing ?? 'cubicOut'],
+        css: (t, u) => `transform: translateX(calc(${travel} * ${u * sign})); opacity: ${rest + (1 - rest) * t}`
+    };
+};

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

@@ -14,7 +14,12 @@ export declare class ThemeFloatingWindows {
     private surfaces;
     readonly layer: Attachment<HTMLElement>;
     readonly portal: Attachment<HTMLElement>;
-    activate(id: string, type: FloatingWindowSurface): number;
+    /**
+     * Brings a surface to the top. `reserveBelow` also claims the index just under it, for a
+     * window's backdrop: the counter never hands an index out twice, so no other surface can land
+     * between a window and its backdrop.
+     */
+    activate(id: string, type: FloatingWindowSurface, reserveBelow?: boolean): number;
     unregisterSurface(id: string, type: FloatingWindowSurface): void;
     isTopWindow(id: string): boolean;
     registerDock(entry: FloatingWindowDockEntry): () => void;

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

@@ -20,8 +20,13 @@ export class ThemeFloatingWindows {
             node.remove();
         };
     };
-    activate(id, type) {
-        this.zIndex += 1;
+    /**
+     * Brings a surface to the top. `reserveBelow` also claims the index just under it, for a
+     * window's backdrop: the counter never hands an index out twice, so no other surface can land
+     * between a window and its backdrop.
+     */
+    activate(id, type, reserveBelow = false) {
+        this.zIndex += reserveBelow ? 2 : 1;
         this.surfaces.set(id, { type, zIndex: this.zIndex });
         return this.zIndex;
     }

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.\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- `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## 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.\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## 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

@@ -54,6 +54,7 @@ Changing the controlled object updates already-rendered Tailwind utilities witho
 - \`spacingScale\`: partial overrides for the strictly increasing \`xs\`, \`sm\`, \`md\`, \`lg\`,
   and \`xl\` spacing multipliers. Defaults to 1/1.5/2/3/4.
 - \`radius\`: \`'none' | 'subtile' | 'small' | 'normal' | 'large' | 'round' | number\`.
+  Controls take the full multiplier; surface steps (\`lg\` and up) stop at \`large\` (1.5×).
 - \`typeScale\`: \`'compact' | 'default' | 'comfortable' | 'large' | TypeScaleOptions\`.
 - \`raisedWithBorder\`: toggles the border used by \`raised-*\` utilities.
 - \`defaultColor\`: \`Colors\` role kit chrome inherits when a control omits \`color\`.

package/dist/generated/componentContract.d.ts

@@ -361,7 +361,7 @@ export declare const componentInventory: readonly [{
     readonly id: "sidebar";
     readonly subpath: "entasis/sidebar";
     readonly sourceIndex: "src/lib/components/Sidebar/index.ts";
-    readonly exportedSymbols: readonly ["Sidebar", "SidebarActiveVariant", "SidebarActivityBar", "SidebarActivityBarItem", "SidebarActivityBarSelectPayload", "SidebarApi", "SidebarCollapsible", "SidebarDensity", "SidebarDisplayState", "SidebarFrame", "SidebarGroup", "SidebarIcon", "SidebarIconVariant", "SidebarMenuActionDescriptor", "SidebarMenuAlign", "SidebarMenuButton", "SidebarMenuButtonItem", "SidebarMenuButtonSize", "SidebarMenuButtonVariant", "SidebarMenuEntry", "SidebarMenuSide", "SidebarMenuSubEntry", "SidebarMode", "SidebarProps", "SidebarRail", "SidebarResizable", "SidebarResizableOptions", "SidebarSearch", "SidebarSide", "SidebarSize", "SidebarState", "SidebarTheme", "SidebarThemeProps", "SidebarTooltipMode", "SidebarTreeNode", "SidebarVariant", "SidebarWidthChangePayload", "setSidebarTheme", "sidebarDescription", "sidebarTheme", "useSidebarTheme"];
+    readonly exportedSymbols: readonly ["Sidebar", "SidebarActiveVariant", "SidebarActivityBar", "SidebarActivityBarItem", "SidebarActivityBarSelectPayload", "SidebarApi", "SidebarCollapsible", "SidebarDensity", "SidebarDisplayState", "SidebarFrame", "SidebarGroup", "SidebarIcon", "SidebarIconVariant", "SidebarMenuActionDescriptor", "SidebarMenuAlign", "SidebarMenuButton", "SidebarMenuButtonItem", "SidebarMenuButtonSize", "SidebarMenuButtonVariant", "SidebarMenuEntry", "SidebarMenuSide", "SidebarMenuSubEntry", "SidebarMode", "SidebarProps", "SidebarRail", "SidebarResizable", "SidebarResizableOptions", "SidebarSearch", "SidebarSide", "SidebarSize", "SidebarState", "SidebarTheme", "SidebarThemeProps", "SidebarTooltipMode", "SidebarTreeNode", "SidebarVariant", "SidebarView", "SidebarWidthChangePayload", "setSidebarTheme", "sidebarDescription", "sidebarTheme", "useSidebarTheme"];
     readonly docs: readonly [{
         readonly id: "sidebar";
         readonly route: "/components/sidebar";

package/dist/generated/componentContract.js

@@ -932,6 +932,7 @@ export const componentInventory = [
             'SidebarTooltipMode',
             'SidebarTreeNode',
             'SidebarVariant',
+            'SidebarView',
             'SidebarWidthChangePayload',
             'setSidebarTheme',
             'sidebarDescription',