diff --git a/packages/dev/s2-docs/pages/react-aria/DropTarget.tsx b/packages/dev/s2-docs/pages/react-aria/DropTarget.tsx index 2f4cb2e69ea..826392568d0 100644 --- a/packages/dev/s2-docs/pages/react-aria/DropTarget.tsx +++ b/packages/dev/s2-docs/pages/react-aria/DropTarget.tsx @@ -1,6 +1,6 @@ "use client"; -import React, {JSX} from 'react'; +import React, {JSX, ReactNode} from 'react'; import type {TextDropItem} from '@react-aria/dnd'; import {useDrop} from '@react-aria/dnd'; @@ -18,7 +18,7 @@ export function DropTarget() { let items = await Promise.all( (e.items as TextDropItem[]) .filter(item => item.kind === 'text' && (item.types.has('text/plain') || item.types.has('my-app-custom-type'))) - .map(async item => { + .map(async (item: TextDropItem) => { if (item.types.has('my-app-custom-type')) { return JSON.parse(await item.getText('my-app-custom-type')); } else { @@ -30,16 +30,16 @@ export function DropTarget() { } }); - let message: JSX.Element[] = [
{`Drop here`}
]; + let message: ReactNode =
'Drop here'
; if (dropped) { message = dropped.map((d, index) => { - let m = d.message; + let m: ReactNode = d.message; if (d.style === 'bold') { - message = [{m}]; + m = {m}; } else if (d.style === 'italic') { - message = [{m}]; + m = {m}; } - return
{message}
; + return
{m}
; }); } diff --git a/packages/dev/s2-docs/pages/react-aria/FocusRing.mdx b/packages/dev/s2-docs/pages/react-aria/FocusRing.mdx index 52d8a4aac79..2cc6456bcf8 100644 --- a/packages/dev/s2-docs/pages/react-aria/FocusRing.mdx +++ b/packages/dev/s2-docs/pages/react-aria/FocusRing.mdx @@ -13,7 +13,7 @@ import {GroupedPropTable} from '../../src/PropTable'; import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/focus'; -export const section = 'Focus'; +export const section = 'Interactions'; # FocusRing @@ -29,10 +29,6 @@ switching in from a different tab, we show the focus ring. If CSS classes are not being used for styling, see [useFocusRing](useFocusRing.html) for a hooks version. -## Props - - - ## Example This example shows how to use `` to apply a CSS class when keyboard focus is on a button. @@ -46,3 +42,7 @@ import './FocusRingExample.css'; ``` + +## API + + \ No newline at end of file diff --git a/packages/dev/s2-docs/pages/react-aria/FocusScope.mdx b/packages/dev/s2-docs/pages/react-aria/FocusScope.mdx index bf41919a10d..dd7a7e6b82a 100644 --- a/packages/dev/s2-docs/pages/react-aria/FocusScope.mdx +++ b/packages/dev/s2-docs/pages/react-aria/FocusScope.mdx @@ -13,7 +13,7 @@ import {GroupedPropTable} from '../../src/PropTable'; import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/focus'; -export const section = 'Focus'; +export const section = 'Interactions'; # FocusScope @@ -34,17 +34,6 @@ in combination with a FocusScope to programmatically move focus within the scope arrow key navigation could be implemented by handling keyboard events and using a focus manager to move focus to the next and previous elements. -## Props - - - -## FocusManager Interface - -To get a focus manager, call the hook -from a component within the FocusScope. A focus manager supports the following methods: - - - ## Example A basic example of a focus scope that contains focus within it is below. Clicking the "Open" @@ -128,3 +117,16 @@ function ToolbarButton(props) { Paste ``` + +## API + +### Props + + + +### FocusManager Interface + +To get a focus manager, call the hook +from a component within the FocusScope. A focus manager supports the following methods: + + \ No newline at end of file diff --git a/packages/dev/s2-docs/pages/react-aria/I18nProvider.mdx b/packages/dev/s2-docs/pages/react-aria/I18nProvider.mdx index 9bdc658f95d..15fb260507d 100644 --- a/packages/dev/s2-docs/pages/react-aria/I18nProvider.mdx +++ b/packages/dev/s2-docs/pages/react-aria/I18nProvider.mdx @@ -12,7 +12,7 @@ export default Layout; import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/i18n'; -export const section = 'Internationalization'; +export const section = 'Utilities'; export const description = 'Implementing collections in React Aria'; @@ -25,10 +25,6 @@ with a locale defined by your application (e.g. application setting). This shoul your entire application in the provider, which will be cause all child elements to receive the new locale information via [useLocale](useLocale.html). -## Props - - - ## Example ```tsx @@ -38,3 +34,7 @@ import {I18nProvider} from '@react-aria/i18n'; ``` + +## Props + + diff --git a/packages/dev/s2-docs/pages/react-aria/PortalProvider.mdx b/packages/dev/s2-docs/pages/react-aria/PortalProvider.mdx index c161d7d7b79..55838cf9965 100644 --- a/packages/dev/s2-docs/pages/react-aria/PortalProvider.mdx +++ b/packages/dev/s2-docs/pages/react-aria/PortalProvider.mdx @@ -12,7 +12,7 @@ export default Layout; import docs from 'docs:@react-aria/overlays'; import {FunctionAPI} from '../../src/FunctionAPI'; -export const section = 'Server Side Rendering'; +export const section = 'Utilities'; # PortalProvider @@ -32,10 +32,6 @@ outside of any possible overflow or stacking contexts. We envision `UNSAFE_Porta elements into a single container at the root of the app or to control the order of children of the `body` element, but you may have use cases that need to do otherwise. -## Props - - - ## Example The example below shows how you can use `UNSAFE_PortalProvider` to portal your Toasts to an arbitrary container. Note that @@ -169,3 +165,8 @@ function MyOverlay(props) { return ReactDOM.createPortal(children, getContainer()); } ``` + +## Props + + + diff --git a/packages/dev/s2-docs/pages/react-aria/SSRProvider.mdx b/packages/dev/s2-docs/pages/react-aria/SSRProvider.mdx index 37f23f1bbbe..262f22460b7 100644 --- a/packages/dev/s2-docs/pages/react-aria/SSRProvider.mdx +++ b/packages/dev/s2-docs/pages/react-aria/SSRProvider.mdx @@ -11,7 +11,7 @@ import {Layout} from '../../src/Layout'; export default Layout; import docs from 'docs:@react-aria/ssr'; -export const section = 'Server Side Rendering'; +export const section = 'Utilities'; export const description = 'Implementing collections in React Aria'; # SSRProvider @@ -26,10 +26,6 @@ See the [server side rendering](ssr.html) docs for more information. **Note**: if you're using React 18 or newer, `SSRProvider` is not necessary and can be removed from your app. React Aria uses the [React.useId](https://react.dev/reference/react/useId) hook internally when using React 18, which ensures ids are consistent. -## Props - - - ## Example ```tsx @@ -39,3 +35,7 @@ import {SSRProvider} from '@react-aria/ssr'; ``` + +## Props + + diff --git a/packages/dev/s2-docs/pages/react-aria/VisuallyHidden.mdx b/packages/dev/s2-docs/pages/react-aria/VisuallyHidden.mdx index 14fb52ee5fe..e99bf515747 100644 --- a/packages/dev/s2-docs/pages/react-aria/VisuallyHidden.mdx +++ b/packages/dev/s2-docs/pages/react-aria/VisuallyHidden.mdx @@ -18,25 +18,20 @@ export const section = 'Utilities'; {docs.exports.VisuallyHidden.description} -## Introduction - -`VisuallyHidden` is a utility component that can be used to hide its children visually, -while keeping them visible to screen readers and other assistive technology. This would -typically be used when you want to take advantage of the behavior and semantics of a -native element like a checkbox or radio button, but replace it with a custom styled -element visually. - -## Props - - +## Gotchas -{/* not implemented yet */} -{/* ## Example +VisuallyHidden is positioned absolutely, so it needs a positioned ancestor. Otherwise, it will be positioned relative to the nearest positioned ancestor, which may be the body, causing undesired scroll bars to appear. -See [useRadioGroup](useRadioGroup.html#styling) and [useCheckbox](useCheckbox.html#styling) -for examples of using `VisuallyHidden` to hide native form elements visually. */} +```tsx + +``` -## Hook +## Hook In order to allow additional rendering flexibility, the `useVisuallyHidden` hook can be used in custom components instead of the `VisuallyHidden` component. It supports the same @@ -44,6 +39,8 @@ options as the component, and returns props to spread onto the element that shou +### Example + ```tsx import {useVisuallyHidden} from '@react-aria/visually-hidden'; @@ -52,16 +49,12 @@ let {visuallyHiddenProps} = useVisuallyHidden();
I am hidden
``` -## Gotchas +## API -VisuallyHidden is positioned absolutely, so it needs a positioned ancestor. Otherwise, it will be positioned relative to the nearest positioned ancestor, which may be the body, causing undesired scroll bars to appear. + -```tsx - -``` +{/* not implemented yet */} +{/* ## Example +See [useRadioGroup](useRadioGroup.html#styling) and [useCheckbox](useCheckbox.html#styling) +for examples of using `VisuallyHidden` to hide native form elements visually. */} diff --git a/packages/dev/s2-docs/pages/react-aria/mergeProps.mdx b/packages/dev/s2-docs/pages/react-aria/mergeProps.mdx index fee98fa10a5..5bd8bf6b915 100644 --- a/packages/dev/s2-docs/pages/react-aria/mergeProps.mdx +++ b/packages/dev/s2-docs/pages/react-aria/mergeProps.mdx @@ -18,16 +18,11 @@ export const section = 'Utilities'; {docs.exports.mergeProps.description} -## API - - - ## Introduction `mergeProps` is a utility function that combines multiple props objects together in a smart way. This can be useful when you need to combine the results of multiple react-aria hooks onto a single -element. For example, both hooks may return the same event handlers, class names, or ids, and only -one of these can be applied. `mergeProps` handles combining these props together so that multiple +element. `mergeProps` handles combining these props together so that multiple event handlers will be chained, multiple classes will be combined, and ids will be deduplicated. For all other props, the last prop object overrides all previous ones. @@ -68,3 +63,7 @@ let merged = { } }; ``` + +## API + + diff --git a/packages/dev/s2-docs/pages/react-aria/useClipboard.mdx b/packages/dev/s2-docs/pages/react-aria/useClipboard.mdx index e044de4e0b1..bf6d6b744da 100644 --- a/packages/dev/s2-docs/pages/react-aria/useClipboard.mdx +++ b/packages/dev/s2-docs/pages/react-aria/useClipboard.mdx @@ -12,16 +12,12 @@ export default Layout; import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/dnd'; import sharedDocs from 'docs:@react-types/shared/src/dnd.d.ts'; -export const section = 'Drag and Drop'; +export const section = 'Interactions'; # useClipboard {docs.exports.useClipboard.description} -## API - - - ## Introduction Copy and paste is a common way to transfer data between locations, either within or between apps. Browsers support copy and paste of selected text content by default, but rich objects with custom data can also be copied and pasted using the [clipboard events](https://developer.mozilla.org/en-US/docs/Web/API/ClipboardEvent) API. For example, an app could support copying and pasting a selected card representing a rich object to a new location, or allow a user to paste files from their device to upload them. This can provide a keyboard accessible alternative to drag and drop. @@ -414,4 +410,8 @@ function Pasteable() { -``` \ No newline at end of file +``` + +## API + + \ No newline at end of file diff --git a/packages/dev/s2-docs/pages/react-aria/useCollator.mdx b/packages/dev/s2-docs/pages/react-aria/useCollator.mdx index 45d63d6cfd1..eae2aa7f72f 100644 --- a/packages/dev/s2-docs/pages/react-aria/useCollator.mdx +++ b/packages/dev/s2-docs/pages/react-aria/useCollator.mdx @@ -12,7 +12,7 @@ export default Layout; import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/i18n'; -export const section = 'Internationalization'; +export const section = 'Utilities'; export const description = 'Implementing collections in React Aria'; @@ -26,10 +26,6 @@ updating when the locale changes, and caching of collators for performance. See [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator) docs for information. -## API - - - ## Example This example includes two textfields and compares the values of the two fields using a collator according to the current locale. @@ -72,3 +68,7 @@ function Example() { ); } ``` + +## API + + \ No newline at end of file diff --git a/packages/dev/s2-docs/pages/react-aria/useDateFormatter.mdx b/packages/dev/s2-docs/pages/react-aria/useDateFormatter.mdx index 2f77d300aed..1fc88a16a6d 100644 --- a/packages/dev/s2-docs/pages/react-aria/useDateFormatter.mdx +++ b/packages/dev/s2-docs/pages/react-aria/useDateFormatter.mdx @@ -12,7 +12,7 @@ export default Layout; import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/i18n'; -export const section = 'Internationalization'; +export const section = 'Utilities'; export const description = 'Implementing collections in React Aria'; # useDateFormatter @@ -25,10 +25,6 @@ updating when the locale changes, and caching of date formatters for performance [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) docs for information on formatting options. -## API - - - ## Example This example displays the current date for two locales: USA, and Russia. Two instances of the `CurrentDate` component are rendered, @@ -55,3 +51,7 @@ function CurrentDate() { ``` + +## API + + diff --git a/packages/dev/s2-docs/pages/react-aria/useDrag.mdx b/packages/dev/s2-docs/pages/react-aria/useDrag.mdx index 7f028799fa3..a97cc75df20 100644 --- a/packages/dev/s2-docs/pages/react-aria/useDrag.mdx +++ b/packages/dev/s2-docs/pages/react-aria/useDrag.mdx @@ -13,20 +13,14 @@ import {GroupedPropTable} from '../../src/PropTable'; import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/dnd'; import sharedDocs from 'docs:@react-types/shared/src/dnd.d.ts'; -export const section = 'Drag and Drop'; +export const section = 'Interactions'; # useDrag {docs.exports.useDrag.description} -## API - - - ## Introduction -Drag and drop is a common UI interaction that allows users to transfer data between two locations by directly moving a visual representation on screen. It is a flexible, efficient, and intuitive way for users to perform a variety of tasks, and is widely supported across both desktop and mobile operating systems. - React Aria supports traditional mouse and touch based drag and drop, but also implements keyboard and screen reader friendly interactions. Users can press Enter on a draggable element to enter drag and drop mode. Then, they can press Tab to navigate between drop targets, and Enter to drop or Escape to cancel. Touch screen reader users can also drag by double tapping to activate drag and drop mode, swiping between drop targets, and double tapping again to drop. See the [drag and drop introduction](dnd.html) to learn more. @@ -40,6 +34,7 @@ This example shows how to make a simple draggable element that provides data as import {useDrag} from '@react-aria/dnd'; import {DropTarget} from './DropTarget.tsx'; import './useDragExample.css'; +import 'vanilla-starter/theme.css'; function Draggable() { let {dragProps, isDragging} = useDrag({ @@ -155,9 +150,11 @@ A Option or Alt to switch from move to copy. The `onDragEnd` event allows the drag source to respond when a drag that it initiated ends, either because it was dropped or because it was canceled by the user. The `dropOperation` property of the event object indicates the operation that was performed. For example, when data is moved, the UI could be updated to reflect this change by removing the original dragged element. This example removes the draggable element from the UI when a move operation is completed. Try holding the Option or Alt keys to change the operation to copy, and see how the behavior changes. + ```tsx render "use client" import React from 'react'; @@ -304,4 +301,8 @@ function Draggable() { ); } -``` \ No newline at end of file +``` + +## API + + diff --git a/packages/dev/s2-docs/pages/react-aria/useDrop.mdx b/packages/dev/s2-docs/pages/react-aria/useDrop.mdx index 1f7e1c93c53..3d35c620520 100644 --- a/packages/dev/s2-docs/pages/react-aria/useDrop.mdx +++ b/packages/dev/s2-docs/pages/react-aria/useDrop.mdx @@ -14,20 +14,14 @@ import {FunctionAPI} from '../../src/FunctionAPI'; import docs from 'docs:@react-aria/dnd'; import sharedDocs from 'docs:@react-types/shared/src/dnd.d.ts'; import typesDocs from 'docs:@react-types/shared/src/events.d.ts'; -export const section = 'Drag and Drop'; +export const section = 'Interactions'; # useDrop {docs.exports.useDrop.description} -## API - - - ## Introduction -Drag and drop is a common UI interaction that allows users to transfer data between two locations by directly moving a visual representation on screen. It is a flexible, efficient, and intuitive way for users to perform a variety of tasks, and is widely supported across both desktop and mobile operating systems. - React Aria supports traditional mouse and touch based drag and drop, but also implements keyboard and screen reader friendly interactions. Users can press Enter on a draggable element to enter drag and drop mode. Then, they can press Tab to navigate between drop targets, and Enter to drop or Escape to cancel. Touch screen reader users can also drag by double tapping to activate drag and drop mode, swiping between drop targets, and double tapping again to drop. See the [drag and drop introduction](dnd.html) to learn more. @@ -43,6 +37,7 @@ import type {TextDropItem} from '@react-aria/dnd'; import {useDrop} from '@react-aria/dnd'; import {Draggable} from './Draggable.tsx'; import './useDragExample.css'; +import 'vanilla-starter/theme.css'; function DropTarget() { let [dropped, setDropped] = React.useState(null); @@ -78,6 +73,7 @@ function DropTarget() { * `directory` – references the contents of a directory ### Text A represents textual data in one or more different formats. These may be either standard [mime types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) or custom app-specific formats. Representing data in multiple formats allows drop targets both within and outside an application to choose data in a format that they understand. For example, a complex object may be serialized in a custom format for use within an application, with fallbacks in plain text and/or rich HTML that can be used when a user drops data from an external application. + The example below finds the first available item that includes a custom app-specific type. The same draggable component as used in the above example is used here, but rather than displaying the plain text representation, the custom format is used instead. ```tsx render @@ -118,8 +114,8 @@ function DropTarget() { ``` ### Files A references a file on the user's device. It includes the name and mime type of the file, and methods to read the contents as plain text, or retrieve a native [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object which can be attached to form data for uploading. -This example accepts JPEG and PNG image files, and renders them by creating a local [object URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL). +This example accepts JPEG and PNG image files, and renders them by creating a local [object URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL). ```tsx render 'use client'; import React from 'react'; @@ -198,7 +194,7 @@ function DropTarget() { ); } return ( -
+
{contents}
); @@ -212,6 +208,7 @@ A * `copy` – indicates that the dragged data will be copied to the target destination. * `link` – indicates that there will be a relationship established between the source and target locations. * `cancel` – indicates that the drag and drop operation will be canceled, resulting in no changes made to the source or target. + Many operating systems display these in the form of a cursor change, e.g. a plus sign to indicate a copy operation. The user may also be able to use a modifier key to choose which drop operation to perform, such as Option or Alt to switch from move to copy. The drag source can specify which drop operations are allowed for the dragged data (see the [useDrag docs](useDrag.html) for how to customize this). By default, the first allowed operation is allowed by drop targets, meaning that the drop target accepts data of any type and operation. @@ -309,7 +306,7 @@ function DropTarget() { onDrop: onEvent }); return ( -
    +
      {events.map((e, i) =>
    • {e}
      • )}
    ); @@ -357,4 +354,8 @@ function DropTarget() {
-``` \ No newline at end of file +``` + +## API + + \ No newline at end of file diff --git a/packages/dev/s2-docs/pages/react-aria/useField.mdx b/packages/dev/s2-docs/pages/react-aria/useField.mdx index 41125ea5648..417e9af4928 100644 --- a/packages/dev/s2-docs/pages/react-aria/useField.mdx +++ b/packages/dev/s2-docs/pages/react-aria/useField.mdx @@ -18,11 +18,7 @@ export const section = 'Utilities'; {docs.exports.useField.description} -## API - - - -## Example +## Introduction The `useField` hook associates a form control with a label, and an optional description and/or error message. This is useful for providing context about how users should fill in a field, or a validation message. `useField` takes care of creating ids for each element and associating them with the correct ARIA attributes (`aria-labelledby` and `aria-describedby`). @@ -31,6 +27,8 @@ By default, `useField` assumes that the label is a native HTML `