docs: add initial Autocomplete hook docs (#7811)

* docs: add Autocomplete hook docs

* update header

* review edits

Author: reidbarber

packages/@react-aria/autocomplete/docs/useAutocomplete.mdx

@@ -0,0 +1,67 @@
+{/* Copyright 2025 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 '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-aria/autocomplete';
+import {FunctionAPI, HeaderInfo, InterfaceType, TypeContext, TypeLink, PageDescription} from '@react-spectrum/docs';
+import packageData from '@react-aria/autocomplete/package.json';
+import statelyDocs from 'docs:@react-stately/autocomplete';
+import {InlineAlert, Content, Heading} from '@adobe/react-spectrum';
+
+---
+category: Pickers
+keywords: [autocomplete, autosuggest, typeahead, search, aria]
+after_version: 3.0.0
+---
+
+# useAutocomplete
+
+<PageDescription>{docs.exports.useAutocomplete.description}</PageDescription>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['useAutocomplete']}
+  />
+
+<InlineAlert variant="notice" marginTop={60}>
+  <Heading>Under construction</Heading>
+  <Content>This hook is in <strong>beta</strong>. More documentation is coming soon!</Content>
+</InlineAlert>
+
+## API
+
+<FunctionAPI function={docs.exports.useAutocomplete} links={docs.links} />
+
+## Features
+
+Autocomplete can be implemented using the [&lt;datalist&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist) HTML element, but this has limited functionality and behaves differently across browsers.
+`useAutocomplete` helps achieve accessible text input and collection that can be styled as needed.
+
+## Anatomy
+
+An autocomplete consists of a text input that displays the current value and a collection of items. Users can type within the input
+to filter the collection. `useAutocomplete` handles exposing the correct ARIA attributes for accessibility for each of the elements comprising the autocomplete.
+
+`useAutocomplete` returns props that you should spread onto the appropriate elements:
+
+<TypeContext.Provider value={docs.links}>
+  <InterfaceType properties={docs.links[docs.exports.useAutocomplete.return.base?.id ?? docs.exports.useAutocomplete.return.id].properties} />
+</TypeContext.Provider>
+
+State is managed by the <TypeLink links={statelyDocs.links} type={statelyDocs.exports.useAutocompleteState} /> hook from `@react-stately/autocomplete`.
+The state object should be passed as an option to `useAutocomplete`.
+
+## Internationalization
+
+`useAutocomplete` handles some aspects of internationalization automatically.
+For example, VoiceOver announcements about the item focus, count, and selection are localized.
+You are responsible for localizing all labels and option
+content that is passed into the autocomplete.

packages/@react-aria/autocomplete/src/index.ts

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 export {useSearchAutocomplete} from './useSearchAutocomplete';
-export {UNSTABLE_useAutocomplete} from './useAutocomplete';
+export {useAutocomplete} from './useAutocomplete';
 
 export type {AriaSearchAutocompleteOptions, SearchAutocompleteAria} from './useSearchAutocomplete';
 export type {AriaSearchAutocompleteProps} from '@react-types/autocomplete';

packages/@react-aria/autocomplete/src/useAutocomplete.ts

@@ -59,7 +59,7 @@ export interface AutocompleteAria {
  * @param props - Props for the autocomplete.
  * @param state - State for the autocomplete, as returned by `useAutocompleteState`.
  */
-export function UNSTABLE_useAutocomplete(props: AriaAutocompleteOptions, state: AutocompleteState): AutocompleteAria {
+export function useAutocomplete(props: AriaAutocompleteOptions, state: AutocompleteState): AutocompleteAria {
   let {
     inputRef,
     collectionRef,

packages/@react-stately/autocomplete/docs/useAutocompleteState.mdx

@@ -0,0 +1,38 @@
+{/* Copyright 2025 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 '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-stately/autocomplete';
+import {ClassAPI, HeaderInfo, FunctionAPI, PageDescription} from '@react-spectrum/docs';
+import packageData from '@react-stately/autocomplete/package.json';
+
+---
+category: Pickers
+keywords: [autocomplete, state]
+after_version: 3.0.0-alpha.0
+---
+
+# useAutocompleteState
+
+<PageDescription>{docs.exports.useAutocompleteState.description}</PageDescription>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['useAutocompleteState']} />
+
+## API
+
+<FunctionAPI function={docs.exports.useAutocompleteState} links={docs.links} />
+
+## Interface
+
+<ClassAPI links={docs.links} class={docs.links[docs.exports.useAutocompleteState.return.id]} />
+

packages/@react-stately/autocomplete/src/index.ts

@@ -10,6 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-export {UNSTABLE_useAutocompleteState} from './useAutocompleteState';
+export {useAutocompleteState} from './useAutocompleteState';
 
 export type {AutocompleteProps, AutocompleteStateOptions, AutocompleteState} from './useAutocompleteState';

packages/@react-stately/autocomplete/src/useAutocompleteState.ts

@@ -41,7 +41,7 @@ export interface AutocompleteStateOptions extends Omit<AutocompleteProps, 'child
 /**
  * Provides state management for an autocomplete component.
  */
-export function UNSTABLE_useAutocompleteState(props: AutocompleteStateOptions): AutocompleteState {
+export function useAutocompleteState(props: AutocompleteStateOptions): AutocompleteState {
   let {
     onInputChange: propsOnInputChange,
     inputValue: propsInputValue,

packages/react-aria-components/src/Autocomplete.tsx

@@ -10,8 +10,8 @@
  * governing permissions and limitations under the License.
  */
 
-import {AriaAutocompleteProps, CollectionOptions, UNSTABLE_useAutocomplete} from '@react-aria/autocomplete';
-import {AutocompleteState, UNSTABLE_useAutocompleteState} from '@react-stately/autocomplete';
+import {AriaAutocompleteProps, CollectionOptions, useAutocomplete} from '@react-aria/autocomplete';
+import {AutocompleteState, useAutocompleteState} from '@react-stately/autocomplete';
 import {InputContext} from './Input';
 import {mergeProps} from '@react-aria/utils';
 import {Provider, removeDataAttributes, SlotProps, SlottedContextValue, useSlottedContext} from './utils';
@@ -40,15 +40,15 @@ export function Autocomplete(props: AutocompleteProps) {
   let ctx = useSlottedContext(AutocompleteContext, props.slot);
   props = mergeProps(ctx, props);
   let {filter} = props;
-  let state = UNSTABLE_useAutocompleteState(props);
+  let state = useAutocompleteState(props);
   let inputRef = useRef<HTMLInputElement | null>(null);
   let collectionRef = useRef<HTMLElement>(null);
   let {
     textFieldProps,
     collectionProps,
     collectionRef: mergedCollectionRef,
     filterFn
-  } = UNSTABLE_useAutocomplete({
+  } = useAutocomplete({
     ...removeDataAttributes(props),
     filter,
     inputRef,