@redis-ui/components 42.8.0 → 43.2.1

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

@@ -0,0 +1,57 @@
+# CountryFlag
+
+Country flag image component that loads flagcdn assets and falls back to an empty placeholder until the image is valid.
+
+## Import
+
+```tsx
+import { CountryFlag } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| countryCode | `string` | required | Country code used to resolve the flag image |
+| native img props | `React.HTMLAttributes<HTMLImageElement>` | - | Standard image attributes forwarded to the rendered flag image |
+
+The component also extends all native `React.HTMLAttributes<HTMLImageElement>` props.
+
+## Examples
+
+### Playground
+
+```tsx
+import { CountryFlag } from '@redislabsdev/redis-ui-components';
+
+<CountryFlag countryCode="us" />
+```
+
+### Empty
+
+> If the `countryCode` is wrong or empty, the component shows an empty flag.
+
+```tsx
+import { CountryFlag } from '@redislabsdev/redis-ui-components';
+
+<CountryFlag countryCode="" />
+```
+
+### Gallery
+
+```tsx
+import countries from './codes.json';
+import { CountryFlag } from '@redislabsdev/redis-ui-components';
+
+<>
+  {Object.entries(countries).map(([code, name]) => (
+    <CountryFlag key={code} countryCode={code} title={`${code}:${name}`} />
+  ))}
+</>
+```
+
+## Notes
+
+- Flags are loaded from `flagcdn.com`.
+- The component renders a placeholder image until the actual flag asset loads successfully.
+- `uk`, `tp`, and `fx` are normalized to `gb`, `tl`, and `fr` before the flag URL is resolved.

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

@@ -0,0 +1,298 @@
+# Drawer
+
+A sliding overlay panel for focused workflows, with collapsible or persistent behavior and composable header, description, body, and footer sections.
+
+## Import
+
+```tsx
+import { Drawer } from '@redislabsdev/redis-ui-components';
+```
+
+> Footer examples use icons from `@redislabsdev/redis-ui-icons`:
+> ```tsx
+> import { StarsIcon } from '@redislabsdev/redis-ui-icons';
+> ```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| persistent | `boolean` | `false` | Keeps the drawer from closing on outside click or `Esc`, and suppresses the default header close button. |
+| open | `boolean` | required | Controls whether the drawer is open. |
+| onOpenChange | `(open: boolean) => void` | - | Called when the open state changes. |
+| containerElement | `HTMLElement` | - | Portal container to render the drawer into instead of `body`. |
+| zIndex | `number` | `theme.core.zIndex.zIndex9998` | Z-index used for the drawer overlay and content. |
+| onDrawerWillOpen | `() => void` | - | Fires when the open animation starts. |
+| onDrawerDidOpen | `() => void` | - | Fires when the open animation ends. |
+| onDrawerWillClose | `() => void` | - | Fires when the close animation starts. |
+| onDrawerDidClose | `() => void` | - | Fires when the close animation ends. |
+
+The component also accepts the native `HTMLAttributes<HTMLDivElement>` props.
+
+## Sub-components
+
+- `Drawer.Header` - Default header wrapper that renders a title and, in non-persistent mode, a close button.
+- `Drawer.Description` - Accessible description wrapper for drawer content.
+- `Drawer.Body` - Main content area inside the drawer.
+- `Drawer.Footer` - Default footer wrapper for primary, secondary, and tertiary actions.
+- `Drawer.Header.Compose` - Custom header layout container.
+- `Drawer.Header.Title` - Drawer heading helper for custom header compositions.
+- `Drawer.Description.Text` - Typography helper for drawer description text.
+- `Drawer.Footer.Compose` - Custom footer layout container.
+- `Drawer.Footer.ActionButtonsContainer` - Container for footer action buttons.
+
+### `Drawer.Header`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | `string` | required | Header title text. |
+| titleHidden | `boolean` | `false` | Visually hides the title while keeping it accessible. |
+
+It also accepts the native `HTMLAttributes<HTMLDivElement>` props through the composed header container.
+
+### `Drawer.Header.Compose`
+
+Accepts the native `HTMLAttributes<HTMLDivElement>` props for the custom header container.
+
+### `Drawer.Header.Title`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| hidden | `boolean` | `false` | Visually hides the title while keeping it accessible. |
+
+It inherits the `Typography.Heading` props.
+
+### `Drawer.Description`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| hidden | `boolean` | `false` | Visually hides the description while keeping it accessible. |
+
+It also accepts the native `HTMLAttributes<HTMLDivElement>` props through the description container.
+
+### `Drawer.Description.Text`
+
+It inherits the `Typography.Heading` props.
+
+### `Drawer.Body`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| focusableForScroll | `boolean` | `true` | Adds focus and region semantics when the body content is scrollable. |
+
+It also accepts the native `HTMLAttributes<HTMLDivElement>` props.
+
+### `Drawer.Footer`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| primaryButtonText | `string` | - | Text for the primary action button. |
+| secondaryButtonText | `string` | - | Text for the secondary action button. |
+| tertiaryButtonText | `string` | - | Text for the tertiary text button. |
+| tertiaryButtonIcon | `IconType` | - | Optional icon rendered before the tertiary button text. |
+| primaryButtonDisabled | `boolean` | - | Disables the primary action button. |
+| secondaryButtonDisabled | `boolean` | - | Disables the secondary action button. |
+| tertiaryButtonDisabled | `boolean` | - | Disables the tertiary action button. |
+| onPrimaryButtonClick | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Primary button click handler. |
+| onSecondaryButtonClick | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Secondary button click handler. |
+| onTertiaryButtonClick | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Tertiary button click handler. |
+
+It also accepts the native `HTMLAttributes<HTMLDivElement>` props.
+
+### `Drawer.Footer.Compose`
+
+Accepts the native `HTMLAttributes<HTMLDivElement>` props for the custom footer container.
+
+### `Drawer.Footer.ActionButtonsContainer`
+
+Accepts the native `HTMLAttributes<HTMLDivElement>` props for the action button container.
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { Button, Drawer } from '@redislabsdev/redis-ui-components';
+import { StarsIcon } from '@redislabsdev/redis-ui-icons';
+import { useState } from 'react';
+
+function Render() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+
+      <Drawer open={open} onOpenChange={setOpen}>
+        <Drawer.Header title="Drawer.Header" titleHidden={false} />
+        <Drawer.Description hidden={false}>Drawer.Description</Drawer.Description>
+        <Drawer.Body>Drawer.Body</Drawer.Body>
+        <Drawer.Footer
+          primaryButtonText="Primary"
+          secondaryButtonText="Secondary"
+          tertiaryButtonText="Tertiary"
+          tertiaryButtonIcon={StarsIcon}
+          onPrimaryButtonClick={() => setOpen(false)}
+          onSecondaryButtonClick={() => setOpen(false)}
+        />
+      </Drawer>
+    </>
+  );
+}
+```
+
+### Collapsible
+
+> The auto collapsible mode is the default mode for the Drawer. It allows closing the drawer automatically when the user clicks outside or presses the `Esc` key. In this mode `Drawer.Header` will have the close button.
+
+```tsx
+import { Button, Drawer } from '@redislabsdev/redis-ui-components';
+import { useState } from 'react';
+
+import { StoryDrawerBodyContent } from './story.components';
+
+function Render() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+
+      <Drawer open={open} onOpenChange={setOpen}>
+        <Drawer.Header title="Collapsible drawer" />
+        <Drawer.Body>
+          <StoryDrawerBodyContent />
+        </Drawer.Body>
+        <Drawer.Footer secondaryButtonText="Close" onSecondaryButtonClick={() => setOpen(false)} />
+      </Drawer>
+    </>
+  );
+}
+```
+
+### Persistent
+
+> The persistent mode prevents the drawer from being accidentally closed, which could result in the loss of filled form data. Use `persistent` prop to enable this mode. You'll need to manage open state manually and close the drawer explicitly.
+
+```tsx
+import { Button, Drawer, Typography } from '@redislabsdev/redis-ui-components';
+import { useState } from 'react';
+
+function Render() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+
+      <Drawer persistent open={open} onOpenChange={setOpen}>
+        <Drawer.Header title="Persistent drawer" />
+        <Drawer.Body>
+          <Typography.Heading size="S">Persistent drawers usually contain forms</Typography.Heading>
+          <br />
+          <Typography.Body>
+            The persistent mode prevents the drawer from being accidentally closed, which could
+            result in the loss of filled form data.
+          </Typography.Body>
+        </Drawer.Body>
+        <Drawer.Footer
+          primaryButtonText="Submit"
+          secondaryButtonText="Cancel"
+          onSecondaryButtonClick={() => setOpen(false)}
+          onPrimaryButtonClick={() => setOpen(false)}
+        />
+      </Drawer>
+    </>
+  );
+}
+```
+
+### InContainer
+
+> Drawer can be opened under a specified container instead of `body`. Use `containerElement` prop to set the container element.
+
+```tsx
+import { Button, Drawer } from '@redislabsdev/redis-ui-components';
+import { useState } from 'react';
+
+import { StoryDrawerBodyContent } from './story.components';
+import * as S from './story.style';
+
+function Render() {
+  const [open, setOpen] = useState(false);
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+
+  return (
+    <S.StoryDrawerContainer ref={setContainer}>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+
+      <Drawer open={open} onOpenChange={setOpen} containerElement={container || undefined}>
+        <Drawer.Header title="Drawer in container" />
+        <Drawer.Body>
+          <StoryDrawerBodyContent />
+        </Drawer.Body>
+      </Drawer>
+    </S.StoryDrawerContainer>
+  );
+}
+```
+
+### Composition
+
+> Use `Drawer.Header.Compose` and `Drawer.Footer.Compose` to compose the header and footer. `Drawer.Body` can have any children.
+
+```tsx
+import { Button, Drawer, Typography } from '@redislabsdev/redis-ui-components';
+import { useState } from 'react';
+
+import { StoryDrawerBodyContent } from './story.components';
+import { StoryGroupTitle, StoryHList, StoryVList } from '../../helpers/Story.style';
+
+function Render() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+
+      <Drawer open={open} onOpenChange={setOpen}>
+        <Drawer.Header.Compose>
+          <StoryHList>
+            <Drawer.Header.Title>Drawer.Header.Title</Drawer.Header.Title>
+            <Button>Custom Header content</Button>
+          </StoryHList>
+        </Drawer.Header.Compose>
+        <Drawer.Description>
+          <StoryHList>
+            <Drawer.Description.Text>Drawer.Description.Text</Drawer.Description.Text>
+            <Button>Custom Description content</Button>
+          </StoryHList>
+        </Drawer.Description>
+        <Drawer.Body>
+          <StoryVList $align="stretch">
+            <StoryGroupTitle>Drawer.Body: any content</StoryGroupTitle>
+            <StoryDrawerBodyContent />
+          </StoryVList>
+        </Drawer.Body>
+        <Drawer.Footer.Compose>
+          <Typography.Body>Custom Footer content</Typography.Body>
+          <Drawer.Footer.ActionButtonsContainer>
+            <Button variant="secondary-invert" onClick={() => setOpen(false)}>
+              Custom Close
+            </Button>
+          </Drawer.Footer.ActionButtonsContainer>
+        </Drawer.Footer.Compose>
+      </Drawer>
+    </>
+  );
+}
+```
+
+## Notes
+
+- The default mode is collapsible: outside clicks and the `Esc` key close the drawer, and `Drawer.Header` shows a close button.
+- Use `persistent` when the drawer contains form state that should not be lost accidentally.
+- Use `containerElement` when the drawer should render into a specific container instead of `body`.
+- `Drawer.Header.Compose` and `Drawer.Footer.Compose` are the intended escape hatches for custom layouts.
+- `Drawer.Body` can contain any children, including other interactive components and scrollable content.
+- When composing the drawer, keep a proper title through `Drawer.Header.title` or `Drawer.Header.Title` so the dialog remains accessible.

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

