@titan-design/react-ui 0.1.0 → 0.2.5

package/src/components/ui/help-tip/HelpTip.stories.tsx

@@ -0,0 +1,250 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { HelpTip, LabelWithHelp } from './HelpTip'
+
+const meta: Meta<typeof HelpTip> = {
+  title: 'Components/HelpTip',
+  component: HelpTip,
+  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+    },
+    placement: {
+      control: 'select',
+      options: ['top', 'bottom', 'left', 'right'],
+    },
+    icon: {
+      control: 'select',
+      options: ['help', 'info', 'warning'],
+    },
+    color: {
+      control: 'select',
+      options: ['default', 'primary', 'secondary', 'muted'],
+    },
+    hasArrow: {
+      control: 'boolean',
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof HelpTip>
+
+export const Default: Story = {
+  args: {
+    content: 'This is helpful information about the feature.',
+    size: 'md',
+    placement: 'top',
+    icon: 'help',
+  },
+}
+
+export const AllIcons: Story = {
+  render: () => (
+    <View className="flex-row gap-8 items-center">
+      <View className="items-center gap-2">
+        <HelpTip content="Help icon tooltip" icon="help" />
+        <Text className="text-xs text-text-secondary">Help</Text>
+      </View>
+      <View className="items-center gap-2">
+        <HelpTip content="Info icon tooltip" icon="info" />
+        <Text className="text-xs text-text-secondary">Info</Text>
+      </View>
+      <View className="items-center gap-2">
+        <HelpTip content="Warning icon tooltip" icon="warning" />
+        <Text className="text-xs text-text-secondary">Warning</Text>
+      </View>
+    </View>
+  ),
+}
+
+export const AllSizes: Story = {
+  render: () => (
+    <View className="flex-row gap-8 items-center">
+      <View className="items-center gap-2">
+        <HelpTip content="Small help tip" size="sm" />
+        <Text className="text-xs text-text-secondary">Small</Text>
+      </View>
+      <View className="items-center gap-2">
+        <HelpTip content="Medium help tip" size="md" />
+        <Text className="text-xs text-text-secondary">Medium</Text>
+      </View>
+      <View className="items-center gap-2">
+        <HelpTip content="Large help tip" size="lg" />
+        <Text className="text-xs text-text-secondary">Large</Text>
+      </View>
+    </View>
+  ),
+}
+
+export const AllColors: Story = {
+  render: () => (
+    <View className="flex-row gap-6 items-center">
+      <HelpTip content="Default color" color="default" />
+      <HelpTip content="Primary color" color="primary" />
+      <HelpTip content="Secondary color" color="secondary" />
+      <HelpTip content="Muted color" color="muted" />
+    </View>
+  ),
+}
+
+export const AllPlacements: Story = {
+  render: () => (
+    <View className="gap-8 items-center py-16">
+      <View className="flex-row items-center gap-2">
+        <Text className="text-text-secondary w-16">Top:</Text>
+        <HelpTip content="Tooltip on top" placement="top" />
+      </View>
+      <View className="flex-row items-center gap-2">
+        <Text className="text-text-secondary w-16">Bottom:</Text>
+        <HelpTip content="Tooltip on bottom" placement="bottom" />
+      </View>
+      <View className="flex-row items-center gap-2">
+        <Text className="text-text-secondary w-16">Left:</Text>
+        <HelpTip content="Tooltip on left" placement="left" />
+      </View>
+      <View className="flex-row items-center gap-2">
+        <Text className="text-text-secondary w-16">Right:</Text>
+        <HelpTip content="Tooltip on right" placement="right" />
+      </View>
+    </View>
+  ),
+}
+
+export const WithLongContent: Story = {
+  args: {
+    content: 'This is a longer tooltip that contains more detailed information about the feature. It will wrap to multiple lines if needed, and you can customize the max width.',
+    maxWidth: 300,
+  },
+}
+
+export const WithRichContent: Story = {
+  render: () => (
+    <HelpTip
+      content={
+        <View className="gap-1">
+          <Text className="text-sm font-semibold text-text-primary">API Rate Limits</Text>
+          <Text className="text-xs text-text-secondary">
+            • Free tier: 100 requests/hour
+          </Text>
+          <Text className="text-xs text-text-secondary">
+            • Pro tier: 1000 requests/hour
+          </Text>
+          <Text className="text-xs text-text-secondary">
+            • Enterprise: Unlimited
+          </Text>
+        </View>
+      }
+      icon="info"
+      maxWidth={220}
+    />
+  ),
+}
+
+export const InlineWithLabel: Story = {
+  render: () => (
+    <View className="gap-4">
+      <View className="flex-row items-center gap-1">
+        <Text className="text-sm font-medium text-text-primary">Email Address</Text>
+        <HelpTip
+          content="We'll never share your email with third parties."
+          size="sm"
+        />
+      </View>
+
+      <View className="flex-row items-center gap-1">
+        <Text className="text-sm font-medium text-text-primary">Password</Text>
+        <HelpTip
+          content="Must be at least 8 characters with one uppercase, one lowercase, and one number."
+          size="sm"
+        />
+      </View>
+
+      <View className="flex-row items-center gap-1">
+        <Text className="text-sm font-medium text-text-primary">API Key</Text>
+        <HelpTip
+          content="Keep this secret! Anyone with this key can access your account."
+          icon="warning"
+          size="sm"
+          color="primary"
+        />
+      </View>
+    </View>
+  ),
+}
+
+export const LabelWithHelpComponent: Story = {
+  render: () => (
+    <View className="gap-4">
+      <LabelWithHelp
+        label="Username"
+        helpContent="Choose a unique username for your account."
+      />
+
+      <LabelWithHelp
+        label="Email Address"
+        helpContent="We'll use this for account notifications."
+        isRequired
+      />
+
+      <LabelWithHelp
+        label="Bio"
+        helpContent="Tell others a bit about yourself. Max 500 characters."
+        helpSize="sm"
+      />
+    </View>
+  ),
+}
+
+export const FormExample: Story = {
+  render: () => (
+    <View className="gap-4 p-4 bg-surface-base rounded-lg max-w-sm">
+      <Text className="text-lg font-semibold text-text-primary">Account Settings</Text>
+
+      <View className="gap-1">
+        <LabelWithHelp
+          label="Display Name"
+          helpContent="This is how your name will appear to other users."
+          isRequired
+        />
+        <View className="border border-border-input rounded-md px-3 py-2 bg-surface-input">
+          <Text className="text-text-primary">John Doe</Text>
+        </View>
+      </View>
+
+      <View className="gap-1">
+        <LabelWithHelp
+          label="Timezone"
+          helpContent="All dates and times will be displayed in this timezone."
+        />
+        <View className="border border-border-input rounded-md px-3 py-2 bg-surface-input">
+          <Text className="text-text-primary">America/New_York (EST)</Text>
+        </View>
+      </View>
+
+      <View className="gap-1">
+        <View className="flex-row items-center gap-1">
+          <Text className="text-sm font-medium text-text-primary">Two-Factor Authentication</Text>
+          <HelpTip
+            content="Enable 2FA for additional account security. You'll need an authenticator app."
+            icon="info"
+            size="sm"
+            color="primary"
+          />
+        </View>
+        <View className="border border-border-input rounded-md px-3 py-2 bg-surface-input">
+          <Text className="text-status-success">Enabled ✓</Text>
+        </View>
+      </View>
+    </View>
+  ),
+}
+
+export const NoArrow: Story = {
+  args: {
+    content: 'This tooltip has no arrow.',
+    hasArrow: false,
+  },
+}

package/src/components/ui/help-tip/HelpTip.test.tsx

@@ -0,0 +1,198 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { HelpTip, LabelWithHelp } from './HelpTip'
+
+describe('HelpTip', () => {
+  it('renders the help icon button', () => {
+    render(<HelpTip content="Help text" />)
+    expect(screen.getByRole('button', { name: 'Show help information' })).toBeInTheDocument()
+  })
+
+  it('shows tooltip content when pressed', () => {
+    render(<HelpTip content="This is helpful" />)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Show help information' }))
+    expect(screen.getByText('This is helpful')).toBeInTheDocument()
+  })
+
+  it('hides tooltip content when pressed again', () => {
+    render(<HelpTip content="Toggle me" />)
+
+    const button = screen.getByRole('button', { name: 'Show help information' })
+    fireEvent.click(button)
+    expect(screen.getByText('Toggle me')).toBeInTheDocument()
+
+    fireEvent.click(button)
+    expect(screen.queryByText('Toggle me')).not.toBeInTheDocument()
+  })
+
+  it('renders custom ReactNode content', () => {
+    render(
+      <HelpTip content={<span data-testid="custom-content">Rich content</span>} />
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Show help information' }))
+    expect(screen.getByTestId('custom-content')).toBeInTheDocument()
+  })
+
+  describe('controlled state', () => {
+    it('shows tooltip when isOpen is true', () => {
+      render(<HelpTip content="Always visible" isOpen />)
+      expect(screen.getByText('Always visible')).toBeInTheDocument()
+    })
+
+    it('hides tooltip when isOpen is false', () => {
+      render(<HelpTip content="Always hidden" isOpen={false} />)
+      expect(screen.queryByText('Always hidden')).not.toBeInTheDocument()
+    })
+
+    it('does not toggle on press when controlled', () => {
+      render(<HelpTip content="Controlled" isOpen={false} />)
+
+      fireEvent.click(screen.getByRole('button', { name: 'Show help information' }))
+      expect(screen.queryByText('Controlled')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('icon types', () => {
+    it('renders help icon by default', () => {
+      render(<HelpTip content="Help" />)
+      expect(screen.getByText('?')).toBeInTheDocument()
+    })
+
+    it('renders info icon', () => {
+      render(<HelpTip content="Info" icon="info" />)
+      expect(screen.getByRole('button', { name: 'Show help information' })).toBeInTheDocument()
+    })
+
+    it('renders warning icon', () => {
+      render(<HelpTip content="Warning" icon="warning" />)
+      expect(screen.getByRole('button', { name: 'Show help information' })).toBeInTheDocument()
+    })
+  })
+
+  describe('sizes', () => {
+    it('renders with sm size', () => {
+      render(<HelpTip content="Small" size="sm" />)
+      expect(screen.getByRole('button', { name: 'Show help information' })).toBeInTheDocument()
+    })
+
+    it('renders with md size (default)', () => {
+      render(<HelpTip content="Medium" size="md" />)
+      expect(screen.getByRole('button', { name: 'Show help information' })).toBeInTheDocument()
+    })
+
+    it('renders with lg size', () => {
+      render(<HelpTip content="Large" size="lg" />)
+      expect(screen.getByRole('button', { name: 'Show help information' })).toBeInTheDocument()
+    })
+  })
+
+  describe('colors', () => {
+    it('renders with default color', () => {
+      render(<HelpTip content="Default" color="default" />)
+      expect(screen.getByRole('button')).toBeInTheDocument()
+    })
+
+    it('renders with primary color', () => {
+      render(<HelpTip content="Primary" color="primary" />)
+      expect(screen.getByRole('button')).toBeInTheDocument()
+    })
+
+    it('renders with secondary color', () => {
+      render(<HelpTip content="Secondary" color="secondary" />)
+      expect(screen.getByRole('button')).toBeInTheDocument()
+    })
+
+    it('renders with muted color', () => {
+      render(<HelpTip content="Muted" color="muted" />)
+      expect(screen.getByRole('button')).toBeInTheDocument()
+    })
+  })
+
+  describe('placement', () => {
+    it('renders with top placement (default)', () => {
+      render(<HelpTip content="Top" placement="top" isOpen />)
+      expect(screen.getByText('Top')).toBeInTheDocument()
+    })
+
+    it('renders with bottom placement', () => {
+      render(<HelpTip content="Bottom" placement="bottom" isOpen />)
+      expect(screen.getByText('Bottom')).toBeInTheDocument()
+    })
+
+    it('renders with left placement', () => {
+      render(<HelpTip content="Left" placement="left" isOpen />)
+      expect(screen.getByText('Left')).toBeInTheDocument()
+    })
+
+    it('renders with right placement', () => {
+      render(<HelpTip content="Right" placement="right" isOpen />)
+      expect(screen.getByText('Right')).toBeInTheDocument()
+    })
+  })
+
+  describe('arrow', () => {
+    it('renders with arrow by default', () => {
+      render(<HelpTip content="With arrow" isOpen />)
+      expect(screen.getByText('With arrow')).toBeInTheDocument()
+    })
+
+    it('renders without arrow when hasArrow is false', () => {
+      render(<HelpTip content="No arrow" hasArrow={false} isOpen />)
+      expect(screen.getByText('No arrow')).toBeInTheDocument()
+    })
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(<HelpTip content="Accessible help tip" />)
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it('has correct accessibility label', () => {
+      render(<HelpTip content="Help text" />)
+      expect(screen.getByLabelText('Show help information')).toBeInTheDocument()
+    })
+
+    it('sets accessibility hint for string content', () => {
+      render(<HelpTip content="This is a hint" />)
+      const button = screen.getByRole('button', { name: 'Show help information' })
+      expect(button).toBeInTheDocument()
+    })
+  })
+})
+
+describe('LabelWithHelp', () => {
+  it('renders label text', () => {
+    render(<LabelWithHelp label="API Key" helpContent="Found in settings" />)
+    expect(screen.getByText('API Key')).toBeInTheDocument()
+  })
+
+  it('renders help icon alongside label', () => {
+    render(<LabelWithHelp label="Field" helpContent="Help text" />)
+    expect(screen.getByRole('button', { name: 'Show help information' })).toBeInTheDocument()
+  })
+
+  it('shows required indicator when isRequired is true', () => {
+    render(<LabelWithHelp label="Email" helpContent="Help" isRequired />)
+    expect(screen.getByText('*')).toBeInTheDocument()
+  })
+
+  it('does not show required indicator by default', () => {
+    render(<LabelWithHelp label="Email" helpContent="Help" />)
+    expect(screen.queryByText('*')).not.toBeInTheDocument()
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(
+        <LabelWithHelp label="Username" helpContent="Choose a unique username" />
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+})

package/src/components/ui/help-tip/HelpTip.tsx

@@ -0,0 +1,229 @@
+import React, { useState } from 'react'
+import { View, Text, Pressable, type ViewProps } from 'react-native'
+import { cn } from '../../../utils/cn'
+
+export type HelpTipSize = 'sm' | 'md' | 'lg'
+export type HelpTipPlacement = 'top' | 'bottom' | 'left' | 'right'
+export type HelpTipIcon = 'help' | 'info' | 'warning'
+
+export interface HelpTipProps extends ViewProps {
+  /** Tooltip content */
+  content: React.ReactNode
+  /** Size of the icon */
+  size?: HelpTipSize
+  /** Placement of the tooltip */
+  placement?: HelpTipPlacement
+  /** Icon type */
+  icon?: HelpTipIcon
+  /** Icon color */
+  color?: 'default' | 'primary' | 'secondary' | 'muted'
+  /** Whether the tooltip is always visible (controlled) */
+  isOpen?: boolean
+  /** Whether to show an arrow */
+  hasArrow?: boolean
+  /** Max width of the tooltip */
+  maxWidth?: number
+  /** Additional className for the icon */
+  iconClassName?: string
+  /** Additional className for the tooltip */
+  tooltipClassName?: string
+}
+
+const sizeStyles: Record<HelpTipSize, { icon: string; text: string }> = {
+  sm: { icon: 'w-3.5 h-3.5 text-xs', text: 'text-xs' },
+  md: { icon: 'w-4 h-4 text-sm', text: 'text-sm' },
+  lg: { icon: 'w-5 h-5 text-base', text: 'text-base' },
+}
+
+const colorStyles: Record<string, string> = {
+  default: 'text-text-tertiary',
+  primary: 'text-brand-primary',
+  secondary: 'text-text-secondary',
+  muted: 'text-text-tertiary opacity-60',
+}
+
+const iconMap: Record<HelpTipIcon, string> = {
+  help: '?',
+  info: 'ℹ',
+  warning: '⚠',
+}
+
+const placementStyles: Record<HelpTipPlacement, string> = {
+  top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
+  bottom: 'top-full left-1/2 -translate-x-1/2 mt-2',
+  left: 'right-full top-1/2 -translate-y-1/2 mr-2',
+  right: 'left-full top-1/2 -translate-y-1/2 ml-2',
+}
+
+const arrowStyles: Record<HelpTipPlacement, string> = {
+  top: 'bottom-0 left-1/2 -translate-x-1/2 translate-y-full border-t-surface-elevated border-x-transparent border-b-transparent',
+  bottom: 'top-0 left-1/2 -translate-x-1/2 -translate-y-full border-b-surface-elevated border-x-transparent border-t-transparent',
+  left: 'right-0 top-1/2 -translate-y-1/2 translate-x-full border-l-surface-elevated border-y-transparent border-r-transparent',
+  right: 'left-0 top-1/2 -translate-y-1/2 -translate-x-full border-r-surface-elevated border-y-transparent border-l-transparent',
+}
+
+/**
+ * HelpTip component for displaying contextual help information.
+ *
+ * A small icon (typically a question mark or info icon) that shows
+ * a tooltip with helpful information when hovered or pressed.
+ *
+ * @example
+ * // Basic usage
+ * <HelpTip content="This field is required for form submission." />
+ *
+ * @example
+ * // With custom icon and placement
+ * <HelpTip
+ *   content="API rate limits apply to this endpoint."
+ *   icon="warning"
+ *   placement="right"
+ *   color="primary"
+ * />
+ *
+ * @example
+ * // Inline with label
+ * <View className="flex-row items-center gap-1">
+ *   <Text>Email Address</Text>
+ *   <HelpTip content="We'll never share your email with anyone." size="sm" />
+ * </View>
+ */
+export function HelpTip({
+  content,
+  size = 'md',
+  placement = 'top',
+  icon = 'help',
+  color = 'default',
+  isOpen: controlledIsOpen,
+  hasArrow = true,
+  maxWidth = 250,
+  iconClassName,
+  tooltipClassName,
+  className,
+  ...props
+}: HelpTipProps) {
+  const [internalIsOpen, setInternalIsOpen] = useState(false)
+  const isOpen = controlledIsOpen ?? internalIsOpen
+
+  const { icon: iconSize, text: textSize } = sizeStyles[size]
+
+  const handlePress = () => {
+    if (controlledIsOpen === undefined) {
+      setInternalIsOpen((prev) => !prev)
+    }
+  }
+
+  const handleHoverIn = () => {
+    if (controlledIsOpen === undefined) {
+      setInternalIsOpen(true)
+    }
+  }
+
+  const handleHoverOut = () => {
+    if (controlledIsOpen === undefined) {
+      setInternalIsOpen(false)
+    }
+  }
+
+  return (
+    <View className={cn('relative inline-flex', className)} {...props}>
+      {/* Icon button */}
+      <Pressable
+        onPress={handlePress}
+        onHoverIn={handleHoverIn}
+        onHoverOut={handleHoverOut}
+        accessibilityRole="button"
+        accessibilityLabel="Show help information"
+        accessibilityHint={typeof content === 'string' ? content : undefined}
+        className={cn(
+          'items-center justify-center rounded-full',
+          'border border-current',
+          colorStyles[color],
+          iconSize,
+          'web:hover:opacity-80 web:cursor-help',
+          iconClassName
+        )}
+      >
+        <Text className={cn('font-semibold', iconSize, colorStyles[color])}>
+          {iconMap[icon]}
+        </Text>
+      </Pressable>
+
+      {/* Tooltip */}
+      {isOpen && (
+        <View
+          className={cn(
+            'absolute z-50',
+            'bg-surface-elevated rounded-lg shadow-lg',
+            'border border-border-default',
+            'px-3 py-2',
+            placementStyles[placement],
+            tooltipClassName
+          )}
+          style={{ maxWidth }}
+        >
+          {typeof content === 'string' ? (
+            <Text className={cn('text-text-primary', textSize)}>
+              {content}
+            </Text>
+          ) : (
+            content
+          )}
+
+          {/* Arrow */}
+          {hasArrow && (
+            <View
+              className={cn(
+                'absolute w-0 h-0',
+                'border-4',
+                arrowStyles[placement]
+              )}
+            />
+          )}
+        </View>
+      )}
+    </View>
+  )
+}
+
+export interface LabelWithHelpProps extends ViewProps {
+  /** Label text */
+  label: string
+  /** Help content */
+  helpContent: React.ReactNode
+  /** Whether the field is required */
+  isRequired?: boolean
+  /** Size of the help icon */
+  helpSize?: HelpTipSize
+  /** Additional className */
+  className?: string
+}
+
+/**
+ * Convenience component combining a label with a help tip.
+ *
+ * @example
+ * <LabelWithHelp
+ *   label="API Key"
+ *   helpContent="Your API key can be found in the developer settings."
+ *   isRequired
+ * />
+ */
+export function LabelWithHelp({
+  label,
+  helpContent,
+  isRequired = false,
+  helpSize = 'sm',
+  className,
+  ...props
+}: LabelWithHelpProps) {
+  return (
+    <View className={cn('flex-row items-center gap-1', className)} {...props}>
+      <Text className="text-sm font-medium text-text-primary">
+        {label}
+        {isRequired && <Text className="text-status-error ml-0.5">*</Text>}
+      </Text>
+      <HelpTip content={helpContent} size={helpSize} />
+    </View>
+  )
+}

package/src/components/ui/help-tip/index.ts

@@ -0,0 +1,2 @@
+export { HelpTip, LabelWithHelp } from './HelpTip'
+export type { HelpTipProps, LabelWithHelpProps, HelpTipSize, HelpTipPlacement, HelpTipIcon } from './HelpTip'