@khanacademy/wonder-blocks-form 2.2.1

package/src/components/checkbox-group.js

@@ -0,0 +1,161 @@
+// @flow
+
+import * as React from "react";
+
+import {View, addStyle} from "@khanacademy/wonder-blocks-core";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {
+    type Typography,
+    LabelMedium,
+    LabelSmall,
+} from "@khanacademy/wonder-blocks-typography";
+import type {StyleType} from "@khanacademy/wonder-blocks-core";
+
+import styles from "./group-styles.js";
+import typeof Choice from "./choice.js";
+
+// Keep synced with CheckboxGroupProps in ../util/types.js
+type CheckboxGroupProps = {|
+    /**
+     * Children should be Choice components.
+     */
+    children: Array<React.Element<Choice>>,
+
+    /**
+     * Group name for this checkbox or radio group. Should be unique for all
+     * such groups displayed on a page.
+     */
+    groupName: string,
+
+    /**
+     * Optional label for the group. This label is optional to allow for
+     * greater flexibility in implementing checkbox and radio groups.
+     */
+    label?: string | React.Element<Typography>,
+
+    /**
+     * Optional description for the group.
+     */
+    description?: string | React.Element<Typography>,
+
+    /**
+     * Optional error message. If supplied, the group will be displayed in an
+     * error state, along with this error message. If no error state is desired,
+     * simply do not supply this prop, or pass along null.
+     */
+    errorMessage?: string,
+
+    /**
+     * Custom styling for this group of checkboxes.
+     */
+    style?: StyleType,
+
+    /**
+     * Callback for when selection of the group has changed. Passes the newly
+     * selected values.
+     */
+    onChange: (selectedValues: Array<string>) => mixed,
+
+    /**
+     * An array of the values of the selected values in this checkbox group.
+     */
+    selectedValues: Array<string>,
+
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string,
+|};
+
+const StyledFieldset = addStyle<"fieldset">("fieldset");
+const StyledLegend = addStyle<"legend">("legend");
+
+/**
+ * A checkbox group allows multiple selection. This component auto-populates
+ * 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.
+ */
+export default class CheckboxGroup extends React.Component<CheckboxGroupProps> {
+    handleChange(changedValue: string, originalCheckedState: boolean) {
+        const {onChange, selectedValues} = this.props;
+
+        if (originalCheckedState) {
+            const index = selectedValues.indexOf(changedValue);
+            const updatedSelection = [
+                ...selectedValues.slice(0, index),
+                ...selectedValues.slice(index + 1),
+            ];
+            onChange(updatedSelection);
+        } else {
+            onChange([...selectedValues, changedValue]);
+        }
+    }
+
+    render(): React.Node {
+        const {
+            children,
+            label,
+            description,
+            errorMessage,
+            groupName,
+            selectedValues,
+            style,
+            testId,
+        } = this.props;
+
+        return (
+            <StyledFieldset data-test-id={testId} style={styles.fieldset}>
+                {/* We have a View here because fieldset cannot be used with flexbox*/}
+                <View style={style}>
+                    {typeof label === "string" ? (
+                        <StyledLegend style={styles.legend}>
+                            <LabelMedium>{label}</LabelMedium>
+                        </StyledLegend>
+                    ) : (
+                        label && label
+                    )}
+                    {typeof description === "string" ? (
+                        <LabelSmall style={styles.description}>
+                            {description}
+                        </LabelSmall>
+                    ) : (
+                        description && description
+                    )}
+                    {errorMessage && (
+                        <LabelSmall style={styles.error}>
+                            {errorMessage}
+                        </LabelSmall>
+                    )}
+                    {(label || description || errorMessage) && (
+                        <Strut size={Spacing.small_12} />
+                    )}
+
+                    {React.Children.map(children, (child, index) => {
+                        const {style, value} = child.props;
+                        const checked = selectedValues.includes(value);
+                        return (
+                            <React.Fragment>
+                                {React.cloneElement(child, {
+                                    checked: checked,
+                                    error: !!errorMessage,
+                                    groupName: groupName,
+                                    id: `${groupName}-${value}`,
+                                    key: value,
+                                    onChange: () =>
+                                        this.handleChange(value, checked),
+                                    style: [
+                                        index > 0 && styles.defaultLineGap,
+                                        style,
+                                    ],
+                                    variant: "checkbox",
+                                })}
+                            </React.Fragment>
+                        );
+                    })}
+                </View>
+            </StyledFieldset>
+        );
+    }
+}

package/src/components/checkbox-group.md

