20 KiB
status, system, requirements
| status | system | requirements | ||||
|---|---|---|---|---|---|---|
| current | ui |
|
Task Listing Display Preferences System Design
Purpose and boundaries
UI owns the independent listing and Home presentation contract in the requirements. Reuse backend-owned user settings for the explicit choice and retain browser-owned listing memory. Workspace selection and Office mode remain governed by ADR 0023 and Office mode ownership.
The Threads page uses its existing conversation deck and saved views. This design does not alter their filters, session selection, resource budgets, swipe feedback, or topbar composition.
Requirement mapping
| Requirement | Design sections |
|---|---|
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-001 |
Preference ownership; Remembered listing and list details |
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-002 |
Portable settings contract; Entry resolution; Failure and recovery |
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-003 |
Portable settings contract; Entry resolution; Home consumers; Settings and mobile composition; Verification |
Preference ownership
| Concept | Existing source | Scope | Values |
|---|---|---|---|
| Startup/default destination | UserSettings.StartupPage, wire startup_page, frontend startupPage |
Portable per user | task_overview (default), last_task, threads |
| Remembered listing | localStorage["kandev.taskListing.view.v1"] |
Current browser/device, existing cross-workspace scope | JSON string kanban, pipeline, list, or threads |
| Recent task target | localStorage["kandev.recentTasks.v1"] |
Current device; target filtered by workspace | Existing recent-task entries |
| Rich List rows | tasks_list_show_details / tasksListShowDetails |
Portable per user | Boolean, default false |
| Workflow filter | Existing workflow_filter_id / workflowId |
Existing portable scope | Existing workflow ID or All Workflows |
Extend the existing startup enum instead of adding a parallel Home preference,
local key, or workspace map. The existing startup setting already owns the
explicit destination choice and the Settings save lifecycle. threads is the
only new fixed destination. task_overview retains its remembered-mode
meaning; last_task retains its startup-only behavior. Separate last-task
startup plus fixed Threads Home is not introduced.
Saving startup_page does not call setStoredTaskListingView. View changes
and the existing /tasks and /threads arrival effects may continue updating
listing memory; they must never PATCH startup_page. Arriving in Threads via
Home can therefore remember Threads as the latest visited mode without
turning listing memory into the authority for the fixed default.
Portable settings contract
StartupPageThreads = "threads" is defined in
apps/backend/internal/user/models/models.go. NormalizeStartupPage preserves
the three valid values and defaults absent or unsupported stored values to
task_overview. applyStartupPage in internal/user/service/service.go
accepts all three values, keeps current whitespace normalization, rejects an
unsupported submitted value without changing the record, and leaves an omitted
patch unchanged.
The existing user-settings HTTP read/update endpoints, DTO/controller mapping,
user.settings.updated event, and revision-controlled write path remain the
transport. DTO serialization, store scan/marshal, event publication, and
internal/backendapp/boot_state_routes.go already call the backend normalizer;
each must retain threads end to end. Settings stay in the existing users
settings JSON on SQLite and PostgreSQL. No table, column, endpoint, or schema
migration is added.
StartupPage in apps/web/lib/types/http-user-settings.ts and
parseStartupPage in apps/web/lib/ssr/user-settings.ts retain all three values.
The common wire-to-store mapper serves HTTP, save responses, and WebSocket updates. Keep
revision ordering, omitted-field preservation, and default ownership from
ADR 0041.
Do not introduce browser persistence for this field.
Entry resolution
There are two decisions: generate a generic Home destination, or resolve a bare root entry. Explicit routing is not a third preference store.
| Entry in a non-Office workspace | task_overview |
last_task |
threads |
|---|---|---|---|
Bare /, optionally with workspaceId |
Remembered listing | Newest matching local task, otherwise remembered listing | Threads in that workspace |
| Home action | Existing overview destination | Existing overview destination, never recent-task resume | /threads?workspace=<id> |
Explicit /?home=overview |
Remembered listing | Remembered listing | Remembered listing, bypassing fixed default |
| Explicit workflow root URL | Board for that workflow | Same | Same |
Explicit /tasks, /threads, task/session or focus URL |
Keep destination | Keep destination | Keep destination |
An explicit overview selects the overview family, not a fixed Kanban mode.
It already restores remembered List or Threads. Preserve that meaning. A
view-toggle selection records its chosen mode before navigating through
resolveTaskListingNavigation; the fixed default cannot bounce the user back
to Threads when they deliberately select Kanban or Pipeline.
Bare root
Keep startup policy in apps/web/lib/startup-page.ts and its integration in
apps/web/app/page-client.tsx. Use the existing
isExplicitHomeDestination checks for props and query task/session IDs,
workflow scope, and home=overview. A workspace ID alone scopes Home and does
not suppress startup selection.
After route settings and workspace resolution settle, a bare root with
startupPage === "threads" resolves directly to linkToThreads(workspaceId).
Otherwise preserve resolveStartupTaskId and remembered-listing fallback.
Use one resolved redirect in the effect, with router.replace, so a fixed
choice cannot issue a competing remembered-list redirect in the same render.
An explicit workflow or task/session destination suppresses both startup
override and remembered routed-view restoration as it does today.
Hydration readiness belongs to the route/bootstrap boundary, not the local
view hook. The useTaskListingView effect synchronizes kanbanViewMode while
preserving loaded; it must not manufacture authoritative settings readiness.
Preserve the actual loaded state and wait for the existing
boot settings or completion of the client settings fetch before resolving a
default. Do not use board snapshots or the presence of workflows alone as a
readiness gate: an empty workspace must still reach Threads or onboarding.
Return explicit readiness from useKanbanRouteBootstrap, scoped to the
requested workspace and fetch lifecycle, and consume it in KanbanRoute before
mounting the default-resolving page.
Record completion for both already-hydrated boot state and fetched state.
Completion remains settled for the same route selection while live workflow
filters or board snapshots change; these updates belong to the mounted listing,
not startup. A different requested workspace or workflow has its own readiness
and cancellation lifecycle.
Failed settings fetches complete with the normal fallback rather than waiting
forever. A late response for a previous workspace cannot redirect the current
route. Existing Office mismatch handling runs before this task-listing choice.
Explicit destinations and reload
The default is not a global route guard. Do not attach a redirect to the
always-mounted sidebar, useTaskListingView, or a settings subscription.
/tasks stays List on reload even with a Threads default. /threads retains
workspace, taskId, and sessionId focus parameters. Browser Back/Forward
restores the explicit route. Settings changes update future Home hrefs without
replacing the current task, workflow, settings, or listing route.
Keep linkToTaskOverview, task Back links, workflow navigation, and
listingHistoryHref as explicit navigation. Never blanket-replace their
overview URLs with a Home-default resolver.
Home consumers
Use one pure Home resolver in
apps/web/lib/navigation/workspace-home.ts with workspace ID, Office mode,
and the saved startup choice as inputs. Both workspaceHomeHref and
homeDestinationHref in core-destinations.ts delegate to it. Extend
NavContext and useNavContext to carry startupPage from authoritative
settings. A missing choice defaults to task_overview for existing callers.
Resolution order is Office home, explicit Threads home for a resolved
non-Office workspace, then the existing overview. Preserve encoded IDs and
the existing different query names (workspaceId for overview/Office,
workspace for Threads). Unknown workspace mode retains the current disabled
Home affordance. No-workspace onboarding remains available.
Office priority uses effective mode, not workspace metadata alone. Phone
listing menus use AppNavSections and useNavContext, whose useInOffice
input follows useOfficeModeState and the Office feature gate. With Office
disabled, the shared resolver preserves the workspace and saved task-listing
default without linking to the unavailable Office surface.
Audit and wire these callers; do not infer workspace type from the pathname:
- Sidebar brand/header and primary Home row.
- Sidebar settings-exit action and workspace picker, including picking the active workspace again when that action currently navigates Home.
useHomeAffordance, used by shared topbars and mobile navigation.- The phone listing drawer's Home row in
AppNavSections. Reuse the shared compact header and menu composition; only Home destination/state changes. - Manifest mobile Home and palette
nav-home. The palette retains its workspace-less overview override for existing startup choices, but routes a selected Threads default through the same workspace-aware Home resolver. Office remains Office when applying the Threads choice; do not send it into a deck.
Changes in src/kanban-route.tsx are limited to entry readiness or wiring;
its Office mismatch redirect is not a new Home action. Office recovery links
and explicit task overview/Back links retain their existing behavior.
Remembered listing and list details
view-preference.ts remains responsible for parsing the local JSON enum,
legacy kanban_view_mode === "graph2" fallback only when no local value
exists, and same-document/storage notifications. A present invalid local
value returns Kanban rather than using the legacy fallback. Failed writes keep
the chosen mode transiently for the current document.
use-task-listing-view.ts exposes the preferred/effective modes and updates
the in-memory Kanban rendering mode. Pipeline renders as Kanban on phones
without changing stored Pipeline; Threads uses the native phone deck.
view-navigation.ts owns explicit toggle routes and path-preserving scope
changes. None of these boundaries owns the portable Home choice.
Keep the existing workflow resolver's All Workflows behavior and List's
tasksListShowDetails flow through useKanbanDisplaySettings, display
controls, and tasks-list-view.tsx. Details remain false by default, portable,
and independent of Home selection. Missing metadata omits only that metadata;
secondary row actions do not activate the row. No rich-row implementation
change is required for Threads Home.
Settings and mobile composition
StartupPageSettingsCard includes threads in its radio options. Keep
AppearanceState.startupPage, buildAppearanceUserSettingsPatch, draft rebase,
and the SettingsSaveProvider contributor. Add no page-local Save button and
do not preview the destination by navigating while the user edits the form.
Revise the existing localized descriptions so they accurately explain all
three options: Task overview restores the last-used listing, Last visited task
only resumes on startup, and Threads always opens on startup and Home in task
workspaces. The shared description must no longer claim every Home action
always opens overview. Reuse the existing Threads label key where possible;
include Threads/home-default search terms in Startup Page discovery aliases.
Update English, pt-pt, and zh-cn, generate zh-hk/zh-tw with i18n:zh-hant, and
regenerate pseudo. Resolve copy with t() at render time; no em dashes.
Mobile contract:
- Entry is the existing phone Settings navigation into Appearance. The nearest
shipped form is
startup-page-settings-card.tsx, with full-width labelled radio rows. The shared phone menu followsmobile-menu-sheet.tsx's inset drawer, fixed heading, internal scroll, and safe-area treatment. - The persistent preference stays inline in the full-page Settings form. This short single choice needs no extra picker overlay. Option label comes first, its effect second; the shared floating Save changes action commits it.
- Reuse the Settings page's existing vertical scroll owner and safe-area clearance. Labels wrap; phone hit areas are at least 44px high. Preserve desktop density and current breakpoints; do not normalize topbar geometry.
- After navigation, reuse the native single-column Threads deck. Do not add a mobile fallback or change deck/session loading solely because it is Home.
- Settings draft, persistence, routing, and failure semantics are shared across desktop and phone; only established surface composition differs.
Failure and recovery
Unsupported stored startup strings normalize to overview; unsupported writes are rejected. Save errors leave the prior authoritative default and a retryable Settings draft. A reload receives the backend value, never a retry marker from browser storage. A successful save or live update changes future Home navigation through the existing revision-aware settings store.
Blocked local storage cannot prevent fixed Threads navigation. An empty deck
is a valid destination and keeps its empty state. Failure to find a recent
task uses the remembered-listing fallback only for last_task. No-workspace
and failed-bootstrap paths retain the existing recovery surface and must not
loop or permanently display a startup loader.
Existing user authorization and workspace access checks remain unchanged; startup choice conveys no additional access. Existing settings request/event errors and route tests provide evidence; no new logs, metrics, or feature flag are required.
Verification
Backend tests cover enum normalization, rejected/omitted patches, JSON round-trip, user isolation, DTO/event/boot retention, and reopening persisted settings. Frontend tests cover parser/mapper/WS parity, shared Home hrefs, explicit-destination precedence, deferred bootstrap, and independent local view memory. Keep existing last-task and Pipeline fallback regressions.
Extend e2e/tests/settings/startup-page.spec.ts and
mobile-startup-page.spec.ts for selection, Save/discard/failure, reload,
Home after using List, workspace switching, and protected explicit routes.
Use isolated test fixtures. Phone proof uses actual taps, checks the labelled
row hit area, verifies reachable Save, and checks no horizontal overflow.
The implementation plan
maps acceptance criteria to exact tests and commands.
Grouped display settings
Requirement REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-004 maps to this section:
004.1 to disclosure state; 004.2/004.3 to composition and summaries;
004.4 to existing state ownership; 004.5/004.6 to accessibility and mobile.
This extension is implemented; preceding shipped contracts remain unchanged.
The implementation package
owns delivery and verification. No new ADR is needed: ADR 0041 continues to
own portable preferences, while disclosure state is transient React state.
Composition and summaries
KanbanDisplayDropdown and DropdownSections in
apps/web/components/kanban-display-dropdown.tsx retain their current caller
props and useKanbanDisplaySettings actions. Wrap existing field sections in
Filters, Sort, Preview panel, and conditional List rows disclosures. Keep
currentPage === "kanban" board-only eligibility and Threads field exclusions
intact. Desktop Threads renders the Filters surface so its workflow filter
remains reachable; repository, board-only controls, plugins, and Preview remain
omitted there. Pipeline follows its existing caller/page semantics; do not infer
eligibility from the visible label.
Registered plugin filters remain in Filters with their existing namespaced
pluginTaskFilterRegistrationKey keys and callbacks.
Reuse the header/summary anatomy of SidebarSettingsDisclosure in
components/task/sidebar-filter/sidebar-settings-disclosure.tsx. Extract its
presentation into components/display-settings-disclosure.tsx with a thin
sidebar compatibility wrapper if needed. Preserve the sidebar's controlled API,
existing test IDs and behavior; avoid importing sidebar domain code into Home.
Render the desktop groups inside the Popover primitive. A DropdownMenu content
surface reserves Tab and arrow navigation for registered menu items, which would
exclude the disclosure headers and nested controls. Popover focus handling keeps
the headers and revealed controls in the browser's normal tab order while
retaining Escape dismissal and trigger focus return. Scope 44px hit areas to
touch; keep fine-pointer controls at normal density. Multi-line headers can grow
to fit their summaries. Reuse chevrons and muted labels.
Derive summaries from current hook props during render. Reuse
KANBAN_SORT_LABEL_KEYS, TASK_PRIORITY_LABEL_KEYS, workflow/repository names,
and getRepositoryPlaceholderKey for existing empty/loading semantics. Empty
priority selection means All priorities; four selected tokens must show their
labels, since unranked tasks remain excluded. Summarize active plugin filters
with their label and selected count, using i18next count forms. Unknown non-All
IDs get a localized unavailable fallback and do not trigger writes. Summaries
wrap without clipping the chevron; full values remain readable when expanded.
Add host copy in en, pt-pt, zh-cn, and generated zh-hk/zh-tw, plus pseudo through
repository scripts. Plugin-supplied labels retain plugin ownership.
Disclosure state and persistence
Keep independent expansion state local to the surface, reset when it closes. Multiple groups can stay open; setting rerenders do not reset expansion. Unmount hidden field content so it cannot receive focus. Do not duplicate filter state, add browser storage, change setting actions, or add backend APIs. Nested Select interactions must not dismiss the parent disclosure/surface. Bound the desktop Popover by available viewport height with one scroll owner.
Mobile and accessibility
MobileDisplayOptions in components/kanban/mobile-display-options.tsx, rendered
by components/kanban/mobile-menu-sheet.tsx, applies the same group anatomy
inside its current ResponsiveMenuSurface. Retain
buildMobileDisplayOptions visibility flags from
hooks/use-mobile-menu-sheet-state.ts: phone Board workflow is selected outside
the drawer, repository remains available, and preview settings retain their
existing visibility. Keep Columns and MobileTasksListOptions outside the
new groups. This is a temporary settings flow, so the existing inset Drawer is
the nearest shipped exemplar and the appropriate surface, with wider Sheet
behavior unchanged. Keep its fixed header, dynamic viewport bound, safe-area
clearance and single internal scrolling body; groups add no nested scrollers.
Share presentation and summary derivation across viewports, not new business
logic. Use full-row semantic buttons, aria-expanded, aria-controls, stable
content IDs, visible focus, and Enter/Space activation. Preserve Escape/back,
focus return and nested Select behavior. Test phone geometry at the configured
Pixel 5 size and immediately below/above the 768px phone boundary.