@fusion.dev/helix-core 0.0.0-dev

package/dist/controllers/drilldown-controller/drilldown-controller.js

@@ -0,0 +1,171 @@
+/**
+ * One page of a nested set showing at a time, with a way back.
+ *
+ * A drill-down replaces the panel rather than opening a second one beside it.
+ * That is the right shape wherever there is no room for two: on a phone there
+ * is no second column, and on a touch screen there is no hover to open one
+ * with. What a reader gets instead is one panel, a title saying where they are,
+ * and a way back.
+ *
+ * **Extracted from `Menu`, which had all of this and did not say so.** The menu
+ * held a `page`, derived the rows on it, read a title off the row that opened
+ * it, and reset on close; the sandbox's settings dropdown has been a drill-down
+ * for as long as it has existed. None of that is about menus. Taking it out is
+ * what lets a settings panel, a filter stack or a navigation tree have the same
+ * behavior without one of them being a menu that is pretending.
+ *
+ * **The tree is the state.** A row's page is its own children, assigned to a
+ * slot, so the controller holds one reference, the row currently drilled into,
+ * and derives everything else from the DOM. The alternative, an id per page and
+ * a map beside it, is a second copy of the structure that a consumer can put
+ * out of step with the first.
+ *
+ * **A stack, not a pointer.** `back()` returns to the page above rather than to
+ * the root, because a reader three levels down pressed one control and expects
+ * one level. The stack is rebuilt from the DOM by walking up from the current
+ * row, so it cannot disagree with the tree: a page removed while it was showing
+ * takes its ancestors with it, and `atRoot` becomes true rather than the
+ * controller holding a reference to something detached.
+ *
+ * Nothing here decides what a row *is*, what it renders, or what happens when
+ * one is chosen. It answers where the reader is and what is on this page.
+ */
+export class DrilldownController {
+    constructor(host, options) {
+        /** The row whose page is showing, or nothing at the top. */
+        this.current = null;
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    /**
+     * The row whose page is showing, once the tree has been asked about it.
+     *
+     * **A held reference can outlive the row it names, and the walk alone does
+     * not catch it.** Removing the row a reader is *on* works: its
+     * `parentElement` is null and the walk stops. Removing one of its
+     * *ancestors* does not, because the subtree comes away intact, so the child
+     * still has a parent and the parent still has a parent. Measured on a
+     * three-level menu with the middle page removed: `depth` answered 2, `rows`
+     * listed a page nobody could see, and `back()` walked to a second detached
+     * row before reaching the top.
+     *
+     * That is the disagreement with the tree the walk exists to prevent, so the
+     * question is asked here, once, and every reader below goes through it.
+     */
+    get here() {
+        return this.current?.isConnected ? this.current : null;
+    }
+    /** The row whose page is showing, or `null` at the top. */
+    get page() {
+        return this.here;
+    }
+    /** Whether the top page is the one showing. */
+    get atRoot() {
+        return this.here === null;
+    }
+    /**
+     * How deep the reader is, with the top page at zero.
+     *
+     * Counted by walking up rather than by keeping a number, for the reason the
+     * stack is: a count can be wrong about a tree, and the tree is what renders.
+     */
+    get depth() {
+        let depth = 0;
+        for (let row = this.here; row; row = this.parentOf(row)) {
+            depth += 1;
+        }
+        return depth;
+    }
+    /**
+     * What the page showing is called.
+     *
+     * The row's own text and not its subtree, because a row that opens a page
+     * contains that page's rows: `textContent` would read back the whole thing.
+     * Empty at the top, where the panel's own label is the name of the place.
+     */
+    get label() {
+        return [...(this.here?.childNodes ?? [])]
+            .filter((node) => node.nodeType === Node.TEXT_NODE)
+            .map((node) => node.textContent?.trim() ?? '')
+            .filter(Boolean)
+            .join(' ');
+    }
+    /** The rows on the page showing, which is what the keyboard moves over. */
+    get rows() {
+        const slot = this.options.slot ?? 'page';
+        const isRow = this.options.isRow ?? (() => true);
+        const source = this.here
+            ? [...this.here.children].filter((child) => child.slot === slot)
+            : this.options.root();
+        return source.filter(isRow);
+    }
+    /** Whether a row has a page to drill into. */
+    hasPage(row) {
+        const slot = this.options.slot ?? 'page';
+        return [...row.children].some((child) => child.slot === slot);
+    }
+    /**
+     * Shows a row's page in place of the one showing.
+     *
+     * Refuses a row with no page rather than drilling into an empty one, which
+     * would leave a reader on a blank panel with a back control as its only
+     * content and nothing saying why.
+     */
+    enter(row) {
+        if (!this.hasPage(row)) {
+            return false;
+        }
+        this.current = row;
+        this.host.requestUpdate();
+        return true;
+    }
+    /** Returns to the page above, and reports whether there was one. */
+    back() {
+        const from = this.here;
+        if (from === null) {
+            /* Which includes a reader whose page has been taken out from under them:
+               they are already at the top, whatever this was still holding. */
+            this.current = null;
+            return false;
+        }
+        this.current = this.parentOf(from);
+        this.host.requestUpdate();
+        return true;
+    }
+    /**
+     * Returns to the top page.
+     *
+     * For closing rather than for navigating: a panel that reopens where it was
+     * left is showing a reader a place they have no memory of choosing.
+     */
+    reset() {
+        if (this.current === null) {
+            return;
+        }
+        this.current = null;
+        this.host.requestUpdate();
+    }
+    /**
+     * The row that opened the page this row is on.
+     *
+     * Walks up two steps, because a row sits inside the row that opened it: its
+     * parent element *is* that row. Read from the DOM each time rather than
+     * stored, so a tree the consumer has changed cannot leave this pointing at
+     * something no longer in it.
+     */
+    parentOf(row) {
+        const slot = this.options.slot ?? 'page';
+        if (row.slot !== slot) {
+            return null;
+        }
+        const parent = row.parentElement;
+        return parent && (this.options.isRow ?? (() => true))(parent)
+            ? parent
+            : null;
+    }
+    /** Back to the top when the host goes away, so it reopens where it opened. */
+    hostDisconnected() {
+        this.current = null;
+    }
+}

package/dist/controllers/floating-controller/floating-controller.d.ts

@@ -0,0 +1,123 @@
+import { type Placement } from '@floating-ui/dom';
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+export type { Placement };
+export interface FloatingOptions {
+    /** The element being pointed at. */
+    anchor: () => HTMLElement | null | undefined;
+    /**
+     * An element to point at the anchor, positioned against whichever side the
+     * floating element landed on.
+     */
+    arrow?: () => HTMLElement | null | undefined;
+    /** The element being placed. */
+    floating: () => HTMLElement | null | undefined;
+    /**
+     * Whether to try another side when the preferred one does not fit.
+     *
+     * On by default. A menu that opens off the bottom of the window is one the
+     * reader cannot use.
+     */
+    flip?: boolean;
+    /**
+     * Space between the anchor and the floating element, in pixels.
+     *
+     * A function where it can change. Options are read at construction, and a
+     * host's own properties are still at their class defaults then, before any
+     * attribute has been parsed.
+     */
+    offset?: number | (() => number);
+    /**
+     * Preferred placement. Defaults to `bottom-start`.
+     *
+     * A function where it can change. Passing the host's property directly reads
+     * it at construction, when it is still the class default, so every instance
+     * gets the same placement whatever its markup said.
+     */
+    placement?: Placement | (() => Placement);
+    /**
+     * Whether to cap the floating element to the space available.
+     *
+     * On by default, written as `--floating-available-block-size` and
+     * `--floating-available-width` rather than as a height. A list decides for
+     * itself whether to scroll or to shrink; a controller that sets the height
+     * has decided that for every element it places.
+     */
+    resize?: boolean;
+    /** Whether to slide along the side to stay in view. On by default. */
+    shift?: boolean;
+    /**
+     * A box to keep the surface inside, instead of the viewport.
+     *
+     * Applied to `shift` and to nothing else, which is the whole of the design.
+     * `shift` slides the surface along the axis it is *not* placed on, so for a
+     * bubble above its anchor this clamps x and leaves y alone, and a chart can
+     * say "stay within my own width" without also saying "stay within my own
+     * height", which would jam the bubble inside the drawing.
+     *
+     * Giving the same box to `flip` or `size` says the second thing. A tooltip
+     * above a reading almost never fits above it *within the chart*, so `flip`
+     * would send every one of them below the point, and `size` would compute an
+     * available height of nearly nothing and squash the box. Both were tried.
+     */
+    within?: () => Element | null | undefined;
+}
+/**
+ * Places one element against another, and keeps it there.
+ *
+ * Positioning is `@floating-ui/dom` rather than arithmetic written here. Two
+ * things in particular are why. A `position: fixed` element inside an ancestor
+ * carrying `transform`, `filter`, `will-change`, or `contain` is positioned
+ * against that ancestor and not the viewport, so viewport coordinates land it
+ * somewhere else entirely. And an overlay has to clear its nearest *clipping*
+ * ancestor, not just the window, or it is placed correctly inside a scrolling
+ * panel and clipped out of sight by it. Both are ordinary here, and both are a
+ * long tail of browser behavior rather than a formula.
+ *
+ * `autoUpdate` keeps the position through scrolling on any ancestor, resizes of
+ * either element, and layout shifts.
+ *
+ * The side the element actually landed on is written back as `data-placement`,
+ * so a styled tier can animate from it rather than from the side that was
+ * asked for.
+ *
+ * **The custom properties are declared here because this is what writes them.**
+ * Each carries a measurement taken against the viewport that no stylesheet can
+ * take for itself, and `core` ships no CSS, so there is no reader inside this
+ * package and none of them is private. `check:hooks` pairs a `@cssproperty`
+ * with a rule that reads one, in both directions, and the underscore these used
+ * to carry was what exempted them from it.
+ *
+ * @cssproperty --floating-anchor-inline-size - How wide the anchor is, for a panel that matches it.
+ * @cssproperty --floating-arrow-x - Where the pointer meets the anchor, along the inline axis.
+ * @cssproperty --floating-arrow-y - Where the pointer meets the anchor, along the block axis.
+ * @cssproperty --floating-available-block-size - How much room is left below, for a panel that scrolls.
+ */
+export declare class FloatingController implements ReactiveController {
+    private readonly options;
+    private cleanup;
+    /**
+     * Which run of placements the results coming back belong to.
+     *
+     * `computePosition` is async, so a measurement started before `stop()` still
+     * resolves after it and wrote its result onto a surface that had just been
+     * taken down: the inline `position` and `translate` went back on, and so did
+     * `data-placed`, which is the attribute five families gate visibility on.
+     * Opening and closing inside one task is all it takes, since the write lands
+     * a microtask later.
+     *
+     * A counter rather than an `AbortController`, because there is nothing to
+     * abort: the work is already done by the time the answer arrives and the only
+     * question is whether anybody still wants it.
+     */
+    private run;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: FloatingOptions);
+    /** The placement in use after the last measurement. */
+    placement: Placement;
+    /** Starts placing, and keeps placing until stopped. */
+    start(): void;
+    /** Stops placing and releases everything it was tracking. */
+    stop(): void;
+    /** Measures both elements and writes the position. */
+    readonly update: () => void;
+    hostDisconnected(): void;
+}

