@box-kite/react 0.0.1 → 2.0.0

package/components/menu.mjs

@@ -0,0 +1,422 @@
+"use client";
+import { l as e, u as t } from "../platform.mjs";
+import { n } from "../effects.mjs";
+import r from "../box.mjs";
+import { a as i, i as a } from "../behavior.mjs";
+import { t as o } from "../identity.mjs";
+import { t as s } from "../keyboard.mjs";
+import { t as c } from "../placement.mjs";
+import l from "./overlay.mjs";
+import { t as u } from "../layer.mjs";
+import { createContext as d, useCallback as f, useContext as p, useMemo as m, useRef as h, useState as g } from "react";
+import { Fragment as _, jsx as v, jsxs as y } from "react/jsx-runtime";
+//#region src/utils/menu/menuUtils.ts
+var b;
+(function(e) {
+	let t = e.ITEM_SELECTOR = "[role=\"menuitem\"],[role=\"menuitemcheckbox\"],[role=\"menuitemradio\"]";
+	function n(e, t) {
+		return t instanceof Element && t.closest("[role=\"menu\"]") === e;
+	}
+	e.owns = n;
+	function r(e) {
+		return [...e.querySelectorAll(t)].filter((t) => n(e, t));
+	}
+	e.items = r;
+	function i(e) {
+		return e.getAttribute("aria-disabled") === "true";
+	}
+	e.isDisabled = i;
+	function a(e) {
+		return e.getAttribute("aria-haspopup") === "menu";
+	}
+	e.isSubTrigger = a;
+	function o(e, t, n) {
+		if (e.length !== 0) return e[t < 0 ? n > 0 ? 0 : e.length - 1 : ((t + n) % e.length + e.length) % e.length];
+	}
+	e.step = o;
+	function c(e, t, n) {
+		let r = s.target(t, n, e.length, (t) => e[t].textContent ?? "");
+		return r < 0 ? void 0 : e[r];
+	}
+	e.typeaheadTarget = c;
+})(b ||= {});
+var x = b, S = d(null);
+function C(e) {
+	let t = p(S);
+	if (!t) throw Error(`<${e}> must be rendered inside a <Menu>.`);
+	return t;
+}
+function w(e) {
+	let [t, n] = g([]);
+	return {
+		panels: t,
+		registerLayer: f((t) => {
+			n((e) => [...e, t]);
+			let r = e?.(t);
+			return () => {
+				n((e) => e.filter((e) => e !== t)), r?.();
+			};
+		}, [e])
+	};
+}
+var T = d(null);
+function E(e) {
+	let { trigger: t, children: n, open: r, defaultOpen: a = !1, onOpenChange: o, label: s, labelledBy: c, side: l = "bottom", align: d = "start", offset: f = 1, flip: p = !0, matchWidth: g = !1, props: b, ...C } = e, T = h("first"), E = i((e) => {
+		let t = x.items(e), n = T.current === "last" ? t[t.length - 1] : t[0];
+		T.current = "first", (n ?? e).focus();
+	}), { panels: O, registerLayer: k } = w(), A = u({
+		haspopup: "menu",
+		idPrefix: "menu",
+		id: C.id,
+		open: r,
+		defaultOpen: a,
+		onOpenChange: o,
+		onOpened: E,
+		inside: O
+	}), j = i((e) => {
+		(e.key === "ArrowDown" || e.key === "ArrowUp") && (e.preventDefault(), T.current = e.key === "ArrowUp" ? "last" : "first", A.isOpen && A.panelElement ? E(A.panelElement) : A.setOpen(!0, {
+			reason: "trigger",
+			event: e
+		}));
+	}), M = m(() => ({
+		ref: A.trigger.ref,
+		props: {
+			...A.trigger.props,
+			onKeyDown: j
+		}
+	}), [j, A.trigger]), N = i((e) => A.setOpen(!1, e)), P = m(() => ({
+		open: A.isOpen,
+		closeAll: N,
+		registerLayer: k
+	}), [
+		N,
+		A.isOpen,
+		k
+	]);
+	return /* @__PURE__ */ y(_, { children: [t(M), /* @__PURE__ */ v(S.Provider, {
+		value: P,
+		children: /* @__PURE__ */ v(D, {
+			layer: A,
+			side: l,
+			align: d,
+			offset: f,
+			flip: p,
+			matchWidth: g,
+			label: s,
+			labelledBy: c ?? (s ? void 0 : A.triggerId),
+			contentProps: b,
+			...C,
+			children: n
+		})
+	})] });
+}
+function D(e) {
+	let { layer: n, side: a, align: o, offset: u, flip: d, matchWidth: f, label: p, labelledBy: m, contentProps: g, closeSelf: _, children: y, ...b } = e, { platform: S, isOpen: w, id: T, triggerElement: E, setPanel: D } = n, O = C("Menu"), k = h({
+		query: "",
+		at: 0
+	}), A = c({
+		side: a,
+		align: o,
+		offset: u,
+		flip: d,
+		matchWidth: f,
+		anchor: E
+	}), j = {
+		role: "menu",
+		"aria-label": p,
+		"aria-labelledby": m,
+		tabIndex: -1,
+		onKeyDown: i((e) => {
+			let n = e.currentTarget;
+			if (!x.owns(n, e.target)) return;
+			let r = x.items(n), i = r.indexOf(document.activeElement), a = (t) => {
+				t && (e.preventDefault(), t.focus());
+			}, o = t(n) ? "ArrowRight" : "ArrowLeft";
+			switch (e.key) {
+				case "ArrowDown": return a(x.step(r, i, 1));
+				case "ArrowUp": return a(x.step(r, i, -1));
+				case "Home": return a(r[0]);
+				case "End": return a(r[r.length - 1]);
+				case "Tab": return O.closeAll({
+					reason: "tab",
+					event: e
+				});
+				case o: return _ ? (e.preventDefault(), _({
+					reason: "trigger",
+					event: e
+				})) : void 0;
+			}
+			if (s.isPrintable(e)) {
+				let t = s.push(k.current, e.key, e.timeStamp);
+				a(x.typeaheadTarget(r, t, i));
+			}
+		}),
+		onPointerOver: i((e) => {
+			let t = e.currentTarget, n = e.target?.closest(x.ITEM_SELECTOR);
+			!n || !x.owns(t, n) || n === document.activeElement || n.focus();
+		}),
+		...g
+	};
+	return S ? /* @__PURE__ */ v(r, {
+		ref: D,
+		component: "menu",
+		...b,
+		variant: [b.variant, { topLayer: !0 }],
+		...A.layerProps,
+		id: T,
+		props: {
+			popover: "auto",
+			...j
+		},
+		children: y
+	}) : w ? /* @__PURE__ */ v(l, {
+		contentRef: D,
+		anchor: E,
+		side: a,
+		align: o,
+		offset: u,
+		flip: d,
+		matchWidth: f,
+		component: "menu",
+		...b,
+		id: T,
+		props: j,
+		children: y
+	}) : null;
+}
+function O(a) {
+	let { label: s, children: c, disabled: l, side: d = "end", align: f = "start", offset: p = 0, flip: h = !0, itemProps: g, props: b, ...T } = a, E = C("Menu.Sub"), O = o("menu-sub"), k = i((e) => {
+		(x.items(e)[0] ?? e).focus();
+	}), A = i((e, t) => {
+		e && t?.focus();
+	}), { panels: j, registerLayer: M } = w(E.registerLayer), N = u({
+		haspopup: "menu",
+		idPrefix: "menu-sub",
+		id: T.id,
+		onOpened: k,
+		onClosing: A,
+		inside: j
+	});
+	n(() => {
+		if (!(!N.isOpen || !N.panelElement)) return E.registerLayer(N.panelElement);
+	}, [
+		N.isOpen,
+		N.panelElement,
+		E.registerLayer
+	]), n(() => {
+		E.open || N.setOpen(!1, { reason: "imperative" });
+	}, [E.open, N.setOpen]), n(() => {
+		if (!N.isOpen) return;
+		let t = new AbortController();
+		return document.addEventListener("focusin", (t) => {
+			e(t, [N.panelElement, N.triggerElement]) || N.setOpen(!1, {
+				reason: "imperative",
+				event: t
+			});
+		}, { signal: t.signal }), () => t.abort();
+	}, [
+		N.isOpen,
+		N.panelElement,
+		N.triggerElement,
+		N.setOpen
+	]);
+	let P = i((e) => {
+		let n = t(e.currentTarget) ? "ArrowLeft" : "ArrowRight";
+		l || e.key !== n || (e.preventDefault(), N.setOpen(!0, {
+			reason: "trigger",
+			event: e
+		}));
+	}), F = i((e) => {
+		l || N.setOpen(!0, {
+			reason: "trigger",
+			event: e
+		});
+	}), I = m(() => ({
+		open: N.isOpen,
+		closeAll: E.closeAll,
+		registerLayer: M
+	}), [
+		N.isOpen,
+		E.closeAll,
+		M
+	]);
+	return /* @__PURE__ */ y(_, { children: [/* @__PURE__ */ y(r, {
+		tag: "button",
+		ref: l ? void 0 : N.trigger.ref,
+		component: "menu.item",
+		variant: { sub: !0 },
+		id: O,
+		props: {
+			type: "button",
+			role: "menuitem",
+			tabIndex: -1,
+			"aria-disabled": l || void 0,
+			...N.trigger.props,
+			...g,
+			onKeyDown: P,
+			onPointerEnter: F
+		},
+		children: [s, /* @__PURE__ */ v(r, { component: "menu.arrow" })]
+	}), !l && /* @__PURE__ */ v(S.Provider, {
+		value: I,
+		children: /* @__PURE__ */ v(D, {
+			layer: N,
+			side: d,
+			align: f,
+			offset: p,
+			flip: h,
+			matchWidth: !1,
+			labelledBy: O,
+			contentProps: b,
+			closeSelf: (e) => N.setOpen(!1, e),
+			...T,
+			children: c
+		})
+	})] });
+}
+function k(e) {
+	let { onSelect: t, disabled: n, closeOnSelect: a = !0, props: o, children: s, ...c } = e, l = C("Menu.Item"), u = i((e) => {
+		n || (t?.(e), a && l.closeAll({
+			reason: "select",
+			event: e
+		}));
+	});
+	return /* @__PURE__ */ v(r, {
+		tag: "button",
+		component: "menu.item",
+		...c,
+		props: {
+			type: "button",
+			role: "menuitem",
+			tabIndex: -1,
+			"aria-disabled": n || void 0,
+			...o,
+			onClick: u
+		},
+		children: s
+	});
+}
+function A(e) {
+	let { checked: t, defaultChecked: n = !1, onCheckedChange: o, disabled: s, closeOnSelect: c = !1, props: l, children: u, ...d } = e, f = C("Menu.CheckboxItem"), [p, m] = a({
+		value: t,
+		defaultValue: n,
+		onChange: o
+	}), h = i((e) => {
+		s || (m(!p, {
+			reason: "select",
+			event: e
+		}), c && f.closeAll({
+			reason: "select",
+			event: e
+		}));
+	});
+	return /* @__PURE__ */ y(r, {
+		tag: "button",
+		component: "menu.item",
+		...d,
+		props: {
+			type: "button",
+			role: "menuitemcheckbox",
+			tabIndex: -1,
+			"aria-checked": p,
+			"aria-disabled": s || void 0,
+			...l,
+			onClick: h
+		},
+		children: [/* @__PURE__ */ v(r, {
+			component: "menu.indicator",
+			children: p && /* @__PURE__ */ v(r, { component: "menu.check" })
+		}), u]
+	});
+}
+function j(e) {
+	let { label: t, value: n, defaultValue: r = "", onValueChange: o, children: s, ...c } = e, [l, u] = a({
+		value: n,
+		defaultValue: r,
+		onChange: o
+	}), d = i((e, t) => u(e, {
+		reason: "select",
+		event: t
+	})), f = m(() => ({
+		value: l,
+		select: d
+	}), [l, d]);
+	return /* @__PURE__ */ v(T.Provider, {
+		value: f,
+		children: /* @__PURE__ */ v(N, {
+			label: t,
+			...c,
+			children: s
+		})
+	});
+}
+function M(e) {
+	let { value: t, disabled: n, closeOnSelect: a = !1, props: o, children: s, ...c } = e, l = C("Menu.RadioItem"), u = p(T);
+	if (!u) throw Error("<Menu.RadioItem> must be rendered inside a <Menu.RadioGroup>.");
+	let d = u.value === t, f = i((e) => {
+		n || (u.select(t, e), a && l.closeAll({
+			reason: "select",
+			event: e
+		}));
+	});
+	return /* @__PURE__ */ y(r, {
+		tag: "button",
+		component: "menu.item",
+		...c,
+		props: {
+			type: "button",
+			role: "menuitemradio",
+			tabIndex: -1,
+			"aria-checked": d,
+			"aria-disabled": n || void 0,
+			...o,
+			onClick: f
+		},
+		children: [/* @__PURE__ */ v(r, {
+			component: "menu.indicator",
+			children: d && /* @__PURE__ */ v(r, { component: "menu.dot" })
+		}), s]
+	});
+}
+function N(e) {
+	let { label: t, props: n, children: i, ...a } = e, s = o("menu-group");
+	return /* @__PURE__ */ y(r, {
+		component: "menu.group",
+		...a,
+		props: {
+			role: "group",
+			"aria-labelledby": t ? s : void 0,
+			...n
+		},
+		children: [t && /* @__PURE__ */ v(r, {
+			component: "menu.label",
+			id: s,
+			props: { role: "presentation" },
+			children: t
+		}), i]
+	});
+}
+function P(e) {
+	let { props: t, ...n } = e;
+	return /* @__PURE__ */ v(r, {
+		component: "menu.separator",
+		...n,
+		props: {
+			role: "separator",
+			...t
+		}
+	});
+}
+k.displayName = "Menu.Item", A.displayName = "Menu.CheckboxItem", j.displayName = "Menu.RadioGroup", M.displayName = "Menu.RadioItem", N.displayName = "Menu.Group", P.displayName = "Menu.Separator", O.displayName = "Menu.Sub";
+var F = Object.assign(E, {
+	Item: k,
+	CheckboxItem: A,
+	RadioGroup: j,
+	RadioItem: M,
+	Group: N,
+	Separator: P,
+	Sub: O
+});
+E.displayName = "Menu";
+//#endregion
+export { F as default };

