@redis-ui/components 42.8.0 → 43.2.1

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

@@ -0,0 +1,399 @@
+# Toast
+
+Imperative notification API with a companion `Toaster` container and a compound `Toast` component for fully custom layouts. It supports semantic variants, custom icons, auto-closing actions, and multiple containers.
+
+## Import
+
+```tsx
+import { Toast, Toaster, toast } from '@redislabsdev/redis-ui-components';
+```
+
+> The icon examples use:
+> ```tsx
+> import { ShardIcon } from '@redislabsdev/redis-ui-icons';
+> ```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| message | `ReactNode` | - | Main toast message content. |
+| description | `ReactNode` | - | Supporting text rendered under the message. |
+| actions | `{ primary?: ToastActionType; secondary?: ToastActionType }` | - | Primary and secondary action button configs. |
+| customIcon | `IconType` | - | Overrides the default semantic icon. |
+| showIcon | `boolean` | `true` | Shows or hides the leading icon. |
+| showCloseButton | `boolean` | `true` | Shows or hides the close button. |
+| compose wrapper props | `ChildFree<ComposeElementProps>` | - | Additional container props forwarded to the composed toast root. |
+
+The root `Toast` component also accepts the same content props as `toast(...)` and forwards them to `Toast.Compose`.
+
+## Sub-components
+
+- `Toast.Compose` - Semantic container for fully custom toast layouts.
+- `Toast.Icon` - Variant-aware icon slot for composed toasts.
+- `Toast.Message` - Message wrapper used when composing a toast body.
+- `Toast.Description` - Description wrapper used when composing a toast body.
+- `Toast.Content` - Default content block that renders the message and description slots.
+- `Toast.Content.Compose` - Low-level content container for custom body layouts.
+- `Toast.Content.Message` - Low-level message slot used inside content compositions.
+- `Toast.Content.Description` - Low-level description slot used inside content compositions.
+- `Toast.Actions` - Default action block that renders primary and secondary actions.
+- `Toast.Actions.Compose` - Low-level action container for custom action layouts.
+- `Toast.Actions.Action` - Action button primitive used in custom action layouts.
+- `Toast.CloseButton` - Close button primitive that dismisses the toast.
+
+### Toast.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `ToastVariant` | current toast variant | Semantic variant inherited from the toast context. |
+| size | `SemanticContainerSize` | `M` | Toast container size. |
+| compose wrapper props | `ComposeElementProps` | - | Additional props forwarded to the toast compose container. |
+
+### Toast.Icon Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `IconType` | - | Optional custom icon component. |
+| icon props | `MonochromeIconProps` | `size="M"` | Additional monochrome icon props, such as custom color and size. |
+
+### Toast.Message Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| body props | `TypographyBodyProps` | - | Typography body props forwarded to the message slot. |
+
+### Toast.Description Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| body props | `TypographyBodyProps` | - | Typography body props forwarded to the description slot. |
+
+### Toast.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| message | `ReactNode` | - | Message content shown in the toast body. |
+| description | `ReactNode` | - | Supporting text shown under the message. |
+| compose wrapper props | `ChildFree<ComposeElementProps>` | - | Additional props forwarded to the content container. |
+
+`Toast.Content` also exposes `Compose`, `Message`, and `Description` for custom body layouts.
+
+### Toast.Actions Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| primary | `ToastActionType` | - | Primary action button configuration. |
+| secondary | `ToastActionType` | - | Secondary action button configuration. |
+| compose wrapper props | `ChildFree<ComposeElementProps>` | - | Additional props forwarded to the actions container. |
+
+`Toast.Actions` also exposes `Compose` and `Action` for custom action layouts.
+
+### Toast.Actions.Action Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` | required | Action label. |
+| onClick | `VoidFunction` | required | Action handler. |
+| icon | `IconType` | - | Optional leading icon. |
+| closes | `boolean` | `false` | Closes the toast after the handler runs. |
+| variant | `SemanticOutlineVariant` | - | Outline variant used by the underlying semantic button. |
+| disabled | `boolean` | `false` | Disables the action button. |
+| button props | `RestSemanticButtonProps` | - | Additional native button props. |
+
+### Toast.CloseButton Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | `SemanticSize` | - | Close button size. |
+| variant | `SemanticVariant` | - | Semantic variant used for styling. |
+| button props | `RestSemanticCloseButtonProps` | - | Additional native button props. |
+
+`Toast.CloseButton` falls back to the default `CancelIcon` when no children are provided.
+
+## Examples
+
+### BasicToast
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+toast('Basic simple toast');
+```
+
+### Playground
+
+```tsx
+import { toast, ToastContentParams, ToastOptions } from '@redislabsdev/redis-ui-components';
+import { unflatten } from '../../helpers/unflatten';
+
+function launchToast(args: Record<string, unknown>) {
+  const { message, description, actions, customIcon, showIcon, showCloseButton, ...rest } =
+    unflatten(args) as ToastContentParams & ToastOptions;
+
+  rest.autoClose = rest.autoClose !== false && rest['autoClose (delay)'];
+
+  toast({ message, description, actions, customIcon, showIcon, showCloseButton }, rest);
+}
+```
+
+### SemanticToasts
+
+> We support a few different semantic variants of toasts.
+
+```tsx
+import { toast, ToastVariant } from '@redislabsdev/redis-ui-components';
+
+const semanticVariants: Exclude<ToastVariant, 'informative'>[] = [
+  'danger',
+  'attention',
+  'notice',
+  'success'
+];
+
+semanticVariants.forEach((variant) => {
+  toast[variant]({
+    message: (
+      <>
+        This is <strong>{variant}</strong> toast
+      </>
+    )
+  });
+});
+```
+
+### ToastUpdate
+
+> If you need to apply new content to an existing toast or change some options, call `toast.update` with the toast id and new parameters. Changed values will be applied over previous values. You cannot reset a value without setting the new one.
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+const toastId = toast('Default toast');
+
+toast.update(toastId, 'Updated toast, same variant', { role: 'status' });
+toast.update(toastId, 'Updated toast, variant is Danger', {
+  variant: toast.Variant.Danger
+});
+```
+
+### MessageAndDescription
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+toast.notice({
+  message: 'This is toast message',
+  description: 'with description'
+});
+```
+
+### MessageOnly
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+toast.notice({
+  message: 'This toast has only message'
+});
+```
+
+### DescriptionOnly
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+toast.notice({
+  description: 'This toast has only description'
+});
+```
+
+### ContentFormatting
+
+> Content parts can contain any JSX elements.
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+toast.notice({
+  message: (
+    <>
+      This is toast with <i>formatted</i> <strong>content</strong>
+    </>
+  ),
+  description: (
+    <>
+      It supports single line or paragraph content with{' '}
+      <u style={{ color: 'green' }}>custom styling</u>
+    </>
+  )
+});
+```
+
+### Actions
+
+> Each Toast can contain two independent action buttons: primary and secondary. Each of them can be added to the toast or omitted.
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+const onClick = () => {};
+
+toast.notice({
+  message: 'Toast with actions',
+  actions: {
+    primary: { label: 'Action 1', onClick },
+    secondary: { label: 'Action 2', onClick }
+  }
+});
+```
+
+### AutoClosingActions
+
+> Each Toast Action allows you to close the toast automatically after performing the action. Use the `closes` flag to enable it.
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+const onClick = () => {};
+
+toast.notice({
+  message: 'Toast with actions',
+  actions: {
+    primary: { label: 'Closing', onClick, closes: true },
+    secondary: { label: 'Non-closing', onClick, closes: false }
+  }
+});
+```
+
+### CustomIcon
+
+> Toast can have a custom icon. Use the `customIcon` property to specify it.
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+import { ShardIcon } from '@redislabsdev/redis-ui-icons';
+
+toast.danger({ message: 'Toast with custom icon', customIcon: ShardIcon });
+```
+
+### InvisibleIcon
+
+> Icon of the toast can be hidden. Use `showIcon = false` to hide it.
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+toast.success({ message: 'Toast without icon', showIcon: false });
+```
+
+### CloseButton
+
+> Close button of the toast can be hidden. Use `showCloseButton = false` to hide it.
+
+```tsx
+import { toast } from '@redislabsdev/redis-ui-components';
+
+toast.notice({ message: 'Toast without close button', showCloseButton: false });
+```
+
+### ComponentContent
+
+> Toast can be specified as a React element. Note that the React element must implement the entire toast, not just its content. The `Toast` component is designed to simplify that.
+
+```tsx
+import { Toast, toast } from '@redislabsdev/redis-ui-components';
+
+toast.success(
+  <Toast
+    message="React component toast"
+    description="This toast is built using <Toast/> component instance"
+  />
+);
+```
+
+### CompositionContent
+
+> Toast component can be composed using the `Toast.Compose` element. Pass the composed element as the content parameter.
+
+```tsx
+import { Toast, toast } from '@redislabsdev/redis-ui-components';
+import { ShardIcon } from '@redislabsdev/redis-ui-icons';
+
+toast(
+  <Toast.Compose style={{ backgroundColor: '#80ecf0a8', borderColor: '#a6d7d9', color: '#0a585b' }}>
+    <Toast.Icon icon={ShardIcon} customColor="#00999f" />
+    <Toast.Message>
+      This toast composed using custom icon and message with overridden style
+    </Toast.Message>
+  </Toast.Compose>
+);
+```
+
+### HiddenToaster
+
+```tsx
+import { Toaster } from '@redislabsdev/redis-ui-components';
+
+<Toaster autoClose={10000} position="top-center" className="sb-unstyled" />
+```
+
+### MultipleContainers
+
+> Multiple toast containers can be used simultaneously by providing a unique `containerId` to each `Toaster`. Toasts can be directed to specific containers by passing the same `containerId` in toast options.
+>
+> In react-toastify v10, the `enableMultiContainer` prop is no longer needed. Multi-container support works automatically when `containerId` is provided.
+
+```tsx
+import { Button, toast, Toaster } from '@redislabsdev/redis-ui-components';
+
+<div style={{ minHeight: '300px' }}>
+  <Toaster containerId="notifications" position="top-right" autoClose={5000} className="sb-unstyled" />
+  <Toaster containerId="alerts" position="bottom-left" autoClose={false} className="sb-unstyled" />
+
+  <Button
+    onClick={() =>
+      toast.success({ message: 'Operation completed successfully!' }, { containerId: 'notifications' })
+    }
+  >
+    Success (top-right)
+  </Button>
+  <Button
+    onClick={() =>
+      toast.notice({ message: 'Here is some information' }, { containerId: 'notifications' })
+    }
+  >
+    Info (top-right)
+  </Button>
+  <Button
+    onClick={() =>
+      toast.danger(
+        { message: 'An error occurred', description: 'Please check your input and try again' },
+        { containerId: 'alerts' }
+      )
+    }
+  >
+    Error (bottom-left)
+  </Button>
+  <Button
+    onClick={() =>
+      toast.attention(
+        { message: 'Warning', description: 'This action cannot be undone' },
+        { containerId: 'alerts' }
+      )
+    }
+  >
+    Warning (bottom-left)
+  </Button>
+</div>
+```
+
+## Notes
+
+- Mount `Toaster` once per app, and use `containerId` when you need multiple containers.
+- `toast` exposes semantic helper methods and enums, including `notice`, `attention`, `danger`, `success`, `Variant`, and `Position`.
+- `toast.update` applies new values over the existing toast state; it does not reset fields back to defaults.
+- `showIcon` and `showCloseButton` only hide the toast chrome; the toast content still renders.
+- `Toast.Compose` is the escape hatch for fully custom toast layouts.
+- `Toast.Message` and `Toast.Description` can render any JSX, not just strings.
+- `Toast.Actions.Action` can auto-close the toast when `closes` is set to `true`.

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

