;;; fzfa-vertico.el --- Vertico extensions for `fzfa' -*- lexical-binding: t; -*-

;; Copyright (C) 2026 James Nguyen

;; Author: James Nguyen <james@jojojames.com>

;; Version: 1.0

;; Package-Requires: ((emacs "29.1"))

;; Homepage: https://github.com/jojojames/fzfa

;; Assisted-by: Claude:claude-opus-4-7

;; SPDX-License-Identifier: GPL-3.0-or-later

;;; Commentary:

;; Per-group column layout for `vertico'. Each completion group

;; renders as its own vertical column instead of the default stacked

;; layout. Primarily intended for `fzfa-multi-read' sessions, where

;; one column equals one source.

;;

;; Loaded automatically when `vertico' is in `fzfa-extensions' and

;; `fzfa-setup' has been called. By default `fzfa-vertico-setup'

;; registers the columns mode with `vertico-multiform-categories'

;; for each category in `fzfa-vertico-multiform-categories'

;; (defaults to `fzfa-multi') and turns `vertico-multiform-mode'

;; on if not already — so columns activate inside multi-source

;; pickers and tear down on exit, without touching unrelated

;; minibuffer sessions. Set `fzfa-vertico-columns-auto' to nil

;; to suppress all auto-wiring.

;;

;; Manual enable (e.g. globally for testing):

;; (fzfa-vertico-columns-mode 1)

;;

;; Or scope a different category yourself:

;; (add-to-list 'vertico-multiform-categories

;; '(imenu fzfa-vertico-columns-mode))

;;

;; When the active completion produces more groups than

;; `fzfa-vertico-columns-max', the overflow groups wrap into

;; additional bands stacked below. For example, with the default

;; max of 3 and 7 groups the layout is three bands of 3, 3, 1

;; columns.

;;

;; Navigation while the mode is active. Vim-style M-hjkl jumps

;; between groups (sources); arrow keys move between candidates

;; within the current source:

;; M-l Next source in reading order; at a

;; band's right edge, wraps to the

;; leftmost source of the next band.

;; M-h Previous source (symmetric inverse).

;; M-j Source in the next band, same

;; column-in-band (jumps a whole band down).

;; M-k Source in the previous band, same

;; column-in-band.

;; next-line / previous-line Move within the current source;

;; at the source's last row, jumps to

;; the source visually below in the

;; next band (and vice versa).

;;

;; The mode falls back to vertico's default arrangement when the

;; active completion has no `group-function' or only produces a

;; single group, so it is safe to enable globally.

;;; Code:

(require 'cl-lib)

(defvar vertico-multiform-mode)

(defvar vertico-multiform-categories)

(declare-function vertico-multiform-mode "vertico-multiform" (&optional arg))

(defvar vertico-group-format)

(defvar vertico-count)

(defvar vertico--candidates)

(defvar vertico--candidates-ov)

(defvar vertico--metadata)

(defvar vertico--index)

(defvar vertico--input)

(declare-function vertico--metadata-get "vertico" (prop))

(declare-function vertico--window-width "vertico" ())

(declare-function vertico--hilit "vertico" (cand))

(declare-function vertico--format-candidate "vertico"

(cand prefix suffix index start))

(declare-function vertico--goto "vertico" (index))

(declare-function vertico-next "vertico" (&optional n))

(declare-function vertico-previous "vertico" (&optional n))

(defvar-local fzfa-vertico--band-offset 0

"Per-minibuffer first visible band index, for pagination.

When `fzfa-vertico-columns-page-size' caps the number of bands

rendered, this offset slides as the selection moves between

bands so the band containing the selection always stays in

view. Recomputed from `vertico--index' on every arrange, so

nothing else needs to mutate it directly.")

(defvar-local fzfa-vertico--initial-snap-done nil

"Per-minibuffer one-shot flag for the initial selection snap.

`vertico--update' resets `vertico--index' to 0 on entry, which —

once partitioned by `fzfa-vertico-columns-source-sort' — points

at whichever candidate `fzfa--sort-by-history' promoted to the

top, not necessarily column 0 row 0. After the first render in

each minibuffer session we move the selection to the partition's

top-left cell and set this flag so subsequent renders honour the

user's explicit navigation.")

(defgroup fzfa-vertico nil

"Vertico extensions for fzfa."

:group 'fzfa

:group 'vertico)

(defcustom fzfa-vertico-columns-max 3

"Maximum number of columns rendered per band.

When the active completion produces more groups than this, the

overflow groups wrap into additional bands stacked below. For

example, with `fzfa-vertico-columns-max' = 3 and 7 groups, the

layout is three bands of (3 3 1) columns."

:type 'natnum

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-strategy 'auto

"How `fzfa-vertico-columns-mode' picks the column count.

`fixed' Always use `fzfa-vertico-columns-max' (clamped to the

number of source-groups) — original behaviour, hands

control to the user.

`auto' Collapse to 1 column when every source-group fits within

`vertico-count' rows stacked; scale up to

`fzfa-vertico-columns-max' when stacking would push later

groups off-screen. Trades horizontal density for text

visibility on light result sets — with few candidates

the wider single column shows each candidate untruncated,

while a busy multi-source query still gets columns to

avoid pagination scroll.

The auto heuristic re-evaluates on every arrange call, so layout

can flip as the user's filter changes group sizes."

:type '(choice (const :tag "Fixed (always columns-max)" fixed)

(const :tag "Auto (stack when it fits, else columns)" auto))

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-page-size 6

"Maximum sources displayed simultaneously; pagination kicks in beyond.

When the active completion produces more groups than this, the

layout paginates: only a window containing at most PAGE-SIZE

sources is visible at any time. The window scrolls

automatically as the selection moves between bands — moving

past the last visible band's bottom row brings the next band

into view; moving past the top scrolls back.

Counted as `(ceil PAGE-SIZE / `fzfa-vertico-columns-max')' bands.

With the default of 6 and `fzfa-vertico-columns-max' = 3 you see

2 bands of 3 columns at a time. Each visible band gets a larger

share of `vertico-count' rows than it would if every band were

on-screen, which is the main UX win for many-source pickers.

Set to 0 or nil to disable pagination (all bands always visible)."

:type '(choice (const :tag "Disable pagination" nil)

(natnum :tag "Page size (sources)"))

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-min-width 12

"Minimum width per column, in characters."

:type 'natnum

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-max-width nil

"Maximum width per column, in characters.

When nil (default), columns expand to fill the window evenly —

the layout always uses the full frame width regardless of the

column count. Set to a positive integer to cap each column;

useful when you'd rather keep individual columns readable and

leave the rest of the frame blank than let a wide column stretch

the whole row."

:type '(choice (const :tag "Expand to fill window" nil)

(natnum :tag "Maximum width in characters"))

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-separator

#(" | " 2 3 (display (space :width (1))

face (:inherit window-divider :inverse-video t)))

"Separator string between adjacent columns.

The middle character carries a `display' property that renders it

as a 1-pixel-wide vertical line in the `window-divider' face, so

the divider looks like a window separator on GUI frames. On a

TTY the display property is ignored and the literal `|' shows

through as a readable fallback."

:type 'string

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-headers t

"When non-nil, render group names as a header row above the candidates.

The header consumes one slot of `vertico-count'."

:type 'boolean

:group 'fzfa-vertico)

(defface fzfa-vertico-columns-header

'((t :inherit minibuffer-prompt))

"Face for source-name header text in `fzfa-vertico-columns-mode'.

The overline above and underline beneath each header are layered

on at render time using `window-divider's foreground, so the

framing rules track theme changes alongside the column-separator

hairline. Customize this face to change the header text's own

foreground / weight."

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-header-face 'fzfa-vertico-columns-header

"Face applied to the column header row.

Defaults to `fzfa-vertico-columns-header', which inherits from

`minibuffer-prompt' and adds an underline."

:type 'face

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-auto t

"When non-nil, `fzfa-vertico-setup' wires up per-category activation.

The hook fires from `fzfa-setup' when `vertico' is in

`fzfa-extensions'. Each entry in

`fzfa-vertico-multiform-categories' is registered with

`vertico-multiform-categories' so the columns layout activates

automatically inside the listed categories' minibuffer

sessions, and `vertico-multiform-mode' is enabled if not already

on. Set to nil to load this extension's commands and face

definitions without touching multiform — you can then enable

`fzfa-vertico-columns-mode' manually or scope it yourself."

:type 'boolean

:group 'fzfa-vertico)

(defcustom fzfa-vertico-multiform-categories '(fzfa-multi)

"Completion categories that should auto-activate columns mode.

Each symbol is registered with `vertico-multiform-categories'

as (CATEGORY `fzfa-vertico-columns-mode'), so opening a

`completing-read' under one of these categories turns the

columns layout on for that session and tears it down on exit.

Defaults to `fzfa-multi' — the category used by

`fzfa-multi-read', `fzfa-find-any', and `fzfa-find-some' — since

multi-source pickers are where the per-group column layout pays

off. Add other categories (e.g. `imenu', `consult-buffer') if

you also want columns there."

:type '(repeat symbol)

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-truncate 'auto

"How to truncate candidates that exceed the column width.

left Keep the leading characters; replace the tail with

`fzfa-vertico-columns-ellipsis'. Matches Emacs's

default `truncate-string-to-width' behaviour.

right Keep the trailing characters; replace the head with

the ellipsis. Best for file paths and grep-style

FILE:LINE:CONTENT candidates where the suffix

(basename, match content) is the identifying part.

auto Per-candidate heuristic — `right' when the candidate

looks path-like (contains `/' or starts with `~'),

`left' otherwise. Default.

function Called with (CAND WIDTH) and must return a string of

visible width WIDTH (pad with spaces if shorter).

Truncation affects only the display: fzf scoring and the

`completing-read' return value always operate on the full

untouched candidate string."

:type '(choice (const :tag "Left-anchored (keep prefix)" left)

(const :tag "Right-anchored (keep suffix)" right)

(const :tag "Auto-detect path-like" auto)

(function :tag "Custom function"))

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-ellipsis

(if (char-displayable-p ?…) "…" "...")

"String used to mark truncated candidates in the columns layout."

:type 'string

:group 'fzfa-vertico)

(defcustom fzfa-vertico-columns-source-sort 'scored

"How to order group columns.

declared Sort by declared order.

scored Groups are sorted by their first candidates score.

Default.

alphabetical Sort group names lexicographically.

function A function called with the partition list

((GROUP . CANDS) ...) returning the reordered list."

:type '(choice (const :tag "By declared source order (alias)" declared)

(const :tag "By per-source fzf score (rank-sorted)" scored)

(const :tag "Alphabetical" alphabetical)

(function :tag "Custom function"))

:group 'fzfa-vertico)

(defvar-keymap fzfa-vertico-columns-map

:doc "Additional keymap activated in `fzfa-vertico-columns-mode'.

Arrow-key remaps move between candidates within a column

(the default within-source navigation), while vim-style M-hjkl

shortcuts jump between groups: M-h/M-l cycle through sources in

reading order, M-j/M-k jump to the source in the next or

previous band (same column-in-band)."

"<remap> <left-char>" #'fzfa-vertico-columns-left

"<remap> <right-char>" #'fzfa-vertico-columns-right

"<remap> <next-line>" #'fzfa-vertico-columns-next

"<remap> <previous-line>" #'fzfa-vertico-columns-previous

"M-h" #'fzfa-vertico-columns-left

"M-l" #'fzfa-vertico-columns-right

"M-j" #'fzfa-vertico-columns-band-down

"M-k" #'fzfa-vertico-columns-band-up)

;;;###autoload

(define-minor-mode fzfa-vertico-columns-mode

"Render each completion group as a column in `vertico'.

The active completion's `group-function' partitions candidates;

each unique group becomes one column. Falls back to the default

stacked layout when there is no `group-function' or only one

group is produced."

:global t :group 'fzfa-vertico

(when-let* ((win (active-minibuffer-window)))

(unless (frame-root-window-p win)

(window-resize win (- (window-pixel-height win)) nil nil 'pixelwise)))

(cl-callf2 rassq-delete-all fzfa-vertico-columns-map minor-mode-map-alist)

(when fzfa-vertico-columns-mode

(push `(vertico--input . ,fzfa-vertico-columns-map)

minor-mode-map-alist)))

