@redis-ui/components 43.0.2 → 43.2.1

package/skills/redis-ui-components/references/FormField.md

@@ -0,0 +1,678 @@
+# FormField
+
+A field wrapper for labels, helper text, and shared id/state propagation around inputs and other controls.
+
+## Import
+
+```tsx
+import { FormField } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Field content rendered inside `FormField.InputContainer` |
+| label | `ReactNode` | - | Label content rendered above the field |
+| infoIconProps | `InfoIconProps` | - | Props forwarded to the label info icon tooltip |
+| required | `boolean` | - | Shows the required marker on the label |
+| optional | `boolean` | - | Shows the optional marker on the label |
+| additionalText | `ReactNode` | - | Helper text rendered below the field |
+| additionalTextDescribesField | `boolean` | `false` | When true, links helper text into the field's aria description when possible |
+| id | `string` | auto-generated | Shared id used by the label and field; set `""` to disable sharing |
+| layout | `'vertical' \| 'horizontal'` | `'vertical'` | Field layout used by the compose wrapper |
+| compose wrapper props | `ComposeElementProps<HTMLElement>` | - | Standard wrapper props applied to the root compose element |
+
+The component also accepts standard wrapper props via `ComposeElementProps<HTMLElement>` on the outer compose element.
+
+## Sub-components
+
+- `FormField.Compose` - Low-level field composition wrapper that provides shared id and state providers.
+- `FormField.Label` - Shared label component for field labels and info tooltips.
+- `FormField.InputContainer` - Layout container for the input or composed control.
+- `FormField.AdditionalText` - Helper text block rendered below the field.
+- `FormField.Nested` - State boundary for nested controls that should not always inherit the parent field state.
+- `FormField.VerticalGroup` - Layout wrapper for aligning multiple fields, including mixed horizontal and vertical layouts.
+
+### FormField.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Compose content rendered inside the field wrapper |
+| id | `string` | auto-generated | Shared id used by the field and nested controls |
+| layout | `'vertical' \| 'horizontal'` | `'vertical'` | Controls whether the field is rendered in a vertical or horizontal layout |
+| compose wrapper props | `ComposeElementProps<HTMLElement>` | - | Standard wrapper props applied to the compose root |
+
+### FormField.AdditionalText Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Helper text content |
+| size | `TypographyBodySize` | `'S'` | Typography body size used for the helper text |
+| forceStatus | `FieldStatus` | - | Overrides the inherited field status when styling the helper text |
+| describeField | `boolean` | `false` | Adds the helper text to the field's aria description when possible |
+| typography body props | `TypographyBodyProps` | - | Standard body typography props forwarded to the helper text |
+
+### FormField.Label Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `ReactNode` | - | Label content rendered above the field |
+| infoIconProps | `InfoIconProps` | - | Props forwarded to the info icon tooltip |
+| required | `boolean` | - | Shows the required marker |
+| optional | `boolean` | - | Shows the optional marker |
+| readOnly | `boolean` | - | Renders the label in read-only styling |
+| label props | `LabelHTMLAttributes<HTMLLabelElement>` | - | Additional native label attributes |
+
+### FormField.Nested Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Nested content rendered inside the isolated field boundary |
+| id | `string` | - | Optional shared id for the nested boundary |
+| disabledState | `'pass' \| 'cut' \| 'smart'` | `'smart'` | Controls how disabled state is shared between the parent field and nested controls |
+
+## Examples
+
+### Playground
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<FormField label="FormField Label" additionalText="additional text">
+  <Input />
+</FormField>
+```
+
+### PartsAndProps
+
+> FormField can have label and additional text.
+> Label in turn can have `label` text, `required` marker, `optional` marker text and info icon with tooltip.
+> All parts are optional.
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField
+    label="Label"
+    required
+    optional
+    infoIconProps={{ content: 'Info tooltip' }}
+    additionalText="additional text"
+  >
+    <Input />
+  </FormField>
+  <FormField>
+    <Input />
+  </FormField>
+</>
+```
+
+### HorizontalLayout
+
+> Normally, horizontal layout is not aligned among fields.
+>
+> To align them, please wrap multiple FormFields with `FormField.VerticalGroup`
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="Short label" additionalText="additional text" layout="horizontal">
+    <Input />
+  </FormField>
+  <FormField
+    label="Looooooooooooooooong label"
+    additionalText="additional text"
+    layout="horizontal"
+  >
+    <Input />
+  </FormField>
+  <FormField.VerticalGroup>
+    <FormField label="Short label" additionalText="additional text" layout="horizontal">
+      <Input />
+    </FormField>
+    <FormField
+      label="Looooooooooooooooong label"
+      additionalText="additional text"
+      layout="horizontal"
+    >
+      <Input />
+    </FormField>
+  </FormField.VerticalGroup>
+</>
+```
+
+### VerticalLayout
+
+> FormField vertical layout looks the same inside `FormField.VerticalGroup`,
+> if no horizontal layout FormField exists in the same group
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="Short label" additionalText="additional text">
+    <Input />
+  </FormField>
+  <FormField
+    label="Looooooooooooooooong label"
+    additionalText="additional text"
+  >
+    <Input />
+  </FormField>
+  <FormField.VerticalGroup>
+    <FormField label="Short label" additionalText="additional text">
+      <Input />
+    </FormField>
+    <FormField
+      label="Looooooooooooooooong label"
+      additionalText="additional text"
+    >
+      <Input />
+    </FormField>
+  </FormField.VerticalGroup>
+</>
+```
+
+### VerticalGroupWithMixedLayout
+
+> If `FormField.VerticalGroup` contains FormFields with mixed horizontal and vertical layouts,
+> it will align all inputs, including read-only ones
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<FormField.VerticalGroup>
+  <FormField label="Vertical layout FormField">
+    <Input />
+  </FormField>
+  <FormField additionalText="no label field">
+    <Input />
+  </FormField>
+  <FormField layout="horizontal" label="Horizontal layout">
+    <Input />
+  </FormField>
+  <FormField
+    layout="horizontal"
+    label="Horizontal layout with readOnly input"
+    additionalText="additional text"
+  >
+    <Input defaultValue="read-only text" readOnly />
+  </FormField>
+</FormField.VerticalGroup>
+```
+
+### Status
+
+> FormField can inherit status of the underling input.
+>
+> Error status changes color of the additional text to red.
+> Valid status doesn't change look of the FormField parts.
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="Valid status" additionalText="additional text">
+    <Input valid />
+  </FormField>
+  <FormField
+    label="Error status"
+    additionalText="additional text - should have error color"
+  >
+    <Input error="Error message" />
+  </FormField>
+</>
+```
+
+### DisabledAndReadonly
+
+> FormField can inherit disabled and readOnly states of the descending input.
+>
+> Read-only state changes color of the FormField label.
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="Disabled input" additionalText="additional text">
+    <Input disabled value="text" />
+  </FormField>
+  <FormField label="Read-only input" additionalText="additional text">
+    <Input value="read-only input value" readOnly />
+  </FormField>
+</>
+```
+
+### SharedId
+
+> FormField and Inputs, Select and few other components use SharedId engine.
+> It allows share custom id, defined on a FormField or underling input.
+>
+> If no id defined, SharedId engine generates id and shares it between FormField and underling input.
+>
+> If id should not be shared, the FormField's `id` property should be set to an empty string.
+> In this case, the label and the input will not be connected by the html "for-id" relationship
+
+```tsx
+import { FormField, Input } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="FormField with custom id" additionalText="id defined on input">
+    <Input id="input-custom-id" />
+  </FormField>
+  <FormField
+    label="FormField with custom id"
+    additionalText="id defined on FormField"
+    id="form-field-custom-id"
+  >
+    <Input />
+  </FormField>
+  <FormField
+    label="FormField with auto-generated id"
+    additionalText="id is not defined - silently generated"
+  >
+    <Input />
+  </FormField>
+  <FormField
+    label="FormField without shared id"
+    additionalText="id is not defined and not generated"
+    id=""
+  >
+    <Input />
+  </FormField>
+</>
+```
+
+### NestedComponents
+
+> Some states and id are shared between FormField and underling input.
+>
+> If an additional component that can share states/id is nested in the main Input or FormField,
+> then the states/id will be shared across all players.
+>
+> To prevent this, wrap the nested component in `FormField.Nested`
+> and it will have independent states/id shared under the `FormField.Nested` wrapper
+>
+> > Note: The `disabled` state is shared smartly with the nested component.
+> > It is propagated to the nested component from the container only if container is disabled.
+> >
+> > This behavior can be changed by setting `disabledState` to:
+> > - `cut` - prevent sharing state, use nested component own state
+> > - `pass` - propagate state in both directions (container will be disabled, if nested is disabled)
+> >
+> > You can prevent sharing disabled state also by wrapping the nested component in `FieldDisabledProvider`
+
+```tsx
+import {
+  FieldDisabledProvider,
+  FormField,
+  Input,
+  QuantityCounter,
+  Select
+} from '@redislabsdev/redis-ui-components';
+
+const options = [{ value: 'MB' }, { value: 'GB' }, { value: 'TB' }];
+
+<>
+  <FormField
+    label='Nested component is wrapped in "FormField.Nested"'
+    additionalText='The nested Input has its own "error" status'
+  >
+    <QuantityCounter.Compose defaultValue={123}>
+      <QuantityCounter.InputGroup.Compose>
+        <QuantityCounter.InputGroup.Tag />
+        <QuantityCounter.InputGroup.ValueLabel>
+          <FormField.Nested>
+            <Input
+              defaultValue="TB"
+              autoSize
+              style={{
+                width: 'fit-content',
+                height: 'fit-content',
+                border: 'none',
+                padding: 0
+              }}
+              error="error"
+            />
+          </FormField.Nested>
+        </QuantityCounter.InputGroup.ValueLabel>
+      </QuantityCounter.InputGroup.Compose>
+    </QuantityCounter.Compose>
+  </FormField>
+
+  <FormField
+    label='Nested component is not wrapped in "FormField.Nested"'
+    additionalText='The nested Input has an "error" status that propagates to the main Input and FormField'
+  >
+    <QuantityCounter.Compose defaultValue={123}>
+      <QuantityCounter.InputGroup.Compose>
+        <QuantityCounter.InputGroup.Tag />
+        <QuantityCounter.InputGroup.ValueLabel>
+          <Input
+            defaultValue="TB"
+            autoSize
+            style={{
+              width: 'fit-content',
+              height: 'fit-content',
+              border: 'none',
+              padding: 0
+            }}
+            error="error"
+          />
+        </QuantityCounter.InputGroup.ValueLabel>
+      </QuantityCounter.InputGroup.Compose>
+    </QuantityCounter.Compose>
+  </FormField>
+
+  <FormField
+    label='Nested component is wrapped in "FormField.Nested"'
+    additionalText='The "disabled" state is smartly passed to descendants. Disabling container disables nested components.'
+  >
+    <QuantityCounter.Compose defaultValue={123}>
+      <QuantityCounter.InputGroup.Compose>
+        <QuantityCounter.InputGroup.Tag disabled />
+        <QuantityCounter.InputGroup.ValueLabel>
+          <FormField.Nested>
+            <Select
+              options={options}
+              style={{
+                width: 'fit-content',
+                height: 'fit-content',
+                border: 'none',
+                padding: 0
+              }}
+              defaultValue="MB"
+            />
+          </FormField.Nested>
+        </QuantityCounter.InputGroup.ValueLabel>
+      </QuantityCounter.InputGroup.Compose>
+    </QuantityCounter.Compose>
+  </FormField>
+
+  <FormField
+    label='Nested component is wrapped in "FormField.Nested"'
+    additionalText='The "disabled" state is smartly passed to descendants. Disabling nested does not affect the container'
+  >
+    <QuantityCounter.Compose defaultValue={123}>
+      <QuantityCounter.InputGroup.Compose>
+        <QuantityCounter.InputGroup.Tag />
+        <QuantityCounter.InputGroup.ValueLabel>
+          <FormField.Nested>
+            <Select
+              options={options}
+              style={{
+                width: 'fit-content',
+                height: 'fit-content',
+                border: 'none',
+                padding: 0
+              }}
+              defaultValue="MB"
+              disabled
+            />
+          </FormField.Nested>
+        </QuantityCounter.InputGroup.ValueLabel>
+      </QuantityCounter.InputGroup.Compose>
+    </QuantityCounter.Compose>
+  </FormField>
+
+  <FormField
+    label='Nested component is wrapped in "FieldDisabledProvider"'
+    additionalText='The nested component has its own "disabled" state'
+  >
+    <QuantityCounter.Compose defaultValue={123}>
+      <QuantityCounter.InputGroup.Compose>
+        <QuantityCounter.InputGroup.Tag />
+        <QuantityCounter.InputGroup.ValueLabel>
+          <FieldDisabledProvider>
+            <Select
+              options={options}
+              style={{
+                width: 'fit-content',
+                height: 'fit-content',
+                border: 'none',
+                padding: 0
+              }}
+              defaultValue="MB"
+              disabled
+            />
+          </FieldDisabledProvider>
+        </QuantityCounter.InputGroup.ValueLabel>
+      </QuantityCounter.InputGroup.Compose>
+    </QuantityCounter.Compose>
+  </FormField>
+</>
+```
+
+### ComposeWithLink
+
+```tsx
+import { FormField, Input, Link } from '@redislabsdev/redis-ui-components';
+
+<FormField.Compose>
+  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+    <FormField.Label label="Label" />
+    <Link external variant="inline" onClick={() => false} />
+  </div>
+  <FormField.InputContainer>
+    <Input />
+  </FormField.InputContainer>
+  <FormField.AdditionalText>additional text</FormField.AdditionalText>
+</FormField.Compose>;
+```
+
+### withSelect
+
+```tsx
+import { FormField, Select } from '@redislabsdev/redis-ui-components';
+
+const options = [
+  { value: 'apple', label: 'Apple' },
+  { value: 'orange', label: 'Orange' },
+  { value: 'grape', label: 'Grape' },
+  { value: 'pear', label: 'Pear' }
+];
+
+<FormField.VerticalGroup style={{ rowGap: '2rem' }}>
+  <FormField
+    label="FormField Label"
+    additionalText="horizontal layout with select"
+    layout="horizontal"
+  >
+    <Select options={options} onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="vertical layout with Select">
+    <Select options={options} onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="disabled Select">
+    <Select options={options} disabled onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="error state of Select">
+    <Select options={options} error="error" onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="custom id of Select">
+    <Select options={options} id="custom-id" onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+</FormField.VerticalGroup>
+```
+
+### withMultiSelect
+
+```tsx
+import { FormField, MultiSelect } from '@redislabsdev/redis-ui-components';
+
+const options = [
+  { value: 'apple', label: 'Apple' },
+  { value: 'orange', label: 'Orange' },
+  { value: 'grape', label: 'Grape' },
+  { value: 'pear', label: 'Pear' }
+];
+
+<FormField.VerticalGroup>
+  <FormField
+    label="FormField Label"
+    additionalText="horizontal layout with multiSelect"
+    layout="horizontal"
+  >
+    <MultiSelect
+      options={options}
+      defaultValue={['apple', 'orange']}
+      onChange={() => undefined}
+      onOpenChange={() => undefined}
+    />
+  </FormField>
+  <FormField label="FormField Label" additionalText="vertical layout with MultiSelect">
+    <MultiSelect options={options} onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="disabled MultiSelect">
+    <MultiSelect options={options} disabled onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="error state of MultiSelect">
+    <MultiSelect options={options} error="error" onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="custom id of MultiSelect">
+    <MultiSelect options={options} id="custom-id" onChange={() => undefined} onOpenChange={() => undefined} />
+  </FormField>
+</FormField.VerticalGroup>
+```
+
+### withRadioGroupHorizontal
+
+> RadioGroup `horizontal` layout
+
+```tsx
+import { FormField, RadioGroup } from '@redislabsdev/redis-ui-components';
+
+const StoryRadioGroup = (props) => (
+  <RadioGroup.Compose defaultValue="1" layout="horizontal" {...props}>
+    <RadioGroup.Item value="1" label="Item 1" />
+    <RadioGroup.Item value="2" label="Item 2" />
+  </RadioGroup.Compose>
+);
+
+<FormField.VerticalGroup style={{ rowGap: '2rem' }}>
+  <FormField label="FormField Label" additionalText="horizontal FormField" layout="horizontal">
+    <StoryRadioGroup />
+  </FormField>
+  <FormField label="FormField Label" additionalText="vertical FormField">
+    <StoryRadioGroup />
+  </FormField>
+  <FormField label="FormField Label" additionalText="disabled RadioGroup">
+    <StoryRadioGroup disabled />
+  </FormField>
+  <FormField label="FormField Label" additionalText="readOnly state of RadioGroup">
+    <StoryRadioGroup readOnly />
+  </FormField>
+  <FormField label="FormField Label" additionalText="custom id of RadioGroup">
+    <StoryRadioGroup id="custom-id" />
+  </FormField>
+</FormField.VerticalGroup>
+```
+
+### withRadioGroupVertical
+
+> RadioGroup `vertical` layout
+
+```tsx
+import { FormField, RadioGroup } from '@redislabsdev/redis-ui-components';
+
+const StoryRadioGroup = (props) => (
+  <RadioGroup.Compose defaultValue="1" layout="horizontal" {...props}>
+    <RadioGroup.Item value="1" label="Item 1" />
+    <RadioGroup.Item value="2" label="Item 2" />
+  </RadioGroup.Compose>
+);
+
+<FormField.VerticalGroup style={{ rowGap: '2rem' }}>
+  <FormField label="FormField Label" additionalText="horizontal FormField" layout="horizontal">
+    <StoryRadioGroup layout="vertical" />
+  </FormField>
+  <FormField label="FormField Label" additionalText="vertical FormField" layout="vertical">
+    <StoryRadioGroup layout="vertical" />
+  </FormField>
+</FormField.VerticalGroup>
+```
+
+### withSwitch
+
+```tsx
+import { useState } from 'react';
+import { FormField, Switch } from '@redislabsdev/redis-ui-components';
+
+function Render() {
+  const [state, setState] = useState(true);
+
+  return (
+    <FormField.VerticalGroup style={{ rowGap: '2rem' }}>
+      <FormField
+        label="FormField Label"
+        additionalText="horizontal layout with Switch"
+        layout="horizontal"
+      >
+        <Switch checked={state} onCheckedChange={setState} />
+      </FormField>
+      <FormField label="FormField Label" additionalText="vertical layout with Switch">
+        <Switch checked={state} onCheckedChange={setState} />
+      </FormField>
+      <FormField label="FormField Label" additionalText="disabled Switch">
+        <Switch checked={state} onCheckedChange={setState} disabled />
+      </FormField>
+      <FormField label="FormField Label" additionalText="readOnly state of Switch">
+        <Switch checked={state} onCheckedChange={setState} readOnly />
+      </FormField>
+      <FormField label="FormField Label" additionalText="custom id of Switch">
+        <Switch checked={state} onCheckedChange={setState} id="custom-id" />
+      </FormField>
+    </FormField.VerticalGroup>
+  );
+}
+```
+
+### withInputs
+
+```tsx
+import {
+  FormField,
+  NumericInput,
+  PasswordInput,
+  QuantityCounter,
+  SearchInput,
+  TextArea
+} from '@redislabsdev/redis-ui-components';
+
+<FormField.VerticalGroup style={{ rowGap: '2rem' }}>
+  <FormField label="FormField Label" additionalText="with SearchInput">
+    <SearchInput defaultValue="search text" />
+  </FormField>
+  <FormField label="FormField Label" additionalText="with PasswordInput">
+    <PasswordInput defaultValue="password" autoComplete="off" />
+  </FormField>
+  <FormField label="FormField Label" additionalText="with NumericInput">
+    <NumericInput defaultValue={10.1} />
+  </FormField>
+  <FormField label="FormField Label" additionalText="with QuantityCounter">
+    <QuantityCounter defaultValue={123} valueLabel="hedgehogs" maxDecimals={0} autoValidate />
+  </FormField>
+  <FormField label="FormField Label" additionalText="with TextArea">
+    <TextArea
+      value={`A grasshopper spent the summer hopping about in the sun and singing to his heart's content. One day, an ant went hurrying by, looking very hot and weary. "Why are you working on such a lovely day?" said the grasshopper. "I'm collecting food for the winter," said the ant, "and I suggest you do the same."`}
+    />
+  </FormField>
+</FormField.VerticalGroup>
+```
+
+## Notes
+
+- FormField can render labels and helper text, and each of those parts is optional.
+- Use `FormField.VerticalGroup` to align multiple fields when mixing horizontal and vertical layouts.
+- Vertical fields inside `FormField.VerticalGroup` stay aligned the same way unless a horizontal field is present in the group.
+- Mixed horizontal and vertical layouts inside `FormField.VerticalGroup` align all inputs, including read-only ones.
+- Error status is inherited from the nested input and turns the additional text red; valid status does not change the field appearance.
+- Read-only state is inherited from the nested input and changes the label color.
+- Shared ids are auto-generated when omitted; setting `id=""` disables sharing between the label and the input.
+- `FormField.Nested` isolates nested controls from the parent field's shared id and state.
+- `disabledState="smart"` propagates disabled state from the container only when the container is disabled; `cut` and `pass` change that sharing behavior.
+- `FieldDisabledProvider` can also be used to keep a nested control's disabled state independent.
+- `FormField.Compose` can be used to build custom layouts, such as placing a link next to the label row.