@khanacademy/wonder-blocks-form 2.2.1

package/src/components/choice-internal.js

@@ -0,0 +1,206 @@
+// @flow
+
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import Color from "@khanacademy/wonder-blocks-color";
+import {View, UniqueIDProvider} from "@khanacademy/wonder-blocks-core";
+import {getClickableBehavior} from "@khanacademy/wonder-blocks-clickable";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {LabelMedium, LabelSmall} from "@khanacademy/wonder-blocks-typography";
+import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
+import CheckboxCore from "./checkbox-core.js";
+import RadioCore from "./radio-core.js";
+
+type Props = {|
+    ...AriaProps,
+
+    /** Whether this choice is checked. */
+    checked: boolean,
+
+    /** Whether this choice option is disabled. */
+    disabled: boolean,
+
+    /** Whether this choice is in error mode. */
+    error: boolean,
+
+    /** Returns the new checked state of the component. */
+    onChange: (newCheckedState: boolean) => mixed,
+
+    /**
+     * Used for accessibility purposes, where the label id should match the
+     * input id.
+     */
+    id?: string,
+
+    /**
+     * Optional additional styling.
+     */
+    style?: StyleType,
+
+    /**
+     * Adds CSS classes to the Button.
+     */
+    className?: string,
+
+    /**
+     * Optional id for testing purposes.
+     */
+    testId?: string,
+
+    /**
+     * Label for the field.
+     */
+    label?: string,
+
+    /** Optional description for the field. */
+    description?: string,
+
+    /** Auto-populated by parent's groupName prop if in a group. */
+    groupName?: string,
+
+    /** Takes either "radio" or "checkbox" value. */
+    variant: "radio" | "checkbox",
+|};
+
+type DefaultProps = {|
+    checked: $PropertyType<Props, "checked">,
+    disabled: $PropertyType<Props, "disabled">,
+    error: $PropertyType<Props, "error">,
+|};
+
+/**
+ * This is a potentially labeled 🔘 or ☑️ item. This is an internal component
+ * that's wrapped by Checkbox and Radio. Choice is a wrapper for Checkbox and
+ * Radio with many of its props auto-populated, to be used with CheckboxGroup
+ * and RadioGroup. This design allows for more explicit prop typing. For
+ * example, we can make onChange a required prop on Checkbox but not on Choice
+ * (because for Choice, that prop would be auto-populated by CheckboxGroup).
+ */ export default class ChoiceInternal extends React.Component<Props> {
+    static defaultProps: DefaultProps = {
+        checked: false,
+        disabled: false,
+        error: false,
+    };
+
+    handleLabelClick: (event: SyntheticEvent<>) => void = (event) => {
+        // Browsers automatically use the for attribute to select the input,
+        // but we use ClickableBehavior to handle this.
+        event.preventDefault();
+    };
+
+    handleClick: () => void = () => {
+        const {checked, onChange, variant} = this.props;
+        // Radio buttons cannot be unchecked
+        if (variant === "radio" && checked) {
+            return;
+        }
+        onChange(!checked);
+    };
+
+    getChoiceCoreComponent(): typeof RadioCore | typeof CheckboxCore {
+        if (this.props.variant === "radio") {
+            return RadioCore;
+        } else {
+            return CheckboxCore;
+        }
+    }
+    getLabel(): React.Node {
+        const {disabled, id, label} = this.props;
+        return (
+            <LabelMedium
+                style={[styles.label, disabled && styles.disabledLabel]}
+            >
+                <label htmlFor={id} onClick={this.handleLabelClick}>
+                    {label}
+                </label>
+            </LabelMedium>
+        );
+    }
+    getDescription(id: string | void): React.Node {
+        const {description} = this.props;
+        return (
+            <LabelSmall style={styles.description} id={id}>
+                {description}
+            </LabelSmall>
+        );
+    }
+    render(): React.Node {
+        const {
+            label,
+            description,
+            // eslint-disable-next-line no-unused-vars
+            onChange,
+            style,
+            className,
+            variant,
+            ...coreProps
+        } = this.props;
+        const ChoiceCore = this.getChoiceCoreComponent();
+        const ClickableBehavior = getClickableBehavior();
+        return (
+            <UniqueIDProvider mockOnFirstRender={true} scope="choice">
+                {(ids) => {
+                    const descriptionId = description && ids.get("description");
+
+                    return (
+                        <View style={style} className={className}>
+                            <ClickableBehavior
+                                disabled={coreProps.disabled}
+                                onClick={this.handleClick}
+                                role={variant}
+                            >
+                                {(state, childrenProps) => {
+                                    return (
+                                        <View
+                                            style={styles.wrapper}
+                                            {...childrenProps}
+                                            // We are resetting the tabIndex=0 from handlers
+                                            // because the ChoiceCore component will receive
+                                            // focus on basis of it being an input element.
+                                            tabIndex={-1}
+                                        >
+                                            <ChoiceCore
+                                                {...coreProps}
+                                                {...state}
+                                                aria-describedby={descriptionId}
+                                            />
+                                            <Strut size={Spacing.xSmall_8} />
+                                            {label && this.getLabel()}
+                                        </View>
+                                    );
+                                }}
+                            </ClickableBehavior>
+                            {description && this.getDescription(descriptionId)}
+                        </View>
+                    );
+                }}
+            </UniqueIDProvider>
+        );
+    }
+}
+const styles = StyleSheet.create({
+    wrapper: {
+        flexDirection: "row",
+        alignItems: "flex-start",
+        outline: "none",
+    },
+    label: {
+        userSelect: "none",
+        // NOTE: The checkbox/radio button (height 16px) should be center
+        // aligned with the first line of the label. However, LabelMedium has a
+        // declared line height of 20px, so we need to adjust the top to get the
+        // desired alignment.
+        marginTop: -2,
+    },
+    disabledLabel: {
+        color: Color.offBlack32,
+    },
+    description: {
+        // 16 for icon + 8 for spacing strut
+        marginLeft: Spacing.medium_16 + Spacing.xSmall_8,
+        marginTop: Spacing.xxxSmall_4,
+        color: Color.offBlack64,
+    },
+});

