leistungsbilanz-ts/docs/circuit-list-editor-interactions.md

Circuit List Editor Interactions

Editing Model

Inline cells are static text by default. A cell enters edit mode by:

• double-click
• Enter
• F2
• typing a printable character (type-to-edit)

Enter confirms changes. Escape cancels current edit draft. Tab and Shift+Tab confirm and move to next/previous editable cell.

selectedCell vs editingCell

• selectedCell tracks spreadsheet navigation focus.
• editingCell tracks active input draft (draft, edit mode, focus token).

The editor can have a selected cell without an active editor input. editingCell is only set while editing.

Normalized Visible Grid

The UI works from a normalized visibleRows model built from filtered/sorted sections:

• section header rows
• circuit rows (circuitCompact, circuitSummary, reserveCircuit)
• device rows (deviceRow)
• section placeholder rows (placeholder)

Selection, keyboard movement, and editability checks run against this normalized grid, not directly against nested API JSON.

Keyboard Behavior

• Enter: start edit (when not editing) or commit (when editing input)
• F2: start edit on selected cell
• Escape: cancel edit draft, or clear multi-row selection when not editing
• Tab / Shift+Tab: move between editable cells (commits active edit)
• arrow keys: move selected cell in grid when not editing
• type-to-edit: printable keys open edit mode and replace current display value with typed character

-frei- Placeholder Behavior

Each section has a trailing placeholder row showing -frei- in BMK column:

• serves as drop target for creating new circuits from project devices or moved rows
• editable placeholder cells can create a new circuit + first row through the same edit command flow

Add Circuit Behavior

Add-circuit actions create reserve circuits in the active section using the section prefix and next numeric suffix (max + 1).
No automatic gap-filling or global renumbering is performed.

Drag-and-Drop Behavior

Intent is separated by drag source type:

• project device drag:
  • drop to section/placeholder -> create new circuit with linked row
  • drop to existing circuit row -> append row to that circuit
• device row drag:
  • drop to existing circuit -> move row(s) into that circuit
  • drop to placeholder -> create new target circuit and move row(s)
• circuit drag (BMK handle):
  • reorder circuits inside same section only
  • cross-section reorder is rejected
• bulk device row move:
  • supported via multi-selection + drag
• multi-circuit move:
  • supported for same-section selected circuit blocks

Filtering and Sorting

• Per-column filtering works on normalized displayed values.
• Sorting is view-level first and treats circuits as blocks.
• Multi-device circuits are not split during sort.
• Sorting alone does not persist order.

Apply Sorted Order

Apply sorted order persists current sorted block order to backend by section.

• disabled while filters are active
• undoable via command history
• until applied, sort remains view-only

Column Configuration

• Column visibility and order are configurable.
• BMK column (equipmentIdentifier) is locked as first column.
• Layout is saved in local storage (circuitTreeEditor.columnLayout.v1).

Undo/Redo

Undo/redo wraps editor operations as command objects with async redo/undo and reloads tree after each command.

Covered operations include:

• insert/delete circuit
• insert/delete row
• edit cell values
• moves (single/bulk rows, circuit reorder)
• renumber and identifier update flows
• apply sorted order

Current limitations:

• session-local only
• no persisted history across browser reload
• some multi-step backend flows are not fully transaction-hardened end-to-end