<>
  <Field
    label="This is the field label"
    validationMessage="This is error text"
    size="small"
    orientation="horizontal"
    required
  >
    <Input contentBefore="$" contentAfter=".00" />
  </Field>
  <Field label="Radio group field">
    <RadioGroup>
      <Radio value="one" label="Option one" />
      <Radio value="two" label="Option two" />
      <Radio value="three" label="Option three" />
    </RadioGroup>
  </Field>
  <Field label="Combobox field" validationState="success" validationMessage="Success text">
    <Combobox>
      <Option value="one">Option one</Option>
      <Option value="two">Option two</Option>
      <Option value="three">Option three</Option>
    </Combobox>
  </Field>
  <Field label="Slider field" validationState="warning" validationMessage="Warning text">
    <Slider defaultValue={25} />
  </Field>
  <Field label="Spin button field" hint="Hint text">
    <SpinButton />
  </Field>
</>

export type FieldSlots = {
  root: NonNullable<Slot<'div'>>;

  /**
   * The label associated with the field.
   */
  label?: Slot<typeof Label>;

  /**
   * A message about the validation state. By default, this is an error message, but it can be a success, warning,
   * or custom message by setting `validationState`.
   */
  validationMessage?: Slot<'div'>;

  /**
   * The icon associated with the `validationMessage`. This will only be displayed if `validationMessage` is set.
   *
   * The default depends on `validationState`:
   * * `error` - `<ErrorCircle12Filled />`
   * * `warning` - `<Warning12Filled />`
   * * `success` - `<CheckmarkCircle12Filled />`
   * * `none` - `null`
   */
  validationMessageIcon?: Slot<'span'>;

  /**
   * Additional hint text below the field.
   */
  hint?: Slot<'div'>;
};

export type FieldProps = Omit<ComponentProps<FieldSlots>, 'children'> & {
  /**
   * The Field's child can be a single form control, or a render function that takes the props that should be spread on
   * a form control.
   *
   * All form controls in this library can be used directly as children (such as `<Input>` or `<RadioGroup>`), as well
   * as intrinsic form controls like `<input>` or `<textarea>`. Custom controls can also be used as long as they
   * accept FieldControlProps and spread them on the appropriate element.
   *
   * For more complex scenarios, a render function can be used to pass the FieldControlProps to the appropriate control.
   */
  children?: React.ReactNode | ((props: FieldControlProps) => React.ReactNode);

  /**
   * The orientation of the label relative to the field component.
   * This only affects the label, and not the validationMessage or hint (which always appear below the field component).
   *
   * @default vertical
   */
  orientation?: 'vertical' | 'horizontal';

  /**
   * The `validationState` affects the display of the `validationMessage` and `validationMessageIcon`.
   *
   * * `error` - (default) The validation message has a red error icon and red text, with `role="alert"` so it is
   *     announced by screen readers. Additionally, the control inside the field has `aria-invalid` set, which adds a
   *     red border to some field components (such as `Input`).
   * * `success` - The validation message has a green checkmark icon and gray text.
   * * `warning` - The validation message has a yellow exclamation icon and gray text.
   * * `none` - The validation message has no icon and gray text.
   *
   * @default error when `validationMessage` is set; none otherwise.
   */
  validationState?: 'error' | 'warning' | 'success' | 'none';

  /**
   * Marks the Field as required. If `true`, an asterisk will be appended to the label, and `aria-required` will be set
   * on the Field's child.
   */
  required?: boolean;

  /**
   * The size of the Field's label.
   *
   * @default medium
   */
  size?: 'small' | 'medium' | 'large';
};

export type FieldState = ComponentState<Required<FieldSlots>> &
  Required<Pick<FieldProps, 'orientation' | 'required' | 'size' | 'validationState'>> &
  Pick<FieldProps, 'children'> & {
    /**
     * The ID generated for the control inside the field, and the default value of label.htmlFor prop.
     */
    generatedControlId: string;
  };

export type FieldContextValue = Readonly<
  Pick<FieldState, 'generatedControlId' | 'orientation' | 'required' | 'size' | 'validationState'> & {
    /** The label's for prop. Undefined if there is no label. */
    labelFor?: string;
    /** The label's id prop. Undefined if there is no label. */
    labelId?: string;
    /** The validationMessage's id prop. Undefined if there is no validationMessage. */
    validationMessageId?: string;
    /** The hint's id prop. Undefined if there is no hint. */
    hintId?: string;
  }
>;

/**
 * The props added to the control inside the Field.
 */
export type FieldControlProps = Pick<
  React.HTMLAttributes<HTMLElement>,
  'id' | 'aria-labelledby' | 'aria-describedby' | 'aria-invalid' | 'aria-required'
>;

/**
 * Gets the control props from the field context, if this inside a `<Field>`.
 *
 * If `props` is provided: copies and merges the FieldControlProps with the given props, if this inside a `<Field>`.
 * Otherwise, returns the FieldControlProps that should be applied to the control.
 *
 * It is preferred to pass a `props` object if available, to improve the resulting merged props.
 *
 * @param props - The existing props for the control. These will be merged with the control props from the field context.
 * @param options - Option to include the size prop.
 * @returns Merged props if inside a `<Field>`, otherwise the original props, or undefined if no props given.
 */
export function useFieldControlProps_unstable<Props extends FieldControlProps>(
  props?: Props,
  options?: FieldControlPropsOptions,
): Props | undefined;

/**
 * Options for `useFieldControlProps_unstable`.
 */
export type FieldControlPropsOptions = {
  /**
   * Skips setting `aria-labelledby` on the control if the `label.htmlFor` refers to the control.
   *
   * This should be used with controls that can be the target of a label's `for` prop:
   * `<button>`, `<input>`, `<progress>`, `<select>`, `<textarea>`.
   */
  supportsLabelFor?: boolean;

  /**
   * Sets `required` instead of `aria-required` when the Field is marked required.
   *
   * This should be used with controls that support the `required` prop:
   * `<input>` (except `range` or `color`), `<select>`, `<textarea>`.
   */
  supportsRequired?: boolean;

  /**
   * Sets the size prop on the control to match the Field's size: `'small' | 'medium' | 'large'`.
   *
   * This should be used with controls that have a custom size prop that matches the Field's size prop.
   */
  supportsSize?: boolean;
};

<Field
  label="This is the field label"
  orientation="horizontal"
  validationState="error"
  validationMessage="This is a validation message"
  hint="This is a hint message"
>
  <Input />
</Field>

<Field
  label="This is the field label"
  orientation="horizontal"
  validationState="error"
  validationMessage="This is a validation message"
  hint="This is a hint message"
>
  {fieldProps => (
    <div>
      <input {...fieldProps} />
    </div>
  )}
</Field>

<slots.root>
  <slots.label {...slotProps.label} />
  {slotProps.root.children}
  <slots.validationMessage {...slotProps.validationMessage}>
    <slots.validationMessageIcon {...slotProps.validationMessageIcon} />
    {slotProps.validationMessage.children}
  </slots.validationMessage>
  <slots.hint {...slotProps.hint} />
</slots.root>

<div className="fui-Field">
  <label className="fui-Field__label fui-Label">This is the field label</label>
  <!-- child field component goes here -->
  <span className="fui-Field__validationMessage">
    <span className="fui-Field__validationMessageIcon"><svg>...</svg></span>
    This is a validation message
  </span>
  <span className="fui-Field__hint">This is a hint message</span>
</div>