@astryxdesign/core 0.5.0 → 0.5.1-canary.046f6ea

package/src/Toast/ToastViewport.tsx

@@ -2,6 +2,18 @@
 
 'use client';
 
+/**
+ * @file ToastViewport.tsx
+ * @input Uses React state/effects, ToastContext, useAnnounce, viewport tokens,
+ *   and placement-derived motion variables
+ * @output Exports the ToastViewport provider, stack, live announcement dispatch,
+ *   focus handoff, safe-area-aware edge gutters, and motion context
+ * @position Core provider/imperative viewport for useToast()
+ *
+ * SYNC: When placement, stacking, focus, announcement, or safe-area behavior
+ *   changes, update ToastViewport.test.tsx, Toast.doc.mjs, and Toast.stories.tsx.
+ */
+
 import {
   isValidElement,
   useCallback,
@@ -17,18 +29,35 @@ import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {useAnnounce} from '../hooks/useAnnounce';
-import {Toast} from './Toast';
+import {ToastSurface} from './Toast';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
 import {useTranslator} from '../i18n';
 
+const SAFE_AREA_INLINE_START = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px))`;
+const SAFE_AREA_INLINE_END = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px))`;
+const SAFE_AREA_BLOCK_START = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))`;
+const SAFE_AREA_BLOCK_END = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-bottom, 0px))`;
+const TOAST_EDGE_DRIFT = spacingVars['--spacing-2'];
+const TOAST_EDGE_DRIFT_NEGATIVE = `calc(-1 * ${TOAST_EDGE_DRIFT})`;
+
 const styles = stylex.create({
   viewport: {
     position: 'fixed',
     zIndex: 500,
     display: 'flex',
+    boxSizing: 'border-box',
     flexDirection: 'column',
-    padding: spacingVars['--spacing-4'],
+    paddingBlockStart: SAFE_AREA_BLOCK_START,
+    paddingBlockEnd: SAFE_AREA_BLOCK_END,
+    paddingInlineStart: {
+      default: SAFE_AREA_INLINE_START,
+      ':is([dir="rtl"] *)': SAFE_AREA_INLINE_END,
+    },
+    paddingInlineEnd: {
+      default: SAFE_AREA_INLINE_END,
+      ':is([dir="rtl"] *)': SAFE_AREA_INLINE_START,
+    },
     pointerEvents: 'none',
     // Reset popover styles — the popover attribute puts us in the top
     // layer (above dialogs), but we don't want its default styles.
@@ -40,25 +69,29 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     overflow: 'visible',
   },
-  bottomEnd: {bottom: 0, insetInlineEnd: 0, alignItems: 'flex-end'},
-  bottomStart: {bottom: 0, insetInlineStart: 0, alignItems: 'flex-start'},
+  viewportInlineSpan: {
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
+  },
+  bottomEnd: {bottom: 0, alignItems: 'flex-end'},
+  bottomStart: {bottom: 0, alignItems: 'flex-start'},
   topEnd: {
     top: 0,
-    insetInlineEnd: 0,
     alignItems: 'flex-end',
     flexDirection: 'column-reverse',
   },
   topStart: {
     top: 0,
-    insetInlineStart: 0,
     alignItems: 'flex-start',
     flexDirection: 'column-reverse',
   },
   toastWrapper: {
     pointerEvents: 'auto',
     display: 'grid',
+    width: '100%',
+    maxWidth: 400,
+    minWidth: 0,
     gridTemplateRows: '1fr',
-    paddingBlockEnd: spacingVars['--spacing-3'],
     transitionProperty: 'grid-template-rows, padding',
     transitionDuration: {
       default: durationVars['--duration-fast'],
@@ -70,11 +103,33 @@ const styles = stylex.create({
       paddingBlockEnd: 0,
     },
   },
+  toastWrapperFromBottom: {
+    '--_toast-slide-y': TOAST_EDGE_DRIFT,
+  },
+  toastWrapperFromTop: {
+    '--_toast-slide-y': TOAST_EDGE_DRIFT_NEGATIVE,
+  },
+  // The inter-toast gap is padding on each wrapper so it collapses with the
+  // grid track. The wrapper nearest the viewport edge drops that padding; the
+  // child flips because top stacks use column-reverse.
+  toastWrapperGap: {
+    paddingBlockEnd: {default: spacingVars['--spacing-2'], ':last-child': 0},
+  },
+  toastWrapperGapReversed: {
+    paddingBlockEnd: {default: spacingVars['--spacing-2'], ':first-child': 0},
+  },
   toastWrapperExiting: {
     gridTemplateRows: '0fr',
     paddingBlockEnd: 0,
   },
   toastWrapperInner: {
+    width: '100%',
+    maxWidth: '100%',
+    minWidth: 0,
+    minHeight: 0,
+    // Required for the 1fr -> 0fr exit collapse to hide the shrinking Toast.
+    // This preserves main's paint containment; browser-chrome behavior is not
+    // changed or claimed by this responsive-layout fix.
     overflow: 'hidden',
   },
 });
@@ -104,6 +159,7 @@ function getNodeText(node: ReactNode): string {
 
 export interface ToastViewportProps {
   position?: ToastPosition;
+  /** Maximum number of visible toasts. @default 5 */
   maxVisible?: number;
   inset?: {top?: number; bottom?: number; start?: number; end?: number};
   /**
@@ -341,6 +397,7 @@ export function ToastViewport({
   );
 
   const visibleToasts = toasts.slice(-maxVisible);
+
   const insetStyle: React.CSSProperties = {};
   if (inset?.top) {
     insetStyle.top = inset.top;
@@ -417,21 +474,31 @@ export function ToastViewport({
         : position === 'bottomStart'
           ? styles.bottomStart
           : styles.bottomEnd;
+  const isReversed = position === 'topEnd' || position === 'topStart';
+  const toastWrapperPositionStyle = isReversed
+    ? styles.toastWrapperFromTop
+    : styles.toastWrapperFromBottom;
+  const gapStyle = isReversed
+    ? styles.toastWrapperGapReversed
+    : styles.toastWrapperGap;
 
   return (
     <ToastContext value={contextValue}>
       {children}
       <div
         ref={viewportRef}
-        role="region"
-        aria-label={t('@astryx.toast.viewport')}
-        tabIndex={-1}
+        role={hasToasts ? 'region' : undefined}
+        aria-label={hasToasts ? t('@astryx.toast.viewport') : undefined}
+        tabIndex={hasToasts ? -1 : undefined}
         // popover="manual" promotes to the top layer (above dialogs).
         // Omitted inside dialogs where the viewport is already in a top layer.
         popover={isTopLayer ? 'manual' : undefined}
-        {...mergeProps(stylex.props(styles.viewport, posStyle), {
-          style: Object.keys(insetStyle).length > 0 ? insetStyle : undefined,
-        })}>
+        {...mergeProps(
+          stylex.props(styles.viewport, styles.viewportInlineSpan, posStyle),
+          {
+            style: Object.keys(insetStyle).length > 0 ? insetStyle : undefined,
+          },
+        )}>
         {visibleToasts.map(entry => {
           const o = entry.options;
           const type = o.type ?? 'info';
@@ -444,6 +511,8 @@ export function ToastViewport({
               data-toast-id={entry.id}
               {...stylex.props(
                 styles.toastWrapper,
+                toastWrapperPositionStyle,
+                gapStyle,
                 isExiting && styles.toastWrapperExiting,
               )}
               onTransitionEnd={
@@ -456,14 +525,16 @@ export function ToastViewport({
                   : undefined
               }>
               <div {...stylex.props(styles.toastWrapperInner)}>
-                <Toast
+                <ToastSurface
                   type={type}
                   body={o.body}
                   endContent={o.endContent}
                   isAutoHide={isAutoHide}
                   autoHideDuration={dur}
                   isExiting={isExiting}
+                  gestureDirection={isReversed ? -1 : 1}
                   onDismiss={reason => removeToast(entry.id, reason)}
+                  renderContent={o.renderContent}
                 />
               </div>
             </div>

package/src/Toast/index.ts

@@ -12,6 +12,8 @@ export type {
   ToastOptions,
   ToastDismissFn,
   ShowToastFn,
+  ToastContentRenderProps,
+  ToastContentRenderFn,
 } from './types';
 
 // Exported for LayerProvider integration

package/src/Toast/types.ts

@@ -6,11 +6,7 @@ import type {ReactNode} from 'react';
 export type ToastType = 'info' | 'error';
 
 /** Position for the toast stack relative to the viewport. */
-export type ToastPosition =
-  | 'topEnd'
-  | 'topStart'
-  | 'bottomEnd'
-  | 'bottomStart';
+export type ToastPosition = 'topEnd' | 'topStart' | 'bottomEnd' | 'bottomStart';
 
 /** Behavior when a toast with the same uniqueID already exists. */
 export type ToastCollisionBehavior = 'overwrite' | 'ignore';
@@ -39,6 +35,21 @@ export interface ToastOptions {
   autoHideDuration?: number;
   /** Content rendered at the end of the toast (trailing slot). */
   endContent?: ReactNode;
+  /**
+   * Replaces the content of this toast's card with your own layout.
+   *
+   * Astryx keeps the card, live-region role and auto-hide behavior, then hands
+   * the renderer this toast's content, resolved settings and `dismiss`
+   * callback. The renderer owns every control inside its layout; call
+   * `dismiss` from the control that should close the toast. Astryx does not
+   * inject a fallback control into custom content.
+   *
+   * Per-toast rather than app-wide on purpose. An app that wants every one of
+   * its toasts to share a layout wraps `useToast()` once and passes this on
+   * every call; a toast raised by library code that knows nothing about that
+   * wrapper then renders as an ordinary Astryx toast.
+   */
+  renderContent?: ToastContentRenderFn;
 
   /** Unique identifier for deduplication. */
   uniqueID?: string;
@@ -54,6 +65,33 @@ export interface ToastOptions {
 /** Function to programmatically dismiss a toast. */
 export type ToastDismissFn = () => void;
 
+/** Values passed to a custom toast content renderer. */
+export interface ToastContentRenderProps {
+  /** Primary message content, as passed to `showToast`. */
+  body: ReactNode;
+  /** Trailing content, as passed to `showToast`. Place it in your layout. */
+  endContent?: ReactNode;
+  /** Resolved toast type — `'error'` also makes the live region assertive. */
+  type: ToastType;
+  /** Whether this toast will dismiss itself. */
+  isAutoHide: boolean;
+  /** Milliseconds until auto-dismiss, when `isAutoHide`. */
+  autoHideDuration: number;
+  /**
+   * Dismisses this toast with reason `'manual'`. Pass it through any nested
+   * components that need to close the toast.
+   */
+  dismiss: ToastDismissFn;
+}
+
+/**
+ * Renders the content of one toast inside Astryx's card — see
+ * `ToastOptions.renderContent`.
+ */
+export type ToastContentRenderFn = (
+  toast: ToastContentRenderProps,
+) => ReactNode;
+
 /** Function returned by useToast to show toasts. */
 export type ShowToastFn = (options: ToastOptions) => ToastDismissFn;
 

package/src/Toast/useToastGesture.ts

@@ -0,0 +1,361 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useToastGesture.ts
+ * @input Uses a resolved Toast edge direction, timer pause/resume hooks,
+ *   dismissal callback, enabled state, and interactive-descendant policy
+ * @output Returns the Toast card root ref and touch/pen gesture bindings
+ * @position Internal Toast gesture unit; attached to the Toast card root
+ */
+
+import {useCallback, useEffect, useRef} from 'react';
+import type {PointerEvent as ReactPointerEvent, RefObject} from 'react';
+
+const DRAG_PROMOTION_SLOP = 8;
+const SWIPE_DISMISS_RATIO = 0.4;
+const FLICK_MIN_DISTANCE = 48;
+const FLICK_VELOCITY = 1.2;
+const VERTICAL_INTENT_RATIO = 1.2;
+const SWIPE_EXIT_DISTANCE = '120%';
+const SWIPE_ACTIVE_FADE_MAX = 0.4;
+const SWIPE_ACTIVE_SCALE_MAX = 0.02;
+
+export type ToastGestureDirection = 1 | -1;
+
+interface GesturePoint {
+  pointerId: number;
+  clientX: number;
+  clientY: number;
+}
+
+interface GestureState {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  startTime: number;
+  direction: ToastGestureDirection;
+  intent: 'pending' | 'vertical' | 'opposite';
+  pausedTimer: boolean;
+  surfaceSize: number;
+  dismissThreshold: number;
+}
+
+interface UseToastGestureOptions {
+  direction: ToastGestureDirection;
+  enabled: boolean;
+  canPauseTimer: boolean;
+  isTimerPaused: () => boolean;
+  pauseTimer: () => void;
+  resumeTimer: () => void;
+  dismiss: () => void;
+  shouldIgnoreTarget: (
+    target: EventTarget | null,
+    root: HTMLElement,
+  ) => boolean;
+}
+
+interface ToastGestureBindings {
+  onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onPointerUp: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onPointerCancel: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onLostPointerCapture: (event: ReactPointerEvent<HTMLDivElement>) => void;
+}
+
+interface UseToastGestureResult {
+  rootRef: RefObject<HTMLDivElement | null>;
+  bindings: ToastGestureBindings;
+}
+
+function swipeProgressValue(travel: number, surfaceSize: number): number {
+  return Math.min(Math.max(travel / surfaceSize, 0), 1);
+}
+
+function clearTransientStyles(root: HTMLElement): void {
+  root.style.removeProperty('transition-duration');
+  root.style.removeProperty('--_toast-swipe-y');
+  root.style.removeProperty('--_toast-swipe-exit-y');
+  root.style.removeProperty('--_toast-swipe-opacity');
+  root.style.removeProperty('--_toast-swipe-scale');
+}
+
+export function useToastGesture({
+  direction,
+  enabled,
+  canPauseTimer,
+  isTimerPaused,
+  pauseTimer,
+  resumeTimer,
+  dismiss,
+  shouldIgnoreTarget,
+}: UseToastGestureOptions): UseToastGestureResult {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const gestureRef = useRef<GestureState | null>(null);
+
+  const resetGesture = useCallback(
+    (shouldResume: boolean) => {
+      const root = rootRef.current;
+      const state = gestureRef.current;
+      gestureRef.current = null;
+      if (root) {
+        clearTransientStyles(root);
+      }
+      if (shouldResume && state?.pausedTimer) {
+        resumeTimer();
+      }
+    },
+    [resumeTimer],
+  );
+
+  const beginGesture = useCallback(
+    (point: GesturePoint, target: EventTarget | null): boolean => {
+      const root = rootRef.current;
+      if (
+        !root ||
+        !enabled ||
+        gestureRef.current != null ||
+        shouldIgnoreTarget(target, root)
+      ) {
+        return false;
+      }
+      const pausedTimer = canPauseTimer && !isTimerPaused();
+      if (pausedTimer) {
+        pauseTimer();
+      }
+      const surfaceSize = Math.max(root.getBoundingClientRect().height, 1);
+      gestureRef.current = {
+        pointerId: point.pointerId,
+        startX: point.clientX,
+        startY: point.clientY,
+        startTime: Date.now(),
+        direction,
+        intent: 'pending',
+        pausedTimer,
+        surfaceSize,
+        dismissThreshold: Math.max(
+          surfaceSize * SWIPE_DISMISS_RATIO,
+          FLICK_MIN_DISTANCE,
+        ),
+      };
+      return true;
+    },
+    [
+      canPauseTimer,
+      direction,
+      enabled,
+      isTimerPaused,
+      pauseTimer,
+      shouldIgnoreTarget,
+    ],
+  );
+
+  const moveGesture = useCallback(
+    (
+      point: GesturePoint,
+      preventDefault: () => void,
+      releaseCapture?: () => void,
+    ) => {
+      const state = gestureRef.current;
+      const root = rootRef.current;
+      if (!state || !root || point.pointerId !== state.pointerId) {
+        return;
+      }
+      const deltaX = point.clientX - state.startX;
+      const deltaY = point.clientY - state.startY;
+      const absX = Math.abs(deltaX);
+      const absY = Math.abs(deltaY);
+      if (state.intent === 'pending') {
+        if (absX > DRAG_PROMOTION_SLOP && absX > absY) {
+          releaseCapture?.();
+          resetGesture(true);
+          return;
+        }
+        if (
+          absY <= DRAG_PROMOTION_SLOP ||
+          absY <= absX * VERTICAL_INTENT_RATIO
+        ) {
+          return;
+        }
+        state.intent = deltaY * state.direction > 0 ? 'vertical' : 'opposite';
+        if (state.intent === 'opposite') {
+          releaseCapture?.();
+          resetGesture(true);
+          return;
+        }
+        root.style.setProperty('transition-duration', '0s');
+      }
+      preventDefault();
+      const travel = Math.max(0, deltaY * state.direction);
+      const progress = swipeProgressValue(travel, state.surfaceSize);
+      root.style.setProperty(
+        '--_toast-swipe-y',
+        `${travel * state.direction}px`,
+      );
+      root.style.setProperty(
+        '--_toast-swipe-opacity',
+        (1 - progress * SWIPE_ACTIVE_FADE_MAX).toFixed(3),
+      );
+      root.style.setProperty(
+        '--_toast-swipe-scale',
+        (1 - progress * SWIPE_ACTIVE_SCALE_MAX).toFixed(3),
+      );
+    },
+    [resetGesture],
+  );
+
+  const endGesture = useCallback(
+    (point: GesturePoint) => {
+      const state = gestureRef.current;
+      const root = rootRef.current;
+      if (!state || !root || point.pointerId !== state.pointerId) {
+        return;
+      }
+      const travel = Math.max(
+        0,
+        (point.clientY - state.startY) * state.direction,
+      );
+      const elapsed = Math.max(1, Date.now() - state.startTime);
+      const isDismissed =
+        state.intent === 'vertical' &&
+        (travel >= state.dismissThreshold ||
+          (travel >= FLICK_MIN_DISTANCE && travel / elapsed > FLICK_VELOCITY));
+
+      gestureRef.current = null;
+      root.style.removeProperty('transition-duration');
+      if (isDismissed) {
+        root.style.setProperty(
+          '--_toast-swipe-exit-y',
+          state.direction === 1
+            ? SWIPE_EXIT_DISTANCE
+            : `calc(-1 * ${SWIPE_EXIT_DISTANCE})`,
+        );
+        dismiss();
+        return;
+      }
+      clearTransientStyles(root);
+      if (state.pausedTimer) {
+        resumeTimer();
+      }
+    },
+    [dismiss, resumeTimer],
+  );
+
+  const handlePointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (
+        event.pointerType === 'pen' &&
+        (event.button == null || event.button === 0) &&
+        beginGesture(event, event.target)
+      ) {
+        rootRef.current?.setPointerCapture?.(event.pointerId);
+      }
+    },
+    [beginGesture],
+  );
+
+  const handlePointerMove = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (event.pointerType !== 'pen') {
+        return;
+      }
+      moveGesture(
+        event,
+        () => event.preventDefault(),
+        () => rootRef.current?.releasePointerCapture?.(event.pointerId),
+      );
+    },
+    [moveGesture],
+  );
+
+  const handlePointerUp = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (event.pointerType !== 'pen') {
+        return;
+      }
+      rootRef.current?.releasePointerCapture?.(event.pointerId);
+      endGesture(event);
+    },
+    [endGesture],
+  );
+
+  const handlePointerCancel = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (
+        event.pointerType === 'pen' &&
+        gestureRef.current?.pointerId === event.pointerId
+      ) {
+        resetGesture(true);
+      }
+    },
+    [resetGesture],
+  );
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root || !enabled) {
+      return;
+    }
+    const point = (touch: Touch): GesturePoint => ({
+      pointerId: touch.identifier,
+      clientX: touch.clientX,
+      clientY: touch.clientY,
+    });
+    const changedTouch = (event: TouchEvent) => {
+      const pointerId = gestureRef.current?.pointerId;
+      return pointerId == null
+        ? undefined
+        : [...event.changedTouches].find(
+            touch => touch.identifier === pointerId,
+          );
+    };
+    const handleTouchStart = (event: TouchEvent) => {
+      const touch = event.touches.length === 1 ? event.changedTouches[0] : null;
+      if (touch) {
+        beginGesture(point(touch), event.target);
+      }
+    };
+    const handleTouchMove = (event: TouchEvent) => {
+      const touch = changedTouch(event);
+      if (touch) {
+        moveGesture(point(touch), () => {
+          if (event.cancelable) {
+            event.preventDefault();
+          }
+        });
+      }
+    };
+    const handleTouchEnd = (event: TouchEvent) => {
+      const touch = changedTouch(event);
+      if (touch) {
+        endGesture(point(touch));
+      } else if (event.touches.length === 0) {
+        resetGesture(true);
+      }
+    };
+    const handleTouchCancel = () => resetGesture(true);
+
+    root.addEventListener('touchstart', handleTouchStart, {passive: true});
+    root.addEventListener('touchmove', handleTouchMove, {passive: false});
+    root.addEventListener('touchend', handleTouchEnd, {passive: true});
+    root.addEventListener('touchcancel', handleTouchCancel, {passive: true});
+    return () => {
+      root.removeEventListener('touchstart', handleTouchStart);
+      root.removeEventListener('touchmove', handleTouchMove);
+      root.removeEventListener('touchend', handleTouchEnd);
+      root.removeEventListener('touchcancel', handleTouchCancel);
+    };
+  }, [beginGesture, enabled, endGesture, moveGesture, resetGesture]);
+
+  return {
+    rootRef,
+    bindings: {
+      onPointerDown: handlePointerDown,
+      onPointerMove: handlePointerMove,
+      onPointerUp: handlePointerUp,
+      onPointerCancel: handlePointerCancel,
+      onLostPointerCapture: handlePointerCancel,
+    },
+  };
+}