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

package/dist/primitives/anchored/anchored.js

@@ -0,0 +1,104 @@
+export const SIDES = ['top', 'bottom', 'start', 'end'];
+export const ALIGNS = ['start', 'center', 'end'];
+export const PHYSICAL_SIDES = ['top', 'bottom', 'left', 'right'];
+/**
+ * The physical side, and the alignment in physical terms (start is left or top), of a
+ * logical placement in the element's direction. Both placement paths use it, so they agree.
+ */
+export function physical(side, align, rtl) {
+    if (side === 'top' || side === 'bottom') {
+        const mirrored = align === 'start' ? 'end' : align === 'end' ? 'start' : align;
+        return [side, rtl ? mirrored : align];
+    }
+    return [(side === 'end') !== rtl ? 'right' : 'left', align];
+}
+/** `position-area` in physical keywords: `bottom span-right` is below, from the left edge. */
+export function positionArea(side, align) {
+    if (align === 'center')
+        return side;
+    const vertical = side === 'top' || side === 'bottom';
+    const span = vertical
+        ? align === 'start'
+            ? 'right'
+            : 'left'
+        : align === 'start'
+            ? 'bottom'
+            : 'top';
+    return `${side} span-${span}`;
+}
+// The margin that faces the anchor; flipping mirrors it to the other side.
+const MARGIN = {
+    top: 'margin-bottom',
+    bottom: 'margin-top',
+    left: 'margin-right',
+    right: 'margin-left'
+};
+let names = 0;
+/**
+ * Whether the element sits in a part of the page whose direction differs from the root's.
+ * Firefox (157) misplaces anchored elements there, so the script places them instead.
+ */
+function mixedDirection(element) {
+    const root = getComputedStyle(document.documentElement).direction;
+    return [element, element.parentElement].some((node) => node && getComputedStyle(node).direction !== root);
+}
+/**
+ * Places the element next to `anchor` and keeps it there on scroll and resize, flipping to
+ * the opposite side when there is not enough room. Uses CSS anchor positioning where the
+ * browser has it, otherwise loads a small script. The element must be positioned against the
+ * viewport: a popover in the top layer, or `position: fixed`.
+ *
+ * @example
+ * <button bind:this={trigger}>Account</button>
+ * <div popover="manual" {@attach anchored({ anchor: trigger, side: 'bottom', align: 'end' })}>…</div>
+ */
+export function anchored({ anchor, side = 'bottom', align = 'start', offset = 5, flip = true }) {
+    return (floating) => {
+        if (!anchor)
+            return;
+        const [physicalSide, physicalAlign] = physical(side, align, getComputedStyle(floating).direction === 'rtl');
+        if (!CSS.supports('position-try-fallbacks: flip-block') || mixedDirection(floating)) {
+            let stop;
+            let cancelled = false;
+            const placement = { side: physicalSide, align: physicalAlign, offset, flip };
+            void import('./fallback.js').then(({ follow }) => {
+                if (!cancelled)
+                    stop = follow(anchor, floating, placement);
+            });
+            return () => {
+                cancelled = true;
+                stop?.();
+            };
+        }
+        const name = `--sv-anchor-${++names}`;
+        const anchorStyle = anchor.style;
+        const existing = getComputedStyle(anchor).getPropertyValue('anchor-name');
+        anchorStyle.setProperty('anchor-name', existing && existing !== 'none' ? `${existing}, ${name}` : name);
+        const vertical = physicalSide === 'top' || physicalSide === 'bottom';
+        const style = floating.style;
+        const properties = {
+            'position-anchor': name,
+            'position-area': positionArea(physicalSide, physicalAlign),
+            'position-try-fallbacks': flip ? (vertical ? 'flip-block' : 'flip-inline') : 'none',
+            inset: 'auto',
+            margin: '0',
+            [MARGIN[physicalSide]]: `${offset}px`
+        };
+        for (const [property, value] of Object.entries(properties))
+            style.setProperty(property, value);
+        return () => {
+            for (const property of Object.keys(properties))
+                style.removeProperty(property);
+            // Other floating elements may share this anchor: remove only this name.
+            const rest = anchorStyle
+                .getPropertyValue('anchor-name')
+                .split(',')
+                .map((entry) => entry.trim())
+                .filter((entry) => entry && entry !== name);
+            if (rest.length)
+                anchorStyle.setProperty('anchor-name', rest.join(', '));
+            else
+                anchorStyle.removeProperty('anchor-name');
+        };
+    };
+}

