WB-1779: Add startIcon prop to Combobox

.changeset/old-pears-fix.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-dropdown": minor
+---
+
+Add `startIcon` prop to Combobox

__docs__/wonder-blocks-dropdown/combobox.stories.tsx

@@ -4,10 +4,13 @@ import {Meta, StoryObj} from "@storybook/react";
 import {expect, userEvent, within} from "@storybook/test";
 import {StyleSheet} from "aphrodite";
 import * as React from "react";
-import {LabelLarge} from "@khanacademy/wonder-blocks-typography";
-import {color, spacing} from "@khanacademy/wonder-blocks-tokens";
+import magnifyingGlassIcon from "@phosphor-icons/core/bold/magnifying-glass-bold.svg";
+
+import {LabelLarge, LabelMedium} from "@khanacademy/wonder-blocks-typography";
+import {color, semanticColor, spacing} from "@khanacademy/wonder-blocks-tokens";
 import {Checkbox} from "@khanacademy/wonder-blocks-form";
 import {Combobox, OptionItem} from "@khanacademy/wonder-blocks-dropdown";
+import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon";
 import {PropsFor, View} from "@khanacademy/wonder-blocks-core";
 import {allProfilesWithPictures} from "./option-item-examples";
 
@@ -428,3 +431,85 @@ export const Error: Story = {
         error: true,
     },
 };
+
+/**
+ * With `startIcon`, you can customize the icon that appears at the beginning of
+ * the Combobox. This is useful when you want to add a custom icon to the
+ * component.
+ *
+ * **NOTE:** When `startIcon` is set, we set some default values for the icon:
+ * - `size`: "small"
+ * - `color`: `semanticColor.icon.default`
+ *
+ * You can customize the size and color of the icon by passing the `size` and
+ * `color` props to the `PhosphorIcon` component.
+ */
+export const StartIcon: Story = {
+    render: function Render(args: PropsFor<typeof Combobox>) {
+        const [_, updateArgs] = useArgs();
+
+        return (
+            <View style={{gap: spacing.medium_16}}>
+                <LabelMedium>With default size and color:</LabelMedium>
+                <Combobox
+                    {...args}
+                    startIcon={
+                        <PhosphorIcon icon={magnifyingGlassIcon} size="small" />
+                    }
+                    onChange={(newValue) => {
+                        updateArgs({value: newValue});
+                        action("onChange")(newValue);
+                    }}
+                />
+                <LabelMedium>With custom size:</LabelMedium>
+                <Combobox
+                    {...args}
+                    startIcon={
+                        <PhosphorIcon
+                            icon={magnifyingGlassIcon}
+                            size="medium"
+                        />
+                    }
+                    onChange={(newValue) => {
+                        updateArgs({value: newValue});
+                        action("onChange")(newValue);
+                    }}
+                />
+                <LabelMedium>With custom color:</LabelMedium>
+                <Combobox
+                    {...args}
+                    startIcon={
+                        <PhosphorIcon
+                            icon={magnifyingGlassIcon}
+                            size="small"
+                            color={semanticColor.icon.action}
+                        />
+                    }
+                    onChange={(newValue) => {
+                        updateArgs({value: newValue});
+                        action("onChange")(newValue);
+                    }}
+                />
+                <LabelMedium>Disabled (overrides color prop):</LabelMedium>
+                <Combobox
+                    {...args}
+                    startIcon={
+                        <PhosphorIcon
+                            icon={magnifyingGlassIcon}
+                            size="small"
+                            color={semanticColor.icon.action}
+                        />
+                    }
+                    disabled={true}
+                    onChange={(newValue) => {
+                        updateArgs({value: newValue});
+                        action("onChange")(newValue);
+                    }}
+                />
+            </View>
+        );
+    },
+    args: {
+        children: items,
+    },
+};

packages/wonder-blocks-dropdown/src/components/__tests__/combobox.test.tsx

@@ -1,12 +1,14 @@
-import * as React from "react";
-import {render, screen, waitFor} from "@testing-library/react";
 import {RenderStateRoot} from "@khanacademy/wonder-blocks-core";
+import {render, screen, waitFor} from "@testing-library/react";
+import * as React from "react";
+import magnifyingGlassIcon from "@phosphor-icons/core/regular/magnifying-glass.svg";
 
+import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon";
 import {PointerEventsCheckLevel, userEvent} from "@testing-library/user-event";
