# Contextual Actions And Stray Surfaces

## Recommendation

Create one shared UI contract for dropped functionality that does not deserve its own product shell.

The default answer for stray functionality should be one of these placements, in order:

1. owner product submenu
2. owner page tab
3. segmented list mode
4. right rail or drawer
5. full detail page under the owner shell

This contract should guide both IA decisions and implementation primitives across watchlist, reachability, triage, workflow replay, and operations.

## Why This Is Needed

- Many dropped Stella Ops components are useful ideas but too narrow to justify a new sidebar branch.
- Without shared rules, every restoration topic risks inventing its own panel, query-param, and deep-link behavior.
- Operators need consistent navigation and return-to-context behavior across shells.
- A common contract reduces FE churn and makes later restorations easier to place.

## Placement Hierarchy

### 1. Submenu
Use when the capability is owner-owned, low-frequency, and configuration-heavy.

Examples:
- watchlist under `Setup > Trust & Signing`
- diagnostics under `Ops > Operations`

### 2. Page tab
Use when the capability is a stable facet of one product shell.

Examples:
- reachability `Witnesses`
- run-detail `Replay`

### 3. Segmented list mode
Use when the capability changes queue state rather than product ownership.

Examples:
- triage `Quiet Lane`
- triage `Needs Review`

### 4. Right rail or drawer
Use when the surface explains, edits, or inspects an item in context.

Examples:
- watchlist entry edit
- reachability PoE detail
- workflow step detail
- triage reason capsule

### 5. Full detail page
Use when the item needs shareable URLs, deep auditability, and enough information density to stand alone.

Examples:
- reachability witness detail
- triage artifact detail
- audit bundle detail

## Decision Matrix

| Situation | Preferred placement | Avoid |
| --- | --- | --- |
| configuration-heavy, low daily traffic | submenu or setup tab | new top-level product |
| one list with rich detail | split list/detail or drawer | separate workbench brand |
| explanation for an active decision | right rail or drawer | isolated route tree |
| durable investigation artifact | full detail page | modal-only access |
| runtime facet of an existing entity | page tab | separate sidebar item |

## Shared Route-State Contract

Use stable, predictable query params and child routes instead of ad hoc local state.

### Preferred query params
- `tab=<name>`
- `panel=<name>`
- `drawer=<name>`
- `returnTo=<encoded route>`
- `scope=<name>`
- `view=<name>`

### Rules
- use child routes for durable subpages
- use query params for secondary panels and drawers
- preserve `returnTo` whenever a user came from another owner shell
- keep panel names short and stable for bookmarks and tests

## Shared Primitives To Build

### 1. Context header
- pinned subject context
- status chips
- return-to-context action

### 2. Split list/detail shell
- stable layout for list left, detail right
- supports keyboard navigation and deep linking

### 3. Drawer host
- route-aware drawers for edit, inspect, and explain flows
- consistent size, close behavior, and history handling

### 4. Right-rail panel stack
- secondary tabs for evidence, explanation, provenance, and history

### 5. Grouped overview cards
- consistent card layout for ops-like overview pages
- each card maps to exactly one child route

### 6. Action tray
- row or bulk actions that preserve page context
- confirmation only for destructive or privilege-sensitive actions

## Shipped Implementation

The shared contract is now implemented under `src/Web/StellaOps.Web/src/app/shared/ui/` and should be treated as the default building block set for restoration work.

### Shipped primitives
- `context-route-state`
  - central helpers for `tab`, `panel`, `drawer`, `returnTo`, `scope`, and `view`
  - includes `readContextRouteState`, `readContextRouteParam`, `buildContextRouteParams`, and `buildContextReturnTo`
- `context-header`
  - stable subject header with chips, context note, and return-to-context action
- `context-drawer-host`
  - overlay or rail presentation with shared close behavior, escape handling, and testable route-state integration
- `list-detail-shell`
  - responsive split list/detail layout for owner shells with one dominant list workflow
- `overview-card-groups`
  - grouped overview cards with one-card-to-one-route behavior
- `tabbed-nav`
  - now supports both classic tabs and owner-shell submenu pills, plus route command arrays and shared query params

### First adopted surfaces
- Watchlist uses the shared route-state, contextual header, tabs, and list-detail shell.
- Reachability uses the shared route-state, contextual header, and tabs.
- Operations uses the shared submenu and grouped overview-card patterns.
- Workflow Replay uses the shared route-state, contextual header, tabs, and drawer host.

### Delivery rule
- New restoration work should adopt these primitives before introducing new feature-local panel or route-state helpers.
- Context-preserving deep links should use `returnTo` instead of bespoke navigation metadata.
- Owner shells should prefer submenu pills, tabs, list-detail layouts, or drawers before creating another top-level route tree.

## Topic Mapping

### Watchlist
- submenu + tabs + edit drawer

### Reachability Witnessing
- tabbed shell + witness detail page + PoE drawer

### Platform Ops
- grouped overview cards + stable child routes

### Triage Explainability
- segmented lanes + detail-side panels + sibling audit-bundles page

### Workflow Visualization
- run-detail tabs + step drawer + evidence deep links

## Implementation Standards

- Prefer contextual UX over new products.
- Preserve deep-link stability for tabs and panels.
- Keep actions evidence-first and operator-confirmed when risk is high.
- Make drawers and rails testable with stable route state.
- Reuse primitives rather than re-creating bespoke shells per topic.

## Non-Goals

- Do not turn every contextual tool into a modal.
- Do not allow each feature team to invent incompatible query-param contracts.
- Do not use new top-level navigation to solve narrow discoverability problems.

## Source Inputs

- `docs/modules/ui/restoration-topics/README.md`
- `docs/modules/ui/component-preservation-map/RESTORATION_PRIORITIES.md`
- `docs/ui-analysis/05_ROUTE_SUMMARY_AND_OBSERVATIONS.md`
- `docs/modules/ui/architecture.md`
- `docs/modules/ui/architecture-rework.md`
- `docs/features/checked/web/contextual-actions-patterns-ui.md`