@khanacademy/wonder-blocks-form 2.4.3 → 2.4.6

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

@@ -0,0 +1,167 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import {LabelMedium, LabelSmall} from "@khanacademy/wonder-blocks-typography";
+import type {StoryComponentType} from "@storybook/react";
+
+import Checkbox from "../checkbox.js";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+
+export default {
+    title: "Form / Checkbox",
+    component: Checkbox,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+};
+
+export const Default: StoryComponentType = (args) => <Checkbox {...args} />;
+
+Default.args = {
+    checked: false,
+    onChange: () => {},
+};
+
+Default.parameters = {
+    chromatic: {
+        // We already have screenshots of another story that covers
+        // this and more cases.
+        disableSnapshot: true,
+    },
+};
+
+export const Controlled: StoryComponentType = () => {
+    const [checked, setChecked] = React.useState(false);
+    return <Checkbox checked={checked} onChange={setChecked} />;
+};
+
+Controlled.parameters = {
+    chromatic: {
+        // Disabling because this doesn't test visuals, its for testing
+        // that `state` works as expected.
+        disableSnapshot: true,
+    },
+    docs: {
+        storyDescription:
+            "Use state to keep track of whether the checkbox is checked or not",
+    },
+};
+
+export const Variants: StoryComponentType = () => (
+    <View style={styles.row}>
+        <Checkbox
+            error={false}
+            checked={false}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            error={false}
+            checked={true}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            error={true}
+            checked={false}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            error={true}
+            checked={true}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            disabled={true}
+            checked={false}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+        <Checkbox
+            disabled={true}
+            checked={true}
+            style={styles.marginRight}
+            onChange={() => {}}
+        />
+    </View>
+);
+
+Variants.parameters = {
+    docs: {
+        storyDescription:
+            "The checkbox has various styles for clickable states. Here are sets of default checkboxes, checkboxes in an error state, and disabled checkboxes.",
+    },
+};
+
+export const WithLabel: StoryComponentType = () => {
+    const [checked, setChecked] = React.useState(false);
+
+    return (
+        <Checkbox
+            label="Receive assignment reminders for Algebra"
+            description="You will receive a reminder 24 hours before each deadline"
+            checked={checked}
+            onChange={setChecked}
+        />
+    );
+};
+
+WithLabel.parameters = {
+    docs: {
+        storyDescription:
+            "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.",
+    },
+};
+
+export const AdditionalClickTarget: StoryComponentType = () => {
+    const [checked, setChecked] = React.useState(false);
+    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={checked} id="topic-123" onChange={setChecked} />
+        </View>
+    );
+};
+
+AdditionalClickTarget.parameters = {
+    docs: {
+        storyDescription:
+            "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.",
+    },
+};
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+    },
+    marginRight: {
+        marginRight: 16,
+    },
+    wrapper: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-evenly",
+    },
+    topic: {
+        maxWidth: 600,
+    },
+});

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

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

@@ -0,0 +1,248 @@
+// @flow
+
+export default {
+    id: {
+        description: `An optional unique identifier for the TextField.
+        If no id is specified, a unique id will be auto-generated.`,
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    type: {
+        description:
+            "Determines the type of input. Defaults to text. This may change the appearance or type of characters allowed.",
+        table: {
+            type: {
+                summary: `"text" | "password" | "email" | "number" | "tel"`,
+            },
+            defaultValue: {
+                summary: "text",
+            },
+        },
+        options: ["text", "password", "email", "number", "tel"],
+        control: {
+            type: "select",
+        },
+    },
+    label: {
+        description: "Provide a label for the TextField.",
+        type: {required: true},
+        table: {
+            type: {
+                summary: "string | React.Element<Typography>",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    description: {
+        description: "Provide a description for the TextField.",
+        table: {
+            type: {
+                summary: "string | React.Element<Typography>",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    value: {
+        description: "The input value.",
+        type: {required: true},
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    autoComplete: {
+        description: "Specifies if the TextField allows autocomplete.",
+        table: {
+            type: {
+                summary: "string",
+                detail: `There is a large number of options, including "on", "off", "username", "current-password", and many others.`,
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    disabled: {
+        description: "Makes a read-only input field that cannot be focused.",
+        table: {
+            type: {
+                summary: "boolean",
+            },
+            defaultValue: {
+                summary: "false",
+            },
+        },
+        control: {
+            type: "boolean",
+        },
+    },
+    light: {
+        description:
+            "Change the field’s sub-components to fit a dark background.",
+        table: {
+            type: {
+                summary: "boolean",
+            },
+            defaultValue: {
+                summary: "false",
+            },
+        },
+        control: {
+            type: "boolean",
+        },
+    },
+    placeholder: {
+        description: "Provide hints or examples of what to enter.",
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    required: {
+        description:
+            "Whether this field is required to to continue, or the error message to render if this field is left blank. Pass in a message instead of `true` if possible.",
+        table: {
+            type: {
+                summary: "boolean | string",
+                detail: "The string will not be used if a `validate` prop is passed in.",
+            },
+        },
+        control: {
+            type: "boolean",
+        },
+    },
+    readOnly: {
+        description: "Specifies if the TextField is read-only.",
+        table: {
+            type: {
+                summary: "boolean",
+            },
+        },
+        control: {
+            type: "boolean",
+        },
+    },
+    style: {
+        description: "Custom styles for the input.",
+        table: {
+            type: {
+                summary: "StyleType",
+            },
+        },
+    },
+    testId: {
+        description: "Optional test ID for e2e testing.",
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    validate: {
+        description:
+            "Provide a validation for the input value. Return a string error message or null | void for a valid input.",
+        table: {
+            type: {
+                summary: "(value: string) => ?string",
+            },
+        },
+        control: {
+            type: "null",
+        },
+    },
+
+    /**
+     * Accessibility
+     */
+    ariaDescribedby: {
+        description:
+            "Identifies the element or elements that describes this text field.",
+        table: {
+            category: "Accessibility",
+            type: {
+                summary: "string | Array<string>",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+
+    /**
+     * Events
+     */
+    onValidate: {
+        description: "Called when the TextField input is validated.",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(errorMessage: ?string) => mixed",
+            },
+        },
+    },
+    onChange: {
+        description:
+            "Called when the value has changed. Use this in conjunction with the `value` prop to update the string rendered in the input field.",
+        type: {required: true},
+        table: {
+            category: "Events",
+            type: {
+                summary: "(newValue: string) => mixed",
+            },
+        },
+    },
+    onKeyDown: {
+        action: "keyDown",
+        description: "Called when a key is pressed.",
+        table: {
+            category: "Events",
+            type: {
+                summary:
+                    "(event: SyntheticKeyboardEvent<HTMLInputElement>) => mixed",
+            },
+        },
+    },
+    onFocus: {
+        action: "focus",
+        description: "Called when the element has been focused.",
+        table: {
+            category: "Events",
+            type: {
+                summary:
+                    "(event: SyntheticFocusEvent<HTMLInputElement>) => mixed",
+            },
+        },
+    },
+    onBlur: {
+        action: "blur",
+        description: "Called when the element has been blurred.",
+        table: {
+            category: "Events",
+            type: {
+                summary:
+                    "(event: SyntheticFocusEvent<HTMLInputElement>) => mixed",
+            },
+        },
+    },
+};