git.stella-ops.org/docs/modules/ui/contextual-actions-patterns/README.md

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

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