@neo4j-ndl/react 4.16.7 → 4.16.9

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

@@ -0,0 +1,225 @@
+# Banner
+
+Import: `import { Banner } from '@neo4j-ndl/react'`
+
+## Props
+
+### Banner
+
+| 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` |  |  | Content to be shown in the banner. |
+| `hasIcon` | `boolean` |  | `false` | Shows a status icon. The icon is based on the value of the `variant` prop |
+| `isAlert` | `boolean` |  | `false` | Sets the role to alert |
+| `isCloseable` | `boolean` |  | `false` | If the banner is closeable. Renders an icon button in the top right corner |
+| `onClose` | `((e?: MouseEvent<HTMLElement, MouseEvent> \| KeyboardEvent<HTMLElement>) => void)` |  |  | Event handler for when the close icon is clicked |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `usage` | `'global' \| 'inline'` |  | `inline` | How the banner is used. |
+| `variant` | `'danger' \| 'info' \| 'neutral' \| 'success' \| 'warning'` |  | `info` | The variant of the banner |
+
+### Banner.Actions
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  |  |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+
+### Banner.Description
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  |  |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+
+### Banner.Header
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  |  |
+| `ref` | `Ref<HTMLSpanElement>` |  |  | A ref to apply to the root element. |
+
+## Accessibility
+
+## Implementation guidelines
+
+The `isAlert` prop must be set to `true` for the banner to be given an alert role, which is used by screen readers. If this role is not wanted, make sure to set the prop to `false`.
+
+## Examples
+
+### Closeable
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Banner } from '@neo4j-ndl/react';
+
+const Component = () => {
+  const title = 'Banner title';
+  return (
+    <Banner
+      isCloseable={true}
+      onClose={() => alert('Banner component close icon clicked')}
+    >
+      <Banner.Header>{title}</Banner.Header>
+      <Banner.Description>Banner description</Banner.Description>
+    </Banner>
+  );
+};
+
+export default Component;
+```
+
+### Global
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Banner } from '@neo4j-ndl/react';
+
+const Component = () => {
+  const title = 'Banner title';
+  return (
+    <Banner usage="global">
+      <Banner.Header>{title}</Banner.Header>
+      <Banner.Description>Banner description</Banner.Description>
+    </Banner>
+  );
+};
+
+export default Component;
+```
+
+### Variants
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Banner } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-8">
+      <Banner variant="info">
+        <Banner.Header>Info</Banner.Header>
+        <Banner.Description>This is a banner of type info.</Banner.Description>
+      </Banner>
+      <Banner variant="success">
+        <Banner.Header>Success</Banner.Header>
+        <Banner.Description>
+          This is a banner of type success.
+        </Banner.Description>
+      </Banner>
+      <Banner variant="warning">
+        <Banner.Header>Warning</Banner.Header>
+        <Banner.Description>
+          This is a banner of type warning.
+        </Banner.Description>
+      </Banner>
+      <Banner variant="danger">
+        <Banner.Header>Danger</Banner.Header>
+        <Banner.Description>
+          This is a banner of type danger.
+        </Banner.Description>
+      </Banner>
+      <Banner variant="neutral">
+        <Banner.Header>Neutral</Banner.Header>
+        <Banner.Description>
+          This is a banner of type neutral.
+        </Banner.Description>
+      </Banner>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### With Actions
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Banner, OutlinedButton, TextButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Banner hasIcon={true}>
+      <Banner.Header>Banner title</Banner.Header>
+      <Banner.Description>Banner description</Banner.Description>
+      <Banner.Actions>
+        <OutlinedButton>Primary action</OutlinedButton>
+        <TextButton>Secondary action</TextButton>
+      </Banner.Actions>
+    </Banner>
+  );
+};
+
+export default Component;
+```
+
+### With Icons
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Banner } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-8">
+      <Banner variant="info" hasIcon={true}>
+        <Banner.Header>Info</Banner.Header>
+        <Banner.Description>This is a banner of type info.</Banner.Description>
+      </Banner>
+      <Banner variant="success" hasIcon={true}>
+        <Banner.Header>Success</Banner.Header>
+        <Banner.Description>
+          This is a banner of type success.
+        </Banner.Description>
+      </Banner>
+      <Banner variant="warning" hasIcon={true}>
+        <Banner.Header>Warning</Banner.Header>
+        <Banner.Description>
+          This is a banner of type warning.
+        </Banner.Description>
+      </Banner>
+      <Banner variant="danger" hasIcon={true}>
+        <Banner.Header>Danger</Banner.Header>
+        <Banner.Description>
+          This is a banner of type danger.
+        </Banner.Description>
+      </Banner>
+      <Banner variant="neutral" hasIcon={true}>
+        <Banner.Header>Neutral</Banner.Header>
+        <Banner.Description>
+          This is a banner of type neutral.
+        </Banner.Description>
+      </Banner>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Without Title
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Banner, OutlinedButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Banner>
+      <Banner.Description>A banner with only description</Banner.Description>
+      <Banner.Actions>
+        <OutlinedButton>Action</OutlinedButton>
+      </Banner.Actions>
+    </Banner>
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,39 @@
+# Box
+
+Import: `import { Box } from '@neo4j-ndl/react'`
+
+## Props
+
+### Box
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `as` | `ElementType<any, keyof IntrinsicElements>` |  | `'div' as T` | An override of the default HTML tag of the root of the component. Can also be another React component. |
+| `borderRadius` | `'2xl' \| '3xl' \| 'full' \| 'lg' \| 'md' \| 'none' \| 'sm' \| 'xl'` |  | `undefined` |  |
+| `children` | `ReactNode` |  |  |  |
+| `padding` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `tokens.space['4']` |  |
+| `paddingBlockEnd` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `undefined` |  |
+| `paddingBlockStart` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `undefined` |  |
+| `paddingInline` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `undefined` |  |
+| `paddingInlineEnd` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `undefined` |  |
+| `paddingInlineStart` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `undefined` |  |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Box } from '@neo4j-ndl/react';
+import type React from 'react';
+
+type BoxProps = React.ComponentProps<typeof Box>;
+
+const BoxDefault = (args: BoxProps) => <Box {...args}>{args.children}</Box>;
+
+BoxDefault.displayName = 'BoxDefault';
+
+export default BoxDefault;
+```

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

@@ -0,0 +1,245 @@
+# Breadcrumbs
+
+Import: `import { Breadcrumbs } from '@neo4j-ndl/react'`
+
+## Props
+
+### Breadcrumbs
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` |  |  | Content to be rendered. Should only be `Breadcrumbs.Item`. |
+| `ref` | `Ref<HTMLElement>` |  |  | A ref to apply to the root element. |
+| `shouldWrap` | `boolean` |  | `true` | Additional classnames. |
+
+### Breadcrumbs.Button
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `as` | `("button" & ElementType<any, keyof IntrinsicElements>) \| ("a" & ElementType<any, keyof IntrinsicElements>) \| ... 177 more ... \| (FunctionComponent<...> & ElementType<...>)` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. What HTML element to render the root element as. |
+| `children` | `ReactNode` |  |  | Content to be rendered. |
+| `href` | `string` | ✅ |  | The href of the link. Only applicable if `as` is `'a'`. |
+| `leadingElement` | `ReactNode` |  |  | Leading element to be rendered. |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void` |  |  | Event handler for when the button is clicked. Only applicable if `as` is `'button'`. |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `target` | `HTMLAttributeAnchorTarget` |  |  | The target of the link. Only applicable if `as` is `'a'`. |
+| `trailingElement` | `ReactNode` |  |  | Trailing element to be rendered. |
+
+### Breadcrumbs.Item
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` |  |  | Content to be rendered. Should be either `Breadcrumbs.Link`, `Breadcrumbs.Button` or `Breadcrumbs.SelectButton`. |
+| `ref` | `Ref<HTMLLIElement>` |  |  | A ref to apply to the root element. |
+
+### Breadcrumbs.Link
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `ariaCurrent` | `boolean \| "time" \| "false" \| "true" \| "page" \| "step" \| "location" \| "date"` |  | `false` | Whether the link is the current item. Use `'page'` if it indicates the current page and `'step'` for steps (in a multi-step wizard for example). @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current |
+| `as` | `("button" & ElementType<any, keyof IntrinsicElements>) \| ("a" & ElementType<any, keyof IntrinsicElements>) \| ... 177 more ... \| (FunctionComponent<...> & ElementType<...>)` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. What HTML element to render the root element as. |
+| `children` | `ReactNode` |  |  | Content to be rendered. |
+| `href` | `string` | ✅ |  | The href of the link. Only applicable if `as` is `'a'`. |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void` |  |  | Event handler for when the button is clicked. Only applicable if `as` is `'button'`. |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `target` | `HTMLAttributeAnchorTarget` |  |  | The target of the link. Only applicable if `as` is `'a'`. |
+
+### Breadcrumbs.SelectButton
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `ariaLabel` | `string` | ✅ |  | Aria label needed for accessibility. |
+| `children` | `ReactNode` |  |  | Content to be rendered. |
+| `isActive` | `boolean` |  |  | Active - used when a connected menu is open |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void` |  |  | Event handler for when the button is clicked. Should be used to open a `Menu`. |
+| `ref` | `Ref<HTMLButtonElement>` |  |  | A ref to apply to the root element. |
+
+## Accessibility
+
+## Implementation guidelines
+
+- The `Link` has a `ariaCurrent` prop that should be set on the breadcrumb that is representing the current step or page, to the corresponding value.
+
+- The `Button` can be used with both icon + text, text only or icon only. If you only provide an icon, to create a custom home breadcrumb e.g., make sure to set the `aria-label` in the `htmlAttributes` prop.
+
+- The `SelectButton` is essentially an icon button, and therefore has a prop `ariaLabel` that is required for accessibility.
+
+## Examples
+
+### Ellipses
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Breadcrumbs, Menu } from '@neo4j-ndl/react';
+import { useRef, useState } from 'react';
+
+const Component = () => {
+  const menuRef = useRef<HTMLButtonElement>(null);
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="#">Home</Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link
+          ref={menuRef}
+          as="button"
+          onClick={() => setIsMenuOpen(!isMenuOpen)}
+          htmlAttributes={{
+            'aria-label': 'Open ellipsis menu',
+          }}
+        >
+          ...
+          <Menu
+            anchorRef={menuRef}
+            isOpen={isMenuOpen}
+            onClose={() => setIsMenuOpen(false)}
+          >
+            <Menu.Item title="Page 1" />
+            <Menu.Item title="Page 2" />
+            <Menu.Item title="Page 3" />
+          </Menu>
+        </Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link as="span" ariaCurrent="page">
+          Current page
+        </Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+};
+
+export default Component;
+```
+
+### Header
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Breadcrumbs, Menu } from '@neo4j-ndl/react';
+import {
+  BuildingOffice2IconOutline,
+  FolderIconOutline,
+  Neo4JIconColorIcon,
+} from '@neo4j-ndl/react/icons';
+import { useRef, useState } from 'react';
+
+const Component = () => {
+  const [isOrganizationMenuOpen, setIsOrganizationMenuOpen] = useState(false);
+  const organizationMenuRef = useRef<HTMLButtonElement>(null);
+
+  return (
+    <Breadcrumbs shouldWrap={false}>
+      <Breadcrumbs.Item className="n-mr-token-8">
+        <button
+          type="button"
+          aria-label="Home"
+          className="n-rounded-sm focus-visible:n-outline-2 focus-visible:n-outline-offset-[3px] focus-visible:n-outline-primary-focus n-shrink-0"
+        >
+          <Neo4JIconColorIcon className="n-h-6 n-w-[26px]" />
+        </button>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Button leadingElement={<BuildingOffice2IconOutline />}>
+          Organization 1
+        </Breadcrumbs.Button>
+        <Breadcrumbs.SelectButton
+          ref={organizationMenuRef}
+          ariaLabel="Open organization menu"
+          onClick={() => {
+            setIsOrganizationMenuOpen((prev) => !prev);
+          }}
+          isActive={isOrganizationMenuOpen}
+        >
+          <Menu
+            anchorRef={organizationMenuRef}
+            isOpen={isOrganizationMenuOpen}
+            onClose={() => setIsOrganizationMenuOpen(false)}
+          >
+            <Menu.Group>
+              <Menu.RadioItem title="Organization 1" isChecked={true} />
+              <Menu.RadioItem title="Organization 2" isChecked={false} />
+            </Menu.Group>
+            <Menu.Divider />
+            <Menu.Group>
+              <Menu.Item title="All Organizations" />
+            </Menu.Group>
+          </Menu>
+        </Breadcrumbs.SelectButton>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Button leadingElement={<FolderIconOutline />}>
+          Project 1
+        </Breadcrumbs.Button>
+        <Breadcrumbs.SelectButton ariaLabel="Open project menu"></Breadcrumbs.SelectButton>
+      </Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+};
+
+export default Component;
+```
+
+### Pages
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Breadcrumbs } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="">Home</Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="">Page</Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="">Subpage</Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="" ariaCurrent="page">
+          Current page
+        </Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+};
+
+export default Component;
+```
+
+### Steps
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Breadcrumbs } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="">Previous step</Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="" ariaCurrent="step">
+          Current step
+        </Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>
+        <Breadcrumbs.Link href="">Next step</Breadcrumbs.Link>
+      </Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+};
+
+export default Component;
+```