package/src/components/choice.js

@@ -0,0 +1,104 @@
+// @flow
+
+import * as React from "react";
+
+import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
+import Checkbox from "./checkbox.js";
+import Radio from "./radio.js";
+
+type Props = {|
+    ...AriaProps,
+
+    /** User-defined. Label for the field. */
+    label: string,
+
+    /** User-defined. Optional description for the field. */
+    description?: string,
+
+    /** User-defined. Should be distinct for each item in the group. */
+    value: string,
+
+    /** User-defined. Whether this choice option is disabled. Default false. */
+    disabled: boolean,
+
+    /** User-defined. Optional id for testing purposes. */
+    testId?: string,
+
+    /** User-defined. Optional additional styling. */
+    style?: StyleType,
+
+    /**
+     * Auto-populated by parent. Whether this choice is checked.
+     * @ignore
+     */
+    checked: boolean,
+
+    /**
+     * Auto-populated by parent. Whether this choice is in error mode (everything
+     * in a choice group would be in error mode at the same time).
+     * @ignore
+     */
+    error?: boolean,
+
+    /**
+     * Auto-populated by parent. Used for accessibility purposes, where the label
+     * id should match the input id.
+     * @ignore
+     */
+    id?: string,
+
+    /**
+     * Auto-populated by parent's groupName prop.
+     * @ignore
+     */
+    groupName?: string,
+
+    /**
+     * Auto-populated by parent. Returns the new checked state of the component.
+     * @ignore
+     */
+    onChange: (newCheckedState: boolean) => mixed,
+
+    /**
+     * Auto-populated by parent.
+     * @ignore
+     */
+    variant?: "radio" | "checkbox",
+|};
+
+type DefaultProps = {|
+    checked: $PropertyType<Props, "checked">,
+    disabled: $PropertyType<Props, "disabled">,
+    onChange: $PropertyType<Props, "onChange">,
+|};
+
+/**
+ * This is a labeled 🔘 or ☑️ item. Choice is meant to be used as children of
+ * CheckboxGroup and RadioGroup because many of its props are auto-populated
+ * and not shown in the documentation here. See those components for usage
+ * examples.
+ *
+ * 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> {
+    static defaultProps: DefaultProps = {
+        checked: false,
+        disabled: false,
+        onChange: () => {},
+    };
+
+    getChoiceComponent(variant: ?string): typeof Radio | typeof Checkbox {
+        if (variant === "checkbox") {
+            return Checkbox;
+        } else {
+            return Radio;
+        }
+    }
+    render(): React.Node {
+        // we don't need this going into the ChoiceComponent
+        // eslint-disable-next-line no-unused-vars
+        const {value, variant, ...remainingProps} = this.props;
+        const ChoiceComponent = this.getChoiceComponent(variant);
+        return <ChoiceComponent {...remainingProps} />;
+    }
+}

package/src/components/field-heading.js

@@ -0,0 +1,157 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {View, type StyleType} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {
+    type Typography,
+    LabelMedium,
+    LabelSmall,
+} from "@khanacademy/wonder-blocks-typography";
+
+type Props = {|
+    /**
+     * The form field component.
+     */
+    field: React.Node,
+
+    /**
+     * The title for the label element.
+     */
+    label: string | React.Element<Typography>,
+
+    /**
+     * The text for the description element.
+     */
+    description?: string | React.Element<Typography>,
+
+    /**
+     * The message for the error element.
+     */
+    error?: string | React.Element<Typography>,
+
+    /**
+     * Custom styles for the field heading container.
+     */
+    style?: StyleType,
+
+    /**
+     * A unique id to link the label (and optional error) to the field.
+     *
+     * The label will assume that the field will have its id formatted as `${id}-field`.
+     * The field can assume that the error will have its id formatted as `${id}-error`.
+     */
+    id?: string,
+
+    /**
+     * Optional test ID for e2e testing.
+     */
+    testId?: string,
+|};
+
+/**
+ * A FieldHeading is an element that provides a label, description, and error element
+ * to present better context and hints to any type of form field component.
+ */
+export default class FieldHeading extends React.Component<Props> {
+    renderLabel(): React.Node {
+        const {label, id, testId} = this.props;
+
+        return (
+            <React.Fragment>
+                {typeof label === "string" ? (
+                    <LabelMedium
+                        style={styles.label}
+                        tag="label"
+                        htmlFor={id && `${id}-field`}
+                        testId={testId && `${testId}-label`}
+                    >
+                        {label}
+                    </LabelMedium>
+                ) : (
+                    label
+                )}
+                <Strut size={Spacing.xxxSmall_4} />
+            </React.Fragment>
+        );
+    }
+
+    maybeRenderDescription(): ?React.Node {
+        const {description, testId} = this.props;
+
+        if (!description) {
+            return null;
+        }
+
+        return (
+            <React.Fragment>
+                {typeof description === "string" ? (
+                    <LabelSmall
+                        style={styles.description}
+                        testId={testId && `${testId}-description`}
+                    >
+                        {description}
+                    </LabelSmall>
+                ) : (
+                    description
+                )}
+                <Strut size={Spacing.xxxSmall_4} />
+            </React.Fragment>
+        );
+    }
+
+    maybeRenderError(): ?React.Node {
+        const {error, id, testId} = this.props;
+
+        if (!error) {
+            return null;
+        }
+
+        return (
+            <React.Fragment>
+                <Strut size={Spacing.small_12} />
+                {typeof error === "string" ? (
+                    <LabelSmall
+                        style={styles.error}
+                        role="alert"
+                        id={id && `${id}-error`}
+                        testId={testId && `${testId}-error`}
+                    >
+                        {error}
+                    </LabelSmall>
+                ) : (
+                    error
+                )}
+            </React.Fragment>
+        );
+    }
+
+    render(): React.Node {
+        const {field, style} = this.props;
+
+        return (
+            <View style={style}>
+                {this.renderLabel()}
+                {this.maybeRenderDescription()}
+                <Strut size={Spacing.xSmall_8} />
+                {field}
+                {this.maybeRenderError()}
+            </View>
+        );
+    }
+}
+
+const styles = StyleSheet.create({
+    label: {
+        color: Color.offBlack,
+    },
+    description: {
+        color: Color.offBlack64,
+    },
+    error: {
+        color: Color.red,
+    },
+});

