@neo4j-ndl/react 4.16.8 → 4.16.9

package/skills/ndl-react/components/code-block.md

@@ -0,0 +1,276 @@
+# CodeBlock
+
+Import: `import { CodeBlock } from '@neo4j-ndl/react'`
+
+## Props
+
+### CodeBlock
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `actions` | `(IconButtonButtonProps & { as?: "button"; } & BaseProps<"button">)[]` |  |  |  |
+| `as` | `ElementType<any, keyof IntrinsicElements>` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. |
+| `code` | `string` | ✅ |  |  |
+| `heading` | `ReactNode` |  |  |  |
+| `isDisabled` | `boolean` |  |  |  |
+| `language` | `'asciidoc' \| 'bash' \| 'c' \| 'csharp' \| 'css-extras' \| 'css' \| 'cypher' \| 'docker' \| 'go' \| 'graphql' \| 'java' \| 'javadoc' \| 'javascript' \| 'json' \| 'jsx' \| 'kotlin' \| 'php' \| 'python' \| 'regex' \| 'rust' \| 'sql' \| 'text' \| 'typescript' \| 'xml' \| 'yaml'` | ✅ |  |  |
+| `maxHeight` | `number` |  |  |  |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `shouldShowLineNumbers` | `boolean` |  |  |  |
+| `theme` | `'base16-ateliersulphurpool.light' \| 'coy' \| 'duotone-light' \| 'ghcolors' \| 'ndl-code-dark' \| 'ndl-code-light' \| 'prism' \| 'solarizedlight' \| 'vs'` |  |  |  |
+
+## Examples
+
+### Code Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+
+import { SHORT_CODE_EXAMPLE } from './example-code-snippets';
+
+const Component = () => {
+  return <CodeBlock code={SHORT_CODE_EXAMPLE} language="typescript" />;
+};
+
+export default Component;
+```
+
+### Code Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+import {
+  PlayCircleIconOutline,
+  Square2StackIconOutline,
+} from '@neo4j-ndl/react/icons';
+
+import { SHORT_CODE_EXAMPLE } from './example-code-snippets';
+
+const Component = () => {
+  return (
+    <CodeBlock
+      code={SHORT_CODE_EXAMPLE}
+      language="typescript"
+      heading="Code Header"
+      isDisabled
+      actions={[
+        {
+          children: (
+            <Square2StackIconOutline className="n-text-neutral-text-icon" />
+          ),
+          description: 'copy',
+          htmlAttributes: { title: 'copy' },
+          onClick: () => alert('This should not trigger when disabled'),
+        },
+        {
+          children: <PlayCircleIconOutline className="n-text-primary-icon" />,
+          description: 'run',
+          htmlAttributes: { title: 'run' },
+          onClick: () => alert('This should not trigger when disabled'),
+        },
+      ]}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Code Full
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+import {
+  PlayCircleIconOutline,
+  Square2StackIconOutline,
+} from '@neo4j-ndl/react/icons';
+
+import { LONG_CODE_EXAMPLE } from './example-code-snippets';
+
+const Component = () => {
+  return (
+    <CodeBlock
+      code={LONG_CODE_EXAMPLE}
+      maxHeight={320}
+      language="typescript"
+      shouldShowLineNumbers
+      theme="ndl-code-light"
+      heading="Code Header"
+      actions={[
+        {
+          children: (
+            <Square2StackIconOutline className="n-text-neutral-text-icon" />
+          ),
+          description: 'copy',
+          htmlAttributes: { title: 'copy' },
+          onClick: () => alert('copied'),
+        },
+        {
+          children: <PlayCircleIconOutline className="n-text-primary-icon" />,
+          description: 'run',
+          htmlAttributes: { title: 'run' },
+          onClick: () => alert('running'),
+        },
+      ]}
+      isDisabled={false}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Code Languages
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+
+import { LANGUAGE_SYNTAX_HIGHLIGHTING_EXAMPLES } from './example-code-snippets';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-8">
+      <CodeBlock
+        code={LANGUAGE_SYNTAX_HIGHLIGHTING_EXAMPLES.TYPESCRIPT}
+        language="typescript"
+        heading="TypeScript"
+        shouldShowLineNumbers
+      />
+
+      <CodeBlock
+        code={LANGUAGE_SYNTAX_HIGHLIGHTING_EXAMPLES.CYPHER}
+        language="cypher"
+        heading="Cypher Query Language"
+        shouldShowLineNumbers
+      />
+
+      <CodeBlock
+        code={LANGUAGE_SYNTAX_HIGHLIGHTING_EXAMPLES.JSON}
+        language="json"
+        heading="JSON Configuration"
+        shouldShowLineNumbers
+      />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Code Overflow
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+
+import { LONG_CODE_EXAMPLE } from './example-code-snippets';
+
+const Component = () => {
+  return (
+    <CodeBlock
+      code={LONG_CODE_EXAMPLE}
+      language="typescript"
+      heading="Code Header"
+      maxHeight={320}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Code With Actions
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+import {
+  PlayCircleIconOutline,
+  Square2StackIconOutline,
+} from '@neo4j-ndl/react/icons';
+
+import { SHORT_CODE_EXAMPLE } from './example-code-snippets';
+
+const Component = () => {
+  return (
+    <CodeBlock
+      code={SHORT_CODE_EXAMPLE}
+      language="typescript"
+      maxHeight={320}
+      actions={[
+        {
+          children: (
+            <Square2StackIconOutline className="n-text-neutral-text-icon" />
+          ),
+          description: 'copy',
+          htmlAttributes: { title: 'copy' },
+          onClick: () => alert('Code copied to clipboard!'),
+        },
+        {
+          children: <PlayCircleIconOutline className="n-text-primary-icon" />,
+          description: 'run',
+          htmlAttributes: { title: 'run' },
+          onClick: () => alert('Running code...'),
+        },
+      ]}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Code With Header
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+
+import { SHORT_CODE_EXAMPLE } from './example-code-snippets';
+
+const Component = () => {
+  return (
+    <CodeBlock
+      code={SHORT_CODE_EXAMPLE}
+      language="typescript"
+      heading="Code Header"
+    />
+  );
+};
+
+export default Component;
+```
+
+### Code With Line Numbers
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CodeBlock } from '@neo4j-ndl/react';
+
+import { SHORT_CODE_EXAMPLE } from './example-code-snippets';
+
+const Component = () => {
+  return (
+    <CodeBlock
+      code={SHORT_CODE_EXAMPLE}
+      language="typescript"
+      heading="Code Header"
+      shouldShowLineNumbers
+    />
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,68 @@
+# Code
+
+Import: `import { Code } from '@neo4j-ndl/react'`
+
+## Props
+
+### Code
+
+| 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 content of the code |
+| `description` | `string` |  |  | The description of the code, will be displayed in a tooltip |
+| `isDisabled` | `boolean` |  | `false` | Whether the code is disabled |
+| `isRunnable` | `boolean` |  | `false` | Whether the code is runnable |
+| `onClick` | `((e: MouseEvent<HTMLElement, MouseEvent> \| KeyboardEvent<HTMLElement>) => void)` |  |  | The callback function triggered when the inline code is clicked |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+
+## Accessibility
+
+## Implementation guidelines
+
+For inline code, when interactive (`isRunnable` is true), the component becomes focusable and supports keyboard navigation with Enter and Space keys. When a `description` is provided, it's properly associated with the element via ARIA attributes.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Code } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Code
+      description="Copy to clipboard"
+      onClick={() => alert('Copied to clipboard')}
+    >
+      :help cypher
+    </Code>
+  );
+};
+
+export default Component;
+```
+
+### Runnable
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Code } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Code
+      isRunnable
+      description="Run query"
+      onClick={() => alert(`Executing: :help cypher`)}
+    >
+      :help cypher
+    </Code>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/color-picker.md

@@ -0,0 +1,131 @@
+# ColorPicker
+
+Import: `import { ColorPicker } from '@neo4j-ndl/react'`
+
+## Props
+
+### ColorPicker
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `color` | `` HsvaColor \| RgbaColor \| `#${string}` `` | ✅ |  | The current color value. Can be provided in HSVA, RGBA, or Hex format. The component will automatically convert between formats as needed. |
+| `onChange` | `` (newColor: { hex: `#${string}`; rgb: RgbaColor; hsva: HsvaColor; }) => void `` | ✅ |  | Callback function triggered when the color value changes. Receives an object containing the new color in all three formats (hex, rgb, hsva) for convenience. |
+| `shouldShowEyeDropper` | `boolean` |  | `true` | Whether to display the eye dropper tool that allows users to sample colors from anywhere on the screen. |
+| `swatches` | `` (HsvaColor \| RgbaColor \| `#${string}`)[] `` |  | `Object.values(tokens.graph).filter(validHex)` | Optional array of predefined color swatches for quick selection. Each swatch can be in HSVA, RGBA, or Hex format. |
+
+By default the `swatches` prop is set to the available graph colors (`tokens.graph`) from `@neo4j-ndl/base`.
+
+Where `HsvaColor`, `RgbaColor`, and `HexColor` types are from `@uiw/react-color`, and represent different color formats:
+
+- `HexColor`: A string in the format `#RRGGBB` (e.g., `#ff0000`).
+- `RgbaColor`: An object with numeric properties `{ r, g, b, a }` for red, green, blue (0–255), and alpha (0–1).
+- `HsvaColor`: An object with numeric properties `{ h, s, v, a }` for hue (0–360), saturation (0–100), value (0–100), and alpha (0–1).
+
+Visit [react-color](https://uiwjs.github.io/react-color/#/) for more information.
+
+## Examples
+
+### Default
+
+```tsx
+import { useState } from 'react';
+
+import { ColorPicker } from '../ColorPicker';
+
+const Component = () => {
+  const [color, setColor] = useState({
+    a: 1,
+    b: 0,
+    g: 0,
+    r: 0,
+  });
+
+  return (
+    <ColorPicker
+      color={color}
+      onChange={(newColor) => setColor(newColor.rgb)}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Custom Swatches
+
+```tsx
+import { useState } from 'react';
+
+import { ColorPicker } from '../ColorPicker';
+
+const Component = () => {
+  const [color, setColor] = useState({
+    a: 1,
+    b: 0,
+    g: 0,
+    r: 0,
+  });
+
+  return (
+    <ColorPicker
+      color={color}
+      onChange={(newColor) => setColor(newColor.rgb)}
+      swatches={[
+        {
+          a: 1,
+          b: 0,
+          g: 0,
+          r: 0,
+        },
+        {
+          a: 1,
+          b: 255,
+          g: 0,
+          r: 0,
+        },
+        {
+          a: 1,
+          b: 0,
+          g: 255,
+          r: 0,
+        },
+        {
+          a: 1,
+          b: 0,
+          g: 0,
+          r: 255,
+        },
+      ]}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Without Eyedropper
+
+```tsx
+import { useState } from 'react';
+
+import { ColorPicker } from '../ColorPicker';
+
+const Component = () => {
+  const [color, setColor] = useState({
+    a: 1,
+    b: 0,
+    g: 0,
+    r: 0,
+  });
+
+  return (
+    <ColorPicker
+      color={color}
+      onChange={(newColor) => setColor(newColor.rgb)}
+      shouldShowEyeDropper={false}
+    />
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/conditional-wrap.md

@@ -0,0 +1,46 @@
+# ConditionalWrap
+
+Import: `import { ConditionalWrap } from '@neo4j-ndl/react'`
+
+## Props
+
+### ConditionalWrap
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  | The children to potentially wrap |
+| `shouldWrap` | `boolean` | ✅ |  | If true, the children will be wrapped |
+| `wrap` | `(children: ReactNode) => ReactNode` | ✅ |  | Function that takes children and returns them wrapped in a component |
+
+## Examples
+
+### Default
+
+```tsx
+import { StatusLabel, Switch } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+import { ConditionalWrap } from '../ConditionalWrap';
+
+const Component = () => {
+  const [shouldWrap, setShouldWrap] = useState(false);
+
+  return (
+    <div className="n-flex n-flex-col n-gap-6">
+      <Switch
+        isChecked={shouldWrap}
+        onChange={() => setShouldWrap(!shouldWrap)}
+        label="shouldWrap"
+      />
+      <ConditionalWrap
+        shouldWrap={shouldWrap}
+        wrap={(children) => <StatusLabel>{children}</StatusLabel>}
+      >
+        Content
+      </ConditionalWrap>
+    </div>
+  );
+};
+
+export default Component;
+```