entasis 0.10.2 → 0.12.0

package/README.md

@@ -13,7 +13,7 @@ Svelte 5 component library for SvelteKit, styled through a Tailwind CSS v4 plugi
 pnpm add entasis
 ```
 
-Peer dependencies: `svelte ^5`, `@sveltejs/kit ^2` and `tailwindcss ^4` (via `@tailwindcss/vite`). There is no `tailwind.config.js`; all configuration lives in your CSS. The library reads SvelteKit's `$app/environment` and, in `NetworkIndicator`, the `navigating` store, so it runs inside a SvelteKit app.
+Peer dependencies: `svelte ^5.32` (attachments and `fromAction`), `@sveltejs/kit ^2` and `tailwindcss ^4` (via `@tailwindcss/vite`). There is no `tailwind.config.js`; all configuration lives in your CSS. The library reads SvelteKit's `$app/environment` and, in `NetworkIndicator`, the `navigating` store, so it runs inside a SvelteKit app.
 
 ### Optional peers
 

package/dist/attachments/disclosurePanel.svelte.d.ts

@@ -0,0 +1,84 @@
+import type { Attachment } from 'svelte/attachments';
+import type { BaseTransitionParams } from '../transitions/transition.js';
+import { type OpenStateAttributes, type OpenTransitionStatus, type TransitionStatusAttributes } from '../utils/stateAttributes.js';
+/**
+ * CSS variable on the panel: its measured height in px while it animates, `auto` once open and
+ * `0px` once closed. Style inner content against it, or animate other properties with it.
+ */
+export declare const DISCLOSURE_PANEL_HEIGHT_VARIABLE = "--disclosure-panel-height";
+/** Enter (`in`) and exit (`out`) timing; a component's resolved motion preset fits as it is. */
+export type DisclosurePanelMotion = {
+    in?: BaseTransitionParams;
+    out?: BaseTransitionParams;
+};
+export type DisclosurePanelOptions = {
+    /** Whether the panel is open. Read reactively. */
+    open: () => boolean;
+    /**
+     * Keep the closed panel in the DOM under `hidden="until-found"`, so the browser's find-in-page,
+     * text fragments and `#id` links can reach its content and open it. Implies `keepMounted`.
+     * That state hides only the content (`content-visibility: hidden`): the panel's own padding,
+     * borders and margins stay laid out, so put them on an element inside the panel.
+     */
+    hiddenUntilFound?: () => boolean | undefined;
+    /** Keep the closed panel in the DOM under `hidden`, preserving its content's state. */
+    keepMounted?: () => boolean | undefined;
+    /** Enter and exit timing. Durations default to the Theme's `normal` step; reduced motion zeroes them. */
+    motion?: () => DisclosurePanelMotion | undefined;
+    /**
+     * Find-in-page matched content inside the closed panel. Open the panel synchronously here
+     * (through the owner's usual open-change path). If the panel is still closed a task later, the
+     * content goes back under `hidden="until-found"`. That open plays no animation.
+     */
+    onBeforeMatch?: (event: Event) => void;
+    /** Runs once when an open finishes: after the enter animation, or at once without motion. */
+    onAfterOpen?: () => void;
+    /**
+     * Runs once when a close finishes: after the exit animation, at once without motion, or when
+     * the panel element is removed mid-close.
+     */
+    onAfterClose?: () => void;
+};
+export type DisclosurePanelAttributes = OpenStateAttributes & TransitionStatusAttributes & {
+    /** `'until-found'` or `true` while the panel is closed and kept in the DOM. */
+    hidden: true | 'until-found' | undefined;
+};
+/**
+ * Drives a disclosure panel (Collapsible, Accordion items, Sidebar groups): its `hidden` state,
+ * a height animation, find-in-page reveal and completion callbacks that always fire once.
+ *
+ * Create it while the owner initialises, spread `attributes` on the panel, attach `attach`, and
+ * render the panel while `rendered` is true:
+ *
+ * ```svelte
+ * const panel = disclosurePanel({ open: () => isOpen, hiddenUntilFound: () => hiddenUntilFound,
+ *   onBeforeMatch: () => setOpen(true), onAfterOpen, onAfterClose, motion: () => contentMotion });
+ *
+ * {#if panel.rendered}
+ *   <div id={contentId} {...panel.attributes} {@attach panel.attach}>…</div>
+ * {/if}
+ * ```
+ *
+ * `attributes` carries `hidden` (`'until-found'` with `hiddenUntilFound`), `data-open` /
+ * `data-closed` and `data-entering` / `data-exiting`, so server-rendered markup is already right.
+ * The enter and exit animations run on the panel's height, block padding, borders and margins
+ * with the Web Animations API; `--disclosure-panel-height` holds the measured height meanwhile.
+ * An animation interrupted by the opposite change reverses from where it is. The first state is
+ * never animated.
+ */
+export declare class DisclosurePanel {
+    #private;
+    constructor(options: DisclosurePanelOptions);
+    /** Whether the owner reports the panel open. */
+    get open(): boolean;
+    /** `closed`, `entering`, `open` or `exiting`. */
+    get status(): OpenTransitionStatus;
+    /** Whether the panel belongs in the DOM: open, closing, or kept while closed. */
+    get rendered(): boolean;
+    /** `hidden` and the state attributes for the panel element. */
+    get attributes(): DisclosurePanelAttributes;
+    /** Attach to the panel element. */
+    attach: Attachment<HTMLElement>;
+}
+/** Creates a `DisclosurePanel` controller; call it while the owning component initialises. */
+export declare const disclosurePanel: (options: DisclosurePanelOptions) => DisclosurePanel;

