@neo4j-ndl/react 4.16.8 → 4.16.9

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

@@ -0,0 +1,26 @@
+# OutlinedButton
+
+Import: `import { OutlinedButton } from '@neo4j-ndl/react'`
+
+## Props
+
+### OutlinedButton
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `as` | `("a" & ElementType<any, keyof IntrinsicElements>) \| ("symbol" & ElementType<any, keyof IntrinsicElements>) \| ... 178 more ...` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. |
+| `children` | `ReactNode` |  |  |  |
+| `href` | `string` |  |  | The URL to link to. Only applies when `as="a"` |
+| `isDisabled` | `boolean` |  | `false` | If the button is in disabled state |
+| `isFloating` | `boolean` |  | `false` | If the button is in floating state |
+| `isFluid` | `boolean` |  |  | If the button is fluid, it will take the full width of its container |
+| `isLoading` | `boolean` |  | `false` | If the button is doing something Async, it will display a loading spinner |
+| `leadingVisual` | `ReactNode` |  |  | Icon to display before the button content |
+| `loadingMessage` | `string` |  |  | Accessible message for screen readers when the button is in a loading state |
+| `onClick` | `((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` |  |  | onClick callback |
+| `onKeyDown` | `((e: KeyboardEvent<HTMLButtonElement>) => void)` |  |  | onKeyDown callback |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'medium' \| 'small'` |  | `medium` | Size of button |
+| `target` | `HTMLAttributeAnchorTarget` |  |  | The target window for the link. Only applies when `as="a"`. Not present or required for other element types. |
+| `type` | `'button' \| 'reset' \| 'submit'` |  | `button` | Type of button |
+| `variant` | `'danger' \| 'neutral' \| 'primary'` |  | `primary` | Variant of the button |

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

@@ -0,0 +1,283 @@
+# Popover
+
+Import: `import { Popover } from '@neo4j-ndl/react'`
+
+## Props
+
+### Popover
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `anchorElement` | `Element \| null` |  |  | Can be used if the anchor should be separated from the trigger. Note: to visually separate the anchor from the trigger, use the Popover.Anchor component instead. |
+| `anchorPosition` | `{ x: number; y: number; }` |  |  | If the anchorPosition is provided the anchorElement will be ignored |
+| `children` | `ReactNode` |  |  | The content of the popover |
+| `closeOnClickOutside` | `boolean` |  | `true` | If the popover should close when the user clicks outside of it |
+| `hasAnchorPortal` | `boolean` |  |  | Use anchorEl for portal's container. Should be used if the popover is portaled and is inside a Dialog for example. |
+| `initialFocus` | `number \| RefObject<HTMLElement \| null>` |  |  | Which element to initially focus. * |
+| `isOpen` | `boolean` |  |  | if the popover is open |
+| `isPortaled` | `boolean` |  |  | Whether the content is rendered in a portal |
+| `offset` | `OffsetOptions` |  |  | can take either a number, an object or a function. Full documentation here:  https://floating-ui.com/docs/offset |
+| `onOpenChange` | `((isOpen: boolean, event?: Event) => void)` |  |  | Called when an internal state change is triggered, when the floating element either opens or closes. It is not called when `isOpen` is updated by the consumer. |
+| `placement` | `'bottom-end-bottom-start' \| 'bottom-end-top-end' \| 'bottom-middle-top-middle' \| 'bottom-start-bottom-end' \| 'bottom-start-top-start' \| 'middle-end-middle-start' \| 'middle-start-middle-end' \| 'top-end-bottom-end' \| 'top-end-top-start' \| 'top-middle-bottom-middle' \| 'top-start-bottom-start' \| 'top-start-top-end'` |  |  | The placement of the floating element is determined by two sets of words. The first set of words specifies the point on the anchor element where the floating element will be attached. The second set of coordinates specifies the point on the floating element that will attach to the anchor element. |
+| `role` | `'alertdialog' \| 'dialog' \| 'grid' \| 'listbox' \| 'menu' \| 'tooltip' \| 'tree'` |  |  | The role of the popover. @deprecated - This prop will be removed in v5. |
+| `shouldCaptureFocus` | `boolean` |  | `false` | If the popover should constrain the focus inside the popover while open |
+| `shouldConstrainSize` | `boolean` |  |  | When true, limits the popover's max-height and max-width to the available viewport space. The consumer is responsible for adding overflow handling (e.g. overflow-y: auto) to the content. |
+| `strategy` | `'absolute' \| 'fixed'` |  |  | The strategy of the popover. Fixed should be used when the popover is inside a Dialog. |
+
+### Popover.Anchor
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` |  |  |  |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+
+### Popover.Content
+
+| 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` | ✅ |  |  |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+
+### Popover.Trigger
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  | The content of the trigger |
+| `hasButtonWrapper` | `boolean` |  | `false` | Whether the trigger should render a button element, or pass its props to the child element |
+| `ref` | `Ref<HTMLButtonElement>` |  |  | A ref to apply to the root element. |
+
+## Accessibility
+
+## Implementation guidelines
+
+When used with a toggle button, the button should have aria-expanded (true when open, false when closed), aria-haspopup set to the role of the popover, and aria-controls set to the id of the popover.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { FilledButton, Popover } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Popover>
+      <Popover.Trigger hasButtonWrapper>
+        <FilledButton>Open Popover</FilledButton>
+      </Popover.Trigger>
+      <Popover.Content className="n-p-token-16">
+        Popover content
+      </Popover.Content>
+    </Popover>
+  );
+};
+
+export default Component;
+```
+
+### Controlled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { FilledButton, Popover } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <Popover
+      isOpen={isOpen}
+      onOpenChange={(open) => {
+        setIsOpen(open);
+      }}
+    >
+      <Popover.Trigger hasButtonWrapper>
+        <FilledButton onClick={() => setIsOpen((prev) => !prev)}>
+          Open Popover
+        </FilledButton>
+      </Popover.Trigger>
+      <Popover.Content className="n-p-token-16">
+        Popover content
+      </Popover.Content>
+    </Popover>
+  );
+};
+
+export default Component;
+```
+
+### Custom Offset
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { FilledButton, Popover, Select } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const offsetOptions = [
+  {
+    label: 'crossAxis-anchor-element-width',
+    value: 'crossAxis-anchor-element-width',
+  },
+  {
+    label: 'crossAxis-anchor-element-negative-width',
+    value: 'crossAxis-anchor-element-negative-width',
+  },
+  {
+    label: 'crossAxis-floating-element-negative-width',
+    value: 'crossAxis-floating-element-negative-width',
+  },
+  {
+    label: 'crossAxis-floating-element-width',
+    value: 'crossAxis-floating-element-width',
+  },
+];
+
+const offsetTranslation: Record<
+  string,
+  React.ComponentProps<typeof Popover>['offset']
+> = {
+  'crossAxis-anchor-element-negative-width': ({ rects }) => ({
+    crossAxis: -rects.reference.width,
+  }),
+  'crossAxis-anchor-element-width': ({ rects }) => ({
+    crossAxis: rects.reference.width,
+  }),
+  'crossAxis-floating-element-negative-width': ({ rects }) => ({
+    crossAxis: -rects.floating.width,
+  }),
+  'crossAxis-floating-element-width': ({ rects }) => ({
+    crossAxis: rects.floating.width,
+  }),
+};
+
+const Component = () => {
+  const [selectedPosition, setSelectedPosition] = useState(
+    offsetOptions[0].value,
+  );
+
+  return (
+    <div className="n-flex n-flex-col n-gap-token-32 n-items-center">
+      <Popover offset={offsetTranslation[selectedPosition]}>
+        <Popover.Trigger hasButtonWrapper>
+          <FilledButton>Open Popover</FilledButton>
+        </Popover.Trigger>
+        <Popover.Content className="n-p-token-16">
+          Popover content
+        </Popover.Content>
+      </Popover>
+
+      <Select
+        type="select"
+        label="Example positions"
+        selectProps={{
+          defaultValue: offsetOptions[0],
+          onChange: (e) => {
+            if (e) {
+              setSelectedPosition(e.value);
+            }
+          },
+          options: offsetOptions,
+        }}
+      />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### In Dialog
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Dialog, FilledButton, Popover } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [isDialogOpen, setDialogOpen] = useState(false);
+  const closeDialog = () => setDialogOpen(false);
+  return (
+    <div className="n-flex n-justify-center">
+      <FilledButton onClick={() => setDialogOpen(true)}>
+        Open Dialog
+      </FilledButton>
+      <Dialog isOpen={isDialogOpen} onClose={closeDialog}>
+        <Dialog.Header>Dialog</Dialog.Header>
+        <Dialog.Content>
+          <Popover>
+            <Popover.Trigger hasButtonWrapper>
+              <FilledButton className="n-mx-auto">Open Popover</FilledButton>
+            </Popover.Trigger>
+            <Popover.Content className="n-p-token-16">
+              Custom Popover content
+            </Popover.Content>
+          </Popover>
+        </Dialog.Content>
+      </Dialog>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### No Button Wrapper
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Popover } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Popover>
+      <Popover.Trigger>
+        <div>Open Popover</div>
+      </Popover.Trigger>
+      <Popover.Content className="n-p-token-16">
+        Popover content
+      </Popover.Content>
+    </Popover>
+  );
+};
+
+export default Component;
+```
+
+### Separate Anchor
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { FilledButton, Popover } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <div className="n-flex n-justify-between n-w-full">
+      <Popover isOpen={isOpen} onOpenChange={(open) => setIsOpen(open)}>
+        <Popover.Anchor>
+          <div>Anchor Element</div>
+        </Popover.Anchor>
+        <Popover.Trigger hasButtonWrapper>
+          <FilledButton onClick={() => setIsOpen(true)}>
+            Click to open popover
+          </FilledButton>
+        </Popover.Trigger>
+        <Popover.Content className="n-p-token-16">
+          Popover content
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/progress-bar.md

