@rozie-ui/popover-react 0.1.0

package/dist/index.mjs

@@ -0,0 +1,302 @@
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef } from "react";
+import { clsx, rozieAttr, useControllableState, useOutsideClick } from "@rozie/runtime-react";
+import "./Popover.css";
+import { arrow, autoUpdate, computePosition, flip, offset, shift } from "@floating-ui/dom";
+import { Fragment, jsx, jsxs } from "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 = 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 = useRef(null);
+	const floatingNode = useRef(null);
+	const arrowNode = useRef(null);
+	const stopAutoUpdate = useRef(null);
+	const lastFocusedEl = useRef(null);
+	const [open, setOpen] = useControllableState({
+		value: props.open,
+		defaultValue: props.defaultOpen ?? false,
+		onValueChange: props.onOpenChange
+	});
+	const _openRef = useRef(open);
+	_openRef.current = open;
+	const anchorEl = useRef(null);
+	const floatingEl = useRef(null);
+	const arrowEl = useRef(null);
+	const _watch0First = useRef(true);
+	const _watch1First = useRef(true);
+	const _watch2First = useRef(true);
+	const _watch3First = useRef(true);
+	const _watch4First = useRef(true);
+	const _watch5First = 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,
+			flip,
+			shift,
+			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
+		};
+		computePosition(anchorNode.current, floatingNode.current, opts).then((result) => {
+			applyPosition(result.x, result.y, result.middlewareData);
+		});
+	}
+	const startTracking = useCallback(() => {
+		if (!anchorNode.current || !floatingNode.current) return;
+		if (stopAutoUpdate.current) {
+			stopAutoUpdate.current();
+			stopAutoUpdate.current = null;
+		}
+		stopAutoUpdate.current = autoUpdate(anchorNode.current, floatingNode.current, position);
+	}, [position]);
+	const stopTracking = useCallback(() => {
+		if (stopAutoUpdate.current) {
+			stopAutoUpdate.current();
+			stopAutoUpdate.current = null;
+		}
+	}, []);
+	const onAnchorClick = useCallback(() => {
+		if (props.disabled) return;
+		requestOpen(!open);
+	}, [
+		open,
+		props.disabled,
+		requestOpen
+	]);
+	const onAnchorPointerEnter = useCallback(() => {
+		if (props.disabled) return;
+		requestOpen(true);
+	}, [props.disabled, requestOpen]);
+	const onAnchorPointerLeave = useCallback(() => {
+		if (props.disabled) return;
+		requestOpen(false);
+	}, [props.disabled, requestOpen]);
+	const onAnchorFocus = useCallback(() => {
+		if (props.disabled) return;
+		requestOpen(true);
+	}, [props.disabled, requestOpen]);
+	const onAnchorBlur = useCallback(() => {
+		if (props.disabled) return;
+		requestOpen(false);
+	}, [props.disabled, requestOpen]);
+	const dismiss = 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();
+	}
+	useEffect(() => {
+		anchorNode.current = anchorEl.current;
+		if (_openRef.current && !props.disabled) {
+			floatingNode.current = floatingEl.current;
+			arrowNode.current = arrowEl.current;
+			startTracking();
+		}
+		return () => {
+			stopTracking();
+		};
+	}, []);
+	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]);
+	useEffect(() => {
+		if (_watch1First.current) {
+			_watch1First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.placement]);
+	useEffect(() => {
+		if (_watch2First.current) {
+			_watch2First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.offset]);
+	useEffect(() => {
+		if (_watch3First.current) {
+			_watch3First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.disableFlip]);
+	useEffect(() => {
+		if (_watch4First.current) {
+			_watch4First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.disableShift]);
+	useEffect(() => {
+		if (_watch5First.current) {
+			_watch5First.current = false;
+			return;
+		}
+		if (open) position();
+	}, [props.strategy]);
+	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]);
+	useOutsideClick([anchorEl, floatingEl], dismiss, () => !!open);
+	const _rozieExposeRef = useRef({
+		show,
+		hide,
+		toggle,
+		reposition
+	});
+	_rozieExposeRef.current = {
+		show,
+		hide,
+		toggle,
+		reposition
+	};
+	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__ */ jsx(Fragment, { children: /* @__PURE__ */ jsxs("div", {
+		...attrs,
+		className: clsx("rozie-popover", attrs.className),
+		"data-rozie-s-c6cf02ea": "",
+		children: [/* @__PURE__ */ jsx("div", {
+			className: "rozie-popover-anchor",
+			ref: anchorEl,
+			"aria-haspopup": "dialog",
+			"aria-expanded": !!open,
+			"aria-describedby": 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__ */ jsxs("div", {
+			className: "rozie-popover-floating",
+			ref: floatingEl,
+			id: "rozie-popover-floating",
+			role: rozieAttr(floatingRole()),
+			"aria-modal": !!(floatingRole() === "dialog"),
+			"data-rozie-s-c6cf02ea": "",
+			children: [!!props.arrow && /* @__PURE__ */ 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
+export { Popover, Popover as default };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@rozie-ui/popover-react",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "description": "Idiomatic React popover/tooltip wrapping @floating-ui/dom — one Rozie source compiled to React.",
+  "keywords": [
+    "rozie",
+    "rozie-ui",
+    "floating-ui",
+    "popover",
+    "tooltip",
+    "dropdown",
+    "positioning",
+    "headless",
+    "component",
+    "react"
+  ],
+  "author": "One Learning Community (https://github.com/One-Learning-Community)",
+  "homepage": "https://github.com/One-Learning-Community/rozie.js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/One-Learning-Community/rozie.js.git",
+    "directory": "packages/ui/popover/packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/One-Learning-Community/rozie.js/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./themes/*": "./src/themes/*",
+    "./rozie-manifest.json": "./rozie-manifest.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "rozie-manifest.json"
+  ],
+  "dependencies": {
+    "@rozie/runtime-react": "0.1.4"
+  },
+  "peerDependencies": {
+    "react": "^18.2 || ^19",
+    "react-dom": "^18.2 || ^19",
+    "@floating-ui/dom": "^1.7.2"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "react-dom": {
+      "optional": false
+    },
+    "@floating-ui/dom": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@floating-ui/dom": "^1.7.2",
+    "@types/react": "^18",
+    "@types/react-dom": "^18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "*.css",
+    "**/*.css"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/rozie-manifest.json

@@ -0,0 +1,112 @@
+{
+  "schemaVersion": 1,
+  "name": "Popover",
+  "props": [
+    {
+      "name": "open",
+      "isModel": true,
+      "required": false,
+      "type": "Boolean"
+    },
+    {
+      "name": "placement",
+      "isModel": false,
+      "required": false,
+      "type": "String"
+    },
+    {
+      "name": "trigger",
+      "isModel": false,
+      "required": false,
+      "type": "String"
+    },
+    {
+      "name": "offset",
+      "isModel": false,
+      "required": false,
+      "type": "Number"
+    },
+    {
+      "name": "disableFlip",
+      "isModel": false,
+      "required": false,
+      "type": "Boolean"
+    },
+    {
+      "name": "disableShift",
+      "isModel": false,
+      "required": false,
+      "type": "Boolean"
+    },
+    {
+      "name": "arrow",
+      "isModel": false,
+      "required": false,
+      "type": "Boolean"
+    },
+    {
+      "name": "disabled",
+      "isModel": false,
+      "required": false,
+      "type": "Boolean"
+    },
+    {
+      "name": "modal",
+      "isModel": false,
+      "required": false,
+      "type": "Boolean"
+    },
+    {
+      "name": "strategy",
+      "isModel": false,
+      "required": false,
+      "type": "String"
+    }
+  ],
+  "slots": [
+    {
+      "name": "anchor",
+      "params": [
+        {
+          "name": "open"
+        },
+        {
+          "name": "toggle"
+        },
+        {
+          "name": "show"
+        },
+        {
+          "name": "hide"
+        }
+      ],
+      "paramTypes": null,
+      "isPortal": false,
+      "isReactive": false
+    },
+    {
+      "name": "",
+      "params": [],
+      "paramTypes": null,
+      "isPortal": false,
+      "isReactive": false
+    }
+  ],
+  "emits": [
+    "change"
+  ],
+  "expose": [
+    {
+      "name": "show"
+    },
+    {
+      "name": "hide"
+    },
+    {
+      "name": "toggle"
+    },
+    {
+      "name": "reposition"
+    }
+  ]
+}

package/src/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/src/Popover.d.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react';
+import type { ForwardRefExoticComponent, RefAttributes } from 'react';
+import type * as React from 'react';
+
+export 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>;
+}
+
+export 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>>;
+export default Popover;