package/src/components/field-heading.md

@@ -0,0 +1,43 @@
+```js
+import {View} from "@khanacademy/wonder-blocks-core";
+import {TextField} from "@khanacademy/wonder-blocks-form";
+
+class FieldHeadingExample extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = {
+            value: "",
+        };
+        this.handleKeyDown = this.handleKeyDown.bind(this);
+    }
+
+    handleKeyDown(event) {
+        if (event.key === "Enter") {
+            event.currentTarget.blur();
+        }
+    }
+
+    render() {
+        return (
+            <FieldHeading
+                field={
+                    <TextField
+                        id="tf-1"
+                        type="text"
+                        value={this.state.value}
+                        placeholder="Username"
+                        onChange={(newValue) => this.setState({value: newValue})}
+                        onKeyDown={this.handleKeyDown}
+                    />
+                }
+                label="Username"
+                description="Please enter your username."
+                error="That username is already taken."
+            />
+
+        );
+    }
+}
+
+<FieldHeadingExample />
+```

package/src/components/group-styles.js

@@ -0,0 +1,35 @@
+// @flow
+import {StyleSheet} from "aphrodite";
+
+import Color from "@khanacademy/wonder-blocks-color";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+
+import type {StyleDeclaration} from "aphrodite";
+
+const styles: StyleDeclaration = StyleSheet.create({
+    fieldset: {
+        border: "none",
+        padding: 0,
+        margin: 0,
+    },
+
+    legend: {
+        padding: 0,
+    },
+
+    description: {
+        marginTop: Spacing.xxxSmall_4,
+        color: Color.offBlack64,
+    },
+
+    error: {
+        marginTop: Spacing.xxxSmall_4,
+        color: Color.red,
+    },
+
+    defaultLineGap: {
+        marginTop: Spacing.xSmall_8,
+    },
+});
+
+export default styles;