@redis-ui/components 42.8.0 → 43.2.1

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

@@ -0,0 +1,468 @@
+# SideBar
+
+Collapsible sidebar navigation with a header toggle, grouped items, scrollable middle content, and a footer area. The component is designed as a compound API so the header, items, splitters, and footer pieces can be composed as needed.
+
+## Import
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| isExpanded | `boolean` | *required* | Controls whether the sidebar is expanded or collapsed |
+
+The component also accepts all `FlexGroupProps` except `direction`, which is fixed to a vertical sidebar layout.
+
+## Sub-components
+
+- `SideBar.SideBarLogo` - Renders the logo icon used inside the sidebar header.
+- `SideBar.Header` - Header row with the expand/collapse toggle button and accessibility announcement.
+- `SideBar.ItemsContainer` - Column container for sidebar items.
+- `SideBar.ScrollContainer` - Flexible scrollable container for sidebar content.
+- `SideBar.Split` - Flexible spacer used to distribute remaining vertical space.
+- `SideBar.Divider` - Visual separator line.
+- `SideBar.Button` - Root collapsible action button shown in the sidebar.
+- `SideBar.Item` - Navigation item with tooltip support when collapsed.
+- `SideBar.Item.Icon` - Icon slot for a sidebar item.
+- `SideBar.Item.Text` - Text slot for a sidebar item.
+- `SideBar.Item.Button` - Compact action button that is shown only when the sidebar is expanded.
+- `SideBar.Footer` - Footer wrapper for metadata, links, and text.
+- `SideBar.Footer.MetaData` - Footer metadata container.
+- `SideBar.Footer.Link` - Footer link rendered as body text.
+- `SideBar.Footer.Text` - Small footer text.
+
+### SideBar.Header Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| onToggle | `() => void` | *required* | Called when the header toggle button is pressed |
+
+The header also accepts standard `HTMLAttributes<HTMLDivElement>`.
+
+### SideBar.SideBarLogo Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| logoIcon | `IconType` | *required* | Logo icon rendered inside the header |
+
+The logo also accepts standard `HTMLAttributes<HTMLSpanElement>` except `children`.
+
+### SideBar.ItemsContainer Props
+
+This component inherits `FlexGroupProps` except `direction`. It renders a column list container with `gap="0"`, `flex="none"`, and `selfAlign="stretch"`.
+
+### SideBar.ScrollContainer Props
+
+This component inherits `FlexGroupProps` except `direction`. It renders a flexible column container with `gap="0"`, `flex="1"`, and `selfAlign="stretch"`.
+
+### SideBar.Divider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| fullWidthWhenExpanded | `boolean` | - | Expands the divider to full width when the sidebar is expanded |
+| noMargin | `boolean` | - | Removes vertical margins |
+| fullWidth | `boolean` | - | Makes the divider span the full width |
+
+The divider also accepts standard `HTMLAttributes<HTMLDivElement>` except `children`.
+
+### SideBar.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| tooltipProps | `SideBarTooltipProps` | *required* | Tooltip configuration used when the sidebar is collapsed |
+| isActive | `boolean` | `false` | Marks the item as the active route/item |
+
+The item also accepts standard `HTMLAttributes<HTMLLIElement>`.
+The tooltip text is used as the collapsed label and tooltip placement defaults to `right`.
+
+### SideBar.Item.Icon Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `IconType` | *required* | Icon rendered inside the item |
+
+### SideBar.Item.Text Props
+
+This slot inherits `TypographyBodyProps`. It renders a `Typography.Body` element with `component="span"`, `ellipsis`, and `tooltipOnEllipsis` enabled.
+
+### SideBar.Item.Button Props
+
+This slot inherits all `ActionIconButtonProps`, defaults `size` to `M`, and renders only while the sidebar is expanded.
+
+### SideBar.Button Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| tooltipProps | `SideBarTooltipProps` | *required* | Tooltip configuration used when the sidebar is collapsed |
+| buttonExpandedContent | `React.ReactNode` | *required* | Content displayed while the sidebar is expanded |
+| buttonCollapsedIcon | `IconType` | `PlusIcon` | Icon shown while the sidebar is collapsed |
+
+The root button also inherits all `ButtonProps` from the base `Button` component.
+The tooltip text is used as the collapsed label and tooltip placement defaults to `right`.
+
+### SideBar.Footer Props
+
+This footer wrapper inherits `ComposeElementProps`.
+
+### SideBar.Footer.MetaData Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | *required* | Footer metadata content |
+
+The metadata container also accepts standard `HTMLAttributes<HTMLDivElement>` except `children`.
+
+### SideBar.Footer.Link Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | *required* | Footer link text |
+
+The link also accepts standard `AnchorHTMLAttributes<HTMLAnchorElement>` except `children`.
+
+### SideBar.Footer.Text Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | *required* | Footer text content |
+
+This slot inherits `TypographyBodyProps` except `children` and renders a small body-text footer line.
+
+## Examples
+
+### Playground
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { ShardIcon } from '@redislabsdev/redis-ui-icons';
+import { RedisIcon } from '@redislabsdev/redis-ui-icons/multicolor';
+import { useArgState } from '../../helpers/useArgState';
+
+const [expanded, onToggle] = useArgState({ arg: true, getNewState: (arg) => !arg });
+
+<SideBar isExpanded={expanded}>
+  <SideBar.Header onToggle={onToggle}>
+    <SideBar.SideBarLogo logoIcon={RedisIcon} />
+  </SideBar.Header>
+  <SideBar.Item tooltipProps={{ text: 'tooltip' }}>
+    <SideBar.Item.Icon icon={ShardIcon} />
+    <SideBar.Item.Text>Item Text</SideBar.Item.Text>
+  </SideBar.Item>
+  <SideBar.Divider fullWidth />
+  <SideBar.Footer>
+    <SideBar.Footer.MetaData>Footer</SideBar.Footer.MetaData>
+  </SideBar.Footer>
+</SideBar>
+```
+
+### ComplexBar
+
+> Complex example of application sidebar with most of the features.  
+> For details on the use of parts, please refer to the relevant documents.
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { PlusIcon } from '@redislabsdev/redis-ui-icons';
+import { useState } from 'react';
+import { RedisIcon } from '@redislabsdev/redis-ui-icons/multicolor';
+import { items } from './SideBar.data';
+
+const [expanded, setExpanded] = useState(true);
+const [activeLink, setActiveLink] = useState(items.top[0].content);
+
+<SideBar isExpanded={expanded} style={{ maxHeight: '55rem', height: 'calc(100vh - 2rem)' }}>
+  <SideBar.Header onToggle={() => setExpanded(!expanded)}>
+    <SideBar.SideBarLogo logoIcon={RedisIcon} />
+  </SideBar.Header>
+  <SideBar.ScrollContainer>
+    <SideBar.ItemsContainer>
+      {items.top.map((item) => (
+        <SideBar.Item
+          isActive={item.content === activeLink}
+          onClick={() => setActiveLink(item.content)}
+          key={item.content}
+          tooltipProps={{ text: item.content, placement: 'right' }}
+        >
+          <SideBar.Item.Icon icon={item.icon} />
+          <SideBar.Item.Text>{item.content}</SideBar.Item.Text>
+          {item.hasButton && (
+            <SideBar.Item.Button
+              icon={PlusIcon}
+              variant="primary"
+              onClick={(e) => {
+                e.stopPropagation();
+              }}
+              title="New database"
+            />
+          )}
+        </SideBar.Item>
+      ))}
+
+      <SideBar.Divider />
+
+      {items.middle.map((item) => (
+        <SideBar.Item
+          isActive={item.content === activeLink}
+          onClick={() => setActiveLink(item.content)}
+          key={item.content}
+          tooltipProps={{ text: item.content, placement: 'right' }}
+        >
+          <SideBar.Item.Icon icon={item.icon} />
+          <SideBar.Item.Text>{item.content}</SideBar.Item.Text>
+        </SideBar.Item>
+      ))}
+    </SideBar.ItemsContainer>
+    <SideBar.Split />
+    <SideBar.Divider fullWidth />
+    <SideBar.ItemsContainer>
+      {items.bottom.map((item) => (
+        <SideBar.Item
+          isActive={item.content === activeLink}
+          onClick={() => {
+            setActiveLink(item.content);
+          }}
+          key={item.content}
+          tooltipProps={{ text: item.content, placement: 'right' }}
+        >
+          <SideBar.Item.Icon icon={item.icon} />
+          <SideBar.Item.Text>{item.content}</SideBar.Item.Text>
+        </SideBar.Item>
+      ))}
+    </SideBar.ItemsContainer>
+  </SideBar.ScrollContainer>
+  <SideBar.Footer>
+    <SideBar.Divider fullWidth />
+    <SideBar.Footer.MetaData>
+      <div>
+        <SideBar.Footer.Link href="/" target="_blank">
+          Terms
+        </SideBar.Footer.Link>
+        {' | '}
+        <SideBar.Footer.Link>Privacy</SideBar.Footer.Link>
+      </div>
+      <SideBar.Footer.Text>© 2022 Redis</SideBar.Footer.Text>
+    </SideBar.Footer.MetaData>
+  </SideBar.Footer>
+</SideBar>
+```
+
+### HeaderAndFooter
+
+> `Header` includes toggle button and. Set `onToggle` handler to switch expanded state.  
+> Add `SideBar.SideBarLogo` icon to show it in the `Header`.
+>
+> `Footer` can have any custom content, but default is `Footer.MetaData` container
+> with optional `Footer.Link` and `Footer.Text` inside. Metadata is hidden in collapsed state.
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { useState } from 'react';
+import { RedisIcon } from '@redislabsdev/redis-ui-icons/multicolor';
+import { StoryHList } from '../../helpers/Story.style';
+
+const [expanded, setExpanded] = useState(true);
+
+const content = (
+  <>
+    <SideBar.Header onToggle={() => setExpanded((val) => !val)}>
+      <SideBar.SideBarLogo logoIcon={RedisIcon} />
+    </SideBar.Header>
+    <SideBar.Footer>
+      <SideBar.Footer.MetaData>
+        <SideBar.Footer.Link>SideBar.Footer.Link</SideBar.Footer.Link>
+        <SideBar.Footer.Text>SideBar.Footer.Text</SideBar.Footer.Text>
+      </SideBar.Footer.MetaData>
+    </SideBar.Footer>
+  </>
+);
+
+<StoryHList $gap="3rem">
+  <SideBar isExpanded={expanded}>{content}</SideBar>
+  <SideBar isExpanded={!expanded}>{content}</SideBar>
+</StoryHList>
+```
+
+### ScrollContainer
+
+> `ScrollContainer` allows to scroll necessary parts of the bar content,
+> when not enough vertical space.  
+> Regularly that are items between `Header` and `Footer`.  
+> Sometimes user can also want to include `Footer` to scrolling.
+>
+> It worth to use only one `ScrollContainer` in the bar.
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { StoryHList } from '../../helpers/Story.style';
+import { items } from './SideBar.data';
+
+const simpleItemRender = (item, i) => (
+  <SideBar.Item key={item.content} tooltipProps={{ text: item.content, placement: 'right' }} isActive={!i}>
+    <SideBar.Item.Icon icon={item.icon} />
+    <SideBar.Item.Text>{item.content}</SideBar.Item.Text>
+  </SideBar.Item>
+);
+
+<StoryHList $gap="3rem" $align="start">
+  <SideBar isExpanded style={{ height: '10rem' }}>
+    <SideBar.ScrollContainer>
+      <SideBar.ItemsContainer>{items.top.map(simpleItemRender)}</SideBar.ItemsContainer>
+    </SideBar.ScrollContainer>
+  </SideBar>
+  <SideBar isExpanded style={{ height: '30rem' }}>
+    <SideBar.ScrollContainer>
+      <SideBar.ItemsContainer>{items.top.map(simpleItemRender)}</SideBar.ItemsContainer>
+    </SideBar.ScrollContainer>
+  </SideBar>
+</StoryHList>
+```
+
+### SplitAndItemsContainer
+
+> When too much vertical space is in the bar and user want to align part of the bar to the bottom,
+> then `Split` can be used.  
+> If more than one `Split` is used, then all spaces are distributed equally.
+>
+> `Split` can be used under `SideBar` or under `ScrollContainer` without mixing.
+>
+> `ItemsContainer` simplifies grouping items and other elements.
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { StoryHList } from '../../helpers/Story.style';
+import { items } from './SideBar.data';
+
+const simpleItemRender = (item, i) => (
+  <SideBar.Item key={item.content} tooltipProps={{ text: item.content, placement: 'right' }} isActive={!i}>
+    <SideBar.Item.Icon icon={item.icon} />
+    <SideBar.Item.Text>{item.content}</SideBar.Item.Text>
+  </SideBar.Item>
+);
+
+<StoryHList $gap="3rem" $align="stretch" style={{ height: '40rem' }}>
+  <SideBar isExpanded>
+    <SideBar.ScrollContainer>
+      <SideBar.ItemsContainer>{items.top.map(simpleItemRender)}</SideBar.ItemsContainer>
+      <SideBar.Split />
+      <SideBar.ItemsContainer>{items.bottom.map(simpleItemRender)}</SideBar.ItemsContainer>
+    </SideBar.ScrollContainer>
+  </SideBar>
+  <SideBar isExpanded>
+    <SideBar.ItemsContainer>{items.top.slice(0, 2).map(simpleItemRender)}</SideBar.ItemsContainer>
+    <SideBar.Split />
+    <SideBar.ItemsContainer>{items.middle.map(simpleItemRender)}</SideBar.ItemsContainer>
+    <SideBar.Split />
+    <SideBar.ItemsContainer>{items.bottom.map(simpleItemRender)}</SideBar.ItemsContainer>
+  </SideBar>
+  <SideBar isExpanded>
+    <SideBar.ScrollContainer>
+      <SideBar.ItemsContainer>{items.top.map(simpleItemRender)}</SideBar.ItemsContainer>
+      <SideBar.ItemsContainer>{items.bottom.map(simpleItemRender)}</SideBar.ItemsContainer>
+    </SideBar.ScrollContainer>
+  </SideBar>
+</StoryHList>
+```
+
+### Button
+
+> Collapsible `Button` can be used instead of `Item`
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { ShardIcon } from '@redislabsdev/redis-ui-icons';
+import { StoryHList } from '../../helpers/Story.style';
+
+const button = (
+  <SideBar.Button
+    tooltipProps={{ text: 'Tooltip text' }}
+    buttonExpandedContent="Button text"
+    buttonCollapsedIcon={ShardIcon}
+  />
+);
+
+<StoryHList $gap="3rem">
+  <SideBar isExpanded>
+    <SideBar.Divider fullWidth />
+    {button}
+    <SideBar.Divider fullWidth />
+  </SideBar>
+  <SideBar isExpanded={false}>
+    <SideBar.Divider fullWidth />
+    {button}
+    <SideBar.Divider fullWidth />
+  </SideBar>
+</StoryHList>
+```
+
+### Divider
+
+> Collapsible `Divider` can have vertical margins and take full width
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { StoryHList } from '../../helpers/Story.style';
+
+const content = (
+  <>
+    <SideBar.Item tooltipProps={{}}>
+      <SideBar.Item.Text>No vertical margins:</SideBar.Item.Text>
+    </SideBar.Item>
+    <SideBar.Divider noMargin />
+    <SideBar.Item tooltipProps={{}}>
+      <SideBar.Item.Text>Side padding (default):</SideBar.Item.Text>
+    </SideBar.Item>
+    <SideBar.Divider />
+    <SideBar.Item tooltipProps={{}}>
+      <SideBar.Item.Text>Full width:</SideBar.Item.Text>
+    </SideBar.Item>
+    <SideBar.Divider fullWidth />
+    <SideBar.Item tooltipProps={{}}>
+      <SideBar.Item.Text>Full width if expanded:</SideBar.Item.Text>
+    </SideBar.Item>
+    <SideBar.Divider fullWidthWhenExpanded />
+  </>
+);
+
+<StoryHList $gap="3rem">
+  <SideBar isExpanded>{content}</SideBar>
+  <SideBar isExpanded={false}>{content}</SideBar>
+</StoryHList>
+```
+
+### Item Playground
+
+```tsx
+import { SideBar } from '@redislabsdev/redis-ui-components';
+import { PlusIcon, ShardIcon } from '@redislabsdev/redis-ui-icons';
+import { useState } from 'react';
+
+const [expanded, setExpanded] = useState(true);
+
+<SideBar isExpanded={expanded}>
+  <SideBar.Header onToggle={() => setExpanded((val) => !val)} />
+  <SideBar.Item tooltipProps={{ text: 'tooltip', placement: 'right' }} isActive={false}>
+    <SideBar.Item.Icon icon={ShardIcon} />
+    <SideBar.Item.Text>Item text</SideBar.Item.Text>
+    <SideBar.Item.Button
+      icon={PlusIcon}
+      onClick={(e) => e.stopPropagation()}
+      title="Plus button"
+    />
+  </SideBar.Item>
+</SideBar>
+```
+
+## Notes
+
+- `SideBar` is a collapsible navigation shell with a fixed header/footer layout and grouped content in the middle.
+- `SideBar.Header` needs an `onToggle` handler and should usually render `SideBar.SideBarLogo` inside it.
+- `SideBar.Footer` is typically used with `Footer.MetaData`; that metadata area is hidden when the sidebar is collapsed.
+- `SideBar.ScrollContainer` is intended for the middle content when vertical space is constrained, and the docs recommend using only one per sidebar.
+- `SideBar.Split` can be used either directly under `SideBar` or under `SideBar.ScrollContainer`, but the two patterns should not be mixed.
+- `SideBar.Divider` supports `noMargin`, `fullWidth`, and `fullWidthWhenExpanded` for layout tuning.
+- `SideBar.Item` wraps collapsed items in a tooltip and exposes `Item.Icon`, `Item.Text`, and `Item.Button` for composition.
+- `SideBar.Item.Button` only renders while the sidebar is expanded and defaults its size to `M`.
+- `SideBar.Button` is the root collapsible action button, and it defaults to `PlusIcon` when no collapsed icon is provided.