package/components/overlay.cjs

@@ -0,0 +1 @@
+"use client";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../platform.cjs"),t=require("../client.cjs"),n=require("../effects.cjs"),r=require("../box.cjs"),i=require("../placement.cjs");let a=require("react"),o=require("react/jsx-runtime"),s=require("react-dom");function c(c,l){let{side:u=`bottom`,align:d=`center`,offset:f=0,flip:p=!0,onSideChange:m,anchor:h,contentRef:g,matchWidth:_=!0,...v}=c,[y,b]=(0,a.useState)(null),[x,S]=(0,a.useState)(!1),C=(0,a.useRef)(null),[w]=(0,a.useState)(e.a),T=(0,a.useRef)(null),E=t.t(!w),D=i.t({side:u,align:d,offset:f,flip:p,matchWidth:_,anchor:h??y,trackSide:!!m});n.n(()=>{let e=T.current;!w||!e||!e.isConnected||e.matches(`:popover-open`)||e.showPopover()}),n.n(()=>{if(w)return;let t=e.c(h)??y;S(!!t&&e.u(t))},[h,y,w]),n.n(()=>{C.current!==D.side&&(C.current=D.side,m?.(D.side))});let O=D.layerProps.ref,k=(0,a.useCallback)(e=>{O?.(e),T.current=e,typeof l==`function`?l(e):l&&(l.current=e)},[O,l]),A=(0,o.jsx)(r.default,{...D.layerProps,ref:k,transition:`none`,props:w?{popover:`manual`}:{dir:x?`rtl`:`ltr`},children:(0,o.jsx)(r.default,{ref:g,...v})});return(0,o.jsxs)(o.Fragment,{children:[!h&&(0,o.jsx)(r.default,{ref:b}),w?A:E&&(0,s.createPortal)(A,E)]})}var l=(0,a.forwardRef)(c);l.displayName=`Overlay`,exports.default=l;

