Checkbox Documentation (#180)

* js docs rough draft

* saving progress

* tested against website branch

* adhere to wave 1 of review comments

* adhere to wave 2 of review comments

* more updates

* a few more updates

* improvements

* forgot yarn install

* revert

Author: MidnightCoder06

packages/@react-spectrum/checkbox/docs/Checkbox.mdx

@@ -0,0 +1,115 @@
+import {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-spectrum/checkbox';
+import packageData from '../package.json';
+import {HeaderInfo, PropTable} from '@react-spectrum/docs';
+
+```jsx import
+ import {Checkbox} from '@react-spectrum/checkbox';
+ ```
+
+# Checkbox
+
+<p>{docs.exports.Checkbox.description}</p>
+
+<HeaderInfo
+ packageData={packageData}
+ componentNames={['Checkbox']}
+ sourceData={[
+ {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/checkbox/'}
+ ]} />
+
+## Example
+
+```tsx example
+<Checkbox>Checkbox Label</Checkbox>
+```
+
+## Content
+
+Checkboxes accept children, which are rendered as the label.
+
+### Accessibility
+
+In certain cases a visible label isn't needed. For example, a checkbox used to select a table row.
+If a visible label isn't specified, an `aria-label` must be provided to the Checkbox for accessibility.
+If the field is labeled by a separate element, an `aria-labelledby` prop must be provided using the id of the labeling element instead.
+
+### Internationalization
+
+To internationalize a Checkbox, a localized label should be passed to the `children` or `aria-label` prop.
+
+## Value
+
+Checkboxes are not selected by default. The `defaultSelected` prop can be used to set the default state (uncontrolled).
+Alternatively, the `isSelected` prop can be used to make the selected state controlled.
+
+```tsx example
+<Checkbox defaultSelected>Uncontrolled</Checkbox>
+<Checkbox isSelected>Controlled</Checkbox>
+```
+
+### Indeterminate
+[View guidelines](https://spectrum.adobe.com/page/checkbox/#Mixed-value)
+
+A Checkbox can be in an indeterminate state, controlled using the `isIndeterminate` prop.
+This overrides the selection state, whether controlled or uncontrolled.
+The Checkbox will remain in an indeterminate state until the `isIndeterminate` prop is set to false, regardless of user interaction.
+
+```tsx example
+<Checkbox isIndeterminate>Checkbox Label</Checkbox>
+```
+
+## Events
+
+Checkboxes accept a user defined `onChange` prop, triggered whenever the Checkbox is clicked.
+The example below uses `onChange` to alert the user to changes in the checkbox's state.
+
+```tsx example
+function Example() {
+  let [selected, setSelection] = React.useState('false');
+
+  let toggle = (value) => {
+    value ? setSelection('true') : setSelection('false');
+  }
+
+  return (
+    <div>
+      <div> The Checkbox is checked: {selected} </div>
+      <Checkbox onChange={toggle}>
+        Checkbox Label
+      </Checkbox>
+    </div>
+  );
+ }
+```
+
+## Validation
+
+Checkboxes can display a validation state to communicate to the user if the current value is invalid.
+Implement your own validation logic in your app and pass `"invalid"` to the Checkbox via the `validationState` prop.
+
+```tsx example
+<Checkbox validationState="invalid">Checkbox Label</Checkbox>
+```
+
+## Props
+
+<PropTable component={docs.exports.Checkbox} links={docs.links} />
+
+## Visual Options
+
+### isDisabled
+[View guidelines](https://spectrum.adobe.com/page/checkbox/#Disabled)
+
+```tsx example
+<Checkbox isDisabled>Checkbox Label</Checkbox>
+```
+
+### isEmphasized
+[View guidelines](https://spectrum.adobe.com/page/checkbox/#Emphasized-or-not?)
+
+```tsx example
+<Checkbox isEmphasized>Checkbox Label</Checkbox>
+```

packages/@react-spectrum/checkbox/src/Checkbox.tsx

@@ -69,6 +69,9 @@ function Checkbox(props: SpectrumCheckboxProps, ref: FocusableRef<HTMLLabelEleme
     </label>
   );
 }
-
+/**
+ * Checkboxes allow users to select multiple items from a list of individual items,
+ * or to mark one individual item as selected.
+ */
 let _Checkbox = forwardRef(Checkbox);
 export {_Checkbox as Checkbox};

packages/@react-types/checkbox/src/index.d.ts

@@ -3,7 +3,6 @@ import {ReactNode} from 'react';
 
 export interface CheckboxBase extends InputBase {
   children?: ReactNode, // pass in children to render label
-
   defaultSelected?: boolean,
   isSelected?: boolean,
   onChange?: (isSelected: boolean) => void,
@@ -12,9 +11,17 @@ export interface CheckboxBase extends InputBase {
 }
 
 export interface CheckboxProps extends CheckboxBase {
+  /**
+   * Indeterminism is presentational, when a checkbox is indeterminate, it overrides the selection state.
+   * The indeterminate visual representation remains even after subsequent clicks .
+   */
   isIndeterminate?: boolean
 }
 
 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.
+   */
   isEmphasized?: boolean
 }