# Bank Composition Base Components Decision

Status: Decided
Cycle: 2026-03
Domain Owner: `docs/studio`
Cross-Domain Impact: `docs/packer`

## Context

The `Bank Composition` section inside `Asset Details` depends on two new Studio components:

- `StudioDualListView<T>`
- `StudioAssetCapacityMeter`

These components need a first-wave contract before the section shell, middleware, and persistence work can proceed safely.

The DTO projection boundary was already closed in:

- [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)

This decision closes the first-wave component direction discussed in:

- [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](../agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md)

## Decision

Adopt narrow, bank-composition-scoped first-wave components.

The component choices are:

1. `StudioDualListView<T>` remains an abstract Studio component;
2. the first concrete implementation is asset-details-specific;
3. `StudioAssetCapacityMeter` is a dumb visual component for vertical capacity display;
4. neither component should own bank-family product rules.

`StudioDualListView<T>` should expose only the hooks needed by the first `Bank Composition` wave:

- row text and/or row graphic projection;
- current left and right collections;
- current selection state;
- move left-to-right;
- move right-to-left;
- `moveUp`;
- `moveDown`;
- visible right-list index refresh.

The first asset-details concrete subclass should render rows directly.
Do not introduce a separate row-renderer abstraction in this first wave.

`StudioAssetCapacityMeter` starts with these baseline inputs:

- `progress` in the `0..1` range;
- a label, including percentage text when needed;
- a severity-band state;
- optional hint text.

## Justification

This keeps component scope small and aligned with the current implementation plan.

The decision avoids two common mistakes:

- overengineering highly generic components before the first section exists;
- burying section behavior directly inside `Asset Details` with no named component boundary.

Direct row rendering in the first concrete dual-list implementation is the pragmatic choice.
There is no current evidence that a standalone row-renderer abstraction is needed.

Keeping `StudioAssetCapacityMeter` dumb also protects the future middleware/controller boundary.
Family-specific rules should not leak into the visual component.

## Invariants and Constraints

The following constraints now apply:

1. `StudioDualListView<T>` must remain abstract in the first wave;
2. the first concrete `StudioDualListView<T>` implementation belongs to the asset-details flow;
3. right-list ordering support must include `moveUp`, `moveDown`, and visible indices;
4. `StudioAssetCapacityMeter` must remain visual and state-driven, not rule-driven;
5. bank-family capacity logic remains outside both components.

## Explicit Non-Decisions

This decision does not yet define:

- the Java package layout or exact class names for the first concrete asset-details subclass;
- the `Bank Composition` section shell layout details;
- the middleware/controller contract;
- the `workspaceBus` event contract;
- persistence or apply behavior.

## Propagation Targets

- Studio agendas:
  [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md)
  [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
  [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
  [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
- Studio specs:
  [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Studio code:
  future component classes for `StudioDualListView<T>`, the first asset-details concrete implementation, and `StudioAssetCapacityMeter`

## Validation Notes

Examples implied by this decision:

- the right/build list can be reordered through `moveUp` and `moveDown`;
- the right/build list can display visible indices without requiring middleware-specific rendering logic;
- the capacity meter can show green, orange, or red state based on inputs from higher-level orchestration without knowing tile or sound rules.