@@ -0,0 +1,70 @@
+# ProgressBar
+
+Import: `import { ProgressBar } from '@neo4j-ndl/react'`
+
+## Props
+
+### ProgressBar
+
+| 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. |
+| `heading` | `string` |  |  | The heading displayed above the progress bar |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'small'` |  | `small` | Size of the progress bar |
+| `value` | `number` | ✅ |  | The current progress value, should be between 0 and 100 |
+
+## Accessibility
+
+## Implementation guidelines
+
+The progress bar component uses `role='progressbar'` and `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` attributes to communicate its current state to assistive technologies. This ensures that users with disabilities can understand the progress being made.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ProgressBar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <ProgressBar value={75} size="large" />;
+};
+
+export default Component;
+```
+
+### Heading
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ProgressBar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <ProgressBar heading="Importing data" value={75} size="large" />;
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ProgressBar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-16">
+      <ProgressBar value={75} size="small" heading="Small" />
+      <ProgressBar value={75} size="large" heading="Large" />
+    </div>
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,150 @@
+# Radio
+
+Import: `import { Radio } from '@neo4j-ndl/react'`
+
+## Props
+
+### Radio
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `ariaLabel` | `string` |  |  | The aria label of the radio. Required if the label is not a string. |
+| `hasLeadingLabel` | `boolean` |  |  | Whether the label should be displayed before the radio |
+| `isChecked` | `boolean` |  |  | Whether the radio is checked |
+| `isDefaultChecked` | `boolean` |  |  | Selects the radio by default in uncontrolled mode |
+| `isDisabled` | `boolean` |  | `false` | Whether the radio is disabled |
+| `isFluid` | `boolean` |  | `false` | Whether the radio & label should take the full available width of its container |
+| `label` | `ReactNode` |  |  | The label of the radio. If not a string, supply an aria label for screen reader support. |
+| `onChange` | `((event: ChangeEvent<HTMLInputElement, Element>) => void)` |  |  | The callback function triggered when the radio value changes |
+| `onClick` | `((event: MouseEvent<HTMLInputElement, MouseEvent>) => void)` |  |  | The callback function triggered when the radio is clicked |
+| `ref` | `Ref<HTMLInputElement>` |  |  | A ref to apply to the root element. |
+| `value` | `string \| number \| readonly string[]` |  |  | The value of the radio |
+
+## Accessibility
+
+## Implementation guidelines
+
+The Radio 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 { Radio } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Radio label="Radio label" />;
+};
+
+export default Component;
+```
+
+### Controlled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [isChecked, setIsChecked] = useState(false);
+
+  return (
+    <Radio
+      label="Controlled radio"
+      isChecked={isChecked}
+      onChange={(event) => setIsChecked(event.target.checked)}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Custom Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, Typography } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Radio
+      label={<Typography variant="label">Custom label</Typography>}
+      ariaLabel="example aria label"
+    />
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-12">
+      <Radio label="Radio label" isDisabled />
+      <Radio label="Radio label" isDisabled isChecked />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Has Label Before
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Radio label="Radio label" hasLeadingLabel />;
+};
+
+export default Component;
+```
+
+### No Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Radio ariaLabel="Radio without label" />;
+};
+
+export default Component;
+```
+
+### Truncated Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-max-w-32">
+      <Radio label="This is a long label that will overflow" />
+    </div>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/read-only-tag.md

@@ -0,0 +1,96 @@
+# ReadOnlyTag
+
+Import: `import { ReadOnlyTag } from '@neo4j-ndl/react'`
+
+## Props
+
+### ReadOnlyTag
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` |  |  | The content of the tag |
+| `color` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8'` |  |  | Categorical color for the background |
+| `leadingVisual` | `ReactNode` |  |  | Icon to display before the content |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'medium' \| 'small' \| 'x-small'` |  |  | Size of the tag |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ReadOnlyTag } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <ReadOnlyTag>Read-only Tag</ReadOnlyTag>;
+};
+
+export default Component;
+```
+
+### Colors
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ReadOnlyTag } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-16">
+      <ReadOnlyTag color="1">Categorical color 1</ReadOnlyTag>
+      <ReadOnlyTag color="2">Categorical color 2</ReadOnlyTag>
+      <ReadOnlyTag color="3">Categorical color 3</ReadOnlyTag>
+      <ReadOnlyTag color="4">Categorical color 4</ReadOnlyTag>
+      <ReadOnlyTag color="5">Categorical color 5</ReadOnlyTag>
+      <ReadOnlyTag color="6">Categorical color 6</ReadOnlyTag>
+      <ReadOnlyTag color="7">Categorical color 7</ReadOnlyTag>
+      <ReadOnlyTag color="8">Categorical color 8</ReadOnlyTag>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ReadOnlyTag } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-row n-gap-token-8">
+      <ReadOnlyTag size="x-small">X-Small</ReadOnlyTag>
+      <ReadOnlyTag size="small">Small</ReadOnlyTag>
+      <ReadOnlyTag size="medium">Medium</ReadOnlyTag>
+      <ReadOnlyTag size="large">Large</ReadOnlyTag>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### With Leading Icon
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ReadOnlyTag } from '@neo4j-ndl/react';
+import { DatabasePlusIcon } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <ReadOnlyTag leadingVisual={<DatabasePlusIcon />}>
+      Read-only Tag with leading icon
+    </ReadOnlyTag>
+  );
+};
+
+export default Component;
+```