fix: decouple facet search labels from visual display

docs/search-ui-react.facetsprops.md

@@ -148,6 +148,25 @@ boolean
 _(Optional)_ Whether or not a search is automatically run when a filter is selected. Defaults to true.
 
 
+</td></tr>
+<tr><td>
+
+[showOptionsSearchInputLabel?](./search-ui-react.facetsprops.showoptionssearchinputlabel.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ Whether or not to display the options search input label visibly on facets that render an options search input. Defaults to false, and is overridden by the same prop on a child facet.
+
+
 </td></tr>
 </tbody></table>
 

docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/search-ui-react](./search-ui-react.md) &gt; [FacetsProps](./search-ui-react.facetsprops.md) &gt; [showOptionsSearchInputLabel](./search-ui-react.facetsprops.showoptionssearchinputlabel.md)
+
+## FacetsProps.showOptionsSearchInputLabel property
+
+Whether or not to display the options search input label visibly on facets that render an options search input. Defaults to false, and is overridden by the same prop on a child facet.
+
+**Signature:**
+
+```typescript
+showOptionsSearchInputLabel?: boolean;
+```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology. Hierarchical facets do not render an options search input, so this has no effect on them.
+

docs/search-ui-react.filtergroupprops.md

@@ -183,7 +183,7 @@ boolean
 
 </td><td>
 
-_(Optional)_ Whether or not to display the visible search input label. Defaults to false.
+_(Optional)_ Whether or not to display the search input label visibly. Defaults to false.
 
 
 </td></tr>

docs/search-ui-react.filtergroupprops.showoptionssearchinputlabel.md

@@ -4,10 +4,15 @@
 
 ## FilterGroupProps.showOptionsSearchInputLabel property
 
-Whether or not to display the visible search input label. Defaults to false.
+Whether or not to display the search input label visibly. Defaults to false.
 
 **Signature:**
 
 ```typescript
 showOptionsSearchInputLabel?: boolean;
 ```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+

docs/search-ui-react.standardfacetprops.md

@@ -183,7 +183,7 @@ boolean
 
 </td><td>
 
-_(Optional)_ Whether or not to show the label for the search bar when present. Defaults to false.
+_(Optional)_ Whether or not to display the search input label visibly. Defaults to false.
 
 
 </td></tr>

docs/search-ui-react.standardfacetprops.showoptionssearchinputlabel.md

@@ -4,10 +4,15 @@
 
 ## StandardFacetProps.showOptionsSearchInputLabel property
 
-Whether or not to show the label for the search bar when present. Defaults to false.
+Whether or not to display the search input label visibly. Defaults to false.
 
 **Signature:**
 
 ```typescript
 showOptionsSearchInputLabel?: boolean;
 ```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+

docs/search-ui-react.staticfiltersprops.md

@@ -183,7 +183,7 @@ boolean
 
 </td><td>
 
-_(Optional)_ Whether or not to display the visible search input label. Defaults to false.
+_(Optional)_ Whether or not to display the search input label visibly. Defaults to false.
 
 
 </td></tr>

docs/search-ui-react.staticfiltersprops.showoptionssearchinputlabel.md

@@ -4,10 +4,15 @@
 
 ## StaticFiltersProps.showOptionsSearchInputLabel property
 
-Whether or not to display the visible search input label. Defaults to false.
+Whether or not to display the search input label visibly. Defaults to false.
 
 **Signature:**
 
 ```typescript
 showOptionsSearchInputLabel?: boolean;
 ```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+

etc/search-ui-react.api.md

@@ -262,6 +262,7 @@ export interface FacetsProps {
     hierarchicalFieldIds?: string[];
     onlyRenderChildren?: boolean;
     searchOnChange?: boolean;
+    showOptionsSearchInputLabel?: boolean;
 }
 
 // @public
