@sveltier/ui 0.0.0-stage → 0.1.0-alpha.0

package/dist/primitives/keyboard/typeahead.js

@@ -0,0 +1,50 @@
+const disabled = (item) => item.matches(':disabled') || item.getAttribute('aria-disabled') === 'true';
+const label = (item) => (item.dataset.svLabel ?? item.getAttribute('aria-label') ?? item.textContent ?? '')
+    .trim()
+    .toLowerCase();
+/**
+ * Typing moves focus to the next item whose label starts with what was typed, as menus,
+ * listboxes and trees do. Repeating one character cycles through the items starting with it.
+ * Labels come from `data-sv-label`, `aria-label`, then the text.
+ *
+ * @example
+ * <ul role="listbox" {@attach rovingFocus({ orientation: 'vertical' })} {@attach typeahead()}>
+ */
+export function typeahead({ items = '[data-sv-item]', timeout = 500, onMatch = (item) => item.focus() } = {}) {
+    return (container) => {
+        let search = '';
+        let timer;
+        function onkeydown(event) {
+            const key = event.key;
+            if (event.defaultPrevented ||
+                event.ctrlKey ||
+                event.metaKey ||
+                event.altKey ||
+                key.length !== 1 ||
+                (key === ' ' && search === '')) {
+                return;
+            }
+            clearTimeout(timer);
+            timer = setTimeout(() => (search = ''), timeout);
+            search += key.toLowerCase();
+            const list = Array.from(container.querySelectorAll(items)).filter((item) => !disabled(item));
+            // "aaa" cycles through the items starting with "a".
+            const repeated = [...search].every((character) => character === search[0]);
+            const term = repeated ? search[0] : search;
+            const current = list.indexOf(document.activeElement);
+            // A new or one-letter search starts after the focused item; a longer one includes it.
+            const from = term.length === 1 ? current + 1 : Math.max(current, 0);
+            const ordered = [...list.slice(from), ...list.slice(0, from)];
+            const match = ordered.find((item) => label(item).startsWith(term));
+            if (match) {
+                event.preventDefault();
+                onMatch(match);
+            }
+        }
+        container.addEventListener('keydown', onkeydown);
+        return () => {
+            clearTimeout(timer);
+            container.removeEventListener('keydown', onkeydown);
+        };
+    };
+}

package/dist/primitives/layer/dismissable.d.ts

@@ -0,0 +1,26 @@
+import type { Attachment } from 'svelte/attachments';
+export declare const DISMISS_REASONS: readonly ["escape", "outside", "focus"];
+export type DismissReason = (typeof DISMISS_REASONS)[number];
+type Elements = Array<Element | null | undefined>;
+export interface DismissableOptions {
+    /** Called when the user dismisses the layer. The component decides whether to close. */
+    onDismiss: (reason: DismissReason) => void;
+    /** Dismiss on Escape, unless something inside handled it first. Defaults to `true`. */
+    escape?: boolean;
+    /** Dismiss on a pointer press outside. Defaults to `true`. */
+    outside?: boolean;
+    /** Dismiss when focus moves outside, as menus do on Tab. Defaults to `false`. */
+    focusOutside?: boolean;
+    /** Elements that count as inside, such as the trigger, which toggles instead. */
+    inside?: Elements | (() => Elements);
+}
+/**
+ * Registers the element as a layer: Escape, a press outside, or (opt-in) focus leaving it
+ * calls `onDismiss` with the reason. Layers stack, and only the topmost one is dismissed, so
+ * nested popovers, sheets and dialogs close one at a time.
+ *
+ * @example
+ * <div popover="manual" {@attach dismissable({ onDismiss: () => (open = false), inside: [trigger] })}>
+ */
+export declare function dismissable(options: DismissableOptions): Attachment<HTMLElement>;
+export {};

package/dist/primitives/layer/dismissable.js

