docs: S2 docs TODOs for release (#9261)

reidbarber · web-flow · commit b47ceb1f25b6 · 2025-12-01T20:16:44.000Z
* fix docs todos

* fix SelectBoxGroup JSDoc

* show asterisk for required props in props tables

* fix marginStart on header logo
diff --git a/packages/@react-spectrum/s2/src/SelectBoxGroup.tsx b/packages/@react-spectrum/s2/src/SelectBoxGroup.tsx
@@ -368,7 +368,7 @@ export function SelectBox(props: SelectBoxProps): ReactNode {
   );
 }
 
-/*
+/**
  * SelectBoxGroup allows users to select one or more options from a list.
  */
 export const SelectBoxGroup = /*#__PURE__*/ forwardRef(function SelectBoxGroup<T extends object>(props: SelectBoxGroupProps<T>, ref: DOMRef<HTMLDivElement>) {
diff --git a/packages/dev/s2-docs/pages/react-aria/FocusScope.mdx b/packages/dev/s2-docs/pages/react-aria/FocusScope.mdx
@@ -42,8 +42,7 @@ button mounts a FocusScope, which auto focuses the first input inside it. Once o
 press the <Keyboard>Tab</Keyboard> key to move within the scope, but focus is contained inside. Clicking the "Close"
 button unmounts the focus scope, which restores focus back to the button.
 
-{/* Not implemented yet */}
-{/* For a full example of building a modal dialog, see [useDialog](useDialog). */}
+For a full example of building a modal dialog, see [useDialog](https://react-spectrum.adobe.com/react-aria/useDialog.html).
 
 ```tsx render
 'use client';
diff --git a/packages/dev/s2-docs/pages/react-aria/VisuallyHidden.mdx b/packages/dev/s2-docs/pages/react-aria/VisuallyHidden.mdx
@@ -56,8 +56,7 @@ let {visuallyHiddenProps} = useVisuallyHidden();
 
 <PropTable links={docs.links} component={docs.exports.VisuallyHidden} />
 
-{/* not implemented yet */}
-{/* ## Example
+## Example
 
-See [useRadioGroup](useRadioGroup#styling) and [useCheckbox](useCheckbox#styling)
-for examples of using `VisuallyHidden` to hide native form elements visually. */}
+See [useRadioGroup](https://react-spectrum.adobe.com/react-aria/useRadioGroup.html#styling) and [useCheckbox](https://react-spectrum.adobe.com/react-aria/useCheckbox.html#styling)
+for examples of using `VisuallyHidden` to hide native form elements visually.
diff --git a/packages/dev/s2-docs/pages/react-aria/useField.mdx b/packages/dev/s2-docs/pages/react-aria/useField.mdx
@@ -26,8 +26,7 @@ The `useField` hook associates a form control with a label, and an optional desc
 
 By default, `useField` assumes that the label is a native HTML `<label>` element. However, if you are labeling a non-native form element, be sure to use an element other than a `<label>` and set the `labelElementType` prop appropriately.
 
-{/* not implemented yet */}
-{/* **Note**: Many other React Aria hooks such as [useTextField](useTextField), [useSelect](useSelect), and [useComboBox](useComboBox) already include support for description and error message elements. If you're using one of those hooks, there's no need to use `useField`. */}
+**Note**: Many other React Aria hooks such as [useTextField](https://react-spectrum.adobe.com/react-aria/useTextField.html), [useSelect](https://react-spectrum.adobe.com/react-aria/useSelect.html), and [useComboBox](https://react-spectrum.adobe.com/react-aria/useComboBox.html) already include support for description and error message elements. If you're using one of those hooks, there's no need to use `useField`.
 
 ## Example
 
diff --git a/packages/dev/s2-docs/pages/react-aria/useFocusRing.mdx b/packages/dev/s2-docs/pages/react-aria/useFocusRing.mdx
@@ -34,10 +34,9 @@ If CSS classes are being used for styling, see the [FocusRing](FocusRing) compon
 This example shows how to use `useFocusRing` to adjust styling when keyboard focus is on a button.
 Specifically, the `outline` property is used to create the focus ring when `isFocusVisible` is true.
 
-{/* Not implemented yet */}
-{/* See [useCheckbox](useCheckbox#styling), [useRadioGroup](useRadioGroup#styling), and
-[useSwitch](useSwitch#example) for more advanced examples of focus rings with other styling
-techniques. */}
+See [useCheckbox](https://react-spectrum.adobe.com/react-aria/useCheckbox.html#styling), [useRadioGroup](https://react-spectrum.adobe.com/react-aria/useRadioGroup.html#styling), and
+[useSwitch](https://react-spectrum.adobe.com/react-aria/useSwitch.html#example) for more advanced examples of focus rings with other styling
+techniques.
 
 ```tsx render
 'use client';
diff --git a/packages/dev/s2-docs/pages/react-aria/useHover.mdx b/packages/dev/s2-docs/pages/react-aria/useHover.mdx
@@ -30,8 +30,7 @@ but `:hover` is problematic on touch devices due to mouse emulation in mobile br
 and device, `:hover` may never apply, or may apply continuously until the user touches another element.
 `useHover` only applies when the pointer is truly capable of hovering, and emulated mouse events are ignored.
 
-{/* TODO: uncomment once we transfer over the blogs to new docs  */}
-{/* Read our [blog post](/blog/building-a-button-part-2) about the complexities of hover event handling to learn more. */}
+Read our [blog post](blog/building-a-button-part-2) about the complexities of hover event handling to learn more.
 
 ## Accessibility
 
diff --git a/packages/dev/s2-docs/pages/react-aria/useKeyboard.mdx b/packages/dev/s2-docs/pages/react-aria/useKeyboard.mdx
@@ -31,8 +31,7 @@ it can call `event.continuePropagation()` to allow parents to handle the event.
 
 This example shows a simple input element that handles keyboard events with `useKeyboard` and logs them to a list below.
 
-{/* TODO: Components hooks have not been written yet */}
-{/* **NOTE: for more advanced text field functionality, see [useTextField](useTextField).** */}
+**NOTE: for more advanced text field functionality, see [useTextField](https://react-spectrum.adobe.com/react-aria/useTextField.html).**
 
 ```tsx render
 "use client"
diff --git a/packages/dev/s2-docs/pages/react-aria/useLabel.mdx b/packages/dev/s2-docs/pages/react-aria/useLabel.mdx
@@ -51,9 +51,8 @@ By default, `useLabel` assumes that the label is a native HTML label element.
 However, if you are labeling a non-native form element, be sure to use an
 element other than a `<label>` and set the `labelElementType` prop appropriately.
 
-{/* not implemented yet */}
-{/* See [useRadioGroup](useRadioGroup#example) and [useTextField](useTextField#example)
-for examples of how `useLabel` is used by components. */}
+See [useRadioGroup](https://react-spectrum.adobe.com/react-aria/useRadioGroup.html#example) and [useTextField](https://react-spectrum.adobe.com/react-aria/useTextField.html#example)
+for examples of how `useLabel` is used by components.
 
 ## API
 
diff --git a/packages/dev/s2-docs/pages/react-aria/useLandmark.mdx b/packages/dev/s2-docs/pages/react-aria/useLandmark.mdx
@@ -39,8 +39,7 @@ If an element within a landmark was previously focused before leaving that landm
 
 If multiple landmarks are registered with the same role, they should have unique labels, which can be provided by aria-label or aria-labelledby.
 
-{/* TODO: Not implemented yet */}
-{/* For an example of landmarks in use, see the [useToastRegion](useToast#anatomy) documentation. */}
+For an example of landmarks in use, see the [useToastRegion](https://react-spectrum.adobe.com/react-aria/useToast.html#anatomy) documentation.
 
 ## Example
 
diff --git a/packages/dev/s2-docs/pages/react-aria/usePress.mdx b/packages/dev/s2-docs/pages/react-aria/usePress.mdx
@@ -34,8 +34,7 @@ the visual appearance of the target. If the pointer is released over the target,
 * Handles canceling press interactions on scroll
 * Normalizes many cross browser inconsistencies
 
-{/* TODO: uncomment once blog posts are transferred over */}
-{/* Read our [blog post](/blog/building-a-button-part-1) about the complexities of press event handling to learn more. */}
+Read our [blog post](blog/building-a-button-part-1) about the complexities of press event handling to learn more.
 
 ## Example
 
@@ -44,8 +43,7 @@ It also uses the `isPressed` state to adjust the background color when the targe
 Press down on the target and drag your pointer off and over to see when the events are fired, and try focusing
 the target with a keyboard and pressing the <Keyboard>Enter</Keyboard> or <Keyboard>Space</Keyboard> keys to trigger events as well.
 
-{/* Not implemented yet */}
-{/* **NOTE: for more advanced button functionality, see [useButton](useButton).** */}
+**NOTE: for more advanced button functionality, see [useButton](https://react-spectrum.adobe.com/react-aria/useButton.html).**
 
 ```tsx render
 "use client";
diff --git a/packages/dev/s2-docs/src/Header.tsx b/packages/dev/s2-docs/src/Header.tsx
@@ -36,7 +36,7 @@ const libraryStyles = style({
       default: 'transparent'
     }
   },
-  marginStart: space(14)
+  marginStart: space(26)
 });
 
 const linkStyle = {
diff --git a/packages/dev/s2-docs/src/PropTable.tsx b/packages/dev/s2-docs/src/PropTable.tsx
@@ -1,3 +1,4 @@
+import Asterisk from '../../../@react-spectrum/s2/ui-icons/Asterisk';
 import {Code, styles as codeStyles} from './Code';
 import {CSSVariables, StateTable} from './StateTable';
 import {DisclosureRow} from './DisclosureRow';
@@ -126,8 +127,9 @@ export function GroupedPropTable({properties, links, propGroups = GROUPS, defaul
 
   // properties.sort((a, b) => a.name.localeCompare(b.name));
 
+  let allProps = [...Object.values(props), ...Object.values(groups).flatMap(g => Object.values(g))];
   // Default to showing required indicators if some properties are optional but not all.
-  // let showRequired = !properties.every(p => p.optional) && !properties.every(p => !p.optional);
+  let showRequired = !allProps.every(p => p.optional) && !allProps.every(p => !p.optional);
 
   // Show default values by default if any of the properties have one defined.
   let showDefault = Object.values(props).some(p => !!p.default);
@@ -143,18 +145,18 @@ export function GroupedPropTable({properties, links, propGroups = GROUPS, defaul
         </tr>
       </TableHeader>
       <TableBody>
-        <Rows props={props} showDefault={showDefault} />
+        <Rows props={props} showDefault={showDefault} showRequired={showRequired} />
       </TableBody>
       {Object.keys(groups).map((group) => (
         <DisclosureRow key={group} title={group} defaultExpanded={defaultExpanded?.has(group)}>
-          <Rows props={groups[group]} showDefault={showDefault} />
+          <Rows props={groups[group]} showDefault={showDefault} showRequired={showRequired} />
         </DisclosureRow>
       ))}
     </Table>
   );
 }
 
-function Rows({props, showDefault}: {props: TInterface['properties'], showDefault?: boolean}) {
+function Rows({props, showDefault, showRequired}: {props: TInterface['properties'], showDefault?: boolean, showRequired?: boolean}) {
   let properties = Object.values(props);
 
   return properties.map((prop, index) => (
@@ -164,10 +166,10 @@ function Rows({props, showDefault}: {props: TInterface['properties'], showDefaul
           <code className={codeStyle}>
             <span className={codeStyles.attribute}>{prop.name}</span>
           </code>
-          {/* {!prop.optional && showRequired
-            ? <Asterisk size="XXS" UNSAFE_className={styles.requiredIcon} aria-label="Required" />
+          {!prop.optional && showRequired
+            ? <Asterisk size="M" className={style({marginStart: 4})} aria-label="Required" />
             : null
-          } */}
+          }
         </TableCell>
         <TableCell hideBorder={!!prop.description}>
           <code className={codeStyle}>

Original file line number	Diff line number	Diff line change
`@@ -368,7 +368,7 @@ export function SelectBox(props: SelectBoxProps): ReactNode {`
`368`	`368`	`);`
`369`	`369`	`}`
`370`	`370`
`371`		`-/*`
	`371`	`+/**`
`372`	`372`	`* SelectBoxGroup allows users to select one or more options from a list.`
`373`	`373`	`*/`
`374`	`374`	`export const SelectBoxGroup = /#__PURE__/ forwardRef(function SelectBoxGroup<T extends object>(props: SelectBoxGroupProps<T>, ref: DOMRef<HTMLDivElement>) {`