@dreamtree-org/twreact-ui 1.3.11 → 2.0.0

package/dist/esm/components/rich-text/RichTextToolbar.js

@@ -4,6 +4,7 @@ import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React, { useState, useRef, useEffect } from 'react';
 import { Redo, Undo, Link, SquareCode, Quote, ListOrdered, List, Heading3, Heading2, Heading1, Code, Strikethrough, Italic, Bold } from 'lucide-react';
 import { cn } from '../../utils/cn.js';
+import { TOUCH_TARGET } from '../../utils/touchTarget.js';
 
 var isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform || "");
 var shortcutLabel = function shortcutLabel(keys) {
@@ -285,9 +286,23 @@ function LinkForm(_ref) {
   });
 }
 var formButton = "h-8 rounded-md px-2 text-sm font-medium text-gray-700 hover:bg-gray-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 dark:text-gray-200 dark:hover:bg-gray-800";
+// Keeps the editor selection when a toolbar button is pressed. `pointerdown`
+// covers touch and pen (iOS drops the selection on a plain tap otherwise);
+// `mousedown` stays for desktop browsers that move focus on mousedown even
+// when pointerdown was cancelled.
+var keepSelection = function keepSelection(e) {
+  return e.preventDefault();
+};
+/** `top` offset for a sticky toolbar: `true` → 0, a number → px, a string → any CSS length. */
+function stickyTop(sticky) {
+  if (typeof sticky === "number") return "".concat(sticky, "px");
+  if (typeof sticky === "string" && sticky) return sticky;
+  return "0px";
+}
 /**
  * A WAI-ARIA toolbar: one tab stop, arrow keys / Home / End move between the
- * buttons (roving tabindex), toggles report `aria-pressed`.
+ * buttons (roving tabindex), toggles report `aria-pressed`. With `sticky` it
+ * stays pinned to the top of the scrolling page while the content scrolls.
  */
 function RichTextToolbar(_ref2) {
   var editor = _ref2.editor,
@@ -296,7 +311,9 @@ function RichTextToolbar(_ref2) {
     disabled = _ref2.disabled,
     controlsId = _ref2.controlsId,
     _ref2$label = _ref2.label,
-    label = _ref2$label === void 0 ? "Formatting" : _ref2$label;
+    label = _ref2$label === void 0 ? "Formatting" : _ref2$label,
+    _ref2$sticky = _ref2.sticky,
+    sticky = _ref2$sticky === void 0 ? false : _ref2$sticky;
   var _useState5 = useState(0),
     _useState6 = _slicedToArray(_useState5, 2),
     focusIndex = _useState6[0],
@@ -345,7 +362,11 @@ function RichTextToolbar(_ref2) {
       "aria-controls": controlsId,
       "aria-orientation": "horizontal",
       onKeyDown: onKeyDown,
-      className: "flex flex-wrap items-center gap-0.5 border-b border-gray-200 bg-gray-50 px-1 py-1 dark:border-gray-700 dark:bg-gray-800/60",
+      "data-sticky": sticky ? "" : undefined,
+      style: sticky ? {
+        top: stickyTop(sticky)
+      } : undefined,
+      className: cn("flex flex-wrap items-center gap-0.5 border-b border-line bg-background px-1 py-1", sticky && "sticky z-sticky"),
       children: keys.map(function (key, i) {
         var item = TOOLBAR_ITEMS[key];
         var Icon = item.icon;
@@ -354,7 +375,7 @@ function RichTextToolbar(_ref2) {
         var newGroup = i > 0 && TOOLBAR_ITEMS[keys[i - 1]].group !== item.group;
         return jsxs(React.Fragment, {
           children: [newGroup && jsx("span", {
-            className: "mx-1 h-5 w-px bg-gray-300 dark:bg-gray-600",
+            className: "mx-1 h-5 w-px bg-line",
             "aria-hidden": "true"
           }), jsx("button", {
             ref: function ref(node) {
@@ -371,13 +392,12 @@ function RichTextToolbar(_ref2) {
             onFocus: function onFocus() {
               return setFocusIndex(i);
             },
-            onMouseDown: function onMouseDown(e) {
-              return e.preventDefault();
-            },
+            onPointerDown: keepSelection,
+            onMouseDown: keepSelection,
             onClick: function onClick() {
               return activate(key);
             },
-            className: cn("inline-flex h-8 w-8 items-center justify-center rounded-md text-gray-600 transition-colors", "hover:bg-gray-200 hover:text-gray-900 dark:text-gray-300 dark:hover:bg-gray-700 dark:hover:text-gray-100", "focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500", "disabled:cursor-not-allowed disabled:opacity-50", pressed && "bg-primary-100 text-primary-700 dark:bg-primary-900/40 dark:text-primary-300", unavailable && "opacity-40"),
+            className: cn("inline-flex h-8 w-8 items-center justify-center rounded-md text-muted transition-colors duration-fast motion-reduce:transition-none", TOUCH_TARGET, "hover:bg-muted/10 hover:text-foreground", "focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500", "disabled:cursor-not-allowed disabled:opacity-50", pressed && "bg-primary-100 text-primary-700 dark:bg-primary-900/40 dark:text-primary-300", unavailable && "opacity-40"),
             children: jsx(Icon, {
               className: "h-4 w-4",
               "aria-hidden": "true"
@@ -394,4 +414,4 @@ function RichTextToolbar(_ref2) {
   });
 }
 
-export { DEFAULT_TOOLBAR, RichTextToolbar, TOOLBAR_ITEMS, normalizeUrl, selectToolbarState };
+export { DEFAULT_TOOLBAR, RichTextToolbar, TOOLBAR_ITEMS, normalizeUrl, selectToolbarState, stickyTop };

package/dist/esm/components/utility/Portal.js

@@ -0,0 +1,31 @@
+'use client';
+import { useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
+
+/**
+ * Internal (not exported). Renders `children` into `container` (default
+ * `document.body`). Renders nothing on the server and on the first client
+ * render, so hydration matches; the portal appears right after mount.
+ *
+ * @param {{ container?: Element | null, children?: React.ReactNode }} props
+ */
+var subscribe = function subscribe() {
+  return function () {};
+};
+var getClientSnapshot = function getClientSnapshot() {
+  return true;
+};
+var getServerSnapshot = function getServerSnapshot() {
+  return false;
+};
+function Portal(_ref) {
+  var container = _ref.container,
+    children = _ref.children;
+  // false on the server and during hydration, true on the client after it.
+  var mounted = useSyncExternalStore(subscribe, getClientSnapshot, getServerSnapshot);
+  if (!mounted || typeof document === "undefined") return null;
+  var target = container || document.body;
+  return target ? /*#__PURE__*/createPortal(children, target) : null;
+}
+
+export { Portal as default };

package/dist/esm/components/utility/PullToRefresh.js

@@ -0,0 +1,229 @@
+'use client';
+import { objectWithoutProperties as _objectWithoutProperties, slicedToArray as _slicedToArray, objectSpread2 as _objectSpread2 } from '../../_virtual/_rollupPluginBabelHelpers.js';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { forwardRef, useState, useRef, useEffect } from 'react';
+import { RefreshCw } from 'lucide-react';
+import { cn } from '../../utils/cn.js';
+import { useLatestRef } from '../../hooks/useLatestRef.js';
+import { useReducedMotion } from '../../hooks/useReducedMotion.js';
+
+var _excluded = ["onRefresh", "threshold", "maxPull", "disabled", "refreshingLabel", "scrollRef", "className", "contentClassName", "children"];
+// Touch pull-to-refresh around a scroll container (DTUI-56). The gesture only
+// starts while the scroller sits at scrollTop 0 and the finger moves down, so
+// normal scrolling is never intercepted. The page itself keeps the global
+// `overscroll-behavior-y: none` baseline, so the browser's own pull-to-refresh
+// does not fight this one.
+var INDICATOR_SIZE = 40;
+// Rubber-band resistance: 1:1 at first, asymptotic to `max`.
+function resist(distance, max) {
+  if (distance <= 0 || max <= 0) return 0;
+  return max * (1 - 1 / (distance / max + 1));
+}
+var PullToRefresh = /*#__PURE__*/forwardRef(function PullToRefresh(_ref, ref) {
+  var onRefresh = _ref.onRefresh,
+    _ref$threshold = _ref.threshold,
+    threshold = _ref$threshold === void 0 ? 64 : _ref$threshold,
+    maxPull = _ref.maxPull,
+    _ref$disabled = _ref.disabled,
+    disabled = _ref$disabled === void 0 ? false : _ref$disabled,
+    _ref$refreshingLabel = _ref.refreshingLabel,
+    refreshingLabel = _ref$refreshingLabel === void 0 ? "Refreshing…" : _ref$refreshingLabel,
+    scrollRef = _ref.scrollRef,
+    className = _ref.className,
+    contentClassName = _ref.contentClassName,
+    children = _ref.children,
+    rest = _objectWithoutProperties(_ref, _excluded);
+  var limit = Math.max(threshold, maxPull !== null && maxPull !== void 0 ? maxPull : threshold * 2);
+  var reducedMotion = useReducedMotion();
+  var _useState = useState(null),
+    _useState2 = _slicedToArray(_useState, 2),
+    scrollEl = _useState2[0],
+    setScrollEl = _useState2[1];
+  var _useState3 = useState(0),
+    _useState4 = _slicedToArray(_useState3, 2),
+    pull = _useState4[0],
+    setPull = _useState4[1];
+  var _useState5 = useState(false),
+    _useState6 = _slicedToArray(_useState5, 2),
+    dragging = _useState6[0],
+    setDragging = _useState6[1];
+  var _useState7 = useState(false),
+    _useState8 = _slicedToArray(_useState7, 2),
+    refreshing = _useState8[0],
+    setRefreshing = _useState8[1];
+  var gesture = useRef(null);
+  var pullRef = useRef(0);
+  var busy = useRef(false);
+  var mounted = useRef(true);
+  var config = useLatestRef({
+    onRefresh: onRefresh,
+    threshold: threshold,
+    limit: limit,
+    disabled: disabled
+  });
+  useEffect(function () {
+    mounted.current = true;
+    return function () {
+      mounted.current = false;
+    };
+  }, []);
+  useEffect(function () {
+    var el = scrollRef ? scrollRef.current : scrollEl;
+    if (!el || disabled) return undefined;
+    var setDistance = function setDistance(value) {
+      pullRef.current = value;
+      setPull(value);
+    };
+    var settle = function settle() {
+      busy.current = false;
+      if (!mounted.current) return;
+      setRefreshing(false);
+      setDistance(0);
+    };
+    var startRefresh = function startRefresh() {
+      busy.current = true;
+      setRefreshing(true);
+      setDistance(config.current.threshold);
+      // A sync throw or a rejection retracts the indicator too; onRefresh owns its errors.
+      new Promise(function (resolve) {
+        var _config$current$onRef, _config$current;
+        return resolve((_config$current$onRef = (_config$current = config.current).onRefresh) === null || _config$current$onRef === void 0 ? void 0 : _config$current$onRef.call(_config$current));
+      }).then(settle, settle);
+    };
+    var begin = function begin(touch) {
+      gesture.current = {
+        x: touch.clientX,
+        y: touch.clientY,
+        axis: null
+      };
+    };
+    var onTouchStart = function onTouchStart(e) {
+      gesture.current = null;
+      if (busy.current || e.touches.length !== 1 || el.scrollTop > 0) return;
+      begin(e.touches[0]);
+    };
+    var onTouchMove = function onTouchMove(e) {
+      if (busy.current || e.touches.length !== 1) return;
+      var touch = e.touches[0];
+      // A scroll that returns to the top mid-gesture can still pull from there.
+      if (!gesture.current) {
+        if (el.scrollTop > 0) return;
+        begin(touch);
+        return;
+      }
+      var g = gesture.current;
+      var dy = touch.clientY - g.y;
+      if (!g.axis) {
+        var dx = touch.clientX - g.x;
+        if (Math.abs(dx) < 4 && Math.abs(dy) < 4) return;
+        g.axis = Math.abs(dx) > Math.abs(dy) || dy < 0 || el.scrollTop > 0 ? "none" : "pull";
+        if (g.axis === "pull") setDragging(true);
+      }
+      if (g.axis !== "pull") return;
+      if (el.scrollTop > 0) {
+        // The user pushed back up and scrolled the content: hand the gesture back.
+        g.axis = "none";
+        setDragging(false);
+        setDistance(0);
+        return;
+      }
+      if (dy <= 0) {
+        setDistance(0);
+        return;
+      }
+      // Only now, mid-pull at the top, keep the browser from also panning.
+      if (e.cancelable) e.preventDefault();
+      setDistance(resist(dy, config.current.limit));
+    };
+    var finish = function finish(commit) {
+      var g = gesture.current;
+      gesture.current = null;
+      if (!g || g.axis !== "pull") return;
+      setDragging(false);
+      if (commit && pullRef.current >= config.current.threshold) startRefresh();else setDistance(0);
+    };
+    var onTouchEnd = function onTouchEnd() {
+      return finish(true);
+    };
+    var onTouchCancel = function onTouchCancel() {
+      return finish(false);
+    };
+    // touchmove must be non-passive to stop the pan while pulling; the rest stay passive.
+    el.addEventListener("touchstart", onTouchStart, {
+      passive: true
+    });
+    el.addEventListener("touchmove", onTouchMove, {
+      passive: false
+    });
+    el.addEventListener("touchend", onTouchEnd, {
+      passive: true
+    });
+    el.addEventListener("touchcancel", onTouchCancel, {
+      passive: true
+    });
+    return function () {
+      gesture.current = null;
+      el.removeEventListener("touchstart", onTouchStart);
+      el.removeEventListener("touchmove", onTouchMove);
+      el.removeEventListener("touchend", onTouchEnd);
+      el.removeEventListener("touchcancel", onTouchCancel);
+    };
+  }, [scrollRef, scrollEl, disabled, config]);
+  // A pull left half-way when `disabled` flips on is dropped (a refresh in flight still shows).
+  var distance = disabled && !refreshing ? 0 : pull;
+  var progress = Math.min(1, distance / threshold);
+  var armed = refreshing || distance >= threshold;
+  var animate = !dragging && !reducedMotion;
+  var transition = animate ? "transition-transform duration-base ease-standard motion-reduce:transition-none" : "";
+  var contentStyle = distance > 0 ? {
+    transform: "translateY(".concat(distance, "px)")
+  } : undefined;
+  var indicatorStyle = {
+    transform: "translateY(".concat(distance - INDICATOR_SIZE, "px)"),
+    opacity: refreshing ? 1 : progress
+  };
+  var iconStyle = reducedMotion || refreshing ? undefined : {
+    transform: "rotate(".concat(Math.round(progress * 270), "deg)")
+  };
+  var contentProps = {
+    className: cn(scrollRef ? "h-full" : "h-full overflow-y-auto overscroll-y-contain", transition, contentClassName),
+    style: contentStyle,
+    "aria-busy": refreshing || undefined,
+    "data-ptr-content": ""
+  };
+  return jsxs("div", _objectSpread2(_objectSpread2({
+    ref: ref,
+    className: cn("relative overflow-hidden", className),
+    "data-state": refreshing ? "refreshing" : distance > 0 ? "pulling" : "idle"
+  }, rest), {}, {
+    children: [jsx("div", {
+      "aria-hidden": "true",
+      "data-ptr-indicator": "",
+      className: cn("pointer-events-none absolute inset-x-0 top-0 z-10 flex justify-center", transition),
+      style: indicatorStyle,
+      children: jsx("span", {
+        className: cn("flex h-10 w-10 items-center justify-center rounded-full border border-line bg-surface shadow-sm", armed ? "text-primary-600 dark:text-primary-400" : "text-muted"),
+        children: jsx(RefreshCw, {
+          className: cn("h-5 w-5", refreshing && !reducedMotion && "animate-spin motion-reduce:animate-none"),
+          style: iconStyle,
+          "aria-hidden": "true",
+          "data-ptr-spinner": ""
+        })
+      })
+    }), jsx("div", {
+      role: "status",
+      "aria-live": "polite",
+      className: "sr-only",
+      children: refreshing ? refreshingLabel : ""
+    }), scrollRef ? jsx("div", _objectSpread2(_objectSpread2({}, contentProps), {}, {
+      children: children
+    })) : jsx("div", _objectSpread2(_objectSpread2({
+      ref: setScrollEl
+    }, contentProps), {}, {
+      children: children
+    }))]
+  }));
+});
+PullToRefresh.displayName = "PullToRefresh";
+
+export { PullToRefresh as default, resist };

package/dist/esm/hooks/useFloatingPosition.js

@@ -0,0 +1,82 @@
+import { offset, flip, shift, size, useFloating, autoUpdate } from '@floating-ui/react-dom';
+
+// Internal (not exported). One positioning engine for every anchored overlay
+// (Popover, Select, Tooltip, Tour, …), replacing the hand-rolled
+// `utils/position.js`.
+var SHIFT_PADDING = 8;
+var MIN_FIT_HEIGHT = 80; // px; never squeeze a capped floating element below this
+/**
+ * Positions a floating element next to a reference element.
+ *
+ * @param {object} [options]
+ * @param {import('@floating-ui/react-dom').Placement} [options.placement='bottom-start']
+ * @param {number} [options.offset=4] - gap in px between reference and floating.
+ * @param {boolean} [options.flip=true] - flip to the opposite side when out of room.
+ * @param {boolean} [options.shift=true] - slide along the axis to stay in view (8px padding).
+ * @param {boolean|'exact'} [options.matchWidth=false] - `true` sets the floating
+ *   element's min-width to the reference's width (listboxes, comboboxes);
+ *   `'exact'` sets its width too.
+ * @param {number} [options.maxHeight] - px cap on the floating element's
+ *   height; it also shrinks to the space left on its side (min 80px).
+ * @param {'fixed'|'absolute'} [options.strategy='fixed']
+ * @param {boolean} [options.open] - while false, auto-updates are paused.
+ * @returns {{ refs: { setReference: Function, setFloating: Function, reference: object, floating: object },
+ *   floatingStyles: object, placement: string, isPositioned: boolean, update: () => void }}
+ */
+function useFloatingPosition() {
+  var _ref = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
+    _ref$placement = _ref.placement,
+    placement = _ref$placement === void 0 ? "bottom-start" : _ref$placement,
+    _ref$offset = _ref.offset,
+    offset$1 = _ref$offset === void 0 ? 4 : _ref$offset,
+    _ref$flip = _ref.flip,
+    flip$1 = _ref$flip === void 0 ? true : _ref$flip,
+    _ref$shift = _ref.shift,
+    shift$1 = _ref$shift === void 0 ? true : _ref$shift,
+    _ref$matchWidth = _ref.matchWidth,
+    matchWidth = _ref$matchWidth === void 0 ? false : _ref$matchWidth,
+    maxHeight = _ref.maxHeight,
+    _ref$strategy = _ref.strategy,
+    strategy = _ref$strategy === void 0 ? "fixed" : _ref$strategy,
+    open = _ref.open;
+  var middleware = [offset(offset$1)];
+  if (flip$1) middleware.push(flip({
+    padding: SHIFT_PADDING
+  }));
+  if (shift$1) middleware.push(shift({
+    padding: SHIFT_PADDING
+  }));
+  if (matchWidth || maxHeight != null) {
+    middleware.push(size({
+      padding: SHIFT_PADDING,
+      apply: function apply(_ref2) {
+        var rects = _ref2.rects,
+          elements = _ref2.elements,
+          availableHeight = _ref2.availableHeight;
+        var style = elements.floating.style;
+        if (matchWidth) style.minWidth = "".concat(rects.reference.width, "px");
+        if (matchWidth === "exact") style.width = "".concat(rects.reference.width, "px");
+        if (maxHeight != null) {
+          var room = Math.max(MIN_FIT_HEIGHT, availableHeight);
+          style.maxHeight = "".concat(Math.min(maxHeight, room), "px");
+        }
+      }
+    }));
+  }
+  var result = useFloating({
+    placement: placement,
+    strategy: strategy,
+    open: open,
+    middleware: middleware,
+    whileElementsMounted: autoUpdate
+  });
+  return {
+    refs: result.refs,
+    floatingStyles: result.floatingStyles,
+    placement: result.placement,
+    isPositioned: result.isPositioned,
+    update: result.update
+  };
+}
+
+export { useFloatingPosition };

package/dist/esm/hooks/useHaptics.js

@@ -0,0 +1,65 @@
+'use client';
+import { useSyncExternalStore, useCallback } from 'react';
+import { useReducedMotion } from './useReducedMotion.js';
+
+/**
+ * Named vibration patterns (milliseconds; arrays alternate vibrate / pause).
+ * Kept short: haptics confirm an action, they never carry information alone.
+ */
+var HAPTIC_PATTERNS = Object.freeze({
+  selection: 10,
+  success: [10, 40, 10],
+  warning: [20, 60, 20],
+  error: [30, 40, 30, 40, 30]
+});
+function canVibrate() {
+  return typeof navigator !== "undefined" && typeof navigator.vibrate === "function";
+}
+// Vibration support never changes during a page's life: nothing to subscribe to.
+var subscribeNever = function subscribeNever() {
+  return function () {};
+};
+var getServerSupported = function getServerSupported() {
+  return false;
+};
+function resolvePattern(pattern) {
+  if (typeof pattern === "number") return pattern > 0 ? pattern : null;
+  if (Array.isArray(pattern)) return pattern.length > 0 ? pattern : null;
+  return Object.prototype.hasOwnProperty.call(HAPTIC_PATTERNS, pattern) ? HAPTIC_PATTERNS[pattern] : null;
+}
+/**
+ * Thin, opt-in wrapper around `navigator.vibrate` with named patterns.
+ *
+ * `trigger` is a no-op (returns `false`) when the Vibration API is missing
+ * (iOS Safari, desktop Safari, the server), when the user asks for reduced
+ * motion, when `enabled` is `false`, or for an unknown pattern name.
+ *
+ * @param options - `enabled` (default `true`) gates every trigger.
+ * @returns `{ trigger, supported, reducedMotion }`.
+ */
+function useHaptics() {
+  var _ref = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
+    _ref$enabled = _ref.enabled,
+    enabled = _ref$enabled === void 0 ? true : _ref$enabled;
+  var supported = useSyncExternalStore(subscribeNever, canVibrate, getServerSupported);
+  var reducedMotion = useReducedMotion();
+  var trigger = useCallback(function () {
+    var pattern = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "selection";
+    if (!enabled || reducedMotion || !canVibrate()) return false;
+    var resolved = resolvePattern(pattern);
+    if (resolved == null) return false;
+    try {
+      return navigator.vibrate(resolved) !== false;
+    } catch (_unused) {
+      // Some embedded browsers throw instead of returning false.
+      return false;
+    }
+  }, [enabled, reducedMotion]);
+  return {
+    trigger: trigger,
+    supported: supported,
+    reducedMotion: reducedMotion
+  };
+}
+
+export { HAPTIC_PATTERNS, useHaptics };

package/dist/esm/hooks/usePresence.js

@@ -0,0 +1,58 @@
+'use client';
+import { slicedToArray as _slicedToArray } from '../_virtual/_rollupPluginBabelHelpers.js';
+import { useState, useEffect } from 'react';
+import { useReducedMotion } from './useReducedMotion.js';
+
+// Internal (not exported). Keeps an overlay mounted through its exit
+// transition so it can animate out before it unmounts.
+/**
+ * @param {boolean} open - whether the overlay should be shown.
+ * @param {{ duration?: number }} [options] - transition length in ms (default
+ *   200). Forced to 0 when the user prefers reduced motion.
+ * @returns {{ mounted: boolean, state: 'entering'|'open'|'exiting'|'closed' }}
+ *   `mounted` stays true through 'exiting' and turns false once `duration`
+ *   has elapsed after `open` became false.
+ */
+function usePresence(open) {
+  var _ref = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
+    _ref$duration = _ref.duration,
+    duration = _ref$duration === void 0 ? 200 : _ref$duration;
+  var reducedMotion = useReducedMotion();
+  var ms = reducedMotion ? 0 : Math.max(0, Number(duration) || 0);
+  var _useState = useState(function () {
+      if (!open) return "closed";
+      return ms > 0 ? "entering" : "open";
+    }),
+    _useState2 = _slicedToArray(_useState, 2),
+    phase = _useState2[0],
+    setPhase = _useState2[1];
+  // When `open` flips, start the transition during render (React's "adjust
+  // state on prop change" pattern), so the first render after the flip is
+  // already 'entering' / 'exiting' and no effect sets state synchronously.
+  var _useState3 = useState(open),
+    _useState4 = _slicedToArray(_useState3, 2),
+    prevOpen = _useState4[0],
+    setPrevOpen = _useState4[1];
+  if (open !== prevOpen) {
+    setPrevOpen(open);
+    if (open) setPhase(ms > 0 ? "entering" : "open");else setPhase(ms > 0 ? "exiting" : "closed");
+  }
+  // Settle on the resting phase once the transition has run.
+  useEffect(function () {
+    if (phase !== "entering" && phase !== "exiting") return undefined;
+    var next = phase === "entering" ? "open" : "closed";
+    var timer = setTimeout(function () {
+      return setPhase(next);
+    }, ms);
+    return function () {
+      return clearTimeout(timer);
+    };
+  }, [phase, ms]);
+  var state = phase;
+  return {
+    mounted: state !== "closed",
+    state: state
+  };
+}
+
+export { usePresence };

package/dist/esm/hooks/usePresentation.js

@@ -0,0 +1,21 @@
+import { useMediaQuery } from './useMediaQuery.js';
+
+// Internal (not exported). Picks how an overlay presents itself: as a bottom
+// sheet on small touch screens, as an anchored popover everywhere else.
+var SHEET_MEDIA_QUERY = "(pointer: coarse) and (max-width: 639px)";
+/**
+ * @param {'auto'|'sheet'|'popover'} [prop='auto'] - an explicit 'sheet' or
+ *   'popover' passes through; 'auto' resolves from SHEET_MEDIA_QUERY.
+ * @returns {'sheet'|'popover'} - 'popover' on the server and while hydrating.
+ */
+function usePresentation() {
+  var prop = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "auto";
+  // Always subscribe (rules of hooks); the result is ignored when explicit.
+  var isSheet = useMediaQuery(SHEET_MEDIA_QUERY, {
+    defaultValue: false
+  });
+  if (prop === "sheet" || prop === "popover") return prop;
+  return isSheet ? "sheet" : "popover";
+}
+
+export { SHEET_MEDIA_QUERY, usePresentation };