Skip to content

Commit

Permalink
chore: Add FormFieldGroup component and density example (#2865)
Browse files Browse the repository at this point in the history
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 <[email protected]>
Co-authored-by: @josh-bagwell <[email protected]>
Co-authored-by: @RayRedGoose <[email protected]>
  • Loading branch information
4 people authored Sep 20, 2024
1 parent 442af05 commit 87dbe31
Show file tree
Hide file tree
Showing 124 changed files with 2,150 additions and 766 deletions.
5 changes: 1 addition & 4 deletions cypress.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,6 @@ export default defineConfig({
retries: {
runMode: 2,
},
env: {
NODE_ENV: 'development', // or 'development', 'production', etc.
},

blockHosts: ['cdn.fontawesome.com'],

Expand All @@ -20,7 +17,7 @@ export default defineConfig({
framework: 'react',
bundler: 'webpack',
},
setupNodeEvents(on) {
setupNodeEvents(on, config) {
on('file:preprocessor', webpack());
},
viewportWidth: 1024,
Expand Down
12 changes: 9 additions & 3 deletions cypress/component/Tabs.spec.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down Expand Up @@ -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', () => {
Expand Down Expand Up @@ -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', () => {
Expand All @@ -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();
});

Expand All @@ -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', () => {
Expand Down
1 change: 1 addition & 0 deletions cypress/support/component.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ before(() => {
},
};
});

cy.configureAxe({
rules: [
{id: 'landmark-one-main', enabled: false}, // stories don't require navigation rules
Expand Down
168 changes: 150 additions & 18 deletions modules/docs/mdx/12.0-UPGRADE-GUIDE.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -123,7 +145,6 @@ The following components are affected:

- `Avatar`
- `Dialog`
- `FormField`
- `Modal`
- `Popup`
- `TextArea`
Expand All @@ -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{})`
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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
Expand Down
12 changes: 12 additions & 0 deletions modules/preview-react/_examples/stories/mdx/Density.mdx
Original file line number Diff line number Diff line change
@@ -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} />
Loading

0 comments on commit 87dbe31

Please sign in to comment.