@neo4j-ndl/react 4.24.2 → 4.25.1

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 |

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

@@ -15,10 +15,12 @@ Import: `import { Select } from '@neo4j-ndl/react'`
 | `ariaLabel` | `string` |  |  | Aria label of the select component |
 | `as` | `ElementType<any, keyof IntrinsicElements>` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. |
 | `errorText` | `ReactNode` |  |  | Error message, if it exists the select will be in error state |
+| `hasRequiredIndicator` | `boolean` |  | `false` | Whether Required or Optional is shown at the end of the label row, based on the `isRequired` prop |
 | `helpText` | `ReactNode` |  |  | Help text of the select component |
 | `isClean` | `boolean` |  | `false` | Whether the select component is clean. If true, the select component will have a transparent background, no border and be hug the width of the content. |
 | `isDisabled` | `boolean` |  |  | Whether the select component is disabled |
 | `isFluid` | `boolean` |  | `true` | Whether the select component is fluid |
+| `isRequired` | `boolean` |  | `false` | Whether a value is required. Sets `aria-required` and enables native form validation. |
 | `label` | `ReactNode` |  |  | Label of the select component. If not provided, please provide an ariaLabel. |
 | `ref` | `any` |  |  | A ref to apply to the root element. |
 | `selectProps` | `StateManagerProps<OptionType, IsMulti, GroupType> \| CreatableProps<OptionType, IsMulti, GroupType> \| AsyncProps<...>` |  | `{}` | Props of the select component, based of React Select props |
@@ -482,6 +484,46 @@ const Component = (props: React.ComponentProps<typeof Select>) => {
 export default Component;
 ```
 
+### Required
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Select } from '@neo4j-ndl/react';
+
+const EXAMPLE_OPTIONS = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Needle 🪡', value: 'needle' },
+  { label: 'Graph Databases', value: 'graph-database' },
+];
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-16">
+      <Select
+        label="Required"
+        type="select"
+        isRequired
+        hasRequiredIndicator
+        selectProps={{
+          options: EXAMPLE_OPTIONS,
+        }}
+      />
+      <Select
+        label="Optional"
+        type="select"
+        hasRequiredIndicator
+        selectProps={{
+          options: EXAMPLE_OPTIONS,
+        }}
+      />
+    </div>
+  );
+};
+
+export default Component;
+```
+
 ### Sizes
 
 ```tsx