@fusion.dev/helix-core 0.2.0 → 0.4.0

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

@@ -1,22 +1,4 @@
 import { deepActiveElement } from '../../utils/focusable-elements/focusable-elements.js';
-/*
- * The element that actually has focus, through any number of shadow roots.
- *
- * `document.activeElement` stops at the outermost host: focus inside a shadow
- * tree is reported as the element containing that tree, because what is inside
- * it is not the document's business. So a frame in a component's shadow root
- * reads as the component, and a check for a frame never matches one. Each root
- * keeps its own `activeElement`, so descending through them gives the element
- * the reader is really on.
- */
-/**
- * How deeply nested an overlay's host is, counting shadow boundaries as well.
- *
- * The innermost overlay is the one a reader means by Escape, and "innermost" has
- * to be measured rather than assumed from listener order: every overlay listens
- * on `document`, so they run in the order they opened, which is not the order
- * they are nested in.
- */
 const deepDepth = (node) => {
     let depth = 0;
     let at = node;
@@ -26,48 +8,7 @@ const deepDepth = (node) => {
     }
     return depth;
 };
-/**
- * Every overlay currently listening, so one press can be settled by asking.
- *
- * Module-level because that is the scope the question has: "which open overlay
- * is innermost" is about the page, and no single controller can answer it from
- * what it holds. Membership is exactly `activate`/`deactivate`, and
- * `hostDisconnected` calls the second, so an overlay torn down rather than
- * closed leaves too.
- */
 const listening = new Set();