@@ -0,0 +1,200 @@
+This example has two items with descriptions, and it sets an error state to the
+entire group if more than three items are selected.
+
+Try out the keyboard navigation! Use tab and shift+tab to navigate among the
+choices, and use space to select/de-select each option.
+
+```js
+import {StyleSheet} from "aphrodite";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {CheckboxGroup, Choice} from "@khanacademy/wonder-blocks-form";
+
+const styles = StyleSheet.create({
+    wrapper: {
+        width: 300,
+    },
+});
+
+class CheckboxGroupPizzaExample extends React.Component {
+    constructor() {
+        super();
+        this.state = {
+            selectedValues: ["pineapple"],
+        };
+        this.handleChange = this.handleChange.bind(this);
+    }
+
+    handleChange(change) {
+        console.log(`${change} was selected!`);
+        const error = this.checkForError(change);
+        this.setState({
+            selectedValues: change,
+            error: error,
+        });
+    }
+
+    checkForError(input) {
+        if (input.length > 3) {
+            return "You have selected too many toppings";
+        }
+    }
+
+    render() {
+        return <CheckboxGroup
+            label="Pizza order"
+            description="You may choose at most three toppings"
+            errorMessage={this.state.error}
+            groupName="Toppings"
+            onChange={this.handleChange}
+            selectedValues={this.state.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" />
+            <Choice label="Pineapple" value="pineapple" description="Does in fact belong on pizzas" />
+        </CheckboxGroup>
+    }
+}
+<View style={styles.wrapper}>
+    <CheckboxGroupPizzaExample />
+</View>
+```
+
+This example shows how one can add custom styles to the checkbox group and to
+each component to achieve desired custom layouts. This context is inspired by
+the class selector modal. The label is created separately because we are
+reflowing all the elements in the group to row.
+
+```js
+import {StyleSheet} from "aphrodite";
+import Color from "@khanacademy/wonder-blocks-color";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {CheckboxGroup, Choice} from "@khanacademy/wonder-blocks-form";
+import {LabelLarge} from "@khanacademy/wonder-blocks-typography";
+
+const styles = StyleSheet.create({
+    wrapper: {
+        width: 650,
+    },
+    group: {
+        flexDirection: "row",
+        flexWrap: "wrap",
+    },
+    choice: {
+        marginTop: 8,
+        width: 200,
+    },
+    title: {
+        paddingBottom: 8,
+        borderBottom: `1px solid ${Color.offBlack64}`,
+    },
+});
+
+class ClassSelectorExample extends React.Component {
+    constructor() {
+        super();
+        this.state = {
+            selectedValues: [],
+        };
+        this.handleChange = this.handleChange.bind(this);
+    }
+
+    handleChange(change) {
+        console.log(`${change} was selected!`);
+        this.setState({
+            selectedValues: change,
+        });
+    }
+
+    render() {
+        return <CheckboxGroup
+            groupName="science-classes"
+            onChange={this.handleChange}
+            selectedValues={this.state.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 style={styles.wrapper}>
+    <LabelLarge style={styles.title}>Science</LabelLarge>
+    <ClassSelectorExample />
+</View>
+```
+
+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.
+
+```js
+import {CheckboxGroup, Choice} from "@khanacademy/wonder-blocks-form";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import {LabelLarge, LabelXSmall} from "@khanacademy/wonder-blocks-typography";
+import {StyleSheet} from "aphrodite";
+
+const styles = StyleSheet.create({
+    choice: {
+        margin: 0,
+        height: 48,
+        borderTop: "solid 1px #CCC",
+        justifyContent: "center",
+        ":last-child": {
+            borderBottom: "solid 1px #CCC",
+        },
+    },
+    description: {
+        marginTop: 5,
+        color: Color.offBlack64,
+    },
+});
+
+class ClassSelectorExample extends React.Component {
+    constructor() {
+        super();
+        this.state = {
+            selectedValues: [],
+        };
+        this.handleChange = this.handleChange.bind(this);
+    }
+
+    handleChange(change) {
+        console.log(`${change} was selected!`);
+        this.setState({
+            selectedValues: change,
+        });
+    }
+
+    render() {
+        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={this.handleChange}
+            selectedValues={this.state.selectedValues}
+        >
+            <Choice label="1" value="1" style={styles.choice} />
+            <Choice label="2" value="2" style={styles.choice} />
+            <Choice label="3" value="3" style={styles.choice} />
+            <Choice label="4" value="4" style={styles.choice} />
+            <Choice label="5" value="5" style={styles.choice} />
+        </CheckboxGroup>
+    }
+}
+
+<View>
+    <ClassSelectorExample />
+</View>
+```

package/src/components/checkbox.js

