@astryxdesign/core 0.4.3 → 0.4.4-canary.0e8af82

package/dist/BottomSheet/BottomSheetSwitcher.js

@@ -0,0 +1,410 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetSwitcher.tsx
+ * @input Uses React context, StyleX, theme tokens, focus/scroll-lock hooks, BottomSheetSwitcherContext
+ * @output Exports BottomSheetSwitcher and BottomSheetSwitcherProps
+ * @position Core switcher for mutually exclusive BottomSheet flows
+ *
+ * The switcher turns a set of declaratively nested BottomSheets into a
+ * controlled single-selection group: `activeSheet` names the one interactive
+ * child, or is null when the flow is closed. During a handoff the new sheet
+ * enters above the previous sheet. If it is shorter, the previous sheet moves
+ * down at the same time until their top edges align; otherwise it stays
+ * stationary. The previous sheet fades only after both motions complete.
+ *
+ * All child sheets render as panels inside one switcher-owned `<dialog>`. A
+ * scrim flow calls showModal() once and keeps that native top-layer dialog open
+ * across every handoff. A no-scrim flow calls show() on the same non-modal shell.
+ * This keeps one modal boundary and one native ::backdrop without a portal.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
+ * - /packages/core/src/BottomSheet/index.ts
+ * - /apps/storybook/stories/BottomSheetSwitcher.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/BottomSheet/BottomSheetSwitcherShowcase.tsx
+ */
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
+import { hasActiveFocusTrapEscape, isImeKeyEvent, useFocusTrap, useScrollLock } from "../hooks/index.js";
+import { composeEventHandlers, mergeProps, mergeRefs } from "../utils/index.js";
+import { BottomSheetSwitcherContext } from "./BottomSheetSwitcherContext.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const styles = {
+  dialog: {
+    kVAEAm: "xixxii4",
+    kpwlN0: "x10a8y8t",
+    kzqmXN: "x1o6l61p",
+    kZKoxP: "xtdtrs8",
+    ks0D6T: "x1x1rfll",
+    kskxy: "x7ab17h",
+    kogj98: "x1ghz6dp",
+    kmVPX3: "x1717udv",
+    kWkggS: "xjbqb8w",
+    kVQacm: "x1rea2x4",
+    k1xSpc: "x1s85apg",
+    kI3sdo: "x1a2a7pz",
+    $$css: true
+  },
+  dialogOpen: {
+    k1xSpc: "x1lliihq",
+    $$css: true
+  },
+  dialogNonModal: {
+    kfzvcC: "x47corl",
+    kY2c9j: "xfo81ep",
+    kzqmXN: "xh8yej3",
+    kZKoxP: "x5yr21d",
+    $$css: true
+  },
+  scrim: {
+    kGyWv1: "xnixb3f",
+    k5sjJv: "xni466t xxiuuzi",
+    kND0Po: "xc0dz0a",
+    k9an0g: "xft5bk6",
+    kb4ib: "x15h3t91",
+    kwHxkk: "x142juwg",
+    k4oj2o: "x1viac0w",
+    $$css: true
+  }
+};
+const IDLE_TRANSITION = {
+  enteringSheet: null,
+  retainedSheet: null,
+  retainedPhase: null,
+  alignmentOffset: 0,
+  isAlignmentComplete: false
+};
+const ALIGNMENT_THRESHOLD_PX = 1;
+function transitionForActiveSheetChange(previousSheet, nextSheet) {
+  if (previousSheet == null) {
+    return IDLE_TRANSITION;
+  }
+  if (nextSheet == null) {
+    return {
+      enteringSheet: null,
+      retainedSheet: previousSheet,
+      retainedPhase: 'exiting',
+      alignmentOffset: 0,
+      isAlignmentComplete: false
+    };
+  }
+  return {
+    enteringSheet: nextSheet,
+    retainedSheet: previousSheet,
+    retainedPhase: 'covered',
+    alignmentOffset: 0,
+    isAlignmentComplete: false
+  };
+}
+function alignmentOffsetForElements(enteringElement, retainedElement) {
+  if (enteringElement == null || retainedElement == null) {
+    return 0;
+  }
+  const enteringPositioner = enteringElement.parentElement;
+  const enteringTop = enteringPositioner?.getBoundingClientRect().top ?? enteringElement.getBoundingClientRect().top;
+  return Math.max(0, enteringTop - retainedElement.getBoundingClientRect().top);
+}
+/**
+ * Coordinates a set of BottomSheets so zero or one is active at a time inside
+ * one shared native dialog. During a handoff the previous panel stays visible
+ * and inert beneath the entering panel, then fades after motion completes.
+ */
+export function BottomSheetSwitcher({
+  activeSheet,
+  onActiveSheetChange,
+  hasScrim = true,
+  children,
+  ref,
+  xstyle,
+  className,
+  style,
+  onCancel,
+  onClick,
+  onKeyDown,
+  ...props
+}) {
+  const dialogRef = useRef(null);
+  const dialogModeRef = useRef(null);
+  const triggerRef = useRef(null);
+  const sheetElementsRef = useRef(new Map());
+  const committedActiveSheetRef = useRef(activeSheet);
+  const [sheetLabels, setSheetLabels] = useState(() => new Map());
+  const [sheetPurposes, setSheetPurposes] = useState(() => new Map());
+  const [unmountedSheetIds, setUnmountedSheetIds] = useState(() => new Set());
+  const [transition, setTransition] = useState(IDLE_TRANSITION);
+  const activeSheetChanged = committedActiveSheetRef.current !== activeSheet;
+  const visibleTransition = activeSheetChanged ? transitionForActiveSheetChange(committedActiveSheetRef.current, activeSheet) : transition;
+  const isFlowVisible = activeSheet != null && !unmountedSheetIds.has(activeSheet) || visibleTransition.retainedSheet != null && !unmountedSheetIds.has(visibleTransition.retainedSheet);
+  const isModal = hasScrim && isFlowVisible;
+  const activeSheetPurpose = (activeSheet == null ? null : sheetPurposes.get(activeSheet)) ?? 'info';
+  const allowsEscapeDismiss = activeSheetPurpose !== 'required';
+  const allowsLightDismiss = activeSheetPurpose === 'info';
+  useLayoutEffect(() => {
+    const previousActiveSheet = committedActiveSheetRef.current;
+    if (previousActiveSheet === activeSheet) {
+      return;
+    }
+    committedActiveSheetRef.current = activeSheet;
+    const nextTransition = transitionForActiveSheetChange(previousActiveSheet, activeSheet);
+    setTransition(nextTransition.retainedSheet != null && !sheetElementsRef.current.has(nextTransition.retainedSheet) ? IDLE_TRANSITION : nextTransition);
+  }, [activeSheet]);
+  const dismissOnEscape = useCallback(() => {
+    if (allowsEscapeDismiss) {
+      onActiveSheetChange(null);
+    }
+  }, [allowsEscapeDismiss, onActiveSheetChange]);
+  const dismissOnLightInteraction = useCallback(() => {
+    if (allowsLightDismiss) {
+      onActiveSheetChange(null);
+    }
+  }, [allowsLightDismiss, onActiveSheetChange]);
+  const {
+    containerRef
+  } = useFocusTrap({
+    isActive: isModal,
+    onEscape: dismissOnEscape
+  });
+  useScrollLock(isModal);
+
+  // Open one shared shell for the complete flow. Modal flows enter the native
+  // top layer once; handoffs only swap panels inside it. The final panel owns
+  // the exit timing, so isFlowVisible becomes false only when it is safe to
+  // close the dialog and restore focus.
+  useLayoutEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog == null) {
+      return;
+    }
+    if (isFlowVisible) {
+      const nextMode = hasScrim ? 'modal' : 'non-modal';
+      if (dialog.open && dialogModeRef.current !== nextMode) {
+        dialog.close();
+      }
+      if (!dialog.open) {
+        if (hasScrim && triggerRef.current == null) {
+          triggerRef.current = document.activeElement;
+        }
+        if (hasScrim) {
+          dialog.showModal();
+        } else {
+          dialog.show();
+        }
+      }
+      dialogModeRef.current = nextMode;
+      return;
+    }
+    if (dialog.open) {
+      dialog.close();
+    }
+    if (dialogModeRef.current === 'modal') {
+      triggerRef.current?.focus();
+    }
+    triggerRef.current = null;
+    dialogModeRef.current = null;
+  }, [hasScrim, isFlowVisible]);
+  const getSheetPhase = useCallback(sheetId => {
+    if (sheetId === activeSheet) {
+      return sheetId === visibleTransition.enteringSheet ? 'entering' : 'active';
+    }
+    if (sheetId === visibleTransition.retainedSheet) {
+      return visibleTransition.retainedPhase ?? 'hidden';
+    }
+    return 'hidden';
+  }, [activeSheet, visibleTransition]);
+  const getSheetAlignmentOffset = useCallback(sheetId => visibleTransition.retainedSheet === sheetId ? visibleTransition.alignmentOffset : 0, [visibleTransition]);
+  const registerSheetElement = useCallback((sheetId, element) => {
+    if (element == null) {
+      sheetElementsRef.current.delete(sheetId);
+      setUnmountedSheetIds(current => {
+        if (current.has(sheetId)) {
+          return current;
+        }
+        const next = new Set(current);
+        next.add(sheetId);
+        return next;
+      });
+      setTransition(current => current.retainedSheet === sheetId ? IDLE_TRANSITION : current);
+    } else {
+      sheetElementsRef.current.set(sheetId, element);
+      setUnmountedSheetIds(current => {
+        if (!current.has(sheetId)) {
+          return current;
+        }
+        const next = new Set(current);
+        next.delete(sheetId);
+        return next;
+      });
+    }
+  }, []);
+  const registerSheetLabel = useCallback((sheetId, label) => {
+    setSheetLabels(current => {
+      if (label == null) {
+        if (!current.has(sheetId)) {
+          return current;
+        }
+        const next = new Map(current);
+        next.delete(sheetId);
+        return next;
+      }
+      if (current.get(sheetId) === label) {
+        return current;
+      }
+      const next = new Map(current);
+      next.set(sheetId, label);
+      return next;
+    });
+  }, []);
+  const registerSheetPurpose = useCallback((sheetId, purpose) => {
+    setSheetPurposes(current => {
+      if (purpose == null) {
+        if (!current.has(sheetId)) {
+          return current;
+        }
+        const next = new Map(current);
+        next.delete(sheetId);
+        return next;
+      }
+      if (current.get(sheetId) === purpose) {
+        return current;
+      }
+      const next = new Map(current);
+      next.set(sheetId, purpose);
+      return next;
+    });
+  }, []);
+  useLayoutEffect(() => {
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- clear a retained sheet after its panel unmounts
+    setTransition(current => current.retainedSheet != null && unmountedSheetIds.has(current.retainedSheet) ? IDLE_TRANSITION : current);
+  }, [unmountedSheetIds]);
+  const onSheetEnterStart = useCallback(sheetId => {
+    setTransition(current => {
+      if (current.enteringSheet !== sheetId || current.retainedSheet == null || current.retainedPhase !== 'covered') {
+        return current;
+      }
+      const alignmentOffset = alignmentOffsetForElements(sheetElementsRef.current.get(sheetId), sheetElementsRef.current.get(current.retainedSheet));
+      if (alignmentOffset <= ALIGNMENT_THRESHOLD_PX) {
+        return current;
+      }
+      return {
+        ...current,
+        retainedPhase: 'aligning',
+        alignmentOffset,
+        isAlignmentComplete: false
+      };
+    });
+  }, []);
+  const onSheetTransitionComplete = useCallback(({
+    sheetId,
+    phase
+  }) => {
+    setTransition(current => {
+      if (phase === 'entering') {
+        if (current.enteringSheet !== sheetId) {
+          return current;
+        }
+        if (current.retainedSheet == null) {
+          return IDLE_TRANSITION;
+        }
+        if (current.retainedPhase === 'aligning' && !current.isAlignmentComplete) {
+          return {
+            ...current,
+            enteringSheet: null
+          };
+        }
+        return {
+          ...current,
+          enteringSheet: null,
+          retainedPhase: 'fading'
+        };
+      }
+      if (phase === 'aligning' && current.retainedSheet === sheetId && current.retainedPhase === 'aligning') {
+        return current.enteringSheet == null ? {
+          ...current,
+          retainedPhase: 'fading'
+        } : {
+          ...current,
+          isAlignmentComplete: true
+        };
+      }
+      if ((phase === 'fading' || phase === 'exiting') && current.retainedSheet === sheetId && current.retainedPhase === phase) {
+        return IDLE_TRANSITION;
+      }
+      return current;
+    });
+  }, []);
+  const setScrimOpacity = useCallback(opacity => {
+    dialogRef.current?.style.setProperty('--_sheet-scrim-opacity', String(opacity));
+  }, []);
+  const onSheetScrimOpacityChange = useCallback((sheetId, opacity) => {
+    // A pointer captured by the outgoing sheet can keep delivering gesture
+    // events after a handoff. Only the currently committed sheet owns the
+    // shared backdrop, so stale gesture updates must not reach the dialog.
+    if (sheetId !== committedActiveSheetRef.current) {
+      return;
+    }
+    setScrimOpacity(opacity);
+  }, [setScrimOpacity]);
+  useLayoutEffect(() => {
+    setScrimOpacity(activeSheet == null ? 0 : 1);
+  }, [activeSheet, setScrimOpacity]);
+  const contextValue = useMemo(() => ({
+    activeSheet,
+    hasScrim,
+    onActiveSheetChange,
+    getSheetPhase,
+    getSheetAlignmentOffset,
+    registerSheetElement,
+    registerSheetLabel,
+    registerSheetPurpose,
+    onSheetEnterStart,
+    onSheetTransitionComplete,
+    onSheetScrimOpacityChange
+  }), [activeSheet, getSheetAlignmentOffset, getSheetPhase, hasScrim, onActiveSheetChange, onSheetEnterStart, onSheetScrimOpacityChange, onSheetTransitionComplete, registerSheetElement, registerSheetLabel, registerSheetPurpose]);
+  const activeLabel = (activeSheet == null ? null : sheetLabels.get(activeSheet)) ?? (visibleTransition.retainedSheet == null ? undefined : sheetLabels.get(visibleTransition.retainedSheet));
+  const handleCancel = useCallback(event => {
+    event.preventDefault();
+    dismissOnEscape();
+  }, [dismissOnEscape]);
+  const handleKeyDown = useCallback(event => {
+    // Modal Escape is owned by useFocusTrap so nested traps can win. A
+    // non-modal switcher has no outer trap, so retain local dismissal while
+    // deferring to an active nested layer and ignoring IME cancellation.
+    if (!isModal && event.key === 'Escape' && !isImeKeyEvent(event.nativeEvent) && !hasActiveFocusTrapEscape()) {
+      event.preventDefault();
+      dismissOnEscape();
+    }
+  }, [dismissOnEscape, isModal]);
+  const handleClick = useCallback(event => {
+    if (hasScrim && event.target === event.currentTarget) {
+      dismissOnLightInteraction();
+    }
+  }, [dismissOnLightInteraction, hasScrim]);
+  const dialogStyleProps = stylex.props(styles.dialog, isFlowVisible && styles.dialogOpen, hasScrim && styles.scrim, !hasScrim && styles.dialogNonModal, xstyle);
+  const dialogPresentationProps = mergeProps(dialogStyleProps, className, style);
+  const ariaLabel = props['aria-label'] ?? (props['aria-labelledby'] == null ? activeLabel : undefined);
+  return /*#__PURE__*/_jsx(BottomSheetSwitcherContext, {
+    value: contextValue,
+    children: /*#__PURE__*/_jsx("dialog", {
+      ...props,
+      ...dialogPresentationProps,
+      ref: mergeRefs(ref, dialogRef, containerRef),
+      "aria-label": ariaLabel,
+      "aria-modal": isModal ? 'true' : undefined,
+      onCancel: composeEventHandlers(onCancel, handleCancel),
+      onClick: composeEventHandlers(onClick, handleClick),
+      onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+      ...(activeSheetPurpose === 'required' ? {
+        role: 'alertdialog'
+      } : undefined),
+      children: children
+    })
+  });
+}
+BottomSheetSwitcher.displayName = 'BottomSheetSwitcher';