;;; Partitioning

(defun fzfa-vertico--group-function ()

"Return the active `group-function', or nil when grouping is disabled."

(and vertico-group-format (vertico--metadata-get 'group-function)))

(defun fzfa-vertico--src-idx-of (part)

"Return PART's first candidate source index, or `most-positive-fixnum'.

Looked up via the session-bound `fzfa--candidate->source' hash; used as

the sort key for the `source-idx' ordering mode."

(let ((c (cadr part)))

(or (and (stringp c)

(> (length c) 0)

(bound-and-true-p fzfa--candidate->source)

(gethash c fzfa--candidate->source))

most-positive-fixnum)))

(defun fzfa-vertico--empty-query-p ()

"Return non-nil when the active minibuffer has no user query.

Used by the `scored' column-sort mode to lock declared order

while sources stream in — without a query there is no rank to

follow, and async arrival order would otherwise shuffle columns."

(when-let* ((win (active-minibuffer-window)))

(with-current-buffer (window-buffer win)

(= (minibuffer-prompt-end) (point-max)))))

(defun fzfa-vertico--sort-parts (parts)

"Order PARTS according to `fzfa-vertico-columns-source-sort'.

`sort' is stable, so groups with equal sort keys (e.g., no

`fzfa-src-idx' property) retain their discovery order."

(pcase fzfa-vertico-columns-source-sort

('scored

;; Empty query → lock declared order so async streaming doesn't

;; shuffle columns as sources arrive at different times. With a

;; query, follow `vertico--candidates' discovery order, which

;; `fzfa--read' merges in rank order (strongest source first).

(if (fzfa-vertico--empty-query-p)

(sort parts (lambda (a b) (< (fzfa-vertico--src-idx-of a)

(fzfa-vertico--src-idx-of b))))

parts))

('alphabetical

(sort parts (lambda (a b) (string< (car a) (car b)))))

((or 'source-idx 'declared)

(sort parts (lambda (a b) (< (fzfa-vertico--src-idx-of a)

(fzfa-vertico--src-idx-of b)))))

((pred functionp)

(funcall fzfa-vertico-columns-source-sort parts))

(_ parts)))

(defun fzfa-vertico--partition (group-fun)

"Partition `vertico--candidates' by GROUP-FUN.

Returns ((GROUP . (CAND ...)) ...) ordered according to

`fzfa-vertico-columns-source-sort'; per-group candidate order

follows the original `vertico--candidates' order."

(let ((table (make-hash-table :test 'equal))

(order nil))

(dolist (c vertico--candidates)

(let ((g (or (funcall group-fun c nil) "")))

(unless (gethash g table)

(puthash g (cons nil nil) table)

(push g order))

(let ((cell (gethash g table)))

(setcar cell (cons c (car cell))))))

(fzfa-vertico--sort-parts

(mapcar (lambda (g) (cons g (nreverse (car (gethash g table)))))

(nreverse order)))))

;;; Navigation

(defun fzfa-vertico--locate (parts idx)

"Find IDX (into `vertico--candidates') in PARTS as (COL . ROW), or nil."

(when-let* ((cand (and (>= idx 0)

(< idx (length vertico--candidates))

(nth idx vertico--candidates))))

(let ((col 0) found)

(cl-dolist (part parts)

(let ((row (cl-position cand (cdr part) :test #'eq)))

(when row

(setq found (cons col row))

(cl-return)))

(cl-incf col))

found)))

(defun fzfa-vertico--flat-index (parts col row)

"Return the `vertico--candidates' index of (COL ROW) in PARTS, or nil."

(when-let* ((cands (cdr (nth col parts)))

(cand (nth row cands)))

(cl-position cand vertico--candidates :test #'eq)))

(defun fzfa-vertico--move-source (dsrc)

"Move DSRC sources horizontally in the linear source order.

Row index is preserved (clamped to the destination source's row

count). Crossing a band boundary wraps to the adjacent band's

edge source on the same data row, matching the visual reading

order left-to-right, top-to-bottom."

(when-let* ((gf (fzfa-vertico--group-function))

(parts (fzfa-vertico--partition gf))

((> (length parts) 1))

(pos (fzfa-vertico--locate parts vertico--index)))

(let* ((n (length parts))

(src (car pos)) (row (cdr pos))

(new-src (max 0 (min (1- n) (+ src dsrc))))

(rows (length (cdr (nth new-src parts))))

(new-row (min (1- rows) row)))

(when-let* ((idx (fzfa-vertico--flat-index parts new-src new-row)))

(vertico--goto idx)))))

(defun fzfa-vertico--move-row (drow)

"Move DROW rows vertically within the current source's column.

At the bottom of a source, DOWN jumps to the source visually

below in the next band (same column-in-band). At the top, UP

jumps to the corresponding source in the previous band."

(when-let* ((gf (fzfa-vertico--group-function))

(parts (fzfa-vertico--partition gf))

((> (length parts) 1))

(pos (fzfa-vertico--locate parts vertico--index)))

(let* ((src (car pos)) (row (cdr pos))

(src-rows (length (cdr (nth src parts))))

(new-row (+ row drow))

(max-cols (max 1 fzfa-vertico-columns-max)))

(cond

((and (>= new-row 0) (< new-row src-rows))

(when-let* ((idx (fzfa-vertico--flat-index parts src new-row)))

(vertico--goto idx)))

((> drow 0)

(let ((next-src (+ src max-cols)))

(when (< next-src (length parts))

(let* ((excess (- new-row src-rows))

(next-rows (length (cdr (nth next-src parts))))

(target (min excess (1- next-rows))))

(when-let* ((idx (fzfa-vertico--flat-index

parts next-src (max 0 target))))

(vertico--goto idx))))))

(t

(let ((prev-src (- src max-cols)))

(when (>= prev-src 0)

(let* ((prev-rows (length (cdr (nth prev-src parts))))

(target (+ prev-rows new-row)))

(when-let* ((idx (fzfa-vertico--flat-index

parts prev-src

(max 0 (min (1- prev-rows) target)))))

(vertico--goto idx))))))))))

(defun fzfa-vertico--multi-columns-p ()

"Non-nil when the current arrange decision renders >1 column.

Not the same as \"there are >1 groups\": auto-strategy may collapse

even a multi-group session to a single stacked column when the

whole thing fits within `vertico-count' vertically. Consulted by

the column-nav wrappers (`fzfa-vertico-columns-next' etc.) so

that stacked mode inherits vertico's default C-n / C-p / cursor

motion instead of our column-aware jumps."

(when-let* ((gf (fzfa-vertico--group-function))

(parts (fzfa-vertico--partition gf)))

(and (> (length parts) 1)

(> (fzfa-vertico--pick-ncols

parts (max 1 fzfa-vertico-columns-max)

vertico-count fzfa-vertico-columns-headers)

1))))

(defun fzfa-vertico-columns-right (&optional n)

"Move N sources to the right in reading order (default 1).

At a band's right edge, wraps to the next band's leftmost source

on the same data row. Falls back to `right-char' when the layout

is single-column (no group-function, or narrowed to one group)."

(interactive "p")

(if (fzfa-vertico--multi-columns-p)

(fzfa-vertico--move-source (or n 1))

(call-interactively #'right-char)))

(defun fzfa-vertico-columns-left (&optional n)

"Move N sources to the left in reading order (default 1).

At a band's left edge, wraps to the previous band's rightmost

source on the same data row. Falls back to `left-char' when the

layout is single-column."

(interactive "p")

(if (fzfa-vertico--multi-columns-p)

(fzfa-vertico--move-source (- (or n 1)))

(call-interactively #'left-char)))

(defun fzfa-vertico-columns-next (&optional n)

"Move N rows down within the current source's column (default 1).

At the source's last row, jumps to the source visually below in

the next band. Falls back to `vertico-next' when the layout is

single-column — so vertico's normal scrolling still works after

narrowing to one source."

(interactive "p")

(if (fzfa-vertico--multi-columns-p)

(fzfa-vertico--move-row (or n 1))

(vertico-next (or n 1))))

(defun fzfa-vertico-columns-previous (&optional n)

"Move N rows up within the current source's column (default 1).

At the source's first row, jumps to the source visually above in

the previous band. Falls back to `vertico-previous' when the

layout is single-column."

(interactive "p")

(if (fzfa-vertico--multi-columns-p)

(fzfa-vertico--move-row (- (or n 1)))

(vertico-previous (or n 1))))

(defun fzfa-vertico--move-band (dband)

"Move DBAND bands vertically, keeping the same column-in-band.

Row index within the destination source is preserved when

possible, clamped to the destination's length. Crossing the

top/bottom edge is a no-op."

(when-let* ((gf (fzfa-vertico--group-function))

(parts (fzfa-vertico--partition gf))

((> (length parts) 1))

(pos (fzfa-vertico--locate parts vertico--index)))

(let* ((src (car pos))

(row (cdr pos))

(max-cols (max 1 fzfa-vertico-columns-max))

(target (+ src (* dband max-cols)))

(n (length parts)))

(when (and (>= target 0) (< target n))

(let* ((rows (length (cdr (nth target parts))))

(new-row (min (1- rows) (max 0 row))))

(when-let* ((idx (fzfa-vertico--flat-index parts target new-row)))

(vertico--goto idx)))))))

(defun fzfa-vertico-columns-band-down (&optional n)

"Jump N bands down to the source in the same column-in-band (default 1).

Falls back to `vertico-next' when the layout is single-column."

(interactive "p")

(if (fzfa-vertico--multi-columns-p)

(fzfa-vertico--move-band (or n 1))

(vertico-next (or n 1))))

(defun fzfa-vertico-columns-band-up (&optional n)

"Jump N bands up to the source in the same column-in-band (default 1).

Falls back to `vertico-previous' when the layout is single-column."

(interactive "p")

(if (fzfa-vertico--multi-columns-p)

(fzfa-vertico--move-band (- (or n 1)))

(vertico-previous (or n 1))))

;;; Rendering

(defun fzfa-vertico--path-like-p (s)

"Heuristic: non-nil when S resembles a file path / grep-style result.

Used by the `auto' value of `fzfa-vertico-columns-truncate' to

pick right-anchored truncation for path-bearing candidates."

(or (string-match-p "/" s)

(string-prefix-p "~" s)))

(defconst fzfa-vertico--match-faces

'(completions-common-part completions-first-difference)

"Faces vertico applies to matched characters in function `vertico--hilit'.

Used to detect when right-truncation would drop a matched span

off the leading edge, so the ellipsis can carry the hint forward.")

(defun fzfa-vertico--has-match-face-p (s)

"Return non-nil when S has any `fzfa-vertico--match-faces' span.

Walks face text properties with `next-single-property-change'

so the scan stays cheap even on long candidates."

(let ((i 0) (len (length s)) hit)

(while (and (< i len) (not hit))

(let* ((face (get-text-property i 'face s))

(faces (if (listp face) face (list face))))

(when (cl-intersection faces fzfa-vertico--match-faces)

(setq hit t)))

(setq i (or (next-single-property-change i 'face s) len)))

hit))

(defun fzfa-vertico--truncate-right (s width)

"Truncate S to visible WIDTH keeping the trailing characters.

Prepends `fzfa-vertico-columns-ellipsis' when truncation occurs.

Text properties on the surviving suffix are preserved, so

vertico's match highlights and the selection face survive intact

on whatever portion of the candidate remains visible. When the

dropped prefix contained a match, the ellipsis itself is

propertized with `completions-common-part' so the column still

signals \"there's a match in the part you can't see\"."

(let* ((ell fzfa-vertico-columns-ellipsis)

(ell-w (string-width ell))

(full-w (string-width s)))

(cond

((<= full-w width)

(concat s (make-string (- width full-w) ?\s)))

((>= ell-w width) ell)

(t

;; Advance until we've dropped enough leading visible width to

;; let the ellipsis + suffix fit, then keep the rest. Wide

;; chars may overshoot by 1 column; pad to WIDTH if so.

(let* ((target (- width ell-w))

(skip (- full-w target))

(acc 0) (i 0) (len (length s)))

(while (and (< i len) (< acc skip))

(setq acc (+ acc (char-width (aref s i))))

(cl-incf i))

(let* ((dropped (substring s 0 i))

(ell-display

(if (fzfa-vertico--has-match-face-p dropped)

(propertize ell 'face 'completions-common-part)

ell))

(out (concat ell-display (substring s i)))

(ow (string-width out)))

(if (>= ow width)

out

(concat out (make-string (- width ow) ?\s)))))))))

(defun fzfa-vertico--truncate (s width)

"Truncate S to visible WIDTH per `fzfa-vertico-columns-truncate'.

Falls back to standard left-anchored `truncate-string-to-width'

for unrecognised values."

(pcase fzfa-vertico-columns-truncate

('right (fzfa-vertico--truncate-right s width))

('auto (if (fzfa-vertico--path-like-p (substring-no-properties s))

(fzfa-vertico--truncate-right s width)

(truncate-string-to-width s width 0 ?\s

fzfa-vertico-columns-ellipsis)))

((pred functionp) (funcall fzfa-vertico-columns-truncate s width))

(_ (truncate-string-to-width s width 0 ?\s

fzfa-vertico-columns-ellipsis))))

(defun fzfa-vertico--render-cell (cand idx width &optional group-fun)

"Render CAND at flat index IDX, truncated/padded to WIDTH.

Reuses `vertico--format-candidate' so selection highlighting and

match-fontification stay consistent with vertico's defaults.

When GROUP-FUN is non-nil, the candidate is passed through

\(funcall GROUP-FUN cand \\='transform) before rendering, mirroring

the display swap `vertico--arrange-candidates' does for the

stacked layout. Highlighting runs first so per-source transforms

that take a substring of CAND (e.g. `fzfa--grep-group' stripping

the FILE: prefix) inherit the match faces.

Width fitting is delegated to `fzfa-vertico--truncate' so

path-bearing candidates can keep their identifying suffix

instead of having their basenames chopped off the right."

(let* ((hi (vertico--hilit (copy-sequence cand)))

(display (or (and group-fun (funcall group-fun hi 'transform))

hi))

(formatted (vertico--format-candidate display "" "" idx 0))

(trimmed (string-trim-right formatted "[\r\n]+")))

(fzfa-vertico--truncate trimmed width)))

(defun fzfa-vertico--header-face-spec ()

"Return a face spec for header text with `window-divider'-colored rules.

Wraps `fzfa-vertico-columns-header-face' in an overline plus an

underline, both drawn in `window-divider's foreground so the

two rules visually frame each header into a tabular row that

matches the column-separator hairline. Falls back to plain

foreground-colored rules when `window-divider' has no specified

foreground."

(let* ((raw (face-attribute 'window-divider :foreground nil t))

(color (and (stringp raw) raw)))

`(:inherit ,fzfa-vertico-columns-header-face

:overline ,(or color t)

:underline ,(if color `(:color ,color :style line) t))))

(defun fzfa-vertico--scroll-offset (data-cap cur-row n-items)

"Return per-source scroll offset to keep CUR-ROW visible.

DATA-CAP is the visible row count for the band; N-ITEMS is the

total length of the source's candidate list. When CUR-ROW is

nil (the source does not contain the selection) returns 0 — only

the source containing the selection scrolls. Otherwise places

CUR-ROW at the bottom of the visible window once it would

otherwise scroll off-screen, clamped so the source never scrolls

past its last item."

(if (null cur-row) 0

(max 0 (min (max 0 (- n-items data-cap))

(- cur-row (1- data-cap))))))

(defun fzfa-vertico--pick-ncols (parts max-cols vcount headers?)

"Return the column count `vertico--arrange-candidates' should use.

PARTS is the group partition (list of (HEADER . ITEMS)). MAX-COLS is

`fzfa-vertico-columns-max' clamped to at least 1. VCOUNT is

`vertico-count' (visible rows). HEADERS? is `fzfa-vertico-columns-headers'.

`fixed' strategy always returns `(min MAX-COLS (length PARTS))'.

`auto' strategy returns 1 when every source-group's items plus

header fit stacked within VCOUNT vertically; otherwise falls back

to `fixed'. The fit check sums per-group heights so a single

oversized group still trips into multi-column even when the total

count is low."

(let ((nparts (length parts)))

(pcase fzfa-vertico-columns-strategy

('auto

(let ((stacked-height

(cl-loop for (_hdr . items) in parts

sum (+ (length items) (if headers? 1 0)))))

(if (<= stacked-height vcount) 1 (min max-cols nparts))))

(_ (min max-cols nparts)))))

(defun fzfa-vertico--display-width ()

"Return the character width of the window that will render candidates.

Prefers the `vertico--candidates-ov' overlay's `window' property — that

is the window `vertico-buffer-mode' targets, and may live on a child

frame (e.g. a posframe) that `vertico--window-width' does not visit

because `get-buffer-window-list' defaults to the current frame only."

(or (and (overlayp vertico--candidates-ov)

(let ((w (overlay-get vertico--candidates-ov 'window)))

(and (window-live-p w) (window-width w))))

(vertico--window-width)))

;; The cl-defmethod can only be defined once `vertico--arrange-candidates'

;; exists as a generic, so defer registration until vertico loads.

(with-eval-after-load 'vertico

(cl-defmethod vertico--arrange-candidates

(&context (fzfa-vertico-columns-mode (eql t)))

"Arrange candidates in per-source columns.

Specializes on FZFA-VERTICO-COLUMNS-MODE = t via the &context method

qualifier; falls through to the default implementation otherwise."

(let* ((gf (fzfa-vertico--group-function))

(parts (and gf (fzfa-vertico--partition gf))))

(if (or (null parts) (<= (length parts) 1)

;; Narrowed to one source: the group-function returns

;; per-file / per-buffer headers from the source's own

;; `:group' (so the narrowed view matches the source's

;; standalone display), which would otherwise be misread

;; as multiple source-columns here.

(bound-and-true-p fzfa--multi-narrowed-p))

(cl-call-next-method)

;; One-shot: place the initial selection at column 0 row 0 of

;; the partition. Goes through `vertico--goto' so the lock-

;; candidate flag is set — vertico then preserves our snapped

;; candidate through subsequent rescores rather than resetting

;; to index 0 on every input change.

(unless fzfa-vertico--initial-snap-done

(setq fzfa-vertico--initial-snap-done t)

(when-let* ((first-cand (cadr (car parts)))

(target (cl-position first-cand vertico--candidates

:test #'eq))

((/= target vertico--index)))

(vertico--goto target)))

(let* ((nparts (length parts))

(max-cols (max 1 fzfa-vertico-columns-max))

(ncols (fzfa-vertico--pick-ncols

parts max-cols vertico-count

fzfa-vertico-columns-headers))

(nbands-total (max 1 (ceiling (/ (float nparts) ncols))))

;; Pagination: cap visible bands to fit `page-size' sources.

;; `page-size' nil / 0 → show all bands (no pagination).

(page-size fzfa-vertico-columns-page-size)

(nbands (if (and page-size (> page-size 0))

(max 1 (min nbands-total

(ceiling (/ (float page-size) ncols))))

nbands-total))

;; Selection's (source-idx . row-in-source). Only the

;; containing source scrolls; others stay parked at top.

(sel-pos (fzfa-vertico--locate parts vertico--index))

(sel-src (car sel-pos))

(sel-row (cdr sel-pos))

;; Slide the band window so the selection's band stays

;; visible. Past the right edge → advance offset; past

;; the left edge → retreat; otherwise keep the prior

;; offset (so a stable selection doesn't trigger scroll

;; jitter as rescores reorder).

(sel-band (and sel-src (/ sel-src ncols)))

(prev-offset fzfa-vertico--band-offset)

(raw-offset

(cond

((null sel-band) prev-offset)

((< sel-band prev-offset) sel-band)

((>= sel-band (+ prev-offset nbands))

(1+ (- sel-band nbands)))

(t prev-offset)))

(band-offset (max 0 (min raw-offset (- nbands-total nbands))))

(sep fzfa-vertico-columns-separator)

(sepw (string-width sep))

(win-w (fzfa-vertico--display-width))

(avail (max ncols (- win-w (* (max 0 (1- ncols)) sepw))))

(col-w (max fzfa-vertico-columns-min-width

(if fzfa-vertico-columns-max-width

(min fzfa-vertico-columns-max-width

(/ avail ncols))

(/ avail ncols))))

(header? fzfa-vertico-columns-headers)

;; Distribute `vertico-count' rows across VISIBLE bands.

;; Pagination's headline benefit: fewer bands on-screen →

;; more rows per band.

(rows-per-band (max (if header? 2 1)

(/ vertico-count nbands)))

(data-cap (max 1 (- rows-per-band (if header? 1 0))))

(lines nil))

(setq fzfa-vertico--band-offset band-offset)

(dotimes (i nbands)

(let* ((band-idx (+ band-offset i))

(start (* band-idx ncols))

(end (min nparts (+ start ncols)))

(band-entries

(cl-loop for s from start below end

collect

(let* ((part (nth s parts))

(items (cdr part))

(n (length items))

(cur (and sel-src (= s sel-src) sel-row))

(off (fzfa-vertico--scroll-offset

data-cap cur n)))

(list :part part :offset off

:visible (max 0 (- n off))))))

(band-visible

(apply #'max 0

(mapcar (lambda (e) (plist-get e :visible))

band-entries)))

(data-rows (min data-cap band-visible)))

(when header?

(let ((face (fzfa-vertico--header-face-spec)))

(push

(concat

(mapconcat

(lambda (e)

(propertize

(truncate-string-to-width

(car (plist-get e :part)) col-w 0 ?\s)

'face face))

band-entries sep)

"\n")

lines)))

(dotimes (r data-rows)

(push

(concat

(mapconcat

(lambda (e)

(let* ((items (cdr (plist-get e :part)))

(off (plist-get e :offset))

(cand (nth (+ off r) items)))

(if-let* ((cand)

(idx (cl-position cand vertico--candidates

:test #'eq)))

(fzfa-vertico--render-cell cand idx col-w gf)

(make-string col-w ?\s))))

band-entries sep)

"\n")

lines))))

(nreverse lines))))))

;;; Setup

;;;###autoload

(defun fzfa-vertico-setup ()

"Wire fzfa's vertico integration into the current session.

Invoked by `fzfa-setup' when `vertico' is listed in

`fzfa-extensions'. No-op when `vertico' is not installed —

keeping the default `fzfa-extensions' list portable across users

who use other completion UIs. Otherwise, when

`fzfa-vertico-columns-auto' is non-nil:

1. Each symbol in `fzfa-vertico-multiform-categories' is added to

`vertico-multiform-categories' as

(CATEGORY `fzfa-vertico-columns-mode'), so the columns layout

auto-activates inside those categories' `completing-read' sessions.

2. `vertico-multiform-mode' is turned on if not already, so the

categories list is honored."

(when (and fzfa-vertico-columns-auto

(locate-library "vertico"))

(require 'vertico nil t)

(require 'vertico-multiform nil t)

;; Preload vertico's optional display-mode extensions so

;; `vertico-multiform--setup' can resolve bare symbols like

;; `indexed', `grid', `flat', `unobtrusive', `reverse', `buffer' in

;; the user's `vertico-multiform-commands' / `vertico-multiform-

;; categories'. vertico-multiform uses `intern-soft' + `fboundp'

;; to look up `vertico-<sym>-mode', which needs the extension's

;; autoload actually loaded — autoloads.el defines it but nothing

;; forces load until we do here. Silent (`nil t') for extensions

;; not shipped by the user's vertico version.

(dolist (ext '(vertico-indexed vertico-grid vertico-flat

vertico-unobtrusive vertico-reverse vertico-buffer))

(require ext nil t))

(dolist (cat fzfa-vertico-multiform-categories)

(let ((entry (list cat 'fzfa-vertico-columns-mode)))

(cl-pushnew entry vertico-multiform-categories :test #'equal)))

(unless (bound-and-true-p vertico-multiform-mode)

(vertico-multiform-mode 1))))

(provide 'fzfa-vertico)

;;; fzfa-vertico.el ends here