ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
dev
TenantAtlas/specs/121-workspace-switch-fix/research.md
ahmido 891f177311 fix: route workspace switch to chooser (#147) 
## Summary
- route the context-bar `Switch workspace` link to the canonical chooser flow instead of workspace management
- add focused regression coverage for topbar switching, management separation, and chooser redirect semantics
- add Spec 121 artifacts (`spec`, `plan`, `research`, `data-model`, `contracts`, `quickstart`, `tasks`, checklist)

## Validation
- `vendor/bin/sail artisan test --compact tests/Feature/Monitoring/HeaderContextBarTest.php tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php tests/Feature/Workspaces/ChooseWorkspacePageTest.php tests/Feature/Workspaces/WorkspaceNavigationHubTest.php tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php`
- `vendor/bin/sail bin pint --dirty --format agent`

## Notes
- base branch: `dev`
- branch: `121-workspace-switch-fix`

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #147
2026-03-08 00:58:51 +00:00

4.4 KiB
Raw Permalink Blame History

Research: Workspace Switch Semantic Fix

Feature: 121-workspace-switch-fix | Date: 2026-03-07

R1: Canonical destination for intentional workspace switching

Decision: Use ChooseWorkspace::getUrl(panel: 'admin').'?choose=1' as the context-bar target for Switch workspace.

Rationale: The codebase already treats the chooser page as the canonical manual-switch experience. The ?choose=1 parameter is the established convention for bypassing workspace auto-resume and forcing the chooser when the user explicitly intends to switch. Anchoring switching in the context bar avoids mixing workspace context controls into the top-right account/user menu.

Alternatives considered:

  • Link to route('filament.admin.resources.workspaces.index'): rejected because that is the management surface (Manage workspaces), not the switch flow.
  • Link to /admin/choose-workspace without ?choose=1: rejected because the codebase already documents ?choose=1 as the explicit forced-chooser contract for intentional switching.

R2: Post-selection redirect behavior after entering the chooser

Decision: Preserve the chooser’s existing redirect behavior after a workspace is selected.

Rationale: ChooseWorkspace::selectWorkspace() already resolves post-selection flow through WorkspaceIntendedUrl::consume() and WorkspaceRedirectResolver::resolve(). That behavior is covered by existing tests and is outside this spec’s scope. The fix is semantic routing into the chooser, not a redesign of what happens after a user selects a workspace.

Alternatives considered:

  • Always redirect back to the current page after selection: rejected because it would change established chooser behavior and broaden scope beyond a low-risk semantic correction.
  • Always redirect to one fixed landing page: rejected because it would bypass the existing tenant-count branching contract.

R3: Separation between switching and management

Decision: Keep workspace management reachable only through its existing dedicated administrative destinations, while the context bar becomes chooser-only.

Rationale: The chooser page already exposes a capability-aware Manage workspaces link for eligible roles, and the workspace resource itself is explicitly labeled Manage workspaces. This preserves the intended split between operational context switching and workspace CRUD administration.

Alternatives considered:

  • Add both switch and management links to the same context-bar action surface: rejected because it would continue the semantic conflation the spec is correcting.
  • Hide workspace management entirely from chooser-adjacent flows: rejected because the current dedicated management affordances are valid and already capability-aware.

R5: Keep switching out of the top-right user menu

Decision: Remove the admin panel Switch workspace user-menu shortcut and keep workspace switching as a context-bar-only affordance.

Rationale: Workspace selection changes application context, not user-account state. Keeping the switcher in the context bar makes it visible in both admin and tenant panels through the shared render hook, while the user menu stays focused on profile, theme, and session actions.

Alternatives considered:

  • Keep the user-menu shortcut as a secondary path: rejected because it duplicates the context action and creates cross-panel inconsistency unless every panel adopts it.
  • Add the shortcut to the tenant panel user menu too: rejected because it still places a context switch under an account-oriented surface.

R4: Smallest reliable test strategy

Decision: Extend response-level topbar rendering coverage in HeaderContextBarTest, and rely on existing workspace chooser/navigation tests for regression protection around management and forced chooser behavior.

Rationale: The bug lives in a rendered Blade partial in the admin topbar, so the most direct regression test is an HTTP response assertion on a real admin page that includes the context bar. Existing tests already cover chooser routing semantics, forced chooser behavior, chooser management-link visibility, and navigation hub separation.

Alternatives considered:

  • Test only the chooser Livewire page: rejected because it would not assert the actual broken context-bar link.
  • Add browser-only coverage: rejected because existing response-based feature tests already cover the required semantic contract at lower cost.