M9 S3 (frontend): recall views adopt useNoteList + AsyncState/EmptyState

The Search / Timeline / Reminders views each hand-rolled the same
items+loading+error scaffold, retry button, and editor-host glue.

- useNoteList(fetcher, fallbackError) (new): the load-a-note-list scaffold
  (items/loading/error + a load() that never leaves a half-state). Views
  supply just the fetcher; the refs drive <AsyncState>.
- SearchView / TimelineView / RemindersView: adopt useNoteList + useNoteEditor
  + <AsyncState>/<EmptyState>; drop the local list/loading/error refs, the
  duplicated retry blocks, and the notes.items-shadowing navigate glue.
- GraphView: editor host now via useNoteEditor (openNode/closeEditor/onNavigate
  collapse to navigate); loading/error via <AsyncState>. Its two empty states
  keep inline markup/buttons, so they stay custom (not forced into EmptyState).
- reminders store: fetchReminders() is the single owner of /api/notes/reminders;
  both the background poll (check) and RemindersView read through it.

Frontend-only; CI vue-tsc is the type gate (no local typecheck, rule 10).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm

frontend/src/composables/useNoteList.ts

@@ -0,0 +1,38 @@
+import { ref, type Ref } from "vue";
+import type { Note } from "../stores/notes";
+
+// The load-a-list-of-notes scaffold every recall view (Search, Timeline, Reminders)
+// hand-rolled: an items ref + loading/error flags + a load() that fills them and never
+// leaves a half-state. The view supplies just the fetcher; wire the returned refs into
+// <AsyncState> and pass `items` to <EmptyState>/cards.
+//
+// `fetcher` returns the notes to show (or [] — e.g. an empty search box). A thrown
+// ApiError's `.error` becomes the message; otherwise `fallbackError` is shown.
+export function useNoteList(
+  fetcher: () => Promise<Note[]>,
+  fallbackError = "Couldn't load your notes.",
+): {
+  items: Ref<Note[]>;
+  loading: Ref<boolean>;
+  error: Ref<string>;
+  load: () => Promise<void>;
+} {
+  const items = ref<Note[]>([]);
+  const loading = ref(false);
+  const error = ref("");
+
+  async function load(): Promise<void> {
+    loading.value = true;
+    error.value = "";
+    try {
+      items.value = await fetcher();
+    } catch (e) {
+      error.value = (e as { error?: string }).error ?? fallbackError;
+      items.value = [];
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  return { items, loading, error, load };
+}

frontend/src/stores/reminders.ts

@@ -20,11 +20,17 @@ export const useReminderStore = defineStore("reminders", () => {
   let timer: ReturnType<typeof setInterval> | undefined;
   let primed = false;
 
+  // Single owner of the reminders endpoint — the RemindersView reads its list through
+  // this too, so the URL + response shape live in one place.
+  async function fetchReminders(): Promise<Note[]> {
+    return (await api.get<{ notes: Note[] }>("/api/notes/reminders")).notes;
+  }
+
   async function check(): Promise<void> {
     const ui = useUiStore();
     let notes: Note[];
     try {
-      notes = (await api.get<{ notes: Note[] }>("/api/notes/reminders")).notes;
+      notes = await fetchReminders();
     } catch {
       return;
     }
@@ -66,5 +72,5 @@ export const useReminderStore = defineStore("reminders", () => {
     osEnabled.value = (await Notification.requestPermission()) === "granted";
   }
 
-  return { osSupported, osEnabled, start, stop, enableOs };
+  return { osSupported, osEnabled, start, stop, enableOs, fetchReminders };
 });

frontend/src/views/GraphView.vue

@@ -2,8 +2,9 @@
 import { computed, onBeforeUnmount, onMounted, ref } from "vue";
 import { useRouter } from "vue-router";
 import { api } from "../api/client";
-import { useNotesStore, type Note } from "../stores/notes";
 import { NOTE_NODE_FILL, type NoteColor } from "../notes/colors";
+import { useNoteEditor } from "../composables/useNoteEditor";
+import AsyncState from "../components/AsyncState.vue";
 import NoteEditor from "../components/NoteEditor.vue";
 
 type NodeKind = "note" | "label";
@@ -29,12 +30,12 @@ const WIDTH = 1000;
 const HEIGHT = 700;
 
 const router = useRouter();
-const notes = useNotesStore();
 const allNodes = ref<GNode[]>([]);
 const edges = ref<GEdge[]>([]);
 const loading = ref(true);
 const error = ref("");
-const editing = ref<Note | null>(null);
+// Editor host: resolve a node id against the store, else fetch (shared controller).
+const { editing, close: closeEditor, navigate } = useNoteEditor();
 // Unlinked notes float in the space by default — the graph is a gentle overview,
 // not a links-only surface. Label hubs are on by default so tags cluster notes.
 const showAll = ref(true);
@@ -263,7 +264,7 @@ function clickNode(n: GNode) {
     void router.push(`/label/${n.labelId}`);
     return;
   }
-  void openNode(n);
+  void navigate(n.id);
 }
 
 function onWheel(e: WheelEvent) {
@@ -293,18 +294,6 @@ function toggleLabels() {
   reheat();
 }
 
-async function openNode(n: GNode) {
-  const found = notes.items.find((x) => x.id === n.id);
-  editing.value = found ?? (await notes.fetchOne(n.id));
-}
-function closeEditor() {
-  editing.value = null;
-}
-async function onNavigate(id: string) {
-  const found = notes.items.find((x) => x.id === id);
-  editing.value = found ?? (await notes.fetchOne(id));
-}
-
 onMounted(loadGraph);
 onBeforeUnmount(() => {
   cancelAnimationFrame(raf);
@@ -336,21 +325,13 @@ onBeforeUnmount(() => {
       </div>
     </div>
 
-    <div v-if="loading" class="py-24 text-center text-sm text-neutral-400">Loading graph…</div>
-
-    <div v-else-if="error" class="py-24 text-center">
-      <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">Couldn't load the graph</h2>
-      <p class="mt-1 text-sm text-neutral-400">{{ error }}</p>
-      <button
-        type="button"
-        class="mt-3 rounded-md border border-neutral-300 px-3 py-1.5 text-sm hover:bg-neutral-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand dark:border-neutral-700 dark:hover:bg-neutral-800"
-        @click="loadGraph"
-      >
-        Retry
-      </button>
-    </div>
-
-    <div v-else-if="allNodes.length === 0" class="py-24 text-center">
+    <AsyncState
+      :loading="loading"
+      :error="error || undefined"
+      error-title="Couldn't load the graph"
+      @retry="loadGraph"
+    >
+    <div v-if="allNodes.length === 0" class="py-24 text-center">
       <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">No notes yet</h2>
       <p class="mt-1 text-sm text-neutral-400">
         Create notes and link them with
@@ -430,9 +411,10 @@ onBeforeUnmount(() => {
         </g>
       </svg>
     </div>
+    </AsyncState>
 
     <template v-if="editing">
-      <NoteEditor :note="editing" @close="closeEditor" @navigate="onNavigate" />
+      <NoteEditor :note="editing" @close="closeEditor" @navigate="navigate" />
     </template>
   </div>
 </template>

frontend/src/views/RemindersView.vue

@@ -1,42 +1,23 @@
 <script setup lang="ts">
-import { onMounted, ref } from "vue";
-import { api } from "../api/client";
+import { onMounted } from "vue";
 import { useNotesStore, type Note } from "../stores/notes";
 import { useReminderStore } from "../stores/reminders";
 import { formatReminder, isOverdue } from "../notes/datetime";
+import { useNoteList } from "../composables/useNoteList";
+import { useNoteEditor } from "../composables/useNoteEditor";
+import AsyncState from "../components/AsyncState.vue";
+import EmptyState from "../components/EmptyState.vue";
 import NoteEditor from "../components/NoteEditor.vue";
 
 const notes = useNotesStore();
 const reminders = useReminderStore();
-const items = ref<Note[]>([]);
-const loading = ref(true);
-const error = ref("");
-const editing = ref<Note | null>(null);
 
-async function load() {
-  loading.value = true;
-  error.value = "";
-  try {
-    items.value = (await api.get<{ notes: Note[] }>("/api/notes/reminders")).notes;
-  } catch (e) {
-    error.value = (e as { error?: string }).error ?? "Couldn't load reminders.";
-    items.value = [];
-  } finally {
-    loading.value = false;
-  }
-}
+const { items, loading, error, load } = useNoteList(() => reminders.fetchReminders(), "Couldn't load reminders.");
 
-function openEditor(n: Note) {
-  editing.value = n;
-}
-async function closeEditor() {
-  editing.value = null;
-  await load();
-}
-async function onNavigate(id: string) {
-  const found = items.value.find((n) => n.id === id) ?? notes.items.find((n) => n.id === id);
-  editing.value = found ?? (await notes.fetchOne(id));
-}
+const { editing, open: openEditor, close: closeEditor, navigate: onNavigate } = useNoteEditor({
+  list: () => items.value,
+  onClose: load,
+});
 
 async function done(n: Note) {
   await notes.completeReminder(n.id);
@@ -68,64 +49,52 @@ onMounted(load);
       Due reminders pop up while ThoughtSync is open. Background alerts arrive with the desktop &amp; mobile apps.
     </p>
 
-    <div v-if="loading" class="py-24 text-center text-sm text-neutral-400">Loading…</div>
-
-    <div v-else-if="error" class="py-24 text-center">
-      <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">Couldn't load reminders</h2>
-      <p class="mt-1 text-sm text-neutral-400">{{ error }}</p>
-      <button
-        type="button"
-        class="mt-3 rounded-md border border-neutral-300 px-3 py-1.5 text-sm hover:bg-neutral-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand dark:border-neutral-700 dark:hover:bg-neutral-800"
-        @click="load"
-      >
-        Retry
-      </button>
-    </div>
-
-    <div v-else-if="items.length === 0" class="py-24 text-center">
-      <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">No reminders</h2>
-      <p class="mt-1 text-sm text-neutral-400">Set a reminder on a note (in its editor) to see it here.</p>
-    </div>
-
-    <ul v-else class="divide-y divide-neutral-100 dark:divide-neutral-800">
-      <li v-for="n in items" :key="n.id" class="flex items-center gap-3 py-3">
-        <button
-          type="button"
-          class="min-w-0 flex-1 rounded text-left focus:outline-none focus-visible:ring-2 focus-visible:ring-brand"
-          @click="openEditor(n)"
-        >
-          <p class="truncate text-sm font-medium text-neutral-800 dark:text-neutral-100">
-            {{ n.display_title || "Untitled" }}
-          </p>
-          <p class="text-xs" :class="isOverdue(n.remind_at) ? 'text-red-500 dark:text-red-400' : 'text-neutral-400'">
-            {{ formatReminder(n.remind_at) }}<span v-if="n.recurrence"> · ↻ {{ n.recurrence }}</span>
-          </p>
-        </button>
-        <button
-          type="button"
-          class="shrink-0 rounded-md border border-neutral-300 px-2 py-1 text-xs text-neutral-600 hover:bg-neutral-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand dark:border-neutral-700 dark:text-neutral-300 dark:hover:bg-neutral-800"
-          @click="done(n)"
-        >
-          Done
-        </button>
-        <button
-          type="button"
-          class="shrink-0 text-xs text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-200"
-          title="Snooze 1 hour"
-          @click="snooze(n, 60)"
-        >
-          1h
-        </button>
-        <button
-          type="button"
-          class="shrink-0 text-xs text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-200"
-          title="Snooze 1 day"
-          @click="snooze(n, 1440)"
-        >
-          1d
-        </button>
-      </li>
-    </ul>
+    <AsyncState :loading="loading" :error="error || undefined" error-title="Couldn't load reminders" @retry="load">
+      <EmptyState
+        v-if="items.length === 0"
+        title="No reminders"
+        subtitle="Set a reminder on a note (in its editor) to see it here."
+      />
+      <ul v-else class="divide-y divide-neutral-100 dark:divide-neutral-800">
+        <li v-for="n in items" :key="n.id" class="flex items-center gap-3 py-3">
+          <button
+            type="button"
+            class="min-w-0 flex-1 rounded text-left focus:outline-none focus-visible:ring-2 focus-visible:ring-brand"
+            @click="openEditor(n)"
+          >
+            <p class="truncate text-sm font-medium text-neutral-800 dark:text-neutral-100">
+              {{ n.display_title || "Untitled" }}
+            </p>
+            <p class="text-xs" :class="isOverdue(n.remind_at) ? 'text-red-500 dark:text-red-400' : 'text-neutral-400'">
+              {{ formatReminder(n.remind_at) }}<span v-if="n.recurrence"> · ↻ {{ n.recurrence }}</span>
+            </p>
+          </button>
+          <button
+            type="button"
+            class="shrink-0 rounded-md border border-neutral-300 px-2 py-1 text-xs text-neutral-600 hover:bg-neutral-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand dark:border-neutral-700 dark:text-neutral-300 dark:hover:bg-neutral-800"
+            @click="done(n)"
+          >
+            Done
+          </button>
+          <button
+            type="button"
+            class="shrink-0 text-xs text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-200"
+            title="Snooze 1 hour"
+            @click="snooze(n, 60)"
+          >
+            1h
+          </button>
+          <button
+            type="button"
+            class="shrink-0 text-xs text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-200"
+            title="Snooze 1 day"
+            @click="snooze(n, 1440)"
+          >
+            1d
+          </button>
+        </li>
+      </ul>
+    </AsyncState>
 
     <template v-if="editing">
       <NoteEditor :note="editing" @close="closeEditor" @navigate="onNavigate" />

frontend/src/views/SearchView.vue

@@ -1,58 +1,31 @@
 <script setup lang="ts">
-import { computed, ref, watch } from "vue";
+import { computed, watch } from "vue";
 import { useRoute } from "vue-router";
 import { api } from "../api/client";
-import { useNotesStore, type Note } from "../stores/notes";
+import { type Note } from "../stores/notes";
+import { useNoteList } from "../composables/useNoteList";
+import { useNoteEditor } from "../composables/useNoteEditor";
+import AsyncState from "../components/AsyncState.vue";
+import EmptyState from "../components/EmptyState.vue";
 import NoteCard from "../components/NoteCard.vue";
 import NoteEditor from "../components/NoteEditor.vue";
 
 const route = useRoute();
-const notes = useNotesStore();
-
-const results = ref<Note[]>([]);
-const loading = ref(false);
-const error = ref("");
-const editing = ref<Note | null>(null);
-
 const query = computed(() => (typeof route.query.q === "string" ? route.query.q : ""));
+const noMatchSubtitle = computed(() => `Nothing found for "${query.value}".`);
 
-async function run() {
+const { items: results, loading, error, load: run } = useNoteList(async () => {
   const q = query.value.trim();
-  if (!q) {
-    results.value = [];
-    return;
-  }
-  loading.value = true;
-  error.value = "";
-  try {
-    const res = await api.get<{ notes: Note[] }>(`/api/notes/search?q=${encodeURIComponent(q)}`);
-    results.value = res.notes;
-  } catch (e) {
-    error.value = (e as { error?: string }).error ?? "Search failed.";
-    results.value = [];
-  } finally {
-    loading.value = false;
-  }
-}
+  if (!q) return [];
+  return (await api.get<{ notes: Note[] }>(`/api/notes/search?q=${encodeURIComponent(q)}`)).notes;
+}, "Search failed.");
+
+const { editing, open: openEditor, close: closeEditor, navigate: onNavigate } = useNoteEditor({
+  list: () => results.value,
+  onClose: run, // reflect any edits made from a result
+});
 
 watch(query, run, { immediate: true });
-
-function openEditor(n: Note) {
-  editing.value = n;
-}
-async function closeEditor() {
-  editing.value = null;
-  await run(); // reflect any edits made from a result
-}
-async function onNavigate(id: string) {
-  const found = results.value.find((n) => n.id === id);
-  if (found) {
-    editing.value = found;
-    return;
-  }
-  const fetched = await notes.fetchOne(id);
-  if (fetched) editing.value = fetched;
-}
 </script>
 
 <template>
@@ -64,28 +37,12 @@ async function onNavigate(id: string) {
       <template v-else>Type in the search box to find your notes.</template>
     </p>
 
-    <div v-if="loading" class="py-20 text-center text-sm text-neutral-400">Searching…</div>
-
-    <div v-else-if="error" class="py-20 text-center">
-      <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">Couldn't search</h2>
-      <p class="mt-1 text-sm text-neutral-400">{{ error }}</p>
-      <button
-        type="button"
-        class="mt-3 rounded-md border border-neutral-300 px-3 py-1.5 text-sm hover:bg-neutral-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand dark:border-neutral-700 dark:hover:bg-neutral-800"
-        @click="run"
-      >
-        Retry
-      </button>
-    </div>
-
-    <div v-else-if="query && results.length === 0" class="py-20 text-center">
-      <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">No matches</h2>
-      <p class="mt-1 text-sm text-neutral-400">Nothing found for "{{ query }}".</p>
-    </div>
-
-    <div v-else class="columns-1 gap-4 sm:columns-2 lg:columns-3 xl:columns-4">
-      <NoteCard v-for="n in results" :key="n.id" :note="n" @open="openEditor" />
-    </div>
+    <AsyncState :loading="loading" :error="error || undefined" error-title="Couldn't search" @retry="run">
+      <EmptyState v-if="query && results.length === 0" title="No matches" :subtitle="noMatchSubtitle" />
+      <div v-else-if="results.length" class="columns-1 gap-4 sm:columns-2 lg:columns-3 xl:columns-4">
+        <NoteCard v-for="n in results" :key="n.id" :note="n" @open="openEditor" />
+      </div>
+    </AsyncState>
   </div>
 
   <template v-if="editing">

frontend/src/views/TimelineView.vue

@@ -1,18 +1,17 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch } from "vue";
 import { api } from "../api/client";
-import { useNotesStore, type Note } from "../stores/notes";
+import { type Note } from "../stores/notes";
+import { useNoteList } from "../composables/useNoteList";
+import { useNoteEditor } from "../composables/useNoteEditor";
+import AsyncState from "../components/AsyncState.vue";
+import EmptyState from "../components/EmptyState.vue";
 import NoteCard from "../components/NoteCard.vue";
 import NoteEditor from "../components/NoteEditor.vue";
 
 // The "find by WHEN" recall lens: your notes grouped by when you captured them,
 // newest first, with an optional date range. A distinct recall axis from search /
 // labels — memory is often temporal even when the content is fuzzy.
-const notes = useNotesStore();
-const items = ref<Note[]>([]);
-const loading = ref(true);
-const error = ref("");
-const editing = ref<Note | null>(null);
 
 // Optional local date-range filter (YYYY-MM-DD from <input type="date">).
 const fromDate = ref("");
@@ -39,19 +38,15 @@ function buildQuery(): string {
   return params.toString();
 }
 
-async function load() {
-  loading.value = true;
-  error.value = "";
-  try {
-    const res = await api.get<{ notes: Note[] }>(`/api/notes?${buildQuery()}`);
-    items.value = res.notes;
-  } catch (e) {
-    error.value = (e as { error?: string }).error ?? "Couldn't load the timeline.";
-    items.value = [];
-  } finally {
-    loading.value = false;
-  }
-}
+const { items, loading, error, load } = useNoteList(
+  async () => (await api.get<{ notes: Note[] }>(`/api/notes?${buildQuery()}`)).notes,
+  "Couldn't load the timeline.",
+);
+
+const { editing, open: openEditor, close: closeEditor, navigate: onNavigate } = useNoteEditor({
+  list: () => items.value,
+  onClose: load, // reflect any edits made from a card
+});
 
 function clearRange() {
   fromDate.value = "";
@@ -100,17 +95,11 @@ const groups = computed<Group[]>(() => {
   return out;
 });
 
-function openEditor(n: Note) {
-  editing.value = n;
-}
-async function closeEditor() {
-  editing.value = null;
-  await load(); // reflect any edits made from a card
-}
-async function onNavigate(id: string) {
-  const found = items.value.find((n) => n.id === id) ?? notes.items.find((n) => n.id === id);
-  editing.value = found ?? (await notes.fetchOne(id));
-}
+const empty = computed(() =>
+  hasRange.value
+    ? { title: "No notes in this range", subtitle: "Try widening the date range, or clear it to see everything." }
+    : { title: "No notes yet", subtitle: "Capture a thought on the board and it'll appear here, dated." },
+);
 
 onMounted(load);
 </script>
@@ -154,41 +143,22 @@ onMounted(load);
       Your notes by when you captured them{{ hasRange ? " — filtered to the chosen dates" : "" }}.
     </p>
 
-    <div v-if="loading" class="py-24 text-center text-sm text-neutral-400">Loading…</div>
-
-    <div v-else-if="error" class="py-24 text-center">
-      <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">Couldn't load the timeline</h2>
-      <p class="mt-1 text-sm text-neutral-400">{{ error }}</p>
-      <button
-        type="button"
-        class="mt-3 rounded-md border border-neutral-300 px-3 py-1.5 text-sm hover:bg-neutral-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand dark:border-neutral-700 dark:hover:bg-neutral-800"
-        @click="load"
-      >
-        Retry
-      </button>
-    </div>
-
-    <div v-else-if="items.length === 0" class="py-24 text-center">
-      <h2 class="text-lg font-semibold text-neutral-700 dark:text-neutral-200">
-        {{ hasRange ? "No notes in this range" : "No notes yet" }}
-      </h2>
-      <p class="mt-1 text-sm text-neutral-400">
-        {{
-          hasRange
-            ? "Try widening the date range, or clear it to see everything."
-            : "Capture a thought on the board and it'll appear here, dated."
-        }}
-      </p>
-    </div>
-
-    <div v-else class="flex flex-col gap-8">
-      <section v-for="group in groups" :key="group.key">
-        <h2 class="mb-3 text-xs font-semibold uppercase tracking-wide text-neutral-400">{{ group.label }}</h2>
-        <div class="columns-1 gap-4 sm:columns-2 lg:columns-3 xl:columns-4">
-          <NoteCard v-for="n in group.notes" :key="n.id" :note="n" @open="openEditor" />
-        </div>
-      </section>
-    </div>
+    <AsyncState
+      :loading="loading"
+      :error="error || undefined"
+      error-title="Couldn't load the timeline"
+      @retry="load"
+    >
+      <EmptyState v-if="items.length === 0" :title="empty.title" :subtitle="empty.subtitle" />
+      <div v-else class="flex flex-col gap-8">
+        <section v-for="group in groups" :key="group.key">
+          <h2 class="mb-3 text-xs font-semibold uppercase tracking-wide text-neutral-400">{{ group.label }}</h2>
+          <div class="columns-1 gap-4 sm:columns-2 lg:columns-3 xl:columns-4">
+            <NoteCard v-for="n in group.notes" :key="n.id" :note="n" @open="openEditor" />
+          </div>
+        </section>
+      </div>
+    </AsyncState>
 
     <template v-if="editing">
       <NoteEditor :note="editing" @close="closeEditor" @navigate="onNavigate" />