@hanzogui/toast 3.0.2 → 7.0.0

package/src/ToastViewport.tsx

@@ -1,7 +1,7 @@
 import { AnimatePresence } from '@hanzogui/animate-presence'
 import { useComposedRefs } from '@hanzogui/compose-refs'
 import { isWeb } from '@hanzogui/constants'
-import type { GetProps, GuiElement } from '@hanzogui/core'
+import type { GetProps, HanzoguiElement } from '@hanzogui/core'
 import { styled } from '@hanzogui/core'
 import { PortalHost } from '@hanzogui/portal'
 import { YStack } from '@hanzogui/stacks'
@@ -28,7 +28,7 @@ const ToastViewportWrapperFrame = styled(YStack, {
         bottom: 0,
         left: 0,
         right: 0,
-        position: 'fixed',
+        position: isWeb ? ('fixed' as any) : 'absolute',
         maxWidth: '100%',
         tabIndex: 0,
         zIndex: 100000,
@@ -37,7 +37,7 @@ const ToastViewportWrapperFrame = styled(YStack, {
   } as const,
 
   defaultVariants: {
-    unstyled: process.env.HANZO_GUI_HEADLESS === '1',
+    unstyled: process.env.HANZOGUI_HEADLESS === '1',
   },
 })
 
@@ -48,14 +48,14 @@ const ToastViewportFrame = styled(YStack, {
     unstyled: {
       false: {
         pointerEvents: 'box-none',
-        position: 'fixed',
+        position: isWeb ? ('fixed' as any) : 'absolute',
         maxWidth: '100%',
       },
     },
   } as const,
 
   defaultVariants: {
-    unstyled: process.env.HANZO_GUI_HEADLESS === '1',
+    unstyled: process.env.HANZOGUI_HEADLESS === '1',
   },
 })
 
@@ -81,7 +81,7 @@ type ToastViewportProps = ToastViewportFrameProps & {
    */
   multipleToasts?: boolean
   /**
-   * When true, uses a portal to render at the very top of the root GuiProvider.
+   * When true, uses a portal to render at the very top of the root HanzoguiProvider.
    */
   portalToRoot?: boolean
 }
