@khanacademy/wonder-blocks-form 2.4.3 → 2.4.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @khanacademy/wonder-blocks-form
 
+## 2.4.4
+
+### Patch Changes
+
+-   Updated dependencies [5f4a4297]
+-   Updated dependencies [2b96fd59]
+    -   @khanacademy/wonder-blocks-core@4.3.2
+    -   @khanacademy/wonder-blocks-clickable@2.2.7
+    -   @khanacademy/wonder-blocks-icon@1.2.28
+    -   @khanacademy/wonder-blocks-layout@1.4.10
+    -   @khanacademy/wonder-blocks-typography@1.1.32
+
 ## 2.4.3
 
 ### Patch Changes

package/dist/index.js

@@ -182,8 +182,22 @@ function _extends() { _extends = Object.assign || function (target) { for (var i
  * ☑️ A nicely styled checkbox for all your checking needs. Can optionally take
  * label and description props.
  *
+ * If used by itself, a checkbox provides two options - checked and unchecked.
+ * A group of checkboxes can be used to allow a user to select multiple values
+ * from a list of options.
+ *
  * If you want a whole group of Checkbox[es] that are related, see the Choice
  * and CheckboxGroup components.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {Checkbox} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [checked, setChecked] = React.useState(false);
+ *
+ * <Checkbox checked={checked} onChange={setChecked} />
+ * ```
  */
 class Checkbox extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
   render() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-form",
-  "version": "2.4.3",
+  "version": "2.4.4",
   "design": "v1",
   "description": "Form components for Wonder Blocks.",
   "main": "dist/index.js",
@@ -16,13 +16,13 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.16.3",
-    "@khanacademy/wonder-blocks-clickable": "^2.2.6",
+    "@khanacademy/wonder-blocks-clickable": "^2.2.7",
     "@khanacademy/wonder-blocks-color": "^1.1.20",
-    "@khanacademy/wonder-blocks-core": "^4.3.1",
-    "@khanacademy/wonder-blocks-icon": "^1.2.27",
-    "@khanacademy/wonder-blocks-layout": "^1.4.9",
+    "@khanacademy/wonder-blocks-core": "^4.3.2",
+    "@khanacademy/wonder-blocks-icon": "^1.2.28",
+    "@khanacademy/wonder-blocks-layout": "^1.4.10",
     "@khanacademy/wonder-blocks-spacing": "^3.0.5",
-    "@khanacademy/wonder-blocks-typography": "^1.1.31"
+    "@khanacademy/wonder-blocks-typography": "^1.1.32"
   },
   "peerDependencies": {
     "aphrodite": "^1.2.5",

package/src/components/__docs__/checkbox-accessibility.stories.mdx

@@ -0,0 +1,147 @@
+import {Meta, Story, Canvas} from "@storybook/addon-docs";
+import {StyleSheet} from "aphrodite";
+
+import Color from "@khanacademy/wonder-blocks-color";
+import {Checkbox} from "@khanacademy/wonder-blocks-form";
+import {LabelSmall} from "@khanacademy/wonder-blocks-typography";
+
+<Meta
+    title="Form/Checkbox/Accessibility"
+    component={Checkbox}
+    parameters={{
+        previewTabs: {
+            canvas: {hidden: true},
+        },
+        viewMode: "docs",
+        chromatic: {
+            // Disables chromatic testing for these stories.
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+export const ErrorTemplate = (args) => {
+    const [checked, setChecked] = React.useState(false);
+    const errorState = !checked;
+    return (
+        <View>
+            <Checkbox
+                checked={checked}
+                onChange={setChecked}
+                error={errorState}
+                aria-describedby={errorState && "error-message"}
+                aria-required={true}
+                {...args}
+            />
+            {errorState && (
+                <LabelSmall style={styles.error} id="error-message">
+                    You must agree to the terms to continue
+                </LabelSmall>
+            )}
+        </View>
+    );
+};
+
+export const DisabledTemplate = (args) => {
+    const [checked, setChecked] = React.useState(false);
+    const errorState = !checked;
+    return (
+        <Checkbox
+            checked={checked}
+            onChange={setChecked}
+            label="Some setting"
+            description="You do not have permission to change this setting"
+            disabled={true}
+        />
+    );
+};
+
+## Accessibility
+
+### ARIA
+
+`Checkbox` can take in all ARIA props defined in Wonder Blocks Core types.
+
+Elements with role `"checkbox"` can have an `aria-checked` property that
+exposes the checked state to assistive technology. The dev does not have
+to worry about this because the Wonder Blocks Checkbox component is an
+`input` element with type `"checkbox"`, as this has built-in semantics and
+does not require ARIA.
+
+The current implementation of `Checkbox` uses `aria-describedby` with the
+label and description that may be passed in as props.
+
+See the Error section for information about `aria-invalid` and
+`aria-required`.
+
+### Error state
+
+The Wonder Blocks `Checkbox` component takes an `error` boolean prop. Setting
+this prop to true will set `aria-invalid` to true, and the color of the
+checkbox to red.
+
+When a form input is invalid, the user should provide a reason for why
+this is.
+
+Generally, it is also suggested this is the validation error message is
+passed to the checkbox's `aria-describedby` prop so assistive tech can
+read it. However, this is not possible with the current implementation of
+the Wonder Blocks Form Checkbox component.
+
+The error state can be used to signal that a required checkbox has not been
+checked. In cases where a checkbox is required, the checkbox component should
+set the `aria-required` prop to true for assistive tech.
+There should also be some sort of visual indication that checking
+the box is required, such as a "Required" label or an asterisk.
+
+<Canvas>
+    <Story
+        name="Error state"
+        args={{
+            label: "I accept the terms and conditions",
+        }}
+    >
+        {ErrorTemplate.bind({})}
+    </Story>
+</Canvas>
+
+### Disabled state
+
+The Wonder Blocks `Checkbox` compoenent takes a `disabled` boolean prop.
+This sets the underlying `input` element's `disabled` prop to `true`.
+This makes is so that the checkbox is not interactable. Also, assistive
+tech will indicated that the checkbox is dimmed.
+
+A user will not be able to navigate to the checkbox with a keyboard.
+Screen reader users will be able to navigate to the checkbox with
+screen reader controls.
+
+It is suggested that if an element is disabled, an explanation as to why
+should to provided somewhere.
+
+<Canvas>
+    <Story name="Disabled state">{DisabledTemplate.bind({})}</Story>
+</Canvas>
+
+### Keyboard Interaction
+
+If a checkbox is not disabled, a user can tab to it using standard
+keyboard navigation. The Space key toggles the checked state of the checkbox.
+
+Note the the Space key triggers the `onChange` function of the
+Wonder Blocks Checkbox component. If the user does not specify an `onChange`
+funciton prop that in turn updates the value of `checked`, neither clicking
+nor the Space key will toggle the Checkbox.
+
+### References
+
+-   [Accessible validation of checkbox and radiobutton groups](https://blog.tenon.io/accessible-validation-of-checkbox-and-radiobutton-groups/)
+-   [HTML: Validating a checkbox with HTML5](https://www.the-art-of-web.com/html/html5-checkbox-required/#example1)
+-   [aria-checked MDN Docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked)
+-   [ARIA: checkbox role MDN Docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role)
+
+export const styles = StyleSheet.create({
+    error: {
+        color: Color.red,
+    },
+});

package/src/components/__docs__/checkbox.stories.js

@@ -0,0 +1,167 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import {LabelMedium, LabelSmall} from "@khanacademy/wonder-blocks-typography";
+import type {StoryComponentType} from "@storybook/react";
+
+import Checkbox from "../checkbox.js";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+
+export default {
+    title: "Form / Checkbox",
+    component: Checkbox,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+};
+
+export const Default: StoryComponentType = (args) => <Checkbox {...args} />;
+
+Default.args = {
+    checked: false,
+    onChange: () => {},
+};
+
+Default.parameters = {
+    chromatic: {
+        // We already have screenshots of another story that covers
+        // this and more cases.
+        disableSnapshot: true,
+    },
+};
+
+export const Controlled: StoryComponentType = () => {
+    const [checked, setChecked] = React.useState(false);
+    return <Checkbox checked={checked} onChange={setChecked} />;
+};
+
+Controlled.parameters = {
+    chromatic: {
+        // Disabling because this doesn't test visuals, its for testing
+        // that `state` works as expected.
+        disableSnapshot: true,
+    },
+    docs: {
+        storyDescription:
+            "Use state to keep track of whether the checkbox is checked or not",
+    },
+};
+
+export const Variants: StoryComponentType = () => (
+    <View style={styles.row}>
+        <Checkbox
+            error={false}
+            checked={false}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            error={false}
+            checked={true}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            error={true}
+            checked={false}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            error={true}
+            checked={true}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            disabled={true}
+            checked={false}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            disabled={true}
+            checked={true}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+    </View>
+);
+
+Variants.parameters = {
+    docs: {
+        storyDescription:
+            "The checkbox has various styles for clickable states. Here are sets of default checkboxes, checkboxes in an error state, and disabled checkboxes.",
+    },
+};
+
+export const WithLabel: StoryComponentType = () => {
+    const [checked, setChecked] = React.useState(false);
+
+    return (
+        <Checkbox
+            label="Receive assignment reminders for Algebra"
+            description="You will receive a reminder 24 hours before each deadline"
+            checked={checked}
+            onChange={setChecked}
+        />
+    );
+};
+
+WithLabel.parameters = {
+    docs: {
+        storyDescription:
+            "The checkbox can have a optional label and description. This allows it to be used as a settings-like item. The user of this component is responsible for keeping track of checked state and providing an onChange callback.",
+    },
+};
+
+export const AdditionalClickTarget: StoryComponentType = () => {
+    const [checked, setChecked] = React.useState(false);
+    const headingText = "Functions";
+    const descriptionText = `A great cook knows how to take basic
+        ingredients and prepare a delicious meal. In this topic, you will
+        become function-chefs! You will learn how to combine functions
+        with arithmetic operations and how to compose functions.`;
+
+    return (
+        <View style={styles.wrapper}>
+            <View style={styles.topic}>
+                <label htmlFor="topic-123">
+                    <LabelMedium>{headingText}</LabelMedium>
+                </label>
+                <LabelSmall>{descriptionText}</LabelSmall>
+            </View>
+            <Checkbox checked={checked} id="topic-123" onChange={setChecked} />
+        </View>
+    );
+};
+
+AdditionalClickTarget.parameters = {
+    docs: {
+        storyDescription:
+            "Sometimes one may wish to use a checkbox in a different context (label may not be right next to the checkbox), like in this example content item. Use a `<label htmlFor={id}>` element where the id matches the `id` prop of the Checkbox. This is for accessibility purposes, and doing this also automatically makes the label a click target for the checkbox.",
+    },
+};
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+    },
+    marginRight: {
+        marginRight: 16,
+    },
+    wrapper: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-evenly",
+    },
+    topic: {
+        maxWidth: 600,
+    },
+});

package/src/components/checkbox.js

@@ -79,8 +79,22 @@ type DefaultProps = {|
  * ☑️ A nicely styled checkbox for all your checking needs. Can optionally take
  * label and description props.
  *
+ * If used by itself, a checkbox provides two options - checked and unchecked.
+ * A group of checkboxes can be used to allow a user to select multiple values
+ * from a list of options.
+ *
  * If you want a whole group of Checkbox[es] that are related, see the Choice
  * and CheckboxGroup components.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {Checkbox} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [checked, setChecked] = React.useState(false);
+ *
+ * <Checkbox checked={checked} onChange={setChecked} />
+ * ```
  */
 export default class Checkbox extends React.Component<ChoiceComponentProps> {
     static defaultProps: DefaultProps = {