@@ -0,0 +1,162 @@
+# Filters
+
+Controlled filter bar for combining menu-based filters, a clear action, and an active-chip summary. Use the composition API when you need to place the controls in a custom layout.
+
+## Import
+
+```tsx
+import { Filters } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| availableFilters | `FilterItemConfig[]` | required | Filter definitions to render. Each item provides a key, label, options, and optional filter type. |
+| activeFilters | `FilterActive[]` | required | Current active filter state. |
+| onChange | `(activeFilters: FilterActive[]) => void` | required | Called when the active filter selection changes. |
+| showSearchLimit | `number` | `7` | Minimum number of options before a filter shows a search input. |
+
+`Filters` extends `HTMLAttributes<HTMLDivElement>` except `onChange`, so you can pass standard div props to the root container.
+
+### Exported Types
+
+- `FilterType` - `'MultiSelect' | 'MultiTreeSelect'`
+- `FilterItemConfig` - filter definition with `key`, `label`, `options`, optional `type`, and optional `showSearch`
+- `FilterOption` - option definition with `label`, `value`, optional `id`, optional `chipLabel`, and optional nested `descendants`
+- `FilterActive` - active filter entry with `key`, `selectedOptions`, and optional `type`
+
+## Sub-components
+
+- `Filters.Compose` - Provides Filters context and debounced change handling for custom compositions.
+- `Filters.FiltersContainer` - Wrapper for the filter trigger row.
+- `Filters.MultiSelectFilter` - Checkbox-based menu for flat multi-select filters.
+- `Filters.MultiTreeSelectFilter` - Tree-based menu for hierarchical filters.
+- `Filters.Clear` - Clear-all action bound to the current filter state.
+- `Filters.Chips` - Renders chips for the active filters and handles removal.
+
+### Filters.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| availableFilters | `FilterItemConfig[]` | required | Filter definitions available to the composition. |
+| activeFilters | `FilterActive[]` | required | Current active filter state. |
+| onChange | `(activeFilters: FilterActive[]) => void` | required | Called when the active filter selection changes. |
+| showSearchLimit | `number` | `7` | Minimum number of options before a filter shows a search input. |
+| children | `React.ReactNode` | required | Custom composition content rendered inside the Filters context. |
+
+### Filters.FiltersContainer Props
+
+Inherits `HTMLAttributes<HTMLDivElement>`.
+
+### Filters.MultiSelectFilter Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| filter | `FilterItemConfig` | required | Filter configuration used to build the menu. |
+| showSearchLimit | `number` | required | Minimum option count before the search input renders. |
+
+`Filters.MultiSelectFilter` also accepts all `MenuProps` except `children`.
+
+### Filters.MultiTreeSelectFilter Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| filter | `FilterItemConfig` | required | Tree filter configuration used to build the menu. |
+| showSearchLimit | `number` | required | Minimum option count before the search input renders. |
+
+`Filters.MultiTreeSelectFilter` uses the same prop surface as `Filters.MultiSelectFilter` and also accepts all `MenuProps` except `children`.
+
+### Filters.Clear Props
+
+`Filters.Clear` inherits `TextButtonProps`.
+
+### Filters.Chips Props
+
+`Filters.Chips` inherits `Omit<ChipListProps, 'chips'>`.
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { Filters } from '@redislabsdev/redis-ui-components';
+import { useArgState } from '../../helpers/useArgState';
+
+function Render(args) {
+  const [activeFilters, setActiveFilters] = useArgState({
+    arg: args.activeFilters,
+    event: args.onChange,
+    getNewState: (_, [value]) => value
+  });
+
+  return <Filters {...args} activeFilters={activeFilters} onChange={setActiveFilters} />;
+}
+```
+
+### Controlled
+
+> Filters work in controlled mode only.<br/>
+> Component requires array of filters with type and options `availableFilters`,
+> selected filter values `activeFilters`,
+> and `onChange` handler to update selection
+
+```tsx
+import { useState } from 'react';
+import { Filters } from '@redislabsdev/redis-ui-components';
+import { availableFilters, defaultFilters } from './FiltersStory.data';
+
+function Render() {
+  const [activeFilters, setActiveFilters] = useState(defaultFilters);
+
+  return (
+    <Filters
+      availableFilters={availableFilters}
+      activeFilters={activeFilters}
+      onChange={setActiveFilters}
+    />
+  );
+}
+```
+
+### Composition
+
+```tsx
+import { useState } from 'react';
+import { Filters } from '@redislabsdev/redis-ui-components';
+import { availableFilters, defaultFilters } from './FiltersStory.data';
+
+function Render() {
+  const [activeFilters, setActiveFilters] = useState(defaultFilters);
+
+  return (
+    <Filters.Compose
+      availableFilters={availableFilters}
+      activeFilters={activeFilters}
+      onChange={setActiveFilters}
+    >
+      <div style={{ display: 'flex', gap: '15px', alignItems: 'center', padding: '5px 0' }}>
+        <Filters.FiltersContainer>
+          {availableFilters.map((filter) => {
+            const FilterComponent =
+              filter.type === 'MultiTreeSelect'
+                ? Filters.MultiTreeSelectFilter
+                : Filters.MultiSelectFilter;
+
+            return <FilterComponent key={filter.key} filter={filter} showSearchLimit={7} />;
+          })}
+        </Filters.FiltersContainer>
+        <Filters.Clear />
+      </div>
+      <Filters.Chips />
+    </Filters.Compose>
+  );
+}
+```
+
+## Notes
+
+- `Filters` works in controlled mode only.
+- `showSearchLimit` defaults to `7` and controls when a search input appears inside a filter menu.
+- `Filters.Clear` clears the current selection and is disabled when there are no active filters.
+- `Filters.Chips` derives chip labels from the active filters and caps the chip list at two rows.

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