@@ -0,0 +1,84 @@
+export const DISMISS_REASONS = ['escape', 'outside', 'focus'];
+// Active layers, topmost last. One set of document listeners routes each event to the
+// topmost layer only: with a listener per layer, a layer closed by an event would leave the
+// stack (Svelte flushes between listeners) and the next layer would react to the same event.
+const layers = [];
+let touch = false;
+function isInside({ element, options }, target) {
+    if (!(target instanceof Node))
+        return false;
+    const inside = options.inside ?? [];
+    return [element, ...(typeof inside === 'function' ? inside() : inside)].some((node) => node?.contains(target));
+}
+// A press on the page's own scrollbar is not a press outside.
+const onScrollbar = (event) => event.target === document.documentElement &&
+    (event.clientX >= document.documentElement.clientWidth ||
+        event.clientY >= document.documentElement.clientHeight);
+function dismissOutside(event) {
+    const top = layers.at(-1);
+    if (top && top.options.outside !== false && !isInside(top, event.target) && !onScrollbar(event)) {
+        top.options.onDismiss('outside');
+    }
+}
+// Escape listens in the bubble phase, so handlers inside run first and can prevent it.
+function onkeydown(event) {
+    const top = layers.at(-1);
+    if (event.key === 'Escape' && !event.defaultPrevented && top && top.options.escape !== false) {
+        event.preventDefault();
+        top.options.onDismiss('escape');
+    }
+}
+function onpointerdown(event) {
+    touch = event.pointerType === 'touch';
+    if (!touch && event.button === 0)
+        dismissOutside(event);
+}
+// Touch dismisses on the click that ends a tap, never on a press that starts a scroll.
+function onclick(event) {
+    if (touch)
+        dismissOutside(event);
+    touch = false;
+}
+function onfocusin(event) {
+    const top = layers.at(-1);
+    if (top?.options.focusOutside && !isInside(top, event.target))
+        top.options.onDismiss('focus');
+}
+function listen() {
+    document.addEventListener('keydown', onkeydown);
+    document.addEventListener('pointerdown', onpointerdown, true);
+    document.addEventListener('click', onclick, true);
+    document.addEventListener('focusin', onfocusin, true);
+}
+function unlisten() {
+    document.removeEventListener('keydown', onkeydown);
+    document.removeEventListener('pointerdown', onpointerdown, true);
+    document.removeEventListener('click', onclick, true);
+    document.removeEventListener('focusin', onfocusin, true);
+}
+/**
+ * Registers the element as a layer: Escape, a press outside, or (opt-in) focus leaving it
+ * calls `onDismiss` with the reason. Layers stack, and only the topmost one is dismissed, so
+ * nested popovers, sheets and dialogs close one at a time.
+ *
+ * @example
+ * <div popover="manual" {@attach dismissable({ onDismiss: () => (open = false), inside: [trigger] })}>
+ */
+export function dismissable(options) {
+    return (element) => {
+        const layer = { element, options };
+        // A layer mounted around active layers (children attach first) goes beneath them.
+        const inner = layers.findIndex((other) => element.contains(other.element));
+        if (inner < 0)
+            layers.push(layer);
+        else
+            layers.splice(inner, 0, layer);
+        if (layers.length === 1)
+            listen();
+        return () => {
+            layers.splice(layers.indexOf(layer), 1);
+            if (layers.length === 0)
+                unlisten();
+        };
+    };
+}

package/dist/primitives/motion/easing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * An easing function from cubic-bezier control points, as CSS `cubic-bezier()` defines it.
+ * Use it where a function is needed (Svelte transitions, Tween); CSS and `element.animate()`
+ * take the string directly.
+ *
+ * @example
+ * const standard = cubicBezier(0.236, 0, 0, 1);
+ */
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number;

package/dist/primitives/motion/easing.js

