@workday/canvas-kit-docs 17.0.0-alpha.0613-next.0 → 17.0.0-alpha.0619-next.0

package/dist/es6/lib/docs.js

@@ -412448,7 +412448,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
   {
     "name": "Select",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/select/lib/Select.tsx",
-    "description": "Use `Select` to allow users to choose an option from a list or type characters to select a matching option.\n\n**Note: `Select` must wrap `FormField` and `FormField` must wrap all `Select` children to ensure proper accessibility. **\n\n```tsx\n<Select items={options}>\n <FormField label=\"Your Label\">\n   <Select.Input onChange={e => handleChange(e)} id=\"contact-select\" />\n   <Select.Popper>\n     <Select.Card>\n       <Select.List>\n         {item => <Select.Item>{item.id}</Select.Item>}\n       </Select.List>\n     </Select.Card>\n     </Select.Popper>\n   </FormField>\n</Select>\n```",
+    "description": "Use `Select` to allow users to choose an option from a list or type characters to select a matching option.\n\n**Note: Wrap `Select` with `FormField` and compose `FormField.Input as={Select.Input}` so the combobox receives the field label.**\n\n```tsx\n<FormField>\n  <FormField.Label>Contact</FormField.Label>\n  <FormField.Field>\n    <Select items={options}>\n      <FormField.Input as={Select.Input} onChange={e => handleChange(e)} />\n      <Select.Popper>\n        <Select.Card>\n          <Select.List>{item => <Select.Item>{item}</Select.Item>}</Select.List>\n        </Select.Card>\n      </Select.Popper>\n    </Select>\n  </FormField.Field>\n</FormField>\n```",
     "declarations": [
       {
         "name": "Select",
@@ -412536,7 +412536,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         {
           "name": "Input",
           "symbol": "SelectInput",
-          "description": "`Select.Input` renders a {@link ComboboxMenu Combobox.Input} that handles keyboard navigation and interaction defined by [WAI](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/).\nThis component can either be [controlled or uncontrolled](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).\n\n```tsx\n<Select items={options}>\n  <FormField label=\"Contact\">\n    <Select.Input onChange={(event) => handleChange(event)}>\n    ...\n  </FormField>\n</Select>\n```",
+          "description": "`Select.Input` renders a {@link ComboboxMenu Combobox.Input} that handles keyboard navigation and interaction defined by [WAI](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/).\nThis component can either be [controlled or uncontrolled](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).\n\nCompose it as `FormField.Input as={Select.Input}` so label, required, and error wiring apply.\n\n```tsx\n<FormField>\n  <FormField.Label>Contact</FormField.Label>\n  <FormField.Field>\n    <Select items={options}>\n      <FormField.Input as={Select.Input} onChange={event => handleChange(event)} />\n      ...\n    </Select>\n  </FormField.Field>\n</FormField>\n```",
           "declarations": [
             {
               "name": "Input",
@@ -412552,7 +412552,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         {
           "name": "Card",
           "symbol": "SelectCard",
-          "description": "`Select.Card` renders a {@link ComboboxCard Combobox.Card}. You have access to all `Card` props.\n\n**Note: The card will be the width of its corresponding `Select.Input`**.\n\n```tsx\n<Select items={options}>\n <FormField label=\"Your Label\">\n   <Select.Input onChange={(event) => handleChange(event)}>\n   <Select.Popper>\n     <Select.Card>\n       ...\n     </Select.Card>\n   </Select.Popper>\n </FormField>\n</Select>\n```",
+          "description": "`Select.Card` renders a {@link ComboboxCard Combobox.Card}. You have access to all `Card` props.\n\n**Note: The card will be the width of its corresponding `Select.Input`**.\n\n```tsx\n<FormField>\n  <FormField.Label>Contact</FormField.Label>\n  <FormField.Field>\n    <Select items={options}>\n      <FormField.Input as={Select.Input} onChange={event => handleChange(event)} />\n      <Select.Popper>\n        <Select.Card>...</Select.Card>\n      </Select.Popper>\n    </Select>\n  </FormField.Field>\n</FormField>\n```",
           "declarations": [
             {
               "name": "Card",
@@ -412568,7 +412568,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         {
           "name": "Item",
           "symbol": "SelectItem",
-          "description": "`Select.Item` renders a {@link ComboboxMenuItem Combobox.Menu.Item} with aria role of `option`. You can optionally render a `Icon`.\n\n```tsx\n<Select items={options}>\n <FormField label=\"Your Label\">\n   <Select.Input onChange={(event) => handleChange(event)}>\n     <Select.Popper>\n       <Select.Card>\n         <Select.List>\n           {(item) => <Select.Item><Select.Item.Icon icon={icon} />{item}</Select.Item>}\n         </Select.List\n       </Select.Card>\n     </Select.Popper>\n </FormField>\n</Select>\n```",
+          "description": "`Select.Item` renders a {@link ComboboxMenuItem Combobox.Menu.Item} with aria role of `option`. You can optionally render a `Icon`.\n\n```tsx\n<FormField>\n  <FormField.Label>Contact</FormField.Label>\n  <FormField.Field>\n    <Select items={options}>\n      <FormField.Input as={Select.Input} onChange={event => handleChange(event)} />\n      <Select.Popper>\n        <Select.Card>\n          <Select.List>\n            {item => (\n              <Select.Item>\n                <Select.Item.Icon icon={icon} />\n                {item}\n              </Select.Item>\n            )}\n          </Select.List>\n        </Select.Card>\n      </Select.Popper>\n    </Select>\n  </FormField.Field>\n</FormField>\n```",
           "declarations": [
             {
               "name": "Item",

package/dist/es6/lib/specs.js

@@ -1491,6 +1491,26 @@ module.exports = {specifications: [
               {
                 "type": "it",
                 "name": "should not have any axe errors"
+              },
+              {
+                "type": "describe",
+                "name": "when the form is submitted with an empty required select",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should focus the first invalid field"
+                  }
+                ]
+              },
+              {
+                "type": "describe",
+                "name": "when a later required field is empty",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should focus the first invalid field"
+                  }
+                ]
               }
             ]
           }

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.1.2",
-    "@workday/canvas-kit-preview-react": "16.1.2",
-    "@workday/canvas-kit-react": "16.1.2",
-    "@workday/canvas-kit-react-fonts": "^16.1.2",
-    "@workday/canvas-kit-styling": "16.1.2",
+    "@workday/canvas-kit-labs-react": "16.1.4",
+    "@workday/canvas-kit-preview-react": "16.1.4",
+    "@workday/canvas-kit-react": "16.1.4",
+    "@workday/canvas-kit-react-fonts": "^16.1.4",
+    "@workday/canvas-kit-styling": "16.1.4",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -19,11 +19,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.1.2",
-    "@workday/canvas-kit-preview-react": "16.1.2",
-    "@workday/canvas-kit-react": "16.1.2",
-    "@workday/canvas-kit-react-fonts": "^16.1.2",
-    "@workday/canvas-kit-styling": "16.1.2",
+    "@workday/canvas-kit-labs-react": "16.1.4",
+    "@workday/canvas-kit-preview-react": "16.1.4",
+    "@workday/canvas-kit-react": "16.1.4",
+    "@workday/canvas-kit-react-fonts": "^16.1.4",
+    "@workday/canvas-kit-styling": "16.1.4",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/mdx/accessibility/AccessibilityOverview.mdx

@@ -86,7 +86,9 @@ Further reading:
 ```
 
 Check out our [Aria Live Region Examples](?path=/docs/guides-accessibility-aria-live-regions--docs)
-for more detailed information about this topic.
+for more detailed information about this topic. For labels, error text, `aria-invalid`, and focus
+after a failed submit, see
+[Form Validation](?path=/docs/guides-accessibility-form-validation--docs).
 
 Sometimes, things change on a webpage without the whole page reloading. Think of a live sports score
 that updates every few seconds or a search result that appears as you type. For users of screen

package/dist/mdx/preview-react/_examples/mdx/FormLibraryExample.mdx

@@ -1,7 +1,39 @@
 import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
 import TextInputWithReactHookForm from './examples/TextInputWithReactHookForm';
 
 
-## Uncontrolled Text Inputs Using React Hook Form
+# Form Validation with React Hook Form and Yup
+
+Accessible form validation is not a library feature. It is a composition of **labels**, **error text
+tied to the field**, **`aria-invalid`**, and **keyboard focus**. Canvas Kit
+[`FormField`](?path=/docs/components-inputs-form-field--docs#accessibility) owns the first three
+when you use its subcomponents. The application owns when validation runs and where focus goes after
+submit.
+
+1. **Identify every field, including required ones** Set `autoComplete` with a
+   [standard token](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill)
+   when the field collects a known personal data type (`username`, `current-password`, `email`,
+   `name`). That supports
+   [WCAG 1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html).
+2. **Move focus to the first invalid field after submit** Failed submit must not leave focus on the
+   submit button. Keyboard and screen-reader users need to land on the first field that is still
+   invalid, in **DOM order**.
+3. **Choose when to validate** Prefer validating **on submit**, then on **blur / touched** for
+   fields the user has already visited (`mode: 'onTouched'` in this example). Validating on every
+   keystroke while the field is still incomplete is noisy and can announce `aria-invalid` too early.
+   (Relevant criteria:
+   [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html),
+   [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html).)
+4. **Do not use a live region for every field error** Field errors belong on the field
+   (`aria-invalid` + `aria-describedby`). They are announced when the field **receives focus**. A
+   page-level live region that restates every invalid field on submit is easy to overdo. Live
+   announcements cannot be replayed, can interrupt, and have uneven support. If you add a form-level
+   summary, keep it short, do not duplicate every message, and read
+   [ARIA Live Regions](?path=/docs/guides-accessibility-aria-live-regions--docs) first.
+
+This example wires `FormField`, `TextInput`, `Select`, and `InputGroup` to
+[React Hook Form](https://www.react-hook-form.com/) with [Yup](https://github.com/jquense/yup). The
+same practices apply if you use Formik, a server round-trip, or hand-rolled state.
 
 <ExampleCodeBlock code={TextInputWithReactHookForm} />

package/dist/mdx/preview-react/_examples/mdx/examples/TextInputWithReactHookForm.tsx

@@ -1,13 +1,18 @@
 import React from 'react';
-import {FieldErrorsImpl, useForm} from 'react-hook-form';
-import {SchemaOf, object, string} from 'yup';
+import {FieldErrors, Resolver, useForm} from 'react-hook-form';
+import {SchemaOf, ValidationError, object, string} from 'yup';
 
 import {PrimaryButton, TertiaryButton} from '@workday/canvas-kit-react/button';
-import {useUniqueId} from '@workday/canvas-kit-react/common';
-import {FormField} from '@workday/canvas-kit-react/form-field';
+import {ErrorType, useUniqueId} from '@workday/canvas-kit-react/common';
+import {
+  FormField,
+  useFormFieldInput,
+  useFormFieldModel,
+} from '@workday/canvas-kit-react/form-field';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {Select} from '@workday/canvas-kit-react/select';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {InputGroup, TextInput} from '@workday/canvas-kit-react/text-input';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
 import {createStyles, px2rem} from '@workday/canvas-kit-styling';
 import {visibleIcon, visibleStrikethroughIcon} from '@workday/canvas-system-icons-web';
 import {system} from '@workday/canvas-tokens-web';
@@ -18,31 +23,30 @@ const styles = createStyles({
   alignItems: 'flex-start',
 });
 
-type YupValidationResolver = <T extends {}>(
-  validationSchema: SchemaOf<T>
-) => (data: T) => Promise<{values: T; errors: {}} | {values: {}; errors: FieldErrorsImpl<T>}>;
-
-const useYupValidationResolver: YupValidationResolver = validationSchema => {
-  return React.useCallback(
+const useYupValidationResolver = <T extends {}>(validationSchema: SchemaOf<T>): Resolver<T> => {
+  return React.useCallback<Resolver<T>>(
     async data => {
       try {
-        const values = await validationSchema.validate(data, {abortEarly: false});
-        return {values, errors: {}};
-      } catch (errors) {
-        return {
-          values: {},
-          //@ts-ignore
-          errors: errors.inner.reduce(
-            (allErrors, currentError) => ({
-              ...allErrors,
-              [currentError.path]: {
-                type: currentError.type ?? 'validation',
-                message: currentError.message,
-              },
-            }),
-            {}
-          ),
-        };
+        await validationSchema.validate(data, {abortEarly: false});
+        return {values: data, errors: {}};
+      } catch (error) {
+        // Yup throws a `ValidationError` for failed validation. Anything else is a real error.
+        if (!ValidationError.isError(error)) {
+          throw error;
+        }
+
+        const errors = error.inner.reduce<Record<string, {type: string; message: string}>>(
+          (allErrors, currentError) => ({
+            ...allErrors,
+            [currentError.path ?? '']: {
+              type: currentError.type ?? 'validation',
+              message: currentError.message,
+            },
+          }),
+          {}
+        );
+
+        return {values: {}, errors: errors as FieldErrors<T>};
       }
     },
     [validationSchema]
@@ -74,6 +78,9 @@ const options = [
 ];
 
 export default () => {
+  const formRef = React.useRef<HTMLFormElement>(null);
+  const [showPassword, setShowPassword] = React.useState(false);
+  const [submitAttempt, setSubmitAttempt] = React.useState(0);
   const {
     handleSubmit,
     register,
@@ -84,19 +91,36 @@ export default () => {
       password: 'foobarbaz',
       role: '',
     },
-    resolver: useYupValidationResolver(validationSchema),
+    resolver: useYupValidationResolver<LoginSchema>(validationSchema),
     mode: 'onTouched',
+    shouldFocusError: true,
   });
 
-  const onSubmit = handleSubmit(values => {
-    setShowPassword(false);
-    // Send data to server
-    setTimeout(() => {
-      alert(JSON.stringify(values, null, 2));
-    }, 0);
-  });
+  const onSubmit = handleSubmit(
+    values => {
+      setShowPassword(false);
+      // Send data to server
+      setTimeout(() => {
+        alert(JSON.stringify(values, null, 2));
+      }, 0);
+    },
+    () => {
+      // Count failed submits so we can move focus after FormField paints `aria-invalid`.
+      setSubmitAttempt(count => count + 1);
+    }
+  );
+
+  React.useEffect(() => {
+    if (submitAttempt === 0) {
+      return;
+    }
+
+    const firstInvalidField = formRef.current?.querySelector<HTMLElement>(
+      '[aria-invalid="true"]:not([aria-hidden="true"]):not([tabindex="-1"])'
+    );
+    firstInvalidField?.focus();
+  }, [submitAttempt, errors]);
 
-  const [showPassword, setShowPassword] = React.useState(false);
   const passwordId = useUniqueId();
   const passwordRef = React.useRef<HTMLInputElement | null>(null);
   const {ref: passwordCallbackRef, ...passwordRegistration} = register('password');
@@ -104,8 +128,15 @@ export default () => {
     passwordCallbackRef(ref);
     passwordRef.current = ref;
   };
+  // `InputGroup` renders the input, so hoist the model to keep the label, hint, and error wiring.
+  const passwordModel = useFormFieldModel({
+    id: passwordId,
+    isRequired: true,
+    error: errors.password ? 'error' : undefined,
+  });
+  const passwordInputProps = useFormFieldInput(passwordModel);
   return (
-    <form onSubmit={onSubmit} action="." noValidate={true}>
+    <form ref={formRef} onSubmit={onSubmit} action="." noValidate={true}>
       <Flex cs={styles}>
         <FormField
           orientation="vertical"
@@ -143,35 +174,33 @@ export default () => {
           </FormField.Field>
           <FormField.Hint>{errors.email?.message}</FormField.Hint>
         </FormField>
-        <FormField
-          orientation="vertical"
-          id={passwordId}
-          isRequired={true}
-          error={!!errors.password ? 'error' : undefined}
-        >
+        <FormField model={passwordModel} orientation="vertical">
           <FormField.Label>Password</FormField.Label>
-          <Flex cs={{gap: system.gap.md}}>
-            <FormField.Field>
-              <FormField.Input
-                as={TextInput}
-                {...passwordRegistration}
-                type={showPassword ? 'text' : 'password'}
-                autoComplete="current-password"
-                spellCheck={false}
-                ref={combinePasswordRef}
-              />
-            </FormField.Field>
-            <TertiaryButton
-              type="button"
-              icon={showPassword ? visibleStrikethroughIcon : visibleIcon}
-              aria-label={showPassword ? 'Hide Password' : 'Show Password'}
-              aria-controls={`input-${passwordId}`}
-              onClick={() => {
-                setShowPassword(state => !state);
-                passwordRef.current?.focus();
-              }}
+          <FormField.Field as={InputGroup}>
+            <InputGroup.Input
+              {...passwordInputProps}
+              {...passwordRegistration}
+              error={errors.password ? ErrorType.Error : undefined}
+              type={showPassword ? 'text' : 'password'}
+              autoComplete="current-password"
+              spellCheck={false}
+              ref={combinePasswordRef}
             />
-          </Flex>
+            <InputGroup.InnerEnd>
+              <Tooltip title={showPassword ? 'Hide Password' : 'Show Password'}>
+                <TertiaryButton
+                  type="button"
+                  size="small"
+                  icon={showPassword ? visibleStrikethroughIcon : visibleIcon}
+                  aria-controls={`input-${passwordId}`}
+                  onClick={() => {
+                    setShowPassword(state => !state);
+                    passwordRef.current?.focus();
+                  }}
+                />
+              </Tooltip>
+            </InputGroup.InnerEnd>
+          </FormField.Field>
           <FormField.Hint>{errors.password?.message || passwordHint}</FormField.Hint>
         </FormField>
 

package/dist/mdx/react/_examples/mdx/Density.mdx

@@ -4,8 +4,24 @@ import Density from './examples/Density';
 
 # 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.
+Canvas Kit does not ship a density system. Forms often still need compact, default, and
+comfortable spacing. This example shows how to style Canvas Kit form elements with
+`createStencil` to get three densities.
+
+Density in this demo changes:
+
+- **Input height and padding** (`system.size.sm` / `md` / `md + 4px`)
+- **Label and input type** (`subtext.medium` / `subtext.large` / `body.small`)
+- **Space between fields** (`system.gap.md` / `lg` / `xl`)
+- **Space between a label and its input** (tighter when labels are vertical)
+
+| Density | Input height | Field spacing | Type |
+| ------- | ------------ | ------------- | ---- |
+| High    | 32px         | 16px          | `subtext.medium` |
+| Medium  | 40px         | 24px          | `subtext.large` |
+| Low     | 48px         | 32px          | `body.small` |
+
+`Switch` does not expose a size API, so its dimensions stay the same across densities. Only its
+label type and surrounding field spacing change.
 
 <ExampleCodeBlock code={Density} />