@khanacademy/wonder-blocks-form 2.4.5 → 2.4.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @khanacademy/wonder-blocks-form
 
+## 2.4.6
+
+### Patch Changes
+
+-   Updated dependencies [ee6fc773]
+    -   @khanacademy/wonder-blocks-clickable@2.3.0
+
 ## 2.4.5
 
 ### Patch Changes

package/dist/index.js

@@ -464,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
 })));
@@ -666,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) {
@@ -725,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"] {
@@ -820,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"] {
@@ -1009,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.5",
+  "version": "2.4.6",
   "design": "v1",
   "description": "Form components for Wonder Blocks.",
   "main": "dist/index.js",
@@ -15,8 +15,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@babel/runtime": "^7.16.3",
-    "@khanacademy/wonder-blocks-clickable": "^2.2.7",
+    "@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.2",
     "@khanacademy/wonder-blocks-icon": "^1.2.29",

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",
+    },
+});

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

@@ -117,7 +117,7 @@ export const WithLabel: StoryComponentType = () => {
 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.",
+            "The checkbox can have an 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.",
     },
 };
 

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

@@ -0,0 +1,86 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import {
+    Choice,
+    CheckboxGroup,
+    RadioGroup,
+} from "@khanacademy/wonder-blocks-form";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+
+import type {StoryComponentType} from "@storybook/react";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+
+export default {
+    title: "Form / Choice",
+    component: Choice,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+};
+
+export const Default: StoryComponentType = (args) => {
+    const [selectedValues, setSelectedValues] = React.useState([]);
+    const [selectedValue, setSelectedValue] = React.useState("");
+
+    return (
+        <View style={styles.row}>
+            <CheckboxGroup
+                label="Pizza order"
+                description="Choose as many toppings as you would like."
+                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" />
+                <Choice {...args} />
+            </CheckboxGroup>
+            <Strut size={Spacing.xLarge_32} />
+            <RadioGroup
+                label="Pizza order"
+                description="Choose only one topping."
+                groupName="Toppings"
+                onChange={setSelectedValue}
+                selectedValue={selectedValue}
+            >
+                <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 {...args} />
+            </RadioGroup>
+        </View>
+    );
+};
+
+Default.args = {
+    label: "Pineapple (Control)",
+    value: "pineapple",
+    description: "Does in fact belong on pizzas",
+};
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+    },
+});