@octane-xplat/ui 0.9.0 → 0.11.0

package/dist/web/modal-focus.web.js

@@ -1,4 +1,10 @@
+import { isTopLayer, layerContains, registerLayer } from "./layer-stack.js";
+import "./layer-keys.web.js";
 //#region src/modal-focus.web.ts
+var TAB_STOP_SELECTOR = "a[href],button,input,textarea,select,[tabindex],[contenteditable=\"true\"]";
+var CLICK_TRIGGER_MAX_AGE_MS = 1e3;
+var recentClickTargets = /* @__PURE__ */ new WeakMap();
+var clickCaptureDocuments = /* @__PURE__ */ new WeakSet();
 var scopes = [];
 var originalInert = /* @__PURE__ */ new Map();
 var observer;
@@ -18,27 +24,59 @@ function updateIsolation() {
 		element.toggleAttribute("inert", inert);
 	}
 }
+function isTabStop(element) {
+	if (element.tabIndex < 0 || element.matches(":disabled") || element.closest("[inert],[hidden]")) return false;
+	for (let parent = element; parent; parent = parent.parentElement) {
+		const style = getComputedStyle(parent);
+		if (style.display === "none" || style.visibility === "hidden") return false;
+	}
+	return true;
+}
 function tabStops(panel) {
-	return Array.from(panel.querySelectorAll("a[href],button,input,textarea,select,[tabindex],[contenteditable=\"true\"]")).filter((element) => {
-		if (element.tabIndex < 0 || element.matches(":disabled") || element.closest("[inert],[hidden]")) return false;
-		for (let parent = element; parent; parent = parent.parentElement) {
-			const style = getComputedStyle(parent);
-			if (style.display === "none" || style.visibility === "hidden") return false;
+	return Array.from(panel.querySelectorAll(TAB_STOP_SELECTOR)).filter(isTabStop);
+}
+function captureClickTargets(document) {
+	if (clickCaptureDocuments.has(document)) return;
+	clickCaptureDocuments.add(document);
+	document.addEventListener("click", (event) => {
+		recentClickTargets.delete(document);
+		for (const target of event.composedPath()) {
+			if (!target || typeof target !== "object" || !("nodeType" in target) || target.nodeType !== 1) continue;
+			const element = target;
+			if (element.matches(TAB_STOP_SELECTOR) && isTabStop(element)) {
+				recentClickTargets.set(document, {
+					element,
+					at: Date.now()
+				});
+				return;
+			}
 		}
-		return true;
-	});
+	}, true);
 }
+if (typeof document !== "undefined") captureClickTargets(document);
 /** Own keyboard focus only for a modal body portal. Inert preserves the
 * background's state while hiding it from both focus and the browser AX tree. */
-function isolateModalFocus(layer, panel, dismiss) {
+function isolateModalFocus(layer, panel, dismiss, depth = scopes.length) {
 	const document = layer.ownerDocument;
+	captureClickTargets(document);
+	const recentClick = recentClickTargets.get(document);
+	const clickTrigger = recentClick && Date.now() - recentClick.at <= CLICK_TRIGGER_MAX_AGE_MS ? recentClick.element : null;
+	recentClickTargets.delete(document);
 	const scope = {
 		layer,
 		panel,
-		trigger: document.activeElement
+		trigger: clickTrigger ?? document.activeElement
 	};
 	const tabIndex = panel.getAttribute("tabindex");
 	if (tabIndex === null) panel.tabIndex = -1;
+	const token = {};
+	const removeLayer = registerLayer({
+		token,
+		depth,
+		behavior: "close",
+		dismiss,
+		contains: (target) => panel.contains(target)
+	});
 	scopes.push(scope);
 	updateIsolation();
 	(tabStops(panel)[0] ?? panel).focus({ preventScroll: true });
@@ -48,15 +86,11 @@ function isolateModalFocus(layer, panel, dismiss) {
 	}
 	const focusInside = () => (tabStops(panel)[0] ?? panel).focus({ preventScroll: true });
 	const onFocus = (event) => {
-		if (topScope() === scope && !panel.contains(event.target)) focusInside();
+		if (topScope() === scope && !panel.contains(event.target) && !layerContains(event.target)) focusInside();
 	};
 	const onKey = (event) => {
-		if (topScope() !== scope || event.isComposing || event.keyCode === 229) return;
-		if (event.key === "Escape") {
-			event.preventDefault();
-			event.stopPropagation();
-			dismiss();
-		} else if (event.key === "Tab") {
+		if (topScope() !== scope || !isTopLayer(token) || event.isComposing || event.keyCode === 229) return;
+		if (event.key === "Tab") {
 			const stops = tabStops(panel);
 			const index = stops.indexOf(document.activeElement);
 			if (!stops.length || index < 0 || (event.shiftKey ? index === 0 : index === stops.length - 1)) {
@@ -73,6 +107,7 @@ function isolateModalFocus(layer, panel, dismiss) {
 		if (index < 0) return;
 		for (const other of scopes) if (other !== scope && other.trigger && scope.layer.contains(other.trigger)) other.trigger = scope.trigger;
 		scopes.splice(index, 1);
+		removeLayer();
 		document.removeEventListener("focusin", onFocus);
 		document.removeEventListener("keydown", onKey, true);
 		if (tabIndex === null) panel.removeAttribute("tabindex");

package/dist/web/nav-contexts.js

@@ -0,0 +1,82 @@
+import { createContext, useContext } from "octane";
+//#region src/nav-contexts.ts
+/** AppShell → MobileNav/MobileNavToggle/TopNav mobile state. The default is
+*  the disabled, non-mobile value so consumers outside an AppShell behave
+*  sanely (the toggle renders nothing). */
+var defaultAppShellMobile = {
+	isMobile: false,
+	isMobileNavOpen: false,
+	toggleMobileNav: () => {},
+	openMobileNav: () => {},
+	closeMobileNav: () => {},
+	isMobileNavEnabled: false,
+	hasAutoToggle: true
+};
+var AppShellMobileContext = /* @__PURE__ */ createContext(defaultAppShellMobile);
+function useAppShellMobile() {
+	return useContext(AppShellMobileContext) ?? defaultAppShellMobile;
+}
+/** AppShell sets this so TopNav can switch between the full bar, the
+*  reduced mobile bar, and drawer rendering below the breakpoint. */
+var TopNavRenderContext = /* @__PURE__ */ createContext("default");
+function useTopNavRenderMode() {
+	return useContext(TopNavRenderContext) ?? "default";
+}
+/** Which TopNav slot an item renders in — items use it for slot-specific
+*  styling (e.g. drawer layouts stretch items full width). */
+var TopNavSlotContext = /* @__PURE__ */ createContext("start");
+function useTopNavSlot() {
+	return useContext(TopNavSlotContext) ?? "start";
+}
+/** Extra drawer content AppShell hands to TopNav's drawer render — the
+*  SideNav's items travel this way when the drawer is combined. */
+var TopNavMobileContentContext = /* @__PURE__ */ createContext(null);
+function useTopNavMobileContent() {
+	return useContext(TopNavMobileContentContext) ?? null;
+}
+/** AppShell sets this so SideNav can switch between the full sidebar, the
+*  horizontal topbar, and the two drawer renderings. */
+var SideNavRenderContext = /* @__PURE__ */ createContext("default");
+function useSideNavRenderMode() {
+	return useContext(SideNavRenderContext) ?? "default";
+}
+/** SideNav collapse state shared with collapse buttons and items. */
+var SideNavCollapseContext = /* @__PURE__ */ createContext(null);
+function useSideNavCollapse() {
+	return useContext(SideNavCollapseContext);
+}
+/** TabList → Tab/TabMenu selection contract. Throws when read outside a
+*  TabList, matching upstream. */
+var TabListContext = /* @__PURE__ */ createContext(null);
+function useTabListContext() {
+	const ctx = useContext(TabListContext);
+	if (ctx == null) throw new Error("useTabListContext must be used within TabList. Wrap your Tab/TabMenu in <TabList>.");
+	return ctx;
+}
+/** Heading-popover close callback — NavHeadingMenu reads it to dismiss the
+*  popover on item selection and Escape. */
+var NavHeadingCloseContext = /* @__PURE__ */ createContext(null);
+function useNavHeadingCloseContext() {
+	return useContext(NavHeadingCloseContext);
+}
+/** NavHeadingMenu → its items: size + the close callback. */
+var NavHeadingMenuContext = /* @__PURE__ */ createContext(null);
+function useNavHeadingMenuContext() {
+	return useContext(NavHeadingMenuContext);
+}
+/** Toolbar → family children that want the resolved size. This is the
+*  local seam standing in for Astryx's SizeContext until the shared size
+*  context lands with the forms/layout task. */
+var ToolbarSizeContext = /* @__PURE__ */ createContext(null);
+var AppShellMobileProvider = AppShellMobileContext;
+var SideNavRenderProvider = SideNavRenderContext;
+var TopNavRenderProvider = TopNavRenderContext;
+var TopNavSlotProvider = TopNavSlotContext;
+var TopNavMobileContentProvider = TopNavMobileContentContext;
+var SideNavCollapseProvider = SideNavCollapseContext;
+var NavHeadingCloseProvider = NavHeadingCloseContext;
+var NavHeadingMenuProvider = NavHeadingMenuContext;
+var TabListProvider = TabListContext;
+var ToolbarSizeProvider = ToolbarSizeContext;
+//#endregion
+export { AppShellMobileContext, AppShellMobileProvider, NavHeadingCloseContext, NavHeadingCloseProvider, NavHeadingMenuContext, NavHeadingMenuProvider, SideNavCollapseContext, SideNavCollapseProvider, SideNavRenderContext, SideNavRenderProvider, TabListContext, TabListProvider, ToolbarSizeContext, ToolbarSizeProvider, TopNavMobileContentContext, TopNavMobileContentProvider, TopNavRenderContext, TopNavRenderProvider, TopNavSlotContext, TopNavSlotProvider, useAppShellMobile, useNavHeadingCloseContext, useNavHeadingMenuContext, useSideNavCollapse, useSideNavRenderMode, useTabListContext, useTopNavMobileContent, useTopNavRenderMode, useTopNavSlot };

package/dist/web/nav-href.web.js

@@ -0,0 +1 @@
+import "./route.web.js";

package/dist/web/octane-client-build.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "buildId": "ff3183ba-911e-4372-ad13-5b2ce15c5b1b",
+  "buildId": "1c2dd44a-dfca-4434-aea5-573ac6a80e5f",
   "mode": "production",
   "capabilities": {
     "independentHydration": false

package/dist/web/outline-dom.web.tsrx.js

@@ -0,0 +1,52 @@
+import { slugify, uniqueSlug } from "./outline-utils.js";
+import { hookSlots, useEffect, useState } from "octane";
+//#region src/outline-dom.web.tsrx
+var _hs$ = /* @__PURE__ */ hookSlots(2);
+var _h$0 = /* @__PURE__ */ Symbol(_hs$);
+var _h$1 = /* @__PURE__ */ Symbol(_hs$ + 1);
+function outlineItemsFromDOM(container, selector = "h1, h2, h3, h4, h5, h6") {
+	const root = container ?? (typeof document !== "undefined" ? document : void 0);
+	if (!root) return [];
+	const nodes = root.querySelectorAll(selector);
+	const counts = /* @__PURE__ */ new Map();
+	const items = [];
+	for (const node of nodes) {
+		const el = node;
+		const level = Number(el.tagName?.slice(1)) || 2;
+		const label = (el.innerText ?? el.textContent ?? "").trim();
+		if (!label) continue;
+		const id = el.id || uniqueSlug(slugify(label), counts);
+		items.push({
+			id,
+			label,
+			level
+		});
+	}
+	return items;
+}
+function useOutlineFromDOM(containerRef, options) {
+	const [items, setItems] = useState([], _h$0);
+	const resolve = () => {
+		return (containerRef && typeof containerRef === "object" && "current" in containerRef ? containerRef.current : containerRef) ?? options?.root ?? (typeof document !== "undefined" ? document : null);
+	};
+	useEffect(() => {
+		const refresh = () => setItems(outlineItemsFromDOM(resolve(), options?.selector));
+		refresh();
+		const root = resolve();
+		const observer = new MutationObserver(refresh);
+		if (root) observer.observe(root, {
+			childList: true,
+			subtree: true,
+			characterData: true
+		});
+		else if (typeof document !== "undefined") observer.observe(document.body, {
+			childList: true,
+			subtree: true,
+			characterData: true
+		});
+		return () => observer.disconnect();
+	}, [options?.selector], _h$1);
+	return items;
+}
+//#endregion
+export { outlineItemsFromDOM, useOutlineFromDOM };

package/dist/web/outline-hooks.tsrx.js

@@ -0,0 +1,17 @@
+import { outlineFromDoc, parseOutlineFromMarkdown } from "./outline-utils.js";
+import { hookSlots } from "octane";
+import { memoPublish, memoSlot, memoTake1 } from "octane/internal/client";
+//#region src/outline-hooks.tsrx
+var _hs$ = /* @__PURE__ */ hookSlots(2);
+var _h$0 = /* @__PURE__ */ Symbol(_hs$);
+var _h$1 = /* @__PURE__ */ Symbol(_hs$ + 1);
+function useOutlineFromMarkdown(markdown) {
+	let __hks, __hkd0, __hke;
+	return __hkd0 = markdown, __hks = memoSlot(_h$0, "useMemo"), __hke = memoTake1(__hks, __hkd0), __hke === null ? memoPublish(__hks, parseOutlineFromMarkdown(markdown), __hkd0) : __hke.value;
+}
+function useOutlineFromDoc(doc) {
+	let __hks$, __hkd0$, __hke$;
+	return __hkd0$ = doc, __hks$ = memoSlot(_h$1, "useMemo"), __hke$ = memoTake1(__hks$, __hkd0$), __hke$ === null ? memoPublish(__hks$, outlineFromDoc(doc), __hkd0$) : __hke$.value;
+}
+//#endregion
+export { useOutlineFromDoc, useOutlineFromMarkdown };

package/dist/web/outline-utils.js

@@ -0,0 +1,122 @@
+//#region src/outline-utils.ts
+/** Slug a heading label the same way upstream's parser does: lowercase,
+*  quotes dropped, non-alphanumerics collapse to '-', edges trimmed. */
+function slugify(value) {
+	return value.trim().toLowerCase().replace(/['"]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/** Disambiguate repeated slugs with a numeric suffix (`setup`, `setup-1`, …).
+*  Empty slugs fall back to `section`. The caller owns the counts map. */
+function uniqueSlug(baseSlug, counts) {
+	const fallbackSlug = baseSlug || "section";
+	const count = counts.get(fallbackSlug) ?? 0;
+	counts.set(fallbackSlug, count + 1);
+	return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`;
+}
+var FENCE = /^(?:`{3,}|~{3,})/;
+var ATX = /^ {0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+var SETEXT_H1 = /^ {0,3}=+[ \t]*$/;
+var SETEXT_H2 = /^ {0,3}-+[ \t]*$/;
+var BLANK = /^\s*$/;
+/** Strip the inline constructs the local Markdown AST supports (code spans,
+*  emphasis, links, images, escapes), leaving the visible text — matching
+*  what `markdownAstText` produces upstream. */
+function inlineMarkdownText(source) {
+	let text = source;
+	text = text.replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1");
+	text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+	text = text.replace(/`([^`]*)`/g, "$1");
+	text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+	text = text.replace(/__([^_]+)__/g, "$1");
+	text = text.replace(/\*([^*]+)\*/g, "$1");
+	text = text.replace(/\b_([^_]+)_\b/g, "$1");
+	text = text.replace(/~~([^~]+)~~/g, "$1");
+	text = text.replace(/\\([\\`*{}[\]()#+\-.!_>~])/g, "$1");
+	text = text.replace(/<[^>]+>/g, "");
+	return text.trim();
+}
+/**
+* Scan markdown source for headings. Not a general parser — it exists to
+* produce outline labels that agree with what the Markdown component renders
+* for the same source. Fenced code blocks (```/~~~) and 4-space-indented
+* lines are never headings; Setext underlines promote the previous
+* non-blank line.
+*/
+function markdownHeadings(markdown) {
+	const headings = [];
+	const lines = markdown.split("\n");
+	let fenced = false;
+	let fenceMarker = "";
+	let previousTextLine = "";
+	for (const line of lines) {
+		const fenceMatch = line.match(FENCE);
+		if (fenceMatch) {
+			if (!fenced) {
+				fenced = true;
+				fenceMarker = fenceMatch[0][0];
+			} else if (fenceMatch[0][0] === fenceMarker) fenced = false;
+			previousTextLine = "";
+			continue;
+		}
+		if (fenced) continue;
+		const atx = line.match(ATX);
+		if (atx) {
+			headings.push({
+				label: inlineMarkdownText(atx[2]),
+				level: atx[1].length
+			});
+			previousTextLine = "";
+			continue;
+		}
+		if (SETEXT_H1.test(line) || SETEXT_H2.test(line)) {
+			if (!BLANK.test(previousTextLine)) {
+				headings.push({
+					label: inlineMarkdownText(previousTextLine.trim()),
+					level: line.includes("=") ? 1 : 2
+				});
+				previousTextLine = "";
+				continue;
+			}
+		}
+		previousTextLine = /^ {4}/.test(line) ? "" : line;
+	}
+	return headings;
+}
+/**
+* Extract outline items from a Markdown string: heading text becomes the
+* label, its slug (with per-document dedup) becomes the id. For
+* `useOutlineFromMarkdown` parity on MdDoc-shaped data see
+* {@link outlineFromDoc}.
+*/
+function parseOutlineFromMarkdown(markdown) {
+	const counts = /* @__PURE__ */ new Map();
+	return markdownHeadings(markdown).filter((heading) => heading.label !== "").map((heading) => ({
+		id: uniqueSlug(slugify(heading.label), counts),
+		label: heading.label,
+		level: heading.level
+	}));
+}
+function inlineNodesText(nodes) {
+	let out = "";
+	for (const node of nodes ?? []) out += node.t === "text" || node.t === "code" ? node.text : node.t === "link" ? node.text : inlineNodesText(node.children);
+	return out;
+}
+/** Outline items from a baked `MdDoc` (the AST `xplat routes` produces and
+*  the `Markdown` component renders) — the portable equivalent of deriving
+*  an outline from rendered markdown content. */
+function outlineFromDoc(doc) {
+	const counts = /* @__PURE__ */ new Map();
+	const items = [];
+	for (const node of doc.children ?? []) {
+		if (node.t !== "h") continue;
+		const label = inlineNodesText(node.children).trim();
+		if (!label) continue;
+		items.push({
+			id: uniqueSlug(slugify(label), counts),
+			label,
+			level: node.depth
+		});
+	}
+	return items;
+}
+//#endregion
+export { inlineMarkdownText, markdownHeadings, outlineFromDoc, parseOutlineFromMarkdown, slugify, uniqueSlug };

package/dist/web/overflow-math.js

@@ -0,0 +1,126 @@
+//#region src/overflow-math.ts
+function clamp(value, min, max) {
+	return Math.max(Math.min(value, max), min);
+}
+/** Resolve the ceiling and floor into a single [floor, ceiling] pair.
+*  `maxVisibleItems` is clamped to itemCount; when max < min the floor wins
+*  via the final clamp (the hook/dev side warns). */
+function resolveBounds(itemCount, minVisibleItems, maxVisibleItems) {
+	return {
+		floor: Math.max(0, Math.min(minVisibleItems, itemCount)),
+		ceiling: Math.max(0, Math.min(maxVisibleItems == null ? itemCount : maxVisibleItems, itemCount))
+	};
+}
+/** Single-line greedy fit — each non-final admitted item reserves indicator
+*  space so the indicator fits once anything overflows. */
+function computeSingleLineFit(orderedWidths, gap, availableWidth, indicatorWidth, floor, ceiling) {
+	let totalWidth = 0;
+	let count = 0;
+	for (let i = 0; i < orderedWidths.length; i++) {
+		if (count >= ceiling) break;
+		const itemWidth = orderedWidths[i];
+		const gapWidth = i > 0 ? gap : 0;
+		const candidateWidth = totalWidth + itemWidth + gapWidth;
+		if (candidateWidth + (i === orderedWidths.length - 1 ? 0 : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0)) > availableWidth && count >= floor) break;
+		totalWidth = candidateWidth;
+		count++;
+	}
+	return count;
+}
+/** Pack items into rows, wrapping when the next item would exceed
+*  `availableWidth`. On the last allowed row, keep `indicatorReserve` px free
+*  so the overflow indicator fits. */
+function packRows(orderedWidths, gap, availableWidth, indicatorReserve, maxRows) {
+	let placed = 0;
+	let row = 1;
+	let rowWidth = 0;
+	for (let i = 0; i < orderedWidths.length; i++) {
+		const w = orderedWidths[i];
+		const isFirstInRow = rowWidth === 0;
+		const candidate = isFirstInRow ? w : rowWidth + gap + w;
+		const onLastRow = row === maxRows;
+		const reserve = onLastRow && indicatorReserve > 0 ? indicatorReserve + gap : 0;
+		if (candidate + reserve <= availableWidth) {
+			rowWidth = candidate;
+			placed++;
+			continue;
+		}
+		if (isFirstInRow) {
+			if (onLastRow && reserve > 0) break;
+			rowWidth = candidate;
+			placed++;
+			continue;
+		}
+		if (row >= maxRows) break;
+		row++;
+		rowWidth = 0;
+		i--;
+	}
+	return {
+		placed,
+		rows: row
+	};
+}
+/** Count how many rows a set of items occupies when wrapped at availableWidth. */
+function countRows(orderedWidths, gap, availableWidth) {
+	if (orderedWidths.length === 0) return 0;
+	let rows = 1;
+	let rowWidth = 0;
+	for (let i = 0; i < orderedWidths.length; i++) {
+		const w = orderedWidths[i];
+		const isFirstInRow = rowWidth === 0;
+		const candidate = isFirstInRow ? w : rowWidth + gap + w;
+		if (candidate <= availableWidth || isFirstInRow) rowWidth = candidate;
+		else {
+			rows++;
+			rowWidth = w;
+		}
+	}
+	return rows;
+}
+/** Multi-row packing: admit items until a new item would require a row beyond
+*  maxRows, reserving indicator space on the final row when items overflow. */
+function computeMultiRowFit(orderedWidths, gap, availableWidth, indicatorWidth, maxRows) {
+	const n = orderedWidths.length;
+	if (n === 0) return {
+		count: 0,
+		rows: 0
+	};
+	const packAll = packRows(orderedWidths, gap, availableWidth, 0, maxRows);
+	if (packAll.placed === n) return {
+		count: n,
+		rows: packAll.rows
+	};
+	const count = packRows(orderedWidths, gap, availableWidth, indicatorWidth, maxRows).placed;
+	const rows = countRows(orderedWidths.slice(0, count), gap, availableWidth);
+	return {
+		count,
+		rows: Math.max(count > 0 ? 1 : 0, rows)
+	};
+}
+function computeOverflow(input) {
+	const { widths, gap, availableWidth, indicatorWidth, minVisibleItems, maxVisibleItems, maxRows, collapseFrom } = input;
+	const itemCount = widths.length;
+	if (itemCount === 0) return {
+		visibleCount: 0,
+		rows: 0
+	};
+	const { floor, ceiling } = resolveBounds(itemCount, minVisibleItems, maxVisibleItems);
+	const ordered = collapseFrom === "start" ? [...widths].reverse() : widths;
+	if (!(maxRows != null && maxRows > 1)) {
+		const visibleCount = clamp(computeSingleLineFit(ordered, gap, availableWidth, indicatorWidth, floor, ceiling), floor, ceiling);
+		return {
+			visibleCount,
+			rows: visibleCount > 0 ? 1 : 0
+		};
+	}
+	const { count, rows } = computeMultiRowFit(ordered, gap, availableWidth, indicatorWidth, maxRows);
+	const visibleCount = clamp(count, floor, ceiling);
+	const resolvedRows = visibleCount === count ? rows : countRows(ordered.slice(0, visibleCount), gap, availableWidth);
+	return {
+		visibleCount,
+		rows: visibleCount > 0 ? Math.max(1, resolvedRows) : 0
+	};
+}
+//#endregion
+export { computeOverflow };

package/dist/web/popover-position.js

@@ -5,25 +5,32 @@ var opposite = {
 	left: "right",
 	right: "left"
 };
-/** Place beside the anchor, flip once when the requested side overflows, then clamp. */
-function positionPopover(anchor, panel, viewport, requested = "bottom", gap = 8) {
+/** Place beside the anchor, flip once when the requested side overflows,
+*  then clamp. `alignment` positions along the cross axis — 'start' keeps
+*  the panel's start edge flush with the anchor's (the historical
+*  behavior), 'center' centers, 'end' aligns the end edges. */
+function positionPopover(anchor, panel, viewport, requested = "bottom", gap = 8, alignment = "start") {
+	const align = (placement) => {
+		if (placement === "top" || placement === "bottom") return alignment === "center" ? anchor.left + (anchor.width - panel.width) / 2 : alignment === "end" ? anchor.left + anchor.width - panel.width : anchor.left;
+		return alignment === "center" ? anchor.top + (anchor.height - panel.height) / 2 : alignment === "end" ? anchor.top + anchor.height - panel.height : anchor.top;
+	};
 	const at = (placement) => {
 		switch (placement) {
 			case "top": return {
-				left: anchor.left,
+				left: align(placement),
 				top: anchor.top - panel.height - gap
 			};
 			case "bottom": return {
-				left: anchor.left,
+				left: align(placement),
 				top: anchor.top + anchor.height + gap
 			};
 			case "left": return {
 				left: anchor.left - panel.width - gap,
-				top: anchor.top
+				top: align(placement)
 			};
 			case "right": return {
 				left: anchor.left + anchor.width + gap,
-				top: anchor.top
+				top: align(placement)
 			};
 		}
 		throw new Error(`Unknown popover placement: ${placement}`);
@@ -40,5 +47,23 @@ function positionPopover(anchor, panel, viewport, requested = "bottom", gap = 8)
 		placement
 	};
 }
+/** Resolve a `useLayer` placement — logical (`above`/`below`/`start`/`end`)
+*  or physical — to a physical side for `positionPopover`. `rtl` mirrors the
+*  logical inline sides. */
+function resolveLayerSide(placement, rtl = false) {
+	switch (placement) {
+		case "below":
+		case "bottom": return "bottom";
+		case "start": return rtl ? "right" : "left";
+		case "end": return rtl ? "left" : "right";
+		case "left":
+		case "right": return placement;
+		default: return "top";
+	}
+}
+/** Horizontal cross-axis alignment follows the anchor's inline direction. */
+function resolveLayerAlignment(alignment = "center", side, rtl = false) {
+	return rtl && (side === "top" || side === "bottom") && alignment !== "center" ? alignment === "start" ? "end" : "start" : alignment;
+}
 //#endregion
-export { positionPopover };
+export { positionPopover, resolveLayerAlignment, resolveLayerSide };