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

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