chore: Add FormFieldGroup component and density example

modules/docs/mdx/12.0-UPGRADE-GUIDE.mdx

@@ -46,6 +46,8 @@ A note to the reader:
 - [Component Updates](#component-updates)
   - [Styling API and CSS Tokens](#styling-api-and-css-tokens)
   - [Avatar](#avatar)
+  - [FormFieldGroup](#form-field-group)
+  - [Select](#select)
   - [Text Area](#text-area)
 - [Troubleshooting](#troubleshooting)
 - [Glossary](#glossary)
@@ -120,12 +122,32 @@ The following components are affected:
 ### Avatar
 
 - Avatar no longer uses `SystemIconCircle` for sizing.
-- `Avatar.Size` is no longer supported. The `size` prop type has change to accept the following:
+- `Avatar.Size` is no longer supported.
+- The `size` prop type has change to accept the following:
   `"extraExtraLarge" | "extraLarge" | "large" | "medium" | "small" | "extraSmall" | (string{})`
-- `Avatar.Variant` is no longer supported. Enum `AvatarVariant` has been removed. The `variant` type
-  prop now accepts `"dark" | "light"`
+- `Avatar.Variant` is no longer supported.
+- Enum `AvatarVariant` has been removed.
+- The `variant` prop now accepts `"dark" | "light"`
 - The `as` prop now accepts any element, not just `div`.
 
+### Form Field Group
+
+We've added a new component to the Preview package under FromField to allow users to group inputs
+without worrying about setting the `as` prop on the `FormField` component.
+
+Use `FormFieldGroup` when you have a group of inputs that need to be associated to one another, like
+`RadioGroup` or a group of `Checkbox`'s. `FormFieldGroup` renders a `fieldset` element and
+`FormFieldGroup.Legend` renders a `legend` element. These elements will allow for correct
+accessibility of grouped inputs.
+
+`FormFieldGroup` supports the same props of `FormField`:
+
+- `error`: `"alert" | "error"` Defines the error around the whole group of inputs.
+- `orientation`: `"horizontal" | "vertical"` Defines the legend placement.
+- `isRequired`: `true` Defines if a group like RadioGroup is required.
+
+### Select
+
 ### Text Area
 
 **PR:** [#2825](https://github.com/Workday/canvas-kit/pull/2825)

modules/preview-react/form-field/index.ts

@@ -1,4 +1,5 @@
 export * from './lib/FormField';
+export * from './lib/FormFieldGroup';
 export * from './lib/hooks/';
 export {formFieldStencil} from './lib/formFieldStencil';
 export {formFieldContainerStencil} from './lib/FormFieldContainer';

modules/preview-react/form-field/lib/FormFieldGroup.tsx

@@ -0,0 +1,128 @@
+import React from 'react';
+
+import {createContainer, GrowthBehavior} from '@workday/canvas-kit-react/common';
+import {FlexProps, mergeStyles} from '@workday/canvas-kit-react/layout';
+
+import {FormFieldGroupList} from './FormFieldGroupList';
+import {FormFieldGroupInput} from './FormFieldGroupInput';
+import {FormField} from './FormField';
+
+import {useFormFieldModel} from './hooks';
+import {formFieldStencil} from './formFieldStencil';
+
+export interface FormFieldGroupProps extends FlexProps, GrowthBehavior {
+  /**
+   * The direction the child elements should stack
+   * @default vertical
+   */
+  orientation?: 'vertical' | 'horizontal';
+  children: React.ReactNode;
+}
+
+/**
+ * Use `FormFieldGroup` to wrap a group of inputs to make them accessible. `FormFieldGroup` will render a `fieldset` element with the purpose of grouping input controls.
+ *
+ * ```tsx
+ * <FormFieldGroup>
+ *    <FormField.Legend>Choose a Pet</FormField.Label>
+ *    <FormFieldGroup.List as={RadioGroup} />
+ *      <FromFieldGroup.Input as={RadioGroup.RadioButton} value='dog'>Dog</FormFieldGroup.Input>
+ *      <FromFieldGroup.Input as={RadioGroup.RadioButton} value='cat'>Cat</FormFieldGroup.Input>
+ *    </FormFieldGroup.List>
+ * </FormFieldGroup>
+ * ```
+ *
+ * @stencil formFieldStencil
+ */
+export const FormFieldGroup = createContainer('fieldset')({
+  displayName: 'FormFieldGroup',
+  modelHook: useFormFieldModel,
+  subComponents: {
+    /**
+     * `FormFieldGroup.Input` will render any `inputs` passed to it via the `as` prop, including `TextInput`, `Select`, `Switch`, `TextArea`, `RadioGroup.RadioButton` or any custom input.
+     * `FormFieldGroup.Input` will apply `aria-invalid` when there is an error on `FromFieldGroup` or `aria-describedby` when an `id` is added on the `FormFieldGroup`.
+     *
+     * **Note: If you pass in a custom input that is *not* as Canvas Kit input, you will have to handle the `error` prop, validation and styling. For a custom approach, reference our Custom storybook example.**
+     *
+     * ```tsx
+     * <FormFieldGroup>
+     *    <FormField.Legend>Choose a Pet</FormField.Label>
+     *    <FormFieldGroup.List as={RadioGroup} />
+     *      <FromFieldGroup.Input as={RadioGroup.RadioButton} value='dog'>Dog</FormFieldGroup.Input>
+     *      <FromFieldGroup.Input as={RadioGroup.RadioButton} value='cat'>Cat</FormFieldGroup.Input>
+     *    </FormFieldGroup.List>
+     * </FormFieldGroup>
+     * ```
+     */
+    Input: FormFieldGroupInput,
+    /**
+     * `FormFieldGroup.Legend` will render a `legend` element. This element labels the contents of a `fieldset`.
+     *
+     * ```tsx
+     * <FormFieldGroup>
+     *    <FormFieldGroup.Legend>Choose a pet</FormFieldGroup.Legend>
+     *    //...
+     *  </FormFieldGroup>
+     * ```
+     *
+     * @stencil formFieldLabelStencil
+     */
+    Legend: FormField.Label.as('legend'),
+    /**
+     * `FormFieldGroup.List` will render a `div`. This element is used to apply the visual error states around the group of inputs. It's contents will be your inputs.
+     */
+    List: FormFieldGroupList,
+    /**
+     * `FormFieldGroup.Hint` will render any additional information you want to provide to the `FormFieldGroup`. If you
+     * set the `orientation` prop to `horizontal` you should use `FormFieldGroup.Container` to properly align the hint with your `FormField.List`.
+     *
+     * ```tsx
+     * <FormFieldGroup>
+     *    <FormFieldGroup.Legend>Choose a pet</FormFieldGroup.Legend>
+     *    <FormFieldGroup.List>
+     *      //...
+     *    <FormFieldGroup.List>
+     *    <FormField.Hint>This is your hint text</FormField.Hint>
+     *  </FormFieldGroup>
+     * ```
+     *
+     * @stencil formFieldHintStencil
+     */
+    Hint: FormField.Hint,
+    /**
+     * `FormFieldGroup.Container` allows you to properly center `FormField.Legend` when the `orientation` is set to `horizontal` and there is hint text..
+     *
+     * ```tsx
+     * <FormFieldGroup orientation="horizontal">
+     *    <FormFieldGroup.Legend>Choose a pet</FormFieldGroup.Legend>
+     *    <FormFieldGroup.Container>
+     *      <FormFieldGroup.List>
+     *        <FromFieldGroup.Input as={RadioGroup.RadioButton} value='dog'>Dog</FormFieldGroup.Input>
+     *        <FromFieldGroup.Input as={RadioGroup.RadioButton} value='cat'>Cat</FormFieldGroup.Input>
+     *      </FormFieldGroup.List>
+     *      <FormFieldGroup.Hint>This is your hint text</FormField.Hint>
+     *    </FormFieldGroup.Container>
+     *  </FormFieldGroup>
+     * ```
+     *
+     * @stencil formFieldContainerStencil
+     */
+    Container: FormField.Container,
+  },
+})<FormFieldGroupProps>(({children, grow, orientation, ...elemProps}, Element, model) => {
+  return (
+    <Element
+      {...mergeStyles(
+        elemProps,
+        formFieldStencil({
+          grow,
+          orientation,
+          error: model.state.error,
+          required: model.state.isRequired,
+        })
+      )}
+    >
+      {children}
+    </Element>
+  );
+});

modules/preview-react/form-field/lib/FormFieldGroupInput.tsx

@@ -0,0 +1,24 @@
+import {createElemPropsHook, createSubcomponent} from '@workday/canvas-kit-react/common';
+import {CSProps, handleCsProp} from '@workday/canvas-kit-styling';
+import React from 'react';
+import {useFormFieldModel} from './hooks';
+
+export interface FormFieldGroupInputProps extends CSProps {}
+/**
+ * Adds the necessary props to an `Input` component.
+ * Used by the FormField.Input subcomponent and other input type components
+ */
+export const useFormFieldGroupInput = createElemPropsHook(useFormFieldModel)(({state}) => {
+  return {
+    'aria-invalid': state.error === 'error' ? true : undefined,
+    'aria-describedby': state.id ? `hint-${state.id}` : undefined,
+  };
+});
+
+export const FormFieldGroupInput = createSubcomponent('input')({
+  displayName: 'FormField.Input',
+  modelHook: useFormFieldModel,
+  elemPropsHook: useFormFieldGroupInput,
+})((elemProps: FormFieldGroupInputProps, Element) => {
+  return <Element {...handleCsProp(elemProps)} />;
+});

modules/preview-react/form-field/lib/FormFieldGroupList.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import {createSubcomponent} from '@workday/canvas-kit-react/common';
+
+import {FlexProps} from '@workday/canvas-kit-react/layout';
+
+import {createStencil, CSProps, calc, px2rem, handleCsProp} from '@workday/canvas-kit-styling';
+import {brand, system} from '@workday/canvas-tokens-web';
+
+import {useFormFieldModel} from './hooks';
+
+export interface FormFieldGroupListProps extends CSProps, FlexProps {}
+
+const formFieldGroupListStencil = createStencil({
+  base: {
+    display: 'flex',
+    flexDirection: 'column',
+    borderRadius: system.shape.x1,
+    gap: system.space.x2,
+    padding: `${px2rem(10)} ${system.space.x3} ${system.space.x2}`,
+    margin: `${calc.negate(system.space.x1)} ${calc.negate(system.space.x3)}`,
+    transition: '100ms box-shadow',
+    width: 'fit-content',
+  },
+  modifiers: {
+    error: {
+      error: {
+        boxShadow: `inset 0 0 0 ${px2rem(2)} ${brand.error.base}`,
+      },
+      alert: {
+        boxShadow: `inset 0 0 0 ${px2rem(1)} ${brand.alert.darkest}, inset 0 0 0 ${px2rem(3)} ${
+          brand.alert.base
+        }`,
+      },
+    },
+  },
+});
+
+export const FormFieldGroupList = createSubcomponent('div')({
+  displayName: 'FormFieldGroup.List',
+  modelHook: useFormFieldModel,
+})<FormFieldGroupListProps>(({children, ...elemProps}, Element, model) => {
+  return (
+    <Element
+      data-width="ck-formfield-width"
+      {...handleCsProp(elemProps, formFieldGroupListStencil({error: model.state.error}))}
+    >
+      {children}
+    </Element>
+  );
+});

modules/preview-react/form-field/lib/FormFieldLabel.tsx

@@ -60,7 +60,7 @@ export const FormFieldLabel = createSubcomponent('label')({
   displayName: 'FormField.Label',
   modelHook: useFormFieldModel,
   elemPropsHook: useFormFieldLabel,
-})<FormFieldLabelProps>(({children, typeLevel, variant, ...elemProps}, Element) => {
+})<FormFieldLabelProps>(({children, typeLevel, variant, ...elemProps}, Element, model) => {
   return (
     <Element {...mergeStyles(elemProps, formFieldLabelStencil({typeLevel, variant}))}>
       {children}

modules/preview-react/form-field/stories/FormField.stories.mdx

@@ -16,6 +16,7 @@ import {Hint} from './examples/Hint';
 import {FieldSet} from './examples/FieldSet';
 import {Grow} from './examples/Grow';
 import {ThemedError} from './examples/ThemedErrors';
+import {GroupedInputs} from './examples/GroupedInputs';
 
 <Meta title="Preview/Inputs/Form Field" component={FormField} />
 
@@ -102,12 +103,20 @@ for required fields are suffixed by a red asterisk.
 
 <ExampleCodeBlock code={Required} />
 
-### Field Set
+### Grouped Inputs
 
-Set the `as` prop of the `FormField` to `fieldset` and the `as` prop of the `FormField.Label` to
-`legend` when using `RadioGroup` to ensure proper accessbility.
+Use `FormFieldGroup` when you have a group of inputs that need to be associated to one another, like
+`RadioGroup` or a group of `Checkbox`'s. `FormFieldGroup` renders a `fieldset` element and
+`FormFieldGroup.Legend` renders a `legend` element. These elements will allow for correct
+accessibility of grouped inputs.
 
-<ExampleCodeBlock code={FieldSet} />
+`FormFieldGroup` supports the same props of `FormField`:
+
+- `error`: `"alert" | "error"` Defines the error around the whole group of inputs.
+- `orientation`: `"horizontal" | "vertical"` Defines the legend placement.
+- `isRequired`: `true` Defines if a group like RadioGroup is required.
+
+<ExampleCodeBlock code={GroupedInputs} />
 
 ### Custom
 

modules/preview-react/form-field/stories/examples/AllFields.tsx

@@ -9,6 +9,7 @@ import {TextArea} from '@workday/canvas-kit-react/text-area';
 import {Switch} from '@workday/canvas-kit-react/switch';
 import {calc, createStyles} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
+import {FormFieldGroup} from '../../lib/FormFieldGroup';
 
 const parentContainerStyles = createStyles({
   flexDirection: 'column',
@@ -47,27 +48,31 @@ export const AllFields = () => {
           </Select.Popper>
         </Select>
       </FormField>
-      <FormField as="fieldset" isRequired={true} error={'error'} orientation="horizontal" grow>
-        <FormField.Label as="legend">Radio Group Legend</FormField.Label>
-        <FormField.Container>
-          <FormField.Input as={RadioGroup}>
-            <RadioGroup.RadioButton value="deep-dish">Deep dish</RadioGroup.RadioButton>
-            <RadioGroup.RadioButton value="thin">Thin</RadioGroup.RadioButton>
-            <RadioGroup.RadioButton value="gluten-free">Gluten free</RadioGroup.RadioButton>
-            <RadioGroup.RadioButton value="cauliflower">Cauliflower</RadioGroup.RadioButton>
-            <RadioGroup.RadioButton value="butter">
-              Butter - the best thing to put on bread
-            </RadioGroup.RadioButton>
-          </FormField.Input>
-          <FormField.Hint>Error Message</FormField.Hint>
-        </FormField.Container>
-      </FormField>
-      <FormField as="fieldset" grow>
-        <FormField.Label as="legend">Checkbox Legend</FormField.Label>
-        <FormField.Input checked={true} as={Checkbox} label="Checkbox Label" />
-        <FormField.Input checked={false} as={Checkbox} label="Thin Crust" />
-        <FormField.Input checked={false} as={Checkbox} label="Extra Cheese" />
-      </FormField>
+      <FormFieldGroup error="error" orientation="horizontal" grow>
+        <FormFieldGroup.Legend>Choose Your Crust</FormFieldGroup.Legend>
+        <FormFieldGroup.Container>
+          <FormFieldGroup.List as={RadioGroup}>
+            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin-crust">
+              Thin Crust
+            </FormFieldGroup.Input>
+            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="hand-tossed">
+              Hand Tossed
+            </FormFieldGroup.Input>
+            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
+              Deep Dish
+            </FormFieldGroup.Input>
+            <FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
+              Cauliflower
+            </FormFieldGroup.Input>
+          </FormFieldGroup.List>
+        </FormFieldGroup.Container>
+      </FormFieldGroup>
+      <FormFieldGroup grow>
+        <FormFieldGroup.Legend>Checkbox Legend</FormFieldGroup.Legend>
+        <FormFieldGroup.Input checked={true} as={Checkbox} label="Checkbox Label" />
+        <FormFieldGroup.Input checked={false} as={Checkbox} label="Thin Crust" />
+        <FormFieldGroup.Input checked={false} as={Checkbox} label="Extra Cheese" />
+      </FormFieldGroup>
 
       <FormField orientation="horizontal" grow>
         <FormField.Label>Switch Label</FormField.Label>