jfs-components 0.0.1

package/src/components/Tooltip/Tooltip.mdx

@@ -0,0 +1,71 @@
+import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import * as TooltipStories from './Tooltip.stories';
+import { Tooltip } from './Tooltip';
+import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
+
+<Meta of={TooltipStories} />
+
+# Tooltip
+
+Tooltip component that displays contextual information when a user interacts with an element. It supports multiple placements, collision detection, and is styled using design tokens.
+
+## Available Collections and Modes
+
+This component uses the following design token collections. Each collection supports multiple modes that can be configured via the `modes` prop.
+
+### Color Mode
+- **Modes:** Light | Dark
+- **Default:** Light
+## Usage
+
+<Canvas>
+  <Story of={TooltipStories.Default} />
+</Canvas>
+
+<AccessibilitySection
+  items={[
+    'The `TooltipTrigger` should wrap an interactive element (e.g., a button or link) that is accessible via keyboard and screen readers.',
+    'Tooltips should not contain interactive elements (links, buttons) as they may be difficult to reach for keyboard users.',
+    'Screen readers generally announce the tooltip content when the trigger receives focus or is activated, depending on platform behavior.',
+  ]}
+/>
+
+<AnatomySection>
+  <ul>
+    <li><strong>Trigger</strong> — The element that toggles the tooltip visibility (wrapped in <code>TooltipTrigger</code>).</li>
+    <li><strong>Content</strong> — The container for the tooltip text or custom content (<code>TooltipContent</code>).</li>
+    <li><strong>Arrow</strong> — The visual indicator pointing to the trigger element, automatically positioned based on placement.</li>
+  </ul>
+</AnatomySection>
+
+<UsageConstraintsSection
+  items={[
+    'Wrap the trigger element with `TooltipTrigger` and the content with `TooltipContent` inside the `Tooltip` component.',
+    'Use the `placement` prop to specify the preferred position (top, bottom, left, right, and variations). The tooltip will automatically adjust if it hits the screen edges.',
+    'Ensure the `Tooltip` component is used within a `SafeAreaProvider` if not already provided by the app root (though the story decorator handles this).',
+    'For long text, the tooltip max-width is constrained by the `maxWidth` token. Text will wrap automatically.',
+  ]}
+/>
+
+## Props
+
+<ArgsTable of={Tooltip} />
+
+## Design Tokens
+
+This component uses the following design tokens, resolved through `getVariableByName`:
+
+- **`maxWidth`**
+- **`radius`**
+- **`tooltip/background`**
+- **`tooltip/label/color`**
+- **`tooltip/label/fontSize`**
+- **`tooltip/label/fontWeight`**
+- **`tooltip/label/lineHeight`**
+- **`tooltip/lable/fontFamily`**
+- **`tooltip/padding/horizontal`**
+- **`tooltip/padding/vertical`**
+- **`tooltip/tipItem/height`**
+- **`tooltip/tipItem/width`**
+
+All tokens support mode-based theming through the `modes` prop.

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,571 @@
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useRef,
+  useCallback,
+  useEffect,
+  ReactNode,
+} from 'react'
+import {
+  View,
+  Text,
+  Modal,
+  Pressable,
+  Platform,
+  StyleSheet,
+  ViewStyle,
+  TextStyle,
+  Dimensions,
+} from 'react-native'
+import Svg, { Path } from 'react-native-svg'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+
+// --- Types ---
+
+export type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end'
+
+type TooltipContextValue = {
+  isVisible: boolean
+  show: () => void
+  hide: () => void
+  toggle: () => void
+  triggerRef: React.RefObject<View | null>
+  triggerRect: Rect | null
+  setTriggerRect: (rect: Rect | null) => void
+  contentSize: Size | null
+  setContentSize: (size: Size) => void
+  modes: Record<string, any>
+  placement: Placement
+}
+
+type Rect = {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+type Size = {
+  width: number
+  height: number
+}
+
+// --- Context ---
+
+const TooltipContext = createContext<TooltipContextValue | undefined>(undefined)
+
+function useTooltipContext() {
+  const context = useContext(TooltipContext)
+  if (!context) {
+    throw new Error('Tooltip compound components must be used within a <Tooltip>')
+  }
+  return context
+}
+
+// --- Components ---
+
+export type TooltipProps = {
+  children: ReactNode
+  modes?: Record<string, any>
+  /** Initial visibility state (controlled) */
+  open?: boolean
+  /** Callback when visibility changes */
+  onOpenChange?: (open: boolean) => void
+  defaultOpen?: boolean
+  /** Preferred placement of the tooltip */
+  placement?: Placement
+}
+
+export function Tooltip({
+  children,
+  modes = {},
+  open,
+  onOpenChange,
+  defaultOpen = false,
+  placement = 'top',
+}: TooltipProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen)
+  const isControlled = open !== undefined
+  const isVisible = isControlled ? open : uncontrolledOpen
+
+  const triggerRef = useRef<View>(null)
+  const [triggerRect, setTriggerRect] = useState<Rect | null>(null)
+  const [contentSize, setContentSize] = useState<Size | null>(null)
+
+  const show = useCallback(() => {
+    if (!isControlled) setUncontrolledOpen(true)
+    onOpenChange?.(true)
+  }, [isControlled, onOpenChange])
+
+  const hide = useCallback(() => {
+    if (!isControlled) setUncontrolledOpen(false)
+    onOpenChange?.(false)
+  }, [isControlled, onOpenChange])
+
+  const toggle = useCallback(() => {
+    if (isVisible) hide()
+    else show()
+  }, [isVisible, hide, show])
+
+  // Poll for trigger position updates while visible to handle scrolling/resize
+  useEffect(() => {
+    if (!isVisible) return
+
+    let animationFrameId: number
+
+    const measure = () => {
+      if (triggerRef.current) {
+        triggerRef.current.measureInWindow((x, y, width, height) => {
+          // Only update if changed significantly to avoid thrashing
+          setTriggerRect((prev) => {
+            if (
+              !prev ||
+              Math.abs(prev.x - x) > 0.5 ||
+              Math.abs(prev.y - y) > 0.5 ||
+              prev.width !== width ||
+              prev.height !== height
+            ) {
+              return { x, y, width, height }
+            }
+            return prev
+          })
+        })
+      }
+      animationFrameId = requestAnimationFrame(measure)
+    }
+
+    measure()
+
+    return () => {
+      if (animationFrameId) cancelAnimationFrame(animationFrameId)
+    }
+  }, [isVisible])
+
+  return (
+    <TooltipContext.Provider
+      value={{
+        isVisible,
+        show,
+        hide,
+        toggle,
+        triggerRef,
+        triggerRect,
+        setTriggerRect,
+        contentSize,
+        setContentSize,
+        modes,
+        placement,
+      }}
+    >
+      {children}
+    </TooltipContext.Provider>
+  )
+}
+
+export type TooltipTriggerProps = {
+  children: React.ReactElement
+  asChild?: boolean
+} & React.ComponentProps<typeof Pressable>
+
+export function TooltipTrigger({ children, asChild, ...props }: TooltipTriggerProps) {
+  const { toggle, triggerRef, setTriggerRect } = useTooltipContext()
+
+  const handleLayout = () => {
+    // We need to measure in window
+    triggerRef.current?.measureInWindow((x, y, width, height) => {
+      setTriggerRect({ x, y, width, height })
+    })
+  }
+
+  // Initial measure on press as backup
+  const handlePress = (e: any) => {
+    triggerRef.current?.measureInWindow((x, y, width, height) => {
+      setTriggerRect({ x, y, width, height })
+      toggle()
+    })
+    
+    // Check if children is a valid element and has props
+    if (React.isValidElement(children)) {
+       const childProps = children.props as any
+       if (childProps.onPress) childProps.onPress(e)
+    }
+    if (props.onPress) props.onPress(e)
+  }
+  
+  if (asChild) {
+    if (!React.isValidElement(children)) return null
+    const childProps = children.props as any
+    
+    return React.cloneElement(children, {
+      ref: triggerRef,
+      onLayout: (e: any) => {
+        handleLayout()
+        if (childProps.onLayout) childProps.onLayout(e)
+      },
+      onPress: handlePress,
+      style: [childProps.style, Platform.OS === 'web' && { userSelect: 'none' }]
+    } as any)
+  }
+
+  return (
+    <Pressable
+      ref={triggerRef}
+      onLayout={handleLayout}
+      onPress={handlePress}
+      style={[{ alignSelf: 'flex-start' }, Platform.OS === 'web' && { userSelect: 'none' } as any]} // Wrap tightly
+      {...props}
+    >
+       {children}
+    </Pressable>
+  )
+}
+
+export type TooltipContentProps = {
+  children: ReactNode
+  sideOffset?: number
+}
+
+export function TooltipContent({ children, sideOffset = 4 }: TooltipContentProps) {
+  const { isVisible, hide, triggerRect, setContentSize, contentSize, modes, placement: preferredPlacement } = useTooltipContext()
+  const insets = useSafeAreaInsets()
+  const { width: windowWidth, height: windowHeight } = Dimensions.get('window')
+
+  // Tokens
+  const bgColor = (getVariableByName('tooltip/background', modes) as string) || '#0f0d0a'
+  const paddingH = Number(getVariableByName('tooltip/padding/horizontal', modes) || 12)
+  const paddingV = Number(getVariableByName('tooltip/padding/vertical', modes) || 8)
+  const radius = Number(getVariableByName('radius', modes) || 8)
+  const maxWidthToken = Number(getVariableByName('maxWidth', modes) || 280)
+  const arrowWidth = Number(getVariableByName('tooltip/tipItem/width', modes) || 16)
+  const arrowHeight = Number(getVariableByName('tooltip/tipItem/height', modes) || 8)
+  const labelColor = (getVariableByName('tooltip/label/color', modes) as string) || '#ffffff'
+  const fontSize = Number(getVariableByName('tooltip/label/fontSize', modes) || 14)
+  const fontWeight = (getVariableByName('tooltip/label/fontWeight', modes) as string) || '500'
+  const lineHeight = Number(getVariableByName('tooltip/label/lineHeight', modes) || 18)
+  const fontFamily = (getVariableByName('tooltip/lable/fontFamily', modes) as string) || undefined
+
+  if (!isVisible) return null
+
+  // Calculation Logic
+  const hasMeasured = !!contentSize && !!triggerRect
+  
+  let computedTop = 0
+  let computedLeft = 0
+  let arrowX = 0
+  let arrowY = 0
+  let finalPlacement = preferredPlacement
+  let finalAxis: 'top' | 'bottom' | 'left' | 'right' = 'top'
+
+  if (hasMeasured && triggerRect && contentSize) {
+    const tooltipH = contentSize.height
+    const tooltipW = contentSize.width
+    const gap = sideOffset + arrowHeight
+    const screenPadding = 8
+
+    // Helpers
+    const getAxis = (p: Placement): 'top' | 'bottom' | 'left' | 'right' => {
+      if (p.startsWith('top')) return 'top'
+      if (p.startsWith('bottom')) return 'bottom'
+      if (p.startsWith('left')) return 'left'
+      if (p.startsWith('right')) return 'right'
+      return 'top'
+    }
+
+    const checkFit = (p: Placement, axis: string): boolean => {
+      if (axis === 'top') return triggerRect.y - insets.top >= tooltipH + gap
+      if (axis === 'bottom') return windowHeight - (triggerRect.y + triggerRect.height) - insets.bottom >= tooltipH + gap
+      if (axis === 'left') return triggerRect.x - insets.left >= tooltipW + gap
+      if (axis === 'right') return windowWidth - (triggerRect.x + triggerRect.width) - insets.right >= tooltipW + gap
+      return false
+    }
+
+    let axis = getAxis(preferredPlacement)
+    
+    // Fallback Logic
+    if (!checkFit(preferredPlacement, axis)) {
+       const opposites: Record<string, 'top' | 'bottom' | 'left' | 'right'> = { 
+         top: 'bottom', bottom: 'top', left: 'right', right: 'left' 
+       }
+       const oppositeAxis = opposites[axis] as 'top' | 'bottom' | 'left' | 'right'
+       
+       if (checkFit(preferredPlacement, oppositeAxis)) {
+         axis = oppositeAxis
+         const parts = preferredPlacement.split('-')
+         const suffix = parts.length > 1 ? parts[1] : ''
+         finalPlacement = (axis + (suffix ? `-${suffix}` : '')) as Placement
+       } else {
+         // Pick max space
+         const spaceTop = triggerRect.y - insets.top
+         const spaceBottom = windowHeight - (triggerRect.y + triggerRect.height) - insets.bottom
+         const spaceLeft = triggerRect.x - insets.left
+         const spaceRight = windowWidth - (triggerRect.x + triggerRect.width) - insets.right
+         
+         if (['top', 'bottom'].includes(axis)) {
+             // Prefer staying vertical if possible, but swap to horizontal if MASSIVELY more space?
+             // For now, stick to flipping axis.
+             axis = spaceTop > spaceBottom ? 'top' : 'bottom'
+         } else {
+             axis = spaceLeft > spaceRight ? 'left' : 'right'
+         }
+         
+         const parts = preferredPlacement.split('-')
+         const suffix = parts.length > 1 ? parts[1] : ''
+         finalPlacement = (axis + (suffix ? `-${suffix}` : '')) as Placement
+       }
+    }
+    finalAxis = axis
+
+    // Calculate Coordinates based on final axis and alignment
+    const alignment = finalPlacement.split('-')[1] || 'center'
+    
+    // Main Axis Position
+    if (axis === 'top') {
+      computedTop = triggerRect.y - tooltipH - gap
+    } else if (axis === 'bottom') {
+      computedTop = triggerRect.y + triggerRect.height + gap
+    } else if (axis === 'left') {
+      computedLeft = triggerRect.x - tooltipW - gap
+    } else if (axis === 'right') {
+      computedLeft = triggerRect.x + triggerRect.width + gap
+    }
+
+    // Cross Axis Position & Shift to maintain arrow connection
+    if (axis === 'top' || axis === 'bottom') {
+       // 1. Initial Alignment
+       if (alignment === 'start') {
+         computedLeft = triggerRect.x
+       } else if (alignment === 'end') {
+         computedLeft = triggerRect.x + triggerRect.width - tooltipW
+       } else { // center
+         computedLeft = triggerRect.x + (triggerRect.width / 2) - (tooltipW / 2)
+       }
+
+       // 2. Shift to keep arrow connected (The "Detachment" Fix)
+       const triggerCenterX = triggerRect.x + triggerRect.width / 2
+       const arrowHalfWidth = arrowWidth / 2
+       // The arrow center must be within the tooltip horizontal range [left + radius + arrowHalf, left + w - radius - arrowHalf]
+       // So: computedLeft + radius + arrowHalf <= triggerCenterX <= computedLeft + w - radius - arrowHalf
+       const minLeftForConnection = triggerCenterX - (tooltipW - radius - arrowHalfWidth)
+       const maxLeftForConnection = triggerCenterX - (radius + arrowHalfWidth)
+       
+       if (computedLeft < minLeftForConnection) computedLeft = minLeftForConnection
+       if (computedLeft > maxLeftForConnection) computedLeft = maxLeftForConnection
+       
+       // 3. Clamp to Screen Edges
+       const minLeft = insets.left + screenPadding
+       const maxLeft = windowWidth - insets.right - tooltipW - screenPadding
+       if (computedLeft < minLeft) computedLeft = minLeft
+       if (computedLeft > maxLeft) computedLeft = maxLeft
+
+    } else { // left or right
+       // 1. Initial Alignment
+       if (alignment === 'start') {
+         computedTop = triggerRect.y
+       } else if (alignment === 'end') {
+         computedTop = triggerRect.y + triggerRect.height - tooltipH
+       } else { // center
+         computedTop = triggerRect.y + (triggerRect.height / 2) - (tooltipH / 2)
+       }
+
+       // 2. Shift to keep arrow connected
+       const triggerCenterY = triggerRect.y + triggerRect.height / 2
+       // Side arrows: "width" is 8 (tip), "height" is 16 (base).
+       // We use arrowWidth variable (16) as the base dimension along the tooltip edge.
+       const arrowHalfBase = arrowWidth / 2 
+       
+       const minTopForConnection = triggerCenterY - (tooltipH - radius - arrowHalfBase)
+       const maxTopForConnection = triggerCenterY - (radius + arrowHalfBase)
+       
+       if (computedTop < minTopForConnection) computedTop = minTopForConnection
+       if (computedTop > maxTopForConnection) computedTop = maxTopForConnection
+       
+       // 3. Clamp to Screen Edges
+       const minTop = insets.top + screenPadding
+       const maxTop = windowHeight - insets.bottom - tooltipH - screenPadding
+       if (computedTop < minTop) computedTop = minTop
+       if (computedTop > maxTop) computedTop = maxTop
+    }
+
+    // Arrow Positioning
+    // Arrow X/Y are relative to the Tooltip Content View (0,0 is top-left of tooltip)
+    // We add 1px overlap to fix gaps
+    const overlap = 1
+
+    if (axis === 'top' || axis === 'bottom') {
+       // Arrow is Horizontal (moving along X)
+       const triggerCenterX = triggerRect.x + triggerRect.width / 2
+       let relArrowX = triggerCenterX - computedLeft
+       const maxArrowX = tooltipW - radius - arrowWidth / 2
+       const minArrowX = radius + arrowWidth / 2
+       
+       if (relArrowX < minArrowX) relArrowX = minArrowX
+       if (relArrowX > maxArrowX) relArrowX = maxArrowX
+       
+       arrowX = relArrowX - arrowWidth / 2
+       arrowY = axis === 'top' ? tooltipH - overlap : -arrowHeight + overlap
+       
+    } else {
+       // Arrow is Vertical (moving along Y)
+       const triggerCenterY = triggerRect.y + triggerRect.height / 2
+       let relArrowY = triggerCenterY - computedTop
+       
+       // Container for side arrow: height is arrowWidth (16)
+       const arrowContainerH = arrowWidth
+       
+       const maxArrowY = tooltipH - radius - arrowContainerH / 2 
+       const minArrowY = radius + arrowContainerH / 2
+       
+       if (relArrowY < minArrowY) relArrowY = minArrowY
+       if (relArrowY > maxArrowY) relArrowY = maxArrowY
+       
+       arrowY = relArrowY - arrowContainerH / 2
+       arrowX = axis === 'left' ? tooltipW - overlap : -arrowHeight + overlap 
+    }
+  }
+
+  // --- Styles ---
+  
+  const contentStyle: ViewStyle = {
+    backgroundColor: bgColor,
+    paddingHorizontal: paddingH,
+    paddingVertical: paddingV,
+    borderRadius: radius,
+    maxWidth: maxWidthToken,
+  }
+
+  const textStyle: TextStyle = {
+    color: labelColor,
+    fontSize,
+    fontWeight: fontWeight as TextStyle['fontWeight'],
+    lineHeight,
+    fontFamily,
+  }
+
+  // Invisible measurement render
+  const measureStyle: ViewStyle = {
+    position: 'absolute',
+    opacity: 0,
+    top: 0, 
+    left: 0,
+    maxWidth: maxWidthToken, // Apply max width constraint during measurement
+    paddingHorizontal: paddingH,
+    paddingVertical: paddingV,
+  }
+
+  if (!hasMeasured) {
+    return (
+      <Modal transparent visible={isVisible} animationType="fade">
+         <View style={StyleSheet.absoluteFill} pointerEvents="none">
+             <View 
+               style={measureStyle} 
+               onLayout={(e) => setContentSize(e.nativeEvent.layout)}
+             >
+               {typeof children === 'string' ? (
+                 <Text style={textStyle}>{children}</Text>
+               ) : (
+                  <View>
+                    {React.Children.map(children, child => {
+                       if (React.isValidElement(child) && (child.type === Text || (child.type as any).displayName === 'Text')) {
+                           return React.cloneElement(child, { style: [textStyle, (child.props as any).style] } as any)
+                       }
+                       return child
+                    })}
+                  </View>
+               )}
+             </View>
+         </View>
+      </Modal>
+    )
+  }
+
+  return (
+    <Modal 
+      transparent 
+      visible={isVisible} 
+      animationType="fade"
+      onRequestClose={hide}
+    >
+      <Pressable style={StyleSheet.absoluteFill} onPress={hide}>
+        <View style={StyleSheet.absoluteFill} pointerEvents="box-none">
+          {/* Tooltip Body */}
+          <View 
+            style={[
+              contentStyle, 
+              { 
+                position: 'absolute', 
+                top: computedTop, 
+                left: computedLeft,
+                // Shadow for elevation
+                shadowColor: "#000",
+                shadowOffset: { width: 0, height: 2 },
+                shadowOpacity: 0.25,
+                shadowRadius: 3.84,
+                elevation: 5,
+              }
+            ]}
+          >
+             {typeof children === 'string' ? (
+                 <Text style={textStyle}>{children}</Text>
+               ) : (
+                  <View>
+                     {React.Children.map(children, child => {
+                       if (React.isValidElement(child) && (child.type === Text || (child.type as any).displayName === 'Text')) {
+                           return React.cloneElement(child, { style: [textStyle, (child.props as any).style] } as any)
+                       }
+                       return child
+                    })}
+                  </View>
+               )}
+             
+             {/* Arrow */}
+             {/* Render different arrow based on axis to avoid rotation gap issues */}
+             <View 
+                style={{
+                  position: 'absolute',
+                  left: arrowX,
+                  top: arrowY,
+                  width: (finalAxis === 'top' || finalAxis === 'bottom') ? arrowWidth : arrowHeight,
+                  height: (finalAxis === 'top' || finalAxis === 'bottom') ? arrowHeight : arrowWidth,
+                }}
+             >
+                <Svg 
+                  width={(finalAxis === 'top' || finalAxis === 'bottom') ? arrowWidth : arrowHeight} 
+                  height={(finalAxis === 'top' || finalAxis === 'bottom') ? arrowHeight : arrowWidth} 
+                  viewBox={`0 0 ${(finalAxis === 'top' || finalAxis === 'bottom') ? arrowWidth : arrowHeight} ${(finalAxis === 'top' || finalAxis === 'bottom') ? arrowHeight : arrowWidth}`}
+                >
+                  {finalAxis === 'top' && (
+                     <Path d={`M0 0 L${arrowWidth / 2} ${arrowHeight} L${arrowWidth} 0 Z`} fill={bgColor} />
+                  )}
+                  {finalAxis === 'bottom' && (
+                     <Path d={`M0 ${arrowHeight} L${arrowWidth / 2} 0 L${arrowWidth} ${arrowHeight} Z`} fill={bgColor} />
+                  )}
+                  {finalAxis === 'left' && (
+                     // Pointing Right. Width=arrowHeight (8), Height=arrowWidth (16)
+                     <Path d={`M0 0 L${arrowHeight} ${arrowWidth / 2} L0 ${arrowWidth} Z`} fill={bgColor} />
+                  )}
+                  {finalAxis === 'right' && (
+                     // Pointing Left
+                     <Path d={`M${arrowHeight} 0 L0 ${arrowWidth / 2} L${arrowHeight} ${arrowWidth} Z`} fill={bgColor} />
+                  )}
+                </Svg>
+             </View>
+          </View>
+        </View>
+      </Pressable>
+    </Modal>
+  )
+}