@neo4j-ndl/react 4.16.8 → 4.16.9

package/skills/ndl-react/components/segmented-control.md

@@ -0,0 +1,200 @@
+# SegmentedControl
+
+Import: `import { SegmentedControl } from '@neo4j-ndl/react'`
+
+## Props
+
+### SegmentedControl
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `as` | `ElementType<any, keyof IntrinsicElements>` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. |
+| `children` | `ReactNode` | ✅ |  | The children component of the segmented control |
+| `hasOnlyIcons` | `boolean` |  | `false` | If segmented control items will include only icons (makes controls rectangular) |
+| `isFloating` | `boolean` |  | `false` | Whether the segmented control has a box shadow applied |
+| `onChange` | `(e: T) => void \| ((e: SetStateAction<T>) => void)` | ✅ |  | The callback function triggered when the segmented control value changes |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `selected` | `SegmentedControlID` | ✅ |  | The currently selected option |
+| `size` | `'large' \| 'medium' \| 'small'` |  | `medium` | Size of the segmented control |
+
+Where type `SegmentedControlID` is defined as: `string | number`.
+
+### SegmentedControl.Item
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `as` | `ElementType<any, keyof IntrinsicElements>` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. |
+| `children` | `ReactNode` |  |  | The children component of the segmented control item |
+| `description` | `string` |  |  | The description of the segmented control item, will be displayed in the tooltip |
+| `isDisabled` | `boolean` |  | `false` | Whether the segmented control item is disabled |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `tooltipProps` | `TooltipObjectProps` |  |  | The tooltip props that will be applied if tooltip is set |
+| `value` | `string` | ✅ |  | The value of the segmented control item |
+
+When the `description` prop is set, hovering over the segmented control item will show a tooltip with the text provided in the `description` prop. `tooltipProps` can be used to customize the tooltip appearance. The `TooltipObjectProps` type is defined as: `{ root?: Partial<React.ComponentProps<typeof Tooltip>>; trigger?: Partial<React.ComponentProps<typeof Tooltip.Trigger>>; content?: Partial<React.ComponentProps<typeof Tooltip.Content>>; }`, see the Tooltip component for more details.
+
+## Accessibility
+
+## Implementation guidelines
+
+SegmentedControl is a grouped interactive control rendered with `role='group'` to convey related selection options. Only one item is selectable at a time, and updates are triggered on click events or using the keyboard navigations. Each segmented control item can have a tooltip applied to it to provide additional information to the user.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SegmentedControl } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selected, setSelected] = useState('tag1');
+
+  return (
+    <SegmentedControl selected={selected} onChange={setSelected}>
+      <SegmentedControl.Item value="tag1">Tag 1</SegmentedControl.Item>
+      <SegmentedControl.Item value="tag2">Tag 2</SegmentedControl.Item>
+      <SegmentedControl.Item value="tag3">Tag 3</SegmentedControl.Item>
+    </SegmentedControl>
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SegmentedControl } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selected, setSelected] = useState('tag1');
+
+  return (
+    <SegmentedControl selected={selected} onChange={setSelected}>
+      <SegmentedControl.Item value="tag1" isDisabled>
+        Tag 1
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="tag2" isDisabled>
+        Tag 2
+      </SegmentedControl.Item>
+    </SegmentedControl>
+  );
+};
+
+export default Component;
+```
+
+### Floating
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SegmentedControl } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selected, setSelected] = useState('tag1');
+
+  return (
+    <SegmentedControl
+      selected={selected}
+      onChange={setSelected}
+      isFloating={true}
+    >
+      <SegmentedControl.Item value="tag1">Tag 1</SegmentedControl.Item>
+      <SegmentedControl.Item value="tag2">Tag 2</SegmentedControl.Item>
+      <SegmentedControl.Item value="tag3">Tag 3</SegmentedControl.Item>
+    </SegmentedControl>
+  );
+};
+
+export default Component;
+```
+
+### Only Icons
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SegmentedControl } from '@neo4j-ndl/react';
+import { BeakerIconOutline, BoltIconOutline } from '@neo4j-ndl/react/icons';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selected, setSelected] = useState('boltIcon');
+
+  return (
+    <SegmentedControl
+      selected={selected}
+      onChange={setSelected}
+      hasOnlyIcons={true}
+    >
+      <SegmentedControl.Item value="boltIcon" description="Bolt View">
+        <BoltIconOutline />
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="beakerIcon" description="Beaker View">
+        <BeakerIconOutline />
+      </SegmentedControl.Item>
+    </SegmentedControl>
+  );
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SegmentedControl } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedSmall, setSelectedSmall] = useState('small1');
+  const [selectedMedium, setSelectedMedium] = useState('medium1');
+  const [selectedLarge, setSelectedLarge] = useState('large1');
+
+  return (
+    <div className="n-flex n-gap-token-16">
+      <SegmentedControl
+        selected={selectedSmall}
+        onChange={setSelectedSmall}
+        size="small"
+      >
+        <SegmentedControl.Item value="small1">Small 1</SegmentedControl.Item>
+        <SegmentedControl.Item value="small2">Small 2</SegmentedControl.Item>
+        <SegmentedControl.Item value="small3">Small 3</SegmentedControl.Item>
+      </SegmentedControl>
+
+      <SegmentedControl
+        selected={selectedMedium}
+        onChange={setSelectedMedium}
+        size="medium"
+      >
+        <SegmentedControl.Item value="medium1">Medium 1</SegmentedControl.Item>
+        <SegmentedControl.Item value="medium2">Medium 2</SegmentedControl.Item>
+        <SegmentedControl.Item value="medium3">Medium 3</SegmentedControl.Item>
+      </SegmentedControl>
+
+      <SegmentedControl
+        selected={selectedLarge}
+        onChange={setSelectedLarge}
+        size="large"
+      >
+        <SegmentedControl.Item value="large1">Large 1</SegmentedControl.Item>
+        <SegmentedControl.Item value="large2">Large 2</SegmentedControl.Item>
+        <SegmentedControl.Item value="large3">Large 3</SegmentedControl.Item>
+      </SegmentedControl>
+    </div>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/select-icon-button.md

@@ -0,0 +1,183 @@
+# SelectIconButton
+
+Import: `import { SelectIconButton } from '@neo4j-ndl/react'`
+
+## Props
+
+### SelectIconButton
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` |  |  | Content displayed in the button |
+| `description` | `string \| null` | ✅ |  | A string that will be shown as a tooltip when hovering over the button. It also acts as an aria-label. {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label} |
+| `isDisabled` | `boolean` |  | `false` | Whether the button is in disabled state |
+| `isLoading` | `boolean` |  | `false` | If the button is doing something Async, it will display a loading spinner |
+| `isOpen` | `boolean` |  | `false` | If the button is opened |
+| `loadingMessage` | `string` |  | `Loading` | Accessible message for screen readers when the button is in a loading state |
+| `onClick` | `((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` |  |  | Callback function to be called when the button is clicked |
+| `ref` | `Ref<HTMLButtonElement>` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'medium' \| 'small'` |  | `medium` | Size of button |
+| `tooltipProps` | `TooltipObjectProps` |  |  | Props for the tooltip component. |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SelectIconButton } from '@neo4j-ndl/react';
+import { SelectIcon } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <SelectIconButton description="Select" isOpen={false}>
+      <SelectIcon />
+    </SelectIconButton>
+  );
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SelectIconButton, Typography } from '@neo4j-ndl/react';
+import { SelectIcon } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-16">
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <SelectIconButton description="Select" size="small" isOpen={false}>
+          <SelectIcon />
+        </SelectIconButton>
+        <Typography variant="label"> Small</Typography>
+      </div>
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <SelectIconButton description="Select" size="medium" isOpen={false}>
+          <SelectIcon />
+        </SelectIconButton>
+        <Typography variant="label"> Medium</Typography>
+      </div>
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <SelectIconButton description="Select" size="large" isOpen={false}>
+          <SelectIcon />
+        </SelectIconButton>
+        <Typography variant="label"> Large</Typography>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### States
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { SelectIconButton, Typography } from '@neo4j-ndl/react';
+import { SelectIcon } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-16">
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <SelectIconButton
+          description="Select"
+          size="small"
+          isDisabled
+          isOpen={false}
+        >
+          <SelectIcon />
+        </SelectIconButton>
+        <Typography variant="label"> Disabled</Typography>
+      </div>
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <SelectIconButton description="Select" size="small" isOpen={true}>
+          <SelectIcon />
+        </SelectIconButton>
+        <Typography variant="label"> Active</Typography>
+      </div>
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <SelectIconButton
+          description="Select"
+          size="small"
+          isLoading
+          loadingMessage="Loading"
+          isOpen={false}
+        >
+          <SelectIcon />
+        </SelectIconButton>
+        <Typography variant="label"> Loading</Typography>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### With Menu
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Menu, SelectIconButton } from '@neo4j-ndl/react';
+import {
+  ExploreIcon,
+  HierarchyTwoIcon,
+  SelectIcon,
+} from '@neo4j-ndl/react/icons';
+import { useRef, useState } from 'react';
+
+const menuItems = [
+  { leadingVisual: <ExploreIcon />, title: 'Force-based layout' },
+  { leadingVisual: <HierarchyTwoIcon />, title: 'Hierarchical layout' },
+];
+
+const Component = () => {
+  const anchorRef = useRef<HTMLButtonElement | null>(null);
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+  const [selectedItem, setSelectedItem] = useState<number>();
+
+  return (
+    <div>
+      <SelectIconButton
+        description="Options"
+        isOpen={isMenuOpen}
+        onClick={() => setIsMenuOpen((old) => !old)}
+        ref={anchorRef}
+      >
+        {selectedItem !== undefined ? (
+          menuItems[selectedItem].leadingVisual
+        ) : (
+          <SelectIcon />
+        )}
+      </SelectIconButton>
+      <Menu
+        isOpen={isMenuOpen}
+        anchorRef={anchorRef}
+        onClose={() => setIsMenuOpen(false)}
+      >
+        {menuItems.map((item, index) => (
+          <Menu.RadioItem
+            key={index}
+            isChecked={selectedItem === index}
+            title={item.title}
+            leadingVisual={item.leadingVisual}
+            onClick={() => setSelectedItem(index)}
+          />
+        ))}
+      </Menu>
+    </div>
+  );
+};
+
+export default Component;
+```