kandev/docs/plans/sidebar-customization/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-09-19	implemented	REQ-UI-SIDEBAR-CUSTOMIZATION-001 REQ-UI-SIDEBAR-CUSTOMIZATION-002 REQ-UI-SIDEBAR-CUSTOMIZATION-003 REQ-UI-SIDEBAR-CUSTOMIZATION-004 REQ-UI-SIDEBAR-CUSTOMIZATION-005	../../specs/ui/system-design/sidebar-customization.md

Implementation Plan: Sidebar Customization

Overview

Deliver personal workspace layouts, named collapsible shortcut sections, and live automation bubbles. Preserve the agreed direct-action icon header and matching labelled list. The five work orders are implemented sequentially in the primary session. This task does not include commits, pushes, or PR publication.

Scope

In scope

• Visibility and ordering of optional navigation entries.
• Named groups mixing GitHub, registered plugin links, canvases, and automations.
• Header actions, expanded lists, drag/drop, and explicit move controls.
• Portable per-user/per-workspace settings, defaults, reset, and conflict recovery.
• Running/idle/paused bubbles, including folded groups and overflow.
• Desktop, collapsed rail, phone editor/menu, accessibility, and localization.

Out of scope

Arbitrary plugin slot buttons, a new plugin SDK API, direct automation execution, custom scripts/URLs, shared team layouts, task filter changes, and reordering Office-only sections. Tasks and required inbox entries remain fixed. Header icons with text labels are deferred in favor of the accepted icon header.

Technical approach

1. Extend internal/user models, DTOs, service CAS, store, boot/WS projection, and settings catalog with sidebar_layouts_by_workspace and a scoped patch.
2. Add typed operations and a reference catalog under apps/web/lib/sidebar/. Adapt resolveDestinations, owner-qualified plugin IDs, canvas eligibility, and existing host launchers. Keep task-view settings independent.
3. Add /settings/sidebar, Appearance/discovery entry points, and a useSettingsSaveContributor editor with a local draft preview.
4. Replace optional composition in AppSidebarModeNav/AppSidebarPrimaryNav with the saved projection. Extend AppNavSections for phone navigation. Retain TasksSection, required inbox entries, and settings takeover.
5. Share automation summary reads and existing automationState derivation; reuse Quick Chat bubble geometry without its unread semantics.

See the requirements and design for contracts. The work orders below record the implementation modules and verification evidence for this package.

ASCII UI preview

The disclosure/action split, icon header, matching list, fixed task region, and dedicated phone composition are structural requirements. Spacing, icons, and example names are illustrative. All product copy uses localization.

UI-01: Desktop editor, draft with hidden entries

Entry: Appearance > Sidebar or Customize sidebar.

Sidebar                         Workspace: Default
Changes apply to your navigation in this workspace.

LAYOUT                           DRAFT PREVIEW
:: Home                 [off]    > Shortcuts [GH][S][C][A]
:: New Task              [on]    Tasks
:: Shortcuts             [on]      ...
   Name [Shortcuts        ]
   :: [GH] GitHub          [x]
   :: [S]  Slack           [x]
   :: [C]  My canvas       [x]
   :: [A]  My automation   [x]
   [+ Add shortcut]
:: Automations          [off]
:: Canvases             [off]
:: Integrations         [off]
   Tasks                [fixed]
[+ Add shortcut section]  [Restore defaults]
                 [Discard] [Save changes]*

:: is a drag handle with explicit move controls. * is the existing shared save control, not a new local footer. The draft preview does not change live navigation. Fixed Tasks and required inbox entries remain outside reorder scope.

UI-02: Phone editor, focused section

Entry: Menu > Customize sidebar. Full-page settings navigation.

< Sidebar              Default
Shortcuts
Name [Shortcuts              ]

[GH] GitHub               [...]
[S]  Slack                [...]
[C]  My canvas            [...]
[A]  My automation        [...]
[+ Add shortcut]

... menu:
  Move up
  Move down
  Move to section >
  Remove

        [Save changes]*

Back returns to the layout list with visibility switches. Add shortcut opens a searchable picker; selection returns to this section draft. The page has one scroll owner and safe-area clearance. Explicit move controls are always reachable.

