@tamagui/v2-toast 2.0.0-1769464493958

package/src/Toast.tsx

@@ -0,0 +1,219 @@
+import { AnimatePresence } from '@tamagui/animate-presence'
+import type { GetProps, NativePlatform, NativeValue, TamaguiElement } from '@tamagui/core'
+import { styled, useEvent } from '@tamagui/core'
+import { composeEventHandlers, withStaticProperties } from '@tamagui/helpers'
+import { YStack } from '@tamagui/stacks'
+import { SizableText } from '@tamagui/text'
+import { useControllableState } from '@tamagui/use-controllable-state'
+import * as React from 'react'
+import { ToastAnnounceExclude } from './ToastAnnounce'
+import type { CustomData } from './ToastImperative'
+import { useToast, useToastController, useToastState } from './ToastImperative'
+import type { ToastExtraProps, ToastProps } from './ToastImpl'
+import { ToastImpl, ToastImplFrame, useToastInteractiveContext } from './ToastImpl'
+import type { ScopedProps, ToastProviderProps } from './ToastProvider'
+import { ToastProvider } from './ToastProvider'
+import type { ToastViewportProps } from './ToastViewport'
+import { ToastViewport } from './ToastViewport'
+
+/* -------------------------------------------------------------------------------------------------
+ * ToastTitle
+ * -----------------------------------------------------------------------------------------------*/
+
+const TITLE_NAME = 'ToastTitle'
+
+const ToastTitle = styled(SizableText, {
+  name: TITLE_NAME,
+
+  variants: {
+    unstyled: {
+      false: {
+        color: '$color',
+        size: '$4',
+      },
+    },
+  } as const,
+
+  defaultVariants: {
+    unstyled: process.env.TAMAGUI_HEADLESS === '1',
+  },
+})
+
+type ToastTitleProps = GetProps<typeof ToastTitle>
+
+/* -------------------------------------------------------------------------------------------------
+ * ToastDescription
+ * -----------------------------------------------------------------------------------------------*/
+
+const DESCRIPTION_NAME = 'ToastDescription'
+
+const ToastDescription = styled(SizableText, {
+  name: DESCRIPTION_NAME,
+
+  variants: {
+    unstyled: {
+      false: {
+        color: '$color11',
+        size: '$1',
+      },
+    },
+  } as const,
+
+  defaultVariants: {
+    unstyled: process.env.TAMAGUI_HEADLESS === '1',
+  },
+})
+
+type ToastDescriptionProps = GetProps<typeof ToastDescription>
+
+/* -------------------------------------------------------------------------------------------------
+ * ToastAction
+ * -----------------------------------------------------------------------------------------------*/
+
+const ACTION_NAME = 'ToastAction'
+
+type ToastActionProps = ScopedProps<
+  ToastCloseProps & {
+    /**
+     * A short description for an alternate way to carry out the action. For screen reader users
+     * who will not be able to navigate to the button easily/quickly.
+     * @example <ToastAction altText="Goto account settings to updgrade">Upgrade</ToastAction>
+     * @example <ToastAction altText="Undo (Alt+U)">Undo</ToastAction>
+     */
+    altText: string
+  }
+>
+
+const ToastAction = React.forwardRef<TamaguiElement, ScopedProps<ToastActionProps>>(
+  function ToastAction(props, forwardedRef) {
+    const { altText, ...actionProps } = props
+    if (!altText) return null
+    return (
+      <ToastAnnounceExclude altText={altText} asChild>
+        <ToastClose {...actionProps} ref={forwardedRef} />
+      </ToastAnnounceExclude>
+    )
+  }
+)
+
+ToastAction.propTypes = {
+  altText(props) {
+    if (!props.altText) {
+      return new Error(`Missing prop \`altText\` expected on \`${ACTION_NAME}\``)
+    }
+    return null
+  },
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ToastClose
+ * -----------------------------------------------------------------------------------------------*/
+
+const CLOSE_NAME = 'ToastClose'
+
+const ToastCloseFrame = styled(YStack, {
+  name: CLOSE_NAME,
+  render: 'button',
+})
+
+type ToastCloseFrameProps = GetProps<typeof ToastCloseFrame>
+type ToastCloseProps = ScopedProps<ToastCloseFrameProps & {}>
+
+const ToastClose = React.forwardRef<TamaguiElement, ToastCloseProps>(
+  function ToastClose(props, forwardedRef) {
+    const { scope, ...closeProps } = props
+    const interactiveContext = useToastInteractiveContext(scope)
+
+    return (
+      <ToastAnnounceExclude asChild>
+        <ToastCloseFrame
+          aria-label="Close"
+          {...closeProps}
+          ref={forwardedRef}
+          onPress={composeEventHandlers(props.onPress as any, interactiveContext.onClose)}
+        />
+      </ToastAnnounceExclude>
+    )
+  }
+)
+
+/* -------------------------------------------------------------------------------------------------
+ * Toast
+ * -----------------------------------------------------------------------------------------------*/
+
+const ToastComponent = ToastImplFrame.styleable<ToastExtraProps>(
+  function Toast(props, forwardedRef) {
+    const { forceMount, open: openProp, defaultOpen, onOpenChange, ...toastProps } = props
+    const [open, setOpen] = useControllableState({
+      prop: openProp,
+      defaultProp: defaultOpen ?? true,
+      onChange: onOpenChange,
+      strategy: 'most-recent-wins',
+    })
+
+    const currentToast = useToastState()
+    const { hide } = useToastController()
+
+    const id = React.useId()
+    const onPause = useEvent(props.onPause)
+    const onResume = useEvent(props.onResume)
+    const isHide = currentToast?.hide === true
+    const shouldShow = (forceMount || open) && !isHide
+
+    return (
+      <AnimatePresence key={id}>
+        {shouldShow ? (
+          <ToastImpl
+            id={id}
+            open={open}
+            {...toastProps}
+            ref={forwardedRef}
+            onClose={() => {
+              setOpen(false)
+              hide()
+            }}
+            onPause={onPause}
+            onResume={onResume}
+            onSwipeEnd={composeEventHandlers(props.onSwipeEnd, (event) => {
+              setOpen(false)
+            })}
+          />
+        ) : null}
+      </AnimatePresence>
+    )
+  }
+)
+
+const Toast = withStaticProperties(ToastComponent, {
+  Title: ToastTitle,
+  Description: ToastDescription,
+  Action: ToastAction,
+  Close: ToastClose,
+})
+
+/* ---------------------------------------------------------------------------------------------- */
+
+export {
+  Toast,
+  ToastProvider,
+  ToastViewport,
+  //
+  // imperative
+  useToast,
+  useToastController,
+  useToastState,
+}
+export type {
+  // imperative
+  CustomData,
+  ToastActionProps,
+  ToastCloseProps,
+  ToastDescriptionProps,
+  NativePlatform as ToastNativePlatform,
+  // backwards
+  NativeValue as ToastNativeValue,
+  ToastProps,
+  ToastProviderProps,
+  ToastTitleProps,
+  ToastViewportProps,
+}

package/src/ToastAnnounce.tsx

@@ -0,0 +1,102 @@
+import { useIsomorphicLayoutEffect } from '@tamagui/constants'
+import type { GetProps, TamaguiElement } from '@tamagui/core'
+import { View, Text, styled, useEvent } from '@tamagui/core'
+import { Portal } from '@tamagui/portal'
+import { startTransition } from '@tamagui/start-transition'
+import { VisuallyHidden } from '@tamagui/visually-hidden'
+import * as React from 'react'
+
+import type { ScopedProps } from './ToastProvider'
+import { useToastProviderContext } from './ToastProvider'
+
+const ToastAnnounceExcludeFrame = styled(View, {
+  name: 'ToastAnnounceExclude',
+})
+
+type ToastAnnounceExcludeFrameProps = GetProps<typeof ToastAnnounceExcludeFrame>
+
+type ToastAnnounceExcludeExtraProps = {
+  altText?: string
+}
+
+type ToastAnnounceExcludeProps = ToastAnnounceExcludeFrameProps &
+  ToastAnnounceExcludeExtraProps
+
+const ToastAnnounceExclude = React.forwardRef<TamaguiElement, ToastAnnounceExcludeProps>(
+  (props, forwardedRef) => {
+    const { altText, ...announceExcludeProps } = props
+
+    return (
+      <ToastAnnounceExcludeFrame
+        data-toast-announce-exclude=""
+        data-toast-announce-alt={altText || undefined}
+        {...announceExcludeProps}
+        ref={forwardedRef}
+      />
+    )
+  }
+)
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface ToastAnnounceProps
+  extends Omit<GetProps<typeof VisuallyHidden>, 'children'>,
+    ScopedProps<{ children: string[] }> {}
+
+const ToastAnnounce: React.FC<ToastAnnounceProps> = (
+  props: ScopedProps<ToastAnnounceProps>
+) => {
+  const { scope, children, ...announceProps } = props
+  const context = useToastProviderContext(scope)
+  const [renderAnnounceText, setRenderAnnounceText] = React.useState(false)
+  const [isAnnounced, setIsAnnounced] = React.useState(false)
+
+  // render text content in the next frame to ensure toast is announced in NVDA
+  useNextFrame(() => {
+    startTransition(() => {
+      setRenderAnnounceText(true)
+    })
+  })
+
+  // cleanup after announcing
+  React.useEffect(() => {
+    const timer = setTimeout(() => setIsAnnounced(true), 1000)
+    return () => clearTimeout(timer)
+  }, [])
+
+  return isAnnounced ? null : (
+    <Portal>
+      <VisuallyHidden {...announceProps}>
+        {renderAnnounceText && (
+          <Text>
+            {context.label} {children}
+          </Text>
+        )}
+      </VisuallyHidden>
+    </Portal>
+  )
+}
+
+/* -----------------------------------------------------------------------------------------------*/
+
+function useNextFrame(callback = () => {}) {
+  const fn = useEvent(callback)
+  useIsomorphicLayoutEffect(() => {
+    let raf1 = 0
+    let raf2 = 0
+    raf1 = requestAnimationFrame(() => {
+      raf2 = requestAnimationFrame(fn)
+    })
+    return () => {
+      cancelAnimationFrame(raf1)
+      cancelAnimationFrame(raf2)
+    }
+  }, [fn])
+}
+
+export {
+  ToastAnnounce,
+  ToastAnnounceExclude,
+  type ToastAnnounceExcludeProps,
+  type ToastAnnounceProps,
+}

package/src/ToastImperative.tsx

@@ -0,0 +1,190 @@
+import type { NativePlatform, NativeValue } from '@tamagui/core'
+import { isAndroid, isIos, isWeb } from '@tamagui/core'
+import React from 'react'
+import { createNativeToast } from './createNativeToast'
+import type { CreateNativeToastOptions, NativeToastRef } from './types'
+
+export interface ToastImperativeOptions
+  extends Omit<CreateNativeToastOptions, 'message'> {
+  /**
+   * Will show a native toast if is true or is set to the current platform. On iOS, it wraps `SPIndicator` and `SPAlert`. On Android, it wraps `ToastAndroid`. On web, it wraps Notification API. Mobile's native features are handled by `burnt`.
+   */
+  native?: NativeValue
+}
+
+/**
+ * Override this in your application to get custom toast fields.
+ *
+ * e.g.
+ * ```ts
+ * declare module '@tamagui/toast' {
+ *   interface CustomData {
+ *     preset: 'error' | 'success'
+ *     isUrgent: true
+ *   }
+ * }
+ *```
+ * You will get auto-completion:
+ * ```ts
+ * toast.show("Message", { preset: 'error', isUrgent: true })
+ * ```
+ */
+export interface CustomData {
+  [key: string]: any
+}
+
+type ShowOptions = CreateNativeToastOptions &
+  CustomData & {
+    /**
+     * Used when need custom data
+     */
+    customData?: CustomData
+    /**
+     * Overrides the native option on `ToastImperativeProvider`
+     */
+    native?: NativeValue
+    /**
+     * Which viewport to send this toast to. This is only intended to be used with custom toasts and you should wire it up when creating the toast.
+     */
+    viewportName?: string | 'default'
+  }
+
+type ToastData = { title: string; id: string } & ShowOptions & {
+    isHandledNatively: boolean
+  } & CustomData
+
+interface ToastContextI {
+  nativeToast: NativeToastRef | null
+
+  /**
+   * Call it to show a new toast. If you're using native toasts, you can pass native options using \`burntOptions\` or \`notificationOptions\` depending on the native platform (mobile/web).
+   */
+  show: (title: string, options?: ShowOptions) => boolean
+
+  /**
+   * Call it to hide the currently displayed toast.
+   *
+   * _NOTE_: does not work on Android native toasts
+   *
+   * _NOTE_: hides the last toast on web notification toasts
+   */
+  hide: () => void
+
+  options?: ToastImperativeOptions
+}
+
+const ToastContext = React.createContext<ToastContextI>({} as any)
+const ToastCurrentContext = React.createContext<ToastData | null>(null)
+
+export const useToastController = () => {
+  return React.useContext(ToastContext)
+}
+
+export const useToastState = () => {
+  return React.useContext(ToastCurrentContext)
+}
+
+/** @deprecated use `useToastController` and `useToastState` instead to avoid performance pitfalls */
+export const useToast = () => {
+  return {
+    ...useToastController(),
+    currentToast: useToastState(),
+  }
+}
+
+interface ToastImperativeProviderProps {
+  children: React.ReactNode
+  /**
+   * Used to provide defaults to imperative API. Options can be overwritten when calling `show()`.
+   */
+  options: ToastImperativeOptions
+}
+
+export const ToastImperativeProvider = ({
+  children,
+  options,
+}: ToastImperativeProviderProps) => {
+  const counterRef = React.useRef(0)
+
+  const [toast, setToast] = React.useState<ToastData | null>(null)
+
+  const [lastNativeToastRef, setLastNativeToastRef] =
+    React.useState<ToastContextI['nativeToast']>(null)
+
+  const show = React.useCallback<ToastContextI['show']>(
+    (title, showOptions) => {
+      const native = showOptions?.native ?? options.native
+      const isWebNative = Array.isArray(native)
+        ? native.includes('web')
+        : native === 'web'
+      const isMobileNative = Array.isArray(native)
+        ? native.includes('mobile')
+        : native === 'mobile'
+      const isAndroidNative =
+        isMobileNative ||
+        (Array.isArray(native) ? native.includes('android') : native === 'android')
+      const isIosNative =
+        isMobileNative ||
+        (Array.isArray(native) ? native.includes('ios') : native === 'ios')
+
+      const isHandledNatively =
+        native === true ||
+        (isWeb && isWebNative) ||
+        (!isWeb && isMobileNative) ||
+        (isAndroid && isAndroidNative) ||
+        (isIos && isIosNative)
+
+      if (isHandledNatively) {
+        const nativeToastResult = createNativeToast(title, showOptions ?? {})
+        if (typeof nativeToastResult === 'object' && nativeToastResult.nativeToastRef) {
+          setLastNativeToastRef(nativeToastResult.nativeToastRef)
+        }
+      }
+      counterRef.current++
+      setToast({
+        ...showOptions?.customData,
+        ...showOptions,
+        viewportName: showOptions?.viewportName ?? 'default',
+        title,
+        id: counterRef.current.toString(),
+        isHandledNatively,
+      })
+      return true
+    },
+    [setToast, JSON.stringify(options.native || null)]
+  )
+
+  const hide = React.useCallback(() => {
+    lastNativeToastRef?.close()
+    setToast((prev) => {
+      if (!prev) return null
+      return {
+        ...prev,
+        hide: true,
+      }
+    })
+
+    setTimeout(() => {
+      setToast(null)
+    }, 100)
+  }, [setToast, lastNativeToastRef])
+
+  const contextValue = React.useMemo(() => {
+    return {
+      show,
+      hide,
+      nativeToast: lastNativeToastRef,
+      options,
+    }
+  }, [show, hide, lastNativeToastRef, JSON.stringify(options || null)])
+
+  return (
+    <ToastContext.Provider value={contextValue}>
+      <ToastCurrentContext.Provider value={toast}>
+        {children}
+      </ToastCurrentContext.Provider>
+    </ToastContext.Provider>
+  )
+}
+
+export type { NativePlatform, NativeValue, ToastImperativeProviderProps }