@neo4j-ndl/react 4.16.7 → 4.16.9

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

@@ -0,0 +1,161 @@
+# DropdownButton
+
+Import: `import { DropdownButton } from '@neo4j-ndl/react'`
+
+## Props
+
+### DropdownButton
+
+| 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 displayed in the button |
+| `isDisabled` | `boolean` |  | `false` | Whether the button is in disabled state |
+| `isFloating` | `boolean` |  | `false` | Whether the button is in floating state |
+| `isLoading` | `boolean` |  | `false` | If the button is loading. Will display a loading spinner |
+| `isOpen` | `boolean` |  | `false` | If the dropdown is activated |
+| `leadingElement` | `ReactNode` |  |  | Element that is shown before the button content |
+| `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` | `any` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'medium' \| 'small'` |  | `medium` | Size of button |
+
+Make sure to set `isOpen` to the corresponding state of the Menu that is being opened by the DropdownButton. That makes sure proper styling and aria attributes are applied to reflect the state.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DropdownButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <DropdownButton>Dropdown Button</DropdownButton>;
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DropdownButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <DropdownButton isDisabled={true}>Dropdown Button</DropdownButton>;
+};
+
+export default Component;
+```
+
+### Floating
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DropdownButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <DropdownButton isFloating={true}>Dropdown Button</DropdownButton>;
+};
+
+export default Component;
+```
+
+### Loading
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DropdownButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <DropdownButton isLoading loadingMessage="Loading">
+      Dropdown Button
+    </DropdownButton>
+  );
+};
+
+export default Component;
+```
+
+### With Avatar
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar, DropdownButton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <DropdownButton
+      leadingElement={<Avatar name="KM" type="icon" shape="square" />}
+    >
+      Dropdown Button
+    </DropdownButton>
+  );
+};
+
+export default Component;
+```
+
+### With Menu
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DropdownButton, Menu } from '@neo4j-ndl/react';
+import { useRef, useState } from 'react';
+
+const Component = () => {
+  const anchorRef = useRef<HTMLButtonElement | null>(null);
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+  return (
+    <div>
+      <DropdownButton
+        isOpen={isMenuOpen}
+        onClick={() => setIsMenuOpen((old) => !old)}
+        ref={anchorRef}
+      >
+        Dropdown Button
+      </DropdownButton>
+      <Menu
+        isOpen={isMenuOpen}
+        anchorRef={anchorRef}
+        onClose={() => setIsMenuOpen(false)}
+      >
+        <Menu.Item title="Action 1" />
+        <Menu.Item title="Action 2" />
+        <Menu.Item title="Action 3" />
+        <Menu.Item title="Action 4" />
+      </Menu>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### With Status Indicator
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DropdownButton, StatusIndicator } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <DropdownButton leadingElement={<StatusIndicator variant="info" />}>
+      Dropdown Button
+    </DropdownButton>
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,371 @@
+# Dropzone
+
+Import: `import { Dropzone } from '@neo4j-ndl/react'`
+
+## Props
+
+### Dropzone
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `acceptedFileExtensions` | `string[]` |  |  | The accepted file extensions for the Drag-and-Drop. |
+| `dropZoneOptions` | `DropzoneOptions` | ✅ |  | Props for the underlying `react-dropzone` component. Don't use `accept`. If using custom file extensions as this option is broken. Instead use the `acceptedFileExtensions` property. |
+| `heading` | `ReactNode` |  |  | Use when wanting a custom heading. |
+| `loadingElement` | `ReactNode` |  |  | Element to display when uploading the file. |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+| `rejectedText` | `ReactNode` |  |  | Message to be shown when file is rejected. |
+| `supportedFilesDescription` | `ReactNode` |  |  | Informational text that highlights the supported file types, will be displayed in the footer. |
+
+Where `DropzoneOptions` is the props for the `react-dropzone` library. For more information, see the [react-dropzone documentation](https://react-dropzone.js.org/#src).
+
+### Dropzone.LoadingProgressBar
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `progressBarMinute` | `number` |  |  | The time in minute left to upload the file. |
+| `progressBarPrecentage` | `number` | ✅ |  | The percentage of the progress bar. |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+
+## Examples
+
+### Default
+
+```tsx
+import { Dropzone } from '@neo4j-ndl/react';
+import { type DropzoneOptions } from 'react-dropzone';
+
+const Component = () => {
+  const onDrop: DropzoneOptions['onDrop'] = (files) => {
+    alert(
+      `attempted to upload ${
+        files.length
+      } file(s). Check console logs for more info`,
+    );
+  };
+
+  return (
+    <Dropzone
+      dropZoneOptions={{
+        onDrop,
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Csv Files
+
+```tsx
+import { Dropzone } from '@neo4j-ndl/react';
+import { type DropzoneOptions } from 'react-dropzone';
+
+const Component = () => {
+  const onDrop: DropzoneOptions['onDrop'] = (files) => {
+    alert(
+      `attempted to upload ${
+        files.length
+      } file(s). Check console logs for more info`,
+    );
+  };
+
+  return (
+    <Dropzone
+      supportedFilesDescription="Supports: CSV"
+      dropZoneOptions={{
+        accept: { 'text/csv': ['.csv'] },
+        onDrop,
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Custom Extensions
+
+```tsx
+import { Dropzone } from '@neo4j-ndl/react';
+import { type DropzoneOptions } from 'react-dropzone';
+
+const Component = () => {
+  const onDrop: DropzoneOptions['onDrop'] = (files) => {
+    alert(
+      `attempted to upload ${
+        files.length
+      } file(s). Check console logs for more info`,
+    );
+  };
+
+  return (
+    <Dropzone
+      supportedFilesDescription="Supports: .dump"
+      acceptedFileExtensions={['.dump']}
+      dropZoneOptions={{
+        onDrop,
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import { Dropzone } from '@neo4j-ndl/react';
+import { type DropzoneOptions } from 'react-dropzone';
+
+const Component = () => {
+  const onDrop: DropzoneOptions['onDrop'] = (files) => {
+    alert(
+      `attempted to upload ${
+        files.length
+      } file(s). Check console logs for more info`,
+    );
+  };
+
+  return (
+    <Dropzone
+      supportedFilesDescription="Supports: CSV Files"
+      dropZoneOptions={{
+        accept: { 'text/csv': ['.csv'] },
+        disabled: true,
+        onDrop,
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Full
+
+```tsx
+import { XMarkIcon } from '@heroicons/react/24/solid';
+import { Dropzone, FilledButton, Typography } from '@neo4j-ndl/react';
+import { useCallback, useState } from 'react';
+import {
+  type DropEvent,
+  type DropzoneOptions,
+  type FileRejection,
+} from 'react-dropzone';
+
+// Configuration constants
+const CONFIG = {
+  MAX_FILES: 3,
+  MAX_FILE_SIZE: 5 * 1024 * 1024, // 5MB
+  PROGRESS_INCREMENT: 5,
+  UPDATE_INTERVAL: 100,
+  ACCEPTED_EXTENSIONS: ['.txt', '.json'] as string[],
+} as const;
+
+enum UploadState {
+  Idle = 'idle',
+  Uploading = 'uploading',
+  Success = 'success',
+  Error = 'error',
+}
+
+interface UploadData {
+  state: UploadState;
+  progress: number;
+  files: File[];
+  errors: string[];
+}
+
+const Component = () => {
+  const [uploadData, setUploadData] = useState<UploadData>({
+    errors: [],
+    files: [],
+    progress: 0,
+    state: UploadState.Idle,
+  });
+
+  const resetUpload = useCallback(() => {
+    setUploadData({
+      errors: [],
+      files: [],
+      progress: 0,
+      state: UploadState.Idle,
+    });
+  }, []);
+
+  const simulateUpload = useCallback((files: File[]) => {
+    setUploadData((prev) => ({
+      ...prev,
+      state: UploadState.Uploading,
+      files,
+      progress: 0,
+    }));
+
+    const interval = setInterval(() => {
+      setUploadData((prev) => {
+        const newProgress = prev.progress + CONFIG.PROGRESS_INCREMENT;
+        if (newProgress >= 100) {
+          clearInterval(interval);
+          setTimeout(
+            () =>
+              setUploadData((current) => ({
+                ...current,
+                state: UploadState.Success,
+              })),
+            500,
+          );
+          return { ...prev, progress: 100 };
+        }
+        return { ...prev, progress: newProgress };
+      });
+    }, CONFIG.UPDATE_INTERVAL);
+  }, []);
+
+  const handleDrop: DropzoneOptions['onDrop'] = useCallback(
+    (
+      acceptedFiles: File[],
+      rejectedFiles: FileRejection[],
+      event: DropEvent,
+    ) => {
+      console.info('Drop event:', { acceptedFiles, event, rejectedFiles });
+
+      if (acceptedFiles.length > 0) {
+        simulateUpload(acceptedFiles);
+      }
+    },
+    [simulateUpload],
+  );
+
+  const handleDropRejected: DropzoneOptions['onDropRejected'] = useCallback(
+    (rejectedFiles: FileRejection[]) => {
+      const errors = rejectedFiles.map(
+        (file) =>
+          `${file.file.name}: ${file.errors.map((e) => e.message).join(', ')}`,
+      );
+      setUploadData((prev) => ({ ...prev, state: UploadState.Error, errors }));
+    },
+    [],
+  );
+
+  const handleError = useCallback((error: Error) => {
+    console.error('Dropzone error:', error);
+    setUploadData((prev) => ({
+      ...prev,
+      state: UploadState.Error,
+      errors: [error.message],
+    }));
+  }, []);
+
+  const renderStatusContent = () => {
+    const { state, progress, files, errors } = uploadData;
+
+    switch (state) {
+      case UploadState.Uploading:
+        return (
+          <Dropzone.LoadingProgressBar
+            progressBarPrecentage={Math.round(progress)}
+          />
+        );
+
+      case UploadState.Success:
+        return (
+          <div className="n-flex n-flex-col n-justify-center n-items-center n-gap-y-token-32">
+            <Typography
+              variant="title-4"
+              className="n-text-success-text n-font-semibold"
+            >
+              Upload Complete!
+            </Typography>
+            <Typography
+              variant="body-small"
+              className="n-text-neutral-text-weak"
+            >
+              Successfully uploaded: {files.map((file) => file.name).join(', ')}
+            </Typography>
+            <FilledButton onClick={resetUpload}>Upload More Files</FilledButton>
+          </div>
+        );
+
+      case UploadState.Error:
+        return (
+          <div className="n-flex n-flex-col n-justify-center n-items-center n-gap-y-token-32">
+            <XMarkIcon className="n-w-token-32 n-h-token-32 n-text-danger-text" />
+            <div className="n-flex n-flex-col n-gap-y-token-2">
+              {errors.map((message, index) => (
+                <Typography
+                  key={index}
+                  variant="label"
+                  className="n-text-danger-text n-font-semibold"
+                  htmlAttributes={{ role: 'alert' }}
+                >
+                  {message}
+                </Typography>
+              ))}
+            </div>
+            <FilledButton onClick={resetUpload}>Try Again</FilledButton>
+          </div>
+        );
+
+      default:
+        return undefined;
+    }
+  };
+
+  return (
+    <Dropzone
+      dropZoneOptions={{
+        disabled: uploadData.state === UploadState.Uploading,
+        maxFiles: CONFIG.MAX_FILES,
+        maxSize: CONFIG.MAX_FILE_SIZE,
+        multiple: true,
+        onDrop: handleDrop,
+        onDropRejected: handleDropRejected,
+        onError: handleError,
+      }}
+      supportedFilesDescription={
+        <div className="n-text-center n-flex n-flex-col n-gap-y-token-2">
+          <Typography variant="body-small" className="n-text-neutral-text-weak">
+            Supports: Text files (.txt, .json) only
+          </Typography>
+          <Typography variant="body-small" className="n-text-neutral-text-weak">
+            Max {CONFIG.MAX_FILES} files •{' '}
+            {CONFIG.MAX_FILE_SIZE / (1024 * 1024)}MB per file
+          </Typography>
+        </div>
+      }
+      acceptedFileExtensions={CONFIG.ACCEPTED_EXTENSIONS}
+      loadingElement={renderStatusContent()}
+      rejectedText="Error: Please make sure to only upload .json or .txt files"
+      heading="Drag & Drop your files"
+    />
+  );
+};
+
+export default Component;
+```
+
+### Loading Progress
+
+```tsx
+import { Dropzone } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Dropzone
+      loadingElement={
+        <Dropzone.LoadingProgressBar
+          progressBarPrecentage={50}
+          progressBarMinute={5}
+        />
+      }
+      dropZoneOptions={{
+        onDrop: () => void 0,
+      }}
+    />
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,26 @@
+# FilledButton
+
+Import: `import { FilledButton } from '@neo4j-ndl/react'`
+
+## Props
+
+### FilledButton
+
+| 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' \| 'primary'` |  | `primary` | Variant of the button |

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

@@ -0,0 +1,82 @@
+# Flex
+
+Import: `import { Flex } from '@neo4j-ndl/react'`
+
+## Props
+
+### Flex
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `alignItems` | `AlignItems` |  | `undefined` | @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items |
+| `as` | `'div' \| 'li' \| 'ol' \| 'span' \| 'ul'` |  |  | 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` |  |  |  |
+| `columnGap` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `undefined` |  |
+| `flexDirection` | `'-moz-initial' \| 'column' \| 'inherit' \| 'initial' \| 'revert-layer' \| 'revert' \| 'row' \| 'unset'` |  | `column` | Flex direction is set to column by default. The `row-reverse` and `column-reverse` values are skipped due to accessibility concerns. @see https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction#accessibility_concerns |
+| `flexWrap` | `'-moz-initial' \| 'inherit' \| 'initial' \| 'nowrap' \| 'revert-layer' \| 'revert' \| 'unset' \| 'wrap-reverse' \| 'wrap'` |  | `nowrap` | @see https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap |
+| `gap` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `8` |  |
+| `justifyContent` | `JustifyContent` |  | `undefined` | @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content |
+| `ref` | `((instance: HTMLDivElement \| null) => void \| (() => VoidOrUndefinedOnly)) \| RefObject<HTMLDivElement \| null> \| ... 9 more ...` |  |  | A ref to apply to the root element. |
+| `rowGap` | `'12' \| '16' \| '2' \| '20' \| '24' \| '32' \| '4' \| '48' \| '6' \| '64' \| '8'` |  | `undefined` |  |
+
+## Examples
+
+### Default
+
+```tsx
+import { tokens } from '@neo4j-ndl/base';
+import { Box, Flex } from '@neo4j-ndl/react';
+
+const Tiles = `
+  linear-gradient(
+    45deg,
+    var(--theme-color-neutral-bg-strong) 25%,
+    transparent 25%
+  ),
+  linear-gradient(
+    135deg,
+    var(--theme-color-neutral-bg-strong) 25%,
+    transparent 25%
+  ),
+  linear-gradient(
+    45deg,
+    transparent 75%,
+    var(--theme-color-neutral-bg-strong) 75%
+  ),
+  linear-gradient(
+    135deg,
+    transparent 75%,
+    var(--theme-color-neutral-bg-strong) 75%
+  )
+`;
+
+const TiledTransparentBackground: React.CSSProperties = {
+  backgroundColor: 'white',
+  backgroundImage: Tiles,
+  backgroundPosition: '0px 0px, 10px 0px, 10px -10px, 0px 10px',
+  backgroundSize: '20px 20px',
+  border: '1px solid var(--theme-color-neutral-border-weak)',
+};
+
+const component = () => (
+  <Flex
+    style={{
+      ...TiledTransparentBackground,
+      borderRadius: tokens.borderRadius['xl'],
+      padding: tokens.space['12'],
+    }}
+  >
+    {Array.from({ length: 3 }).map((_, i) => (
+      <Box
+        key={`box-${i}`}
+        borderRadius="xl"
+        style={{ height: '80px', minWidth: '240px' }}
+        className="n-bg-primary-bg-weak n-border n-border-primary-border-strong"
+      ></Box>
+    ))}
+  </Flex>
+);
+
+export default component;
+```