package/components/overlay.d.ts

@@ -0,0 +1,47 @@
+import { Ref, RefAttributes } from 'react';
+import { BoxProps } from '../box';
+import { ExtractElementFromTag } from '../react/reactTypes';
+import { ComponentsAndVariants } from '@box-kite/core/types';
+import { AnchorAlign, AnchorSide } from '../utils/anchor/anchorUtils';
+import { ElementLike } from '../utils/dom/domUtils';
+interface OverlayProps {
+    /**
+     * Which side of the anchor the layer sits on: `top`/`bottom` are the block axis, `start`/`end` the
+     * inline one, so a layer beside its anchor mirrors in a right-to-left page. Default `'bottom'`.
+     */
+    side?: AnchorSide;
+    /** Which of the anchor's edges to line up with along the other axis. Default `'center'`. */
+    align?: AnchorAlign;
+    /** The gap between anchor and layer, on the ÷4 spacing scale — `offset={2}` is 8px. Default `0`. */
+    offset?: number;
+    /**
+     * Whether a side with no room may be swapped for its opposite. Default `true`. It shadows the CSS prop
+     * of that name — a mirrored layer is a rarity, and one placement vocabulary across the hook, this and
+     * `Tooltip` is worth more than the transform, which a child of the layer can still take.
+     */
+    flip?: boolean;
+    /**
+     * Fires with the side the layer ended up on, which is the requested one unless a flip moved it — what
+     * a popup that grows away from its trigger needs to know to animate the right way. Asking for it is
+     * what turns on the one read the CSS path otherwise never does, so leave it out when nothing uses it.
+     */
+    onSideChange?(side: AnchorSide): void;
+    /**
+     * Anchor to this element rather than to the spot the layer was declared in. A trigger is almost always
+     * the right answer: the placeholder is a real box with no size, so `align` and `matchWidth` have
+     * nothing to work from, and inside a flex row it becomes a flex item of its own.
+     */
+    anchor?: ElementLike;
+    /**
+     * The content Box, which is the one that animates. `ref` is the anchored layer, which transitions
+     * nothing on purpose — so a `<Presence>` measuring an exit has to reach past it.
+     */
+    contentRef?: Ref<HTMLDivElement>;
+    /**
+     * Whether the layer is at least as wide as its anchor. Default true, so a dropdown popup lines up with
+     * its trigger; a tooltip sizes to its own content and turns it off.
+     */
+    matchWidth?: boolean;
+}
+declare const _default: <TTag extends keyof React.JSX.IntrinsicElements = "div", TKey extends keyof ComponentsAndVariants = never>(props: Omit<BoxProps<TTag, TKey>, "flip"> & RefAttributes<ExtractElementFromTag<TTag>> & OverlayProps) => React.ReactNode;
+export default _default;