package/dist/BottomSheet/BottomSheetSwitcherContext.d.ts

@@ -0,0 +1,21 @@
+import type { DialogPurpose } from '../Dialog';
+export type BottomSheetSwitcherPhase = 'entering' | 'active' | 'covered' | 'aligning' | 'fading' | 'exiting' | 'hidden';
+export interface BottomSheetSwitcherTransitionEvent {
+    sheetId: string;
+    phase: 'entering' | 'aligning' | 'fading' | 'exiting';
+}
+export interface BottomSheetSwitcherContextValue {
+    activeSheet: string | null;
+    hasScrim: boolean;
+    onActiveSheetChange: (sheetId: string | null) => void;
+    getSheetPhase: (sheetId: string) => BottomSheetSwitcherPhase;
+    getSheetAlignmentOffset: (sheetId: string) => number;
+    registerSheetElement: (sheetId: string, element: HTMLElement | null) => void;
+    registerSheetLabel: (sheetId: string, label: string | null) => void;
+    registerSheetPurpose: (sheetId: string, purpose: DialogPurpose | null) => void;
+    onSheetEnterStart: (sheetId: string) => void;
+    onSheetTransitionComplete: (event: BottomSheetSwitcherTransitionEvent) => void;
+    onSheetScrimOpacityChange: (sheetId: string, opacity: number) => void;
+}
+export declare const BottomSheetSwitcherContext: import("react").Context<BottomSheetSwitcherContextValue | null>;
+//# sourceMappingURL=BottomSheetSwitcherContext.d.ts.map

