@redis-ui/components 43.0.2 → 43.2.1

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

@@ -0,0 +1,398 @@
+# Slider
+
+Composable range slider with a default wrapper, track, thumb, marks, and labels. Use `Slider` for the standard layout, or `Slider.Compose` when you need to position and style the pieces manually.
+
+## Import
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+```
+
+> Examples also use icons from `@redislabsdev/redis-ui-icons`:
+> ```tsx
+> import { PlusIcon, MinusIcon, InfoIcon } from '@redislabsdev/redis-ui-icons';
+> ```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `number[]` | - | Controlled slider value |
+| defaultValue | `number[]` | - | Uncontrolled initial value |
+| onChange | `(values: number[]) => void` | - | Called when the slider value changes |
+| disabled | `boolean` | `false` | Disables interaction |
+| min | `number` | `0` | Minimum slider value |
+| max | `number` | *required* | Maximum slider value |
+| step | `number` | `1` | Step increment |
+| marks | `SliderMarks` | - | Mark and label definitions for `Slider.MarksAndLabels` |
+
+The top-level `Slider` also inherits standard compose element props through `ComposeElementProps`, excluding `children`, `content`, `dir`, `defaultValue`, and `onChange`.
+
+## Sub-components
+
+- `Slider.Compose` - low-level slider root that provides slider context and renders the Radix slider container.
+- `Slider.Track` - default track wrapper that renders `Slider.Track.Range`.
+- `Slider.Track.Compose` - container for custom track composition.
+- `Slider.Track.Range` - renders the filled portion of the track.
+- `Slider.Thumb` - default thumb wrapper.
+- `Slider.Thumb.Compose` - container for custom thumb composition.
+- `Slider.Mark` - default mark renderer positioned by `value`.
+- `Slider.Mark.Compose` - renders a mark at a specific value with custom children.
+- `Slider.Label` - default label renderer positioned by `value`.
+- `Slider.Label.Compose` - renders a label at a specific value and can set the slider value when clicked.
+- `Slider.MarksAndLabels` - renders marks and labels from a `marks` array, with optional custom renderers.
+
+## Examples
+
+### Playground
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<Slider defaultValue={[0]} max={9} aria-label="slider" />;
+```
+
+### Uncontrolled
+
+> The slider can be used in uncontrolled mode with `defaultValue`.
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<Slider max={9} defaultValue={[3]} aria-label="Slider" />;
+```
+
+### Controlled
+
+> Use `value` and `onChange` for controlled mode.
+> The slider value is controlled externally - use the +/- buttons to change the value from outside the slider.
+
+```tsx
+import { useState } from 'react';
+import { Slider, ActionIconButton } from '@redislabsdev/redis-ui-components';
+import { PlusIcon, MinusIcon } from '@redislabsdev/redis-ui-icons';
+
+function ControlledSliderExample() {
+  const [stepIndex, setStepIndex] = useState(1);
+
+  const decrement = () => setStepIndex((prev) => Math.max(0, prev - 1));
+  const increment = () => setStepIndex((prev) => Math.min(6, prev + 1));
+
+  const handleValueChange = (value: number[]) => {
+    setStepIndex(value[0]);
+  };
+
+  return (
+    <>
+      <Slider max={6} value={[stepIndex]} onChange={handleValueChange} aria-label="Slider" />
+      <p>Use the buttons to control the slider externally:</p>
+      <div>
+        <ActionIconButton
+          icon={MinusIcon}
+          onClick={decrement}
+          disabled={stepIndex === 0}
+          aria-label="Decrement"
+        />
+        <ActionIconButton
+          icon={PlusIcon}
+          onClick={increment}
+          disabled={stepIndex === 6}
+          aria-label="Increment"
+        />
+      </div>
+      <p>
+        Selected: <strong>{stepIndex}</strong>
+      </p>
+    </>
+  );
+}
+
+<ControlledSliderExample />;
+```
+
+### Disabled
+
+> Set `disabled` prop to disable the slider.
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<Slider max={9} defaultValue={[3]} aria-label="Slider" disabled />;
+```
+
+### DifferentStepCounts
+
+> The slider works with any number of steps.
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Slider max={2} defaultValue={[1]} aria-label="Slider" />
+  <Slider max={6} defaultValue={[3]} aria-label="Slider" />
+</>;
+```
+
+### PartialLabelsAndMarks
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<Slider
+  max={6}
+  defaultValue={[3]}
+  marks={[
+    { value: 0, mark: true, label: 'Min' },
+    { value: 1, mark: true },
+    { value: 2, mark: true },
+    { value: 3, mark: true, label: 'Medium' },
+    { value: 4, mark: true },
+    { value: 5, mark: true },
+    { value: 6, mark: true, label: 'Max' }
+  ]}
+  aria-label="Slider"
+/>;
+```
+
+### MinAndStep
+
+> Use `min` and `step` props to customize the slider range and granularity.
+> This example shows a slider from 10 to 100 with steps of 10.
+
+```tsx
+import { useState } from 'react';
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+function MinAndStepExample() {
+  const [value, setValue] = useState([30]);
+
+  return (
+    <>
+      <Slider.Compose min={10} max={100} step={10} value={value} onChange={setValue} aria-label="Slider">
+        <Slider.Track.Compose>
+          <Slider.Track.Range />
+        </Slider.Track.Compose>
+        <Slider.MarksAndLabels
+          marks={[
+            { value: 10, mark: true, label: '10' },
+            { value: 30, mark: true, label: '30' },
+            { value: 50, mark: true, label: '50' },
+            { value: 70, mark: true, label: '70' },
+            { value: 100, mark: true, label: '100' }
+          ]}
+        />
+        <Slider.Thumb />
+      </Slider.Compose>
+      <p>
+        Current value: <strong>{value[0]}</strong>
+      </p>
+    </>
+  );
+}
+
+<MinAndStepExample />;
+```
+
+### WithMarks
+
+> Display marks only without labels.
+> Marks are visual indicators positioned at specific values on the slider.
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+const marks = [
+  { value: 0, mark: true },
+  { value: 1, mark: true },
+  { value: 2, mark: true },
+  { value: 3, mark: true },
+  { value: 4, mark: true },
+  { value: 5, mark: true },
+  { value: 6, mark: true },
+  { value: 7, mark: true },
+  { value: 8, mark: true },
+  { value: 9, mark: true }
+];
+
+<>
+  <Slider.Compose max={9} defaultValue={[5]} aria-label="Slider">
+    <Slider.Track.Compose>
+      <Slider.Track.Range />
+    </Slider.Track.Compose>
+    <Slider.MarksAndLabels marks={marks} />
+    <Slider.Thumb />
+  </Slider.Compose>
+  <Slider.Compose max={9} defaultValue={[5]} disabled>
+    <Slider.Track.Compose>
+      <Slider.Track.Range />
+    </Slider.Track.Compose>
+    <Slider.MarksAndLabels marks={marks} />
+    <Slider.Thumb />
+  </Slider.Compose>
+</>;
+```
+
+### CustomRenderers
+
+> Customize the appearance of marks and labels using custom render functions.
+> This example shows custom styling with badges, icons, and conditional formatting.
+
+```tsx
+import { FlexGroup, Badge, Typography, Slider } from '@redislabsdev/redis-ui-components';
+import { InfoIcon } from '@redislabsdev/redis-ui-icons';
+import { MOCK_MARKS } from './SliderStory.data';
+import * as S from './SliderStory.style';
+
+const CustomLabel = ({ value, label = '' }: { value: number; label?: string }) => {
+  return (
+    <FlexGroup direction="column" align="center">
+      {value === 5 && <Badge label="Middle" variant="notice" />}
+      <FlexGroup>
+        <Typography.Body variant={value === 0 || value === 10 || value === 5 ? 'italic' : 'regular'}>
+          {label}
+        </Typography.Body>
+        {value === 8 && <InfoIcon />}
+      </FlexGroup>
+    </FlexGroup>
+  );
+};
+
+const CustomMark = () => <S.Mark />;
+
+<Slider.Compose max={10} defaultValue={[5]} aria-label="Slider">
+  <Slider.Track.Compose>
+    <Slider.Track.Range />
+  </Slider.Track.Compose>
+  <Slider.MarksAndLabels marks={MOCK_MARKS} renderLabel={CustomLabel} renderMark={CustomMark} />
+  <Slider.Thumb />
+</Slider.Compose>;
+```
+
+### ComposeWithLabels
+
+> Display labels only without marks.
+> Labels show text at specific positions on the slider.
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<Slider.Compose max={10} defaultValue={[5]} aria-label="Slider">
+  <Slider.Track.Compose>
+    <Slider.Track.Range />
+  </Slider.Track.Compose>
+  <Slider.MarksAndLabels
+    marks={[
+      { value: 0, mark: false, label: 'Min' },
+      { value: 5, mark: false, label: 'Medium' },
+      { value: 10, mark: false, label: 'Max' }
+    ]}
+  />
+  <Slider.Thumb />
+</Slider.Compose>;
+```
+
+### ComposeWithMarksAndLabels
+
+> Display both marks and labels together.
+> Each mark can have an optional label to describe its value.
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<Slider.Compose max={9} defaultValue={[5]}>
+  <Slider.Track.Compose>
+    <Slider.Track.Range />
+  </Slider.Track.Compose>
+  <Slider.MarksAndLabels
+    marks={[
+      { value: 0, mark: true, label: '0GB' },
+      { value: 2, mark: true, label: '2GB' },
+      { value: 5, mark: true, label: '5GB' },
+      { value: 8, mark: true, label: '8GB' },
+      { value: 9, mark: true, label: '10GB' }
+    ]}
+  />
+  <Slider.Thumb />
+</Slider.Compose>;
+```
+
+### DeepComposition
+
+> Deep composition allows you to place Mark and Label components independently.
+> This gives you full control over positioning and styling.
+
+```tsx
+import { Slider } from '@redislabsdev/redis-ui-components';
+
+<Slider.Compose max={9} defaultValue={[5]}>
+  <Slider.Track.Compose>
+    <Slider.Track.Range />
+  </Slider.Track.Compose>
+
+  <Slider.Mark value={0} />
+  <Slider.Mark value={2} />
+  <Slider.Mark value={5} />
+  <Slider.Mark value={8} />
+  <Slider.Mark value={9} />
+
+  <Slider.Label value={0}>Min</Slider.Label>
+  <Slider.Label value={4}>Medium</Slider.Label>
+  <Slider.Label value={9}>Max</Slider.Label>
+
+  <Slider.Thumb />
+</Slider.Compose>;
+```
+
+### CustomStyling
+
+> Full composition example showing how to create custom styled slider components.
+> You can compose your own slider with custom styling for all parts.
+
+```tsx
+import { Fragment, useState } from 'react';
+import { Slider } from '@redislabsdev/redis-ui-components';
+import { PLANS_MOCK_MARKS } from './SliderStory.data';
+import * as S from './SliderStory.style';
+
+function CustomStylingExample() {
+  const [value, setValue] = useState([5]);
+
+  return (
+    <>
+      <Slider.Compose onChange={setValue} value={value} max={PLANS_MOCK_MARKS.length - 1}>
+        <S.CustomTrackCompose>
+          <S.CustomRange />
+        </S.CustomTrackCompose>
+        {PLANS_MOCK_MARKS.map(({ value: valueMark, label }) => (
+          <Fragment key={valueMark}>
+            <S.CustomLabel value={valueMark}>{label}</S.CustomLabel>
+            <Slider.Mark.Compose value={valueMark}>
+              <S.CustomMark />
+            </Slider.Mark.Compose>
+          </Fragment>
+        ))}
+        <Slider.Thumb.Compose>
+          <S.CustomThumb />
+        </Slider.Thumb.Compose>
+      </Slider.Compose>
+      <p>
+        Current value: <strong>{value[0]}</strong>
+      </p>
+    </>
+  );
+}
+
+<CustomStylingExample />;
+```
+
+## Notes
+
+- Use `defaultValue` for uncontrolled sliders.
+- Use `value` and `onChange` when the slider state is controlled externally.
+- Set `disabled` to prevent interaction.
+- `min` and `step` let you customize the value range and granularity.
+- `marks` accepts `SliderMarks`, where each entry can include `value`, `mark`, and `label`.
+- `Slider.MarksAndLabels` supports custom `renderMark` and `renderLabel` callbacks for fully custom mark/label rendering.
+- `Slider.Mark.Compose` and `Slider.Label.Compose` let you place marks and labels independently.
+- `Slider.Label.Compose` is clickable by default and can update the slider value unless `clickable={false}`.
+- The top-level `Slider` is a convenience wrapper; use `Slider.Compose` when you need to build the slider layout manually.

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

@@ -0,0 +1,288 @@
+# Stepper
+
+Composable stepper for ordered workflows with a data-driven root API, controlled navigation, and fully composable step parts for custom labels, icons, and styling.
+
+## Import
+
+```tsx
+import { Stepper } from '@redislabsdev/redis-ui-components';
+```
+
+If you want to style against step state, also import `StepperStepState` from the same package.
+
+## Props
+
+### `Stepper`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| steps | `StepperStep[]` | required | Array of step descriptors rendered by the root stepper |
+| currentStep | `number` | `-1` | Zero-based active step index |
+| getIsStepInteractive | `(stepIndex: number) => boolean` | - | Optional predicate that marks specific steps interactive |
+| onStepChange | `(stepIndex: number) => void` | - | Called when the user activates a step |
+| compose root props | `ComposeElementProps<HTMLElement>` | - | Additional container props forwarded to `Stepper.Compose` |
+
+`Stepper` also accepts the remaining `ComposeElementProps<HTMLElement>` props, including `className`, `style`, `id`, `data-*`, and event handlers.
+
+### `StepperStep`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| label | `ReactNode` | Optional label content for the step |
+| icon | `ReactNode` | Optional icon content for the step circle |
+
+### `Stepper.Compose`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | required | Step compositions rendered inside the stepper |
+| currentStep | `number` | `-1` | Zero-based active step index |
+| getIsStepInteractive | `(stepIndex: number) => boolean` | - | Optional predicate that marks specific steps interactive |
+| onStepChange | `(stepIndex: number) => void` | - | Called when the user activates a step |
+| compose root props | `ComposeElementProps<HTMLElement>` | - | Standard container props forwarded to the compose root |
+
+`Stepper.Compose` also accepts the remaining `ComposeElementProps<HTMLElement>` props.
+
+### `Stepper.Step`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Label content rendered by the default step layout |
+| step wrapper props | `HTMLAttributes<HTMLDivElement>` | - | Additional props forwarded to the step wrapper |
+
+`Stepper.Step` is a convenience wrapper around `Stepper.Step.Compose`, `Stepper.Step.Icon`, and `Stepper.Step.Label`.
+
+### `Stepper.Step.Compose`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | required | Custom step contents |
+| compose root props | `ComposeElementProps<HTMLElement>` | - | Standard container props forwarded to the step compose root |
+
+### `Stepper.Step.Icon`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Custom icon content; when omitted, the step number is shown and completed steps render a check icon |
+| icon wrapper props | `HTMLAttributes<HTMLDivElement>` | - | Additional props forwarded to the icon container |
+
+### `Stepper.Step.Label`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Label content rendered next to the icon |
+| typography body props | `TypographyBodyProps` | - | Remaining body typography props forwarded to the label |
+
+### `Stepper.Step.useStepContext`
+
+Hook that returns the current step `state` and `index` for custom step rendering and styling.
+
+## Sub-components
+
+- `Stepper.Compose` - Root composition container that provides stepper state and navigation.
+- `Stepper.Step` - Convenience wrapper that renders the default step layout.
+- `Stepper.Step.Compose` - Low-level step wrapper used for custom step compositions.
+- `Stepper.Step.Icon` - Step circle content, including default index and completed state handling.
+- `Stepper.Step.Label` - Step label rendered with body typography styling.
+- `Stepper.Step.useStepContext` - Hook for reading the current step state and index inside custom step parts.
+
+## Examples
+
+### Playground
+
+```tsx
+import { Stepper } from '@redislabsdev/redis-ui-components';
+
+const storySteps = [
+  { label: 'Create a subscription' },
+  { label: 'Create a database' },
+  { label: 'Connect & add keys' }
+];
+
+<Stepper currentStep={1} steps={storySteps} />
+```
+
+### Steps
+
+> The same stepper with different `currentStep` prop.
+
+```tsx
+import { Stepper } from '@redislabsdev/redis-ui-components';
+
+const storySteps = [
+  { label: 'Create a subscription' },
+  { label: 'Create a database' },
+  { label: 'Connect & add keys' }
+];
+
+<>
+  <Stepper currentStep={-1} steps={storySteps} />
+  <Stepper currentStep={0} steps={storySteps} />
+  <Stepper currentStep={1} steps={storySteps} />
+  <Stepper currentStep={2} steps={storySteps} />
+  <Stepper currentStep={3} steps={storySteps} />
+</>
+```
+
+### Interactive
+
+> `Stepper` can be interactive if `onStepChange` is defined. It allows only controlled mode.<br/>
+> Use `ArrowLeft/Right`, `Home` and `End` keys for navigation or pointer click.
+
+```tsx
+import { useState } from 'react';
+import { Stepper } from '@redislabsdev/redis-ui-components';
+
+const storySteps = [
+  { label: 'Create a subscription' },
+  { label: 'Create a database' },
+  { label: 'Connect & add keys' }
+];
+
+function Example() {
+  const [currentStep, setCurrentStep] = useState(1);
+
+  return <Stepper steps={storySteps} currentStep={currentStep} onStepChange={setCurrentStep} />;
+}
+```
+
+### ClickableStepLabels
+
+> `Stepper.Step` can have any content.
+
+```tsx
+import { useState } from 'react';
+import { Stepper } from '@redislabsdev/redis-ui-components';
+import * as S from './StepperStory.style';
+
+const storySteps = [
+  { label: 'Create a subscription' },
+  { label: 'Create a database' },
+  { label: 'Connect & add keys' }
+];
+
+function Example() {
+  const [currentStep, setCurrentStep] = useState(1);
+
+  return (
+    <Stepper.Compose currentStep={currentStep} onStepChange={setCurrentStep}>
+      {storySteps.map(({ label: stepLabel }) => (
+        <Stepper.Step key={stepLabel}>
+          <S.AnchorLike>{stepLabel}</S.AnchorLike>
+        </Stepper.Step>
+      ))}
+    </Stepper.Compose>
+  );
+}
+```
+
+### StepCustomIcon
+
+> To change custom content of the step circle, you need to compose `Step` and set necessary `Step.Icon` content.
+
+```tsx
+import { useState } from 'react';
+import { DatabaseIcon, LinkIcon, SubscriptionsIcon } from '@redislabsdev/redis-ui-icons';
+import { Stepper } from '@redislabsdev/redis-ui-components';
+
+const storySteps = [
+  { label: 'Create a subscription' },
+  { label: 'Create a database' },
+  { label: 'Connect & add keys' }
+];
+
+function Example() {
+  const [currentStep, setCurrentStep] = useState(1);
+
+  return (
+    <>
+      <Stepper.Compose currentStep={currentStep} onStepChange={setCurrentStep}>
+        {storySteps.map(({ label: stepLabel }, index) => (
+          <Stepper.Step.Compose key={stepLabel}>
+            <Stepper.Step.Icon>{'ABC'[index]}</Stepper.Step.Icon>
+            <Stepper.Step.Label>{stepLabel}</Stepper.Step.Label>
+          </Stepper.Step.Compose>
+        ))}
+      </Stepper.Compose>
+
+      <Stepper.Compose currentStep={currentStep} onStepChange={setCurrentStep}>
+        {storySteps.map(({ label: stepLabel }, index) => {
+          const StepIcon = [SubscriptionsIcon, DatabaseIcon, LinkIcon][index];
+
+          return (
+            <Stepper.Step.Compose key={stepLabel}>
+              <Stepper.Step.Icon>
+                <StepIcon customColor="currentColor" size="M" />
+              </Stepper.Step.Icon>
+              <Stepper.Step.Label>{stepLabel}</Stepper.Step.Label>
+            </Stepper.Step.Compose>
+          );
+        })}
+      </Stepper.Compose>
+
+      <Stepper
+        currentStep={currentStep}
+        onStepChange={setCurrentStep}
+        steps={[
+          {
+            label: storySteps[0].label
+          },
+          {
+            label: storySteps[1].label,
+            icon: <DatabaseIcon customColor="currentColor" size="M" />
+          },
+          {
+            label: storySteps[2].label,
+            icon: 'III'
+          },
+          {}
+        ]}
+      />
+    </>
+  );
+}
+```
+
+### ComposingAndStyling
+
+> The `Stepper` component contains `Step` items. Each `Step` has a `data-state` attribute with `\"completed\" | \"focused\" | \"idle\"`, which can be used for CSS selector styling.
+>
+> Each `Step` component has two parts, `Icon` and `Label`, and both share the same `data-state` attribute.
+
+```tsx
+import { useState } from 'react';
+import { Stepper } from '@redislabsdev/redis-ui-components';
+import * as S from './StepperStory.style';
+
+function Example() {
+  const [currentStep, setCurrentStep] = useState(1);
+
+  const steps = [
+    { label: 'Item 1', icon: 'I' },
+    { label: 'Item 2', icon: 'II' },
+    { label: 'Item 3', icon: 'III' },
+    { label: 'Item 4', icon: 'IV' },
+    { label: 'Item 5', icon: 'V' }
+  ];
+
+  return (
+    <S.StepperCompose currentStep={currentStep} onStepChange={setCurrentStep}>
+      {steps.map(({ label, icon }, index) => (
+        <S.StepperStepCompose key={index}>
+          <S.StepperStepLabel>{label}</S.StepperStepLabel>
+          <S.StepperStepIcon>{icon}</S.StepperStepIcon>
+        </S.StepperStepCompose>
+      ))}
+    </S.StepperCompose>
+  );
+}
+```
+
+## Notes
+
+- `Stepper` supports both data-driven steps via `steps` and custom step compositions via `Stepper.Compose`.
+- `onStepChange` enables interactive controlled mode and keyboard navigation with `ArrowLeft/Right`, `Home`, and `End`.
+- `Stepper.Step` can render any `ReactNode`, not just plain text labels.
+- `Stepper.Step.Icon` falls back to the step number when no custom icon content is provided, and completed steps render a check icon.
+- `Stepper.Step` and its parts expose `data-state` values of `idle`, `focused`, and `completed`, which are intended for custom styling.
+- `StepperStepState` is the exported constant to target those states in styled wrappers and CSS selectors.