prometeu-studio/docs/studio/decisions/Bank Composition Base Components Decision.md

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

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

• 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 Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md
• Studio specs: 4. Assets Workspace Specification.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.