# Componentization of Composebox

## Instruction for CL Authors

If you are reading this, you likely have reached here because your CL updates
`composebox.ts` or `cr_components/composebox/composebox_test.ts` and there is an
IFTTT warning about these files.

If your change does not introduce any new logic (e.g., formatting the file or a
cosmetic change), please add `NO_IFTTT=no logic added to composebox` tag and
continue the review.

Otherwise, please follow the steps below to resolve the warning. For more
information about why we are doing this, please read the
[Context section](#context).

## Instruction for Test Authors (`cr_components/.../composebox_test.ts`)

We have established a strict engineering policy: **Do NOT add new unit tests to
`cr_components/composebox/composebox_test.ts`.** Because `<cr-composebox>` is
being componentized into a lightweight default container, any modern addition
or bug fix naturally aligns with one of three distinct testing boundaries:

1. **Shared Core Logic (Mixin Test)**: Add tests for state orchestration, IPC
   communication, Smart Compose routing, and multi-modal attachments to
   `chrome/test/data/webui/cr_components/composebox/composebox_mixin_test.ts`.
2. **UI & DOM Rendering (Subcomponents)**: Add tests for component-specific
   DOM rendering and user interaction to isolated unit test suites in
   `cr_components/composebox/` (e.g., `file_carousel_test.ts`,
   `file_thumbnail_test.ts`, `error_scrim_test.ts`).
3. **End-to-End Surface Workflows (Embedders)**: Add tests for surface-specific
   slottings, permissions, and host integrations directly to surface-specific
   embedder test suites (e.g., `omnibox_popup/`, `contextual_tasks/`, or
   `new_tab_page/composebox/composebox_test.ts`).

`cr_components/composebox/composebox_test.ts` is in maintenance mode and will be
deleted once remaining legacy test cases are absorbed into the mixin and
embedders.

## Steps to Follow

There are two cases:

1. Your logic/methods are used by multiple (>= 2) surfaces.
2. Your logic/methods are used by only one surface (Cobrowse, NTP, or Omnibox).

Once one of the sets of steps below is taken, please add
`NO_IFTTT=added a componentization reviewer` tag and continue the review.

If you are unsure about what to do, please add an owner from the OWNERS file to
the reviewers list with a comment containing your question.

### Case 1: Shared Logic/Methods

1. Move the logic to `ComposeboxEmbedderMixin` in
   `ui/webui/resources/cr_components/composebox/composebox_mixin.ts` and remove
   the logic from `composebox.ts`.

2. Add any of the owners to the reviewer list.

### Case 2: Surface-specific Logic/Methods

Please do the following depending on which surface uses your methods and then
add an owner from the OWNERS file to the reviewers list.

#### Cobrowse/Contextual Tasks

Please add a comment
`"// TODO: crbug.com/486707842 - Move to the Contextual Tasks embedder"` to the
methods/logic added, and then add `jilinyang@` to the cc list.

#### NTP

Please update `NtpComposeboxElement` in
`chrome/browser/resources/new_tab_page/ntp_composebox.ts` in addition to
`composebox.ts`.
______________________________________________________________________

## Context

The `cr-composebox` component was originally designed as a monolithic component.
As more surfaces (such as NTP Realbox, Omnibox, and Cobrowse) began to use and
customize it, the file `composebox.ts` accumulated surface-specific logic. This
led to a complex, hard-to-maintain codebase where changes for one surface could
inadvertently affect others, and the file became a bottleneck for development.

## Decision

We decided to componentize the `cr-composebox` architecture to separate shared
logic from surface-specific implementations.

1. **Shared Logic**: Core behaviors and common features are extracted into
   `ComposeboxEmbedderMixin`.
2. **Surface-Specific Logic**: Features unique to a specific surface should be
   implemented in that surface's specific embedder.
3. **Ownership**: Members listed in OWNERS file should ensure that changes are
   properly reviewed. It is these owners' responsibility to enforce the
   separation of logic above.
4. **Enforcement (Temporary)**: We added an IFTTT (If This Then That) check on
   `composebox.ts` to ensure that new methods are properly evaluated and placed
   either in the mixin or marked for moving to an embedder. This IFTTT should be
   removed when `composebox.ts` is removed at the end of the componentization
   project.

## Consequences

### Positive

- **Modularity**: Clear separation of concerns between shared logic and
  surface-specific UI.
- **Maintainability**: Reduced risk of regressions when updating specific
  surfaces.
- **Scalability**: Easier to add new surfaces or features without cluttering the
  shared codebase.

### Negative/Friction

- **Developer Friction**: Authors modifying `composebox.ts` must follow extra
  steps, add specific TODOs, and seek review from the componentization team.
- **Complexity**: Moving to a mixin-based architecture introduces some
  indirection compared to a single monolithic file.