@@ -106,7 +106,7 @@ const ToastViewport = React.memo(
       const wrapperRef = React.useRef<HTMLDivElement>(null)
       const ref = React.useRef<HTMLDivElement>(null)
       const onViewportChange = React.useCallback(
-        (el: GuiElement) => {
+        (el: HanzoguiElement) => {
           if (context.viewports[name] !== el) context.onViewportChange(name, el)
         },
         [name, context.viewports]
@@ -262,6 +262,7 @@ const ToastViewport = React.memo(
       const contents = (
         <ToastViewportWrapperFrame
           ref={wrapperRef as any}
+          // biome-ignore lint/a11y/useSemanticElements: <explanation>
           role="region"
           aria-label={label.replace('{hotkey}', hotkeyLabel)}
           // // Ensure virtual cursor from landmarks menus triggers focus/blur for pause/resume
@@ -363,7 +364,7 @@ const FocusProxy = React.forwardRef<FocusProxyElement, ScopedProps<FocusProxyPro
         {...proxyProps}
         ref={forwardedRef}
         // Avoid page scrolling when focus is on the focus proxy
-        position="fixed"
+        position={isWeb ? ('fixed' as any) : 'absolute'}
         onFocus={(event) => {
           if (!isWeb) return
           const prevFocusedElement = event.relatedTarget as HTMLElement | null
@@ -379,7 +380,7 @@ FocusProxy.displayName = FOCUS_PROXY_NAME
 
 /* -----------------------------------------------------------------------------------------------*/
 
-function focusFirst(candidates: GuiElement[]) {
+function focusFirst(candidates: HanzoguiElement[]) {
   if (!isWeb) return
   const previouslyFocusedElement = document.activeElement
   return candidates.some((candidate) => {
@@ -400,7 +401,7 @@ function focusFirst(candidates: GuiElement[]) {
  * See: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker
  * Credit: https://github.com/discord/focus-layers/blob/master/src/util/wrapFocus.tsx#L1
  */
-function getTabbableCandidates(container: GuiElement) {
+function getTabbableCandidates(container: HanzoguiElement) {
   if (!isWeb) return []
   const containerHtml = container as HTMLElement
   const nodes: HTMLElement[] = []

package/src/Toaster.tsx

@@ -0,0 +1,181 @@
+/**
+ * Toaster — drop-in all-in-one toast component.
+ * Thin wrapper around Toast + Toast.Viewport + Toast.List (composable API).
+ */
+
+import type { HanzoguiElement } from '@hanzogui/core'
+import * as React from 'react'
+import { Toast } from './ToastComposable'
+import type { ToastPosition } from './ToastComposable'
+import type { SwipeDirection } from './ToastProvider'
+import type { ExternalToast } from './ToastState'
+import type { BurntToastOptions } from './types'
+
+export type ToasterPosition = ToastPosition
+
+export interface ToasterProps {
+  /**
+   * Position of the toasts on screen
+   * @default 'bottom-right'
+   */
+  position?: ToasterPosition
+
+  /**
+   * Expand toasts on hover to show all
+   * @default false
+   */
+  expand?: boolean
+
+  /**
+   * Number of toasts visible at once
+   * @default 4
+   */
+  visibleToasts?: number
+
+  /**
+   * Gap between toasts in pixels
+   * @default 14
+   */
+  gap?: number
+
+  /**
+   * Default duration for toasts in ms
+   * @default 4000
+   */
+  duration?: number
+
+  /**
+   * Offset from screen edge in pixels
+   * @default 24
+   */
+  offset?: number | { top?: number; right?: number; bottom?: number; left?: number }
+
+  /**
+   * Hotkey to focus toast viewport
+   * @default ['altKey', 'KeyT']
+   */
+  hotkey?: string[]
+
+  /**
+   * Direction(s) toasts can be swiped to dismiss.
+   * 'auto' detects based on position (swipe toward nearest edge).
+   * @default 'auto'
+   */
+  swipeDirection?: SwipeDirection
+
+  /**
+   * Distance in pixels swipe must pass to dismiss
+   * @default 50
+   */
+  swipeThreshold?: number
+
+  /**
+   * Show close button on toasts
+   * @default false
+   */
+  closeButton?: boolean
+
+  /**
+   * Theme for toasts (auto-detected if not set)
+   */
+  theme?: 'light' | 'dark' | 'system'
+
+  /**
+   * Custom icons for toast types
+   */
+  icons?: {
+    success?: React.ReactNode
+    error?: React.ReactNode
+    warning?: React.ReactNode
+    info?: React.ReactNode
+    loading?: React.ReactNode
+    close?: React.ReactNode
+  }
+
+  /**
+   * Default toast options
+   */
+  toastOptions?: ExternalToast
+
+  /**
+   * Container aria label for screen readers
+   * @default 'Notifications'
+   */
+  containerAriaLabel?: string
+
+  /**
+   * When true, uses burnt native OS toasts on mobile instead of RN views.
+   * @default false
+   */
+  native?: boolean
+
+  /**
+   * Options for burnt native toasts on mobile
+   */
+  burntOptions?: Omit<BurntToastOptions, 'title' | 'message' | 'duration'>
+
+  /**
+   * Options for web Notification API
+   */
+  notificationOptions?: NotificationOptions
+
+  /**
+   * Force reduced motion mode (disables animations)
+   */
+  reducedMotion?: boolean
+}
+
+export const Toaster = React.forwardRef<HanzoguiElement, ToasterProps>(
+  function Toaster(props, ref) {
+    const {
+      position = 'bottom-right',
+      expand = false,
+      visibleToasts,
+      gap,
+      duration,
+      offset,
+      hotkey,
+      swipeDirection,
+      swipeThreshold,
+      closeButton,
+      theme,
+      icons,
+      toastOptions,
+      containerAriaLabel = 'Notifications',
+      native,
+      burntOptions,
+      notificationOptions,
+      reducedMotion,
+    } = props
+
+    return (
+      <Toast
+        position={position}
+        expand={expand}
+        visibleToasts={visibleToasts}
+        gap={gap}
+        duration={toastOptions?.duration ?? duration}
+        swipeDirection={swipeDirection}
+        swipeThreshold={swipeThreshold}
+        closeButton={closeButton}
+        theme={theme}
+        icons={icons}
+        native={native}
+        burntOptions={burntOptions}
+        notificationOptions={notificationOptions}
+        reducedMotion={reducedMotion}
+      >
+        <Toast.Viewport
+          ref={ref}
+          offset={offset}
+          hotkey={hotkey}
+          label={containerAriaLabel}
+        >
+          <Toast.List />
+        </Toast.Viewport>
+      </Toast>
+    )
+  }
+)
+
+Toaster.displayName = 'Toaster'

package/src/createNativeToast.native.tsx

@@ -27,3 +27,7 @@ export const hideNativeToast: HideNativeToastsFn = () => {
   if (!burnt.isEnabled) return
   burnt.state.dismissAllAlerts!()
 }
+
+export async function requestNotificationPermission(): Promise<null> {
+  return null
+}

package/src/createNativeToast.tsx

@@ -5,40 +5,23 @@ export const createNativeToast: CreateNativeToastsFn = (
   { message, notificationOptions }
 ) => {
   if (!('Notification' in window)) {
-    console.error('This browser does not support notifications')
     return false
   }
 
-  if (Notification.permission === 'denied') return false
-  const showNotification = () => {
-    const notification = new Notification(title, {
-      body: message,
-      ...notificationOptions,
-    })
+  if (Notification.permission !== 'granted') return false
 
-    return notification
-  }
+  const notification = new Notification(title, {
+    body: message,
+    ...notificationOptions,
+  })
 
-  if (Notification.permission === 'granted') {
-    const notification = showNotification()
-    return {
-      nativeToastRef: notification,
-    }
+  return {
+    nativeToastRef: notification,
   }
-  Notification.requestPermission().then((permission) => {
-    if (permission === 'granted') {
-      const notification = showNotification()
-      return {
-        nativeToastRef: notification,
-      }
-    }
-  })
-  return true
 }
 
 export const hideNativeToast: HideNativeToastsFn = (ref) => {
   if (!('Notification' in window)) {
-    console.error('This browser does not support notifications')
     return
   }
 
@@ -46,3 +29,14 @@ export const hideNativeToast: HideNativeToastsFn = (ref) => {
     ref.close()
   }
 }
+
+/**
+ * Request notification permission from the browser.
+ * Must be called from a user gesture (click/tap handler).
+ */
+export async function requestNotificationPermission(): Promise<NotificationPermission | null> {
+  if (!('Notification' in window)) return null
+  if (Notification.permission === 'granted') return 'granted'
+  if (Notification.permission === 'denied') return 'denied'
+  return Notification.requestPermission()
+}

package/src/dispatchNativeToast.ts

@@ -0,0 +1,43 @@
+import type { ToastT } from './ToastState'
+import type { BurntToastOptions } from './types'
+import { createNativeToast } from './createNativeToast'
+
+/**
+ * Attempts to dispatch a toast via native platform API (Burnt on mobile, Notification on web).
+ * Returns true if the toast was handled natively, false if it should fall through to in-app.
+ */
+export function dispatchNativeToast(
+  toast: ToastT,
+  opts: {
+    duration: number
+    burntOptions?: Omit<BurntToastOptions, 'title' | 'message' | 'duration'>
+    notificationOptions?: NotificationOptions
+  }
+): boolean {
+  const titleText = typeof toast.title === 'function' ? toast.title() : toast.title
+  if (typeof titleText !== 'string') return false
+
+  const descText =
+    typeof toast.description === 'function' ? toast.description() : toast.description
+  const toastType = toast.type ?? 'default'
+
+  const preset: BurntToastOptions['preset'] =
+    toastType === 'error' ? 'error' : toastType === 'success' ? 'done' : 'none'
+  const haptic: BurntToastOptions['haptic'] =
+    toastType === 'error'
+      ? 'error'
+      : toastType === 'success'
+        ? 'success'
+        : toastType === 'warning'
+          ? 'warning'
+          : 'none'
+
+  const result = createNativeToast(titleText, {
+    message: typeof descText === 'string' ? descText : undefined,
+    duration: toast.duration ?? opts.duration,
+    burntOptions: { preset, haptic, ...opts.burntOptions },
+    notificationOptions: opts.notificationOptions,
+  })
+
+  return result !== false
+}

package/src/useAnimatedDragGesture.native.ts

@@ -0,0 +1,255 @@
+/**
+ * Native drag gesture handling for toast swipe-to-dismiss.
+ *
+ * Uses react-native-gesture-handler (RNGH) when available for proper gesture
+ * coordination with ScrollView and navigation. Falls back to PanResponder.
+ *
+ * Pattern: same as Sheet — RNGH is accessed through @hanzogui/native global
+ * registry, never imported directly. The gesture is created in useMemo and
+ * returns null when RNGH is not set up.
+ */
+
+import { getGestureHandler } from '@hanzogui/native'
+import * as React from 'react'
+import type { PanResponderGestureState } from 'react-native'
+import { PanResponder } from 'react-native'
+import type { SwipeDirection } from './ToastProvider'
+
+export interface UseAnimatedDragGestureOptions {
+  direction: SwipeDirection
+  threshold: number
+  disabled?: boolean
+  expanded?: boolean
+  onDragMove: (x: number, y: number) => void
+  onDragStart?: () => void
+  onDismiss: (exitDirection: 'left' | 'right' | 'up' | 'down', velocity: number) => void
+  onCancel: () => void
+}
+
+const VELOCITY_THRESHOLD = 0.11
+const GESTURE_GRANT_THRESHOLD = 10
+
+function resisted(delta: number, maxResist = 25): number {
+  if (delta >= 0) return delta
+  const pastBoundary = Math.abs(delta)
+  const resistedDistance = Math.sqrt(pastBoundary) * 2
+  return -Math.min(resistedDistance, maxResist)
+}
+
+const EXIT_DRAG_CAP = 80
+
+function cappedExit(delta: number): number {
+  if (Math.abs(delta) <= EXIT_DRAG_CAP) return delta
+  const sign = delta > 0 ? 1 : -1
+  const overshoot = Math.abs(delta) - EXIT_DRAG_CAP
+  return sign * (EXIT_DRAG_CAP + Math.sqrt(overshoot) * 2)
+}
+
+function computeOffset(
+  direction: SwipeDirection,
+  dx: number,
+  dy: number
+): { offsetX: number; offsetY: number } {
+  let offsetX = 0
+  let offsetY = 0
+
+  if (direction === 'right') {
+    offsetX = dx > 0 ? cappedExit(dx) : resisted(dx)
+  } else if (direction === 'left') {
+    offsetX = dx < 0 ? cappedExit(dx) : -resisted(-dx)
+  } else if (direction === 'down') {
+    offsetY = dy > 0 ? cappedExit(dy) : resisted(dy)
+  } else if (direction === 'up') {
+    offsetY = dy < 0 ? cappedExit(dy) : -resisted(-dy)
+  } else if (direction === 'horizontal') {
+    offsetX = cappedExit(dx)
+  } else if (direction === 'vertical') {
+    offsetY = cappedExit(dy)
+  }
+
+  return { offsetX, offsetY }
+}
+
+function computeExitDirection(
+  direction: SwipeDirection,
+  dx: number,
+  dy: number
+): 'left' | 'right' | 'up' | 'down' | null {
+  if (direction === 'right' && dx > 0) return 'right'
+  if (direction === 'left' && dx < 0) return 'left'
+  if (direction === 'horizontal') {
+    if (Math.abs(dx) > Math.abs(dy)) return dx > 0 ? 'right' : 'left'
+  }
+  if (direction === 'down' && dy > 0) return 'down'
+  if (direction === 'up' && dy < 0) return 'up'
+  if (direction === 'vertical') {
+    if (Math.abs(dy) > Math.abs(dx)) return dy > 0 ? 'down' : 'up'
+  }
+  return null
+}
+
+function shouldGrantGestureMove(dir: SwipeDirection, dx: number, dy: number): boolean {
+  const absDx = Math.abs(dx)
+  const absDy = Math.abs(dy)
+  if (
+    (dir === 'horizontal' || dir === 'left' || dir === 'right') &&
+    absDx > GESTURE_GRANT_THRESHOLD &&
+    absDx > absDy
+  ) {
+    return true
+  }
+  if (
+    (dir === 'vertical' || dir === 'up' || dir === 'down') &&
+    absDy > GESTURE_GRANT_THRESHOLD &&
+    absDy > absDx
+  ) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Single hook — always calls the same hooks in the same order.
+ * Creates RNGH gesture in useMemo (returns null if unavailable).
+ * Creates PanResponder in useMemo (returns null if RNGH is used).
+ * Consumer checks `gesture` to decide whether to wrap with GestureDetector.
+ */
+export function useAnimatedDragGesture(options: UseAnimatedDragGestureOptions) {
+  const { direction, threshold, disabled } = options
+
+  const [isDragging, setIsDragging] = React.useState(false)
+
+  const isHorizontal =
+    direction === 'left' || direction === 'right' || direction === 'horizontal'
+
+  const gestureRef = React.useRef<any>(null)
+
+  // store callbacks in refs for stable closures
+  const onDragMoveRef = React.useRef(options.onDragMove)
+  const onDragStartRef = React.useRef(options.onDragStart)
+  const onDismissRef = React.useRef(options.onDismiss)
+  const onCancelRef = React.useRef(options.onCancel)
+  onDragMoveRef.current = options.onDragMove
+  onDragStartRef.current = options.onDragStart
+  onDismissRef.current = options.onDismiss
+  onCancelRef.current = options.onCancel
+
+  // check once — RNGH availability is set at app init and never changes
+  const rnghEnabled = getGestureHandler().isEnabled
+
+  // RNGH gesture (null if not available)
+  const gesture = React.useMemo(() => {
+    if (!rnghEnabled || disabled) return null
+
+    const { Gesture } = getGestureHandler().state
+    if (!Gesture) return null
+
+    const pan = Gesture.Pan()
+      .withRef(gestureRef)
+      .shouldCancelWhenOutside(false)
+      .runOnJS(true)
+
+    if (isHorizontal) {
+      pan.activeOffsetX([-10, 10])
+      pan.failOffsetY([-20, 20])
+    } else {
+      pan.activeOffsetY([-10, 10])
+      pan.failOffsetX([-20, 20])
+    }
+
+    pan
+      .onStart(() => {
+        setIsDragging(true)
+        onDragStartRef.current?.()
+      })
+      .onChange((event: any) => {
+        const { offsetX, offsetY } = computeOffset(
+          direction,
+          event.translationX,
+          event.translationY
+        )
+        onDragMoveRef.current(offsetX, offsetY)
+      })
+      .onEnd((event: any) => {
+        const dx = event.translationX
+        const dy = event.translationY
+        const relevantDelta = isHorizontal ? dx : dy
+        const relevantVelocity = isHorizontal
+          ? Math.abs(event.velocityX / 1000)
+          : Math.abs(event.velocityY / 1000)
+
+        const passedThreshold = Math.abs(relevantDelta) >= threshold
+        const hasVelocity = relevantVelocity > VELOCITY_THRESHOLD
+        const exitDirection = computeExitDirection(direction, dx, dy)
+        const shouldDismiss = exitDirection && (passedThreshold || hasVelocity)
+
+        setIsDragging(false)
+
+        if (shouldDismiss && exitDirection) {
+          onDismissRef.current(exitDirection, relevantVelocity)
+        } else {
+          onCancelRef.current()
+        }
+      })
+      .onFinalize(() => {
+        setIsDragging(false)
+      })
+
+    return pan
+  }, [disabled, direction, threshold, isHorizontal, rnghEnabled])
+
+  // PanResponder fallback (null if RNGH is used)
+  const panResponder = React.useMemo(() => {
+    if (rnghEnabled || disabled) return null
+
+    return PanResponder.create({
+      onMoveShouldSetPanResponder: (_e, g) => {
+        return shouldGrantGestureMove(direction, g.dx, g.dy)
+      },
+      onMoveShouldSetPanResponderCapture: (_e, g) => {
+        return shouldGrantGestureMove(direction, g.dx, g.dy)
+      },
+      onPanResponderTerminationRequest: () => false,
+
+      onPanResponderGrant: () => {
+        setIsDragging(true)
+        onDragStartRef.current?.()
+      },
+
+      onPanResponderMove: (_e, g: PanResponderGestureState) => {
+        const { offsetX, offsetY } = computeOffset(direction, g.dx, g.dy)
+        onDragMoveRef.current(offsetX, offsetY)
+      },
+
+      onPanResponderRelease: (_e, g: PanResponderGestureState) => {
+        const { dx, dy, vx, vy } = g
+        const relevantDelta = isHorizontal ? dx : dy
+        const relevantVelocity = isHorizontal ? Math.abs(vx) : Math.abs(vy)
+
+        const passedThreshold = Math.abs(relevantDelta) >= threshold
+        const hasVelocity = relevantVelocity > VELOCITY_THRESHOLD
+        const exitDirection = computeExitDirection(direction, dx, dy)
+        const shouldDismiss = exitDirection && (passedThreshold || hasVelocity)
+
+        setIsDragging(false)
+
+        if (shouldDismiss && exitDirection) {
+          onDismissRef.current(exitDirection, relevantVelocity)
+        } else {
+          onCancelRef.current()
+        }
+      },
+
+      onPanResponderTerminate: () => {
+        setIsDragging(false)
+        onCancelRef.current()
+      },
+    })
+  }, [disabled, direction, threshold, isHorizontal, rnghEnabled])
+
+  return {
+    isDragging,
+    gestureHandlers: panResponder?.panHandlers ?? {},
+    gesture,
+  }
+}