@uniflowed/ui 0.0.0-alpha.10

package/internal/anchor.js

@@ -0,0 +1,500 @@
+// @flow
+//
+// Where an overlay goes, given where its trigger is.
+//
+// A popover, a tooltip and a hover card are the same three sentences: a box
+// appears next to another box, it stays on the screen when there is no room
+// where it was asked to go, and it says where it ended up so a stylesheet can
+// point an arrow at the trigger. Written into each component, those three
+// sentences are three copies that agree until one of them is fixed.
+//
+// # Flip *and* shift, because a flip alone is not enough
+//
+// There are two answers to "it does not fit", and a positioning layer needs
+// both:
+//
+//   * **Flip** — the main axis. A menu whose trigger is near the bottom of the
+//     viewport opens upwards instead of off the page, and reports
+//     `data-side="top"` so the arrow moves with it.
+//   * **Shift** — the cross axis. A menu wider than its trigger, aligned to a
+//     trigger near the right edge, has nowhere to flip *to*: both alignments
+//     overflow when the overlay is wider than the room on either side of the
+//     anchor. Sliding it back along the trigger is the only answer that keeps
+//     it on screen, and it is what Floating UI calls `shift`.
+//
+// Flipping the *alignment* — `start` becomes `end` when the aligned edge would
+// leave the viewport — is the thing that looks like a shift and is not. It
+// moves the overlay by its own width, which is a jump the reader sees, and it
+// still overflows in exactly the case above. So the alignment never flips here:
+// the side flips, the cross axis slides, and `data-align` keeps saying what the
+// caller asked for.
+//
+// # One tier, measured, and why there is no declarative second one
+//
+// The platform grew this capability: CSS anchor positioning places an element
+// against an `anchor-name` in the compositor, with `position-try-fallbacks` for
+// the collision case and no JavaScript on the scroll path. It is the better
+// mechanism and it is deliberately not used here, because it cannot express
+// half of what this module promises:
+//
+//   * `position-area` places a box in one of a grid of regions around the
+//     anchor. There is no spelling that says "and then move it back inside the
+//     viewport": the property chooses a region, it does not clamp a coordinate.
+//   * `position-try-fallbacks`, with the built-in `flip-block` / `flip-inline`
+//     or a hand-written `@position-try` block, tries another *placement* when
+//     the first overflows. Every one of those is a flip. None is a slide.
+//   * `position-area: span-all` with `justify-self: anchor-center` centres the
+//     overlay on the anchor and then needs a `margin-inline` to pull it back
+//     inside — and that margin is a number only a measurement produces, so the
+//     declarative path would be a measured path wearing a stylesheet.
+//
+// A tier that flips and a tier that flips *and* slides put the same overlay in
+// two different places, and which one a reader gets depends on their browser.
+// Shipping one tier that both engines run is worth more than shipping the
+// faster one to some of them, so this module measures. It is the reason
+// `packages/ui` has no `CSS.supports` in it: there is nothing to branch on.
+//
+// The measuring is kept cheap rather than clever. A placement is computed on
+// open, on a scroll anywhere in the page, on a viewport resize and on a resize
+// of either box — and each of those is one `getBoundingClientRect` per box
+// followed by the arithmetic below, which reads nothing else.
+//
+// # Why the arithmetic is a function and not a hook
+//
+// `placeOverlay` takes three rectangles and returns a placement. It touches no
+// element, no window and no React, so the whole of the collision behaviour —
+// every flip, every slide, right-to-left alignment, the overlay that is wider
+// than the viewport — is testable by calling it with numbers. That matters more
+// here than in most modules: the DOM these components are tested in computes no
+// layout at all, so a test that went through the hook could only assert *that*
+// a position was applied, never that it was the right one.
+//
+// # Why an overlay is `position: fixed`
+//
+// Because the coordinates are the viewport's. It also gets most of what a
+// portal is usually reached for: a fixed box is not clipped by an ancestor's
+// `overflow: hidden`, so a menu in a table row or a scroll container is not cut
+// in half — without moving the element away from its trigger in the
+// accessibility tree, which is the trade `dialog.js`'s header refuses to make.
+// The exception is an ancestor with `transform`, `filter` or `will-change`,
+// which becomes the containing block for a fixed descendant; that is the CSS
+// the top layer would answer, and answering it is ubugeeei-prod/uf#256's
+// remaining half rather than this module's.
+//
+// # Why this is `internal/` and not a subpath
+//
+// The same reason `roving-focus.js` gives. This is not a positioning library,
+// it is the relationship the overlay parts build: a `data-side` that agrees
+// with the coordinates, one set of custom-property names for a stylesheet to
+// read, and one definition of what `start` means in a right-to-left page.
+// Exported, a consumer could build a part that positions itself differently and
+// still calls itself an overlay.
+
+import { useEffect, useState } from "@uniflowed/react";
+import { useStableCallback } from "@uniflowed/hooks/lifecycle";
+
+import type { Direction } from "./roving-focus.js";
+import { directionOf } from "./roving-focus.js";
+
+/**
+ * Which side of its trigger an overlay opens onto.
+ *
+ * Physical rather than logical, which is the opposite of `Align` below and is
+ * deliberate: `side` answers "above or below", and the two horizontal ones are
+ * named after the screen because a design that puts a popover to the right of
+ * a toolbar means the right of the toolbar in any writing direction. What the
+ * writing direction changes is the *alignment*, which is where the reading
+ * order actually lives.
+ */
+export type Side = "top" | "right" | "bottom" | "left";
+
+/**
+ * Where the overlay sits along the trigger's other axis.
+ *
+ * Logical: `start` is the left edge in a left-to-right page and the right edge
+ * in a right-to-left one, so a menu aligned to the start of its trigger opens
+ * the way the reader reads in both.
+ */
+export type Align = "start" | "center" | "end";
+
+/** A box, in viewport coordinates: what `getBoundingClientRect` reports. */
+export type Rect = {|
+  readonly x: number,
+  readonly y: number,
+  readonly width: number,
+  readonly height: number,
+|};
+
+/** Everything `placeOverlay` needs, and nothing it could read for itself. */
+export type Anchoring = {|
+  /** The trigger. */
+  readonly anchor: Rect,
+  /** The overlay. Only its size is used; where it is now does not matter. */
+  readonly overlay: Rect,
+  /** What it has to stay inside, which is the viewport for a fixed element. */
+  readonly viewport: Rect,
+  readonly side: Side,
+  readonly align: Align,
+  /** The gap between the trigger and the overlay, in pixels. */
+  readonly sideOffset: number,
+  /** A nudge along the cross axis, in the direction the page reads. */
+  readonly alignOffset: number,
+  /** Whether to flip and slide at all. `false` places it exactly as asked. */
+  readonly avoidCollisions: boolean,
+  /** How close to the viewport edge the overlay may come. */
+  readonly collisionPadding: number,
+  readonly direction: Direction,
+|};
+
+/** Where the overlay goes, and what the placement had to do to get there. */
+export type Placement = {|
+  readonly x: number,
+  readonly y: number,
+  /** The side it ended up on, which is the requested one unless it flipped. */
+  readonly side: Side,
+  /** The requested alignment. It never changes; see the module header. */
+  readonly align: Align,
+  /** How far it slid along the cross axis, so an arrow can be moved back. */
+  readonly shift: number,
+  /** The room between the trigger and the viewport edge, and across it. */
+  readonly availableWidth: number,
+  readonly availableHeight: number,
+|};
+
+/** What `useAnchor` reports back for `data-side` and `data-align`. */
+export type Anchored = {|
+  readonly side: Side,
+  readonly align: Align,
+|};
+
+/** What `useAnchor` is told, on top of the geometry `placeOverlay` needs. */
+export type AnchorRequest = {|
+  readonly anchorRef: { current: HTMLElement | null },
+  readonly overlayRef: { current: HTMLElement | null },
+  /** Nothing is measured while it is closed: there is nothing to measure. */
+  readonly open: boolean,
+  readonly side: Side,
+  readonly align: Align,
+  readonly sideOffset: number,
+  readonly alignOffset: number,
+  readonly avoidCollisions: boolean,
+  readonly collisionPadding: number,
+|};
+
+/** The side a flip goes to. */
+const OPPOSITE: { readonly [Side]: Side } = {
+  top: "bottom",
+  bottom: "top",
+  left: "right",
+  right: "left",
+};
+
+/** Whether a side stacks the overlay above the trigger or beside it. */
+function isVertical(side: Side): boolean {
+  return side === "top" || side === "bottom";
+}
+
+/**
+ * The space between each edge of the anchor and the edge of the viewport,
+ * already minus the padding the overlay must not come inside.
+ *
+ * Negative for an anchor that is itself off the screen, which is a real state
+ * — a trigger scrolled halfway out of a container — and is why nothing below
+ * assumes these are positive.
+ */
+function roomAround(
+  anchor: Rect,
+  viewport: Rect,
+  collisionPadding: number,
+): { readonly [Side]: number } {
+  return {
+    top: anchor.y - (viewport.y + collisionPadding),
+    bottom: viewport.y + viewport.height - collisionPadding - (anchor.y + anchor.height),
+    left: anchor.x - (viewport.x + collisionPadding),
+    right: viewport.x + viewport.width - collisionPadding - (anchor.x + anchor.width),
+  };
+}
+
+/**
+ * The side the overlay actually fits on.
+ *
+ * The requested side wins whenever it fits, because a component that moved an
+ * overlay it did not have to move is one a designer cannot lay out against.
+ * When it does not fit and the opposite side does, it flips. When *neither*
+ * fits — a tall overlay next to a trigger in the middle of a short viewport —
+ * it takes the side with more room, so the reader sees as much of it as the
+ * page allows and `availableHeight` tells the stylesheet how much that was.
+ */
+function sideThatFits(anchoring: Anchoring, room: { readonly [Side]: number }): Side {
+  const { overlay, side, sideOffset } = anchoring;
+  const needed = (isVertical(side) ? overlay.height : overlay.width) + sideOffset;
+  const opposite = OPPOSITE[side];
+  if (room[side] >= needed) {
+    return side;
+  }
+  if (room[opposite] >= needed) {
+    return opposite;
+  }
+  return room[opposite] > room[side] ? opposite : side;
+}
+
+/**
+ * Where the overlay's leading edge goes along the cross axis, before sliding.
+ *
+ * `start` is the anchor's leading edge, `end` puts the overlay's trailing edge
+ * on the anchor's, and `center` splits the difference. Which edge is "leading"
+ * is the writing direction's business, and only on a horizontal cross axis: a
+ * page that reads right to left still reads top to bottom, so an overlay beside
+ * its trigger aligns to the top for `start` either way.
+ */
+function alignedAt(
+  align: Align,
+  mirrored: boolean,
+  anchorStart: number,
+  anchorSize: number,
+  overlaySize: number,
+): number {
+  const resolved = mirrored ? mirror(align) : align;
+  return match (resolved) {
+    "start" => anchorStart,
+    "center" => anchorStart + anchorSize / 2 - overlaySize / 2,
+    "end" => anchorStart + anchorSize - overlaySize,
+  };
+}
+
+/** `start` and `end` swapped, for a right-to-left page. */
+function mirror(align: Align): Align {
+  return match (align) {
+    "start" => "end",
+    "center" => "center",
+    "end" => "start",
+  };
+}
+
+/**
+ * Place `overlay` against `anchor` inside `viewport`.
+ *
+ * Pure arithmetic over three rectangles: no element, no window, no React. See
+ * the module header for why that is the point rather than a convenience.
+ */
+export function placeOverlay(anchoring: Anchoring): Placement {
+  const {
+    align,
+    alignOffset,
+    anchor,
+    avoidCollisions,
+    collisionPadding,
+    direction,
+    overlay,
+    sideOffset,
+    viewport,
+  } = anchoring;
+
+  const room = roomAround(anchor, viewport, collisionPadding);
+  const side = avoidCollisions ? sideThatFits(anchoring, room) : anchoring.side;
+  const vertical = isVertical(side);
+
+  // The main axis: hard against the trigger's edge, plus the gap. The overlay
+  // is never pushed along this axis, because pushing it would slide it over
+  // the trigger it is meant to be pointing at.
+  const main = match (side) {
+    "top" => anchor.y - overlay.height - sideOffset,
+    "bottom" => anchor.y + anchor.height + sideOffset,
+    "left" => anchor.x - overlay.width - sideOffset,
+    "right" => anchor.x + anchor.width + sideOffset,
+  };
+
+  // The cross axis: aligned, nudged, then slid back inside if it has to be.
+  const anchorStart = vertical ? anchor.x : anchor.y;
+  const anchorSize = vertical ? anchor.width : anchor.height;
+  const overlaySize = vertical ? overlay.width : overlay.height;
+  const viewportStart = vertical ? viewport.x : viewport.y;
+  const viewportSize = vertical ? viewport.width : viewport.height;
+  // A positive `alignOffset` moves the overlay the way the page reads, so the
+  // same number nudges a menu in the same visual direction as its own text.
+  const reading = vertical && direction === "rtl" ? -1 : 1;
+  const wanted =
+    alignedAt(align, vertical && direction === "rtl", anchorStart, anchorSize, overlaySize) +
+    alignOffset * reading;
+
+  const lowest = viewportStart + collisionPadding;
+  const highest = viewportStart + viewportSize - collisionPadding - overlaySize;
+  // `Math.max` last, so an overlay *wider* than the viewport — where `highest`
+  // is below `lowest` and no position satisfies both — is pinned to the leading
+  // edge rather than pushed off the far one. `availableWidth` is what a
+  // stylesheet reads to stop it being that wide in the first place.
+  const cross = avoidCollisions ? Math.max(lowest, Math.min(wanted, highest)) : wanted;
+
+  const alongSide = Math.max(0, room[side] - sideOffset);
+  const acrossSide = Math.max(0, viewportSize - collisionPadding * 2);
+
+  return {
+    align,
+    availableHeight: vertical ? alongSide : acrossSide,
+    availableWidth: vertical ? acrossSide : alongSide,
+    shift: cross - wanted,
+    side,
+    x: vertical ? cross : main,
+    y: vertical ? main : cross,
+  };
+}
+
+/**
+ * Write a placement onto the overlay.
+ *
+ * Imperatively, and only these seven properties. They change on every scroll
+ * frame while an overlay is open, and putting them in state would re-render the
+ * overlay and everything in it sixty times a second to move a box — which is
+ * exactly the cost `index.js`'s header says this package does not pay. React
+ * owns nothing written here: it never sets `left`, `top` or a custom property
+ * on these elements, and a caller who passes a `style` of their own keeps every
+ * property in it except the ones this component's position is made of.
+ *
+ * The two measurements are the ones a caller cannot compute for themselves. A
+ * `Select` popup that must match its trigger's width needs the trigger
+ * measured; a menu near the bottom of the page needs to know how much room is
+ * left before it can decide to scroll rather than overflow.
+ */
+function write(overlay: HTMLElement, anchor: Rect, placement: Placement): void {
+  const style = overlay.style;
+  style.position = "fixed";
+  style.left = `${placement.x}px`;
+  style.top = `${placement.y}px`;
+  style.setProperty("--uf-anchor-trigger-width", `${anchor.width}px`);
+  style.setProperty("--uf-anchor-trigger-height", `${anchor.height}px`);
+  style.setProperty("--uf-anchor-available-width", `${placement.availableWidth}px`);
+  style.setProperty("--uf-anchor-available-height", `${placement.availableHeight}px`);
+  // How far the slide moved it, so an arrow drawn by a stylesheet can be moved
+  // back the other way and keep pointing at the trigger.
+  style.setProperty("--uf-anchor-shift", `${placement.shift}px`);
+}
+
+/** The rectangle of an element, as the arithmetic above wants it. */
+function rectOf(element: HTMLElement): Rect {
+  const box = element.getBoundingClientRect();
+  return { height: box.height, width: box.width, x: box.left, y: box.top };
+}
+
+/**
+ * Keep an overlay against its trigger for as long as it is open.
+ *
+ * Returns the side and alignment it settled on, which the part renders as
+ * `data-side` and `data-align`. Those are state — they change rarely, a
+ * stylesheet has to see them, and a flip is exactly the moment an arrow has to
+ * move — while the coordinates are written straight to the element; `write`
+ * says why.
+ */
+export hook useAnchor(request: AnchorRequest): Anchored {
+  const {
+    align,
+    alignOffset,
+    anchorRef,
+    avoidCollisions,
+    collisionPadding,
+    open,
+    overlayRef,
+    side,
+    sideOffset,
+  } = request;
+  const [settled, setSettled] = useState<Anchored>({ align, side });
+
+  const reflow = useStableCallback(() => {
+    const anchor = anchorRef.current;
+    const overlay = overlayRef.current;
+    const view = overlay?.ownerDocument?.defaultView;
+    if (anchor == null || overlay == null || view == null) {
+      return;
+    }
+    const box = rectOf(anchor);
+    const placement = placeOverlay({
+      align,
+      alignOffset,
+      anchor: box,
+      avoidCollisions,
+      collisionPadding,
+      direction: directionOf(anchor),
+      overlay: rectOf(overlay),
+      side,
+      sideOffset,
+      // The viewport of a fixed element, which is the whole of it: a fixed box
+      // is positioned against the viewport rather than against whatever is
+      // scrolled around it.
+      viewport: { height: view.innerHeight, width: view.innerWidth, x: 0, y: 0 },
+    });
+    write(overlay, box, placement);
+    setSettled((current) =>
+      current.side === placement.side && current.align === placement.align
+        ? // The same object, so a scroll that changes nothing renders nothing.
+          current
+        : { align: placement.align, side: placement.side },
+    );
+  });
+
+  useEffect(() => {
+    const anchor = anchorRef.current;
+    const overlay = overlayRef.current;
+    const view = overlay?.ownerDocument?.defaultView;
+    if (!open || anchor == null || overlay == null || view == null) {
+      // Forget the measurement when the overlay closes. It is only read while
+      // `open`, but a body that stays mounted across a close — `PopoverBody`
+      // does — reopens in a commit where `open` is already `true`, and would
+      // report the *previous* opening's side until `reflow` corrects it from
+      // an effect, which runs after paint. That is one frame of an arrow
+      // drawn from `data-side` pointing the wrong way, after a reopen that
+      // follows a flip.
+      if (!open) {
+        setSettled((current) =>
+          current.side === side && current.align === align ? current : { align, side },
+        );
+      }
+      return;
+    }
+    reflow();
+
+    const document = overlay.ownerDocument;
+    const moved = () => reflow();
+    // Capture, because a scroll event does not bubble: a trigger inside a
+    // scrolling panel would otherwise move under an overlay that never heard
+    // about it. Passive, because this never prevents the scroll it is watching.
+    document.addEventListener("scroll", moved, { capture: true, passive: true });
+    view.addEventListener("resize", moved);
+    // A trigger that grows — a button whose label changed, a field that gained
+    // a second line — moves the overlay without any scroll or resize event
+    // being fired at all.
+    //
+    // Read off the window rather than through a local: a capitalised name
+    // holding a constructor is read as a React component by `uf lint`, and it
+    // is right to — the rule cannot tell this one from a component, and the
+    // window's own property is the thing being asked about anyway.
+    const host: $FlowFixMe = view;
+    const sizes = typeof host.ResizeObserver === "function" ? new host.ResizeObserver(moved) : null;
+    sizes?.observe(anchor);
+    sizes?.observe(overlay);
+
+    return () => {
+      document.removeEventListener("scroll", moved, true);
+      view.removeEventListener("resize", moved);
+      sizes?.disconnect();
+    };
+    // The measurements are read through `reflow`, which is stable and always
+    // has the latest of them; they are named here so that changing one — a
+    // caller flipping `side` on a breakpoint — measures again.
+  }, [
+    align,
+    alignOffset,
+    anchorRef,
+    avoidCollisions,
+    collisionPadding,
+    open,
+    overlayRef,
+    reflow,
+    side,
+    sideOffset,
+  ]);
+
+  // What was asked for until there is something measured to report, so the
+  // first commit — and the server's markup, which measures nothing at all —
+  // says the requested side rather than the last one some other opening
+  // happened to settle on.
+  return open ? settled : { align, side };
+}

