@khanacademy/wonder-blocks-form 2.4.3 → 2.4.6

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @khanacademy/wonder-blocks-form
 
+## 2.4.6
+
+### Patch Changes
+
+-   Updated dependencies [ee6fc773]
+    -   @khanacademy/wonder-blocks-clickable@2.3.0
+
+## 2.4.5
+
+### Patch Changes
+
+-   Updated dependencies [83486dba]
+    -   @khanacademy/wonder-blocks-icon@1.2.29
+
+## 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() {
@@ -450,6 +464,24 @@ const styles = aphrodite__WEBPACK_IMPORTED_MODULE_1__["StyleSheet"].create({
     boxShadow: `0px 0px 0px 1px ${_khanacademy_wonder_blocks_color__WEBPACK_IMPORTED_MODULE_2___default.a.red}, 0px 0px 0px 2px ${_khanacademy_wonder_blocks_color__WEBPACK_IMPORTED_MODULE_2___default.a.white}`
   }
 });
+
+/**
+ * A TextField is an element used to accept a single line of text from the user.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {TextField} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [value, setValue] = React.useState("");
+ *
+ * <TextField
+ *     id="some-unique-text-field-id"
+ *     value={value}
+ *     onChange={setValue}
+ * />
+ * ```
+ */
 const TextField = /*#__PURE__*/react__WEBPACK_IMPORTED_MODULE_0__["forwardRef"]((props, ref) => /*#__PURE__*/react__WEBPACK_IMPORTED_MODULE_0__["createElement"](TextFieldInternal, _extends({}, props, {
   forwardedRef: ref
 })));
