Docs for useLandmark

packages/@react-aria/landmark/docs/useLandmark.mdx

@@ -0,0 +1,111 @@
+{/* Copyright 2023 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/landmark';
+import {HeaderInfo, FunctionAPI, PageDescription} from '@react-spectrum/docs';
+import {Keyboard} from '@react-spectrum/text';
+import packageData from '@react-aria/landmark/package.json';
+
+---
+category: Utilities
+keywords: [landmarks, aria]
+---
+
+# useLandmark
+
+<PageDescription>{docs.exports.useLandmark.description}</PageDescription>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['useLandmark']}
+  sourceData={[
+    {type: 'W3C', url: 'https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/'}
+  ]} />
+
+## API
+
+<FunctionAPI function={docs.exports.useLandmark} links={docs.links} />
+
+## Features
+
+Landmarks provide a way to designate important subsections of a page. They allow screen reader users to get an overview of the various sections of the page, and jump to a specific section.
+By default, browsers do not provide a consistent way to navigate between landmarks using the keyboard.
+The `useLandmark` hook enables keyboard navigation between landmarks, and provides a consistent experience across browsers.
+
+* <Keyboard>F6</Keyboard> and <Keyboard>Shift+F6</Keyboard> key navigation between landmarks
+* <Keyboard>Alt+F6</Keyboard> key navigation to the main landmark
+* Support for navigating nested landmarks
+
+## Anatomy
+
+Landmark elements can be registered with the `useLandmark` hook. The `role` prop is required.
+
+Pressing <Keyboard>F6</Keyboard> will move focus to the next landmark on the page, and pressing <Keyboard>Shift+F6</Keyboard> will move focus to the previous landmark.
+If an element within a landmark was previously focused before leaving that landmark, focus will return to that element when navigating back to that landmark.
+<Keyboard>Alt+F6</Keyboard> will always move focus to the main landmark if it has been registered.
+
+If multiple landmarks are registered with the same role, they should have unique labels, which can be provided by aria-label or aria-labelledby.
+
+For an example of landmarks in use, see the [useToastRegion](useToast.html#anatomy) documentation.
+
+## Example
+
+```tsx example export=true
+import {useLandmark} from '@react-aria/landmark';
+import {useRef} from 'react';
+
+function Navigation(props) {
+  let ref = useRef();
+  let {landmarkProps} = useLandmark({...props, role: 'navigation'}, ref);
+  return (
+    <nav ref={ref} {...props} {...landmarkProps}>
+      {props.children}
+    </nav>
+  );
+}
+
+function Region(props) {
+  let ref = useRef();
+  let {landmarkProps} = useLandmark({...props, role: 'region'}, ref);
+  return (
+    <article ref={ref} {...props} {...landmarkProps}>
+      {props.children}
+    </article>
+  );
+}
+
+function Search(props) {
+  let ref = useRef();
+  let {landmarkProps} = useLandmark({...props, role: 'search'}, ref);
+  return (
+    <form ref={ref} {...props} {...landmarkProps}>
+      <h2 id="search-header">Search</h2>
+      <input aria-labelledby="search-header" type="search" />
+    </form>
+  );
+}
+
+<div>
+  <Navigation>
+    <h2>Navigation</h2>
+    <ul>
+      <li><a href="#">Link 1</a></li>
+      <li><a href="#">Link 2</a></li>
+    </ul>
+  </Navigation>
+  <Search />
+  <Region>
+    <h2>Region</h2>
+    <p>Example region with no focusable children.</p>
+  </Region>
+</div>
+```