@redis-ui/components 43.0.2 → 43.2.1

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

@@ -0,0 +1,193 @@
+# Switch
+
+A boolean switch component with controlled and uncontrolled state, disabled/read-only behavior, and a composition API for custom switcher and title layouts.
+
+## Import
+
+```tsx
+import { Switch } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked` | `boolean` | - | Controlled checked state. |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled initial checked state. |
+| `disabled` | `boolean` | `false` | Disables interaction and propagates to the switcher. |
+| `readOnly` | `boolean` | `false` | Renders the switch as read-only while preserving its value. |
+| `onCheckedChange` | `(checked: boolean) => void` | - | Called when the checked state changes. |
+| `titleOn` | `ReactNode` | - | Content shown when the switch is checked. |
+| `titleOff` | `ReactNode` | - | Content shown when the switch is unchecked. |
+| `className` | `string` | - | Applied to the composed root element. |
+| `style` | `CSSProperties` | - | Applied to the composed root element. |
+| `id` | `string` | - | Shared id used for label association with the switcher. |
+| `other button attributes` | `HTMLAttributes<HTMLButtonElement>` | - | Any other button attributes are forwarded to `Switch.Switcher`. |
+
+The component also accepts the rest of `HTMLAttributes<HTMLButtonElement>`, which are merged onto the switcher part.
+
+## Sub-components
+
+- `Switch.Compose` - Composition root that provides checked state and field context.
+- `Switch.Switcher` - Interactive switch button/track rendered inside the composition.
+- `Switch.Switcher.Compose` - Low-level switcher root used for advanced custom layouts.
+- `Switch.Switcher.Knob` - Thumb element rendered inside the switcher.
+- `Switch.Title` - Text label that reflects the current checked state.
+
+### Switch.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `disabled` | `boolean` | `false` | Disables interaction for the composed switch. |
+| `readOnly` | `boolean` | `false` | Marks the composed switch as read-only. |
+| `checked` | `boolean` | - | Controlled checked state. |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled initial checked state. |
+| `onCheckedChange` | `(checked: boolean) => void` | - | Called when the checked state changes. |
+| `children` | `ReactNode` | - | Composed switch parts, typically `Switch.Switcher` and `Switch.Title`. |
+
+`Switch.Compose` also accepts the standard `ComposeElementProps<HTMLElement>` props, including `className`, `style`, `data-*` attributes, and event handlers.
+
+### Switch.Switcher Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | - | Shared id for label association and test targeting. |
+| `other button attributes` | `HTMLAttributes<HTMLButtonElement>` | - | Remaining button props are merged onto the switcher element. |
+
+`Switch.Switcher` accepts the rest of `HTMLAttributes<HTMLButtonElement>` and combines its own pointer, keyboard, and mouse handlers with any handlers passed in.
+
+### Switch.Title Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `titleOn` | `ReactNode` | - | Content shown when the switch is checked. |
+| `titleOff` | `ReactNode` | - | Content shown when the switch is unchecked. |
+
+`Switch.Title` also extends `ChildFree<TypographyBodyProps>`, so typography body props can be passed through without `children`.
+
+## Examples
+
+### Playground
+
+```tsx
+import { Switch } from '@redislabsdev/redis-ui-components';
+
+<Switch {...args} checked={checked} onCheckedChange={handleClickSwitch} />
+```
+
+### Disabled
+
+```tsx
+import { Switch } from '@redislabsdev/redis-ui-components';
+
+<>
+  {[false, true].map((checked) => (
+    <Switch
+      key={`${checked}`}
+      disabled
+      defaultChecked={checked}
+      titleOn="titleOn"
+      titleOff="titleOff"
+    />
+  ))}
+</>
+```
+
+### Readonly
+
+```tsx
+import { Switch } from '@redislabsdev/redis-ui-components';
+
+<>
+  {[false, true].map((checked) => (
+    <Switch
+      key={`${checked}`}
+      readOnly
+      defaultChecked={checked}
+      titleOn="titleOn"
+      titleOff="titleOff"
+    />
+  ))}
+</>
+```
+
+### WithinFormField
+
+```tsx
+import { FormField, Switch } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="Normal" additionalText="Switch in FormField">
+    <Switch checked={state} titleOn="titleOn" titleOff="titleOff" onCheckedChange={setState} />
+  </FormField>
+  <FormField label="Readonly" additionalText="Switch in FormField">
+    <Switch
+      checked={state}
+      readOnly
+      titleOn="titleOn"
+      titleOff="titleOff"
+      onCheckedChange={setState}
+    />
+  </FormField>
+  <FormField label="Disabled" additionalText="Switch in FormField">
+    <Switch
+      checked={state}
+      disabled
+      titleOn="titleOn"
+      titleOff="titleOff"
+      onCheckedChange={setState}
+    />
+  </FormField>
+</>
+```
+
+### BasicComposition
+
+```tsx
+import { Switch } from '@redislabsdev/redis-ui-components';
+
+<Switch.Compose checked={state} onCheckedChange={setState}>
+  <Switch.Switcher />
+  <Switch.Title titleOn="On" titleOff="Off" />
+</Switch.Compose>
+```
+
+### BothSideText
+
+```tsx
+import { Switch } from '@redislabsdev/redis-ui-components';
+
+<Switch.Compose checked={state} onCheckedChange={setState}>
+  <Switch.Title titleOn="On" titleOff="Off" />
+  <Switch.Switcher />
+  <Switch.Title titleOn="Off" titleOff="On" />
+</Switch.Compose>
+```
+
+### StyledComposition
+
+> Custom styling can be added to all components in a composition.
+> Styles can be state-consistent.
+
+```tsx
+import { FormField, Switch } from '@redislabsdev/redis-ui-components';
+import * as S from './SwitchStory.style';
+
+<FormField label={<S.CustomTitle checked={state}>Fancy Switch</S.CustomTitle>}>
+  <Switch.Compose checked={state}>
+    <S.CustomSwitcherCompose data-testid="switcher" checked={state} onCheckedChange={setState}>
+      <S.CustomKnob $on={state} />
+    </S.CustomSwitcherCompose>
+    <S.CustomText checked={state} titleOn="On" titleOff="Off" />
+  </Switch.Compose>
+</FormField>
+```
+
+## Notes
+
+- `titleOn` and `titleOff` accept any `ReactNode`, not just strings.
+- `Switch.Title` only renders when at least one of `titleOn` or `titleOff` is provided.
+- When used without composition, all HTML button attributes other than `className` and `style` are redirected to the switcher part.
+- The switcher root exposes `data-role="switch-root"` and the title exposes `data-role="switch-title"`.
+- In tests, locate the interactive element by its `role="switch"`, use `userEvent.click` to toggle it, and assert disabled/read-only state on the switcher.
+- `Switch.Switcher.Compose` and `Switch.Switcher.Knob` are intended for advanced custom styling and layout.

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

