replace isLabelVisuallyHidden with aria-label

.changeset/empty-oranges-laugh.md

@@ -0,0 +1,5 @@
+---
+"@easypost/easy-ui": minor
+---
+
+feat: support traditional aria labeling for TextField, Textarea, and Select

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

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

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

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;
 }

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

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>

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

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",
   },
 };
 

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}

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}

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} />
 

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",