package/dist/primitives/anchored/fallback.d.ts

@@ -0,0 +1,31 @@
+import type { Align, PhysicalSide as Physical } from './anchored.js';
+interface Size {
+    width: number;
+    height: number;
+}
+interface Rect extends Size {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+/**
+ * Where the floating element goes: on `side` of the anchor, aligned along it, on the opposite
+ * side when that has more room (with `flip`), and kept inside the viewport.
+ */
+export declare function place(anchor: Rect, floating: Size, viewport: Size, side: Physical, align: Align, offset: number, flip?: boolean): {
+    x: number;
+    y: number;
+    side: Physical;
+};
+export interface Placement {
+    /** Physical side, as anchored() resolves it from the writing direction. */
+    side: Physical;
+    /** Physical alignment: start is left or top. */
+    align: Align;
+    offset: number;
+    flip: boolean;
+}
+/** Keeps `floating` placed against `anchor` until the returned function is called. */
+export declare function follow(anchor: Element, floating: HTMLElement, { side, align, offset, flip }: Placement): () => void;
+export {};

package/dist/primitives/anchored/fallback.js

@@ -0,0 +1,73 @@
+const OPPOSITE = {
+    top: 'bottom',
+    bottom: 'top',
+    left: 'right',
+    right: 'left'
+};
+// Distance kept from the viewport edges, in px.
+const PADDING = 8;
+const clamp = (value, min, max) => Math.max(min, Math.min(value, max));
+/**
+ * Where the floating element goes: on `side` of the anchor, aligned along it, on the opposite
+ * side when that has more room (with `flip`), and kept inside the viewport.
+ */
+export function place(anchor, floating, viewport, side, align, offset, flip = true) {
+    const room = {
+        top: anchor.top - PADDING,
+        bottom: viewport.height - anchor.bottom - PADDING,
+        left: anchor.left - PADDING,
+        right: viewport.width - anchor.right - PADDING
+    };
+    const vertical = side === 'top' || side === 'bottom';
+    const need = (vertical ? floating.height : floating.width) + offset;
+    if (flip && room[side] < need && room[OPPOSITE[side]] > room[side])
+        side = OPPOSITE[side];
+    const [start, length, size, axis] = vertical
+        ? [anchor.left, anchor.width, floating.width, viewport.width]
+        : [anchor.top, anchor.height, floating.height, viewport.height];
+    const cross = clamp(align === 'start'
+        ? start
+        : align === 'end'
+            ? start + length - size
+            : start + (length - size) / 2, PADDING, axis - size - PADDING);
+    const main = side === 'top'
+        ? anchor.top - offset - floating.height
+        : side === 'bottom'
+            ? anchor.bottom + offset
+            : side === 'left'
+                ? anchor.left - offset - floating.width
+                : anchor.right + offset;
+    return vertical ? { x: cross, y: main, side } : { x: main, y: cross, side };
+}
+/** Keeps `floating` placed against `anchor` until the returned function is called. */
+export function follow(anchor, floating, { side, align, offset, flip }) {
+    const style = floating.style;
+    style.setProperty('inset', '0 auto auto 0');
+    style.setProperty('margin', '0');
+    let frame = 0;
+    function update() {
+        frame = 0;
+        const root = document.documentElement;
+        const result = place(anchor.getBoundingClientRect(), floating.getBoundingClientRect(), { width: root.clientWidth, height: root.clientHeight }, side, align, offset, flip);
+        style.setProperty('translate', `${result.x}px ${result.y}px`);
+        floating.dataset.side = result.side;
+    }
+    const schedule = () => {
+        frame ||= requestAnimationFrame(update);
+    };
+    const observer = new ResizeObserver(schedule);
+    observer.observe(anchor);
+    observer.observe(floating);
+    addEventListener('scroll', schedule, { capture: true, passive: true });
+    addEventListener('resize', schedule, { passive: true });
+    update();
+    return () => {
+        cancelAnimationFrame(frame);
+        observer.disconnect();
+        removeEventListener('scroll', schedule, { capture: true });
+        removeEventListener('resize', schedule);
+        for (const property of ['inset', 'margin', 'translate'])
+            style.removeProperty(property);
+        delete floating.dataset.side;
+    };
+}

package/dist/primitives/focus/focus-trap.d.ts

@@ -0,0 +1,25 @@
+import type { Attachment } from 'svelte/attachments';
+import { type FocusableElement } from './tabbable.js';
+export interface FocusTrapOptions {
+    /**
+     * Where focus goes when the trap starts, unless it is already inside: an element, a selector
+     * inside the container, or `false` to leave it where it is. Defaults to the first tabbable
+     * element, else the container.
+     */
+    initialFocus?: FocusableElement | string | false;
+    /**
+     * Where focus goes when the trap ends: `true` for the element that had it when the trap
+     * started, an element (pass the trigger: Safari does not focus a button on click, so the
+     * element that had focus may be the page itself), or `false` to leave it. Defaults to `true`.
+     */
+    returnFocus?: boolean | FocusableElement | null;
+}
+/**
+ * Keeps keyboard focus inside the element: Tab and Shift+Tab wrap at the edges, and focus
+ * that leaves by pointer or script is brought back. Traps stack: a trap inside another, or
+ * opened after it, takes over until it ends, then the previous one resumes.
+ *
+ * @example
+ * <div role="dialog" aria-modal="true" {@attach open && focusTrap()}>…</div>
+ */
+export declare function focusTrap({ initialFocus, returnFocus }?: FocusTrapOptions): Attachment<HTMLElement>;

package/dist/primitives/focus/focus-trap.js

@@ -0,0 +1,86 @@
+import { tabbable } from './tabbable.js';
+// Active traps, innermost last. Only the last one acts.
+const traps = [];
+/**
+ * Keeps keyboard focus inside the element: Tab and Shift+Tab wrap at the edges, and focus
+ * that leaves by pointer or script is brought back. Traps stack: a trap inside another, or
+ * opened after it, takes over until it ends, then the previous one resumes.
+ *
+ * @example
+ * <div role="dialog" aria-modal="true" {@attach open && focusTrap()}>…</div>
+ */
+export function focusTrap({ initialFocus, returnFocus = true } = {}) {
+    return (container) => {
+        const previous = returnFocus === true ? document.activeElement : returnFocus;
+        let madeFocusable = false;
+        let last;
+        function enter(target) {
+            if (target)
+                return target.focus();
+            if (!container.hasAttribute('tabindex')) {
+                container.tabIndex = -1;
+                madeFocusable = true;
+            }
+            container.focus();
+        }
+        const trap = {
+            container,
+            resume: () => enter(last?.isConnected && container.contains(last) ? last : tabbable(container)[0])
+        };
+        const active = () => traps.at(-1) === trap;
+        function onkeydown(event) {
+            if (event.key !== 'Tab' || event.defaultPrevented || !active())
+                return;
+            const items = tabbable(container);
+            const current = document.activeElement;
+            const edge = event.shiftKey ? items[0] : items.at(-1);
+            if (items.length === 0 || current === edge || !container.contains(current)) {
+                event.preventDefault();
+                enter(event.shiftKey ? items.at(-1) : items[0]);
+            }
+        }
+        function onfocusin(event) {
+            if (!active())
+                return;
+            const target = event.target;
+            if (container.contains(target))
+                last = target;
+            else
+                trap.resume();
+        }
+        // A trap mounted around active traps (children attach first) goes beneath them.
+        const inner = traps.findIndex((other) => container.contains(other.container));
+        if (inner < 0)
+            traps.push(trap);
+        else
+            traps.splice(inner, 0, trap);
+        document.addEventListener('keydown', onkeydown, true);
+        document.addEventListener('focusin', onfocusin, true);
+        if (initialFocus !== false && !container.contains(document.activeElement)) {
+            enter(typeof initialFocus === 'string'
+                ? container.querySelector(initialFocus)
+                : (initialFocus ?? tabbable(container)[0]));
+        }
+        return () => {
+            document.removeEventListener('keydown', onkeydown, true);
+            document.removeEventListener('focusin', onfocusin, true);
+            traps.splice(traps.indexOf(trap), 1);
+            if (madeFocusable)
+                container.removeAttribute('tabindex');
+            // In a later task: after the other attachments of the closing surface have cleaned up
+            // (inertOthers may still hold the page inert now) and after the browser has moved
+            // focus for the press that closed it. Then give focus back if it is still ours
+            // (inside the trap, or lost to the page), and let the trap below take over again.
+            setTimeout(() => {
+                const focused = document.activeElement;
+                const lost = !focused || focused === document.body || container.contains(focused);
+                const restorable = previous instanceof HTMLElement || previous instanceof SVGElement;
+                if (lost && restorable && previous.isConnected)
+                    previous.focus();
+                const below = traps.at(-1);
+                if (below && !below.container.contains(document.activeElement))
+                    below.resume();
+            });
+        };
+    };
+}

package/dist/primitives/focus/roving-focus.d.ts

@@ -0,0 +1,22 @@
+import type { Attachment } from 'svelte/attachments';
+export interface RovingFocusOptions {
+    /** Which arrow keys move: left/right, up/down, or both. Defaults to `'horizontal'`. */
+    orientation?: 'horizontal' | 'vertical' | 'both';
+    /** Wrap from the last item to the first and back. Defaults to `true`. */
+    loop?: boolean;
+    /** Selector for the items, inside the container. Defaults to `[data-sv-item]`. */
+    items?: string;
+}
+/**
+ * Gives a composite widget (toolbar, menu, radio group, tabs, listbox) one tab stop: the
+ * active item has `tabindex="0"`, the others `-1`. Arrow keys move along the orientation
+ * (left and right follow the writing direction), Home and End jump to the ends, and disabled
+ * items are skipped. The first stop is the item marked selected, checked or current.
+ *
+ * @example
+ * <div role="toolbar" {@attach rovingFocus()}>
+ *   <button data-sv-item>Bold</button>
+ *   <button data-sv-item>Italic</button>
+ * </div>
+ */
+export declare function rovingFocus({ orientation, loop, items }?: RovingFocusOptions): Attachment<HTMLElement>;

package/dist/primitives/focus/roving-focus.js

@@ -0,0 +1,86 @@
+const disabled = (item) => item.matches(':disabled') || item.getAttribute('aria-disabled') === 'true';
+/**
+ * Gives a composite widget (toolbar, menu, radio group, tabs, listbox) one tab stop: the
+ * active item has `tabindex="0"`, the others `-1`. Arrow keys move along the orientation
+ * (left and right follow the writing direction), Home and End jump to the ends, and disabled
+ * items are skipped. The first stop is the item marked selected, checked or current.
+ *
+ * @example
+ * <div role="toolbar" {@attach rovingFocus()}>
+ *   <button data-sv-item>Bold</button>
+ *   <button data-sv-item>Italic</button>
+ * </div>
+ */
+export function rovingFocus({ orientation = 'horizontal', loop = true, items = '[data-sv-item]' } = {}) {
+    return (container) => {
+        const all = () => Array.from(container.querySelectorAll(items));
+        let current;
+        /** Makes `item` the tab stop, or keeps the current one, or picks the first enabled. */
+        function sync(item) {
+            const list = all();
+            const enabled = list.filter((candidate) => !disabled(candidate));
+            if (item)
+                current = item;
+            if (!current || !list.includes(current) || disabled(current)) {
+                current =
+                    enabled.find((candidate) => candidate.matches('[aria-selected="true"],[aria-checked="true"],[aria-current]:not([aria-current="false"])')) ?? enabled[0];
+            }
+            for (const candidate of list)
+                candidate.tabIndex = candidate === current ? 0 : -1;
+        }
+        function onkeydown(event) {
+            if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey)
+                return;
+            const list = all().filter((item) => !disabled(item));
+            const index = list.indexOf(event.target);
+            if (index < 0)
+                return;
+            const forward = getComputedStyle(container).direction === 'rtl' ? -1 : 1;
+            const horizontal = orientation !== 'vertical';
+            const vertical = orientation !== 'horizontal';
+            const step = {
+                ArrowRight: horizontal ? forward : undefined,
+                ArrowLeft: horizontal ? -forward : undefined,
+                ArrowDown: vertical ? 1 : undefined,
+                ArrowUp: vertical ? -1 : undefined
+            };
+            let next;
+            if (event.key === 'Home')
+                next = 0;
+            else if (event.key === 'End')
+                next = list.length - 1;
+            else if (step[event.key] !== undefined) {
+                next = index + step[event.key];
+                next = loop
+                    ? (next + list.length) % list.length
+                    : Math.min(Math.max(next, 0), list.length - 1);
+            }
+            else
+                return;
+            event.preventDefault();
+            sync(list[next]);
+            list[next]?.focus();
+        }
+        function onfocusin(event) {
+            const item = event.target.closest(items);
+            if (item && container.contains(item) && !disabled(item))
+                sync(item);
+        }
+        // Items come and go (filtering, async data): keep exactly one tab stop.
+        const observer = new MutationObserver(() => sync());
+        observer.observe(container, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ['disabled', 'aria-disabled']
+        });
+        container.addEventListener('keydown', onkeydown);
+        container.addEventListener('focusin', onfocusin);
+        sync();
+        return () => {
+            observer.disconnect();
+            container.removeEventListener('keydown', onkeydown);
+            container.removeEventListener('focusin', onfocusin);
+        };
+    };
+}

