@graphprotocol/gds-react 0.1.2 → 0.2.1

package/src/components/Tooltip.parts.tsx

@@ -5,32 +5,33 @@ import {
   useCallback,
   useContext,
   useEffect,
-  useMemo,
   useRef,
   useState,
   type ComponentProps,
   type ReactElement,
   type ReactNode,
+  type Ref,
 } from 'react'
-import { Tooltip } from '@base-ui/react/tooltip'
+import { Tooltip, type TooltipRoot as BaseUITooltipRoot } from '@base-ui/react/tooltip'
+import { useMergedRefs } from '@base-ui/utils/useMergedRefs'
+import type { SetReturnType } from 'type-fest'
 
 import { twToPx, type GDSComponentProps } from '@graphprotocol/gds-css'
 
 import { useControlled, useCSSPropsPolyfill, useGDS } from '../hooks/index.ts'
-import { cn, getCSSPropsAttributes } from '../utils/index.ts'
+import { cn, getCSSPropsAttributes, getReactNodeKey } from '../utils/index.ts'
 import { Portal } from './base/Portal.tsx'
-import { Render, type RenderProps } from './base/Render.tsx'
+import { Render, type RenderProp } from './base/Render.tsx'
 import { TooltipMeta } from './Tooltip.meta.ts'
 
-type DefinedReactNode = Exclude<ReactNode, undefined>
+type Content = Exclude<ReactNode, undefined>
+type SetDeferredContentFunction = (content: Content, priority?: number) => void
+type OpenChangeReason = BaseUITooltipRoot.ChangeEventDetails['reason']
 
 const TooltipContext = createContext<{
-  enabled: boolean
-  registerNestedSetOpen: (nestedSetOpen: (newOpen: boolean) => void) => void
+  collectContent: SetDeferredContentFunction
+  disableDescendants: boolean
 } | null>(null)
-const TooltipCollectorContext = createContext<
-  ((content: DefinedReactNode, priority?: number) => void) | null
->(null)
 
 const OPEN_DELAY = 300
 
@@ -40,237 +41,308 @@ export interface TooltipProps
    * The content to display in the tooltip. If not provided, defaults to any content collected from
    * `Tooltip.Content` or `Tooltip.Collector` descendants.
    */
-  content?: ReactNode | undefined
+  content?: Content | undefined
   /** Force the tooltip to be open or closed. */
   open?: boolean | undefined
   /** Called when the tooltip is opened or closed. */
-  onOpenChange?: ((open: boolean) => void) | undefined
+  onOpenChange?: ((open: boolean, reason: OpenChangeReason) => void) | undefined
   /** The element that triggers the tooltip. */
