docs: update outdated DropdownField mention and links, add Field story, update labelling techniques (#33699)

Author: smhigley

packages/react-components/react-combobox/stories/src/Dropdown/DropdownAccessibility.md

@@ -2,15 +2,15 @@
 
 ### Do
 
-- **Provide a label for the Dropdown.** This can be done either by using the `DropdownField` component with a `label` prop, or by using a [custom labeling technique](#TODO).
+- **Provide a label for the Dropdown.** This can be done either by using the `Field` component with a `label` prop, or by using a custom labeling technique like a custom `<label for="dropdownId">` element, `aria-label` or `aria-labelledby`.
 - **Use Dropdown when you need JSX or styled options, otherwise use Select.** For simple single-select use cases, consider using `Select` for better accessibility and mobile support.
 - **Use multi-select Dropdown when you have 10+ options, otherwise use a Checkbox group.** For simple multiselect use cases with less than 10 options, consider using a group of `Checkbox` components.
 - **Set `inlinePopup={true}` when possible for better VoiceOver support.** The `inlinePopup` prop will cause the listbox popup to be rendered immediately after the button in the DOM. Safari does not support `aria-owns`, so this enables iOS VoiceOver swipe navigation between the button and options.
-- **Review [known accessiblity issues](./?path=/docs/concepts-developer-accessibility-components-dropdown--page).**
+- **Review [known accessiblity issues](./?path=/docs/concepts-developer-accessibility-components-dropdown--docs).**
 
 ### Don't
 
 - **Don't nest interactive controls in Dropdown slots or children.** The `Dropdown`'s `button` slot and children of `<Option>` components will not expose nested interactive elements to screen reader users, and additional non-`Option` children in the `listbox` slot will not be keyboard accessible.
 - **Don’t place the Dropdown button on a surface which doesn’t have a sufficient contrast.** The colors adjacent to the input should have a sufficient contrast. Particularly, the color of input with filled darker and lighter styles needs to provide greater than 3 to 1 contrast ratio against the immediate surrounding color to pass accessibility requirements. When using underline or outline styles, ensure the color of bottom border stroke has a sufficient contrast of greater than 3 to 1 against the immediate surrounding color.
 
-Read the [Dropdown accessibility spec](./?path=/docs/concepts-developer-accessibility-components-dropdown--page) for more detailed information, as well as full descriptions of semantics and keyboard behavior.
+Read the [Dropdown accessibility spec](./?path=/docs/concepts-developer-accessibility-components-dropdown--docs) for more detailed information, as well as full descriptions of semantics and keyboard behavior.

packages/react-components/react-combobox/stories/src/Dropdown/DropdownActiveOptionChange.stories.tsx

@@ -35,8 +35,8 @@ export const ActiveOptionChange = (props: Partial<DropdownProps>) => {
   return (
     <div className={styles.root}>
       {activeOptionText}
-      <label id={dropdownId}>Schedule a meeting</label>
-      <Dropdown aria-labelledby={dropdownId} onActiveOptionChange={onActiveOptionChange} {...props}>
+      <label htmlFor={dropdownId}>Schedule a meeting</label>
+      <Dropdown id={dropdownId} onActiveOptionChange={onActiveOptionChange} {...props}>
         <Option text="Katri Athokas" onMouseEnter={onMouseEnter}>
           <Persona
             avatar={{ color: 'colorful', 'aria-hidden': true }}

packages/react-components/react-combobox/stories/src/Dropdown/DropdownAppearance.stories.tsx

@@ -48,8 +48,8 @@ export const Appearance = (props: Partial<DropdownProps>) => {
     <div className={styles.root}>
       <div>
         <h3>Outline</h3>
-        <label id={`${dropdownId}-outline`}>Select an animal</label>
-        <Dropdown aria-labelledby={`${dropdownId}-outline`} placeholder="-" appearance="outline" {...props}>
+        <label htmlFor={`${dropdownId}-outline`}>Select an animal</label>
+        <Dropdown id={`${dropdownId}-outline`} placeholder="-" appearance="outline" {...props}>
           <Option>Cat</Option>
           <Option>Dog</Option>
           <Option>Bird</Option>
@@ -58,8 +58,8 @@ export const Appearance = (props: Partial<DropdownProps>) => {
 
       <div>
         <h3>Underline</h3>
-        <label id={`${dropdownId}-underline`}>Select an animal</label>
-        <Dropdown aria-labelledby={`${dropdownId}-underline`} placeholder="-" appearance="underline" {...props}>
+        <label htmlFor={`${dropdownId}-underline`}>Select an animal</label>
+        <Dropdown id={`${dropdownId}-underline`} placeholder="-" appearance="underline" {...props}>
           <Option>Cat</Option>
           <Option>Dog</Option>
           <Option>Bird</Option>
@@ -68,8 +68,8 @@ export const Appearance = (props: Partial<DropdownProps>) => {
 
       <div className={styles.filledDarker}>
         <h3>Filled Darker</h3>
-        <label id={`${dropdownId}-filledDarker`}>Select an animal</label>
-        <Dropdown aria-labelledby={`${dropdownId}-filledDarker`} placeholder="-" appearance="filled-darker" {...props}>
+        <label htmlFor={`${dropdownId}-filledDarker`}>Select an animal</label>
+        <Dropdown id={`${dropdownId}-filledDarker`} placeholder="-" appearance="filled-darker" {...props}>
           <Option>Cat</Option>
           <Option>Dog</Option>
           <Option>Bird</Option>
@@ -78,13 +78,8 @@ export const Appearance = (props: Partial<DropdownProps>) => {
 
       <div className={styles.filledLighter}>
         <h3>Filled Lighter</h3>
-        <label id={`${dropdownId}-filledLighter`}>Select an animal</label>
-        <Dropdown
-          aria-labelledby={`${dropdownId}-filledLighter`}
-          placeholder="-"
-          appearance="filled-lighter"
-          {...props}
-        >
+        <label htmlFor={`${dropdownId}-filledLighter`}>Select an animal</label>
+        <Dropdown id={`${dropdownId}-filledLighter`} placeholder="-" appearance="filled-lighter" {...props}>
           <Option>Cat</Option>
           <Option>Dog</Option>
           <Option>Bird</Option>

packages/react-components/react-combobox/stories/src/Dropdown/DropdownClearable.stories.tsx

@@ -17,8 +17,8 @@ export const Clearable = () => {
 
   return (
     <div className={styles.root}>
-      <Label id={dropdownId}>Pick a color</Label>
-      <Dropdown clearable aria-labelledby={dropdownId} placeholder="Select a color">
+      <Label htmlFor={dropdownId}>Pick a color</Label>
+      <Dropdown clearable id={dropdownId} placeholder="Select a color">
         <Option>Red</Option>
         <Option>Green</Option>
         <Option>Blue</Option>

packages/react-components/react-combobox/stories/src/Dropdown/DropdownComplexOptions.stories.tsx

@@ -18,8 +18,8 @@ export const ComplexOptions = (props: Partial<DropdownProps>) => {
   const styles = useStyles();
   return (
     <div className={styles.root}>
-      <label id={dropdownId}>Schedule a meeting</label>
-      <Dropdown aria-labelledby={dropdownId} {...props}>
+      <label htmlFor={dropdownId}>Schedule a meeting</label>
+      <Dropdown id={dropdownId} {...props}>
         <Option text="Katri Athokas">
           <Persona
             avatar={{ color: 'colorful', 'aria-hidden': true }}

packages/react-components/react-combobox/stories/src/Dropdown/DropdownControllingOpenAndClose.stories.tsx

@@ -26,8 +26,8 @@ export const ControllingOpenAndClose = () => {
   return (
     <div className={styles.root}>
       <Checkbox value="open" name="state" label="open" checked={open} onChange={onChange} />
-      <label id={dropdownId}>Best pet</label>
-      <Dropdown aria-labelledby={dropdownId} placeholder="Select an animal" open={open} onOpenChange={handleOpenChange}>
+      <label htmlFor={dropdownId}>Best pet</label>
+      <Dropdown id={dropdownId} placeholder="Select an animal" open={open} onOpenChange={handleOpenChange}>
         {options.map(option => (
           <Option key={option} disabled={option === 'Ferret'}>
             {option}

packages/react-components/react-combobox/stories/src/Dropdown/DropdownCustomOptions.stories.tsx

@@ -76,13 +76,8 @@ export const CustomOptions = (props: Partial<DropdownProps>) => {
   const styles = useStyles();
   return (
     <div className={styles.root}>
-      <label id={dropdownId}>Best pet</label>
-      <Dropdown
-        aria-labelledby={dropdownId}
-        listbox={{ className: styles.listbox }}
-        placeholder="Select an animal"
-        {...props}
-      >
+      <label htmlFor={dropdownId}>Best pet</label>
+      <Dropdown id={dropdownId} listbox={{ className: styles.listbox }} placeholder="Select an animal" {...props}>
         <CustomOptionGroup label="Land" options={land} />
         <CustomOptionGroup label="Sea" options={water} />
       </Dropdown>

packages/react-components/react-combobox/stories/src/Dropdown/DropdownDefault.stories.tsx

@@ -19,8 +19,8 @@ export const Default = (props: Partial<DropdownProps>) => {
   const styles = useStyles();
   return (
     <div className={styles.root}>
-      <label id={dropdownId}>Best pet</label>
-      <Dropdown aria-labelledby={dropdownId} placeholder="Select an animal" {...props}>
+      <label htmlFor={dropdownId}>Best pet</label>
+      <Dropdown id={dropdownId} placeholder="Select an animal" {...props}>
         {options.map(option => (
           <Option key={option} disabled={option === 'Ferret'}>
             {option}

packages/react-components/react-combobox/stories/src/Dropdown/DropdownDisabled.stories.tsx

@@ -19,8 +19,8 @@ export const Disabled = (props: Partial<DropdownProps>) => {
   const styles = useStyles();
   return (
     <div className={styles.root}>
-      <label id={comboId}>Best pet</label>
-      <Dropdown aria-labelledby={comboId} disabled placeholder="Select an animal" {...props}>
+      <label htmlFor={comboId}>Best pet</label>
+      <Dropdown id={comboId} disabled placeholder="Select an animal" {...props}>
         {options.map(option => (
           <Option key={option}>{option}</Option>
         ))}

packages/react-components/react-combobox/stories/src/Dropdown/DropdownField.stories.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { Dropdown, Field, makeStyles, Option } from '@fluentui/react-components';
+import type { DropdownProps } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  root: {
+    maxWidth: '400px',
+  },
+});
+
+export const WithField = (props: Partial<DropdownProps>) => {
+  const styles = useStyles();
+  const options = ['Cat', 'Caterpillar', 'Corgi', 'Chupacabra', 'Dog', 'Ferret', 'Fish', 'Fox', 'Hamster', 'Snake'];
+  return (
+    <Field label="Best pet" required hint="Try picking 'Cat'" className={styles.root}>
+      <Dropdown placeholder="Select an animal" {...props}>
+        {options.map(option => (
+          <Option key={option} disabled={option === 'Ferret'}>
+            {option}
+          </Option>
+        ))}
+      </Dropdown>
+    </Field>
+  );
+};
+
+WithField.parameters = {
+  docs: {
+    description: {
+      story: 'Field can be used with Dropdown to provide a label, description, error message, and more.',
+    },
+  },
+};