package/dist/BottomSheet/BottomSheetSwitcherContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetSwitcherContext.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetSwitcherContext.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,WAAW,CAAC;AAE7C,MAAM,MAAM,wBAAwB,GAChC,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;CACvD;AAED,MAAM,WAAW,+BAA+B;IAC9C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACtD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,wBAAwB,CAAC;IAC7D,uBAAuB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACrD,oBAAoB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7E,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACpE,oBAAoB,EAAE,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,GAAG,IAAI,KAC1B,IAAI,CAAC;IACV,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,yBAAyB,EAAE,CACzB,KAAK,EAAE,kCAAkC,KACtC,IAAI,CAAC;IACV,yBAAyB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvE;AAED,eAAO,MAAM,0BAA0B,iEACsB,CAAC"}

package/dist/BottomSheet/BottomSheetSwitcherContext.js

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetSwitcherContext.ts
+ * @input Uses React context
+ * @output Internal phase and lifecycle context shared by BottomSheetSwitcher and BottomSheet
+ * @position Private coordination layer for mutually exclusive BottomSheets
+ */
+import { createContext } from 'react';
+export const BottomSheetSwitcherContext = /*#__PURE__*/createContext(null);
+BottomSheetSwitcherContext.displayName = 'BottomSheetSwitcherContext';

