feat: manga collections (0.17.0)

User-owned named lists of mangas with an add-to-collection modal on
the manga page and dedicated /collections and /collections/:id pages.

- Schema (0010): `collections` (per-user case-insensitive name
  uniqueness) + `collection_mangas` join with cascade FKs.
- Endpoints: full CRUD on `/v1/collections`, idempotent add/remove
  for `/v1/collections/:id/mangas`, and `/v1/mangas/:id/my-collections`
  for the modal's pre-checked state. Owner-mismatch surfaces as 404
  (not 403) so the API doesn't disclose collection existence to
  non-owners; the frontend funnels 401 to /login. Three-state PATCH
  via a new shared `domain::patch::Patch<T>` lets clients distinguish
  "leave alone", "clear", and "set" for description.
- Frontend: reusable `Modal` component (focus trap, opt-in
  backdrop close, ESC) and `AddToCollectionModal` with optimistic
  toggling that's race-safe under fast clicks. /collections page
  renders cover-collage cards; /collections/:id is editable with
  per-card remove. Top nav gets a Collections link.

155 backend tests (incl. 21 collection tests covering ownership,
idempotence, sample-cover enrichment, three-state PATCH, FK race);
88 frontend tests; svelte-check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-05-17 17:43:06 +02:00
parent 5e92a2c450
commit 274cc819ca
24 changed files with 2689 additions and 100 deletions

View File

@@ -0,0 +1,158 @@
import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
import {
listMyCollections,
listMyCollectionsOrEmpty,
createCollection,
getCollection,
updateCollection,
deleteCollection,
listCollectionMangas,
addMangaToCollection,
removeMangaFromCollection,
getMyCollectionsContaining
} from './collections';
function ok(body: unknown, status = 200): Response {
return new Response(JSON.stringify(body), {
status,
headers: { 'content-type': 'application/json' }
});
}
function noContent(): Response {
return new Response(null, { status: 204 });
}
function envelope(status: number, code: string, message: string): Response {
return new Response(JSON.stringify({ error: { code, message } }), {
status,
headers: { 'content-type': 'application/json' }
});
}
function collectionFixture(extra: Record<string, unknown> = {}) {
return {
id: 'c1',
user_id: 'u1',
name: 'Favorites',
description: null,
created_at: '2026-01-01T00:00:00Z',
updated_at: '2026-01-01T00:00:00Z',
manga_count: 0,
sample_covers: [],
...extra
};
}
describe('collections api client', () => {
let fetchSpy: MockInstance<typeof globalThis.fetch>;
beforeEach(() => {
fetchSpy = vi.spyOn(globalThis, 'fetch');
});
afterEach(() => {
vi.restoreAllMocks();
});
it('listMyCollections returns the paged envelope', async () => {
fetchSpy.mockResolvedValueOnce(
ok({
items: [collectionFixture()],
page: { limit: 50, offset: 0, total: 1 }
})
);
const result = await listMyCollections();
expect(result.items[0].name).toBe('Favorites');
const url = fetchSpy.mock.calls[0][0] as string;
expect(url).toMatch(/\/v1\/me\/collections$/);
});
it('listMyCollectionsOrEmpty returns empty page on 401', async () => {
fetchSpy.mockResolvedValueOnce(envelope(401, 'unauthenticated', 'login required'));
const result = await listMyCollectionsOrEmpty();
expect(result.items).toEqual([]);
expect(result.page.total).toBeNull();
});
it('listMyCollectionsOrEmpty re-throws non-401 errors', async () => {
fetchSpy.mockResolvedValueOnce(envelope(500, 'internal_error', 'oops'));
await expect(listMyCollectionsOrEmpty()).rejects.toMatchObject({ status: 500 });
});
it('createCollection POSTs JSON to /v1/collections', async () => {
fetchSpy.mockResolvedValueOnce(ok(collectionFixture(), 201));
const c = await createCollection({ name: 'Favorites' });
expect(c.name).toBe('Favorites');
const init = fetchSpy.mock.calls[0][1] as RequestInit;
expect(init.method).toBe('POST');
expect(JSON.parse(init.body as string)).toEqual({ name: 'Favorites' });
});
it('getCollection encodes the id', async () => {
fetchSpy.mockResolvedValueOnce(ok(collectionFixture()));
await getCollection('id with space');
const url = fetchSpy.mock.calls[0][0] as string;
expect(url).toContain('/v1/collections/id%20with%20space');
});
it('updateCollection PATCHes with the patch body', async () => {
fetchSpy.mockResolvedValueOnce(ok(collectionFixture({ name: 'Read later' })));
const updated = await updateCollection('c1', { name: 'Read later' });
expect(updated.name).toBe('Read later');
const init = fetchSpy.mock.calls[0][1] as RequestInit;
expect(init.method).toBe('PATCH');
expect(JSON.parse(init.body as string)).toEqual({ name: 'Read later' });
});
it('deleteCollection issues DELETE', async () => {
fetchSpy.mockResolvedValueOnce(noContent());
await deleteCollection('c1');
const init = fetchSpy.mock.calls[0][1] as RequestInit;
expect(init.method).toBe('DELETE');
});
it('listCollectionMangas returns the paged envelope of mangas', async () => {
fetchSpy.mockResolvedValueOnce(
ok({
items: [
{
id: 'm1',
title: 'Berserk',
status: 'ongoing',
alt_titles: [],
description: null,
cover_image_path: null,
created_at: '2026-01-01T00:00:00Z',
updated_at: '2026-01-01T00:00:00Z'
}
],
page: { limit: 50, offset: 0, total: 1 }
})
);
const r = await listCollectionMangas('c1');
expect(r.items[0].title).toBe('Berserk');
});
it('addMangaToCollection POSTs the manga_id', async () => {
fetchSpy.mockResolvedValueOnce(ok({}, 201));
await addMangaToCollection('c1', 'm9');
const init = fetchSpy.mock.calls[0][1] as RequestInit;
expect(init.method).toBe('POST');
expect(JSON.parse(init.body as string)).toEqual({ manga_id: 'm9' });
});
it('removeMangaFromCollection DELETEs the nested resource', async () => {
fetchSpy.mockResolvedValueOnce(noContent());
await removeMangaFromCollection('c1', 'm9');
const url = fetchSpy.mock.calls[0][0] as string;
expect(url).toMatch(/\/v1\/collections\/c1\/mangas\/m9$/);
});
it('getMyCollectionsContaining returns the id list', async () => {
fetchSpy.mockResolvedValueOnce(ok({ collection_ids: ['c1', 'c3'] }));
const ids = await getMyCollectionsContaining('m1');
expect(ids).toEqual(['c1', 'c3']);
const url = fetchSpy.mock.calls[0][0] as string;
expect(url).toMatch(/\/v1\/mangas\/m1\/my-collections$/);
});
});