-/**
- * Closes an overlay on Escape or on a pointer press outside it.
- *
- * Both, because they are different intentions with the same meaning: Escape is
- * the keyboard's way out and clicking away is the pointer's, and an overlay
- * that honors only one is one half its readers cannot dismiss.
- *
- * The outside press is watched on `pointerdown` rather than `click`, so a press
- * that starts outside and drags across the overlay still counts as leaving
- * rather than as interacting.
- *
- * A press inside a frame is the third case, and it needs its own signal. The
- * frame swallows the event, so the document that owns the overlay never sees a
- * `pointerdown` at all.
- *
- * Where the frame is same-origin there is a document to listen to, and this
- * listens to it: the same handler, on every reachable frame document, so a
- * press in there arrives as a press whose path holds nothing of the overlay,
- * which is what it is.
- *
- * **The focus signal alone was not enough, and a browser difference is why.**
- * A press in a frame moves focus into it in Chromium, so the window blurs and a
- * frame is what took focus. WebKit does neither: focus stays on the menu item
- * the reader pressed to open the overlay, the window never blurs, and every
- * observable thing about that tap says nothing happened. Measured on the
- * sandbox, whose preview is a frame filling half the tool, the settings menu
- * could not be dismissed by pressing the component it configures.
- *
- * Both signals are kept, because they answer different frames. The listener
- * only reaches same-origin ones; the blur only fires where the browser moves
- * focus. A cross-origin frame in Chromium has the second and not the first.
- */
 export class DismissController {
     constructor(host, { boundary, onDismiss }) {
         this.active = false;
@@ -75,31 +16,11 @@ export class DismissController {
             if (event.key !== 'Escape') {
                 return;
             }
-            /* One overlay per press, decided by asking all of them rather than by
-             * comparing against whoever ran before.
-             *
-             * `stopPropagation` cannot arrange this: every open overlay registers this
-             * same listener on `document`, so they are siblings on one node where the
-             * only ordering is registration, and propagation is about ancestors.
-             *
-             * Carrying the winning depth on the event does not arrange it either. A
-             * handler that runs before any deeper one has no way to know a deeper one
-             * exists, so it dismisses and only then loses the comparison. Registration
-             * order is the order the overlays
-             * *opened*, and opening the outer one first is the ordinary case: a dialog,
-             * then a select inside it. Measured, that closed both.
-             *
-             * So the first handler to see the press takes it for everybody, and picks
-             * the winner from every controller currently listening, which is a question
-             * that has one answer whenever it is asked. */
             const taken = event;
             if (taken.helixDismissTaken) {
                 return;
             }
             taken.helixDismissTaken = true;
-            /* Ties go to whoever asked, which is the first to run. Two overlays neither
-               of which is inside the other have no better answer available, and exactly
-               one closing is the point. */
             let deepest = this;
             let found = deepDepth(this.host);
             for (const other of listening) {
@@ -111,15 +32,6 @@ export class DismissController {
             }
             deepest.onDismiss();
         };
-        /**
-         * Focus left the document. If a frame took it, that was a press.
-         *
-         * Deferred by a task, because the order of `blur` against the focus moving is
-         * not something every browser agrees on and reading `activeElement` too early
-         * gives the element that is losing focus rather than the one taking it. The
-         * guard is for the case where the overlay closed for another reason in
-         * between, which would otherwise dismiss whatever opened next.
-         */
         this.handleWindowBlur = () => {
             setTimeout(() => {
                 if (this.active && deepActiveElement()?.tagName === 'IFRAME') {
@@ -128,16 +40,6 @@ export class DismissController {
             });
         };
         this.handlePointerDown = (event) => {
-            // `composedPath` rather than `target`, so a press inside the overlay's own
-            // shadow root is still recognized as inside it.
-            /* More than one thing can be inside.
-             *
-             * A control is not always one element: a popover opened by an invoker
-             * somewhere else on the page has that invoker as part of it, and a press on
-             * it is not a press outside. Treating it as outside closed the panel on
-             * `pointerdown` and the invoker's own `--toggle` reopened it on the `click`
-             * that followed, so the panel could never be closed by the button that
-             * opened it. */
             const inside = this.boundary?.() ?? this.host;
             const boundaries = (Array.isArray(inside) ? inside : [inside]).filter(Boolean);
             const path = event.composedPath();
@@ -145,35 +47,12 @@ export class DismissController {
                 this.onDismiss();
             }
         };
-        /**
-         * The frame documents being listened to, held so the same ones are released.
-         *
-         * Gathered when the overlay opens rather than watched for: an overlay is open
-         * for as long as a reader is deciding something, and a frame that arrives
-         * inside that window is a page rebuilding itself under a menu, which is not a
-         * case worth a `MutationObserver` on every open surface. Held rather than
-         * re-collected on the way out, because a frame removed while the overlay was
-         * open would otherwise be missed and one navigated elsewhere would be a
-         * different document.
-         */
         this.frames = [];
         this.host = host;
         this.boundary = boundary;
         this.onDismiss = onDismiss;
         host.addController(this);
     }
-    /**
-     * Every frame document on the page this one is allowed to read.
-     *
-     * Through the shadow roots as well, because a component that renders a frame
-     * renders it inside itself: the sandbox's preview is one, and
-     * `document.querySelectorAll` cannot see it.
-     *
-     * A cross-origin frame throws on `contentDocument` rather than returning
-     * null in some browsers, so the read is guarded and the frame is simply
-     * skipped. Nothing is lost by skipping it that was not already lost: there is
-     * no listener to add to a document this one may not touch.
-     */
     static frameDocuments() {
         const found = [];
         const walk = (root) => {
@@ -186,7 +65,6 @@ export class DismissController {
                         }
                     }
                     catch {
-                        // Cross-origin. The blur signal is what covers those.
                     }
                 }
                 if (element.shadowRoot) {
@@ -197,7 +75,6 @@ export class DismissController {
         walk(document);
         return found;
     }
-    /** Starts listening. */
     activate() {
         if (this.active) {
             return;
@@ -212,7 +89,6 @@ export class DismissController {
             inner.addEventListener('pointerdown', this.handlePointerDown);
         }
     }
-    /** Stops listening. */
     deactivate() {
         if (!this.active) {
             return;

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

@@ -1,72 +1,19 @@
-/**
- * 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.
- *
- * **None of this is about menus.** A settings panel, a filter stack or a
- * navigation tree gets the same behavior without 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)) {
@@ -74,13 +21,6 @@ export class DrilldownController {
         }
         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)
@@ -88,7 +28,6 @@ export class DrilldownController {
             .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);
@@ -97,18 +36,10 @@ export class DrilldownController {
             : 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;
@@ -117,12 +48,9 @@ export class DrilldownController {
         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;
         }
@@ -130,12 +58,6 @@ export class DrilldownController {
         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;
@@ -143,14 +65,6 @@ export class DrilldownController {
         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) {
@@ -161,7 +75,6 @@ export class DrilldownController {
             ? 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.js

@@ -1,30 +1,4 @@
 import { arrow, autoUpdate, computePosition, flip, offset, shift, size, } from '@floating-ui/dom';
-/**
- * The panel's largest corner radius, which is how far its arrow has to stay
- * from either end.
- *
- * **Without it the arrow is correctly aimed and looks wrong.** Floating UI
- * centers the arrow on the anchor, and on a small trigger that center is inside
- * the panel's own corner: the arrow's base meets the curve instead of a straight
- * run and its outer flank is cut by it. Measured against a 4px radius and an 8px
- * arrow, a 14px trigger put the arrow's near flank 1.5px from the panel's edge
- * and a 20px trigger put it at 4.3px, so anything narrower than the arrow plus
- * two radii is broken by construction. An icon beside a heading is the ordinary
- * way to be under that.
- *
- * `padding` is what Floating UI's `arrow` middleware takes for exactly this, and
- * its own guidance for a rounded surface is the border radius.
- *
- * **Measured rather than named**, so a family that rounds itself differently is
- * right without telling this controller. Reading a token here would put a value
- * from `helix/styles` into a tier that must not name one, and would still be
- * wrong for any component that overrides its own radius. The four corners rather
- * than one, because they can differ and the arrow travels along two of them; the
- * largest clears all of them.
- *
- * A percentage is refused rather than guessed at: it resolves against the box,
- * which is the thing being positioned.
- */
 const corner = (floating) => {
     const style = getComputedStyle(floating);
     const corners = [
@@ -45,56 +19,10 @@ const corner = (floating) => {
     }
     return largest;
 };
-/**
- * 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. the `hooks` rule pairs a documented
- * hook with a rule that reads one, in both directions.
- *
- * @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 would write its result onto a surface that had just
-         * been taken down: the inline `position` and `translate` back on, and with
-         * them `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();
@@ -117,22 +45,8 @@ export class FloatingController {
             }
             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 asks for the
-                       inline twin, so writing it would be a `setProperty` on every
-                       reposition of every floating element for nobody. 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,
@@ -144,14 +58,8 @@ export class FloatingController {
             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;
                 }
@@ -160,48 +68,9 @@ export class FloatingController {
                     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. **Never subtract an ancestor's origin from it.**
-                     *
-                     * A surface landing hundreds of pixels from its anchor looks like an
-                     * ancestor stealing the containing block, which `transform`, `filter`
-                     * and `backdrop-filter` all do to a `fixed` descendant. Check the tier
-                     * first: the UA stylesheet centers a `popover` through `inset: 0` and
-                     * `margin: auto`, and the headless tooltip ships no styles to overrule
-                     * it, so it sits mid-viewport with a zeroed translate while `Tooltip`,
-                     * which sets `margin: 0`, never does. A correction added for that
-                     * subtracts a real ancestor's origin from an already correct number and
-                     * throws every tooltip on the page off by it. */
                     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. */
                 floating.setAttribute('data-placed', '');
                 const point = middlewareData.arrow;
                 if (pointer && point) {
@@ -209,32 +78,14 @@ export class FloatingController {
                         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();
@@ -243,10 +94,7 @@ export class FloatingController {
         }
         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;

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

@@ -1,16 +1,4 @@
 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;
@@ -21,25 +9,12 @@ export class FocusTrapController {
             }
             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 an identity check reads "outside the
-             * trap" on every element: against the two branches below, shift-Tab jumps
-             * to the last item from anywhere and forward Tab never wraps at all.
-             *
-             * 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) {
@@ -54,26 +29,16 @@ export class FocusTrapController {
         };
         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 pulls focus into
-           itself a frame after it has gone: the reader is looking at the page, the
-           surface is not on it, and their next key goes somewhere they cannot see.
-           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);