@rozie-ui/popover-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 One Learning Community LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @rozie-ui/popover-react
+
+Idiomatic **react** `Popover` — a headless floating primitive for tooltips and popovers, wrapping [`@floating-ui/dom`](https://floating-ui.com) for collision-aware positioning (offset / flip / shift / arrow) with live `autoUpdate` tracking. You bring the anchor (the `anchor` slot) and the floating content (the default slot); Popover owns placement, the open/close gesture (`trigger`: click / hover / focus), dismissal (Escape + click-outside), the WAI-ARIA wiring (tooltip vs dialog), and a two-way `open` model — compiled from one [Rozie](https://github.com/One-Learning-Community/rozie.js) source. Every visual value is a CSS custom property, so it re-skins to any design system. This package is generated; do not edit `src/` by hand.
+
+## Install
+
+```bash
+npm i @rozie-ui/popover-react @floating-ui/dom
+```
+
+Peer dependencies: `react + react-dom + @floating-ui/dom`. Install them alongside this package.
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { Popover } from '@rozie-ui/popover-react';
+import '@floating-ui/dom'; // peer engine — installed alongside this package
+
+export function Demo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <Popover
+      open={open}
+      onOpenChange={setOpen}
+      trigger="click"
+      placement="bottom"
+      offset={8}
+      arrow
+      onChange={(next) => console.log('open:', next)}
+      anchor={({ toggle }) => <button onClick={toggle}>Menu</button>}
+    >
+      <div>Floating content</div>
+    </Popover>
+  );
+}
+```
+
+## Theming
+
+Every visual value is a `--rozie-popover-*` CSS custom property (background, border, radius, shadow, padding, z-index, max-width, arrow size) — override any of them at any ancestor scope to match your design system.
+
+## Props
+
+| Name | Type | Default | Two-way (model) | Required | Description |
+| --- | --- | --- | :---: | :---: | --- |
+| `open` | `Boolean` | `false` | ✓ |  | Whether the floating content is open. The sole `model: true` prop — two-way bind it (`r-model:open` / `v-model:open` / `bind:open` / `[(open)]`) and Popover writes the new state back whenever the trigger or a dismissal toggles it. Left unbound it falls back to an uncontrolled default. |
+| `placement` | `String` | `"bottom"` |  |  | Floating UI placement of the content relative to the anchor — one of `top`/`right`/`bottom`/`left`, each optionally suffixed `-start`/`-end` (e.g. `bottom-start`). With `disableFlip` off, the content may flip to the opposite side when it would overflow the viewport. Reconciled at runtime. |
+| `trigger` | `String` | `"click"` |  |  | How the anchor opens the content: `'click'` toggles on click, `'hover'` opens on pointer-enter and closes on pointer-leave (tooltip-style), `'focus'` opens on focus and closes on blur. Drives both the gesture handlers and the ARIA role (`'hover'`/`'focus'` → tooltip, `'click'` → popover dialog). |
+| `offset` | `Number` | `8` |  |  | Distance in pixels between the anchor and the floating content (the Floating UI `offset` middleware). Reconciled at runtime. |
+| `disableFlip` | `Boolean` | `false` |  |  | Disable the Floating UI `flip` middleware. By default the content flips to the opposite side of the anchor when it would overflow the viewport; set this to keep it pinned to `placement` regardless. |
+| `disableShift` | `Boolean` | `false` |  |  | Disable the Floating UI `shift` middleware. By default the content shifts along its axis to stay within the viewport; set this to keep it strictly aligned to the anchor. |
+| `arrow` | `Boolean` | `false` |  |  | Opt in to a positioned arrow element. When set, Popover renders an arrow `<div>` and runs the Floating UI `arrow` middleware against it so it points at the anchor. Style it via the `--rozie-popover-*` arrow CSS custom properties. |
+| `disabled` | `Boolean` | `false` |  |  | Disable the control entirely: the trigger no longer opens the content and any open content is suppressed. |
+| `modal` | `Boolean` | `false` |  |  | Opt in to modal dialog semantics for a `click` popover. **Off by default:** a click popover is a non-modal, click-outside-dismissable layer, so its panel is rendered role-neutral (the slot content owns its own ARIA role — e.g. a `role="menu"`) and carries NO `aria-modal`. Set `modal` for a genuinely modal dialog popover: the panel then gets `role="dialog"` + `aria-modal="true"`. **Note:** Popover ships no focus trap (it stays a minimal headless primitive); if you set `modal`, provide your own focus containment so the `aria-modal` claim holds. Ignored for `hover`/`focus` triggers (always tooltip-flavored). |
+| `strategy` | `String` | `"absolute"` |  |  | Floating UI positioning strategy — 'absolute' (default) or 'fixed'. Use 'fixed' to escape a scrollable/overflow-clipping ancestor (e.g. a sticky table header). Reconciled at runtime. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `change` | Fired whenever the open state changes — a click/hover/focus trigger gesture, an Escape or click-outside dismissal, or a programmatic `show`/`hide`/`toggle`. Payload is the new `open` boolean. The two-way `open` model is updated alongside it. |
+
+## Imperative handle
+
+Beyond props, the component exposes imperative methods (declared once in the Rozie source via `$expose`). Grab a handle with the native ref mechanism and call them directly:
+
+| Method | Description |
+| --- | --- |
+| `show` | Open the floating content (no-op when `disabled`). Emits `change` and updates the `open` model. |
+| `hide` | Close the floating content. Emits `change` and updates the `open` model. |
+| `toggle` | Flip the open state (no-op when `disabled`). Emits `change` and updates the `open` model. |
+| `reposition` | Recompute the floating position immediately (the Floating UI `computePosition` pass). Useful after content size changes that `autoUpdate` does not observe. |
+
+```tsx
+import { useRef } from 'react';
+import { Popover, type PopoverHandle } from '@rozie-ui/popover-react';
+
+const pop = useRef<PopoverHandle>(null);
+// <Popover ref={pop} ... />
+pop.current?.show();
+pop.current?.hide();
+pop.current?.toggle();
+pop.current?.reposition();
+```
+
+## Slots
+
+| Slot | Params |
+| --- | --- |
+| anchor | open, toggle, show, hide |
+| (default) |  |

package/dist/Popover.css

@@ -0,0 +1,28 @@
+.rozie-popover[data-rozie-s-c6cf02ea] {
+  display: contents;
+}
+.rozie-popover-anchor[data-rozie-s-c6cf02ea] {
+  display: inline-block;
+}
+.rozie-popover-floating[data-rozie-s-c6cf02ea] {
+  position: absolute;
+  left: 0;
+  top: 0;
+  z-index: var(--rozie-popover-z, 1000);
+  width: max-content;
+  max-width: var(--rozie-popover-max-width, calc(100vw - 16px));
+  background: var(--rozie-popover-bg, #fff);
+  color: var(--rozie-popover-color, inherit);
+  border: var(--rozie-popover-border, 1px solid rgba(0, 0, 0, 0.12));
+  border-radius: var(--rozie-popover-radius, 8px);
+  box-shadow: var(--rozie-popover-shadow, 0 8px 24px rgba(0, 0, 0, 0.12));
+  padding: var(--rozie-popover-padding, 8px 12px);
+}
+.rozie-popover-arrow[data-rozie-s-c6cf02ea] {
+  position: absolute;
+  width: var(--rozie-popover-arrow-size, 8px);
+  height: var(--rozie-popover-arrow-size, 8px);
+  background: var(--rozie-popover-bg, #fff);
+  border: var(--rozie-popover-border, 1px solid rgba(0, 0, 0, 0.12));
+  transform: rotate(45deg);
+}

package/dist/index.cjs

@@ -0,0 +1,307 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let react = require("react");
+let _rozie_runtime_react = require("@rozie/runtime-react");
+require("./Popover.css");
+let _floating_ui_dom = require("@floating-ui/dom");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/internal/middleware.ts
+/**
+* Build the ordered middleware array for `computePosition`. Pure — no engine
+* import, no DOM read beyond the passed-in arrow element.
+*/
+function buildMiddleware(factories, config) {
+	const mw = [factories.offset(config.offset)];
+	if (!config.disableFlip) mw.push(factories.flip());
+	if (!config.disableShift) mw.push(factories.shift());
+	if (config.arrow && config.arrowEl) mw.push(factories.arrow({ element: config.arrowEl }));
+	return mw;
+}
+//#endregion
+//#region src/Popover.tsx
+const Popover = (0, react.forwardRef)(function Popover(_props, ref) {
+	const props = {
+		..._props,
+		placement: _props.placement ?? "bottom",
+		trigger: _props.trigger ?? "click",
+		offset: _props.offset ?? 8,
+		disableFlip: _props.disableFlip ?? false,
+		disableShift: _props.disableShift ?? false,
+		arrow: _props.arrow ?? false,
+		disabled: _props.disabled ?? false,
+		modal: _props.modal ?? false,
+		strategy: _props.strategy ?? "absolute"
+	};
+	const attrs = (() => {
+		const { open, placement, trigger, offset, disableFlip, disableShift, arrow, disabled, modal, strategy, defaultValue, onOpenChange, defaultOpen, ...rest } = _props;
+		return rest;
+	})();
+	const anchorNode = (0, react.useRef)(null);
+	const floatingNode = (0, react.useRef)(null);
+	const arrowNode = (0, react.useRef)(null);
+	const stopAutoUpdate = (0, react.useRef)(null);
+	const lastFocusedEl = (0, react.useRef)(null);
+	const [open, setOpen] = (0, _rozie_runtime_react.useControllableState)({
+		value: props.open,
+		defaultValue: props.defaultOpen ?? false,
+		onValueChange: props.onOpenChange
+	});
+	const _openRef = (0, react.useRef)(open);
+	_openRef.current = open;
+	const anchorEl = (0, react.useRef)(null);
+	const floatingEl = (0, react.useRef)(null);
+	const arrowEl = (0, react.useRef)(null);
+	const _watch0First = (0, react.useRef)(true);
+	const _watch1First = (0, react.useRef)(true);
+	const _watch2First = (0, react.useRef)(true);
+	const _watch3First = (0, react.useRef)(true);
+	const _watch4First = (0, react.useRef)(true);
+	const _watch5First = (0, react.useRef)(true);
+	function deepActiveElement() {
+		let el = document.activeElement;
+		while (el && el.shadowRoot && el.shadowRoot.activeElement) el = el.shadowRoot.activeElement;
+		return el;
+	}
+	function requestOpen(next) {
+		if (open === next) return;
+		if (next && props.trigger === "click") lastFocusedEl.current = deepActiveElement();
+		setOpen(next);
+		props.onChange && props.onChange(next);
+		if (!next && props.trigger === "click" && lastFocusedEl.current && lastFocusedEl.current.isConnected && typeof lastFocusedEl.current.focus === "function") lastFocusedEl.current.focus();
+		if (!next) lastFocusedEl.current = null;
+	}
+	function applyPosition(x, y, middlewareData) {
+		if (!floatingNode.current) return;
+		floatingNode.current.style.left = x + "px";
+		floatingNode.current.style.top = y + "px";
+		if (arrowNode.current && middlewareData && middlewareData.arrow) {
+			const ax = middlewareData.arrow.x;
+			const ay = middlewareData.arrow.y;
+			arrowNode.current.style.left = ax == null ? "" : ax + "px";
+			arrowNode.current.style.top = ay == null ? "" : ay + "px";
+		}
+	}
+	function position() {
+		if (!anchorNode.current || !floatingNode.current) return;
+		const middleware = buildMiddleware({
+			offset: _floating_ui_dom.offset,
+			flip: _floating_ui_dom.flip,
+			shift: _floating_ui_dom.shift,
+			arrow: _floating_ui_dom.arrow
+		}, {
+			offset: props.offset,
+			disableFlip: props.disableFlip,
+			disableShift: props.disableShift,
+			arrow: props.arrow,
+			arrowEl: arrowNode.current
+		});
+		if (props.strategy === "fixed") floatingNode.current.style.position = "fixed";
+		else floatingNode.current.style.position = "";
+		let opts = null;
+		opts = {
+			placement: props.placement,
+			strategy: props.strategy,
+			middleware
+		};
+		(0, _floating_ui_dom.computePosition)(anchorNode.current, floatingNode.current, opts).then((result) => {
+			applyPosition(result.x, result.y, result.middlewareData);
+		});
+	}
+	const startTracking = (0, react.useCallback)(() => {
+		if (!anchorNode.current || !floatingNode.current) return;
+		if (stopAutoUpdate.current) {
+			stopAutoUpdate.current();
+			stopAutoUpdate.current = null;
+		}
+		stopAutoUpdate.current = (0, _floating_ui_dom.autoUpdate)(anchorNode.current, floatingNode.current, position);
+	}, [position]);
+	const stopTracking = (0, react.useCallback)(() => {
+		if (stopAutoUpdate.current) {
+			stopAutoUpdate.current();
+			stopAutoUpdate.current = null;
+		}
+	}, []);
+	const onAnchorClick = (0, react.useCallback)(() => {
+		if (props.disabled) return;
+		requestOpen(!open);
+	}, [
+		open,
+		props.disabled,
+		requestOpen
+	]);
+	const onAnchorPointerEnter = (0, react.useCallback)(() => {
+		if (props.disabled) return;
+		requestOpen(true);
+	}, [props.disabled, requestOpen]);
+	const onAnchorPointerLeave = (0, react.useCallback)(() => {
+		if (props.disabled) return;
+		requestOpen(false);
+	}, [props.disabled, requestOpen]);
+	const onAnchorFocus = (0, react.useCallback)(() => {
+		if (props.disabled) return;
+		requestOpen(true);
+	}, [props.disabled, requestOpen]);
+	const onAnchorBlur = (0, react.useCallback)(() => {
+		if (props.disabled) return;
+		requestOpen(false);
+	}, [props.disabled, requestOpen]);
+	const dismiss = (0, react.useCallback)(() => {
+		requestOpen(false);
+	}, [requestOpen]);
+	function isTooltip() {
+		return props.trigger === "hover" || props.trigger === "focus";
+	}
+	function floatingRole() {
+		return isTooltip() ? "tooltip" : props.modal ? "dialog" : void 0;
+	}
+	function show() {
+		if (!props.disabled) requestOpen(true);
+	}
+	function hide() {
+		requestOpen(false);
+	}
+	function toggle() {
+		if (!props.disabled) requestOpen(!open);
+	}
+	function reposition() {
+		position();
+	}
+	(0, react.useEffect)(() => {
+		anchorNode.current = anchorEl.current;
+		if (_openRef.current && !props.disabled) {
+			floatingNode.current = floatingEl.current;
+			arrowNode.current = arrowEl.current;
+			startTracking();
+		}
+		return () => {
+			stopTracking();
+		};
+	}, []);
+	(0, react.useEffect)(() => {
+		if (_watch0First.current) {
+			_watch0First.current = false;
+			return;
+		}
+		if (open && !props.disabled) queueMicrotask(() => {
+			if (!open || props.disabled) return;
+			floatingNode.current = floatingEl.current;
+			arrowNode.current = arrowEl.current;
+			startTracking();
+		});
+		else stopTracking();
+	}, [open]);
+	(0, react.useEffect)(() => {
+		if (_watch1First.current) {
+			_watch1First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.placement]);
+	(0, react.useEffect)(() => {
+		if (_watch2First.current) {
+			_watch2First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.offset]);
+	(0, react.useEffect)(() => {
+		if (_watch3First.current) {
+			_watch3First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.disableFlip]);
+	(0, react.useEffect)(() => {
+		if (_watch4First.current) {
+			_watch4First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.disableShift]);
+	(0, react.useEffect)(() => {
+		if (_watch5First.current) {
+			_watch5First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.strategy]);
+	(0, react.useEffect)(() => {
+		if (!open) return;
+		const _rozieHandler = ($event) => {
+			if ($event.key !== "Escape") return;
+			dismiss($event);
+		};
+		document.addEventListener("keydown", _rozieHandler);
+		return () => document.removeEventListener("keydown", _rozieHandler);
+	}, [dismiss, open]);
+	(0, _rozie_runtime_react.useOutsideClick)([anchorEl, floatingEl], dismiss, () => !!open);
+	const _rozieExposeRef = (0, react.useRef)({
+		show,
+		hide,
+		toggle,
+		reposition
+	});
+	_rozieExposeRef.current = {
+		show,
+		hide,
+		toggle,
+		reposition
+	};
+	(0, react.useImperativeHandle)(ref, () => ({
+		show: (...args) => _rozieExposeRef.current.show(...args),
+		hide: (...args) => _rozieExposeRef.current.hide(...args),
+		toggle: (...args) => _rozieExposeRef.current.toggle(...args),
+		reposition: (...args) => _rozieExposeRef.current.reposition(...args)
+	}), []);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		...attrs,
+		className: (0, _rozie_runtime_react.clsx)("rozie-popover", attrs.className),
+		"data-rozie-s-c6cf02ea": "",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: "rozie-popover-anchor",
+			ref: anchorEl,
+			"aria-haspopup": "dialog",
+			"aria-expanded": !!open,
+			"aria-describedby": (0, _rozie_runtime_react.rozieAttr)(isTooltip() && open ? "rozie-popover-floating" : void 0),
+			onClick: ($event) => {
+				props.trigger === "click" && onAnchorClick();
+			},
+			onPointerEnter: ($event) => {
+				props.trigger === "hover" && onAnchorPointerEnter();
+			},
+			onPointerLeave: ($event) => {
+				props.trigger === "hover" && onAnchorPointerLeave();
+			},
+			onFocus: ($event) => {
+				props.trigger === "focus" && onAnchorFocus();
+			},
+			onBlur: ($event) => {
+				props.trigger === "focus" && onAnchorBlur();
+			},
+			"data-rozie-s-c6cf02ea": "",
+			children: (props.renderAnchor ?? props.slots?.["anchor"])?.({
+				open,
+				toggle,
+				show,
+				hide
+			})
+		}), !!(open && !props.disabled) && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "rozie-popover-floating",
+			ref: floatingEl,
+			id: "rozie-popover-floating",
+			role: (0, _rozie_runtime_react.rozieAttr)(floatingRole()),
+			"aria-modal": !!(floatingRole() === "dialog"),
+			"data-rozie-s-c6cf02ea": "",
+			children: [!!props.arrow && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "rozie-popover-arrow",
+				ref: arrowEl,
+				"data-rozie-s-c6cf02ea": ""
+			}), typeof (props.children ?? props.slots?.[""]) === "function" ? (props.children ?? props.slots?.[""])() : props.children ?? props.slots?.[""]]
+		})]
+	}) });
+});
+//#endregion
+exports.Popover = Popover;
+exports.default = Popover;

package/dist/index.d.cts

@@ -0,0 +1,66 @@
+import * as React from "react";
+import { ReactNode } from "react";
+
+//#region src/Popover.d.ts
+interface PopoverProps {
+  /**
+   * Whether the floating content is open. The sole `model: true` prop — two-way bind it (`r-model:open` / `v-model:open` / `bind:open` / `[(open)]`) and Popover writes the new state back whenever the trigger or a dismissal toggles it. Left unbound it falls back to an uncontrolled default.
+   */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (next: boolean) => void;
+  /**
+   * Floating UI placement of the content relative to the anchor — one of `top`/`right`/`bottom`/`left`, each optionally suffixed `-start`/`-end` (e.g. `bottom-start`). With `disableFlip` off, the content may flip to the opposite side when it would overflow the viewport. Reconciled at runtime.
+   */
+  placement?: string;
+  /**
+   * How the anchor opens the content: `'click'` toggles on click, `'hover'` opens on pointer-enter and closes on pointer-leave (tooltip-style), `'focus'` opens on focus and closes on blur. Drives both the gesture handlers and the ARIA role (`'hover'`/`'focus'` → tooltip, `'click'` → popover dialog).
+   */
+  trigger?: string;
+  /**
+   * Distance in pixels between the anchor and the floating content (the Floating UI `offset` middleware). Reconciled at runtime.
+   */
+  offset?: number;
+  /**
+   * Disable the Floating UI `flip` middleware. By default the content flips to the opposite side of the anchor when it would overflow the viewport; set this to keep it pinned to `placement` regardless.
+   */
+  disableFlip?: boolean;
+  /**
+   * Disable the Floating UI `shift` middleware. By default the content shifts along its axis to stay within the viewport; set this to keep it strictly aligned to the anchor.
+   */
+  disableShift?: boolean;
+  /**
+   * Opt in to a positioned arrow element. When set, Popover renders an arrow `<div>` and runs the Floating UI `arrow` middleware against it so it points at the anchor. Style it via the `--rozie-popover-*` arrow CSS custom properties.
+   */
+  arrow?: boolean;
+  /**
+   * Disable the control entirely: the trigger no longer opens the content and any open content is suppressed.
+   */
+  disabled?: boolean;
+  /**
+   * Opt in to modal dialog semantics for a `click` popover. **Off by default:** a click popover is a non-modal, click-outside-dismissable layer, so its panel is rendered role-neutral (the slot content owns its own ARIA role — e.g. a `role="menu"`) and carries NO `aria-modal`. Set `modal` for a genuinely modal dialog popover: the panel then gets `role="dialog"` + `aria-modal="true"`. **Note:** Popover ships no focus trap (it stays a minimal headless primitive); if you set `modal`, provide your own focus containment so the `aria-modal` claim holds. Ignored for `hover`/`focus` triggers (always tooltip-flavored).
+   */
+  modal?: boolean;
+  /**
+   * Floating UI positioning strategy — 'absolute' (default) or 'fixed'. Use 'fixed' to escape a scrollable/overflow-clipping ancestor (e.g. a sticky table header). Reconciled at runtime.
+   */
+  strategy?: string;
+  onChange?: (...args: unknown[]) => void;
+  renderAnchor?: (params: {
+    open: boolean;
+    toggle: () => void;
+    show: () => void;
+    hide: () => void;
+  }) => ReactNode;
+  children?: ReactNode;
+  slots?: Record<string, () => ReactNode>;
+}
+interface PopoverHandle {
+  show: (...args: any[]) => any;
+  hide: (...args: any[]) => any;
+  toggle: (...args: any[]) => any;
+  reposition: (...args: any[]) => any;
+}
+declare const Popover: React.ForwardRefExoticComponent<PopoverProps & React.RefAttributes<PopoverHandle>>;
+//#endregion
+export { Popover, Popover as default, type PopoverHandle };

package/dist/index.d.mts

@@ -0,0 +1,66 @@
+import * as _$react from "react";
+import { ReactNode } from "react";
+//#region src/Popover.d.ts
+interface AnchorCtx {
+  open: any;
+  toggle: any;
+  show: any;
+  hide: any;
+}
+interface PopoverProps {
+  /**
+   * Whether the floating content is open. The sole `model: true` prop — two-way bind it (`r-model:open` / `v-model:open` / `bind:open` / `[(open)]`) and Popover writes the new state back whenever the trigger or a dismissal toggles it. Left unbound it falls back to an uncontrolled default.
+   */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Floating UI placement of the content relative to the anchor — one of `top`/`right`/`bottom`/`left`, each optionally suffixed `-start`/`-end` (e.g. `bottom-start`). With `disableFlip` off, the content may flip to the opposite side when it would overflow the viewport. Reconciled at runtime.
+   */
+  placement?: string;
+  /**
+   * How the anchor opens the content: `'click'` toggles on click, `'hover'` opens on pointer-enter and closes on pointer-leave (tooltip-style), `'focus'` opens on focus and closes on blur. Drives both the gesture handlers and the ARIA role (`'hover'`/`'focus'` → tooltip, `'click'` → popover dialog).
+   */
+  trigger?: string;
+  /**
+   * Distance in pixels between the anchor and the floating content (the Floating UI `offset` middleware). Reconciled at runtime.
+   */
+  offset?: number;
+  /**
+   * Disable the Floating UI `flip` middleware. By default the content flips to the opposite side of the anchor when it would overflow the viewport; set this to keep it pinned to `placement` regardless.
+   */
+  disableFlip?: boolean;
+  /**
+   * Disable the Floating UI `shift` middleware. By default the content shifts along its axis to stay within the viewport; set this to keep it strictly aligned to the anchor.
+   */
+  disableShift?: boolean;
+  /**
+   * Opt in to a positioned arrow element. When set, Popover renders an arrow `<div>` and runs the Floating UI `arrow` middleware against it so it points at the anchor. Style it via the `--rozie-popover-*` arrow CSS custom properties.
+   */
+  arrow?: boolean;
+  /**
+   * Disable the control entirely: the trigger no longer opens the content and any open content is suppressed.
+   */
+  disabled?: boolean;
+  /**
+   * Opt in to modal dialog semantics for a `click` popover. **Off by default:** a click popover is a non-modal, click-outside-dismissable layer, so its panel is rendered role-neutral (the slot content owns its own ARIA role — e.g. a `role="menu"`) and carries NO `aria-modal`. Set `modal` for a genuinely modal dialog popover: the panel then gets `role="dialog"` + `aria-modal="true"`. **Note:** Popover ships no focus trap (it stays a minimal headless primitive); if you set `modal`, provide your own focus containment so the `aria-modal` claim holds. Ignored for `hover`/`focus` triggers (always tooltip-flavored).
+   */
+  modal?: boolean;
+  /**
+   * Floating UI positioning strategy — 'absolute' (default) or 'fixed'. Use 'fixed' to escape a scrollable/overflow-clipping ancestor (e.g. a sticky table header). Reconciled at runtime.
+   */
+  strategy?: string;
+  onChange?: (...args: any[]) => void;
+  renderAnchor?: (ctx: AnchorCtx) => ReactNode;
+  children?: ReactNode;
+  slots?: Record<string, () => _$react.ReactNode>;
+}
+interface PopoverHandle {
+  show: (...args: any[]) => any;
+  hide: (...args: any[]) => any;
+  toggle: (...args: any[]) => any;
+  reposition: (...args: any[]) => any;
+}
+declare const Popover: _$react.ForwardRefExoticComponent<PopoverProps & _$react.RefAttributes<PopoverHandle>>;
+//#endregion
+export { Popover, Popover as default, type PopoverHandle };