View File

@@ -0,0 +1,139 @@
import { ApiError, request, type Manga, type Page } from './client';
export type Collection = {
id: string;
user_id: string;
name: string;
description: string | null;
created_at: string;
updated_at: string;
};
/** Returned by `GET /v1/me/collections` — enriched for card rendering. */
export type CollectionSummary = Collection & {
manga_count: number;
/** Up to 3 cover image keys, newest-added first. */
sample_covers: string[];
};
export type CollectionsPage = {
items: CollectionSummary[];
page: Page;
};
export type CollectionMangasPage = {
items: Manga[];
page: Page;
};
export type NewCollection = {
name: string;
description?: string | null;
};
export type CollectionPatch = {
name?: string;
description?: string | null;
};
export type ListMyOptions = { limit?: number; offset?: number };
export async function listMyCollections(
opts: ListMyOptions = {}
): Promise<CollectionsPage> {
const params = new URLSearchParams();
if (opts.limit != null) params.set('limit', String(opts.limit));
if (opts.offset != null) params.set('offset', String(opts.offset));
const qs = params.toString();
return request<CollectionsPage>(`/v1/me/collections${qs ? `?${qs}` : ''}`);
}
/** Empty page on 401 so guest-rendering pages don't have to special-case. */
export async function listMyCollectionsOrEmpty(): Promise<CollectionsPage> {
try {
return await listMyCollections();
} catch (e) {
if (e instanceof ApiError && e.status === 401) {
return { items: [], page: { limit: 50, offset: 0, total: null } };
}
throw e;
}
}
export async function createCollection(
input: NewCollection
): Promise<Collection> {
return request<Collection>('/v1/collections', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(input)
});
}
export async function getCollection(id: string): Promise<Collection> {
return request<Collection>(`/v1/collections/${encodeURIComponent(id)}`);
}
export async function updateCollection(
id: string,
patch: CollectionPatch
): Promise<Collection> {
return request<Collection>(`/v1/collections/${encodeURIComponent(id)}`, {
method: 'PATCH',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(patch)
});
}
export async function deleteCollection(id: string): Promise<void> {
await request<void>(`/v1/collections/${encodeURIComponent(id)}`, {
method: 'DELETE'
});
}
export async function listCollectionMangas(
id: string,
opts: ListMyOptions = {}
): Promise<CollectionMangasPage> {
const params = new URLSearchParams();
if (opts.limit != null) params.set('limit', String(opts.limit));
if (opts.offset != null) params.set('offset', String(opts.offset));
const qs = params.toString();
return request<CollectionMangasPage>(
`/v1/collections/${encodeURIComponent(id)}/mangas${qs ? `?${qs}` : ''}`
);
}
export async function addMangaToCollection(
collectionId: string,
mangaId: string
): Promise<void> {
await request<void>(
`/v1/collections/${encodeURIComponent(collectionId)}/mangas`,
{
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ manga_id: mangaId })
}
);
}
export async function removeMangaFromCollection(
collectionId: string,
mangaId: string
): Promise<void> {
await request<void>(
`/v1/collections/${encodeURIComponent(collectionId)}/mangas/${encodeURIComponent(mangaId)}`,
{ method: 'DELETE' }
);
}
/** Which of the user's collections currently contain this manga. */
export async function getMyCollectionsContaining(
mangaId: string
): Promise<string[]> {
const r = await request<{ collection_ids: string[] }>(
`/v1/mangas/${encodeURIComponent(mangaId)}/my-collections`
);
return r.collection_ids;
}

