# Station Search Page — Design Spec

**Date:** 2026-04-05  
**Status:** Approved

---

## Overview

A public-facing Livewire page that lets anyone search for nearby petrol stations by postcode, town, or city. The user selects a fuel type and search radius in miles. On submit, results are fetched server-side from `/api/stations` and displayed as a list.

---

## Routing

- Route: `GET /stations` — public, no auth middleware
- Registered in `routes/web.php` as a full-page Livewire component
- Uses the existing `x-layouts::app` (sidebar) layout

---

## Component

**Class:** `app/Livewire/Public/StationSearch.php`  
**View:** `resources/views/livewire/public/station-search.blade.php`

### Public properties

| Property | Type | Default | Notes |
|---|---|---|---|
| `$search` | string | `''` | Postcode, outcode, town or city |
| `$fuelType` | string | `''` | API fuel type alias (e.g. `petrol`, `diesel`) |
| `$radius` | int | `5` | In miles — converted to km before API call |
| `$results` | array | `[]` | Populated from API `data` array |
| `$meta` | array | `[]` | Populated from API `meta` object |
| `$apiError` | string\|null | `null` | Human-readable error from API or network failure |

### Method: `findStations()`

1. Validate: `$search` required, `$fuelType` required, `$radius` integer between 1–20
2. Reset `$results`, `$meta`, `$apiError`
3. Convert radius: `$radiusKm = $this->radius * 1.60934`
4. Call `Http::timeout(10)->withHeaders(['X-Api-Key' => config('services.fuelalert.api_key')])->get(url('/api/stations'), ['postcode' => $this->search, 'fuel_type' => $this->fuelType, 'radius' => $radiusKm, 'sort' => 'price'])`
5. On 422 — extract `errors.postcode[0]` or `message` and set `$apiError`
6. On other non-2xx — set `$apiError` to a generic message
7. On success — set `$results` and `$meta` from response JSON

### Configuration

- API key read from `config('services.fuelalert.api_key')`
- `.env` key: `FUELALERT_API_KEY`
- Add to `config/services.php` under `fuelalert`

---

## Form UI

Three fields in a horizontal row (stacks vertically on mobile):

1. **Search** — text input, placeholder "Postcode, town or city"
2. **Fuel type** — select with options:
   - Petrol (E10) → `petrol`
   - Super Unleaded (E5) → `e5`
   - Diesel → `diesel`
   - Premium Diesel → `b7_premium`
   - B10 Biodiesel → `b10`
   - HVO → `hvo`
3. **Radius** — select: 1, 2, 5, 10, 20 miles (default 5)

Submit button with `wire:loading` spinner and disabled state while request is in flight.

Inline validation errors shown below each field using `@error`.

---

## Results List

Shown below the form after a successful search.

**Meta bar** (above results): "{count} stations found · Cheapest: {lowest}p · Average: {avg}p"

**Each station row:**
- Station name + brand (badge if supermarket)
- Address / postcode
- Distance in miles (convert `distance_km` from response: `× 0.621371`, rounded to 1dp)
- Price: formatted as `{price}p` per litre (e.g. `143.9p`)
- Last updated: human-readable relative time (e.g. "2 hours ago") using `Carbon::parse(...)->diffForHumans()`

Sorted cheapest first (default). No client-side re-sorting in v1.

---

## States

| State | UI |
|---|---|
| Initial | Form only, no results area |
| Loading | Submit button shows spinner + disabled, no results change |
| Results | Meta bar + station list below form |
| API error | Error alert above results (e.g. "Postcode not found.") |
| Empty results | "No stations found within {radius} miles of {search}." |

---

## Data Flow

```
User fills form → submit → findStations() → Http::get /api/stations
  → success → $results + $meta populated → Livewire re-renders list
  → 422    → $apiError = postcode error message
  → other  → $apiError = "Unable to fetch stations. Please try again."
```

---

## Config

Add to `config/services.php`:
```php
'fuelalert' => [
    'api_key' => env('FUELALERT_API_KEY'),
],
```

Add to `.env` and `.env.example`:
```
FUELALERT_API_KEY=
```

---

## Testing

Feature test: `tests/Feature/Livewire/StationSearchTest.php`

Test cases:
- Form renders with empty state
- Validation: search required, fuel type required, radius required
- Successful search populates `$results` and `$meta` (Http::fake)
- 422 response sets `$apiError`
- Network failure sets `$apiError`
- Distance converted correctly from km to miles
- Radius converted correctly from miles to km in outgoing request