@patternmode/stacksheet 1.3.7 → 1.4.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 "use client";
 import { Portal } from "@radix-ui/react-portal";
-import { createContext, use, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { createContext, use, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { createStore, useStore } from "zustand";
 import { useShallow } from "zustand/react/shallow";
 import { springs as springs$1 } from "@howells/motion";
@@ -56,10 +56,12 @@ const DEFAULT_CONFIG = {
 	closeThreshold: .25,
 	dismissible: true,
 	drag: true,
+	handle: "inside",
 	lockScroll: true,
 	maxDepth: Number.POSITIVE_INFINITY,
 	maxWidth: "90vw",
 	modal: true,
+	repositionInputs: true,
 	scaleBackgroundAmount: .97,
 	shouldScaleBackground: false,
 	showOverlay: true,
@@ -169,38 +171,123 @@ const useViewportHeight = (active) => {
 	}, []);
 	return active ? height ?? 0 : 0;
 };
-const useBodyScale = (config, isOpen, prefersReducedMotion) => {
+/** Input types that don't summon the on-screen keyboard. */
+const NON_TEXT_INPUT_TYPES = new Set([
+	"button",
+	"checkbox",
+	"color",
+	"file",
+	"hidden",
+	"image",
+	"radio",
+	"range",
+	"reset",
+	"submit"
+]);
+/** True for elements whose focus raises the on-screen keyboard. */
+const isEditableElement = (el) => {
+	if (!(el instanceof HTMLElement)) return false;
+	if (el.isContentEditable) return true;
+	if (el instanceof HTMLTextAreaElement) return true;
+	if (el instanceof HTMLInputElement) return !NON_TEXT_INPUT_TYPES.has(el.type);
+	return false;
+};
+/**
+* Height (px) the on-screen keyboard occupies while a field inside `containerRef`
+* is focused, else `0`. Derived from the gap between the layout viewport and the
+* (keyboard-shrunk, possibly panned) visual viewport.
+*
+* Focus-gated to fields *inside the container* so unrelated `visualViewport`
+* changes — Android URL-bar collapse, or typing into the page behind a
+* non-modal sheet — don't move the sheet, and zero while pinch-zoomed since a
+* shrunk visual viewport then isn't a keyboard. rAF-throttled because iOS
+* fires many resize events over the keyboard's open animation.
+*/
+const useKeyboardInset = (active, containerRef) => {
+	const [inset, setInset] = useState(0);
 	useEffect(() => {
-		const wrapper = document.querySelector("[data-stacksheet-wrapper]");
-		const resetWrapper = () => {
-			if (wrapper instanceof HTMLElement) {
-				wrapper.style.transform = "";
-				wrapper.style.borderRadius = "";
-				wrapper.style.transition = "";
-				wrapper.style.overflow = "";
-				wrapper.style.transformOrigin = "";
-			}
+		const canListen = active && typeof window !== "undefined";
+		const container = containerRef.current;
+		const viewport = canListen ? window.visualViewport : void 0;
+		let frame = 0;
+		let scheduled = false;
+		const measure = () => {
+			const el = document.activeElement;
+			const focused = isEditableElement(el) && container !== null && container.contains(el);
+			const zoomed = (viewport?.scale ?? 1) > 1;
+			const visibleHeight = viewport?.height ?? window.innerHeight;
+			const gap = window.innerHeight - (viewport?.offsetTop ?? 0) - visibleHeight;
+			setInset(focused && !zoomed ? Math.max(0, gap) : 0);
 		};
-		const canScale = config.shouldScaleBackground && !prefersReducedMotion && wrapper instanceof HTMLElement;
-		if (canScale && isOpen) {
-			const scale = config.scaleBackgroundAmount;
-			wrapper.style.transition = "transform 500ms cubic-bezier(0.32, 0.72, 0, 1), border-radius 500ms cubic-bezier(0.32, 0.72, 0, 1)";
-			wrapper.style.transform = `scale(${scale})`;
-			wrapper.style.borderRadius = "8px";
-			wrapper.style.overflow = "hidden";
-			wrapper.style.transformOrigin = "center top";
-			return resetWrapper;
+		const schedule = () => {
+			if (scheduled) return;
+			scheduled = true;
+			frame = window.requestAnimationFrame(() => {
+				scheduled = false;
+				measure();
+			});
+		};
+		if (canListen) {
+			container?.addEventListener("focusin", schedule);
+			container?.addEventListener("focusout", schedule);
+			viewport?.addEventListener("resize", schedule, { passive: true });
+			viewport?.addEventListener("scroll", schedule, { passive: true });
+			schedule();
 		}
-		const handleEnd = () => {
-			resetWrapper();
+		return () => {
+			if (frame !== 0) window.cancelAnimationFrame(frame);
+			container?.removeEventListener("focusin", schedule);
+			container?.removeEventListener("focusout", schedule);
+			viewport?.removeEventListener("resize", schedule);
+			viewport?.removeEventListener("scroll", schedule);
 		};
-		if (canScale) {
-			wrapper.style.transform = "";
-			wrapper.style.borderRadius = "";
-			wrapper.addEventListener("transitionend", handleEnd, { once: true });
+	}, [active, containerRef]);
+	return active ? inset : 0;
+};
+const BODY_SCALE_TRANSITION = "transform 500ms cubic-bezier(0.32, 0.72, 0, 1), border-radius 500ms cubic-bezier(0.32, 0.72, 0, 1)";
+/** Fallback delay (transition duration + margin) if `transitionend` never fires. */
+const BODY_SCALE_RESET_FALLBACK_MS = 600;
+/** Cancels a pending un-scale reset when the sheet reopens mid-animation. */
+let cancelPendingBodyScaleReset;
+const useBodyScale = (config, isOpen, prefersReducedMotion) => {
+	useEffect(() => {
+		const wrapper = document.querySelector("[data-stacksheet-wrapper]");
+		const scalable = config.shouldScaleBackground && !prefersReducedMotion && wrapper instanceof HTMLElement && isOpen ? wrapper : null;
+		if (scalable !== null) {
+			cancelPendingBodyScaleReset?.();
+			scalable.style.transition = BODY_SCALE_TRANSITION;
+			scalable.style.transform = `scale(${config.scaleBackgroundAmount})`;
+			scalable.style.borderRadius = "8px";
+			scalable.style.overflow = "hidden";
+			scalable.style.transformOrigin = "center top";
 		}
 		return () => {
-			if (wrapper instanceof HTMLElement) wrapper.removeEventListener("transitionend", handleEnd);
+			if (scalable === null) return;
+			scalable.style.transition = BODY_SCALE_TRANSITION;
+			scalable.style.transform = "";
+			scalable.style.borderRadius = "";
+			const controller = new AbortController();
+			const { signal } = controller;
+			const finish = () => {
+				controller.abort();
+				cancelPendingBodyScaleReset = void 0;
+				scalable.style.transition = "";
+				scalable.style.overflow = "";
+				scalable.style.transformOrigin = "";
+			};
+			scalable.addEventListener("transitionend", (event) => {
+				if (event.target === scalable && event.propertyName === "transform") finish();
+			}, { signal });
+			const timeoutId = setTimeout(() => {
+				if (!signal.aborted) finish();
+			}, BODY_SCALE_RESET_FALLBACK_MS);
+			signal.addEventListener("abort", () => {
+				clearTimeout(timeoutId);
+			});
+			cancelPendingBodyScaleReset = () => {
+				controller.abort();
+				cancelPendingBodyScaleReset = void 0;
+			};
 		};
 	}, [
 		isOpen,
@@ -307,23 +394,22 @@ const getSnapOffset = (snapIndex, snapHeights, panelHeight) => {
 //#region src/renderer-helpers.ts
 const EMPTY_CLASSNAMES = {
 	backdrop: "",
-	header: "",
 	panel: ""
 };
 const resolveClassNames = (cn) => {
 	if (!cn) return EMPTY_CLASSNAMES;
 	return {
 		backdrop: cn.backdrop ?? "",
-		header: cn.header ?? "",
 		panel: cn.panel ?? ""
 	};
 };
-const buildAriaProps = (isTop, isModal, isComposable, ariaLabel, panelId, hasDescription) => {
+const buildAriaProps = ({ ariaLabel, hasDescription, hasTitle, isComposable, isModal, isTop, panelId }) => {
 	if (!isTop) return {};
 	const props = { role: "dialog" };
 	if (isModal) props["aria-modal"] = "true";
 	if (isComposable) {
-		props["aria-labelledby"] = `${panelId}-title`;
+		if (hasTitle) props["aria-labelledby"] = `${panelId}-title`;
+		else props["aria-label"] = ariaLabel;
 		if (hasDescription) props["aria-describedby"] = `${panelId}-desc`;
 	} else props["aria-label"] = ariaLabel;
 	return props;
@@ -345,8 +431,21 @@ const VISUAL_TWEEN = {
 const SHADOW_SM = "0px 1px 3px 0px rgba(0,0,0,0.06), 0px 6px 12px 0px rgba(0,0,0,0.06)";
 const SHADOW_LG = "0px 8px 24px 0px rgba(0,0,0,0.06), 0px 24px 48px 0px rgba(0,0,0,0.04), 0px 48px 96px 0px rgba(0,0,0,0.03)";
 const getShadow = (isNested) => isNested ? SHADOW_SM : SHADOW_LG;
-const buildPanelStyle = (panelStyles, isTop, hasPanelClass, isDragging) => ({
+/**
+* Clear the on-screen keyboard. Plain sheets stay anchored at bottom: 0 and
+* pad their content up instead — the panel surface extends under the keyboard
+* (and iOS Safari's floating URL-pill chrome), so no backdrop gap ever shows
+* between sheet and keyboard, and measurement error hides behind the keyboard.
+* Snap sheets are transform-anchored, so they lift via `bottom` (not the
+* Motion `y` transform) and keep their viewport-driven sizing untouched.
+*/
+const getKeyboardClearance = (keyboardInset, padForKeyboard) => {
+	if (keyboardInset <= 0) return {};
+	return padForKeyboard ? { paddingBottom: keyboardInset } : { bottom: keyboardInset };
+};
+const buildPanelStyle = (panelStyles, isTop, hasPanelClass, isDragging, keyboardInset, padForKeyboard) => ({
 	...panelStyles,
+	...getKeyboardClearance(keyboardInset, padForKeyboard),
 	pointerEvents: isTop ? "auto" : "none",
 	...isTop ? {} : { contain: "layout style paint" },
 	...isDragging ? { transition: "none" } : {},
@@ -504,12 +603,41 @@ const getPanelDimension = (panel, axis) => {
 	if (!panel) return 300;
 	return axis === "x" ? panel.offsetWidth : panel.offsetHeight;
 };
+/** Upper bound on retained samples — plenty for a 100ms window at 120Hz. */
+const MAX_SAMPLES = 20;
+/**
+* Append a pointer sample, pruning entries that fall outside the sliding
+* window (plus a hard cap as a memory guard). Mutates and returns `samples`.
+*/
+const appendVelocitySample = (samples, sample) => {
+	samples.push(sample);
+	const cutoff = sample.time - 100;
+	while (samples.length > MAX_SAMPLES || samples.length > 2 && (samples[0]?.time ?? 0) < cutoff) samples.shift();
+	return samples;
+};
+/**
+* Compute release velocity (px/ms, positive = dismiss direction) from the
+* samples recorded within the sliding window before `releaseTime`.
+*
+* Using only recent samples means a pause followed by a flick reports the
+* flick's velocity — not the whole-gesture average, which would dilute it
+* to near zero.
+*/
+const getReleaseVelocity = (samples, releaseTime) => {
+	const cutoff = releaseTime - 100;
+	const recent = samples.filter((sample) => sample.time >= cutoff);
+	const [first] = recent;
+	const last = recent.at(-1);
+	if (first === void 0 || last === void 0 || last.time <= first.time) return 0;
+	return (last.offset - first.offset) / (last.time - first.time);
+};
 //#endregion
 //#region src/Drag/use-drag.ts
-const resetDragRefs = ({ committedRef, offsetRef, scrollTargetRef, startRef }) => {
+const resetDragRefs = ({ committedRef, offsetRef, samplesRef, scrollTargetRef, startRef }) => {
 	startRef.current = null;
 	committedRef.current = null;
 	offsetRef.current = 0;
+	samplesRef.current = [];
 	scrollTargetRef.current = null;
 };
 const createDragHandlers = ({ axis, config, onDragUpdate, panelRef, refs, sign }) => {
@@ -524,13 +652,15 @@ const createDragHandlers = ({ axis, config, onDragUpdate, panelRef, refs, sign }
 		if (!isHandle && isInteractiveElement(target)) return;
 		refs.scrollTargetRef.current = isHandle ? null : findScrollableAncestor(target, axis);
 		refs.startRef.current = {
-			time: Date.now(),
 			x: e.clientX,
 			y: e.clientY
 		};
 		refs.committedRef.current = null;
 		refs.offsetRef.current = 0;
-		if (e.currentTarget instanceof HTMLElement) e.currentTarget.setPointerCapture(e.pointerId);
+		refs.samplesRef.current = [{
+			offset: 0,
+			time: Date.now()
+		}];
 	};
 	const handlePointerMove = (e) => {
 		if (refs.startRef.current === null) return;
@@ -544,11 +674,16 @@ const createDragHandlers = ({ axis, config, onDragUpdate, panelRef, refs, sign }
 				refs.startRef.current = null;
 				return;
 			}
+			if (e.currentTarget instanceof HTMLElement) e.currentTarget.setPointerCapture(e.pointerId);
 		}
 		if (refs.committedRef.current !== "drag") return;
 		const directional = (axis === "x" ? dx : dy) * sign;
 		const clampedOffset = directional >= 0 ? directional : -Math.sqrt(Math.abs(directional)) * RUBBER_BAND_FACTOR;
 		refs.offsetRef.current = clampedOffset;
+		appendVelocitySample(refs.samplesRef.current, {
+			offset: clampedOffset,
+			time: Date.now()
+		});
 		onDragUpdate({
 			isDragging: true,
 			offset: clampedOffset
@@ -561,8 +696,7 @@ const createDragHandlers = ({ axis, config, onDragUpdate, panelRef, refs, sign }
 			return;
 		}
 		const offset = Math.max(0, refs.offsetRef.current);
-		const elapsed = Date.now() - refs.startRef.current.time;
-		const velocity = elapsed > 0 ? offset / elapsed : 0;
+		const velocity = getReleaseVelocity(refs.samplesRef.current, Date.now());
 		resetDragRefs(refs);
 		const panelSize = getPanelDimension(panelRef.current, axis);
 		if (config.snapHeights.length > 0) {
@@ -619,6 +753,7 @@ const useDrag = (panelRef, config, onDragUpdate) => {
 	const startRef = useRef(null);
 	const committedRef = useRef(null);
 	const offsetRef = useRef(0);
+	const samplesRef = useRef([]);
 	const scrollTargetRef = useRef(null);
 	const { axis, sign } = getDismissAxis(config.side);
 	const { handlePointerCancel, handlePointerDown, handlePointerMove, handlePointerUp } = createDragHandlers({
@@ -629,6 +764,7 @@ const useDrag = (panelRef, config, onDragUpdate) => {
 		refs: {
 			committedRef,
 			offsetRef,
+			samplesRef,
 			scrollTargetRef,
 			startRef
 		},
@@ -692,6 +828,12 @@ const useSheetPanel = () => {
 //#endregion
 //#region src/stacking.ts
 /**
+* Resting height of a bottom sheet. `dvh` tracks the dynamic viewport on iOS
+* Safari (accounts for browser chrome). Shared so the keyboard-inset `calc()`
+* in `buildPanelStyle` can't drift from the panel's base height.
+*/
+const BOTTOM_SHEET_HEIGHT = "85dvh";
+/**
 * Compute visual transforms for a panel at a given depth.
 * depth=0 is the top (foreground) panel.
 * Panels beyond renderThreshold are clamped to the edge position and faded out.
@@ -768,6 +910,7 @@ const getPanelStyles = (side, config, index) => {
 	const base = {
 		display: "flex",
 		flexDirection: "column",
+		outline: "none",
 		position: "fixed",
 		transformOrigin: getTransformOrigin(side),
 		willChange: "transform",
@@ -776,9 +919,9 @@ const getPanelStyles = (side, config, index) => {
 	if (side === "bottom") return {
 		...base,
 		bottom: 0,
-		height: "85dvh",
+		height: BOTTOM_SHEET_HEIGHT,
 		left: 0,
-		maxHeight: "85dvh",
+		maxHeight: BOTTOM_SHEET_HEIGHT,
 		right: 0
 	};
 	const sideStyles = side === "right" ? {
@@ -826,34 +969,25 @@ const XIcon = () => /* @__PURE__ */ jsx("svg", {
 });
 //#endregion
 //#region src/SheetPanel/default-header.tsx
-const DefaultHeader = ({ isNested, onBack, onClose, className }) => /* @__PURE__ */ jsxs("div", {
-	className: `flex shrink-0 items-center justify-between px-4 pt-4 pb-2 ${className ?? ""}`,
-	children: [/* @__PURE__ */ jsx("div", {
-		className: "flex items-center gap-2",
-		children: isNested && /* @__PURE__ */ jsx("button", {
-			"aria-label": "Back",
-			className: "flex min-h-11 min-w-11 shrink-0 cursor-pointer items-center justify-center rounded-full border-none bg-black/5 p-0 text-inherit opacity-70 transition-opacity duration-150 hover:opacity-100",
-			onClick: onBack,
-			type: "button",
-			children: /* @__PURE__ */ jsx(ArrowLeftIcon, {})
-		})
-	}), /* @__PURE__ */ jsx("button", {
-		"aria-label": "Close",
-		className: "flex min-h-11 min-w-11 shrink-0 cursor-pointer items-center justify-center rounded-full border-none bg-black/5 p-0 text-inherit opacity-70 transition-opacity duration-150 hover:opacity-100",
-		onClick: onClose,
-		type: "button",
-		children: /* @__PURE__ */ jsx(XIcon, {})
-	})]
-});
+const DefaultHeader = ({ isNested, onBack, onClose }) => /* @__PURE__ */ jsxs(Fragment, { children: [isNested && /* @__PURE__ */ jsx("button", {
+	"aria-label": "Back",
+	className: "absolute left-2 top-2 z-20 flex min-h-11 min-w-11 cursor-pointer items-center justify-center rounded-md border-none bg-transparent p-0 text-inherit opacity-50 transition-opacity duration-150 hover:opacity-100",
+	onClick: onBack,
+	type: "button",
+	children: /* @__PURE__ */ jsx(ArrowLeftIcon, {})
+}), /* @__PURE__ */ jsx("button", {
+	"aria-label": "Close",
+	className: "absolute right-2 top-2 z-20 flex min-h-11 min-w-11 cursor-pointer items-center justify-center rounded-md border-none bg-transparent p-0 text-inherit opacity-50 transition-opacity duration-150 hover:opacity-100",
+	onClick: onClose,
+	type: "button",
+	children: /* @__PURE__ */ jsx(XIcon, {})
+})] });
 //#endregion
 //#region src/SheetPanel/sheet-panel-content.tsx
-const PanelInnerContent = ({ isComposable, shouldRender, Content, data, renderHeader, headerProps, headerClassName }) => {
+const PanelInnerContent = ({ isComposable, shouldRender, Content, data, renderHeader, headerProps }) => {
 	if (isComposable) return shouldRender && Content !== void 0 ? /* @__PURE__ */ jsx(Content, { ...data }) : null;
 	const customHeader = renderHeader !== void 0 && renderHeader !== false ? renderHeader : void 0;
-	return /* @__PURE__ */ jsxs(Fragment, { children: [customHeader === void 0 ? /* @__PURE__ */ jsx(DefaultHeader, {
-		...headerProps,
-		className: headerClassName
-	}) : customHeader(headerProps), shouldRender && Content !== void 0 && /* @__PURE__ */ jsx("div", {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [customHeader === void 0 ? /* @__PURE__ */ jsx(DefaultHeader, { ...headerProps }) : customHeader(headerProps), shouldRender && Content !== void 0 && /* @__PURE__ */ jsx("div", {
 		className: "min-h-0 flex-1 overflow-y-auto overscroll-contain",
 		"data-stacksheet-no-drag": "",
 		children: /* @__PURE__ */ jsx(Content, { ...data })
@@ -896,7 +1030,7 @@ const ModalFocusTrap = ({ enabled, active, fallbackRef, children }) => {
 				if (fallbackRef.current !== null) return fallbackRef.current;
 				return document.body;
 			},
-			initialFocus: false,
+			initialFocus: () => fallbackRef.current ?? void 0,
 			returnFocusOnDeactivate: true
 		},
 		paused,
@@ -905,9 +1039,9 @@ const ModalFocusTrap = ({ enabled, active, fallbackRef, children }) => {
 };
 //#endregion
 //#region src/SheetPanel/sheet-panel-handles.tsx
-const BottomHandle = ({ onDismiss }) => /* @__PURE__ */ jsx("button", {
+const BottomHandle = ({ onDismiss, position = "inside" }) => /* @__PURE__ */ jsx("button", {
 	"aria-label": "Dismiss",
-	className: "absolute inset-x-0 top-0 z-10 flex w-full cursor-grab touch-none items-center justify-center border-none bg-transparent pt-2.5 pb-2",
+	className: joinClassNames("absolute inset-x-0 z-10 flex w-full cursor-grab touch-none items-center justify-center border-none bg-transparent text-inherit", position === "outside" ? "bottom-full pt-1 pb-2" : "top-0 pt-2.5 pb-2"),
 	"data-stacksheet-handle": "",
 	onClick: onDismiss,
 	type: "button",
@@ -969,14 +1103,16 @@ const getHeaderProps = ({ close, isNested, pop, side }) => ({
 	onClose: close,
 	side
 });
-const getPanelContext = ({ close, hasDescription, isNested, isTop, panelId, pop, registerDescription, side }) => ({
+const getPanelContext = ({ close, hasDescription, hasTitle, isNested, isTop, panelId, pop, registerDescription, registerTitle, side }) => ({
 	back: pop,
 	close,
 	hasDescription,
+	hasTitle,
 	isNested,
 	isTop,
 	panelId,
 	registerDescription,
+	registerTitle,
 	side
 });
 const getOptionalSideHandle = ({ isHovered, onDismiss, show, side }) => show ? /* @__PURE__ */ jsx(SideHandle, {
@@ -984,7 +1120,10 @@ const getOptionalSideHandle = ({ isHovered, onDismiss, show, side }) => show ? /
 	onDismiss,
 	side
 }) : null;
-const getOptionalBottomHandle = (show, onDismiss) => show ? /* @__PURE__ */ jsx(BottomHandle, { onDismiss }) : null;
+const getOptionalBottomHandle = (show, onDismiss, position) => show ? /* @__PURE__ */ jsx(BottomHandle, {
+	onDismiss,
+	position
+}) : null;
 const completeOpeningAnimation = (hasEnteredRef, isTop, onOpenCompleteRef) => {
 	if (isTop && !hasEnteredRef.current) {
 		hasEnteredRef.current = true;
@@ -1024,28 +1163,49 @@ const useSheetPanelDrag = ({ activeSnapIndex, config, isNested, isTop, onSnap, p
 };
 const useSheetPanelContext = ({ close, isNested, isTop, pop, side }, panelId) => {
 	const [hasDescription, setHasDescription] = useState(false);
-	const registerDescription = () => {
+	const [hasTitle, setHasTitle] = useState(false);
+	const registerDescription = useCallback(() => {
 		setHasDescription(true);
 		return () => {
 			setHasDescription(false);
 		};
-	};
+	}, []);
+	const registerTitle = useCallback(() => {
+		setHasTitle(true);
+		return () => {
+			setHasTitle(false);
+		};
+	}, []);
 	return {
 		hasDescription,
-		panelContext: getPanelContext({
+		hasTitle,
+		panelContext: useMemo(() => getPanelContext({
 			close,
 			hasDescription,
+			hasTitle,
 			isNested,
 			isTop,
 			panelId,
 			pop,
 			registerDescription,
+			registerTitle,
 			side
-		})
+		}), [
+			close,
+			hasDescription,
+			hasTitle,
+			isNested,
+			isTop,
+			panelId,
+			pop,
+			registerDescription,
+			registerTitle,
+			side
+		])
 	};
 };
 const useSheetPanelModel = (props) => {
-	const { item, index, depth, isTop, isNested, side, config, classNames, pop, close, snapHeights, activeSnapIndex, layout, renderHeader, slideFrom, slideTarget, spring, stackSpring } = props;
+	const { item, index, depth, isTop, isNested, side, config, classNames, pop, close, snapHeights, keyboardInset, activeSnapIndex, layout, renderHeader, slideFrom, slideTarget, spring, stackSpring } = props;
 	const panelRef = useRef(null);
 	const [isHovered, setIsHovered] = useState(false);
 	const measuredHeight = usePanelHeight(panelRef, snapHeights.length > 0);
@@ -1055,18 +1215,27 @@ const useSheetPanelModel = (props) => {
 	const dragState = useSheetPanelDrag(props, panelRef);
 	const ariaLabel = getPanelAriaLabel(item, config.ariaLabel);
 	const panelId = `stacksheet-${item.id}`;
-	const { hasDescription, panelContext } = useSheetPanelContext(props, panelId);
+	const { hasDescription, hasTitle, panelContext } = useSheetPanelContext(props, panelId);
 	const isComposable = resolvePanelLayout(layout, renderHeader) === "composable";
 	const hasPanelClass = classNames.panel !== "";
 	const dragOffset = getDragTransform(side, dragState.offset);
-	const panelStyle = buildPanelStyle(panelStyles, isTop, hasPanelClass, dragState.isDragging);
+	const activeKeyboardInset = isTop && side === "bottom" ? keyboardInset : 0;
+	const panelStyle = buildPanelStyle(panelStyles, isTop, hasPanelClass, dragState.isDragging, activeKeyboardInset, snapHeights.length === 0);
 	const headerProps = getHeaderProps({
 		close,
 		isNested,
 		pop,
 		side
 	});
-	const ariaProps = buildAriaProps(isTop, config.modal, isComposable, ariaLabel, panelId, hasDescription);
+	const ariaProps = buildAriaProps({
+		ariaLabel,
+		hasDescription,
+		hasTitle,
+		isComposable,
+		isModal: config.modal,
+		isTop,
+		panelId
+	});
 	const transition = buildPanelTransition(dragState.isDragging, isTop, spring, stackSpring);
 	const animatedRadius = getAnimatedBorderRadius(side, depth, config.stacking);
 	const snapYOffset = computeSnapYOffset(side, snapHeights, activeSnapIndex, measuredHeight);
@@ -1074,7 +1243,7 @@ const useSheetPanelModel = (props) => {
 	const animateTarget = buildAnimateTarget(slideTarget, getStackOffset(side, transform.offset), dragOffset, transform, animatedRadius, transition, snapYOffset, isTop);
 	const initialRadius = getInitialRadius(side);
 	const showSideHandle = isTop && side !== "bottom";
-	const showBottomHandle = isTop && side === "bottom";
+	const showBottomHandle = isTop && side === "bottom" && !isComposable;
 	const dismiss = isNested ? pop : close;
 	const sideHandle = getOptionalSideHandle({
 		isHovered,
@@ -1085,7 +1254,8 @@ const useSheetPanelModel = (props) => {
 	return {
 		animateTarget,
 		ariaProps,
-		bottomHandle: getOptionalBottomHandle(showBottomHandle, dismiss),
+		bottomHandle: getOptionalBottomHandle(showBottomHandle, dismiss, config.handle),
+		bottomHandleOutside: showBottomHandle && config.handle === "outside",
 		handleAnimationComplete,
 		headerProps,
 		hoverProps: getPanelHoverProps(showSideHandle, setIsHovered),
@@ -1101,7 +1271,7 @@ const useSheetPanelModel = (props) => {
 };
 const SheetPanel = (props) => {
 	const { item, isTop, config, classNames, Content, shouldRender, renderHeader, prefersReducedMotion } = props;
-	const { animateTarget, ariaProps, bottomHandle, handleAnimationComplete, headerProps, hoverProps, inactivePanelProps, initialRadius, isComposable, panelContext, panelRef, panelStyle, resolvedSlideFrom, sideHandle } = useSheetPanelModel(props);
+	const { animateTarget, ariaProps, bottomHandle, bottomHandleOutside, handleAnimationComplete, headerProps, hoverProps, inactivePanelProps, initialRadius, isComposable, panelContext, panelRef, panelStyle, resolvedSlideFrom, sideHandle } = useSheetPanelModel(props);
 	const panelContent = /* @__PURE__ */ jsxs(m.div, {
 		animate: animateTarget,
 		className: classNames.panel || void 0,
@@ -1129,18 +1299,21 @@ const SheetPanel = (props) => {
 		...hoverProps,
 		...inactivePanelProps,
 		...ariaProps,
-		children: [sideHandle, /* @__PURE__ */ jsxs("div", {
-			className: "relative flex min-h-0 flex-1 flex-col overflow-hidden rounded-[inherit]",
-			children: [bottomHandle, /* @__PURE__ */ jsx(PanelInnerContent, {
-				Content,
-				data: item.data,
-				headerClassName: classNames.header || void 0,
-				headerProps,
-				isComposable,
-				renderHeader,
-				shouldRender
-			})]
-		})]
+		children: [
+			sideHandle,
+			bottomHandleOutside ? bottomHandle : null,
+			/* @__PURE__ */ jsxs("div", {
+				className: "relative flex min-h-0 flex-1 flex-col overflow-hidden rounded-[inherit]",
+				children: [bottomHandleOutside ? null : bottomHandle, /* @__PURE__ */ jsx(PanelInnerContent, {
+					Content,
+					data: item.data,
+					headerProps,
+					isComposable,
+					renderHeader,
+					shouldRender
+				})]
+			})
+		]
 	}, item.id);
 	return /* @__PURE__ */ jsx(SheetPanelContext.Provider, {
 		value: panelContext,
@@ -1227,6 +1400,13 @@ const useSnapState = (config, isOpen, side, stack) => {
 		snapHeights
 	};
 };
+const usePanelKeyboardInset = (config, isOpen, side) => {
+	const panelWrapperRef = useRef(null);
+	return {
+		keyboardInset: useKeyboardInset(isOpen && side === "bottom" && config.repositionInputs, panelWrapperRef),
+		panelWrapperRef
+	};
+};
 const useCloseControls = (rawClose, rawPop) => {
 	const closeReasonRef = useRef("programmatic");
 	const closeWith = (reason) => {
@@ -1275,15 +1455,14 @@ const useDismissalEffects = ({ closeReasonRef, config, isOpen, rawClose, rawPop,
 	useEffect(() => {
 		const shouldListen = isOpen && config.closeOnEscape && config.dismissible;
 		const handleKeyDown = (e) => {
-			if (e.key === "Escape") {
-				e.preventDefault();
-				dismissFromEscape({
-					closeReasonRef,
-					rawClose,
-					rawPop,
-					stackLengthRef
-				});
-			}
+			if (e.key !== "Escape" || e.defaultPrevented) return;
+			e.preventDefault();
+			dismissFromEscape({
+				closeReasonRef,
+				rawClose,
+				rawPop,
+				stackLengthRef
+			});
 		};
 		if (shouldListen) document.addEventListener("keydown", handleKeyDown);
 		return () => {
@@ -1299,7 +1478,7 @@ const useDismissalEffects = ({ closeReasonRef, config, isOpen, rawClose, rawPop,
 	]);
 	useEffect(() => {
 		const CloseWatcherConstructor = globalThis.CloseWatcher;
-		const shouldListen = isOpen && config.dismissible && CloseWatcherConstructor !== void 0;
+		const shouldListen = isOpen && config.closeOnEscape && config.dismissible && CloseWatcherConstructor !== void 0;
 		let watcher;
 		const handleClose = () => {
 			dismissFromEscape({
@@ -1321,6 +1500,7 @@ const useDismissalEffects = ({ closeReasonRef, config, isOpen, rawClose, rawPop,
 		};
 	}, [
 		isOpen,
+		config.closeOnEscape,
 		config.dismissible,
 		rawPop,
 		rawClose,
@@ -1341,6 +1521,7 @@ const SheetRenderer = ({ store, config, sheets, componentMap, classNames: classN
 	const classNames = resolveClassNames(classNamesProp);
 	const { activeSnapIndex, handleSnap, snapHeights } = useSnapState(config, isOpen, side, stack);
 	const { close, closeReasonRef, closeWith, pop, popWith } = useCloseControls(rawClose, rawPop);
+	const { panelWrapperRef, keyboardInset } = usePanelKeyboardInset(config, isOpen, side);
 	useBodyScale(config, isOpen, prefersReducedMotion);
 	useFocusRestore(isOpen);
 	useDismissalEffects({
@@ -1386,6 +1567,7 @@ const SheetRenderer = ({ store, config, sheets, componentMap, classNames: classN
 		}), /* @__PURE__ */ jsx(RemoveScroll, {
 			enabled: shouldLockScroll,
 			forwardProps: true,
+			ref: panelWrapperRef,
 			children: /* @__PURE__ */ jsx("div", {
 				className: "pointer-events-none fixed inset-0 overflow-hidden",
 				style: { zIndex: config.zIndex + 1 },
@@ -1407,6 +1589,7 @@ const SheetRenderer = ({ store, config, sheets, componentMap, classNames: classN
 							isNested,
 							isTop,
 							item,
+							keyboardInset,
 							layout,
 							onSnap: handleSnap,
 							pop,
@@ -1438,6 +1621,15 @@ const getComponentName = (component) => {
 	return name === "" ? void 0 : name;
 };
 const getNodeEnv = () => globalThis.process?.env?.NODE_ENV;
+/**
+* Generate a unique sheet id. `crypto.randomUUID` is only available in
+* secure contexts, so fall back to a timestamp + random suffix on
+* non-secure origins (e.g. plain-HTTP LAN dev servers).
+*/
+const generateSheetId = () => {
+	if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+	return `sheet-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+};
 const getStringArg = (value, name) => {
 	if (typeof value !== "string") throw new TypeError(`Expected ${name} to be a string.`);
 	return value;
@@ -1489,7 +1681,7 @@ const resolveArgs = (componentRegistry, componentMap, getNextKey, warnedNames, f
 		return {
 			ariaLabel: resolvePresentationOptions(third)?.ariaLabel,
 			data: toRecord(second),
-			id: crypto.randomUUID(),
+			id: generateSheetId(),
 			type: typeKey
 		};
 	}
@@ -1828,7 +2020,7 @@ const SheetClose = ({ asChild, className, style, children }) => {
 	const isAsChild = asChild === true;
 	return /* @__PURE__ */ jsx(isAsChild ? Slot : "button", {
 		"aria-label": children === void 0 || children === null ? "Close" : void 0,
-		className: joinClassNames(isAsChild ? void 0 : "flex min-h-11 min-w-11 shrink-0 cursor-pointer items-center justify-center rounded-md border-none bg-transparent p-0 text-inherit opacity-60 transition-opacity duration-150 hover:opacity-100", className),
+		className: joinClassNames(isAsChild ? void 0 : "absolute right-2 top-2 z-20 flex min-h-11 min-w-11 cursor-pointer items-center justify-center rounded-md border-none bg-transparent p-0 text-inherit opacity-50 transition-opacity duration-150 hover:opacity-100", className),
 		onClick: close,
 		style,
 		type: isAsChild ? void 0 : "button",
@@ -1860,7 +2052,8 @@ const SheetFooter = ({ asChild, className, style, children }) => {
 //#endregion
 //#region src/SheetParts/sheet-handle.tsx
 const SheetHandle = ({ asChild, className, style, children }) => {
-	const { close, back, isNested } = useSheetPanel();
+	const { close, back, isNested, side } = useSheetPanel();
+	if (side !== "bottom") return null;
 	const dismiss = isNested ? back : close;
 	const isAsChild = asChild === true;
 	return /* @__PURE__ */ jsx(isAsChild ? Slot : "button", {
@@ -1881,7 +2074,7 @@ const SheetHandle = ({ asChild, className, style, children }) => {
 const SheetHeader = ({ asChild, className, style, children }) => {
 	const isAsChild = asChild === true;
 	return /* @__PURE__ */ jsx(isAsChild ? Slot : "header", {
-		className: joinClassNames(isAsChild ? "shrink-0" : "flex h-14 shrink-0 items-center justify-between border-b px-6", className),
+		className: joinClassNames(isAsChild ? "shrink-0" : "flex shrink-0 items-center justify-between gap-3", className),
 		style,
 		children
 	});
@@ -1889,7 +2082,8 @@ const SheetHeader = ({ asChild, className, style, children }) => {
 //#endregion
 //#region src/SheetParts/sheet-title.tsx
 const SheetTitle = ({ asChild, className, style, children }) => {
-	const { panelId } = useSheetPanel();
+	const { panelId, registerTitle } = useSheetPanel();
+	useEffect(() => registerTitle(), [registerTitle]);
 	const isAsChild = asChild === true;
 	return /* @__PURE__ */ jsx(isAsChild ? Slot : "h2", {
 		className: joinClassNames(isAsChild ? void 0 : "font-semibold text-sm", className),