@fusion.dev/helix-core 0.0.0-dev

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

@@ -0,0 +1,97 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * What an indicator needs to know, asked for rather than assumed.
+ */
+export interface IndicatorOptions {
+    /** The element that is currently marked, or nothing if none is. */
+    active: () => HTMLElement | null | undefined;
+    /** The traveling mark. Positioned against the surface. */
+    indicator: () => HTMLElement | null | undefined;
+    /**
+     * The box the mark is positioned against, which is its containing block.
+     *
+     * Not the host. An absolutely positioned element is placed against its
+     * containing block's *padding* box, so this has to be whichever element
+     * carries `position: relative`, and that is usually a part rather than the
+     * host itself.
+     */
+    surface: () => HTMLElement | null | undefined;
+}
+/**
+ * Measures the marked child and writes the geometry onto a traveling mark.
+ *
+ * **Four components had written this and the copies had diverged.** `Navigation`,
+ * `Tabs`, `Toggle.Group` and `Outline` each measured an active child and wrote
+ * a position onto an indicator, and two of them had bugs the others did not.
+ * `Outline`'s own comment counted the repetition rather than resolving it, and
+ * the audit found the same shape independently in all four.
+ *
+ * What the copies disagreed about, and what this settles:
+ *
+ * **The inline axis is signed.** In a right-to-left document the distance is
+ * measured from the surface's right edge and applied as a negative translation,
+ * because the mark travels from the inline start and the inline start is on the
+ * right. `Navigation` measured from the physical left and applied it from the
+ * inline-start edge with an unsigned offset, so its marker went the wrong way
+ * in RTL. That is the bug this extraction exists to stop repeating.
+ *
+ * **The border has to come off both axes.** `getBoundingClientRect` gives the
+ * border box and the containing block is the padding box, so a surface with a
+ * border of its own puts the mark one border-width out. `Tabs` and
+ * `Toggle.Group` each did this arithmetic separately, `Outline` did the block
+ * half with `clientTop`, and `Navigation` did neither. `clientLeft` and `clientTop`
+ * are the border widths, already resolved, which is why they are used here
+ * rather than parsing `borderLeftWidth`.
+ *
+ * **Nothing is written until there is something to measure.** A zero-width box
+ * is a component whose children have not upgraded yet, and writing zeroes would
+ * park the mark at the origin and leave it there. The `data-placed` attribute is
+ * what a stylesheet waits for, so a mark fades in where it belongs rather than
+ * sliding from the corner on first paint.
+ *
+ * The four custom properties are the contract. What a component does with them
+ * is its own business, which is how one controller serves a bar under a tab, a
+ * pill filling it, and a rule down the side of a contents page.
+ *
+ * **Declared here because this is what writes them.** They carry a measurement
+ * no stylesheet can take, they are read by whoever draws the mark, and `core`
+ * ships no CSS, so there is no reader inside this package and nothing about
+ * 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 --indicator-block-size - How tall the active item is, in pixels.
+ * @cssproperty --indicator-inline-size - How wide the active item is, in pixels.
+ * @cssproperty --indicator-x - Where the active item starts, along the inline axis.
+ * @cssproperty --indicator-y - Where the active item starts, along the block axis.
+ */
+export declare class IndicatorController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    private resize;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: IndicatorOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Called after every update, which is when the marked child may have moved. */
+    hostUpdated(): void;
+    /** Where the mark was last put, so a placement can tell a move from a resize. */
+    private last;
+    /** The guard behind `transitionend`, in case it never comes. */
+    private settling;
+    /**
+     * The listener currently waiting, so the next move can take it off first.
+     *
+     * **Without this, a move inside a second orphans a listener.** Each placement
+     * built a fresh `settle` closure and then called `clearTimeout` on the timer
+     * belonging to the *previous* one, which is the only thing that would have
+     * removed it: the event itself never arrives under reduced motion, where
+     * there is no transition to end. So a reader changing tabs quickly, or any
+     * reader at all with motion reduced, left one dead listener per selection on
+     * an element that lives as long as the page. The people who asked for less
+     * work were the ones accumulating it.
+     */
+    private waiting;
+    place(): void;
+    /** Takes the pending listener and its guard off, wherever they came from. */
+    private stopWaiting;
+}

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

