@khanacademy/wonder-blocks-form 3.1.10 → 3.1.12

package/dist/components/choice.d.ts

@@ -0,0 +1,127 @@
+import * as React from "react";
+import type { AriaProps, StyleType } from "@khanacademy/wonder-blocks-core";
+import Checkbox from "./checkbox";
+import Radio from "./radio";
+type Props = AriaProps & {
+    /** User-defined. Label for the field. */
+    label: React.ReactNode;
+    /** User-defined. Optional description for the field. */
+    description?: React.ReactNode;
+    /** 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) => unknown;
+    /**
+     * Auto-populated by parent.
+     * @ignore
+     */
+    variant?: "radio" | "checkbox";
+};
+type DefaultProps = {
+    checked: Props["checked"];
+    disabled: Props["disabled"];
+    onChange: 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.
+ *
+ * ### 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;
+    getChoiceComponent(variant?: string | null): typeof Radio | typeof Checkbox;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/choice.js.flow

@@ -0,0 +1,161 @@
+/**
+ * Flowtype definitions for choice
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { AriaProps, StyleType } from "@khanacademy/wonder-blocks-core";
+import Checkbox from "./checkbox";
+import Radio from "./radio";
+declare type Props = {
+  ...AriaProps,
+  ...{
+    /**
+     * User-defined. Label for the field.
+     */
+    label: React.Node,
+
+    /**
+     * User-defined. Optional description for the field.
+     */
+    description?: React.Node,
+
+    /**
+     * 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",
+    ...
+  },
+};
+declare 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.
+ *
+ * ### 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>
+ * ```
+ */
+declare export default class Choice mixins React.Component<Props> {
+  static defaultProps: DefaultProps;
+  getChoiceComponent(variant?: string | null): typeof Radio | typeof Checkbox;
+  render(): React.Element<>;
+}

package/dist/components/field-heading.d.ts

@@ -0,0 +1,50 @@
+import * as React from "react";
+import { StyleType } from "@khanacademy/wonder-blocks-core";
+type Props = {
+    /**
+     * The form field component.
+     */
+    field: React.ReactNode;
+    /**
+     * The title for the label element.
+     */
+    label: React.ReactNode;
+    /**
+     * The text for the description element.
+     */
+    description?: React.ReactNode;
+    /**
+     * Whether this field is required to continue.
+     */
+    required?: boolean;
+    /**
+     * The message for the error element.
+     */
+    error?: React.ReactNode;
+    /**
+     * 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.ReactNode;
+    maybeRenderDescription(): React.ReactNode | null | undefined;
+    maybeRenderError(): React.ReactNode | null | undefined;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/field-heading.js.flow

@@ -0,0 +1,64 @@
+/**
+ * Flowtype definitions for field-heading
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import { StyleType } from "@khanacademy/wonder-blocks-core";
+declare type Props = {
+  /**
+   * The form field component.
+   */
+  field: React.Node,
+
+  /**
+   * The title for the label element.
+   */
+  label: React.Node,
+
+  /**
+   * The text for the description element.
+   */
+  description?: React.Node,
+
+  /**
+   * Whether this field is required to continue.
+   */
+  required?: boolean,
+
+  /**
+   * The message for the error element.
+   */
+  error?: React.Node,
+
+  /**
+   * 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.
+ */
+declare export default class FieldHeading mixins React.Component<Props> {
+  renderLabel(): React.Node;
+  maybeRenderDescription(): React.Node | null | void;
+  maybeRenderError(): React.Node | null | void;
+  render(): React.Element<>;
+}

package/dist/components/group-styles.d.ts

@@ -0,0 +1,3 @@
+import type { StyleDeclaration } from "aphrodite";
+declare const styles: StyleDeclaration;
+export default styles;

package/dist/components/group-styles.js.flow

@@ -0,0 +1,10 @@
+/**
+ * Flowtype definitions for group-styles
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { StyleDeclaration } from "aphrodite";
+declare var styles: StyleDeclaration;
+declare export default typeof styles;

package/dist/components/labeled-text-field.d.ts

@@ -0,0 +1,169 @@
+import * as React from "react";
+import { StyleType } from "@khanacademy/wonder-blocks-core";
+import { TextFieldType } from "./text-field";
+type WithForwardRef = {
+    forwardedRef: React.ForwardedRef<HTMLInputElement>;
+};
+type Props = {
+    /**
+     * An optional unique identifier for the TextField.
+     * If no id is specified, a unique id will be auto-generated.
+     */
+    id?: string;
+    /**
+     * Determines the type of input. Defaults to text.
+     */
+    type: TextFieldType;
+    /**
+     * Provide a label for the TextField.
+     */
+    label: React.ReactNode;
+    /**
+     * Provide a description for the TextField.
+     */
+    description?: React.ReactNode;
+    /**
+     * The input value.
+     */
+    value: string;
+    /**
+     * Makes a read-only input field that cannot be focused. Defaults to false.
+     */
+    disabled: boolean;
+    /**
+     * Whether this field is required to to continue, or the error message to
+     * render if this field is left blank.
+     *
+     * This can be a boolean or a string.
+     *
+     * String:
+     * Please pass in a translated string to use as the error message that will
+     * render if the user leaves this field blank. If this field is required,
+     * and a string is not passed in, a default untranslated string will render
+     * upon error.
+     * Note: The string will not be used if a `validate` prop is passed in.
+     *
+     * Example message: i18n._("A password is required to log in.")
+     *
+     * Boolean:
+     * True/false indicating whether this field is required. Please do not pass
+     * in `true` if possible - pass in the error string instead.
+     * If `true` is passed, and a `validate` prop is not passed, that means
+     * there is no corresponding message and the default untranlsated message
+     * will be used.
+     */
+    required?: boolean | string;
+    /**
+     * Identifies the element or elements that describes this text field.
+     */
+    ariaDescribedby?: string | undefined;
+    /**
+     * Provide a validation for the input value.
+     * Return a string error message or null | void for a valid input.
+     */
+    validate?: (value: string) => string | null | undefined;
+    /**
+     * Called when the TextField input is validated.
+     */
+    onValidate?: (errorMessage?: string | null | undefined) => unknown;
+    /**
+     * Called when the value has changed.
+     */
+    onChange: (newValue: string) => unknown;
+    /**
+     * Called when a key is pressed.
+     */
+    onKeyDown?: (event: React.KeyboardEvent<HTMLInputElement>) => unknown;
+    /**
+     * Called when the element has been focused.
+     */
+    onFocus?: (event: React.FocusEvent<HTMLInputElement>) => unknown;
+    /**
+     * Called when the element has been blurred.
+     */
+    onBlur?: (event: React.FocusEvent<HTMLInputElement>) => unknown;
+    /**
+     * Provide hints or examples of what to enter.
+     */
+    placeholder?: string;
+    /**
+     * Change the field’s sub-components to fit a dark background.
+     */
+    light: boolean;
+    /**
+     * Custom styles for the container.
+     *
+     * Note: This style is passed to the field heading container
+     * due to scenarios where we would like to set a specific
+     * width for the text field. If we apply the style directly
+     * to the text field, the container would not be affected.
+     * For example, setting text field to "width: 50%" would not
+     * affect the container since text field is a child of the container.
+     * In this case, the container would maintain its width ocuppying
+     * unnecessary space when the text field is smaller.
+     */
+    style?: StyleType;
+    /**
+     * Optional test ID for e2e testing.
+     */
+    testId?: string;
+    /**
+     * Specifies if the TextField is read-only.
+     */
+    readOnly?: boolean;
+    /**
+     * Specifies if the TextField allows autocomplete.
+     */
+    autoComplete?: string;
+};
+type PropsWithForwardRef = Props & WithForwardRef;
+type DefaultProps = {
+    type: PropsWithForwardRef["type"];
+    disabled: PropsWithForwardRef["disabled"];
+    light: PropsWithForwardRef["light"];
+};
+type State = {
+    /**
+     * Displayed when the validation fails.
+     */
+    error: string | null | undefined;
+    /**
+     * The user focuses on the textfield.
+     */
+    focused: boolean;
+};
+/**
+ * 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.
+ */
+declare class LabeledTextField extends React.Component<PropsWithForwardRef, State> {
+    static defaultProps: DefaultProps;
+    constructor(props: PropsWithForwardRef);
+    handleValidate: (errorMessage?: string | null | undefined) => unknown;
+    handleFocus: (event: React.FocusEvent<HTMLInputElement>) => unknown;
+    handleBlur: (event: React.FocusEvent<HTMLInputElement>) => unknown;
+    render(): React.ReactElement;
+}
+type ExportProps = Omit<JSX.LibraryManagedAttributes<typeof LabeledTextField, React.ComponentProps<typeof LabeledTextField>>, "forwardedRef">;
+/**
+ * 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}
+ * />
+ * ```
+ */
+declare const _default: React.ForwardRefExoticComponent<ExportProps & React.RefAttributes<HTMLInputElement>>;
+export default _default;