package/dist/attachments/disclosurePanel.svelte.js

@@ -0,0 +1,277 @@
+import { getContext, tick, untrack } from 'svelte';
+import { defaultMotionTokens } from '../tailwind/scales.js';
+import { easingBezierStrings } from '../transitions/easingFunctions.js';
+import { prefersReducedMotion } from '../utils/motion.svelte.js';
+import { openStateAttributes, transitionStatusAttributes } from '../utils/stateAttributes.js';
+/**
+ * CSS variable on the panel: its measured height in px while it animates, `auto` once open and
+ * `0px` once closed. Style inner content against it, or animate other properties with it.
+ */
+export const DISCLOSURE_PANEL_HEIGHT_VARIABLE = '--disclosure-panel-height';
+// The block-axis box a collapse squeezes to nothing, as `slide` does.
+const BOX_PROPERTIES = [
+    'height',
+    'paddingTop',
+    'paddingBottom',
+    'borderTopWidth',
+    'borderBottomWidth',
+    'marginTop',
+    'marginBottom'
+];
+const COLLAPSED = Object.fromEntries(BOX_PROPERTIES.map((name) => [name, '0px']));
+// Computed values are used values in px while rendered, and mid-animation values while an
+// animation runs, whatever the panel's box-sizing.
+const readBox = (element) => {
+    const style = getComputedStyle(element);
+    return Object.fromEntries(BOX_PROPERTIES.map((name) => {
+        const value = style[name];
+        return [name, value && value.endsWith('px') ? value : '0px'];
+    }));
+};
+const overrideStyle = (element, property, value) => {
+    const previous = element.style.getPropertyValue(property);
+    const priority = element.style.getPropertyPriority(property);
+    element.style.setProperty(property, value);
+    return () => {
+        if (previous === '')
+            element.style.removeProperty(property);
+        else
+            element.style.setProperty(property, previous, priority);
+    };
+};
+/**
+ * Drives a disclosure panel (Collapsible, Accordion items, Sidebar groups): its `hidden` state,
+ * a height animation, find-in-page reveal and completion callbacks that always fire once.
+ *
+ * Create it while the owner initialises, spread `attributes` on the panel, attach `attach`, and
+ * render the panel while `rendered` is true:
+ *
+ * ```svelte
+ * const panel = disclosurePanel({ open: () => isOpen, hiddenUntilFound: () => hiddenUntilFound,
+ *   onBeforeMatch: () => setOpen(true), onAfterOpen, onAfterClose, motion: () => contentMotion });
+ *
+ * {#if panel.rendered}
+ *   <div id={contentId} {...panel.attributes} {@attach panel.attach}>…</div>
+ * {/if}
+ * ```
+ *
+ * `attributes` carries `hidden` (`'until-found'` with `hiddenUntilFound`), `data-open` /
+ * `data-closed` and `data-entering` / `data-exiting`, so server-rendered markup is already right.
+ * The enter and exit animations run on the panel's height, block padding, borders and margins
+ * with the Web Animations API; `--disclosure-panel-height` holds the measured height meanwhile.
+ * An animation interrupted by the opposite change reverses from where it is. The first state is
+ * never animated.
+ */
+export class DisclosurePanel {
+    #options;
+    #theme;
+    #status = $state('closed');
+    #element = null;
+    // The open state the panel rests in or is moving to.
+    #target;
+    // The completion callback the current change still owes.
+    #pending = null;
+    #animation = null;
+    #animationId = 0;
+    // A finished collapse kept filled until `hidden` or the unmount reaches the DOM.
+    #lingering = null;
+    #restoreOverflow = null;
+    // Set by find-in-page: the next open reveals the content at once.
+    #skipOpenMotion = false;
+    #revealTimeout;
+    #revealFrame;
+    constructor(options) {
+        this.#options = options;
+        this.#theme = getContext('entasisTheme');
+        const open = untrack(() => !!options.open());
+        this.#target = open;
+        this.#status = open ? 'open' : 'closed';
+        $effect(() => {
+            const next = !!options.open();
+            untrack(() => this.#sync(next));
+        });
+    }
+    /** Whether the owner reports the panel open. */
+    get open() {
+        return !!this.#options.open();
+    }
+    /** `closed`, `entering`, `open` or `exiting`. */
+    get status() {
+        return this.#status;
+    }
+    /** Whether the panel belongs in the DOM: open, closing, or kept while closed. */
+    get rendered() {
+        return this.open || this.#status !== 'closed' || this.#keepsElement();
+    }
+    /** `hidden` and the state attributes for the panel element. */
+    get attributes() {
+        const open = this.open;
+        const hidden = !open && this.#status === 'closed';
+        return {
+            hidden: hidden ? (this.#hiddenUntilFound() ? 'until-found' : true) : undefined,
+            ...openStateAttributes(open),
+            ...transitionStatusAttributes(this.#status)
+        };
+    }
+    /** Attach to the panel element. */
+    attach = (element) => untrack(() => {
+        this.#element = element;
+        element.style.setProperty(DISCLOSURE_PANEL_HEIGHT_VARIABLE, this.#status === 'open' ? 'auto' : '0px');
+        const onBeforeMatch = (event) => this.#handleBeforeMatch(element, event);
+        element.addEventListener('beforematch', onBeforeMatch);
+        // An open that started before the panel was rendered animates now.
+        if (this.#pending && !this.#animation)
+            this.#run();
+        return () => {
+            element.removeEventListener('beforematch', onBeforeMatch);
+            this.#cancelReveal();
+            if (this.#element !== element)
+                return;
+            this.#element = null;
+            this.#stopAnimation();
+            // A panel removed while it closes has finished closing.
+            if (this.#pending === 'close')
+                this.#finish();
+        };
+    });
+    #hiddenUntilFound = () => !!this.#options.hiddenUntilFound?.();
+    #keepsElement = () => this.#hiddenUntilFound() || !!this.#options.keepMounted?.();
+    #isOpenNow = () => untrack(() => !!this.#options.open());
+    #sync(open) {
+        if (open === this.#target)
+            return;
+        this.#target = open;
+        this.#pending = open ? 'open' : 'close';
+        this.#status = open ? 'entering' : 'exiting';
+        this.#run();
+    }
+    #timing(open) {
+        const reduced = this.#theme ? this.#theme.preferReducesMotion : prefersReducedMotion();
+        const motion = this.#options.motion?.();
+        const params = (open ? motion?.in : motion?.out) ?? {};
+        const tokens = this.#theme?.motion ?? defaultMotionTokens;
+        return {
+            duration: reduced ? 0 : (params.duration ?? tokens.duration.normal),
+            delay: params.delay ?? 0,
+            easing: easingBezierStrings[params.easing ?? tokens.easing.standard]
+        };
+    }
+    #run() {
+        const element = this.#element;
+        const open = this.#target;
+        if (!element) {
+            // An open waits for its element; a close has nothing left to collapse.
+            if (!open)
+                this.#finish();
+            return;
+        }
+        // Read before stopping, so an interrupted animation reverses from where it is.
+        const current = this.#animation || this.#lingering ? readBox(element) : null;
+        this.#stopAnimation();
+        const skip = open && this.#skipOpenMotion;
+        this.#skipOpenMotion = false;
+        const timing = this.#timing(open);
+        if (skip || timing.duration <= 0) {
+            this.#finish();
+            return;
+        }
+        // Measured with the variable at `auto`, so a panel styled `height: var(…)` reports its content.
+        element.style.setProperty(DISCLOSURE_PANEL_HEIGHT_VARIABLE, 'auto');
+        const natural = readBox(element);
+        const from = current ?? (open ? COLLAPSED : natural);
+        const to = open ? natural : COLLAPSED;
+        element.style.setProperty(DISCLOSURE_PANEL_HEIGHT_VARIABLE, `${parseFloat(natural.height) || 0}px`);
+        this.#restoreOverflow = overrideStyle(element, 'overflow', 'hidden');
+        const id = ++this.#animationId;
+        // `both`: the first keyframe holds through a delay, so the panel doesn't show at its final
+        // or CSS height first, and the last one holds until `#finish` settles the styles.
+        const animation = element.animate([from, to], {
+            duration: timing.duration,
+            delay: timing.delay,
+            easing: timing.easing,
+            fill: 'both'
+        });
+        this.#animation = animation;
+        animation.onfinish = () => {
+            if (id === this.#animationId)
+                this.#finish();
+        };
+    }
+    #finish() {
+        const open = this.#target;
+        const element = this.#element;
+        const collapse = !open && element ? this.#animation : null;
+        if (collapse) {
+            // Keep the collapsed fill until `hidden` or the unmount lands, so the panel never
+            // flashes back to full height for a frame.
+            this.#animation = null;
+            this.#animationId += 1;
+            this.#lingering = collapse;
+            void tick().then(() => {
+                if (this.#lingering === collapse)
+                    this.#releaseLingering();
+            });
+        }
+        else {
+            this.#stopAnimation();
+        }
+        element?.style.setProperty(DISCLOSURE_PANEL_HEIGHT_VARIABLE, open ? 'auto' : '0px');
+        this.#status = open ? 'open' : 'closed';
+        const pending = this.#pending;
+        this.#pending = null;
+        if (pending === 'open')
+            this.#options.onAfterOpen?.();
+        else if (pending === 'close')
+            this.#options.onAfterClose?.();
+    }
+    #releaseLingering() {
+        this.#lingering?.cancel();
+        this.#lingering = null;
+        this.#restoreOverflow?.();
+        this.#restoreOverflow = null;
+    }
+    #stopAnimation() {
+        this.#animationId += 1;
+        const animation = this.#animation;
+        this.#animation = null;
+        animation?.cancel();
+        this.#releaseLingering();
+    }
+    #handleBeforeMatch(element, event) {
+        if (this.#target)
+            return;
+        this.#skipOpenMotion = true;
+        // The browser measures the match as soon as this event returns; a styled collapse must
+        // not hide it.
+        element.style.setProperty(DISCLOSURE_PANEL_HEIGHT_VARIABLE, 'auto');
+        this.#options.onBeforeMatch?.(event);
+        this.#cancelReveal();
+        // An owner that refuses the open (a controlled parent ignoring the change) leaves the panel
+        // closed: give its state a task to arrive, then hide the content again, still findable.
+        this.#revealTimeout = setTimeout(() => {
+            this.#revealTimeout = undefined;
+            if (this.#isOpenNow())
+                return;
+            this.#revealFrame = requestAnimationFrame(() => {
+                this.#revealFrame = undefined;
+                if (this.#isOpenNow())
+                    return;
+                this.#skipOpenMotion = false;
+                if (this.#element !== element)
+                    return;
+                element.style.setProperty(DISCLOSURE_PANEL_HEIGHT_VARIABLE, '0px');
+                if (this.#hiddenUntilFound())
+                    element.setAttribute('hidden', 'until-found');
+            });
+        }, 0);
+    }
+    #cancelReveal() {
+        clearTimeout(this.#revealTimeout);
+        this.#revealTimeout = undefined;
+        if (this.#revealFrame !== undefined)
+            cancelAnimationFrame(this.#revealFrame);
+        this.#revealFrame = undefined;
+    }
+}
+/** Creates a `DisclosurePanel` controller; call it while the owning component initialises. */
+export const disclosurePanel = (options) => new DisclosurePanel(options);

package/dist/attachments/portal.d.ts

@@ -1,6 +1,22 @@
 import type { Attachment } from 'svelte/attachments';
+/** What `<Theme portalContainer>` accepts: a container, or a function that finds it later. */
+export type PortalContainerSource = HTMLElement | ShadowRoot | (() => HTMLElement | ShadowRoot | null | undefined);
+type ContainerSource = () => PortalContainerSource | undefined;
 /**
- * Moves the node to `document.body` (or `target`) on mount and removes it on destroy.
+ * Registers where `<Theme portalContainer>` is read from, for the lifetime of a Theme. `portal()`
+ * runs inside an attachment, where `getContext` is unavailable, so the mounted Theme is found the
+ * way `prefersReducedMotion()` finds it: the most recently mounted one that sets a container.
+ */
+export declare function registerPortalContainer(source: ContainerSource): () => void;
+/**
+ * The node `portal()` mounts `node` into: the Theme's `portalContainer`, else the shadow root
+ * the node renders in (its panels keep the styles adopted there), else `document.body`.
+ */
+export declare function resolvePortalContainer(node: Node): HTMLElement | ShadowRoot | null;
+/**
+ * Moves the node to the Theme's portal container (`document.body` by default, the shadow root
+ * when rendered inside one) or to `target`, on mount, and removes it on destroy.
  * Use as an attachment: `{@attach portal()}` or `{@attach portal(targetEl)}`.
  */
 export declare function portal(target?: Element): Attachment<HTMLElement>;
+export {};

package/dist/attachments/portal.js

@@ -1,10 +1,47 @@
+const sources = [];
 /**
- * Moves the node to `document.body` (or `target`) on mount and removes it on destroy.
+ * Registers where `<Theme portalContainer>` is read from, for the lifetime of a Theme. `portal()`
+ * runs inside an attachment, where `getContext` is unavailable, so the mounted Theme is found the
+ * way `prefersReducedMotion()` finds it: the most recently mounted one that sets a container.
+ */
+export function registerPortalContainer(source) {
+    sources.push(source);
+    return () => {
+        const index = sources.lastIndexOf(source);
+        if (index >= 0)
+            sources.splice(index, 1);
+    };
+}
+const configuredContainer = () => {
+    for (let index = sources.length - 1; index >= 0; index -= 1) {
+        const source = sources[index]();
+        const container = typeof source === 'function' ? source() : source;
+        if (container?.isConnected)
+            return container;
+    }
+    return null;
+};
+/**
+ * The node `portal()` mounts `node` into: the Theme's `portalContainer`, else the shadow root
+ * the node renders in (its panels keep the styles adopted there), else `document.body`.
+ */
+export function resolvePortalContainer(node) {
+    const configured = configuredContainer();
+    if (configured)
+        return configured;
+    const root = node.getRootNode();
+    if (typeof ShadowRoot !== 'undefined' && root instanceof ShadowRoot)
+        return root;
+    return node.ownerDocument?.body ?? null;
+}
+/**
+ * Moves the node to the Theme's portal container (`document.body` by default, the shadow root
+ * when rendered inside one) or to `target`, on mount, and removes it on destroy.
  * Use as an attachment: `{@attach portal()}` or `{@attach portal(targetEl)}`.
  */
 export function portal(target) {
     return (node) => {
-        const mount = target ?? (typeof document !== 'undefined' ? document.body : undefined);
+        const mount = target ?? resolvePortalContainer(node);
         if (!mount)
             return;
         mount.appendChild(node);

package/dist/attachments/spinnerOverlay.svelte.js

@@ -51,6 +51,17 @@ export const spinnerOverlay = (opts) => {
         });
         mountedSpinnerIndicators.set(overlay, { component, className, variant });
     };
+    // The overlay sits inside the host's border, where the host clips its content with its inner
+    // radius (outer radius minus border width). Inheriting the outer radius made the overlay's corners
+    // rounder than that clip and let the host's background show at each corner.
+    const matchInnerRadius = (node, overlay) => {
+        const style = getComputedStyle(node);
+        const corner = (radius, a, b) => `max(0px, calc(${radius} - ${Math.max(parseFloat(a) || 0, parseFloat(b) || 0)}px))`;
+        overlay.style.borderTopLeftRadius = corner(style.borderTopLeftRadius, style.borderTopWidth, style.borderLeftWidth);
+        overlay.style.borderTopRightRadius = corner(style.borderTopRightRadius, style.borderTopWidth, style.borderRightWidth);
+        overlay.style.borderBottomRightRadius = corner(style.borderBottomRightRadius, style.borderBottomWidth, style.borderRightWidth);
+        overlay.style.borderBottomLeftRadius = corner(style.borderBottomLeftRadius, style.borderBottomWidth, style.borderLeftWidth);
+    };
     const setOverlay = (node) => {
         let mounted = false;
         let overlay = getSpinnerOverlay(node);
@@ -64,6 +75,7 @@ export const spinnerOverlay = (opts) => {
         }
         overlay.dataset.color = opts.color ?? 'neutral';
         overlay.className = classes.overlay({ class: opts.class });
+        matchInnerRadius(node, overlay);
         return [overlay, mounted];
     };
     const setText = (overlay) => {

package/dist/attachments/transitionSize.d.ts

@@ -12,5 +12,11 @@ export type TransitionSizeOptions = {
     easing?: MotionEasingToken | Easing;
     /** Optional custom event names that should trigger a re-measure. */
     events?: string | string[];
+    /**
+     * While a width animation runs, keep each direct child at the width it settles at, so its
+     * content does not re-wrap at every intermediate width; the clipped element reveals it as it
+     * grows. Default `true` for the `width` and `both` axes.
+     */
+    fixContentWidth?: boolean;
 };
 export declare const transitionSize: (options?: TransitionSizeOptions) => Attachment<HTMLElement>;

package/dist/attachments/transitionSize.js

@@ -60,6 +60,7 @@ export const transitionSize = (options = {}) => {
     };
     const isActive = () => options.isActive?.() ?? true;
     const eventNames = getEventNames(options.events);
+    const fixContentWidth = options.fixContentWidth ?? axis !== 'height';
     return (node) => {
         if (typeof ResizeObserver === 'undefined')
             return;
@@ -69,9 +70,33 @@ export const transitionSize = (options = {}) => {
         let animationId = 0;
         let shouldRetarget = false;
         const initialOverflow = node.style.overflow;
+        // Children pinned to their settled width for the current animation, with their own styles.
+        let pinned = [];
+        const unpinChildren = () => {
+            for (const { child, width, flexShrink } of pinned) {
+                child.style.width = width;
+                child.style.flexShrink = flexShrink;
+            }
+            pinned = [];
+        };
+        const pinChildren = () => {
+            if (!fixContentWidth)
+                return;
+            for (const child of Array.from(node.children)) {
+                if (!(child instanceof HTMLElement) || child.hidden)
+                    continue;
+                const width = child.getBoundingClientRect().width;
+                if (!width)
+                    continue;
+                pinned.push({ child, width: child.style.width, flexShrink: child.style.flexShrink });
+                child.style.width = `${width}px`;
+                child.style.flexShrink = '0';
+            }
+        };
         const restoreOverflow = (id) => {
             if (id !== animationId)
                 return;
+            unpinChildren();
             node.style.overflow = initialOverflow;
             animation = null;
             previousSize = readSize(node);
@@ -83,6 +108,8 @@ export const transitionSize = (options = {}) => {
             const currentAnimation = animation;
             animation = null;
             currentAnimation.cancel();
+            // The next measurement must see the children's natural layout, not the pinned one.
+            unpinChildren();
         };
         const animateToCurrentSize = () => {
             frame = null;
@@ -115,6 +142,8 @@ export const transitionSize = (options = {}) => {
                 ? currentDuration
                 : remainingDuration;
             node.style.overflow = 'hidden';
+            // Measured before the keyframes apply, while the children sit at their settled widths.
+            pinChildren();
             animation = node.animate(getKeyframes(previousVisualSize, nextSize, axis), {
                 duration: animationDuration,
                 easing: easing()
@@ -143,6 +172,7 @@ export const transitionSize = (options = {}) => {
             if (frame !== null)
                 cancelAnimationFrame(frame);
             cancelAnimation();
+            unpinChildren();
             observer.disconnect();
             mutationObserver.disconnect();
             eventNames.forEach((eventName) => node.removeEventListener(eventName, handleEvent));