vwiebe/joplin-plugin-gtd-calendar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
joplin-plugin-gtd-calendar/SLICE8.md

13 KiB
Raw Blame History

SLICE 8 — Incremental card limits for kanban and matrix views

State-saving rule: update this file and TASKS.md after every completed task and whenever work pauses. Automated checks and manual Joplin acceptance must be recorded separately.

Status

COMPLETE (2026-07-27). All seven phases passed, including automated validation, production packaging, documentation, and user-confirmed manual Joplin acceptance.

Goal

Keep large kanban columns and matrix quadrants readable by rendering cards in configurable batches. Every bucket initially shows 10 cards by default. A local "List more" control reveals the next batch without changing the source note or persisting UI state. Reloading the rendered note resets all buckets.

Confirmed behavior

  • Add page-size: to both gtd-kanban and gtd-matrix blocks.
  • Default: 10.
  • Valid values: positive integers only.
  • Invalid values produce a warning and fall back to 10.
  • Apply the limit independently after existing filtering and sorting to:
    • Backlog, In Progress, and Done on kanban boards.
    • All four quadrants in both matrix modes.
  • "List more" reveals the next page-size entries in only that bucket.
  • Show the control only when hidden entries remain.
  • Hovering or focusing the control shows the exact number of additional entries remaining, for example 13 more entries.
  • Clicking updates the remaining count and removes the control after the final batch.
  • Expansion exists only in the current webview DOM. It is not written to the note, settings, plugin process, or project data.
  • Column/quadrant headings continue to show total card counts, not visible counts.
  • Collector results and overall statistics continue to represent all cards.

Architecture and data flow

gtd-kanban / gtd-matrix YAML
        |
        v
parseKanbanConfig / parseMatrixConfig
  validates page-size -> normalized pageSize
        |
        v
handleGetKanban / handleGetMatrix
  returns pageSize alongside the complete sorted board
        |
        v
renderKanban / renderMatrix
  gives each column or quadrant its own visibleCount
        |
        v
renderIncrementalCardList
  renders slice(0, visibleCount), remaining summary, and List more

The collectors (collectKanban.ts and collectMatrix.ts) must not paginate or truncate. Keeping pagination in the webview avoids corrupting totals, changing sort semantics, or requiring another plugin-process request on every click.

Implementation plan

Phase 1 — Configuration contract

  • Add pageSize: number to KanbanConfig and MatrixConfig in src/Gtd/types.ts.
  • Add page-size to each parser's known-key list.
  • Normalize omitted page-size to 10.
  • Accept numeric or YAML numeric-string values only when they resolve to a finite positive integer.
  • Warn with consistent wording for zero, negative, fractional, non-numeric, NaN, or infinite values and use 10.
  • Add parser tests in src/tests/Gtd/kanban.test.ts and src/tests/Gtd/matrix.test.ts for:
    • omitted/default value;
    • 1, 10, and a larger valid override;
    • numeric-string compatibility;
    • zero, negative, fractional, and non-numeric fallback;
    • recognition as a known key (no unknown-option warning).

Progress log

  • 2026-07-27 — Phase 1 complete. Added shared page-size normalization and required pageSize fields for kanban/matrix config. Focused validation: 2 suites passed, 59/59 tests. Full validation: 12 suites passed, 164/164 tests. No manual testing applies yet because the value is not sent to or used by the webview until later phases.

Phase 2 — Plugin-to-webview payload

  • Add pageSize: config.pageSize to successful kanban and matrix responses in src/index.ts.

  • Add the same normalized value to missing-source-note/error responses so rendering behavior is structurally consistent.

  • Do not change collector arguments, result shapes, sorting, card totals, or scope behavior.

  • 2026-07-27 — Phase 2 complete. Added normalized pageSize to successful and missing-source-note responses for both kanban and matrix handlers. No collector or rendering changes. Full Jest validation: 12 suites passed, 164/164 tests. npx tsc --noEmit --skipLibCheck passed; the unmodified command remains blocked by unresolved generated Joplin declarations and the repository's Jest/TypeScript library mismatch. No manual testing applies yet.

