entasis 0.7.1 → 0.9.0

package/dist/components/Sidebar/sidebar.theme.js

@@ -111,6 +111,28 @@ const defaultNav = cva({
         density: 'normal'
     }
 });
+// With `views`, the panel and the menu inside it are one-cell grids whose layers are the views
+// they show: one at rest, two while they slide past each other. The cell clips the slide.
+const defaultViewStage = cva({
+    base: 'grid min-h-0 flex-1 grid-cols-1 grid-rows-1 overflow-x-clip'
+});
+// `translate` / `opacity` carry the swipe: they follow the finger with no transition while
+// dragging, then ease to rest. The view-change motion animates `transform`, so the two never fight.
+const defaultViewLayer = cva({
+    base: 'col-start-1 row-start-1 min-w-0 transition-[translate,opacity] ease-enter data-[dragging=true]:transition-none',
+    variants: {
+        // A body layer is its own scroll container, and `touch-action` only counts up to the nearest
+        // one: set on the layer, it leaves vertical scrolling to the browser and horizontal moves to
+        // the back swipe.
+        swipe: {
+            true: 'touch-pan-y',
+            false: null
+        }
+    },
+    defaultVariants: {
+        swipe: false
+    }
+});
 const defaultGroup = cva({
     base: 'relative flex w-full min-w-0 flex-col',
     variants: {
@@ -612,12 +634,19 @@ const defaultMain = cva({
         edgeRevealed: {
             true: '',
             false: ''
+        },
+        // Nothing of the sidebar is left beside the page: the panel is hidden and there is no
+        // activity bar. Only then does an inset or split page drop its frame and fill the edge; with
+        // an activity bar the rail stays on screen, so the page keeps its framed form.
+        flush: {
+            true: '',
+            false: ''
         }
     },
     compoundVariants: [
         {
             variant: ['inset', 'split'],
-            displayState: ['expanded', 'collapsed'],
+            flush: false,
             class: 'md:[--page-shell-edge-inset:0.5rem]'
         },
         {
@@ -642,15 +671,32 @@ const defaultMain = cva({
         },
         {
             variant: ['inset', 'split'],
-            displayState: 'hidden',
+            flush: true,
             class: 'md:p-0 md:rounded-none'
+        },
+        // A hidden split panel no longer separates the page from the activity bar's card: the page
+        // takes the gutter on that side itself, so the two cards stay apart.
+        {
+            variant: 'split',
+            displayState: 'hidden',
+            flush: false,
+            side: 'left',
+            class: 'md:pl-md'
+        },
+        {
+            variant: 'split',
+            displayState: 'hidden',
+            flush: false,
+            side: 'right',
+            class: 'md:pr-md'
         }
     ],
     defaultVariants: {
         variant: 'admin',
         side: 'left',
         displayState: 'expanded',
-        edgeRevealed: false
+        edgeRevealed: false,
+        flush: false
     }
 });
 const defaultEdgeTrigger = cva({
@@ -891,6 +937,24 @@ export const defaultSidebarMotion = motion({
         out: { axis: 'y', x: 0, y: 0, scale: 1, opacity: 0.2 },
         duration: 'normal',
         easing: 'standard'
+    },
+    variants: {
+        part: {
+            collapse: {},
+            // The pager between views: the arriving view comes from the inline end and the leaving
+            // one goes to the start, side by side, each travelling `x` while it fades between
+            // `opacity` and 1. `enter` easing moves on the first frame; an in-out curve would sit
+            // still for the first and last fifth and squeeze the whole swap into a blink.
+            view: {
+                in: { axis: 'x', x: '100%', opacity: 0 },
+                out: { axis: 'x', x: '100%', opacity: 0 },
+                duration: 'slow',
+                easing: 'enter'
+            }
+        }
+    },
+    defaultVariants: {
+        part: 'collapse'
     }
 });
 export const sidebarTheme = {
@@ -899,6 +963,8 @@ export const sidebarTheme = {
     panel: defaultPanel,
     header: defaultStackSection,
     nav: defaultNav,
+    viewStage: defaultViewStage,
+    viewLayer: defaultViewLayer,
     footer: defaultStackSection,
     group: defaultGroup,
     groupLabel: defaultGroupLabel,

package/dist/components/Sidebar/sidebar.views.svelte.d.ts

@@ -0,0 +1,138 @@
+import { type Snippet } from 'svelte';
+import type { TransitionConfig } from 'svelte/transition';
+import type { ResolvedMotion } from '../../utils/motion/index.js';
+import type { SidebarApi, SidebarGroup, SidebarMenuButtonItem, SidebarMenuEntry, SidebarSearch, SidebarSide, SidebarView } from './sidebar.props.js';
+/** What the panel renders for a view: the Sidebar's own props, or a view's resolved over its parents. */
+export type SidebarSlotValues = {
+    items?: SidebarGroup[];
+    content?: Snippet<[SidebarApi]>;
+    headerButton?: SidebarMenuButtonItem;
+    search?: SidebarSearch;
+    headerMenu?: SidebarMenuEntry[];
+    header?: Snippet<[SidebarApi]>;
+    footerButton?: SidebarMenuButtonItem;
+    footerMenu?: SidebarMenuEntry[];
+    footer?: Snippet<[SidebarApi]>;
+};
+/** The header and footer props a view can set; together they are the panel's chrome. */
+declare const chromeProps: readonly ["header", "headerButton", "search", "headerMenu", "footerButton", "footerMenu", "footer"];
+/**
+ * What slides on a view change. `body` is the menu alone; `panel` is the whole panel (header,
+ * menu, footer), which only swaps when the two views do not share the same chrome.
+ */
+export type SidebarViewKind = 'panel' | 'body';
+type Views = Record<string, SidebarView>;
+type PropSlot = (typeof chromeProps)[number];
+/** The view and its ancestors, nearest first. A missing parent or a parent cycle ends the chain. */
+export declare const viewChain: (views: Views, id: string) => string[];
+/**
+ * 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 declare const resolveSlot: <S extends PropSlot>(views: Views, id: string, slot: S, root: SidebarSlotValues) => {
+    owner: string | null;
+    value: SidebarSlotValues[S];
+};
+export type SidebarViewDirection = 'forward' | 'back' | 'none';
+/** Which half of a back swipe a layer plays: the view leaving (`over`) or its parent (`under`). */
+export type SidebarSwipeRole = 'over' | 'under';
+export type SidebarViewLayer = {
+    key: string;
+    view: string;
+    role?: SidebarSwipeRole;
+};
+type Swipe = {
+    from: string;
+    to: string;
+    /** `drag` follows the finger; `commit` / `cancel` animate to rest, then the swipe ends. */
+    phase: 'drag' | 'commit' | 'cancel';
+    /** Distance travelled toward the inline end, in px. */
+    offset: number;
+    width: number;
+    /** The commit has finished moving and waits for the view change to land (a route, say). */
+    settled?: boolean;
+};
+type SidebarViewsOptions = {
+    readonly views: Views | undefined;
+    readonly view: string | undefined;
+    readonly defaultView: string | undefined;
+    readonly onViewChange: ((view: string) => void) | undefined;
+    readonly isMobile: boolean;
+    readonly side: SidebarSide;
+    readonly root: SidebarSlotValues;
+    setViewProp: (view: string | undefined) => void;
+};
+export declare class SidebarViewsState {
+    #private;
+    private options;
+    swipe: Swipe | null;
+    rtl: boolean;
+    constructor(options: SidebarViewsOptions);
+    get enabled(): boolean;
+    /** The view on screen: the selected one when it exists, else `defaultView`, else the first. */
+    get current(): string | undefined;
+    depth(id: string): number;
+    parentOf(id: string): string | undefined;
+    labelOf(id: string): string | undefined;
+    /**
+     * 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(): {
+        from?: string;
+        to?: string;
+        direction: SidebarViewDirection;
+    };
+    setView: (view: string) => void;
+    /** A view's body. */
+    body(view: string): {
+        items: SidebarGroup[] | undefined;
+        content: Snippet<[SidebarApi]> | undefined;
+    };
+    /** A view's header and footer props, each from the nearest view that sets it, else the Sidebar. */
+    chrome(view: string): SidebarSlotValues;
+    /**
+     * 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: SidebarViewKind): SidebarViewLayer[];
+    /**
+     * 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: SidebarSwipeRole | undefined, travel: number | string, opacity: number): {
+        translate?: undefined;
+        opacity?: undefined;
+    } | {
+        translate: string;
+        opacity: number;
+    };
+    get canSwipeBack(): boolean;
+    /**
+     * 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(): boolean;
+    /** Called by the body stage once a settling swipe has had its motion duration. */
+    settleSwipe(): void;
+    /** Back swipe on the view body: toward the inline end, anywhere on the body, mobile only. */
+    swipeAttachment: (node: HTMLElement) => void | (() => void);
+}
+type ViewTransitionParams = {
+    phase: 'in' | 'out';
+    direction: SidebarViewDirection;
+    motion: ResolvedMotion;
+};
+/**
+ * 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 declare const sidebarViewTransition: (node: HTMLElement, { phase, direction, motion }: ViewTransitionParams) => TransitionConfig;
+export {};

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',