156 lines
4.7 KiB
Markdown
156 lines
4.7 KiB
Markdown
# 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`
|