package/dist/primitives/focus/tabbable.d.ts

@@ -0,0 +1,9 @@
+export type FocusableElement = HTMLElement | SVGElement;
+/** Whether `element` can be reached with Tab right now. */
+export declare function isTabbable(element: Element): element is FocusableElement;
+/**
+ * The elements inside `container` that Tab reaches, in the order Tab reaches them: positive
+ * `tabindex` first, then document order. Like browsers, a radio group contributes one stop,
+ * its checked radio or else its first.
+ */
+export declare function tabbable(container: ParentNode): FocusableElement[];

package/dist/primitives/focus/tabbable.js

@@ -0,0 +1,75 @@
+// Elements that can be focusable at all; isTabbable() then checks the current state.
+const CANDIDATES = [
+    'a[href]',
+    'area[href]',
+    'button',
+    'input:not([type="hidden"])',
+    'select',
+    'textarea',
+    'iframe',
+    'object',
+    'embed',
+    'audio[controls]',
+    'video[controls]',
+    'summary',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]'
+].join(',');
+/**
+ * The element's place in the Tab order. `tabIndex` reports -1 for editing hosts and media
+ * controls without a `tabindex` attribute, although Tab reaches them.
+ */
+function tabIndexOf(element) {
+    if (element.hasAttribute('tabindex'))
+        return element.tabIndex;
+    const reachable = element instanceof HTMLElement &&
+        (element.isContentEditable || element.matches('audio[controls],video[controls]'));
+    return reachable ? 0 : element.tabIndex;
+}
+/** Whether `element` can be reached with Tab right now. */
+export function isTabbable(element) {
+    if (!(element instanceof HTMLElement || element instanceof SVGElement))
+        return false;
+    if (tabIndexOf(element) < 0 || element.matches(':disabled') || element.closest('[inert]')) {
+        return false;
+    }
+    // The content of a closed <details> is not rendered, except its own summary.
+    const details = element.closest('details:not([open])');
+    if (details && !(element.localName === 'summary' && element.parentElement === details)) {
+        return false;
+    }
+    return element.checkVisibility({ checkVisibilityCSS: true, visibilityProperty: true });
+}
+/**
+ * The elements inside `container` that Tab reaches, in the order Tab reaches them: positive
+ * `tabindex` first, then document order. Like browsers, a radio group contributes one stop,
+ * its checked radio or else its first.
+ */
+export function tabbable(container) {
+    const found = [];
+    const radios = new Map();
+    for (const element of container.querySelectorAll(CANDIDATES)) {
+        if (!isTabbable(element))
+            continue;
+        if (element instanceof HTMLInputElement && element.type === 'radio' && element.name) {
+            const group = `${element.form?.id ?? ''}|${element.name}`;
+            const chosen = radios.get(group);
+            if (!chosen) {
+                radios.set(group, element);
+                found.push(element);
+            }
+            else if (element.checked && !chosen.checked) {
+                radios.set(group, element);
+                found[found.indexOf(chosen)] = element;
+            }
+            continue;
+        }
+        found.push(element);
+    }
+    // Stable sort: positive tabindex in ascending order, then everything else as it was.
+    const rank = (element) => {
+        const index = tabIndexOf(element);
+        return index > 0 ? index : Infinity;
+    };
+    return found.sort((a, b) => rank(a) - rank(b));
+}

