@redis-ui/components 42.8.0 → 43.2.1

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

@@ -0,0 +1,214 @@
+# Breadcrumbs
+
+A breadcrumb navigation component that renders a trail of items with a default separator, controlled navigation callbacks, and a compound composition API for custom layouts.
+
+## Import
+
+```tsx
+import { Breadcrumbs } from '@redislabsdev/redis-ui-components';
+```
+
+> The composition example also uses icons from `@redislabsdev/redis-ui-icons`:
+> ```tsx
+> import { ChevronRightIcon } from '@redislabsdev/redis-ui-icons';
+> ```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| items | `BreadcrumbItem[]` | - | Breadcrumb entries rendered from left to right. Each item can provide `label`, optional `href`, and optional `onClick`; the last item is rendered as the current page. |
+| separator | `ReactNode` | `'/'` | Separator rendered between breadcrumb items. |
+| aria-label | `string` | `'Breadcrumb'` | Accessible label for the breadcrumb navigation landmark. |
+| compose wrapper props | `ComposeElementProps<HTMLElement>` | - | Additional props passed to the underlying `<nav>` element, excluding `children`. |
+
+## Sub-components
+
+- `Breadcrumbs.Compose` - Navigation wrapper that renders the semantic breadcrumb `<nav>`.
+- `Breadcrumbs.List` - Ordered list container for breadcrumb items.
+- `Breadcrumbs.Item` - List item wrapper used to structure breadcrumb entries and separators.
+- `Breadcrumbs.Link` - Interactive breadcrumb link that supports `href`, `onClick`, and `disabled`.
+- `Breadcrumbs.Separator` - Separator element rendered between items, hidden from screen readers by default.
+- `Breadcrumbs.Current` - Current page marker rendered with `aria-current="page"`.
+
+### Breadcrumbs.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| aria-label | `string` | `'Breadcrumb'` | Accessible label for the breadcrumb navigation landmark. |
+| compose wrapper props | `ComposeElementProps<HTMLElement>` | - | Additional props passed to the underlying `<nav>` element. |
+
+### Breadcrumbs.List Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| list props | `ComposeElementProps<HTMLOListElement>` | - | Additional props passed to the underlying ordered list. |
+
+### Breadcrumbs.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| item props | `ComposeElementProps<HTMLLIElement>` | - | Additional props passed to the underlying list item. |
+
+### Breadcrumbs.Link Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Link label or custom content. |
+| disabled | `boolean` | `false` | Disables the link and removes it from the tab order. |
+| link props | `Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'onKeyDown'>` | - | Additional anchor props passed to the breadcrumb link. |
+
+### Breadcrumbs.Separator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `'/'` | Custom separator content. |
+| separator props | `HTMLAttributes<HTMLSpanElement>` | - | Additional props passed to the separator span. |
+
+### Breadcrumbs.Current Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Label or content for the current page. |
+| current props | `HTMLAttributes<HTMLSpanElement>` | - | Additional props passed to the current page span. |
+
+## Examples
+
+### Playground
+
+```tsx
+import { Breadcrumbs } from '@redislabsdev/redis-ui-components';
+
+<Breadcrumbs
+  items={[
+    { label: 'Home', onClick: () => {} },
+    { label: 'Products', onClick: () => {} },
+    { label: 'Category', onClick: () => {} },
+    { label: 'Current Page' }
+  ]}
+  separator="/"
+/>
+```
+
+### Basic
+
+> Basic breadcrumbs with default separator. Click on breadcrumb items to navigate.
+
+```tsx
+import { useState } from 'react';
+import { Breadcrumbs } from '@redislabsdev/redis-ui-components';
+
+function ControlledBreadcrumbExample() {
+  const [currentPath, setCurrentPath] = useState<string[]>(['Home', 'Products', 'Current Page']);
+
+  const handleClick = (index: number) => {
+    setCurrentPath(currentPath.slice(0, index + 1));
+  };
+
+  return (
+    <Breadcrumbs
+      items={currentPath.map((label, index) => ({
+        label,
+        onClick: index < currentPath.length - 1 ? () => handleClick(index) : undefined
+      }))}
+    />
+  );
+}
+```
+
+### Composition
+
+> Use composition pattern for full control over rendering, including Select components.
+
+```tsx
+import { useState } from 'react';
+import { Breadcrumbs, Select, SelectOption, TextButton } from '@redislabsdev/redis-ui-components';
+import { ChevronRightIcon } from '@redislabsdev/redis-ui-icons';
+import styled from 'styled-components';
+import { useTheme } from '@redislabsdev/redis-ui-styles';
+
+const categoryOptions: SelectOption[] = [
+  { value: 'electronics', label: 'Electronics' },
+  { value: 'clothing', label: 'Clothing' },
+  { value: 'books', label: 'Books' },
+  { value: 'home', label: 'Home & Garden' }
+];
+
+const BreadcrumbTextButton = styled(TextButton)`
+  color: ${() => useTheme().components.breadcrumbs.current.textColor};
+  font-weight: ${() => useTheme().components.breadcrumbs.current.fontWeight};
+
+  &:hover {
+    color: ${() => useTheme().components.breadcrumbs.link.states.hover?.textColor};
+  }
+
+  &:active {
+    color: ${() => useTheme().components.breadcrumbs.link.states.active?.textColor};
+  }
+`;
+
+function CompositionWithSelectExample() {
+  const [selectedCategory, setSelectedCategory] = useState('electronics');
+
+  return (
+    <Breadcrumbs.Compose aria-label="Breadcrumb">
+      <Breadcrumbs.List>
+        <Breadcrumbs.Item>
+          <Breadcrumbs.Link
+            onClick={() => {
+              // eslint-disable-next-line no-alert
+              alert('Navigate to Home');
+            }}
+          >
+            Home
+          </Breadcrumbs.Link>
+        </Breadcrumbs.Item>
+        <Breadcrumbs.Item>
+          <Breadcrumbs.Separator>
+            <ChevronRightIcon size="S" />
+          </Breadcrumbs.Separator>
+        </Breadcrumbs.Item>
+        <Breadcrumbs.Item>
+          <Breadcrumbs.Link
+            onClick={() => {
+              // eslint-disable-next-line no-alert
+              alert('Navigate to Products');
+            }}
+          >
+            Products
+          </Breadcrumbs.Link>
+        </Breadcrumbs.Item>
+        <Breadcrumbs.Item>
+          <Breadcrumbs.Separator>
+            <ChevronRightIcon size="S" />
+          </Breadcrumbs.Separator>
+        </Breadcrumbs.Item>
+        <Breadcrumbs.Item>
+          <Select.Compose
+            options={categoryOptions}
+            value={selectedCategory}
+            onChange={(value) => setSelectedCategory(value as string)}
+          >
+            <Select.Trigger.Compose customContainer>
+              <span>
+                <BreadcrumbTextButton variant="primary-inline">
+                  <Select.Trigger.Value />
+                  <Select.Trigger.Arrow />
+                </BreadcrumbTextButton>
+              </span>
+            </Select.Trigger.Compose>
+            <Select.Content searchable />
+          </Select.Compose>
+        </Breadcrumbs.Item>
+      </Breadcrumbs.List>
+    </Breadcrumbs.Compose>
+  );
+}
+```
+
+## Notes
+
+- Breadcrumbs render a semantic navigation trail and the last item is treated as the current page.
+- Basic breadcrumbs use a default `/` separator, but the separator can be customized with any React node.
+- The composition pattern is the right choice when you need full control over rendering, including nested components such as `Select`.
+- `BreadcrumbItem` entries are `{ label, href?, onClick? }` objects; the root component renders the last entry as `Breadcrumbs.Current`.

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

