@khanacademy/wonder-blocks-form 2.4.3 → 2.4.6

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

@@ -11,8 +11,42 @@ import Button from "@khanacademy/wonder-blocks-button";
 
 import type {StoryComponentType} from "@storybook/react";
 
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+import TextFieldArgTypes from "./text-field.argtypes.js";
+
 export default {
     title: "Form / TextField",
+    component: TextField,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+    argTypes: TextFieldArgTypes,
+};
+
+export const Default: StoryComponentType = (args) => {
+    return <TextField {...args} />;
+};
+
+Default.args = {
+    id: "some-id",
+    type: "text",
+    value: "",
+    disabled: false,
+    placeholder: "",
+    required: false,
+    light: false,
+    testId: "",
+    readOnly: false,
+    autoComplete: "off",
+    validate: () => {},
+    onValidate: () => {},
+    onChange: () => {},
+    onKeyDown: () => {},
+    onFocus: () => {},
+    onBlur: () => {},
 };
 
 export const Text: StoryComponentType = () => {
@@ -40,6 +74,13 @@ export const Text: StoryComponentType = () => {
     );
 };
 
+Text.parameters = {
+    docs: {
+        storyDescription:
+            "An input field with type `text` takes all kinds of characters.",
+    },
+};
+
 export const Required: StoryComponentType = () => {
     const [value, setValue] = React.useState("");
 
@@ -55,7 +96,7 @@ export const Required: StoryComponentType = () => {
 
     return (
         <TextField
-            id="tf-1"
+            id="tf-2"
             type="text"
             value={value}
             onChange={handleChange}
@@ -65,6 +106,19 @@ export const Required: StoryComponentType = () => {
     );
 };
 
+Required.parameters = {
+    docs: {
+        storyDescription: `A required field will have error styling if the
+        field is left blank. To observe this, type something into the
+        field, backspace all the way, and then shift focus out of the field.`,
+    },
+    chromatic: {
+        // Disabling snapshot because it doesn't show the error style
+        // until after the user interacts with this field.
+        disableSnapshot: true,
+    },
+};
+
 export const Number: StoryComponentType = () => {
     const [value, setValue] = React.useState("12345");
 
@@ -80,7 +134,7 @@ export const Number: StoryComponentType = () => {
 
     return (
         <TextField
-            id="tf-1"
+            id="tf-3"
             type="number"
             value={value}
             placeholder="Number"
@@ -90,6 +144,13 @@ export const Number: StoryComponentType = () => {
     );
 };
 
+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 [errorMessage, setErrorMessage] = React.useState();
@@ -129,7 +190,7 @@ export const Password: StoryComponentType = () => {
     return (
         <View>
             <TextField
-                id="tf-1"
+                id="tf-4"
                 type="password"
                 value={value}
                 placeholder="Password"
@@ -150,6 +211,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@khanacademy.org");
     const [errorMessage, setErrorMessage] = React.useState();
@@ -187,7 +257,7 @@ export const Email: StoryComponentType = () => {
     return (
         <View>
             <TextField
-                id="tf-1"
+                id="tf-5"
                 type="email"
                 value={value}
                 placeholder="Email"
@@ -208,6 +278,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 Telephone: StoryComponentType = () => {
     const [value, setValue] = React.useState("123-456-7890");
     const [errorMessage, setErrorMessage] = React.useState();
@@ -245,7 +324,7 @@ export const Telephone: StoryComponentType = () => {
     return (
         <View>
             <TextField
-                id="tf-1"
+                id="tf-6"
                 type="tel"
                 value={value}
                 placeholder="Telephone"
@@ -266,6 +345,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");
     const [errorMessage, setErrorMessage] = React.useState();
@@ -303,7 +391,7 @@ export const Error: StoryComponentType = () => {
     return (
         <View>
             <TextField
-                id="tf-1"
+                id="tf-7"
                 type="email"
                 value={value}
                 placeholder="Email"
@@ -324,15 +412,12 @@ export const Error: StoryComponentType = () => {
     );
 };
 
-export const Disabled: StoryComponentType = () => (
-    <TextField
-        id="tf-1"
-        value=""
-        placeholder="This field is disabled."
-        onChange={() => {}}
-        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("khan@khanacademy.org");
@@ -371,7 +456,7 @@ export const Light: StoryComponentType = () => {
     return (
         <View style={styles.darkBackground}>
             <TextField
-                id="tf-1"
+                id="tf-9"
                 type="email"
                 value={value}
                 placeholder="Email"
@@ -395,6 +480,98 @@ export const Light: StoryComponentType = () => {
     );
 };
 
+Light.parameters = {
+    docs: {
+        storyDescription: `If the \`light\` prop is set to true,
+        \`TextField\` will have light styling. 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 [errorMessage, setErrorMessage] = React.useState();
+    const [focused, setFocused] = React.useState(false);
+
+    const handleChange = (newValue: string) => {
+        setValue(newValue);
+    };
+
+    const validate = (value: string) => {
+        const emailRegex = /^[^@\s]+@[^@\s.]+\.[^@.\s]+$/;
+        if (!emailRegex.test(value)) {
+            return "Please enter a valid email";
+        }
+    };
+
+    const handleValidate = (errorMessage: ?string) => {
+        setErrorMessage(errorMessage);
+    };
+
+    const handleKeyDown = (event: SyntheticKeyboardEvent<HTMLInputElement>) => {
+        if (event.key === "Enter") {
+            event.currentTarget.blur();
+        }
+    };
+
+    const handleFocus = () => {
+        setFocused(true);
+    };
+
+    const handleBlur = () => {
+        setFocused(false);
+    };
+
+    return (
+        <View style={styles.darkBackground}>
+            <TextField
+                id="tf-7"
+                type="email"
+                value={value}
+                placeholder="Email"
+                light={true}
+                validate={validate}
+                onValidate={handleValidate}
+                onChange={handleChange}
+                onKeyDown={handleKeyDown}
+                onFocus={handleFocus}
+                onBlur={handleBlur}
+            />
+            {!focused && errorMessage && (
+                <View>
+                    <Strut size={Spacing.xSmall_8} />
+                    <_Text style={styles.errorMessage}>{errorMessage}</_Text>
+                </View>
+            )}
+        </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 = () => (
+    <TextField
+        id="tf-8"
+        value=""
+        placeholder="This field is disabled."
+        onChange={() => {}}
+        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 [value, setValue] = React.useState("");
 
@@ -410,7 +587,7 @@ export const CustomStyle: StoryComponentType = () => {
 
     return (
         <TextField
-            id="tf-1"
+            id="tf-10"
             style={styles.customField}
             type="text"
             value={value}
@@ -421,6 +598,15 @@ export const CustomStyle: StoryComponentType = () => {
     );
 };
 
+CustomStyle.parameters = {
+    docs: {
+        storyDescription: `\`TextField\` can take in custom styles that
+        override the default styles. This example has custom styles for the
+        \`backgroundColor\`, \`color\`, \`border\`, \`maxWidth\`, and
+        placeholder \`color\` properties.`,
+    },
+};
+
 export const Ref: StoryComponentType = () => {
     const [value, setValue] = React.useState("");
     const inputRef: RefObject<typeof HTMLInputElement> = React.createRef();
@@ -444,7 +630,7 @@ export const Ref: StoryComponentType = () => {
     return (
         <View>
             <TextField
-                id="tf-1"
+                id="tf-11"
                 type="text"
                 value={value}
                 placeholder="Text"
@@ -460,6 +646,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");
 
@@ -475,7 +678,7 @@ export const ReadOnly: StoryComponentType = () => {
 
     return (
         <TextField
-            id="tf-1"
+            id="tf-12"
             type="text"
             value={value}
             placeholder="Text"
@@ -486,6 +689,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("");
 
@@ -500,18 +717,38 @@ export const AutoComplete: StoryComponentType = () => {
     };
 
     return (
-        <TextField
-            id="tf-1"
-            type="text"
-            value={value}
-            placeholder="Name"
-            onChange={handleChange}
-            onKeyDown={handleKeyDown}
-            autoComplete="name"
-        />
+        <form>
+            <TextField
+                id="tf-13"
+                type="text"
+                value={value}
+                placeholder="Name"
+                onChange={handleChange}
+                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({
     errorMessage: {
         color: Color.red,
@@ -537,4 +774,7 @@ const styles = StyleSheet.create({
     button: {
         maxWidth: 150,
     },
+    fieldWithButton: {
+        marginBottom: Spacing.medium_16,
+    },
 });

package/src/components/checkbox-group.js

@@ -76,6 +76,33 @@ const StyledLegend = addStyle<"legend">("legend");
  * 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>
+ * ```
  */
 export default class CheckboxGroup extends React.Component<CheckboxGroupProps> {
     handleChange(changedValue: string, originalCheckedState: boolean) {

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 = {

package/src/components/choice.js

@@ -80,7 +80,65 @@ type DefaultProps = {|
  *
  * If you wish to use just a single field, use Checkbox or Radio with the
  * optional label and description props.
- */ export default class Choice extends React.Component<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>
+ * ```
+ */
+export default class Choice extends React.Component<Props> {
     static defaultProps: DefaultProps = {
         checked: false,
         disabled: false,

package/src/components/labeled-text-field.js

@@ -293,6 +293,26 @@ type ExportProps = $Diff<
     WithForwardRef,
 >;
 
+/**
+ * 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: React.AbstractComponent<ExportProps, HTMLInputElement> =
     React.forwardRef<ExportProps, HTMLInputElement>((props, ref) => (
         <LabeledTextFieldInternal {...props} forwardedRef={ref} />

package/src/components/radio-group.js

@@ -73,6 +73,33 @@ const StyledLegend = addStyle<"legend">("legend");
  * 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>
+ * ```
  */
 export default class RadioGroup extends React.Component<RadioGroupProps> {
     handleChange(changedValue: string) {

package/src/components/text-field.js

@@ -348,6 +348,23 @@ type ExportProps = $Diff<
     WithForwardRef,
 >;
 
+/**
+ * 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: React.AbstractComponent<ExportProps, HTMLInputElement> =
     React.forwardRef<ExportProps, HTMLInputElement>((props, ref) => (
         <TextFieldInternal {...props} forwardedRef={ref} />