#+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?