package/components/overlay.mjs

@@ -0,0 +1,52 @@
+"use client";
+import { a as e, c as t, u as n } from "../platform.mjs";
+import { t as r } from "../client.mjs";
+import { n as i } from "../effects.mjs";
+import a from "../box.mjs";
+import { t as o } from "../placement.mjs";
+import { forwardRef as s, useCallback as c, useRef as l, useState as u } from "react";
+import { Fragment as d, jsx as f, jsxs as p } from "react/jsx-runtime";
+import { createPortal as m } from "react-dom";
+//#region src/components/overlay.tsx
+function h(s, h) {
+	let { side: g = "bottom", align: _ = "center", offset: v = 0, flip: y = !0, onSideChange: b, anchor: x, contentRef: S, matchWidth: C = !0, ...w } = s, [T, E] = u(null), [D, O] = u(!1), k = l(null), [A] = u(e), j = l(null), M = r(!A), N = o({
+		side: g,
+		align: _,
+		offset: v,
+		flip: y,
+		matchWidth: C,
+		anchor: x ?? T,
+		trackSide: !!b
+	});
+	i(() => {
+		let e = j.current;
+		!A || !e || !e.isConnected || e.matches(":popover-open") || e.showPopover();
+	}), i(() => {
+		if (A) return;
+		let e = t(x) ?? T;
+		O(!!e && n(e));
+	}, [
+		x,
+		T,
+		A
+	]), i(() => {
+		k.current !== N.side && (k.current = N.side, b?.(N.side));
+	});
+	let P = N.layerProps.ref, F = c((e) => {
+		P?.(e), j.current = e, typeof h == "function" ? h(e) : h && (h.current = e);
+	}, [P, h]), I = /* @__PURE__ */ f(a, {
+		...N.layerProps,
+		ref: F,
+		transition: "none",
+		props: A ? { popover: "manual" } : { dir: D ? "rtl" : "ltr" },
+		children: /* @__PURE__ */ f(a, {
+			ref: S,
+			...w
+		})
+	});
+	return /* @__PURE__ */ p(d, { children: [!x && /* @__PURE__ */ f(a, { ref: E }), A ? I : M && m(I, M)] });
+}
+var g = s(h);
+g.displayName = "Overlay";
+//#endregion
+export { g as default };