@@ -0,0 +1,383 @@
+# Tabs
+
+Tabs renders a tab bar and matching content panes from a shared tab list. It supports controlled and uncontrolled state, keyboard activation behavior, variant styling, and a compound composition API for fully custom layouts.
+
+## Import
+
+```tsx
+import { Tabs } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| tabs | `TTab[]` | required | Tabs to render. Each item combines trigger and content data. |
+| defaultValue | `NoInfer<TValue>` | - | Initial active tab when using uncontrolled state. |
+| value | `NoInfer<TValue>` | - | Controlled active tab value. |
+| onChange | `(newValue: TValue) => void` | - | Called when the active tab changes. |
+| activateOnFocus | `boolean` | `false` | Activates a tab as soon as it receives focus instead of waiting for Enter or Space. |
+| variant | `'default' \| 'sub'` | `'default'` | Tab bar styling variant. |
+
+The root `Tabs` component also accepts native compose element props, excluding `children` and `dir`.
+
+### Related Types
+
+- `TabInfo<TValue = string>` - Combined trigger and content data for a single tab.
+- `TabTriggerInfo<TValue = string>` - Trigger metadata with `value`, optional `label`, and optional `disabled`.
+- `TabContentInfo<TValue = string>` - Content metadata with `value` and `content`.
+- `TabsVariant` - `'default' | 'sub'`.
+
+## Sub-components
+
+- `Tabs.Compose` - Shared state wrapper for fully custom tab layouts.
+- `Tabs.TabBar` - Default tab trigger renderer built from a `tabs` array.
+- `Tabs.TabBar.Compose` - Composition wrapper for custom trigger layouts.
+- `Tabs.TabBar.Trigger` - Default trigger renderer for a single tab.
+- `Tabs.TabBar.Trigger.Compose` - Radix trigger wrapper for custom trigger content.
+- `Tabs.TabBar.Trigger.Tab` - Tab label container; string children are wrapped in `Typography.Body`.
+- `Tabs.TabBar.Trigger.Marker` - Active, hover, focus, and disabled indicator rendered inside a trigger.
+- `Tabs.ContentPane` - Default content renderer built from a `tabs` array.
+- `Tabs.ContentPane.Compose` - Composition wrapper for custom content layouts.
+- `Tabs.ContentPane.Content` - Individual content panel linked by `value`.
+
+### Tabs.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultValue | `NoInfer<TValue>` | - | Initial active tab when using uncontrolled state. |
+| value | `NoInfer<TValue>` | - | Controlled active tab value. |
+| onChange | `(newValue: TValue) => void` | - | Called when the active tab changes. |
+| activateOnFocus | `boolean` | `false` | Activates a tab as soon as it receives focus instead of waiting for Enter or Space. |
+| children | `React.ReactNode` | required | Custom tab bar and content pane layout. |
+
+Tabs.Compose also accepts native compose element props, excluding `dir`.
+
+### Tabs.TabBar Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| tabs | `TabTriggerInfo[]` | required | Tabs to render in the bar. |
+| variant | `TabsVariant` | `'default'` | Tab bar styling variant. |
+
+Tabs.TabBar also accepts native compose element props, excluding `children`.
+
+### Tabs.TabBar.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `TabsVariant` | `'default'` | Tab bar styling variant. |
+| children | `React.ReactNode` | required | Custom trigger elements. |
+
+Tabs.TabBar.Compose also accepts native compose element props.
+
+### Tabs.TabBar.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | required | Active value for the trigger. |
+| disabled | `boolean` | `false` | Disables the trigger. |
+| children | `React.ReactNode` | required | Trigger label or custom trigger content. |
+
+Tabs.TabBar.Trigger also accepts the same native button compose props as `Tabs.TabBar.Trigger.Compose`.
+
+### Tabs.TabBar.Trigger.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | required | Active value for the trigger. |
+| disabled | `boolean` | `false` | Disables the trigger. |
+| children | `React.ReactNode` | required | Custom trigger content. |
+
+Tabs.TabBar.Trigger.Compose also accepts native button compose props.
+
+### Tabs.TabBar.Trigger.Tab Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Tab label content. |
+
+Tabs.TabBar.Trigger.Tab also accepts native compose element props.
+
+### Tabs.TabBar.Trigger.Marker Props
+
+Tabs.TabBar.Trigger.Marker does not define custom props. It accepts native `HTMLAttributes<HTMLDivElement>` without `children`.
+
+### Tabs.ContentPane Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| tabs | `TabContentInfo[]` | required | Tab content panels to render. |
+
+Tabs.ContentPane also accepts native compose element props, excluding `children`.
+
+### Tabs.ContentPane.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Custom content panel layout. |
+
+Tabs.ContentPane.Compose also accepts native compose element props.
+
+### Tabs.ContentPane.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | required | Value that links the panel to a tab trigger. |
+| children | `React.ReactNode` | required | Panel content. |
+
+Tabs.ContentPane.Content also accepts native content compose props.
+
+## Examples
+
+### Basic Usage
+
+> Playground story
+
+```tsx
+import { Tabs } from '@redislabsdev/redis-ui-components';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+<Tabs tabs={tabs} defaultValue={tabs[0].value} />
+```
+
+### ControlledMode
+
+> Set `value` and `onChange` props to use controlled mode
+
+```tsx
+import { useState } from 'react';
+import { Tabs } from '@redislabsdev/redis-ui-components';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+function Example() {
+  const [selectedTab, setSelectedTab] = useState(tabs[0].value);
+
+  return <Tabs tabs={tabs} value={selectedTab} onChange={setSelectedTab} />;
+}
+```
+
+### Variants
+
+> 2 variants are supported, `default` and `sub`. Use `variant` prop to set it.
+
+```tsx
+import { Tabs } from '@redislabsdev/redis-ui-components';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+<>
+  <Tabs tabs={tabs} defaultValue={tabs[0].value} />
+  <Tabs tabs={tabs} defaultValue={tabs[0].value} variant="sub" />
+</>
+```
+
+### ActivateTabOnFocus
+
+> When navigating between tabs using the keyboard, the tab will only be focused by the arrow keys, but activated when Enter or Space is pressed.
+> To change this behavior, set the `activateOnFocus` prop to true, and the tab will be activated by the arrow keys.
+
+```tsx
+import { Tabs } from '@redislabsdev/redis-ui-components';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+<Tabs tabs={tabs} defaultValue={tabs[0].value} activateOnFocus />
+```
+
+### HeaderAndContent
+
+> Tabs component can be shallow composed using 2 main parts:
+> - `Tabs.TabBar` for rendering header
+> - `Tabs.ContentPane` for rendering content
+>
+> Each part receives tabs list as `tabs` prop.
+> Same tabs list can be used for both parts and for `Tabs` component
+>
+> State management props should be passed to `Tabs.Compose`
+>
+> All parts can have custom styling
+
+```tsx
+import { Tabs } from '@redislabsdev/redis-ui-components';
+import styled from 'styled-components';
+import { useTheme } from '@redislabsdev/redis-ui-styles';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+function Example() {
+  return (
+    <Tabs.Compose defaultValue={tabs[1].value}>
+      <Tabs.TabBar
+        tabs={tabs}
+        style={{ background: useTheme().semantic.color.background.notice100 }}
+      />
+      <Tabs.ContentPane
+        tabs={tabs}
+        style={{ background: useTheme().semantic.color.background.success100 }}
+      />
+    </Tabs.Compose>
+  );
+}
+```
+
+### TabBarOnly
+
+> Tabs component can be used without `Tabs.ContentPane`.
+> e.g. when using tabs with router, router Switch can be used instead of tab content (controlled mode is required to manage tabs state)
+
+```tsx
+import { useState } from 'react';
+import { Tabs } from '@redislabsdev/redis-ui-components';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+function Example() {
+  const [selectedTab, setSelectedTab] = useState(tabs[0].value);
+
+  return (
+    <Tabs.Compose value={selectedTab} onChange={setSelectedTab}>
+      <Tabs.TabBar tabs={tabs} />
+    </Tabs.Compose>
+  );
+}
+```
+
+### HeaderComposition
+
+> The `Tabs.TabBar` can be composed and all parts can be customized including the tab trigger content and marker
+>
+> Styled components should be defined outside the render function.
+
+```tsx
+import { Tabs } from '@redislabsdev/redis-ui-components';
+import styled from 'styled-components';
+import { useTheme } from '@redislabsdev/redis-ui-styles';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+const CustomTabsTabBarTriggerCompose = styled(Tabs.TabBar.Trigger.Compose)``;
+
+const CustomTabsTriggerContent = styled(Tabs.TabBar.Trigger.Tab)`
+  && {
+    padding: 5px;
+    border-radius: 6px 6px 0 0;
+  }
+
+  ${CustomTabsTabBarTriggerCompose}:hover && {
+    background-color: ${useTheme().semantic.color.background.neutral500};
+  }
+  ${CustomTabsTabBarTriggerCompose}[data-state='active'] && {
+    background-color: ${useTheme().semantic.color.background.neutral800};
+    color: ${useTheme().semantic.color.background.neutral100};
+  }
+  ${CustomTabsTabBarTriggerCompose}[data-disabled] && {
+    background: none;
+    border: solid ${useTheme().semantic.color.background.neutral300};
+    border-width: 1px 1px 0 1px;
+  }
+`;
+
+const CustomTabsTriggerMarker = styled(Tabs.TabBar.Trigger.Marker)`
+  ${CustomTabsTabBarTriggerCompose}[data-state='active'] && {
+    background-color: ${useTheme().semantic.color.background.danger500};
+    height: 5px;
+  }
+`;
+
+function Example() {
+  return (
+    <Tabs.Compose defaultValue="tab1">
+      <Tabs.TabBar.Compose>
+        {tabs.map(({ value, label, disabled }) => (
+          <CustomTabsTabBarTriggerCompose key={value} value={value} disabled={disabled}>
+            <CustomTabsTriggerContent>{label ?? value}</CustomTabsTriggerContent>
+            <CustomTabsTriggerMarker />
+          </CustomTabsTabBarTriggerCompose>
+        ))}
+      </Tabs.TabBar.Compose>
+      <Tabs.ContentPane tabs={tabs} />
+    </Tabs.Compose>
+  );
+}
+```
+
+### ContentComposition
+
+> The `Tabs.ContentPane` can be composed and customized using a container for each tab (`Tabs.ContentPane.Content`) and a main container (`Tabs.ContentPane.Compose`).
+
+```tsx
+import { Tabs } from '@redislabsdev/redis-ui-components';
+import styled from 'styled-components';
+import { useTheme } from '@redislabsdev/redis-ui-styles';
+
+const tabs = [
+  { value: 'tab1', label: 'First Tab', content: 'First Tab Content' },
+  { value: 'tab2', label: 'Second Tab', content: 'Second Tab Content' },
+  { value: 'tab3', label: 'Third Tab (disabled)', content: 'Third Tab Content', disabled: true }
+];
+
+const CustomTabsContentPaneContent = styled(Tabs.ContentPane.Content)`
+  background-color: ${useTheme().semantic.color.background.success100};
+  padding: 10px;
+  border: 1px solid ${({ theme }) => theme.components.tabs.variants.default?.tabsLine.color};
+  border-top: none;
+`;
+
+function Example() {
+  return (
+    <Tabs.Compose defaultValue="tab1">
+      <Tabs.TabBar tabs={tabs} />
+      <Tabs.ContentPane.Compose>
+        <CustomTabsContentPaneContent value="tab1">
+          <strong>First Tab Content</strong>
+        </CustomTabsContentPaneContent>
+        <CustomTabsContentPaneContent value="tab2">
+          <em>Second Tab Content</em>
+        </CustomTabsContentPaneContent>
+      </Tabs.ContentPane.Compose>
+    </Tabs.Compose>
+  );
+}
+```
+
+## Notes
+
+- Use `value` and `onChange` together for controlled mode.
+- `Tabs` supports `default` and `sub` variants.
+- Keyboard navigation activates on Enter or Space by default; set `activateOnFocus` to activate the tab when focus moves with the arrow keys.
+- `Tabs.TabBar` and `Tabs.ContentPane` can be used together as shallow composition building blocks.
+- Pass the same `tabs` array to `Tabs.TabBar` and `Tabs.ContentPane` when composing them separately.
+- `Tabs.Compose` should receive the shared state props when building custom layouts.
+- `Tabs` can be used without `Tabs.ContentPane` when a router or other external content switch handles the panel rendering.
+- Define styled components outside the render function when composing `Tabs.TabBar` or `Tabs.ContentPane`.