@@ -652,6 +684,63 @@ const styles = aphrodite__WEBPACK_IMPORTED_MODULE_1__["StyleSheet"].create({
  *
  * If you wish to use just a single field, use Checkbox or Radio with the
  * optional label and description props.
+ *
+ * ### Checkbox Usage
+ *
+ * ```jsx
+ * import {Choice, CheckboxGroup} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [selectedValues, setSelectedValues] = React.useState([]);
+ *
+ * // Checkbox usage
+ * <CheckboxGroup
+ *     label="some-label"
+ *     description="some-description"
+ *     groupName="some-group-name"
+ *     onChange={setSelectedValues}
+ *     selectedValues={selectedValues}
+ * />
+ *     // Add as many choices as necessary
+ *     <Choice
+ *        label="Choice 1"
+ *        value="some-choice-value"
+ *        description="Some choice description."
+ *     />
+ *     <Choice
+ *        label="Choice 2"
+ *        value="some-choice-value-2"
+ *        description="Some choice description."
+ *     />
+ * </CheckboxGroup>
+ * ```
+ *
+ * ### Radio Usage
+ *
+ * ```jsx
+ * import {Choice, RadioGroup} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [selectedValue, setSelectedValue] = React.useState("");
+ *
+ * <RadioGroup
+ *     label="some-label"
+ *     description="some-description"
+ *     groupName="some-group-name"
+ *     onChange={setSelectedValue}>
+ *     selectedValues={selectedValue}
+ * />
+ *     // Add as many choices as necessary
+ *     <Choice
+ *        label="Choice 1"
+ *        value="some-choice-value"
+ *        description="Some choice description."
+ *     />
+ *     <Choice
+ *        label="Choice 2"
+ *        value="some-choice-value-2"
+ *        description="Some choice description."
+ *     />
+ * </RadioGroup>
+ * ```
  */
 class Choice extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
   getChoiceComponent(variant) {
@@ -711,6 +800,33 @@ const StyledLegend = Object(_khanacademy_wonder_blocks_core__WEBPACK_IMPORTED_MO
  * many props for its children Choice components. The Choice component is
  * exposed for the user to apply custom styles or to indicate which choices are
  * disabled.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {Choice, CheckboxGroup} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [selectedValues, setSelectedValues] = React.useState([]);
+ *
+ * <CheckboxGroup
+ *     label="some-label"
+ *     description="some-description"
+ *     groupName="some-group-name"
+ *     onChange={setSelectedValues}
+ *     selectedValues={selectedValues}
+ * />
+ *     // Add as many choices as necessary
+ *     <Choice
+ *        label="Choice 1"
+ *        value="some-choice-value"
+ *     />
+ *     <Choice
+ *        label="Choice 2"
+ *        value="some-choice-value-2"
+ *        description="Some choice description."
+ *     />
+ * </CheckboxGroup>
+ * ```
  */
 
 class CheckboxGroup extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
@@ -806,6 +922,33 @@ const StyledLegend = Object(_khanacademy_wonder_blocks_core__WEBPACK_IMPORTED_MO
  * indicate which choices are disabled. The use of the groupName prop is
  * important to maintain expected keyboard navigation behavior for
  * accessibility.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {Choice, RadioGroup} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [selectedValue, setSelectedValue] = React.useState([]);
+ *
+ * <RadioGroup
+ *     label="some-label"
+ *     description="some-description"
+ *     groupName="some-group-name"
+ *     onChange={setSelectedValue}
+ *     selectedValue={selectedValue}
+ * />
+ *     // Add as many choices as necessary
+ *     <Choice
+ *        label="Choice 1"
+ *        value="some-choice-value"
+ *     />
+ *     <Choice
+ *        label="Choice 2"
+ *        value="some-choice-value-2"
+ *        description="Some choice description."
+ *     />
+ * </RadioGroup>
+ * ```
  */
 
 class RadioGroup extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
@@ -995,6 +1138,27 @@ LabeledTextFieldInternal.defaultProps = {
   disabled: false,
   light: false
 };
+
+/**
+ * A LabeledTextField is an element used to accept a single line of text
+ * from the user paired with a label, description, and error field elements.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {LabeledTextField} from "@khanacademy/wonder-blocks-form";
+ *
+ * const [value, setValue] = React.useState("");
+ *
+ * <LabeledTextField
+ *     label="Label"
+ *     description="Hello, this is the description for this field"
+ *     placeholder="Placeholder"
+ *     value={value}
+ *     onChange={setValue}
+ * />
+ * ```
+ */
 const LabeledTextField = /*#__PURE__*/react__WEBPACK_IMPORTED_MODULE_0__["forwardRef"]((props, ref) => /*#__PURE__*/react__WEBPACK_IMPORTED_MODULE_0__["createElement"](LabeledTextFieldInternal, _extends({}, props, {
   forwardedRef: ref
 })));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-form",
-  "version": "2.4.3",
+  "version": "2.4.6",
   "design": "v1",
   "description": "Form components for Wonder Blocks.",
   "main": "dist/index.js",
@@ -15,14 +15,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@babel/runtime": "^7.16.3",
-    "@khanacademy/wonder-blocks-clickable": "^2.2.6",
+    "@babel/runtime": "^7.18.6",
+    "@khanacademy/wonder-blocks-clickable": "^2.3.0",
     "@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.29",
+    "@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-group.stories.js

@@ -0,0 +1,266 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import {Choice, CheckboxGroup} from "@khanacademy/wonder-blocks-form";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {LabelLarge, LabelXSmall} from "@khanacademy/wonder-blocks-typography";
+
+import type {StoryComponentType} from "@storybook/react";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+
+export default {
+    title: "Form / CheckboxGroup",
+    component: CheckboxGroup,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+};
+
+export const Default: StoryComponentType = (args) => {
+    return (
+        <CheckboxGroup {...args}>
+            <Choice label="Pepperoni" value="pepperoni" />
+            <Choice
+                label="Sausage"
+                value="sausage"
+                description="Imported from Italy"
+            />
+            <Choice label="Extra cheese" value="cheese" />
+            <Choice label="Green pepper" value="pepper" />
+            <Choice label="Mushroom" value="mushroom" />
+        </CheckboxGroup>
+    );
+};
+
+Default.args = {
+    // Required
+    groupName: "toppings",
+    selectedValues: ["pepperoni", "sausage"],
+    onChange: () => {},
+    // Optional
+    label: "Pizza toppings",
+    description: "Choose as many toppings as you would like.",
+};
+
+export const Basic: StoryComponentType = () => {
+    const [selectedValues, setSelectedValues] = React.useState([]);
+
+    return (
+        <CheckboxGroup
+            groupName="toppings"
+            onChange={setSelectedValues}
+            selectedValues={selectedValues}
+        >
+            <Choice label="Pepperoni" value="pepperoni" />
+            <Choice
+                label="Sausage"
+                value="sausage"
+                description="Imported from Italy"
+            />
+            <Choice label="Extra cheese" value="cheese" />
+            <Choice label="Green pepper" value="pepper" />
+            <Choice label="Mushroom" value="mushroom" />
+        </CheckboxGroup>
+    );
+};
+
+Basic.parameters = {
+    docs: {
+        storyDescription: `This is a basic example of a checkbox group.
+        The Wonder Blocks \`CheckboxGroup\` component takes \`Choice\`
+        components as children. One of the \`Choice\` components here
+        includes a description.`,
+    },
+};
+
+export const Error: StoryComponentType = () => {
+    const toppingsError = "You have selected too many toppings";
+    const [selectedValues, setSelectedValues] = React.useState([
+        "pepperoni",
+        "sausage",
+        "cheese",
+        "pepper",
+    ]);
+    const [error, setError] = React.useState(toppingsError);
+
+    // Returns an error message if more than 3 items are selected,
+    // and it returns undefined otherwise. We use undefined instead of
+    // null here because null would result in a flow error, whereas
+    // undefined would be the same as not passing in anything to the
+    // checkbox group's `errorMessage` prop.
+    const checkForError = (input) => {
+        if (input.length > 3) {
+            return toppingsError;
+        }
+    };
+
+    const handleChange = (input) => {
+        const errorMessage = checkForError(input);
+        setSelectedValues(input);
+        setError(errorMessage);
+    };
+
+    return (
+        <CheckboxGroup
+            label="Pizza order"
+            groupName="toppings"
+            description="You may choose at most three toppings"
+            onChange={handleChange}
+            errorMessage={error}
+            selectedValues={selectedValues}
+        >
+            <Choice label="Pepperoni" value="pepperoni" />
+            <Choice
+                label="Sausage"
+                value="sausage"
+                description="Imported from Italy"
+            />
+            <Choice label="Extra cheese" value="cheese" />
+            <Choice label="Green pepper" value="pepper" />
+            <Choice label="Mushroom" value="mushroom" />
+        </CheckboxGroup>
+    );
+};
+
+Error.parameters = {
+    docs: {
+        storyDescription: `This is what a checkbox group looks like
+        if it has an error. It displays the error that is passed into the
+        \`errorMessage\` prop, provided the error is not null. It also
+        uses the error styling for all the checkboxes. Here, the error
+        message is saved as a state, updated in the change handler, and then
+        passed in as the \`errorMessage\` prop.`,
+    },
+};
+
+export const RowStyling: StoryComponentType = () => {
+    const [selectedValues, setSelectedValues] = React.useState([]);
+
+    return (
+        <View style={styles.wrapper}>
+            <LabelLarge style={styles.title}>Science</LabelLarge>
+            <CheckboxGroup
+                groupName="science-classes"
+                onChange={setSelectedValues}
+                selectedValues={selectedValues}
+                style={styles.group}
+            >
+                <Choice label="Biology" value="1" style={styles.choice} />
+                <Choice label="AP®︎ Biology" value="2" style={styles.choice} />
+                <Choice
+                    label="High school biology"
+                    value="3"
+                    style={styles.choice}
+                />
+                <Choice
+                    label="Cosmology and astronomy"
+                    value="4"
+                    style={styles.choice}
+                />
+                <Choice
+                    label="Electrical engineering"
+                    value="5"
+                    style={styles.choice}
+                />
+                <Choice
+                    label="Health and medicine"
+                    value="6"
+                    style={styles.choice}
+                />
+            </CheckboxGroup>
+        </View>
+    );
+};
+
+RowStyling.parameters = {
+    docs: {
+        storyDescription: `This example shows how one can add custom styles
+        to the checkbox group and to each component to achieve desired custom
+        layouts. The context in this example is inspired by the class selector
+        modal. The label is created separately because we are reflowing all
+        the elements in the group to row. The checkboxes render
+        horizontally when the style on the \`CheckboxGroup\` is set to
+        \`{flexDirection: "row"}\`. Here, \`{flexWrap: "wrap"}\` is also
+        used so the options continue on the next line.`,
+    },
+};
+
+export const MultipleChoiceStyling: StoryComponentType = () => {
+    const [selectedValues, setSelectedValues] = React.useState([]);
+
+    return (
+        <CheckboxGroup
+            label={<LabelLarge>Select all prime numbers</LabelLarge>}
+            description={
+                <LabelXSmall style={styles.description}>
+                    Hint: There is at least one prime number
+                </LabelXSmall>
+            }
+            groupName="science-classes"
+            onChange={setSelectedValues}
+            selectedValues={selectedValues}
+        >
+            <Choice label="1" value="1" style={styles.multipleChoice} />
+            <Choice label="2" value="2" style={styles.multipleChoice} />
+            <Choice label="3" value="3" style={styles.multipleChoice} />
+            <Choice label="4" value="4" style={styles.multipleChoice} />
+            <Choice
+                label="5"
+                value="5"
+                style={[styles.multipleChoice, styles.last]}
+            />
+        </CheckboxGroup>
+    );
+};
+
+MultipleChoiceStyling.parameters = {
+    docs: {
+        storyDescription: `This example shows how to use custom styling
+        to change the appearance of the checkbox group to look more like
+        a multiple choice question. You may also provide custom typography
+        to the label and description. Here, there is a line in
+        between each question, which is achieved using the
+        \`{borderTop: "solid 1px #CCC"}\` style on each \`Choice\`
+        component.`,
+    },
+};
+
+const styles = StyleSheet.create({
+    // Row styling
+    wrapper: {
+        width: 650,
+    },
+    group: {
+        flexDirection: "row",
+        flexWrap: "wrap",
+    },
+    choice: {
+        marginTop: Spacing.xSmall_8,
+        width: 200,
+    },
+    title: {
+        paddingBottom: Spacing.xSmall_8,
+        borderBottom: `1px solid ${Color.offBlack64}`,
+    },
+    // Multiple choice styling
+    multipleChoice: {
+        margin: 0,
+        height: 48,
+        borderTop: "solid 1px #CCC",
+        justifyContent: "center",
+    },
+    description: {
+        marginTop: 5,
+        color: Color.offBlack64,
+    },
+    last: {
+        borderBottom: "solid 1px #CCC",
+    },
+});