From e13e0b8c78db869f4d377701b0fb326eb1c3a70c Mon Sep 17 00:00:00 2001
From: ssingh <ssingh@easypost.com>
Date: Mon, 13 Nov 2023 17:08:59 -0800
Subject: [PATCH] replace isLabelVisuallyHidden with aria-label

---
 .changeset/empty-oranges-laugh.md             |  5 ++++
 documentation/specs/Select.md                 |  8 +++---
 documentation/specs/TextField.md              | 13 +++------
 documentation/specs/Textarea.md               | 13 +++------
 .../src/InputField/InputField.module.scss     |  4 ---
 easy-ui-react/src/InputField/InputField.tsx   | 27 +++++++++----------
 easy-ui-react/src/InputField/Label.tsx        | 21 ++-------------
 easy-ui-react/src/Select/Select.mdx           |  7 +++--
 easy-ui-react/src/Select/Select.stories.tsx   |  2 +-
 easy-ui-react/src/Select/Select.tsx           |  2 --
 easy-ui-react/src/Select/SelectField.tsx      | 27 +++++++++----------
 easy-ui-react/src/TextField/TextField.mdx     |  2 +-
 .../src/TextField/TextField.stories.tsx       |  4 +--
 easy-ui-react/src/TextField/TextField.tsx     |  8 +++---
 easy-ui-react/src/Textarea/Textarea.mdx       |  2 +-
 .../src/Textarea/Textarea.stories.tsx         |  4 +--
 easy-ui-react/src/Textarea/Textarea.tsx       |  8 +++---
 17 files changed, 58 insertions(+), 99 deletions(-)
 create mode 100644 .changeset/empty-oranges-laugh.md

diff --git a/.changeset/empty-oranges-laugh.md b/.changeset/empty-oranges-laugh.md
new file mode 100644
index 00000000..55fd21c8
--- /dev/null
+++ b/.changeset/empty-oranges-laugh.md
@@ -0,0 +1,5 @@
+---
+"@easypost/easy-ui": minor
+---
+
+feat: support traditional aria labeling for TextField, Textarea, and Select
diff --git a/documentation/specs/Select.md b/documentation/specs/Select.md
index c2e20c14..c5cccd98 100644
--- a/documentation/specs/Select.md
+++ b/documentation/specs/Select.md
@@ -12,7 +12,6 @@ The `Select` component allows users to select a value from a set of options. Tho
 
 - Setting the `size` property also sets size for iconAtStart: The size values map to Easy UI's token sizes for icons.
 - When `errorText` is supplied with `validationState="invalid"`, `helperText` is overriden.
-- `isLabelVisuallyHidden` property can be used to visually hide the label.
 - Supports disabled state.
 
 ### Risks and Challenges