package/internal/controlled-state.js

@@ -0,0 +1,65 @@
+// @flow
+//
+// The one contract every part of this package makes about state.
+//
+// Each primitive here has a value somebody may want to own: a dialog's open,
+// a tab set's selection, a switch's checked, a combobox's text. A library that
+// only supports one of the two arrangements is unusable in the other half of
+// applications — a form library owns the value, and a page that just wants tabs
+// does not — so every one of them is uncontrolled by default and controlled the
+// moment the corresponding prop is passed.
+//
+// Written once because the failure mode of writing it six times is that five of
+// them agree and one does not, and the one that does not is a component that
+// silently ignores the parent's value on the second render. The rules it fixes:
+//
+//   * `undefined` means "not controlled", and `null` does not. A combobox with
+//     no selection is `value={null}` and is still controlled.
+//   * A controlled component never writes its internal state, so a parent that
+//     rejects a change actually rejects it, rather than the component moving
+//     and then being moved back on the next render.
+//   * `onChange` is called for both arrangements, so a caller can observe
+//     without taking ownership.
+//
+// # Why this is `internal/` and not a subpath
+//
+// A public `useControlled` would be a general-purpose hook, and general-purpose
+// React hooks are `@uniflowed/hooks`' subject, not this package's. What lives
+// here is narrower than that: the specific contract this package's components
+// promise about their props. Exporting it would publish a second, weaker copy
+// of somebody else's API.
+
+import { useCallback, useState } from "@uniflowed/react";
+
+/**
+ * A value the caller may own, and the setter that respects the answer.
+ *
+ * `controlled` is the prop; `fallback` is the `defaultValue`-shaped initial
+ * state used only while the caller owns nothing.
+ */
+export hook useControlled<T>(
+  controlled: T | void,
+  fallback: T,
+  onChange: ((next: T) => mixed) | void,
+): [T, (next: T) => void] {
+  const [internal, setInternal] = useState<T>(fallback);
+  // `=== undefined` rather than `== null`: `null` is a legitimate controlled
+  // value — a combobox with nothing selected — and treating it as "give me the
+  // uncontrolled behaviour" made a cleared selection reappear on the next
+  // render.
+  const owned = controlled === undefined;
+
+  const set = useCallback(
+    (next: T) => {
+      if (owned) {
+        setInternal(next);
+      }
+      // Both arrangements report, so a caller can watch a value it does not
+      // own without having to take it over to do so.
+      onChange?.(next);
+    },
+    [owned, onChange],
+  );
+
+  return [owned ? internal : (controlled as $FlowFixMe), set];
+}

