@redis-ui/components 42.8.0 → 43.2.1

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

@@ -0,0 +1,868 @@
+# Popover
+
+Popup component with trigger/content composition and a richer `Popover.Card` surface for formatted content.
+
+## Import
+
+```tsx
+import { Popover } from '@redislabsdev/redis-ui-components';
+```
+
+If you use the story examples that rely on icons, also import them from `@redislabsdev/redis-ui-icons`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Trigger content rendered inside the popover |
+| content | `React.ReactNode` | - | Content rendered inside the popover popup |
+| defaultOpen | `boolean` | - | Uncontrolled initial open state |
+| open | `boolean` | `visible` | Controlled open state |
+| onOpenChange | `(open: boolean) => void` | `onVisibilityChange` | Controlled open-state callback |
+| disabled | `boolean` | - | Disables opening and closes controlled content |
+| visible | `boolean` | - | Deprecated alias for `open` |
+| onVisibilityChange | `(open: boolean) => void` | - | Deprecated alias for `onOpenChange` |
+| withButton | `boolean` | - | Wraps the trigger in an invisible button when needed |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | `bottom` | Preferred popup side |
+| sideOffset | `number` | `5` | Offset between trigger and popup |
+| persistent | `boolean` | `false` | Prevents closing on outside click |
+| onClickOutside | `(event) => void` | - | Outside click handler |
+| alignOffset | `number` | - | Additional alignment offset |
+| align | `'start' \| 'center' \| 'end'` | `center` | Alignment against the trigger |
+| maxWidth | `string` | - | Max popup width override |
+| portal | `HTMLElement \| null` | `document.body` | Portal container or `null` to render inline |
+| collisionBoundary | `RadixPopover.PopoverContentProps['collisionBoundary']` | - | Radix collision boundary override |
+| windowBar | `WindowBarProps` | - | Deprecated `Popover.Content` alias for `Popover.Card` window bar content |
+| title | `string` | - | Deprecated `Popover.Content` alias for card header title |
+| text | `ContentBodyProps['text']` | - | Deprecated `Popover.Content` alias for card body text |
+| actionButtonText | `string` | - | Deprecated `Popover.Content` alias for card footer action label |
+| actionButtonHandler | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Deprecated `Popover.Content` alias for card footer action callback |
+| link | `string` | - | Deprecated `Popover.Content` alias for card footer link |
+| linkText | `string` | - | Deprecated `Popover.Content` alias for card footer link text |
+
+## Sub-components
+
+- `Popover.Compose` - Controlled root wrapper.
+- `Popover.Trigger` - Trigger wrapper for button and non-button triggers.
+- `Popover.Content` - Popup content surface.
+- `Popover.Card` - Rich content card surface.
+- `Popover.Content.Text` - Text wrapper for string content inside `Popover.Content`.
+- `Popover.Card.Close` - Close button alias for `Popover.Content.Close`.
+
+## Examples
+
+### Playground
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+
+<Popover content="Popovers can display any content" onOpenChange={() => {}}>
+  <Button>Click me</Button>
+</Popover>
+```
+
+### TriggerWithButton
+
+> `Popover.Trigger` has a `withButton` prop that wraps trigger elements with an invisible button.
+>
+> Use it when you have multiple trigger elements or when the trigger content does not work as a button, such as SVG or plain text.
+
+```tsx
+import { Popover } from '@redislabsdev/redis-ui-components';
+import { InfoIcon } from '@redislabsdev/redis-ui-icons';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Popover content="Plain text trigger" withButton defaultOpen={inStory}>
+        Plain text
+      </Popover>
+      <Popover content="SVG trigger" withButton defaultOpen={inStory}>
+        <InfoIcon />
+      </Popover>
+      <Popover content="Multiple elements trigger" withButton defaultOpen={inStory}>
+        <strong>Multiple</strong>&nbsp;<em>Elements</em>
+      </Popover>
+    </>
+  );
+}
+```
+
+### ProgrammaticallyOpened
+
+> `Popover` can be controlled by setting `open` and `onOpenChange`.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, Popover, Switch, Typography } from '@redislabsdev/redis-ui-components';
+import { StoryHList } from '../../helpers/Story.style';
+
+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 (
+    <StoryHList $gap="2rem">
+      <Switch checked={enabled} onCheckedChange={setEnabled} />
+      {enabled ? (
+        <>
+          <Typography.Heading size="M">
+            Popover will be open in {countDown} seconds
+          </Typography.Heading>
+          <Popover
+            open={open}
+            onOpenChange={(toOpen) => {
+              if (!toOpen) {
+                setOpen(false);
+                setEnabled(false);
+              }
+            }}
+            content={
+              <div
+                style={{
+                  display: 'flex',
+                  flexDirection: 'column',
+                  alignItems: 'center',
+                  gap: 20
+                }}
+              >
+                <div>This Popover is opened programmatically</div>
+                <Button
+                  onClick={() => {
+                    setOpen(false);
+                    setEnabled(false);
+                  }}
+                >
+                  Close
+                </Button>
+              </div>
+            }
+            withButton
+          >
+            Popover will be opened here
+          </Popover>
+        </>
+      ) : (
+        <Typography.Heading size="M">Switch timer ON</Typography.Heading>
+      )}
+    </StoryHList>
+  );
+}
+```
+
+### PopoverPlacements
+
+> Use `placement` to choose the preferred side of the trigger. The popover can flip when collisions occur.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Popover open={inStory} content="Left" placement="left">
+        <Button>Left</Button>
+      </Popover>
+      <Popover open={inStory} content="Top" placement="top">
+        <Button>Top</Button>
+      </Popover>
+      <Popover open={inStory} content="Bottom" placement="bottom">
+        <Button>Bottom</Button>
+      </Popover>
+      <Popover open={inStory} content="Right" placement="right">
+        <Button>Right</Button>
+      </Popover>
+    </>
+  );
+}
+```
+
+### PopoverAlign
+
+> Use `align` to choose the preferred alignment against the trigger. `alignOffset` can nudge the popup slightly.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Popover
+        open={inStory}
+        content={
+          <>
+            Popover with <strong>align: end</strong> and <strong>alignOffset</strong>
+          </>
+        }
+        placement="top"
+        align="end"
+        alignOffset={-20}
+      >
+        <Button>align: end</Button>
+      </Popover>
+      <Popover
+        open={inStory}
+        content={
+          <>
+            Popover with <strong>align: center</strong>
+          </>
+        }
+        placement="top"
+        align="center"
+      >
+        <Button>align: center</Button>
+      </Popover>
+      <Popover
+        open={inStory}
+        content={
+          <>
+            Popover with <strong>align: start</strong>
+          </>
+        }
+        placement="top"
+        align="start"
+      >
+        <Button>align: start</Button>
+      </Popover>
+    </>
+  );
+}
+```
+
+### LongText
+
+> Long text in the popover content will wrap.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Popover
+      defaultOpen={inStory}
+      content="This is Popover content with a really really really really really really really really really really really really long text"
+    >
+      <Button>Click me</Button>
+    </Popover>
+  );
+}
+```
+
+### CustomMaxWidth
+
+> `maxWidth` can make long text or wider content layout more consistently.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Popover
+      defaultOpen={inStory}
+      maxWidth="1000rem"
+      content="Custom maxWidth can be defined to make very long text laid out more consistently or contain wider content"
+    >
+      <Button>Click me</Button>
+    </Popover>
+  );
+}
+```
+
+### PersistentPopover
+
+> Use `persistent` when the popover should not close accidentally on outside click.
+>
+> Add a `Close` button so users can dismiss it explicitly.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+
+<Popover
+  persistent
+  content={
+    <>
+      <Popover.Content.Close />
+      If Popover should not be accidentally closed, <strong>persistent</strong> flag can be used
+      <Popover.Card.Footer
+        actionButtonText="Click me"
+        linkText="Read me"
+        actionButtonHandler={() => {}}
+        link="#"
+      />
+    </>
+  }
+>
+  <Button>Click me</Button>
+</Popover>
+```
+
+### ClickOutsideEvent
+
+> `onClickOutside` lets you react when the user clicks outside an opened popover.
+>
+> In this example, clicking outside causes the green indicator to flash.
+
+```tsx
+import { useState } from 'react';
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import * as S from './PopoverStory.style';
+
+function useAnimTrigger() {
+  const [counter, setCounter] = useState(0);
+
+  return [counter, () => setCounter((c) => c + 1)] as const;
+}
+
+function Render() {
+  const [state, turnOnIndicator] = useAnimTrigger();
+
+  return (
+    <>
+      <Popover
+        onClickOutside={turnOnIndicator}
+        content="Click outside of this popup. The green indicator should show that the event has fired."
+      >
+        <Button>Regular</Button>
+      </Popover>
+      <S.Indicator key={state} $state={state} />
+      <Popover
+        persistent
+        onClickOutside={turnOnIndicator}
+        content={
+          <>
+            <Popover.Content.Close />
+            Click outside of this popup. The green indicator should show that the event has fired.
+          </>
+        }
+      >
+        <Button>Persistent</Button>
+      </Popover>
+    </>
+  );
+}
+```
+
+### DisabledAndEmptyPopover
+
+> An empty `content` value or the `disabled` flag prevents the popover from opening.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Popover
+    content={
+      <>
+        Popover with empty (falsy) content or Popover with <strong>disabled</strong> flag will
+        not be visible
+      </>
+    }
+  >
+    <Button>Click me</Button>
+  </Popover>
+  <Popover content="Disabled" disabled open>
+    <Button>Disabled</Button>
+  </Popover>
+  <Popover content="" open>
+    <Button>Empty content</Button>
+  </Popover>
+</>
+```
+
+### Portal
+
+> `Popover` can render without a portal or inside a custom portal container.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      <Popover
+        open={inStory}
+        maxWidth="20vw"
+        content="This Popover is rendered with default portal (document.body)"
+      >
+        <Button>With portal</Button>
+      </Popover>
+      <Popover open={inStory} portal={null} content="This Popover is rendered without portal">
+        <Button>No portal</Button>
+      </Popover>
+    </>
+  );
+}
+```
+
+### InModal
+
+> `Popover` opened from `Modal` should appear over the modal.
+
+```tsx
+import { Button, Modal, Popover } from '@redislabsdev/redis-ui-components';
+
+<Modal.Compose>
+  <Modal.Trigger>
+    <Button variant="primary">Open Modal</Button>
+  </Modal.Trigger>
+  <Modal.Content.Compose style={{ width: '400px', height: '200px' }}>
+    <Modal.Content.Header title="Modal Title" />
+    <Modal.Content.Body.Compose>
+      <Popover content="This Popover is opened from Modal">
+        <Button>Open popover</Button>
+      </Popover>
+    </Modal.Content.Body.Compose>
+  </Modal.Content.Compose>
+</Modal.Compose>
+```
+
+### ComposePopover
+
+> `Popover` can be composed with `Popover.Trigger`, `Popover.Content`, and `Popover.Content.Text`.
+>
+> `Popover.Card` is available for richer content.
+>
+> With composition, `backgroundColor` also applies to the popup arrow.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { InfoIcon } from '@redislabsdev/redis-ui-icons';
+import * as S from './PopoverStory.style';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Popover.Compose defaultOpen={inStory}>
+      <Popover.Trigger withButton>
+        <InfoIcon />
+        Click me
+      </Popover.Trigger>
+      <Popover.Content.Compose backgroundColor="#eff9f5">
+        <S.PopoverContentText>This Popover is composed</S.PopoverContentText>
+      </Popover.Content.Compose>
+    </Popover.Compose>
+  );
+}
+```
+
+### AsyncContent
+
+> Popover with async content.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, Loader, Popover } 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 (
+    <Popover content={<AsyncContentComponent />}>
+      <Button>Get async content</Button>
+    </Popover>
+  );
+}
+```
+
+## Popover API
+
+### `Popover.Compose` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Popover composition tree |
+| defaultOpen | `boolean` | - | Uncontrolled initial open state |
+| open | `boolean` | `visible` | Controlled open state |
+| onOpenChange | `(open: boolean) => void` | `onVisibilityChange` | Controlled open-state callback |
+| disabled | `boolean` | - | Disables the popover root |
+| visible | `boolean` | - | Deprecated alias for `open` |
+| onVisibilityChange | `(open: boolean) => void` | - | Deprecated alias for `onOpenChange` |
+
+### `Popover.Trigger` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Trigger content |
+| withButton | `boolean` | - | Wraps the trigger in an invisible button |
+
+### `Popover.Content` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| content | `React.ReactNode` | - | Popup content |
+| backgroundColor | `string` | - | Popup background color override |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | `bottom` | Preferred popup side |
+| sideOffset | `number` | `5` | Offset between trigger and popup |
+| persistent | `boolean` | `false` | Prevents closing on outside click |
+| onClickOutside | `(event) => void` | - | Outside click handler |
+| alignOffset | `number` | - | Additional alignment offset |
+| align | `'start' \| 'center' \| 'end'` | `center` | Alignment against the trigger |
+| maxWidth | `string` | - | Max popup width override |
+| portal | `HTMLElement \| null` | `document.body` | Portal container or `null` to render inline |
+| collisionBoundary | `RadixPopover.PopoverContentProps['collisionBoundary']` | - | Radix collision boundary override |
+| windowBar | `WindowBarProps` | - | Deprecated alias for `Popover.Card.WindowBar` content |
+| title | `string` | - | Deprecated alias for `Popover.Card.Header` title |
+| text | `ContentBodyProps['text']` | - | Deprecated alias for `Popover.Card.Body` text |
+| actionButtonText | `string` | - | Deprecated alias for `Popover.Card.Footer` action label |
+| actionButtonHandler | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Deprecated alias for `Popover.Card.Footer` action callback |
+| link | `string` | - | Deprecated alias for `Popover.Card.Footer` link |
+| linkText | `string` | - | Deprecated alias for `Popover.Card.Footer` link text |
+| other div props | `Omit<PopoverContentComposeProps, 'children'>` | - | Standard popup container props forwarded to the composed content |
+
+### `Popover.Content.Compose` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Popup content |
+| backgroundColor | `string` | - | Popup background color override |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | `bottom` | Preferred popup side |
+| sideOffset | `number` | `5` | Offset between trigger and popup |
+| persistent | `boolean` | `false` | Prevents closing on outside click |
+| onClickOutside | `(event) => void` | - | Outside click handler |
+| alignOffset | `number` | - | Additional alignment offset |
+| align | `'start' \| 'center' \| 'end'` | `center` | Alignment against the trigger |
+| maxWidth | `string` | - | Max popup width override |
+| portal | `HTMLElement \| null` | `document.body` | Portal container or `null` to render inline |
+| collisionBoundary | `RadixPopover.PopoverContentProps['collisionBoundary']` | - | Radix collision boundary override |
+| other div props | `PopoverContentComposeProps` | - | Standard popup container props |
+
+### `Popover.Content.Close` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `IconType` | `CancelIcon` | Override icon used by the close button |
+| other button props | `PopoverCloseProps` | - | Standard button props forwarded to the close button |
+
+### `Popover.Content.Text`
+
+Inherits `TypographyBodyProps`. This is the styled text wrapper used when `Popover.content` is a string.
+
+### `Popover.Content.Header` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | `string` | - | Header title text |
+| hideCloseButton | `boolean` | `false` | Hides the close button |
+| other div props | `ContentHeaderComposeProps` | - | Standard header container props |
+
+### `Popover.Content.Header.Compose` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| other div props | `ContentHeaderComposeProps` | - | Standard header container props |
+
+### `Popover.Content.Header.Title`
+
+Inherits `TypographyHeadingProps`. The wrapper renders the title with `size="S"` by default.
+
+### `Popover.Content.Body` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| text | `string` | - | Body text |
+| other div props | `ContentBodyComposeProps` | - | Standard body container props |
+
+### `Popover.Content.Body.Compose` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| other div props | `ContentBodyComposeProps` | - | Standard body container props |
+
+### `Popover.Content.Body.Text`
+
+Inherits `TypographyBodyProps`.
+
+### `Popover.Content.Footer` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| actionButtonText | `string` | - | Action button label |
+| actionButtonHandler | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Action button click handler |
+| link | `string` | - | Footer link URL |
+| linkText | `string` | - | Footer link label |
+| other div props | `ContentFooterComposeProps` | - | Standard footer container props |
+
+### `Popover.Content.Footer.Compose` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| other div props | `ContentFooterComposeProps` | - | Standard footer container props |
+
+### `Popover.Content.WindowBar` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | `string` | `''` | Window bar title text |
+| variant | `BadgeVariants` | `default` | Semantic window bar variant |
+| hideCloseButton | `boolean` | `false` | Hides the close button |
+| withIcon | `boolean` | `true` | Shows the icon slot when a variant icon is available |
+| icon | `IconType` | - | Custom icon override |
+| other div props | `WindowBarComposeProps` | - | Standard window bar container props |
+
+### `Popover.Content.WindowBar.Compose` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `BadgeVariants` | - | Semantic window bar variant |
+| other div props | `WindowBarComposeProps` | - | Standard window bar container props |
+
+### `Popover.Content.WindowBar.Header` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Header content |
+
+### `Popover.Content.WindowBar.Heading`
+
+Inherits `TypographyHeadingProps`. The styled wrapper keeps the heading line-height tight.
+
+### `Popover.Content.WindowBar.Icon`
+
+Uses `BadgeIconProps`. Story usage passes `variant`, `icon`, `size`, and `customColor`.
+
+### `Popover.Content.WindowBar.Close` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `IconType` | `CancelIcon` | Override icon used by the close button |
+| other button props | `React.HTMLAttributes<HTMLButtonElement>` | - | Standard button props forwarded to the close button |
+
+## Popover.Card
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | `string` | - | Card header title |
+| text | `ContentBodyProps['text']` | - | Card body text |
+| actionButtonText | `string` | - | Footer action button label |
+| actionButtonHandler | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Footer action button callback |
+| link | `string` | - | Footer link URL |
+| linkText | `string` | - | Footer link label |
+| windowBar | `WindowBarProps` | - | Optional semantic window bar content |
+| persistent | `boolean` | - | Keeps the content open on outside click |
+| other div props | `Omit<ComposeProps, 'children' | 'title'>` | - | Standard card container props |
+
+### Sub-components
+
+- `Popover.Card.Compose` - Card container surface.
+- `Popover.Card.Header` - Alias of `Popover.Content.Header`.
+- `Popover.Card.Body` - Alias of `Popover.Content.Body`.
+- `Popover.Card.Footer` - Alias of `Popover.Content.Footer`.
+- `Popover.Card.WindowBar` - Alias of `Popover.Content.WindowBar`.
+- `Popover.Card.WindowBar.Header` - Alias of `Popover.Content.WindowBar.Header`.
+- `Popover.Card.WindowBar.Icon` - Alias of `Popover.Content.WindowBar.Icon`.
+- `Popover.Card.WindowBar.Close` - Alias of `Popover.Content.WindowBar.Close`.
+
+### `Popover.Card.Compose` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Card content |
+| other div props | `ComposeProps` | - | Standard card container props |
+
+### `Popover.Card.Close`
+
+Uses the same props as `Popover.Content.Close`.
+
+### `Popover.Card Header / Body / Footer / WindowBar`
+
+These aliases reuse the same prop surfaces as the corresponding `Popover.Content.*` subcomponents. The card stories exercise them through the composed card example.
+
+### `Popover.Card` Notes
+
+- `Popover.Card.WindowBar` supports semantic variants. When you compose the bar manually, apply the variant to the icon as well.
+- `Popover.Card` is the preferred replacement for the deprecated `Popover.Content` card-style props.
+
+## Popover.Card Examples
+
+### Playground
+
+```tsx
+import { Popover } from '@redislabsdev/redis-ui-components';
+import { PhoneIcon } from '@redislabsdev/redis-ui-icons';
+
+<Popover
+  open
+  content={
+    <Popover.Card
+      windowBar={{
+        title: 'WindowBar Title',
+        withIcon: true,
+        variant: 'default',
+        icon: PhoneIcon
+      }}
+      title="Popover Card title"
+      text="Popover Card displays formatted content"
+      link="#"
+      actionButtonHandler={() => {}}
+      actionButtonText="Action"
+    />
+  }
+>
+  <span />
+</Popover>
+```
+
+### CardVariants
+
+> `Popover.Card.WindowBar` supports semantic variants. To set the variant, use the `variant` prop on `WindowBar` or on the `windowBar` prop.
+>
+> In composition, apply the same variant to the icon as well.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { useViewMode } from '../../helpers/useViewMode';
+
+const variants = ['default', 'informative', 'notice', 'danger', 'attention', 'success'] as const;
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <>
+      {variants.map((variant) => (
+        <Popover
+          key={variant}
+          open={inStory}
+          content={
+            <Popover.Card
+              windowBar={{ variant, title: 'WindowBar title' }}
+              title="Header title"
+              text="Body text"
+              actionButtonText="Action"
+              actionButtonHandler={() => {}}
+              link="#"
+            />
+          }
+        >
+          <Button>{variant}</Button>
+        </Popover>
+      ))}
+    </>
+  );
+}
+```
+
+### ComposeCard
+
+> `Popover.Card` can be composed from `WindowBar`, `Header`, `Body`, and `Footer` pieces.
+
+```tsx
+import { Button, Popover } from '@redislabsdev/redis-ui-components';
+import { PhoneIcon } from '@redislabsdev/redis-ui-icons';
+import { useViewMode } from '../../helpers/useViewMode';
+
+function Render() {
+  const { inStory } = useViewMode();
+
+  return (
+    <Popover
+      defaultOpen={inStory}
+      content={
+        <Popover.Card.Compose>
+          <Popover.Card.WindowBar.Compose>
+            <Popover.Card.WindowBar.Header>
+              <Popover.Card.WindowBar.Icon
+                icon={PhoneIcon}
+                variant="default"
+                size="L"
+                customColor="currentColor"
+              />
+              <Popover.Card.WindowBar.Heading size="S">
+                Custom WindowBar.Header
+              </Popover.Card.WindowBar.Heading>
+            </Popover.Card.WindowBar.Header>
+            <Popover.Card.WindowBar.Close />
+          </Popover.Card.WindowBar.Compose>
+          <Popover.Card.Header.Compose>
+            <Popover.Card.Header.Title>Custom Header title</Popover.Card.Header.Title>
+          </Popover.Card.Header.Compose>
+          <Popover.Card.Body.Compose>
+            <Popover.Card.Body.Text>Custom Body text</Popover.Card.Body.Text>
+          </Popover.Card.Body.Compose>
+          <Popover.Card.Footer.Compose>
+            <Button>Custom Footer button</Button>
+          </Popover.Card.Footer.Compose>
+        </Popover.Card.Compose>
+      }
+    >
+      <Button>Click me</Button>
+    </Popover>
+  );
+}
+```
+
+## Notes
+
+- `visible` and `onVisibilityChange` are deprecated aliases for `open` and `onOpenChange`.
+- `Popover.Content` still accepts deprecated card-style props (`windowBar`, `title`, `text`, `actionButtonText`, `actionButtonHandler`, `link`, `linkText`), but `Popover.Card` is the preferred API.
+- `Popover.Trigger` with `withButton` is useful when the trigger content is plain text, SVG, or multiple elements.
+- `Popover.Content.Text` is the string-content wrapper used by the default `Popover` render path.
+- `Popover.Card.Close` mirrors `Popover.Content.Close`.
+- Use `placement`, `align`, and `alignOffset` together for positioning control; collisions can still flip the popup.
+- `persistent` prevents outside clicks from closing the popup, so pair it with an explicit close control.
+- `onClickOutside` fires when the user clicks outside the popover.
+- Empty or falsy `content` and `disabled` popovers will not open.
+- `portal={null}` renders the popover inline instead of through a portal.
+- `Popover.Content.WindowBar` returns `null` when it has no title.