Skip to content

Commit 1403064

Browse files
devongovettdevongovett
committed
docs: Add concepts page
1 parent 8e7a57d commit 1403064

File tree

3 files changed

+160
-4
lines changed

3 files changed

+160
-4
lines changed

‎packages/dev/s2-docs/pages/react-aria/concepts.mdx‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
import {Layout} from '../../src/Layout';
2+
export default Layout;
3+
4+
export const section = 'Guides';
5+
export const description = 'Implementing drag and drop in React Aria';
6+
7+
# Concepts
8+
9+
<PageDescription>React Aria is built around three core principles: **Accessibility**, **Internationalization**, and **Interactions**. Together, these ensure that every component you build works for everyone, everywhere, and on every device.</PageDescription>
10+
11+
## Accessibility
12+
13+
Accessible applications are usable by everyone, including people with disabilities. Accessibility benefits all users — not just those using assistive technologies — by improving efficiency, consistency, and usability.
14+
15+
React Aria provides built-in support for screen readers and keyboard navigation, following the [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/) and [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) guidelines. It supplies the correct semantics via ARIA roles and attributes, handles keyboard and pointer events, manages focus, and provides screen reader announcements. React Aria components are tested across a wide variety of devices, browsers, and screen readers.
16+
17+
You’re responsible for providing meaningful labels and ensuring your visual design supports all users. This includes designing with sufficient [color contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast) and [hit target sizes](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced), including visible [focus rings](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance), respecting [motion preferences](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions), and more. The [WCAG guidelines](https://www.w3.org/WAI/WCAG22/Understanding/) are a good resource to reference when designing and building components with React Aria.
18+
19+
### Labeling
20+
21+
Most components should have a visible label, which is usually provided by rendering a `<Label>` element within it. This is associated with the component automatically.
22+
23+
```tsx
24+
import {TextField, Label, Input} from 'react-aria-components';
25+
26+
<TextField>
27+
{/*- begin highlight -*/}
28+
<Label>First name</Label>
29+
{/*- end highlight -*/}
30+
<Input />
31+
</TextField>
32+
```
33+
34+
When a component doesn't have a visible label, it must have an [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) prop to provide an accessible name.
35+
36+
```tsx
37+
import {ProgressBar} from 'react-aria-components';
38+
39+
<ProgressBar
40+
/*- begin highlight -*/
41+
aria-label="Processing" />
42+
/*- end highlight -*/
43+
```
44+
45+
### Supported screen readers
46+
47+
React Aria is tested across a variety of devices, browsers, and screen readers.
48+
49+
* [VoiceOver on macOS](https://www.apple.com/accessibility/mac/vision/) in Safari and Chrome
50+
* [JAWS](https://www.freedomscientific.com/products/software/jaws/) on Windows in Firefox and Chrome
51+
* [NVDA](https://www.nvaccess.org) on Windows in Firefox and Chrome
52+
* [VoiceOver on iOS](https://www.apple.com/accessibility/iphone/vision/)
53+
* [TalkBack](https://www.android.com/accessibility/) on Android in Chrome
54+
55+
### Automated testing
56+
57+
Automated accessibility testing tools sometimes catch false positives in React Aria. These are documented in our [wiki](https://github.com/adobe/react-spectrum/wiki/Known-accessibility-false-positives). Use the rules below to ignore these issues in your own testing tools, such as in the [Storybook test runner](https://storybook.js.org/docs/7.1/react/writing-tests/accessibility-testing#a11y-config-with-the-test-runner) or [Storybook a11y addon](https://storybook.js.org/docs/7.1/react/writing-tests/accessibility-testing#global-a11y-configuration).
58+
59+
```tsx
60+
{
61+
rules: [
62+
{
63+
id: 'aria-hidden-focus',
64+
selector: 'body *:not([data-a11y-ignore="aria-hidden-focus"])'
65+
}
66+
]
67+
}
68+
```
69+
70+
## Internationalization
71+
72+
Localization is an important way to make your application usable by the widest number of people. React Aria includes localized strings for 30+ languages, handles dates and numbers in many calendar and numbering systems, and supports right-to-left interactions (e.g. keyboard navigation).
73+
74+
You’re responsible for ensuring your design supports right-to-left layout, and adapts to different languages (e.g. using appropriate fonts). Modern CSS grid and flex layouts are automatically mirrored depending on the direction, and [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values) can be used to adapt margins, paddings, borders, etc.
75+
76+
### Setting the locale
77+
78+
React Aria automatically detects the user's current language by default. Use the `I18nProvider` component to set the locale to a specific value. You should also set the `lang` and `dir` attributes on the root-most element of your application.
79+
80+
```tsx
81+
import {I18nProvider, useLocale} from 'react-aria-components';
82+
83+
<I18nProvider locale="fr-FR">
84+
<App />
85+
</I18nProvider>
86+
87+
function App() {
88+
let {locale, direction} = useLocale();
89+
90+
return (
91+
<html lang={locale} dir={direction}>
92+
{/* your app here */}
93+
</html>
94+
);
95+
}
96+
```
97+
98+
### Supported locales
99+
100+
<ul style={{columnWidth: 200, paddingLeft: 16, fontFamily: 'adobe-clean-spectrum-vf'}}>
101+
<li>Arabic (United Arab Emirates)</li>
102+
<li>Bulgarian (Bulgaria)</li>
103+
<li>Chinese (Simplified)</li>
104+
<li>Chinese (Traditional)</li>
105+
<li>Croatian (Croatia)</li>
106+
<li>Czech (Czech Republic)</li>
107+
<li>Danish (Denmark)</li>
108+
<li>Dutch (Netherlands)</li>
109+
<li>English (Great Britain)</li>
110+
<li>English (United States)</li>
111+
<li>Estonian (Estonia)</li>
112+
<li>Finnish (Finland)</li>
113+
<li>French (Canada)</li>
114+
<li>French (France)</li>
115+
<li>German (Germany)</li>
116+
<li>Greek (Greece)</li>
117+
<li>Hebrew (Israel)</li>
118+
<li>Hungarian (Hungary)</li>
119+
<li>Italian (Italy)</li>
120+
<li>Japanese (Japan)</li>
121+
<li>Korean (Korea)</li>
122+
<li>Latvian (Latvia)</li>
123+
<li>Lithuanian (Lithuania)</li>
124+
<li>Norwegian (Norway)</li>
125+
<li>Polish (Poland)</li>
126+
<li>Portuguese (Brazil)</li>
127+
<li>Romanian (Romania)</li>
128+
<li>Russian (Russia)</li>
129+
<li>Serbian (Serbia)</li>
130+
<li>Slovakian (Slovakia)</li>
131+
<li>Slovenian (Slovenia)</li>
132+
<li>Spanish (Spain)</li>
133+
<li>Swedish (Sweden)</li>
134+
<li>Turkish (Turkey)</li>
135+
<li>Ukrainian (Ukraine)</li>
136+
</ul>
137+
138+
## Interactions
139+
140+
Modern web apps run on everything from desktops to mobile devices to TVs, with users interacting through mouse, touch, keyboard, and assistive technologies. React Aria normalizes these differences, delivering consistent “press”, “hover”, and “focus” behaviors across all browsers and input types.
141+
142+
React Aria components provide data attributes and render props to style these states:
143+
144+
* `data-pressed` – like the `:active` pseudo class, but removed when dragging off the element.
145+
* `data-hovered` – like `:hover`, but does not apply on touch devices to avoid sticky hover states.
146+
* `data-focus-visible` – like `:focus-visible`, but avoids false positives from programmatic focus.
147+
148+
These states also come with corresponding events such as `onPress` and `onHoverStart`. To use these events in your own custom components, see hooks such as [usePress](usePress.html), [useHover](useHover.html), [useMove](useMove.html), and [useFocusRing](useFocusRing.html).
149+
150+
Read our blog post series to learn more about the intricacies behind these interactions.
151+
152+
* [Building a Button Part 1: Press Events](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html)
153+
* [Building a Button Part 2: Hover Interactions](https://react-spectrum.adobe.com/blog/building-a-button-part-2.html)
154+
* [Building a Button Part 3: Keyboard Focus Behavior](https://react-spectrum.adobe.com/blog/building-a-button-part-3.html)
155+
156+
Higher level interaction patterns such as [selection](selection.html) and [drag and drop](dnd.html) are also built on top of these low level primitives.

‎packages/dev/s2-docs/pages/react-aria/index.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -305,7 +305,7 @@ export const hideFromSearch = true;
305305
<Section className="cyan-gradient-background">
306306
<h2><GradientText>High quality</GradientText> <span className="bg-clip-text bg-linear-to-t from-cyan-600 to-green-600">interactions</span> <GradientText>on all devices.</GradientText></h2>
307307
<p className="m-0">React Aria ensures a great experience for users, no matter their device. All components are optimized for mouse, touch, keyboard, and screen reader interactions, with a meticulous attention to detail that makes your app feel responsive and natural on every platform.</p>
308-
<LearnMoreLink href="interactions.html" className="text-cyan-700 dark:text-cyan-600 hover:bg-cyan-400/[15%]" />
308+
<LearnMoreLink href="concepts.html#interactions" className="text-cyan-700 dark:text-cyan-600 hover:bg-cyan-400/[15%]" />
309309

310310
<PaginatedCarousel className="grid gap-4 md:gap-6 grid-cols-[repeat(4,100%)] md:grid-cols-2 md:grid-rows-2 -mx-8 md:mx-0 px-8 md:px-0 py-4 md:py-0 overflow-auto md:overflow-visible snap-x snap-mandatory no-scrollbar" paginationClassName="md:hidden">
311311
<Card>
@@ -347,7 +347,7 @@ export const hideFromSearch = true;
347347
<Section className="blue-gradient-background">
348348
<h2><span className="bg-clip-text bg-linear-to-b from-sky-500 to-indigo-600">Accessibility</span> <GradientText>that's truly first-class.</GradientText></h2>
349349
<p className="m-0">React Aria is designed with accessibility as a top priority, and battle tested in production applications. All components are built to work across a wide variety of devices and assistive technologies to ensure the best experience possible for all users.</p>
350-
<LearnMoreLink href="accessibility.html" className="text-blue-600 dark:text-blue-500 hover:bg-blue-400/[15%]" />
350+
<LearnMoreLink href="concepts.html#accessibility" className="text-blue-600 dark:text-blue-500 hover:bg-blue-400/[15%]" />
351351

352352
<div className="grid gap-y-6 gap-x-20 md:grid-cols-[min-content_auto] md:grid-flow-col place-items-center">
353353
<div className="w-full max-w-xs md:w-auto md:max-w-none md:row-span-3 md:h-full aspect-1/2 iphone-frame md:order-4">
@@ -376,7 +376,7 @@ export const hideFromSearch = true;
376376
<Section className="orange-gradient-background">
377377
<h2><GradientText>Ready for an</GradientText> <span className="bg-clip-text bg-linear-to-b from-yellow-500 to-orange-600">international</span> <GradientText>audience.</GradientText></h2>
378378
<p className="m-0">React Aria is engineered for internationalization out of the box, including translations in over 30 languages, localized date and number formatting and parsing, support for 13 calendar systems, 5 numbering systems, right-to-left layout, and more.</p>
379-
<LearnMoreLink href="internationalization.html" className="text-orange-700 dark:text-orange-600 hover:bg-orange-400/[15%]" />
379+
<LearnMoreLink href="concepts.html#internationalization" className="text-orange-700 dark:text-orange-600 hover:bg-orange-400/[15%]" />
380380
<I18n />
381381
</Section>
382382

‎packages/dev/s2-docs/pages/react-aria/styling.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ Components often support multiple UI states (e.g. pressed, hovered, selected, et
4747
}
4848
```
4949

50-
In order to ensure high quality interactions across browsers and devices, React Aria Components includes states such as `data-hovered` and `data-pressed` which are similar to CSS pseudo classes such as `:hover` and `:active`, but work consistently between mouse, touch, and keyboard modalities. You can read more about this in our [blog post series](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html) and our [Interactions](https://react-spectrum.adobe.com/react-aria/interactions.html) overview.
50+
React Aria includes states such as `data-hovered` and `data-pressed` which are similar to CSS pseudo classes such as `:hover` and `:active`, but work consistently between mouse, touch, and keyboard modalities. You can read more about this in our [blog post series](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html) and our [Interactions](concepts.html#interactions) overview.
5151

5252
All states supported by each component are listed in the Styling section of their documentation.
5353

0 commit comments

Comments
 (0)