@@ -1174,7 +1175,7 @@ export interface VisualAutocompleteConfig {
 
 // Warnings were encountered during analysis:
 //
-// dist/index.d.ts:1921:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
+// dist/index.d.ts:1934:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 

src/components/FacetProps.ts

@@ -33,6 +33,16 @@ export interface FacetsProps {
   excludedFieldIds?: string[],
   /** List of field ids that should be rendered as hierarchical facets. */
   hierarchicalFieldIds?: string[],
+  /**
+   * Whether or not to display the options search input label visibly on facets that render an
+   * options search input. Defaults to false, and is overridden by the same prop on a child facet.
+   *
+   * @remarks
+   * The label is always associated with the search input so that it has an accessible name.
+   * When false, the label is visually hidden but remains available to assistive technology.
+   * Hierarchical facets do not render an options search input, so this has no effect on them.
+   */
+  showOptionsSearchInputLabel?: boolean,
   /** The custom facet components that will override the default rendering.
    *
    * @remarks
@@ -66,10 +76,7 @@ export interface StandardFacetProps {
   showMoreLimit?: number,
   /** CSS classes for customizing the component styling. */
   customCssClasses?: FilterGroupCssClasses,
-  /**
-   * Whether or not to show the label for the search bar when present.
-   * Defaults to false.
-   */
+  /** {@inheritDoc FilterGroupProps.showOptionsSearchInputLabel} */
   showOptionsSearchInputLabel?: boolean
 }
 

src/components/Facets.tsx

@@ -40,6 +40,7 @@ export function Facets(props: FacetsProps): React.JSX.Element {
     hierarchicalFieldIds,
     excludedFieldIds = [],
     customCssClasses = {},
+    showOptionsSearchInputLabel,
   } = props;
   const resolvedHierarchicalFieldIds = useMemo(() => hierarchicalFieldIds ?? [], [hierarchicalFieldIds]);
 
@@ -89,6 +90,7 @@ export function Facets(props: FacetsProps): React.JSX.Element {
                     facetsCustomCssClasses={customCssClasses}
                     fieldIdToCustomFacetProps={fieldIdToCustomFacetProps}
                     hierarchicalFieldIds={resolvedHierarchicalFieldIds}
+                    showOptionsSearchInputLabel={showOptionsSearchInputLabel}
                   />
                   {(i < facets.length - 1)
                     && <FilterDivider className={customCssClasses?.divider}/>}
@@ -140,6 +142,7 @@ export function HierarchicalFacet(props: HierarchicalFacetProps) { return null;
  * @param facetsCustomCssClasses - {@link FacetsCssClasses}
  * @param fieldIdToCustomFacetProps - a map of fieldId to facet props
  * @param hierarchicalFieldIds - a list of hierarchical field ids
+ * @param showOptionsSearchInputLabel - whether to display the options search input label visibly
  * @returns {@link ReactElement}
  *
  * @internal
@@ -149,20 +152,26 @@ export function Facet({
   facetsCustomCssClasses,
   fieldIdToCustomFacetProps,
   hierarchicalFieldIds,
+  showOptionsSearchInputLabel,
 }: {
   facet: DisplayableFacet,
   facetsCustomCssClasses: FacetsCssClasses,
   fieldIdToCustomFacetProps: Map<string, any>,
-  hierarchicalFieldIds: string[]
+  hierarchicalFieldIds: string[],
+  showOptionsSearchInputLabel?: boolean
 }) {
   let facetType: FacetType;
   let facetProps: FacetProps = {
     fieldId: facet.fieldId,
     label: facet.displayName,
+    showOptionsSearchInputLabel,
   };
   const customFacetElement = fieldIdToCustomFacetProps.get(facet.fieldId);
   if (customFacetElement) {
     facetProps = { ...facetProps, ...customFacetElement.props };
+    if (customFacetElement.props.showOptionsSearchInputLabel === undefined) {
+      facetProps.showOptionsSearchInputLabel = showOptionsSearchInputLabel;
+    }
     facetType = getFacetTypeFromReactElementType(
       (typeof customFacetElement.type === 'function')
         ? customFacetElement.type.name : '');

src/components/FilterGroup.tsx

@@ -50,7 +50,13 @@ export interface FilterGroupProps {
   defaultExpanded?: boolean,
   /** Whether or not to display a text input to search for filter options. */
   searchable?: boolean,
-  /** Whether or not to display the visible search input label. Defaults to false. */
+  /**
+   * Whether or not to display the search input label visibly. Defaults to false.
+   *
+   * @remarks
+   * The label is always associated with the search input so that it has an accessible name.
+   * When false, the label is visually hidden but remains available to assistive technology.
+   */
   showOptionsSearchInputLabel?: boolean,
   /** CSS classes for customizing the component styling. */
   customCssClasses?: FilterGroupCssClasses,
@@ -83,11 +89,9 @@ export function FilterGroup({
       ...optionInput && { input: optionInput }
     };
   }, [customCssClasses]);
-  const searchInputLabel = showOptionsSearchInputLabel
-    ? t('filterGroupSearchInputLabel', {
-      title
-    })
-    : undefined;
+  const searchInputLabel = t('filterGroupSearchInputLabel', {
+    title
+  });
 
   return (
     <FilterGroupProvider
@@ -106,6 +110,7 @@ export function FilterGroup({
               className={cssClasses.searchInput}
               labelClassName={cssClasses.searchInputLabel}
               label={searchInputLabel}
+              visuallyHiddenLabel={!showOptionsSearchInputLabel}
             />}
           <CheckboxOptions
             filterOptions={filterOptions}
@@ -120,6 +125,7 @@ export function FilterGroup({
               className={cssClasses.searchInput}
               labelClassName={cssClasses.searchInputLabel}
               label={searchInputLabel}
+              visuallyHiddenLabel={!showOptionsSearchInputLabel}
             />}
           <CheckboxOptions
             filterOptions={filterOptions}

src/components/Filters/SearchInput.tsx

@@ -11,12 +11,17 @@ import { useId } from '../../hooks/useId';
 export interface SearchInputProps {
   /** CSS class names applied to the input element. */
   className?: string,
-  /** CSS class names applied to the label element. */
+  /** CSS class names applied to the label element when it is visible. */
   labelClassName?: string,
   /** {@inheritDoc FilterSearch.placeholder} */
   placeholder?: string,
-  /** The visible label text associated with the input. */
-  label?: string
+  /** The label text associated with the input. */
+  label?: string,
+  /**
+   * Whether the label is hidden from view while remaining associated with the input for
+   * assistive technology. Defaults to false.
+   */
+  visuallyHiddenLabel?: boolean
 }
 
 /**
@@ -33,7 +38,8 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
     className = 'text-sm form-input bg-white h-9 w-full outline-none p-2 mb-2 rounded-md border border-gray-300 focus:ring-primary focus:ring-0 text-neutral-dark placeholder:text-neutral',
     labelClassName = 'mb-1 block text-sm font-medium text-neutral-dark',
     placeholder,
-    label
+    label,
+    visuallyHiddenLabel = false
   } = props;
   const { searchValue, setSearchValue } = useFilterGroupContext();
   const handleChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
@@ -42,13 +48,18 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
 
   const labelId = useId('filters-search-input-label');
   const inputId = useId('filter-group-search-input');
+  const labelElement = label && (
+    <label
+      id={labelId}
+      htmlFor={inputId}
+      className={visuallyHiddenLabel ? 'sr-only' : labelClassName}
+    >
+      {label}
+    </label>
+  );
   return (
     <>
-      {label && (
-        <label id={labelId} htmlFor={inputId} className={labelClassName}>
-          {label}
-        </label>
-      )}
+      {!visuallyHiddenLabel && labelElement}
       <input
         id={inputId}
         className={className}
@@ -57,6 +68,8 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
         value={searchValue}
         onChange={handleChange}
       />
+      {/* Keep the input first so sibling spacing utilities do not add a gap above it. */}
+      {visuallyHiddenLabel && labelElement}
     </>
   );
 }

src/components/SearchI18nextProvider.tsx

@@ -28,6 +28,7 @@ type translationKeys =
   'dismiss' |
   'dropDownScreenReaderInstructions' |
   'feedback' |
+  'filterGroupSearchInputLabel' |
   'invalidRange' |
   'max' |
   'min' |