docs(ui): map restoration topics and delivery sprints
This commit is contained in:
master
155
docs/modules/ui/contextual-actions-patterns/README.md
Normal file
155
docs/modules/ui/contextual-actions-patterns/README.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user