@redis-ui/components 43.0.2 → 43.2.1

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.