leistungsbilanz-ts/docs/spec/04-ui-interaction-requirements.md

UI and Interaction Requirements

UI Philosophy

The circuit list editor should feel spreadsheet-like and efficient.

The main interaction surface is the table itself.

The table should not look like a form with permanently visible input fields in every cell.

Cells are displayed as static text by default and become editable only when the user intentionally edits them.

The editor should support both:

• efficient keyboard-based editing
• low-click mouse interaction
• drag-and-drop workflows

Cell Editing

Cells are displayed as static text by default.

A cell enters edit mode when the user:

• double-clicks it
• presses Enter while it is selected
• starts typing while it is selected
• presses F2 while it is selected

Editing behavior:

• Enter confirms the edit
• Tab confirms and moves to the next editable cell
• Shift + Tab confirms and moves to the previous editable cell
• Escape cancels the edit
• Arrow keys navigate between cells when not editing
• Arrow keys move the cursor inside text while editing

Row Insertion Shortcuts

The editor should support fast row insertion.

Required shortcuts:

• Ctrl + Plus inserts a new row below the selected row
• Ctrl + Shift + Plus should be treated the same where keyboard layouts require Shift for +
• Insert may optionally insert a new row below the selected row

Insert behavior:

• if a circuit or row is selected, insert below it
• if no row is selected, insert at the end of the active section
• the new row should immediately focus the display name or device cell

Project Device Sidebar

The distribution board editor should show the project device list near the circuit list.

Preferred layout:

• left sidebar: searchable project device list
• right main area: circuit list table

The project device sidebar should support:

• search by name
• filter by category
• filter by phase type
• filter by cost group
• showing device name
• showing default display name
• showing phase type
• showing quantity and power if available
• dragging devices into the circuit list

Drag Project Device into Circuit List

Project devices can be dragged from the project device sidebar into the circuit list.

Drop into a valid section or free circuit placeholder

Creates a new circuit.

The new circuit:

• receives the next equipment identifier of the target section
• is inserted at the drop position
• contains one device row linked to the dragged project device
• receives an initial display name copied from the project device
• keeps this copied display name locally

Drop onto an existing circuit identifier / circuit target

Adds the device to that existing circuit.

The app creates another device row inside that circuit.

The device row:

• has no own equipment identifier
• is linked to the project device
• contributes to the circuit total power
• appears indented when the circuit contains multiple devices

Free Circuit Placeholder

Each section should show a free circuit placeholder at the end.

Example:

Lighting
-1F1  Beleuchtung Flur
-1F2  Beleuchtung Außen
-frei-

If a device is dropped onto -frei-, a new circuit is created.

After creation, a new -frei- placeholder appears at the end of the section.

Valid Drop Zones

A project device may only be dropped into technically valid sections.

Default rules:

Condition	Valid section	Prefix
Category = Lighting	Lighting	-1F
Phase type = single-phase and not Lighting	Single-phase circuits	-2F
Phase type = three-phase and not Lighting	Three-phase circuits	-3F

Invalid drop targets should visually reject the dragged item.

If the user tries to move a device into another section, show a confirmation dialog.

The dialog should explain that moving to another section may change technical classification fields such as:

• phase type
• category
• numbering section

The user can confirm or cancel.

The app must not silently change project device data.

Drag Handle Behavior

Different drag start areas trigger different behavior.

Drag from equipment identifier / circuit handle

Moves the entire circuit.

All device rows assigned to the circuit move together.

The equipment identifier remains unchanged.

Drag from device area

Moves only the selected device row or selected device rows.

A device can be:

• reordered inside the same circuit
• moved to another existing circuit
• moved into the next free circuit placeholder
• moved to another valid section after confirmation

Moving Devices Between Circuits

A device row can be moved from one circuit to another.

When moved:

• it is removed from the old circuit
• it is assigned to the new circuit
• it keeps its own device values
• it contributes to the new circuit total
• both old and new circuit totals are recalculated
• no automatic renumbering happens

Convert Device to Own Circuit

A device row can be moved to a free circuit placeholder.

When this happens:

• a new circuit is created
• the device becomes the first device row of the new circuit
• the new circuit receives the next equipment identifier in the section
• a new free placeholder appears at the end

Multi-Row Selection and Dragging

The table should support selecting multiple rows.

Selection behavior:

• Ctrl + click selects or deselects individual rows
• Shift + click selects a continuous row range
• selected rows can be dragged together

When multiple selected device rows are moved:

• they remain together
• their internal order is preserved
• they are inserted as one block

When multiple selected circuits are moved:

• each selected circuit moves with all assigned device rows
• internal circuit/device structure is preserved
• equipment identifiers remain unchanged unless explicitly renumbered

Dropping rows at the end of a section compacts visual row order. It does not renumber equipment identifiers.

Delete Behavior

Deleting a device row deletes only that device.

The circuit itself remains as long as at least one device is assigned to it.

If the first visible device of a circuit is deleted and other devices remain, the next device moves up visually.

If the last device of a circuit is deleted, ask the user whether to:

• keep the empty circuit as reserve
• delete the circuit completely
• cancel

Deleting never triggers automatic renumbering.

Filtering and Sorting

The table should support Excel-like filtering and sorting through column headers.

Filtering

Each column header can open a filter menu.

The filter menu shows available values in that column.

The user can select one or more values.

Examples:

• filter by room number
• filter by room name
• filter by cost group
• filter by category
• filter by phase type
• filter by connection type

Sorting

Each column can be sorted ascending or descending.

Sorting via table headers sorts complete circuits as blocks.

A circuit and its assigned device rows stay together.

Sorting must not split devices away from their circuit.

Sorting changes only the visual order.

Equipment identifiers are not changed by sorting.

After sorting, the user may explicitly press "Renumber section".

Column Configuration

The table should support configurable columns.

Users can:

• show columns
• hide columns
• reorder columns by drag and drop
• reset to default column layout

Column visibility and order should be stored per user or per project.

Hidden columns remain stored and available for calculations.

Undo / Redo

Undo and redo should be implemented from the beginning for structural and destructive operations.

At minimum, undo / redo must support:

• insert circuit
• insert device
• delete circuit
• delete device
• move circuit
• move device
• move multiple selected rows
• renumber section
• edit equipment identifier
• edit cell value
• synchronize linked project device fields
• disconnect linked project device