@@ -0,0 +1,164 @@
+/**
+ * Measures the marked child and writes the geometry onto a traveling mark.
+ *
+ * **Four components had written this and the copies had diverged.** `Navigation`,
+ * `Tabs`, `Toggle.Group` and `Outline` each measured an active child and wrote
+ * a position onto an indicator, and two of them had bugs the others did not.
+ * `Outline`'s own comment counted the repetition rather than resolving it, and
+ * the audit found the same shape independently in all four.
+ *
+ * What the copies disagreed about, and what this settles:
+ *
+ * **The inline axis is signed.** In a right-to-left document the distance is
+ * measured from the surface's right edge and applied as a negative translation,
+ * because the mark travels from the inline start and the inline start is on the
+ * right. `Navigation` measured from the physical left and applied it from the
+ * inline-start edge with an unsigned offset, so its marker went the wrong way
+ * in RTL. That is the bug this extraction exists to stop repeating.
+ *
+ * **The border has to come off both axes.** `getBoundingClientRect` gives the
+ * border box and the containing block is the padding box, so a surface with a
+ * border of its own puts the mark one border-width out. `Tabs` and
+ * `Toggle.Group` each did this arithmetic separately, `Outline` did the block
+ * half with `clientTop`, and `Navigation` did neither. `clientLeft` and `clientTop`
+ * are the border widths, already resolved, which is why they are used here
+ * rather than parsing `borderLeftWidth`.
+ *
+ * **Nothing is written until there is something to measure.** A zero-width box
+ * is a component whose children have not upgraded yet, and writing zeroes would
+ * park the mark at the origin and leave it there. The `data-placed` attribute is
+ * what a stylesheet waits for, so a mark fades in where it belongs rather than
+ * sliding from the corner on first paint.
+ *
+ * The four custom properties are the contract. What a component does with them
+ * is its own business, which is how one controller serves a bar under a tab, a
+ * pill filling it, and a rule down the side of a contents page.
+ *
+ * **Declared here because this is what writes them.** They carry a measurement
+ * no stylesheet can take, they are read by whoever draws the mark, and `core`
+ * ships no CSS, so there is no reader inside this package and nothing about
+ * 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 --indicator-block-size - How tall the active item is, in pixels.
+ * @cssproperty --indicator-inline-size - How wide the active item is, in pixels.
+ * @cssproperty --indicator-x - Where the active item starts, along the inline axis.
+ * @cssproperty --indicator-y - Where the active item starts, along the block axis.
+ */
+export class IndicatorController {
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    hostConnected() {
+        /* The host's own size is not enough: a strip that keeps its width while its
+           children rewrap moves every one of them, and a mark measured against the
+           old layout is left behind. Observing the host catches both, because a
+           rewrap changes its height. */
+        this.resize = new ResizeObserver(() => this.place());
+        this.resize.observe(this.host);
+    }
+    hostDisconnected() {
+        this.resize?.disconnect();
+        this.resize = undefined;
+        /* The host going away is the third way a move can end, and the one nothing
+           was watching. A timer holding a closure over a detached element keeps it
+           alive for the second it has left to run. */
+        this.stopWaiting();
+    }
+    /** Called after every update, which is when the marked child may have moved. */
+    hostUpdated() {
+        this.place();
+    }
+    /*
+     * Measures and writes, or gives up without writing anything.
+     *
+     * Public because `slotchange` is not an update: children arriving is exactly
+     * when the first measurement becomes possible, and a component that only
+     * placed on its own updates left the mark unplaced for the life of the page.
+     */
+    place() {
+        const indicator = this.options.indicator();
+        const surface = this.options.surface();
+        const active = this.options.active();
+        if (!indicator || !surface) {
+            return;
+        }
+        if (!active) {
+            // Nothing is marked, so there is nothing to point at. The attribute goes
+            // and the stylesheet takes the mark away with it.
+            indicator.removeAttribute('data-placed');
+            return;
+        }
+        const box = active.getBoundingClientRect();
+        const own = surface.getBoundingClientRect();
+        if (box.width === 0 && box.height === 0) {
+            return;
+        }
+        /* `clientLeft` and `clientTop` are the resolved border widths, which is the
+           difference between the border box the measurement gives and the padding
+           box the mark is placed against. */
+        const rtl = getComputedStyle(surface).direction === 'rtl';
+        const inline = rtl
+            ? own.right - box.right - surface.clientLeft
+            : box.left - own.left - surface.clientLeft;
+        const x = `${rtl ? -inline : inline}px`;
+        const y = `${box.top - own.top - surface.clientTop}px`;
+        /* `data-moving` while it is on its way, so a stylesheet can say something
+         * about the travel itself.
+         *
+         * There is no CSS state for "a transition is running", and the effect this
+         * exists for wants one: a mark that swells as it leaves and settles back
+         * when it lands reads as a thing being carried rather than a rectangle
+         * being repositioned. The controller is the only thing that knows a move
+         * has been asked for, so it says so.
+         *
+         * Only on a *change*, and never on the first placement: the mark arrives by
+         * fading in, and swelling on arrival would be an animation about nothing.
+         *
+         * Cleared on `transitionend` with a timeout behind it. The event is the
+         * honest signal and it does not always come: a move under reduced motion
+         * has no transition to end, and neither does one whose computed position
+         * turns out identical after a resize. A marker that can stick is worse than
+         * one that clears a little early. */
+        const moved = this.last !== undefined && (this.last.x !== x || this.last.y !== y);
+        this.last = { x, y };
+        indicator.style.setProperty('--indicator-x', x);
+        indicator.style.setProperty('--indicator-y', y);
+        indicator.style.setProperty('--indicator-inline-size', `${box.width}px`);
+        indicator.style.setProperty('--indicator-block-size', `${box.height}px`);
+        indicator.toggleAttribute('data-placed', true);
+        if (!moved) {
+            return;
+        }
+        indicator.toggleAttribute('data-moving', true);
+        this.stopWaiting();
+        /* `translate` only. `transitionend` fires once per property, and a
+           stylesheet reacting to `data-moving` is very likely to transition
+           something shorter than the travel: the outline's mark widens over
+           `duration-fast` while it travels over `duration-normal`, so an unfiltered
+           listener had the width's own transition end the move that caused it, a
+           third of the way through. */
+        const settle = (event) => {
+            if (event && event.propertyName !== 'translate') {
+                return;
+            }
+            indicator.removeAttribute('data-moving');
+            this.stopWaiting();
+        };
+        indicator.addEventListener('transitionend', settle);
+        this.waiting = { on: indicator, settle };
+        this.settling = setTimeout(settle, 1000);
+    }
+    /** Takes the pending listener and its guard off, wherever they came from. */
+    stopWaiting() {
+        clearTimeout(this.settling);
+        this.settling = undefined;
+        if (this.waiting) {
+            this.waiting.on.removeEventListener('transitionend', this.waiting.settle);
+            this.waiting = undefined;
+        }
+    }
+}