-import Combobox from "../combobox";
-import OptionItem from "../option-item";
 import {defaultComboboxLabels} from "../../util/constants";
 import {MaybeValueOrValues} from "../../util/types";
+import Combobox from "../combobox";
+import OptionItem from "../option-item";
 
 const doRender = (element: React.ReactElement) => {
     render(element, {wrapper: RenderStateRoot});
@@ -305,6 +307,31 @@ describe("Combobox", () => {
         expect(screen.getByRole("combobox")).not.toHaveFocus();
     });
 
+    it("should include an icon at the beginning of the combobox", () => {
+        // Arrange
+
+        // Act
+        doRender(
+            <Combobox
+                selectionType="single"
+                value=""
+                startIcon={
+                    <PhosphorIcon
+                        icon={magnifyingGlassIcon}
+                        testId="start-icon"
+                    />
+                }
+            >
+                <OptionItem label="option 1" value="option1" />
+                <OptionItem label="option 2" value="option2" />
+                <OptionItem label="option 3" value="option3" />
+            </Combobox>,
+        );
+
+        // Assert
+        expect(screen.getByTestId("start-icon")).toBeInTheDocument();
+    });
+
     describe("dismiss button", () => {
         it("should clear the value when the user presses the clear button (x) via Mouse", async () => {
             // Arrange

packages/wonder-blocks-dropdown/src/components/combobox.tsx

@@ -11,9 +11,15 @@ import {
 } from "@khanacademy/wonder-blocks-core";
 import {TextField} from "@khanacademy/wonder-blocks-form";
 import IconButton from "@khanacademy/wonder-blocks-icon-button";
-import {border, color, spacing} from "@khanacademy/wonder-blocks-tokens";
+import {
+    border,
+    color,
+    semanticColor,
+    spacing,
+} from "@khanacademy/wonder-blocks-tokens";
 
 import {DetailCell} from "@khanacademy/wonder-blocks-cell";
+import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon";
 import {useListbox} from "../hooks/use-listbox";
 import {useMultipleSelection} from "../hooks/use-multiple-selection";
 import {
@@ -132,6 +138,13 @@ type Props = {
      */
     // TODO(WB-1740): Add support to `inline` and `both` values.
     autoComplete?: "none" | "list" | undefined;
+
+    /**
+     * An optional decorative icon to display at the start of the combobox.
+     */
+    startIcon?: React.ReactElement<
+        React.ComponentProps<typeof PhosphorIcon>
+    > | null;
 };
 
 /**
@@ -158,6 +171,7 @@ export default function Combobox({
     opened,
     placeholder,
     selectionType = "single",
+    startIcon,
     testId,
     value = "",
 }: Props) {
@@ -477,6 +491,30 @@ export default function Combobox({
         return [labelFromSelected];
     }, [children, labelFromSelected, selected]);
 
+    /**
+     * Renders the start icon if provided.
+     */
+    const maybeRenderStartIcon = () => {
+        if (!startIcon) {
+            return null;
+        }
+
+        const startIconElement = React.cloneElement(startIcon, {
+            // Provide a default size for the icon that can be overridden by
+            // the consumer.
+            size: "small",
+            ...startIcon.props,
+            // Override the disabled state of the icon to match the combobox
+            // state.
+            color: disabled
+                ? color.offBlack32
+                : // Use the color passed in, otherwise use the default color.
+                  startIcon.props.color ?? semanticColor.icon.primary,
+        } as Partial<React.ReactElement<React.ComponentProps<typeof PhosphorIcon>>>);
+
+        return <View style={styles.iconWrapper}>{startIconElement}</View>;
+    };
+
     const pillIdPrefix = id ? `${id}-pill-` : ids.get("pill");
 
     const currentActiveDescendant = !openState
@@ -534,6 +572,8 @@ export default function Combobox({
                         removeSelectedLabel={labels.removeSelected}
                     />
                 )}
+                {maybeRenderStartIcon()}
+
                 <TextField
                     id={ids.get("input")}
                     testId={testId}
@@ -739,4 +779,11 @@ const styles = StyleSheet.create({
         // This is calculated based on the padding + width of the arrow button.
         right: spacing.xLarge_32 + spacing.xSmall_8,
     },
+    iconWrapper: {
+        padding: spacing.xxxSmall_4,
+        // View has a default minWidth of 0, which causes the label text
+        // to encroach on the icon when it needs to truncate. We can fix
+        // this by setting the minWidth to auto.
+        minWidth: "auto",
+    },
 });