@@ -0,0 +1,163 @@
+# ToggleButton
+
+A button with two stable states: regular and pressed. It supports both controlled and uncontrolled usage, can show a count indicator, and can render icons inside the button content.
+
+## Import
+
+```tsx
+import { ToggleButton } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `pressed` | `boolean` | - | Controlled pressed state |
+| `defaultPressed` | `boolean` | - | Initial pressed state for uncontrolled usage |
+| `onPressedChange` | `(pressed: boolean) => void` | - | Called when the pressed state changes |
+| `onClick` | `(pressed: boolean) => void` | - | Deprecated alias for `onPressedChange` |
+| `children` | `React.ReactNode` | - | Button content |
+| `disabled` | `boolean` | `false` | Whether the button is disabled |
+
+The component also extends all native `ButtonHTMLAttributes<HTMLButtonElement>` props, except `onClick` which is re-typed to receive the pressed state.
+
+## Sub-components
+
+- `ToggleButton.IndicatorCount` - Renders a numeric badge inside the toggle button and clamps values above 999 to `999+`.
+
+### ToggleButton.IndicatorCount Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `count` | `number` | *required* | Count value to display |
+
+The component also extends all `Typography.Body` props except `children`.
+
+## Examples
+
+### Playground
+
+```tsx
+import { ToggleButton } from '@redislabsdev/redis-ui-components';
+
+<ToggleButton disabled={false}>Toggle Button</ToggleButton>
+```
+
+### DefaultPressed
+
+> Pressed state can be initially set by using `defaultPressed` prop.
+
+```tsx
+import { ToggleButton } from '@redislabsdev/redis-ui-components';
+
+<ToggleButton defaultPressed>Initially pressed</ToggleButton>
+```
+
+### Controlled
+
+> Toggle button state can be controlled.
+> Use `pressed` and `onPressedChange` props to control it.
+
+```tsx
+import { useState } from 'react';
+import { Button, ToggleButton } from '@redislabsdev/redis-ui-components';
+
+const [pressed, setPressed] = useState(false);
+
+<>
+  <Button onClick={() => setPressed(false)}>Set `pressed=false`</Button>
+  <Button onClick={() => setPressed(true)}>Set `pressed=true`</Button>
+  <ToggleButton pressed={pressed} onPressedChange={setPressed}>
+    Controlled Toggle Button
+  </ToggleButton>
+</>
+```
+
+### 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 { ToggleButton } from '@redislabsdev/redis-ui-components';
+
+<>
+  <ToggleButton disabled>Disabled</ToggleButton>
+  <ToggleButton disabled defaultPressed>
+    Pressed - Disabled
+  </ToggleButton>
+</>
+```
+
+### WithCountIndicator
+
+> To add count indicator to a ToggleButton, use the `ToggleButton.IndicatorCount` component.
+> This component can be placed anywhere inside the `ToggleButton` component.
+
+```tsx
+import { ToggleButton } from '@redislabsdev/redis-ui-components';
+
+<>
+  <ToggleButton>
+    Button
+    <ToggleButton.IndicatorCount count={1} />
+  </ToggleButton>
+  <ToggleButton>
+    <ToggleButton.IndicatorCount count={10} />
+    Button
+  </ToggleButton>
+  <ToggleButton>
+    Button
+    <ToggleButton.IndicatorCount count={100} />
+  </ToggleButton>
+  <ToggleButton>
+    Button
+    <ToggleButton.IndicatorCount count={1000} />
+  </ToggleButton>
+</>
+```
+
+### WithIcon
+
+> To add an icon to a ToggleButton, use the `Button.Icon` component.
+> This component can be placed anywhere inside the `ToggleButton` component.
+> It will automatically be sized and colored to match its parent ToggleButton.
+>
+> Do not use this component if you need a round icon-only Button. Instead,
+> use the IconButton or ActionIconButton components.
+>
+> If you need to pass props to the icon element you should declare it as a separate component.
+>
+> Do not declare components inside other components (like an inline arrow function or any other way),
+> or at least wrap them in `useMemo`,
+> otherwise it will cause re-render of the element on every render of the parent component.
+
+```tsx
+import { ToggleButton, Button } from '@redislabsdev/redis-ui-components';
+import { ChevronDownIcon, ContractIcon, MarketplaceIcon } from '@redislabsdev/redis-ui-icons';
+
+<>
+  <ToggleButton>
+    <Button.Icon icon={ContractIcon} />
+    Left Icon
+  </ToggleButton>
+  <ToggleButton>
+    Right Icon
+    <Button.Icon icon={MarketplaceIcon} />
+  </ToggleButton>
+  <ToggleButton>
+    Icon & Indicator
+    <ToggleButton.IndicatorCount count={1} />
+    <Button.Icon customSize="1rem" icon={ChevronDownIcon} />
+  </ToggleButton>
+</>
+```
+
+## Notes
+
+- `ToggleButton` supports both uncontrolled mode with `defaultPressed` and controlled mode with `pressed` plus `onPressedChange`.
+- `onClick` is deprecated; use `onPressedChange` instead.
+- `ToggleButton.IndicatorCount` can be placed anywhere inside the toggle button.
+- Values above `999` render as `999+`.
+- For icon-only round buttons, use `IconButton` or `ActionIconButton` instead of `Button.Icon`.
+- The component forwards refs to the underlying `<button>` element.