Phase 3 — Shared incremental renderer

  • Add one shared helper in src/gtd-calendar-webview.js, tentatively renderIncrementalCardList(cards, pageSize, detail, contentScriptId).

  • Keep visibleCount in the helper's closure, initialized to Math.min(pageSize, cards.length).

  • Render cards through the existing renderCard function so styling and click-to-open behavior remain unchanged.

  • On each click, increase visibleCount by pageSize, capped at the full card count, then render only the newly revealed cards or refresh the local list without affecting other buckets.

  • Reuse the helper from renderColumn and matrixQuadrant; pass payload.pageSize || 10 from both top-level renderers as a defensive fallback for stale payloads.

  • Preserve the existing total-count text in every column/quadrant heading.

  • 2026-07-27 — Phase 3 complete. Added one incremental card-list helper and wired it to all three kanban columns and all four matrix quadrants. Each bucket owns independent closure state, initially renders one batch, appends one batch per click, removes the basic control when complete, and preserves total heading/stat counts. Validation: JavaScript syntax and git diff --check passed, npx tsc --noEmit --skipLibCheck passed, and 12 Jest suites passed with 164/164 tests. Full-file formatting was intentionally not applied because the legacy webview does not match the default formatter and doing so rewrites roughly 2,000 unrelated lines. Tooltip, accessibility association, and final CSS remain Phase 4; manual Joplin acceptance is deferred until then.

Phase 4 — Control, summary popup, and accessibility

  • Render "List more" as a real button with type="button".

  • Place the button outside card elements so its click cannot bubble into a card's note-open handler.

  • Add a dedicated tooltip element whose text is generated from the remaining count with correct singular/plural wording (1 more entry, N more entries).

  • Associate the button and tooltip with aria-describedby using a unique ID.

  • Show the tooltip on both :hover and :focus-visible; do not rely only on the native title attribute.

  • Add focused styles in src/event-calendar.css for the control, tooltip, positioning, keyboard focus, and light/dark theme compatibility.

  • Update or remove the button and tooltip atomically after every expansion.

  • 2026-07-27 — Phase 4 complete. Added a real button, unique tooltip IDs, aria-describedby, exact singular/plural remaining counts, an updating accessible label, and pointer-hover/keyboard-focus popup behavior. New cards insert before the control so focus survives intermediate expansion; the control is removed only after the final batch. Added scoped, theme-aware CSS. Validation: JavaScript syntax, npx tsc --noEmit --skipLibCheck, and git diff --check passed; 12 Jest suites passed with 164/164 tests. Visual and keyboard behavior still requires manual Joplin acceptance after a current package is built.

Phase 5 — Automated verification

The current Jest configuration uses jest-environment-node and the webview is a browser IIFE with no DOM-test harness. This slice will not add a new DOM runtime solely for one interaction. Automated coverage will therefore focus on the stable configuration contract, while DOM behavior receives explicit manual acceptance. If implementation exposes a genuinely reusable pure batching helper without duplicating browser logic, add focused unit tests for it; otherwise do not create a test-only abstraction.

  • Run focused parser tests for kanban and matrix configuration.

  • Run the complete Jest suite and record suite/test totals.

  • Run npm run dist, which includes the repository's full test/build/package workflow, and record the produced .jpl path.

  • Run git diff --check.

  • Re-run the repository-wide prohibited-reference audit.

  • 2026-07-27 — Phase 5 complete. Focused kanban/matrix validation passed 2/2 suites and 59/59 tests; the full suite passed 12/12 suites and 164/164 tests. JavaScript syntax, npx tsc --noEmit --skipLibCheck, and git diff --check passed. npm run dist archived the previous package to build-archive/com.victorwiebe.joplin.plugin.gtd-calendar-0.7.0-20260727-150417.jpl and created publish/com.victorwiebe.joplin.plugin.gtd-calendar.jpl (158,720 bytes, manifest version 0.7.0). The JPL tar contains all five expected runtime files, and its webview contains the pageSize and tooltip markers. Both prohibited-reference audits returned no matches. No browser-only test abstraction was added because the batching helper remains a DOM-owning closure; its visual and keyboard behavior stays within explicit manual acceptance.