@@ -0,0 +1,46 @@
+/**
+ * An easing function from cubic-bezier control points, as CSS `cubic-bezier()` defines it.
+ * Use it where a function is needed (Svelte transitions, Tween); CSS and `element.animate()`
+ * take the string directly.
+ *
+ * @example
+ * const standard = cubicBezier(0.236, 0, 0, 1);
+ */
+export function cubicBezier(x1, y1, x2, y2) {
+    // Polynomial coefficients of x(s) and y(s) for the curve parameter s.
+    const cx = 3 * x1;
+    const bx = 3 * (x2 - x1) - cx;
+    const ax = 1 - cx - bx;
+    const cy = 3 * y1;
+    const by = 3 * (y2 - y1) - cy;
+    const ay = 1 - cy - by;
+    const x = (s) => ((ax * s + bx) * s + cx) * s;
+    const y = (s) => ((ay * s + by) * s + cy) * s;
+    const slope = (s) => (3 * ax * s + 2 * bx) * s + cx;
+    return (t) => {
+        if (t <= 0 || t >= 1)
+            return t <= 0 ? 0 : 1;
+        // Newton's method from s = t, then bisection if the slope is too flat to trust.
+        let s = t;
+        for (let i = 0; i < 8; i++) {
+            const error = x(s) - t;
+            if (Math.abs(error) < 1e-6)
+                return y(s);
+            const d = slope(s);
+            if (Math.abs(d) < 1e-6)
+                break;
+            s -= error / d;
+        }
+        let low = 0;
+        let high = 1;
+        s = t;
+        for (let i = 0; i < 32 && high - low > 1e-6; i++) {
+            if (x(s) < t)
+                low = s;
+            else
+                high = s;
+            s = (low + high) / 2;
+        }
+        return y(s);
+    };
+}

package/dist/primitives/motion/motion.d.ts

@@ -0,0 +1,59 @@
+import { Spring } from 'svelte/motion';
+import type { TransitionConfig } from 'svelte/transition';
+/** The theme's timing at an element: durations in ms and the easing as a CSS value. */
+export interface Motion {
+    fast: number;
+    normal: number;
+    slow: number;
+    ease: string;
+}
+/**
+ * Reads the theme's timing where the element is: the theme in scope, and near-zero
+ * durations while the user prefers reduced motion. For `element.animate()` and CSS.
+ */
+export declare function motion(element: Element): Motion;
+/**
+ * A CSS easing as a function, for Svelte transitions and `Tween`. Understands `cubic-bezier()`
+ * and the keywords; anything else (`steps()`, `linear()`) falls back to `ease`.
+ */
+export declare function easing(ease: string): (t: number) => number;
+export interface TransitionOptions {
+    /** In ms. Defaults to the theme's normal duration. */
+    duration?: number;
+    delay?: number;
+}
+/** Fades in and out with the theme's timing. */
+export declare function fade(node: Element, options?: TransitionOptions): TransitionConfig;
+/** Fades in while moving up `distance` px (8 by default), with the theme's timing. */
+export declare function rise(node: Element, { distance, ...options }?: TransitionOptions & {
+    distance?: number;
+}): TransitionConfig;
+/** Fades in while growing from `scale` (94.4%, 1 − φ⁻⁶), with the theme's timing. */
+export declare function pop(node: Element, { scale, ...options }?: TransitionOptions & {
+    scale?: number;
+}): TransitionConfig;
+/** Spring presets on the φ series: stiffness 1/φⁿ, damping 1 − 1/φⁿ. */
+export declare const SPRINGS: {
+    readonly snappy: {
+        readonly stiffness: 0.236;
+        readonly damping: 0.764;
+    };
+    readonly standard: {
+        readonly stiffness: 0.146;
+        readonly damping: 0.854;
+    };
+    readonly gentle: {
+        readonly stiffness: 0.09;
+        readonly damping: 0.91;
+    };
+};
+export type SpringPreset = keyof typeof SPRINGS;
+/**
+ * A Svelte `Spring` with a φ preset that jumps straight to its target while the user prefers
+ * reduced motion. For motion that is essential, `set(value, { instant: false })` still animates.
+ *
+ * @example
+ * const balance = spring(0, 'gentle');
+ * balance.target = 248190.35;
+ */
+export declare function spring<T>(value: T, preset?: SpringPreset): Spring<T>;

