Files
kandev/docs/specs/ui/system-design/task-listing-display-preferences.md
T
2026-09-14 09:26:24 +01:00

20 KiB

status, system, requirements
status system requirements
current ui
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-001
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-002
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-003
REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-004

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 follows mobile-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.