entasis 0.10.2 → 0.12.0

package/dist/utils/useListNavigation.svelte.js

@@ -1,5 +1,68 @@
 import { untrack } from 'svelte';
 import { createTypeahead } from './typeahead.js';
+import { elementById } from './id.js';
+/**
+ * Hands each distinct value its own DOM id, numbered in the order the values are first asked
+ * for. Sanitizing a value into an id collides (`a.b` and `a_b` both become `a_b`) and searching
+ * for its index is quadratic; a map lookup is neither. Ids are stable for the life of the map.
+ */
+export const createOptionIds = (prefix) => {
+    // Plain map on purpose: ids are handed out while rendering and must not be tracked state.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    const ids = new Map();
+    let sequence = 0;
+    return {
+        /** The id of `value`; the first request assigns the next number. */
+        get(value) {
+            let id = ids.get(value);
+            if (id === undefined) {
+                id = `${prefix}-option-${sequence}`;
+                sequence += 1;
+                ids.set(value, id);
+            }
+            return id;
+        },
+        /** Forgets every assignment (numbering carries on, so old ids are never reused). */
+        clear() {
+            ids.clear();
+        }
+    };
+};
+const scrollsVertically = (element) => {
+    const overflow = getComputedStyle(element).overflowY;
+    return overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay';
+};
+const nearestScroller = (element) => {
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+        if (scrollsVertically(parent))
+            return parent;
+    }
+    return null;
+};
+/**
+ * Brings `element` into view by moving the container's own `scrollTop`. Unlike `scrollIntoView`
+ * it never scrolls the page or an ancestor, so an inline list inside a page stays put.
+ *
+ * Rects include ancestor transforms (a popover mid-open animation is scaled), while `scrollTop`
+ * is in layout pixels, so the offsets are divided by the container's rendered scale first.
+ */
+const scrollWithin = (container, element) => {
+    const style = getComputedStyle(container);
+    const paddingTop = parseFloat(style.scrollPaddingTop) || 0;
+    const paddingBottom = parseFloat(style.scrollPaddingBottom) || 0;
+    const bounds = container.getBoundingClientRect();
+    const target = element.getBoundingClientRect();
+    const scale = container.offsetHeight > 0 && bounds.height > 0 ? bounds.height / container.offsetHeight : 1;
+    // The element's edges in the container's layout space, from the top of its padding box.
+    const targetTop = (target.top - bounds.top) / scale - container.clientTop;
+    const targetBottom = (target.bottom - bounds.top) / scale - container.clientTop;
+    const top = paddingTop;
+    const bottom = container.clientHeight - paddingBottom;
+    if (targetTop < top)
+        container.scrollTop -= top - targetTop;
+    else if (targetBottom > bottom)
+        container.scrollTop += targetBottom - bottom;
+};
 /**
  * Value-driven keyboard navigation for combobox-style widgets (command palettes, dropdowns,
  * autocompletes): DOM focus stays on the input, only the highlight moves ("virtual focus",
@@ -7,95 +70,235 @@ import { createTypeahead } from './typeahead.js';
  *
  * Unlike `useNavigation` (DOM/index-based roving tabindex — right for menus, tabs, toolbars),
  * the highlight here is a *value*, so it survives the item set changing underneath it: when the
- * highlighted value disappears (typing in a filter), the highlight re-anchors to the first value.
+ * highlighted value disappears (typing in a filter), the highlight re-anchors per
+ * `autoHighlight` — the first value by default. With `open` and `anchor` it also lands on the
+ * selected value each time the list opens and when the query clears.
  *
  * Must be called during component init (it registers an `$effect`).
  *
  * Wire-up: `onkeydown={nav.onKeydown}` on the input, `aria-activedescendant={nav.activeDescendant}`,
- * `onpointermove={() => nav.setHighlighted(value)}` on rows, `aria-selected={nav.highlighted === value}`.
+ * `id={nav.optionId(value)}` and `onpointermove={(event) => nav.pointerHighlight(value, event)}` on
+ * rows, `aria-selected={nav.highlighted === value}`.
  */
 export const useListNavigation = (opts) => {
     let highlighted = $state();
-    const setHighlighted = (value) => {
+    let lastDetails = $state({ reason: 'list' });
+    let lastPointer = null;
+    let scrollTimer;
+    const loopMode = () => opts.loop === false ? false : opts.loop === 'input' ? 'input' : 'wrap';
+    const autoHighlight = () => opts.autoHighlight ?? 'always';
+    const ids = opts.idPrefix !== undefined ? createOptionIds(opts.idPrefix) : null;
+    const optionId = (value) => opts.optionId?.(value) ?? ids?.get(value);
+    const setHighlighted = (value, details) => {
         if (highlighted === value)
             return;
+        const next = details ?? { reason: 'pointer' };
         highlighted = value;
-        opts.onHighlightChange?.(value);
+        lastDetails = next;
+        opts.onHighlightChange?.(value, next);
     };
-    // Re-anchor to the first value whenever the set changes (typing, external item updates).
-    // `highlighted` reads/writes are untracked so this reacts only to `values` — arrow/hover
-    // moves change `highlighted` but not the set, so they won't clobber an in-progress selection.
+    /** Scroll the highlighted option into view, inside its scroll container only. */
+    const scrollToHighlighted = () => {
+        if (highlighted === undefined || typeof document === 'undefined')
+            return;
+        const id = optionId(highlighted);
+        const element = id ? elementById(opts.scrollContainer?.(), id) : null;
+        if (!element)
+            return;
+        const container = opts.scrollContainer?.() ?? nearestScroller(element);
+        if (container)
+            scrollWithin(container, element);
+    };
+    /** Scroll now and once more after the next flush, for options a popup is still mounting. */
+    const scrollSoon = () => {
+        scrollToHighlighted();
+        if (scrollTimer)
+            clearTimeout(scrollTimer);
+        scrollTimer = setTimeout(scrollToHighlighted, 0);
+    };
+    /** The value to highlight with no keyboard input: the anchor, else the auto-highlight rule. */
+    const resting = (values, query, useAnchor) => {
+        if (useAnchor && query === '') {
+            const anchor = untrack(() => opts.anchor?.());
+            if (anchor !== undefined && values.includes(anchor))
+                return anchor;
+        }
+        const mode = autoHighlight();
+        if (mode === 'always' || (mode === true && query !== ''))
+            return values[0];
+        return undefined;
+    };
+    // Re-anchor whenever the set, the query or the open state changes (typing, external item
+    // updates). `highlighted` reads/writes are untracked so this reacts only to those inputs —
+    // arrow/hover moves change `highlighted` but not the set, so they won't clobber an
+    // in-progress selection.
+    let previousQuery;
+    let previousOpen;
+    let previousCount = 0;
     $effect(() => {
         const values = opts.values();
+        const query = opts.query?.() ?? '';
+        const open = opts.open?.() ?? true;
         untrack(() => {
-            if (highlighted === undefined || !values.includes(highlighted)) {
-                setHighlighted(values[0]);
+            const opened = open && previousOpen !== true;
+            const queryChanged = previousQuery !== undefined && query !== previousQuery;
+            const cleared = queryChanged && query === '';
+            // Options that load after the list opened (async sources) still get the anchor.
+            const arrived = previousCount === 0 && values.length > 0;
+            previousQuery = query;
+            previousOpen = open;
+            previousCount = values.length;
+            if (!open)
+                return;
+            // A new query shows a new list: the first match belongs in view, however far the user
+            // had scrolled the previous one.
+            const typed = queryChanged && !cleared;
+            if (typed) {
+                // The old highlight may be gone from the list; any rendered option finds the scroller.
+                const probe = [highlighted, values[0]].find((value) => value !== undefined && optionId(value));
+                const element = probe !== undefined && typeof document !== 'undefined'
+                    ? elementById(opts.scrollContainer?.(), optionId(probe))
+                    : null;
+                const container = opts.scrollContainer?.() ?? (element ? nearestScroller(element) : null);
+                if (container)
+                    container.scrollTop = 0;
+            }
+            if (opened || cleared) {
+                setHighlighted(resting(values, query, true), { reason: 'list' });
+                scrollSoon();
+                return;
+            }
+            const stale = highlighted === undefined || !values.includes(highlighted);
+            // Typing starts the highlight over at the first match; without auto-highlight a
+            // surviving highlight stays (and is scrolled back into view below).
+            const next = typed || stale ? resting(values, query, arrived) : highlighted;
+            if (typed && next === undefined && !stale) {
+                scrollToHighlighted();
+            }
+            else {
+                setHighlighted(next, { reason: 'list' });
+                if (arrived)
+                    scrollSoon();
+                else if (typed)
+                    scrollToHighlighted();
             }
         });
     });
-    /** Highlight a value and scroll its option into view. */
-    const highlight = (value) => {
-        setHighlighted(value);
-        if (value !== undefined && opts.optionId) {
-            document.getElementById(opts.optionId(value))?.scrollIntoView({ block: 'nearest' });
-        }
+    /**
+     * Re-run the resting highlight (anchor, else the auto-highlight rule) on demand, e.g. when a
+     * consumer opens the list itself rather than through `open`.
+     */
+    const reanchor = () => {
+        setHighlighted(resting(opts.values(), opts.query?.() ?? '', true), { reason: 'list' });
+        scrollSoon();
     };
-    /** Move the highlight by `delta` values, wrapping around both ends (unless `loop: false`). */
-    const move = (delta) => {
+    /** Highlight a value and scroll its option into view (inside the list only). */
+    const highlight = (value, details) => {
+        setHighlighted(value, details ?? { reason: 'keyboard' });
+        if (value !== undefined)
+            scrollToHighlighted();
+    };
+    /**
+     * Move the highlight by `delta` values. Past an end it wraps, lands on no highlight (`loop:
+     * 'input'`) or stops (`loop: false`). With nothing highlighted, going forward starts at the
+     * first value and going back at the last.
+     */
+    const move = (delta, details) => {
         const values = opts.values();
         if (values.length === 0)
             return;
         const current = highlighted === undefined ? -1 : values.indexOf(highlighted);
-        const next = opts.loop === false
-            ? Math.max(0, Math.min(values.length - 1, current + delta))
-            : (((current + delta) % values.length) + values.length) % values.length;
-        highlight(values[next]);
+        const mode = loopMode();
+        let next;
+        if (current === -1) {
+            next = delta > 0 ? 0 : values.length - 1;
+        }
+        else if (mode === 'wrap') {
+            next = (((current + delta) % values.length) + values.length) % values.length;
+        }
+        else if (mode === 'input') {
+            const target = current + delta;
+            next = target < 0 || target >= values.length ? undefined : target;
+        }
+        else {
+            next = Math.max(0, Math.min(values.length - 1, current + delta));
+        }
+        highlight(next === undefined ? undefined : values[next], details);
     };
     /** Highlight the first value. */
-    const first = () => {
+    const first = (details) => {
         const values = opts.values();
         if (values.length)
-            highlight(values[0]);
+            highlight(values[0], details);
     };
     /** Highlight the last value. */
-    const last = () => {
+    const last = (details) => {
         const values = opts.values();
         if (values.length)
-            highlight(values[values.length - 1]);
+            highlight(values[values.length - 1], details);
+    };
+    /**
+     * Pointer hover: highlights `value` unless the pointer hasn't moved. Browsers (Safari) fire
+     * a pointermove with unchanged coordinates when keyboard scrolling slides an option under a
+     * resting cursor; honoring it would snap the highlight away from the keyboard's choice.
+     * Returns whether the highlight was handled.
+     */
+    const pointerHighlight = (value, event) => {
+        if (event) {
+            const moved = !lastPointer || lastPointer.x !== event.clientX || lastPointer.y !== event.clientY;
+            lastPointer = { x: event.clientX, y: event.clientY };
+            if (!moved)
+                return false;
+        }
+        setHighlighted(value, { reason: 'pointer', event });
+        return true;
     };
+    let keyEvent;
     const typeahead = opts.typeahead
         ? createTypeahead({
             getItems: () => opts.values(),
             getText: opts.typeahead,
             getCurrentIndex: () => highlighted === undefined ? -1 : opts.values().indexOf(highlighted),
-            onMatch: (_index, value) => highlight(value)
+            onMatch: (_index, value) => highlight(value, { reason: 'keyboard', event: keyEvent })
         })
         : null;
+    // A pending buffer or scroll must not outlive the list.
+    $effect(() => () => {
+        typeahead?.reset();
+        if (scrollTimer)
+            clearTimeout(scrollTimer);
+    });
     /** Keydown handler for the focused input: ArrowUp/Down, Home, End, Enter, typeahead. */
     const onKeydown = (event) => {
-        if (typeahead?.handleKey(event)) {
-            event.preventDefault();
-            return;
+        const details = { reason: 'keyboard', event };
+        if (typeahead) {
+            keyEvent = event;
+            const consumed = typeahead.handleKey(event);
+            keyEvent = undefined;
+            if (consumed) {
+                event.preventDefault();
+                return;
+            }
         }
         switch (event.key) {
             case 'ArrowDown':
                 event.preventDefault();
-                move(1);
+                move(1, details);
                 break;
             case 'ArrowUp':
                 event.preventDefault();
-                move(-1);
+                move(-1, details);
                 break;
             case 'Home':
                 if (opts.values().length) {
                     event.preventDefault();
-                    first();
+                    first(details);
                 }
                 break;
             case 'End':
                 if (opts.values().length) {
                     event.preventDefault();
-                    last();
+                    last(details);
                 }
                 break;
             case 'Enter':
@@ -111,16 +314,39 @@ export const useListNavigation = (opts) => {
         get highlighted() {
             return highlighted;
         },
+        /** Why the highlight last moved, and the event behind it. */
+        get highlightDetails() {
+            return lastDetails;
+        },
         /** DOM id of the highlighted option, for `aria-activedescendant`. */
         get activeDescendant() {
-            return highlighted !== undefined ? opts.optionId?.(highlighted) : undefined;
+            return highlighted !== undefined ? optionId(highlighted) : undefined;
         },
-        /** Set the highlight without scrolling — for pointermove/hover. */
+        /**
+         * DOM id of a value's option: `optionId` when given, else the next id in sequence for
+         * `idPrefix`. `undefined` when neither was provided.
+         */
+        optionId,
+        /** Type-to-highlight state; `null` without the `typeahead` option. */
+        typeahead: typeahead
+            ? {
+                /** True while typed characters are buffered (Space belongs to the search, not to selection). */
+                get isTyping() {
+                    return typeahead.isTyping;
+                },
+                /** Drop the buffered characters, e.g. on blur or close. */
+                reset: typeahead.reset
+            }
+            : null,
+        /** Set the highlight without scrolling — for hover. Prefer `pointerHighlight`. */
         setHighlighted,
+        pointerHighlight,
         highlight,
         move,
         first,
         last,
+        reanchor,
+        scrollToHighlighted,
         onKeydown
     };
 };

package/dist/utils/useLiveAnnouncer.svelte.d.ts

@@ -1,18 +1,93 @@
+import type { Attachment } from 'svelte/attachments';
+/** `polite` waits for the screen reader to finish; `assertive` interrupts it. */
+export type LivePoliteness = 'polite' | 'assertive';
+export type LiveAnnouncerOptions = {
+    /** @default 'polite' */
+    politeness?: LivePoliteness;
+};
+/** Attributes of a live region element. */
+export type LiveRegionAttributes = {
+    id: string;
+    role: 'status' | 'alert';
+    'aria-live': LivePoliteness;
+    'aria-atomic': 'true';
+};
 /**
- * A polite live region's message, wired so repeats are actually re-read.
+ * A live region's message, wired so repeats are actually re-read.
  *
  * Screen readers only announce a live region when its text *changes*, so the same
  * message twice in a row would be silent. Blanking the region first and setting the
  * text in a microtask forces the change; a revision counter drops stale microtasks so
  * a burst of announcements settles on the last one and a disposed owner announces
  * nothing at all.
+ *
+ * The owner renders the region itself, always, so it exists before the first message:
+ * `<span class="sr-only" {...announcer.regionAttrs}>{announcer.message}</span>`.
  */
-export declare const useLiveAnnouncer: (baseId: string, suffix?: string) => {
+export declare const useLiveAnnouncer: (baseId: string, suffix?: string, { politeness }?: LiveAnnouncerOptions) => {
     /** `id` for the live region element; owners expose it as `aria-*` targets. */
     regionId: string;
+    politeness: LivePoliteness;
+    /** `id`, `role`, `aria-live` and `aria-atomic` for the region element. */
+    regionAttrs: LiveRegionAttributes;
     readonly message: string;
     announce(next: string): void;
     /** Clears the region and cancels any pending announcement. */
     reset(): void;
 };
 export type LiveAnnouncer = ReturnType<typeof useLiveAnnouncer>;
+export type LiveRegionsOptions = {
+    /**
+     * How long the regions stay empty after the host mounts before they take text. Screen readers
+     * (Safari's in particular) miss a region that is inserted and filled in quick succession, so a
+     * message announced earlier waits for this delay. @default 100
+     */
+    settleDelay?: number;
+    /**
+     * Clears a message this long after it was announced, so browsing the page later doesn't land
+     * on stale text. `0` keeps messages until the next one. @default 7000
+     */
+    clearAfter?: number;
+};
+/**
+ * A persistent pair of live regions, one polite (`role="status"`) and one assertive
+ * (`role="alert"`), for owners that announce events rather than render them in place
+ * (a Toaster announcing each toast, a list announcing its result count).
+ *
+ * Attach `host` once to an element that is always rendered and stays in the accessibility tree
+ * (no `hidden`, `display: none` or `visibility: hidden` ancestor). It inserts both regions empty
+ * as soon as it mounts, so they exist before the first announcement, and holds messages until
+ * the regions have settled. The host may render its own children: when Svelte empties it (a
+ * host whose only child is an `{#each}` is cleared at once when the list empties), the regions
+ * are put back with their text. Removing the host removes the regions.
+ */
+export declare const useLiveRegions: (baseId: string, suffix?: string, { settleDelay, clearAfter }?: LiveRegionsOptions) => {
+    polite: {
+        /** `id` for the live region element; owners expose it as `aria-*` targets. */
+        regionId: string;
+        politeness: LivePoliteness;
+        /** `id`, `role`, `aria-live` and `aria-atomic` for the region element. */
+        regionAttrs: LiveRegionAttributes;
+        readonly message: string;
+        announce(next: string): void;
+        /** Clears the region and cancels any pending announcement. */
+        reset(): void;
+    };
+    assertive: {
+        /** `id` for the live region element; owners expose it as `aria-*` targets. */
+        regionId: string;
+        politeness: LivePoliteness;
+        /** `id`, `role`, `aria-live` and `aria-atomic` for the region element. */
+        regionAttrs: LiveRegionAttributes;
+        readonly message: string;
+        announce(next: string): void;
+        /** Clears the region and cancels any pending announcement. */
+        reset(): void;
+    };
+    host: Attachment<HTMLElement>;
+    /** Announces `message` in the polite region, or the assertive one. */
+    announce(message: string, politeness?: LivePoliteness): void;
+    /** Clears both regions and cancels pending announcements. */
+    reset(): void;
+};
+export type LiveRegions = ReturnType<typeof useLiveRegions>;

package/dist/utils/useLiveAnnouncer.svelte.js

@@ -1,19 +1,32 @@
+import { untrack } from 'svelte';
 /**
- * A polite live region's message, wired so repeats are actually re-read.
+ * A live region's message, wired so repeats are actually re-read.
  *
  * Screen readers only announce a live region when its text *changes*, so the same
  * message twice in a row would be silent. Blanking the region first and setting the
  * text in a microtask forces the change; a revision counter drops stale microtasks so
  * a burst of announcements settles on the last one and a disposed owner announces
  * nothing at all.
+ *
+ * The owner renders the region itself, always, so it exists before the first message:
+ * `<span class="sr-only" {...announcer.regionAttrs}>{announcer.message}</span>`.
  */
-export const useLiveAnnouncer = (baseId, suffix = 'live') => {
+export const useLiveAnnouncer = (baseId, suffix = 'live', { politeness = 'polite' } = {}) => {
     const regionId = `${baseId}-${suffix}`;
+    const regionAttrs = {
+        id: regionId,
+        role: politeness === 'assertive' ? 'alert' : 'status',
+        'aria-live': politeness,
+        'aria-atomic': 'true'
+    };
     let message = $state('');
     let revision = 0;
     return {
         /** `id` for the live region element; owners expose it as `aria-*` targets. */
         regionId,
+        politeness,
+        /** `id`, `role`, `aria-live` and `aria-atomic` for the region element. */
+        regionAttrs,
         get message() {
             return message;
         },
@@ -32,3 +45,107 @@ export const useLiveAnnouncer = (baseId, suffix = 'live') => {
         }
     };
 };
+// Inline, so the regions stay hidden without depending on a utility class being compiled.
+const VISUALLY_HIDDEN = {
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    padding: '0',
+    margin: '-1px',
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    'white-space': 'nowrap',
+    border: '0'
+};
+/**
+ * A persistent pair of live regions, one polite (`role="status"`) and one assertive
+ * (`role="alert"`), for owners that announce events rather than render them in place
+ * (a Toaster announcing each toast, a list announcing its result count).
+ *
+ * Attach `host` once to an element that is always rendered and stays in the accessibility tree
+ * (no `hidden`, `display: none` or `visibility: hidden` ancestor). It inserts both regions empty
+ * as soon as it mounts, so they exist before the first announcement, and holds messages until
+ * the regions have settled. The host may render its own children: when Svelte empties it (a
+ * host whose only child is an `{#each}` is cleared at once when the list empties), the regions
+ * are put back with their text. Removing the host removes the regions.
+ */
+export const useLiveRegions = (baseId, suffix = 'live', { settleDelay = 100, clearAfter = 7000 } = {}) => {
+    const polite = useLiveAnnouncer(baseId, `${suffix}-polite`, { politeness: 'polite' });
+    const assertive = useLiveAnnouncer(baseId, `${suffix}-assertive`, {
+        politeness: 'assertive'
+    });
+    const clearTimers = {};
+    const cancelClear = (politeness) => {
+        clearTimeout(clearTimers[politeness]);
+        delete clearTimers[politeness];
+    };
+    const host = (node) => untrack(() => {
+        const ownerDocument = node.ownerDocument;
+        const createRegion = (announcer) => {
+            const region = ownerDocument.createElement('div');
+            for (const [name, value] of Object.entries(announcer.regionAttrs)) {
+                region.setAttribute(name, value);
+            }
+            region.setAttribute('data-live-region', announcer.politeness);
+            for (const [property, value] of Object.entries(VISUALLY_HIDDEN)) {
+                region.style.setProperty(property, value);
+            }
+            node.append(region);
+            return region;
+        };
+        const politeRegion = createRegion(polite);
+        const assertiveRegion = createRegion(assertive);
+        // Svelte empties a host whose only child is an `{#each}` with `textContent = ''` once
+        // the list is empty, taking the regions along: put them back as soon as that happens.
+        const restore = () => {
+            for (const region of [politeRegion, assertiveRegion]) {
+                if (region.parentNode !== node)
+                    node.append(region);
+            }
+        };
+        const observer = typeof MutationObserver === 'undefined' ? undefined : new MutationObserver(restore);
+        observer?.observe(node, { childList: true });
+        let settled = $state(settleDelay <= 0);
+        const settleTimer = settleDelay > 0 ? setTimeout(() => (settled = true), settleDelay) : undefined;
+        $effect(() => {
+            politeRegion.textContent = settled ? polite.message : '';
+            restore();
+        });
+        $effect(() => {
+            assertiveRegion.textContent = settled ? assertive.message : '';
+            restore();
+        });
+        return () => {
+            observer?.disconnect();
+            clearTimeout(settleTimer);
+            cancelClear('polite');
+            cancelClear('assertive');
+            politeRegion.remove();
+            assertiveRegion.remove();
+        };
+    });
+    return {
+        polite,
+        assertive,
+        host,
+        /** Announces `message` in the polite region, or the assertive one. */
+        announce(message, politeness = 'polite') {
+            const announcer = politeness === 'assertive' ? assertive : polite;
+            announcer.announce(message);
+            cancelClear(politeness);
+            if (clearAfter > 0) {
+                clearTimers[politeness] = setTimeout(() => {
+                    delete clearTimers[politeness];
+                    announcer.reset();
+                }, clearAfter);
+            }
+        },
+        /** Clears both regions and cancels pending announcements. */
+        reset() {
+            cancelClear('polite');
+            cancelClear('assertive');
+            polite.reset();
+            assertive.reset();
+        }
+    };
+};