@neo4j-ndl/react 4.16.7 → 4.16.9

package/skills/ndl-react/components/checkbox.md

@@ -0,0 +1,269 @@
+# Checkbox
+
+Import: `import { Checkbox } from '@neo4j-ndl/react'`
+
+## Props
+
+### Checkbox
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `ariaLabel` | `string` |  |  | The aria label of the checkbox. Required if the label is not a string. |
+| `hasLeadingLabel` | `boolean` |  |  | Whether the label should be displayed before the checkbox |
+| `isChecked` | `boolean` |  |  | Whether the checkbox is checked |
+| `isDefaultChecked` | `boolean` |  |  | Checks the input by default in uncontrolled mode |
+| `isDisabled` | `boolean` |  | `false` | Whether the checkbox is disabled |
+| `isFluid` | `boolean` |  | `false` | Whether the checkbox & label should take the full available width of its container |
+| `isIndeterminate` | `boolean` |  | `false` | Whether the checkbox is indeterminate |
+| `label` | `ReactNode` |  |  | The label of the checkbox. If not a string, supply an aria label for screen reader support. |
+| `onChange` | `((event: ChangeEvent<HTMLInputElement, Element>) => void)` |  |  | The callback function triggered when the checkbox value changes |
+| `onClick` | `((event: MouseEvent<HTMLInputElement, MouseEvent>) => void)` |  |  | The callback function triggered when the checkbox is clicked |
+| `ref` | `Ref<HTMLInputElement>` |  |  | A ref to apply to the root element. |
+| `value` | `string \| number \| readonly string[]` |  |  | The value of the checkbox |
+
+## Accessibility
+
+## Implementation guidelines
+
+The Checkbox component uses implicit label wrapping to associate the visible label with the input for screen readers. If you omit the label prop or use an invalid label (no text content), the `ariaLabel` prop will be required to ensure an accessible name.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Checkbox label="Uncontrolled checkbox" />;
+};
+
+export default Component;
+```
+
+### Controlled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [isChecked, setIsChecked] = useState(false);
+  return (
+    <Checkbox
+      isChecked={isChecked}
+      onChange={(event) => setIsChecked(event.target.checked)}
+      label="Controlled checkbox"
+    />
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Checkbox label="Checkbox label" isDisabled />;
+};
+
+export default Component;
+```
+
+### Fluid
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Checkbox isFluid />;
+};
+
+export default Component;
+```
+
+### Full
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [childCheckboxes, setChildCheckboxes] = useState({
+    childOne: false,
+    childThree: true,
+    childTwo: false,
+  });
+
+  const handleParentCheckboxChange = (
+    event: React.ChangeEvent<HTMLInputElement>,
+  ) => {
+    const isChecked = event.target.checked;
+
+    // Update child checkboxes based on parent checkbox state.
+    setChildCheckboxes({
+      childOne: isChecked,
+      childThree: isChecked,
+      childTwo: isChecked,
+    });
+  };
+
+  const handleChildCheckboxChange = (
+    childKey: keyof typeof childCheckboxes,
+  ) => {
+    // Set currently clicked child checkbox.
+    setChildCheckboxes((prevState) => ({
+      ...prevState,
+      [childKey]: !prevState[childKey],
+    }));
+  };
+
+  const isParentChecked = Object.values(childCheckboxes).every(
+    (isChildChecked) => isChildChecked,
+  );
+
+  const isParentIndeterminate =
+    Object.values(childCheckboxes).some((isChildChecked) => isChildChecked) &&
+    !isParentChecked;
+
+  return (
+    <div className="n-flex n-flex-col n-items-start n-gap-1">
+      <Checkbox
+        isChecked={isParentChecked}
+        isIndeterminate={isParentIndeterminate}
+        label="Parent checkbox"
+        onChange={(event) => {
+          handleParentCheckboxChange(event);
+        }}
+      />
+      <Checkbox
+        className="n-ml-7"
+        isChecked={childCheckboxes.childOne}
+        label="Child checkbox 1"
+        onChange={() => handleChildCheckboxChange('childOne')}
+      />
+      <Checkbox
+        className="n-ml-7"
+        isChecked={childCheckboxes.childTwo}
+        label="Child checkbox 2"
+        onChange={() => handleChildCheckboxChange('childTwo')}
+      />
+      <Checkbox
+        className="n-ml-7"
+        isChecked={childCheckboxes.childThree}
+        label="Child checkbox 3"
+        onChange={() => handleChildCheckboxChange('childThree')}
+      />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Has Label Before
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Checkbox label="Checkbox label" hasLeadingLabel />;
+};
+
+export default Component;
+```
+
+### Indeterminate
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, FilledButton } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [isChecked, setIsChecked] = useState(false);
+  const [isIndeterminate, setIsIndeterminate] = useState(true);
+
+  return (
+    <div
+      style={{
+        alignItems: 'center',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '10px',
+      }}
+    >
+      <Checkbox
+        isChecked={isChecked}
+        isIndeterminate={isIndeterminate}
+        onChange={(event) => {
+          setIsChecked(event.target.checked);
+          setIsIndeterminate(event.target.indeterminate);
+        }}
+        ariaLabel="Indeterminate checkbox"
+      />
+      <div style={{ marginTop: '25px', width: '100%' }}>
+        <div>Checkbox checked state: {isChecked.toString()}</div>
+        <div>Checkbox indeterminate state: {isIndeterminate.toString()}</div>
+      </div>
+      <div>
+        <FilledButton onClick={() => setIsChecked((prev: boolean) => !prev)}>
+          Toggle checked
+        </FilledButton>
+        <FilledButton
+          onClick={() => setIsIndeterminate((prev: boolean) => !prev)}
+          style={{ marginLeft: '10px' }}
+        >
+          Toggle indeterminate
+        </FilledButton>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Label Before
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Checkbox hasLeadingLabel label="Label" />;
+};
+
+export default Component;
+```
+
+### No Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Checkbox ariaLabel="no-label-provided" />;
+};
+
+export default Component;
+```

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