package/dist/primitives/inert/inert-others.d.ts

@@ -0,0 +1,12 @@
+import type { Attachment } from 'svelte/attachments';
+/**
+ * Makes everything outside the element inert (not focusable, not clickable, hidden from
+ * assistive technology) while attached, for modal surfaces that are not a `<dialog>`.
+ * Live regions stay active so announcements still reach screen readers. Calls stack: an
+ * inner modal never reactivates what an outer one made inert, and elements that were inert
+ * before stay inert.
+ *
+ * @example
+ * <div role="dialog" aria-modal="true" {@attach open && inertOthers()}>…</div>
+ */
+export declare function inertOthers(): Attachment<HTMLElement>;

package/dist/primitives/inert/inert-others.js

@@ -0,0 +1,44 @@
+// Elements this module made inert, with how many active calls need them inert.
+const owned = new Map();
+/**
+ * Makes everything outside the element inert (not focusable, not clickable, hidden from
+ * assistive technology) while attached, for modal surfaces that are not a `<dialog>`.
+ * Live regions stay active so announcements still reach screen readers. Calls stack: an
+ * inner modal never reactivates what an outer one made inert, and elements that were inert
+ * before stay inert.
+ *
+ * @example
+ * <div role="dialog" aria-modal="true" {@attach open && inertOthers()}>…</div>
+ */
+export function inertOthers() {
+    return (element) => {
+        const changed = [];
+        for (let node = element; node.parentElement && node !== document.body; node = node.parentElement) {
+            for (const sibling of node.parentElement.children) {
+                if (sibling === node || sibling.matches('[aria-live]'))
+                    continue;
+                const count = owned.get(sibling);
+                if (count !== undefined)
+                    owned.set(sibling, count + 1);
+                else if (sibling.hasAttribute('inert'))
+                    continue;
+                else {
+                    owned.set(sibling, 1);
+                    sibling.setAttribute('inert', '');
+                }
+                changed.push(sibling);
+            }
+        }
+        return () => {
+            for (const sibling of changed) {
+                const count = (owned.get(sibling) ?? 1) - 1;
+                if (count > 0)
+                    owned.set(sibling, count);
+                else {
+                    owned.delete(sibling);
+                    sibling.removeAttribute('inert');
+                }
+            }
+        };
+    };
+}

