@graphprotocol/gds-react 0.1.2 → 0.2.0

package/src/components/Tooltip.parts.tsx

@@ -2,10 +2,8 @@
 
 import {
   createContext,
-  useCallback,
   useContext,
   useEffect,
-  useMemo,
   useRef,
   useState,
   type ComponentProps,
@@ -13,24 +11,25 @@ import {
   type ReactNode,
 } from 'react'
 import { Tooltip } from '@base-ui/react/tooltip'
+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
 
 const TooltipContext = createContext<{
-  enabled: boolean
-  registerNestedSetOpen: (nestedSetOpen: (newOpen: boolean) => void) => void
+  collectContent: SetDeferredContentFunction
+  inheritContent: SetDeferredContentFunction
+  disableDescendants: boolean
+  registerDescendantSetOpen: (descendantSetOpen: (newOpen: boolean) => void) => void
 } | null>(null)
-const TooltipCollectorContext = createContext<
-  ((content: DefinedReactNode, priority?: number) => void) | null
->(null)
 
 const OPEN_DELAY = 300
 
@@ -40,24 +39,26 @@ 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
   /** The element that triggers the tooltip. */
-  children: ReactElement<Record<string, unknown>>
+  children: ReactElement
 }
 
 export function TooltipRoot({
   ref: passedRef,
   content: passedContent,
-  position,
+  side,
   gap,
   align,
+  alignOffset,
   open: controlledOpen,
   onOpenChange,
   disabled,
+  overrideDescendants,
   className,
   style,
   children,
@@ -65,44 +66,85 @@ export function TooltipRoot({
 }: TooltipProps) {
   const { dirProps } = useGDS()
 
+  const ancestorTooltip = useContext(TooltipContext)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+
   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 [setCollectedContent, collectedContent] = useDeferredContent()
+  const [setInheritedContent, inheritedContent] = useDeferredContent()
+
+  const content =
+    passedContent !== undefined
+      ? passedContent
+      : collectedContent !== undefined
+        ? collectedContent
+        : inheritedContent
 
-  const { onCollect, collectedContent } = useCollectedTooltip()
-  const content = passedContent !== undefined ? passedContent : collectedContent
+  const triggerDisabled =
+    'props' in children &&
+    children.props &&
+    typeof children.props === 'object' &&
+    'disabled' in children.props
+      ? children.props.disabled === true
+      : false
+
+  // Propagate the passed/collected content up for the first tooltip ancestor that needs them
+  if (passedContent !== undefined && !cssProps.disabled && !triggerDisabled) {
+    ancestorTooltip?.inheritContent(passedContent, 3)
+  }
+
+  const collectContent: SetDeferredContentFunction = (newCollectedContent, priority) => {
+    const prioritizedCollectedContent = setCollectedContent(newCollectedContent, priority)
+    if (!triggerDisabled) ancestorTooltip?.inheritContent(prioritizedCollectedContent, 2)
+  }
+
+  const inheritContent: SetDeferredContentFunction = (newInheritedContent, priority) => {
+    void setInheritedContent(newInheritedContent, priority)
+    if (!triggerDisabled) ancestorTooltip?.inheritContent(newInheritedContent, 1)
+  }
+
+  const disabledByAncestor = ancestorTooltip?.disableDescendants ?? false
+  const disableDescendants =
+    disabledByAncestor ||
+    triggerDisabled ||
+    (content !== undefined && !cssProps.disabled && cssProps.overrideDescendants)
+  const enabled = Boolean(content) && !cssProps.disabled && !triggerDisabled && !disabledByAncestor
 
-  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 descendantSetOpen = useRef<(newOpen: boolean) => void>(null)
+  const registerDescendantSetOpen = (newDescendantSetOpen: (newOpen: boolean) => void) => {
+    descendantSetOpen.current = newDescendantSetOpen
+  }
+  const justOpenedRef = useRef(false)
   const setOpen = (newOpen: boolean) => {
     ownSetOpen(newOpen)
     /**
-     * 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).
+     * Notify overridden descendant 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 tooltips nested under
+     * an enabled tooltip are disabled to prevent a lot of weirdness).
      */
-    nestedSetOpen.current?.(newOpen)
-  }
-  tooltipAncestor?.registerNestedSetOpen(setOpen)
-
-  if (cssProps.disabled && open) {
-    setOpen(false)
+    if (cssProps.overrideDescendants) {
+      descendantSetOpen.current?.(newOpen)
+    }
+    if (newOpen) {
+      justOpenedRef.current = true
+      window.setTimeout(() => {
+        justOpenedRef.current = false
+      }, 0)
+    }
   }
+  ancestorTooltip?.registerDescendantSetOpen(setOpen)
 
   const openTimeoutRef = useRef<number>(undefined)
   const clearOpenTimeout = () => {
@@ -114,147 +156,145 @@ export function TooltipRoot({
     clearOpenTimeout()
   }
 
-  const tooltipContextValue = useMemo(
-    () => ({
-      enabled,
-      registerNestedSetOpen,
-    }),
-    [enabled, registerNestedSetOpen],
-  )
-
   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,
+        inheritContent,
+        disableDescendants,
+        registerDescendantSetOpen,
+      }}
+    >
+      <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
+          }
+          // 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)
+        }}
+      >
+        <Tooltip.Trigger
+          ref={triggerRef}
+          delay={OPEN_DELAY}
+          closeDelay={100}
+          render={({ onClick: _onClick, ...renderProps }) => (
+            <Render {...(enabled ? renderProps : {})} render={children} />
+          )}
+        />
+        <Tooltip.Portal>
+          <Tooltip.Positioner
+            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}
+            {...dirProps}
+          >
+            <Tooltip.Popup
+              ref={passedRef}
+              data-side={cssProps.side}
+              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=end]:-translate-x-1
+                i:data-starting-style:data-[side=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>
+            >
+              {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}
+            {...props}
+          />
+        </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
-}
+function useDeferredContent() {
+  const [content, setContent] = useState<Content | undefined>(undefined)
+  const pendingContentRef = useRef<Content | undefined>(undefined)
+  const pendingPriorityRef = useRef<number | undefined>(undefined)
 
-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)
-}
-
-/** 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
+  render?: RenderProp | undefined
   children: ReactNode
 }
 
 /**
  * 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
@@ -262,15 +302,32 @@ export interface TooltipContentProps {
  * from the trigger's accessible name).
  */
 export function TooltipContent({ render, children }: TooltipContentProps) {
-  const collectTooltip = useCollectTooltip()
+  const ancestorTooltip = useContext(TooltipContext)
 
-  if (collectTooltip) {
-    collectTooltip(children || null, 100)
-  }
+  ancestorTooltip?.collectContent(children || null)
 
-  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)
 
-  return children
+export interface TooltipCollectorProps {
+  children: ReactNode
+}
+
+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,
+})