UI-03: Picker and save failures, shared content

< Add shortcut
[Search shortcuts...       ]
Built-in / Plugins / Canvases / Automations
[GH] GitHub
[S]  Slack
[C]  My canvas
[A]  My automation

Empty: No matching shortcuts
Loading: Loading shortcuts...
Error: Could not load shortcuts [Retry]

Save conflict: Layout changed elsewhere.
Your draft is retained. [Load latest]
Save error: Could not save changes. [Retry]

Desktop uses the existing picker overlay; phone uses the focused picker step. Loading, empty, and error are alternatives, not simultaneous messages.

UI-04: Expanded desktop sidebar, section folded and unfolded

Entry: workspace navigation after saving the layout.

Default                              [collapse]
> Shortcuts                 [GH][S][C][A]
Tasks                           All tasks
  ...

v Shortcuts                 [GH][S][C][A]
    GitHub
    Slack
    My canvas
    My automation
Tasks                           All tasks
  ...

The label/chevron toggles expansion; sibling icons navigate directly. Tasks retains the remaining scroll space. Header and list use the same ordering.

UI-05: Narrow header, collapsed rail, and unavailable target

> My longer group     [GH][S][...]

56px rail: [Group]
  opened menu:
    GitHub
    Slack
    My canvas
    My automation

v Shortcuts              [GH][?][C][A]
    GitHub
    Unavailable                 [disabled]
    My canvas
    My automation

More and the rail launcher reveal all remaining items with names. Saved unavailable references remain removable in settings. A new empty group shows its name; its editor offers Add shortcut. Icons never shrink to force a fit.

UI-06: Phone navigation drawer

Entry: app menu; same layout, dedicated touch composition.

Menu                              [close]
Workspace: Default
v Shortcuts
  [GH]    [S]    [C]    [A]    [...]
    GitHub
    Slack
    My canvas
    My automation
Tasks
Settings
Customize sidebar

The fixed menu header sits above one scrolling body. The icon strip occupies a separate line to retain 44px hit targets. Folding hides labelled entries only. Navigating closes the menu. Disclosure and overflow actions keep it open.

UI-07: Activity in folded, expanded, and overflow states

> Shortcuts                 [GH][S][C][A*]

v Shortcuts                 [GH][S][C][A*]
    GitHub
    Slack
    My canvas
    My automation                  Running *

> Shortcuts                 [GH][S][...*]
Rail: [Group*]
Phone:
> Shortcuts
  [GH]    [S]    [C]    [A*]

* represents an overlaid bubble, not a literal glyph. Running is blue, idle green, and paused muted. Unknown/loading/error has a distinct neutral indicator and explanatory text. Overflow and rail launchers aggregate hidden running activity. No bubble click target is added; the parent opens the shortcut.

Tests

All test names below are implementation targets. Each work order adds failing coverage before its production changes, then records actual results.

Acceptance criteria (AC-UI-SIDEBAR-CUSTOMIZATION-)	Proposed evidence and test cases
001.2, 001.3, 004.3	internal/user/service/sidebar_layout_test.go: TestSidebarLayoutScopedCAS, TestSidebarLayoutResetRevision, TestSidebarLayoutAccess; handlers/store round trips
004.5	Same service test: TestSidebarLayoutValidation; layout-operations.test.ts: validates groups and moves without duplicates
001.1, 001.4, 001.5	layout-projection.test.ts: preserves protected entries and palette; visibility/navigation E2E
002.1, 002.6, 004.4	shortcut-catalog.test.ts: resolves typed targets, isolates plugin owners, retains unavailable references, navigates without executing
002.4, 004.1, 004.2, 004.3	sidebar-layout-editor.test.tsx: saves and discards scoped drafts, keeps draft after conflict, moves across groups; sidebar-layout-editor-dnd.test.ts: group reorder, cross-group move, duplicate rejection; editor E2E
002.2, 002.3, 002.5	shortcut-section.test.tsx: separates disclosure and navigation, shares order, offers overflow and rail menu; navigation E2E
003.1, 003.2, 003.3, 003.4	use-shortcut-activity.test.ts: refreshes idle pins, does not claim idle before load, rejects stale workspace results, shares polling; activity E2E
005.1, 005.2, 005.3, 005.4	Phone E2E below, typecheck, i18n:check, and i18n:ratchet