package/components/popover.cjs

@@ -0,0 +1 @@
+"use client";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../box.cjs"),t=require("../behavior.cjs"),n=require("../placement.cjs"),r=require("./overlay.cjs"),i=require("../layer.cjs");let a=require("react/jsx-runtime");function o(o){let{trigger:s,children:c,open:l,defaultOpen:u=!1,onOpenChange:d,label:f,labelledBy:p,side:m=`bottom`,align:h=`center`,offset:g=2,flip:_=!0,matchWidth:v=!1,autoFocus:y=!0,props:b,...x}=o,S=t.a(e=>{!y||e.contains(document.activeElement)||e.focus()}),{platform:C,isOpen:w,id:T,trigger:E,triggerElement:D,setPanel:O}=i.t({haspopup:`dialog`,idPrefix:`popover`,id:x.id,open:l,defaultOpen:u,onOpenChange:d,onOpened:S}),k=n.t({side:m,align:h,offset:g,flip:_,matchWidth:v,anchor:D}),A={"aria-label":f,"aria-labelledby":p},j=x;return C?(0,a.jsxs)(a.Fragment,{children:[s(E),(0,a.jsx)(e.default,{ref:O,component:`popover`,...j,variant:[j.variant,{topLayer:!0}],...k.layerProps,id:T,props:{popover:`auto`,role:`dialog`,...A,tabIndex:-1,...b},children:c})]}):(0,a.jsxs)(a.Fragment,{children:[s(E),w&&(0,a.jsx)(r.default,{contentRef:O,anchor:D,side:m,align:h,offset:g,flip:_,matchWidth:v,component:`popover`,...j,id:T,props:{role:`dialog`,...A,tabIndex:-1,...b},children:c})]})}var s=o;s.displayName=`Popover`,exports.default=s;