package/dist/controllers/keyboard-navigation-controller/keyboard-navigation-controller.d.ts

@@ -0,0 +1,113 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What a controller needs of an item to move to it and choose it. */
+export interface NavigableItem {
+    /**
+     * Whether the press came from inside this item, for `origin: 'focus'`.
+     *
+     * Every item that uses this is an element, so this is `Node.contains` and
+     * nothing has to implement it. It is declared because the controller depends
+     * on it, and a structural interface that leaves out what it calls is a
+     * `NavigableItem` a component can satisfy and still break.
+     */
+    contains(node: Node | null): boolean;
+    /** Whether the item can be reached at all. Skipped when it cannot. */
+    disabled: boolean;
+    /** Moves focus to the item, which each family does its own way. */
+    focusItem(): void;
+    /** Chooses the item, which for a radio group is the same act as arriving. */
+    select(): void;
+    /** Whether the item is the current one, which is where movement starts. */
+    selected: boolean;
+}
+/** How the controller is told what it is moving through. */
+export interface KeyboardNavigationOptions {
+    /** The items, in the order a reader moves through them. */
+    items: () => NavigableItem[];
+    /**
+     * Where a move starts from.
+     *
+     * `selection` is the radio-group reading and the default: the set has one
+     * answer, focus is always on it, and the two never diverge.
+     *
+     * `focus` is for a set where they can. Tabs is the case: in `manual` mode a
+     * reader arrows without choosing, so after one press focus is no longer on
+     * the selection, and starting from the selection walks from the same place
+     * every time. It is also the only reading that can tell a press on a tab from
+     * a press somewhere else in the component, which matters wherever the host
+     * holds more than the set (a tab panel is a tab stop of its own).
+     */
+    origin?: 'focus' | 'selection';
+    /**
+     * Whether arriving also chooses.
+     *
+     * A function rather than a flag: Tabs takes it from `manual`, which a
+     * consumer can change at any time, and a value read once in the constructor
+     * would be the value the element happened to have when it upgraded.
+     */
+    selects?: () => boolean;
+    /**
+     * Keys this component binds to something else, which this must not take.
+     *
+     * **A claim, not a preference.** "Both axes, always" is argued below and the
+     * argument holds: a reader who guesses the wrong axis and gets nothing is a
+     * reader who concludes the set does not answer the keyboard. So this is not a
+     * way to support fewer keys. It is a way to say that a key already means
+     * something here, and a component that names one owes that key a binding of
+     * its own.
+     *
+     * `Menu` is the case it was written for. Its rows can open a submenu, and the
+     * platform's own bindings for that are the horizontal pair: right goes in,
+     * left comes back. Those keys are not unhandled in a menu, they are spoken
+     * for, and without this the controller would take them first and a submenu
+     * could not be opened from the keyboard at all.
+     */
+    reserved?: () => string[];
+    /**
+     * Whether the ends join up. Radio groups wrap; a list of commands does not.
+     */
+    wrap?: boolean;
+}
+/**
+ * Moves through a set of items with the arrow keys, and chooses as it goes.
+ *
+ * **Moving and choosing are one act here, not two.** That is the radio group
+ * pattern and it is the difference from a listbox: moving focus without
+ * choosing leaves a keyboard reader sitting on an item they have not selected,
+ * with nothing on screen saying which of the two is true. A pointer user
+ * chooses by arriving, so a keyboard user does too.
+ *
+ * **Both axes, always.** A vertical set still answers left and right, and a
+ * horizontal one still answers up and down. Binding only the axis the items
+ * happen to be laid out on means a reader who guesses wrong gets nothing, and
+ * `orientation` is presentation: the same set of choices reads the same way
+ * whichever direction it runs.
+ *
+ * Disabled items are skipped rather than stopped at, so a set with a gap in it
+ * still moves in one press.
+ *
+ * Written because `Radio.Group` and `Toggle.Group` had this twice, identically,
+ * down to the order of the branches. The second copy is what makes it a
+ * controller: one is a component's own business, two is a pattern, and the two
+ * had not diverged only because nothing had touched them yet.
+ *
+ * **`Tabs` is the third, and it is what `origin` and `selects` are for.** It had
+ * diverged, which is the case the paragraph above was worried about: it started
+ * from focus rather than from the selection, and it moved without choosing when
+ * `manual` was set. Both are real and neither is a tabs-only idea, so they are
+ * options here rather than a reason to keep a fourth copy. What it does *not*
+ * keep is its own key set: it bound the horizontal pair only, and both axes is
+ * the house position, argued two paragraphs up. A reader on a tab who presses
+ * Down now moves along the row instead of getting nothing.
+ */
+export declare class KeyboardNavigationController implements ReactiveController {
+    private readonly host;
+    private readonly items;
+    private readonly origin;
+    private readonly selects;
+    private readonly reserved;
+    private readonly wrap;
+    constructor(host: ReactiveControllerHost & HTMLElement, { items, origin, reserved, selects, wrap, }: KeyboardNavigationOptions);
+    private readonly handleKeydown;
+    hostConnected(): void;
+    hostDisconnected(): void;
+}