package/dist/primitives/keyboard/keymap.d.ts

@@ -0,0 +1,17 @@
+import type { Attachment } from 'svelte/attachments';
+/** Runs for a key combination. Return `false` to let the event through unhandled. */
+export type KeyHandler = (event: KeyboardEvent) => void | false;
+/**
+ * The combination of an event as `keymap` names it: `Ctrl+Alt+Shift+Meta+Key`. With `rtl`
+ * given, horizontal arrows become `ArrowForward` / `ArrowBackward` for that direction.
+ */
+export declare function combination(event: KeyboardEvent, rtl?: boolean): string;
+/**
+ * Binds keys to handlers on the element. A handled key has its default prevented. Write
+ * combinations as `Ctrl+Alt+Shift+Meta+Key` with `event.key` names; `ArrowForward` and
+ * `ArrowBackward` follow the writing direction, and physical arrow names work too.
+ *
+ * @example
+ * <div role="slider" {@attach keymap({ ArrowForward: up, ArrowBackward: down, Home: min, End: max })}>
+ */
+export declare function keymap(map: Record<string, KeyHandler>): Attachment<HTMLElement>;

package/dist/primitives/keyboard/keymap.js

@@ -0,0 +1,39 @@
+/**
+ * The combination of an event as `keymap` names it: `Ctrl+Alt+Shift+Meta+Key`. With `rtl`
+ * given, horizontal arrows become `ArrowForward` / `ArrowBackward` for that direction.
+ */
+export function combination(event, rtl) {
+    let key = event.key;
+    if (rtl !== undefined && (key === 'ArrowRight' || key === 'ArrowLeft')) {
+        key = (key === 'ArrowRight') !== rtl ? 'ArrowForward' : 'ArrowBackward';
+    }
+    // event.key already carries Shift for characters: "?" rather than "Shift+/".
+    const shift = event.shiftKey && key.length > 1;
+    return ((event.ctrlKey ? 'Ctrl+' : '') +
+        (event.altKey ? 'Alt+' : '') +
+        (shift ? 'Shift+' : '') +
+        (event.metaKey ? 'Meta+' : '') +
+        key);
+}
+/**
+ * Binds keys to handlers on the element. A handled key has its default prevented. Write
+ * combinations as `Ctrl+Alt+Shift+Meta+Key` with `event.key` names; `ArrowForward` and
+ * `ArrowBackward` follow the writing direction, and physical arrow names work too.
+ *
+ * @example
+ * <div role="slider" {@attach keymap({ ArrowForward: up, ArrowBackward: down, Home: min, End: max })}>
+ */
+export function keymap(map) {
+    return (element) => {
+        function onkeydown(event) {
+            if (event.defaultPrevented)
+                return;
+            const rtl = getComputedStyle(element).direction === 'rtl';
+            const handler = map[combination(event, rtl)] ?? map[combination(event)];
+            if (handler && handler(event) !== false)
+                event.preventDefault();
+        }
+        element.addEventListener('keydown', onkeydown);
+        return () => element.removeEventListener('keydown', onkeydown);
+    };
+}

package/dist/primitives/keyboard/typeahead.d.ts

@@ -0,0 +1,18 @@
+import type { Attachment } from 'svelte/attachments';
+export interface TypeaheadOptions {
+    /** Selector for the items, inside the container. Defaults to `[data-sv-item]`. */
+    items?: string;
+    /** How long typed characters keep building one search, in ms. Defaults to 500. */
+    timeout?: number;
+    /** What a match does. Defaults to focusing the item. */
+    onMatch?: (item: HTMLElement) => void;
+}
+/**
+ * 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 declare function typeahead({ items, timeout, onMatch }?: TypeaheadOptions): Attachment<HTMLElement>;