diff --git a/packages/@react-spectrum/form/docs/Form.mdx b/packages/@react-spectrum/form/docs/Form.mdx new file mode 100644 index 00000000000..0967c6c938e --- /dev/null +++ b/packages/@react-spectrum/form/docs/Form.mdx @@ -0,0 +1,218 @@ + + +import {Layout} from '@react-spectrum/docs'; +export default Layout; + +import docs from 'docs:@react-spectrum/form'; +import {HeaderInfo, PropTable} from '@react-spectrum/docs'; +import packageData from '../package.json'; + +```jsx import + import {Checkbox} from '@react-spectrum/checkbox'; + import {Form} from '@react-spectrum/form'; + import {Radio, RadioGroup} from '@react-spectrum/radio'; + import {TextField} from '@react-spectrum/textfield'; + ``` + +# Form + +

{docs.exports.Form.description}

+ + + +## Example + +```tsx example +

Login

+
+ + + Remember me + +``` + +## Content + +Form accepts one or more children to render as its form elements. Label alignment, positioning, and other [properties](#visual-options) +are set on the Form itself and propagated to its children to generate a cohesive design. To override these top level Form props on individual children, +set them directly on the child instead. + +```tsx example +

Sign Up

+
+ + + + +``` + +### Accessibility + +As per [W3 Form guidelines](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/form.html), the controls provided to the form should +use native host semantics (`button`, `input`, `select`, `textarea`) whenever possible. React Spectrum components such as Button, TextField, and TextArea +all satisfy this criteria. + +## Labeling + +### Accessibility + +A label should be provided to the Form by adding either the `aria-label` or `aria-labelledby` prop, so that the element will be identified to assistive +technology as a form landmark region to which assistive technology can navigate to. + +```tsx example +

Personal Information

+
+ + + + Dogs + Cats + Dragons + + +``` + + +## Props + + + +## Visual Options + +### Label Position and Label Alignment + +```tsx example +
+ + + Dogs + Cats + + + +
+ + + Dogs + Cats + + + +
+ + + Dogs + Cats + + + +
+ + + Dogs + Cats + + +``` + +### Quiet + +```tsx example +
+ + + +``` + +### Emphasized + +```tsx example +
+ + + Dogs + Cats + + +``` + +### Disabled + +```tsx example +
+ + + Dogs + Cats + + +``` + +### Required and Necessity Indicator + +```tsx example +
+ + + Dogs + Cats + + + +
+ + + Dogs + Cats + + + +
+ + + Dogs + Cats + + +``` + +### Read Only + +```tsx example +
+ + + Dogs + Cats + + +``` + +### Validation State + +```tsx example +
+ + + Dogs + Cats + + + +
+ + + Dogs + Cats + + +``` diff --git a/packages/@react-spectrum/form/src/Form.tsx b/packages/@react-spectrum/form/src/Form.tsx index 8ab6898fa8a..28a93b86213 100644 --- a/packages/@react-spectrum/form/src/Form.tsx +++ b/packages/@react-spectrum/form/src/Form.tsx @@ -79,5 +79,8 @@ function Form(props: SpectrumFormProps, ref: DOMRef) { ); } +/** + * Form provides unified structure, alignment, and styling for a user's form fields. + */ const _Form = React.forwardRef(Form); export {_Form as Form}; diff --git a/packages/@react-types/checkbox/src/index.d.ts b/packages/@react-types/checkbox/src/index.d.ts index d45d8ab73ac..f439876d51d 100644 --- a/packages/@react-types/checkbox/src/index.d.ts +++ b/packages/@react-types/checkbox/src/index.d.ts @@ -32,8 +32,7 @@ export interface CheckboxProps extends CheckboxBase { export interface SpectrumCheckboxProps extends CheckboxProps, DOMProps, StyleProps { /** - * By default, checkboxes are not emphasized (gray). - * This prop sets the emphasized style (blue) which provides visual prominence. + * This prop sets the emphasized style which provides visual prominence. */ isEmphasized?: boolean } diff --git a/packages/@react-types/form/src/index.d.ts b/packages/@react-types/form/src/index.d.ts index 85b0f240bb7..2b27fe3be54 100644 --- a/packages/@react-types/form/src/index.d.ts +++ b/packages/@react-types/form/src/index.d.ts @@ -14,11 +14,21 @@ import {DOMProps, SpectrumLabelableProps, StyleProps, ValidationState} from '@re import {ReactElement} from 'react'; export interface SpectrumFormProps extends DOMProps, StyleProps, SpectrumLabelableProps { + /** The contents of the Form. */ children: ReactElement | ReactElement[], + /** Whether the Form elements are displayed with their quiet style. */ isQuiet?: boolean, + /** Whether the Form elements are rendered with their emphasized style. */ isEmphasized?: boolean, + /** Whether the Form elements are disabled. */ isDisabled?: boolean, + /** Whether user input is required on each of the Form elements before Form submission. */ isRequired?: boolean, + /** Whether the Form elements can be selected but not changed by the user. */ isReadOnly?: boolean, + /** + * Whether the Form elements should display their "valid" or "invalid" visual styling. + * @default "valid" + */ validationState?: ValidationState } diff --git a/packages/@react-types/switch/src/index.d.ts b/packages/@react-types/switch/src/index.d.ts index 2f408910226..b1679ae556c 100644 --- a/packages/@react-types/switch/src/index.d.ts +++ b/packages/@react-types/switch/src/index.d.ts @@ -16,8 +16,7 @@ import {DOMProps, StyleProps} from '@react-types/shared'; export type SwitchProps = CheckboxBase; export interface SpectrumSwitchProps extends SwitchProps, DOMProps, StyleProps { /** - * By default, switches are not emphasized (gray). - * This prop sets the emphasized style (blue) which provides visual prominence. + * This prop sets the emphasized style which provides visual prominence. * @default "false" */ isEmphasized?: boolean