@redis-ui/components 43.0.2 → 43.2.1

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

@@ -0,0 +1,563 @@
+# Banner
+
+Semantic banner and strip component with automatic icon, message, action, and close-button composition. It also exposes a lower-level `Banner.Compose` surface for custom layouts.
+
+## Import
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+```
+
+> Icons used in examples are imported separately from `@redislabsdev/redis-ui-icons`.
+
+## Props
+
+### Banner
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| show | `boolean` | `true` | Controls whether the banner renders at all |
+| onClose | `VoidFunction` | - | Close callback passed to the compose surface and close actions |
+| variant | `'informative' \| 'notice' \| 'danger' \| 'attention' \| 'success'` | `informative` | Semantic banner variant |
+| size | `'M' \| 'S'` | `M` | Banner density |
+| layoutVariant | `'banner' \| 'strip'` | `banner` | Full banner or strip layout |
+| message | `ReactNode` | - | Message content displayed by the banner |
+| actions | `{ primary?: BannerActionType; secondary?: BannerActionType }` | - | Primary and secondary action descriptors |
+| customIcon | `IconType` | - | Custom icon rendered instead of the semantic icon |
+| showIcon | `boolean` | `true` | Shows or hides the leading icon |
+| showCloseButton | `boolean` | `!!onClose` | Shows or hides the close button |
+
+The root banner forwards standard `div` attributes through the compose container.
+
+### Banner.Compose
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | required | Composed banner contents |
+| variant | `'informative' \| 'notice' \| 'danger' \| 'attention' \| 'success'` | `informative` | Semantic banner variant for the container |
+| size | `'M' \| 'S'` | `M` | Banner density for composed children |
+| layoutVariant | `'banner' \| 'strip'` | `banner` | Container layout variant |
+| onClose | `VoidFunction` | - | Close callback shared through banner context |
+
+`Banner.Compose` accepts standard `div` attributes.
+
+### Banner.Actions
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| primary | `BannerActionType` | - | Primary action descriptor |
+| secondary | `BannerActionType` | - | Secondary action descriptor |
+
+`Banner.Actions` accepts standard `div` attributes and renders nothing when both actions are missing.
+
+### Banner.Actions.Compose
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | required | Custom action-row contents |
+
+`Banner.Actions.Compose` accepts standard `div` attributes.
+
+### Banner.Actions.Action
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` | required | Action label text |
+| onClick | `VoidFunction` | required | Action callback |
+| closes | `boolean` | `false` | Closes the banner after the action runs |
+| icon | `IconType` | - | Optional icon shown before the label |
+| variant | `'primary' \| 'secondary'` | `primary` | Outline style for the action button |
+| size | `'M' \| 'S'` | `M` | Action button density |
+| disabled | `boolean` | `false` | Disables the action button |
+
+`Banner.Actions.Action` accepts standard `button` attributes.
+
+### Banner.Icon
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `'informative' \| 'notice' \| 'danger' \| 'attention' \| 'success'` | `informative` | Semantic icon variant |
+| customIcon | `IconType` | - | Custom icon override |
+
+`Banner.Icon` also inherits `MonochromeIconProps` from `@redislabsdev/redis-ui-icons`.
+
+### Banner.Message
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | required | Message content |
+
+`Banner.Message` inherits `Typography.Body` props.
+
+### Banner.CloseButton
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | `'M' \| 'S'` | `M` | Close icon size inherited through banner context |
+| variant | `'informative' \| 'notice' \| 'danger' \| 'attention' \| 'success'` | `informative` | Semantic color variant inherited through banner context |
+
+`Banner.CloseButton` accepts standard `button` attributes.
+
+### Banner.Split
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| minWidth | `string \| number \| undefined` | - | Minimum width for the split spacer |
+
+`Banner.Split` accepts standard `div` attributes.
+
+## Sub-components
+
+- `Banner.Compose` - Low-level banner container used for custom composition.
+- `Banner.Icon` - Semantic banner icon wrapper with optional custom icon.
+- `Banner.Message` - Message content wrapper for banner text.
+- `Banner.Actions` - Default action row wrapper for primary and secondary actions.
+- `Banner.Actions.Compose` - Low-level action-row container for fully custom action layouts.
+- `Banner.Actions.Action` - Semantic action button used inside `Banner.Actions.Compose`.
+- `Banner.CloseButton` - Close button alias that uses banner context.
+- `Banner.Split` - Spacer/split element between the banner message and actions.
+
+## Examples
+
+### Playground
+
+```tsx
+import { Banner, BannerProps } from '@redislabsdev/redis-ui-components';
+import { unflatten } from '../../helpers/unflatten';
+
+const handleClose = () => {};
+const handleClick = () => {};
+
+function Render(args: unknown) {
+  const props = unflatten(args) as BannerProps;
+
+  if (props.actions?.primary) {
+    props.actions.primary.onClick = handleClick;
+  }
+
+  if (props.actions?.secondary) {
+    props.actions.secondary.onClick = handleClick;
+  }
+
+  return <Banner {...props} onClose={handleClose} />;
+}
+```
+
+### BasicBanner
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Banner message="Basic banner" />
+  <Banner layoutVariant="strip" message="Basic banner strip" />
+</>
+```
+
+### SemanticBanners
+
+> We support a few different semantic variants of banners.
+
+```tsx
+import { Banner, BannerVariant, bannerVariants } from '@redislabsdev/redis-ui-components';
+import { PhoneIcon } from '@redislabsdev/redis-ui-icons';
+
+const handleClose = () => {};
+const handleClick = () => {};
+
+const restOfBannerProps = {
+  onClose: handleClose,
+  actions: {
+    primary: {
+      label: 'Primary',
+      onClick: handleClick,
+      icon: PhoneIcon
+    },
+    secondary: {
+      label: 'Secondary',
+      onClick: handleClick
+    }
+  }
+};
+
+const renderSemanticBanner = (variant: BannerVariant, idx: number) => (
+  <Banner
+    key={idx}
+    variant={variant}
+    message={
+      <>
+        variant = <strong>&quot;{variant}&quot;</strong>
+      </>
+    }
+    {...restOfBannerProps}
+  />
+);
+
+<>
+  {bannerVariants.map(renderSemanticBanner)}
+</>
+```
+
+### SemanticStrips
+
+> We support a few different semantic variants of banner strips.
+
+```tsx
+import { Banner, BannerVariant, bannerVariants } from '@redislabsdev/redis-ui-components';
+import { PhoneIcon } from '@redislabsdev/redis-ui-icons';
+
+const handleClose = () => {};
+const handleClick = () => {};
+
+const restOfBannerProps = {
+  onClose: handleClose,
+  actions: {
+    primary: {
+      label: 'Primary',
+      onClick: handleClick,
+      icon: PhoneIcon
+    },
+    secondary: {
+      label: 'Secondary',
+      onClick: handleClick
+    }
+  }
+};
+
+const renderSemanticBanner = (variant: BannerVariant, idx: number) => (
+  <Banner
+    key={idx}
+    variant={variant}
+    layoutVariant="strip"
+    message={
+      <>
+        variant = <strong>&quot;{variant}&quot;</strong>
+      </>
+    }
+    {...restOfBannerProps}
+  />
+);
+
+<>
+  {bannerVariants.map(renderSemanticBanner)}
+</>
+```
+
+### BannerSize
+
+> Banner can be one of the following sizes
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+
+const handleClose = () => {};
+const handleClick = () => {};
+
+const restOfBannerProps = {
+  onClose: handleClose,
+  actions: {
+    primary: {
+      label: 'Primary',
+      onClick: handleClick
+    },
+    secondary: {
+      label: 'Secondary',
+      onClick: handleClick
+    }
+  }
+};
+
+<>
+  <Banner message="Medium Banner (size='M')" size="M" {...restOfBannerProps} />
+  <Banner message="Small Banner (size='S')" size="S" {...restOfBannerProps} />
+  <Banner message="Default size Banner strip" layoutVariant="strip" {...restOfBannerProps} />
+</>
+```
+
+### MessageFormatting
+
+> Message can contain any JSX elements
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+
+const handleClose = () => {};
+
+<>
+  <Banner message="Simple text message" />
+  <Banner
+    variant="notice"
+    message={
+      <>
+        <strong>JSX formatted</strong> <em style={{ color: 'limegreen' }}>message</em>
+      </>
+    }
+  />
+  <Banner
+    variant="attention"
+    message={
+      <>
+        This message is
+        <br />
+        forced multiline
+      </>
+    }
+    onClose={handleClose}
+  />
+  <Banner
+    layoutVariant="strip"
+    variant="notice"
+    message={
+      <>
+        <strong>JSX formatted</strong> <em style={{ color: 'limegreen' }}>message</em>
+      </>
+    }
+  />
+  <Banner
+    layoutVariant="strip"
+    variant="attention"
+    message={
+      <>
+        This message is
+        <br />
+        forced multiline
+      </>
+    }
+    onClose={handleClose}
+  />
+</>
+```
+
+### Actions
+
+> Each Banner can contain two independent action buttons: primary and secondary. Each of them can be added separately.
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+
+const handleClick = () => {};
+
+<>
+  <Banner
+    message="Banner with both actions"
+    actions={{
+      primary: { label: 'Primary Action', onClick: handleClick },
+      secondary: { label: 'Secondary Action', onClick: handleClick }
+    }}
+  />
+  <Banner
+    message="Banner with Primary action"
+    actions={{
+      primary: { label: 'Primary Action', onClick: handleClick }
+    }}
+  />
+  <Banner
+    message="Banner with Secondary action"
+    actions={{
+      secondary: { label: 'Secondary Action', onClick: handleClick }
+    }}
+  />
+  <Banner
+    layoutVariant="strip"
+    message="Banner strip with actions"
+    actions={{
+      primary: { label: 'Primary Action', onClick: handleClick },
+      secondary: { label: 'Secondary Action', onClick: handleClick }
+    }}
+  />
+</>
+```
+
+### AutoClosingActions
+
+> Each Banner Action allows to close banner automatically after performing the action. Use `closes` flag of the action to enable it.
+>
+> `onClose` handler should be specified to perform the close operation.
+>
+> If necessary, the close button can be hidden by setting `showCloseButton={false}`.
+
+```tsx
+import { useState } from 'react';
+import { Banner, Button } from '@redislabsdev/redis-ui-components';
+
+const handleClick = () => {};
+
+function Render() {
+  const [show, setShow] = useState(true);
+
+  return (
+    <>
+      {show || (
+        <Button onClick={() => setShow(!show)} style={{ minHeight: 42 }}>
+          Show Banner
+        </Button>
+      )}
+      <Banner
+        show={show}
+        message="Auto-closing Actions"
+        actions={{
+          primary: { label: 'Close 1', onClick: handleClick, closes: true },
+          secondary: { label: 'Close 2', onClick: handleClick, closes: true }
+        }}
+        onClose={() => setShow(false)}
+      />
+    </>
+  );
+}
+```
+
+### CustomIcon
+
+> Banner can have custom icon. Use `customIcon` property to specify it.
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+import { ShardIcon } from '@redislabsdev/redis-ui-icons';
+
+<>
+  <Banner message="Banner with custom icon" customIcon={ShardIcon} />
+  <Banner layoutVariant="strip" message="Banner strip with custom icon" customIcon={ShardIcon} />
+</>
+```
+
+### InvisibleIcon
+
+> Icon of the banner can be hidden. Use `showIcon = false` to hide it.
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+
+<>
+  <Banner message="Banner without icon" showIcon={false} />
+  <Banner layoutVariant="strip" message="Banner strip without icon" showIcon={false} />
+</>
+```
+
+### CloseButton
+
+> To show the close button, `onClose` handler should be specified.
+>
+> The close button can be forced to be hidden, even if a close handler is specified. Use `showCloseButton={false}` to hide it.
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+
+const handleClose = () => {};
+const handleClick = () => {};
+
+<>
+  <Banner message="Banner with close button" onClose={handleClose} />
+  <Banner
+    message="Banner with forcibly hidden close button"
+    onClose={handleClose}
+    showCloseButton={false}
+    actions={{ secondary: { label: 'Save and Close', onClick: handleClick, closes: true } }}
+  />
+  <Banner layoutVariant="strip" message="Banner strip with close button" onClose={handleClose} />
+  <Banner
+    layoutVariant="strip"
+    message="Banner strip with forcibly hidden close button"
+    onClose={handleClose}
+    showCloseButton={false}
+    actions={{ secondary: { label: 'Save and Close', onClick: handleClick, closes: true } }}
+  />
+</>
+```
+
+### ForceBannerWidth
+
+> If the banner or strip is narrower than the content, it can wrap long message text.
+>
+> If the banner is stretched, it may leave space to the right of the short text. The strip always centers the entire content.
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+
+const handleClose = () => {};
+const handleClick = () => {};
+
+<>
+  <Banner message="Short msg" style={{ width: '100%' }} />
+  <Banner
+    message="Short msg"
+    actions={{ secondary: { label: 'Action', onClick: handleClick } }}
+    style={{ width: 'auto' }}
+  />
+  <Banner
+    onClose={handleClose}
+    message="Very very very very very very very very long message is wrapping"
+    actions={{ secondary: { label: 'Action', onClick: handleClick } }}
+    style={{ width: 'auto' }}
+  />
+  <Banner layoutVariant="strip" message="Short msg" />
+  <Banner
+    layoutVariant="strip"
+    message="Short msg"
+    actions={{ secondary: { label: 'Action', onClick: handleClick } }}
+  />
+  <Banner
+    layoutVariant="strip"
+    onClose={handleClose}
+    message="Very very very very very very very very long message is wrapping"
+    actions={{ secondary: { label: 'Action', onClick: handleClick } }}
+  />
+</>
+```
+
+### CompositionWithStyling
+
+> Banner can be custom composed by using `Banner.Compose` as the root element. Composition elements can be styled.
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+import { ShardIcon } from '@redislabsdev/redis-ui-icons';
+
+<Banner.Compose
+  style={{ backgroundColor: '#80ecf0a8', borderColor: '#a6d7d9', color: '#0a585b' }}
+>
+  <Banner.Icon customIcon={ShardIcon} customColor="#00999f" />
+  <Banner.Message>
+    This banner composed using custom icon and message with overridden style
+  </Banner.Message>
+</Banner.Compose>
+```
+
+### CompositionOfActions
+
+> Actions have their own composition. Use `Banner.Actions.Compose` and `Banner.Actions.Action`.
+
+```tsx
+import { Banner } from '@redislabsdev/redis-ui-components';
+import { ShardIcon, StarsIcon } from '@redislabsdev/redis-ui-icons';
+
+const handleClose = () => {};
+const handleClick = () => {};
+
+<Banner.Compose variant="success" size="S" onClose={handleClose}>
+  <Banner.Icon customIcon={StarsIcon} />
+  <Banner.Message>Message text</Banner.Message>
+  <Banner.Split />
+  <Banner.Actions.Compose>
+    <Banner.Actions.Action
+      label="Primary"
+      icon={ShardIcon}
+      closes
+      variant="primary"
+      onClick={handleClick}
+    />
+    <Banner.Actions.Action label="Other" variant="secondary" onClick={handleClick} />
+  </Banner.Actions.Compose>
+  <Banner.CloseButton />
+</Banner.Compose>
+```
+
+## Notes
+
+- Banner semantic variants are `informative`, `notice`, `danger`, `attention`, and `success`.
+- `showIcon={false}` hides the leading icon.
+- `showCloseButton={false}` hides the close button even when `onClose` is provided.
+- Action descriptors can auto-close the banner when `closes` is set, but `onClose` must be available for the close behavior to run.
+- Banner and strip layouts wrap long content; strips center the entire content.
+- `Banner.Compose` is the right entry point for custom layouts and can be styled directly.
+- `Banner.Actions.Compose` and `Banner.Actions.Action` expose the extended action composition surface.
+- Banner message content can contain any JSX.