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

package/dist/BottomSheet/BottomSheetPanel.js

@@ -0,0 +1,441 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetPanel.tsx
+ * @input Uses React, StyleX, theme tokens, useSheetGestures
+ * @output Internal BottomSheetPanel surface and motion-state types
+ * @position Shared presentation layer for standalone and switcher BottomSheets
+ *
+ * This component owns everything intrinsic to a sheet surface: height budgets,
+ * drag and snap gestures, the handle and scrolling body, motion styles, and
+ * transition completion. It deliberately does not own a dialog, focus, inert
+ * state, or switcher registration; those belong to the hosting controller.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetPanel.test.tsx
+ * - /packages/core/src/BottomSheet/snapOffsets.ts
+ * - /packages/core/src/BottomSheet/useMobileKeyboard.ts
+ * - /packages/core/src/BottomSheet/useSheetGestures.ts
+ */
+import { useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { useDevWarning } from "../hooks/index.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, durationVars, easeVars, radiusVars, shadowVars, sizeVars, spacingVars } from "../theme/tokens.stylex.js";
+import { mergeProps, themeProps } from "../utils/index.js";
+import { isValidSnapPoint, resolveSnapPoints } from "./snapOffsets.js";
+import { useMobileKeyboard } from "./useMobileKeyboard.js";
+import { useSheetGestures } from "./useSheetGestures.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const HEIGHT_BUDGETS = {
+  hug: '92dvh',
+  capped: '62dvh',
+  tall: '92dvh'
+};
+// SYNC: must match OVERSCROLL_MAX in useSheetGestures.ts.
+const OVERSCROLL_PADDING = 48;
+const MOBILE_KEYBOARD_BOTTOM_CLEARANCE = 48;
+const TRANSITION_BACKSTOP_BUFFER_MS = 50;
+
+// Measure the same viewport the height budgets are written against. Those are
+// `dvh`, which the virtual keyboard does not shrink, so reading
+// `visualViewport` here would make the two disagree by exactly the keyboard's
+// height: every detent would move while the sheet it measures did not. A
+// keyboard is `useMobileKeyboard`'s business — it holds the sheet still and
+// scrolls the body — and it does not redefine the sheet's detents.
+function layoutViewportHeight() {
+  return typeof window === 'undefined' ? 0 : window.innerHeight;
+}
+
+/**
+ * A stable identity for a set of snap points. Type-tagged, so the fraction
+ * `0.5` and the (invalid) string `'0.5'` cannot collide on one key.
+ *
+ * Recomputed every render — the panel re-renders on every frame of a drag — so
+ * it stays a single pass over a handful of values, and everything derived from
+ * the points hangs off it instead of being rebuilt per frame.
+ */
+function snapPointsKeyFor(points) {
+  let key = '';
+  for (const point of points ?? []) {
+    key += `${typeof point}:${point}|`;
+  }
+  return key;
+}
+const styles = {
+  sheet: {
+    kfzvcC: "x67bb7w",
+    kB7OPa: "x9f619",
+    k1xSpc: "x78zum5",
+    kXwgrk: "xdt5ytf",
+    kAzted: "x2lwn1j",
+    kzqmXN: "xh8yej3",
+    ks0D6T: "x11gisft",
+    kWkggS: "x10xzikg",
+    krdFHd: "x81l70g",
+    kfmiAY: "x7hs6f1",
+    kGVxlE: "x1kcpxr7",
+    kI3sdo: "x1a2a7pz",
+    kVQacm: "xb3r6kr",
+    kGO01o: "x1wkw6tp",
+    k1K539: "x1if0o47",
+    k3aq6I: "xnn1q72 xhbqy3z",
+    kSiTet: "x1hc1fzr",
+    k1ekBW: "xwcsmn1",
+    kIyJzY: "x80gvsz",
+    kAMwcw: "xlr8y92",
+    k6sLGO: "x1q1rmc8",
+    k6CgDc: "xzg1mie",
+    $$css: true
+  },
+  sheetClosing: {
+    k3aq6I: "x1weeur4",
+    $$css: true
+  },
+  sheetFading: {
+    kSiTet: "xg01cxk",
+    $$css: true
+  },
+  sheetInactive: {
+    kfzvcC: "x47corl",
+    $$css: true
+  },
+  budget: {
+    kZKoxP: "x1tpcejd",
+    $$css: true
+  },
+  hugHeight: {
+    kZKoxP: "xg7h5cd",
+    kskxy: "x14bu9tk",
+    $$css: true
+  }
+};
+function motionForState(state) {
+  if (state.kind === 'open') {
+    return state.entering ? 'entering' : null;
+  }
+  if (state.kind === 'retained') {
+    return state.motion === 'covered' ? null : state.motion;
+  }
+  return state.kind === 'exiting' ? 'exiting' : null;
+}
+function waitForTransition(element, propertyName, complete) {
+  if (element == null) {
+    complete();
+    return () => {};
+  }
+  let done = false;
+  let timer = null;
+  const finish = () => {
+    if (done) {
+      return;
+    }
+    done = true;
+    if (timer != null) {
+      clearTimeout(timer);
+    }
+    element.removeEventListener('transitionend', handleTransitionEnd);
+    element.removeEventListener('transitioncancel', handleTransitionEnd);
+    complete();
+  };
+  const handleTransitionEnd = event => {
+    if (event.target === element && event.propertyName === propertyName) {
+      finish();
+    }
+  };
+  element.addEventListener('transitionend', handleTransitionEnd);
+  element.addEventListener('transitioncancel', handleTransitionEnd);
+  const computedStyle = getComputedStyle(element);
+  if (element.style.transition.trim() === 'none' || computedStyle.transition.trim() === 'none') {
+    finish();
+    return () => {};
+  }
+  const properties = computedStyle.transitionProperty.split(',').map(value => value.trim());
+  const durations = computedStyle.transitionDuration.split(',').map(parseTransitionTime);
+  const delays = computedStyle.transitionDelay.split(',').map(parseTransitionTime);
+  let hasUnresolvedTiming = false;
+  const transitionMs = properties.reduce((longest, property, index) => {
+    if (property !== propertyName && property !== 'all') {
+      return longest;
+    }
+    const duration = durations[index % durations.length];
+    const delay = delays[index % delays.length];
+    if (duration == null || delay == null) {
+      hasUnresolvedTiming = true;
+      return longest;
+    }
+    return Math.max(longest, duration + delay);
+  }, 0);
+  if (hasUnresolvedTiming) {
+    // JSDOM can leave CSS variables unresolved. In that case the native event
+    // remains authoritative; choosing a fixed timeout here would make an
+    // assumption about the consumer's theme.
+    return () => {
+      element.removeEventListener('transitionend', handleTransitionEnd);
+      element.removeEventListener('transitioncancel', handleTransitionEnd);
+    };
+  }
+  if (transitionMs <= 0) {
+    finish();
+    return () => {};
+  }
+  timer = setTimeout(finish, transitionMs + TRANSITION_BACKSTOP_BUFFER_MS);
+  return () => {
+    if (timer != null) {
+      clearTimeout(timer);
+    }
+    element.removeEventListener('transitionend', handleTransitionEnd);
+    element.removeEventListener('transitioncancel', handleTransitionEnd);
+  };
+}
+function parseTransitionTime(value) {
+  const normalizedValue = value.trim();
+  if (!/^-?(?:\d+|\d*\.\d+)(?:ms|s)$/.test(normalizedValue)) {
+    return null;
+  }
+  const time = Number.parseFloat(value);
+  return normalizedValue.endsWith('ms') ? time : time * 1000;
+}
+
+/** Internal visual and gesture surface shared by every BottomSheet host. */
+export function BottomSheetPanel({
+  ref,
+  state,
+  height,
+  children,
+  snapPoints,
+  className,
+  style,
+  tabIndex,
+  xstyle,
+  isSwipeDismissAllowed = true,
+  isPageScrollLocked = false,
+  onDismiss,
+  onScrimOpacity,
+  onElementChange,
+  onMotionStart,
+  onMotionComplete,
+  ...props
+}) {
+  const elementRef = useRef(null);
+  const previousStateRef = useRef(state);
+  const reactivatedEntranceRef = useRef(false);
+  const onMotionStartRef = useRef(onMotionStart);
+  const onMotionCompleteRef = useRef(onMotionComplete);
+  const startedMotionRef = useRef(null);
+  const pendingMotionCompleteRef = useRef(null);
+  const isEntering = state.kind === 'open' && state.entering;
+  const previousState = previousStateRef.current;
+  const wasEntering = previousState.kind === 'open' && previousState.entering;
+  if (isEntering && !wasEntering) {
+    reactivatedEntranceRef.current = previousState.kind === 'retained';
+  } else if (!isEntering) {
+    reactivatedEntranceRef.current = false;
+  }
+  useLayoutEffect(() => {
+    previousStateRef.current = state;
+    onMotionStartRef.current = onMotionStart;
+    onMotionCompleteRef.current = onMotionComplete;
+  }, [onMotionComplete, onMotionStart, state]);
+  const isInteractive = state.kind === 'open';
+  const isPresented = state.kind !== 'hidden';
+  const isRetained = state.kind === 'retained';
+  const isInactive = isRetained || state.kind === 'exiting';
+  const isClosing = state.kind === 'exiting';
+  const isFading = isRetained && state.motion === 'fading';
+  const alignmentOffset = isRetained ? state.alignmentOffset : 0;
+
+  // Everything derived from the snap points keys off their identity, not the
+  // array's: the resolver's identity is the hook's signal that the stops
+  // changed, so it must not churn on a re-render the drag caused. The memo
+  // reads the points through a ref, so the resolver resolves them at call time
+  // — against whatever the viewport is then, not what it was at memo time.
+  const snapPointsKey = snapPointsKeyFor(snapPoints);
+  const snapPointsRef = useRef(snapPoints);
+  snapPointsRef.current = snapPoints;
+  const {
+    snapHeights,
+    ignoredSnapPointsMessage
+  } = useMemo(() => {
+    if (snapPointsKey === '') {
+      return {
+        snapHeights: undefined,
+        ignoredSnapPointsMessage: ''
+      };
+    }
+    const ignored = (snapPointsRef.current ?? []).filter(point => !isValidSnapPoint(point));
+    return {
+      snapHeights: () => resolveSnapPoints(snapPointsRef.current ?? [], layoutViewportHeight()),
+      ignoredSnapPointsMessage: ignored.length === 0 ? '' : `snapPoints ignored ${JSON.stringify(ignored)}. A snap point is a viewport fraction above 0 and up to 1 (0.5 is half the screen), a px length ('320px'), or a percentage ('50%').`
+    };
+  }, [snapPointsKey]);
+  useDevWarning('BottomSheet', ignoredSnapPointsMessage, ignoredSnapPointsMessage !== '');
+  const {
+    contentProps,
+    handleProps,
+    bodyProps,
+    bodyElementRef,
+    sheetRef,
+    dragOffset,
+    settledOffset,
+    isDragging,
+    sheetHeight,
+    scrollPreservationInset,
+    settlingLayoutOffset,
+    settledLayoutOffset,
+    completeScrollAreaSettle
+  } = useSheetGestures({
+    isOpen: isInteractive,
+    canDismiss: isSwipeDismissAllowed,
+    offscreenBlockEndInset: OVERSCROLL_PADDING,
+    onDismiss,
+    snapHeights,
+    onScrimOpacity
+  });
+  const setElement = useCallback(element => {
+    sheetRef(element);
+    elementRef.current = element;
+    onElementChange?.(element);
+  }, [onElementChange, sheetRef]);
+  useMobileKeyboard({
+    bodyRef: bodyElementRef,
+    bottomClearance: MOBILE_KEYBOARD_BOTTOM_CLEARANCE,
+    isEnabled: height === 'tall',
+    isFullyExpanded: settledOffset === 0,
+    isPageScrollLocked,
+    isSheetTraveling: isDragging && dragOffset !== settledOffset,
+    isOpen: isInteractive,
+    isPresented,
+    sheetRef: elementRef
+  });
+  // Keep controller registration attached to one stable host ref. React
+  // detaches an old callback ref when a consumer supplies a new identity; if
+  // that public ref were merged with setElement, an ordinary parent rerender
+  // could be mistaken for the panel unmounting and cancel a sheet handoff.
+  useImperativeHandle(ref, () => elementRef.current, []);
+  const motion = motionForState(state);
+  useLayoutEffect(() => {
+    if (motion == null) {
+      return;
+    }
+    startedMotionRef.current = null;
+    pendingMotionCompleteRef.current = null;
+    if (motion === 'entering' && reactivatedEntranceRef.current) {
+      pendingMotionCompleteRef.current = motion;
+      return;
+    }
+    return waitForTransition(elementRef.current, motion === 'fading' ? 'opacity' : 'transform', () => {
+      if (startedMotionRef.current === motion) {
+        onMotionCompleteRef.current?.(motion);
+      } else {
+        pendingMotionCompleteRef.current = motion;
+      }
+    });
+  }, [motion]);
+  // The snap is transform-only; the layout height reconciles when it lands.
+  // waitForTransition — the same helper the motion states use — resolves that
+  // even when no `transitionend` is coming: inline or computed
+  // `transition: none`, a zero duration, and a timer backstop otherwise.
+  useLayoutEffect(() => {
+    if (settlingLayoutOffset == null) {
+      return;
+    }
+    return waitForTransition(elementRef.current, 'transform', completeScrollAreaSettle);
+  }, [completeScrollAreaSettle, settlingLayoutOffset]);
+  useEffect(() => {
+    if (motion == null) {
+      return;
+    }
+    onMotionStartRef.current?.(motion);
+    startedMotionRef.current = motion;
+    if (pendingMotionCompleteRef.current === motion) {
+      pendingMotionCompleteRef.current = null;
+      onMotionCompleteRef.current?.(motion);
+    }
+    return () => {
+      if (startedMotionRef.current === motion) {
+        startedMotionRef.current = null;
+      }
+      if (pendingMotionCompleteRef.current === motion) {
+        pendingMotionCompleteRef.current = null;
+      }
+    };
+  }, [motion]);
+  const isNamedHeight = typeof height === 'string' && height in HEIGHT_BUDGETS;
+  const budget = isNamedHeight ? HEIGHT_BUDGETS[height] : typeof height === 'number' ? `${height}px` : height;
+  const hasMeasuredSheet = sheetHeight > 0;
+  let gestureTransform = contentProps.style.transform;
+  let resizedHeight;
+  if (hasMeasuredSheet) {
+    // The sheet's travel is split across two properties: `layoutOffset` is the
+    // part the scrolling area gives up as layout height, and the remainder is
+    // a compositor transform. Live gestures and snaps only ever move the
+    // transform — the layout height changes at rest, in one reconciling render
+    // whose visible geometry is identical (see useSheetGestures).
+    //   - dragging above the base restores the full height below the viewport
+    //   - a peek settles with layout 0, so it slides rather than reflowing
+    const layoutOffset = isDragging ? dragOffset < settledOffset ? 0 : settledLayoutOffset : settlingLayoutOffset ?? settledLayoutOffset;
+    const activeOffset = isDragging ? dragOffset : settledOffset;
+    const translation = activeOffset - layoutOffset;
+
+    // At layout 0 the sheet is its natural height, so leave that to CSS —
+    // `hug` sheets must stay fit-content. While the sheet is in motion it is
+    // pinned in px instead: content reflowing mid-gesture would move the
+    // surface out from under the finger, or under the snap.
+    const isTraveling = isDragging || settlingLayoutOffset != null;
+    resizedHeight = layoutOffset > 0 || isTraveling ? `${Math.max(0, sheetHeight - Math.max(0, layoutOffset))}px` : undefined;
+    gestureTransform = translation !== 0 ? `translateY(${translation}px)` : undefined;
+  }
+  const retainedTransform = alignmentOffset > 0 ? [gestureTransform, `translateY(${alignmentOffset}px)`].filter(Boolean).join(' ') : gestureTransform;
+  const gestureStyle = {
+    ...contentProps.style,
+    transform: gestureTransform,
+    height: resizedHeight
+  };
+  return /*#__PURE__*/_jsxs("div", {
+    ...props,
+    ref: setElement,
+    tabIndex: tabIndex ?? -1,
+    ...mergeProps(themeProps('bottom-sheet'), stylex.props(styles.sheet, height === 'hug' ? styles.hugHeight : styles.budget, isClosing && styles.sheetClosing, isFading && styles.sheetFading, isInactive && styles.sheetInactive, xstyle), className, {
+      ['--_sheet-budget']: budget,
+      ...(isInteractive ? gestureStyle : isRetained ? {
+        transform: retainedTransform,
+        height: resizedHeight
+      } : isClosing ? {
+        height: resizedHeight
+      } : {}),
+      ...style
+    }),
+    children: [/*#__PURE__*/_jsx("div", {
+      ...{
+        className: "x2lah0s x78zum5 x6s0dn4 xl56j7k x1k15mir x5ve5x3 x1jm3nie"
+      },
+      ...handleProps,
+      "aria-hidden": "true",
+      children: /*#__PURE__*/_jsx("div", {
+        ...{
+          className: "x1m747yf x11c6zpc xjspbzw x1m4xfpy"
+        }
+      })
+    }), /*#__PURE__*/_jsx("div", {
+      ...mergeProps({
+        0: {
+          className: "x1iyjqo2 x2lwn1j x9f619 x1odjw0f x8du1vd xx69xxh x18d9i69"
+        },
+        1: {
+          className: "x1iyjqo2 x2lwn1j x9f619 x1odjw0f x8du1vd xx69xxh x18d9i69 xrw9175 x1s928wv xhkezso xu6fald x2q1x1w"
+        }
+      }[!!(height === 'tall') << 0], scrollPreservationInset > 0 ? {
+        style: {
+          paddingBlockEnd: `${scrollPreservationInset}px`
+        }
+      } : {}),
+      ...bodyProps,
+      children: children
+    })]
+  });
+}
+BottomSheetPanel.displayName = 'BottomSheetPanel';