Phase 6 — Documentation

  • Add page-size to the kanban and matrix option tables in README.md.

  • Add examples showing the default and a custom batch size.

  • Explain that expansion is per bucket, advances one batch per click, and resets on reload.

  • Update SPEC.md with config validation, rendering ownership, and transient state semantics.

  • Add an unreleased SLICE8 entry to CHANGELOG.md without changing the package version until release scope is decided.

  • 2026-07-27 — Phase 6 README work complete. Added page-size to both option tables, an explicit default kanban example, a custom matrix example, and the per-bucket expansion, remaining-count popup, full-total, and reload reset behavior. Updated the README test count to the current 164. README diff validation passed. SPEC.md and CHANGELOG.md were completed after Phase 7 acceptance; Phase 6 and SLICE8 are now complete.

Phase 7 — Manual Joplin acceptance

PASSED — USER SIGN-OFF RECEIVED 2026-07-27. All manual checks below passed against the Phase 5 package.

Use a test dashboard that includes a kanban, Skeleton matrix, and Eisenhower matrix. Prepare buckets containing 0, 1, 10, 11, 20, and 21+ cards.

  • Confirm 0–10 cards show no "List more" control.

  • Confirm 11 cards show 10 initially and reveal the final card with one click.

  • Confirm 21+ cards expand by exactly 10 per click with the default.

  • Confirm a custom page-size changes both initial and subsequent batches.

  • Confirm the hover and keyboard-focus popup always reports the exact number still hidden.

  • Confirm expansion in one column/quadrant does not alter another.

  • Confirm multiple blocks in one note maintain independent state.

  • Confirm card order, styling, hover detail, recurrence glyphs, completion styling, and click-to-open behavior remain unchanged.

  • Confirm headings and overall statistics retain full totals.

  • Confirm reloading the rendered note resets every expanded bucket.

  • Confirm invalid page-size values warn and render with the default of 10.

  • Record user sign-off here; do not mark manual acceptance complete before confirmation. Confirmed by user 2026-07-27: all passed.

  • 2026-07-27 — User reported "all passed" for the complete Phase 7 checklist.

Acceptance criteria

SLICE8 is complete only when:

  • Every kanban column and matrix quadrant initially renders no more than its normalized page-size.
  • Every click reveals at most one further batch in only the selected bucket.
  • The remaining-count popup is exact and usable with pointer and keyboard.
  • Fully expanded buckets have no "List more" control.
  • Reloading resets expansion.
  • Full card collections, ordering, headings, statistics, navigation, styling, and warnings remain correct.
  • Focused tests, the full suite, and the production package build pass.
  • Manual Joplin acceptance is explicitly confirmed.

Files expected to change

  • src/Gtd/types.ts
  • src/Gtd/parseKanbanConfig.ts
  • src/Gtd/parseMatrixConfig.ts
  • src/index.ts
  • src/gtd-calendar-webview.js
  • src/event-calendar.css
  • src/tests/Gtd/kanban.test.ts
  • src/tests/Gtd/matrix.test.ts
  • README.md
  • SPEC.md
  • CHANGELOG.md
  • SLICE8.md
  • TASKS.md

Out of scope

  • Server-side pagination or lazy fetching from Joplin.
  • Persisting expanded state across reloads.
  • A global "expand all" control.
  • Limits for calendar, unscheduled, or Gantt views.
  • Notebook grouping from SLICE10.
  • Inclusion of normal note cards from SLICE9.

Outcome and resume point

SLICE8 is complete. page-size is implemented for kanban and matrix views, the current production JPL is in publish/, all 164 automated tests pass, and manual Joplin acceptance is signed off. Nothing remains in this slice; proceed to SLICE9.