package/dist/primitives/motion/motion.js

@@ -0,0 +1,80 @@
+import { Spring, prefersReducedMotion } from 'svelte/motion';
+import { cubicBezier } from './easing.js';
+/**
+ * Reads the theme's timing where the element is: the theme in scope, and near-zero
+ * durations while the user prefers reduced motion. For `element.animate()` and CSS.
+ */
+export function motion(element) {
+    const style = getComputedStyle(element);
+    const read = (name, fallback) => {
+        const value = style.getPropertyValue(`--sv-duration-${name}`).trim();
+        const ms = parseFloat(value) * (value.endsWith('ms') ? 1 : 1000);
+        return Number.isFinite(ms) ? ms : fallback;
+    };
+    return {
+        fast: read('fast', 144),
+        normal: read('normal', 233),
+        slow: read('slow', 377),
+        ease: style.getPropertyValue('--sv-ease').trim() || 'ease'
+    };
+}
+const KEYWORDS = {
+    linear: [0, 0, 1, 1],
+    ease: [0.25, 0.1, 0.25, 1],
+    'ease-in': [0.42, 0, 1, 1],
+    'ease-out': [0, 0, 0.58, 1],
+    'ease-in-out': [0.42, 0, 0.58, 1]
+};
+/**
+ * A CSS easing as a function, for Svelte transitions and `Tween`. Understands `cubic-bezier()`
+ * and the keywords; anything else (`steps()`, `linear()`) falls back to `ease`.
+ */
+export function easing(ease) {
+    const points = /cubic-bezier\(([^)]+)\)/.exec(ease)?.[1]?.split(',').map(Number);
+    const [x1, y1, x2, y2] = points?.length === 4 && points.every(Number.isFinite)
+        ? points
+        : (KEYWORDS[ease.trim()] ?? KEYWORDS.ease);
+    return cubicBezier(x1, y1, x2, y2);
+}
+function themed(node, { duration, delay = 0 }, css) {
+    const timing = motion(node);
+    return { delay, duration: duration ?? timing.normal, easing: easing(timing.ease), css };
+}
+/** Fades in and out with the theme's timing. */
+export function fade(node, options = {}) {
+    return themed(node, options, (t) => `opacity: ${t}`);
+}
+/** Fades in while moving up `distance` px (8 by default), with the theme's timing. */
+export function rise(node, { distance = 8, ...options } = {}) {
+    return themed(node, options, (t, u) => `opacity: ${t}; transform: translateY(${u * distance}px)`);
+}
+/** Fades in while growing from `scale` (94.4%, 1 − φ⁻⁶), with the theme's timing. */
+export function pop(node, { scale = 0.944, ...options } = {}) {
+    return themed(node, options, (t) => `opacity: ${t}; transform: scale(${scale + (1 - scale) * t})`);
+}
+/** Spring presets on the φ series: stiffness 1/φⁿ, damping 1 − 1/φⁿ. */
+export const SPRINGS = {
+    snappy: { stiffness: 0.236, damping: 0.764 },
+    standard: { stiffness: 0.146, damping: 0.854 },
+    gentle: { stiffness: 0.09, damping: 0.91 }
+};
+// A Svelte Spring whose updates are instant while the user prefers reduced motion.
+class ReducibleSpring extends Spring {
+    set(value, options) {
+        return super.set(value, {
+            ...options,
+            instant: options?.instant ?? prefersReducedMotion.current
+        });
+    }
+}
+/**
+ * A Svelte `Spring` with a φ preset that jumps straight to its target while the user prefers
+ * reduced motion. For motion that is essential, `set(value, { instant: false })` still animates.
+ *
+ * @example
+ * const balance = spring(0, 'gentle');
+ * balance.target = 248190.35;
+ */
+export function spring(value, preset = 'standard') {
+    return new ReducibleSpring(value, SPRINGS[preset]);
+}