package/dist/controllers/keyboard-navigation-controller/keyboard-navigation-controller.js

@@ -0,0 +1,117 @@
+/** Every key that moves within a set, which is the whole of what this handles. */
+const KEYS = new Set(['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Home']);
+/**
+ * Moves through a set of items with the arrow keys, and chooses as it goes.
+ *
+ * **Moving and choosing are one act here, not two.** That is the radio group
+ * pattern and it is the difference from a listbox: moving focus without
+ * choosing leaves a keyboard reader sitting on an item they have not selected,
+ * with nothing on screen saying which of the two is true. A pointer user
+ * chooses by arriving, so a keyboard user does too.
+ *
+ * **Both axes, always.** A vertical set still answers left and right, and a
+ * horizontal one still answers up and down. Binding only the axis the items
+ * happen to be laid out on means a reader who guesses wrong gets nothing, and
+ * `orientation` is presentation: the same set of choices reads the same way
+ * whichever direction it runs.
+ *
+ * Disabled items are skipped rather than stopped at, so a set with a gap in it
+ * still moves in one press.
+ *
+ * Written because `Radio.Group` and `Toggle.Group` had this twice, identically,
+ * down to the order of the branches. The second copy is what makes it a
+ * controller: one is a component's own business, two is a pattern, and the two
+ * had not diverged only because nothing had touched them yet.
+ *
+ * **`Tabs` is the third, and it is what `origin` and `selects` are for.** It had
+ * diverged, which is the case the paragraph above was worried about: it started
+ * from focus rather than from the selection, and it moved without choosing when
+ * `manual` was set. Both are real and neither is a tabs-only idea, so they are
+ * options here rather than a reason to keep a fourth copy. What it does *not*
+ * keep is its own key set: it bound the horizontal pair only, and both axes is
+ * the house position, argued two paragraphs up. A reader on a tab who presses
+ * Down now moves along the row instead of getting nothing.
+ */
+export class KeyboardNavigationController {
+    constructor(host, { items, origin = 'selection', reserved = () => [], selects = () => true, wrap = true, }) {
+        this.handleKeydown = (event) => {
+            if (!KEYS.has(event.key) || this.reserved().includes(event.key)) {
+                return;
+            }
+            const items = this.items().filter((item) => !item.disabled);
+            if (items.length === 0) {
+                return;
+            }
+            /* `-1` means two different things and only one of them is a starting point.
+             *
+               Starting from the selection, `-1` is "nothing is chosen", and the
+               arithmetic below relies on it: a forward step lands on the first item and
+               a backward step on the last, both of which are where a reader entering an
+               unanswered set expects to arrive.
+        
+               Starting from focus, `-1` is "the press did not come from the set", and
+               there is nothing to move. The listener is on the host, not on the items,
+               and a host can hold more than the set: a tab panel is `tabindex="0"`, so
+               an arrow pressed while reading a panel used to move the tabs out from
+               under the reader. */
+            const current = this.origin === 'focus'
+                ? items.findIndex((item) => item.contains(event.target))
+                : items.findIndex((item) => item.selected);
+            if (this.origin === 'focus' && current === -1) {
+                return;
+            }
+            const last = items.length - 1;
+            let next = current;
+            if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+                next = this.wrap ? (current + 1) % items.length : Math.min(current + 1, last);
+            }
+            else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+                /* From nothing, backwards is the last, which the arithmetic did not give.
+                 *
+                 * `(-1 - 1 + length) % length` is `length - 2`: the *second* to last. So a
+                 * reader arrowing backwards into an unanswered group landed one short of
+                 * the end, and the comment above says plainly that it lands on the end.
+                 * The wrapping form is right for every real index and wrong for the one
+                 * that is not an index.
+                 *
+                 * And the clamp is `Math.max` against the forward branch's `Math.min`,
+                 * which it was missing. Unclamped this is `-1` on the first item, and
+                 * `items[-1]` is undefined, so nothing was focused and nothing chosen on a
+                 * press that `preventDefault` had already swallowed. Holding Left on the
+                 * first star of a rating got silence, where holding Right on the last one
+                 * holds its ground. */
+                next =
+                    current < 0
+                        ? last
+                        : this.wrap
+                            ? (current - 1 + items.length) % items.length
+                            : Math.max(current - 1, 0);
+            }
+            else if (event.key === 'Home') {
+                next = 0;
+            }
+            else {
+                next = last;
+            }
+            event.preventDefault();
+            const target = items[next];
+            target?.focusItem();
+            if (this.selects()) {
+                target?.select();
+            }
+        };
+        this.host = host;
+        this.items = items;
+        this.origin = origin;
+        this.reserved = reserved;
+        this.selects = selects;
+        this.wrap = wrap;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('keydown', this.handleKeydown);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('keydown', this.handleKeydown);
+    }
+}

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

