From 23c741c4dc8a3e5a753b3c42389b8c673052d2ce Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sat, 6 Jun 2026 15:14:45 -0500
Subject: feat(views): pearl-set-grouping command

Phase 3 of the interactive-grouping spec: the command that ties phases 1 and 2 together. pearl-set-grouping completing-reads a dimension (status/project/assignee/priority/none), coerces and validates it, regroups the buffer, then persists the choice on the source. M-x only for now, like pearl-set-sort. The transient and keymap entries come later.

pearl--apply-grouping is the non-interactive core, shaped like pearl--apply-sort. On a successful regroup it re-folds the page and writes :client-group into the header. On an empty buffer it reports no-issues and writes nothing, so a failed grouping never advertises a layout the buffer doesn't show. none ungroups and clears the override. 4 tests cover persistence, the none-clears path, the re-fold, and the no-issues skip.
---
 pearl.el | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

(limited to 'pearl.el')

diff --git a/pearl.el b/pearl.el
index 875963f..3c9e7d0 100644
--- a/pearl.el
+++ b/pearl.el
@@ -7235,6 +7235,47 @@ sort -- with none set, asks you to run `pearl-set-sort' first."
          (target (pearl--toggle-sort-target source)))
     (pearl--apply-sort source (car target) (cdr target))))
 
+(defun pearl--apply-grouping (source value)
+  "Regroup the current buffer by VALUE and persist it on SOURCE.
+VALUE is an `issueGrouping' value, or nil to flatten.  Re-lays-out the issue
+subtrees, re-folds (the regroup's delete+insert drops fold overlays, like
+sort), and writes the updated `:client-group' into `#+LINEAR-SOURCE' only after
+a successful regroup, so a failed/empty buffer never advertises a grouping it
+doesn't show.  Returns `grouped' on success or `no-issues' when there's nothing
+to group."
+  (pcase (pearl--regroup-issue-subtrees value)
+    ('no-issues
+     (message "No issues to group in this buffer")
+     'no-issues)
+    (_
+     (pearl--restore-page-visibility)
+     (pearl--write-linear-source-header (pearl--source-with-grouping source value))
+     (if value
+         (message "Grouped current buffer by %s"
+                  (car (rassoc value pearl--grouping-choices)))
+       (message "Ungrouped current buffer"))
+     'grouped)))
+
+;;;###autoload
+(defun pearl-set-grouping (display)
+  "Group the active Linear view by DISPLAY, or ungroup it.
+Interactively completes the dimension (status/project/assignee/priority/none).
+Regroups the buffer in place client-side -- no refetch -- reading each issue's
+group from its drawer, and persists the choice under `:client-group' so a
+refresh reproduces it.  `none' ungroups back to the flat list (and, on a Custom
+View, restores the view's own server grouping on the next refresh).  Cycle is
+not offered: it isn't in the drawer, so an offline regroup can't read it."
+  (interactive
+   (list (completing-read
+          "Group by: "
+          (pearl--completion-table-keep-order
+           (mapcar #'car pearl--grouping-choices))
+          nil t)))
+  (pearl--require-account-context)
+  (let ((value (pearl--grouping-display-to-value display)))
+    (pearl--check-grouping value)
+    (pearl--apply-grouping (pearl--active-source-or-error) value)))
+
 (defun pearl--view-node-prefs (view)
   "Extract the runnable view preferences from a Custom View node VIEW.
 Returns `(:sort SORT :show-completed SC)': SORT is the `IssueSortInput' for the
-- 
cgit v1.2.3