@khanacademy/wonder-blocks-form 4.0.9 → 4.1.0

package/src/__tests__/__snapshots__/custom-snapshot.test.tsx.snap

@@ -2,6 +2,7 @@
 
 exports[`CheckboxCore type:default checked:false 1`] = `
 <input
+  aria-checked="false"
   aria-invalid={false}
   checked={false}
   className=""
@@ -46,9 +47,73 @@ exports[`CheckboxCore type:default checked:false 1`] = `
 />
 `;
 
+exports[`CheckboxCore type:default checked:null 1`] = `
+[
+  <input
+    aria-checked="mixed"
+    aria-invalid={false}
+    className=""
+    disabled={false}
+    onChange={[Function]}
+    onClick={[Function]}
+    style={
+      {
+        ":active": {
+          "background": "#1b50b3",
+          "boxShadow": "0 0 0 1px #ffffff, 0 0 0 3px #1b50b3",
+        },
+        ":focusVisible": {
+          "boxShadow": "0 0 0 1px #ffffff, 0 0 0 3px #1865f2",
+        },
+        ":hover": {
+          "boxShadow": "0 0 0 1px #ffffff, 0 0 0 3px #1865f2",
+        },
+        "MozAppearance": "none",
+        "WebkitAppearance": "none",
+        "appearance": "none",
+        "backgroundColor": "#1865f2",
+        "borderRadius": 3,
+        "borderStyle": "solid",
+        "borderWidth": 0,
+        "boxSizing": "border-box",
+        "height": 16,
+        "margin": 0,
+        "minHeight": 16,
+        "minWidth": 16,
+        "outline": "none",
+        "width": 16,
+      }
+    }
+    type="checkbox"
+  />,
+  <svg
+    className=""
+    height={16}
+    style={
+      {
+        "display": "inline-block",
+        "flexGrow": 0,
+        "flexShrink": 0,
+        "pointerEvents": "none",
+        "position": "absolute",
+        "verticalAlign": "text-bottom",
+      }
+    }
+    viewBox="0 0 16 16"
+    width={16}
+  >
+    <path
+      d="M3 8C3 7.44772 3.44772 7 4 7H12C12.5523 7 13 7.44772 13 8C13 8.55228 12.5523 9 12 9H4C3.44772 9 3 8.55228 3 8Z"
+      fill="#ffffff"
+    />
+  </svg>,
+]
+`;
+
 exports[`CheckboxCore type:default checked:true 1`] = `
 [
   <input
+    aria-checked="true"
     aria-invalid={false}
     checked={true}
     className=""
@@ -111,6 +176,7 @@ exports[`CheckboxCore type:default checked:true 1`] = `
 
 exports[`CheckboxCore type:disabled checked:false 1`] = `
 <input
+  aria-checked="false"
   aria-invalid={false}
   checked={false}
   className=""
@@ -141,9 +207,65 @@ exports[`CheckboxCore type:disabled checked:false 1`] = `
 />
 `;
 
+exports[`CheckboxCore type:disabled checked:null 1`] = `
+[
+  <input
+    aria-checked="mixed"
+    aria-invalid={false}
+    className=""
+    disabled={true}
+    onChange={[Function]}
+    onClick={[Function]}
+    style={
+      {
+        "MozAppearance": "none",
+        "WebkitAppearance": "none",
+        "appearance": "none",
+        "backgroundColor": "#f7f8fa",
+        "borderColor": "rgba(33,36,44,0.16)",
+        "borderRadius": 3,
+        "borderStyle": "solid",
+        "borderWidth": 1,
+        "boxSizing": "border-box",
+        "cursor": "auto",
+        "height": 16,
+        "margin": 0,
+        "minHeight": 16,
+        "minWidth": 16,
+        "outline": "none",
+        "width": 16,
+      }
+    }
+    type="checkbox"
+  />,
+  <svg
+    className=""
+    height={16}
+    style={
+      {
+        "display": "inline-block",
+        "flexGrow": 0,
+        "flexShrink": 0,
+        "pointerEvents": "none",
+        "position": "absolute",
+        "verticalAlign": "text-bottom",
+      }
+    }
+    viewBox="0 0 16 16"
+    width={16}
+  >
+    <path
+      d="M3 8C3 7.44772 3.44772 7 4 7H12C12.5523 7 13 7.44772 13 8C13 8.55228 12.5523 9 12 9H4C3.44772 9 3 8.55228 3 8Z"
+      fill="rgba(33,36,44,0.32)"
+    />
+  </svg>,
+]
+`;
+
 exports[`CheckboxCore type:disabled checked:true 1`] = `
 [
   <input
+    aria-checked="true"
     aria-invalid={false}
     checked={true}
     className=""
@@ -198,6 +320,7 @@ exports[`CheckboxCore type:disabled checked:true 1`] = `
 
 exports[`CheckboxCore type:error checked:false 1`] = `
 <input
+  aria-checked="false"
   aria-invalid={true}
   checked={false}
   className=""
@@ -242,9 +365,73 @@ exports[`CheckboxCore type:error checked:false 1`] = `
 />
 `;
 
+exports[`CheckboxCore type:error checked:null 1`] = `
+[
+  <input
+    aria-checked="mixed"
+    aria-invalid={true}
+    className=""
+    disabled={false}
+    onChange={[Function]}
+    onClick={[Function]}
+    style={
+      {
+        ":active": {
+          "background": "#9e271d",
+          "boxShadow": "0 0 0 1px #ffffff, 0 0 0 3px #9e271d",
+        },
+        ":focusVisible": {
+          "boxShadow": "0 0 0 1px #ffffff, 0 0 0 3px #d92916",
+        },
+        ":hover": {
+          "boxShadow": "0 0 0 1px #ffffff, 0 0 0 3px #d92916",
+        },
+        "MozAppearance": "none",
+        "WebkitAppearance": "none",
+        "appearance": "none",
+        "backgroundColor": "#d92916",
+        "borderRadius": 3,
+        "borderStyle": "solid",
+        "borderWidth": 0,
+        "boxSizing": "border-box",
+        "height": 16,
+        "margin": 0,
+        "minHeight": 16,
+        "minWidth": 16,
+        "outline": "none",
+        "width": 16,
+      }
+    }
+    type="checkbox"
+  />,
+  <svg
+    className=""
+    height={16}
+    style={
+      {
+        "display": "inline-block",
+        "flexGrow": 0,
+        "flexShrink": 0,
+        "pointerEvents": "none",
+        "position": "absolute",
+        "verticalAlign": "text-bottom",
+      }
+    }
+    viewBox="0 0 16 16"
+    width={16}
+  >
+    <path
+      d="M3 8C3 7.44772 3.44772 7 4 7H12C12.5523 7 13 7.44772 13 8C13 8.55228 12.5523 9 12 9H4C3.44772 9 3 8.55228 3 8Z"
+      fill="#ffffff"
+    />
+  </svg>,
+]
+`;
+
 exports[`CheckboxCore type:error checked:true 1`] = `
 [
   <input
+    aria-checked="true"
     aria-invalid={true}
     checked={true}
     className=""
@@ -351,6 +538,51 @@ exports[`RadioCore type:default checked:false 1`] = `
 />
 `;
 
+exports[`RadioCore type:default checked:null 1`] = `
+<input
+  aria-invalid={false}
+  className=""
+  disabled={false}
+  onChange={[Function]}
+  onClick={[Function]}
+  style={
+    {
+      ":active": {
+        "backgroundColor": "#dae6fd",
+        "borderColor": "#1865f2",
+        "borderWidth": 2,
+      },
+      ":focusVisible": {
+        "backgroundColor": "#ffffff",
+        "borderColor": "#1865f2",
+        "borderWidth": 2,
+      },
+      ":hover": {
+        "backgroundColor": "#ffffff",
+        "borderColor": "#1865f2",
+        "borderWidth": 2,
+      },
+      "MozAppearance": "none",
+      "WebkitAppearance": "none",
+      "appearance": "none",
+      "backgroundColor": "#ffffff",
+      "borderColor": "rgba(33,36,44,0.50)",
+      "borderRadius": "50%",
+      "borderStyle": "solid",
+      "borderWidth": 1,
+      "boxSizing": "border-box",
+      "height": 16,
+      "margin": 0,
+      "minHeight": 16,
+      "minWidth": 16,
+      "outline": "none",
+      "width": 16,
+    }
+  }
+  type="radio"
+/>
+`;
+
 exports[`RadioCore type:default checked:true 1`] = `
 <input
   aria-invalid={false}
@@ -424,6 +656,37 @@ exports[`RadioCore type:disabled checked:false 1`] = `
 />
 `;
 
+exports[`RadioCore type:disabled checked:null 1`] = `
+<input
+  aria-invalid={false}
+  className=""
+  disabled={true}
+  onChange={[Function]}
+  onClick={[Function]}
+  style={
+    {
+      "MozAppearance": "none",
+      "WebkitAppearance": "none",
+      "appearance": "none",
+      "backgroundColor": "#f7f8fa",
+      "borderColor": "rgba(33,36,44,0.16)",
+      "borderRadius": "50%",
+      "borderStyle": "solid",
+      "borderWidth": 1,
+      "boxSizing": "border-box",
+      "cursor": "auto",
+      "height": 16,
+      "margin": 0,
+      "minHeight": 16,
+      "minWidth": 16,
+      "outline": "none",
+      "width": 16,
+    }
+  }
+  type="radio"
+/>
+`;
+
 exports[`RadioCore type:disabled checked:true 1`] = `
 [
   <input
@@ -517,6 +780,51 @@ exports[`RadioCore type:error checked:false 1`] = `
 />
 `;
 
+exports[`RadioCore type:error checked:null 1`] = `
+<input
+  aria-invalid={true}
+  className=""
+  disabled={false}
+  onChange={[Function]}
+  onClick={[Function]}
+  style={
+    {
+      ":active": {
+        "backgroundColor": "#fceeec",
+        "borderColor": "#9e271d",
+        "borderWidth": 2,
+      },
+      ":focusVisible": {
+        "backgroundColor": "#fceeec",
+        "borderColor": "#d92916",
+        "borderWidth": 2,
+      },
+      ":hover": {
+        "backgroundColor": "#fceeec",
+        "borderColor": "#d92916",
+        "borderWidth": 2,
+      },
+      "MozAppearance": "none",
+      "WebkitAppearance": "none",
+      "appearance": "none",
+      "backgroundColor": "#fceeec",
+      "borderColor": "#d92916",
+      "borderRadius": "50%",
+      "borderStyle": "solid",
+      "borderWidth": 1,
+      "boxSizing": "border-box",
+      "height": 16,
+      "margin": 0,
+      "minHeight": 16,
+      "minWidth": 16,
+      "outline": "none",
+      "width": 16,
+    }
+  }
+  type="radio"
+/>
+`;
+
 exports[`RadioCore type:error checked:true 1`] = `
 <input
   aria-invalid={true}

package/src/__tests__/custom-snapshot.test.tsx

@@ -5,7 +5,7 @@ import CheckboxCore from "../components/checkbox-core";
 import RadioCore from "../components/radio-core";
 
 const states = ["default", "error", "disabled"];
-const checkedStates = [false, true];
+const checkedStates = [false, true, null];
 
 describe("CheckboxCore", () => {
     states.forEach((state: any) => {

package/src/components/checkbox-core.tsx

@@ -6,21 +6,54 @@ import {addStyle} from "@khanacademy/wonder-blocks-core";
 import Icon from "@khanacademy/wonder-blocks-icon";
 
 import type {IconAsset} from "@khanacademy/wonder-blocks-icon";
-
-import type {ChoiceCoreProps} from "../util/types";
+import type {ChoiceCoreProps, Checked} from "../util/types";
+
+// `AriaChecked` and `mapCheckedToAriaChecked()` are used to convert the
+// `checked` prop value to a value that a screen reader can understand via the
+// `aria-checked` attribute
+type AriaChecked = "true" | "false" | "mixed";
+
+function mapCheckedToAriaChecked(value: Checked): AriaChecked {
+    switch (value) {
+        case true:
+            return "true";
+        case false:
+            return "false";
+        default:
+            return "mixed";
+    }
+}
 
 const {blue, red, white, offWhite, offBlack16, offBlack32, offBlack50} = Color;
 
 const StyledInput = addStyle("input");
 
-const checkboxCheck: IconAsset = {
+const checkPath: IconAsset = {
     small: "M11.263 4.324a1 1 0 1 1 1.474 1.352l-5.5 6a1 1 0 0 1-1.505-.036l-2.5-3a1 1 0 1 1 1.536-1.28L6.536 9.48l4.727-5.157z",
 };
 
+const indeterminatePath: IconAsset = {
+    small: "M3 8C3 7.44772 3.44772 7 4 7H12C12.5523 7 13 7.44772 13 8C13 8.55228 12.5523 9 12 9H4C3.44772 9 3 8.55228 3 8Z",
+};
+
 /**
  * The internal stateless ☑️ Checkbox
  */
 export default class CheckboxCore extends React.Component<ChoiceCoreProps> {
+    componentDidMount(): void {
+        if (this.props.checked == null && this.inputRef.current != null) {
+            this.inputRef.current.indeterminate = true;
+        }
+    }
+
+    componentDidUpdate(prevProps: Readonly<ChoiceCoreProps>): void {
+        if (this.inputRef.current != null) {
+            this.inputRef.current.indeterminate = this.props.checked == null;
+        }
+    }
+
+    inputRef: React.RefObject<HTMLInputElement> = React.createRef();
+
     handleChange: () => void = () => {
         // Empty because change is handled by ClickableBehavior
         return;
@@ -50,13 +83,26 @@ export default class CheckboxCore extends React.Component<ChoiceCoreProps> {
             "data-test-id": testId,
         } as const;
 
+        const checkboxIcon = (
+            <Icon
+                color={disabled ? offBlack32 : white}
+                icon={checked ? checkPath : indeterminatePath}
+                size="small"
+                style={sharedStyles.checkboxIcon}
+            />
+        );
+
+        const ariaChecked = mapCheckedToAriaChecked(checked);
+
         return (
             <React.Fragment>
                 <StyledInput
                     {...sharedProps}
+                    ref={this.inputRef}
                     type="checkbox"
+                    aria-checked={ariaChecked}
                     aria-invalid={error}
-                    checked={checked}
+                    checked={checked ?? undefined}
                     disabled={disabled}
                     id={id}
                     name={groupName}
@@ -66,14 +112,7 @@ export default class CheckboxCore extends React.Component<ChoiceCoreProps> {
                     style={defaultStyle}
                     {...props}
                 />
-                {checked && (
-                    <Icon
-                        color={disabled ? offBlack32 : white}
-                        icon={checkboxCheck}
-                        size="small"
-                        style={sharedStyles.checkIcon}
-                    />
-                )}
+                {checked || checked == null ? checkboxIcon : <></>}
             </React.Fragment>
         );
     }
@@ -109,7 +148,7 @@ const sharedStyles = StyleSheet.create({
         borderWidth: 1,
     },
 
-    checkIcon: {
+    checkboxIcon: {
         position: "absolute",
         pointerEvents: "none",
     },
@@ -135,7 +174,7 @@ const colors = {
 
 const styles: Record<string, any> = {};
 
-const _generateStyles = (checked: boolean, error: boolean) => {
+const _generateStyles = (checked: Checked, error: boolean) => {
     // "hash" the parameters
     const styleKey = `${String(checked)}-${String(error)}`;
     if (styles[styleKey]) {
@@ -145,7 +184,7 @@ const _generateStyles = (checked: boolean, error: boolean) => {
     const palette = error ? colors.error : colors.default;
 
     let newStyles: Record<string, any> = {};
-    if (checked) {
+    if (checked || checked == null) {
         newStyles = {
             default: {
                 backgroundColor: palette.base,

package/src/components/checkbox.tsx

@@ -1,14 +1,16 @@
 import * as React from "react";
 
 import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
+import type {Checked} from "../util/types";
+
 import ChoiceInternal from "./choice-internal";
 
 // Keep synced with ChoiceComponentProps in ../util/types.js
 type ChoiceComponentProps = AriaProps & {
     /**
-     * Whether this component is checked
+     * Whether this component is checked or indeterminate
      */
-    checked: boolean;
+    checked: Checked;
     /**
      * Whether this component is disabled
      */

package/src/components/choice-internal.tsx

@@ -12,7 +12,7 @@ import RadioCore from "./radio-core";
 
 type Props = AriaProps & {
     /** Whether this choice is checked. */
-    checked: boolean;
+    checked: boolean | null | undefined;
     /** Whether this choice option is disabled. */
     disabled: boolean;
     /** Whether this choice is in error mode. */
@@ -49,7 +49,6 @@ type Props = AriaProps & {
 };
 
 type DefaultProps = {
-    checked: Props["checked"];
     disabled: Props["disabled"];
     error: Props["error"];
 };
@@ -63,7 +62,6 @@ type DefaultProps = {
  * (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,
     };

package/src/components/radio-core.tsx

@@ -4,7 +4,7 @@ import {StyleSheet} from "aphrodite";
 import Color, {mix, fade} from "@khanacademy/wonder-blocks-color";
 import {addStyle} from "@khanacademy/wonder-blocks-core";
 
-import type {ChoiceCoreProps} from "../util/types";
+import type {ChoiceCoreProps, Checked} from "../util/types";
 
 const {blue, red, white, offWhite, offBlack16, offBlack32, offBlack50} = Color;
 
@@ -28,6 +28,7 @@ const StyledInput = addStyle("input");
             testId,
             ...sharedProps
         } = this.props;
+
         const stateStyles = _generateStyles(checked, error);
         const defaultStyle = [
             sharedStyles.inputReset,
@@ -44,7 +45,7 @@ const StyledInput = addStyle("input");
                     {...sharedProps}
                     type="radio"
                     aria-invalid={error}
-                    checked={checked}
+                    checked={checked ?? undefined}
                     disabled={disabled}
                     id={id}
                     name={groupName}
@@ -112,7 +113,7 @@ const colors = {
     },
 } as const;
 const styles: Record<string, any> = {};
-const _generateStyles = (checked: boolean, error: boolean) => {
+const _generateStyles = (checked: Checked, error: boolean) => {
     // "hash" the parameters
     const styleKey = `${String(checked)}-${String(error)}`;
     if (styles[styleKey]) {

package/src/util/types.ts

@@ -6,10 +6,13 @@ import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
 
 import Choice from "../components/choice";
 
+// Checkbox is in indeterminate state when `checked` is `null` | `undefined`
+export type Checked = boolean | null | undefined;
+
 // Shared props for radio-core and checkbox-core
 export type ChoiceCoreProps = AriaProps & {
     /** Whether this component is checked */
-    checked: boolean;
+    checked: Checked;
     /** Whether this component is disabled */
     disabled: boolean;
     /** Whether this component should show an error state */