View File

@@ -0,0 +1,279 @@
<script lang="ts">
import Modal from './Modal.svelte';
import {
addMangaToCollection,
createCollection,
listMyCollections,
getMyCollectionsContaining,
removeMangaFromCollection,
type CollectionSummary
} from '$lib/api/collections';
import Plus from '@lucide/svelte/icons/plus';
let {
open,
mangaId,
onClose
}: {
open: boolean;
mangaId: string;
onClose: () => void;
} = $props();
let collections = $state<CollectionSummary[]>([]);
let containingIds = $state<Set<string>>(new Set());
let busyIds = $state<Set<string>>(new Set());
let newName = $state('');
let creating = $state(false);
let loading = $state(false);
let error: string | null = $state(null);
// Refetch every time the modal opens (and when the manga id changes
// mid-session — unlikely but cheap). The data is per-user and per-
// manga, so re-fetching is the simplest way to stay in sync with
// changes made elsewhere (e.g., a collection deleted on another page).
$effect(() => {
if (open) {
void load();
}
});
async function load() {
loading = true;
error = null;
try {
const [page, ids] = await Promise.all([
listMyCollections({ limit: 200 }),
getMyCollectionsContaining(mangaId)
]);
collections = page.items;
containingIds = new Set(ids);
} catch (e) {
error = (e as Error).message;
} finally {
loading = false;
}
}
// Functional set updates that read the latest state at mutation
// time, so concurrent toggles on different rows don't clobber
// each other by building from a stale snapshot.
function withAdd<T>(s: Set<T>, v: T): Set<T> {
const n = new Set(s);
n.add(v);
return n;
}
function withDelete<T>(s: Set<T>, v: T): Set<T> {
const n = new Set(s);
n.delete(v);
return n;
}
async function toggle(collection: CollectionSummary) {
if (busyIds.has(collection.id)) return;
const wasIn = containingIds.has(collection.id);
// Optimistic toggle — local set first; revert on failure.
containingIds = wasIn
? withDelete(containingIds, collection.id)
: withAdd(containingIds, collection.id);
busyIds = withAdd(busyIds, collection.id);
try {
if (wasIn) {
await removeMangaFromCollection(collection.id, mangaId);
collection.manga_count = Math.max(0, collection.manga_count - 1);
} else {
await addMangaToCollection(collection.id, mangaId);
collection.manga_count += 1;
}
} catch (e) {
// Revert (read latest containingIds, not the pre-toggle snapshot).
containingIds = wasIn
? withAdd(containingIds, collection.id)
: withDelete(containingIds, collection.id);
error = (e as Error).message;
} finally {
busyIds = withDelete(busyIds, collection.id);
}
}
async function createAndAdd() {
const name = newName.trim();
if (!name || creating) return;
creating = true;
error = null;
try {
const created = await createCollection({ name });
// The list endpoint sorts by updated_at DESC; adding the
// manga immediately also bumps it. Append a synthetic
// summary so the new collection appears checked-on right
// away rather than waiting for a refetch.
await addMangaToCollection(created.id, mangaId);
collections = [
{
...created,
manga_count: 1,
sample_covers: []
},
...collections
];
containingIds = new Set([...containingIds, created.id]);
newName = '';
} catch (e) {
error = (e as Error).message;
} finally {
creating = false;
}
}
function onCreateSubmit(e: SubmitEvent) {
e.preventDefault();
void createAndAdd();
}
</script>
<Modal {open} {onClose} title="Add to collection" size="md" testid="add-to-collection-modal">
{#if loading}
<p class="status">Loading your collections…</p>
{:else if error}
<p class="error" role="alert" data-testid="add-to-collection-error">{error}</p>
{:else if collections.length === 0}
<p class="status" data-testid="no-collections">
You don't have any collections yet. Create one below to get started.
</p>
{:else}
<ul class="collection-list">
{#each collections as c (c.id)}
{@const checked = containingIds.has(c.id)}
{@const busy = busyIds.has(c.id)}
<li>
<label class="row" class:checked>
<input
type="checkbox"
{checked}
disabled={busy}
onchange={() => toggle(c)}
data-testid={`collection-toggle-${c.id}`}
/>
<span class="row-label">
<span class="row-name">{c.name}</span>
<span class="row-count">
{c.manga_count}
{c.manga_count === 1 ? 'manga' : 'mangas'}
</span>
</span>
</label>
</li>
{/each}
</ul>
{/if}
<form
class="create-form"
onsubmit={onCreateSubmit}
action="javascript:void(0)"
>
<input
type="text"
bind:value={newName}
maxlength="64"
placeholder="Create new collection"
aria-label="New collection name"
data-testid="new-collection-name"
/>
<button
type="submit"
class="create-btn"
disabled={!newName.trim() || creating}
data-testid="create-collection-btn"
>
<Plus size={14} aria-hidden="true" />
<span>{creating ? 'Creating…' : 'Create + add'}</span>
</button>
</form>
</Modal>
<style>
.status {
color: var(--text-muted);
}
.error {
color: var(--danger);
margin: 0 0 var(--space-2);
}
.collection-list {
list-style: none;
padding: 0;
margin: 0 0 var(--space-3);
display: flex;
flex-direction: column;
gap: var(--space-1);
max-height: 16rem;
overflow-y: auto;
}
.row {
display: flex;
align-items: center;
gap: var(--space-2);
padding: var(--space-2);
border-radius: var(--radius-md);
cursor: pointer;
transition: background var(--transition);
}
.row:hover {
background: var(--surface-elevated);
}
.row.checked {
background: var(--primary-soft-bg);
}
.row-label {
display: flex;
flex-direction: column;
min-width: 0;
}
.row-name {
color: var(--text);
font-weight: var(--weight-medium);
}
.row-count {
color: var(--text-muted);
font-size: var(--font-xs);
}
.create-form {
display: flex;
gap: var(--space-2);
align-items: center;
padding-top: var(--space-3);
border-top: 1px solid var(--border);
}
.create-form input {
flex: 1;
min-width: 0;
}
.create-btn {
display: inline-flex;
align-items: center;
gap: var(--space-1);
background: var(--primary);
color: var(--primary-contrast);
border: 1px solid var(--primary);
padding: 0 var(--space-3);
height: 36px;
white-space: nowrap;
}
.create-btn:hover:not(:disabled) {
background: var(--primary-hover);
border-color: var(--primary-hover);
}
</style>

View File

@@ -0,0 +1,221 @@
<script lang="ts">
import { onMount } from 'svelte';
import type { Snippet } from 'svelte';
import X from '@lucide/svelte/icons/x';
let {
open,
title,
onClose,
children,
footer,
size = 'md',
closeOnBackdrop = false,
testid
}: {
open: boolean;
title: string;
onClose: () => void;
children: Snippet;
footer?: Snippet;
size?: 'sm' | 'md' | 'lg';
/**
* Whether clicking the dim backdrop closes the modal. Off by
* default — forms with unsaved input would discard typed data
* on a misclick. Opt-in for confirm dialogs and read-only
* popovers.
*/
closeOnBackdrop?: boolean;
testid?: string;
} = $props();
let dialog: HTMLDivElement | undefined = $state();
// Track previous focus so we can restore it on close — a basic
// requirement for any focus-trapping modal.
let previouslyFocused: HTMLElement | null = null;
$effect(() => {
if (open) {
previouslyFocused = document.activeElement as HTMLElement | null;
// Defer until the dialog mounts.
queueMicrotask(() => dialog?.focus());
} else if (previouslyFocused) {
previouslyFocused.focus();
previouslyFocused = null;
}
});
function focusable(): HTMLElement[] {
if (!dialog) return [];
// Standard set of "tab can land here" elements, minus those
// disabled or with `tabindex=-1`. Sufficient for our forms.
const selector = [
'a[href]',
'button:not([disabled])',
'input:not([disabled]):not([type="hidden"])',
'select:not([disabled])',
'textarea:not([disabled])',
'[tabindex]:not([tabindex="-1"])'
].join(',');
return Array.from(dialog.querySelectorAll<HTMLElement>(selector));
}
function onKeydown(e: KeyboardEvent) {
if (!open) return;
if (e.key === 'Escape') {
e.stopPropagation();
onClose();
return;
}
if (e.key === 'Tab') {
// Wrap focus inside the dialog so Tab/Shift+Tab don't
// escape to the background page.
const items = focusable();
if (items.length === 0) {
e.preventDefault();
dialog?.focus();
return;
}
const first = items[0];
const last = items[items.length - 1];
const active = document.activeElement as HTMLElement | null;
if (e.shiftKey) {
if (active === first || !dialog?.contains(active)) {
e.preventDefault();
last.focus();
}
} else if (active === last) {
e.preventDefault();
first.focus();
}
}
}
onMount(() => {
document.addEventListener('keydown', onKeydown);
return () => document.removeEventListener('keydown', onKeydown);
});
function onBackdropClick(e: MouseEvent) {
if (!closeOnBackdrop) return;
if (e.target === e.currentTarget) onClose();
}
</script>
{#if open}
<div
class="backdrop"
onclick={onBackdropClick}
role="presentation"
data-testid={testid ? `${testid}-backdrop` : undefined}
>
<div
class="dialog size-{size}"
role="dialog"
aria-modal="true"
aria-labelledby="modal-title"
tabindex="-1"
bind:this={dialog}
data-testid={testid}
>
<header class="header">
<h2 id="modal-title">{title}</h2>
<button
type="button"
class="close"
onclick={onClose}
aria-label="Close"
title="Close"
data-testid={testid ? `${testid}-close` : undefined}
>
<X size={18} aria-hidden="true" />
</button>
</header>
<div class="body">{@render children()}</div>
{#if footer}
<footer class="footer">{@render footer()}</footer>
{/if}
</div>
</div>
{/if}
<style>
.backdrop {
position: fixed;
inset: 0;
background: rgba(0, 0, 0, 0.4);
display: flex;
align-items: center;
justify-content: center;
padding: var(--space-4);
z-index: var(--z-modal);
}
.dialog {
background: var(--surface);
color: var(--text);
border: 1px solid var(--border);
border-radius: var(--radius-lg);
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);
max-height: 90vh;
display: flex;
flex-direction: column;
width: 100%;
outline: none;
}
.size-sm {
max-width: 24rem;
}
.size-md {
max-width: 32rem;
}
.size-lg {
max-width: 48rem;
}
.header {
display: flex;
align-items: center;
justify-content: space-between;
padding: var(--space-3) var(--space-4);
border-bottom: 1px solid var(--border);
}
.header h2 {
margin: 0;
font-size: var(--font-lg);
}
.close {
display: inline-flex;
align-items: center;
justify-content: center;
width: 32px;
height: 32px;
padding: 0;
background: transparent;
color: var(--text-muted);
border: 1px solid transparent;
border-radius: var(--radius-sm);
}
.close:hover {
background: var(--surface-elevated);
color: var(--text);
}
.body {
padding: var(--space-4);
overflow-y: auto;
}
.footer {
padding: var(--space-3) var(--space-4);
border-top: 1px solid var(--border);
display: flex;
gap: var(--space-2);
justify-content: flex-end;
}
</style>