@tamagui/tabs-headless 2.7.7 → 3.0.0-beta.643.1

package/src/useTabs.tsx

@@ -1,15 +1,24 @@
-import { composeEventHandlers } from '@tamagui/helpers'
+import { isWeb } from '@tamagui/constants'
 import { useControllableState } from '@tamagui/use-controllable-state'
 import { useDirection } from '@tamagui/use-direction'
 import * as React from 'react'
-import { useCallback, useId, useRef, useState } from 'react'
 
 export type TabsActivationMode = 'automatic' | 'manual'
 export type TabsOrientation = 'horizontal' | 'vertical'
 export type Direction = 'ltr' | 'rtl'
 
+// the skinned Tabs and any headless consumer must derive the same ids, or
+// aria-controls / aria-labelledby stop pointing at each other
+export function makeTriggerId(baseId: string, value: string) {
+  return `${baseId}-trigger-${value}`
+}
+
+export function makeContentId(baseId: string, value: string) {
+  return `${baseId}-content-${value}`
+}
+
 // -------------------------------------------------------------------------------------------------
-// useTabs
+// useTabs - root controller
 // -------------------------------------------------------------------------------------------------
 
 export interface UseTabsProps {
@@ -20,387 +29,194 @@ export interface UseTabsProps {
   /** A function called when a new tab is selected */
   onValueChange?: (value: string) => void
   /**
-   * The orientation the tabs are layed out.
-   * Mainly so arrow navigation is done accordingly (left & right vs. up & down)
+   * The orientation the tabs are laid out.
    * @defaultValue horizontal
    */
   orientation?: TabsOrientation
-  /**
-   * The direction of navigation between toolbar items.
-   */
+  /** The direction of navigation between tab triggers. */
   dir?: Direction
   /**
-   * Whether a tab is activated automatically (on focus) or manually (on click/enter).
+   * Whether a tab is activated automatically (on focus) or manually (on press/enter).
+   * Automatic activation is web-only; native always activates manually.
    * @defaultValue automatic
    */
   activationMode?: TabsActivationMode
-  /**
-   * Whether keyboard navigation should loop from last to first and vice versa.
-   * @defaultValue true
-   */
-  loop?: boolean
 }
 
-export interface UseTabsReturn {
-  /** The currently selected tab value */
-  value: string
-  /** Function to change the selected tab */
-  setValue: (value: string) => void
-  /** The resolved text direction */
-  direction: Direction
-  /** Props to spread on the tabs container element */
-  tabsProps: {
-    'data-orientation': TabsOrientation
-    dir: Direction
-  }
-  /** Props to spread on the tab list element */
-  listProps: {
-    role: 'tablist'
-    'aria-orientation': TabsOrientation
-  }
-  /** Function to get props for a tab trigger */
-  getTabProps: (tabValue: string, disabled?: boolean) => TabTriggerProps
-  /** Function to get props for a tab content panel */
-  getContentProps: (tabValue: string) => TabContentProps
-  /** Context value to provide to child components */
-  contextValue: TabsContextValue
-}
-
-export interface TabTriggerProps {
-  role: 'tab'
-  id: string
-  'aria-selected': boolean
-  'aria-controls': string
-  'data-state': 'active' | 'inactive'
-  'data-disabled'?: ''
-  disabled?: boolean
-  tabIndex: number
-  onKeyDown: (event: React.KeyboardEvent) => void
-  onClick: (event: React.MouseEvent) => void
-  onFocus: (event: React.FocusEvent) => void
-}
-
-export interface TabContentProps {
-  role: 'tabpanel'
-  id: string
-  'aria-labelledby': string
-  'data-state': 'active' | 'inactive'
-  'data-orientation': TabsOrientation
-  hidden: boolean
-  tabIndex: 0
-}
-
-export interface TabsContextValue {
-  baseId: string
-  value: string
-  setValue: (value: string) => void
-  orientation: TabsOrientation
-  direction: Direction
-  activationMode: TabsActivationMode
-  loop: boolean
-}
-
-export function useTabs(props: UseTabsProps = {}): UseTabsReturn {
+export function useTabs(props: UseTabsProps = {}) {
   const {
     value: valueProp,
     onValueChange,
-    defaultValue = '',
+    defaultValue,
     orientation = 'horizontal',
     dir,
     activationMode = 'automatic',
-    loop = true,
   } = props
 
   const direction = useDirection(dir)
-  const baseId = useId()
+  const baseId = React.useId()
 
   const [value, setValue] = useControllableState({
     prop: valueProp,
     onChange: onValueChange,
-    defaultProp: defaultValue,
+    defaultProp: defaultValue ?? '',
   })
 
-  const tabRefs = useRef<Map<string, HTMLElement>>(new Map())
-  const [tabValues, setTabValues] = useState<string[]>([])
-
-  const registerTab = useCallback((tabValue: string, element: HTMLElement | null) => {
-    if (element) {
-      tabRefs.current.set(tabValue, element)
-      setTabValues((prev) => (prev.includes(tabValue) ? prev : [...prev, tabValue]))
-    } else {
-      tabRefs.current.delete(tabValue)
-      setTabValues((prev) => prev.filter((v) => v !== tabValue))
-    }
-  }, [])
-
-  const focusTab = useCallback((tabValue: string) => {
-    const element = tabRefs.current.get(tabValue)
-    element?.focus()
-  }, [])
-
-  const getNextTab = useCallback(
-    (currentValue: string, direction: 1 | -1): string | null => {
-      const currentIndex = tabValues.indexOf(currentValue)
-      if (currentIndex === -1) return null
-
-      let nextIndex = currentIndex + direction
-      if (loop) {
-        nextIndex = (nextIndex + tabValues.length) % tabValues.length
-      } else {
-        if (nextIndex < 0 || nextIndex >= tabValues.length) return null
-      }
-      return tabValues[nextIndex] ?? null
-    },
-    [tabValues, loop]
-  )
-
-  const handleKeyDown = useCallback(
-    (tabValue: string) => (event: React.KeyboardEvent) => {
-      const isHorizontal = orientation === 'horizontal'
-      const isRtl = direction === 'rtl'
-
-      let nextTab: string | null = null
-
-      switch (event.key) {
-        case 'ArrowRight':
-          if (isHorizontal) {
-            nextTab = getNextTab(tabValue, isRtl ? -1 : 1)
-          }
-          break
-        case 'ArrowLeft':
-          if (isHorizontal) {
-            nextTab = getNextTab(tabValue, isRtl ? 1 : -1)
-          }
-          break
-        case 'ArrowDown':
-          if (!isHorizontal) {
-            nextTab = getNextTab(tabValue, 1)
-          }
-          break
-        case 'ArrowUp':
-          if (!isHorizontal) {
-            nextTab = getNextTab(tabValue, -1)
-          }
-          break
-        case 'Home':
-          nextTab = tabValues[0] ?? null
-          break
-        case 'End':
-          nextTab = tabValues[tabValues.length - 1] ?? null
-          break
-        case ' ':
-        case 'Enter':
-          if (activationMode === 'manual') {
-            setValue(tabValue)
-            event.preventDefault()
-          }
-          return
-      }
-
-      if (nextTab) {
-        event.preventDefault()
-        focusTab(nextTab)
-        if (activationMode === 'automatic') {
-          setValue(nextTab)
-        }
-      }
-    },
-    [orientation, direction, getNextTab, tabValues, activationMode, setValue, focusTab]
+  // triggers report their presence so consumers can re-measure when the set changes
+  const [triggersCount, setTriggersCount] = React.useState(0)
+  const registerTrigger = React.useCallback(
+    () => setTriggersCount((count) => count + 1),
+    []
   )
-
-  const getTabProps = useCallback(
-    (tabValue: string, disabled?: boolean): TabTriggerProps => {
-      const isSelected = value === tabValue
-      const triggerId = makeTriggerId(baseId, tabValue)
-      const contentId = makeContentId(baseId, tabValue)
-
-      return {
-        role: 'tab',
-        id: triggerId,
-        'aria-selected': isSelected,
-        'aria-controls': contentId,
-        'data-state': isSelected ? 'active' : 'inactive',
-        ...(disabled && { 'data-disabled': '' as const }),
-        disabled,
-        tabIndex: isSelected ? 0 : -1,
-        onKeyDown: disabled ? () => {} : handleKeyDown(tabValue),
-        onClick: (event: React.MouseEvent) => {
-          if (!disabled && !isSelected) {
-            setValue(tabValue)
-          }
-        },
-        onFocus: (event: React.FocusEvent) => {
-          registerTab(tabValue, event.currentTarget as HTMLElement)
-          if (!disabled && !isSelected && activationMode === 'automatic') {
-            setValue(tabValue)
-          }
-        },
-      }
-    },
-    [value, baseId, handleKeyDown, setValue, activationMode, registerTab]
-  )
-
-  const getContentProps = useCallback(
-    (tabValue: string): TabContentProps => {
-      const isSelected = value === tabValue
-      const triggerId = makeTriggerId(baseId, tabValue)
-      const contentId = makeContentId(baseId, tabValue)
-
-      return {
-        role: 'tabpanel',
-        id: contentId,
-        'aria-labelledby': triggerId,
-        'data-state': isSelected ? 'active' : 'inactive',
-        'data-orientation': orientation,
-        hidden: !isSelected,
-        tabIndex: 0,
-      }
-    },
-    [value, baseId, orientation]
+  const unregisterTrigger = React.useCallback(
+    () => setTriggersCount((count) => count - 1),
+    []
   )
 
-  const contextValue: TabsContextValue = {
-    baseId,
-    value,
-    setValue,
-    orientation,
-    direction,
-    activationMode,
-    loop,
-  }
-
   return {
     value,
     setValue,
+    baseId,
     direction,
+    orientation,
+    activationMode,
+    triggersCount,
+    registerTrigger,
+    unregisterTrigger,
     tabsProps: {
       'data-orientation': orientation,
-      dir: direction,
-    },
-    listProps: {
-      role: 'tablist',
-      'aria-orientation': orientation,
     },
-    getTabProps,
-    getContentProps,
-    contextValue,
   }
 }
 
 // -------------------------------------------------------------------------------------------------
-// useTabsContext - for component-based APIs
+// useTabsList - the tablist container
 // -------------------------------------------------------------------------------------------------
 
-const TabsContext = React.createContext<TabsContextValue | null>(null)
+export interface UseTabsListProps {
+  orientation?: TabsOrientation
+  /** Disables every trigger in the list. */
+  disabled?: boolean
+}
 
-export const TabsProvider = TabsContext.Provider
+export function useTabsList(props: UseTabsListProps) {
+  const { orientation = 'horizontal', disabled = false } = props
 
-export function useTabsContext(): TabsContextValue {
-  const context = React.useContext(TabsContext)
-  if (!context) {
-    throw new Error('useTabsContext must be used within a TabsProvider')
+  return {
+    listProps: {
+      role: 'tablist' as const,
+      'aria-orientation': orientation,
+      'aria-disabled': disabled || undefined,
+      'data-orientation': orientation,
+      'data-disabled': disabled ? ('' as const) : undefined,
+    },
   }
-  return context
 }
 
 // -------------------------------------------------------------------------------------------------
-// useTab - hook for individual tab triggers
+// useTab - an individual trigger
 // -------------------------------------------------------------------------------------------------
 
+/** the fields the primary-pointer check reads off a web press event */
+export type TabPressEvent = {
+  button?: number
+  ctrlKey?: boolean
+}
+
 export interface UseTabProps {
+  baseId: string
+  /** The value this trigger selects. */
   value: string
+  /** The currently selected value. */
+  selectedValue?: string
   disabled?: boolean
-  onPress?: (event: any) => void
-  onKeyDown?: (event: React.KeyboardEvent) => void
-  onFocus?: (event: React.FocusEvent) => void
+  activationMode?: TabsActivationMode
+  onChange: (value: string) => void
 }
 
 export function useTab(props: UseTabProps) {
-  const { value: tabValue, disabled, onPress, onKeyDown, onFocus } = props
-  const context = useTabsContext()
-  const { value, setValue, baseId, activationMode, orientation, direction, loop } =
-    context
-
-  const isSelected = value === tabValue
-  const triggerId = makeTriggerId(baseId, tabValue)
-  const contentId = makeContentId(baseId, tabValue)
+  const {
+    baseId,
+    value,
+    selectedValue,
+    disabled = false,
+    activationMode = 'automatic',
+    onChange,
+  } = props
 
-  const ref = useRef<HTMLElement>(null)
+  const isSelected = value === selectedValue
+  const triggerId = makeTriggerId(baseId, value)
+  const contentId = makeContentId(baseId, value)
 
   return {
     isSelected,
+    triggerId,
+    contentId,
     tabProps: {
-      ref,
       role: 'tab' as const,
       id: triggerId,
       'aria-selected': isSelected,
       'aria-controls': contentId,
-      'data-state': isSelected ? 'active' : 'inactive',
-      ...(disabled && { 'data-disabled': '' as const }),
+      'data-state': isSelected ? ('active' as const) : ('inactive' as const),
+      'data-disabled': disabled ? ('' as const) : undefined,
       disabled,
-      tabIndex: isSelected ? 0 : -1,
-      onKeyDown: composeEventHandlers(onKeyDown, (event: React.KeyboardEvent) => {
-        if (disabled) return
-        if ([' ', 'Enter'].includes(event.key)) {
-          setValue(tabValue)
-          event.preventDefault()
-        }
-      }),
-      onPress: composeEventHandlers(onPress, () => {
-        if (!disabled && !isSelected) {
-          setValue(tabValue)
-        }
-      }),
-      onFocus: composeEventHandlers(onFocus, () => {
-        if (!disabled && !isSelected && activationMode === 'automatic') {
-          setValue(tabValue)
+      onPress: (event?: TabPressEvent) => {
+        // ignore secondary and ctrl-clicks on web; native has no such notion
+        const isPrimaryPointer =
+          !isWeb || (event?.button === 0 && event?.ctrlKey === false)
+        if (!disabled && !isSelected && isPrimaryPointer) {
+          onChange(value)
         }
+      },
+      ...(isWeb && {
+        onKeyDown: (event: React.KeyboardEvent) => {
+          if (!disabled && [' ', 'Enter'].includes(event.key)) {
+            onChange(value)
+            event.preventDefault()
+          }
+        },
+        onFocus: () => {
+          if (!isSelected && !disabled && activationMode !== 'manual') {
+            onChange(value)
+          }
+        },
       }),
     },
   }
 }
 
 // -------------------------------------------------------------------------------------------------
-// useTabContent - hook for tab content panels
+// useTabContent - a content panel
 // -------------------------------------------------------------------------------------------------
 
 export interface UseTabContentProps {
+  baseId: string
+  /** The value that selects this content. */
   value: string
+  /** The currently selected value. */
+  selectedValue?: string
+  orientation?: TabsOrientation
+  /** Mounts the content even when its value is not selected. */
   forceMount?: boolean
 }
 
 export function useTabContent(props: UseTabContentProps) {
-  const { value: tabValue, forceMount } = props
-  const context = useTabsContext()
-  const { value, baseId, orientation } = context
+  const { baseId, value, selectedValue, orientation = 'horizontal', forceMount } = props
 
-  const isSelected = value === tabValue
-  const triggerId = makeTriggerId(baseId, tabValue)
-  const contentId = makeContentId(baseId, tabValue)
+  const isSelected = value === selectedValue
+  const shouldMount = Boolean(forceMount) || isSelected
 
   return {
     isSelected,
-    shouldMount: forceMount || isSelected,
+    shouldMount,
     contentProps: {
       role: 'tabpanel' as const,
-      id: contentId,
-      'aria-labelledby': triggerId,
-      'data-state': isSelected ? 'active' : 'inactive',
+      id: makeContentId(baseId, value),
+      'aria-labelledby': makeTriggerId(baseId, value),
+      'data-state': isSelected ? ('active' as const) : ('inactive' as const),
       'data-orientation': orientation,
-      hidden: !isSelected,
+      hidden: !shouldMount,
       tabIndex: 0,
     },
   }
 }
-
-// -------------------------------------------------------------------------------------------------
-// Helpers
-// -------------------------------------------------------------------------------------------------
-
-function makeTriggerId(baseId: string, value: string) {
-  return `${baseId}-trigger-${value}`
-}
-
-function makeContentId(baseId: string, value: string) {
-  return `${baseId}-content-${value}`
-}