E2E tests

Files live under apps/web/e2e/tests/. Each desktop scenario has a phone scenario with the same values and its own composition assertions.

Files	Project	Scenarios and acceptance coverage
settings/sidebar-customization.spec.ts, settings/mobile-sidebar-customization.spec.ts	chromium / mobile-chrome	Added and passing. Desktop covers four picker additions, hidden Home, group reorder, save/reload, navigation rendering, and live pinned-automation activity. Phone covers the focused editor, four shortcuts, same-group move controls, touch sizing, and horizontal-overflow safety. AC 001.1-.5, 002.1/.4, 003.1, 004.1-.5, 005.1-.4.
Existing automations-sidebar.spec.ts plus sidebar unit/component tests	chromium / existing regression	Covers the established automation list lifecycle, shortcut disclosure/actions, overflow, and rail behavior. These checks remain separate from the new mixed-layout browser scenario.

Use test-base and existing automation/plugin fixtures. Stub summary responses only for deterministic failure tests; prove at least one real run lifecycle. Phone tests assert 44px bounds, safe-area scrolling, no horizontal page overflow, and focus return. Test just below/above 768px plus the standard phone viewport.

Work orders

• Task 01: Persist workspace sidebar layouts
• Task 02: Resolve shortcut references and layout operations
• Task 03: Build the desktop and phone settings editor
• Task 04: Render shortcut sections across navigation surfaces
• Task 05: Show automation activity on shortcut icons

Dependency order: 01 -> 02 -> 03 -> 04 -> 05. No parallel agents are authorized. Work orders contain exact commands and proposed files. Install workspace dependencies once before implementation checks if this worktree lacks them. Managed E2E builds fresh assets; never use --no-build after source changes.

Verification results

Product checks passed:

• (cd apps/backend && go test ./internal/user/... ./internal/settingscatalog/...) passed.
• Focused frontend Vitest coverage passed for settings mapping, layout operations and projection, shortcut catalog, editor save/conflict flows, drag-and-drop handlers, navigation, and activity.
• (cd apps/web && pnpm run typecheck) passed.
• (cd apps/web && pnpm run lint) passed.
• (cd apps/web && pnpm run i18n:check && pnpm run i18n:ratchet) passed.
• (cd apps/web && pnpm run build:vite) passed.
• Existing desktop regression E2E passed 5 tests across automation sidebar activity and system navigation.
• Existing mobile regression E2E passed 5 tests across settings navigation, sidebar access, and touch sizing.
• New desktop sidebar customization E2E passed 2 tests, including four shortcut editing, visibility, group reorder, save/reload, navigation rendering, and a pinned automation status transition.
• New phone sidebar customization E2E passed 1 test, including the focused editor, four shortcuts, same-group move controls, touch sizing, save/reload, and horizontal-overflow safety.
• node scripts/validate-public-docs.mjs and node --test scripts/validate-public-docs.test.mjs passed.
• python3 scripts/list-docs.py validate and python3 scripts/lint-spec-files.py --all passed.
• git diff --check passed.

The two dedicated sidebar-customization E2E files are now present and recorded above. The broader layout/sidebar-shortcuts.spec.ts and layout/sidebar-shortcut-activity.spec.ts matrix files were not added; their covered behavior remains represented by the named existing regression and unit/component suites. No unrun scenarios are reported as verified here.

Risks

• Shortcut status polling must stay shared and remain active when groups fold.
• Plugin navigation links are supported; arbitrary plugin slot buttons are not.
• Concurrent edits require a conflict response instead of silent overwrites.
• Existing Office/inbox contracts require fixed entries and mode-aware defaults.
• Phone controls need a separate icon strip; squeezing the desktop header fails touch sizing. The saved order stays shared.

Completion

Implementation is reconciled with the design. Requirement and design statuses are active/current, this plan is implemented, work-order results record the checks, and public docs describe the shipped behavior. No commit, push, or PR is part of this task.