@@ -59,10 +58,9 @@ export type SelectProps<T> = AriaSelectProps<T> &
 
 export type BaseSelectFieldProps = {
   /**
-   * Visually hides the label, but keeps it accessible.
-   * @default false
+   * Accessibility label for select field.
    */
-  isLabelVisuallyHidden?: boolean;
+  "aria-label"?: string;
   /**
    * Whether the select field is disabled.
    * @default false
@@ -219,7 +217,7 @@ export function Component() {
 
 Accessibility
 
-- Labels should be included on all select fields as they describe the purpose of any associated form control. In situations when you may want the label to be visually hidden, use the `isLabelVisuallyHidden` prop.
+- Labels should be included on all select fields as they describe the purpose of any associated form control. In situations when you may want the label to be visually hidden, provide a label via the `aria-label` prop.
 - The dropdown has an ARIA role of `listbox`.
 
 ## Dependencies
diff --git a/documentation/specs/TextField.md b/documentation/specs/TextField.md
index 31c72ac9..aad13598 100644
--- a/documentation/specs/TextField.md
+++ b/documentation/specs/TextField.md
@@ -15,7 +15,6 @@ The `TextField` component allows users to input text on a single line and provid
 - Setting the `size` property also sets size for iconAtStart and iconAtEnd: The size values map to Easy UI's token sizes for icons.
 - When `errorText` is supplied with `validationState="invalid"`, `helperText` is overriden.
 - Underlying input type can be set to `text`, `email`, `password`, `tel`, or `search`.
-- `isLabelVisuallyHidden` property can be used to visually hide the label.
 
 ### Risks and Challenges
 
@@ -49,10 +48,9 @@ export type InputFieldProps = AriaTextFieldProps & {
    */
   type?: InputType;
   /**
-   * Visually hides the label, but keeps it accessible.
-   * @default false
+   * Accessibility label for input field.
    */
-  isLabelVisuallyHidden?: boolean;
+  "aria-label"?: string;
   /**
    * Whether the input is disabled.
    * @default false
@@ -121,7 +119,6 @@ export function TextField(props: TextFieldProps) {
   const {
     type = "text",
     size = "md",
-    isLabelVisuallyHidden = false,
     isDisabled = false,
     isRequired = false,
     validationState = "valid",
@@ -141,7 +138,6 @@ export function TextField(props: TextFieldProps) {
     <InputField
       type={type}
       size={size}
-      isLabelVisuallyHidden={isLabelVisuallyHidden}
       isDisabled={isDisabled}
       isRequired={isRequired}
       validationState={validationState}
@@ -219,8 +215,7 @@ export function Component() {
     <>
       <TextField
         type="search"
-        label="Search for carriers" // visually hidden but still accessible via isLabelVisuallyHidden prop
-        isLabelVisuallyHidden
+        aria-label="Search for carriers"
         iconAtStart={AnIcon}
         value={searchedValue}
         onChange={(inputValue) => setSearchedValue(inputValue)} // value is returned automatically via react-aria
@@ -283,7 +278,7 @@ export function Component() {
 
 Accessibility
 
-- Labels should be included on all text fields as they describe the purpose of the form control. In situations when you may want the label to be visually hidden, use the `isLabelVisuallyHidden` prop.
+- Labels should be included on all text fields as they describe the purpose of the form control. In situations when you may want the label to be visually hidden, provide a label via the `aria-label` prop.
 - Do not use `placeholder` text as a replacement for labels. It can be used to provide an example to users, but will disappear from the field when a user enters text. It's also not broadly supported by assistive technologies and won't display in older browsers.
 
 ## Dependencies
diff --git a/documentation/specs/Textarea.md b/documentation/specs/Textarea.md
index 13e47d48..3a543b66 100644
--- a/documentation/specs/Textarea.md
+++ b/documentation/specs/Textarea.md
@@ -12,7 +12,6 @@ The `Textarea` component allows users to input text on multiple lines.
 
 - Users can adjust height, but not width.
 - When `errorText` is supplied with `validationState="invalid"`, `helperText` is overriden.
-- `isLabelVisuallyHidden` property can be used to visually hide the label.
 
 ### Risks and Challenges
 
@@ -44,10 +43,9 @@ export type InputFieldProps = AriaTextFieldProps & {
    */
   type?: InputType;
   /**
-   * Visually hides the label, but keeps it accessible.
-   * @default false
+   * Accessibility label for input field.
    */
-  isLabelVisuallyHidden?: boolean;
+  "aria-label"?: string;
   /**
    * Whether the input is disabled.
    * @default false
@@ -124,7 +122,6 @@ The bulk of the `Textarea` component behavior will be handled by an internal `In
 export function Textarea(props: TextareaProps) {
   const {
     size = "md",
-    isLabelVisuallyHidden = false,
     isDisabled = false,
     isRequired = false,
     validationState = "valid",
@@ -142,7 +139,6 @@ export function Textarea(props: TextareaProps) {
     <InputField
       isMultiline
       size={size}
-      isLabelVisuallyHidden={isLabelVisuallyHidden}
       isDisabled={isDisabled}
       isRequired={isRequired}
       validationState={validationState}
@@ -194,8 +190,7 @@ export function Component() {
   return (
     <>
       <Textarea
-        label="Label" // visually hidden but still accessible via isLabelVisuallyHidden prop
-        isLabelVisuallyHidden
+        aria-label="Label"
         value={description}
         onChange={(inputValue) => setDescription(inputValue)} // value is returned automatically via react-aria
         placeholder="Enter free-form text"
@@ -237,7 +232,7 @@ export function Component() {
 
 Accessibility
 
-- Labels should be included on all text area fields as they describe the purpose of any associated form control. In situations when you may want the label to be visually hidden, use the `isLabelVisuallyHidden` prop.
+- Labels should be included on all text area fields as they describe the purpose of any associated form control. In situations when you may want the label to be visually hidden, provide a label via the `aria-label` prop.
 - Do not use `placeholder` text as a replacement for labels. It can be used to provide an example to users, but will disappear from the field when a user enters text. It's also not broadly supported by assistive technologies and won't display in older browsers.
 
 ## Dependencies
diff --git a/easy-ui-react/src/InputField/InputField.module.scss b/easy-ui-react/src/InputField/InputField.module.scss
index ea8f29e8..12dc9c02 100644
--- a/easy-ui-react/src/InputField/InputField.module.scss
+++ b/easy-ui-react/src/InputField/InputField.module.scss
@@ -13,10 +13,6 @@
   margin-bottom: design-token("space.1");
 }
 
-.labelHidden {
-  margin-bottom: 0;
-}
-
 .input {
   @include Input.input;
 }
diff --git a/easy-ui-react/src/InputField/InputField.tsx b/easy-ui-react/src/InputField/InputField.tsx
index 4887cd5c..07ba1f58 100644
--- a/easy-ui-react/src/InputField/InputField.tsx
+++ b/easy-ui-react/src/InputField/InputField.tsx
@@ -31,10 +31,9 @@ export type InputFieldProps = AriaTextFieldProps & {
    */
   type?: InputType;
   /**
-   * Visually hides the label, but keeps it accessible.
-   * @default false
+   * Accessibility label for input field.
    */
-  isLabelVisuallyHidden?: boolean;
+  "aria-label"?: string;
   /**
    * Whether the input is disabled.
    * @default false
@@ -72,7 +71,7 @@ export type InputFieldProps = AriaTextFieldProps & {
    */
   isMultiline?: boolean;
   /** The content to display as the label. */
-  label: ReactNode;
+  label?: ReactNode;
   /** Error text that appears below input. */
   errorText?: ReactNode;
   /** Helper text that appears below input. */
@@ -102,7 +101,6 @@ export function InputField(props: InputFieldProps) {
     isMultiline = false,
     type = "text",
     size = "md",
-    isLabelVisuallyHidden = false,
     isDisabled = false,
     isRequired = false,
     validationState = "valid",
@@ -170,15 +168,16 @@ export function InputField(props: InputFieldProps) {
 
   return (
     <div className={classNames(styles.root)}>
-      <Label
-        isLabelVisuallyHidden={isLabelVisuallyHidden}
-        fieldSize={adjustedSize}
-        hasError={hasError}
-        isLabelEmphasized={isLabelEmphasized}
-        {...labelProps}
-      >
-        {label}
-      </Label>
+      {label && (
+        <Label
+          fieldSize={adjustedSize}
+          hasError={hasError}
+          isLabelEmphasized={isLabelEmphasized}
+          {...labelProps}
+        >
+          {label}
+        </Label>
+      )}
       <div className={styles.inputIconContainer}>
         {hasStartIcon && (
           <InputIcon
diff --git a/easy-ui-react/src/InputField/Label.tsx b/easy-ui-react/src/InputField/Label.tsx
index 61928888..374ff982 100644
--- a/easy-ui-react/src/InputField/Label.tsx
+++ b/easy-ui-react/src/InputField/Label.tsx
@@ -5,11 +5,6 @@ import styles from "./InputField.module.scss";
 import { classNames } from "../utilities/css";
 
 export type LabelProps = {
-  /**
-   * Visually hides the label, but keeps it accessible.
-   * @default false
-   */
-  isLabelVisuallyHidden?: boolean;
   /**
    * Label text displays with emphasis.
    * @default false
@@ -37,7 +32,6 @@ export type LabelProps = {
  */
 export function Label(props: LabelProps) {
   const {
-    isLabelVisuallyHidden = false,
     isLabelEmphasized = false,
     fieldSize = "md",
     hasError = false,
@@ -53,19 +47,8 @@ export function Label(props: LabelProps) {
   const as = isLabelEmphasized ? "strong" : "span";
   const color = hasError ? "danger" : undefined;
   return (
-    <label
-      {...labelProps}
-      className={classNames(
-        styles.label,
-        isLabelVisuallyHidden && styles.labelHidden,
-      )}
-    >
-      <Text
-        variant={textVariant}
-        as={as}
-        color={color}
-        visuallyHidden={isLabelVisuallyHidden}
-      >
+    <label {...labelProps} className={classNames(styles.label)}>
+      <Text variant={textVariant} as={as} color={color}>
         {children}
       </Text>
     </label>
diff --git a/easy-ui-react/src/Select/Select.mdx b/easy-ui-react/src/Select/Select.mdx
index 0662552d..1cfa9753 100644
--- a/easy-ui-react/src/Select/Select.mdx
+++ b/easy-ui-react/src/Select/Select.mdx
@@ -48,7 +48,7 @@ When `validationState` is set to `invalid`, the `<Select />` field displays with
 
 ## Visually hidden label
 
-To hide a `label` but maintain accessibility, use `isLabelVisuallyHidden`.
+To hide a `label` but maintain accessibility, use `aria-label`.
 
 <Canvas of={SelectStories.VisuallyHiddenLabel} />
 
@@ -104,10 +104,9 @@ export type SelectProps<T> = AriaSelectProps<T> &
 
 export type BaseSelectFieldProps = {
   /**
-   * Visually hides the label, but keeps it accessible.
-   * @default false
+   * Accessibility label for select field.
    */
-  isLabelVisuallyHidden?: boolean;
+  "aria-label"?: string;
   /**
    * Whether the select field is disabled.
    * @default false
diff --git a/easy-ui-react/src/Select/Select.stories.tsx b/easy-ui-react/src/Select/Select.stories.tsx
index 69565081..417a6712 100644
--- a/easy-ui-react/src/Select/Select.stories.tsx
+++ b/easy-ui-react/src/Select/Select.stories.tsx
@@ -119,7 +119,7 @@ export const Error: Story = {
 export const VisuallyHiddenLabel: Story = {
   render: Template.bind({}),
   args: {
-    isLabelVisuallyHidden: true,
+    "aria-label": "Label",
   },
 };
 
diff --git a/easy-ui-react/src/Select/Select.tsx b/easy-ui-react/src/Select/Select.tsx
index 72c3cb1f..36a746de 100644
--- a/easy-ui-react/src/Select/Select.tsx
+++ b/easy-ui-react/src/Select/Select.tsx
@@ -92,7 +92,6 @@ export type SelectProps<T> = AriaSelectProps<T> &
  */
 export function Select<T extends object>(props: SelectProps<T>) {
   const {
-    isLabelVisuallyHidden,
     isDisabled,
     validationState,
     isLabelEmphasized,
@@ -131,7 +130,6 @@ export function Select<T extends object>(props: SelectProps<T>) {
   return (
     <InternalSelectContext.Provider value={context}>
       <SelectField
-        isLabelVisuallyHidden={isLabelVisuallyHidden}
         isDisabled={isDisabled}
         validationState={validationState}
         isLabelEmphasized={isLabelEmphasized}
diff --git a/easy-ui-react/src/Select/SelectField.tsx b/easy-ui-react/src/Select/SelectField.tsx
index 39dca5a0..c172c528 100644
--- a/easy-ui-react/src/Select/SelectField.tsx
+++ b/easy-ui-react/src/Select/SelectField.tsx
@@ -15,10 +15,9 @@ export type ValidationState = "valid" | "invalid";
 
 export type BaseSelectFieldProps = {
   /**
-   * Visually hides the label, but keeps it accessible.
-   * @default false
+   * Accessibility label for select field.
    */
-  isLabelVisuallyHidden?: boolean;
+  "aria-label"?: string;
   /**
    * Whether the select field is disabled.
    * @default false
@@ -46,7 +45,7 @@ export type BaseSelectFieldProps = {
    */
   size?: SelectFieldSize;
   /** The content to display as the label. */
-  label: ReactNode;
+  label?: ReactNode;
   /** Error text that appears below select field. */
   errorText?: ReactNode;
   /** Helper text that appears below select field. */
@@ -72,7 +71,6 @@ type SelectFieldProps = BaseSelectFieldProps & SelectFieldAttributeProps;
 
 export function SelectField(props: SelectFieldProps) {
   const {
-    isLabelVisuallyHidden = false,
     isDisabled = false,
     validationState = "valid",
     isLabelEmphasized = false,
@@ -97,15 +95,16 @@ export function SelectField(props: SelectFieldProps) {
 
   return (
     <div className={classNames(styles.fieldRoot)}>
-      <Label
-        isLabelVisuallyHidden={isLabelVisuallyHidden}
-        fieldSize={size}
-        hasError={hasError}
-        isLabelEmphasized={isLabelEmphasized}
-        {...labelProps}
-      >
-        {label}
-      </Label>
+      {label && (
+        <Label
+          fieldSize={size}
+          hasError={hasError}
+          isLabelEmphasized={isLabelEmphasized}
+          {...labelProps}
+        >
+          {label}
+        </Label>
+      )}
       <HiddenSelect
         isDisabled={isDisabled}
         state={selectState}
diff --git a/easy-ui-react/src/TextField/TextField.mdx b/easy-ui-react/src/TextField/TextField.mdx
index 1600e546..071ff9ff 100644
--- a/easy-ui-react/src/TextField/TextField.mdx
+++ b/easy-ui-react/src/TextField/TextField.mdx
@@ -53,7 +53,7 @@ When `validationState` is set to `invalid`, the `<TextField />` displays with er
 
 ## Visually hidden label
 
-To hide a `label` but maintain accessibility, use `isLabelVisuallyHidden`.
+To hide a `label` but maintain accessibility, use `aria-label`.
 
 <Canvas of={TextFieldStories.VisuallyHiddenLabel} />
 
diff --git a/easy-ui-react/src/TextField/TextField.stories.tsx b/easy-ui-react/src/TextField/TextField.stories.tsx
index e7268c26..e97a51eb 100644
--- a/easy-ui-react/src/TextField/TextField.stories.tsx
+++ b/easy-ui-react/src/TextField/TextField.stories.tsx
@@ -124,8 +124,7 @@ export const Error: Story = {
 export const VisuallyHiddenLabel: Story = {
   render: Template.bind({}),
   args: {
-    label: "Label",
-    isLabelVisuallyHidden: true,
+    "aria-label": "Label",
   },
 };
 
@@ -189,7 +188,6 @@ export const Controls: Story = {
     type: "text",
     size: "md",
     label: "Label",
-    isLabelVisuallyHidden: false,
     isDisabled: false,
     isRequired: false,
     validationState: "valid",
diff --git a/easy-ui-react/src/TextField/TextField.tsx b/easy-ui-react/src/TextField/TextField.tsx
index 5a41904c..1453d112 100644
--- a/easy-ui-react/src/TextField/TextField.tsx
+++ b/easy-ui-react/src/TextField/TextField.tsx
@@ -17,7 +17,8 @@ export type TextFieldProps = Omit<InputFieldProps, "isMultiline" | "rows">;
  * When `errorText` is supplied with `validationState="invalid"`, `helperText` is overriden.
  *
  * Labels should be included on all text fields as they describe the purpose of the form control.
- * In situations when you may want the label to be visually hidden, use the `isLabelVisuallyHidden` prop.
+ * In situations when you may want the label to be visually hidden, omit the label and provide an
+ * `aria-label`.
  *
  * @example
  * _Email with autoFocus:_
@@ -73,8 +74,7 @@ export type TextFieldProps = Omit<InputFieldProps, "isMultiline" | "rows">;
  *    <>
  *      <TextField
  *        type="search"
- *        label="Search for carriers" // visually hidden but still accessible via isLabelVisuallyHidden prop
- *        isLabelVisuallyHidden
+ *        aria-label="Search for carriers"
  *        iconAtStart={SearchIcon}
  *        value={searchedValue}
  *        onChange={(inputValue) => setSearchedValue(inputValue)} // value is returned automatically via react-aria
@@ -112,7 +112,6 @@ export function TextField(props: TextFieldProps) {
   const {
     type = "text",
     size = "md",
-    isLabelVisuallyHidden = false,
     isDisabled = false,
     isRequired = false,
     validationState = "valid",
@@ -124,7 +123,6 @@ export function TextField(props: TextFieldProps) {
     <InputField
       type={type}
       size={size}
-      isLabelVisuallyHidden={isLabelVisuallyHidden}
       isDisabled={isDisabled}
       isRequired={isRequired}
       validationState={validationState}
diff --git a/easy-ui-react/src/Textarea/Textarea.mdx b/easy-ui-react/src/Textarea/Textarea.mdx
index e9602649..85b46f73 100644
--- a/easy-ui-react/src/Textarea/Textarea.mdx
+++ b/easy-ui-react/src/Textarea/Textarea.mdx
@@ -41,7 +41,7 @@ When `validationState` is set to `invalid`, the `<Textarea />` displays with err
 
 ## Visually hidden label
 
-To hide a `label` but maintain accessibility, use `isLabelVisuallyHidden`.
+To hide a `label` but maintain accessibility, use `aria-label`.
 
 <Canvas of={TextareaStories.VisuallyHiddenLabel} />
 
diff --git a/easy-ui-react/src/Textarea/Textarea.stories.tsx b/easy-ui-react/src/Textarea/Textarea.stories.tsx
index f354fe6d..875fd073 100644
--- a/easy-ui-react/src/Textarea/Textarea.stories.tsx
+++ b/easy-ui-react/src/Textarea/Textarea.stories.tsx
@@ -70,8 +70,7 @@ export const Error: Story = {
 export const VisuallyHiddenLabel: Story = {
   render: Template.bind({}),
   args: {
-    label: "Label",
-    isLabelVisuallyHidden: true,
+    "aria-label": "Label",
   },
 };
 
@@ -120,7 +119,6 @@ export const Controls: Story = {
   args: {
     size: "md",
     label: "Label",
-    isLabelVisuallyHidden: false,
     isDisabled: false,
     isRequired: false,
     validationState: "valid",
diff --git a/easy-ui-react/src/Textarea/Textarea.tsx b/easy-ui-react/src/Textarea/Textarea.tsx
index ec8ad8ce..08e13344 100644
--- a/easy-ui-react/src/Textarea/Textarea.tsx
+++ b/easy-ui-react/src/Textarea/Textarea.tsx
@@ -21,7 +21,8 @@ export type TextareaProps = Omit<
  * Use this component when you want to allow users to enter a sizeable amount of free-form text.
  *
  * Labels should always be included as they describe the purpose of the textarea.
- * In situations when you may want the label to be visually hidden, use the `isLabelVisuallyHidden` prop.
+ * In situations when you may want the label to be visually hidden, omit the label and provide an
+ * `aria-label`.
  *
  * @example
  * _Description with helper text:_
@@ -54,8 +55,7 @@ export type TextareaProps = Omit<
  *  return (
  *    <>
  *      <Textarea
- *        label="Label" // visually hidden but still accessible via isLabelVisuallyHidden prop
- *        isLabelVisuallyHidden
+ *        aria-label="Label"
  *        value={description}
  *        onChange={(inputValue) => setDescription(inputValue)} // value is returned automatically via react-aria
  *        placeholder="Enter free-form text"
@@ -92,7 +92,6 @@ export type TextareaProps = Omit<
 export function Textarea(props: TextareaProps) {
   const {
     size = "md",
-    isLabelVisuallyHidden = false,
     isDisabled = false,
     isRequired = false,
     validationState = "valid",
@@ -105,7 +104,6 @@ export function Textarea(props: TextareaProps) {
     <InputField
       isMultiline
       size={size}
-      isLabelVisuallyHidden={isLabelVisuallyHidden}
       isDisabled={isDisabled}
       isRequired={isRequired}
       validationState={validationState}