@neo4j-ndl/react 4.16.7 → 4.16.9

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

@@ -0,0 +1,274 @@
+# Skeleton
+
+Import: `import { Skeleton } from '@neo4j-ndl/react'`
+
+## Props
+
+### Skeleton
+
+| 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 inside the skeleton. Size is inherited from the children if height or width are not provided. |
+| `height` | `string` |  |  | Height of the skeleton |
+| `isLoading` | `boolean` |  | `true` | Whether the skeleton is loading |
+| `onBackground` | `'default' \| 'weak'` |  | `default` | What background the skeleton is placed on. |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `shape` | `'circular' \| 'rectangular'` |  | `rectangular` | Shape of the skeleton |
+| `width` | `string` |  |  | Width of the skeleton |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Skeleton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-4">
+      <Skeleton height="50px" width="100%" />
+      <Skeleton height="30px" width="80%" />
+      <Skeleton height="20px" width="60%" />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Circular
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Skeleton } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-4 n-items-center">
+      <Skeleton shape="circular" height="50px" width="50px" />
+      <Skeleton shape="circular" height="40px" width="40px" />
+      <Skeleton shape="circular" height="30px" width="30px" />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Full Example
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Skeleton, TextButton, Typography } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-row n-gap-2">
+      <div className="n-flex n-flex-col n-gap-2 n-bg-neutral-bg-weak n-shadow-light-raised n-w-72 n-rounded-2xl n-p-2">
+        <div className="n-bg-neutral-bg-default n-flex n-items-center n-justify-center n-h-36 n-rounded-2xl n-mb-4">
+          <svg
+            width="48"
+            height="48"
+            viewBox="0 0 48 48"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <g clipPath="url(#clip0_5044_6981)">
+              <path
+                d="M1.5 33.75C1.5 35.1424 2.05312 36.4777 3.03769 37.4623C4.02226 38.4469 5.35761 39 6.75 39C8.14239 39 9.47774 38.4469 10.4623 37.4623C11.4469 36.4777 12 35.1424 12 33.75C12 32.3576 11.4469 31.0223 10.4623 30.0377C9.47774 29.0531 8.14239 28.5 6.75 28.5C5.35761 28.5 4.02226 29.0531 3.03769 30.0377C2.05312 31.0223 1.5 32.3576 1.5 33.75V33.75Z"
+                stroke="#4C99A4"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M36 33.75C36 34.4394 36.1358 35.1221 36.3996 35.7591C36.6635 36.396 37.0502 36.9748 37.5377 37.4623C38.0252 37.9498 38.604 38.3365 39.2409 38.6004C39.8779 38.8642 40.5606 39 41.25 39C41.9394 39 42.6221 38.8642 43.2591 38.6004C43.896 38.3365 44.4748 37.9498 44.9623 37.4623C45.4498 36.9748 45.8365 36.396 46.1004 35.7591C46.3642 35.1221 46.5 34.4394 46.5 33.75C46.5 33.0606 46.3642 32.3779 46.1004 31.7409C45.8365 31.104 45.4498 30.5252 44.9623 30.0377C44.4748 29.5502 43.896 29.1635 43.2591 28.8996C42.6221 28.6358 41.9394 28.5 41.25 28.5C40.5606 28.5 39.8779 28.6358 39.2409 28.8996C38.604 29.1635 38.0252 29.5502 37.5377 30.0377C37.0502 30.5252 36.6635 31.104 36.3996 31.7409C36.1358 32.3779 36 33.0606 36 33.75Z"
+                stroke="#4C99A4"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M18.75 33.75C18.75 35.1424 19.3031 36.4777 20.2877 37.4623C21.2723 38.4469 22.6076 39 24 39C25.3924 39 26.7277 38.4469 27.7123 37.4623C28.6969 36.4777 29.25 35.1424 29.25 33.75C29.25 32.3576 28.6969 31.0223 27.7123 30.0377C26.7277 29.0531 25.3924 28.5 24 28.5C22.6076 28.5 21.2723 29.0531 20.2877 30.0377C19.3031 31.0223 18.75 32.3576 18.75 33.75V33.75Z"
+                stroke="#4C99A4"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M15.376 46.5C14.8905 45.1818 14.1085 43.9928 13.0906 43.0247C12.0727 42.0566 10.846 41.3353 9.50508 40.9165C8.1642 40.4977 6.74503 40.3926 5.35707 40.6092C3.96911 40.8258 2.64948 41.3585 1.5 42.1659"
+                stroke="#4C99A4"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M32.626 46.5C33.1113 45.1818 33.893 43.9928 34.9107 43.0248C35.9284 42.0567 37.155 41.3354 38.4957 40.9165C39.8365 40.4977 41.2555 40.3926 42.6434 40.6092C44.0312 40.8258 45.3507 41.3585 46.5 42.166"
+                stroke="#4C99A4"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M32.626 46.5C31.9729 44.7387 30.7962 43.2195 29.2541 42.1467C27.7121 41.0738 25.8786 40.4988 24 40.4988C22.1215 40.4988 20.288 41.0738 18.7459 42.1467C17.2039 43.2195 16.0272 44.7387 15.374 46.5"
+                stroke="#4C99A4"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M28.5 22.5C28.5 22.5 30 15 36 13.5"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M40.5 12H46.5"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M43.5 9V15"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M19.5 22.5C19.5 22.5 18 15 12 13.5"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M7.5 12H1.5"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M4.5 9V15"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M21 4.5H27"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M24 1.5V7.5"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M24 22.5V13.5"
+                stroke="#5CC3C9"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+            </g>
+            <defs>
+              <clipPath id="clip0_5044_6981">
+                <rect width="48" height="48" fill="white" />
+              </clipPath>
+            </defs>
+          </svg>
+        </div>
+        <Typography variant="title-3">Customer stories</Typography>
+        <Typography variant="body-medium">
+          Customer success stories across industries
+        </Typography>
+        <TextButton className="n-w-fit">Go to case studies</TextButton>
+      </div>
+      <div className="n-flex n-flex-col n-gap-2 n-bg-neutral-bg-weak n-shadow-light-raised n-w-72 n-rounded-2xl n-p-2">
+        <Skeleton
+          shape="rectangular"
+          className="n-w-full n-h-36 n-rounded-2xl n-mb-4"
+          onBackground="weak"
+        />
+        <div className="n-flex n-flex-col n-gap-2">
+          <Skeleton
+            shape="rectangular"
+            className="n-w-full"
+            onBackground="weak"
+            width="80%"
+          >
+            <Typography variant="title-3">Customer stories</Typography>
+          </Skeleton>
+          <Skeleton className="n-w-full" onBackground="weak" width="60%">
+            <Typography variant="body-medium">Customer</Typography>
+          </Skeleton>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Inherit Height
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Skeleton, Typography } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-4">
+      <Skeleton>
+        <Typography variant="display">Large display text</Typography>
+      </Skeleton>
+      <Skeleton>
+        <Typography variant="body-medium">Regular body text</Typography>
+      </Skeleton>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Inherit Width
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Skeleton, Typography } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-4">
+      <Skeleton shape="rectangular">
+        <Typography variant="body-medium">
+          This text determines the skeleton width
+        </Typography>
+      </Skeleton>
+      <Skeleton shape="rectangular">
+        <Typography variant="title-3">Shorter text</Typography>
+      </Skeleton>
+    </div>
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,308 @@
+# Slider
+
+Import: `import { Slider } from '@neo4j-ndl/react'`
+
+## Props
+
+### Slider
+
+| 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. |
+| `inputProps` | `HtmlAttributes<"input">` |  | `{}` | Input props of the underlying input element |
+| `isDisabled` | `boolean` |  | `false` | Whether the slider is disabled |
+| `maxValue` | `number` |  | `100` | The maximum value possible to choose |
+| `minValue` | `number` |  | `0` | The minimum value possible to choose |
+| `onChange` | `((value: number) => void) \| ((value: [number, number]) => void)` | ✅ |  | Callback function triggered when the slider value(s) changes. The function parameter varies depending on the slider type, for single slider, it is a number and for range slider, it is an array of two numbers. |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `showSteps` | `boolean` |  | `false` | Whether to display visual indicators for each step in the slider |
+| `showValues` | `boolean` |  | `false` | Whether to display a tooltip with the current value when the slider is being dragged |
+| `step` | `number` |  | `1` | Determines the step size that will be added or removed from the current value when moving the slider button |
+| `type` | `'range' \| 'single'` |  | `single` | Type of the slider |
+| `value` | `number` | ✅ |  | Current value of the single slider. **Only required when the type is 'single'**. |
+| `values` | `[number, number]` | ✅ |  | Current values of the range slider as an array of two numbers `[min, max]`. **Only required when the type is 'range'**. |
+
+The `type` prop is used to determine the type of the slider. It can be `single` or `range`. The `value` prop is required when the `type` is `single` and `values` is required when the `type` is `range`. It also affects the `onChange` prop type.
+
+## Accessibility
+
+## Implementation guidelines
+
+The Slider component is built with full accessibility support using React Aria. It includes proper ARIA attributes, keyboard navigation support, and focus management. Users can interact with the slider using:
+
+ - **Mouse/Touch**: Click and drag the thumb(s) to adjust values
+- **Keyboard**: Use arrow keys to increment/decrement values, Home/End keys to jump to min/max values
+- **Screen Readers**: Proper ARIA labels and value announcements
+
+The component supports explicit and custom `aria-valuetext` through the `inputProps` for enhanced screen reader experience.
+
+## Examples
+
+### Default
+
+```tsx
+import { Slider } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Slider
+      minValue={0}
+      maxValue={100}
+      value={50}
+      onChange={(newValue) => {
+        console.info('onChange', newValue);
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Custom Step Length
+
+```tsx
+import { Slider } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Slider
+      minValue={0}
+      maxValue={100}
+      step={10}
+      value={50}
+      onChange={(newValue) => {
+        console.info('onChange', newValue);
+      }}
+      showSteps
+      showValues
+    />
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import { Slider } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Slider
+      minValue={0}
+      maxValue={100}
+      step={10}
+      value={50}
+      onChange={(newValue) => {
+        console.info('onChange', newValue);
+      }}
+      isDisabled
+    />
+  );
+};
+
+export default Component;
+```
+
+### Range
+
+```tsx
+import { Slider } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Slider
+      type="range"
+      values={[10, 50]}
+      onChange={(newValue) => {
+        console.info('onChange', newValue);
+      }}
+      minValue={0}
+      maxValue={200}
+      step={10}
+      isDisabled={false}
+      showSteps={true}
+      showValues={true}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Show Steps
+
+```tsx
+import { Slider } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Slider
+      minValue={0}
+      maxValue={100}
+      value={50}
+      onChange={(newValue) => {
+        console.info('onChange', newValue);
+      }}
+      showSteps
+    />
+  );
+};
+
+export default Component;
+```
+
+### Show Values
+
+```tsx
+import { Slider } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Slider
+      minValue={0}
+      maxValue={100}
+      value={50}
+      onChange={(newValue) => {
+        console.info('onChange', newValue);
+      }}
+      showValues
+    />
+  );
+};
+
+export default Component;
+```
+
+### Single
+
+```tsx
+import { Slider } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Slider
+      type="single"
+      value={100}
+      onChange={(newValue) => {
+        console.info('onChange', newValue);
+      }}
+      minValue={0}
+      maxValue={200}
+      isDisabled={false}
+      step={10}
+      showSteps={true}
+      showValues={true}
+      inputProps={{ 'aria-valuetext': 'percent' }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Single Controlled
+
+```tsx
+import { Slider, TextInput } from '@neo4j-ndl/react';
+import { useCallback, useState } from 'react';
+
+const MIN_VALUE = 0;
+const MAX_VALUE = 100;
+const STEP = 5;
+const INITIAL_VALUE = 50;
+
+const getValidationError = (
+  input: string,
+): { error: string; isValid: false } | { error: undefined; isValid: true } => {
+  const trimmed = input.trim();
+
+  if (!trimmed) {
+    return { error: 'Value is required', isValid: false };
+  }
+
+  const numValue = Number(trimmed);
+  if (isNaN(numValue)) {
+    return { error: 'Please enter a valid number', isValid: false };
+  }
+
+  if (!Number.isInteger(numValue)) {
+    return { error: 'Please enter a whole number', isValid: false };
+  }
+
+  if (numValue < MIN_VALUE) {
+    return { error: `Value must be at least ${MIN_VALUE}`, isValid: false };
+  }
+
+  if (numValue > MAX_VALUE) {
+    return { error: `Value must be at most ${MAX_VALUE}`, isValid: false };
+  }
+
+  return { error: undefined, isValid: true };
+};
+
+const Component = () => {
+  const [value, setValue] = useState(INITIAL_VALUE);
+  const [inputValue, setInputValue] = useState(String(INITIAL_VALUE));
+  const { error, isValid } = getValidationError(inputValue);
+  const hasError = !isValid;
+
+  const handleInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const newInputValue = e.target.value;
+      setInputValue(newInputValue);
+
+      if (isValid) {
+        setValue(Number(newInputValue));
+      }
+    },
+    [setInputValue, setValue, isValid],
+  );
+
+  const handleSliderChange = useCallback(
+    (newValue: number) => {
+      setValue(newValue);
+      setInputValue(String(newValue));
+    },
+    [setInputValue, setValue],
+  );
+
+  return (
+    <div className="n-flex n-flex-col n-gap-token-16">
+      <TextInput
+        label="Slider value"
+        helpText={`Enter a value between ${MIN_VALUE} and ${MAX_VALUE}`}
+        isRequired
+        errorText={error}
+        htmlAttributes={{
+          max: MAX_VALUE,
+          min: MIN_VALUE,
+          step: STEP,
+          type: 'number',
+        }}
+        value={inputValue}
+        onChange={handleInputChange}
+      />
+
+      <Slider
+        type="single"
+        value={value}
+        onChange={handleSliderChange}
+        minValue={MIN_VALUE}
+        maxValue={MAX_VALUE}
+        step={STEP}
+        showSteps
+        showValues
+        isDisabled={hasError}
+        inputProps={{
+          'aria-valuetext': `${value} out of ${MAX_VALUE}`,
+        }}
+      />
+    </div>
+  );
+};
+
+export default Component;
+```