# Utility Functions

The tooltip system provides utility functions for advanced scenarios, including context scoping for nested tooltips and complex component hierarchies.

## Capabilities

### Context Scoping

Create scoped contexts for tooltip components to enable nesting and avoid conflicts.

```typescript { .api }
/**
 * Creates a scoped context for tooltip components
 * Enables nesting tooltips and avoiding context conflicts
 * @returns Scope object for scoped tooltip components
 */
function createTooltipScope(): Scope;

type Scope = {
  [scopeName: string]: React.Context<any>[];
};
```

**Usage Examples:**

```typescript
import { createTooltipScope, TooltipProvider, Tooltip } from "@radix-ui/react-tooltip";

// Basic scoped tooltips
function ScopedTooltips() {
  const scope = createTooltipScope();
  
  return (
    <TooltipProvider __scopeTooltip={scope}>
      <Tooltip __scopeTooltip={scope}>
        {/* This tooltip uses scoped context */}
      </Tooltip>
    </TooltipProvider>
  );
}

// Nested tooltip scenarios
function NestedTooltipExample() {
  const outerScope = createTooltipScope();
  const innerScope = createTooltipScope();
  
  return (
    <TooltipProvider __scopeTooltip={outerScope}>
      <Tooltip __scopeTooltip={outerScope}>
        <TooltipTrigger __scopeTooltip={outerScope}>
          Outer tooltip trigger
        </TooltipTrigger>
        <TooltipPortal __scopeTooltip={outerScope}>
          <TooltipContent __scopeTooltip={outerScope}>
            Outer tooltip content
            
            {/* Inner scoped tooltip */}
            <TooltipProvider __scopeTooltip={innerScope}>
              <Tooltip __scopeTooltip={innerScope}>
                <TooltipTrigger __scopeTooltip={innerScope}>
                  Inner trigger
                </TooltipTrigger>
                <TooltipPortal __scopeTooltip={innerScope}>
                  <TooltipContent __scopeTooltip={innerScope}>
                    Inner tooltip content
                  </TooltipContent>
                </TooltipPortal>
              </Tooltip>
            </TooltipProvider>
          </TooltipContent>
        </TooltipPortal>
      </Tooltip>
    </TooltipProvider>
  );
}

// Component library with scoped tooltips
function ComponentLibrary() {
  const libraryScope = createTooltipScope();
  
  return (
    <div className="library-wrapper">
      <TooltipProvider 
        __scopeTooltip={libraryScope}
        delayDuration={500}
      >
        {/* All tooltips in this library use scoped context */}
        <LibraryComponent scope={libraryScope} />
        <AnotherLibraryComponent scope={libraryScope} />
      </TooltipProvider>
    </div>
  );
}

function LibraryComponent({ scope }) {
  return (
    <Tooltip __scopeTooltip={scope}>
      <TooltipTrigger __scopeTooltip={scope}>
        Library component
      </TooltipTrigger>
      <TooltipPortal __scopeTooltip={scope}>
        <TooltipContent __scopeTooltip={scope}>
          Scoped tooltip for library
        </TooltipContent>
      </TooltipPortal>
    </Tooltip>
  );
}
```

### Scope Usage Patterns

#### Nested Tooltips

Use scoping when tooltips need to be nested within each other:

```typescript
// Each level gets its own scope
const level1Scope = createTooltipScope();
const level2Scope = createTooltipScope();
const level3Scope = createTooltipScope();
```

#### Component Library Isolation

Use scoping to isolate tooltip behavior in reusable components:

```typescript
// Library creates its own scope
function MyLibraryProvider({ children }) {
  const libraryScope = createTooltipScope();
  
  return (
    <TooltipProvider __scopeTooltip={libraryScope}>
      {React.Children.map(children, child => 
        React.cloneElement(child, { __scopeTooltip: libraryScope })
      )}
    </TooltipProvider>
  );
}
```

#### Multi-Instance Applications

Use scoping when multiple independent tooltip systems exist:

```typescript
function MultiInstanceApp() {
  const headerScope = createTooltipScope();
  const sidebarScope = createTooltipScope();
  const contentScope = createTooltipScope();
  
  return (
    <div>
      <Header tooltipScope={headerScope} />
      <Sidebar tooltipScope={sidebarScope} />
      <Content tooltipScope={contentScope} />
    </div>
  );
}
```

### Scope Properties

#### Context Isolation

Each scope creates isolated context that:
- Prevents provider/consumer mismatches across different tooltip hierarchies
- Allows independent configuration for different tooltip groups
- Enables safe nesting without context conflicts

#### Provider Independence

Scoped tooltips maintain independent:
- **Delay timers**: Each scope has its own delay state
- **Hover behavior**: Independent hover and grace area handling
- **Configuration**: Separate delay durations and settings
- **Event handling**: Isolated open/close event coordination

### Advanced Scoping

#### Scope Composition

Scopes can be composed for complex hierarchies:

```typescript
function ComplexApp() {
  const appScope = createTooltipScope();
  const modalScope = createTooltipScope();
  
  return (
    <TooltipProvider __scopeTooltip={appScope}>
      {/* App-level tooltips */}
      <AppTooltips scope={appScope} />
      
      <Modal>
        <TooltipProvider __scopeTooltip={modalScope}>
          {/* Modal-level tooltips */}
          <ModalTooltips scope={modalScope} />
        </TooltipProvider>
      </Modal>
    </TooltipProvider>
  );
}
```

#### Dynamic Scoping

Scopes can be created dynamically:

```typescript
function DynamicTooltips() {
  const [scopes] = useState(() => ({
    primary: createTooltipScope(),
    secondary: createTooltipScope(),
  }));
  
  return (
    <div>
      <Section scope={scopes.primary} />
      <Section scope={scopes.secondary} />
    </div>
  );
}
```

### Scope Integration

All tooltip components accept the `__scopeTooltip` prop:

- `TooltipProvider`
- `Tooltip` 
- `TooltipTrigger`
- `TooltipPortal`
- `TooltipContent`
- `TooltipArrow`

When using scopes, ensure all related components use the same scope object.

## Types

```typescript { .api }
type Scope = {
  [scopeName: string]: React.Context<any>[];
};

type ScopedProps<P = {}> = P & { 
  __scopeTooltip?: Scope;
};
```