package/components/popover.d.ts

@@ -0,0 +1,100 @@
+import { BoxProps } from '../box';
+import { ChangeHandler } from '../react/a11y/useControllableState';
+import { PopoverReason, PopoverTrigger as PopoverLayerTrigger, PopoverTriggerAttributes as PopoverLayerTriggerAttributes } from '../react/popover/usePopoverLayer';
+import { ComponentsAndVariants } from '@box-kite/core/types';
+import { AnchorAlign, AnchorSide } from '../utils/anchor/anchorUtils';
+export type { PopoverReason };
+/** The DOM attributes the trigger has to carry. */
+export type PopoverTriggerAttributes = PopoverLayerTriggerAttributes<'dialog'>;
+/**
+ * What the trigger has to carry: spread it onto the control itself, not a wrapper. The `ref` is what the
+ * popover is anchored to, so it is not optional decoration (see `anchor` on `Overlay`).
+ *
+ * ```tsx
+ * {(trigger) => <Button {...trigger}>Options</Button>}          // a Box component
+ * {(trigger) => <button ref={trigger.ref} {...trigger.props}>}  // a plain element
+ * ```
+ *
+ * It must be a **button**: `popovertarget` is what the browser toggles on, and it only reads it off one.
+ */
+export type PopoverTrigger = PopoverLayerTrigger<'dialog'>;
+type PopoverBoxProps<TKey extends keyof ComponentsAndVariants> = Omit<BoxProps<'div', TKey>, 'open' | 'flip'>;
+interface Props<TKey extends keyof ComponentsAndVariants> extends PopoverBoxProps<TKey> {
+    /** The trigger, handed the ref and props that wire it to the popover. It has to be a button. */
+    trigger: (trigger: PopoverTrigger) => React.ReactNode;
+    /** The panel's content. Rendered whether or not the popover is open — see the note on mounting. */
+    children?: React.ReactNode;
+    /** Controlled open state. Leave it out and the popover owns it. */
+    open?: boolean;
+    /** Whether it starts open, when the popover owns its own state. */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new state and why it changed — `'trigger'`, `'escape'`, `'outside-pointer'` or
+     * `'imperative'`. A close cannot be refused: the browser has already done it by the time this runs.
+     */
+    onOpenChange?: ChangeHandler<boolean, PopoverReason>;
+    /** The panel's accessible name. `role="dialog"` has none of its own, and a dialog without one is unusable. */
+    label?: string;
+    /** Names the panel after an element already on the page, instead of `label`. */
+    labelledBy?: string;
+    /**
+     * Which side of the trigger the panel sits on — `top`/`bottom` are the block axis, `start`/`end` the
+     * inline one, so a panel beside its trigger mirrors in a right-to-left page. Default `'bottom'`.
+     */
+    side?: AnchorSide;
+    /** Which of the trigger's edges to line the panel up with along the other axis. Default `'center'`. */
+    align?: AnchorAlign;
+    /** The gap between trigger and panel, on the ÷4 spacing scale. Default 2 — 8px. */
+    offset?: number;
+    /** Whether a side with no room may be swapped for its opposite. Default `true`. */
+    flip?: boolean;
+    /** Whether the panel is at least as wide as its trigger. Default `false` — a panel sizes to its content. */
+    matchWidth?: boolean;
+    /**
+     * Whether opening moves focus into the panel. Default `true`, which is what APG asks of a dialog. An
+     * `autofocus` attribute inside wins: the browser applies it first and this only acts on what is left.
+     */
+    autoFocus?: boolean;
+}
+/**
+ * A panel anchored to a trigger, on the platform's own Popover API: the top layer, light dismiss and
+ * focus return are the browser's, and the position is CSS anchor positioning.
+ *
+ * ```tsx
+ * <Popover label="Filters" trigger={(t) => <Button {...t}>Filters</Button>}>
+ *   <Checkbox label="Only mine" />
+ * </Popover>
+ * ```
+ *
+ * **There is no portal.** A top-layer element paints above every stacking context and outside every
+ * clipped ancestor, which is the whole class of bug a portal exists to work around — and because the
+ * panel stays where it was declared in the DOM, it inherits the theme, the custom properties and the text
+ * direction around it, and the tab order runs trigger → panel with nothing to arrange. (Measured against a
+ * `z-index: 9999` sibling, a `transform`ed ancestor and an `overflow: hidden` one.)
+ *
+ * **The panel is always rendered**, and closed means `display: none` from the UA stylesheet. That is what
+ * lets the browser own show and hide — and what makes the exit a plain CSS transition rather than a
+ * `<Presence>`, since nothing unmounts. Content that is expensive to render should be gated by the
+ * consumer: `{open && <Heavy />}`.
+ *
+ * **The panel keeps the side it chose when it opened.** Chrome re-evaluates `position-try-fallbacks` on
+ * scroll for an ordinary positioned element and never for one in the top layer (measured in 152), so a
+ * panel left open while the page scrolls does not flip when its side runs out of room. Every open picks
+ * the right side; it is only a scroll *while* open that this affects. See `Overlay`, which shares it.
+ *
+ * Where the browser has no Popover API the panel is an `Overlay` — a portal — with `useDismiss` and
+ * `useFocusReturn` supplying what the platform otherwise would.
+ *
+ * @a11y `role="dialog"` on the panel, named by `label` or `labelledBy`; the popover attribute supplies no
+ * role at all, and a panel with none is announced as a group of orphaned content.
+ * @a11y The trigger carries `aria-expanded`, `aria-haspopup="dialog"` and `aria-controls`, so the control
+ * says what it operates and what state it is in.
+ * @a11y Focus moves into the panel on open and back to the trigger on close. Nothing is trapped: this is a
+ * non-modal dialog, so Tab leaves it, and the panel follows the trigger in the DOM either way.
+ * @keyboard Enter, Space — On the trigger, toggles the panel.
+ * @keyboard Escape — Closes it and returns focus to the trigger, from anywhere inside.
+ * @keyboard Tab — Moves into the panel from the trigger, and out of the panel to whatever follows it.
+ */
+declare function PopoverImpl<TKey extends keyof ComponentsAndVariants = 'popover'>(props: Props<TKey>): import("react").JSX.Element;
+declare const Popover: typeof PopoverImpl;
+export default Popover;