feat(mangas): per-field sort options + direction toggle on the catalog (0.88.0)

Sort the manga catalog by created / updated / title / author with an independent asc/desc direction control. An omitted `order` defaults per field (dates newest-first, text A→Z), matching the UI, so a bare `?sort=<field>` means the same thing in the browser and over the API; `sort=recent` remains a back-compat alias for `created`. - Backend: SortField/SortOrder parsed with validation (structured 422 on bad input), per-field default_order, NULLS LAST only on the nullable author key, and migration 0033 indexing mangas(updated_at DESC, id) to back the default sort and its id tie-break. - Frontend: catalog sort field + direction (SegmentedControl) on desktop and a mobile bottom sheet; pure helpers in $lib/mangaSort; keyboard-accessible direction control; visible Direction labels and a sheet "Done" button. - Tests: backend integration coverage (defaults, alias, invalid input, ascending-id tie-break), frontend unit + e2e. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-25 07:15:51 +02:00
parent 93b7e451bf
commit dee53fa212
16 changed files with 936 additions and 75 deletions
--- a/backend/tests/api_mangas.rs
+++ b/backend/tests/api_mangas.rs
@@ -11,6 +11,53 @@ fn metadata(title: &str) -> serde_json::Value {
    json!({ "title": title })
 }

+/// Collect the `title` field of every item in a list response, in order.
+fn title_list(body: &serde_json::Value) -> Vec<&str> {
+    body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|m| m["title"].as_str().unwrap())
+        .collect()
+}
+
+/// Create a manga via the upload API, asserting it succeeded.
+async fn seed(app: &axum::Router, cookie: &str, title: &str) {
+    let resp = app
+        .clone()
+        .oneshot(common::post_multipart_with_cookie(
+            "/api/v1/mangas",
+            MultipartBuilder::new().add_json("metadata", json!({ "title": title })),
+            cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED, "seed({title}) failed");
+}
+
+/// Pin a manga's `created_at` to an explicit RFC3339 instant so time-based
+/// ordering assertions don't depend on insert timing.
+async fn set_created_at(pool: &PgPool, title: &str, when: &str) {
+    let ts: chrono::DateTime<chrono::Utc> = when.parse().unwrap();
+    sqlx::query("UPDATE mangas SET created_at = $1 WHERE title = $2")
+        .bind(ts)
+        .bind(title)
+        .execute(pool)
+        .await
+        .unwrap();
+}
+
+/// Pin a manga's `updated_at` to an explicit RFC3339 instant.
+async fn set_updated_at(pool: &PgPool, title: &str, when: &str) {
+    let ts: chrono::DateTime<chrono::Utc> = when.parse().unwrap();
+    sqlx::query("UPDATE mangas SET updated_at = $1 WHERE title = $2")
+        .bind(ts)
+        .bind(title)
+        .execute(pool)
+        .await
+        .unwrap();
+}
+
 #[sqlx::test(migrations = "./migrations")]
 async fn list_is_empty_initially(pool: PgPool) {
    let h = common::harness(pool);
@@ -103,19 +150,307 @@ async fn list_sort_title_orders_alphabetically(pool: PgPool) {
            .unwrap();
    }

+    // Title sort now requires an explicit direction; the wire default is
+    // `desc`, so A→Z needs `order=asc`.
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?sort=title&order=asc"))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    let titles = title_list(&body);
+    assert_eq!(titles, vec!["Berserk", "One Piece", "Vinland Saga"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_sort_title_desc_orders_reverse_alphabetically(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    for title in ["Vinland Saga", "Berserk", "One Piece"] {
+        seed(&h.app, &cookie, title).await;
+    }
+
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?sort=title&order=desc"))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    let titles = title_list(&body);
+    assert_eq!(titles, vec!["Vinland Saga", "One Piece", "Berserk"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_default_sort_is_updated_desc(pool: PgPool) {
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    for title in ["Alpha", "Bravo", "Charlie"] {
+        seed(&h.app, &cookie, title).await;
+    }
+    // Pin explicit, distinct update times so the default ordering is
+    // deterministic regardless of insert timing. Bravo is the most recently
+    // updated and must appear first under the default (updated DESC).
+    set_updated_at(&pool, "Alpha", "2020-01-01T00:00:00Z").await;
+    set_updated_at(&pool, "Bravo", "2023-01-01T00:00:00Z").await;
+    set_updated_at(&pool, "Charlie", "2021-01-01T00:00:00Z").await;
+
+    // No sort/order params — exercises the default.
+    let resp = h.app.oneshot(common::get("/api/v1/mangas")).await.unwrap();
+    let body = common::body_json(resp).await;
+    let titles = title_list(&body);
+    assert_eq!(titles, vec!["Bravo", "Charlie", "Alpha"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_sort_created_orders_by_creation_time(pool: PgPool) {
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    for title in ["Alpha", "Bravo", "Charlie"] {
+        seed(&h.app, &cookie, title).await;
+    }
+    set_created_at(&pool, "Alpha", "2020-01-01T00:00:00Z").await;
+    set_created_at(&pool, "Bravo", "2023-01-01T00:00:00Z").await;
+    set_created_at(&pool, "Charlie", "2021-01-01T00:00:00Z").await;
+
+    // Newest-created first.
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::get("/api/v1/mangas?sort=created&order=desc"))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    assert_eq!(title_list(&body), vec!["Bravo", "Charlie", "Alpha"]);
+
+    // Ascending is the exact reverse.
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?sort=created&order=asc"))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    assert_eq!(title_list(&body), vec!["Alpha", "Charlie", "Bravo"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_sort_author_orders_by_author_name_nulls_last(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    // Author order is deliberately scrambled relative to title order so the
+    // assertion can't pass by accidentally sorting on title.
+    for (title, authors) in [
+        ("Akira", json!(["Beta Author"])),
+        ("Boku", json!(["Alpha Author"])),
+        ("Chi", json!(["Gamma Author"])),
+        ("NoAuthor", json!([])),
+    ] {
+        let _ = h
+            .app
+            .clone()
+            .oneshot(common::post_multipart_with_cookie(
+                "/api/v1/mangas",
+                MultipartBuilder::new()
+                    .add_json("metadata", json!({ "title": title, "authors": authors })),
+                &cookie,
+            ))
+            .await
+            .unwrap();
+    }
+
+    // Ascending by author name; the authorless manga sorts last (NULLS LAST).
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::get("/api/v1/mangas?sort=author&order=asc"))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    assert_eq!(title_list(&body), vec!["Boku", "Akira", "Chi", "NoAuthor"]);
+
+    // Descending flips the authored mangas but keeps the authorless one last.
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?sort=author&order=desc"))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    assert_eq!(title_list(&body), vec!["Chi", "Akira", "Boku", "NoAuthor"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_sort_recent_alias_maps_to_created_desc(pool: PgPool) {
+    // `recent` was the pre-0.88 sort value (newest created first). It is kept
+    // as an alias for `created` so existing bots/scripts don't break.
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    for title in ["Alpha", "Bravo", "Charlie"] {
+        seed(&h.app, &cookie, title).await;
+    }
+    set_created_at(&pool, "Alpha", "2020-01-01T00:00:00Z").await;
+    set_created_at(&pool, "Bravo", "2023-01-01T00:00:00Z").await;
+    set_created_at(&pool, "Charlie", "2021-01-01T00:00:00Z").await;
+
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?sort=recent"))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    // Same ordering as `sort=created&order=desc`: newest-created first.
+    assert_eq!(title_list(&body), vec!["Bravo", "Charlie", "Alpha"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_sort_field_defaults_direction_per_field(pool: PgPool) {
+    // When `order` is omitted, the API applies the field's natural direction:
+    // text fields ascend (A→Z), matching the frontend's `defaultOrderFor`, so
+    // a bare `?sort=title` link reads the same in the UI and over the wire.
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    for title in ["Vinland Saga", "Berserk", "One Piece"] {
+        seed(&h.app, &cookie, title).await;
+    }
+
    let resp = h
        .app
        .oneshot(common::get("/api/v1/mangas?sort=title"))
        .await
        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
    let body = common::body_json(resp).await;
-    let titles: Vec<&str> = body["items"]
-        .as_array()
-        .unwrap()
+    assert_eq!(title_list(&body), vec!["Berserk", "One Piece", "Vinland Saga"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_sort_author_default_is_ascending_nulls_last(pool: PgPool) {
+    // The other text field: a bare `?sort=author` must default to ascending and
+    // keep authorless mangas last (NULLS LAST), exercising the omitted-order
+    // path through the author subquery — not just `title`.
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    for (title, authors) in [
+        ("Akira", json!(["Beta Author"])),
+        ("Boku", json!(["Alpha Author"])),
+        ("NoAuthor", json!([])),
+    ] {
+        let _ = h
+            .app
+            .clone()
+            .oneshot(common::post_multipart_with_cookie(
+                "/api/v1/mangas",
+                MultipartBuilder::new()
+                    .add_json("metadata", json!({ "title": title, "authors": authors })),
+                &cookie,
+            ))
+            .await
+            .unwrap();
+    }
+
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?sort=author"))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    // Alpha Author (Boku) < Beta Author (Akira); authorless sorts last.
+    assert_eq!(title_list(&body), vec!["Boku", "Akira", "NoAuthor"]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_rejects_invalid_sort_and_order_with_envelope(pool: PgPool) {
+    let h = common::harness(pool);
+
+    // Unknown sort field → structured 422, not axum's plain-text 400.
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::get("/api/v1/mangas?sort=bogus"))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["details"]["sort"], "invalid");
+
+    // Unknown order → same treatment.
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?order=sideways"))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["details"]["order"], "invalid");
+}
+
+/// Pin a manga's primary key to an explicit UUID. Safe only for freshly
+/// seeded mangas with no chapters/authors/tags referencing them.
+async fn set_id(pool: &PgPool, title: &str, id: &str) {
+    let uuid: uuid::Uuid = id.parse().unwrap();
+    sqlx::query("UPDATE mangas SET id = $1 WHERE title = $2")
+        .bind(uuid)
+        .bind(title)
+        .execute(pool)
+        .await
+        .unwrap();
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_tie_break_orders_equal_keys_by_ascending_id(pool: PgPool) {
+    // The trailing `, id` in ORDER BY is what keeps pagination stable when the
+    // primary sort key ties. Pin three mangas to the SAME created_at and assign
+    // ids whose ascending order (Bravo < Charlie < Alpha) deliberately differs
+    // from insertion/physical order, so the expected ordering can ONLY come
+    // from the id tie-break.
+    //
+    // We sort by `created` on purpose: `mangas_created_at_idx` is `(created_at
+    // DESC)` with no id, so it does NOT encode the secondary order — unlike the
+    // default `updated` path, whose `mangas_updated_at_idx (updated_at DESC,
+    // id)` would mask a missing clause. Drop `, id` from the query and this
+    // test fails.
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    for title in ["Alpha", "Bravo", "Charlie"] {
+        seed(&h.app, &cookie, title).await;
+        set_created_at(&pool, title, "2022-01-01T00:00:00Z").await;
+    }
+    set_id(&pool, "Alpha", "33333333-3333-4333-8333-333333333333").await;
+    set_id(&pool, "Bravo", "11111111-1111-4111-8111-111111111111").await;
+    set_id(&pool, "Charlie", "22222222-2222-4222-8222-222222222222").await;
+
+    let page = |limit: i64, offset: i64| {
+        let app = h.app.clone();
+        async move {
+            let resp = app
+                .oneshot(common::get(&format!(
+                    "/api/v1/mangas?sort=created&limit={limit}&offset={offset}"
+                )))
+                .await
+                .unwrap();
+            common::body_json(resp).await
+        }
+    };
+
+    // Single page: tied rows come back in ascending-id order.
+    let full = page(50, 0).await;
+    assert_eq!(title_list(&full), vec!["Bravo", "Charlie", "Alpha"]);
+
+    // Paginating one row at a time reproduces that exact sequence — no overlap,
+    // no gap — which only holds because the id tie-break makes the order total.
+    let paged: Vec<String> = vec![page(1, 0).await, page(1, 1).await, page(1, 2).await]
        .iter()
-        .map(|m| m["title"].as_str().unwrap())
+        .map(|b| b["items"][0]["title"].as_str().unwrap().to_string())
        .collect();
-    assert_eq!(titles, vec!["Berserk", "One Piece", "Vinland Saga"]);
+    assert_eq!(paged, vec!["Bravo", "Charlie", "Alpha"]);
 }

 #[sqlx::test(migrations = "./migrations")]