chore: Add FormFieldGroup component and density example (#2865)

Fixes: #2805, #2806, #2820, [#2807](#2807) [category:Components] Release Note: - We've added a new `FormFieldGroup` component to use when grouping inputs like checkboxes and radio inputs that need to be associated to one another. Its API matches the `FormField` API where you have `error` prop as well as `id` `isRequired` and `orienation`. - `orientation` has been added back to `useFormFieldModel` to better support sub component styling. - Styles have been cleaned up to use `gap` for proper spacing between labels, inputs and hint text. - Added a new `FormField.Field` component to ensure proper alignment between label and inputs regardless of orientation and hint text. Ensure to wrap your inputs and hint text in this component. Co-authored-by: manuel.carrera <manuel.carrera@workday.com> Co-authored-by: @josh-bagwell <44883293+josh-bagwell@users.noreply.github.com> Co-authored-by: @RayRedGoose <48605821+RayRedGoose@users.noreply.github.com>
Workday · Sep 20, 2024 · 87dbe31 · 87dbe31
1 parent 442af05
commit 87dbe31
Show file tree

Hide file tree

Showing 124 changed files with 2,150 additions and 766 deletions.
diff --git a/cypress.config.ts b/cypress.config.ts
@@ -8,9 +8,6 @@ export default defineConfig({
   retries: {
     runMode: 2,
   },
-  env: {
-    NODE_ENV: 'development', // or 'development', 'production', etc.
-  },
 
   blockHosts: ['cdn.fontawesome.com'],
 
@@ -20,7 +17,7 @@ export default defineConfig({
       framework: 'react',
       bundler: 'webpack',
     },
-    setupNodeEvents(on) {
+    setupNodeEvents(on, config) {
       on('file:preprocessor', webpack());
     },
     viewportWidth: 1024,

diff --git a/cypress/component/Tabs.spec.tsx b/cypress/component/Tabs.spec.tsx
@@ -481,11 +481,14 @@ describe('Tabs', () => {
   context('when [Components/Containers/Tabs, OverflowTabs] story is rendered', () => {
     beforeEach(() => {
       cy.mount(<OverflowTabs />);
-      cy.wait(500);
     });
 
     it('should pass axe checks', () => {
-      cy.checkA11y();
+      cy.checkA11y('[role="tablist"]', {
+        rules: {
+          'aria-required-children': {enabled: false},
+        },
+      });
     });
 
     it('should not show the "More" button', () => {
@@ -519,7 +522,7 @@ describe('Tabs', () => {
     context('when tab list container is only 500px wide', () => {
       beforeEach(() => {
         cy.findByRole('button', {name: '500px'}).click();
-        cy.wait(0);
+        cy.findByRole('button', {name: '500px'}).should('have.attr', 'aria-pressed', 'true');
       });
 
       it('should pass axe checks', () => {
@@ -587,6 +590,7 @@ describe('Tabs', () => {
     context('when tab list container is only 360px wide', () => {
       beforeEach(() => {
         cy.findByRole('button', {name: '360px'}).click();
+        cy.findByRole('button', {name: '360px'}).should('have.attr', 'aria-pressed', 'true');
       });
 
       it('should pass axe checks', () => {
@@ -613,6 +617,7 @@ describe('Tabs', () => {
 
       context('when the "More" button is clicked', () => {
         beforeEach(() => {
+          cy.findByRole('button', {name: '360px'}).should('have.attr', 'aria-pressed', 'true');
           cy.findByRole('button', {name: 'More'}).click();
         });
 
@@ -629,6 +634,7 @@ describe('Tabs', () => {
     context('when tab list container is only 150px wide', () => {
       beforeEach(() => {
         cy.findByRole('button', {name: '150px'}).click();
+        cy.findByRole('button', {name: '150px'}).should('have.attr', 'aria-pressed', 'true');
       });
 
       it('should pass axe checks', () => {

diff --git a/cypress/support/component.ts b/cypress/support/component.ts
@@ -54,6 +54,7 @@ before(() => {
       },
     };
   });
+
   cy.configureAxe({
     rules: [
       {id: 'landmark-one-main', enabled: false}, // stories don't require navigation rules

diff --git a/modules/docs/mdx/12.0-UPGRADE-GUIDE.mdx b/modules/docs/mdx/12.0-UPGRADE-GUIDE.mdx
@@ -42,12 +42,13 @@ A note to the reader:
 - [Styling Updates](#styling-updates)
   - [Compatability Mode](#compatability-mode)
 - [Deprecations](#deprecations)
+  - [Form Field Container](#form-field-container)
 - [Removals](#removals)
   - [InputIconContainer](#inputiconcontainer)
-  - [Select (Preview)](#select-preview)
 - [Component Updates](#component-updates)
   - [Styling API and CSS Tokens](#styling-api-and-css-tokens)
   - [Avatar](#avatar)
+  - [Select](#select)
   - [Form Field](#form-field)
   - [Text Area](#text-area)
 - [Troubleshooting](#troubleshooting)
@@ -83,17 +84,38 @@ We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to co
 in a future major release. This signals consumers to migrate to a more stable alternative before the
 deprecated code is removed.
 
-## Removals
+### Form Field Container
 
-Removals are deletions from our codebase and you can no longer consume this component. We've either
-promoted or replaced a component or utility.
+**PR:** [#2865](https://github.com/Workday/canvas-kit/pull/2865)
 
-### Select (Preview)
+We've deprecated `FormField.Container`. Please use `FormField.Field` or `FormFieldGroup.Field` for
+grouped inputs, this ensures proper label alignment and spacing of inputs and hint text, regardless
+of the orientation.
 
-**PR:** [#2796](https://github.com/Workday/canvas-kit/pull/2796)
+```tsx
+// v11
+<FormField>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Container>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>You must provide an email</FormField.Hint>
+  </FormField.Container>
+</FormField>
+
+// v12
+<FormField>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>You must provide an email</FormField.Hint>
+  </FormField.Field>
+</FormField>
+```
+
+## Removals
 
-We've removed the `Select` component that was in Preview. Please use the compound
-[Select component from Main](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-select--basic).
+Removals are deletions from our codebase and you can no longer consume this component. We've either
+promoted or replaced a component or utility.
 
 ### InputIconContainer
 
@@ -123,7 +145,6 @@ The following components are affected:
 
 - `Avatar`
 - `Dialog`
-- `FormField`
 - `Modal`
 - `Popup`
 - `TextArea`
@@ -136,6 +157,12 @@ The following components are affected:
 
 ### Avatar
 
+**PR** [#2793](https://github.com/Workday/canvas-kit/pull/2793)
+
+Avatar has been updated to use our new
+[styling utilities](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-stencil).
+The following changes have been made to the API:
+
 - `Avatar.Size` has been deprecated. The `size` prop still accepts `Avatar.Size` in addition to the
   following values:
   `"extraExtraLarge" | "extraLarge" | "large" | "medium" | "small" | "extraSmall" | (string{})`
@@ -149,12 +176,16 @@ The following components are affected:
 
 ### Form Field
 
-**PR** [#2881](https://github.com/Workday/canvas-kit/pull/2881)
+**PRs:** [#2865](https://github.com/Workday/canvas-kit/pull/2865),
+[#2881](https://github.com/Workday/canvas-kit/pull/2881)
+
+We've promoted FormField from [Preview](#preview) to [Main](#main). The following changes has been
+made to provide more flexibility and better explicit components when using inputs.
 
-The orientation prop on the `FormField` component will be updated to accept the following values:
-`vertical`, `horizontalStart`, and `horizontalEnd`. `horizontal` will still be accepted as a value
-in v12, but it will be deprecated and slated for removal in a future major release. These changes
-are intended to provide more flexibility with label alignments on `FormField` elements.
+- The orientation prop on the `FormField` component will be updated to accept the following values:
+  `vertical`, `horizontalStart`, and `horizontalEnd`. `horizontal` will still be accepted as a value
+  in v12, but it will be deprecated and slated for removal in a future major release. These changes
+  are intended to provide more flexibility with label alignments on `FormField` elements.
 
 > **Note**: The horizontal alignment of start and end are relative to its container, meaning start
 > and end match the flex property of `flex-start` and `flex-end`. This is especially applicable for
@@ -163,9 +194,105 @@ are intended to provide more flexibility with label alignments on `FormField` el
 > **Note:** Orientation "horizontal" has been deprecated. You will see a console warn message
 > suggesting to update your types and usage to `horizontalStart`, `horizontalEnd` or `vertical`.
 
+- `useFormFieldModel`: `orientation` has been added back into `useFormFieldModel`. While we still
+  support compat mode due to
+  [style merging issues](https://github.com/Workday/canvas-kit/discussions/2893), having orientation
+  on the model allows for proper styling of sub components.
+
+- Styles clean up. `FormField.Hint` and `FormField.Label` where using `margin` for spacing. We've
+  updated styles so that the containing element uses `gap` for proper spacing.
+
+> **Note:** If spacing seems off between the input and hint text, ensure you're using
+> `FormField.Field` wrappign your input and hint text.
+
 🤖 The codemod will handle the change of `orientation="horizontal"` to
 `orientation="horizontalStart"` if you're using the string literal values.
 
+#### Form Field Group
+
+We've added a new component 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` supports the same props of `FormField`:
+
+- `error`: `"alert" | "error"` Defines the error around the whole group of inputs.
+- `orientation`: `"horizontalStart" | "horizontalEnd" | "vertical" | "horizontal" `. Defines the
+  label placement.
+- `isRequired`: `true` Defines if a group like `RadioGroup` is required.
+
+#### FormField Field
+
+We've added a new sub-component to `FormField` and `FormFieldGroup`, `FormField.Field` and
+`FormFieldGroup.Field`. This sub-component is meant to ensure that the label is always aligned with
+the input regardless of the `orientation`prop's value on`FormField` or `FormFieldGroup`. This
+component should replace `FormField.Container` and always be used to ensure proper alignment of the
+label and hint text. Our examples have been updated to reflect this.
+
+Although there is no codemod for this change and it's non-breaking, we suggest moving towards adding
+this sub-component when using `FormField`. This component also exists on `FormFieldGroup`.
+
+```tsx
+<FormField orientation="horizontal">
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>You must provide an email</FormField.Hint>
+  </FormField.Field>
+</FormField>
+```
+
+### Select
+
+**PR:** [#2865](https://github.com/Workday/canvas-kit/pull/2865)
+
+As we transition to use our CSS tokens to provide better theming capabilities and our new styling
+methods, we're moving away from components extending `Themeable`. `Themeable` has been removed from
+`SelectProps.`
+
+If you wish to theme `Select` we suggest using the CanvasProvider to do so.
+
+```tsx
+const theme: PartialEmotionCanvasTheme = {
+  canvas: {
+    palette: {
+      common: {
+        focusOutline: 'pink',
+      },
+      primary: {
+        main: 'green',
+        light: 'lightgreen',
+      },
+    },
+  },
+};
+
+//...
+
+<CanvasProvider theme={theme}>
+  <Flex cs={parentContainerStyles}>
+    <Select items={options}>
+      <FormField>
+        <FormField.Label>Contact</FormField.Label>
+        <FormField.Input as={Select.Input} onChange={handleChange} />
+        <Select.Popper>
+          <Select.Card>
+            <Select.List>
+              {item => {
+                return <Select.Item>{item}</Select.Item>;
+              }}
+            </Select.List>
+          </Select.Card>
+        </Select.Popper>
+      </FormField>
+    </Select>
+    Selected Value: {value}
+  </Flex>
+</CanvasProvider>;
+```
+
 ### Text Area
 
 **PR:** [#2825](https://github.com/Workday/canvas-kit/pull/2825)
@@ -176,10 +303,15 @@ type.
 
 ```tsx
 // v11
-interface MyProps { resize?: TextAreaResizeDirection }
-
-// 12 type ValueOf<T> = T[keyof T]; interface MyProps { resize?:
-ValueOf<typeof TextAreaResizeDirection> }
+interface MyProps {
+  resize?: TextAreaResizeDirection;
+}
+
+// 12
+type ValueOf<T> = T[keyof T];
+interface MyProps {
+  resize?: ValueOf<typeof TextAreaResizeDirection>;
+}
 ```
 
 ## Troubleshooting

diff --git a/modules/preview-react/_examples/stories/mdx/Density.mdx b/modules/preview-react/_examples/stories/mdx/Density.mdx
@@ -0,0 +1,12 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import {Density} from './examples/Density';
+
+<Meta title="Examples/Forms/Density and Alignment" />
+
+# Canvas Kit Density Examples
+
+Although we currently don't support a density system, it's common practice to provide varying
+options to users, especially in the context of forms. Below is an example of how you can style our
+from elements to achieve the desired density.
+
+<ExampleCodeBlock code={Density} />