@galaxy-io/dls 1.6.1 → 2.0.1

package/dist/navigation/Topbar.js

@@ -0,0 +1,62 @@
+import Text, { TextWeight } from "../text/Text.js";
+/* empty css                 */
+import { styled } from "@linaria/react";
+import { forwardRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/navigation/Topbar.tsx
+/**
+* The 48px bar across the top of a page: where you are on the left, what you can do on the right.
+* A `<header>` with a bottom hairline and three slots in a row: `leading` (a sidebar toggle, a
+* back button, a brand mark), the main content (`children`: breadcrumbs or the page title) and
+* `actions` at the end (search, the assistant, the account). It owns the height, the rule, the
+* spacing and the left / right split; everything inside is composed from other components. It
+* does not stick, route or collapse. In an app frame it sits above the page's scrolling region.
+*
+* Outside `main`, `article`, `aside`, `nav` and `section` the `<header>` is the page's `banner`
+* landmark, so use one Topbar per page. New in 2.0 (from the rafa prototype).
+*/
+/** The bar: 48px, a bottom hairline, `background.base` (the top of the page, not chrome). */
+var Root = /*#__PURE__*/ styled("header")({
+	name: "Root",
+	class: "gx-Topbar-r1xyq67l",
+	propsAsIs: false
+});
+var Leading = /*#__PURE__*/ styled("div")({
+	name: "Leading",
+	class: "gx-Topbar-Leading-ly1m7jx",
+	propsAsIs: false
+});
+/** Grows to push `actions` to the end; clips a trail that does not fit instead of pushing them out. */
+var Content = /*#__PURE__*/ styled("div")({
+	name: "Content",
+	class: "gx-Topbar-Content-cmm5l4g",
+	propsAsIs: false
+});
+var Actions = /*#__PURE__*/ styled("div")({
+	name: "Actions",
+	class: "gx-Topbar-Actions-acmt9iy",
+	propsAsIs: false
+});
+/** The page bar: `leading`, the title or breadcrumbs, and `actions` at the end. */
+var Topbar = forwardRef(function Topbar({ children, leading, actions, className, style, ...rest }, ref) {
+	return /* @__PURE__ */ jsxs(Root, {
+		...rest,
+		ref,
+		className,
+		style,
+		children: [
+			leading && /* @__PURE__ */ jsx(Leading, { children: leading }),
+			/* @__PURE__ */ jsx(Content, { children: typeof children === "string" ? /* @__PURE__ */ jsx(Text, {
+				as: "span",
+				weight: TextWeight.MEDIUM,
+				lineClamp: 1,
+				shouldTooltipOnOverflow: true,
+				children
+			}) : children }),
+			actions && /* @__PURE__ */ jsx(Actions, { children: actions })
+		]
+	});
+});
+Topbar.displayName = "Topbar";
+//#endregion
+export { Topbar as default };

package/dist/overlay/OverlayProvider.d.ts

@@ -1,37 +1,33 @@
-import { type PropsWithChildren } from "react";
-import { OverlayLayer } from "./constants";
-/** One registered overlay in the stack. */
-export interface OverlayEntry {
-    id: string;
-    onDismiss: () => void;
-    layer: OverlayLayer;
-    dismissOnOverlayClick: boolean;
-    zIndex: number;
+/**
+ * The root of the overlay stack: one store per app and one Escape listener that reaches only the
+ * topmost registered overlay. `GalaxyProvider` mounts it, so apps never do; mount it yourself only
+ * in a React root that has no `GalaxyProvider`. A nested `OverlayProvider` (a scoped
+ * `GalaxyProvider`) reuses the outer stack.
+ *
+ * `OverlayNode` marks the subtree of an open overlay, so overlays opened inside it stack above it.
+ *
+ * Both render no element. SSR: the listener attaches in an effect; nothing touches `document` at
+ * module scope.
+ */
+import { type ReactNode } from "react";
+export interface OverlayProviderProps {
+    /** The app. Mounted by `GalaxyProvider`; mount it yourself only in a React root that has no `GalaxyProvider`. */
+    children: ReactNode;
 }
-/** Options for `useOverlay`'s third argument. */
-export interface OverlayRegisterOptions {
-    /** Stacking tier. Modals always sit above drawers. @default OverlayLayer.MODAL */
-    layer?: OverlayLayer;
-    /** Call `onDismiss` when the shared backdrop is clicked. */
-    dismissOnOverlayClick?: boolean;
+export interface OverlayNodeProps {
+    /** The `overlayId` from this overlay's `useOverlay`. Overlays rendered inside stack above this one. */
+    overlayId: string;
+    /** The overlay's content (inside its `Portal`). */
+    children: ReactNode;
 }
-export interface OverlayInfo {
-    zIndex: number;
-    isTopmost: boolean;
+/** Holds the overlay stack and routes Escape to the topmost overlay. */
+declare function OverlayProvider({ children }: OverlayProviderProps): import("react").JSX.Element;
+declare namespace OverlayProvider {
+    var displayName: string;
 }
-export interface OverlayContextValue {
-    register: (id: string, onDismiss: () => void, options?: OverlayRegisterOptions) => void;
-    unregister: (id: string) => void;
-    overlays: OverlayEntry[];
+/** Marks an open overlay's content, so overlays opened inside it stack above it. */
+export declare function OverlayNode({ overlayId, children }: OverlayNodeProps): import("react").JSX.Element;
+export declare namespace OverlayNode {
+    var displayName: string;
 }
-export declare const OverlayContext: import("react").Context<OverlayContextValue | null>;
-/**
- * Coordinates every `Modal` and `Drawer` on the page. Mount it once near the
- * root, above anything that opens an overlay.
- *
- * Renders one shared backdrop for the whole stack and routes Escape to the
- * topmost overlay only, so nesting a modal over a drawer behaves.
- */
-export declare const OverlayProvider: ({ children }: PropsWithChildren) => import("react").JSX.Element;
 export default OverlayProvider;
-export { getOverlayZIndex, OVERLAY_LAYER_PRIORITY, OVERLAY_Z_INDEX, OVERLAY_Z_INDEX_BASE, OVERLAY_Z_INDEX_STEP, OverlayLayer, } from "./constants";

package/dist/overlay/OverlayProvider.js

@@ -1,99 +1,48 @@
-import { withTheme } from "../theme/GalaxyTheme.js";
-import { OVERLAY_LAYER_PRIORITY, OVERLAY_Z_INDEX, OVERLAY_Z_INDEX_BASE, OVERLAY_Z_INDEX_STEP, OverlayLayer, getOverlayZIndex } from "./constants.js";
-/* empty css                          */
-import { styled } from "@linaria/react";
-import { createContext, useCallback, useMemo, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { createPortal } from "react-dom";
+import { OverlayParentContext, OverlayStoreContext, createOverlayStore, isOverlayEscape } from "./useOverlay.js";
+import { useContext, useEffect, useState } from "react";
+import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 //#region src/overlay/OverlayProvider.tsx
-var OverlayContext = createContext(null);
-var _exp = () => ({ theme }) => theme.color.opacity.bw48;
-var _exp2 = () => ({ isVisible }) => isVisible ? "blur(4px)" : "blur(0px)";
-var _exp3 = () => ({ isVisible }) => isVisible ? 1 : 0;
-var _exp4 = () => ({ isVisible }) => isVisible ? "visible" : "hidden";
-var _exp5 = () => ({ isVisible }) => isVisible ? "backdrop-filter 0.2s ease-out, opacity 0.2s ease-out" : "none";
-var _exp6 = () => ({ $zIndex }) => $zIndex;
-var _exp7 = () => ({ isVisible }) => isVisible ? "auto" : "none";
-var SharedOverlay = withTheme(/*#__PURE__*/ styled("div")({
-	name: "SharedOverlay",
-	class: "s1hpu3t7",
-	propsAsIs: false,
-	vars: {
-		"s1hpu3t7-0": [_exp()],
-		"s1hpu3t7-1": [_exp2()],
-		"s1hpu3t7-2": [_exp3()],
-		"s1hpu3t7-3": [_exp4()],
-		"s1hpu3t7-4": [_exp5()],
-		"s1hpu3t7-5": [_exp6()],
-		"s1hpu3t7-6": [_exp7()]
-	}
-}));
 /**
-* Coordinates every `Modal` and `Drawer` on the page. Mount it once near the
-* root, above anything that opens an overlay.
+* The root of the overlay stack: one store per app and one Escape listener that reaches only the
+* topmost registered overlay. `GalaxyProvider` mounts it, so apps never do; mount it yourself only
+* in a React root that has no `GalaxyProvider`. A nested `OverlayProvider` (a scoped
+* `GalaxyProvider`) reuses the outer stack.
 *
-* Renders one shared backdrop for the whole stack and routes Escape to the
-* topmost overlay only, so nesting a modal over a drawer behaves.
+* `OverlayNode` marks the subtree of an open overlay, so overlays opened inside it stack above it.
+*
+* Both render no element. SSR: the listener attaches in an effect; nothing touches `document` at
+* module scope.
 */
-var OverlayProvider = ({ children }) => {
-	const [overlays, setOverlays] = useState([]);
-	const zIndexCounterRef = useRef(0);
-	const register = useCallback((id, onDismiss, options) => {
-		const layer = options?.layer ?? OverlayLayer.DRAWER;
-		const dismissOnOverlayClick = options?.dismissOnOverlayClick ?? true;
-		setOverlays((prev) => {
-			const existingIndex = prev.findIndex((entry) => entry.id === id);
-			if (existingIndex === -1) {
-				const zIndex = OVERLAY_Z_INDEX_BASE + zIndexCounterRef.current * 10;
-				zIndexCounterRef.current += 1;
-				return [...prev, {
-					id,
-					onDismiss,
-					layer,
-					dismissOnOverlayClick,
-					zIndex
-				}];
-			}
-			const next = [...prev];
-			next[existingIndex] = {
-				...prev[existingIndex],
-				onDismiss,
-				layer,
-				dismissOnOverlayClick
-			};
-			return next;
-		});
-	}, []);
-	const unregister = useCallback((id) => {
-		setOverlays((prev) => prev.filter((entry) => entry.id !== id));
-	}, []);
-	const topmost = useMemo(() => {
-		if (overlays.length === 0) return null;
-		return overlays.reduce((top, entry) => entry.zIndex > top.zIndex ? entry : top, overlays[0]);
-	}, [overlays]);
-	const handleOverlayClick = useCallback(() => {
-		if (!topmost || !topmost.dismissOnOverlayClick) return;
-		topmost.onDismiss();
-	}, [topmost]);
-	const contextValue = useMemo(() => ({
-		register,
-		unregister,
-		overlays
-	}), [
-		register,
-		unregister,
-		overlays
-	]);
-	const isVisible = !!topmost;
-	const backdropZIndex = topmost ? topmost.zIndex - 1 : OVERLAY_Z_INDEX_BASE - 1;
-	return /* @__PURE__ */ jsxs(OverlayContext.Provider, {
-		value: contextValue,
-		children: [children, createPortal(/* @__PURE__ */ jsx(SharedOverlay, {
-			isVisible,
-			$zIndex: backdropZIndex,
-			onClick: handleOverlayClick
-		}), document.body)]
+/** Holds the overlay stack and routes Escape to the topmost overlay. */
+function OverlayProvider({ children }) {
+	const outerStore = useContext(OverlayStoreContext);
+	const [ownStore] = useState(() => outerStore === null ? createOverlayStore() : null);
+	useEffect(() => {
+		if (ownStore === null) return;
+		const handleKeyDown = (event) => {
+			if (!isOverlayEscape(event)) return;
+			const onEscapeRef = ownStore.getTopmostEscape();
+			if (onEscapeRef === null) return;
+			event.preventDefault();
+			onEscapeRef.current?.();
+		};
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [ownStore]);
+	if (ownStore === null) return /* @__PURE__ */ jsx(Fragment$1, { children });
+	return /* @__PURE__ */ jsx(OverlayStoreContext.Provider, {
+		value: ownStore,
+		children
+	});
+}
+OverlayProvider.displayName = "OverlayProvider";
+/** Marks an open overlay's content, so overlays opened inside it stack above it. */
+function OverlayNode({ overlayId, children }) {
+	return /* @__PURE__ */ jsx(OverlayParentContext.Provider, {
+		value: overlayId,
+		children
 	});
-};
+}
+OverlayNode.displayName = "OverlayNode";
 //#endregion
-export { OVERLAY_LAYER_PRIORITY, OVERLAY_Z_INDEX, OVERLAY_Z_INDEX_BASE, OVERLAY_Z_INDEX_STEP, OverlayContext, OverlayLayer, OverlayProvider, OverlayProvider as default, getOverlayZIndex };
+export { OverlayNode, OverlayProvider as default };

package/dist/overlay/useOverlay.d.ts

@@ -1,18 +1,94 @@
-import { type OverlayRegisterOptions } from "./OverlayProvider";
-export interface UseOverlayReturn {
-    /** The z-index to render this overlay at. Assigned by its position in the stack. */
+/**
+ * The stacking and Escape coordinator for everything that floats above the page. An overlay calls
+ * `useOverlay` while it is open: the hook registers it in one stack per app (held by
+ * `OverlayProvider`, which `GalaxyProvider` mounts) and returns the `zIndex` to render at and
+ * whether it is the topmost. The root routes Escape to the topmost overlay only.
+ *
+ * Order: by layer (`z.dropdown` < `z.drawer` < `z.modal` < `z.tooltip`), then by nesting (an
+ * overlay rendered inside another's `OverlayNode` sits above it, in at least its layer), then by
+ * the order they opened.
+ *
+ * The stack renders nothing, moves no focus, draws no backdrop and handles no pointer events.
+ *
+ * SSR: nothing here touches `window` or `document` at module scope. Registration runs in a layout
+ * effect on the client; the server snapshot is the closed state.
+ */
+import { type MutableRefObject } from "react";
+/** The `z` layer an overlay belongs to. Layers never interleave: a higher layer is always above a lower one. */
+export declare enum OverlayLayer {
+    /** Anchored panels: Popover, Dropdown, Menu, ContextMenu, SelectInput, DateInput, ColorInput (`z.dropdown`, 1000). */
+    DROPDOWN = "DROPDOWN",
+    /** Drawers (`z.drawer`, 1100). */
+    DRAWER = "DRAWER",
+    /** Modals, ConfirmDialog, CommandPalette (`z.modal`, 1200). */
+    MODAL = "MODAL",
+    /** Tooltips (`z.tooltip`, 1400). */
+    TOOLTIP = "TOOLTIP"
+}
+/** Options for `useOverlay`. */
+export interface UseOverlayOptions {
+    /** Whether the overlay is open. It is in the stack while `true`. Pass the overlay's own open state. */
+    isOpen: boolean;
+    /** Which `z` layer it belongs to. Modals always sit above drawers, drawers above dropdowns, tooltips above everything. */
+    layer: OverlayLayer;
+    /** Called when Escape is pressed while this overlay is the topmost. When omitted, Escape does nothing while it is topmost and does not reach the overlays below. */
+    onEscape?: (() => void) | undefined;
+}
+/** What `useOverlay` returns. */
+export interface UseOverlayResult {
+    /** The z-index to render at: its layer's base plus its rank in that layer. While closed (or before registration), the base of its own layer. */
     zIndex: number;
-    /** True when nothing is stacked above. Only the topmost overlay should act on Escape. */
+    /** `true` while it is the highest overlay in the stack. `false` while closed. */
     isTopmost: boolean;
+    /** This overlay's id in the stack (a `useId()` value). Pass it to `OverlayNode` around the overlay's content. */
+    overlayId: string;
 }
+/** One registered overlay's place in the stack. Identity is stable until a value changes. */
+interface OverlaySnapshot {
+    zIndex: number;
+    isTopmost: boolean;
+}
+/**
+ * The per-root stack. Plain JS, created in `OverlayProvider`'s state (never at module scope).
+ * @internal Shared with `OverlayProvider`; not part of the public API.
+ */
+export interface OverlayStore {
+    register: (id: string, layer: OverlayLayer, parentId: string | null, onEscapeRef: MutableRefObject<(() => void) | undefined>) => void;
+    update: (id: string, layer: OverlayLayer, parentId: string | null) => void;
+    unregister: (id: string) => void;
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: (id: string) => OverlaySnapshot | null;
+    /** The topmost entry's Escape callback holder, or `null` while the stack is empty. */
+    getTopmostEscape: () => MutableRefObject<(() => void) | undefined> | null;
+}
+/**
+ * Creates one stack.
+ * @internal Used by `OverlayProvider`.
+ */
+export declare function createOverlayStore(): OverlayStore;
+/**
+ * The enclosing root's stack, or `null` outside any `OverlayProvider`.
+ * @internal Provided by `OverlayProvider`.
+ */
+export declare const OverlayStoreContext: import("react").Context<OverlayStore | null>;
+/**
+ * The `overlayId` of the nearest enclosing `OverlayNode`, or `null`.
+ * @internal Provided by `OverlayNode`.
+ */
+export declare const OverlayParentContext: import("react").Context<string | null>;
+/**
+ * Whether an Escape keydown should reach an overlay: not already handled, not mid IME
+ * composition, not a key repeat (holding Escape closes one layer, not all of them).
+ * @internal Shared with `OverlayProvider`.
+ */
+export declare function isOverlayEscape(event: KeyboardEvent): boolean;
 /**
- * Registers an overlay in the global stack and returns its z-index and whether
- * it's on top. `Modal` and `Drawer` use it internally — reach for it only when
- * building your own overlay that must interleave correctly with theirs.
+ * Registers an overlay in the app's stack while `isOpen`, and returns its `zIndex`, whether it is
+ * the topmost, and the `overlayId` to pass to `OverlayNode`.
  *
- * Registration follows `enabled`, so pass your `open` flag straight through.
- * Falls back to a computed top-of-stack z-index when there's no
- * `OverlayProvider`, so it degrades rather than throwing.
+ * @example
+ * const { zIndex, overlayId } = useOverlay({ isOpen, layer: OverlayLayer.DROPDOWN, onEscape: () => setIsOpen(false) });
+ * <Portal><OverlayNode overlayId={overlayId}><Panel style={{ "--gx-popover-z": zIndex }}>…</Panel></OverlayNode></Portal>
  */
-export declare const useOverlay: (onDismiss: () => void, enabled: boolean, options?: OverlayRegisterOptions) => UseOverlayReturn;
-export default useOverlay;
+export declare function useOverlay({ isOpen, layer, onEscape }: UseOverlayOptions): UseOverlayResult;
+export {};

package/dist/overlay/useOverlay.js

@@ -1,55 +1,232 @@
-import { OVERLAY_Z_INDEX_BASE } from "./constants.js";
-import { OverlayContext } from "./OverlayProvider.js";
-import { useContext, useEffect, useId } from "react";
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+import { Z } from "../theme/tokens/scales.js";
+import { createContext, useContext, useEffect, useId, useRef, useSyncExternalStore } from "react";
 //#region src/overlay/useOverlay.ts
 /**
-* Registers an overlay in the global stack and returns its z-index and whether
-* it's on top. `Modal` and `Drawer` use it internally — reach for it only when
-* building your own overlay that must interleave correctly with theirs.
+* The stacking and Escape coordinator for everything that floats above the page. An overlay calls
+* `useOverlay` while it is open: the hook registers it in one stack per app (held by
+* `OverlayProvider`, which `GalaxyProvider` mounts) and returns the `zIndex` to render at and
+* whether it is the topmost. The root routes Escape to the topmost overlay only.
 *
-* Registration follows `enabled`, so pass your `open` flag straight through.
-* Falls back to a computed top-of-stack z-index when there's no
-* `OverlayProvider`, so it degrades rather than throwing.
+* Order: by layer (`z.dropdown` < `z.drawer` < `z.modal` < `z.tooltip`), then by nesting (an
+* overlay rendered inside another's `OverlayNode` sits above it, in at least its layer), then by
+* the order they opened.
+*
+* The stack renders nothing, moves no focus, draws no backdrop and handles no pointer events.
+*
+* SSR: nothing here touches `window` or `document` at module scope. Registration runs in a layout
+* effect on the client; the server snapshot is the closed state.
 */
-var useOverlay = (onDismiss, enabled, options) => {
-	const context = useContext(OverlayContext);
-	const id = useId();
-	const layer = options?.layer;
-	const dismissOnOverlayClick = options?.dismissOnOverlayClick;
-	const register = context?.register;
-	const unregister = context?.unregister;
-	useEffect(() => {
-		if (!register || !unregister) return;
-		if (enabled) register(id, onDismiss, {
-			layer,
-			dismissOnOverlayClick
-		});
-		else unregister(id);
-		return () => {
-			unregister(id);
+/** The `z` layer an overlay belongs to. Layers never interleave: a higher layer is always above a lower one. */
+var OverlayLayer = /* @__PURE__ */ function(OverlayLayer) {
+	/** Anchored panels: Popover, Dropdown, Menu, ContextMenu, SelectInput, DateInput, ColorInput (`z.dropdown`, 1000). */
+	OverlayLayer["DROPDOWN"] = "DROPDOWN";
+	/** Drawers (`z.drawer`, 1100). */
+	OverlayLayer["DRAWER"] = "DRAWER";
+	/** Modals, ConfirmDialog, CommandPalette (`z.modal`, 1200). */
+	OverlayLayer["MODAL"] = "MODAL";
+	/** Tooltips (`z.tooltip`, 1400). */
+	OverlayLayer["TOOLTIP"] = "TOOLTIP";
+	return OverlayLayer;
+}({});
+/** Layer → its base z-index, read as numbers from the `z` scale (logic, not CSS). */
+var OVERLAY_LAYER_TO_Z_MAP = {
+	["DROPDOWN"]: Z.dropdown,
+	["DRAWER"]: Z.drawer,
+	["MODAL"]: Z.modal,
+	["TOOLTIP"]: Z.tooltip
+};
+/** The highest rank within a layer. The `z` steps are 100 apart, so layers never interleave. */
+var OVERLAY_MAX_RANK = 99;
+/**
+* Creates one stack.
+* @internal Used by `OverlayProvider`.
+*/
+function createOverlayStore() {
+	const entries = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	let snapshots = /* @__PURE__ */ new Map();
+	let topmostId = null;
+	let sequenceCounter = 0;
+	/** Effective layer, sort key and depth, following registered parents (memoized per pass). */
+	const computeOrder = () => {
+		const memo = /* @__PURE__ */ new Map();
+		const resolve = (id, entry) => {
+			const cached = memo.get(id);
+			if (cached !== void 0) return cached;
+			const ownZ = OVERLAY_LAYER_TO_Z_MAP[entry.layer];
+			const parent = entry.parentId === null ? void 0 : entries.get(entry.parentId);
+			let order;
+			if (entry.parentId !== null && parent !== void 0) {
+				const parentOrder = resolve(entry.parentId, parent);
+				order = {
+					id,
+					layerZ: Math.max(ownZ, parentOrder.layerZ),
+					key: Math.max(entry.sequence, parentOrder.key),
+					depth: parentOrder.depth + 1,
+					sequence: entry.sequence
+				};
+			} else order = {
+				id,
+				layerZ: ownZ,
+				key: entry.sequence,
+				depth: 0,
+				sequence: entry.sequence
+			};
+			memo.set(id, order);
+			return order;
 		};
+		for (const [id, entry] of entries) resolve(id, entry);
+		return [...memo.values()].sort((a, b) => a.layerZ - b.layerZ || a.key - b.key || a.depth - b.depth || a.sequence - b.sequence);
+	};
+	/** Recomputes every snapshot, keeps unchanged ones by identity, and notifies on any change. */
+	const recompute = () => {
+		const sorted = computeOrder();
+		const next = /* @__PURE__ */ new Map();
+		const last = sorted[sorted.length - 1];
+		topmostId = last === void 0 ? null : last.id;
+		let rank = 0;
+		let previousLayerZ = null;
+		for (const order of sorted) {
+			rank = order.layerZ === previousLayerZ ? rank + 1 : 0;
+			previousLayerZ = order.layerZ;
+			const zIndex = order.layerZ + Math.min(rank, OVERLAY_MAX_RANK);
+			const isTopmost = order.id === topmostId;
+			const previous = snapshots.get(order.id);
+			next.set(order.id, previous !== void 0 && previous.zIndex === zIndex && previous.isTopmost === isTopmost ? previous : {
+				zIndex,
+				isTopmost
+			});
+		}
+		snapshots = next;
+		for (const listener of listeners) listener();
+	};
+	return {
+		register(id, layer, parentId, onEscapeRef) {
+			sequenceCounter += 1;
+			entries.set(id, {
+				layer,
+				parentId,
+				sequence: sequenceCounter,
+				onEscapeRef
+			});
+			recompute();
+		},
+		update(id, layer, parentId) {
+			const entry = entries.get(id);
+			if (entry === void 0 || entry.layer === layer && entry.parentId === parentId) return;
+			entries.set(id, {
+				...entry,
+				layer,
+				parentId
+			});
+			recompute();
+		},
+		unregister(id) {
+			if (!entries.delete(id)) return;
+			recompute();
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		getSnapshot(id) {
+			return snapshots.get(id) ?? null;
+		},
+		getTopmostEscape() {
+			if (topmostId === null) return null;
+			return entries.get(topmostId)?.onEscapeRef ?? null;
+		}
+	};
+}
+/**
+* The enclosing root's stack, or `null` outside any `OverlayProvider`.
+* @internal Provided by `OverlayProvider`.
+*/
+var OverlayStoreContext = createContext(null);
+/**
+* The `overlayId` of the nearest enclosing `OverlayNode`, or `null`.
+* @internal Provided by `OverlayNode`.
+*/
+var OverlayParentContext = createContext(null);
+/**
+* Whether an Escape keydown should reach an overlay: not already handled, not mid IME
+* composition, not a key repeat (holding Escape closes one layer, not all of them).
+* @internal Shared with `OverlayProvider`.
+*/
+function isOverlayEscape(event) {
+	return event.key === "Escape" && !event.defaultPrevented && !event.isComposing && !event.repeat;
+}
+/** No root: there is nothing to subscribe to. */
+var subscribeToNothing = () => () => {};
+var getNoSnapshot = () => null;
+/**
+* Registers an overlay in the app's stack while `isOpen`, and returns its `zIndex`, whether it is
+* the topmost, and the `overlayId` to pass to `OverlayNode`.
+*
+* @example
+* const { zIndex, overlayId } = useOverlay({ isOpen, layer: OverlayLayer.DROPDOWN, onEscape: () => setIsOpen(false) });
+* <Portal><OverlayNode overlayId={overlayId}><Panel style={{ "--gx-popover-z": zIndex }}>…</Panel></OverlayNode></Portal>
+*/
+function useOverlay({ isOpen, layer, onEscape }) {
+	const store = useContext(OverlayStoreContext);
+	const parentId = useContext(OverlayParentContext);
+	const overlayId = useId();
+	const onEscapeRef = useRef(onEscape);
+	onEscapeRef.current = onEscape;
+	const placementRef = useRef({
+		layer,
+		parentId
+	});
+	placementRef.current = {
+		layer,
+		parentId
+	};
+	useIsomorphicLayoutEffect(() => {
+		if (store === null || !isOpen) return;
+		store.register(overlayId, placementRef.current.layer, placementRef.current.parentId, onEscapeRef);
+		return () => store.unregister(overlayId);
+	}, [
+		store,
+		isOpen,
+		overlayId
+	]);
+	useIsomorphicLayoutEffect(() => {
+		if (store === null || !isOpen) return;
+		store.update(overlayId, layer, parentId);
 	}, [
-		id,
-		onDismiss,
-		enabled,
+		store,
+		isOpen,
+		overlayId,
 		layer,
-		dismissOnOverlayClick,
-		register,
-		unregister
+		parentId
 	]);
-	const overlays = context?.overlays ?? [];
-	const entry = overlays.find((e) => e.id === id);
-	if (entry) {
-		const maxZIndex = Math.max(...overlays.map((o) => o.zIndex));
-		return {
-			zIndex: entry.zIndex,
-			isTopmost: entry.zIndex === maxZIndex
+	useEffect(() => {
+		if (store !== null || !isOpen) return;
+		const handleKeyDown = (event) => {
+			if (isOverlayEscape(event)) onEscapeRef.current?.();
 		};
-	}
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [store, isOpen]);
+	const snapshot = useSyncExternalStore(store === null ? subscribeToNothing : store.subscribe, () => store === null ? null : store.getSnapshot(overlayId), getNoSnapshot);
+	if (store === null) return {
+		zIndex: OVERLAY_LAYER_TO_Z_MAP[layer],
+		isTopmost: isOpen,
+		overlayId
+	};
+	if (snapshot === null || !isOpen) return {
+		zIndex: OVERLAY_LAYER_TO_Z_MAP[layer],
+		isTopmost: false,
+		overlayId
+	};
 	return {
-		zIndex: (overlays.length > 0 ? Math.max(...overlays.map((o) => o.zIndex)) : OVERLAY_Z_INDEX_BASE - 10) + 10,
-		isTopmost: true
+		zIndex: snapshot.zIndex,
+		isTopmost: snapshot.isTopmost,
+		overlayId
 	};
-};
+}
 //#endregion
-export { useOverlay as default, useOverlay };
+export { OverlayLayer, OverlayParentContext, OverlayStoreContext, createOverlayStore, isOverlayEscape, useOverlay };