[origin] Default combobox clear to active (#28544)

## Reason

[DES-36](https://lightspark.atlassian.net/browse/DES-36) needs
edit-existing forms to avoid showing a noisy clear affordance for saved
country/nationality values until the user is actually interacting with
the field. Origin now makes that active behavior the default so
consumers get the quieter edit-existing state without product-level
props.

## Overview

Adds `visibility` to `Combobox.Clear` with `active` and `always` modes
while preserving Base UI's ownership of clear behavior and clearable
state.

`active` is the new default: the clear affordance is hidden at rest and
appears while the field is focused or open. This intentionally changes
existing `<Combobox.Clear />` consumers from "always visible when
clearable" to "visible while active when clearable." Consumers that need
the previous/create-flow behavior can opt into `visibility="always"`.
Consumers that should not expose a clear affordance should omit
`<Combobox.Clear />`.

## QA Notes

Existing Combobox.Clear consumers should be checked with the new default
in mind:

- Edit-existing surfaces should no longer show the clear icon at rest
when they load with saved values.
- Focusing/opening the combobox should reveal the clear affordance when
Base UI reports a clearable value.
- Create/select flows that want the clear icon visible while a value
exists should use `visibility="always"`.
- Flows that should not offer clearing should omit `<Combobox.Clear />`.

## Storybook preview

- Components/Combobox / Default:
https://dev.dev.sparkinfra.net/app/origin-storybook-pr-28544/?path=/story/components-combobox--default
- Components/Combobox / Default Active Clear:
https://dev.dev.sparkinfra.net/app/origin-storybook-pr-28544/?path=/story/components-combobox--with-clear
- Components/Combobox / Always Clear:
https://dev.dev.sparkinfra.net/app/origin-storybook-pr-28544/?path=/story/components-combobox--always-clear

## Test Plan

- `mise exec -- node -v` -> `v20.19.6`
- `mise exec -- corepack yarn --version` -> `4.13.0`
- `mise exec -- corepack yarn workspace @lightsparkdev/origin playwright
test -c playwright-ct.config.ts
src/components/Combobox/Combobox.test.tsx`
- `mise exec -- corepack yarn workspace @lightsparkdev/origin types`
- `mise exec -- corepack yarn workspace @lightsparkdev/origin lint`
(passes with existing warnings in DatePicker/Sidebar)
- `mise exec -- corepack yarn workspace @lightsparkdev/origin format`

[DES-36]:
https://lightspark.atlassian.net/browse/DES-36?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
GitOrigin-RevId: 9423d49750e801bb7e60f4a26b75457040dd226d

Author: 2 people

packages/origin/src/components/Combobox/Combobox.module.scss

@@ -24,7 +24,10 @@
     padding-left: var(--spacing-2xs);
   }
 
-  &:has(.clear:not([hidden])) {
+  &:has(.clearAlways:not([hidden])),
+  &:focus-within:has(.clearActive:not([hidden])),
+  &[data-focused]:has(.clearActive:not([hidden])),
+  &[data-popup-open]:has(.clearActive:not([hidden])) {
     padding-right: calc(var(--spacing-xs) + 42px);
   }
 
@@ -129,7 +132,6 @@
 
 .clear {
   box-sizing: border-box;
-  display: flex;
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
@@ -157,6 +159,20 @@
   }
 }
 
+.clearActive {
+  display: none;
+}
+
+.inputWrapper:focus-within .clearActive:not([hidden]),
+.inputWrapper[data-focused] .clearActive:not([hidden]),
+.inputWrapper[data-popup-open] .clearActive:not([hidden]) {
+  display: flex;
+}
+
+.clearAlways:not([hidden]) {
+  display: flex;
+}
+
 .clear svg {
   width: 17px;
   height: 17px;

packages/origin/src/components/Combobox/Combobox.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
-import { Combobox } from "./index";
+import { Combobox, type ComboboxClearProps } from "./index";
 import { Field } from "@/components/Field";
 
 const meta: Meta<typeof Combobox.Root> = {
@@ -36,6 +36,14 @@ export const Default: Story = {
   args: {
     disabled: false,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "No-clear reference. Omit Combobox.Clear when a flow should not expose a clear affordance.",
+      },
+    },
+  },
   render: (args) => (
     <Combobox.Root items={fruits} {...args}>
       <Combobox.InputWrapper>
@@ -91,13 +99,22 @@ export const LongList: Story = {
   ),
 };
 
-export const WithClear: Story = {
-  render: () => (
+function ClearStory({
+  visibility,
+  label,
+}: {
+  visibility?: ComboboxClearProps["visibility"];
+  label: string;
+}) {
+  return (
     <Combobox.Root items={fruits} defaultValue="Apple">
       <Combobox.InputWrapper>
-        <Combobox.Input placeholder="Select a fruit..." />
+        <Combobox.Input placeholder={label} />
         <Combobox.ActionButtons>
-          <Combobox.Clear aria-label="Clear selection" />
+          <Combobox.Clear
+            aria-label="Clear selection"
+            visibility={visibility}
+          />
           <Combobox.Trigger aria-label="Open popup" />
         </Combobox.ActionButtons>
       </Combobox.InputWrapper>
@@ -117,7 +134,32 @@ export const WithClear: Story = {
         </Combobox.Positioner>
       </Combobox.Portal>
     </Combobox.Root>
-  ),
+  );
+}
+
+export const WithClear: Story = {
+  name: "Default Active Clear",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Default edit-existing flow. The clear affordance is hidden at rest, appears while the field is focused or open, and is removed by Base UI once the value is cleared.",
+      },
+    },
+  },
+  render: () => <ClearStory label="Edit saved fruit..." />,
+};
+
+export const AlwaysClear: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Opt in when a clear affordance should remain visible while the value is clearable. Base UI still removes it once the value is cleared.",
+      },
+    },
+  },
+  render: () => <ClearStory label="Select a fruit..." visibility="always" />,
 };
 
 function MultipleField({

packages/origin/src/components/Combobox/Combobox.test-stories.tsx

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { useState } from "react";
-import { Combobox } from "./index";
+import { Combobox, type ComboboxClearProps } from "./index";
 
 const fruits = [
   "Apple",
@@ -307,12 +307,22 @@ export const TestComboboxWithGroups = () => (
   </Combobox.Root>
 );
 
-export const TestComboboxWithClear = () => (
+export const TestComboboxWithClear = ({
+  clearClassName,
+  visibility,
+}: {
+  clearClassName?: ComboboxClearProps["className"];
+  visibility?: ComboboxClearProps["visibility"];
+} = {}) => (
   <Combobox.Root items={fruits} defaultValue="Apple">
-    <Combobox.InputWrapper>
+    <Combobox.InputWrapper data-testid="combobox-clear-wrapper">
       <Combobox.Input placeholder="Select a fruit..." />
       <Combobox.ActionButtons>
-        <Combobox.Clear aria-label="Clear selection" />
+        <Combobox.Clear
+          aria-label="Clear selection"
+          className={clearClassName}
+          visibility={visibility}
+        />
         <Combobox.Trigger aria-label="Open popup" />
       </Combobox.ActionButtons>
     </Combobox.InputWrapper>
@@ -333,3 +343,10 @@ export const TestComboboxWithClear = () => (
     </Combobox.Portal>
   </Combobox.Root>
 );
+
+export const TestComboboxWithClearClassNameCallback = () => (
+  <TestComboboxWithClear
+    clearClassName={(state) => (state.open ? "clear-open" : "clear-closed")}
+    visibility="always"
+  />
+);

packages/origin/src/components/Combobox/Combobox.test.tsx

@@ -8,6 +8,7 @@ import {
   TestComboboxControlled,
   TestComboboxWithGroups,
   TestComboboxWithClear,
+  TestComboboxWithClearClassNameCallback,
   TestComboboxChipPassThrough,
   ConformanceInputWrapper,
   ConformanceActionButtons,
@@ -270,14 +271,103 @@ test.describe("Combobox", () => {
   });
 
   test.describe("clear button", () => {
-    test("clears selection on click", async ({ mount }) => {
+    test("defaults to active visibility and clears selection on click", async ({
+      mount,
+      page,
+    }) => {
       const component = await mount(<TestComboboxWithClear />);
       const input = component.getByPlaceholder("Select a fruit...");
-      const clear = component.locator('button[class*="clear"]');
+      const clear = component.getByRole("button", {
+        name: "Clear selection",
+        includeHidden: true,
+      });
+
+      await expect(input).toHaveValue("Apple");
+      await expect(clear).toHaveCSS("display", "none");
+
+      await input.click();
+      await expect(page.getByRole("listbox")).toBeVisible();
+      await expect(clear).toBeVisible();
+      await clear.click();
+      await expect(input).toHaveValue("");
+    });
+
+    test("always clear remains visible while clearable", async ({ mount }) => {
+      const component = await mount(
+        <TestComboboxWithClear visibility="always" />,
+      );
+      const input = component.getByPlaceholder("Select a fruit...");
+      const clear = component.getByRole("button", { name: "Clear selection" });
 
       await expect(input).toHaveValue("Apple");
+      await expect(clear).toBeVisible();
+      await expect(clear).not.toHaveAttribute("visibility", "always");
+      await expect(clear).not.toHaveAttribute(
+        "data-clear-visibility",
+        "always",
+      );
       await clear.click();
       await expect(input).toHaveValue("");
+      await expect(clear).toBeHidden();
+    });
+
+    test("preserves Base UI stateful clear className callback", async ({
+      mount,
+    }) => {
+      const component = await mount(<TestComboboxWithClearClassNameCallback />);
+      const clear = component.getByRole("button", { name: "Clear selection" });
+
+      await expect(clear).toHaveClass(/clear-closed/);
+    });
+
+    test("active clear is hidden at rest and appears while focused or open", async ({
+      mount,
+      page,
+    }) => {
+      const component = await mount(
+        <TestComboboxWithClear visibility="active" />,
+      );
+      const input = component.getByPlaceholder("Select a fruit...");
+      const wrapper = page.getByTestId("combobox-clear-wrapper");
+      const clear = component.getByRole("button", {
+        name: "Clear selection",
+        includeHidden: true,
+      });
+
+      const restingPadding = await wrapper.evaluate((element) =>
+        Number.parseFloat(window.getComputedStyle(element).paddingRight),
+      );
+
+      await expect(input).toHaveValue("Apple");
+      await expect(clear).toHaveCSS("display", "none");
+      await expect(
+        component.getByRole("button", { name: "Clear selection" }),
+      ).toBeHidden();
+
+      await input.click();
+      await expect(page.getByRole("listbox")).toBeVisible();
+      await expect(clear).toBeVisible();
+
+      const activePadding = await wrapper.evaluate((element) =>
+        Number.parseFloat(window.getComputedStyle(element).paddingRight),
+      );
+      expect(activePadding).toBeGreaterThan(restingPadding);
+
+      await clear.click();
+      await expect(input).toHaveValue("");
+    });
+
+    test("omitting Clear does not render the clear affordance", async ({
+      mount,
+    }) => {
+      const component = await mount(<TestCombobox />);
+
+      await expect(
+        component.getByRole("button", {
+          name: "Clear selection",
+          includeHidden: true,
+        }),
+      ).toHaveCount(0);
     });
   });
 

packages/origin/src/components/Combobox/index.ts

@@ -9,6 +9,7 @@ export type {
   ActionButtonsProps as ComboboxActionButtonsProps,
   TriggerProps as ComboboxTriggerProps,
   ClearProps as ComboboxClearProps,
+  ClearVisibility as ComboboxClearVisibility,
   PortalProps as ComboboxPortalProps,
   PositionerProps as ComboboxPositionerProps,
   PopupProps as ComboboxPopupProps,

packages/origin/src/components/Combobox/parts.tsx

@@ -141,22 +141,53 @@ export const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(
   },
 );
 
-export interface ClearProps extends BaseCombobox.Clear.Props {}
+export type ClearVisibility = "always" | "active";
+
+export interface ClearProps
+  extends Omit<BaseCombobox.Clear.Props, "keepMounted"> {
+  /**
+   * Controls when Origin shows the clear affordance. Base UI still owns the
+   * clear behavior and whether a value is currently clearable. Defaults to
+   * "active", which shows the affordance while the field is focused or open.
+   */
+  visibility?: ClearVisibility;
+  /**
+   * Unsupported in Origin. Clear visibility relies on Base UI unmounting or
+   * hiding the button when the value is not clearable.
+   */
+  keepMounted?: never;
+}
 
 /**
  * Combobox.Clear - Button to clear the selection.
  *
  * Renders as a small icon button with the X icon.
- * Uses Base UI's default behavior - only visible when there's a value to clear.
+ * Uses Base UI's default behavior - only rendered when there's a value to clear.
  */
 export const Clear = React.forwardRef<HTMLButtonElement, ClearProps>(
-  function Clear({ className, children, ...props }, ref) {
+  function Clear(
+    {
+      className,
+      children,
+      keepMounted: _keepMounted,
+      visibility = "active",
+      ...props
+    },
+    ref,
+  ) {
+    const originClassName = [
+      styles.clear,
+      visibility === "active" && styles.clearActive,
+      visibility === "always" && styles.clearAlways,
+    ];
+    const clearClassName =
+      typeof className === "function"
+        ? (state: BaseCombobox.Clear.State) =>
+            clsx(originClassName, className(state))
+        : clsx(originClassName, className);
+
     return (
-      <BaseCombobox.Clear
-        ref={ref}
-        className={clsx(styles.clear, className)}
-        {...props}
-      >
+      <BaseCombobox.Clear ref={ref} className={clearClassName} {...props}>
         {children ?? <CentralIcon name="IconCircleX" size={17} />}
       </BaseCombobox.Clear>
     );

packages/origin/src/index.ts

@@ -37,6 +37,10 @@ export type {
 export { Checkbox } from "./components/Checkbox";
 export { Command } from "./components/Command";
 export { Combobox } from "./components/Combobox";
+export type {
+  ComboboxClearProps,
+  ComboboxClearVisibility,
+} from "./components/Combobox";
 export { ContextMenu } from "./components/ContextMenu";
 export { Dialog } from "./components/Dialog";
 export { Drawer, createHandle } from "./components/Drawer";

packages/origin/tsconfig.json

@@ -15,7 +15,7 @@
       "@test-utils/*": ["./test-utils/*"]
     }
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "include": ["src/**/*.ts", "src/**/*.tsx", "type-tests/**/*.tsx"],
   "exclude": [
     "node_modules",
     "tools",

packages/origin/type-tests/combobox-clear.tsx

@@ -0,0 +1,7 @@
+import { Combobox } from "../src";
+
+<Combobox.Clear className={(state) => (state.open ? "open" : "closed")} />;
+
+// Origin clear visibility depends on Base UI owning mount/hidden state.
+// @ts-expect-error keepMounted is intentionally not part of the Origin API.
+<Combobox.Clear keepMounted />;