@khanacademy/wonder-blocks-form 2.4.4 → 2.4.7

package/src/components/{labeled-text-field.stories.js → __docs__/labeled-text-field.stories.js}

@@ -1,5 +1,6 @@
 // @flow
 import * as React from "react";
+import {StyleSheet} from "aphrodite";
 
 import {LabeledTextField} from "@khanacademy/wonder-blocks-form";
 import {View} from "@khanacademy/wonder-blocks-core";
@@ -8,12 +9,46 @@ import Color from "@khanacademy/wonder-blocks-color";
 import Spacing from "@khanacademy/wonder-blocks-spacing";
 import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Button from "@khanacademy/wonder-blocks-button";
-import {StyleSheet} from "aphrodite";
 
 import type {StoryComponentType} from "@storybook/react";
 
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+import LabeledTextFieldArgTypes from "./labeled-text-field.argtypes.js";
+
 export default {
     title: "Form / LabeledTextField",
+    component: LabeledTextField,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+    argTypes: LabeledTextFieldArgTypes,
+};
+
+export const Default: StoryComponentType = (args) => {
+    return <LabeledTextField {...args} />;
+};
+
+Default.args = {
+    id: "some-ltf-id",
+    type: "text",
+    label: "Label",
+    description: "Hello, this is the description for this field",
+    value: "",
+    disabled: false,
+    required: false,
+    light: false,
+    placeholder: "Placeholder",
+    readOnly: false,
+    autoComplete: "off",
+    validate: () => {},
+    onValidate: () => {},
+    onChange: () => {},
+    onKeyDown: () => {},
+    onFocus: () => {},
+    onBlur: () => {},
 };
 
 export const Text: StoryComponentType = () => {
@@ -37,6 +72,13 @@ export const Text: StoryComponentType = () => {
     );
 };
 
+Text.parameters = {
+    docs: {
+        storyDescription:
+            "An input field with type `text` takes all kinds of characters.",
+    },
+};
+
 export const RequiredWithDefaultText: StoryComponentType = () => {
     const [value, setValue] = React.useState("");
 
@@ -51,13 +93,29 @@ export const RequiredWithDefaultText: StoryComponentType = () => {
             label="Name"
             description="Please enter your name"
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             onKeyDown={handleKeyDown}
             required={true}
         />
     );
 };
 
