323 lines
13 KiB
Markdown
323 lines
13 KiB
Markdown
---
|
|
created: 2026-09-19
|
|
status: implemented
|
|
requirements:
|
|
- 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
|
|
system_design:
|
|
- ../../specs/ui/system-design/sidebar-customization.md
|
|
legacy_specs: []
|
|
---
|
|
|
|
# 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](../../specs/ui/requirements/sidebar-customization.md)
|
|
and [design](../../specs/ui/system-design/sidebar-customization.md) 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.
|
|
|
|
```text
|
|
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.
|
|
|
|
```text
|
|
< 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
|
|
|
|
```text
|
|
< 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.
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
> 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.
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
> 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
|
|
|
|
- [x] [Task 01: Persist workspace sidebar layouts](task-01-persist-layouts.md)
|
|
- [x] [Task 02: Resolve shortcut references and layout operations](task-02-resolve-shortcuts.md)
|
|
- [x] [Task 03: Build the desktop and phone settings editor](task-03-edit-layouts.md)
|
|
- [x] [Task 04: Render shortcut sections across navigation surfaces](task-04-render-navigation.md)
|
|
- [x] [Task 05: Show automation activity on shortcut icons](task-05-show-activity.md)
|
|
|
|
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.
|