@neo4j-ndl/react 4.16.7 → 4.16.9

package/skills/ndl-react/components/inline-edit.md

@@ -0,0 +1,209 @@
+# InlineEdit
+
+Import: `import { InlineEdit } from '@neo4j-ndl/react'`
+
+## Props
+
+### InlineEdit
+
+| 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. |
+| `blurBehavior` | `'cancel' \| 'confirm' \| 'none'` |  | `confirm` | What the input should do on blur - "confirm" will confirm the value - "cancel" will cancel the value - "none" will do nothing |
+| `defaultValue` | `string` |  |  | The default input value. Use for an uncontrolled component. |
+| `hasEditIcon` | `boolean` |  | `false` | If edit pencil icon should be visible on hover |
+| `inputProps` | `HtmlAttributes<"input">` |  |  | props applied to the internal input element |
+| `isDisabled` | `boolean` |  | `false` |  |
+| `isEditing` | `boolean` |  | `undefined` | If the input is in editing mode Used in a stateless inline edit |
+| `isFluid` | `boolean` |  | `false` | If the input is fluid |
+| `label` | `ReactNode` |  |  | Label text |
+| `onCancel` | `((event?: MouseEvent<HTMLElement, MouseEvent> \| KeyboardEvent<HTMLElement>) => void)` |  |  | Callback when cancel icon button is pressed |
+| `onChange` | `((value: string) => void)` |  |  | Callback when the input value changes. Must be used when the component is controlled. |
+| `onConfirm` | `((value: string, event?: MouseEvent<HTMLElement, MouseEvent> \| KeyboardEvent<HTMLElement>) => void)` |  |  | Callback when confirm icon button is pressed |
+| `placeholder` | `string` | ✅ |  | Placeholder text displayed when the input is empty. |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `typographyVariant` | `'body-large' \| 'body-medium' \| 'body-small' \| 'code' \| 'display' \| 'label' \| 'subheading-large' \| 'subheading-medium' \| 'subheading-small' \| 'title-1' \| 'title-2' \| 'title-3' \| 'title-4'` |  | `subheading-medium` | The typographyVariant of the component applied to Typography as its variant. |
+| `value` | `string` |  |  | The input value. Makes the component controlled. |
+
+## Accessibility
+
+## Implementation guidelines
+
+The InlineEdit component provides an accessible inline editing experience. It includes proper ARIA labels, keyboard navigation support (Enter to confirm, Escape to cancel), and focus management. The component supports both controlled and uncontrolled modes, with appropriate screen reader announcements for state changes.
+
+## Examples
+
+### Default
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [value, setValue] = useState('Database Name 1');
+
+  return (
+    <InlineEdit
+      label="Editable inline edit ✨"
+      placeholder="Placeholder"
+      defaultValue={value}
+      onConfirm={setValue}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Controlled Editing
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <InlineEdit
+      isEditing={true}
+      label="Controlled Editing"
+      placeholder="Placeholder"
+      defaultValue="Database Name 1"
+    />
+  );
+};
+
+export default Component;
+```
+
+### Controlled Value
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+import { useRef, useState } from 'react';
+
+const Component = () => {
+  const initialValue = 'Controlled Value';
+  const [value, setValue] = useState(initialValue);
+  const previousValueRef = useRef(initialValue);
+
+  return (
+    <InlineEdit
+      label="Controlled value"
+      placeholder="Placeholder"
+      value={value}
+      onChange={setValue}
+      onConfirm={(newValue, event) => {
+        previousValueRef.current = newValue;
+        event?.stopPropagation();
+      }}
+      onCancel={(event) => {
+        setValue(previousValueRef.current);
+        event?.stopPropagation();
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+
+const Component = () => (
+  <InlineEdit
+    defaultValue="Database Name 1"
+    isDisabled={true}
+    label="Disabled inline edit ⛔"
+    placeholder="Placeholder"
+  />
+);
+
+export default Component;
+```
+
+### Fluid
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <InlineEdit
+      label="Inline edit with fluid width"
+      placeholder="Placeholder"
+      defaultValue="hello"
+      isFluid={true}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Header
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <InlineEdit
+      defaultValue="Database Name 1"
+      typographyVariant="display"
+      placeholder="Placeholder"
+    />
+  );
+};
+
+export default Component;
+```
+
+### No Confirm On Blur
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+
+const Component = () => (
+  <InlineEdit
+    label="Doesn't confirm input on blur"
+    defaultValue="Database Name 1"
+    blurBehavior="none"
+    placeholder="Placeholder"
+  />
+);
+
+export default Component;
+```
+
+### With Edit Icon
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+
+const Component = () => (
+  <InlineEdit
+    defaultValue="Database Name 1"
+    hasEditIcon={true}
+    label="Inline Edit with Hover Icon"
+    placeholder="Placeholder"
+  />
+);
+export default Component;
+```
+
+### With Placeholder
+
+```tsx
+import { InlineEdit } from '@neo4j-ndl/react';
+
+const Component = () => (
+  <InlineEdit
+    placeholder="Placeholder text"
+    label="Placeholder is displayed when defaultValue is empty"
+  />
+);
+
+export default Component;
+```

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

@@ -0,0 +1,63 @@
+# Kbd
+
+Import: `import { Kbd } from '@neo4j-ndl/react'`
+
+## Props
+
+### Kbd
+
+| 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. |
+| `keys` | `ReactNode[]` |  |  | The main keys to display in the keyboard shortcut. |
+| `modifierKeys` | `KbdKey[]` |  |  | The modifier keys to display in the keyboard shortcut. |
+| `os` | `'linux' \| 'mac' \| 'windows'` |  |  | Override the operating system detection for key symbols |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+
+## Accessibility
+
+## WAI-ARIA roles and attributes
+
+- Renders as a [`<kbd>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/kbd) element by default, which is the semantic HTML element for keyboard input
+- Visual key symbols (e.g. `⌘`, `⇧`) are marked with `aria-hidden="true"` so screen readers skip them
+- A screen-reader-friendly text is generated automatically (e.g. "Shortcut: Command + Shift + K") and rendered in a visually hidden span
+
+## Implementation guidelines
+
+- The component handles screen reader announcements internally so no additional ARIA attributes are needed
+- If `modifierKeys` and `keys` are both omitted, the component renders an empty announcement. Always provide at least one of them
+- When using custom `keys` content (e.g. React elements instead of strings), the screen reader text may not resolve correctly. Use string values where possible
+
+### Related WCAG criteria
+
+- [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A): The visual key symbols are non-text content so the component provides a screen-reader-friendly text alternative automatically, but custom React element keys may result in an empty announcement
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Kbd } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Kbd modifierKeys={['meta', 'shift']} keys={['A']} />;
+};
+
+export default Component;
+```
+
+### Sequence
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Kbd } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Kbd keys={['P', '1']} />;
+};
+
+export default Component;
+```

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

