@tamagui/toast 1.7.11 → 1.8.1

package/src/ToastViewport.tsx

@@ -0,0 +1,354 @@
+import { AnimatePresence } from '@tamagui/animate-presence'
+import { useComposedRefs } from '@tamagui/compose-refs'
+import { GetProps, TamaguiElement, isWeb, styled } from '@tamagui/core'
+import { PortalHost } from '@tamagui/portal'
+import { YStack } from '@tamagui/stacks'
+import { VisuallyHidden } from '@tamagui/visually-hidden'
+import * as React from 'react'
+
+import {
+  Collection,
+  ScopedProps,
+  useCollection,
+  useToastProviderContext,
+} from './ToastProvider'
+
+const VIEWPORT_NAME = 'ToastViewport'
+const VIEWPORT_DEFAULT_HOTKEY = ['F8']
+const VIEWPORT_PAUSE = 'toast.viewportPause'
+const VIEWPORT_RESUME = 'toast.viewportResume'
+
+const ToastViewportWrapperFrame = styled(YStack, {
+  name: 'ViewportWrapper',
+  pointerEvents: 'box-none',
+  top: 0,
+  bottom: 0,
+  left: 0,
+  right: 0,
+  // @ts-ignore
+  position: isWeb ? 'fixed' : 'absolute',
+  maxWidth: '100%',
+  tabIndex: 0,
+  zIndex: 100000,
+})
+
+const ToastViewportFrame = styled(YStack, {
+  name: VIEWPORT_NAME,
+  pointerEvents: 'box-none',
+  // @ts-ignore
+  position: isWeb ? 'fixed' : 'absolute',
+  maxWidth: '100%',
+})
+type ToastViewportFrameProps = GetProps<typeof ToastViewportFrame>
+type ToastViewportProps = ToastViewportFrameProps & {
+  /**
+   * The keys to use as the keyboard shortcut that will move focus to the toast viewport.
+   * @defaultValue ['F8']
+   */
+  hotkey?: string[]
+  /**
+   * An author-localized label for the toast viewport to provide context for screen reader users
+   * when navigating page landmarks. The available `{hotkey}` placeholder will be replaced for you.
+   * @defaultValue 'Notifications ({hotkey})'
+   */
+  label?: string
+  /**
+   * Used to reference the viewport if you want to have multiple viewports in the same provider.
+   */
+  name?: string
+}
+
+const ToastViewport = React.forwardRef<HTMLDivElement, ToastViewportProps>(
+  (props: ScopedProps<ToastViewportProps>, forwardedRef) => {
+    const {
+      __scopeToast,
+      hotkey = VIEWPORT_DEFAULT_HOTKEY,
+      label = 'Notifications ({hotkey})',
+      name,
+      ...viewportProps
+    } = props
+    const context = useToastProviderContext(VIEWPORT_NAME, __scopeToast)
+    const getItems = useCollection(__scopeToast)
+    const headFocusProxyRef = React.useRef<FocusProxyElement>(null)
+    const tailFocusProxyRef = React.useRef<FocusProxyElement>(null)
+    const wrapperRef = React.useRef<HTMLDivElement>(null)
+    const ref = React.useRef<HTMLDivElement>(null)
+    const composedRefs = useComposedRefs(forwardedRef, ref, context.onViewportChange)
+    const hotkeyLabel = hotkey.join('+').replace(/Key/g, '').replace(/Digit/g, '')
+    const hasToasts = context.toastCount > 0
+
+    React.useEffect(() => {
+      if (!isWeb) return
+      const handleKeyDown = (event: KeyboardEvent) => {
+        // we use `event.code` as it is consistent regardless of meta keys that were pressed.
+        // for example, `event.key` for `Control+Alt+t` is `†` and `t !== †`
+        const isHotkeyPressed = hotkey.every(
+          (key) => (event as any)[key] || event.code === key
+        )
+        if (isHotkeyPressed) ref.current?.focus()
+        console.log(isHotkeyPressed)
+      }
+      document.addEventListener('keydown', handleKeyDown)
+      return () => {
+        document.removeEventListener('keydown', handleKeyDown)
+      }
+    }, [hotkey])
+
+    React.useEffect(() => {
+      if (!isWeb) return
+      const wrapper = wrapperRef.current
+      const viewport = ref.current
+      if (hasToasts && wrapper && viewport) {
+        const handlePause = () => {
+          if (!context.isClosePausedRef.current) {
+            const pauseEvent = new CustomEvent(VIEWPORT_PAUSE)
+            viewport.dispatchEvent(pauseEvent)
+            context.isClosePausedRef.current = true
+          }
+        }
+
+        const handleResume = () => {
+          if (context.isClosePausedRef.current) {
+            const resumeEvent = new CustomEvent(VIEWPORT_RESUME)
+            viewport.dispatchEvent(resumeEvent)
+            context.isClosePausedRef.current = false
+          }
+        }
+
+        const handleFocusOutResume = (event: FocusEvent) => {
+          const isFocusMovingOutside = !wrapper.contains(
+            event.relatedTarget as HTMLElement
+          )
+          if (isFocusMovingOutside) handleResume()
+        }
+
+        const handlePointerLeaveResume = () => {
+          const isFocusInside = wrapper.contains(document.activeElement)
+          if (!isFocusInside) handleResume()
+        }
+        // Toasts are not in the viewport React tree so we need to bind DOM events
+
+        wrapper.addEventListener('focusin', handlePause)
+        wrapper.addEventListener('focusout', handleFocusOutResume)
+        wrapper.addEventListener('pointermove', handlePause)
+        wrapper.addEventListener('pointerleave', handlePointerLeaveResume)
+        window.addEventListener('blur', handlePause)
+        window.addEventListener('focus', handleResume)
+        return () => {
+          wrapper.removeEventListener('focusin', handlePause)
+          wrapper.removeEventListener('focusout', handleFocusOutResume)
+          wrapper.removeEventListener('pointermove', handlePause)
+          wrapper.removeEventListener('pointerleave', handlePointerLeaveResume)
+          window.removeEventListener('blur', handlePause)
+          window.removeEventListener('focus', handleResume)
+        }
+      }
+    }, [hasToasts, context.isClosePausedRef])
+
+    const getSortedTabbableCandidates = React.useCallback(
+      ({ tabbingDirection }: { tabbingDirection: 'forwards' | 'backwards' }) => {
+        const toastItems = getItems()
+        const tabbableCandidates = toastItems.map((toastItem) => {
+          const toastNode = toastItem.ref.current!
+          const toastTabbableCandidates = [toastNode, ...getTabbableCandidates(toastNode)]
+          return tabbingDirection === 'forwards'
+            ? toastTabbableCandidates
+            : toastTabbableCandidates.reverse()
+        })
+        return (
+          tabbingDirection === 'forwards'
+            ? tabbableCandidates.reverse()
+            : tabbableCandidates
+        ).flat()
+      },
+      [getItems]
+    )
+
+    React.useEffect(() => {
+      if (!isWeb) return
+      const viewport = ref.current
+      // We programmatically manage tabbing as we are unable to influence
+      // the source order with portals, this allows us to reverse the
+      // tab order so that it runs from most recent toast to least
+      if (viewport) {
+        const handleKeyDown = (event: KeyboardEvent) => {
+          const isMetaKey = event.altKey || event.ctrlKey || event.metaKey
+          const isTabKey = event.key === 'Tab' && !isMetaKey
+
+          if (isTabKey) {
+            const focusedElement = document.activeElement
+            const isTabbingBackwards = event.shiftKey
+            const targetIsViewport = event.target === viewport
+
+            // If we're back tabbing after jumping to the viewport then we simply
+            // proxy focus out to the preceding document
+            if (targetIsViewport && isTabbingBackwards) {
+              headFocusProxyRef.current?.focus()
+              return
+            }
+
+            const tabbingDirection = isTabbingBackwards ? 'backwards' : 'forwards'
+            const sortedCandidates = getSortedTabbableCandidates({ tabbingDirection })
+            const index = sortedCandidates.findIndex(
+              (candidate) => candidate === focusedElement
+            )
+            if (focusFirst(sortedCandidates.slice(index + 1))) {
+              event.preventDefault()
+            } else {
+              // If we can't focus that means we're at the edges so we
+              // proxy to the corresponding exit point and let the browser handle
+              // tab/shift+tab keypress and implicitly pass focus to the next valid element in the document
+              isTabbingBackwards
+                ? headFocusProxyRef.current?.focus()
+                : tailFocusProxyRef.current?.focus()
+            }
+          }
+        }
+
+        // Toasts are not in the viewport React tree so we need to bind DOM events
+        viewport.addEventListener('keydown', handleKeyDown)
+        return () => viewport.removeEventListener('keydown', handleKeyDown)
+      }
+    }, [getItems, getSortedTabbableCandidates])
+
+    return (
+      <ToastViewportWrapperFrame
+        ref={wrapperRef}
+        role="region"
+        aria-label={label.replace('{hotkey}', hotkeyLabel)}
+        // // Ensure virtual cursor from landmarks menus triggers focus/blur for pause/resume
+        tabIndex={-1}
+        // // incase list has size when empty (e.g. padding), we remove pointer events so
+        // // it doesn't prevent interactions with page elements that it overlays
+        // pointerEvents={hasToasts ? undefined : 'none'}
+      >
+        {hasToasts && (
+          <FocusProxy
+            ref={headFocusProxyRef}
+            onFocusFromOutsideViewport={() => {
+              const tabbableCandidates = getSortedTabbableCandidates({
+                tabbingDirection: 'forwards',
+              })
+              focusFirst(tabbableCandidates)
+            }}
+          />
+        )}
+        {/**
+         * tabindex on the the list so that it can be focused when items are removed. we focus
+         * the list instead of the viewport so it announces number of items remaining.
+         */}
+        <Collection.Slot scope={__scopeToast}>
+          <ToastViewportFrame ref={composedRefs} {...viewportProps}>
+            <PortalHost
+              // TODO: user should be able to control this prop to customize AnimatePresence
+              render={(children) => <AnimatePresence>{children}</AnimatePresence>}
+              name={name ?? 'default'}
+            />
+          </ToastViewportFrame>
+        </Collection.Slot>
+        {hasToasts && (
+          <FocusProxy
+            ref={tailFocusProxyRef}
+            onFocusFromOutsideViewport={() => {
+              const tabbableCandidates = getSortedTabbableCandidates({
+                tabbingDirection: 'backwards',
+              })
+              focusFirst(tabbableCandidates)
+            }}
+          />
+        )}
+      </ToastViewportWrapperFrame>
+    )
+  }
+)
+
+ToastViewport.displayName = VIEWPORT_NAME
+
+/* -----------------------------------------------------------------------------------------------*/
+
+const FOCUS_PROXY_NAME = 'ToastFocusProxy'
+
+type FocusProxyElement = React.ElementRef<typeof VisuallyHidden>
+type VisuallyHiddenProps = GetProps<typeof VisuallyHidden>
+interface FocusProxyProps extends VisuallyHiddenProps {
+  onFocusFromOutsideViewport(): void
+}
+
+const FocusProxy = React.forwardRef<FocusProxyElement, ScopedProps<FocusProxyProps>>(
+  (props, forwardedRef) => {
+    const { __scopeToast, onFocusFromOutsideViewport, ...proxyProps } = props
+    const context = useToastProviderContext(FOCUS_PROXY_NAME, __scopeToast)
+
+    return (
+      <VisuallyHidden
+        aria-hidden
+        tabIndex={0}
+        {...proxyProps}
+        ref={forwardedRef}
+        // Avoid page scrolling when focus is on the focus proxy
+        position={isWeb ? ('fixed' as any) : 'absolute'}
+        onFocus={(event) => {
+          if (!isWeb) return
+          const prevFocusedElement = event.relatedTarget as HTMLElement | null
+          const isFocusFromOutsideViewport = !(context.viewport as HTMLElement)?.contains(
+            prevFocusedElement
+          )
+          if (isFocusFromOutsideViewport) onFocusFromOutsideViewport()
+        }}
+      />
+    )
+  }
+)
+
+FocusProxy.displayName = FOCUS_PROXY_NAME
+
+/* -----------------------------------------------------------------------------------------------*/
+
+function focusFirst(candidates: TamaguiElement[]) {
+  if (!isWeb) return
+  const previouslyFocusedElement = document.activeElement
+  return candidates.some((candidate) => {
+    // if focus is already where we want to go, we don't want to keep going through the candidates
+    if (candidate === previouslyFocusedElement) return true
+    candidate.focus()
+    return document.activeElement !== previouslyFocusedElement
+  })
+}
+
+/**
+ * Returns a list of potential tabbable candidates.
+ *
+ * NOTE: This is only a close approximation. For example it doesn't take into account cases like when
+ * elements are not visible. This cannot be worked out easily by just reading a property, but rather
+ * necessitate runtime knowledge (computed styles, etc). We deal with these cases separately.
+ *
+ * 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: TamaguiElement) {
+  if (!isWeb) return []
+  const containerHtml = container as HTMLElement
+  const nodes: HTMLElement[] = []
+  const walker = document.createTreeWalker(containerHtml, NodeFilter.SHOW_ELEMENT, {
+    acceptNode: (node: any) => {
+      const isHiddenInput = node.tagName === 'INPUT' && node.type === 'hidden'
+      if (node.disabled || node.hidden || isHiddenInput) return NodeFilter.FILTER_SKIP
+      // `.tabIndex` is not the same as the `tabindex` attribute. It works on the
+      // runtime's understanding of tabbability, so this automatically accounts
+      // for any kind of element that could be tabbed to.
+      return node.tabIndex >= 0 ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
+    },
+  })
+  while (walker.nextNode()) nodes.push(walker.currentNode as HTMLElement)
+  // we do not take into account the order of nodes with positive `tabIndex` as it
+  // hinders accessibility to have tab order different from visual order.
+  return nodes
+}
+
+export {
+  ToastViewport,
+  ToastViewportProps,
+  VIEWPORT_DEFAULT_HOTKEY,
+  VIEWPORT_PAUSE,
+  VIEWPORT_RESUME,
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const TOAST_NAME = 'Toast'

package/src/createNativeToast.native.tsx

@@ -0,0 +1,16 @@
+import { CreateNativeToastsOptions, CreateNativeToastsOptionsFn } from './types'
+
+export const createNativeToast: CreateNativeToastsOptionsFn = (
+  title,
+  { message, duration, preset = 'done' }: CreateNativeToastsOptions
+) => {
+  // import inline to allow lazy usage of native dependecy:
+  const Burnt = require('burnt')
+
+  Burnt.toast({
+    title,
+    message: message ?? '',
+    preset,
+    duration,
+  })
+}

package/src/createNativeToast.tsx

@@ -0,0 +1,25 @@
+import { CreateNativeToastsOptionsFn } from './types'
+
+export const createNativeToast: CreateNativeToastsOptionsFn = (title, { message }) => {
+  if (!('Notification' in window)) {
+    throw Error('This browser does not support desktop notification')
+  }
+
+  if (Notification.permission === 'denied') return {}
+
+  const showNotification = () => {
+    new Notification(title, {
+      body: message,
+    })
+  }
+
+  if (Notification.permission === 'granted') {
+    showNotification()
+  } else {
+    Notification.requestPermission().then((permission) => {
+      if (permission === 'granted') {
+        showNotification()
+      }
+    })
+  }
+}

package/src/createToast.tsx

@@ -0,0 +1,93 @@
+import { isWeb } from '@tamagui/core'
+import { Scope, createContextScope } from '@tamagui/create-context'
+import React, { useRef } from 'react'
+
+import { createNativeToast } from './createNativeToast'
+import { CreateNativeToastsOptions, CreateNativeToastsOptionsFn } from './types'
+
+type NativeValue = boolean | 'web' | 'mobile'
+interface CreateToastOptions {
+  /**
+   * 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
+}
+interface ToastOptions extends CreateNativeToastsOptions {
+  /**
+   * Used when need custom data
+   */
+  additionalInfo?: Record<string, any>
+  /**
+   * Overrides the native option on `createToast()`
+   */
+  native?: NativeValue
+}
+type ScopedProps<P> = P & { __scopeToast?: Scope }
+
+type ToastData = { title: string; id: string } & CreateNativeToastsOptions
+
+interface ImperativeToastContextValue {
+  currentToast: ToastData | null
+  addToast: CreateNativeToastsOptionsFn
+}
+
+const [createImperativeToastContext, createImperativeToastScope] =
+  createContextScope('ImperativeToast')
+
+const [ImperativeToastProvider, useToastProviderContext] =
+  createImperativeToastContext<ImperativeToastContextValue>('ImperativeToastProvider')
+
+const createToast = (options = {} as CreateToastOptions) => {
+  return {
+    ImperativeToastProvider: ({
+      __scopeToast,
+      children,
+    }: ScopedProps<{ children: React.ReactNode }>) => {
+      const counterRef = useRef(0)
+      const [toast, setToast] =
+        React.useState<ImperativeToastContextValue['currentToast']>(null)
+      const addToast = React.useCallback<CreateNativeToastsOptionsFn>(
+        (title, options) => {
+          counterRef.current++
+          setToast({ title, id: counterRef.current.toString(), ...options })
+        },
+        [setToast]
+      )
+
+      return (
+        <ImperativeToastProvider
+          scope={__scopeToast}
+          addToast={addToast}
+          currentToast={toast}
+        >
+          {children}
+        </ImperativeToastProvider>
+      )
+    },
+    useToast: () => {
+      const context = useToastProviderContext('useToast', undefined)
+
+      return {
+        /**
+         * The toast to get and show if not using native
+         */
+        currentToast: context.currentToast,
+        show(title: string, showOptions?: ToastOptions) {
+          const native = showOptions?.native || options.native
+          if (
+            native === true ||
+            (Array.isArray(options.native) &&
+              ((isWeb && options.native.includes('web')) ||
+                (!isWeb && options.native.includes('mobile'))))
+          ) {
+            return createNativeToast(title, showOptions ?? {})
+          }
+          context.addToast(title, showOptions ?? {})
+        },
+      }
+    },
+  }
+}
+
+export { createToast }
+export type { CreateToastOptions }

package/src/types.ts

@@ -0,0 +1,21 @@
+import { ToastOptions as BurntToastOptions } from 'burnt/build/types'
+
+export interface CreateNativeToastsOptions {
+  /**
+   * Body of the toast
+   */
+  message?: BurntToastOptions['message']
+  /**
+   * Only supported on native iOS driver
+   */
+  preset?: BurntToastOptions['preset']
+  /**
+   * Duration of toast
+   */
+  duration?: BurntToastOptions['duration']
+}
+
+export type CreateNativeToastsOptionsFn = (
+  title: string,
+  options: CreateNativeToastsOptions
+) => void