<TooltipHost
  content="This is the tooltip content"
  // This id is used on the tooltip itself, not the host
  // (so an element with this id only exists when the tooltip is shown)
  id={tooltipId}
  calloutProps={calloutProps}
  styles={hostStyles}
>
  <DefaultButton aria-describedby={tooltipId}>Hover over me</DefaultButton>
</TooltipHost>

<Tooltip content="Example tooltip" trigger={<Button content="A button" />} />

<Tooltip content="Copy" relationship="label">
  <Button icon={<CopyRegular />} />
</Tooltip>

<Tooltip content="This is an example" relationship="description">
  <a href="http://example.com">A link</a>
</Tooltip>

<Tooltip content={<b>The content can be JSX</b>} relationship="label">
  <Button />
</Tooltip>

<Tooltip content="Supports any component that accepts HTML attributes" relationship="label">
  <FancyButton />
</Tooltip>

<Tooltip content="The child can be a render function" relationship="description">
  {triggerProps => (
    <>
      <div>
        <button {...triggerProps}>The trigger element</button>
      </div>
    </>
  )}
</Tooltip>

<Tooltip
  content="It can target an element other than its trigger"
  relationship="description"
  positioning={{ target: targetElement }}
>
  <button>
    Custom target: <div ref={setTargetElement} />
  </button>
</Tooltip>

/**
 * Slot properties for Tooltip
 */
export type TooltipSlots = {
  /**
   * The text or JSX content of the tooltip.
   */
  content: NonNullable<Slot<'div'>>;
};

/**
 * Properties for Tooltip
 */
export type TooltipProps = ComponentProps<TooltipSlots> & {
  /**
   * (Required) Specifies whether this tooltip is acting as the description or label of its trigger element.
   *
   * * `label` - The tooltip sets the trigger's aria-label or aria-labelledby attribute. This is useful for buttons
   *    displaying only an icon, for example.
   * * `description` - The tooltip sets the trigger's aria-description or aria-describedby attribute.
   * * `inaccessible` - No aria attributes are set on the trigger. This makes the tooltip's content inaccessible to
   *   screen readers, and should only be used if the tooltip's text is available by some other means.
   */
  relationship: 'label' | 'description' | 'inaccessible';

  /**
   * The tooltip can have a single JSX child, or a render function that accepts TooltipTriggerProps.
   *
   * If no child is provided, the tooltip's target must be set with the `positioning` prop, and its
   * visibility must be controlled with the `visible` prop.
   */
  children?:
    | (React.ReactElement & { ref?: React.Ref<unknown> })
    | ((props: TooltipTriggerProps) => React.ReactElement | null)
    | null;

  /**
   * The tooltip's visual appearance.
   * * `normal` - Uses the theme's background and text colors.
   * * `inverted` - Higher contrast variant that uses the theme's inverted colors.
   *
   * @defaultvalue normal
   */
  appearance?: 'normal' | 'inverted';

  /**
   * Render an arrow pointing to the target element
   *
   * @defaultvalue false
   */
  withArrow?: boolean;

  /**
   * Configure the positioning of the tooltip
   *
   * @defaultvalue above
   */
  positioning?: PositioningShorthand;

  /**
   * Control the tooltip's visibility programatically.
   *
   * This can be used in conjunction with onVisibleChange to modify the tooltip's show and hide behavior.
   *
   * If not provided, the visibility will be controlled by the tooltip itself, based on hover and focus events on the
   * trigger (child) element.
   */
  visible?: boolean;

  /**
   * Notification when the visibility of the tooltip is changing
   */
  onVisibleChange?: (
    event: React.PointerEvent<HTMLElement> | React.FocusEvent<HTMLElement> | undefined,
    data: OnVisibleChangeData,
  ) => void;

  /**
   * Delay before the tooltip is shown, in milliseconds.
   *
   * @defaultvalue 250
   */
  showDelay?: number;

  /**
   * Delay before the tooltip is hidden, in milliseconds.
   *
   * @defaultvalue 250
   */
  hideDelay?: number;
};

/**
 * The properties that are added to the trigger of the Tooltip
 */
export type TooltipTriggerProps = {
  ref?: React.Ref<never>;
} & Pick<
  React.HTMLAttributes<HTMLElement>,
  'onPointerEnter' | 'onPointerLeave' | 'onFocus' | 'onBlur' | 'aria-describedby' | 'aria-labelledby' | 'aria-label'
>;

/**
 * Data for the Tooltip's onVisibleChange event.
 */
export type OnVisibleChangeData = {
  visible: boolean;
};

/**
 * The context provided by TooltipProvider
 */
export type TooltipContextType = {
  /**
   * When a tooltip is shown, it sets itself as the visibleTooltip.
   * The next tooltip to become visible can use it to hide the previous tooltip immediately.
   */
  visibleTooltip?: {
    hide: () => void;
  };
};

/**
 * Context shared by all of the tooltips in the app
 */
export const TooltipContext = React.createContext<TooltipContextType>({});

<Tooltip content="Example" relationship="label">
  <button>
    <svg>...</svg>
  </button>
</Tooltip>

<body>
  <!-- App root -->
  <div>
    <button aria-label="Example" onPointerEnter="{...}" onPointerLeave="{...}" onFocus="{...}" onBlur="{...}">
      <svg>...</svg>
    </button>
  </div>
</body>

<Tooltip content="Example description of the button" relationship="description" withArrow>
  <button>The Button</button>
</Tooltip>

<body>
  <!-- App root -->
  <div>
    <button aria-describedby="tooltip-2" onPointerEnter="{...}" onPointerLeave="{...}" onFocus="{...}" onBlur="{...}">
      The Button
    </button>
  </div>

  <!-- Portal for Tooltip -->
  <div>
    <div role="tooltip" id="tooltip-2" class="{tooltip}">
      <div class="{arrow}"></div>
      Example description of the button
    </div>
  </div>
</body>