package/dist/BottomSheet/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @file index.ts
+ * @input BottomSheet.tsx, BottomSheetSwitcher.tsx
+ * @output Re-exports the BottomSheet public API
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ */
+export { BottomSheet } from './BottomSheet';
+export type { BottomSheetHeight, BottomSheetProps, BottomSheetSnapPoint, } from './BottomSheet';
+export { BottomSheetSwitcher } from './BottomSheetSwitcher';
+export type { BottomSheetSwitcherProps } from './BottomSheetSwitcher';
+//# sourceMappingURL=index.d.ts.map

package/dist/BottomSheet/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAC,wBAAwB,EAAC,MAAM,uBAAuB,CAAC"}

package/dist/BottomSheet/index.js

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input BottomSheet.tsx, BottomSheetSwitcher.tsx
+ * @output Re-exports the BottomSheet public API
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ */
+export { BottomSheet } from "./BottomSheet.js";
+export { BottomSheetSwitcher } from "./BottomSheetSwitcher.js";

package/dist/BottomSheet/snapOffsets.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @file snapOffsets.ts
+ * @input Pure geometry helpers — no React, no DOM.
+ * @output Resolves snap points and converts them to translateY offsets.
+ * @position Internal to BottomSheet; consumed by useSheetGestures and
+ *   BottomSheetPanel, tested by snapOffsets.test.ts.
+ *
+ * A detent is represented as an offset in px from the fully-open position
+ * (0 = fully open, larger = more collapsed). The panel may render that offset
+ * as a translate or as a reduction in layout height. These
+ * helpers turn snap points into the shared offset list; they are pure so the
+ * geometry can be unit-tested without a DOM.
+ */
+/**
+ * A height the sheet can rest at, expressed as the sheet's VISIBLE height:
+ *
+ * - a number in `(0, 1]` — a fraction of the viewport (`0.5` is half the
+ *   screen), so the stop tracks rotation and window resizes;
+ * - a `'<n>%'` string — the same thing spelled in CSS;
+ * - a `'<n>px'` string — an absolute height that does not scale.
+ *
+ * Anything else — a unitless string, `calc()`, `vh`, `rem`, a number outside
+ * `(0, 1]` — is ignored with a dev warning. Percentages resolve against the
+ * layout viewport (`window.innerHeight`), the same box the height budgets are
+ * written against, so the mobile keyboard never moves a stop.
+ */
+export type BottomSheetSnapPoint = number | string;
+/**
+ * Detents whose resting offsets land within this many px of each other are
+ * treated as the same stop (the taller one wins). Stops the sheet from having
+ * two near-identical rest positions — e.g. when a content-hugging height sits
+ * a hair away from a fractional snap point.
+ */
+export declare const DETENT_DEDUP_PX = 48;
+/**
+ * Largest share of the fully open sheet the shortest stop may fill and still
+ * be a peek. Above it the stop is a working surface — it lays its content out
+ * and keeps a full scrim — so a two-stop sheet like `[0.5]` behaves like the
+ * half-height panel it asks for rather than like a glance.
+ */
+export declare const PEEK_MAX_HEIGHT_RATIO = 0.25;
+/**
+ * Whether a snap point can be resolved at all. The viewport only scales the
+ * result, so validity is independent of it.
+ */
+export declare function isValidSnapPoint(point: BottomSheetSnapPoint): boolean;
+/**
+ * Resolve snap points to candidate visible heights in px, dropping the ones
+ * this sheet cannot honor. Callers warn about those separately — this stays
+ * silent because it runs on every drag frame.
+ */
+export declare function resolveSnapPoints(points: ReadonlyArray<BottomSheetSnapPoint>, viewportPx: number): number[];
+/**
+ * Given the sheet's full height (px, as rendered fully open) and a set of
+ * candidate detent *visible heights* (px), return the resting offsets from
+ * fully-open, ascending and de-duplicated.
+ *
+ * - `0` (fully open) is always the first detent.
+ * - Only heights strictly shorter than the sheet become collapsed detents; a
+ *   height >= the sheet is already covered by the fully-open stop.
+ * - Offsets closer than `dedupPx` collapse to the smaller (taller) offset, so
+ *   near-identical detents — e.g. a hug height ≈ a snap point — become one stop.
+ */
+export declare function computeDetentOffsets(sheetHeight: number, detentHeights: ReadonlyArray<number>, dedupPx?: number): number[];
+/** Nearest value in `offsets` to `value` (offsets must be non-empty). */
+export declare function nearestOffset(value: number, offsets: ReadonlyArray<number>): number;
+/**
+ * Minimum scrim opacity at the peek detent. The scrim thins to a glance state
+ * but never fully vanishes, because a modal sheet keeps the background inert —
+ * a fully clear backdrop would read as "interactive" when it isn't. (For a
+ * genuinely interactive, undimmed peek, use a non-modal sheet, `hasScrim=false`.)
+ */
+export declare const MIN_PEEK_SCRIM_OPACITY = 0.3;
+/**
+ * The peek detent's offset, or `null` when this sheet has no peek.
+ *
+ * A peek is the shortest stop AND a sliver — at most `PEEK_MAX_HEIGHT_RATIO`
+ * of the fully open sheet. It is the one detent the sheet does NOT express as
+ * layout height: at a sliver there is nothing useful to lay out, and reflowing
+ * the content into it (then back out on the way up) is churn the user sees, so
+ * it keeps the full layout height and slides below the viewport instead. It is
+ * also the only stop that thins the scrim.
+ *
+ * A sheet whose shortest stop is a working height — `[0.5]`, say — has no
+ * peek: half a screen of content deserves to be laid out at half a screen, and
+ * a scrim that thinned there would read as a dismissed sheet.
+ */
+export declare function peekOffsetFor(offsets: ReadonlyArray<number>, visibleSheetHeight: number): number | null;
+/**
+ * Scrim opacity (1 = fully visible) for a drag/settle `offset`.
+ *
+ * The scrim is full down to the shortest stop that is still a working surface,
+ * and only thins past it — onto a peek, where it holds at
+ * `MIN_PEEK_SCRIM_OPACITY` (a glance state, and the sheet is still modal), or
+ * out through the dismiss overshoot toward `dismissOffset`, where it clears
+ * completely because the sheet is leaving.
+ *
+ * So a sheet whose stops are all working heights keeps a full scrim at every
+ * one of them; only the sliver of a peek, or a sheet on its way out, dims less.
+ */
+export declare function scrimOpacityForOffset(offset: number, offsets: ReadonlyArray<number>, dismissOffset: number, peekOffset: number | null): number;
+/**
+ * Settle target for a released drag. Restricts candidates to the drag
+ * direction so a committed drag never snaps *back past* where it started
+ * (a down-drag settles at/below the start, an up-drag at/above), then picks
+ * the nearest remaining detent. `dir`: 1 = dragged down, -1 = up, 0 = neither.
+ */
+export declare function resolveSettleOffset(value: number, offsets: ReadonlyArray<number>, dir: number, baseOffset: number): number;
+//# sourceMappingURL=snapOffsets.d.ts.map

package/dist/BottomSheet/snapOffsets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapOffsets.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/snapOffsets.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAkC1C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAErE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,CAAC,oBAAoB,CAAC,EAC3C,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CASV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,EACpC,OAAO,GAAE,MAAwB,GAChC,MAAM,EAAE,CAcV;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAC7B,MAAM,CAKR;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,kBAAkB,EAAE,MAAM,GACzB,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAgBR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,MAAM,CAcR"}