package/dist/primitives/portal/Portal.svelte

@@ -0,0 +1,37 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+
+	export interface PortalProps {
+		/** Where the content goes: an element or a selector. Defaults to `document.body`. */
+		target?: HTMLElement | string;
+		children: Snippet;
+	}
+</script>
+
+<script lang="ts">
+	// Renders its children as a separate root in another part of the document, with the same
+	// contexts. Moving the element itself would break how Svelte removes it later.
+	import { getAllContexts, mount, unmount } from 'svelte';
+	import { sveltierError } from '../../core/errors/errors.js';
+	import { hasThemeContext, useTheme } from '../../core/theme/context.js';
+	import PortalContent from './PortalContent.svelte';
+
+	let { target = 'body', children }: PortalProps = $props();
+
+	const context = getAllContexts();
+	const theme = hasThemeContext() ? useTheme() : undefined;
+
+	$effect(() => {
+		const parent = typeof target === 'string' ? document.querySelector(target) : target;
+		if (!parent) {
+			throw sveltierError(
+				'SV3001',
+				`Portal: no element matches "${target}". Render the target first, or pass the element itself.`
+			);
+		}
+		const root = mount(PortalContent, { target: parent, props: { children, theme }, context });
+		return () => {
+			void unmount(root);
+		};
+	});
+</script>

package/dist/primitives/portal/Portal.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+export interface PortalProps {
+    /** Where the content goes: an element or a selector. Defaults to `document.body`. */
+    target?: HTMLElement | string;
+    children: Snippet;
+}
+declare const Portal: import("svelte").Component<PortalProps, {}, "">;
+type Portal = ReturnType<typeof Portal>;
+export default Portal;