@@ -0,0 +1,294 @@
+# CleanIconButton
+
+Import: `import { CleanIconButton } from '@neo4j-ndl/react'`
+
+## Props
+
+### CleanIconButton
+
+| 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` |  |  |  |
+| `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} |
+| `descriptionKbdProps` | `(KbdProps & { as?: ElementType<any, keyof IntrinsicElements>; } & BaseProps<ElementType<any, keyof IntrinsicElements>>)` |  |  | The Kbd components that will be displayed in the tooltip after the description text, this does not include the keyboard shortcut functionality this only displays the Kbd components. |
+| `isActive` | `boolean` |  |  | Active - used for open context menus for example |
+| `isDisabled` | `boolean` |  | `false` | If the icon button is in disabled state |
+| `isLoading` | `boolean` |  | `false` | If the button is doing something Async, it will display a loading spinner |
+| `loadingMessage` | `string` |  |  | Accessible message for screen readers when the button is in a loading state |
+| `onClick` | `((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` |  |  | Click handler |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'medium' \| 'small'` |  | `medium` | Size of button |
+| `tooltipProps` | `TooltipObjectProps` |  |  | Props for the tooltip component. |
+| `variant` | `'danger' \| 'neutral'` |  | `neutral` | Variant of the button |
+
+## Accessibility
+
+## Implementation guidelines
+
+A CleanIconButton must have the `tooltip` prop set for it to be accessible. The tooltip text is used as the aria-label for screen readers. CleanIconButtons are interactive elements that allow users to trigger actions with either `Space` or `Enter`. Try to avoid disabling buttons since they are removed from the accessibility tree. Instead, give the user feedback on the action.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton } from '@neo4j-ndl/react';
+import { MagnifyingGlassIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <CleanIconButton description="Search">
+      <MagnifyingGlassIconOutline />
+    </CleanIconButton>
+  );
+};
+
+export default Component;
+```
+
+### Active
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton } from '@neo4j-ndl/react';
+import { MagnifyingGlassIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <CleanIconButton description="Search" isActive>
+      <MagnifyingGlassIconOutline />
+    </CleanIconButton>
+  );
+};
+
+export default Component;
+```
+
+### All
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { IconButton, Typography } from '@neo4j-ndl/react';
+import { ArrowDownTrayIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <div className="n-grid n-grid-cols-[auto_auto_auto_auto] n-gap-token-32 n-place-items-center n-w-fit">
+      {/* size row */}
+      <Typography variant="subheading-small" className="n-justify-self-end">
+        Size
+      </Typography>
+      <IconButton description="Size example" size="small">
+        Small
+      </IconButton>
+      <IconButton description="Size example" size="medium">
+        Medium
+      </IconButton>
+      <IconButton description="Size example" size="large">
+        Large
+      </IconButton>
+
+      {/* tone row */}
+      <Typography variant="subheading-small" className="n-justify-self-end">
+        Tone
+      </Typography>
+      <IconButton description="Grouped example" tone="default">
+        <ArrowDownTrayIconOutline />
+      </IconButton>
+      <IconButton description="Grouped example" tone="danger">
+        <ArrowDownTrayIconOutline />
+      </IconButton>
+      <div></div>
+      <div></div>
+
+      {/* isDisabled Row */}
+      <Typography variant="subheading-small" className="n-justify-self-end">
+        Disabled
+      </Typography>
+      <IconButton description="Disabled example" isDisabled>
+        <ArrowDownTrayIconOutline />
+      </IconButton>
+      <div></div>
+      <div></div>
+
+      {/* isLoading Row */}
+      <Typography variant="subheading-small" className="n-justify-self-end">
+        Loading
+      </Typography>
+      <IconButton description="Loading example" isLoading>
+        <ArrowDownTrayIconOutline />
+      </IconButton>
+      <div></div>
+      <div></div>
+
+      {/* isFloating row */}
+      <Typography variant="subheading-small" className="n-justify-self-end">
+        Floating
+      </Typography>
+      <IconButton description="Floating example" isFloating>
+        <ArrowDownTrayIconOutline />
+      </IconButton>
+      <div></div>
+      <div></div>
+
+      {/* isGrouped row */}
+      <Typography variant="subheading-small" className="n-justify-self-end">
+        Grouped
+      </Typography>
+      <IconButton description="Grouped example" isGrouped>
+        <ArrowDownTrayIconOutline />
+      </IconButton>
+      <div></div>
+      <div></div>
+
+      {/* isActive row */}
+      <Typography variant="subheading-small" className="n-justify-self-end">
+        Active
+      </Typography>
+      <IconButton description="Active example" isActive>
+        <ArrowDownTrayIconOutline />
+      </IconButton>
+      <div></div>
+      <div></div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton } from '@neo4j-ndl/react';
+import { MagnifyingGlassIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <CleanIconButton description="Search" isDisabled>
+      <MagnifyingGlassIconOutline />
+    </CleanIconButton>
+  );
+};
+
+export default Component;
+```
+
+### Keyboard Display
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton } from '@neo4j-ndl/react';
+import { MagnifyingGlassIconOutline } 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">
+        <CleanIconButton
+          description="Search"
+          descriptionKbdProps={{ keys: ['B'], modifierKeys: ['meta'] }}
+          variant="neutral"
+        >
+          <MagnifyingGlassIconOutline />
+        </CleanIconButton>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Loading
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton } from '@neo4j-ndl/react';
+import { MagnifyingGlassIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <CleanIconButton description="Search" isLoading loadingMessage="Loading">
+      <MagnifyingGlassIconOutline />
+    </CleanIconButton>
+  );
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton, Typography } from '@neo4j-ndl/react';
+import { MagnifyingGlassIconOutline } 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">
+        <CleanIconButton description="Search" size="small">
+          <MagnifyingGlassIconOutline />
+        </CleanIconButton>
+        <Typography variant="label"> Small</Typography>
+      </div>
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <CleanIconButton description="Search" size="medium">
+          <MagnifyingGlassIconOutline />
+        </CleanIconButton>
+        <Typography variant="label"> Medium</Typography>
+      </div>
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <CleanIconButton description="Search" size="large">
+          <MagnifyingGlassIconOutline />
+        </CleanIconButton>
+        <Typography variant="label"> Large</Typography>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Tone
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton, Typography } from '@neo4j-ndl/react';
+import { MagnifyingGlassIconOutline } 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">
+        <CleanIconButton description="Search" variant="neutral">
+          <MagnifyingGlassIconOutline />
+        </CleanIconButton>
+        <Typography variant="label">Default</Typography>
+      </div>
+      <div className="n-flex n-flex-row n-gap-token-16 n-items-center">
+        <CleanIconButton description="Search" variant="danger">
+          <MagnifyingGlassIconOutline />
+        </CleanIconButton>
+        <Typography variant="label">Danger</Typography>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/clipboard-button.md

