@c9up/nebula 0.1.0

package/dist/organisms/Tooltip.js

@@ -0,0 +1,94 @@
+/**
+ * Tooltip — a label that appears on hover or focus.
+ *
+ * Three rules separate a usable tooltip from an irritating one, and all three
+ * are about time rather than appearance:
+ *
+ * - An **open delay**, so moving the pointer across a toolbar does not fire
+ *   six tooltips on the way past.
+ * - A **close delay**, so travelling from the trigger to the tooltip — which a
+ *   user does to read a long one, or click a link inside — does not dismiss it
+ *   halfway.
+ * - **No delay between neighbours.** Once one tooltip is showing, the next one
+ *   appears instantly; the user has clearly decided to browse the toolbar, and
+ *   re-serving the delay each time makes the interface feel stuck. That is why
+ *   `lastClosedAt` is module state and not per-component.
+ *
+ * Focus opens it with no delay at all. A keyboard user landing on a control
+ * has already committed to it, and a delay just looks like lag.
+ *
+ * `role="tooltip"` plus `aria-describedby` — never `aria-labelledby`. A
+ * tooltip supplements a control's name; it is not the name. A button labelled
+ * only by its tooltip is unlabelled to anything that does not hover.
+ */
+import { component, html, onUnmount, signal } from "@c9up/aurora";
+import { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { fadeInOut } from "../lib/motion.js";
+import { read } from "../lib/props.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+const OPEN_DELAY_MS = 500;
+const CLOSE_DELAY_MS = 150;
+/** How long after one closes that the next opens instantly. */
+const GRACE_MS = 300;
+/** Shared across every tooltip on the page — see the "no delay" rule above. */
+let lastClosedAt = 0;
+export const Tooltip = component((props) => {
+    const triggerId = uid("tooltip-trigger");
+    const contentId = uid("tooltip-content");
+    const open = signal(false);
+    let timer;
+    function clear() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function scheduleOpen(immediate) {
+        clear();
+        const withinGrace = Date.now() - lastClosedAt < GRACE_MS;
+        const delay = immediate || withinGrace ? 0 : (props.openDelay ?? OPEN_DELAY_MS);
+        if (delay === 0) {
+            open(true);
+            return;
+        }
+        timer = setTimeout(() => open(true), delay);
+    }
+    function scheduleClose() {
+        clear();
+        timer = setTimeout(() => {
+            open(false);
+            lastClosedAt = Date.now();
+        }, props.closeDelay ?? CLOSE_DELAY_MS);
+    }
+    onUnmount(clear);
+    floatingSurface({
+        anchor: () => document.getElementById(triggerId),
+        open: () => open(),
+        onClose: () => {
+            clear();
+            open(false);
+        },
+        placement: props.placement ?? "top",
+        offset: 6,
+        outsidePointer: false,
+        content: () => html `<div
+				data-slot="tooltip-content"
+				id="${contentId}"
+				role="tooltip"
+				class="${cn("bg-primary text-primary-foreground z-50 w-fit rounded-md px-3 py-1.5 text-xs text-balance", fadeInOut, read(props.contentClass))}"
+				@pointerenter="${clear}"
+				@pointerleave="${scheduleClose}"
+			>${props.content}</div>`,
+    });
+    return html `<span
+		data-slot="tooltip-trigger"
+		id="${triggerId}"
+		aria-describedby="${() => (open() ? contentId : undefined)}"
+		class="${() => cn("inline-flex", read(props.class))}"
+		@pointerenter="${() => scheduleOpen(false)}"
+		@pointerleave="${scheduleClose}"
+		@focusin="${() => scheduleOpen(true)}"
+		@focusout="${scheduleClose}"
+	>${slot(props.trigger)}</span>`;
+});

package/dist/organisms/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Organisms — components that escape their own DOM position.
+ *
+ * The line that separates these from molecules: an organism portals, traps
+ * focus, floats against an anchor, or coordinates several molecules into one
+ * working unit. Dialog is an organism though its markup is simpler than
+ * Table's, because it renders into `<body>` and takes over the page while it
+ * is open.
+ *
+ * Almost all of them are assembled from two shared surfaces —
+ * `floatingSurface` for the anchored overlays, `modalSurface` for the modal
+ * ones — so the parts that are easy to get wrong (teardown order, focus
+ * restoration, hiding the page from assistive technology) exist once.
+ */
+export { AlertDialog, type AlertDialogProps } from "./AlertDialog.js";
+export { addDays, addMonths, Calendar, type CalendarProps, type DateRange, isSameDay, monthGrid, startOfDay, } from "./Calendar.js";
+export { Carousel, type CarouselProps } from "./Carousel.js";
+export { Chart, type ChartDatum, type ChartProps, type ChartSeries, valueRange, } from "./Chart.js";
+export { Combobox, type ComboboxOption, type ComboboxProps, } from "./Combobox.js";
+export { Command, type CommandItem, type CommandProps, defaultFilter, } from "./Command.js";
+export { CommandDialog, type CommandDialogProps } from "./CommandDialog.js";
+export { ContextMenu, type ContextMenuProps } from "./ContextMenu.js";
+export { type Column, DataTable, type DataTableProps } from "./DataTable.js";
+export { DatePicker, type DatePickerProps, toISODate } from "./DatePicker.js";
+export { DateRangePicker, type DateRangePickerProps, } from "./DateRangePicker.js";
+export { Dialog, type DialogProps, dialogBackdropClasses, dialogPanelClasses, useDialog, } from "./Dialog.js";
+export { Drawer, type DrawerProps } from "./Drawer.js";
+export { DropdownMenu, type DropdownMenuProps } from "./DropdownMenu.js";
+export { bind, type FieldBinding, Form, type FormProps, SubmitButton, type SubmitButtonProps, TextAreaField, type TextAreaFieldProps, TextField, type TextFieldProps, } from "./Form.js";
+export { HoverCard, type HoverCardProps } from "./HoverCard.js";
+export { Menubar, type MenubarMenu, type MenubarProps } from "./Menubar.js";
+export { MessageScroller, type MessageScrollerProps, } from "./MessageScroller.js";
+export { type NavigationItem, type NavigationLink, NavigationMenu, type NavigationMenuProps, } from "./NavigationMenu.js";
+export { Popover, type PopoverProps, popoverContentClasses, } from "./Popover.js";
+export { type Answer, type Answers, type FreeformQuestion, isAnswered, type MultipleChoiceQuestion, type Question, Questionnaire, type QuestionnaireProps, type QuestionOption, type SingleChoiceQuestion, } from "./Questionnaire.js";
+export { Select, type SelectOption, type SelectProps, selectTriggerClasses, } from "./Select.js";
+export { Sheet, type SheetProps } from "./Sheet.js";
+export { Sidebar, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuAction, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, SidebarMenuSubItem, type SidebarProps, SidebarTrigger, type SidebarTriggerProps, sidebarCollapsed, sidebarState, } from "./Sidebar.js";
+export { Toaster, type ToasterProps, type ToastOptions, type ToastVariant, toast, } from "./Toaster.js";
+export { Tooltip, type TooltipProps } from "./Tooltip.js";

package/dist/organisms/index.js

@@ -0,0 +1,40 @@
+/**
+ * Organisms — components that escape their own DOM position.
+ *
+ * The line that separates these from molecules: an organism portals, traps
+ * focus, floats against an anchor, or coordinates several molecules into one
+ * working unit. Dialog is an organism though its markup is simpler than
+ * Table's, because it renders into `<body>` and takes over the page while it
+ * is open.
+ *
+ * Almost all of them are assembled from two shared surfaces —
+ * `floatingSurface` for the anchored overlays, `modalSurface` for the modal
+ * ones — so the parts that are easy to get wrong (teardown order, focus
+ * restoration, hiding the page from assistive technology) exist once.
+ */
+export { AlertDialog } from "./AlertDialog.js";
+export { addDays, addMonths, Calendar, isSameDay, monthGrid, startOfDay, } from "./Calendar.js";
+export { Carousel } from "./Carousel.js";
+export { Chart, valueRange, } from "./Chart.js";
+export { Combobox, } from "./Combobox.js";
+export { Command, defaultFilter, } from "./Command.js";
+export { CommandDialog } from "./CommandDialog.js";
+export { ContextMenu } from "./ContextMenu.js";
+export { DataTable } from "./DataTable.js";
+export { DatePicker, toISODate } from "./DatePicker.js";
+export { DateRangePicker, } from "./DateRangePicker.js";
+export { Dialog, dialogBackdropClasses, dialogPanelClasses, useDialog, } from "./Dialog.js";
+export { Drawer } from "./Drawer.js";
+export { DropdownMenu } from "./DropdownMenu.js";
+export { bind, Form, SubmitButton, TextAreaField, TextField, } from "./Form.js";
+export { HoverCard } from "./HoverCard.js";
+export { Menubar } from "./Menubar.js";
+export { MessageScroller, } from "./MessageScroller.js";
+export { NavigationMenu, } from "./NavigationMenu.js";
+export { Popover, popoverContentClasses, } from "./Popover.js";
+export { isAnswered, Questionnaire, } from "./Questionnaire.js";
+export { Select, selectTriggerClasses, } from "./Select.js";
+export { Sheet } from "./Sheet.js";
+export { Sidebar, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuAction, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubItem, SidebarTrigger, sidebarCollapsed, sidebarState, } from "./Sidebar.js";
+export { Toaster, toast, } from "./Toaster.js";
+export { Tooltip } from "./Tooltip.js";

package/dist/primitives/controllable.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Controlled / uncontrolled state.
+ *
+ * Every stateful shadcn component takes the same trio: `open` (the caller
+ * owns the state), `defaultOpen` (the component owns it) and `onOpenChange`
+ * (told either way). Radix folds that into `useControllableState`; this is the
+ * Aurora equivalent, and the reason a Dialog can be opened either by its own
+ * trigger or by a signal somewhere else in the app without changing shape.
+ *
+ *   // uncontrolled — nebula holds the state
+ *   Dialog({ defaultOpen: false })
+ *
+ *   // controlled — the app holds it, nebula only asks
+ *   const open = signal(false)
+ *   Dialog({ open, onOpenChange: open })
+ *
+ * The rule is one line: a `value` that reads as anything other than
+ * `undefined` wins over the internal signal, on every read. Deciding once at
+ * setup instead would freeze a component whose prop only becomes defined after
+ * an async load.
+ */
+import { type ReadSignal } from "@c9up/aurora";
+import { type Reactive } from "../lib/props.js";
+export interface ControllableOptions<T> {
+    /** The caller's value. Present means controlled. */
+    value?: Reactive<T | undefined>;
+    /** Starting value when uncontrolled. */
+    initial: T;
+    /** Notified on every change, controlled or not. */
+    onChange?: (next: T) => void;
+}
+export interface Controllable<T> {
+    /** Current value — the caller's when controlled, ours otherwise. */
+    readonly current: ReadSignal<T>;
+    /** Request a change. Always notifies; only writes internally when uncontrolled. */
+    set(next: T): void;
+}
+export declare function controllable<T>(options: ControllableOptions<T>): Controllable<T>;

package/dist/primitives/controllable.js

@@ -0,0 +1,43 @@
+/**
+ * Controlled / uncontrolled state.
+ *
+ * Every stateful shadcn component takes the same trio: `open` (the caller
+ * owns the state), `defaultOpen` (the component owns it) and `onOpenChange`
+ * (told either way). Radix folds that into `useControllableState`; this is the
+ * Aurora equivalent, and the reason a Dialog can be opened either by its own
+ * trigger or by a signal somewhere else in the app without changing shape.
+ *
+ *   // uncontrolled — nebula holds the state
+ *   Dialog({ defaultOpen: false })
+ *
+ *   // controlled — the app holds it, nebula only asks
+ *   const open = signal(false)
+ *   Dialog({ open, onOpenChange: open })
+ *
+ * The rule is one line: a `value` that reads as anything other than
+ * `undefined` wins over the internal signal, on every read. Deciding once at
+ * setup instead would freeze a component whose prop only becomes defined after
+ * an async load.
+ */
+import { memo, signal } from "@c9up/aurora";
+import { read } from "../lib/props.js";
+export function controllable(options) {
+    const internal = signal(options.initial);
+    const current = memo(() => {
+        if (options.value === undefined)
+            return internal();
+        const external = read(options.value);
+        return external === undefined ? internal() : external;
+    });
+    return {
+        current,
+        set(next) {
+            // Written even when controlled. The caller may ignore `onChange` and
+            // leave its own state put — a "cancel" on a confirm dialog does exactly
+            // that — and the internal value has to stay in step for the moment the
+            // caller stops controlling it.
+            internal(next);
+            options.onChange?.(next);
+        },
+    };
+}

package/dist/primitives/dismissable.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Dismissable layers — Escape, click-outside and focus-outside, stacked.
+ *
+ * Every transient surface needs this: Popover, DropdownMenu, ContextMenu,
+ * Select, Combobox, Tooltip, Dialog, Sheet, Drawer. Wiring it per component
+ * is how you end up with a menu inside a dialog where Escape closes both, or
+ * a submenu whose parent collapses the moment you click into it.
+ *
+ * So layers live in one stack and the rules are applied once, globally:
+ *
+ * - **Escape** reaches only the topmost layer that accepts it. That is what
+ *   makes Escape close a submenu first and its parent menu second.
+ * - **Pointer outside** walks the stack top-down and stops at the first layer
+ *   the event landed inside. Layers above it close, layers below it stay. A
+ *   click in a parent menu therefore closes the submenu and nothing else.
+ * - **Focus outside** follows the same walk, but only layers that opt in — a
+ *   modal dialog holds focus by design and must not close because focus moved.
+ *
+ * Layers are portalled, so a nested surface is not a DOM descendant of its
+ * parent. Containment is answered per layer by its own element plus whatever
+ * it excludes (its trigger, almost always), never by tree position.
+ */
+export type DismissReason = "escape" | "outside-pointer" | "outside-focus";
+export interface DismissableOptions {
+    /** The surface itself. Read lazily — it mounts after the layer registers. */
+    element: () => HTMLElement | null;
+    /** Called when this layer should close. */
+    onDismiss: (reason: DismissReason) => void;
+    /**
+     * Extra elements that do not count as "outside". The trigger belongs here:
+     * without it, pressing the trigger to close would dismiss on pointerdown and
+     * immediately reopen on click.
+     */
+    exclude?: () => ReadonlyArray<HTMLElement | null | undefined>;
+    /** Escape dismisses this layer when it is topmost. Default `true`. */
+    escapeKey?: boolean;
+    /** A pointer press outside dismisses. Default `true`. */
+    outsidePointer?: boolean;
+    /** Focus moving outside dismisses. Default `false`. */
+    outsideFocus?: boolean;
+}
+export interface DismissableLayer {
+    /** Remove this layer from the stack. Safe to call twice. */
+    remove(): void;
+}
+/**
+ * Register a dismissable layer. The returned handle must be removed when the
+ * surface unmounts — a stale layer keeps answering Escape for a surface that
+ * is no longer on screen.
+ */
+export declare function dismissable(options: DismissableOptions): DismissableLayer;
+/** How many layers are currently open. Used by the Escape/scroll-lock tests. */
+export declare function layerCount(): number;

package/dist/primitives/dismissable.js

@@ -0,0 +1,158 @@
+/// <reference lib="dom" />
+/**
+ * Dismissable layers — Escape, click-outside and focus-outside, stacked.
+ *
+ * Every transient surface needs this: Popover, DropdownMenu, ContextMenu,
+ * Select, Combobox, Tooltip, Dialog, Sheet, Drawer. Wiring it per component
+ * is how you end up with a menu inside a dialog where Escape closes both, or
+ * a submenu whose parent collapses the moment you click into it.
+ *
+ * So layers live in one stack and the rules are applied once, globally:
+ *
+ * - **Escape** reaches only the topmost layer that accepts it. That is what
+ *   makes Escape close a submenu first and its parent menu second.
+ * - **Pointer outside** walks the stack top-down and stops at the first layer
+ *   the event landed inside. Layers above it close, layers below it stay. A
+ *   click in a parent menu therefore closes the submenu and nothing else.
+ * - **Focus outside** follows the same walk, but only layers that opt in — a
+ *   modal dialog holds focus by design and must not close because focus moved.
+ *
+ * Layers are portalled, so a nested surface is not a DOM descendant of its
+ * parent. Containment is answered per layer by its own element plus whatever
+ * it excludes (its trigger, almost always), never by tree position.
+ */
+const stack = [];
+let nextLayerId = 0;
+let listening = false;
+/**
+ * Register a dismissable layer. The returned handle must be removed when the
+ * surface unmounts — a stale layer keeps answering Escape for a surface that
+ * is no longer on screen.
+ */
+export function dismissable(options) {
+    nextLayerId += 1;
+    const layer = { ...options, id: nextLayerId };
+    stack.push(layer);
+    startListening();
+    let removed = false;
+    return {
+        remove() {
+            if (removed)
+                return;
+            removed = true;
+            const index = stack.findIndex((entry) => entry.id === layer.id);
+            if (index !== -1)
+                stack.splice(index, 1);
+            stopListeningIfIdle();
+        },
+    };
+}
+/** How many layers are currently open. Used by the Escape/scroll-lock tests. */
+export function layerCount() {
+    return stack.length;
+}
+// ─── global listeners ────────────────────────────────────────────────
+/**
+ * Listeners attach on the first layer and detach with the last, rather than
+ * living for the lifetime of the page. An app that never opens an overlay
+ * pays nothing, and a test that opens and closes one leaves no residue.
+ */
+function startListening() {
+    if (listening || typeof document === "undefined")
+        return;
+    listening = true;
+    document.addEventListener("keydown", onKeyDown, true);
+    document.addEventListener("pointerdown", onPointerDown, true);
+    document.addEventListener("focusin", onFocusIn, true);
+}
+function stopListeningIfIdle() {
+    if (!listening || stack.length > 0)
+        return;
+    listening = false;
+    document.removeEventListener("keydown", onKeyDown, true);
+    document.removeEventListener("pointerdown", onPointerDown, true);
+    document.removeEventListener("focusin", onFocusIn, true);
+}
+function onKeyDown(event) {
+    if (event.key !== "Escape")
+        return;
+    // Topmost layer that accepts Escape — not simply the topmost layer. A
+    // Tooltip stacked over a Popover opts out, and Escape must then reach the
+    // Popover rather than being swallowed.
+    for (let i = stack.length - 1; i >= 0; i -= 1) {
+        const layer = stack[i];
+        if (layer === undefined)
+            continue;
+        if (layer.escapeKey === false)
+            continue;
+        event.stopPropagation();
+        layer.onDismiss("escape");
+        return;
+    }
+}
+function onPointerDown(event) {
+    dismissOutside(event, "outside-pointer");
+}
+function onFocusIn(event) {
+    dismissOutside(event, "outside-focus");
+}
+/**
+ * Close every layer the event landed outside of, stopping at the first one it
+ * landed inside.
+ *
+ * The snapshot is taken before dismissing: `onDismiss` mutates the stack, and
+ * iterating the live array while it shrinks skips layers.
+ */
+function dismissOutside(event, reason) {
+    const path = eventPath(event);
+    const snapshot = stack.slice();
+    for (let i = snapshot.length - 1; i >= 0; i -= 1) {
+        const layer = snapshot[i];
+        if (layer === undefined)
+            continue;
+        if (containsEvent(layer, path))
+            return;
+        const optedIn = reason === "outside-pointer"
+            ? layer.outsidePointer !== false
+            : layer.outsideFocus === true;
+        // A layer that opted out still blocks: closing the one beneath it while
+        // it stays open would leave the stack inverted on screen.
+        if (!optedIn)
+            return;
+        layer.onDismiss(reason);
+    }
+}
+/** Did the event originate inside this layer, or inside anything it excludes? */
+function containsEvent(layer, path) {
+    const element = layer.element();
+    if (element !== null && path.includes(element))
+        return true;
+    const excluded = layer.exclude?.() ?? [];
+    for (const candidate of excluded) {
+        if (candidate && path.includes(candidate))
+            return true;
+    }
+    return false;
+}
+/**
+ * The nodes an event travelled through.
+ *
+ * `composedPath()` is what makes containment correct across a shadow root,
+ * where `event.target` is retargeted to the host and a naive `contains()`
+ * check reports the wrong answer. Not every DOM implementation nebula runs
+ * against provides it, so the ancestor walk stands in when it is missing.
+ */
+function eventPath(event) {
+    if (typeof event.composedPath === "function") {
+        const path = event.composedPath();
+        if (path.length > 0)
+            return path;
+    }
+    const walked = [];
+    let node = event.target instanceof Node ? event.target : null;
+    while (node !== null) {
+        walked.push(node);
+        node = node.parentNode;
+    }
+    return walked;
+}

package/dist/primitives/floating.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Floating placement — where a popover, menu, select or tooltip goes.
+ *
+ * This is the piece Radix delegates to `@floating-ui/dom`. nebula computes it
+ * instead, because the alternative is a runtime dependency in a workspace
+ * whose stated position is that `cn` was worth reimplementing rather than
+ * pulling in clsx and tailwind-merge.
+ *
+ * Scope is chosen to make that defensible. Floating UI is a general middleware
+ * pipeline; this is the four behaviours the shadcn component set actually
+ * uses — `offset`, `flip`, `shift`, and arrow centring — plus the available
+ * height a scrollable menu needs for its `max-height`. No middleware
+ * abstraction, no virtual elements, no `autoPlacement`.
+ *
+ * The geometry lives in `resolvePosition`, a pure function over rectangles.
+ * Everything that touches the DOM — measuring, writing styles, watching for
+ * scroll — is in `autoPosition` around it. That split is what lets the flip
+ * and shift rules be tested exhaustively without a browser, which matters
+ * because they are where placement bugs actually live.
+ *
+ * Coordinates are viewport-relative and meant for `position: fixed`. Fixed
+ * positioning is what lets a portalled surface ignore every transformed or
+ * clipping ancestor between it and the root; an absolutely positioned popover
+ * has to find an offset parent, and gets it wrong the moment one appears.
+ */
+export type Side = "top" | "right" | "bottom" | "left";
+export type Align = "start" | "center" | "end";
+export type Placement = Side | `${Side}-${Align}`;
+/** Just the fields of a DOMRect the maths needs. */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface Viewport {
+    readonly width: number;
+    readonly height: number;
+}
+export interface PositionOptions {
+    /** Preferred placement. Default `"bottom"`. */
+    placement?: Placement;
+    /** Gap between anchor and surface, in px. Default `4`. */
+    offset?: number;
+    /** Keep this much clearance from the viewport edge. Default `8`. */
+    padding?: number;
+    /** Flip to the opposite side when the preferred one does not fit. Default `true`. */
+    flip?: boolean;
+    /** Slide along the cross axis to stay on screen. Default `true`. */
+    shift?: boolean;
+    /** Arrow size in px; centres the arrow and keeps it off the corners. */
+    arrowSize?: number;
+    /**
+     * Mirror the placement for a right-to-left writing direction.
+     *
+     * Placements are written in physical terms — `"right-start"` for a submenu —
+     * because that is what reads clearly at the call site and what CSS ends up
+     * applying. In Arabic or Hebrew those names mean the wrong edge: a submenu
+     * belongs on the *inline end*, which is the left. Rather than making every
+     * component reason in logical directions, the mirror happens once, here.
+     *
+     * `autoPosition` reads it off the anchor's computed direction, so a component
+     * never has to pass it.
+     */
+    rtl?: boolean;
+}
+export interface Position {
+    readonly x: number;
+    readonly y: number;
+    /** Placement actually used — may differ from the request after a flip. */
+    readonly placement: Placement;
+    readonly side: Side;
+    readonly align: Align;
+    /**
+     * Space between the surface's edge and the viewport on the resolved side.
+     * Menus bind it to `max-height` so a long list scrolls instead of
+     * overflowing off screen.
+     */
+    readonly availableHeight: number;
+    /** Arrow offset along the surface's cross axis, when `arrowSize` was given. */
+    readonly arrow?: {
+        readonly x?: number;
+        readonly y?: number;
+    };
+}
+/**
+ * Compute where the surface goes. Pure — no DOM, no side effects.
+ *
+ * Order matters and matches Floating UI's: offset, then flip, then shift.
+ * Shifting before flipping would slide a surface halfway off the anchor to
+ * make room on a side that should have been abandoned entirely.
+ */
+export declare function resolvePosition(anchor: Rect, floating: Rect, viewport: Viewport, options?: PositionOptions): Position;
+export interface AutoPositionOptions extends PositionOptions {
+    /** The arrow element to position, if the surface has one. */
+    arrow?: () => HTMLElement | null;
+    /** Force the surface to the anchor's width. Select and Combobox use it. */
+    matchWidth?: boolean;
+    /** Called after each reposition — for `data-side` attributes and the like. */
+    onPositioned?: (position: Position) => void;
+}
+export interface AutoPosition {
+    /** Recompute and rewrite the styles now. */
+    update(): void;
+    /** Stop watching. Styles already written are left in place. */
+    stop(): void;
+}
+/**
+ * Position `floating` against `anchor` and keep it there.
+ *
+ * Updates run on scroll (captured, so ancestor scroll containers are covered
+ * without walking the tree to find them) and on resize, plus whenever either
+ * element changes size where `ResizeObserver` exists. A menu whose content
+ * loads in and grows would otherwise stay positioned for its old height.
+ */
+export declare function autoPosition(anchor: HTMLElement, floating: HTMLElement, options?: AutoPositionOptions): AutoPosition;