[WIP] docs: add new React Aria hooks docs

packages/dev/s2-docs/pages/react-aria/Button.mdx

@@ -12,7 +12,7 @@ import '../../tailwind/tailwind.css';
 import typesDocs from 'docs:@react-types/shared/src/events.d.ts';
 
 export const tags = ['btn'];
-export const relatedPages = [{'title': 'useButton', 'url': 'Button/useButton.html'}];
+export const relatedPages = [{'title': 'useButton', 'url': './Button/useButton'}];
 export const description = 'Allows a user to perform an action, with mouse, touch, and keyboard interactions.';
 
 # Button

packages/dev/s2-docs/pages/react-aria/Button/useButton.mdx

@@ -0,0 +1,76 @@
+{/* Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License. */}
+
+import {Layout} from '../../../src/Layout';
+export default Layout;
+import {FunctionAPI} from '../../../src/FunctionAPI';
+import {InterfaceType} from '../../../src/types';
+import docs from 'docs:@react-aria/button';
+
+export const section = 'Hooks';
+export const description = 'Provides the behavior and accessibility implementation for a button.';
+export const isSubpage = true;
+
+# useButton
+
+<PageDescription>{docs.exports.useButton.description}</PageDescription>
+
+```tsx render
+"use client";
+import React from 'react';
+import {useButton} from 'react-aria/useButton';
+
+function Button(props) {
+  let ref = React.useRef(null);
+  let {buttonProps, isPressed} = useButton(props, ref);
+
+  return (
+    <button
+      {...buttonProps}
+      ref={ref}
+      style={{
+        background: isPressed ? 'darkgreen' : 'green',
+        color: 'white',
+        border: 'none',
+        padding: '8px 12px',
+        borderRadius: 8,
+        fontSize: 14,
+        cursor: 'pointer'
+      }}>
+      {props.children}
+    </button>
+  );
+}
+
+<Button onPress={() => alert('Button pressed!')}>Press me</Button>
+```
+
+## Features
+
+On the surface, building a custom styled button seems simple. However, there are many cross browser inconsistencies in interactions and accessibility features to consider. `useButton` handles all of these interactions for you, so you can focus on the styling. It follows the [ARIA button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+
+* Native HTML `<button>` support
+* `<a>` and custom element type support via ARIA
+* Mouse and touch event handling, and press state management
+* Keyboard focus management and cross browser normalization
+* Keyboard event support for <Keyboard>Space</Keyboard> and <Keyboard>Enter</Keyboard> keys
+
+Read our [blog post](../blog/building-a-button-part-1) about the complexities of building buttons that work well across devices and interaction methods.
+
+## API
+
+<FunctionAPI function={docs.exports.useButton} links={docs.links} />
+
+### AriaButtonProps
+
+<InterfaceType {...docs.exports.AriaButtonProps} />
+
+### ButtonAria
+
+<InterfaceType {...docs.exports.ButtonAria} />

packages/dev/s2-docs/pages/react-aria/ListBox.mdx

@@ -10,7 +10,7 @@ import {InlineAlert, Heading, Content} from '@react-spectrum/s2'
 
 export const tags = ['options'];
 export const relatedPages = [
-  {title: 'useListBox', url: 'ListBox/useListBox.html'},
+  {title: 'useListBox', url: './ListBox/useListBox'},
   {title: 'Testing ListBox', url: './ListBox/testing'}
 ];
 export const description = 'Displays a list of options and allows a user to select one or more of them.';

packages/dev/s2-docs/pages/react-aria/ListBox/useListBox.mdx

@@ -0,0 +1,145 @@
+{/* Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License. */}
+
+import {Layout} from '../../../src/Layout';
+export default Layout;
+import {FunctionAPI} from '../../../src/FunctionAPI';
+import {InterfaceType} from '../../../src/types';
+import docs from 'docs:@react-aria/listbox';
+
+export const section = 'Hooks';
+export const description = 'Provides the behavior and accessibility implementation for a listbox component.';
+export const isSubpage = true;
+
+# useListBox
+
+<PageDescription>{docs.exports.useListBox.description}</PageDescription>
+
+```tsx render
+"use client";
+import React from 'react';
+import {useListBox, useOption} from 'react-aria/useListBox';
+import {useListState} from 'react-stately/useListState';
+import {Item} from 'react-stately/Item';
+import {useFocusRing} from 'react-aria/useFocusRing';
+import {mergeProps} from 'react-aria/mergeProps';
+
+function ListBox(props) {
+  // Create state based on the incoming props.
+  let state = useListState(props);
+  let ref = React.useRef(null);
+  let {listBoxProps, labelProps} = useListBox(props, state, ref);
+
+  return (
+    <>
+      <div {...labelProps}>{props.label}</div>
+      <ul
+        {...listBoxProps}
+        ref={ref}
+        style={{
+          padding: 0,
+          margin: '5px 0',
+          listStyle: 'none',
+          border: '1px solid gray',
+          maxWidth: 250,
+          maxHeight: 300,
+          overflow: 'auto'
+        }}>
+        {[...state.collection].map(item => (
+          <Option key={item.key} item={item} state={state} />
+        ))}
+      </ul>
+    </>
+  );
+}
+
+function Option({item, state}) {
+  let ref = React.useRef(null);
+  let {optionProps, isSelected, isDisabled} = useOption({key: item.key}, state, ref);
+
+  // Determine whether we should show a keyboard focus ring for accessibility.
+  let {isFocusVisible, focusProps} = useFocusRing();
+
+  return (
+    <li
+      {...mergeProps(optionProps, focusProps)}
+      ref={ref}
+      style={{
+        display: 'block',
+        padding: '2px 5px',
+        outline: isFocusVisible ? '2px solid orange' : 'none',
+        background: isSelected ? 'blueviolet' : 'transparent',
+        color: isSelected ? 'white' : isDisabled ? '#aaa' : 'inherit',
+        cursor: 'default'
+      }}>
+      {item.rendered}
+    </li>
+  );
+}
+
+<ListBox label="Alignment" selectionMode="single">
+  <Item>Left</Item>
+  <Item>Middle</Item>
+  <Item>Right</Item>
+</ListBox>
+```
+
+## Features
+
+A listbox can be built using the [&lt;select&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) and [&lt;option&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option) HTML elements, but this is not possible to style consistently cross browser. `useListBox` helps achieve accessible listbox components that can be styled as needed. It follows the [ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
+
+Note: `useListBox` only handles the list itself. For a dropdown similar to a `<select>`, see [useSelect](../Select/useSelect).
+
+* Exposed to assistive technology as a `listbox` using ARIA
+* Support for single, multiple, or no selection
+* Support for disabled items
+* Support for sections
+* Labeling support for accessibility
+* Support for mouse, touch, and keyboard interactions
+* Tab stop focus management
+* Keyboard navigation support including arrow keys, home/end, page up/down, select all, and clear
+* Automatic scrolling support during keyboard navigation
+* Typeahead to allow focusing options by typing text
+* Support for use with virtualized lists
+
+## State management
+
+`useListBox` requires knowledge of the options in the listbox in order to handle keyboard navigation and other interactions. It does this using the `Collection` interface, which is a generic interface to access sequential unique keyed data. You can implement this interface yourself, e.g. by using a prop to pass a list of item objects, but `useListState` from `react-stately` implements a JSX based interface for building collections instead. See [Collection Components](../collections) for more information.
+
+In addition, `useListState` manages the state necessary for multiple selection and exposes a `SelectionManager`, which makes use of the collection to provide an interface to update the selection state. For more information, see [Selection](../selection).
+
+## API
+
+<FunctionAPI function={docs.exports.useListBox} links={docs.links} />
+<FunctionAPI function={docs.exports.useOption} links={docs.links} />
+<FunctionAPI function={docs.exports.useListBoxSection} links={docs.links} />
+
+### AriaListBoxOptions
+
+<InterfaceType {...docs.exports.AriaListBoxOptions} />
+
+### ListBoxAria
+
+<InterfaceType {...docs.exports.ListBoxAria} />
+
+### AriaOptionProps
+
+<InterfaceType {...docs.exports.AriaOptionProps} />
+
+### OptionAria
+
+<InterfaceType {...docs.exports.OptionAria} />
+
+### AriaListBoxSectionProps
+
+<InterfaceType {...docs.exports.AriaListBoxSectionProps} />
+
+### ListBoxSectionAria
+
+<InterfaceType {...docs.exports.ListBoxSectionAria} />

packages/dev/s2-docs/pages/react-aria/Select.mdx

@@ -9,7 +9,7 @@ import {InlineAlert, Heading, Content} from '@react-spectrum/s2'
 
 export const tags = ['picker', 'dropdown', 'menu', 'input'];
 export const relatedPages = [
-  {title: 'useSelect', url: 'Select/useSelect.html'},
+  {title: 'useSelect', url: './Select/useSelect'},
   {title: 'Testing Select', url: './Select/testing'}
 ];
 export const description = 'Displays a collapsible list of options and allows a user to select one of them.';

packages/dev/s2-docs/pages/react-aria/Select/useSelect.mdx

@@ -0,0 +1,140 @@
+{/* Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License. */}
+
+import {Layout} from '../../../src/Layout';
+export default Layout;
+import {FunctionAPI} from '../../../src/FunctionAPI';
+import {InterfaceType} from '../../../src/types';
+import docs from 'docs:@react-aria/select';
+
+export const section = 'Hooks';
+export const description = 'Provides the behavior and accessibility implementation for a select component.';
+export const isSubpage = true;
+
+# useSelect
+
+<PageDescription>{docs.exports.useSelect.description}</PageDescription>
+
+This example uses `useSelect` to provide the behavior for a custom select, and reuses the [Button](../Button), [Popover](../Popover), and [ListBox](../ListBox) components from React Aria Components to render the trigger, popup, and list of options. The values returned by the hook are passed to these components via context, following the [Reusing children](../customization#reusing-children) pattern. A &lt;`HiddenSelect`&gt; renders a hidden native `<select>` to enable browser form autofill.
+
+```tsx render
+"use client";
+import React from 'react';
+import {HiddenSelect, useSelect} from 'react-aria/useSelect';
+import {useSelectState} from 'react-stately/useSelectState';
+import {CollectionBuilder} from 'react-aria/CollectionBuilder';
+import {Provider} from 'react-aria-components/slots';
+import {SelectValue, SelectContext, SelectStateContext, SelectValueContext} from 'react-aria-components/Select';
+import {Collection} from 'react-aria-components/Collection';
+import {LabelContext} from 'react-aria-components/Label';
+import {ButtonContext} from 'react-aria-components/Button';
+import {OverlayTriggerStateContext} from 'react-aria-components/Dialog';
+import {PopoverContext} from 'react-aria-components/Popover';
+import {ListBoxContext, ListStateContext} from 'react-aria-components/ListBox';
+import {Button} from 'vanilla-starter/Button';
+import {Label} from 'vanilla-starter/Form';
+import {Popover} from 'vanilla-starter/Popover';
+import {SelectListBox, SelectItem} from 'vanilla-starter/Select';
+import {ChevronDown} from 'lucide-react';
+import 'vanilla-starter/Select.css';
+
+function Select(props) {
+  // useSelectState needs a collection built from the items. CollectionBuilder
+  // renders a hidden copy of them to construct it before rendering.
+  return (
+    <CollectionBuilder content={<Collection>{props.children}</Collection>}>
+      {collection => <SelectInner {...props} collection={collection} />}
+    </CollectionBuilder>
+  );
+}
+
+function SelectInner({collection, ...props}) {
+  // Create state based on the collection and incoming props.
+  let state = useSelectState({...props, collection, children: undefined});
+
+  // Get props for child elements from useSelect.
+  let buttonRef = React.useRef(null);
+  let scrollRef = React.useRef(null);
+  let {labelProps, triggerProps, valueProps, menuProps, hiddenSelectProps} =
+    useSelect(props, state, buttonRef);
+
+  // Provide the values returned by the hook to the reused components via context.
+  return (
+    <Provider
+      values={[
+        [SelectContext, props],
+        [SelectStateContext, state],
+        [SelectValueContext, valueProps],
+        [LabelContext, {...labelProps, elementType: 'span'}],
+        [ButtonContext, {...triggerProps, ref: buttonRef, isPressed: state.isOpen}],
+        [OverlayTriggerStateContext, state],
+        [PopoverContext, {trigger: 'Select', triggerRef: buttonRef, scrollRef, placement: 'bottom start'}],
+        [ListBoxContext, {...menuProps, ref: scrollRef}],
+        [ListStateContext, state]
+      ]}>
+      <div className="react-aria-Select">
+        <Label>{props.label}</Label>
+        <Button>
+          <SelectValue />
+          <ChevronDown />
+        </Button>
+        <HiddenSelect {...hiddenSelectProps} />
+        <Popover hideArrow className="select-popover">
+          {/* Rendered from the collection in state, provided via ListStateContext. */}
+          <SelectListBox />
+        </Popover>
+      </div>
+    </Provider>
+  );
+}
+
+<Select label="Favorite Animal">
+  <SelectItem>Aardvark</SelectItem>
+  <SelectItem>Cat</SelectItem>
+  <SelectItem>Dog</SelectItem>
+  <SelectItem>Kangaroo</SelectItem>
+  <SelectItem>Panda</SelectItem>
+  <SelectItem>Snake</SelectItem>
+</Select>
+```
+
+## Features
+
+A select can be built using the [&lt;select&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) and [&lt;option&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option) HTML elements, but this is not possible to style consistently cross browser, especially the options. `useSelect` helps achieve accessible select components that can be styled as needed without compromising on high quality interactions. It follows the [ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
+
+* Exposed to assistive technology as a button with a `listbox` popup using ARIA (combined with [useListBox](../ListBox/useListBox))
+* Support for selecting a single option
+* Support for disabled options
+* Support for sections
+* Labeling support for accessibility
+* Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors
+* Support for mouse, touch, and keyboard interactions
+* Tab stop focus management
+* Keyboard support for opening the listbox using the arrow keys, including automatically focusing the first or last item accordingly
+* Typeahead to allow selecting options by typing text, even without opening the listbox
+* Browser autofill integration via a hidden native `<select>` element
+* Mobile screen reader listbox dismissal support
+
+## State management
+
+`useSelect` requires knowledge of the options in the select in order to handle keyboard navigation and other interactions. It does this using the `Collection` interface, which is a generic interface to access sequential unique keyed data. You can implement this interface yourself, e.g. by using a prop to pass a list of item objects, but `useSelectState` from `react-stately` implements a JSX based interface for building collections instead. See [Collection Components](../collections) for more information.
+
+In addition, `useSelectState` manages the state necessary for selection and exposes a `SelectionManager`, which makes use of the collection to provide an interface to update the selection state. It also holds state to track if the popup is open. For more information about selection, see [Selection](../selection).
+
+## API
+
+<FunctionAPI function={docs.exports.useSelect} links={docs.links} />
+
+### AriaSelectOptions
+
+<InterfaceType {...docs.exports.AriaSelectOptions} />
+
+### SelectAria
+
+<InterfaceType {...docs.exports.SelectAria} />