479 lines
18 KiB
Markdown
479 lines
18 KiB
Markdown
# Concise Default View Implementation Plan
|
|
|
|
**Goal:** Default index shows only READING + 5 most recent WANT books, with filter links to expanded views.
|
|
|
|
**Architecture:** `spine-index-model` gains an optional `filter` argument (nil = concise, "all"/"read"/"want" = expanded). The handler reads `filter` from the request query and passes it through. The template gains conditional nav links and summary-group rows. Existing group rendering unchanged.
|
|
|
|
**Tech Stack:** Emacs Lisp (model/handler), Mustache (template)
|
|
|
|
---
|
|
|
|
## File overview
|
|
|
|
**Modify:**
|
|
- `spine.el` — `spine-index-model` (add filter param, concise logic), `defservlet index` (pass query filter)
|
|
- `templates/index.mustache` — filter nav bar, summary-group rows
|
|
- `test/spine-index-model-test.el` — new test file for filtered model
|
|
|
|
---
|
|
|
|
### Task 1: Write failing tests for filtered `spine-index-model`
|
|
|
|
**Files:**
|
|
- Create: `test/spine-index-model-test.el`
|
|
|
|
- [ ] **Step 1: Create test file with setup**
|
|
|
|
```elisp
|
|
;;; spine-index-model-test.el — ERT tests for spine-index-model with filter
|
|
|
|
(require 'ert)
|
|
(require 'cl-lib)
|
|
|
|
(setq spine-skip-server-start t)
|
|
(setq spine-org-file (expand-file-name "sample-books.org"
|
|
(file-name-directory
|
|
(directory-file-name
|
|
(file-name-directory load-file-name)))))
|
|
(load-file (expand-file-name "../spine.el"
|
|
(file-name-directory load-file-name)))
|
|
|
|
(defconst spine-index-model-test--books (spine-books)
|
|
"Books fixture loaded once from sample-books.org.")
|
|
```
|
|
|
|
- [ ] **Step 2: Write test — concise view excludes READ and ABANDONED groups, has summary**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-concise-hides-read-and-abandoned ()
|
|
"Concise view (filter=nil) omits READ/ABANDONED groups, adds summary-groups."
|
|
(let* ((model (spine-index-model spine-index-model-test--books))
|
|
(groups (ht-get model "groups"))
|
|
(summaries (ht-get model "summary_groups"))
|
|
(group-labels (mapcar (lambda (g) (ht-get g "label")) groups)))
|
|
(should-not (member "read" group-labels))
|
|
(should-not (member "abandoned" group-labels))
|
|
(should summaries)
|
|
(should (= (length summaries) 1)) ; only READ, no ABANDONED in sample data
|
|
(should (string= (ht-get (car summaries) "label") "read"))
|
|
(should (= (ht-get (car summaries) "count") 1)) ; Ancillary Justice
|
|
(should (string= (ht-get (car summaries) "href") "/index?filter=read"))))
|
|
```
|
|
|
|
- [ ] **Step 3: Write test — concise view includes READING group**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-concise-includes-reading ()
|
|
"Concise view includes READING group with all reading books."
|
|
(let* ((model (spine-index-model spine-index-model-test--books))
|
|
(groups (ht-get model "groups"))
|
|
(reading-group (cl-find "reading" groups
|
|
:key (lambda (g) (ht-get g "label"))
|
|
:test #'string=)))
|
|
(should reading-group)
|
|
(should (= (ht-get reading-group "count") 1)) ; Use of Weapons
|
|
(should (string= (ht-get (car (ht-get reading-group "books")) "title")
|
|
"Use of Weapons"))))
|
|
```
|
|
|
|
- [ ] **Step 4: Write test — concise view limits WANT to 5 most recent**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-concise-want-limited-to-five ()
|
|
"Concise view limits WANT group to 5 books, sorted by :ADDED: desc."
|
|
(let* ((model (spine-index-model spine-index-model-test--books))
|
|
(groups (ht-get model "groups"))
|
|
(want-group (cl-find "on deck" groups
|
|
:key (lambda (g) (ht-get g "label"))
|
|
:test #'string=)))
|
|
(should want-group)
|
|
(let ((books (ht-get want-group "books")))
|
|
(should (<= (length books) 5))
|
|
;; sample-books.org has 3 WANT books — all should appear, sorted newest first
|
|
(should (= (length books) 3))
|
|
;; Piranesi added 2026-06-01, Dune 2026-05-10, Left Hand 2026-04-01
|
|
(should (string= (ht-get (nth 0 books) "title") "Piranesi"))
|
|
(should (string= (ht-get (nth 1 books) "title") "Dune"))
|
|
(should (string= (ht-get (nth 2 books) "title") "The Left Hand of Darkness")))))
|
|
```
|
|
|
|
- [ ] **Step 5: Write test — filter=all returns full model (no summary, all groups)**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-filter-all-shows-all-groups ()
|
|
"filter=all returns all groups, no summary-groups."
|
|
(let* ((model (spine-index-model spine-index-model-test--books "all"))
|
|
(groups (ht-get model "groups"))
|
|
(summaries (ht-get model "summary_groups"))
|
|
(group-labels (mapcar (lambda (g) (ht-get g "label")) groups)))
|
|
(should-not summaries)
|
|
(should (member "on deck" group-labels))
|
|
(should (member "reading" group-labels))
|
|
(should (member "read" group-labels))
|
|
(should (= (length groups) 3)))) ; WANT, READING, READ (no ABANDONED in sample)
|
|
```
|
|
|
|
- [ ] **Step 6: Write test — filter=read returns only READ group**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-filter-read-returns-only-read ()
|
|
"filter=read returns only the READ group."
|
|
(let* ((model (spine-index-model spine-index-model-test--books "read"))
|
|
(groups (ht-get model "groups")))
|
|
(should (= (length groups) 1))
|
|
(should (string= (ht-get (car groups) "label") "read"))
|
|
(should (= (ht-get (car groups) "count") 1))))
|
|
```
|
|
|
|
- [ ] **Step 7: Write test — filter=want returns only WANT group**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-filter-want-returns-only-want ()
|
|
"filter=want returns only the WANT group."
|
|
(let* ((model (spine-index-model spine-index-model-test--books "want"))
|
|
(groups (ht-get model "groups")))
|
|
(should (= (length groups) 1))
|
|
(should (string= (ht-get (car groups) "label") "on deck"))
|
|
(should (= (ht-get (car groups) "count") 3))))
|
|
```
|
|
|
|
- [ ] **Step 8: Write test — invalid filter falls back to concise**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-invalid-filter-falls-back-to-concise ()
|
|
"Unrecognised filter value behaves like nil (concise view)."
|
|
(let* ((model (spine-index-model spine-index-model-test--books "bogus"))
|
|
(groups (ht-get model "groups"))
|
|
(summaries (ht-get model "summary_groups"))
|
|
(group-labels (mapcar (lambda (g) (ht-get g "label")) groups)))
|
|
(should summaries) ; has summary
|
|
(should-not (member "read" group-labels)) ; no read group
|
|
(should (member "reading" group-labels)) ; has reading
|
|
(should (member "on deck" group-labels)))) ; has want
|
|
```
|
|
|
|
- [ ] **Step 9: Write test — model includes current_filter in context**
|
|
|
|
```elisp
|
|
(ert-deftest spine-index-model-includes-current-filter ()
|
|
"Model includes :current_filter key matching the filter argument."
|
|
(should (equal (ht-get (spine-index-model spine-index-model-test--books) "current_filter") ""))
|
|
(should (equal (ht-get (spine-index-model spine-index-model-test--books "all") "current_filter") "all"))
|
|
(should (equal (ht-get (spine-index-model spine-index-model-test--books "read") "current_filter") "read"))
|
|
(should (equal (ht-get (spine-index-model spine-index-model-test--books "want") "current_filter") "want")))
|
|
```
|
|
|
|
- [ ] **Step 10: Run tests to verify they fail**
|
|
|
|
```bash
|
|
cd /work/personal-local/spine
|
|
emacs --batch -l test/spine-index-model-test.el \
|
|
--eval "(ert-run-tests-batch-and-exit '(not (tag :unstable)))" 2>&1
|
|
```
|
|
|
|
Expected: all tests fail because `spine-index-model` doesn't accept a second argument yet.
|
|
|
|
- [ ] **Step 11: Commit test file**
|
|
|
|
```bash
|
|
git add test/spine-index-model-test.el
|
|
git commit -m "test: add failing tests for filtered spine-index-model"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Implement filtered `spine-index-model`
|
|
|
|
**Files:**
|
|
- Modify: `spine.el:77-155`
|
|
|
|
- [ ] **Step 1: Update signature and add filter handling**
|
|
|
|
Swap the function at line 77:
|
|
|
|
```elisp
|
|
(defun spine-index-model (books &optional filter selected-id)
|
|
"Build the view model ht for templates/index.mustache from BOOKS.
|
|
FILTER controls which books are shown:
|
|
nil — concise: READING + 5 most recent WANT, others as summary links
|
|
\"all\" — full listing, no truncation
|
|
\"read\" — only READ books
|
|
\"want\" — only WANT books
|
|
SELECTED-ID expands the matching book's detail section."
|
|
(let* ((status-labels
|
|
'(("WANT" . "on deck")
|
|
("READING" . "reading")
|
|
("READ" . "read")
|
|
("ABANDONED" . "abandoned")))
|
|
(format-icons
|
|
'(("hardcover" . "ti-book")
|
|
("ebook" . "ti-device-tablet")
|
|
("audiobook" . "ti-headphones")))
|
|
(order '("WANT" "READING" "READ" "ABANDONED"))
|
|
(valid-filters '("all" "read" "want"))
|
|
(effective-filter (if (member filter valid-filters) filter nil))
|
|
(grouped (make-hash-table :test 'equal))
|
|
(total (length books))
|
|
(reading-count 0))
|
|
(dolist (book books)
|
|
(when (equal "READING" (plist-get book :status))
|
|
(cl-incf reading-count)))
|
|
(dolist (book books)
|
|
(let ((status (or (plist-get book :status) "WANT")))
|
|
(push book (gethash status grouped))))
|
|
(let ((groups nil)
|
|
(summary-groups nil))
|
|
(dolist (status order)
|
|
(let ((group-books (nreverse (gethash status grouped))))
|
|
(when group-books
|
|
(if (and (null effective-filter)
|
|
(member status '("READ" "ABANDONED")))
|
|
;; Concise: replace read/abandoned groups with summary links
|
|
(push (ht ("label" (cdr (assoc status status-labels)))
|
|
("count" (length group-books))
|
|
("href" (format "/index?filter=%s"
|
|
(downcase status))))
|
|
summary-groups)
|
|
;; Show the group (possibly filtered to one status)
|
|
(when (or (null effective-filter)
|
|
(string= (downcase status) effective-filter)
|
|
(string= effective-filter "all"))
|
|
;; Sort WANT by ADDED descending when in concise view
|
|
(when (and (null effective-filter)
|
|
(string= status "WANT"))
|
|
(setq group-books
|
|
(cl-subseq (sort group-books
|
|
(lambda (a b)
|
|
(let ((a-date (plist-get a :added))
|
|
(b-date (plist-get b :added)))
|
|
(cond
|
|
((null a-date) nil)
|
|
((null b-date) t)
|
|
(t (string> a-date b-date))))))
|
|
0 (min (length group-books) 5))))
|
|
(let ((book-models nil))
|
|
(dolist (book group-books)
|
|
(let* ((id (plist-get book :id))
|
|
(selected (equal id selected-id))
|
|
(fmt (plist-get book :format))
|
|
(rating (plist-get book :rating))
|
|
(notes (plist-get book :notes))
|
|
(status (or (plist-get book :status) "WANT"))
|
|
(model
|
|
(ht
|
|
("format_icon"
|
|
(or (cdr (assoc fmt format-icons)) ""))
|
|
("status_class" (downcase status))
|
|
("status_label" (downcase status))
|
|
("title" (plist-get book :title))
|
|
("author" (or (plist-get book :author) ""))
|
|
("tags_inline"
|
|
(let ((tags (plist-get book :tags)))
|
|
(when tags
|
|
(mapconcat (lambda (tag) (concat ":" tag ":"))
|
|
tags " "))))
|
|
("rec_via" (plist-get book :rec_by))
|
|
("rating_display"
|
|
(when (and rating (> (length rating) 0))
|
|
(make-string (string-to-number rating) ?\u2605)))
|
|
("selected" selected)
|
|
("detail"
|
|
(when selected
|
|
(ht
|
|
("meta"
|
|
(let ((added (plist-get book :added))
|
|
(fmt (plist-get book :format)))
|
|
(cond
|
|
((and added fmt)
|
|
(format "started %s · %s" added fmt))
|
|
(added (format "started %s" added))
|
|
(fmt (format "format: %s" fmt))
|
|
(t ""))))
|
|
("notes"
|
|
(when notes
|
|
(cl-loop for (date text) in notes
|
|
collect (ht
|
|
("date" (format "[%s]" date))
|
|
("text" text)))))))))))
|
|
(push model book-models)))
|
|
(push (ht ("label" (cdr (assoc status status-labels)))
|
|
("count" (length group-books))
|
|
("books" (nreverse book-models)))
|
|
groups))))))
|
|
(ht ("app_title" "spine")
|
|
("total_books" total)
|
|
("reading_count" reading-count)
|
|
("current_filter" (or effective-filter ""))
|
|
("summary_groups" (nreverse summary-groups))
|
|
("groups" (nreverse groups))))))
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests to verify they pass**
|
|
|
|
```bash
|
|
cd /work/personal-local/spine
|
|
emacs --batch -l test/spine-index-model-test.el \
|
|
-l test/spine-books-test.el \
|
|
-l test/spine-add-book-test.el \
|
|
--eval "(ert-run-tests-batch-and-exit '(not (tag :unstable)))" 2>&1
|
|
```
|
|
|
|
Expected: all tests pass (new filter tests + existing books + add-book tests).
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add spine.el
|
|
git commit -m "feat: add filter parameter to spine-index-model for concise default view"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Update `defservlet index` handler
|
|
|
|
**Files:**
|
|
- Modify: `spine.el:308-313`
|
|
|
|
- [ ] **Step 1: Pass query filter to model**
|
|
|
|
Swap lines 308-313:
|
|
|
|
```elisp
|
|
(defservlet index text/html (path query request)
|
|
(let* ((books (spine-books))
|
|
(filter (cadr (assoc "filter" query))))
|
|
(if books
|
|
(insert (spine-render "index.mustache"
|
|
(spine-index-model books filter (cadr (assoc "id" query)))))
|
|
(insert (spine-render-empty-state)))))
|
|
```
|
|
|
|
- [ ] **Step 2: Run existing tests to confirm handler change doesn't break anything**
|
|
|
|
```bash
|
|
cd /work/personal-local/spine
|
|
emacs --batch -l test/spine-index-model-test.el \
|
|
-l test/spine-books-test.el \
|
|
-l test/spine-add-book-test.el \
|
|
--eval "(ert-run-tests-batch-and-exit '(not (tag :unstable)))" 2>&1
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add spine.el
|
|
git commit -m "feat: pass filter query param from index handler to model"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Update `templates/index.mustache` with filter links and summary groups
|
|
|
|
**Files:**
|
|
- Modify: `templates/index.mustache`
|
|
|
|
- [ ] **Step 1: Add filter nav bar after header, before groups**
|
|
|
|
Insert after the closing `</header>` (line 87) and before the `{{#groups}}` section (line 89):
|
|
|
|
```mustache
|
|
{{#current_filter}}
|
|
<nav class="filter-bar" style="padding: .4rem .9rem; font-size: .8rem;">
|
|
<a href="/index">Concise view</a>
|
|
</nav>
|
|
{{/current_filter}}
|
|
{{^current_filter}}
|
|
<nav class="filter-bar" style="padding: .4rem .9rem; font-size: .8rem;">
|
|
<span>
|
|
<a href="/index?filter=all">All books ({{total_books}})</a>
|
|
·
|
|
<a href="/index?filter=want">Want list</a>
|
|
·
|
|
<a href="/index?filter=read">Read ({{reading_count}})</a>
|
|
</span>
|
|
</nav>
|
|
{{/current_filter}}
|
|
```
|
|
|
|
- [ ] **Step 2: Add summary group rows after groups section**
|
|
|
|
Insert after the closing `{{/groups}}` (line 109) and before `<div class="endpad">` (line 110):
|
|
|
|
```mustache
|
|
{{#summary_groups}}
|
|
<div class="row"><a href="{{href}}">{{label}} · {{count}}</a></div>
|
|
{{/summary_groups}}
|
|
```
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add templates/index.mustache
|
|
git commit -m "feat: add filter nav bar and summary group links to index template"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: Manual integration test
|
|
|
|
- [ ] **Step 1: Start the server and verify concise default view**
|
|
|
|
```bash
|
|
cd /work/personal-local/spine
|
|
SPINE_ORG_FILE=$(pwd)/sample-books.org emacs --batch -l spine.el \
|
|
--eval "(setq spine-org-file \"$(pwd)/sample-books.org\")" \
|
|
--eval "(httpd-start)" \
|
|
--eval "(message \"Server running on port 8080\")" &
|
|
sleep 2
|
|
curl -s http://localhost:8080/index | head -50
|
|
```
|
|
|
|
Verify the output:
|
|
- Shows READING group (Use of Weapons)
|
|
- Shows WANT group (Piranesi, Dune, Left Hand)
|
|
- Does NOT show READ group (Ancillary Justice) as a full group
|
|
- Shows a summary link for "read · 1"
|
|
- Shows "All books (5)" filter nav link
|
|
|
|
- [ ] **Step 2: Test filter=all**
|
|
|
|
```bash
|
|
curl -s "http://localhost:8080/index?filter=all"
|
|
```
|
|
|
|
Verify: all books shown in their groups, no summary sections, "Concise view" link present.
|
|
|
|
- [ ] **Step 3: Test filter=read**
|
|
|
|
```bash
|
|
curl -s "http://localhost:8080/index?filter=read"
|
|
```
|
|
|
|
Verify: only Ancillary Justice shown, "Concise view" link present.
|
|
|
|
- [ ] **Step 4: Kill the server**
|
|
|
|
```bash
|
|
kill %1 2>/dev/null; wait 2>/dev/null
|
|
```
|
|
|
|
- [ ] **Step 5: Run all tests one final time**
|
|
|
|
```bash
|
|
cd /work/personal-local/spine
|
|
emacs --batch -l test/spine-index-model-test.el \
|
|
-l test/spine-books-test.el \
|
|
-l test/spine-add-book-test.el \
|
|
--eval "(ert-run-tests-batch-and-exit '(not (tag :unstable)))" 2>&1
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 6: Final commit if any fixes needed**
|
|
|
|
```bash
|
|
git commit -am "fix: address integration test findings"
|
|
```
|