@redis-ui/components 43.0.2 → 43.2.1

package/skills/redis-ui-components/references/Tooltip.md

@@ -0,0 +1,636 @@
+# Tooltip
+
+Popup component triggered by pointer hover, with customizable content, controlled state, and composition helpers.
+
+## Import
+
+```tsx
+import { Tooltip, TooltipProvider } from '@redislabsdev/redis-ui-components';
+```
+
+> `TooltipProvider` is exported alongside `Tooltip` and sets the shared hover delay (`openDelayDuration`, default `0`).
+
+> Examples that use `InfoIcon` also import it from `@redislabsdev/redis-ui-icons`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Trigger content rendered inside the tooltip wrapper |
+| content | `ReactNode` | - | Tooltip content; falsy values hide the tooltip and string content is wrapped automatically |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Side where the tooltip is rendered |
+| sideOffset | `number` | `5` | Gap between the trigger and the tooltip panel |
+| maxWidth | `string` | theme default | Maximum width of the tooltip panel |
+| alignOffset | `number` | - | Offset applied along the alignment axis |
+| align | `'start' \| 'center' \| 'end'` | - | Alignment of the tooltip panel relative to the trigger |
+| disableInteractionHelper | `boolean` | - | Deprecated interaction helper flag |
+| portal | `HTMLElement \| null` | `document.body` | Portal container; `null` renders without a portal |
+| collisionBoundary | `RadixTooltip.TooltipContentProps['collisionBoundary']` | - | Radix collision boundary forwarded to the content |
+| defaultOpen | `boolean` | - | Starts the tooltip open in uncontrolled mode |
+| openDelayDuration | `number` | - | Delay before the tooltip opens |
+| open | `boolean` | - | Controlled open state |
+| onOpenChange | `(open: boolean) => void` | - | Called when the open state changes |
+| disabled | `boolean` | - | Prevents the tooltip from opening |
+| interactive | `boolean` | `false` | Keeps the tooltip open when the pointer moves into the content |
+| withButton | `boolean` | `false` | Wraps trigger content in an invisible button for plain text, SVG, or multi-element triggers |
+
+## TooltipProvider
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| openDelayDuration | `number` | `0` | Shared hover delay applied by the Radix tooltip provider |
+| children | `React.ReactNode` | required | Tooltip tree wrapped by the provider |
+
+## Sub-components
+
+- `Tooltip.Compose` - Wraps the Radix tooltip root and handles controlled, uncontrolled, and interactive tooltip state.
+- `Tooltip.Trigger` - Attaches tooltip trigger behavior to child content.
+- `Tooltip.Content` - Renders the tooltip panel and auto-wraps string content in `Tooltip.Content.Text`.
+- `Tooltip.Content.Compose` - Low-level tooltip content wrapper that controls placement, portal, width, and collision behavior.
+- `Tooltip.Content.Text` - Typography body wrapper for simple tooltip text.
+- `Tooltip.Card` - Formatted tooltip card variant with header, body, and footer blocks.
+- `Tooltip.Card.Compose` - Low-level wrapper for composing card content.
+- `Tooltip.Card.Header` - Header block for tooltip cards; defaults to hiding the close button.
+- `Tooltip.Card.Header.Compose` - Low-level header wrapper.
+- `Tooltip.Card.Header.Title` - Header title text; inherits `TypographyHeadingProps`.
+- `Tooltip.Card.Body` - Body block for tooltip cards.
+- `Tooltip.Card.Body.Compose` - Low-level body wrapper.
+- `Tooltip.Card.Body.Text` - Body text; inherits `TypographyBodyProps`.
+- `Tooltip.Card.Footer` - Footer block for tooltip cards with optional action button and link.
+- `Tooltip.Card.Footer.Compose` - Low-level footer wrapper.
+
+## Tooltip.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Tooltip root children, typically `Tooltip.Trigger` and `Tooltip.Content` |
+| defaultOpen | `boolean` | - | Starts the tooltip open in uncontrolled mode |
+| openDelayDuration | `number` | - | Delay before opening the tooltip |
+| open | `boolean` | - | Controlled open state |
+| onOpenChange | `(open: boolean) => void` | - | Called when the open state changes |
+| disabled | `boolean` | - | Prevents the tooltip from opening |
+| interactive | `boolean` | `false` | Keeps the tooltip open when the pointer moves into the tooltip content |
+
+## Tooltip.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Trigger content |
+| withButton | `boolean` | `false` | Wraps the trigger content in an invisible button |
+
+## Tooltip.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| content | `ReactNode` | - | Tooltip content; string values are wrapped in `Tooltip.Content.Text` |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Side where the tooltip is rendered |
+| sideOffset | `number` | `5` | Gap between trigger and content |
+| maxWidth | `string` | theme default | Maximum width of the tooltip panel |
+| alignOffset | `number` | - | Offset along the alignment axis |
+| align | `'start' \| 'center' \| 'end'` | - | Alignment of the tooltip panel relative to the trigger |
+| disableInteractionHelper | `boolean` | - | Deprecated interaction helper flag |
+| portal | `HTMLElement \| null` | `document.body` | Portal container; `null` renders the tooltip inline |
+| collisionBoundary | `RadixTooltip.TooltipContentProps['collisionBoundary']` | - | Radix collision boundary forwarded to the content |
+
+## Tooltip.Content.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Tooltip content body |
+| backgroundColor | `string` | - | Overrides the tooltip background color |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Tooltip side relative to the trigger |
+| sideOffset | `number` | `5` | Gap between trigger and content |
+| maxWidth | `string` | theme default | Maximum width of the tooltip panel |
+| alignOffset | `number` | - | Offset along the alignment axis |
+| align | `'start' \| 'center' \| 'end'` | - | Alignment of the tooltip panel |
+| disableInteractionHelper | `boolean` | - | Deprecated interaction helper flag |
+| portal | `HTMLElement \| null` | `document.body` | Portal container; `null` renders without a portal |
+| collisionBoundary | `RadixTooltip.TooltipContentProps['collisionBoundary']` | - | Radix collision boundary forwarded to the content |
+
+## Tooltip.Card Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | `string` | - | Card title shown in the header |
+| text | `string` | - | Card body text |
+| actionButtonText | `string` | - | Label for the optional action button |
+| actionButtonHandler | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Click handler for the action button |
+| link | `string` | - | Optional footer link URL |
+| linkText | `string` | - | Label for the footer link |
+
+`Tooltip.Card` also accepts standard div attributes via the underlying compose wrapper.
+
+## Tooltip.Card.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Card content wrapper and standard div attributes from the underlying compose wrapper |
+
+## Tooltip.Card.Header Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | `string` | - | Header title |
+| hideCloseButton | `boolean` | `true` | Hides the close button by default |
+| children | `React.ReactNode` | - | Standard div attributes from the wrapped header component |
+
+## Tooltip.Card.Header.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Header composition content and standard div attributes |
+
+## Tooltip.Card.Body Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| text | `string` | - | Body text |
+| children | `React.ReactNode` | - | Standard div attributes from the wrapped body component |
+
+## Tooltip.Card.Body.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Body composition content and standard div attributes |
+
+## Tooltip.Card.Footer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| actionButtonText | `string` | - | Label for the action button |
+| actionButtonHandler | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Click handler for the action button |
+| link | `string` | - | Optional footer link URL |
+| linkText | `string` | - | Label for the footer link |
+| children | `React.ReactNode` | - | Standard div attributes from the wrapped footer component |
+
+## Tooltip.Card.Footer.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Footer composition content and standard div attributes |
+
+## Examples
+
+### Playground
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+
+<Tooltip content="Tooltips can display any content">
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+### TriggerWithButton
+
+> Tooltip Trigger has property `withButton` which allows wrapping trigger elements with invisible button.
+>
+> Use this property if you have multiple elements or your element doesn't work as trigger (e.g. svg, plain text)
+
+```tsx
+import { Tooltip } from '@redislabsdev/redis-ui-components';
+import { InfoIcon } from '@redislabsdev/redis-ui-icons';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Tooltip content="Plain text trigger" withButton defaultOpen={inStory}>
+        Plain text
+      </Tooltip>
+      <Tooltip content="SVG trigger" withButton defaultOpen={inStory}>
+        <InfoIcon />
+      </Tooltip>
+      <Tooltip content="Multiple elements trigger" withButton defaultOpen={inStory}>
+        <strong>Multiple</strong>&nbsp;<em>Elements</em>
+      </Tooltip>
+    </>
+  );
+}
+```
+
+### ProgrammaticallyOpened
+
+> Tooltip can be opened programmatically by setting `open` or `defaultOpen` props
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, Switch, Tooltip, Typography } from '@redislabsdev/redis-ui-components';
+
+function Render() {
+  const [open, setOpen] = useState(false);
+  const [enabled, setEnabled] = useState(false);
+  const [countDown, setCountDown] = useState(0);
+
+  const resetTimer = () => {
+    setCountDown(3);
+  };
+
+  useEffect(() => {
+    if (enabled) {
+      if (countDown > 0) {
+        const timer = setTimeout(() => {
+          setCountDown(countDown - 1);
+        }, 1000);
+
+        return () => clearTimeout(timer);
+      }
+
+      setOpen(true);
+    } else {
+      resetTimer();
+    }
+
+    return undefined;
+  }, [countDown, enabled]);
+
+  return (
+    <>
+      <Switch checked={enabled} onCheckedChange={setEnabled} />
+      {enabled ? (
+        <>
+          <Typography.Heading size="M">Tooltip will be open in {countDown} seconds</Typography.Heading>
+          <Tooltip
+            open={open}
+            content={
+              <div
+                style={{
+                  display: 'flex',
+                  flexDirection: 'column',
+                  alignItems: 'center',
+                  gap: 20
+                }}
+              >
+                <div>This tooltip is opened programmatically</div>
+                <Button
+                  onClick={() => {
+                    setOpen(false);
+                    setEnabled(false);
+                  }}
+                >
+                  Close
+                </Button>
+              </div>
+            }
+            withButton
+          >
+            Tooltip will be opened here
+          </Tooltip>
+        </>
+      ) : (
+        <Typography.Heading size="M">Switch timer ON</Typography.Heading>
+      )}
+    </>
+  );
+}
+```
+
+### TooltipPositions
+
+> Multiple Tooltips can be opened in the controlled mode only.
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Tooltip open={inStory} content="Left" placement="left">
+        <Button>Left</Button>
+      </Tooltip>
+      <Tooltip open={inStory} content="Top" placement="top">
+        <Button>Top</Button>
+      </Tooltip>
+      <Tooltip open={inStory} content="Bottom" placement="bottom">
+        <Button>Bottom</Button>
+      </Tooltip>
+      <Tooltip open={inStory} content="Right" placement="right">
+        <Button>Right</Button>
+      </Tooltip>
+    </>
+  );
+}
+```
+
+### TooltipAlign
+
+> Multiple Tooltips can be opened in the controlled mode only.
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Tooltip
+        open={inStory}
+        content={
+          <>
+            tooltip with <strong>align: end</strong> and <strong>alignOffset</strong>
+          </>
+        }
+        placement="top"
+        align="end"
+        alignOffset={-20}
+      >
+        <Button>align: end</Button>
+      </Tooltip>
+      <Tooltip
+        open={inStory}
+        content={
+          <>
+            tooltip with <strong>align: center</strong>
+          </>
+        }
+        placement="top"
+        align="center"
+      >
+        <Button>align: center</Button>
+      </Tooltip>
+      <Tooltip
+        open={inStory}
+        content={
+          <>
+            tooltip with <strong>align: start</strong>
+          </>
+        }
+        placement="top"
+        align="start"
+      >
+        <Button>align: start</Button>
+      </Tooltip>
+    </>
+  );
+}
+```
+
+### LongText
+
+> Long text in the tooltip content will be wrapped
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Tooltip
+      defaultOpen={inStory}
+      content="This is tooltip content with a really really really really really really really really really really really really long text"
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+  );
+}
+```
+
+### CustomMaxWidth
+
+> Custom `maxWidth` can be defined to make very long text laid out more consistently or to contain wider content
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Tooltip
+      defaultOpen={inStory}
+      maxWidth="1000rem"
+      content="Custom max width can be defined to make very long text laid out more consistently or contain wider content"
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+  );
+}
+```
+
+### InteractiveTooltip
+
+> If content of Tooltip should be reachable by mouse, `interactive` flag can be used.
+> It prevents closing Tooltip, when mouse leaves trigger in direction to the tooltip.
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+import { fn } from '@storybook/test';
+
+<Tooltip
+  content={
+    <>
+      If content of Tooltip should be reachable by mouse, <strong>interactive</strong> flag can be
+      used
+      <Tooltip.Card.Footer
+        actionButtonText="Click me"
+        linkText="Read me"
+        actionButtonHandler={fn()}
+        link="#"
+      />
+    </>
+  }
+  interactive
+>
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+### DisabledAndEmptyTooltip
+
+> Tooltip with empty (falsy) content or tooltip with `disabled` flag will not be visible
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Tooltip
+    content={
+      <>
+        Tooltip with empty (falsy) content or tooltip with <strong>disabled</strong> flag will not
+        be visible
+      </>
+    }
+  >
+    <Button>Hover me</Button>
+  </Tooltip>
+  <Tooltip content="Disabled" disabled open>
+    <Button>Disabled</Button>
+  </Tooltip>
+  <Tooltip content="" open>
+    <Button>Empty content</Button>
+  </Tooltip>
+</>
+```
+
+### Portal
+
+> Tooltip can be rendered without portal or with custom portal container, using `portal` prop
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Tooltip
+        open={inStory}
+        maxWidth="20vw"
+        content="This tooltip is rendered with default portal (document.body)"
+      >
+        <Button>With portal</Button>
+      </Tooltip>
+      <Tooltip open={inStory} portal={null} content="This tooltip is rendered without portal">
+        <Button>No portal</Button>
+      </Tooltip>
+    </>
+  );
+}
+```
+
+### ComposeTooltip
+
+> Tooltip can be composed using `Tooltip.Trigger`, `Tooltip.Content` and `Tooltip.Content.Text` components
+
+```tsx
+import { Tooltip } from '@redislabsdev/redis-ui-components';
+import { InfoIcon } from '@redislabsdev/redis-ui-icons';
+import { useViewMode } from '../../helpers/useViewMode';
+import * as S from './Tooltip.style';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Tooltip.Compose defaultOpen={inStory}>
+      <Tooltip.Trigger withButton>
+        <InfoIcon />
+        Hover me
+      </Tooltip.Trigger>
+      <Tooltip.Content.Compose backgroundColor="#eff9f5">
+        <S.TooltipContentText>This tooltip is composed</S.TooltipContentText>
+      </Tooltip.Content.Compose>
+    </Tooltip.Compose>
+  );
+}
+```
+
+### AsyncContent
+
+> Tooltip with async content.
+>
+> Make sure to add `interactive`, to prevent Tooltip getting
+> closed when content changes producing hover event.
+>
+> `⚠️` In general, try avoiding this approach and use a Popover instead, unless it's a must.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, Loader, Tooltip } from '@redislabsdev/redis-ui-components';
+
+function AsyncContentComponent() {
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const timeout = setTimeout(setLoading, 1500, false);
+
+    return () => clearTimeout(timeout);
+  }, []);
+
+  return loading ? (
+    <Loader size="15" />
+  ) : (
+    <div>
+      <p>Async content:</p>
+      <p>Loaded</p>
+    </div>
+  );
+}
+
+function Render() {
+  return (
+    <Tooltip interactive content={<AsyncContentComponent />}>
+      <Button>Get async content</Button>
+    </Tooltip>
+  );
+}
+```
+
+### Tooltip.Card Playground
+
+```tsx
+import { Tooltip } from '@redislabsdev/redis-ui-components';
+
+<Tooltip
+  open
+  content={
+    <Tooltip.Card
+      title="Tooltip Card"
+      text="Tooltip Card displays formatted content"
+      link="#"
+      actionButtonHandler={() => {}}
+      actionButtonText="Action"
+    />
+  }
+>
+  <span style={{ marginTop: 120 }} />
+</Tooltip>
+```
+
+### Tooltip.Card ComposeCard
+
+> `Tooltip.Card` can be composed of `Header`, `Body` and `Footer` component
+
+```tsx
+import { Button, Tooltip } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Tooltip
+      defaultOpen={inStory}
+      interactive
+      content={
+        <Tooltip.Card.Compose>
+          <Tooltip.Card.Header.Compose>
+            <Tooltip.Card.Header.Title>Custom Header title</Tooltip.Card.Header.Title>
+          </Tooltip.Card.Header.Compose>
+          <Tooltip.Card.Body.Compose>
+            <Tooltip.Card.Body.Text>Custom Body text</Tooltip.Card.Body.Text>
+          </Tooltip.Card.Body.Compose>
+          <Tooltip.Card.Footer.Compose>
+            <Button>Custom Footer button</Button>
+          </Tooltip.Card.Footer.Compose>
+        </Tooltip.Card.Compose>
+      }
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+  );
+}
+```
+
+## Notes
+
+- `TooltipProvider` defaults `openDelayDuration` to `0`.
+- `Tooltip.Content` hides itself when `content` is falsy.
+- `Tooltip.Trigger` can wrap plain text, SVG, or multi-element triggers by setting `withButton`.
+- `Tooltip.Compose` supports controlled and uncontrolled open state.
+- `Tooltip.Content.Compose` defaults `placement` to `top`, `sideOffset` to `5`, `portal` to `document.body`, and `interactive` to `false`.
+- `Tooltip.Card.Header` hides the close button by default.
+- `Tooltip.Card.Footer` renders nothing when both `link` and `actionButtonHandler` are missing.
+- For async tooltip content, prefer `Popover` unless the tooltip interaction is required.