@@ -0,0 +1,154 @@
+# ClipboardButton
+
+Import: `import { ClipboardButton } from '@neo4j-ndl/react'`
+
+## Props
+
+### ClipboardButton
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `descriptionKbdProps` | `(KbdProps & { as?: ElementType<any, keyof IntrinsicElements>; } & BaseProps<ElementType<any, keyof IntrinsicElements>>)` |  |  |  |
+| `isDisabled` | `boolean` |  |  |  |
+| `size` | `'large' \| 'medium' \| 'small'` |  |  |  |
+| `textToCopy` | `string` | ✅ |  | The text that should be set to users clipboard |
+| `tooltipProps` | `Omit<TooltipProps, "children">` |  |  |  |
+| `type` | `'clean-icon-button' \| 'icon-button' \| 'outlined-button'` |  | `clean-icon-button` |  |
+
+For more information of the `TooltipProps` type, see the Tooltip component documentation.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ClipboardButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <ClipboardButton textToCopy="This is the text to copy" />;
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ClipboardButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <ClipboardButton textToCopy="This is the text to copy" isDisabled={true} />
+  );
+};
+
+export default Component;
+```
+
+### Keyboard Shortcut
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ClipboardButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <ClipboardButton
+      textToCopy="This is the text to copy"
+      descriptionKbdProps={{
+        keys: ['c'],
+        modifierKeys: ['ctrl', 'shift'],
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Not Clean
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ClipboardButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <ClipboardButton textToCopy="This is the text to copy" type="icon-button" />
+  );
+};
+
+export default Component;
+```
+
+### Not Icon Button
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ClipboardButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <ClipboardButton
+      type="outlined-button"
+      textToCopy="This is the text to copy"
+    />
+  );
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ClipboardButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-token-16">
+      <ClipboardButton textToCopy="This is the text to copy" size="small" />
+      <ClipboardButton textToCopy="This is the text to copy" size="medium" />
+      <ClipboardButton textToCopy="This is the text to copy" size="large" />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Tooltip
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ClipboardButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <ClipboardButton
+      textToCopy="This is the text to copy"
+      tooltipProps={{
+        hoverDelay: {
+          close: 100,
+          open: 100,
+        },
+        isInitialOpen: true,
+        placement: 'right',
+        type: 'simple',
+      }}
+    />
+  );
+};
+
+export default Component;
+```