Documentation

docs/circuit-list-editor-interactions.md

@@ -0,0 +1,109 @@
+# 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