+RequiredWithDefaultText.parameters = {
+    docs: {
+        storyDescription: `A required field will show the message
+        "This field is required." by default if someone types in it
+        at some point but leaves it blank. Type in the field, then
+        backspace all the way and click out of the field to see
+        this message. Note that this message would not appear if
+        the \`validation\` prop were set.`,
+    },
+    chromatic: {
+        // Disabling snapshot because it doesn't show the error message
+        // until after the user interacts with this field.
+        disableSnapshot: true,
+    },
+};
+
 export const RequiredWithSpecifiedText: StoryComponentType = () => {
     const [value, setValue] = React.useState("");
 
@@ -72,7 +130,7 @@ export const RequiredWithSpecifiedText: StoryComponentType = () => {
             label="Name"
             description="Please enter your name"
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             onKeyDown={handleKeyDown}
             required="This specific field is super required."
         />
@@ -80,8 +138,16 @@ export const RequiredWithSpecifiedText: StoryComponentType = () => {
 };
 
 RequiredWithSpecifiedText.parameters = {
+    docs: {
+        storyDescription: `If a string is passed into the \`required\` prop,
+        the specified message will show when the field is left blank.
+        Type in the field, then backspace all the way and click out of
+        the field to see this message. Note that this message would not
+        appear if the \`validation\` prop were set.`,
+    },
     chromatic: {
-        // We have screenshots of other stories that cover this case.
+        // Disabling snapshot because it doesn't show the error message
+        // until after the user interacts with this field.
         disableSnapshot: true,
     },
 };
@@ -101,15 +167,22 @@ export const Number: StoryComponentType = () => {
             type="number"
             description="Please enter your age"
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             placeholder="Age"
             onKeyDown={handleKeyDown}
         />
     );
 };
 
+Number.parameters = {
+    docs: {
+        storyDescription:
+            "An input field with type `number` will only take numeric characters as input.",
+    },
+};
+
 export const Password: StoryComponentType = () => {
-    const [value, setValue] = React.useState("Password123");
+    const [value, setValue] = React.useState("$ecure123");
 
     const validate = (value: string) => {
         if (value.length < 8) {
@@ -132,7 +205,7 @@ export const Password: StoryComponentType = () => {
             type="password"
             description="Please enter a secure password"
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             placeholder="Password"
             validate={validate}
             onKeyDown={handleKeyDown}
@@ -140,6 +213,15 @@ export const Password: StoryComponentType = () => {
     );
 };
 
+Password.parameters = {
+    docs: {
+        storyDescription: `An input field with type \`password\` will
+        obscure the input value. It also often contains validation.
+        In this example, the password must be over 8 characters long and
+        must contain a numeric value.`,
+    },
+};
+
 export const Email: StoryComponentType = () => {
     const [value, setValue] = React.useState("khan@khan.org");
 
@@ -161,7 +243,7 @@ export const Email: StoryComponentType = () => {
             label="Email"
             type="email"
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             description="Please provide your personal email"
             placeholder="Email"
             validate={validate}
@@ -170,6 +252,15 @@ export const Email: StoryComponentType = () => {
     );
 };
 
+Email.parameters = {
+    docs: {
+        storyDescription: `An input field with type \`email\` will automatically
+        validate an input on submit to ensure it's either formatted properly
+        or blank. \`TextField\` will run validation on blur if the
+        \`validate\` prop is passed in, as in this example.`,
+    },
+};
+
 export const EmailRequired: StoryComponentType = () => {
     const [value, setValue] = React.useState("");
 
@@ -190,7 +281,7 @@ export const EmailRequired: StoryComponentType = () => {
         <LabeledTextField
             label="Email"
             type="email"
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             description="Please provide your personal email"
             value={value}
             validate={validate}
@@ -201,6 +292,13 @@ export const EmailRequired: StoryComponentType = () => {
 };
 
 EmailRequired.parameters = {
+    docs: {
+        storyDescription: `An example of a required field that also has
+        a \`validation\` prop passed in. \`required\` can be a boolean or
+        a string. In this case, \`required\` is set to \`true\` since a
+        string would not even be used if it were passed in because the
+        validation overrides it.`,
+    },
     chromatic: {
         // We have screenshots of other stories that cover this case.
         disableSnapshot: true,
@@ -228,7 +326,7 @@ export const Telephone: StoryComponentType = () => {
             label="Telephone"
             type="tel"
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             description="Please provide your personal phone number"
             placeholder="Telephone"
             validate={validate}
@@ -237,6 +335,15 @@ export const Telephone: StoryComponentType = () => {
     );
 };
 
+Telephone.parameters = {
+    docs: {
+        storyDescription: `An input field with type \`tel\` will NOT
+        validate an input on submit by default as telephone numbers
+        can vary considerably. \`TextField\` will run validation on blur
+        if the \`validate\` prop is passed in, as in this example.`,
+    },
+};
+
 export const Error: StoryComponentType = () => {
     const [value, setValue] = React.useState("khan");
 
@@ -258,7 +365,7 @@ export const Error: StoryComponentType = () => {
             label="Email"
             type="email"
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             description="Please provide your personal email"
             placeholder="Email"
             validate={validate}
@@ -267,16 +374,12 @@ export const Error: StoryComponentType = () => {
     );
 };
 
-export const Disabled: StoryComponentType = () => (
-    <LabeledTextField
-        label="Name"
-        description="Please enter your name"
-        value=""
-        onChange={() => {}}
-        placeholder="Name"
-        disabled={true}
-    />
-);
+Error.parameters = {
+    docs: {
+        storyDescription: `If an input value fails validation,
+        \`TextField\` will have error styling.`,
+    },
+};
 
 export const Light: StoryComponentType = () => {
     const [value, setValue] = React.useState("");
@@ -299,7 +402,7 @@ export const Light: StoryComponentType = () => {
                     </LabelSmall>
                 }
                 value={value}
-                onChange={(newValue) => setValue(newValue)}
+                onChange={setValue}
                 placeholder="Name"
                 light={true}
                 onKeyDown={handleKeyDown}
@@ -308,6 +411,80 @@ export const Light: StoryComponentType = () => {
     );
 };
 
+Light.parameters = {
+    docs: {
+        storyDescription: `If the \`light\` prop is set to true, the
+        underlying \`TextField\` will have a light border when focused.
+        This is intended to be used on a dark background. There is also a
+        specific light styling for the error state, as seen in the
+        \`ErrorLight\` story.`,
+    },
+};
+
+export const ErrorLight: StoryComponentType = () => {
+    const [value, setValue] = React.useState("khan");
+
+    const validate = (value: string) => {
+        const emailRegex = /^[^@\s]+@[^@\s.]+\.[^@.\s]+$/;
+        if (!emailRegex.test(value)) {
+            return "Please enter a valid email";
+        }
+    };
+
+    const handleKeyDown = (event: SyntheticKeyboardEvent<HTMLInputElement>) => {
+        if (event.key === "Enter") {
+            event.currentTarget.blur();
+        }
+    };
+
+    return (
+        <View style={styles.darkBackground}>
+            <LabeledTextField
+                label={
+                    <LabelMedium style={styles.whiteColor}>Email</LabelMedium>
+                }
+                description={
+                    <LabelSmall style={styles.offWhiteColor}>
+                        Please provide your personal email
+                    </LabelSmall>
+                }
+                type="email"
+                value={value}
+                light={true}
+                onChange={setValue}
+                placeholder="Email"
+                validate={validate}
+                onKeyDown={handleKeyDown}
+            />
+        </View>
+    );
+};
+
+ErrorLight.parameters = {
+    docs: {
+        storyDescription: `If an input value fails validation and the
+        \`light\` prop is true, \`TextField\` will have light error styling.`,
+    },
+};
+
+export const Disabled: StoryComponentType = () => (
+    <LabeledTextField
+        label="Name"
+        description="Please enter your name"
+        value=""
+        onChange={() => {}}
+        placeholder="Name"
+        disabled={true}
+    />
+);
+
+Disabled.parameters = {
+    docs: {
+        storyDescription: `If the \`disabled\` prop is set to true,
+        \`TextField\` will have disabled styling and will not be interactable.`,
+    },
+};
+
 export const CustomStyle: StoryComponentType = () => {
     const [firstName, setFirstName] = React.useState("");
     const [lastName, setLastName] = React.useState("");
@@ -324,7 +501,7 @@ export const CustomStyle: StoryComponentType = () => {
                 label="First name"
                 description="Please enter your first name"
                 value={firstName}
-                onChange={(newValue) => setFirstName(newValue)}
+                onChange={setFirstName}
                 placeholder="Khan"
                 style={styles.grow}
                 onKeyDown={handleKeyDown}
@@ -334,7 +511,7 @@ export const CustomStyle: StoryComponentType = () => {
                 label="Last name"
                 description="Please enter your last name"
                 value={lastName}
-                onChange={(newValue) => setLastName(newValue)}
+                onChange={setLastName}
                 placeholder="Academy"
                 style={styles.grow}
                 onKeyDown={handleKeyDown}
@@ -343,6 +520,14 @@ export const CustomStyle: StoryComponentType = () => {
     );
 };
 
+CustomStyle.parameters = {
+    docs: {
+        storyDescription: `\`LabeledTextField\` can take in custom styles that
+        override the default styles. In this example, each field has the
+        style property \`flexGrow: 1\``,
+    },
+};
+
 export const Ref: StoryComponentType = () => {
     const [value, setValue] = React.useState("Khan");
     const inputRef = React.createRef();
@@ -365,7 +550,7 @@ export const Ref: StoryComponentType = () => {
                 label="Name"
                 description="Please enter your name"
                 value={value}
-                onChange={(newValue) => setValue(newValue)}
+                onChange={setValue}
                 placeholder="Name"
                 onKeyDown={handleKeyDown}
                 ref={inputRef}
@@ -378,6 +563,23 @@ export const Ref: StoryComponentType = () => {
     );
 };
 
+Ref.parameters = {
+    docs: {
+        storyDescription: `If you need to save a reference to the input
+        field, you can do so by using the \`ref\` prop. In this example,
+        we want the input field to receive focus when the button is
+        pressed. We can do this by creating a React ref of type
+        \`HTMLInputElement\` and passing it into \`TextField\`'s \`ref\` prop.
+        Now we can use the ref variable in the \`handleSubmit\` function to
+        shift focus to the field.`,
+        chromatic: {
+            // Disabling snapshot because this is testing interaction,
+            // not visuals.
+            disableSnapshot: true,
+        },
+    },
+};
+
 export const ReadOnly: StoryComponentType = () => {
     const [value, setValue] = React.useState("Khan");
 
@@ -392,7 +594,7 @@ export const ReadOnly: StoryComponentType = () => {
             label="Read Only"
             description="This is a read-only field."
             value={value}
-            onChange={(newValue) => setValue(newValue)}
+            onChange={setValue}
             placeholder="Name"
             onKeyDown={handleKeyDown}
             readOnly={true}
@@ -400,6 +602,20 @@ export const ReadOnly: StoryComponentType = () => {
     );
 };
 
+ReadOnly.parameters = {
+    docs: {
+        storyDescription: `An input field with the prop \`readOnly\` set
+        to true is not interactable. It looks the same as if it were not
+        read only, and it can still receive focus, but the interaction
+        point will not appear and the input will not change.`,
+        chromatic: {
+            // Disabling snapshot because this is testing interaction,
+            // not visuals.
+            disableSnapshot: true,
+        },
+    },
+};
+
 export const AutoComplete: StoryComponentType = () => {
     const [value, setValue] = React.useState("");
 
@@ -410,18 +626,38 @@ export const AutoComplete: StoryComponentType = () => {
     };
 
     return (
-        <LabeledTextField
-            label="Name"
-            description="Please enter your name."
-            value={value}
-            onChange={(newValue) => setValue(newValue)}
-            placeholder="Name"
-            onKeyDown={handleKeyDown}
-            autoComplete="name"
-        />
+        <form>
+            <LabeledTextField
+                label="Name"
+                description="Please enter your name."
+                value={value}
+                onChange={setValue}
+                placeholder="Name"
+                onKeyDown={handleKeyDown}
+                style={styles.fieldWithButton}
+                autoComplete="name"
+            />
+            <Button type="submit">Submit</Button>
+        </form>
     );
 };
 
+AutoComplete.parameters = {
+    docs: {
+        storyDescription: `If \`TextField\`'s \`autocomplete\` prop is set,
+        the browser can predict values for the input. When the user starts
+        to type in the field, a list of options will show up based on
+        values that may have been submitted at a previous time.
+        In this example, the text field provides options after you
+        input a value, press the submit button, and refresh the page.`,
+        chromatic: {
+            // Disabling snapshot because this is testing interaction,
+            // not visuals.
+            disableSnapshot: true,
+        },
+    },
+};
+
 const styles = StyleSheet.create({
     darkBackground: {
         background: Color.darkBlue,
@@ -442,4 +678,7 @@ const styles = StyleSheet.create({
     grow: {
         flexGrow: 1,
     },
+    fieldWithButton: {
+        marginBottom: Spacing.medium_16,
+    },
 });

package/src/components/__docs__/radio-group.stories.js

@@ -0,0 +1,182 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {Choice, RadioGroup} from "@khanacademy/wonder-blocks-form";
+import {LabelLarge} 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 / RadioGroup",
+    component: RadioGroup,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+};
+
+export const Default: StoryComponentType = (args) => {
+    return (
+        <RadioGroup {...args}>
+            <Choice label="Bulbasaur" value="bulbasaur" />
+            <Choice
+                label="Charmander"
+                value="charmander"
+                description="Oops, we ran out of Charmanders"
+                disabled
+            />
+            <Choice label="Squirtle" value="squirtle" />
+            <Choice label="Pikachu" value="pikachu" />
+        </RadioGroup>
+    );
+};
+
+Default.args = {
+    // Required
+    groupName: "pokemon",
+    selectedValue: "bulbasaur",
+    onChange: () => {},
+    // Optional
+    label: "Pokemon",
+    description: "Your first Pokemon.",
+};
+
+export const Basic: StoryComponentType = () => {
+    const [selectedValue, setSelectedValue] = React.useState("");
+
+    return (
+        <RadioGroup
+            groupName="pokemon"
+            label="Pokemon"
+            description="Your first Pokemon."
+            onChange={setSelectedValue}
+            selectedValue={selectedValue}
+        >
+            <Choice label="Bulbasaur" value="bulbasaur" />
+            <Choice
+                label="Charmander"
+                value="charmander"
+                description="Oops, we ran out of Charmanders"
+                disabled
+            />
+            <Choice label="Squirtle" value="squirtle" />
+            <Choice label="Pikachu" value="pikachu" />
+        </RadioGroup>
+    );
+};
+
+Basic.parameters = {
+    docs: {
+        storyDescription: `This is a basic example of a radio group.
+        The Wonder Blocks \`RadioGroup\` component takes \`Choice\`
+        components as children. One of the \`Choice\` components here
+        includes a description.`,
+    },
+};
+
+export const Error: StoryComponentType = () => {
+    const emptyError = "You must select an option to continue.";
+    const [selectedValue, setSelectedValue] = React.useState("");
+    const [error, setError] = React.useState(emptyError);
+
+    // This returns an error message if no option is 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
+    // radio group's `errorMessage` prop.
+    const checkForError = (input) => {
+        if (!input) {
+            return emptyError;
+        }
+    };
+
+    const handleChange = (input) => {
+        const errorMessage = checkForError(input);
+        setSelectedValue(input);
+        setError(errorMessage);
+    };
+
+    return (
+        <RadioGroup
+            groupName="pokemon"
+            label="Pokemon"
+            description="Your first Pokemon."
+            onChange={handleChange}
+            selectedValue={selectedValue}
+            errorMessage={error}
+        >
+            <Choice label="Bulbasaur" value="bulbasaur" />
+            <Choice label="Charmander" value="charmander" />
+            <Choice label="Squirtle" value="squirtle" />
+            <Choice label="Pikachu" value="pikachu" />
+        </RadioGroup>
+    );
+};
+
+Error.parameters = {
+    docs: {
+        storyDescription: `This is what a radio 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 radio buttons. Here, the error
+        message is saved as a state, updated in the change handler, and then
+        passed in as the \`errorMessage\` prop.`,
+    },
+};
+
+export const MultipleChoiceStyling: StoryComponentType = () => {
+    const [selectedValue, setSelectedValue] = React.useState("");
+
+    return (
+        <>
+            <LabelLarge style={styles.prompt}>
+                Select your blood type
+            </LabelLarge>
+            <RadioGroup
+                groupName="science-classes"
+                onChange={setSelectedValue}
+                selectedValue={selectedValue}
+            >
+                <Choice label="A" value="1" style={styles.choice} />
+                <Choice label="B" value="2" style={styles.choice} />
+                <Choice label="AB" value="3" style={styles.choice} />
+                <Choice
+                    label="O"
+                    value="4"
+                    style={[styles.choice, styles.lastChoice]}
+                />
+            </RadioGroup>
+        </>
+    );
+};
+
+MultipleChoiceStyling.parameters = {
+    docs: {
+        storyDescription: `This example shows how to use custom styling
+        to change the appearance of the radio group to look more like
+        a multiple choice question. 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({
+    choice: {
+        margin: 0,
+        height: 48,
+        borderTop: "solid 1px #CCC",
+        justifyContent: "center",
+    },
+    lastChoice: {
+        borderBottom: "solid 1px #CCC",
+    },
+    prompt: {
+        marginBottom: 16,
+    },
+});