Add stage 4: frontend lists view + enforce 100-list cap

API: GET /api/lists is now ordered alphabetically (COLLATE NOCASE) by title
with no other option, and TodoListController rejects a create past 100 lists
per owner with 409. New TodoListRepository::countForOwner.

Frontend: HomeView replaces the placeholder with the user's lists (rendered in
API order) and a create form (title + optional description). New Pinia lists
store fetches and creates, re-fetching after a create so the new list sorts
into place; it is reset on logout. Form disables and explains at 100 lists;
create errors surface inline. Neutral .badge with a .badge--warn variant;
dropped the unused .facts styles.

Tests: alphabetical ordering and the 100-list cap. Suite: 17 passing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -10,7 +10,8 @@ SQLite file, plus a Vue 3 + TypeScript PWA frontend in [web/](web/).
 | 1 | Auth API — register, login, `GET /me` | ✅ done |
 | 2 | Frontend shell — Vite PWA, auth-gated routing, register/login pages | ✅ done |
 | 3 | Todo list + item CRUD API | ✅ done |
-| 4 | Todo UI in the frontend | planned |
+| 4 | Frontend lists view — list index + create form | ✅ done |
+| 5 | Frontend list detail — items UI | planned |
 
 Registration signs the user in immediately, with the account's email marked
 unverified (`user.email_verified` is `false` until a future stage adds a
@@ -180,12 +181,16 @@ owner (the creator); another user's list — or a missing one — always respond
 
 | Method | Path | Purpose |
 |--------|------|---------|
-| `GET` | `/api/lists` | the caller's lists, newest first |
+| `GET` | `/api/lists` | the caller's lists, sorted A→Z by title |
 | `POST` | `/api/lists` | create a list |
 | `GET` | `/api/lists/{id}` | one list |
 | `PATCH` | `/api/lists/{id}` | update `title` and/or `description` |
 | `DELETE` | `/api/lists/{id}` | delete the list and its items (`204`) |
 
+`GET /api/lists` is always ordered alphabetically (case-insensitive) by title;
+there is no other sort option. A user may own at most **100 lists** — creating
+one beyond that responds `409`.
+
 Create/update body: `title` (required on create, 1–255 chars), `description`
 (optional, ≤ 2000 chars, defaults to `""`). `PATCH` needs at least one field.
 

src/Http/Controllers/TodoListController.php

@@ -18,6 +18,7 @@ final class TodoListController extends Controller
 {
     private const TITLE_MAX = 255;
     private const DESCRIPTION_MAX = 2000;
+    private const MAX_LISTS_PER_OWNER = 100;
 
     public function __construct(private readonly TodoListRepository $lists)
     {
@@ -38,12 +39,21 @@ final class TodoListController extends Controller
      */
     public function store(Request $request, Response $response): Response
     {
+        $ownerId = $this->user($request)['id'];
+
         $validator = new Validator($this->body($request));
         $title = $validator->requiredString('title', self::TITLE_MAX);
         $description = $validator->optionalString('description', self::DESCRIPTION_MAX) ?? '';
         $validator->assert();
 
-        $list = $this->lists->create($this->user($request)['id'], $title, $description);
+        if ($this->lists->countForOwner($ownerId) >= self::MAX_LISTS_PER_OWNER) {
+            throw new ApiException(
+                sprintf('You have reached the maximum of %d lists.', self::MAX_LISTS_PER_OWNER),
+                409,
+            );
+        }
+
+        $list = $this->lists->create($ownerId, $title, $description);
 
         return $this->json($response, ['list' => $this->present($list)], 201);
     }

src/Repository/TodoListRepository.php

@@ -28,16 +28,29 @@ final class TodoListRepository
     }
 
     /**
+     * Every list owned by the user, always sorted alphabetically by title
+     * (case-insensitive). There is deliberately no other ordering option.
+     *
      * @return TodoListRow[]
      */
     public function allForOwner(int $ownerId): array
     {
-        $stmt = $this->pdo->prepare(self::SELECT . ' WHERE l.owner_id = :owner ORDER BY l.created_at DESC, l.id DESC');
+        $stmt = $this->pdo->prepare(
+            self::SELECT . ' WHERE l.owner_id = :owner ORDER BY l.title COLLATE NOCASE ASC, l.id ASC'
+        );
         $stmt->execute(['owner' => $ownerId]);
 
         return array_map($this->cast(...), $stmt->fetchAll());
     }
 
+    public function countForOwner(int $ownerId): int
+    {
+        $stmt = $this->pdo->prepare('SELECT COUNT(*) FROM todo_lists WHERE owner_id = :owner');
+        $stmt->execute(['owner' => $ownerId]);
+
+        return (int) $stmt->fetchColumn();
+    }
+
     /**
      * @return TodoListRow|null
      */

tests/TodoTest.php

@@ -31,6 +31,36 @@ final class TodoTest extends ApiTestCase
         self::assertSame($list['id'], $index['lists'][0]['id']);
     }
 
+    public function test_lists_come_back_alphabetically(): void
+    {
+        $auth = $this->authHeader();
+
+        foreach (['Banana', 'apple', 'Cherry'] as $title) {
+            $this->request('POST', '/api/lists', ['title' => $title], $auth);
+        }
+
+        $titles = array_column($this->decode($this->request('GET', '/api/lists', null, $auth))['lists'], 'title');
+        self::assertSame(['apple', 'Banana', 'Cherry'], $titles);
+    }
+
+    public function test_an_owner_cannot_exceed_100_lists(): void
+    {
+        $auth = $this->authHeader();
+
+        for ($i = 1; $i <= 100; $i++) {
+            $response = $this->request('POST', '/api/lists', ['title' => "List {$i}"], $auth);
+            self::assertSame(201, $response->getStatusCode(), "list {$i} should be created");
+        }
+
+        $overflow = $this->request('POST', '/api/lists', ['title' => 'One too many'], $auth);
+        self::assertSame(409, $overflow->getStatusCode());
+        self::assertStringContainsString('100', $this->decode($overflow)['error']['message']);
+
+        // The cap is per owner, so a different user is unaffected.
+        $other = $this->authHeader('roomy@example.com');
+        self::assertSame(201, $this->request('POST', '/api/lists', ['title' => 'Fine'], $other)->getStatusCode());
+    }
+
     public function test_list_creation_validates_title(): void
     {
         $response = $this->request('POST', '/api/lists', ['description' => 'no title'], $this->authHeader());

web/README.md

@@ -38,8 +38,9 @@ npm run preview
 src/main.ts            App bootstrap; resolves the stored session before mount
 src/router/index.ts    Routes + guard (redirects to /login when unauthenticated)
 src/stores/auth.ts     Pinia store: token in localStorage, register/login/fetchMe
+src/stores/lists.ts    Pinia store: the user's lists (fetch + create)
 src/lib/api.ts         fetch wrapper, bearer token, typed ApiError
-src/views/             HomeView (placeholder), LoginView, RegisterView
+src/views/             HomeView (lists + create form), LoginView, RegisterView
 ```
 
 ## Auth flow

web/src/App.vue

@@ -1,12 +1,15 @@
 <script setup lang="ts">
 import { RouterView, useRouter } from 'vue-router'
 import { useAuthStore } from './stores/auth'
+import { useListsStore } from './stores/lists'
 
 const auth = useAuthStore()
+const lists = useListsStore()
 const router = useRouter()
 
 async function onLogout() {
   auth.logout()
+  lists.reset()
   await router.push({ name: 'login' })
 }
 </script>

web/src/stores/lists.ts

@@ -0,0 +1,44 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { apiRequest } from '../lib/api'
+import type { TodoList } from '../types'
+
+/** Matches MAX_LISTS_PER_OWNER on the API. */
+export const MAX_LISTS = 100
+
+export const useListsStore = defineStore('lists', () => {
+  // Kept in the order the API returns them (alphabetical by title).
+  const lists = ref<TodoList[]>([])
+  const loaded = ref(false)
+  const loading = ref(false)
+
+  async function fetchLists(): Promise<void> {
+    loading.value = true
+    try {
+      const { lists: fetched } = await apiRequest<{ lists: TodoList[] }>('/lists', { auth: true })
+      lists.value = fetched
+      loaded.value = true
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function createList(title: string, description: string): Promise<TodoList> {
+    const { list } = await apiRequest<{ list: TodoList }>('/lists', {
+      method: 'POST',
+      auth: true,
+      body: { title, description },
+    })
+
+    // Re-fetch so the new list lands in its correct alphabetical position.
+    await fetchLists()
+    return list
+  }
+
+  function reset(): void {
+    lists.value = []
+    loaded.value = false
+  }
+
+  return { lists, loaded, loading, fetchLists, createList, reset }
+})

web/src/style.css

@@ -100,32 +100,46 @@ h1 {
   padding: 0.1rem 0.45rem;
   border-radius: 999px;
   font-size: 0.75rem;
-  border: 1px solid var(--warn-border);
+  white-space: nowrap;
-  background: var(--warn-bg);
+  border: 1px solid var(--border);
+  background: var(--bg);
+  color: var(--muted);
 }
 
-.facts {
+.badge--warn {
-  margin: 1.25rem 0 0;
+  border-color: var(--warn-border);
+  background: var(--warn-bg);
+  color: inherit;
+}
+
+.lists {
+  list-style: none;
+  margin: 1.5rem 0 0;
+  padding: 0;
   display: grid;
   gap: 0.75rem;
 }
 
-.facts div {
+.lists__item {
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 0.75rem 0.9rem;
+}
+
+.lists__head {
   display: flex;
+  align-items: center;
   justify-content: space-between;
-  gap: 1rem;
+  gap: 0.75rem;
-  border-top: 1px solid var(--border);
-  padding-top: 0.6rem;
 }
 
-.facts dt {
+.lists__title {
-  color: var(--muted);
+  font-weight: 600;
+  word-break: break-word;
 }
 
-.facts dd {
+.lists__item .muted {
-  margin: 0;
+  margin: 0.35rem 0 0;
-  text-align: right;
-  word-break: break-all;
 }
 
 .form {

web/src/types.ts

@@ -12,6 +12,17 @@ export interface AuthResponse {
   expires_at: string
 }
 
+export interface TodoList {
+  id: number
+  title: string
+  description: string
+  owner_id: number
+  item_count: number
+  completed_count: number
+  created_at: string
+  updated_at: string
+}
+
 /** Shape of every error body returned by the API. */
 export interface ApiErrorBody {
   error: {

web/src/views/HomeView.vue

@@ -1,35 +1,95 @@
 <script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import { ApiError } from '../lib/api'
 import { useAuthStore } from '../stores/auth'
+import { MAX_LISTS, useListsStore } from '../stores/lists'
 
 const auth = useAuthStore()
+const lists = useListsStore()
+
+const loadError = ref<string | null>(null)
+
+const title = ref('')
+const description = ref('')
+const createError = ref<ApiError | null>(null)
+const submitting = ref(false)
+
+onMounted(load)
+
+async function load() {
+  loadError.value = null
+  try {
+    await lists.fetchLists()
+  } catch (e) {
+    loadError.value = e instanceof ApiError ? e.message : 'Could not load your lists.'
+  }
+}
+
+async function onCreate() {
+  submitting.value = true
+  createError.value = null
+  try {
+    await lists.createList(title.value, description.value)
+    title.value = ''
+    description.value = ''
+  } catch (e) {
+    createError.value = e instanceof ApiError ? e : new ApiError('Could not create the list.', 0)
+  } finally {
+    submitting.value = false
+  }
+}
 </script>
 
 <template>
   <section class="card">
-    <h1>Your todo list</h1>
+    <h1>Your lists</h1>
-    <p class="muted">
-      Placeholder page. The list and its items arrive in the next stage — for now
-      this screen just proves you are authenticated against the REST API.
-    </p>
 
     <div v-if="!auth.emailVerified" class="notice">
       Your email address <strong>{{ auth.user?.email }}</strong> has not been
-      verified yet. Verification will be added in a later stage.
+      verified yet.
     </div>
 
-    <dl class="facts">
+    <form class="form" @submit.prevent="onCreate">
-      <div>
+      <label>
-        <dt>Signed in as</dt>
+        <span>New list title</span>
-        <dd>{{ auth.user?.email }}</dd>
+        <input v-model="title" type="text" maxlength="255" required :disabled="lists.lists.length >= MAX_LISTS" />
+        <small v-if="createError?.fieldError('title')" class="field-error">
+          {{ createError.fieldError('title') }}
+        </small>
+      </label>
+
+      <label>
+        <span>Description <span class="hint">(optional)</span></span>
+        <input v-model="description" type="text" maxlength="2000" :disabled="lists.lists.length >= MAX_LISTS" />
+      </label>
+
+      <p v-if="createError && Object.keys(createError.details).length === 0" class="form-error">
+        {{ createError.message }}
+      </p>
+
+      <button type="submit" :disabled="submitting || lists.lists.length >= MAX_LISTS">
+        {{ submitting ? 'Creating…' : 'Create list' }}
+      </button>
+
+      <p v-if="lists.lists.length >= MAX_LISTS" class="hint">
+        You have reached the maximum of {{ MAX_LISTS }} lists.
+      </p>
+    </form>
+
+    <p v-if="loadError" class="form-error">{{ loadError }}</p>
+    <p v-else-if="lists.loading && !lists.loaded" class="muted">Loading…</p>
+    <p v-else-if="lists.lists.length === 0" class="muted">
+      No lists yet — create your first one above.
+    </p>
+
+    <ul v-else class="lists">
+      <li v-for="list in lists.lists" :key="list.id" class="lists__item">
+        <div class="lists__head">
+          <span class="lists__title">{{ list.title }}</span>
+          <span class="badge">{{ list.completed_count }} / {{ list.item_count }} done</span>
         </div>
-      <div>
+        <p v-if="list.description" class="muted">{{ list.description }}</p>
-        <dt>Account created</dt>
+      </li>
-        <dd>{{ auth.user?.created_at ?? '—' }}</dd>
+    </ul>
-      </div>
-      <div>
-        <dt>Email verified</dt>
-        <dd>{{ auth.emailVerified ? 'yes' : 'no' }}</dd>
-      </div>
-    </dl>
   </section>
 </template>