1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
|
#+TITLE: pearl — Interactive Sort/Order Spec
#+AUTHOR: Craig Jennings
#+DATE: 2026-05-24
#+STARTUP: showall
* Status
*DRAFT — design proposal; nothing in =pearl.el= has changed.* Open questions for Craig at the end.
Companion to [[file:issue-query-spec.org][issue-query-spec.org]], which defines the =:sort= / =:order= the saved-query layer already supports. This doc covers changing the order of the *current* view interactively, without hand-editing a saved query.
* Problem
v1 supports =:sort= (=updated= / =priority= / =title=) and =:order= (=asc= / =desc=) on saved queries. But to change how the active file is ordered, the user has to edit =pearl-saved-queries= (or the source plist) by hand and re-run. There's no "sort this view by priority, descending" command. For a view you're actually looking at, that's the natural thing to want.
* Current state
- =pearl--sort-issues= (query spec) applies =:sort= / =:order= client-side at the render boundary, so a refresh always lays headings out the same way.
- =:sort= = =priority= / =title= are client-side; =created= / =updated= map to the server =orderBy= (the only fields Linear's API orders on). The query spec documents this split.
- The active file's =#+LINEAR-SOURCE:= header records the source plist, including any =:sort= / =:order=, so =refresh-current-view= reproduces the ordering.
* Proposed design
** The command
=pearl-set-sort= (interactive), run in the active file:
1. =completing-read= the sort key: =updated=, =created=, =priority=, =title=.
2. =completing-read= (or a toggle) the order: =asc= / =desc=.
3. Update the =:sort= / =:order= in the active file's recorded =#+LINEAR-SOURCE:=.
4. Re-order the view (see below).
A =pearl-toggle-sort-order= convenience command just flips =asc=/=desc= on the current sort and re-orders. Both go on the transient menu (a small "Sort" group, or under View).
** Re-order in place vs refetch
The split matters for whether a sort change needs the network:
- *Client-side sorts* (=priority=, =title=): the issues are already in the buffer. Re-sort in place — reparse the issue subtrees, reorder them, rewrite. No refetch. Fast, works offline.
- *Server-side sorts* (=created=, =updated=): the ordering comes from the server =orderBy=, and the fetch may have been truncated at the page cap, so the correct order needs a refetch with the new =orderBy=. Re-run the source (the =refresh-current-view= path) with the updated sort.
So =set-sort= decides: client-side key → re-sort the buffer; server-side key → refetch. The command reports which it did.
** Persistence
The change updates the active file's =#+LINEAR-SOURCE:= so a later =refresh-current-view= keeps the new order. Whether it also writes back to a named saved query in =pearl-saved-queries= is open question 3 — my lean is no by default (the active file is the scratch view; saved queries are the durable definitions), with an explicit "save this ordering to the query" as a separate step.
* Proposed v1 decisions (this feature)
1. =pearl-set-sort= + =pearl-toggle-sort-order=, both on the transient menu.
2. Client-side keys re-sort the buffer in place; server-side keys refetch.
3. The change updates the active file's recorded source so refresh preserves it.
4. Completion is over the known keys/orders, never free text.
* vNext / out of scope
- Multi-key sort (e.g. priority then updated).
- Per-heading manual reordering that sticks across refresh.
- Exposing the full Linear =orderBy= surface if the API later un-gates the =[INTERNAL]= per-field sort.
* Open questions for Craig
1. *Command vs transient-only*: a plain =M-x pearl-set-sort= with two completing-reads, or a dedicated transient sub-menu with one-key sort toggles (=p= priority, =u= updated, =t= title, =o= flip order)? The transient reads faster for a frequent action.
2. *In-place re-sort fidelity*: re-sorting client-side means reparsing and rewriting issue subtrees in the buffer. Acceptable, or prefer always-refetch for simplicity even when a client-side sort wouldn't need it?
3. *Write-back*: should changing the sort offer to persist it to the originating saved query, or only ever update the active file's header?
|