package/dist/controllers/floating-controller/floating-controller.js

@@ -0,0 +1,227 @@
+import { arrow, autoUpdate, computePosition, flip, offset, shift, size, } from '@floating-ui/dom';
+/**
+ * Places one element against another, and keeps it there.
+ *
+ * Positioning is `@floating-ui/dom` rather than arithmetic written here. Two
+ * things in particular are why. A `position: fixed` element inside an ancestor
+ * carrying `transform`, `filter`, `will-change`, or `contain` is positioned
+ * against that ancestor and not the viewport, so viewport coordinates land it
+ * somewhere else entirely. And an overlay has to clear its nearest *clipping*
+ * ancestor, not just the window, or it is placed correctly inside a scrolling
+ * panel and clipped out of sight by it. Both are ordinary here, and both are a
+ * long tail of browser behavior rather than a formula.
+ *
+ * `autoUpdate` keeps the position through scrolling on any ancestor, resizes of
+ * either element, and layout shifts.
+ *
+ * The side the element actually landed on is written back as `data-placement`,
+ * so a styled tier can animate from it rather than from the side that was
+ * asked for.
+ *
+ * **The custom properties are declared here because this is what writes them.**
+ * Each carries a measurement taken against the viewport that no stylesheet can
+ * take for itself, and `core` ships no CSS, so there is no reader inside this
+ * package and none of them is private. `check:hooks` pairs a `@cssproperty`
+ * with a rule that reads one, in both directions, and the underscore these used
+ * to carry was what exempted them from it.
+ *
+ * @cssproperty --floating-anchor-inline-size - How wide the anchor is, for a panel that matches it.
+ * @cssproperty --floating-arrow-x - Where the pointer meets the anchor, along the inline axis.
+ * @cssproperty --floating-arrow-y - Where the pointer meets the anchor, along the block axis.
+ * @cssproperty --floating-available-block-size - How much room is left below, for a panel that scrolls.
+ */
+export class FloatingController {
+    constructor(host, options) {
+        /**
+         * Which run of placements the results coming back belong to.
+         *
+         * `computePosition` is async, so a measurement started before `stop()` still
+         * resolves after it and wrote its result onto a surface that had just been
+         * taken down: the inline `position` and `translate` went back on, and so did
+         * `data-placed`, which is the attribute five families gate visibility on.
+         * Opening and closing inside one task is all it takes, since the write lands
+         * a microtask later.
+         *
+         * A counter rather than an `AbortController`, because there is nothing to
+         * abort: the work is already done by the time the answer arrives and the only
+         * question is whether anybody still wants it.
+         */
+        this.run = 0;
+        /** The placement in use after the last measurement. */
+        this.placement = 'bottom-start';
+        /** Measures both elements and writes the position. */
+        this.update = () => {
+            const anchor = this.options.anchor();
+            const floating = this.options.floating();
+            if (!anchor || !floating) {
+                return;
+            }
+            const run = this.run;
+            const pointer = this.options.arrow?.();
+            const gap = typeof this.options.offset === 'function' ? this.options.offset() : this.options.offset;
+            const preferred = typeof this.options.placement === 'function'
+                ? this.options.placement()
+                : this.options.placement;
+            const middleware = [offset(gap ?? 0)];
+            if (this.options.flip !== false) {
+                middleware.push(flip());
+            }
+            if (this.options.shift !== false) {
+                const inside = this.options.within?.();
+                middleware.push(shift({ padding: 8, ...(inside ? { boundary: inside } : {}) }));
+            }
+            if (this.options.resize !== false) {
+                middleware.push(size({
+                    /* The height and not the width, which is asymmetric on purpose. A
+                       panel that runs out of room grows a scrollbar downwards and every
+                       rule reading this asks for a `max-block-size`; nothing in the
+                       library has ever asked for the inline twin, so writing it was a
+                       `setProperty` on every reposition of every floating element for
+                       nobody. `check:hooks` is what says so out loud: declared and never
+                       read is a promise on the API page with nothing behind it. It comes
+                       back the day a rule wants it, together with that rule. */
+                    apply: ({ availableHeight, elements, rects }) => {
+                        elements.floating.style.setProperty('--floating-available-block-size', `${Math.round(availableHeight)}px`);
+                        /* The anchor's width, which a panel that has to match the control
+                           it hangs off cannot get any other way. `min-inline-size: 100%`
+                           reads the containing block, and this positions with
+                           `position: fixed`, so that percentage is the viewport: a select's
+                           list came out the full width of the window, flush to its left
+                           edge. It looked like a positioning fault and was a percentage
+                           resolving against something the CSS could not see. */
+                        elements.floating.style.setProperty('--floating-anchor-inline-size', `${Math.round(rects.reference.width)}px`);
+                    },
+                    padding: 8,
+                }));
+            }
+            if (pointer) {
+                middleware.push(arrow({ element: pointer }));
+            }
+            computePosition(anchor, floating, {
+                middleware,
+                placement: preferred ?? 'bottom-start',
+                // `fixed` so the overlay clears an ancestor with `overflow: hidden`.
+                // Floating UI resolves the containing block either way, so this is about
+                // clipping rather than about which coordinates are correct.
+                strategy: 'fixed',
+            }).then(({ middlewareData, placement, x, y }) => {
+                /* Stopped while this was being measured, so the answer is about a surface
+                   nobody is showing any more. Writing it would re-mark a closed panel as
+                   placed. */
+                if (run !== this.run) {
+                    return;
+                }
+                this.placement = placement;
+                Object.assign(floating.style, {
+                    insetBlockStart: '0',
+                    insetInlineStart: '0',
+                    position: 'fixed',
+                    // A translate rather than insets, so the position never lands on a
+                    // subpixel boundary and blurs the text inside it.
+                    //
+                    // **The `translate` property, not `transform`.** They are not
+                    // interchangeable here. The individual properties compose ahead of
+                    // `transform`, so a panel that also sets `scale` for an entrance ends
+                    // up with `scale() translate()`, and a concatenation applies its right
+                    // hand side first: the position is computed and *then* multiplied by
+                    // the scale factor. A tooltip 600px down the page scaling from 0.9
+                    // therefore opens 60px out of place and slides into position, and one
+                    // scaling from 0 flies in from the viewport corner. As `translate` it
+                    // composes as `translate() scale()`, the offset is applied in the
+                    // parent's coordinates, and the scale cannot reach it.
+                    /* **Written as viewport coordinates, which is what they are.**
+                     *
+                     * `computePosition` returns a position in the viewport and this element
+                     * is `position: fixed`, so the two agree and the translate is the answer
+                     * unmodified.
+                     *
+                     * **A correction used to sit here and it was answering the wrong
+                     * question.** A chart's bubble was landing hundreds of pixels from its
+                     * anchor, which looked like an ancestor stealing the containing block:
+                     * `transform`, `filter` and `backdrop-filter` all do that to a `fixed`
+                     * descendant, and the page's cards are glass. Measured, the bubble with
+                     * a zeroed translate sat at (799, 439) rather than the origin, which
+                     * seemed to confirm it.
+                     *
+                     * It was not that. 799 is `(1728 - 130) / 2` and 439 is near
+                     * `(1003 - 73) / 2`: the bubble was centered in the viewport, which is
+                     * what the UA stylesheet does to a `popover` through `inset: 0` and
+                     * `margin: auto`. The chart was rendering the *headless* tooltip, which
+                     * ships no styles to overrule that; `Tooltip` sets `margin: 0` and the
+                     * controller writes the insets, so a styled one was never centered and
+                     * never needed correcting. Fixing the tier fixed the position, and the
+                     * correction then subtracted a real ancestor's origin from an already
+                     * correct number and threw every tooltip on the page off by it.
+                     *
+                     * Recorded because the evidence for the wrong answer was a measurement,
+                     * not a guess, and the number that disproved it was arithmetic on the
+                     * viewport. */
+                    translate: `${Math.round(x)}px ${Math.round(y)}px`,
+                });
+                floating.setAttribute('data-placement', placement);
+                /* Placed, and it is a separate fact from shown. `computePosition` is
+                   async, so between the render that reveals a panel and the microtask
+                   that positions it there is a frame where the panel is visible at
+                   whatever its stylesheet said, which for an absolutely positioned one
+                   with no offsets is its host's top-left. Measured on the select: the
+                   panel appeared 24px up and to the left of the trigger for one frame on
+                   the first open, and looked correct on every open after, because the
+                   inline styles from last time were still on it.
+          
+                   A panel that wants to fade in on placement selects on this. Nothing has
+                   to: `data-placement` has been written here all along and this is its
+                   pair, so a component that ignores both is exactly as it was. */
+                floating.setAttribute('data-placed', '');
+                const point = middlewareData.arrow;
+                if (pointer && point) {
+                    Object.assign(pointer.style, {
+                        insetBlockStart: point.y === undefined ? '' : `${point.y}px`,
+                        insetInlineStart: point.x === undefined ? '' : `${point.x}px`,
+                    });
+                    /* Where the pointer ended up, as the center of it, published for
+                       anything that has to grow out of the thing it points at.
+                     *
+                     * A panel scaling in wants its `transform-origin` on its own arrow, and
+                     * the arrow is not reliably where the placement says: `top-start` puts
+                     * it near one end, and `shift` slides it anywhere along the edge to
+                     * keep the panel on screen. Selecting on `data-placement` alone gets
+                     * the axis right and the position wrong, which reads as the panel
+                     * growing out of a point next to the trigger rather than out of it.
+                     *
+                     * Only the axis the arrow travels on is written. On a `top` placement
+                     * the arrow moves horizontally and its vertical position is the panel's
+                     * edge, so `--floating-arrow-y` is left unset and a consumer's fallback
+                     * stands. Cleared rather than zeroed when absent, so the fallback in
+                     * `var()` is what applies. */
+                    floating.style.setProperty('--floating-arrow-x', point.x === undefined ? '' : `${Math.round(point.x + pointer.offsetWidth / 2)}px`);
+                    floating.style.setProperty('--floating-arrow-y', point.y === undefined ? '' : `${Math.round(point.y + pointer.offsetHeight / 2)}px`);
+                }
+            });
+        };
+        this.options = options;
+        // Registered so the host's disconnect releases the tracking, which is the
+        // whole reason this is a controller rather than a function.
+        host.addController(this);
+    }
+    /** Starts placing, and keeps placing until stopped. */
+    start() {
+        const anchor = this.options.anchor();
+        const floating = this.options.floating();
+        if (!anchor || !floating || this.cleanup) {
+            return;
+        }
+        this.cleanup = autoUpdate(anchor, floating, this.update);
+    }
+    /** Stops placing and releases everything it was tracking. */
+    stop() {
+        // Before the teardown, so a measurement already in flight is disowned
+        // rather than racing the attribute removal below.
+        this.run += 1;
+        this.cleanup?.();
+        this.cleanup = undefined;
+        this.options.floating()?.removeAttribute('data-placed');
+    }
+    hostDisconnected() {
+        this.stop();
+    }
+}

