ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

fix: route workspace switch to chooser #147

Merged
ahmido merged 2 commits from 121-workspace-switch-fix into dev 2026-03-08 00:58:52 +00:00
Conversation 0 Commits 2 Files Changed 17 +55 -54
8 changed files with 55 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit e5f5832c4e - Show all commits

20
app/Providers/Filament/AdminPanelProvider.php
View File

@ -26,7 +26,6 @@
use App\Services\Auth\WorkspaceRoleCapabilityMap;
use App\Support\Auth\Capabilities;
use App\Support\Workspaces\WorkspaceContext;
use Filament\Actions\Action;
use Filament\Http\Middleware\Authenticate;
use Filament\Http\Middleware\AuthenticateSession;
use Filament\Http\Middleware\DisableBladeIconComponents;
@ -135,25 +134,6 @@ public function panel(Panel $panel): Panel
->group('Monitoring')
->sort(30),
])
->userMenuItems([
Action::make('switch-workspace')
->label('Switch workspace')
->url(fn (): string => ChooseWorkspace::getUrl(panel: 'admin').'?choose=1')
->icon('heroicon-o-arrows-right-left')
->visible(function (): bool {
$user = auth()->user();
if (! $user instanceof User) {
return false;
}
return WorkspaceMembership::query()
->where('user_id', (int) $user->getKey())
->join('workspaces', 'workspace_memberships.workspace_id', '=', 'workspaces.id')
->whereNull('workspaces.archived_at')
->count() > 1;
}),
])
->renderHook(
PanelsRenderHook::HEAD_END,
fn () => view('filament.partials.livewire-intercept-shim')->render()

11
specs/121-workspace-switch-fix/contracts/routes.md
View File

@ -6,10 +6,11 @@ ## Intent-level contract
### Switch workspace
- **Surface**: admin context bar
- **Surface**: admin and tenant-panel context bar
- **Label**: `Switch workspace`
- **Canonical target**: `ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'`
- **Meaning**: enter the explicit workspace chooser flow
- **User-menu duplication**: not allowed
### Manage workspaces
@ -39,12 +40,14 @@ ## Invariants
1. Workspace chooser remains the canonical manual-switch surface.
2. `?choose=1` remains the explicit forced-chooser signal for intentional switching.
3. Workspace management remains separately reachable and semantically distinct.
4. Choosing a workspace continues to use existing `WorkspaceIntendedUrl` / `WorkspaceRedirectResolver` behavior.
5. No new routes, middleware rules, or authorization rules are introduced.
3. The top-right user menu must not expose a duplicate workspace-switch shortcut.
4. Workspace management remains separately reachable and semantically distinct.
5. Choosing a workspace continues to use existing `WorkspaceIntendedUrl` / `WorkspaceRedirectResolver` behavior.
6. No new routes, middleware rules, or authorization rules are introduced.
## Verification expectations
- Response rendering for a real admin page containing the context bar must show the chooser target.
- Filament user-menu evaluation must not register a `switch-workspace` item.
- Existing chooser behavior tests remain green.
- Workspace management navigation remains reachable through its existing destination.

17
specs/121-workspace-switch-fix/plan.md
View File

@ -5,7 +5,7 @@ # Implementation Plan: Workspace Switch Semantic Fix
## Summary
Correct the admin context-bar `Switch workspace` affordance so it uses the same canonical chooser flow as the existing user-menu switch action. The implementation will update the topbar partial to target `ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'`, preserving the current chooser redirect behavior (`WorkspaceIntendedUrl` / `WorkspaceRedirectResolver`) and leaving workspace management reachable only through its separate administrative navigation path. Validation stays focused on response-level topbar rendering plus regression coverage that management navigation and chooser semantics remain distinct.
Correct the context-bar `Switch workspace` affordance so it uses the canonical chooser flow and remains the only workspace-switching affordance. The implementation will keep the topbar partial targeting `ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'`, remove the duplicate admin user-menu shortcut, preserve the current chooser redirect behavior (`WorkspaceIntendedUrl` / `WorkspaceRedirectResolver`), and leave workspace management reachable only through its separate administrative navigation path. Validation stays focused on response-level topbar rendering plus regression coverage that management navigation and chooser semantics remain distinct.
## Technical Context
@ -13,11 +13,11 @@ ## Technical Context
**Primary Dependencies**: Filament v5 + Livewire v4.0+ + Tailwind CSS v4
**Storage**: PostgreSQL + session-backed workspace context; no schema changes
**Testing**: Pest v4 feature tests (HTTP response assertions and existing workspace flow regression tests)
**Target Platform**: Web admin panel (`/admin`) running in Laravel Sail / container deployment
**Target Platform**: Web admin and tenant panels (`/admin`, `/admin/t/...`) running in Laravel Sail / container deployment
**Project Type**: Laravel monolith / Filament web application
**Performance Goals**: No additional remote calls or new query paths; topbar render remains effectively unchanged except for link destination
**Constraints**: Preserve existing RBAC and workspace isolation rules; preserve chooser post-selection behavior; avoid hardcoded management URLs for switch intent; no CRUD behavior changes
**Scale/Scope**: One context-bar Blade partial plus targeted workspace/navigation tests; no data migration, no new services, no new routes
**Constraints**: Preserve existing RBAC and workspace isolation rules; preserve chooser post-selection behavior; avoid hardcoded management URLs for switch intent; keep workspace switching in context surfaces rather than account surfaces; no CRUD behavior changes
**Scale/Scope**: One context-bar Blade partial, one admin panel provider cleanup, plus targeted workspace/navigation tests; no data migration, no new services, no new routes
## Constitution Check
@ -67,7 +67,7 @@ ### Source Code (repository root)
│ └── EnsureWorkspaceSelected.php # reference-only forced chooser semantics
├── Providers/
│ └── Filament/
│ └── AdminPanelProvider.php # reference-only existing canonical switch pattern
│ └── AdminPanelProvider.php # MODIFY — remove duplicate user-menu switch shortcut
└── Support/
└── Workspaces/
├── WorkspaceIntendedUrl.php # reference-only existing post-selection flow
@ -84,7 +84,7 @@ ### Source Code (repository root)
├── Monitoring/
│ └── HeaderContextBarTest.php # MODIFY — assert chooser target from context bar
└── Workspaces/
├── WorkspaceSwitchUserMenuTest.php # reference or extend — existing canonical chooser target pattern
├── WorkspaceSwitchUserMenuTest.php # MODIFY — assert user menu no longer exposes workspace switching
├── ChooseWorkspacePageTest.php # reference or extend — management remains reachable
└── WorkspaceNavigationHubTest.php # reference-only IA separation guard
```
@ -106,7 +106,7 @@ ## Phase 0 — Research (output: `research.md`)
Research goals:
- Confirm the canonical workspace-switch destination and whether forced chooser semantics require `?choose=1`.
- Confirm whether chooser post-selection redirect behavior should remain unchanged.
- Confirm the smallest reliable test surface for a topbar link semantic fix plus management-navigation regression coverage.
- Confirm the smallest reliable test surface for a context-bar-only switch rule plus management-navigation regression coverage.
## Phase 1 — Design & Contracts (outputs: `data-model.md`, `contracts/`, `quickstart.md`)
@ -118,6 +118,7 @@ ## Phase 1 — Design & Contracts (outputs: `data-model.md`, `contracts/`, `quic
Design focus:
- Treat the context-bar link as a pure navigation contract update, not a behavior rewrite.
- Reuse the existing chooser page and `?choose=1` forced-chooser convention to preserve manual switching semantics.
- Remove the duplicate user-menu shortcut so workspace switching stays anchored to the context bar.
- Preserve existing management navigation, chooser redirect resolution, and capability boundaries unchanged.
- Validate the semantic split with response-level topbar assertions plus regression checks around management reachability.
@ -127,9 +128,11 @@ ### UI routing correction
- Replace the context-bar `Switch workspace` link target in `context-bar.blade.php`.
- Use the canonical chooser helper (`ChooseWorkspace::getUrl(panel: 'admin')`) with the forced chooser query parameter.
- Keep the link as navigation-only; no action/mutation flow is added.
- Remove the duplicate Filament user-menu switch action from the admin panel provider.
### Regression protection
- Extend the real rendered topbar test to assert the context-bar switch link points at the chooser URL rather than workspace CRUD.
- Update user-menu coverage to assert no workspace-switch shortcut is registered there.
- Reuse or mirror existing workspace chooser tests to prove management navigation remains separate and accessible through its dedicated path.
- Keep existing middleware/chooser tests as the source of truth for post-selection branching.

12
specs/121-workspace-switch-fix/quickstart.md
View File

@ -6,6 +6,7 @@ ## Scope
A small navigation-semantic correction:
- update the context-bar `Switch workspace` link,
- remove the duplicate user-menu `Switch workspace` shortcut,
- keep chooser behavior unchanged,
- keep workspace management navigation unchanged,
- add focused regression coverage.
@ -13,10 +14,12 @@ ## Scope
## Implementation order
1. Update [resources/views/filament/partials/context-bar.blade.php](../../../resources/views/filament/partials/context-bar.blade.php) so `Switch workspace` targets the chooser helper with `?choose=1`.
2. Extend [tests/Feature/Monitoring/HeaderContextBarTest.php](../../../tests/Feature/Monitoring/HeaderContextBarTest.php) to assert the rendered context-bar link points to the chooser target.
3. Add or extend one workspace regression test to confirm management navigation remains separately reachable.
4. Run focused Sail-based tests.
5. Run Pint on dirty files.
2. Remove the admin user-menu `Switch workspace` shortcut from [app/Providers/Filament/AdminPanelProvider.php](../../../app/Providers/Filament/AdminPanelProvider.php).
3. Extend [tests/Feature/Monitoring/HeaderContextBarTest.php](../../../tests/Feature/Monitoring/HeaderContextBarTest.php) to assert the rendered context-bar link points to the chooser target.
4. Extend [tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php](../../../tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php) to assert no user-menu shortcut is registered.
5. Add or extend one workspace regression test to confirm management navigation remains separately reachable.
6. Run focused Sail-based tests.
7. Run Pint on dirty files.
## Reference files
@ -38,5 +41,6 @@ ## Validation commands
## Expected outcome
- Context-bar switching always opens the chooser.
- The top-right user menu does not offer a duplicate workspace switch entry.
- Workspace management remains a separate administrative path.
- Existing chooser branching behavior and middleware semantics remain unchanged.

12
specs/121-workspace-switch-fix/research.md
View File

@ -6,7 +6,7 @@ ## 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 admin user menu uses this exact destination today, while the context bar still points to the workspace CRUD index. The `?choose=1` parameter is the established convention for bypassing workspace auto-resume and forcing the chooser when the user explicitly intends to switch.
**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.
@ -32,6 +32,16 @@ ## R3: Separation between switching and management
- 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.

13
specs/121-workspace-switch-fix/spec.md
View File

@ -3,12 +3,12 @@ # Feature Specification: Workspace Switch Semantic Fix
**Feature Branch**: `121-workspace-switch-fix`
**Created**: 2026-03-07
**Status**: Draft
**Input**: User description: "Separate workspace switching from workspace management in the context bar so the Switch workspace action always routes to the canonical workspace chooser instead of the workspace CRUD index."
**Input**: User description: "Separate workspace switching from workspace management in the context bar so the Switch workspace action always routes to the canonical workspace chooser instead of the workspace CRUD index. Keep workspace switching as a context-bar-only affordance rather than a user-menu shortcut."
## Spec Scope Fields *(mandatory)*
- **Scope**: workspace
- **Primary Routes**: authenticated admin context bar workspace switch entry; workspace chooser flow at `/admin/choose-workspace`; workspace management page at `/admin/workspaces`
- **Primary Routes**: authenticated admin and tenant-panel context bar workspace switch entry; workspace chooser flow at `/admin/choose-workspace`; workspace management page at `/admin/workspaces`
- **Data Ownership**: workspace-owned context selection only; no new workspace records or workspace management data changes
- **RBAC**: authenticated users continue to switch only among workspaces they already belong to; workspace management remains behind its existing administrative capabilities with no visibility or permission expansion
@ -26,6 +26,7 @@ ### User Story 1 - Direct workspace switching (Priority: P1)
1. **Given** a signed-in user with access to multiple workspaces, **When** the user selects “Switch workspace” from the context bar, **Then** the user is taken directly to the workspace chooser flow.
2. **Given** a signed-in user who opens the chooser from the context bar, **When** the chooser loads, **Then** the user sees the existing workspace selection experience rather than a workspace management list.
3. **Given** a signed-in user with access to multiple workspaces, **When** the user opens the top-right user menu, **Then** no separate `Switch workspace` shortcut is shown there.
---
@ -59,10 +60,11 @@ ### User Story 3 - Maintain navigational coherence (Priority: P3)
### Edge Cases
- What happens when a user has access to only one workspace but the switch entry is still shown? The action should still resolve to the chooser flow rather than rerouting to management.
- What happens when a user has access to only one workspace but the switch entry is still shown in the context bar? The action should still resolve to the chooser flow rather than rerouting to management.
- How does the system handle a user whose active workspace becomes unavailable between rendering the context bar and clicking the switch action? The user should still be routed to the chooser, where existing entitlement handling determines the next safe state.
- What happens if a user lacks workspace management capability? The context-switching entry must still work without revealing or implying management access.
- How does the system handle stale bookmarks to workspace management? Existing management links remain valid and separate from switching intent.
- What happens if a user looks for workspace switching in the top-right user menu? The product should not duplicate the affordance there; the context bar remains the single canonical switch surface.
## Requirements *(mandatory)*
@ -82,12 +84,14 @@ ### Functional Requirements
- **FR-004**: The system MUST preserve existing visibility and permission rules for workspace management.
- **FR-005**: The system MUST keep navigation and breadcrumb behavior coherent after the destination change.
- **FR-006**: The system MUST preserve current capability-aware handling for users who can switch workspaces but cannot manage workspaces.
- **FR-007**: The system MUST expose workspace switching through the context bar only, and MUST NOT register a duplicate `Switch workspace` shortcut in the Filament user menu.
## UI Action Matrix *(mandatory when Filament is changed)*
| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Context bar workspace switcher | Global admin context bar | None | Not applicable | `Switch workspace` (navigation only) | None | None | Not applicable | Not applicable | No | Navigation-only action. Destination changes to the chooser flow. No destructive behavior, no mutation, and no authorization expansion. |
| Context bar workspace switcher | Global admin and tenant-panel context bar | None | Not applicable | `Switch workspace` (navigation only) | None | None | Not applicable | Not applicable | No | Navigation-only action. Destination changes to the chooser flow. No destructive behavior, no mutation, and no authorization expansion. |
| User menu workspace shortcut | Top-right user menu | None | Not applicable | None | None | None | Not applicable | Not applicable | No | Explicitly absent by design. Workspace switching remains anchored in the context bar to preserve context-vs-account semantics. |
| Workspace management navigation | Existing admin navigation destination | Existing actions unchanged | Existing management affordances unchanged | Existing actions unchanged | Existing actions unchanged | Existing empty-state behavior unchanged | Existing actions unchanged | Existing save/cancel behavior unchanged | Unchanged | Included for separation-of-concerns verification only; this feature does not change management behavior. |
### Key Entities *(include if feature involves data)*
@ -110,3 +114,4 @@ ### Measurable Outcomes
- **SC-002**: A multi-workspace user can begin a workspace switch in one click from the context bar without encountering CRUD management controls.
- **SC-003**: Administrative users retain an unchanged path to workspace management during regression testing.
- **SC-004**: Manual QA confirms no broken links, redirect loops, or breadcrumb confusion across the switch and management paths.
- **SC-005**: Validation confirms the top-right user menu does not expose a separate `Switch workspace` shortcut.

9
specs/121-workspace-switch-fix/tasks.md
View File

@ -6,7 +6,7 @@ # Tasks: Workspace Switch Semantic Fix
**Tests**: Tests are REQUIRED for this runtime behavior change. Use Pest feature tests via Sail.
**Operations**: No `OperationRun` work is required for this feature.
**RBAC**: No authorization model changes are planned; tasks must preserve existing workspace membership and capability behavior.
**Filament UI Action Surfaces**: The affected surface is a topbar navigation link; no new CRUD action surface is introduced.
**Filament UI Action Surfaces**: The affected surface is a topbar navigation link; no new CRUD action surface is introduced, and the top-right user menu must not duplicate workspace switching.
**Filament UI UX-001**: No Create/Edit/View layout changes are required; preserve existing chooser and management screens.
**Organization**: Tasks are grouped by user story so each story remains independently testable.
@ -43,11 +43,12 @@ ### Tests for User Story 1 ⚠️
> **NOTE**: Add or update these tests first and ensure they fail before implementation.
- [X] T004 [P] [US1] Extend tests/Feature/Monitoring/HeaderContextBarTest.php to assert the rendered `Switch workspace` link targets `/admin/choose-workspace?choose=1` and does not target `/admin/workspaces`
- [X] T005 [P] [US1] Keep the canonical chooser target expectation aligned in tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php so topbar and user-menu switching semantics stay consistent
- [X] T005 [P] [US1] Update tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php to assert the top-right user menu does not expose a `Switch workspace` shortcut, even when multiple workspaces exist
### Implementation for User Story 1
- [X] T006 [US1] Update resources/views/filament/partials/context-bar.blade.php to route `Switch workspace` to `ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'`
- [X] T016 [US1] Remove the duplicate `Switch workspace` user-menu action from app/Providers/Filament/AdminPanelProvider.php so the context bar is the only switch surface
**Checkpoint**: User Story 1 should now be independently functional and verifiable from the rendered admin topbar.
@ -95,7 +96,7 @@ ## Phase 6: Polish & Cross-Cutting Concerns
**Purpose**: Final verification and formatting for the complete change.
- [X] T013 Perform manual QA for `/admin/choose-workspace?choose=1` and `/admin/workspaces`, confirming page title, breadcrumbs, back-navigation, and link targets remain coherent across switching and management flows
- [X] T013 Perform manual QA for `/admin/choose-workspace?choose=1` and `/admin/workspaces`, confirming page title, breadcrumbs, back-navigation, link targets, and absence of a user-menu switch shortcut remain coherent across switching and management flows
- [X] T014 Run focused Pest coverage with `vendor/bin/sail artisan test --compact` for 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, and tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php
- [X] T015 Run `vendor/bin/sail bin pint --dirty --format agent`
@ -139,7 +140,7 @@ ## Parallel Example: User Story 1
```bash
# Launch both regression updates for the switching contract together:
Task: "Extend tests/Feature/Monitoring/HeaderContextBarTest.php to assert the rendered Switch workspace link targets /admin/choose-workspace?choose=1 and does not target /admin/workspaces"
Task: "Keep the canonical chooser target expectation aligned in tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php so topbar and user-menu switching semantics stay consistent"
Task: "Update tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php to assert the top-right user menu does not expose a Switch workspace shortcut"
```
---

15
tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php
View File

@ -2,7 +2,6 @@
declare(strict_types=1);
use App\Filament\Pages\ChooseWorkspace;
use App\Models\User;
use App\Models\Workspace;
use App\Models\WorkspaceMembership;
@ -17,9 +16,9 @@
Http::preventStrayRequests();
});
// --- T032: it_shows_switch_workspace_menu_when_multiple_workspaces ---
// --- T032: it_keeps_workspace_switch_out_of_user_menu_when_multiple_workspaces ---
it('shows switch workspace in user menu when multiple workspaces', function (): void {
it('keeps switch workspace out of the user menu when multiple workspaces exist', function (): void {
$user = User::factory()->create();
$workspaceA = Workspace::factory()->create(['name' => 'Workspace Alpha']);
@ -46,16 +45,12 @@
->get('/admin/workspaces');
$response->assertOk();
$switchWorkspace = Filament::getUserMenuItems()['switch-workspace'] ?? null;
expect($switchWorkspace)->not->toBeNull();
expect($switchWorkspace->getUrl())->toBe(ChooseWorkspace::getUrl(panel: 'admin').'?choose=1');
expect(Filament::getUserMenuItems())->not->toHaveKey('switch-workspace');
});
// --- T032: it_hides_switch_workspace_menu_when_single_workspace ---
// --- T032: it_keeps_workspace_switch_out_of_user_menu_when_single_workspace ---
it('hides switch workspace in user menu when single workspace', function (): void {
it('keeps switch workspace out of the user menu when single workspace exists', function (): void {
$user = User::factory()->create();
$workspace = Workspace::factory()->create(['name' => 'Solo Workspace']);