@neo4j-ndl/react 4.24.2 → 4.25.0

package/skills/ndl-react/components/checkbox-group.md

@@ -0,0 +1,195 @@
+[//]: # (This file is auto-generated by the docs:generate-skills script, do not edit it manually)
+
+# CheckboxGroup
+
+Import: `import { CheckboxGroup } from '@neo4j-ndl/react'`
+
+## Props
+
+### CheckboxGroup
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  | The controls grouped by the fieldset |
+| `errorText` | `ReactNode` |  |  | Error message displayed below the grouped controls. When provided, it replaces `helpText` |
+| `hasRequiredIndicator` | `boolean` |  |  | Whether Required or Optional is shown at the end of the legend row |
+| `hasVisuallyHiddenLabel` | `boolean` |  |  | Whether the legend is clipped out of the layout, leaving it to screen readers only |
+| `helpText` | `ReactNode` |  |  | Assistive text displayed below the grouped controls |
+| `isDisabled` | `boolean` |  | `false` | Whether all native form controls in the fieldset are disabled |
+| `isRequired` | `boolean` |  | `false` | Whether the grouped field is required |
+| `label` | `ReactNode` | ✅ |  | The accessible label displayed in the fieldset legend |
+| `name` | `string` |  |  | Shared native name for checkbox form values |
+| `ref` | `Ref<HTMLFieldSetElement>` |  |  | A ref to apply to the root element. |
+
+Checked state remains on each `Checkbox`. Browsers cannot natively validate
+an “at least one” checkbox requirement, so applications should set
+`errorText` after validating a required group.
+
+## Accessibility
+
+`CheckboxGroup` renders a native `<fieldset>` and `<legend>`. The legend names
+the group, while every `Checkbox` keeps its own label. A shared `name` can be
+provided when checked values should be submitted under the same form key.
+
+Each native checkbox remains a separate Tab stop and Space toggles the focused
+checkbox. `isDisabled` disables the fieldset and every descendant control.
+
+Browsers cannot express an “at least one checkbox” constraint with native
+`required`; applying `required` to every checkbox would require every option.
+Use `isRequired` for the group’s required presentation, validate the selected
+values in the application, and provide `errorText` when validation fails.
+“Required” is included in the legend's accessible name.
+
+Help and error text are associated with the group through `aria-describedby`;
+individual checkboxes retain only descriptions supplied directly to them. An
+error replaces help text and sets `aria-invalid` on the group and its
+checkboxes.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, CheckboxGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <CheckboxGroup
+      label="Notification channels"
+      name="notification-channel"
+      helpText="Choose every channel you want to use."
+    >
+      <Checkbox label="Email" value="email" isDefaultChecked />
+      <Checkbox label="In-app" value="in-app" />
+      <Checkbox label="Mobile push" value="push" />
+    </CheckboxGroup>
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, CheckboxGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <CheckboxGroup
+      label="Notification channels"
+      name="notification-channel-disabled"
+      isDisabled
+    >
+      <Checkbox label="Email" value="email" isDefaultChecked />
+      <Checkbox label="In-app" value="in-app" />
+      <Checkbox label="Mobile push" value="push" />
+    </CheckboxGroup>
+  );
+};
+
+export default Component;
+```
+
+### Error
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, CheckboxGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <CheckboxGroup
+      label="Notification channels"
+      name="notification-channel-error"
+      errorText="Select at least one notification channel."
+    >
+      <Checkbox label="Email" value="email" isDefaultChecked />
+      <Checkbox label="In-app" value="in-app" />
+      <Checkbox label="Mobile push" value="push" />
+    </CheckboxGroup>
+  );
+};
+
+export default Component;
+```
+
+### Optional
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, CheckboxGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <CheckboxGroup
+      label="Notification channels"
+      name="notification-channel-optional"
+      hasRequiredIndicator
+    >
+      <Checkbox label="Email" value="email" isDefaultChecked />
+      <Checkbox label="In-app" value="in-app" />
+      <Checkbox label="Mobile push" value="push" />
+    </CheckboxGroup>
+  );
+};
+
+export default Component;
+```
+
+### Required
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, CheckboxGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <CheckboxGroup
+      label="Notification channels"
+      name="notification-channel-required"
+      hasRequiredIndicator
+      isRequired
+    >
+      <Checkbox label="Email" value="email" isDefaultChecked />
+      <Checkbox label="In-app" value="in-app" />
+      <Checkbox label="Mobile push" value="push" />
+    </CheckboxGroup>
+  );
+};
+
+export default Component;
+```
+
+### Visually Hidden Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, CheckboxGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <>
+      <CheckboxGroup
+        label="Notification channels"
+        name="notification-channel-hidden"
+        hasVisuallyHiddenLabel
+      >
+        <Checkbox label="Email" value="email" isDefaultChecked />
+        <Checkbox label="In-app" value="in-app" />
+        <Checkbox label="Mobile push" value="push" />
+      </CheckboxGroup>
+    </>
+  );
+};
+
+export default Component;
+```

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

@@ -0,0 +1,235 @@
+[//]: # (This file is auto-generated by the docs:generate-skills script, do not edit it manually)
+
+# Fieldset
+
+Import: `import { Fieldset } from '@neo4j-ndl/react'`
+
+## Props
+
+### Fieldset
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  | The controls grouped by the fieldset |
+| `errorText` | `ReactNode` |  |  | Error message displayed below the grouped controls. When provided, it replaces `helpText` |
+| `hasRequiredIndicator` | `boolean` |  | `false` | Whether Required or Optional is shown at the end of the legend row |
+| `hasVisuallyHiddenLabel` | `boolean` |  | `false` | Whether the legend is clipped out of the layout, leaving it to screen readers only |
+| `helpText` | `ReactNode` |  |  | Assistive text displayed below the grouped controls |
+| `isDisabled` | `boolean` |  | `false` | Whether all native form controls in the fieldset are disabled |
+| `isRequired` | `boolean` |  | `false` | Whether the grouped field is required |
+| `label` | `ReactNode` | ✅ |  | The accessible label displayed in the fieldset legend |
+| `ref` | `Ref<HTMLFieldSetElement>` |  |  | A ref to apply to the root element. |
+
+Use `RadioGroup` or `CheckboxGroup` when the children are exclusively
+radios or checkboxes and should inherit shared group attributes.
+
+## Accessibility
+
+`Fieldset` renders a native `<fieldset>` whose first child is a `<legend>`.
+This gives the grouped controls a shared accessible name while each control
+keeps its own label.
+
+Help and error text are associated with the fieldset through
+`aria-describedby`. An error replaces help text, sets `aria-invalid`, and is
+announced by the shared polite live region. `isDisabled` uses the native
+`disabled` attribute, which disables descendant form controls. Because a
+generic fieldset cannot apply native required behavior to arbitrary children,
+`isRequired` adds “Required” to the legend's accessible name; consumers remain
+responsible for validating the controls.
+
+Use `hasVisuallyHiddenLabel` only when the same group name is already visible
+elsewhere. The legend remains available to assistive technology.
+
+Use `RadioGroup` for one-of-many radio choices and `CheckboxGroup` for related
+checkboxes. Use `Fieldset` directly for mixed or other related form controls.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, Fieldset, TextArea, TextInput } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Fieldset
+      label="Team settings"
+      helpText="These settings apply to the whole team."
+    >
+      <TextInput label="Team name" placeholder="Graph Platform" />
+      <TextInput
+        label="Contact email"
+        placeholder="team@example.com"
+        htmlAttributes={{ type: 'email' }}
+      />
+      <TextArea
+        label="Team description"
+        placeholder="Describe what your team works on"
+      />
+      <Checkbox label="Allow other members to invite people" />
+    </Fieldset>
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import {
+  Checkbox,
+  Fieldset,
+  Radio,
+  Switch,
+  TextArea,
+  TextInput,
+  TimePicker,
+  TimeZonePicker,
+} from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Fieldset label="Team settings" isDisabled>
+      <TextInput label="Team name" placeholder="Graph Platform" />
+      <TextInput
+        label="Contact email"
+        placeholder="team@example.com"
+        htmlAttributes={{ type: 'email' }}
+      />
+      <TextArea
+        label="Team description"
+        placeholder="Describe what your team works on"
+      />
+      <Checkbox label="Allow other members to invite people" />
+      <Radio label="Use team defaults" />
+      <Switch label="Enable team notifications" />
+      <TimePicker label="Daily reminder time" />
+      <TimeZonePicker label="Team time zone" value="Europe/Stockholm" />
+    </Fieldset>
+  );
+};
+
+export default Component;
+```
+
+### Error
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, Fieldset, TextArea, TextInput } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Fieldset
+      label="Team settings"
+      errorText="Review the team settings before continuing."
+    >
+      <TextInput label="Team name" placeholder="Graph Platform" />
+      <TextInput
+        label="Contact email"
+        placeholder="team@example.com"
+        htmlAttributes={{ type: 'email' }}
+      />
+      <TextArea
+        label="Team description"
+        placeholder="Describe what your team works on"
+      />
+      <Checkbox label="Allow other members to invite people" />
+    </Fieldset>
+  );
+};
+
+export default Component;
+```
+
+### Optional
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, Fieldset, TextArea, TextInput } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Fieldset label="Team settings" hasRequiredIndicator>
+      <TextInput label="Team name" placeholder="Graph Platform" />
+      <TextInput
+        label="Contact email"
+        placeholder="team@example.com"
+        htmlAttributes={{ type: 'email' }}
+      />
+      <TextArea
+        label="Team description"
+        placeholder="Describe what your team works on"
+      />
+      <Checkbox label="Allow other members to invite people" />
+    </Fieldset>
+  );
+};
+
+export default Component;
+```
+
+### Required
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, Fieldset, TextArea, TextInput } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <Fieldset label="Team settings" hasRequiredIndicator isRequired>
+      <TextInput label="Team name" placeholder="Graph Platform" />
+      <TextInput
+        label="Contact email"
+        placeholder="team@example.com"
+        htmlAttributes={{ type: 'email' }}
+      />
+      <TextArea
+        label="Team description"
+        placeholder="Describe what your team works on"
+      />
+      <Checkbox label="Allow other members to invite people" />
+    </Fieldset>
+  );
+};
+
+export default Component;
+```
+
+### Visually Hidden Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Checkbox, Fieldset, TextArea, TextInput } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <>
+      <Fieldset label="Team settings" hasVisuallyHiddenLabel>
+        <TextInput label="Team name" placeholder="Graph Platform" />
+        <TextInput
+          label="Contact email"
+          placeholder="team@example.com"
+          htmlAttributes={{ type: 'email' }}
+        />
+        <TextArea
+          label="Team description"
+          placeholder="Describe what your team works on"
+        />
+        <Checkbox label="Allow other members to invite people" />
+      </Fieldset>
+    </>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/radio-group.md

@@ -0,0 +1,259 @@
+[//]: # (This file is auto-generated by the docs:generate-skills script, do not edit it manually)
+
+# RadioGroup
+
+Import: `import { RadioGroup } from '@neo4j-ndl/react'`
+
+## Props
+
+### RadioGroup
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | ✅ |  | The controls grouped by the fieldset |
+| `errorText` | `ReactNode` |  |  | Error message displayed below the grouped controls. When provided, it replaces `helpText` |
+| `hasRequiredIndicator` | `boolean` |  |  | Whether Required or Optional is shown at the end of the legend row |
+| `hasVisuallyHiddenLabel` | `boolean` |  |  | Whether the legend is clipped out of the layout, leaving it to screen readers only |
+| `helpText` | `ReactNode` |  |  | Assistive text displayed below the grouped controls |
+| `isDisabled` | `boolean` |  | `false` | Whether all native form controls in the fieldset are disabled |
+| `isRequired` | `boolean` |  | `false` | Whether the grouped field is required |
+| `label` | `ReactNode` | ✅ |  | The accessible label displayed in the fieldset legend |
+| `name` | `string` | ✅ |  | Shared native name for the radios in the group |
+| `onChange` | `((value: string, event: ChangeEvent<HTMLInputElement, Element>) => void)` |  |  | Called with the newly selected radio's value when the selection changes |
+| `orientation` | `'horizontal' \| 'vertical'` |  | `vertical` | Whether the radios are stacked vertically or laid out in a wrapping row |
+| `ref` | `Ref<HTMLFieldSetElement>` |  |  | A ref to apply to the root element. |
+| `value` | `string \| null` |  |  | The value of the selected radio. Pass `null` when no radio is selected. Leave undefined for uncontrolled usage |
+
+Pass `value` and `onChange` to control the selection from the group; each
+`Radio` is then checked when its `value` matches the group's `value`, and
+its own `isChecked` is ignored. Without `value`, selection state remains on
+each `Radio` (for example via `isDefaultChecked`), and `onChange` can still
+be used to observe changes. Radios inherit `name`, disabled, required,
+help, and validation semantics from the group.
+
+## Accessibility
+
+`RadioGroup` renders a native `<fieldset>` and `<legend>` with
+`role="radiogroup"`. The legend names the group, while every `Radio` keeps its
+own label. The required shared `name` is inherited by the radios so browsers
+treat them as one native choice.
+
+Native radios provide the keyboard behavior: Tab enters or leaves the group,
+arrow keys move and select within a same-name group, and Space selects the
+focused radio. No custom roving focus is added. Both up/down and left/right
+arrows work regardless of `orientation`, so the horizontal layout needs no
+extra keyboard handling.
+
+When `isRequired` is set, the group has `aria-required="true"` and its radios
+inherit native `required`. `isDisabled` disables the fieldset and every
+descendant control.
+
+Help and error text are associated with the radiogroup through
+`aria-describedby`; individual radios retain only descriptions supplied
+directly to them. An error replaces help text and sets `aria-invalid` on the
+radiogroup.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <RadioGroup
+      label="Default project size"
+      name="project-size"
+      helpText="Choose the size used for new projects."
+    >
+      <Radio label="Small" value="small" />
+      <Radio label="Medium" value="medium" isDefaultChecked />
+      <Radio label="Large" value="large" />
+    </RadioGroup>
+  );
+};
+
+export default Component;
+```
+
+### Controlled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup, Typography } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [projectSize, setProjectSize] = useState('medium');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <RadioGroup
+        label="Default project size"
+        name="project-size"
+        value={projectSize}
+        onChange={setProjectSize}
+      >
+        <Radio label="Small" value="small" />
+        <Radio label="Medium" value="medium" />
+        <Radio label="Large" value="large" />
+      </RadioGroup>
+      <Typography variant="body-medium">Selected: {projectSize}</Typography>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <RadioGroup
+      label="Default project size"
+      name="project-size-disabled"
+      isDisabled
+    >
+      <Radio label="Small" value="small" />
+      <Radio label="Medium" value="medium" isDefaultChecked />
+      <Radio label="Large" value="large" />
+    </RadioGroup>
+  );
+};
+
+export default Component;
+```
+
+### Error
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <RadioGroup
+      label="Default project size"
+      name="project-size-error"
+      errorText="Select a project size."
+    >
+      <Radio label="Small" value="small" />
+      <Radio label="Medium" value="medium" isDefaultChecked />
+      <Radio label="Large" value="large" />
+    </RadioGroup>
+  );
+};
+
+export default Component;
+```
+
+### Horizontal
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <RadioGroup
+      label="Default project size"
+      name="project-size"
+      helpText="Choose the size used for new projects."
+      orientation="horizontal"
+    >
+      <Radio label="Small" value="small" />
+      <Radio label="Medium" value="medium" isDefaultChecked />
+      <Radio label="Large" value="large" />
+    </RadioGroup>
+  );
+};
+
+export default Component;
+```
+
+### Optional
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <RadioGroup
+      label="Default project size"
+      name="project-size-optional"
+      hasRequiredIndicator
+    >
+      <Radio label="Small" value="small" />
+      <Radio label="Medium" value="medium" isDefaultChecked />
+      <Radio label="Large" value="large" />
+    </RadioGroup>
+  );
+};
+
+export default Component;
+```
+
+### Required
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <RadioGroup
+      label="Default project size"
+      name="project-size-required"
+      hasRequiredIndicator
+      isRequired
+    >
+      <Radio label="Small" value="small" />
+      <Radio label="Medium" value="medium" isDefaultChecked />
+      <Radio label="Large" value="large" />
+    </RadioGroup>
+  );
+};
+
+export default Component;
+```
+
+### Visually Hidden Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Radio, RadioGroup } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <>
+      <RadioGroup
+        label="Default project size"
+        name="project-size-hidden"
+        hasVisuallyHiddenLabel
+      >
+        <Radio label="Small" value="small" />
+        <Radio label="Medium" value="medium" isDefaultChecked />
+        <Radio label="Large" value="large" />
+      </RadioGroup>
+    </>
+  );
+};
+
+export default Component;
+```

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

@@ -12,7 +12,7 @@ Import: `import { Radio } from '@neo4j-ndl/react'`
 |------|------|----------|---------|-------------|
 | `ariaLabel` | `string` |  |  | The aria label of the radio. Required if the label is not a string. |
 | `hasLeadingLabel` | `boolean` |  |  | Whether the label should be displayed before the radio |
-| `isChecked` | `boolean` |  |  | Whether the radio is checked |
+| `isChecked` | `boolean` |  |  | Whether the radio is checked. Ignored when a parent `RadioGroup` has a `value` |
 | `isDefaultChecked` | `boolean` |  |  | Selects the radio by default in uncontrolled mode |
 | `isDisabled` | `boolean` |  | `false` | Whether the radio is disabled |
 | `isFluid` | `boolean` |  | `false` | Whether the radio & label should take the full available width of its container |