package/internal/disclosure.js

@@ -0,0 +1,97 @@
+// @flow
+//
+// The other pattern every part of this package keeps writing.
+//
+// `roving-focus.js` is the keyboard half of these components. This is the
+// other half, and it is one sentence: **a button says whether a region is
+// showing, and names it.** `Dialog.Trigger` and `Menu.Trigger` are that
+// sentence, and so are a collapsible, an accordion header and an expandable
+// entry in a site's navigation — three components that look nothing alike and
+// are the same three attributes underneath.
+//
+// Two rules make it up, and both of them fail silently.
+//
+//   * **Name it only while it is there.** `aria-controls` pointing at an id
+//     nothing has tells a reader there is somewhere to go and then has nowhere
+//     to send them, and `aria-labelledby` pointing at a missing element makes a
+//     screen reader announce *nothing at all* rather than falling back to the
+//     element's own text. So a panel reports whether it is in the document, and
+//     whatever names it only claims the name while the report says yes. This is
+//     the same subscription `Tabs.Panel` makes to `Tabs.Tab`, for the same
+//     reason.
+//   * **A closed panel is hidden, not absent.** `Tabs.Panel` returns `null`
+//     when it is not selected, which is right for a tab set — the panels are
+//     alternatives, and a reader looking for text in one of them is looking at
+//     the wrong tab. It is wrong for a disclosure: the browser's find-in-page
+//     cannot find text in a section that is not in the document, so a
+//     forty-section FAQ becomes forty sections a reader has to open by hand to
+//     search. `hidden="until-found"` is the platform's answer — the browser
+//     reveals the section, fires `beforematch`, and scrolls to the match —
+//     and it works in Chrome since 102 (2022-05), Firefox since 148 (2026-02)
+//     and Safari since 26.2 (2025-12, which does not yet scroll to the match);
+//     checked 2026-09-06. Everywhere else it degrades to a plain `hidden`,
+//     which is what the panel would have been anyway.
+//
+// # Why `useUntilFound` is a hook and not a prop
+//
+// Because React 19 cannot say `hidden="until-found"`. `hidden` is on React's
+// list of boolean attributes, so `<div hidden="until-found">` renders
+// `hidden=""` — the string is truthy, and truthy is all React keeps. There is
+// no prop spelling that produces the attribute, which is a thing worth knowing
+// before spending an afternoon looking for one.
+//
+// So the panel is rendered with the ordinary boolean `hidden` — which is what
+// the server sends, and what keeps a closed section closed before any
+// JavaScript arrives — and an effect *upgrades* the attribute afterwards. It is
+// an upgrade rather than a fight: React sets `hidden=""` when it commits, this
+// runs after that commit, and the next time React changes the prop it removes
+// or re-adds the attribute and this upgrades it again. Nothing here writes an
+// attribute React believes it owns while React believes it.
+//
+// # Why this is `internal/` and not a subpath
+//
+// The same reason `roving-focus.js` gives. These are rules about markup this
+// package emits — that a trigger and its panel agree on an id, that a panel is
+// the element carrying `hidden` — and they hold because the components build
+// both halves. Exported, they would be advice.
+
+import { useEffect } from "@uniflowed/react";
+
+/**
+ * Report that this part is in the document, for as long as it is.
+ *
+ * `register` is the setter from whatever names this part; it is called with
+ * `true` on mount and `false` on unmount, and taking it as a possibly-missing
+ * function lets a part be rendered outside the thing that would name it
+ * without the caller having to care.
+ */
+export hook usePresence(register: ((present: boolean) => void) | void): void {
+  useEffect(() => {
+    if (register == null) {
+      return;
+    }
+    register(true);
+    return () => register(false);
+  }, [register]);
+}
+
+/**
+ * Keep a closed panel hidden the way the platform means it: findable.
+ *
+ * The element must be rendered with a plain boolean `hidden` as well — see the
+ * module header. This only upgrades the attribute React has already committed,
+ * so a browser that has never heard of `until-found` sees exactly the `hidden`
+ * it would have seen, and one that has can reveal the section for a
+ * find-in-page hit.
+ */
+export hook useUntilFound(ref: { current: HTMLElement | null }, open: boolean): void {
+  useEffect(() => {
+    const element = ref.current;
+    // Nothing to do while it is open: React has removed the attribute, and
+    // adding one back would hide a panel the reader just opened.
+    if (element == null || open) {
+      return;
+    }
+    element.setAttribute("hidden", "until-found");
+  }, [ref, open]);
+}