# UI Design

## Environment Baseline

* Confirmation popup source identity is configurable via `MAILSHOTS_UI_SOURCE_LABEL`.
* Default value for `MAILSHOTS_UI_SOURCE_LABEL` is `Mailshots`.

## Purpose

Define user interface requirements common to all pages.

## Top-Level Layout

* Use WordPress admin-page navigation as the canonical navigation model.
* Each plugin page should render its own content region within the standard WordPress admin page layout.

## Navigation

* Implement navigation as a set of WordPress Admin Pages under the FECA Mailshots plugin admin entry.

## Content Pane

* Constrain content pane to one visible screen page.
* When content exceeds available space, scroll inside the content pane.
* Structure the pane into these regions as applicable:
  * context pane (top left)
  * information pane (optional)
  * statistics pane (optional)
  * actions / filter pane (optional)
  * data pane (optional)

## Standard Page Regions

For pages using info/statistics/actions/data regions:

* Place information pane at top-right for hints, feedback, and errors.
* Place statistics pane at top between context area and information pane.
* Place actions pane below top panes.
* Place data pane below top panes/actions.
* Keep controls visible while allowing internal scrolling in the data pane.
* Avoid horizontal scrolling when content width can be adjusted to prevent it.

### Multi-Pane Data Areas

* If a data area contains two or more sibling panes, provide a draggable divider between adjacent panes.
* Use vertical dividers for left/right panes and horizontal dividers for top/bottom panes.
* Persist user-adjusted split ratios per page.
* On narrow viewports, collapse split layouts to a vertical stack and disable drag interaction.
* Keep each pane independently scrollable when content exceeds pane bounds.

## Common UX Rules

* Use configured `MAILSHOTS_UI_SOURCE_LABEL` as source identity in confirmation popups.
* Hide CRUD forms when not in use.
* Use red visual treatment for destructive actions.
* Provide spacing between action buttons and panel edges.
* Use "Save" / "Quit" to save (and leave) a modal or "Quit" to leave it.
* If "Save" fails - display a message in the modal and do not leave the modal.
* Under no conditions allow a user-entry error to lose user entered data - always allow them a way to recover without reentering work.
* If an operation takes a long time (more than 1s),  display a progress message while the operation is taking place, and remove it afterwards.
* Keep control labels and the controls they label together.
* Allow both vertical and horizontal space between controls.

## Default Table Behavior

* Allow user-resizable widths for all displayed table columns, including in Firefox-derived browsers.
* Use edge-drag column resizing with no explicit/visible drag-handle element.
* Persist column widths per table.
* Where a table supports sorting, provide:
  * a `Sort by` dropdown listing sortable columns
  * an adjacent direction dropdown with options `Ascending` and `Descending`
* Do not use per-column header sort controls.
* Keep any `Actions` column non-sortable.
* If a page-specific rule conflicts with default table behavior, page-specific rule takes precedence.

## Resize Stability Requirements

* Do not trigger data reloads during column resize interactions.
* Keep table visible while dragging a column-resize handle.
* Do not show transient loading states during resize unless a real refresh is explicitly requested.
* Ensure resize-state updates (for example column widths) do not alter API request dependencies for table-load effects.
* Keep API client functions used in effect dependencies referentially stable across normal UI rerenders (for example resize, hover, selection changes).