@@ -0,0 +1,132 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type Placement } from '../floating-controller/floating-controller.js';
+export interface PopoverOptions {
+    /** The element the surface opens against. */
+    anchor: () => HTMLElement | null | undefined;
+    /**
+     * The element that points at the anchor, where the surface has one.
+     *
+     * Passed through to the floating pass, which positions it against whichever
+     * side the surface ended up on. Optional because most surfaces have none: a
+     * menu and a select are read as belonging to the control they hang off, and
+     * only a bubble has to say which thing it is describing.
+     */
+    arrow?: () => HTMLElement | null | undefined;
+    /**
+     * What counts as inside for the purpose of a press landing elsewhere.
+     *
+     * Defaults to the surface. A host that draws no box of its own points this at
+     * itself instead, so a press on its trigger is inside rather than out.
+     */
+    boundary?: () => Element | readonly (Element | null | undefined)[] | null | undefined;
+    /** Space between the anchor and the surface, in pixels. */
+    offset?: number | (() => number);
+    /**
+     * A box to keep the surface inside, instead of the viewport.
+     *
+     * Not `boundary` above, and the two are easy to confuse: that one decides
+     * what counts as inside for a *press*, and this one decides what counts as
+     * inside for the *placement*. A tooltip on a chart wants the second and has
+     * no use for the first.
+     */
+    within?: () => Element | null | undefined;
+    /**
+     * Whether to measure the anchor and place the surface against it.
+     *
+     * On unless said otherwise, which is every surface that hangs off something:
+     * a menu, a select, a tooltip. Off is for a surface whose position is a fact
+     * about the page rather than about its trigger, and the one that asked for
+     * it is a full-bleed navigation panel: it spans the viewport and sits under
+     * the header, so there is nothing to measure and nothing to flip or shift
+     * to. Placing it anyway wrote a `translate` of the trigger's own offset over
+     * a band that is meant to start at the edge.
+     *
+     * The rest still applies, which is why this is an option here rather than a
+     * reason to do without the controller: the top layer and the dismissal are
+     * exactly what such a panel needs, and they are what this bundles. What it
+     * gives up is the measuring pass, and the surface's own stylesheet says where
+     * it goes.
+     */
+    place?: boolean | (() => boolean);
+    /**
+     * Called when a press outside or an Escape asks for it to close.
+     *
+     * The host decides what closing means, because it is the only thing that
+     * knows what else has to happen: a menu forgets which page it was on, a
+     * select puts focus back on its trigger, and a tooltip does neither.
+     */
+    onDismiss: () => void;
+    /** Preferred side. It moves if that side does not fit. */
+    placement?: Placement | (() => Placement);
+    /** The panel that floats. */
+    surface: () => HTMLElement | null | undefined;
+}
+/**
+ * A surface that floats against something, in the top layer, until dismissed.
+ *
+ * Three things always travel together and were written out longhand three
+ * times: the popover API, a `FloatingController` and a `DismissController`.
+ * Individually each is small, which is exactly why the copies drifted rather
+ * than being noticed. **`Select` never called `showPopover` at all**, so its
+ * list was an ordinary positioned panel and any ancestor with `overflow:
+ * hidden` clipped it, while a menu two folders away in the same position did
+ * not. That is not a difference anyone chose.
+ *
+ * **The top layer is the whole point.** A floating panel has to escape every
+ * clipping ancestor between it and the page, and `position: fixed` does not do
+ * that: it is clipped by `overflow` on any ancestor and re-anchored entirely by
+ * an ancestor carrying `transform`, `filter` or `contain`. The popover API
+ * lifts the element out of the tree's paint order for real, and it is the only
+ * thing that does.
+ *
+ * `manual` rather than `auto`, because the host owns dismissal. `auto`
+ * popovers light-dismiss themselves and close each other, which is close to
+ * what is wanted and not the same: a select that closed itself before its own
+ * change event landed, or a submenu that closed its parent, are both things the
+ * platform would do here and neither is right.
+ *
+ * **The order matters on the way up.** `showPopover` first, then position:
+ * measuring an element that is still `display: none` gives zeroes, so a surface
+ * positioned before it is shown lands at the origin and slides into place on
+ * the next frame. On the way down it is the reverse, and stopping the observer
+ * before hiding avoids a final measurement of an element on its way out.
+ *
+ * What this does not own is *when*. Opening is the host's, because a menu opens
+ * on click, a tooltip on hover and a select on either, and none of that is
+ * about surfaces.
+ */
+export declare class PopoverController implements ReactiveController {
+    private readonly options;
+    private readonly floating;
+    private readonly dismisser;
+    /** Whether the surface is currently shown, so the calls can be idempotent. */
+    private shown;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: PopoverOptions);
+    /** Whether the surface is showing. */
+    get open(): boolean;
+    /** Whether this one is placed by measurement, read fresh so it may change. */
+    private get places();
+    /**
+     * Shows the surface, positions it, and starts listening for a way out.
+     *
+     * Safe to call when already open, so a host may call it from whatever
+     * combination of a property, an event and a command it likes without keeping
+     * track of which one got there first.
+     */
+    show(): void;
+    /** Hides the surface and stops everything watching it. */
+    hide(): void;
+    /** Whichever of the two the surface is not already doing. */
+    toggle(): void;
+    /**
+     * Places the surface again, for an anchor that moved without the page moving.
+     *
+     * `autoUpdate` watches scrolling, resizing and layout shift, which covers
+     * everything that moves an anchor *with* its surroundings. It does not cover
+     * an absolutely positioned anchor being moved by an inline style, and that is
+     * exactly what a chart does: the mark walks from reading to reading while the
+     * page holds still, so the bubble was placed once and stayed there.
+     */
+    reposition(): void;
+    hostDisconnected(): void;
+}