package/dist/primitives/portal/PortalContent.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	// The root mounted by Portal. It repeats the nearest theme scope, so portaled content
+	// looks like the place it came from.
+	import type { Snippet } from 'svelte';
+	import type { ThemeInstance } from '../../core/theme/context.js';
+	import './portal.css';
+
+	let { children, theme }: { children: Snippet; theme?: ThemeInstance } = $props();
+</script>
+
+{#if theme}
+	<div class="sv-portal" data-sv-theme={theme.name}>{@render children()}</div>
+{:else}
+	{@render children()}
+{/if}

package/dist/primitives/portal/PortalContent.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { ThemeInstance } from '../../core/theme/context.js';
+type $$ComponentProps = {
+    children: Snippet;
+    theme?: ThemeInstance;
+};
+declare const PortalContent: import("svelte").Component<$$ComponentProps, {}, "">;
+type PortalContent = ReturnType<typeof PortalContent>;
+export default PortalContent;

package/dist/primitives/portal/portal.css

@@ -0,0 +1,8 @@
+@layer sv.tokens, sv.base, sv.components, sv.utilities;
+
+@layer sv.components {
+	/* Carries the theme scope of portaled content without adding a box. */
+	.sv-portal {
+		display: contents;
+	}
+}

package/dist/primitives/scroll-lock/scroll-lock.d.ts

@@ -0,0 +1,10 @@
+import type { Attachment } from 'svelte/attachments';
+/**
+ * Stops the page from scrolling while the element is attached, for modal surfaces. The
+ * scrollbar's width is kept as padding, so the layout does not shift. Locks are counted, so
+ * nested modals are safe: the page scrolls again when the last one ends.
+ *
+ * @example
+ * <dialog {@attach open && scrollLock()}>…</dialog>
+ */
+export declare function scrollLock(): Attachment;

package/dist/primitives/scroll-lock/scroll-lock.js

@@ -0,0 +1,33 @@
+let locks = 0;
+let restore;
+/**
+ * Stops the page from scrolling while the element is attached, for modal surfaces. The
+ * scrollbar's width is kept as padding, so the layout does not shift. Locks are counted, so
+ * nested modals are safe: the page scrolls again when the last one ends.
+ *
+ * @example
+ * <dialog {@attach open && scrollLock()}>…</dialog>
+ */
+export function scrollLock() {
+    return () => {
+        if (locks++ === 0) {
+            const html = document.documentElement;
+            const { overflow, paddingInlineEnd } = html.style;
+            const scrollbar = window.innerWidth - html.clientWidth;
+            const gutter = getComputedStyle(html).scrollbarGutter.includes('stable');
+            if (scrollbar > 0 && !gutter) {
+                const padding = parseFloat(getComputedStyle(html).paddingInlineEnd) || 0;
+                html.style.paddingInlineEnd = `${padding + scrollbar}px`;
+            }
+            html.style.overflow = 'hidden';
+            restore = () => {
+                html.style.overflow = overflow;
+                html.style.paddingInlineEnd = paddingInlineEnd;
+            };
+        }
+        return () => {
+            if (--locks === 0)
+                restore?.();
+        };
+    };
+}

package/dist/primitives/virtual/virtual-list.svelte.d.ts

@@ -0,0 +1,65 @@
+import type { Attachment } from 'svelte/attachments';
+export type VirtualKey = string | number;
+export interface VirtualListOptions {
+    /** How many items the list has. */
+    count: number;
+    /**
+     * Item height in px: one number when every item is as tall, or an estimate per index.
+     * Items with the `measure` attachment are measured, and the measurement wins.
+     */
+    itemSize: number | ((index: number) => number);
+    /** Items rendered beyond each edge of the viewport. Defaults to 3. */
+    overscan?: number;
+    /**
+     * A stable key per item, so measured heights follow items that move. Defaults to the index.
+     * Once items are measured it is read for every item when sizes change: keep large data in
+     * `$state.raw`, not deep `$state`.
+     */
+    key?: (index: number) => VirtualKey;
+    /** Viewport height in px assumed until the viewport is measured, as on the server. Defaults to 0. */
+    ssrHeight?: number;
+}
+export interface VirtualItem {
+    readonly index: number;
+    readonly key: VirtualKey;
+    /** Distance from the top of the list to the item, in px. */
+    readonly start: number;
+    readonly size: number;
+    /** `start + size`. */
+    readonly end: number;
+}
+export interface ScrollToIndexOptions {
+    /**
+     * Where the item lands. `auto` scrolls as little as possible, and not at all when the item
+     * is in view. Defaults to `'auto'`.
+     */
+    align?: 'auto' | 'start' | 'center' | 'end';
+}
+/** A virtual list: which items to render for the scroll position, and where. Every field is reactive. */
+export interface VirtualList {
+    /** The items to render: those in view, plus the overscan. */
+    readonly items: VirtualItem[];
+    /** Height of all the items together in px: the height of the element that holds them. */
+    readonly totalSize: number;
+    /** For the scroll container. */
+    readonly viewport: Attachment<HTMLElement>;
+    /** For item elements, with `data-index={item.index}`, to measure their real height. */
+    readonly measure: Attachment<HTMLElement>;
+    /**
+     * Scrolls the viewport, at once, so the item is in view, and renders it in the same update.
+     * Indexes outside the list are ignored.
+     */
+    scrollToIndex(index: number, options?: ScrollToIndexOptions): void;
+}
+/**
+ * Renders only the items in view out of thousands. Options are read through a function, so
+ * they stay reactive.
+ *
+ * @example
+ * const list = virtualList(() => ({ count: rows.length, itemSize: 34 }));
+ * // <div class="viewport" {@attach list.viewport}>
+ * //   <div style:height="{list.totalSize}px" style:position="relative">
+ * //     {#each list.items as item (item.key)}
+ * //       <div class="row" style:transform="translateY({item.start}px)">…</div>
+ */
+export declare function virtualList(options: () => VirtualListOptions): VirtualList;