@workday/canvas-kit-docs 16.0.10 → 16.0.12

package/dist/mdx/react/text-area/TextArea.mdx

@@ -1,8 +1,4 @@
-import {
-  ExampleCodeBlock,
-  Specifications,
-  SymbolDoc,
-} from '@workday/canvas-kit-docs';
+import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
 import Basic from './examples/Basic';
 import Disabled from './examples/Disabled';
 import Grow from './examples/Grow';
@@ -91,8 +87,8 @@ input component. By default, the orientation will be set to `vertical`.
 
 ### Required
 
-Set the `required` prop of the wrapping Form Field to `true` to indicate that the field is required.
-Labels for required fields are suffixed by a red asterisk.
+Set the `isRequired` prop of the wrapping Form Field to `true` to indicate that the field is
+required. Labels for required fields are suffixed by a red asterisk.
 
 <ExampleCodeBlock code={Required} />
 
@@ -100,38 +96,146 @@ Labels for required fields are suffixed by a red asterisk.
 
 Form Field provides error and caution states for Text Area. Set the `error` prop on Form Field to
 `"error"` or `"caution"` and use `FormField.Hint` to provide error messages. See
-[Form Field's Error documentation](/components/inputs/form-field/#error-states) for
-examples and accessibility guidance.
+[Form Field's Error documentation](/components/inputs/form-field/#error-states) for examples and
+accessibility guidance.
 
 ## Accessibility
 
-`TextArea` should be used with [Form Field](/components/inputs/form-field/) to
-ensure proper labeling, error handling, and help text association. See
-[FormField's accessibility documentation](/components/inputs/form-field/#accessibility)
-for comprehensive guidance on form accessibility best practices.
+The primary accessibility goal for `TextArea` is to give every user a visible, persistent label and
+clear instructions, and to ensure assistive technology users can identify the multi-line field and
+hear hints, errors, required state, and character-limit information when the control receives focus.
+Use `TextArea` when users need to enter multiple lines or paragraphs of text. For single-line values
+(names, emails, short answers), use [TextInput](/components/inputs/text-input/) instead.
+
+### Minimum Accessible Structure
+
+Build on the Basic example: label first, then the input inside `FormField.Field`. This order matches
+the DOM reading sequence and ensures the label's `htmlFor` targets the `<textarea>` before hint text
+follows the control.
+
+```tsx
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextArea} from '@workday/canvas-kit-react/text-area';
+
+<FormField>
+  <FormField.Label>Leave a Review</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextArea} />
+    <FormField.Hint>Share any additional feedback.</FormField.Hint>
+  </FormField.Field>
+</FormField>;
+```
+
+Every `TextArea` requires **`FormField`**, a visible **`FormField.Label`**, and
+**`FormField.Input as={TextArea}`** so the control has a programmatically determinable name,
+relationships, and instructions. See
+[FormField's accessibility documentation](/components/inputs/form-field/#accessibility) for shared
+form-field guidance. Include **`FormField.Hint`** for instructions, validation messages, or
+character counts—`FormField` associates that text with the text area through `aria-describedby`.
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically when you compose `TextArea` with `FormField` subcomponents.
+**Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by subcomponents_):
+
+- **`TextArea`**: Renders a native `<textarea>` element. Screen readers identify it as a multi-line
+  text input.
+- **`TextArea` `disabled`**: Maps to the native `disabled` attribute; disabled fields are removed
+  from the tab order.
+- **User-resizable dimensions**: Defaults to `resize: both` so users can adjust the control for
+  visual comfort.
+
+**Keyboard** (_standard `TextArea` behavior_):
+
+<kbd>Enter</kbd>: Inserts a new line (native `<textarea>` behavior). Do not add custom key handlers that prevent standard text editing.
 
-### Character Limits
+`TextArea` uses native `<textarea>` keyboard behavior (tab order, label activation, and text-editing
+shortcuts).
 
-When limiting text area length:
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
 
-- Use the `maxLength` attribute to enforce the limit programmatically.
-- For longer limits (100+ characters), consider adding character count information to
-  `FormField.Hint`.
-- Avoid announcing character counts after every keystroke, as this disrupts screen reader users.
-  Check out
-  [Debouncing an AriaLiveRegion: TextArea with character limit](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-aria-live-regions--docs#debouncing-an-arialiveregion-textarea-with-character-limit)
-  for an example of how to wait for users to stop typing before announcing the character count to
-  screen readers.
+- On focus, assistive technology announces the field label and, when applicable: required state,
+  invalid state (`error="error"`), and hint or error text via `aria-describedby`.
+- The current value or "blank" is announced when the text area receives focus.
+- The Caution state is visual only — `aria-invalid` is **not** set for `error="caution"`.
+- Disabled text areas may be announced as unavailable and are skipped in the tab order.
 
-### Screen Reader Experience
+For rendered label, input, and hint association markup, see the DOM examples in
+[FormField's Built-in Behaviors](/components/inputs/form-field/#built-in-behaviors). `TextArea`
+renders a native `<textarea>` in place of `<input>`.
 
-When properly implemented with `FormField`, screen readers will announce:
+### Accessibility Requirements
+
+Required in application code for an accessible `TextArea`. Rows marked _(conditional)_ apply only
+when the situation matches—otherwise omit.
+
+**If no design spec is provided:** use a visible `FormField.Label`, wrap the control with
+`FormField.Input as={TextArea}`, omit `isHidden`, keep default `resize: both`, omit a custom `id`
+unless testing or composition requires it, and omit a `ref` unless programmatic focus is required.
+
+**Programmatic focus** _(conditional — omit by default)_:
+
+Use a ref when the product needs to move focus to the text area after an action (for example,
+focusing the field after a validation error, or a control that focuses the text area). Do not attach
+a `ref` or call `focus()` unless the design or developer asks for it. See
+[Ref Forwarding](#ref-forwarding) under Usage for a complete Storybook example.
+
+```tsx
+const Example = () => {
+  const ref = React.useRef<HTMLTextAreaElement>(null);
+
+  const handleClick = () => {
+    ref.current?.focus();
+  };
+
+  return (
+    <>
+      <FormField>
+        <FormField.Label>Leave a Review</FormField.Label>
+        <FormField.Field>
+          <FormField.Input as={TextArea} ref={ref} />
+        </FormField.Field>
+      </FormField>
+      <PrimaryButton onClick={handleClick}>Focus Text Area</PrimaryButton>
+    </>
+  );
+};
+```
 
-- The label text when the text area receives focus.
-- Required, disabled, or read-only status.
-- Help text and error messages (via `aria-describedby`).
-- The current value or "blank" if empty.
-- That it's a multi-line text input field.
+| Requirement                        | How to satisfy                                                                                                                                                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Input wiring                       | **`FormField.Input as={TextArea}`** wrapping every `TextArea` instance. See [FormField accessibility](/components/inputs/form-field/#accessibility) for label, hint, error, and required wiring                                                                     |
+| Character limit _(conditional)_    | `maxLength` on **`FormField.Input`**, visible count in **`FormField.Hint`**, and debounced **`AriaLiveRegion`**. See [Aria Live Regions guide](?path=/docs/guides-accessibility-aria-live-regions--docs#debouncing-an-arialiveregion-textarea-with-character-limit) |
+| Programmatic focus _(conditional)_ | `ref` on **`FormField.Input`** and call `focus()` when moving focus to the field after an action—omit by default (see **Programmatic focus** above)                                                                                                                 |
+
+**Summary for code generation:**
+
+- **REQUIRED:** visible label, `FormField.Input as={TextArea}` wiring
+- **CONDITIONAL:** character limit with live region, programmatic focus via `ref`. See
+  [FormField accessibility](/components/inputs/form-field/#accessibility) for shared FormField
+  conditionals (hint/error, required, disabled, placeholder, stable `id`).
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- **Unlabeled text areas**: Do not use `TextArea` without `FormField` and `FormField.Label` (see
+  **Minimum accessible structure**). For shared FormField anti-patterns (manual ARIA wiring,
+  placeholder-only labels, color-only errors, broken ID references), see
+  [FormField Anti-Patterns](/components/inputs/form-field/#anti-patterns).
+- **Single-line input for multi-line content**: Do not use
+  [TextInput](/components/inputs/text-input/) when the user needs to enter paragraphs or multi-line
+  text; use `TextArea` instead.
+- **Per-keystroke character announcements**: Do not announce character counts after every keystroke;
+  debounce `AriaLiveRegion` updates so screen reader users are not interrupted while typing.
+- **Disabling resize unnecessarily**: Do not set `resize` to `none` unless there is a strong design
+  or layout requirement; users lose a visual comfort affordance that supports low-vision and motor
+  needs.
+- **Programmatic focus by default**: Do not attach a `ref` or call `focus()` on the text area unless
+  the design or developer asks for it (see **Programmatic focus** in Accessibility Requirements).
 
 ## Component API
 

package/dist/mdx/react/text-input/TextInput.mdx

@@ -1,8 +1,5 @@
-import {
-  ExampleCodeBlock,
-  Specifications,
-  SymbolDoc,
-} from '@workday/canvas-kit-docs';
+import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
+
 import Basic from './examples/Basic';
 import Disabled from './examples/Disabled';
 import Grow from './examples/Grow';
@@ -66,8 +63,6 @@ the width of its container.
 
 <ExampleCodeBlock code={Grow} />
 
-The `grow` prop may also be applied directly to the Text Input if Form Field is not being used.
-
 ### Label Position Horizontal
 
 Set the `orientation` prop of the Form Field to designate the position of the label relative to the
@@ -77,8 +72,8 @@ input component. By default, the orientation will be set to `vertical`.
 
 ### Required
 
-Set the `required` prop of the wrapping Form Field to `true` to indicate that the field is required.
-Labels for required fields are suffixed by a red asterisk.
+Set the `isRequired` prop of the wrapping Form Field to `true` to indicate that the field is
+required. Labels for required fields are suffixed by a red asterisk.
 
 <ExampleCodeBlock code={Required} />
 
@@ -97,11 +92,16 @@ something else, be sure to set the `width` property of `InputGroup.InnerStart` o
 `InputGroup.InnerEnd` to match the intended width of the element. Do not use the `cs` prop or any
 method to change width. The `width` prop is used to correctly position other inner elements.
 
+Do **not** use `FormField.Input as={InputGroup}` — that breaks label association. Render
+`FormField.Field as={InputGroup}`, hoist the input `id` from the Form Field model, and set it on
+`InputGroup.Input` (see the Icons example).
+
 <ExampleCodeBlock code={Icons} />
 
-> **Accessibility Note**: In this example, the mail icon is decorative and hidden from screen
-> readers. If icons are used for conveying meaning in addition to the label text, a text alternative
-> must be provided for screen readers.
+> **Accessibility Note**: Canvas Kit icons are already hidden from assistive technology — their SVG
+> markup sets `role="presentation"` and `focusable="false"` — so decorative icons like the mail icon
+> in this example need no extra attributes. If an icon conveys meaning beyond the label text,
+> provide that meaning as text for screen readers.
 
 ### Error States
 
@@ -112,33 +112,192 @@ accessibility guidance.
 
 ## Accessibility
 
-`TextInput` should be used with [Form Field](/components/inputs/form-field/) to ensure proper
-labeling, error handling, and help text association. See
-[FormField's accessibility documentation](/components/inputs/form-field/#accessibility) for
-comprehensive guidance on form accessibility best practices.
-
-### Autocomplete Attribute
-
-- Add appropriate `autoComplete` values to indicate the input's purpose (e.g., `"email"`, `"name"`,
-  `"street-address"`, `"tel"`). Read more about
-  [Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html).
-- Autocomplete enables browser autofill and helps assistive technologies understand the field's
-  purpose, benefiting users with cognitive disabilities and motor impairments.
-- Autocomplete also helps password managers identify the correct fields.
+The primary accessibility goal for `TextInput` is to give every user a visible, persistent label and
+clear instructions, and to ensure assistive technology users can identify the single-line field and
+hear hints, errors, required state, and input purpose when the control receives focus. Use
+`TextInput` for single-line values (names, emails, short answers). For multiple lines or paragraphs
+of text, use [TextArea](/components/inputs/text-area/) instead.
+
+### Minimum Accessible Structure
+
+Build on the Basic example: label first, then the input inside `FormField.Field`. This order matches
+the DOM reading sequence and ensures the label's `htmlFor` targets the `<input>` before hint text
+follows the control.
+
+```tsx
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+
+<FormField>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>We'll never share your email.</FormField.Hint>
+  </FormField.Field>
+</FormField>;
+```
 
-### Input Type for Mobile Keyboards
+Every `TextInput` requires **`FormField`**, a visible **`FormField.Label`**, and
+**`FormField.Input as={TextInput}`** so the control has a programmatically determinable name,
+relationships, and instructions. See
+[FormField's accessibility documentation](/components/inputs/form-field/#accessibility) for shared
+form-field guidance. Include **`FormField.Hint`** for instructions or validation
+messages—`FormField` associates that text with the input through `aria-describedby`.
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically when you compose `TextInput` with `FormField` subcomponents
+(and `InputGroup`, when used). **Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by subcomponents_):
+
+- **`TextInput`**: Renders a native `<input type="text">` by default. Screen readers identify it as
+  a single-line text input.
+- **`TextInput` `disabled`**: Maps to the native `disabled` attribute; disabled fields are removed
+  from the tab order.
+- **`InputGroup.ClearButton`**: Sets `role="presentation"` and `tabIndex={-1}` so the control is not
+  in the tab order and is not exposed as an operable button to screen readers. Clearing is available
+  via native keyboard editing in the input.
+- **`InputGroup.Input`**: Always ensures a `placeholder` attribute exists (empty string when unset)
+  so `:placeholder-shown` styling for the clear button works correctly.
+- **Canvas Kit icons** (for example `SystemIcon` inside `InputGroup`): SVG markup includes
+  `role="presentation"` and `focusable="false"`, which removes the implied `img` role. Decorative
+  icons need no `aria-hidden`.
+
+**Keyboard** (_standard `TextInput` behavior_):
+
+`TextInput` uses native `<input>` keyboard behavior (tab order, label activation, and text-editing
+shortcuts). Do not add custom key handlers that prevent standard text editing.
+
+**`InputGroup.ClearButton`** is intentionally not keyboard-focusable; users clear the value with
+standard input editing keys.
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the field label and, when applicable: required state,
+  invalid state (`error="error"`), and hint or error text via `aria-describedby`.
+- The current value or "blank" is announced when the input receives focus.
+- The Caution state is visual only — `aria-invalid` is **not** set for `error="caution"`.
+- Disabled inputs may be announced as unavailable and are skipped in the tab order.
+- **`InputGroup.ClearButton`** is not announced as a separate operable control.
+- Icons rendered inside **`InputGroup.InnerStart`** or **`InputGroup.InnerEnd`** are not announced,
+  because their SVG markup uses `role="presentation"`.
+
+For rendered label, input, and hint association markup, see the DOM examples in
+[FormField's Built-in Behaviors](/components/inputs/form-field/#built-in-behaviors). `TextInput`
+renders a native `<input>` (see FormField examples).
+
+### Accessibility Requirements
+
+Required in application code for an accessible `TextInput`. Rows marked _(conditional)_ apply only
+when the situation matches—otherwise omit.
+
+**If no design spec is provided:** use a visible `FormField.Label`, wrap the control with
+`FormField.Input as={TextInput}`, omit `isHidden`, omit a custom `id` unless testing or composition
+requires it, omit a `ref` unless programmatic focus is required, and omit `InputGroup` unless icons
+or a clear control are part of the design.
+
+**Programmatic focus** _(conditional — omit by default)_:
+
+Use a ref when the product needs to move focus to the input after an action (for example, focusing
+the field after a validation error, or a control that focuses the input). Do not attach a `ref` or
+call `focus()` unless the design or developer asks for it. See [Ref Forwarding](#ref-forwarding)
+under Usage for a complete Storybook example.
+
+```tsx
+const Example = () => {
+  const ref = React.useRef<HTMLInputElement>(null);
+
+  const handleClick = () => {
+    ref.current?.focus();
+  };
+
+  return (
+    <>
+      <FormField>
+        <FormField.Label>Email</FormField.Label>
+        <FormField.Field>
+          <FormField.Input as={TextInput} ref={ref} />
+        </FormField.Field>
+      </FormField>
+      <PrimaryButton onClick={handleClick}>Focus Text Input</PrimaryButton>
+    </>
+  );
+};
+```
 
-`TextInput` defaults to `<input type="text">`, but for better mobile keyboard support, use more
-specific `type` attributes (like `"email"`, `"tel"`, `"url"`, or `"search"`) as needed.
+**`InputGroup` with icons** _(conditional)_:
 
-### Screen Reader Experience
+When the design includes start/end icons or a clear control, compose `InputGroup` as
+`FormField.Field` (not as `FormField.Input`) and wire the input `id` from the Form Field model:
 
-When properly implemented with `FormField`, screen readers will announce:
+```tsx
+import {
+  FormField,
+  useFormFieldInput,
+  useFormFieldModel,
+} from '@workday/canvas-kit-react/form-field';
+import {SystemIcon} from '@workday/canvas-kit-react/icon';
+import {InputGroup} from '@workday/canvas-kit-react/text-input';
+import {mailIcon} from '@workday/canvas-system-icons-web';
+
+const model = useFormFieldModel();
+const {id: formFieldInputId} = useFormFieldInput(model);
+
+<FormField model={model}>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field as={InputGroup}>
+    <InputGroup.InnerStart>
+      <SystemIcon icon={mailIcon} />
+    </InputGroup.InnerStart>
+    <InputGroup.Input id={formFieldInputId} autoComplete="email" />
+    <InputGroup.InnerEnd>
+      <InputGroup.ClearButton />
+    </InputGroup.InnerEnd>
+  </FormField.Field>
+</FormField>;
+```
 
-- The label text when the input receives focus.
-- Required, disabled, or read-only status.
-- Help text and error messages (via `aria-describedby`).
-- The current value or "blank" if empty.
+| Requirement                           | How to satisfy                                                                                                                                                                                                                                               |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Input wiring                          | **`FormField.Input as={TextInput}`** wrapping every `TextInput` instance. See [FormField accessibility](/components/inputs/form-field/#accessibility) for label, hint, error, and required wiring                                                            |
+| Autocomplete _(conditional)_          | `autoComplete` on **`FormField.Input`** (or **`InputGroup.Input`**) with an appropriate token (e.g. `"email"`, `"name"`, `"street-address"`, `"tel"`). See [Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html) |
+| Input `type` _(conditional)_          | More specific `type` than `"text"` (e.g. `"email"`, `"tel"`, `"url"`, `"search"`) when a specialized mobile keyboard improves entry                                                                                                                          |
+| Icons / clear control _(conditional)_ | **`FormField.Field as={InputGroup}`** + **`InputGroup.Input`** with hoisted `id` (see **`InputGroup` with icons** above). Decorative icons need no extra attributes; when an icon conveys meaning beyond the label, convey that meaning as text              |
+| Programmatic focus _(conditional)_    | `ref` on **`FormField.Input`** and call `focus()` when moving focus to the field after an action—omit by default (see **Programmatic focus** above)                                                                                                          |
+
+**Summary for code generation:**
+
+- **REQUIRED:** visible label, `FormField.Input as={TextInput}` wiring
+- **CONDITIONAL:** `autoComplete`, specialized `type`, `InputGroup` icon/clear composition with
+  hoisted `id`, programmatic focus via `ref`. See
+  [FormField accessibility](/components/inputs/form-field/#accessibility) for shared FormField
+  conditionals (hint/error, required, disabled, placeholder, stable `id`).
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- **Unlabeled text inputs**: Do not use `TextInput` without `FormField` and `FormField.Label` (see
+  **Minimum accessible structure**). For shared FormField anti-patterns (manual ARIA wiring,
+  placeholder-only labels, color-only errors, broken ID references), see
+  [FormField Anti-Patterns](/components/inputs/form-field/#anti-patterns).
+- **Multi-line content in `TextInput`**: Do not use `TextInput` when the user needs to enter
+  paragraphs or multi-line text; use [TextArea](/components/inputs/text-area/) instead.
+- **`FormField.Input as={InputGroup}`**: Do not put `InputGroup` on `FormField.Input` — that breaks
+  label association. Use **`FormField.Field as={InputGroup}`**, hoist `id` from
+  `useFormFieldInput(model)`, and pass it to **`InputGroup.Input`** (see **`InputGroup` with icons**
+  in Accessibility Requirements and [Icons](#icons) under Usage).
+- **Re-wiring `ClearButton` a11y**: Do not override `InputGroup.ClearButton`'s `role` or `tabIndex`
+  to make it a focusable, announced button — Canvas Kit intentionally keeps clearing on the input.
+- **Redundant `aria-hidden` on icons**: Do not add `aria-hidden` to Canvas Kit icons — their SVG
+  markup already sets `role="presentation"` and `focusable="false"`.
+- **Meaningful icons without a text alternative**: Do not rely on an icon inside `InputGroup` to
+  convey information beyond the label; because icons are presentational, that meaning must come from
+  text such as **`FormField.Label`** or **`FormField.Hint`**.
+- **Programmatic focus by default**: Do not attach a `ref` or call `focus()` on the input unless the
+  design or developer asks for it (see **Programmatic focus** in Accessibility Requirements).
 
 ## Component API
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "16.0.10",
+  "version": "16.0.12",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -47,10 +47,10 @@
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
     "@workday/canvas-expressive-icons-web": "1.0.2",
-    "@workday/canvas-kit-labs-react": "^16.0.10",
-    "@workday/canvas-kit-preview-react": "^16.0.10",
-    "@workday/canvas-kit-react": "^16.0.10",
-    "@workday/canvas-kit-styling": "^16.0.10",
+    "@workday/canvas-kit-labs-react": "^16.0.12",
+    "@workday/canvas-kit-preview-react": "^16.0.12",
+    "@workday/canvas-kit-react": "^16.0.12",
+    "@workday/canvas-kit-styling": "^16.0.12",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-tokens-web": "^4.4.0",
     "markdown-to-jsx": "^7.2.0",
@@ -63,5 +63,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "e77be87cfbf4620e2e9f02fa722c489061833d66"
+  "gitHead": "e5a8658cb7f35a14333b162a8b4001d899a010a6"
 }