@@ -0,0 +1,152 @@
+# FlexDivider
+
+A visual separator line used to divide content within flex layouts. Automatically adapts its orientation based on the parent `FlexGroup` direction, or can be explicitly set when used in custom containers. Supports configurable padding, spacing, and automatic hiding of redundant dividers.
+
+## Import
+
+```tsx
+import { FlexDivider } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `padding` | `'XXS' \| 'XS' \| 'S' \| 'M' \| 'L' \| 'XL' \| 'XXL' \| 'none' \| string` | `'none'` | Paddings from the edges of the container to the divider line. Accepts predefined sizes or custom CSS dimension values. |
+| `spacing` | `'XXS' \| 'XS' \| 'S' \| 'M' \| 'L' \| 'XL' \| 'XXL' \| 'none' \| string` | `'none'` | Additional margins between the divider line and adjacent elements. Gap of flex container is preferred. |
+| `orientation` | `'horizontal' \| 'vertical'` | — | The orientation of the divider line when used in a custom container. `FlexGroup` automatically defines its orientation, so this is only needed outside of `FlexGroup`. |
+| `autoHide` | `boolean` | `true` | Hide extra dividers if there are multiple ones next to each other or if one is displayed as the first/last element. |
+
+## Examples
+
+### Playground
+
+```tsx
+<FlexGroup direction="row" align="stretch">
+  <div>a</div>
+  <FlexDivider />
+  <div>b</div>
+  <div>c</div>
+</FlexGroup>
+```
+
+### AutoHiding
+
+> `FlexDivider` allows you to automatically hide unnecessary dividers. If a divider appears as the first/last element or is duplicated, it will be hidden. To prevent automatic hiding, set the `autoHide` property for that particular divider to `false`.
+
+```tsx
+import { FlexGroup, FlexDivider, Switch } from '@redislabsdev/redis-ui-components';
+import { useState } from 'react';
+
+const [autoHide, setAutoHide] = useState(true);
+
+<FlexGroup direction="row" align="stretch" justify="center">
+  <FlexDivider autoHide={autoHide} />
+  <div>a</div>
+  <FlexDivider autoHide={autoHide} />
+  <FlexDivider autoHide={autoHide} />
+  <div>b</div>
+  <FlexDivider autoHide={autoHide} />
+  <div>c</div>
+  <FlexDivider autoHide={autoHide} />
+</FlexGroup>
+```
+
+### Paddings
+
+> `FlexDivider` allows control `padding` from the edge of container to the line. Supports predefined sizes (XXS ... XXL, none) or custom values (in format of one/two CSS dimensions).
+
+```tsx
+<FlexGroup>
+  <div>S:</div>
+  <FlexDivider padding="S" />
+  <div>M:</div>
+  <FlexDivider padding="M" />
+  <div>L:</div>
+  <FlexDivider padding="L" />
+  <div>custom:</div>
+  <FlexDivider padding="5rem 2rem" />
+</FlexGroup>
+```
+
+### Spacing
+
+> `FlexDivider` allows control `spacing` between the divider and adjacent elements. Supports predefined sizes (XXS ... XXL, none) or custom values (in format of one/two CSS dimensions).
+
+```tsx
+<FlexGroup gap="0">
+  <div>S:</div>
+  <FlexDivider spacing="S" />
+  <div>M:</div>
+  <FlexDivider spacing="M" />
+  <div>L:</div>
+  <FlexDivider spacing="L" />
+  <div>custom:</div>
+  <FlexDivider spacing="3rem 1rem" />
+</FlexGroup>
+```
+
+### HorizontalContainer
+
+> Shows `FlexDivider` usage in horizontal (`row`) layouts. Demonstrates how dividers work in `FlexGroup` containers, custom flex containers, and the limitations with block-level containers.
+
+```tsx
+{/* Inside FlexGroup - orientation is automatic */}
+<FlexGroup justify="center" align="stretch">
+  <div>a</div>
+  <FlexDivider />
+  <div>b</div>
+  <FlexDivider />
+  <div>c</div>
+</FlexGroup>
+
+{/* Inside a custom flex container - orientation must be set explicitly */}
+<div style={{ display: 'flex', flexDirection: 'row', justifyContent: 'center', gap: 10 }}>
+  <div>a</div>
+  <FlexDivider orientation="vertical" />
+  <div>b</div>
+  <FlexDivider orientation="vertical" />
+  <div>c</div>
+</div>
+```
+
+### VerticalContainer
+
+> Shows `FlexDivider` usage in vertical (`column`) layouts. Compares behavior across `FlexGroup` containers, custom flex containers, and custom block containers.
+
+```tsx
+{/* FlexGroup column container */}
+<FlexGroup direction="column" align="stretch" gap="M">
+  <div>a</div>
+  <FlexDivider padding="S" />
+  <div>b</div>
+  <FlexDivider />
+  <div>c</div>
+</FlexGroup>
+
+{/* Custom flex column container */}
+<div style={{ display: 'flex', flexDirection: 'column', gap: '1.2rem' }}>
+  <div>a</div>
+  <FlexDivider orientation="horizontal" padding="S" />
+  <div>b</div>
+  <FlexDivider orientation="horizontal" />
+  <div>c</div>
+</div>
+
+{/* Custom block container */}
+<div>
+  <div>a</div>
+  <FlexDivider orientation="horizontal" spacing="M" padding="S" />
+  <div>b</div>
+  <FlexDivider orientation="horizontal" spacing="M" />
+  <div>c</div>
+</div>
+```
+
+## Notes
+
+- When used inside a `FlexGroup`, the divider automatically detects the container's direction and renders with the correct orientation. No need to set the `orientation` prop.
+- When used in a custom flex container (not `FlexGroup`), you must explicitly set `orientation` to `'vertical'` (for row layouts) or `'horizontal'` (for column layouts).
+- `FlexDivider` does not work with horizontal block containers out of the box; additional styling is required.
+- The `autoHide` feature (enabled by default) uses CSS adjacency selectors to hide dividers that are first, last, or consecutive, keeping the layout clean even when items are conditionally rendered.
+- Both `padding` and `spacing` accept predefined size tokens (`XXS` through `XXL`, `none`) or arbitrary CSS dimension strings (e.g., `"5rem 2rem"`).