docs: add search/nav/management/errors design spec
This commit is contained in:
@@ -0,0 +1,353 @@
|
|||||||
|
# Search, Nav, Management & Error States — Design Spec
|
||||||
|
|
||||||
|
**Date:** 2026-04-08
|
||||||
|
**Scope:** Backend search service, frontend nav shell, song management (edit + delete), error states.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
PocketChords has working persistence and a functional chord viewer. This iteration makes the app feel polished and complete: server-side search, consistent navigation, song management, and proper error handling.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Backend: Search Service
|
||||||
|
|
||||||
|
### Architecture
|
||||||
|
|
||||||
|
A dedicated `SongSearchService` with its own port — fully decoupled from `SongService`. Search and CRUD are independently swappable.
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /songs?q=… → SongSearchService → Box<dyn SongSearchPort> → SqliteSongRepository
|
||||||
|
GET /songs → SongService → Box<dyn SongRepositoryPort> → SqliteSongRepository
|
||||||
|
```
|
||||||
|
|
||||||
|
`SqliteSongRepository` implements both ports — one struct, two trait impls.
|
||||||
|
|
||||||
|
### New domain port (`crates/domain/src/ports.rs`)
|
||||||
|
|
||||||
|
```rust
|
||||||
|
#[async_trait]
|
||||||
|
pub trait SongSearchPort: Send + Sync {
|
||||||
|
async fn search(&self, query: &str) -> Result<Vec<SongSummary>, RepositoryError>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `SqliteSongRepository` search impl (`crates/infrastructure/persistence/src/lib.rs`)
|
||||||
|
|
||||||
|
SQLite `LIKE` query on title and artist columns:
|
||||||
|
```sql
|
||||||
|
SELECT id, title, artist, original_key, preview_chords
|
||||||
|
FROM songs
|
||||||
|
WHERE title LIKE ? OR artist LIKE ?
|
||||||
|
ORDER BY created_at DESC
|
||||||
|
```
|
||||||
|
Bind parameter: `format!("%{}%", query)` for both.
|
||||||
|
|
||||||
|
### New `SongSearchService` (`crates/common/src/lib.rs`)
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct SongSearchService {
|
||||||
|
search: Box<dyn SongSearchPort>,
|
||||||
|
}
|
||||||
|
impl SongSearchService {
|
||||||
|
pub fn new(search: Box<dyn SongSearchPort>) -> Self
|
||||||
|
pub async fn search(&self, query: &str) -> Result<Vec<SongSummary>, RepositoryError>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `AppState` update (`crates/api/src/routes/tabs.rs`)
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct AppState {
|
||||||
|
pub fetcher: Box<dyn TabFetcherPort>,
|
||||||
|
pub parser: Box<dyn TabParserPort>,
|
||||||
|
pub songs: SongService,
|
||||||
|
pub search: SongSearchService,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### API endpoint update (`crates/api/src/routes/songs.rs`)
|
||||||
|
|
||||||
|
`GET /songs` — branches on presence of `q` query param:
|
||||||
|
```rust
|
||||||
|
#[derive(Deserialize)]
|
||||||
|
pub struct ListQuery { pub q: Option<String> }
|
||||||
|
|
||||||
|
pub async fn list_songs(
|
||||||
|
State(state): State<Arc<AppState>>,
|
||||||
|
Query(params): Query<ListQuery>,
|
||||||
|
) -> Result<Json<Vec<SongSummary>>, ...> {
|
||||||
|
if let Some(q) = params.q.filter(|s| !s.is_empty()) {
|
||||||
|
state.search.search(&q).await ...
|
||||||
|
} else {
|
||||||
|
state.songs.list().await ...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `main.rs` wiring
|
||||||
|
|
||||||
|
Use a single `Arc<SqliteSongRepository>` shared between both services — avoids two connection pools:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
use std::sync::Arc;
|
||||||
|
let repo = Arc::new(SqliteRepositoryFactory::create(&database_url).await?);
|
||||||
|
let songs = SongService::new(Box::new(Arc::clone(&repo)));
|
||||||
|
let search = SongSearchService::new(Box::new(Arc::clone(&repo)));
|
||||||
|
```
|
||||||
|
|
||||||
|
Requires `SqliteSongRepository` to implement both ports, and `Arc<SqliteSongRepository>` to implement them via blanket delegation. In practice: implement the traits on `Arc<SqliteSongRepository>` directly, or on `SqliteSongRepository` and add `#[async_trait] impl SongRepositoryPort for Arc<SqliteSongRepository> { ... }` forwarding impls.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Backend: Edit endpoint
|
||||||
|
|
||||||
|
### New endpoint
|
||||||
|
|
||||||
|
`PATCH /songs/:id` — updates mutable metadata fields only.
|
||||||
|
|
||||||
|
**Request body:**
|
||||||
|
```json
|
||||||
|
{ "title": "New Title", "artist": "New Artist", "original_key": "Am" }
|
||||||
|
```
|
||||||
|
All fields optional. Only provided fields are updated.
|
||||||
|
|
||||||
|
**Response:** `200 OK` with updated `SongSummary`.
|
||||||
|
|
||||||
|
### Domain port update
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub trait SongRepositoryPort: Send + Sync {
|
||||||
|
async fn save(&self, song: &Song) -> Result<StoredSong, RepositoryError>;
|
||||||
|
async fn list(&self) -> Result<Vec<SongSummary>, RepositoryError>;
|
||||||
|
async fn get(&self, id: Uuid) -> Result<Option<Song>, RepositoryError>;
|
||||||
|
async fn delete(&self, id: Uuid) -> Result<(), RepositoryError>;
|
||||||
|
async fn update_meta(&self, id: Uuid, title: Option<&str>, artist: Option<&str>, original_key: Option<&str>) -> Result<SongSummary, RepositoryError>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `SongService` gains `update_meta`
|
||||||
|
|
||||||
|
Delegates to repo. Also updates `body` JSON so the full Song stays in sync:
|
||||||
|
```sql
|
||||||
|
UPDATE songs SET title = COALESCE(?, title), artist = COALESCE(?, artist),
|
||||||
|
original_key = COALESCE(?, original_key), body = ?
|
||||||
|
WHERE id = ?
|
||||||
|
```
|
||||||
|
Deserializes `body`, patches `meta`, re-serializes, writes back.
|
||||||
|
|
||||||
|
### New handler `update_song` in `songs.rs`
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub async fn update_song(
|
||||||
|
State(state): State<Arc<AppState>>,
|
||||||
|
Path(id): Path<String>,
|
||||||
|
Json(body): Json<UpdateSongRequest>,
|
||||||
|
) -> Result<Json<SongSummary>, (StatusCode, Json<ErrorResponse>)>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Frontend: Layout & Nav
|
||||||
|
|
||||||
|
### New files
|
||||||
|
|
||||||
|
- `app/app/routes/layout.tsx` — parent route shell with bottom tab bar
|
||||||
|
- `app/app/components/bottom-nav.tsx` — single Library tab
|
||||||
|
|
||||||
|
### Route config update (`app/app/routes.ts`)
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import { type RouteConfig, index, layout, route } from "@react-router/dev/routes";
|
||||||
|
|
||||||
|
export default [
|
||||||
|
layout("routes/layout.tsx", [
|
||||||
|
index("routes/home.tsx"),
|
||||||
|
route("songs/:id", "routes/songs.$id.tsx"),
|
||||||
|
]),
|
||||||
|
] satisfies RouteConfig;
|
||||||
|
```
|
||||||
|
|
||||||
|
### `layout.tsx`
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export default function Layout() {
|
||||||
|
return (
|
||||||
|
<div className="flex flex-col h-dvh">
|
||||||
|
<div className="flex-1 overflow-hidden">
|
||||||
|
<Outlet />
|
||||||
|
</div>
|
||||||
|
<BottomNav />
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `bottom-nav.tsx`
|
||||||
|
|
||||||
|
Single tab: Library icon + label, links to `/`, highlights when active (`useLocation`).
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<nav className="border-t bg-background">
|
||||||
|
<NavLink to="/" className={({ isActive }) => ...}>
|
||||||
|
<Music className="w-5 h-5" />
|
||||||
|
<span className="text-xs">Library</span>
|
||||||
|
</NavLink>
|
||||||
|
</nav>
|
||||||
|
```
|
||||||
|
|
||||||
|
Uses `NavLink` from react-router for active state styling.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Frontend: Live Search
|
||||||
|
|
||||||
|
### `home.tsx` changes
|
||||||
|
|
||||||
|
- Remove `useState(query)` client-side filter
|
||||||
|
- Add `useSearchParams` hook — search term lives in URL (`?q=…`)
|
||||||
|
- Debounce input changes (300ms) before updating URL param
|
||||||
|
- Loader reads `q` from `request.url` and calls `listSongs(q)` or `listSongs()`
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// loader
|
||||||
|
export async function loader({ request }: Route.LoaderArgs) {
|
||||||
|
const q = new URL(request.url).searchParams.get("q") ?? "";
|
||||||
|
const songs = await listSongs(q);
|
||||||
|
return { songs, q };
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// api.ts
|
||||||
|
export async function listSongs(q = ""): Promise<SongSummary[]> {
|
||||||
|
const url = q ? `${API_BASE}/songs?q=${encodeURIComponent(q)}` : `${API_BASE}/songs`;
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Component uses `useNavigate` + `useSearchParams` + debounced `setSearchParams`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Frontend: Song Management
|
||||||
|
|
||||||
|
### `TransposeBar` update
|
||||||
|
|
||||||
|
Add `onEdit` and `onDelete` prop callbacks. Add `DropdownMenu` (shadcn) triggered by a `MoreHorizontal` icon button in the header row.
|
||||||
|
|
||||||
|
Menu items:
|
||||||
|
- **Edit** → calls `onEdit()`
|
||||||
|
- **Delete** → calls `onDelete()`
|
||||||
|
|
||||||
|
### New `EditSongSheet` component (`app/app/components/edit-song-sheet.tsx`)
|
||||||
|
|
||||||
|
Bottom `Sheet` with three inputs: Title, Artist, Key. Pre-filled from current `SongMeta`. Submit calls `updateSong(id, { title, artist, original_key })` → updates `song.meta` in component state → closes sheet.
|
||||||
|
|
||||||
|
### New `DeleteSongDialog` component (`app/app/components/delete-song-dialog.tsx`)
|
||||||
|
|
||||||
|
`AlertDialog` (shadcn): "Are you sure? This cannot be undone." Confirm → `deleteSong(id)` → navigate to `/`.
|
||||||
|
|
||||||
|
### `songs.$id.tsx` changes
|
||||||
|
|
||||||
|
- Import `EditSongSheet`, `DeleteSongDialog`
|
||||||
|
- Track `editOpen`, `deleteOpen` state
|
||||||
|
- Pass `onEdit`/`onDelete` to `TransposeBar`
|
||||||
|
|
||||||
|
### New `api.ts` helpers
|
||||||
|
|
||||||
|
```ts
|
||||||
|
export async function updateSong(id: string, patch: {
|
||||||
|
title?: string; artist?: string; original_key?: string;
|
||||||
|
}): Promise<SongSummary>
|
||||||
|
|
||||||
|
export async function deleteSong(id: string): Promise<void> // already exists
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Frontend: Error States
|
||||||
|
|
||||||
|
### Library (`home.tsx`)
|
||||||
|
|
||||||
|
Loader catches API errors and returns `{ songs: [], error: true }`. Component shows inline error when `error` is true:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
{loaderData.error && (
|
||||||
|
<div className="flex flex-col items-center gap-3 pt-12 text-center px-6">
|
||||||
|
<p className="text-sm text-muted-foreground">
|
||||||
|
Couldn't load your songs. Is the API running?
|
||||||
|
</p>
|
||||||
|
<Button variant="outline" size="sm" onClick={() => revalidator.revalidate()}>
|
||||||
|
Retry
|
||||||
|
</Button>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
```
|
||||||
|
|
||||||
|
Uses `useRevalidator` from react-router for the retry.
|
||||||
|
|
||||||
|
### Song detail (`songs.$id.tsx`)
|
||||||
|
|
||||||
|
`getSong` returns `null` on 404 or throws on network error. Loader returns `{ song: null }` on any failure. Component shows:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
{!song && (
|
||||||
|
<div className="flex flex-col items-center justify-center h-full gap-4">
|
||||||
|
<p className="text-muted-foreground">Song not found or unavailable.</p>
|
||||||
|
<Link to="/" className="text-sm text-primary">← Back to library</Link>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Transient errors (toasts)
|
||||||
|
|
||||||
|
`sonner` is already in the project. Import `toast` from `sonner`. Fire on:
|
||||||
|
- Add song failure: `toast.error("Failed to import song", { description: err.message })`
|
||||||
|
- Delete failure: `toast.error("Failed to delete song")`
|
||||||
|
- Edit failure: `toast.error("Failed to save changes")`
|
||||||
|
|
||||||
|
Add `<Toaster />` to `layout.tsx` (one location, covers all pages).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## New/Modified Files Summary
|
||||||
|
|
||||||
|
**Rust:**
|
||||||
|
- `crates/domain/src/ports.rs` — add `SongSearchPort`, add `update_meta` to `SongRepositoryPort`
|
||||||
|
- `crates/domain/src/lib.rs` — re-export `SongSearchPort`
|
||||||
|
- `crates/infrastructure/persistence/src/lib.rs` — impl `SongSearchPort`, impl `update_meta`
|
||||||
|
- `crates/common/src/lib.rs` — add `SongSearchService`, add `SongService::update_meta`
|
||||||
|
- `crates/api/src/routes/tabs.rs` — add `search: SongSearchService` to `AppState`
|
||||||
|
- `crates/api/src/routes/songs.rs` — update `list_songs` for `?q=`, add `update_song`
|
||||||
|
- `crates/api/src/main.rs` — wire `SongSearchService`, add `PATCH /songs/{id}`
|
||||||
|
|
||||||
|
**Frontend:**
|
||||||
|
- `app/app/routes.ts` — add layout route
|
||||||
|
- `app/app/routes/layout.tsx` — new shell with `<Outlet>` + `<BottomNav>`
|
||||||
|
- `app/app/components/bottom-nav.tsx` — new single-tab nav
|
||||||
|
- `app/app/routes/home.tsx` — URL-based search params, loader uses `q`
|
||||||
|
- `app/app/routes/songs.$id.tsx` — edit/delete integration, null error state
|
||||||
|
- `app/app/components/transpose-bar.tsx` — add DropdownMenu with Edit/Delete
|
||||||
|
- `app/app/components/edit-song-sheet.tsx` — new edit sheet
|
||||||
|
- `app/app/components/delete-song-dialog.tsx` — new confirm dialog
|
||||||
|
- `app/app/lib/api.ts` — update `listSongs(q?)`, add `updateSong`
|
||||||
|
- `app/app/lib/types.ts` — add `UpdateSongRequest`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
1. `cargo build --workspace` — clean
|
||||||
|
2. `cargo test --workspace` — all pass
|
||||||
|
3. `GET /songs?q=ocean` returns songs matching title/artist
|
||||||
|
4. `PATCH /songs/:id` with `{ "title": "New" }` updates title, leaves rest unchanged
|
||||||
|
5. Library search input debounces — network tab shows requests fire 300ms after typing stops
|
||||||
|
6. Song detail `⋯` menu shows Edit and Delete
|
||||||
|
7. Edit sheet pre-fills current values, saves successfully
|
||||||
|
8. Delete dialog navigates back to library on confirm
|
||||||
|
9. With API stopped: library shows "Couldn't load" inline + Retry; detail shows "← Back"
|
||||||
|
10. Failed add/delete fires a sonner toast
|
||||||
|
11. Bottom nav tab highlights on `/`, not highlighted on `/songs/:id`
|
||||||
|
12. `npm run typecheck` — clean
|
||||||
Reference in New Issue
Block a user