package/dist/BottomSheet/BottomSheetSwitcher.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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 { type ReactNode, type SyntheticEvent } from 'react';
+import type { BaseProps } from '../BaseProps';
+export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
+    /** Ref forwarded to the shared native dialog. */
+    ref?: React.Ref<HTMLDialogElement>;
+    /** Called when the shared native dialog receives a cancel event. */
+    onCancel?: (event: SyntheticEvent<HTMLDialogElement>) => void;
+    /**
+     * ID of the interactive BottomSheet, or null when the flow should close.
+     * Must match a nested BottomSheet's `sheetId`. The previous sheet may remain
+     * visually present and inert while the new sheet enters, moving downward at
+     * the same time if the new sheet is shorter, then fade away.
+     */
+    activeSheet: string | null;
+    /** Called with null when the active sheet requests dismissal. */
+    onActiveSheetChange: (sheetId: string | null) => void;
+    /**
+     * Whether to open the shared dialog modally with its native ::backdrop.
+     * Disable for a viewport-anchored, non-modal flow over an interactive page.
+     * @default true
+     */
+    hasScrim?: boolean;
+    /** BottomSheets identified by unique `sheetId` values. */
+    children: ReactNode;
+}
+/**
+ * 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 declare function BottomSheetSwitcher({ activeSheet, onActiveSheetChange, hasScrim, children, ref, xstyle, className, style, onCancel, onClick, onKeyDown, ...props }: BottomSheetSwitcherProps): import("react").JSX.Element;
+export declare namespace BottomSheetSwitcher {
+    var displayName: string;
+}
+//# sourceMappingURL=BottomSheetSwitcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetSwitcher.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetSwitcher.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAQL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA2H5C,MAAM,WAAW,wBAAyB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC5E,iDAAiD;IACjD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IAE9D;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,iEAAiE;IACjE,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAEtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,WAAW,EACX,mBAAmB,EACnB,QAAe,EACf,QAAQ,EACR,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,OAAO,EACP,SAAS,EACT,GAAG,KAAK,EACT,EAAE,wBAAwB,+BA4Z1B;yBAzae,mBAAmB"}