@@ -0,0 +1,43 @@
+# LoadingBar
+
+Import: `import { LoadingBar } from '@neo4j-ndl/react'`
+
+## Props
+
+### LoadingBar
+
+| 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. |
+| `hasRail` | `boolean` |  | `false` |  |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { LoadingBar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <LoadingBar />;
+};
+
+export default Component;
+```
+
+### With Rail
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { LoadingBar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <LoadingBar hasRail />;
+};
+
+export default Component;
+```

package/skills/ndl-react/components/loading-spinner.md

@@ -0,0 +1,57 @@
+# LoadingSpinner
+
+Import: `import { LoadingSpinner } from '@neo4j-ndl/react'`
+
+## Props
+
+### LoadingSpinner
+
+| 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. |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'medium' \| 'small'` |  | `small` |  |
+
+## Accessibility
+
+## Implementation guidelines
+
+The loading spinner component uses `role='status'` and `aria-label='Loading content'` to notify assistive technologies that a background process is occurring. The `aria-live='polite'` setting ensures screen readers announce the message non-intrusively when the spinner appears or updates. This informs users that content is loading without interrupting their workflow.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { LoadingSpinner } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <LoadingSpinner />;
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { LoadingSpinner } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-token-16">
+      <LoadingSpinner size="small" />
+
+      <LoadingSpinner size="medium" />
+
+      <LoadingSpinner size="large" />
+    </div>
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,57 @@
+# Logo
+
+Import: `import { Logo } from '@neo4j-ndl/react'`
+
+## Props
+
+### Logo
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `color` | `'black' \| 'color' \| 'white'` |  |  |  |
+| `ref` | `Ref<SVGSVGElement>` |  |  | A ref to apply to the root element. |
+| `type` | `'full' \| 'icon'` |  | `full` |  |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Logo } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Logo className="n-w-24" />;
+};
+
+export default Component;
+```
+
+### Black
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Logo } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Logo className="n-w-24" color="black" />;
+};
+
+export default Component;
+```
+
+### Icon
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Logo } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Logo className="n-w-24" type="icon" />;
+};
+
+export default Component;
+```