Add a global completion percentage to series list #539

Open
opened 2026-09-25 12:49:06 +01:00 by Vylpes · 2 comments
Owner

Like how we have for each series, let us have a global percentage also

Why

/series list already shows per-series claim progress as (owned/total) on each line (SeriesHelper.GenerateSeriesListPage). Players cannot see overall catalog completion without mentally aggregating every series.

Scope

In scope: Discord /series list embed (all pages) and pagination buttons — add global completion based on the same inventory rules as the per-series counts.

Out of scope: /series view title progress (#540); changing per-series line format; web/management UI.

Acceptance criteria

  • GIVEN a user opens /series list (or navigates list pages via buttons)
    WHEN GenerateSeriesListPage builds the embed
    THEN the embed shows a global completion percentage for the entire card catalog (all series in CoreClient.Cards), not just the series on the current page.

  • GIVEN the global totals are computed
    WHEN compared to the existing per-series (owned/total) logic on each line
    THEN owned = count of the user’s inventory rows whose CardNumber appears in any series card list; total = sum of series.cards.length across all series (same semantics as today’s per-line filter/count, aggregated once).

  • GIVEN global owned and total
    WHEN the percentage is displayed
    THEN it is a whole number 0–100 using rounded percent (Math.round(100 * owned / total)), and total = 0 is handled without division errors (show 0%).

  • GIVEN the list embed is rendered
    WHEN a user views the title and footer
    THEN the title includes the global percent (e.g. Series — 42% complete) and the footer includes aggregate counts (e.g. {owned}/{total} cards) in addition to the existing series count and page text.

  • GIVEN the user paginates the series list
    WHEN they move between pages
    THEN the global percentage and aggregate counts stay identical on every page (only the description lines change).

  • GIVEN automated tests for GenerateSeriesListPage
    WHEN CI runs
    THEN tests cover at least: empty inventory (0%); partial catalog completion with correct owned/total; full catalog (100%); pagination does not alter global stats.

Subtasks

  • Add shared/global completion calculation in SeriesHelper (reuse same inventory + catalog rules as per-series lines)
  • Update list embed title and footer to show global % and {owned}/{total} cards
  • Extend tests/helpers/SeriesHelper.test.ts for global completion + pagination invariants
  • Add a CHANGELOG entry under the target release for the new global completion display

Notes

  • Related: #540 (per-series progress on /series view title)
  • Current per-series format shipped in 0.10.0 (#295); this story adds catalog-wide percentage only.
Like how we have for each series, let us have a global percentage also ## Why `/series list` already shows per-series claim progress as `(owned/total)` on each line (`SeriesHelper.GenerateSeriesListPage`). Players cannot see overall catalog completion without mentally aggregating every series. ## Scope **In scope:** Discord `/series list` embed (all pages) and pagination buttons — add **global** completion based on the same inventory rules as the per-series counts. **Out of scope:** `/series view` title progress ([#540](https://git.vylpes.xyz/External/card-drop/issues/540)); changing per-series line format; web/management UI. ## Acceptance criteria - **GIVEN** a user opens `/series list` (or navigates list pages via buttons) **WHEN** `GenerateSeriesListPage` builds the embed **THEN** the embed shows a **global completion percentage** for the **entire** card catalog (all series in `CoreClient.Cards`), not just the series on the current page. - **GIVEN** the global totals are computed **WHEN** compared to the existing per-series `(owned/total)` logic on each line **THEN** **owned** = count of the user’s inventory rows whose `CardNumber` appears in **any** series card list; **total** = sum of `series.cards.length` across all series (same semantics as today’s per-line filter/count, aggregated once). - **GIVEN** global owned and total **WHEN** the percentage is displayed **THEN** it is a whole number **0–100** using **rounded** percent (`Math.round(100 * owned / total)`), and **total = 0** is handled without division errors (show **0%**). - **GIVEN** the list embed is rendered **WHEN** a user views the title and footer **THEN** the **title** includes the global percent (e.g. `Series — 42% complete`) **and** the **footer** includes aggregate counts (e.g. `{owned}/{total} cards`) in addition to the existing series count and page text. - **GIVEN** the user paginates the series list **WHEN** they move between pages **THEN** the global percentage and aggregate counts stay **identical** on every page (only the description lines change). - **GIVEN** automated tests for `GenerateSeriesListPage` **WHEN** CI runs **THEN** tests cover at least: empty inventory (0%); partial catalog completion with correct owned/total; full catalog (100%); pagination does not alter global stats. ## Subtasks - [ ] Add shared/global completion calculation in `SeriesHelper` (reuse same inventory + catalog rules as per-series lines) - [ ] Update list embed title and footer to show global % and `{owned}/{total} cards` - [ ] Extend `tests/helpers/SeriesHelper.test.ts` for global completion + pagination invariants - [ ] Add a **CHANGELOG** entry under the target release for the new global completion display ## Notes - Related: [#540](https://git.vylpes.xyz/External/card-drop/issues/540) (per-series progress on `/series view` title) - Current per-series format shipped in 0.10.0 (#295); this story adds **catalog-wide** percentage only.
Vylpes added this to the 0.11.0 milestone 2026-09-25 12:49:18 +01:00
Smithy-bot stopped working 2026-10-30 11:01:58 +00:00
18 seconds
Member

Story point estimate

3 story points

Rationale

  • Acceptance criteria and subtasks are already concrete (shared helper calculation, embed title/footer, unit tests, CHANGELOG).
  • Scope mirrors recent series-list work (#359): localized changes in SeriesHelper + tests, no new commands or API surface.
  • Pagination invariant and edge case (total = 0) are specified; no open product questions.

Smithy-bot → needs/tests (next: QA scripts against the criteria).

## Story point estimate **3** story points ### Rationale - Acceptance criteria and subtasks are already concrete (shared helper calculation, embed title/footer, unit tests, CHANGELOG). - Scope mirrors recent series-list work ([#359](https://git.vylpes.xyz/External/card-drop/issues/359)): localized changes in `SeriesHelper` + tests, no new commands or API surface. - Pagination invariant and edge case (`total = 0`) are specified; no open product questions. Smithy-bot → **needs/tests** (next: QA scripts against the criteria).
Smithy-bot stopped working 2026-10-31 11:00:57 +00:00
7 seconds
Smithy-bot stopped working 2026-11-02 11:04:38 +00:00
4 seconds
Member

Planning — needs/tests → needs/approval

QA scripts mapped to the acceptance criteria in the issue description. Run on a branch with the implementation merged or deployed to stage; unit-test rows via yarn test locally/CI.

Preconditions

  • Discord test user with a known inventory (empty, partial, and full-catalog scenarios if feasible).
  • Catalog with multiple series and enough cards that /series list spans ≥ 2 pages (pagination buttons visible).
  • Ability to run yarn test (tests/helpers/SeriesHelper.test.ts).
  • Optional: read access to CoreClient.Cards / fixture data to compute expected owned/total manually for one scenario.

AC1 — Global completion % for entire catalog on /series list

ID Steps Expected
T1.1 Run /series list as a user with a partial inventory Embed shows a global completion percentage reflecting all series in the catalog, not only series on page 1
T1.2 Compare global % to manual sum of catalog-wide owned/total (same rules as AC2) Displayed rounded percent matches Math.round(100 * owned / total)
T1.3 Confirm per-series lines still show existing (owned/total) per line Per-line format unchanged; only global aggregate added

AC2 — Owned/total semantics match per-series logic (aggregated once)

ID Steps Expected
T2.1 Pick a user inventory where a card number appears in multiple series lists (if catalog has overlap) or where owned cards span several series Owned = count of inventory rows whose CardNumber appears in any series card list (same filter as per-line logic)
T2.2 Sum series.cards.length across all series in CoreClient.Cards Total equals that sum (not page-local)
T2.3 For one series on page 1, verify line (owned/total) still matches pre-change behaviour No regression to per-series counts

AC3 — Percent display and total = 0 edge case

ID Steps Expected
T3.1 User with empty inventory on a non-empty catalog Global percent 0% (or equivalent copy); no crash
T3.2 If test harness can simulate total = 0 catalog (fixture/mocks) Shows 0% without division-by-zero
T3.3 User who owns every catalog card (100%) Global percent 100%
T3.4 Partial completion where raw ratio is not an integer Percent is whole number 0–100 via rounding (not floor/truncate unless implementation explicitly matches Math.round)

ID Steps Expected
T4.1 View embed title on /series list Includes global percent (e.g. Series — 42% complete or agreed wording from implementation)
T4.2 View embed footer Includes aggregate {owned}/{total} cards and retains existing series count + page text
T4.3 Spot-check title/footer strings for empty and partial users Consistent formatting; readable in Discord embed limits

AC5 — Pagination invariants

ID Steps Expected
T5.1 Note global %, footer owned/total, and any other global stats on page 1 Baseline recorded
T5.2 Click Next (or equivalent) to page 2+ Description lines change (different series)
T5.3 Compare global % and footer aggregate counts on page 2 vs page 1 Identical on every page
T5.4 Return to page 1 via Previous Global stats still match T5.1

AC6 — Automated tests (SeriesHelper / CI)

ID Steps Expected
U1 yarn test — tests/helpers/SeriesHelper.test.ts (and full suite) Green
U2 Test: empty inventory 0% global completion; safe totals
U3 Test: partial catalog completion Correct owned/total and rounded %
U4 Test: full catalog 100%
U5 Test: pagination / multiple pages Global stats unchanged when page index changes
U6 Forgejo Actions / CI on PR Test job passes

Subtasks / scope regression

ID Steps Expected
S1 CHANGELOG entry under target release Documents global completion on /series list
R1 /series view title progress (#540) Out of scope — unchanged by this story
R2 Web/management UI Out of scope — unchanged

Sign-off checklist

  • T1–T5, U1–U6, S1, and R1–R2 pass.
  • Global stats stable across pagination; per-series lines unchanged.

Moving to needs/approval for your review before implementation. @Vylpes

## Planning — needs/tests → needs/approval QA scripts mapped to the acceptance criteria in the issue description. Run on a branch with the implementation merged or deployed to **stage**; unit-test rows via `yarn test` locally/CI. ### Preconditions - Discord test user with a known inventory (empty, partial, and full-catalog scenarios if feasible). - Catalog with **multiple series** and enough cards that `/series list` spans **≥ 2 pages** (pagination buttons visible). - Ability to run `yarn test` (`tests/helpers/SeriesHelper.test.ts`). - Optional: read access to `CoreClient.Cards` / fixture data to compute expected owned/total manually for one scenario. --- ### AC1 — Global completion % for entire catalog on `/series list` | ID | Steps | Expected | |----|--------|----------| | T1.1 | Run `/series list` as a user with a **partial** inventory | Embed shows a **global** completion **percentage** reflecting **all** series in the catalog, not only series on page 1 | | T1.2 | Compare global % to manual sum of catalog-wide owned/total (same rules as AC2) | Displayed **rounded** percent matches `Math.round(100 * owned / total)` | | T1.3 | Confirm per-series lines still show existing `(owned/total)` per line | Per-line format **unchanged**; only global aggregate added | --- ### AC2 — Owned/total semantics match per-series logic (aggregated once) | ID | Steps | Expected | |----|--------|----------| | T2.1 | Pick a user inventory where a card number appears in **multiple** series lists (if catalog has overlap) or where owned cards span several series | **Owned** = count of inventory rows whose `CardNumber` appears in **any** series card list (same filter as per-line logic) | | T2.2 | Sum `series.cards.length` across **all** series in `CoreClient.Cards` | **Total** equals that sum (not page-local) | | T2.3 | For one series on page 1, verify line `(owned/total)` still matches pre-change behaviour | No regression to per-series counts | --- ### AC3 — Percent display and `total = 0` edge case | ID | Steps | Expected | |----|--------|----------| | T3.1 | User with **empty** inventory on a non-empty catalog | Global percent **0%** (or equivalent copy); no crash | | T3.2 | If test harness can simulate **total = 0** catalog (fixture/mocks) | Shows **0%** without division-by-zero | | T3.3 | User who owns **every** catalog card (100%) | Global percent **100%** | | T3.4 | Partial completion where raw ratio is not an integer | Percent is **whole number 0–100** via **rounding** (not floor/truncate unless implementation explicitly matches `Math.round`) | --- ### AC4 — Title and footer copy | ID | Steps | Expected | |----|--------|----------| | T4.1 | View embed **title** on `/series list` | Includes global percent (e.g. `Series — 42% complete` or agreed wording from implementation) | | T4.2 | View embed **footer** | Includes aggregate `{owned}/{total} cards` **and** retains existing series count + page text | | T4.3 | Spot-check title/footer strings for empty and partial users | Consistent formatting; readable in Discord embed limits | --- ### AC5 — Pagination invariants | ID | Steps | Expected | |----|--------|----------| | T5.1 | Note global **%**, footer **owned/total**, and any other global stats on page 1 | Baseline recorded | | T5.2 | Click **Next** (or equivalent) to page 2+ | **Description lines** change (different series) | | T5.3 | Compare global **%** and footer aggregate counts on page 2 vs page 1 | **Identical** on every page | | T5.4 | Return to page 1 via **Previous** | Global stats still match T5.1 | --- ### AC6 — Automated tests (`SeriesHelper` / CI) | ID | Steps | Expected | |----|--------|----------| | U1 | `yarn test` — `tests/helpers/SeriesHelper.test.ts` (and full suite) | Green | | U2 | Test: empty inventory | **0%** global completion; safe totals | | U3 | Test: partial catalog completion | Correct owned/total and rounded % | | U4 | Test: full catalog | **100%** | | U5 | Test: pagination / multiple pages | Global stats unchanged when page index changes | | U6 | Forgejo Actions / CI on PR | Test job passes | --- ### Subtasks / scope regression | ID | Steps | Expected | |----|--------|----------| | S1 | **CHANGELOG** entry under target release | Documents global completion on `/series list` | | R1 | `/series view` title progress ([#540](https://git.vylpes.xyz/External/card-drop/issues/540)) | **Out of scope** — unchanged by this story | | R2 | Web/management UI | **Out of scope** — unchanged | --- ### Sign-off checklist - [ ] T1–T5, U1–U6, S1, and R1–R2 pass. - [ ] Global stats stable across pagination; per-series lines unchanged. Moving to **needs/approval** for your review before implementation. @Vylpes
Smithy-bot removed their assignment 2026-11-02 11:05:20 +00:00
Smithy-bot stopped working 2026-11-02 11:05:32 +00:00
2 seconds
Smithy-bot added spent time 2026-11-02 11:05:35 +00:00
2 minutes
Vylpes removed their assignment 2026-11-02 12:59:27 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Total time spent: 2 minutes 31 seconds
Smithy-bot
2 minutes 31 seconds
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
External/card-drop#539
No description provided.