-  children: ReactElement<Record<string, unknown>>
+  children: ReactElement
+  /**
+   * Props to merge with the trigger element. Set to `'forward'` to have the trigger automatically
+   * receive applicable props passed to the `Tooltip` itself (excluding tooltip-specific props like
+   * `content`, `side` and other positioning props, `open`, `disabled`, etc.).
+   */
+  triggerProps?: ComponentProps<'button'> | 'forward' | undefined
 }
 
 export function TooltipRoot({
   ref: passedRef,
   content: passedContent,
-  position,
+  side,
   gap,
   align,
+  alignOffset,
   open: controlledOpen,
   onOpenChange,
   disabled,
+  overrideDescendants,
   className,
   style,
   children,
-  ...props
+  triggerProps: passedTriggerProps,
+  ...passedProps
 }: TooltipProps) {
   const { dirProps } = useGDS()
 
+  const ancestorTooltip = useContext(TooltipContext)
+
+  const popupProps = passedTriggerProps !== 'forward' ? passedProps : {}
+  const popupRef = passedTriggerProps !== 'forward' ? passedRef : undefined
+
+  const triggerProps = passedTriggerProps === 'forward' ? passedProps : passedTriggerProps
+  const triggerDisabled =
+    triggerProps && 'disabled' in triggerProps ? triggerProps.disabled === true : false
+
   const [cssPropsPolyfillRef, cssPropsPolyfillAttributes, cssProps] = useCSSPropsPolyfill(
     TooltipMeta,
-    { position, align, disabled },
-    { returnPropValues: { position, gap, align, disabled } },
+    { side, align, disabled, overrideDescendants },
+    { returnPropValues: { side, gap, align, alignOffset, disabled, overrideDescendants } },
   )
   const cssPropsAttributes = getCSSPropsAttributes(
     TooltipMeta,
-    { position, gap, align, disabled },
+    { side, gap, align, alignOffset, disabled, overrideDescendants },
     style,
   )
 
-  const tooltipAncestor = useContext(TooltipContext)
-  const hasEnabledTooltipAncestor = tooltipAncestor?.enabled ?? false
-
-  const { onCollect, collectedContent } = useCollectedTooltip()
+  const [setCollectedContent, collectedContent] = useDeferredContent()
   const content = passedContent !== undefined ? passedContent : collectedContent
 
-  const enabled = !cssProps.disabled && !hasEnabledTooltipAncestor && Boolean(content)
-  const [open, ownSetOpen] = useControlled(controlledOpen, false, onOpenChange)
-  const nestedSetOpen = useRef<(newOpen: boolean) => void>(null)
-  const registerNestedSetOpen = useCallback((newNestedSetOpen: (newOpen: boolean) => void) => {
-    nestedSetOpen.current = newNestedSetOpen
-  }, [])
-  const setOpen = (newOpen: boolean) => {
-    ownSetOpen(newOpen)
+  /**
+   * Propagate collected content up till it reaches `Tooltip.Collector`'s closest non-disabled
+   * tooltip ancestor with no passed content.
+   */
+  const collectContent: SetDeferredContentFunction = (newCollectedContent, priority) => {
+    if (passedContent === undefined || cssProps.disabled) {
+      void setCollectedContent(newCollectedContent, priority)
+      ancestorTooltip?.collectContent(newCollectedContent, priority)
+    }
+  }
+
+  const disabledByAncestor = ancestorTooltip?.disableDescendants ?? false
+  const disableDescendants =
+    disabledByAncestor ||
+    (content !== undefined && !cssProps.disabled && cssProps.overrideDescendants)
+  const enabled =
+    Boolean(content) &&
+    !cssProps.disabled &&
+    (!triggerDisabled || controlledOpen) &&
+    !disabledByAncestor
+
+  const triggerRef = useRef<HTMLButtonElement>(null)
+  const triggerPassedRef = useMergedRefs(
     /**
-     * Notify nested (overridden) tooltips of the open state change. This ensures, for example, that
-     * moving the cursor away from a `CopyButton` while its "Copied!" tooltip is shown closes the
-     * inner tooltip as well (which doesn't happen automatically because nested tooltips are
-     * disabled to prevent a lot of weirdness).
+     * Conditionally setting the ref to force the tooltip to refresh its position when `enabled`
+     * changes, preventing it from moving to the viewport's top-left corner in some cases (e.g. when
+     * `CopyButton` returns to its default tooltip).
      */
-    nestedSetOpen.current?.(newOpen)
-  }
-  tooltipAncestor?.registerNestedSetOpen(setOpen)
+    enabled ? triggerRef : undefined,
+    (passedTriggerProps === 'forward' ? passedRef : passedTriggerProps?.ref) as
+      | Ref<HTMLButtonElement>
+      | undefined,
+  )
 
-  if (cssProps.disabled && open) {
-    setOpen(false)
-  }
+  const [open, privateSetOpen] = useControlled(controlledOpen, false, onOpenChange)
+  const justOpenedRef = useRef(false)
+  const setOpen = useCallback(
+    (newOpen: boolean, reason: OpenChangeReason) => {
+      privateSetOpen(newOpen, reason)
+      if (newOpen) {
+        justOpenedRef.current = true
+        window.setTimeout(() => {
+          justOpenedRef.current = false
+        }, 0)
+      }
+    },
+    [privateSetOpen],
+  )
 
   const openTimeoutRef = useRef<number>(undefined)
-  const clearOpenTimeout = () => {
+  const clearOpenTimeout = useCallback(() => {
     if (!openTimeoutRef.current) return
     window.clearTimeout(openTimeoutRef.current)
     openTimeoutRef.current = undefined
-  }
-  if (!enabled) {
-    clearOpenTimeout()
-  }
+  }, [])
 
-  const tooltipContextValue = useMemo(
-    () => ({
-      enabled,
-      registerNestedSetOpen,
-    }),
-    [enabled, registerNestedSetOpen],
-  )
+  useEffect(() => {
+    if (!enabled) {
+      clearOpenTimeout()
+      if (open) setOpen(false, 'disabled')
+    }
+  }, [enabled, open, setOpen, clearOpenTimeout])
 
   return (
-    <TooltipContext.Provider value={tooltipContextValue}>
-      <TooltipCollector onCollect={onCollect}>
-        <Tooltip.Root
-          disabled={!enabled}
-          disableHoverablePopup
-          open={open}
-          onOpenChange={(newOpen, eventDetails) => {
-            clearOpenTimeout()
-            if (!enabled) return
-            // Disable Base UI's default behavior of closing the tooltip when pressing the trigger
-            if (!newOpen && eventDetails.reason === 'trigger-press') {
-              // Ensure clicking on the trigger before the tooltip has a chance to open doesn't prevent it from opening
-              openTimeoutRef.current = window.setTimeout(() => setOpen(true), OPEN_DELAY)
-              return
+    <TooltipContext.Provider
+      value={{
+        collectContent,
+        disableDescendants,
+      }}
+    >
+      <Tooltip.Root
+        disabled={!enabled}
+        disableHoverablePopup
+        open={open}
+        onOpenChange={(newOpen, eventDetails) => {
+          clearOpenTimeout()
+          if (!enabled) return
+          // Disable Base UI's default behavior of closing the tooltip when pressing the trigger
+          if (!newOpen && eventDetails.reason === 'trigger-press') {
+            // Ensure clicking on the trigger before the tooltip has a chance to open doesn't prevent it from opening
+            openTimeoutRef.current = window.setTimeout(
+              () => setOpen(true, eventDetails.reason),
+              OPEN_DELAY,
+            )
+            return
+          }
+          // Make `overrideDescendants={false}` work as expected (see the `NestedSimultaneous` story)
+          if (
+            !newOpen &&
+            eventDetails.reason === 'none' &&
+            (justOpenedRef.current ||
+              (!cssProps.overrideDescendants && triggerRef.current?.matches(':hover')))
+          ) {
+            return
+          }
+          setOpen(newOpen, eventDetails.reason)
+        }}
+      >
+        <Tooltip.Trigger
+          delay={OPEN_DELAY}
+          closeDelay={100}
+          {...(triggerProps as ComponentProps<typeof Tooltip.Trigger>)}
+          ref={triggerPassedRef}
+          disabled={undefined} // Not passed through for some reason, so we set it in `render` and override it to `undefined` here just in case
+          render={(renderProps) => (
+            <Render
+              render={children}
+              {...renderProps}
+              disabled={triggerDisabled}
+              onClick={triggerProps?.onClick} // Prevent the tooltip re-opening after clicking e.g. a `Menu` trigger
+            />
+          )}
+        />
+        <Tooltip.Portal>
+          <Tooltip.Positioner
+            key={getReactNodeKey(content)} // Refresh the tooltip's position when the content changes (see `WithDynamicContent` story)
+            side={
+              cssProps.side === 'start'
+                ? 'inline-start'
+                : cssProps.side === 'end'
+                  ? 'inline-end'
+                  : cssProps.side
             }
-            setOpen(newOpen)
-          }}
-        >
-          <Tooltip.Trigger
-            delay={OPEN_DELAY}
-            closeDelay={100}
-            render={({ onClick: _onClick, ...renderProps }) => (
-              <Render {...(enabled ? renderProps : {})} render={children} />
-            )}
-          />
-          <Tooltip.Portal>
-            <Tooltip.Positioner
-              // The `key` is needed for the `data-[starting-style]`s to refresh properly when these props change in CSS
-              key={`${cssProps.position}-${cssProps.gap}-${cssProps.align}`}
-              side={cssProps.position}
-              sideOffset={twToPx(cssProps.gap)}
-              align={cssProps.align}
-              {...dirProps}
-            >
-              <Tooltip.Popup
-                ref={passedRef}
-                className={cn(
-                  `gds-tooltip root-block u:max-w-(--available-width) u:rounded-4 u:bg-default u:px-2 u:py-1 u:text-12 u:text-default u:transition
-                  i:origin-(--transform-origin)
-                  i:data-ending-style:opacity-0
-                  i:data-starting-style:opacity-0
-                  i:data-starting-style:data-[side=bottom]:-translate-y-1
-                  i:data-starting-style:data-[side=inline-end]:-translate-x-1
-                  i:data-starting-style:data-[side=inline-start]:translate-x-1
-                  i:data-starting-style:data-[side=top]:translate-y-1
-                  i:rtl:data-starting-style:data-[side=inline-end]:translate-x-1
-                  i:rtl:data-starting-style:data-[side=inline-start]:-translate-x-1`,
-                  className,
-                )}
-                {...cssPropsAttributes}
-                {...cssPropsPolyfillAttributes}
-                {...props}
-              >
-                {content}
-              </Tooltip.Popup>
-            </Tooltip.Positioner>
-          </Tooltip.Portal>
-          {/* Ensure changes to CSS props are detected even when the tooltip is not mounted */}
-          <Portal>
-            <span
-              ref={cssPropsPolyfillRef}
-              className={cn('gds-tooltip i:invisible', className)}
+            sideOffset={twToPx(cssProps.gap)}
+            align={cssProps.align}
+            alignOffset={twToPx(cssProps.alignOffset)}
+            collisionPadding={8}
+            disableAnchorTracking // Prevent the tooltip from moving to the viewport's top-left corner when the trigger is unmounted
+            {...dirProps}
+          >
+            <Tooltip.Popup
+              ref={popupRef}
+              className={cn(
+                `gds-tooltip root-block u:max-w-(--available-width) u:rounded-4 u:bg-default u:px-2 u:py-1 u:text-12 u:transition
+                i:origin-(--transform-origin)
+                i:data-ending-style:opacity-0
+                i:data-starting-style:opacity-0
+                i:data-starting-style:data-[side=bottom]:-translate-y-1
+                i:data-starting-style:data-[side=inline-end]:-translate-x-1
+                i:data-starting-style:data-[side=inline-start]:translate-x-1
+                i:data-starting-style:data-[side=top]:translate-y-1
+                i:rtl:data-starting-style:data-[side=end]:translate-x-1
+                i:rtl:data-starting-style:data-[side=start]:-translate-x-1`,
+                className,
+              )}
               {...cssPropsAttributes}
               {...cssPropsPolyfillAttributes}
-              {...props}
-            />
-          </Portal>
-        </Tooltip.Root>
-      </TooltipCollector>
+              {...popupProps}
+            >
+              {content}
+            </Tooltip.Popup>
+          </Tooltip.Positioner>
+        </Tooltip.Portal>
+        {/* Ensure changes to CSS props are detected even when the tooltip is not mounted */}
+        <Portal>
+          <span
+            ref={cssPropsPolyfillRef}
+            className={cn('gds-tooltip i:invisible', className)}
+            {...cssPropsAttributes}
+            {...cssPropsPolyfillAttributes}
+            {...popupProps}
+          />
+        </Portal>
+      </Tooltip.Root>
     </TooltipContext.Provider>
   )
 }
 
-export interface TooltipCollectorProps {
-  /** Callback when a tooltip is collected from a child component. */
-  onCollect?: ((content: DefinedReactNode) => void) | undefined
-  children: ReactNode
-}
-
-export function TooltipCollector({ onCollect, children }: TooltipCollectorProps) {
-  return (
-    <TooltipCollectorContext.Provider value={onCollect ?? null}>
-      {children}
-    </TooltipCollectorContext.Provider>
-  )
-}
-
-/** Hook for components to send tooltip content up to a collector. */
-export function useCollectTooltip() {
-  return useContext(TooltipCollectorContext)
-}
+function useDeferredContent() {
+  const [content, setContent] = useState<Content | undefined>(undefined)
+  const pendingContentRef = useRef<Content | undefined>(undefined)
+  const pendingPriorityRef = useRef<number | undefined>(undefined)
 
-/** Hook for components to collect tooltip content from children. */
-export function useCollectedTooltip() {
-  const [collectedContent, setCollectedContent] = useState<DefinedReactNode>(null)
-  const pendingContent = useRef<DefinedReactNode>(null)
-  const pendingPriority = useRef<number>(0)
-
-  // Collect tooltip during render phase (store in ref to avoid state update during render)
-  const onCollect = (content: DefinedReactNode, priority = 0) => {
-    // Only update if this content has higher priority than what we've collected so far
-    if (priority >= pendingPriority.current) {
-      pendingContent.current = content
-      pendingPriority.current = priority
+  // Store the content in a ref to avoid updating the state during render
+  const setDeferredContent: SetReturnType<SetDeferredContentFunction, Content> = (
+    newContent: Content,
+    priority = 0,
+  ) => {
+    // If we've already stored content this render, only replace it if the new content has higher priority
+    if (
+      pendingContentRef.current === undefined ||
+      priority >= (pendingPriorityRef.current ?? -Infinity)
+    ) {
+      pendingContentRef.current = newContent
+      pendingPriorityRef.current = priority
     }
+    return pendingContentRef.current
   }
 
-  // Commit the collected tooltip after render
-  // oxlint-disable-next-line react-hooks/exhaustive-deps -- Must run after every render to sync collected tooltips
+  // Commit the stored content after render
+  // oxlint-disable-next-line react-hooks/exhaustive-deps -- Must run after every render to sync
   useEffect(() => {
-    if (collectedContent !== pendingContent.current) {
-      setCollectedContent(pendingContent.current)
+    if (getReactNodeKey(content) !== getReactNodeKey(pendingContentRef.current)) {
+      setContent(pendingContentRef.current)
     }
     // Reset for next render
-    pendingContent.current = null
-    pendingPriority.current = 0
+    pendingContentRef.current = undefined
+    pendingPriorityRef.current = undefined
   })
 
-  return {
-    onCollect,
-    collectedContent,
-  }
+  return [setDeferredContent, content] as const
 }
 
 export interface TooltipContentProps {
-  render?: RenderProps['render'] | undefined
   children: ReactNode
+  priority?: number | undefined
+  render?: RenderProp | undefined
 }
 
 /**
  * Wrap any text or `ReactNode` with this component to use it as the default `content` of the
- * nearest `Tooltip`, in addition to rendering it inline. It is meant to be wrapped in a `sr-only`
+ * closest `Tooltip`, in addition to rendering it inline. It is meant to be wrapped in a `sr-only`
  * element, so that the content rendered inline is visually hidden but accessible to screen readers,
  * unlike the content rendered in the tooltip itself, which is hidden from the accessibility tree
  * since most tooltips are decorative. This allows a tooltip to be non-decorative, in the rare case
  * where the information it provides is not otherwise available to screen readers (i.e. different
  * from the trigger's accessible name).
  */
-export function TooltipContent({ render, children }: TooltipContentProps) {
-  const collectTooltip = useCollectTooltip()
+export function TooltipContent({ children, priority, render }: TooltipContentProps) {
+  const ancestorTooltip = useContext(TooltipContext)
 
-  if (collectTooltip) {
-    collectTooltip(children || null, 100)
-  }
+  ancestorTooltip?.collectContent(children || null, priority)
 
-  if (render) {
-    return <Render render={render}>{children}</Render>
-  }
+  return render ? <Render render={render}>{children}</Render> : children
+}
+TooltipContent.displayName = 'Tooltip.Content'
+
+const TooltipCollectorContext = createContext<SetDeferredContentFunction | null>(null)
+
+export interface TooltipCollectorProps {
+  children: ReactNode
+}
 
-  return children
+export function TooltipCollector({ children }: TooltipCollectorProps) {
+  const ancestorTooltip = useContext(TooltipContext)
+
+  return (
+    <TooltipCollectorContext.Provider value={ancestorTooltip?.collectContent ?? null}>
+      {children}
+    </TooltipCollectorContext.Provider>
+  )
+}
+TooltipCollector.displayName = 'Tooltip.Collector'
+
+/** Hook for components to send tooltip content up to a collector. */
+export function useTooltipCollector() {
+  return useContext(TooltipCollectorContext)
 }

package/src/components/Tooltip.tsx

@@ -1,10 +1,10 @@
 import { TooltipCollector, TooltipContent, TooltipRoot } from './Tooltip.parts.tsx'
 
 export const Tooltip = Object.assign(TooltipRoot, {
-  Collector: TooltipCollector,
   Content: TooltipContent,
+  Collector: TooltipCollector,
 })
 
-export { useCollectTooltip, useCollectedTooltip } from './Tooltip.parts.tsx'
+export { useTooltipCollector } from './Tooltip.parts.tsx'
 
 export type { TooltipProps, TooltipCollectorProps, TooltipContentProps } from './Tooltip.parts.tsx'

package/src/components/base/Addon.meta.ts

@@ -1,3 +1,5 @@
 import { createComponent } from '@graphprotocol/gds-css'
 
-export const AddonMeta = createComponent('Addon')
+export const AddonMeta = createComponent('Addon', {
+  isolate: false,
+})