generated from coulomb/repo-seed
Add dashboard UI improvement workplan
This commit is contained in:
268
workplans/STATE-WP-0043-dashboard-ui-experience.md
Normal file
268
workplans/STATE-WP-0043-dashboard-ui-experience.md
Normal file
@@ -0,0 +1,268 @@
|
||||
---
|
||||
id: STATE-WP-0043
|
||||
type: workplan
|
||||
title: "Dashboard UI Experience Improvements"
|
||||
domain: custodian
|
||||
repo: state-hub
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: custodian
|
||||
created: "2026-05-19"
|
||||
updated: "2026-05-19"
|
||||
state_hub_workstream_id: "028f60d0-8f72-4426-9267-3e6ed69a5223"
|
||||
---
|
||||
|
||||
# Dashboard UI Experience Improvements
|
||||
|
||||
## Summary
|
||||
|
||||
Address the active dashboard-improvement suggestions and fold them into a
|
||||
coherent UI pass that makes State Hub easier to operate day to day. The focus is
|
||||
not a visual redesign; it is better operational affordances: clearer repository
|
||||
identity in TPSC views, safe status-editing controls for tasks and workstreams,
|
||||
cleaner feedback workflow states, and more consistent reusable dashboard
|
||||
patterns.
|
||||
|
||||
## Current Findings
|
||||
|
||||
Existing active UI feedback records:
|
||||
|
||||
- `07ee477f-a800-4687-8ae9-c82a9bed095b` — TPSC GDPR Warnings / Per-Repo
|
||||
Breakdown should show the repository name instead of an id, and link to the
|
||||
repository in Gitea in a new tab.
|
||||
- `de2d14b7-c85e-4ac1-8a12-7c69af9942fa` — Workstream / Tasks should allow
|
||||
changing workstream and task statuses from the dashboard.
|
||||
|
||||
Inspection notes:
|
||||
|
||||
- `dashboard/src/tpsc.md` builds the Per-Repo Breakdown from snapshots and uses
|
||||
`snap.repo_id` directly. It does not enrich rows from `/repos/`, so the table
|
||||
cannot show names, slugs, domains, or remote URLs.
|
||||
- `dashboard/src/tasks.md`, `dashboard/src/tasks/[id].md`, and
|
||||
`dashboard/src/workstreams/[id].md` display status as read-only even though
|
||||
`PATCH /tasks/{id}` and `PATCH /workstreams/{id}` already exist.
|
||||
- Marking a task `done` through the current task PATCH endpoint can create a
|
||||
heuristic token event when no token fields are supplied. UI status changes
|
||||
need to make that side effect deliberate.
|
||||
- `dashboard/src/ui-feedback.md` only treats `finished` and `wont_fix` as
|
||||
closed, so legacy `resolved` feedback can still appear as active.
|
||||
- `CUST-WP-0003` already owns the WHI KPI-card work. This workplan should not
|
||||
duplicate that implementation; it should only align shared UI patterns around
|
||||
it.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Reworking the overall dashboard information architecture.
|
||||
- Replacing Observable Framework or adding a frontend framework.
|
||||
- Implementing the WHI KPI card already tracked by `CUST-WP-0003`.
|
||||
- Adding authentication or authorization around dashboard mutations.
|
||||
|
||||
## T01 — Triage Feedback Workflow States
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "2aaeb57e-26aa-438d-bfd8-4943c8b0b136"
|
||||
```
|
||||
|
||||
Normalize the UI-feedback workflow so actionable and closed suggestions are
|
||||
shown in the correct sections.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Treat `finished`, `wont_fix`, `resolved`, and `addressed` as closed in
|
||||
`dashboard/src/ui-feedback.md`, or migrate legacy records to `finished` if the
|
||||
API data model prefers canonical workflow statuses.
|
||||
- Keep `submitted`, `analyse`, `plan`, `implement`, `test`, and `review` as the
|
||||
active workflow.
|
||||
- Add notes or status transitions to the two active feedback records once this
|
||||
workplan is synced into State Hub.
|
||||
- Confirm the UI Feedback KPI counts match the visible Active and Closed lists.
|
||||
|
||||
Done when the UI Feedback page no longer mixes resolved legacy records into the
|
||||
active queue and the two live suggestions are clearly visible as planned work.
|
||||
|
||||
## T02 — Improve TPSC Per-Repo Breakdown
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "b6fe5e8e-80f6-439f-8ddc-47e65218f041"
|
||||
```
|
||||
|
||||
Make the TPSC Per-Repo Breakdown identify repositories by useful human labels
|
||||
and link to the source repo when a web-safe remote URL is available.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Fetch `/repos/` in `dashboard/src/tpsc.md` and build lookup maps by `id` and
|
||||
`slug`.
|
||||
- Resolve each snapshot row to a repo object before rendering.
|
||||
- Show the repo name and slug, not the raw UUID.
|
||||
- Link to `remote_url` in a new tab when it is already an HTTP(S) URL. For
|
||||
non-web remotes such as `gitea-remote:coulomb/state-hub.git`, show a clear
|
||||
non-linked slug unless a reliable Gitea URL transform already exists locally.
|
||||
- Use `target="_blank"` with `rel="noopener noreferrer"`.
|
||||
- Preserve the existing service maturity chips and latest-snapshot behavior.
|
||||
|
||||
Done when the active suggestion
|
||||
`07ee477f-a800-4687-8ae9-c82a9bed095b` is satisfied and unknown/missing repos
|
||||
degrade gracefully.
|
||||
|
||||
## T03 — Design Safe Status Editing Controls
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "11166491-2c7a-4007-9820-e0707e71556c"
|
||||
```
|
||||
|
||||
Define and implement a shared status-editing control that can be reused by task
|
||||
and workstream pages without surprising side effects.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Add a small dashboard component, for example
|
||||
`dashboard/src/components/status-control.js`, that renders a compact status
|
||||
select or segmented action control.
|
||||
- Support task statuses: `todo`, `in_progress`, `blocked`, `done`, and
|
||||
`cancelled`.
|
||||
- Support workstream statuses from `WORKSTREAM_STATUSES`.
|
||||
- Use `apiFetch` for PATCH requests, with disabled, saving, success, and error
|
||||
states.
|
||||
- Prevent parent row/modal click handlers from firing when the control is used.
|
||||
- For task transitions to `done`, handle the current token-event behavior
|
||||
explicitly: either collect optional token metadata, show a confirmation that a
|
||||
heuristic token event will be created, or add a backend-safe status-only path
|
||||
before enabling one-click completion.
|
||||
|
||||
Done when status editing has one reusable implementation and destructive or
|
||||
side-effectful transitions are guarded.
|
||||
|
||||
## T04 — Add Detail-Page Status Editing
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "34b29724-bd4b-416e-ab55-1d37132490dd"
|
||||
```
|
||||
|
||||
Add status controls to the places where operators naturally inspect a single
|
||||
task or workstream.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Add a task status control to `dashboard/src/tasks/[id].md`.
|
||||
- Add a workstream status control to `dashboard/src/workstreams/[id].md`.
|
||||
- Add task status controls to the Tasks table inside
|
||||
`dashboard/src/workstreams/[id].md`.
|
||||
- Refresh or locally update displayed rows after a successful PATCH.
|
||||
- Keep the raw field table for audit/debug context, but make the primary status
|
||||
affordance visible in the summary area.
|
||||
|
||||
Done when the active suggestion
|
||||
`de2d14b7-c85e-4ac1-8a12-7c69af9942fa` works from detail pages.
|
||||
|
||||
## T05 — Add List-Page Status Editing
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "0562bd05-d67c-4fe2-b501-166650d7129a"
|
||||
```
|
||||
|
||||
Extend safe status editing to the high-volume list views after the detail-page
|
||||
path is solid.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Add task status controls to `dashboard/src/tasks.md` table rows.
|
||||
- Add workstream status controls to `dashboard/src/workstreams.md` table rows if
|
||||
the table structure can accommodate them without crowding.
|
||||
- Keep filters stable after edits.
|
||||
- Do not allow row-click modal behavior to conflict with status controls.
|
||||
- Show a compact error state near the edited row if a PATCH fails.
|
||||
|
||||
Done when common status changes can be made from list views without navigating
|
||||
away and without breaking table scanning.
|
||||
|
||||
## T06 — Consolidate Reusable UI Patterns
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T06
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "7b055f11-25e2-45cb-80ac-d2d175fb5a1f"
|
||||
```
|
||||
|
||||
Reduce one-off inline UI code in the touched surfaces so future dashboard work
|
||||
stays consistent.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Reuse or extend `entity-modal.js`, `workplan-status.js`, `field-help.js`, and
|
||||
`config.js` rather than adding page-local copies of status maps and API
|
||||
behavior.
|
||||
- Prefer shared status badges and compact action controls over repeated inline
|
||||
color styles.
|
||||
- Align empty, loading, offline, and save-error states across the touched pages.
|
||||
- Keep the dashboard dense and operational rather than turning it into a
|
||||
marketing-style layout.
|
||||
- Preserve existing help overlays and the shift-click suggestion workflow.
|
||||
|
||||
Done when the changed pages share status/control primitives and have visibly
|
||||
consistent spacing, labels, and failure states.
|
||||
|
||||
## T07 — Close the Feedback Loop
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "0b182fff-c100-468c-afed-91918483638f"
|
||||
```
|
||||
|
||||
Make the UI feedback workflow reflect the work after implementation.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Add implementation notes to the two relevant technical-debt records.
|
||||
- Move each suggestion through the workflow to `review` when the code is ready
|
||||
for the original suggester.
|
||||
- Move to `finished` only after verification or operator confirmation.
|
||||
- Update relevant docs under `dashboard/src/docs/` if controls or behavior
|
||||
changed in a way operators need to understand.
|
||||
|
||||
Done when the dashboard suggestions page tells the same story as the shipped UI.
|
||||
|
||||
## T08 — Verification
|
||||
|
||||
```task
|
||||
id: STATE-WP-0043-T08
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "9d59cae4-c2a8-43e1-8a28-6344e22653b0"
|
||||
```
|
||||
|
||||
Verify the UI changes against both code and running dashboard behavior.
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Run the dashboard build from `dashboard/`.
|
||||
- Run the relevant backend tests if any API behavior changes.
|
||||
- Use the local dashboard preview with the local API and exercise:
|
||||
- TPSC Per-Repo Breakdown with linked and unlinked repos.
|
||||
- Task status transitions, including a guarded `done` transition.
|
||||
- Workstream status transitions.
|
||||
- Offline/error behavior for failed PATCH requests.
|
||||
- UI Feedback active/closed counts.
|
||||
- Check desktop and mobile widths for table overflow, clipped text, and
|
||||
overlapping controls.
|
||||
|
||||
Done when the implementation is build-clean, manually verified in the browser,
|
||||
and any intentional residual risks are documented.
|
||||
Reference in New Issue
Block a user