# Implementation Plan: Spec 348 - Choose Environment Enterprise Selector

**Branch**: `348-choose-environment-enterprise-selector` | **Date**: 2026-06-02 | **Spec**: `specs/348-choose-environment-enterprise-selector/spec.md`

## Summary

Productize the existing `/admin/choose-environment` selector so it behaves like an enterprise context-selection surface: stable layout, immediate secondary actions, search for larger workspaces, localized search states, and no raw technical badge overflow.

## Technical Context

- **Language/Version**: PHP 8.4.15, Laravel 12.52.x.
- **Primary Dependencies**: Filament 5.2.x, Livewire 4.1.x, Tailwind CSS 4.x, Pest 4.x.
- **Storage**: PostgreSQL; no schema change.
- **Testing**: Pest Feature tests.
- **Constraints**: No provider calls during render, no new persistence, no new route, no destructive action.

## Implementation Approach

1. Extend `ChooseEnvironment` with a local `search` property and a filtered collection helper.
2. Replace the dynamic card grid with a single-column selector layout that fits the Filament simple-layout container.
3. Move `Add environment` and `Switch workspace` into the top selector header as neutral secondary actions.
4. Add a localized search box, result count, clear action, and no-results state.
5. Hide the default raw `managed_environment` kind label while preserving non-default short labels such as `DEV`.
6. Add stable test IDs for selector, filter, actions, result list, no-results state, and environment cards.
7. Extend focused Feature coverage for markup and Livewire search behavior.

## UI / Surface Guardrail Plan

- **Affected surface**: `UI-004` `/admin/choose-environment`.
- **Native vs custom**: existing custom Blade in a Filament Page; no new component family.
- **Action hierarchy**: environment card selection remains the primary page purpose; Add/Switch remain neutral secondary actions.
- **Status semantics**: lifecycle status remains a badge; status colors are not applied to buttons.
- **Dangerous actions**: none.

## Validation Plan

- Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Workspaces/ChooseEnvironmentPageTest.php --compact`.
- Run `cd apps/platform && ./vendor/bin/sail pint app/Filament/Pages/ChooseEnvironment.php tests/Feature/Workspaces/ChooseEnvironmentPageTest.php`.
- Run `git diff --check`.
- Verify in the in-app browser at `/admin/choose-environment` for current, mobile, and desktop viewports.

## Deployment Impact

- **Env vars**: none.
- **Migrations**: none.
- **Queues / scheduler**: none.
- **Storage**: none.
- **Assets**: no Filament asset registration; normal Vite/Tailwind build applies. `filament:assets` is not newly required by this change.