package/dist/controllers/focus-trap-controller/focus-trap-controller.d.ts

@@ -0,0 +1,26 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * Keeps Tab inside a container while it is open, and gives focus back after.
+ *
+ * A dialog that does not trap focus is one a keyboard user tabs straight out
+ * of, into a page they cannot see and cannot get back from. Restoring focus on
+ * release matters just as much: without it, closing a drawer drops the reader
+ * at the top of the document.
+ *
+ * Finding the focusable elements is `focusableElements`, which is a utility
+ * rather than part of this, because that half is what roving tabindex and
+ * arrow-key navigation need and neither of them traps anything.
+ */
+export declare class FocusTrapController implements ReactiveController {
+    private container;
+    /** The frame waiting to take focus, so a release can call it off. */
+    private frame;
+    private previous;
+    constructor(host: ReactiveControllerHost);
+    private readonly handleKeydown;
+    /** Starts trapping, remembering where focus came from. */
+    activate(container: HTMLElement): void;
+    /** Stops trapping and returns focus to wherever it was. */
+    deactivate(): void;
+    hostDisconnected(): void;
+}

package/dist/controllers/focus-trap-controller/focus-trap-controller.js

@@ -0,0 +1,93 @@
+import { deepActiveElement, deepContains, focusableElements, } from '../../utils/focusable-elements/focusable-elements.js';
+/**
+ * Keeps Tab inside a container while it is open, and gives focus back after.
+ *
+ * A dialog that does not trap focus is one a keyboard user tabs straight out
+ * of, into a page they cannot see and cannot get back from. Restoring focus on
+ * release matters just as much: without it, closing a drawer drops the reader
+ * at the top of the document.
+ *
+ * Finding the focusable elements is `focusableElements`, which is a utility
+ * rather than part of this, because that half is what roving tabindex and
+ * arrow-key navigation need and neither of them traps anything.
+ */
+export class FocusTrapController {
+    constructor(host) {
+        this.container = null;
+        this.previous = null;
+        this.handleKeydown = (event) => {
+            if (event.key !== 'Tab' || !this.container) {
+                return;
+            }
+            const items = focusableElements(this.container);
+            if (items.length === 0) {
+                // Nothing to move to, so keep focus where it is rather than letting Tab
+                // escape into the page behind.
+                event.preventDefault();
+                return;
+            }
+            const first = items[0];
+            const last = items.at(-1);
+            const active = deepActiveElement();
+            /* Which item holds focus, rather than which item *is* focus.
+             *
+             * `focusableElements` returns hosts: a `helix-button` delegates focus, so
+             * the list holds the component and `deepActiveElement` returns the
+             * `<button>` in its shadow root. They are never equal, and the container
+             * never `contains` the second, so this read `active === first` as false on
+             * the first element and "outside the trap" on every element. Measured
+             * against the two branches below, that made shift-Tab jump to the last item
+             * from anywhere and forward Tab never wrap at all, which is a trap that
+             * leaks in one direction and cannot be walked backwards in the other.
+             *
+             * An index also gives the outside-entirely case for free: -1 wraps to
+             * whichever end the reader was heading for. */
+            const at = items.findIndex((item) => item === active || deepContains(item, active));
+            if (event.shiftKey) {
+                if (at <= 0) {
+                    event.preventDefault();
+                    last.focus();
+                }
+            }
+            else if (at === -1 || at === items.length - 1) {
+                event.preventDefault();
+                first.focus();
+            }
+        };
+        host.addController(this);
+    }
+    /** Starts trapping, remembering where focus came from. */
+    activate(container) {
+        this.container = container;
+        this.previous = deepActiveElement();
+        document.addEventListener('keydown', this.handleKeydown, true);
+        /* After render, so the container has something to focus, and *held*, so a
+           release before the frame runs can cancel it.
+         *
+           Unheld, an overlay opened and closed inside one frame pulled focus into
+           itself a frame after it had gone: the reader is looking at the page, the
+           surface is not on it, and their next key goes somewhere they cannot see.
+           That is not a contrived sequence. A menu that closes on the same
+           activation that opened it does exactly this, and so does any consumer
+           toggling `open` twice in one task. */
+        this.frame = requestAnimationFrame(() => {
+            this.frame = undefined;
+            const items = focusableElements(container);
+            (items[0] ?? container).focus();
+        });
+    }
+    /** Stops trapping and returns focus to wherever it was. */
+    deactivate() {
+        if (this.frame !== undefined) {
+            cancelAnimationFrame(this.frame);
+            this.frame = undefined;
+        }
+        document.removeEventListener('keydown', this.handleKeydown, true);
+        this.container = null;
+        this.previous?.focus();
+        this.previous = null;
+    }
+    hostDisconnected() {
+        this.deactivate();
+    }
+}