update lua API to 1-based indices; add renderer

examples/counter.lua

@@ -0,0 +1,65 @@
+local tracker = require 'u.tracker'
+local Buffer = require 'u.buffer'
+local h = require('u.renderer').h
+
+-- Create an buffer for the UI
+vim.cmd.vnew()
+local ui_buf = Buffer.current()
+ui_buf:set_tmp_options()
+
+local s_count = tracker.create_signal(0, 'counter_signal')
+
+-- Effect: Render
+-- Setup the effect for rendering the UI whenever dependencies are updated
+tracker.create_effect(function()
+  -- Calling `Signal:get()` in an effect registers the given signal as a
+  -- dependency of the current effect. Whenever that signal (or any other
+  -- dependency) changes, the effect will rerun. In this particular case,
+  -- rendering the UI is an effect that depends on one signal.
+  local count = s_count:get()
+
+  -- Markup is hyperscript, which is just 1) text, and 2) tags (i.e.,
+  -- constructed with `h(...)` calls). To help organize the markup, text and
+  -- tags can be nested in tables at any depth. Line breaks must be specified
+  -- manually, with '\n'.
+  ui_buf:render {
+    'Reactive Counter Example\n',
+    '========================\n\n',
+
+    { 'Counter: ', tostring(count), '\n' },
+
+    '\n',
+
+    {
+      h('text', {
+        hl = 'DiffDelete',
+        nmap = {
+          ['<CR>'] = function()
+            -- Update the contents of the s_count signal, notifying any
+            -- dependencies (in this case, the render effect):
+            s_count:schedule_update(function(n) return n - 1 end)
+            -- Also equivalent: s_count:schedule_set(s_count:get() - 1)
+            return ''
+          end,
+        },
+      }, ' Decrement '),
+      ' ',
+      h('text', {
+        hl = 'DiffAdd',
+        nmap = {
+          ['<CR>'] = function()
+            -- Update the contents of the s_count signal, notifying any
+            -- dependencies (in this case, the render effect):
+            s_count:schedule_update(function(n) return n + 1 end)
+            -- Also equivalent: s_count:schedule_set(s_count:get() - 1)
+            return ''
+          end,
+        },
+      }, ' Increment '),
+    },
+
+    '\n',
+    '\n',
+    { 'Press <CR> on each "button" above to increment/decrement the counter.' },
+  }
+end)

examples/filetree.lua