@@ -0,0 +1,169 @@
+# Button
+
+A standard button component supporting multiple variants, sizes, and optional icons. It forwards refs and provides a `Button.Icon` sub-component for embedding icons that automatically match the button's size and color.
+
+## Import
+```tsx
+import { Button } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | `'large' \| 'medium' \| 'small'` | `'medium'` | The size of the button |
+| variant | `'primary' \| 'destructive' \| 'secondary-fill' \| 'secondary-invert' \| 'secondary-ghost' \| 'upsell' \| 'upsell-invert' \| 'upsell-ghost'` | `'primary'` | The visual style variant of the button |
+| disabled | `boolean` | `false` | Whether the button is disabled |
+| onClick | `(e: React.MouseEvent<HTMLButtonElement>) => void` | - | Click event handler |
+| theme | `Theme` | - | Theme override from `@redislabsdev/redis-ui-styles` |
+| children | `React.ReactNode` | - | Button content (inherited from `ButtonHTMLAttributes`) |
+
+The component also extends all native `ButtonHTMLAttributes<HTMLButtonElement>` props.
+
+## Sub-components
+
+- **`Button.Icon`** - Renders an icon inside the button, automatically sized and colored to match the parent button.
+
+### Button.Icon Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `IconType` | *required* | The icon component from `@redislabsdev/redis-ui-icons` |
+| customSize | `string` | - | Override the automatic icon size (e.g. `'2.8rem'`) |
+| title | `string` | - | Title attribute for the icon container |
+
+## Examples
+
+### Playground
+```tsx
+import { Button } from '@redislabsdev/redis-ui-components';
+
+<Button variant="primary" size="medium" disabled={false}>
+  Button
+</Button>
+```
+
+### Sizes
+> 3 sizes are supported with `medium` being the default.
+```tsx
+import { Button } from '@redislabsdev/redis-ui-components';
+import { EditIcon } from '@redislabsdev/redis-ui-icons';
+
+<>
+  <Button size="small">
+    <Button.Icon icon={EditIcon} />
+    Small
+  </Button>
+  <Button size="medium">
+    <Button.Icon icon={EditIcon} />
+    Medium
+  </Button>
+  <Button size="large">
+    <Button.Icon icon={EditIcon} />
+    Large
+  </Button>
+</>
+```
+
+### Variants
+> 8 total variants are supported, 1 primary, 3 secondary, a destructive variant, and 3 upsell variants. The default is `primary`.
+```tsx
+import { Button } from '@redislabsdev/redis-ui-components';
+import { CancelIcon } from '@redislabsdev/redis-ui-icons';
+
+<>
+  <Button variant="primary">
+    Primary
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button variant="secondary-fill">
+    Secondary Fill
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button variant="secondary-invert">
+    Secondary Invert
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button variant="secondary-ghost">
+    Secondary Ghost
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button variant="destructive">
+    Destructive
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button variant="upsell">
+    Upsell
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button variant="upsell-invert">
+    Upsell Invert
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button variant="upsell-ghost">
+    Upsell Ghost
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+</>
+```
+
+### Disabled
+> Buttons can be disabled by setting the `disabled` prop to `true`. This will disable any hover styles and prevent click events from firing.
+```tsx
+import { Button } from '@redislabsdev/redis-ui-components';
+import { CancelIcon } from '@redislabsdev/redis-ui-icons';
+
+<>
+  <Button disabled>
+    Primary
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button disabled variant="secondary-fill">
+    Secondary Fill
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button disabled variant="secondary-invert">
+    Secondary Invert
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+  <Button disabled variant="secondary-ghost">
+    Secondary Ghost
+  </Button>
+  <Button disabled variant="destructive">
+    Destructive
+    <Button.Icon icon={CancelIcon} />
+  </Button>
+</>
+```
+
+### WithIcon
+> To add an icon to a button, use the `Button.Icon` component. This component can be placed anywhere inside the `Button` component. It will automatically be sized and colored to match its parent button.
+>
+> Do not use this component if you need a round icon-only button. Instead, use the IconButton or ActionIconButton components.
+```tsx
+import { Button } from '@redislabsdev/redis-ui-components';
+import { ContractIcon, MarketplaceIcon, ShardIcon } from '@redislabsdev/redis-ui-icons';
+
+<>
+  <Button>
+    <Button.Icon icon={ContractIcon} />
+    Left Icon
+  </Button>
+  <Button>
+    Right Icon
+    <Button.Icon icon={MarketplaceIcon} />
+  </Button>
+  <Button>
+    <Button.Icon icon={ShardIcon} />
+  </Button>
+  <Button>
+    <Button.Icon icon={ShardIcon} customSize="2.8rem" />
+    Custom icon size
+  </Button>
+</>
+```
+
+## Notes
+- The button renders with `type="button"` by default.
+- `Button.Icon` automatically sizes the icon based on the parent button's size (`S` for small, `M` for medium, `L` for large).
+- If you need to pass props to the icon element, declare it as a separate component outside the parent or wrap it in `useMemo`. Do not pass it as an inline arrow function, as it will cause re-renders on every render of the parent component.
+- For icon-only round buttons, use the `IconButton` or `ActionIconButton` components instead.
+- The component forwards refs to the underlying `<button>` element.

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

@@ -0,0 +1,126 @@
+# ButtonGroup
+
+A grouped button container for building segmented button sets with optional icons and explicit selected states. `ButtonGroup` does not manage selection on its own, so single- and multi-select behavior is handled by the consumer.
+
+## Import
+
+```tsx
+import { ButtonGroup } from '@redislabsdev/redis-ui-components';
+```
+
+> If the examples use icons, import them from `@redislabsdev/redis-ui-icons`:
+>
+> ```tsx
+> import { InfoIcon, ShardIcon, StarsIcon } from '@redislabsdev/redis-ui-icons';
+> ```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `...div props` | `React.HTMLAttributes<HTMLDivElement>` | - | Standard `div` attributes forwarded to the wrapper. |
+
+## Sub-components
+
+- `ButtonGroup.Button` - Individual button inside the group. Supports selected and disabled states.
+- `ButtonGroup.Icon` - Icon wrapper that renders a medium-sized icon in the group color.
+
+### `ButtonGroup.Button` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isSelected` | `boolean` | - | Marks the button as selected for styling purposes. |
+| `onClick` | `(e: React.MouseEvent<HTMLButtonElement>) => void` | - | Click handler used to toggle selection. |
+| `children` | `React.ReactNode` | - | Button content. |
+
+`ButtonGroup.Button` also accepts all native `button` attributes.
+
+### `ButtonGroup.Icon` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconType` | required | Icon component rendered inside the button group item. |
+
+## Examples
+
+### SingleSelectionSimulation
+
+```tsx
+import { useState } from 'react';
+import { ButtonGroup } from '@redislabsdev/redis-ui-components';
+import { InfoIcon, ShardIcon, StarsIcon } from '@redislabsdev/redis-ui-icons';
+
+const items = [
+  { value: 'item1', label: 'Button 1', icon: ShardIcon, disabled: true },
+  { value: 'item2', label: 'Button 2', icon: StarsIcon },
+  { value: 'item3', label: 'Button 3' }
+];
+
+const [selected, setSelected] = useState<string>(items[0].value);
+
+const selectSingle = (value: string) => {
+  if (selected !== value) {
+    setSelected(value);
+  }
+};
+
+const isSelected = (value: string) => selected === value;
+
+<ButtonGroup>
+  {items.map((item) => (
+    <ButtonGroup.Button
+      key={item.value}
+      disabled={item.disabled}
+      isSelected={isSelected(item.value)}
+      onClick={() => selectSingle(item.value)}
+    >
+      {item.icon && <ButtonGroup.Icon icon={item.icon} />}
+      {item.label || item.value}
+      <ButtonGroup.Icon icon={InfoIcon} />
+    </ButtonGroup.Button>
+  ))}
+</ButtonGroup>;
+```
+
+### MultiSelectionSimulation
+
+```tsx
+import { useState } from 'react';
+import { ButtonGroup } from '@redislabsdev/redis-ui-components';
+import { InfoIcon, ShardIcon, StarsIcon } from '@redislabsdev/redis-ui-icons';
+
+const items = [
+  { value: 'item1', label: 'Initially selected', icon: ShardIcon },
+  { value: 'item2', label: 'Selected-Disabled', icon: StarsIcon, disabled: true },
+  { value: 'item3', label: 'Initially unselected' },
+  { value: 'item4', label: 'Disabled', disabled: true }
+];
+
+const [selected, setSelected] = useState<string[]>([items[0].value, items[1].value]);
+
+const toggleMultiSelection = (value: string) =>
+  selected.includes(value) ? selected.filter((sel) => sel !== value) : [...selected, value];
+const isSelected = (value: string) => selected.includes(value);
+
+<ButtonGroup>
+  {items.map((item) => (
+    <ButtonGroup.Button
+      key={item.value}
+      disabled={item.disabled}
+      isSelected={isSelected(item.value)}
+      onClick={() => setSelected(toggleMultiSelection(item.value))}
+    >
+      {item.icon && <ButtonGroup.Icon icon={item.icon} />}
+      {item.label || item.value}
+      <ButtonGroup.Icon icon={InfoIcon} />
+    </ButtonGroup.Button>
+  ))}
+</ButtonGroup>;
+```
+
+## Notes
+
+- `ButtonGroup` has no internal selection logic; manage selected state in the parent component.
+- `ButtonGroup.Button` is styled as a native `button` and can be disabled through the standard `disabled` attribute.
+- `ButtonGroup.Icon` always renders the icon at `size="M"` with `customColor="currentColor"`.
+- If you need to pass props to an icon component, declare it outside the render path or wrap it in `useMemo`; avoid inline arrow functions because they re-create the icon on every parent render.

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