@@ -0,0 +1,94 @@
+// @flow
+
+import * as React from "react";
+
+import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
+import ChoiceInternal from "./choice-internal.js";
+
+// Keep synced with ChoiceComponentProps in ../util/types.js
+type ChoiceComponentProps = {|
+    ...AriaProps,
+
+    /**
+     * Whether this component is checked
+     */
+    checked: boolean,
+
+    /**
+     * Whether this component is disabled
+     */
+    disabled: boolean,
+
+    /**
+     * Whether this component should show an error state
+     */
+    error: boolean,
+
+    /**
+     * Callback when this component is selected. The newCheckedState is the
+     * new checked state of the component.
+     */
+    onChange: (newCheckedState: boolean) => mixed,
+
+    /**
+     * Optional label for the field.
+     */
+    label?: string,
+
+    /**
+     * Optional description for the field.
+     */
+    description?: string,
+
+    /**
+     * Unique identifier attached to the HTML input element. If used, need to
+     * guarantee that the ID is unique within everything rendered on a page.
+     * Used to match `<label>` with `<input>` elements for screenreaders.
+     */
+    id?: string,
+
+    /**
+     * Optional styling for the container. Does not style the component.
+     */
+    style?: StyleType,
+
+    /**
+     * Adds CSS classes to the Checkbox.
+     */
+    className?: string,
+
+    /**
+     * Optional test ID for e2e testing
+     */
+    testId?: string,
+
+    /**
+     * Name for the checkbox or radio button group. Only applicable for group
+     * contexts, auto-populated by group components via Choice.
+     * @ignore
+     */
+    groupName?: string,
+|};
+
+type DefaultProps = {|
+    disabled: $PropertyType<ChoiceComponentProps, "disabled">,
+    error: $PropertyType<ChoiceComponentProps, "error">,
+|};
+
+/**
+ * ☑️ A nicely styled checkbox for all your checking needs. Can optionally take
+ * label and description props.
+ *
+ * If you want a whole group of Checkbox[es] that are related, see the Choice
+ * and CheckboxGroup components.
+ */
+export default class Checkbox extends React.Component<ChoiceComponentProps> {
+    static defaultProps: DefaultProps = {
+        disabled: false,
+        error: false,
+    };
+
+    render(): React.Node {
+        return <ChoiceInternal variant="checkbox" {...this.props} />;
+    }
+}

package/src/components/checkbox.md

@@ -0,0 +1,134 @@
+The checkbox has various styles for clickable states. Here are sets of default checkboxes, checkboxes in an error state, and disabled checkboxes.
+```js
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Checkbox} from "@khanacademy/wonder-blocks-form";
+import {StyleSheet} from "aphrodite";
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+    },
+    marginRight: {
+        marginRight: 16,
+    }
+});
+
+const handleChange = (checked) => console.log(`clicked on checkbox, will be checked=${checked.toString()}`);
+
+<View style={styles.row}>
+    <Checkbox error={false} checked={false} style={styles.marginRight} onChange={handleChange} />
+    <Checkbox error={false} checked={true} style={styles.marginRight} onChange={handleChange} />
+    <Checkbox error={true} checked={false} style={styles.marginRight} onChange={handleChange} />
+    <Checkbox error={true} checked={true} style={styles.marginRight} onChange={handleChange} />
+    <Checkbox disabled={true} checked={false} style={styles.marginRight} onChange={handleChange} />
+    <Checkbox disabled={true} checked={true} style={styles.marginRight} onChange={handleChange} />
+</View>
+```
+
+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.
+
+```js
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Checkbox} from "@khanacademy/wonder-blocks-form";
+import {LabelMedium, LabelSmall} from "@khanacademy/wonder-blocks-typography";
+import {StyleSheet} from "aphrodite";
+
+class Settings extends React.Component {
+    constructor() {
+        super();
+        this.state = {
+            assignment: false,
+        };
+        this.handleChange = this.handleChange.bind(this);
+    }
+
+    handleChange(checked) {
+        this.setState({
+            assignment: checked,
+        });
+        // Potentially do something here with this updated state information.
+    }
+
+    render() {
+        const handleChanged = (checked) => console.log(`clicked on checkbox with checked=${checked.toString()}`);
+        const headingText = "Functions";
+
+        return <View>
+            <Checkbox
+                label="Receive assignment reminders for Algebra"
+                description="You will receive a reminder 24 hours before each deadline"
+                checked={this.state.assignment}
+                id="assignment"
+                onChange={this.handleChange}
+                testId="algebra-assignment-test"
+                variant="checkbox"
+            />
+        </View>;
+    }
+}
+
+<Settings />
+```
+
+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.
+```js
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Checkbox} from "@khanacademy/wonder-blocks-form";
+import {LabelMedium, LabelSmall} from "@khanacademy/wonder-blocks-typography";
+import {StyleSheet} from "aphrodite";
+
+const styles = StyleSheet.create({
+    wrapper: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-evenly",
+    },
+    topic: {
+        maxWidth: 600,
+    },
+});
+
+class ContentItem extends React.Component {
+    constructor() {
+        super();
+        this.state = {
+            checked: false,
+        }
+    }
+
+    handleChange(checked) {
+        this.setState({
+            checked: checked,
+        });
+        // Potentially do something here with this updated state information.
+    }
+
+    render() {
+        const handleChanged = (checked) => console.log(`clicked on checkbox with checked=${checked.toString()}`);
+        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={this.state.checked}
+                    id="topic-123"
+                    onChange={(checked) => this.handleChange(checked)}
+                />
+        </View>;
+    }
+}
+
+<ContentItem />
+```