@@ -0,0 +1,468 @@
+--------------------------------------------------------------------------------
+-- File Tree Viewer Module
+--
+-- Future Enhancements:
+-- - Consider implementing additional features like searching for files,
+--   filtering displayed nodes, or adding support for more file types.
+-- - Improve user experience with customizable UI elements and enhanced
+--   navigation options.
+-- - Implement a file watcher to automatically update the file tree when files
+--   change on the underlying filesystem.
+--------------------------------------------------------------------------------
+
+--- @alias FsDir { kind: 'dir'; path: string; expanded: boolean; children: FsNode[] }
+--- @alias FsFile { kind: 'file'; path: string }
+--- @alias FsNode FsDir | FsFile
+--- @alias ShowOpts { root_path?: string, width?: number, focus_path?: string }
+
+local Buffer = require 'u.buffer'
+local Renderer = require('u.renderer').Renderer
+local TreeBuilder = require('u.renderer').TreeBuilder
+local h = require('u.renderer').h
+local tracker = require 'u.tracker'
+
+local logger = require('u.logger').Logger.new 'filetree'
+
+local M = {}
+local H = {}
+
+--------------------------------------------------------------------------------
+-- Helpers:
+--------------------------------------------------------------------------------
+
+--- Splits the given path into a list of path components.
+--- @param path string
+function H.split_path(path)
+  local parts = {}
+  local curr = path
+  while #curr > 0 and curr ~= '.' and curr ~= '/' do
+    table.insert(parts, 1, vim.fs.basename(curr))
+    curr = vim.fs.dirname(curr)
+  end
+  return parts
+end
+
+--- Normalizes the given path to an absolute path.
+--- @param path string
+function H.normalize(path) return vim.fs.abspath(vim.fs.normalize(path)) end
+
+--- Computes the relative path from `base` to `path`.
+--- @param path string
+--- @param base string
+function H.relative(path, base)
+  path = H.normalize(path)
+  base = H.normalize(base)
+  if path:sub(1, #base) == base then path = path:sub(#base + 1) end
+  if vim.startswith(path, '/') then path = path:sub(2) end
+  return path
+end
+
+--- @param root_path string
+--- @return { tree: FsDir; path_to_node: table<string, FsNode> }
+function H.get_tree_inf(root_path)
+  logger:info { 'get_tree_inf', root_path }
+  --- @type table<string, FsNode>
+  local path_to_node = {}
+
+  --- @type FsDir
+  local tree = {
+    kind = 'dir',
+    path = H.normalize(root_path or '.'),
+    expanded = true,
+    children = {},
+  }
+  path_to_node[tree.path] = tree
+
+  H.populate_dir_children(tree, path_to_node)
+  return { tree = tree, path_to_node = path_to_node }
+end
+
+--- @param tree FsDir
+--- @param path_to_node table<string, FsNode>
+function H.populate_dir_children(tree, path_to_node)
+  tree.children = {}
+
+  for child_path, kind in vim.iter(vim.fs.dir(tree.path, { depth = 1 })) do
+    child_path = H.normalize(vim.fs.joinpath(tree.path, child_path))
+    local prev_node = path_to_node[child_path]
+
+    if kind == 'directory' then
+      local new_node = {
+        kind = 'dir',
+        path = child_path,
+        expanded = prev_node and prev_node.expanded or false,
+        children = prev_node and prev_node.children or {},
+      }
+      path_to_node[new_node.path] = new_node
+      table.insert(tree.children, new_node)
+    else
+      local new_node = {
+        kind = 'file',
+        path = child_path,
+      }
+      path_to_node[new_node.path] = new_node
+      table.insert(tree.children, new_node)
+    end
+  end
+
+  table.sort(tree.children, function(a, b)
+    -- directories first:
+    if a.kind ~= b.kind then return a.kind == 'dir' end
+    return a.path < b.path
+  end)
+end
+
+--- @param opts {
+---   bufnr: number;
+---   prev_winnr: number;
+---   root_path: string;
+---   focus_path?: string;
+--- }
+---
+--- @return { expand: fun(path: string), collapse: fun(path: string) }
+local function _render_in_buffer(opts)
+  local winnr = vim.api.nvim_buf_call(
+    opts.bufnr,
+    function() return vim.api.nvim_get_current_win() end
+  )
+  local s_tree_inf = tracker.create_signal(H.get_tree_inf(opts.root_path))
+  local s_focused_path = tracker.create_signal(H.normalize(opts.focus_path or opts.root_path))
+
+  tracker.create_effect(function()
+    local focused_path = s_focused_path:get()
+
+    s_tree_inf:update(function(tree_inf)
+      local parts = H.split_path(H.relative(focused_path, tree_inf.tree.path))
+      local path_to_node = tree_inf.path_to_node
+
+      --- @param node FsDir
+      --- @param child_names string[]
+      local function expand_to(node, child_names)
+        if #child_names == 0 then return end
+        node.expanded = true
+
+        local next_child_name = table.remove(child_names, 1)
+        for _, child in ipairs(node.children) do
+          if child.kind == 'dir' and vim.fs.basename(child.path) == next_child_name then
+            H.populate_dir_children(child, path_to_node)
+            expand_to(child, child_names)
+          end
+        end
+      end
+      expand_to(tree_inf.tree, parts)
+      return tree_inf
+    end)
+  end)
+
+  --
+  -- :help watch-file
+  --
+  local watcher = vim.uv.new_fs_event()
+  if watcher ~= nil then
+    --- @diagnostic disable-next-line: unused-local
+    watcher:start(opts.root_path, { recursive = true }, function(_err, fname, _status)
+      fname = H.normalize(fname)
+
+      local dir_path = vim.fs.dirname(fname)
+      local dir = s_tree_inf:get().path_to_node[dir_path]
+      if not dir then return end
+
+      s_tree_inf:schedule_update(function(tree_inf)
+        H.populate_dir_children(dir, tree_inf.path_to_node)
+        return tree_inf
+      end)
+    end)
+  end
+  vim.api.nvim_create_autocmd('WinClosed', {
+    once = true,
+    pattern = tostring(winnr),
+    callback = function()
+      if watcher == nil then return end
+
+      watcher:stop()
+      watcher = nil
+    end,
+  })
+
+  local controller = {}
+
+  --- @param path string
+  function controller.focus_path(path) s_focused_path:set(H.normalize(path)) end
+
+  function controller.refresh() s_tree_inf:set(H.get_tree_inf(opts.root_path)) end
+
+  --- @param path string
+  function controller.expand(path)
+    path = H.normalize(path)
+    local path_to_node = s_tree_inf:get().path_to_node
+
+    local node = path_to_node[path]
+    if node == nil then return end
+
+    if node.kind == 'dir' then
+      s_tree_inf:update(function(tree_inf2)
+        H.populate_dir_children(node, path_to_node)
+        tree_inf2.path_to_node[node.path].expanded = true
+        return tree_inf2
+      end)
+      if #node.children == 0 then
+        s_focused_path:set(node.path)
+      else
+        s_focused_path:set(node.children[1].path)
+      end
+    else
+      if node.kind == 'file' then
+        -- open file:
+        vim.api.nvim_win_call(opts.prev_winnr, function() vim.cmd.edit(node.path) end)
+        vim.api.nvim_set_current_win(opts.prev_winnr)
+      end
+    end
+  end
+
+  --- @param path string
+  function controller.collapse(path)
+    path = H.normalize(path)
+    local path_to_node = s_tree_inf:get().path_to_node
+
+    local node = path_to_node[path]
+    if node == nil then return end
+
+    if node.kind == 'dir' then
+      if node.expanded then
+        -- collapse self/node:
+        s_focused_path:set(node.path)
+        s_tree_inf:update(function(tree_inf2)
+          tree_inf2.path_to_node[node.path].expanded = false
+          return tree_inf2
+        end)
+      else
+        -- collapse parent:
+        local parent_dir = path_to_node[vim.fs.dirname(node.path)]
+        if parent_dir ~= nil then
+          s_focused_path:set(parent_dir.path)
+          s_tree_inf:update(function(tree_inf2)
+            tree_inf2.path_to_node[parent_dir.path].expanded = false
+            return tree_inf2
+          end)
+        end
+      end
+    elseif node.kind == 'file' then
+      local parent_dir = path_to_node[vim.fs.dirname(node.path)]
+      if parent_dir ~= nil then
+        s_focused_path:set(parent_dir.path)
+        s_tree_inf:update(function(tree_inf2)
+          tree_inf2.path_to_node[parent_dir.path].expanded = false
+          return tree_inf2
+        end)
+      end
+    end
+  end
+
+  --- @param root_path string
+  function controller.new(root_path)
+    vim.ui.input({
+      prompt = 'New: ',
+      completion = 'file',
+    }, function(input)
+      if input == nil then return end
+      local new_path = vim.fs.joinpath(root_path, input)
+
+      if vim.endswith(input, '/') then
+        -- Create a directory:
+        vim.fn.mkdir(new_path, input, 'p')
+      else
+        -- Create a file:
+
+        -- First, make sure the parent directory exists:
+        vim.fn.mkdir(vim.fs.dirname(new_path), 'p')
+
+        -- Now create an empty file:
+        local uv = vim.loop or vim.uv
+        local fd = uv.fs_open(new_path, 'w', 438)
+        if fd then uv.fs_write(fd, '') end
+      end
+
+      controller.refresh()
+      controller.focus_path(new_path)
+    end)
+  end
+
+  --- @param path string
+  function controller.rename(path)
+    path = H.normalize(path)
+    local root_path = vim.fs.dirname(path)
+    vim.ui.input({
+      prompt = 'Rename: ',
+      default = vim.fs.basename(path),
+      completion = 'file',
+    }, function(input)
+      if input == nil then return end
+
+      local new_path = vim.fs.joinpath(root_path, input);
+      (vim.loop or vim.uv).fs_rename(path, new_path)
+      controller.refresh()
+      controller.focus_path(new_path)
+    end)
+  end
+
+  --
+  -- Render:
+  --
+  local renderer = Renderer.new(opts.bufnr)
+  tracker.create_effect(function()
+    --- @type { tree: FsDir; path_to_node: table<string, FsNode> }
+    local tree_inf = s_tree_inf:get()
+    local tree = tree_inf.tree
+
+    --- @type string
+    local focused_path = s_focused_path:get()
+
+    --- As we render the tree, keep track of what line each node is on, so that
+    --- we have an easy way to make the cursor jump to each node (i.e., line)
+    --- at will:
+    --- @type table<string, number>
+    local node_lines = {}
+    local current_line = 0
+
+    --- The UI is rendered as a list of hypserscript elements:
+    local tb = TreeBuilder.new()
+
+    --- Since the filesystem is a recursive tree of nodes, we need to
+    --- recursively render each node. This function does just that:
+    --- @param node FsNode
+    --- @param level number
+    local function render_node(node, level)
+      local name = vim.fs.basename(node.path)
+      current_line = current_line + 1
+      node_lines[node.path] = current_line
+
+      local nmaps = {
+        h = function()
+          vim.schedule(function() controller.collapse(node.path) end)
+          return ''
+        end,
+        l = function()
+          vim.schedule(function() controller.expand(node.path) end)
+          return ''
+        end,
+        n = function()
+          vim.schedule(
+            function()
+              controller.new(node.kind == 'file' and vim.fs.dirname(node.path) or node.path)
+            end
+          )
+          return ''
+        end,
+        r = function()
+          vim.schedule(function() controller.rename(node.path) end)
+          return ''
+        end,
+        y = function()
+          vim.fn.setreg([["]], H.relative(node.path, tree.path))
+          return ''
+        end,
+      }
+
+      if node.kind == 'dir' then
+        --
+        -- Render a directory node:
+        --
+        local icon = node.expanded and '' or ''
+        tb:put {
+          current_line > 1 and '\n',
+          h(
+            'text',
+            { hl = 'Constant', nmap = nmaps },
+            { string.rep('  ', level), icon, ' ', name }
+          ),
+        }
+        if node.expanded then
+          for _, child in ipairs(node.children) do
+            render_node(child, level + 1)
+          end
+        end
+      elseif node.kind == 'file' then
+        tb:put {
+          current_line > 1 and '\n',
+          h('text', { nmap = nmaps }, { string.rep('  ', level), '󰈔 ', name }),
+        }
+      end
+    end
+    render_node(tree, 0)
+
+    -- The following modifies buffer contents, so it needs to be scheduled:
+    vim.schedule(function()
+      renderer:render(tb:tree())
+
+      local cpos = vim.api.nvim_win_get_cursor(winnr)
+      pcall(vim.api.nvim_win_set_cursor, winnr, { node_lines[focused_path], cpos[2] })
+    end)
+  end, 's:tree')
+
+  return controller
+end
+
+--------------------------------------------------------------------------------
+-- Public API functions:
+--------------------------------------------------------------------------------
+
+--- @type {
+---   bufnr: number;
+---   winnr: number;
+---   controller: { expand: fun(path: string), collapse: fun(path: string) };
+--- } | nil
+local current_inf = nil
+
+--- Show the filetree:
+--- @param opts? ShowOpts
+function M.show(opts)
+  if current_inf ~= nil then return current_inf.controller end
+  opts = opts or {}
+
+  local prev_winnr = vim.api.nvim_get_current_win()
+
+  vim.cmd 'vnew'
+  local buf = Buffer.from_nr(vim.api.nvim_get_current_buf())
+  buf:set_tmp_options()
+
+  local winnr = vim.api.nvim_get_current_win()
+  vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes('<C-w>H', true, true, true), 'x', false)
+  vim.api.nvim_win_set_width(0, opts.width or 30)
+  vim.api.nvim_create_autocmd('WinClosed', {
+    once = true,
+    pattern = tostring(winnr),
+    callback = M.hide,
+  })
+
+  vim.wo[0][0].number = false
+  vim.wo[0][0].relativenumber = false
+
+  local bufnr = vim.api.nvim_get_current_buf()
+
+  local controller = _render_in_buffer(vim.tbl_extend('force', opts, {
+    bufnr = bufnr,
+    prev_winnr = prev_winnr,
+    root_path = opts.root_path or H.normalize '.',
+  }))
+  current_inf = { bufnr = bufnr, winnr = winnr, controller = controller }
+  return controller
+end
+
+--- Hide the filetree:
+function M.hide()
+  if current_inf == nil then return end
+  pcall(vim.cmd.bdelete, current_inf.bufnr)
+  current_inf = nil
+end
+
+--- Toggle the filetree:
+--- @param opts? ShowOpts
+function M.toggle(opts)
+  if current_inf == nil then
+    M.show(opts)
+  else
+    M.hide()
+  end
+end
+
+return M

examples/notify.lua

@@ -0,0 +1,137 @@
+local Buffer = require 'u.buffer'
+local TreeBuilder = require('u.renderer').TreeBuilder
+local tracker = require 'u.tracker'
+local utils = require 'u.utils'
+local Window = require 'my.window'
+
+local TIMEOUT = 4000
+local ICONS = {
+  [vim.log.levels.TRACE] = { text = '󰃤', group = 'DiagnosticSignOk' },
+  [vim.log.levels.DEBUG] = { text = '󰃤', group = 'DiagnosticSignOk' },
+  [vim.log.levels.INFO] = { text = '', group = 'DiagnosticSignInfo' },
+  [vim.log.levels.WARN] = { text = '', group = 'DiagnosticSignWarn' },
+  [vim.log.levels.ERROR] = { text = '', group = 'DiagnosticSignError' },
+}
+local DEFAULT_ICON = { text = '', group = 'DiagnosticSignOk' }
+
+--- @alias Notification {
+---   kind: number;
+---   id: number;
+---   text: string;
+--- }
+
+local M = {}
+
+--- @type Window | nil
+local notifs_w
+
+local s_notifications_raw = tracker.create_signal {}
+local s_notifications = s_notifications_raw:debounce(50)
+
+-- Render effect:
+tracker.create_effect(function()
+  --- @type Notification[]
+  local notifs = s_notifications:get()
+
+  if #notifs == 0 then
+    if notifs_w then
+      notifs_w:close(true)
+      notifs_w = nil
+    end
+    return
+  end
+
+  vim.schedule(function()
+    local editor_size = utils.get_editor_dimensions()
+    local avail_width = editor_size.width
+    local float_width = 40
+    local win_config = {
+      relative = 'editor',
+      anchor = 'NE',
+      row = 0,
+      col = avail_width,
+      width = float_width,
+      height = math.min(#notifs, editor_size.height - 3),
+      border = 'single',
+      focusable = false,
+    }
+    if not notifs_w or not vim.api.nvim_win_is_valid(notifs_w.win) then
+      notifs_w = Window.new(Buffer.create(false, true), win_config)
+      vim.wo[notifs_w.win].cursorline = false
+      vim.wo[notifs_w.win].list = false
+      vim.wo[notifs_w.win].listchars = ''
+      vim.wo[notifs_w.win].number = false
+      vim.wo[notifs_w.win].relativenumber = false
+      vim.wo[notifs_w.win].wrap = false
+    else
+      notifs_w:set_config(win_config)
+    end
+
+    notifs_w:render(TreeBuilder.new()
+      :nest(function(tb)
+        for idx, notif in ipairs(notifs) do
+          if idx > 1 then tb:put '\n' end
+
+          local notif_icon = ICONS[notif.kind] or DEFAULT_ICON
+          tb:put_h('text', { hl = notif_icon.group }, notif_icon.text)
+          tb:put { '  ', notif.text }
+        end
+      end)
+      :tree())
+    vim.api.nvim_win_call(notifs_w.win, function()
+      -- scroll to bottom:
+      vim.cmd.normal 'G'
+      -- scroll all the way to the left:
+      vim.cmd.normal '9999zh'
+    end)
+  end)
+end)
+
+local _orig_notify
+
+--- @param msg string
+--- @param level integer|nil
+--- @param opts table|nil
+local function my_notify(msg, level, opts)
+  vim.schedule(function() _orig_notify(msg, level, opts) end)
+  if level == nil then level = vim.log.levels.INFO end
+  if level < vim.log.levels.INFO then return end
+
+  local id = math.random(math.huge)
+
+  --- @param notifs Notification[]
+  s_notifications_raw:schedule_update(function(notifs)
+    table.insert(notifs, { kind = level, id = id, text = msg })
+    return notifs
+  end)
+
+  vim.defer_fn(function()
+    --- @param notifs Notification[]
+    s_notifications_raw:schedule_update(function(notifs)
+      for i, notif in ipairs(notifs) do
+        if notif.id == id then
+          table.remove(notifs, i)
+          break
+        end
+      end
+      return notifs
+    end)
+  end, TIMEOUT)
+end
+
+local _once_msgs = {}
+local function my_notify_once(msg, level, opts)
+  if vim.tbl_contains(_once_msgs, msg) then return false end
+  table.insert(_once_msgs, msg)
+  vim.notify(msg, level, opts)
+  return true
+end
+
+function M.setup()
+  if _orig_notify == nil then _orig_notify = vim.notify end
+
+  vim.notify = my_notify
+  vim.notify_once = my_notify_once
+end
+
+return M

examples/picker.lua

@@ -0,0 +1,949 @@
+local utils = require 'u.utils'
+local Buffer = require 'u.buffer'
+local Renderer = require('u.renderer').Renderer
+local h = require('u.renderer').h
+local TreeBuilder = require('u.renderer').TreeBuilder
+local tracker = require 'u.tracker'
+
+local M = {}
+
+local S_EDITOR_DIMENSIONS =
+  tracker.create_signal(utils.get_editor_dimensions(), 's:editor_dimensions')
+vim.api.nvim_create_autocmd('VimResized', {
+  callback = function()
+    local new_dim = utils.get_editor_dimensions()
+    S_EDITOR_DIMENSIONS:set(new_dim)
+  end,
+})
+
+--- @param low number
+--- @param x number
+--- @param high number
+local function clamp(low, x, high)
+  x = math.max(low, x)
+  x = math.min(x, high)
+  return x
+end
+
+--- @generic T
+--- @param arr `T`[]
+--- @return T[]
+local function shallow_copy_arr(arr) return vim.iter(arr):totable() end
+
+--------------------------------------------------------------------------------
+-- BEGIN create_picker
+--
+-- This is the star of the show (in this file, anyway).
+-- In summary, the outline of this function is:
+-- 1. Setup signals/memos for computing the picker size, and window positions
+-- 2. Create the two windows:
+--   a. The picker input. This is where the filter is typed
+--   b. The picker list. This is where the items are displayed
+-- 3. Setup event handlers that respond to user input
+-- 4. Render the list. After all the prework above, this is probably the
+--    shortest portion of this function.
+--------------------------------------------------------------------------------
+
+--- @alias SelectController {
+---   get_items: fun(): T[];
+---   set_items: fun(items: T[]);
+---   set_filter_text: fun(filter_text: string);
+---   get_selected_indices: fun(): number[];
+---   get_selected_items: fun(): T[];
+---   set_selected_indices: fun(indicies: number[], ephemeral?: boolean);
+---   close: fun();
+--- }
+--- @alias SelectOpts<T> {
+---   items: `T`[];
+---   multi?: boolean;
+---   format_item?: fun(item: T): Tree;
+---   on_finish?: fun(items: T[], indicies: number[]);
+---   on_selection_changed?: fun(items: T[], indicies: number[]);
+---   mappings?: table<string, fun(select: SelectController)>;
+--- }
+
+--- @generic T
+--- @param opts SelectOpts<T>
+function M.create_picker(opts) -- {{{
+  local is_in_insert_mode = vim.api.nvim_get_mode().mode:sub(1, 1) == 'i'
+  local stopinsert = not is_in_insert_mode
+
+  if opts.multi == nil then opts.multi = false end
+
+  local H = {}
+
+  --- Runs a function `fn`, and if it fails, cleans up the UI by calling
+  --- `H.finish`
+  ---
+  --- @generic T
+  --- @param fn fun(): `T`
+  --- @return T
+  local function safe_run(fn, ...)
+    local ok, result_or_error = pcall(fn, ...)
+    if not ok then
+      pcall(H.finish, true, result_or_error)
+      error(result_or_error .. '\n' .. debug.traceback())
+    end
+    return result_or_error
+  end
+
+  --- Creates a function that safely calls the given function, cleaning up the
+  --- UI if it ever fails
+  ---
+  --- @generic T
+  --- @param fn `T`
+  --- @return T
+  local function safe_wrap(fn)
+    return function(...) return safe_run(fn, ...) end
+  end
+
+  --
+  -- Compute the positions of the input bar and the list:
+  --
+
+  -- Reactively compute the space available for the picker based on the size of
+  -- the editor
+  local s_editor_dimensions = S_EDITOR_DIMENSIONS:clone()
+  local s_picker_space_available = tracker.create_memo(safe_wrap(function()
+    local editor_dim = s_editor_dimensions:get()
+    local width = math.floor(editor_dim.width * 0.75)
+    local height = math.floor(editor_dim.height * 0.75)
+    local row = math.floor((editor_dim.height - height) / 2)
+    local col = math.floor((editor_dim.width - width) / 2)
+    return { width = width, height = height, row = row, col = col }
+  end))
+
+  -- Reactively compute the size of the prompt (input) bar
+  local s_w_input_coords = tracker.create_memo(safe_wrap(function()
+    local picker_coords = s_picker_space_available:get()
+    return {
+      width = picker_coords.width,
+      height = 1,
+      row = picker_coords.row,
+      col = picker_coords.col,
+    }
+  end))
+
+  -- Reactively compute the size of the list view
+  local s_w_list_coords = tracker.create_memo(safe_wrap(function()
+    local picker_coords = s_picker_space_available:get()
+    return {
+      width = picker_coords.width,
+      height = picker_coords.height - 3,
+      row = picker_coords.row + 3,
+      col = picker_coords.col,
+    }
+  end))
+
+  --
+  -- Create resources (i.e., windows):
+  --
+
+  local w_input_cfg = {
+    width = s_w_input_coords:get().width,
+    height = s_w_input_coords:get().height,
+    row = s_w_input_coords:get().row,
+    col = s_w_input_coords:get().col,
+    relative = 'editor',
+    focusable = true,
+    border = vim.o.winborder or 'rounded',
+  }
+  local w_input_buf = Buffer.create(false, true)
+  local w_input = vim.api.nvim_open_win(w_input_buf.bufnr, false, w_input_cfg)
+  vim.wo[w_input][0].cursorline = false
+  vim.wo[w_input][0].list = false
+  vim.wo[w_input][0].number = false
+  vim.wo[w_input][0].relativenumber = false
+
+  -- The following option is a signal to other plugins like 'cmp' to not mess
+  -- with this buffer:
+  vim.bo[w_input_buf.bufnr].buftype = 'prompt'
+  vim.fn.prompt_setprompt(w_input_buf.bufnr, '')
+
+  vim.api.nvim_set_current_win(w_input)
+  tracker.create_effect(safe_wrap(function()
+    -- update window position/size every time the editor is resized:
+    w_input_cfg = vim.tbl_deep_extend('force', w_input_cfg, s_w_input_coords:get())
+    vim.api.nvim_win_set_config(w_input, w_input_cfg)
+  end))
+
+  local w_list_cfg = {
+    width = s_w_list_coords:get().width,
+    height = s_w_list_coords:get().height,
+    row = s_w_list_coords:get().row,
+    col = s_w_list_coords:get().col,
+    relative = 'editor',
+    focusable = true,
+    border = 'rounded',
+  }
+  local w_list_buf = Buffer.create(false, true)
+  local w_list = vim.api.nvim_open_win(w_list_buf.bufnr, false, w_list_cfg)
+  vim.wo[w_list][0].number = false
+  vim.wo[w_list][0].relativenumber = false
+  vim.wo[w_list][0].scrolloff = 0
+  tracker.create_effect(safe_wrap(function()
+    -- update window position/size every time the editor is resized:
+    w_list_cfg = vim.tbl_deep_extend('force', w_list_cfg, s_w_list_coords:get())
+    vim.api.nvim_win_set_config(w_list, w_list_cfg)
+  end))
+
+  -- Now that we have created the window with the prompt in it, start insert
+  -- mode so that the user can type immediately:
+  vim.cmd.startinsert()
+
+  --
+  -- State:
+  --
+
+  local s_items_raw = tracker.create_signal(opts.items, 's:items')
+  local s_items = s_items_raw:debounce(100)
+  local s_selected_indices = tracker.create_signal({}, 's:selected_indices')
+  local s_top_offset = tracker.create_signal(0, 's:top_offset')
+  local s_cursor_index = tracker.create_signal(1, 's:cursor_index')
+
+  local s_filter_text_undebounced = tracker.create_signal('', 's:filter_text')
+  w_input_buf:autocmd('TextChangedI', {
+    callback = safe_wrap(
+      function() s_filter_text_undebounced:set(vim.api.nvim_get_current_line()) end
+    ),
+  })
+  local s_filter_text = s_filter_text_undebounced:debounce(50)
+
+  --
+  -- Derived State:
+  --
+
+  local s_formatted_items = tracker.create_memo(function()
+    local function _format_item(item)
+      return opts.format_item and opts.format_item(item) or tostring(item)
+    end
+
+    local items = s_items:get()
+    return vim
+      .iter(items)
+      :map(function(item) return { item = item, formatted = _format_item(item) } end)
+      :totable()
+  end)
+
+  -- When the filter text changes, update the filtered items:
+  local s_filtered_items = tracker.create_memo(
+    safe_wrap(function()
+      local formatted_items = s_formatted_items:get()
+      local filter_text = vim.trim(s_filter_text:get()):lower()
+
+      --- @type string
+      local filter_pattern
+      --- @type boolean
+      local use_plain_pattern
+      if #formatted_items > 250 and #filter_text <= 3 then
+        filter_pattern = filter_text
+        use_plain_pattern = true
+      elseif #formatted_items > 1000 then
+        filter_pattern = filter_text
+        use_plain_pattern = true
+      else
+        filter_pattern = '('
+          .. vim.iter(vim.split(filter_text, '')):map(function(c) return c .. '.*' end):join ''
+          .. ')'
+        use_plain_pattern = false
+      end
+      filter_pattern = filter_pattern:lower()
+
+      --- @type table<integer, string>
+      local formatted_strings = {}
+      --- @type table<integer, string>
+      local matches = {}
+
+      local new_filtered_items = vim
+        .iter(formatted_items)
+        :enumerate()
+        :map(
+          function(i, inf) return { orig_idx = i, item = inf.item, formatted = inf.formatted } end
+        )
+        :filter(function(inf)
+          if filter_text == '' then return true end
+          local formatted_as_string = Renderer.markup_to_string({ tree = inf.formatted }):lower()
+
+          formatted_strings[inf.orig_idx] = formatted_as_string
+          if use_plain_pattern then
+            local x, y = formatted_as_string:find(filter_pattern, 1, true)
+            if x ~= nil and y ~= nil then matches[inf.orig_idx] = formatted_as_string:sub(x, y) end
+          else
+            matches[inf.orig_idx] = string.match(formatted_as_string, filter_pattern)
+          end
+
+          return matches[inf.orig_idx] ~= nil
+        end)
+        :totable()
+
+      -- Don't sort if there are over 500 items:
+      if #new_filtered_items <= 500 then
+        table.sort(new_filtered_items, function(a_inf, b_inf)
+          local a = formatted_strings[a_inf.orig_idx]
+          local b = formatted_strings[b_inf.orig_idx]
+          if a == b then return false end
+
+          local a_match = matches[a_inf.orig_idx]
+          local b_match = matches[b_inf.orig_idx]
+          return #a_match < #b_match
+        end)
+      end
+
+      s_top_offset:set(0)
+      s_cursor_index:set(1)
+      return new_filtered_items
+    end),
+    'e:(filter_text=>filtered_items)'
+  )
+
+  -- Visible items, are _just_ the items that fit into the current viewport.
+  -- This is an optimization so that we are not rendering thousands of lines of
+  -- items on each state-change.
+  local s_visible_items = tracker.create_memo(
+    safe_wrap(function()
+      return vim
+        .iter(s_filtered_items:get())
+        :enumerate()
+        :skip(s_top_offset:get())
+        :take(s_w_list_coords:get().height)
+        :map(
+          function(i, inf)
+            return {
+              filtered_idx = i,
+              orig_idx = inf.orig_idx,
+              item = inf.item,
+              formatted = inf.formatted,
+            }
+          end
+        )
+        :totable()
+    end),
+    'm:visible_items'
+  )
+
+  -- Track selection information:
+  local s_selection_info = tracker.create_memo(
+    safe_wrap(function()
+      local items = s_items:get()
+      local selected_indices = s_selected_indices:get()
+      --- @type { orig_idx: number; item: T }[]
+      local filtered_items = s_filtered_items:get()
+      local cursor_index = s_cursor_index:get()
+      local indices = shallow_copy_arr(selected_indices)
+      if #indices == 0 and #filtered_items > 0 then
+        indices = { filtered_items[cursor_index].orig_idx }
+      end
+      return {
+        items = vim.iter(indices):map(function(i) return items[i] end):totable(),
+        indices = indices,
+      }
+    end),
+    'm:selection_info'
+  )
+
+  --- When it is time to close the picker, this is the main cleanup routine
+  --- that runs in all cases:
+  ---
+  --- @param esc? boolean Whether the user pressed <Esc> or not
+  --- @param err? any Any error that occurred
+  function H.finish(esc, err)
+    -- s_editor_dimensions is the only signal that is cloned from a global,
+    -- one. It is therefore the only one that needs to be manually disposed.
+    -- The other ones should get cleaned up by the GC
+    s_editor_dimensions:dispose()
+    -- If we happen to have any async state-changes coming down the pipeline,
+    -- we can say right now that we are done rendering new UI (to avoid
+    -- "invalid window ID" errors):
+    H.unsubscribe_render_effect()
+    -- buftype=prompt buffers are not "temporary", so delete the buffer manually:
+    vim.api.nvim_buf_delete(w_input_buf.bufnr, { force = true })
+    -- The following is not needed, since the buffer is deleted above:
+    -- vim.api.nvim_win_close(w_input, false)
+    vim.api.nvim_win_close(w_list, false)
+    if stopinsert then vim.cmd.stopinsert() end
+    local inf = s_selection_info:get()
+    if not err and opts.on_finish then
+      -- If on_finish opens another picker, the closing of this one can happen
+      -- in _too_ quick succession, so put a small delay in there.
+      --
+      -- TODO: figure out _why_ this is actually happening, and then a better
+      -- way to handle this.
+      vim.defer_fn(function()
+        if esc then
+          opts.on_finish({}, {})
+        else
+          opts.on_finish(inf.items, inf.indices)
+        end
+      end, 100)
+    end
+  end
+
+  -- On selection info changed:
+  tracker.create_effect(
+    safe_wrap(function()
+      local inf = s_selection_info:get()
+      if opts.on_selection_changed then opts.on_selection_changed(inf.items, inf.indices) end
+    end),
+    'e:selection_changed'
+  )
+
+  --
+  -- Public API (i.e., `controller`):
+  -- We will fill in the methods further down, but we need this variable in scope so that it can be
+  -- closed over by some of the event handlers:
+  --
+  local controller = {}
+
+  --
+  -- Events
+  --
+  vim.keymap.set('i', '<Esc>', function() H.finish(true) end, { buffer = w_input_buf.bufnr })
+
+  vim.keymap.set('i', '<CR>', function() H.finish() end, { buffer = w_input_buf.bufnr })
+
+  local function action_next_line()
+    local max_line = #s_filtered_items:get()
+    local next_cursor_index = clamp(1, s_cursor_index:get() + 1, max_line)
+    if next_cursor_index - s_top_offset:get() > s_w_list_coords:get().height then
+      s_top_offset:set(s_top_offset:get() + 1)
+    end
+    s_cursor_index:set(next_cursor_index)
+  end
+  vim.keymap.set(
+    'i',
+    '<C-n>',
+    safe_wrap(action_next_line),
+    { buffer = w_input_buf.bufnr, desc = 'Picker: next' }
+  )
+  vim.keymap.set(
+    'i',
+    '<Down>',
+    safe_wrap(action_next_line),
+    { buffer = w_input_buf.bufnr, desc = 'Picker: next' }
+  )
+
+  local function action_prev_line()
+    local max_line = #s_filtered_items:get()
+    local next_cursor_index = clamp(1, s_cursor_index:get() - 1, max_line)
+    if next_cursor_index - s_top_offset:get() < 1 then s_top_offset:set(s_top_offset:get() - 1) end
+    s_cursor_index:set(next_cursor_index)
+  end
+  vim.keymap.set(
+    'i',
+    '<C-p>',
+    safe_wrap(action_prev_line),
+    { buffer = w_input_buf.bufnr, desc = 'Picker: previous' }
+  )
+  vim.keymap.set(
+    'i',
+    '<Up>',
+    safe_wrap(action_prev_line),
+    { buffer = w_input_buf.bufnr, desc = 'Picker: previous' }
+  )
+
+  vim.keymap.set(
+    'i',
+    '<Tab>',
+    safe_wrap(function()
+      if not opts.multi then return end
+
+      local index = s_filtered_items:get()[s_cursor_index:get()].orig_idx
+      if vim.tbl_contains(s_selected_indices:get(), index) then
+        s_selected_indices:set(
+          vim.iter(s_selected_indices:get()):filter(function(i) return i ~= index end):totable()
+        )
+      else
+        local new_selected_indices = shallow_copy_arr(s_selected_indices:get())
+        table.insert(new_selected_indices, index)
+        s_selected_indices:set(new_selected_indices)
+      end
+      action_next_line()
+    end),
+    { buffer = w_input_buf.bufnr }
+  )
+
+  for key, fn in pairs(opts.mappings or {}) do
+    vim.keymap.set(
+      'i',
+      key,
+      safe_wrap(function() return fn(controller) end),
+      { buffer = w_input_buf.bufnr }
+    )
+  end
+
+  -- Render:
+  H.unsubscribe_render_effect = tracker.create_effect(
+    safe_wrap(function()
+      local selected_indices = s_selected_indices:get()
+      local top_offset = s_top_offset:get()
+      local cursor_index = s_cursor_index:get()
+      --- @type { filtered_idx: number; orig_idx: number; item: T; formatted: string }[]
+      local visible_items = s_visible_items:get()
+
+      -- The above has to run in the execution context for the signaling to work, but
+      -- the following cannot run in a NeoVim loop-callback:
+      vim.schedule(function()
+        w_list_buf:render(TreeBuilder.new()
+          :nest(function(tb)
+            for loop_idx, inf in ipairs(visible_items) do
+              local is_cur_line = inf.filtered_idx == cursor_index
+              local is_selected = vim.tbl_contains(selected_indices, inf.orig_idx)
+
+              tb:put(loop_idx > 1 and '\n')
+              tb:put(is_cur_line and h('text', { hl = 'Structure' }, '❯') or ' ')
+              tb:put(is_selected and h('text', { hl = 'Comment' }, '* ') or '  ')
+              tb:put(inf.formatted)
+            end
+          end)
+          :tree())
+
+        -- set the window viewport to have the first line in view:
+        pcall(vim.api.nvim_win_call, w_list, function() vim.fn.winrestview { topline = 1 } end)
+        pcall(vim.api.nvim_win_set_cursor, w_list, { cursor_index - top_offset, 0 })
+      end)
+    end),
+    'e:render'
+  )
+
+  --
+  -- Populate the public API:
+  --
+  function controller.get_items()
+    return safe_run(function() return s_items_raw:get() end)
+  end
+
+  --- @param items T[]
+  function controller.set_items(items)
+    return safe_run(function() s_items_raw:set(items) end)
+  end
+
+  function controller.set_filter_text(filter_text)
+    return safe_run(function()
+      vim.api.nvim_win_call(w_input, function() vim.api.nvim_set_current_line(filter_text) end)
+    end)
+  end
+
+  function controller.get_selected_indices()
+    return safe_run(function() return s_selection_info:get().indices end)
+  end
+
+  function controller.get_selected_items()
+    return safe_run(function() return s_selection_info:get().items end)
+  end
+
+  --- @param indicies number[]
+  --- @param ephemeral? boolean
+  function controller.set_selected_indices(indicies, ephemeral)
+    return safe_run(function()
+      if ephemeral == nil then ephemeral = false end
+
+      if ephemeral and #indicies == 1 then
+        local matching_filtered_item_idx, _ = vim.iter(s_filtered_items:get()):enumerate():find(
+          function(_idx, inf) return inf.orig_idx == indicies[1] end
+        )
+        if matching_filtered_item_idx ~= nil then s_cursor_index:set(indicies[1]) end
+      else
+        if not opts.multi then
+          local err = 'Cannot set multiple selected indices on a single-select picker'
+          H.finish(true, err)
+          error(err)
+        end
+        s_selected_indices:set(indicies)
+      end
+    end)
+  end
+
+  function controller.close()
+    return safe_run(function() H.finish(true) end)
+  end
+
+  return controller --[[@as SelectController]]
+end -- }}}
+
+--------------------------------------------------------------------------------
+-- END create_picker
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+-- vim.ui.select override
+--------------------------------------------------------------------------------
+
+local ORIGINAL_UI_SELECT
+function M.register_ui_select()
+  ORIGINAL_UI_SELECT = vim.ui.select
+  --- @generic T
+  --- @param items `T`[]
+  --- @param opts { prompt?: string, kind?: any, format_item?: fun(item: T):string }
+  --- @param cb fun(item: T|nil):any
+  --- @diagnostic disable-next-line: duplicate-set-field
+  function vim.ui.select(items, opts, cb)
+    M.create_picker {
+      items = items,
+      format_item = function(item)
+        local s = opts.format_item and opts.format_item(item) or tostring(item)
+        s = s:gsub('<', '&lt;')
+        return s
+      end,
+      on_finish = function(sel_items)
+        if #sel_items == 0 then cb(nil) end
+        cb(sel_items[#sel_items])
+      end,
+    }
+  end
+end
+function M.unregister_ui_select()
+  if not ORIGINAL_UI_SELECT then return end
+
+  vim.ui.select = ORIGINAL_UI_SELECT
+  ORIGINAL_UI_SELECT = nil
+end
+
+--------------------------------------------------------------------------------
+-- Built-in pickers
+-- 1. files
+-- 2. buffers
+-- 3. code-symbols
+--------------------------------------------------------------------------------
+
+--- @param opts? { limit?: number }
+function M.files(opts) -- {{{
+  opts = opts or {}
+  opts.limit = opts.limit or 10000
+
+  local cmd = {}
+  if vim.fn.executable 'rg' then
+    cmd = {
+      'rg',
+      '--color=never',
+      '--files',
+      '--hidden',
+      '--follow',
+      '-g',
+      '!.git',
+      '-g',
+      '!node_modules',
+      '-g',
+      '!target',
+    }
+  elseif vim.fn.executable 'fd' then
+    cmd = {
+      'fd',
+      '--color=never',
+      '--type',
+      'f',
+      '--hidden',
+      '--follow',
+      '--exclude',
+      '.git',
+      '--exclude',
+      'node_modules',
+      '--exclude',
+      'target',
+    }
+  elseif vim.fn.executable 'find' then
+    cmd = {
+      'find',
+      '-type',
+      'f',
+      '-not',
+      '-path',
+      "'*/.git/*'",
+      '-not',
+      '-path',
+      "'*/node_modules/*'",
+      '-not',
+      '-path',
+      "'*/target/*'",
+      '-printf',
+      "'%P\n'",
+    }
+  end
+
+  if #cmd == 0 then
+    vim.notify('rg/fd/find executable not found: cannot list files', vim.log.levels.ERROR)
+    return
+  end
+
+  -- Keep track of the job that will list files independent from the picker. We
+  -- will stream lines from this process to the picker as they come in:
+  local job_inf = { id = 0, proc_lines = {}, notified_over_limit = false }
+
+  -- Initially, create the picker with no items:
+  local picker = M.create_picker {
+    multi = true,
+    items = {},
+
+    --- @params items string[]
+    on_finish = function(items)
+      pcall(vim.fn.jobstop, job_inf.id)
+
+      if #items == 0 then return end
+      if #items == 1 then
+        vim.cmd.edit(items[1])
+      else
+        -- populate quickfix:
+        vim.fn.setqflist(vim
+          .iter(items)
+          :map(
+            function(item)
+              return {
+                filename = item,
+                lnum = 1,
+                col = 1,
+              }
+            end
+          )
+          :totable())
+        vim.cmd.copen()
+      end
+    end,
+
+    mappings = {
+      ['<C-t>'] = function(sel)
+        sel.close()
+        --- @type string[]
+        local items = sel.get_selected_items()
+
+        -- open in new tab:
+        for _, item in ipairs(items) do
+          vim.cmd.tabnew(item)
+        end
+      end,
+
+      ['<C-v>'] = function(sel)
+        sel.close()
+        --- @type string[]
+        local items = sel.get_selected_items()
+
+        -- open in vertical split:
+        for _, item in ipairs(items) do
+          vim.cmd.vsplit(item)
+        end
+      end,
+
+      ['<C-s>'] = function(sel)
+        sel.close()
+        --- @type string[]
+        local items = sel.get_selected_items()
+
+        -- open in horizontal split:
+        for _, item in ipairs(items) do
+          vim.cmd.split(item)
+        end
+      end,
+    },
+  }
+
+  -- Kick off the process that lists the files. As lines come in, send them to
+  -- the picker:
+  job_inf.id = vim.fn.jobstart(cmd, {
+    --- @param data string[]
+    on_stdout = vim.schedule_wrap(function(_chanid, data, _name)
+      local lines = job_inf.proc_lines
+      local function set_lines_as_items_state()
+        picker.set_items(vim
+          .iter(lines)
+          :enumerate()
+          :filter(function(idx, item)
+            -- Filter out an incomplete last line:
+            local is_last_line = idx == #lines
+            if is_last_line and item == '' then return false end
+            return true
+          end)
+          :map(function(_, item) return item end)
+          :totable())
+      end
+
+      -- It's just not a good idea to process large lists with Lua. The default
+      -- limit is 10,000 items, and even crunching through this is iffy on a
+      -- fast laptop. Show a warning and truncate the list in this case.
+      if #lines >= opts.limit then
+        if not job_inf.notified_over_limit then
+          vim.notify(
+            'Picker list is too large (truncating list to ' .. opts.limit .. ' items)',
+            vim.log.levels.WARN
+          )
+          pcall(vim.fn.jobstop, job_inf.id)
+          job_inf.notified_over_limit = true
+        end
+        return
+      end
+
+      -- :help channel-lines
+
+      local eof = #data == 1 and data[1] == ''
+      if eof then set_lines_as_items_state() end
+
+      -- Complete the previous line:
+      if #lines > 0 then lines[#lines] = lines[#lines] .. table.remove(data, 1) end
+
+      for _, l in ipairs(data) do
+        table.insert(lines, l)
+      end
+
+      set_lines_as_items_state()
+    end),
+  })
+end -- }}}
+
+function M.buffers() -- {{{
+  local cwd = vim.fn.getcwd()
+  -- ensure that `cwd` ends with a trailing slash:
+  if cwd[#cwd] ~= '/' then cwd = cwd .. '/' end
+
+  --- @type { name: string; changed: number; bufnr: number }[]
+  local bufs = vim.fn.getbufinfo { buflisted = 1 }
+
+  M.create_picker {
+    multi = true,
+    items = bufs,
+
+    --- @param item { name: string; changed: number; bufnr: number }
+    format_item = function(item)
+      local item_name = item.name
+      if item_name == '' then item_name = '[No Name]' end
+      -- trim leading `cwd` from the buffer name:
+      if item_name:sub(1, #cwd) == cwd then item_name = item_name:sub(#cwd + 1) end
+
+      return TreeBuilder.new():put(item.changed == 1 and '[+] ' or '    '):put(item_name):tree()
+    end,
+
+    --- @params items { bufnr: number }[]
+    on_finish = function(items)
+      if #items == 0 then return end
+      if #items == 1 then
+        vim.cmd.buffer(items[1].bufnr)
+      else
+        -- populate quickfix:
+        vim.fn.setqflist(vim
+          .iter(items)
+          :map(
+            function(item)
+              return {
+                bufnr = item.bufnr,
+                filename = item.name,
+                lnum = 1,
+                col = 1,
+              }
+            end
+          )
+          :totable())
+        vim.cmd.copen()
+      end
+    end,
+
+    mappings = {
+      ['<C-t>'] = function(sel)
+        sel.close()
+        --- @type { bufnr: number }[]
+        local items = sel.get_selected_items()
+
+        -- open in new tab:
+        for _, item in ipairs(items) do
+          vim.cmd.tabnew()
+          vim.cmd.buffer(item.bufnr)
+        end
+      end,
+
+      ['<C-v>'] = function(sel)
+        sel.close()
+        --- @type { bufnr: number }[]
+        local items = sel.get_selected_items()
+
+        -- open in new vertial split:
+        for _, item in ipairs(items) do
+          vim.cmd.vsplit()
+          vim.cmd.buffer(item.bufnr)
+        end
+      end,
+
+      ['<C-s>'] = function(sel)
+        sel.close()
+        --- @type { bufnr: number }[]
+        local items = sel.get_selected_items()
+
+        -- open in horizontal split:
+        for _, item in ipairs(items) do
+          vim.cmd.split()
+          vim.cmd.buffer(item.bufnr)
+        end
+      end,
+
+      ['<C-x>'] = function(sel)
+        local selected_items = sel.get_selected_items()
+        for _, item in ipairs(selected_items) do
+          -- delete the buffer
+          vim.cmd.bdelete(item.bufnr)
+        end
+
+        sel.set_selected_indices {}
+        sel.set_items(
+          vim
+            .iter(sel.get_items())
+            :filter(function(item) return not vim.tbl_contains(selected_items, item) end)
+            :totable()
+        )
+      end,
+    },
+  }
+end -- }}}
+
+local IS_CODE_SYMBOL_RUNNING = false
+function M.lsp_code_symbols() -- {{{
+  if IS_CODE_SYMBOL_RUNNING then return end
+  IS_CODE_SYMBOL_RUNNING = true
+
+  -- Avoid callback-hell with a wizard-based "steps"-system. Define each "step"
+  -- sequentially in the code, and wire up the callbacks to call the next step:
+  -- a simple, yet powerful, and easy to understand pattern/approach.
+  local STEPS = {}
+
+  --- @param info vim.lsp.LocationOpts.OnList
+  function STEPS._1_on_symbols(info)
+    M.create_picker {
+      items = info.items,
+      --- @param item { text: string }
+      format_item = function(item)
+        local s = item.text:gsub('<', '&lt;')
+        return s
+      end,
+      on_finish = STEPS._2_on_symbol_picked,
+    }
+  end
+
+  --- @param items { filename: string, lnum: integer, col: integer }[]
+  function STEPS._2_on_symbol_picked(items)
+    if #items == 0 then return STEPS._finally() end
+
+    local item = items[1]
+
+    -- Jump to the file/buffer:
+    local buf = vim
+      .iter(vim.fn.getbufinfo { buflisted = 1 })
+      :find(function(b) return b.name == item.filename end)
+    if buf ~= nil then
+      vim.api.nvim_win_set_buf(0, buf.bufnr)
+    else
+      vim.cmd.edit(item.filename)
+    end
+
+    -- Jump to the specific location:
+    vim.api.nvim_win_set_cursor(0, { item.lnum, item.col - 1 })
+    vim.cmd.normal 'zz'
+
+    STEPS._finally()
+  end
+
+  function STEPS._finally() IS_CODE_SYMBOL_RUNNING = false end
+
+  -- Kick off the async operation:
+  vim.lsp.buf.document_symbol { on_list = STEPS._1_on_symbols }
+end -- }}}
+
+function M.setup()
+  utils.ucmd('Files', M.files)
+  utils.ucmd('Buffers', M.buffers)
+  utils.ucmd('Lspcodesymbols', M.lsp_code_symbols)
+end
+
+return M

examples/splitjoin.lua

@@ -4,9 +4,9 @@ local Range = require 'u.range'
 
 local M = {}
 
----@param bracket_range Range
----@param left string
----@param right string
+--- @param bracket_range u.Range
+--- @param left string
+--- @param right string
 local function split(bracket_range, left, right)
   local code = CodeWriter.from_pos(bracket_range.start)
   code:write_raw(left)
@@ -52,17 +52,21 @@ local function split(bracket_range, left, right)
   bracket_range:replace(code.lines)
 end
 
----@param bracket_range Range
----@param left string
----@param right string
+--- @param bracket_range u.Range
+--- @param left string
+--- @param right string
 local function join(bracket_range, left, right)
-  local inner_range = Range.new(bracket_range.start:must_next(), bracket_range.stop:must_next(-1), bracket_range.mode)
-  local newline = vim
-    .iter(inner_range:lines())
-    :map(function(l) return vim.trim(l) end)
-    :filter(function(l) return l ~= '' end)
-    :join ' '
-  bracket_range:replace { left .. newline .. right }
+  local inner_range = bracket_range:shrink(1)
+  if inner_range then
+    local newline = vim
+      .iter(inner_range:lines())
+      :map(function(l) return vim.trim(l) end)
+      :filter(function(l) return l ~= '' end)
+      :join ' '
+    bracket_range:replace { left .. newline .. right }
+  else
+    bracket_range:replace { left .. right }
+  end
 end
 
 local function splitjoin()
@@ -80,7 +84,7 @@ local function splitjoin()
 end
 
 function M.setup()
-  vim.keymap.set('n', 'gS', function() vim_repeat.run(splitjoin) end)
+  vim.keymap.set('n', 'gS', function() vim_repeat.run_repeatable(splitjoin) end)
 end
 
 return M

examples/surround.lua

@@ -1,12 +1,12 @@
 local vim_repeat = require 'u.repeat'
-local opkeymap = require 'u.opkeymap'
-local Pos = require 'u.pos'
 local Range = require 'u.range'
 local Buffer = require 'u.buffer'
 local CodeWriter = require 'u.codewriter'
 
 local M = {}
 
+local ESC = vim.api.nvim_replace_termcodes('<Esc>', true, false, true)
+
 local surrounds = {
   [')'] = { left = '(', right = ')' },
   ['('] = { left = '( ', right = ' )' },
@@ -21,8 +21,17 @@ local surrounds = {
   ['`'] = { left = '`', right = '`' },
 }
 
----@return { left: string; right: string }|nil
+--- @type { left: string; right: string } | nil
+local CACHED_BOUNDS = nil
+
+--- @return { left: string; right: string }|nil
 local function prompt_for_bounds()
+  if vim_repeat.is_repeating() then
+    -- If we are repeating, we don't want to prompt for bounds, because
+    -- we want to reuse the last bounds:
+    return CACHED_BOUNDS
+  end
+
   local cn = vim.fn.getchar()
   -- Check for non-printable characters:
   if type(cn) ~= 'number' or cn < 32 or cn > 126 then return end
@@ -36,15 +45,17 @@ local function prompt_for_bounds()
     vim.keymap.del('c', '>')
     local endtag = '</' .. tag:sub(2):match '[^ >]*' .. '>'
     -- selene: allow(global_usage)
-    return { left = tag, right = endtag }
+    CACHED_BOUNDS = { left = tag, right = endtag }
+    return CACHED_BOUNDS
   else
     -- Default surround:
-    return (surrounds)[c] or { left = c, right = c }
+    CACHED_BOUNDS = (surrounds)[c] or { left = c, right = c }
+    return CACHED_BOUNDS
   end
 end
 
----@param range Range
----@param bounds { left: string; right: string }
+--- @param range u.Range
+--- @param bounds { left: string; right: string }
 local function do_surround(range, bounds)
   local left = bounds.left
   local right = bounds.right
@@ -59,7 +70,7 @@ local function do_surround(range, bounds)
     range:replace(left .. range:text() .. right)
   elseif range.mode == 'V' then
     local buf = Buffer.current()
-    local cw = CodeWriter.from_line(buf:line0(range.start.lnum):text(), buf.buf)
+    local cw = CodeWriter.from_line(range.start:line(), buf.bufnr)
 
     -- write the left bound at the current indent level:
     cw:write(left)
@@ -86,97 +97,107 @@ local function do_surround(range, bounds)
   range.start:save_to_pos '.'
 end
 
+-- Add surround:
+--- @param ty 'line' | 'char' | 'block'
+function _G.MySurroundOpFunc(ty)
+  if ty == 'block' then
+    -- We won't handle block-selection:
+    return
+  end
+
+  local range = Range.from_op_func(ty)
+  local hl
+  if not vim_repeat.is_repeating() then hl = range:highlight('IncSearch', { priority = 999 }) end
+
+  local bounds = prompt_for_bounds()
+  if hl then hl.clear() end
+  if bounds == nil then return end
+
+  do_surround(range, bounds)
+end
+
 function M.setup()
   require('u.repeat').setup()
 
   -- Visual
-  vim.keymap.set('v', 'S', function()
-    local c = vim.fn.getcharstr()
+  vim.keymap.set('x', 'S', function()
     local range = Range.from_vtext()
-    local bounds = surrounds[c] or { left = c, right = c }
-    vim_repeat.run(function()
-      do_surround(range, bounds)
-      -- this is a visual mapping: end in normal mode:
-      vim.cmd { cmd = 'normal', args = { '' }, bang = true }
-    end)
+    local bounds = prompt_for_bounds()
+    if bounds == nil then return end
+
+    do_surround(range, bounds)
+    -- this is a visual mapping: end in normal mode:
+    vim.cmd.normal(ESC)
   end, { noremap = true, silent = true })
 
   -- Change
   vim.keymap.set('n', 'cs', function()
-    local from_cn = vim.fn.getchar()
+    local from_cn = vim.fn.getchar() --[[@as number]]
     -- Check for non-printable characters:
     if from_cn < 32 or from_cn > 126 then return end
-    local from_c = vim.fn.nr2char(from_cn)
-    local from = surrounds[from_c] or { left = from_c, right = from_c }
-    local function get_fresh_arange()
-      local arange = Range.from_text_object('a' .. from_c, { user_defined = true })
-      if arange == nil then return nil end
-      if from_c == 'q' then
-        from.left = arange.start:char()
-        from.right = arange.stop:char()
+
+    vim_repeat.run_repeatable(function()
+      local from_c = vim.fn.nr2char(from_cn)
+      local from = surrounds[from_c] or { left = from_c, right = from_c }
+      local function get_fresh_arange()
+        local arange = Range.from_motion('a' .. from_c, { user_defined = true })
+        if arange == nil then return end
+        if from_c == 'q' then
+          from.left = arange.start:char()
+          from.right = arange.stop:char()
+        end
+        return arange
       end
-      return arange
-    end
 
-    local arange = get_fresh_arange()
-    if arange == nil then return nil end
+      local arange = get_fresh_arange()
+      if arange == nil then return end
 
-    local hl_info1 = Range.new(arange.start, arange.start, 'v'):highlight('IncSearch', { priority = 999 })
-    local hl_info2 = Range.new(arange.stop, arange.stop, 'v'):highlight('IncSearch', { priority = 999 })
-    local hl_clear = function()
-      if hl_info1 then hl_info1.clear() end
-      if hl_info2 then hl_info2.clear() end
-    end
+      local hl_info1 = vim_repeat.is_repeating() and nil
+        or Range.new(arange.start, arange.start, 'v'):highlight('IncSearch', { priority = 999 })
+      local hl_info2 = vim_repeat.is_repeating() and nil
+        or Range.new(arange.stop, arange.stop, 'v'):highlight('IncSearch', { priority = 999 })
+      local hl_clear = function()
+        if hl_info1 then hl_info1.clear() end
+        if hl_info2 then hl_info2.clear() end
+      end
 
-    local to = prompt_for_bounds()
-    hl_clear()
-    if to == nil then return end
-
-    vim_repeat.run(function()
-      -- Re-fetch the arange, just in case this action is being repeated:
-      arange = get_fresh_arange()
-      if arange == nil then return nil end
+      local to = prompt_for_bounds()
+      hl_clear()
+      if to == nil then return end
 
       if from_c == 't' then
         -- For tags, we want to replace the inner text, not the tag:
-        local irange = Range.from_text_object('i' .. from_c, { user_defined = true })
-        if arange == nil or irange == nil then return nil end
+        local irange = Range.from_motion('i' .. from_c, { user_defined = true })
+        if arange == nil or irange == nil then return end
 
-        local lrange = Range.new(arange.start, irange.start:must_next(-1))
-        local rrange = Range.new(irange.stop:must_next(1), arange.stop)
+        local lrange, rrange = arange:difference(irange)
+        if not lrange or not rrange then return end
 
         rrange:replace(to.right)
         lrange:replace(to.left)
       else
         -- replace `from.right` with `to.right`:
-        local last_line = arange:line0(-1).text() --[[@as string]]
-        local from_right_match = last_line:match(vim.pesc(from.right) .. '$')
-        if from_right_match then
-          local match_start = arange.stop:clone()
-          match_start.col = match_start.col - #from_right_match + 1
-          Range.new(match_start, arange.stop):replace(to.right)
-        end
+        local right_text = arange:sub(-1, -#from.right)
+        right_text:replace(to.right)
 
         -- replace `from.left` with `to.left`:
-        local first_line = arange:line0(0).text() --[[@as string]]
-        local from_left_match = first_line:match('^' .. vim.pesc(from.left))
-        if from_left_match then
-          local match_end = arange.start:clone()
-          match_end.col = match_end.col + #from_left_match - 1
-          Range.new(arange.start, match_end):replace(to.left)
-        end
+        local left_text = arange:sub(1, #from.left)
+        left_text:replace(to.left)
       end
     end)
   end, { noremap = true, silent = true })
 
   -- Delete
+  local CACHED_DELETE_FROM = nil
   vim.keymap.set('n', 'ds', function()
-    local txt_obj = vim.fn.getcharstr()
-    vim_repeat.run(function()
+    vim_repeat.run_repeatable(function()
+      local txt_obj = vim_repeat.is_repeating() and CACHED_DELETE_FROM or vim.fn.getcharstr()
+      CACHED_DELETE_FROM = txt_obj
+
       local buf = Buffer.current()
-      local irange = Range.from_text_object('i' .. txt_obj)
-      local arange = Range.from_text_object('a' .. txt_obj)
-      if arange == nil or irange == nil then return nil end
+      local irange = Range.from_motion('i' .. txt_obj)
+      local arange = Range.from_motion('a' .. txt_obj)
+      if arange == nil or irange == nil then return end
       local starting_cursor_pos = arange.start:clone()
 
       -- Now, replace `arange` with the content of `irange`.  If `arange` was multiple lines,
@@ -187,28 +208,19 @@ function M.setup()
         -- Dedenting moves the cursor, so we need to set the cursor to a consistent starting spot:
         arange.start:save_to_pos '.'
         -- Dedenting also changed the inner text, so re-acquire it:
-        arange = Range.from_text_object('a' .. txt_obj)
-        irange = Range.from_text_object('i' .. txt_obj)
+        arange = Range.from_motion('a' .. txt_obj)
+        irange = Range.from_motion('i' .. txt_obj)
         if arange == nil or irange == nil then return end -- should never be true
         arange:replace(irange:lines())
-
-        local final_range = Range.new(
-          arange.start,
-          Pos.new(
-            arange.stop.buf,
-            irange.start.lnum + (arange.stop.lnum + arange.start.lnum),
-            arange.stop.col,
-            arange.stop.off
-          ),
-          irange.mode
-        )
+        -- `arange:replace(..)` updates its own `stop` position, so we will use
+        -- `arange` as the final resulting range that holds the modified text
 
         -- delete last line, if it is empty:
-        local last = buf:line0(final_range.stop.lnum)
+        local last = buf:line(arange.stop.lnum)
         if last:text():match '^%s*$' then last:replace(nil) end
 
         -- delete first line, if it is empty:
-        local first = buf:line0(final_range.start.lnum)
+        local first = buf:line(arange.start.lnum)
         if first:text():match '^%s*$' then first:replace(nil) end
       else
         -- trim start:
@@ -220,35 +232,10 @@ function M.setup()
     end)
   end, { noremap = true, silent = true })
 
-  opkeymap('n', 'ys', function(range)
-    local hl_info = range:highlight('IncSearch', { priority = 999 })
-
-    ---@type { left: string; right: string }
-    local bounds
-    -- selene: allow(global_usage)
-    if _G.my_surround_bounds ~= nil then
-      -- This command was repeated with `.`, we don't need
-      -- to prompt for the bounds:
-      -- selene: allow(global_usage)
-      bounds = _G.my_surround_bounds
-    else
-      local prompted_bounds = prompt_for_bounds()
-      if prompted_bounds == nil and hl_info then return hl_info.clear() end
-      if prompted_bounds then bounds = prompted_bounds end
-    end
-
-    if hl_info then hl_info.clear() end
-    do_surround(range, bounds)
-    -- selene: allow(global_usage)
-    _G.my_surround_bounds = nil
-
-    -- return repeatable injection
-    return function()
-      -- on_repeat, we "stage" the bounds that we were originally called with:
-      -- selene: allow(global_usage)
-      _G.my_surround_bounds = bounds
-    end
-  end)
+  vim.keymap.set('n', 'ys', function()
+    vim.o.operatorfunc = 'v:lua.MySurroundOpFunc'
+    return 'g@'
+  end, { expr = true })
 end
 
 return M

examples/text-objects.lua

@@ -1,4 +1,4 @@
-local utils = require 'u.utils'
+local txtobj = require 'u.txtobj'
 local Pos = require 'u.pos'
 local Range = require 'u.range'
 local Buffer = require 'u.buffer'
@@ -7,52 +7,33 @@ local M = {}
 
 function M.setup()
   -- Select whole file:
-  utils.define_text_object('ag', function() return Buffer.current():all() end)
+  txtobj.define('ag', function() return Buffer.current():all() end)
 
   -- Select current line:
-  utils.define_text_object('a.', function()
-    local lnum = Pos.from_pos('.').lnum
-    return Buffer.current():line0(lnum)
-  end)
+  txtobj.define('a.', function() return Buffer.current():line(Pos.from_pos('.').lnum) end)
 
   -- Select the nearest quote:
-  utils.define_text_object('aq', function() return Range.find_nearest_quotes() end)
-  utils.define_text_object('iq', function()
+  txtobj.define('aq', function() return Range.find_nearest_quotes() end)
+  txtobj.define('iq', function()
     local range = Range.find_nearest_quotes()
     if range == nil then return end
     return range:shrink(1)
   end)
 
   ---Selects the next quote object (searches forward)
-  ---@param q string
+  --- @param q string
   local function define_quote_obj(q)
-    local function select_around()
-      -- Operator mappings are effectively running in visual mode, the way
-      -- `define_text_object` is implemented, so feed the keys `a${q}` to vim
-      -- to select the appropriate text-object
-      vim.cmd { cmd = 'normal', args = { 'a' .. q }, bang = true }
+    local function select_around() return Range.from_motion('a' .. q) end
 
-      -- Now check on the visually selected text:
-      local range = Range.from_vtext()
-      if range:is_empty() then return range.start end
-      range.start = range.start:find_next(1, q) or range.start
-      range.stop = range.stop:find_next(-1, q) or range.stop
-      return range
-    end
+    txtobj.define('a' .. q, function() return select_around() end)
+    txtobj.define('i' .. q, function()
+      local range = select_around()
+      if range == nil or range:is_empty() then return range end
 
-    utils.define_text_object('a' .. q, function() return select_around() end)
-    utils.define_text_object('i' .. q, function()
-      local range_or_pos = select_around()
-      if Range.is(range_or_pos) then
-        local start_next = range_or_pos.start:next(1)
-        local stop_prev = range_or_pos.stop:next(-1)
-        if start_next > stop_prev then return start_next end
-
-        local range = range_or_pos:shrink(1)
-        return range
-      else
-        return range_or_pos
-      end
+      local start_next = range.start:next(1) or range.start
+      local stop_prev = range.stop:next(-1)
+      if start_next > stop_prev then return Range.new(start_next) end
+      return range:shrink(1) or range
     end)
   end
   define_quote_obj [["]]
@@ -60,36 +41,26 @@ function M.setup()
   define_quote_obj [[`]]
 
   ---Selects the "last" quote object (searches backward)
-  ---@param q string
+  --- @param q string
   local function define_last_quote_obj(q)
     local function select_around()
       local curr = Pos.from_pos('.'):find_next(-1, q)
       if not curr then return end
       -- Reset visual selection to current context:
-      Range.new(curr, curr):set_visual_selection()
-      vim.cmd.normal('a' .. q)
-      local range = Range.from_vtext()
-      if range:is_empty() then return range.start end
-      range.start = range.start:find_next(1, q) or range.start
-      range.stop = range.stop:find_next(-1, q) or range.stop
-      return range
+      curr:save_to_pos '.'
+      return Range.from_motion('a' .. q)
     end
 
-    utils.define_text_object('al' .. q, function() return select_around() end)
-    utils.define_text_object('il' .. q, function()
-      local range_or_pos = select_around()
-      if range_or_pos == nil then return end
+    txtobj.define('al' .. q, function() return select_around() end)
+    txtobj.define('il' .. q, function()
+      local range = select_around()
+      if range == nil or range:is_empty() then return range end
 
-      if Range.is(range_or_pos) then
-        local start_next = range_or_pos.start:next(1)
-        local stop_prev = range_or_pos.stop:next(-1)
-        if start_next > stop_prev then return start_next end
+      local start_next = range.start:next(1) or range.start
+      local stop_prev = range.stop:next(-1)
+      if start_next > stop_prev then return Range.new(start_next) end
 
-        local range = range_or_pos:shrink(1)
-        return range
-      else
-        return range_or_pos
-      end
+      return range:shrink(1) or range
     end)
   end
   define_last_quote_obj [["]]
@@ -111,8 +82,8 @@ function M.setup()
     local keybinds = { ... }
     table.insert(keybinds, b)
     for _, k in ipairs(keybinds) do
-      utils.define_text_object('al' .. k, function() return select_around() end)
-      utils.define_text_object('il' .. k, function()
+      txtobj.define('al' .. k, function() return select_around() end)
+      txtobj.define('il' .. k, function()
         local range = select_around()
         return range and range:shrink(1)
       end)