@@ -0,0 +1,56 @@
+# Card
+
+A simple container card with configurable width and height. It renders as a flex column and uses the theme card surface styling.
+
+## Import
+
+```tsx
+import { Card } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| width | `number \| string` | `100%` | Overrides the card width |
+| height | `number \| string` | `fit-content` | Overrides the card height |
+
+The component also extends all native `React.HTMLAttributes<HTMLDivElement>` props.
+
+## Examples
+
+### Playground
+
+```tsx
+import { Card } from '@redislabsdev/redis-ui-components';
+
+<Card>Content</Card>
+```
+
+### Sizing
+
+> If `width` is not defined, `Card` takes 100%. If `height` is not defined, `Card` fits content
+
+```tsx
+import { Card } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Card>
+    <span>No width and height defined</span>
+  </Card>
+  <Card width={150} height={100}>
+    <span>width=150px;</span>
+    <span>height=100px;</span>
+  </Card>
+  <Card width="fit-content" height="fit-content">
+    <span>width=fit-content;</span>
+    <span>height=fit-content;</span>
+  </Card>
+</>
+```
+
+## Notes
+
+- If `width` is not provided, the card defaults to `100%`.
+- If `height` is not provided, the card defaults to `fit-content`.
+- The component forwards standard `div` attributes through `React.HTMLAttributes<HTMLDivElement>`.