@redis-ui/components 43.0.2 → 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/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>`.

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

@@ -0,0 +1,171 @@
+# Checkbox
+
+A compound checkbox component with primary and danger variants, controlled or uncontrolled checked state, an indeterminate mode, and composable building blocks for custom layouts.
+
+## Import
+
+```tsx
+import { Checkbox } from '@redislabsdev/redis-ui-components';
+```
+
+If you use the controlled example, also import `CheckedType` from the same package.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `CheckboxLabelProps['children']` | - | Label content rendered next to the checkbox |
+| defaultChecked | `boolean` | `false` | Initial uncontrolled checked state |
+| checked | `CheckedType` | - | Controlled checked state, including `indeterminate` |
+| onCheckedChange | `(checked: CheckedType) => void` | - | Callback fired when the checked state changes |
+| required | `boolean` | `false` | Marks the checkbox as required |
+| disabled | `boolean` | `false` | Disables the checkbox interaction |
+| id | `string` | auto-generated | Shared id used by the label and indicator |
+| variant | `'primary' \| 'danger'` | `'primary'` | Visual variant for the checkbox |
+| readOnly | `boolean` | `false` | Renders the indicator in read-only mode |
+| indicator button props | `Omit<HTMLAttributes<HTMLButtonElement>, 'checked' \| 'defaultChecked' \| 'defaultValue' \| 'children' \| 'color'>` | - | Additional button props forwarded to the indicator |
+
+## Sub-components
+
+- `Checkbox.Compose` - Provides the checkbox context and controllable state for custom layouts.
+- `Checkbox.Indicator` - Renders the interactive checkbox control and checkmark icon.
+- `Checkbox.Label` - Renders the label linked to the checkbox `id`.
+
+### Checkbox.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultChecked | `boolean` | `false` | Initial uncontrolled checked state |
+| checked | `CheckedType` | - | Controlled checked state, including `indeterminate` |
+| onCheckedChange | `(checked: CheckedType) => void` | - | Callback fired when the checked state changes |
+| required | `boolean` | `false` | Marks the checkbox as required |
+| disabled | `boolean` | `false` | Disables the checkbox interaction |
+| id | `string` | auto-generated | Shared id used by the label and indicator |
+| variant | `'primary' \| 'danger'` | `'primary'` | Visual variant for the checkbox |
+| compose wrapper props | `Omit<ComposeElementProps<HTMLElement>, 'onChange' \| 'defaultChecked'>` | - | Additional wrapper props applied to the compose root |
+
+### Checkbox.Indicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| readOnly | `boolean` | `false` | Renders the indicator without allowing state changes |
+| indicator button props | `Omit<HTMLAttributes<HTMLButtonElement>, 'checked' \| 'defaultChecked' \| 'defaultValue' \| 'children' \| 'color'>` | - | Additional button props forwarded to the indicator element |
+
+### Checkbox.Label Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `CheckboxLabelProps['children']` | - | Label content |
+| label props | `LabelHTMLAttributes<HTMLLabelElement>` | - | Additional label element props |
+
+## Examples
+
+### Playground
+
+```tsx
+import { Checkbox } from '@redislabsdev/redis-ui-components';
+
+<Checkbox label="Checkbox Label" />
+```
+
+### Variants
+
+> Use the `variant` prop to switch between the primary and danger looks.
+
+```tsx
+import { Checkbox } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Checkbox label="Checked" checked />
+  <Checkbox label="Unchecked" checked={false} />
+  <Checkbox label="Indeterminate" checked="indeterminate" />
+  <Checkbox variant="danger" label="Checked" checked />
+  <Checkbox variant="danger" label="Unchecked" checked={false} />
+  <Checkbox variant="danger" label="Indeterminate" checked="indeterminate" />
+</>
+```
+
+### DisabledVariants
+
+> Disabled checkboxes also support both visual variants.
+
+```tsx
+import { Checkbox } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Checkbox disabled label="Checked" checked />
+  <Checkbox disabled label="Unchecked" />
+  <Checkbox disabled label="Indeterminate" checked="indeterminate" />
+  <Checkbox disabled variant="danger" label="Checked" checked />
+  <Checkbox disabled variant="danger" label="Unchecked" />
+  <Checkbox disabled variant="danger" label="Indeterminate" checked="indeterminate" />
+</>
+```
+
+### Multiline
+
+> For multiline labels, align the checkbox container to the top so the indicator stays aligned with the first line.
+
+```tsx
+import { Checkbox } from '@redislabsdev/redis-ui-components';
+
+<Checkbox
+  style={{ alignItems: 'flex-start', maxWidth: 600 }}
+  label='This Checkbox with a very long label that takes up several lines. For multiline checkboxes you need to set "align-items: flex-start;" to align check indicator to the top. Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+/>
+```
+
+### Controlled
+
+> Controlled mode can switch between checked and indeterminate.
+
+```tsx
+import { useState } from 'react';
+import { Button, Checkbox } from '@redislabsdev/redis-ui-components';
+import type { CheckedType } from '@redislabsdev/redis-ui-components';
+
+const [checked, setChecked] = useState<CheckedType>('indeterminate');
+
+const onCheckedChange = (newChecked: CheckedType) => {
+  setChecked(newChecked || 'indeterminate');
+};
+
+<>
+  <Button onClick={() => setChecked(true)}>Checked</Button>
+  <Button onClick={() => setChecked('indeterminate')}>Indeterminate</Button>
+  <Checkbox
+    checked={checked}
+    onCheckedChange={onCheckedChange}
+    label="This Checkbox switches between Checked and Indeterminate"
+  />
+</>
+```
+
+### Composition
+
+```tsx
+import { Checkbox } from '@redislabsdev/redis-ui-components';
+import { MasterCardIcon } from '@redislabsdev/redis-ui-icons/multicolor';
+
+<>
+  <Checkbox.Compose>
+    <Checkbox.Label>Left side label</Checkbox.Label>
+    <Checkbox.Indicator />
+  </Checkbox.Compose>
+
+  <Checkbox.Compose defaultChecked>
+    <Checkbox.Indicator />
+    <Checkbox.Label>
+      <MasterCardIcon size="XL" />
+      Label with Icon
+    </Checkbox.Label>
+  </Checkbox.Compose>
+</>
+```
+
+## Notes
+
+- `Checkbox.Compose`, `Checkbox.Indicator`, and `Checkbox.Label` are compound components and should be rendered together.
+- `Checkbox.Compose` generates an id automatically when one is not provided.
+- String labels are wrapped in body typography with ellipsis tooltip support; non-string children are rendered as-is.
+- `checked` accepts `true`, `false`, or `'indeterminate'`.