Merge pull request #155 from FluxxField/feat/surround-textobjects

feat: surround operations, textobject registry, and target expansion

Author: FluxxField

README.md

@@ -28,6 +28,7 @@ A motion framework for Neovim. Enable a motion, enable an operator. They compose
       yank = true,         -- y + any motion
       change = true,       -- c + any motion
       treesitter = true,   -- ]], [[, af, if, ac, ic, aa, ia, fn, saa, gS, R
+      surround = true,     -- ds, cs, ys, gza, gzp, visual S + i(/a(/di"/dsq/dst/dsf/etc.
       diagnostics = true,  -- ]d, [d, ]e, [e
       misc = true,         -- . g. g1-g9 gp gP gA-gZ gmd gmy (repeat, history, pins, multi-cursor)
     },
@@ -63,7 +64,7 @@ presets = {
 Enable `words` and `delete` as presets. Now `dw`, `db`, `de`, `dge` all work. Enable `search` and `ds`, `dS`, `df`, `dt` work too. Enable `lines` and you get `dj`, `dk`. Every motion preset **multiplies** with every operator preset:
 
 ```
-11 composable motions  ×  5 operators  =  55+ compositions
+11 composable motions  ×  5 operators  =  55+ compositions  (+ surround operators)
          from 16 keys, zero mappings defined
 ```
 
@@ -92,6 +93,39 @@ yaa   yank an argument        =if   indent a function body
 cic   change inside a class   >ac   indent a class
 ```
 
+### Surround with labeled targets
+
+SmartMotion replaces nvim-surround with something better: **every pair on screen gets a label.**
+
+```
+ds(   → labels appear on every () pair → pick one → delimiters deleted
+cs(   → labels appear → pick one → delimiters highlight → type replacement
+ysaw( → word labels appear → pick one → word wrapped with ( )
+dsq   → labels on all quotes ("/'/`) → pick one → quotes deleted
+dst   → labels on all HTML/XML tags → pick one → tags removed
+dsf   → labels on all function calls → pick one → unwrapped
+cst   → labels on tags → pick one → tag name deleted → insert mode with live sync
+csf   → labels on calls → pick one → name deleted → insert mode at name position
+```
+
+`di(`, `da{`, `ci"`, `vi[` all show labels on every matching pair visible. No cursor proximity guessing — you pick exactly which pair you mean. `q` matches any quote type. `t` matches HTML/XML tags. `f` targets function calls for surround operations (while `dif`/`daf` still act on function bodies).
+
+Opening chars add padding (`ysaw(` → `( word )`), closing chars don't (`ysaw)` → `(word)`). Visual mode `S` wraps a selection. `gza` is a quick "wrap this word" shortcut.
+
+### Expand your target with `+` / `-`
+
+After picking a target, press `+` to grow the selection forward or `-` to grow backward. Dim hints show you what's expandable:
+
+```
+ysaw  [word labels] → pick "foo"
+      "foo" highlights, dim + on next word, dim - on previous
+  +   → range grows to "foo bar"
+  +   → range grows to "foo bar baz"
+  (   → wraps as ( foo bar baz )
+```
+
+No other motion plugin does this. `BS` undoes the last expansion. Any non-expansion key (like the delimiter) confirms and executes. Zero friction when you don't need it — just type the delimiter immediately.
+
 ### Modify the search mid-selection
 
 Other motion plugins lock you in once labels appear. SmartMotion lets you change the search context without cancelling:
@@ -181,7 +215,7 @@ Press an operator, then any motion key. Labels appear, pick a target, action run
 | Combo | What it does |
 |-------|-------------|
 | `dw`  | Labels words after cursor → pick one → delete it |
-| `ds`  | Live search → pick match → delete it |
+| `ds`  | Live search → pick match → delete it (without surround preset) |
 | `df`  | 2-char find → delete from cursor to target (inclusive) |
 | `dt`  | 2-char till → delete from cursor to just before target |
 | `dd`  | Delete current line |
@@ -287,6 +321,59 @@ Works best with [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim). Mul
 
 </details>
 
+<details>
+<summary><b>Surround</b>: <code>ds</code> <code>cs</code> <code>ys</code> <code>gza</code> <code>gzp</code> <code>S</code> + pair text objects + <code>q</code> <code>t</code> <code>f</code></summary>
+
+**Pair text objects** (work with ANY operator: `di(`, `ya{`, `ci"`, `>a[`):
+
+| Key   | Mode    | Description                          |
+|-------|---------|--------------------------------------|
+| `i(`  | x, o    | Inside parentheses                   |
+| `a(`  | x, o    | Around parentheses                   |
+| `i{`  | x, o    | Inside braces                        |
+| `a{`  | x, o    | Around braces                        |
+| `i[`  | x, o    | Inside brackets                      |
+| `a[`  | x, o    | Around brackets                      |
+| `i<`  | x, o    | Inside angle brackets                |
+| `a<`  | x, o    | Around angle brackets                |
+| `i"`  | x, o    | Inside double quotes                 |
+| `a"`  | x, o    | Around double quotes                 |
+| `i'`  | x, o    | Inside single quotes                 |
+| `a'`  | x, o    | Around single quotes                 |
+| `iq`  | x, o    | Inside nearest quote (any type)      |
+| `aq`  | x, o    | Around nearest quote (any type)      |
+| `it`  | x, o    | Inside HTML/XML tag                  |
+| `at`  | x, o    | Around HTML/XML tag                  |
+
+Closing chars work too: `di)` = `di(`, `da}` = `da{`, etc.
+
+**Surround operators**:
+
+| Key   | Mode | Description                                          |
+|-------|------|------------------------------------------------------|
+| `ds(` | n    | Delete surrounding parens (leaves content)           |
+| `cs(` | n    | Change surrounding parens (prompts for replacement)  |
+| `dsq` | n    | Delete nearest surrounding quote (any type)          |
+| `csq` | n    | Change nearest quote to something else               |
+| `dst` | n    | Delete surrounding HTML/XML tag                      |
+| `cst` | n    | Change surrounding tag (in-place, live multi-cursor) |
+| `dsf` | n    | Unwrap function call: `print(x)` → `x`              |
+| `csf` | n    | Change function name (in-place insert mode)          |
+| `ys`  | n    | Add surround: `ysaw(` = wrap word with parens        |
+| `gza` | n    | Quick surround: word hints → pick → type delimiter   |
+| `gzp` | n    | Paste surround: wrap with previously yanked pair     |
+| `S`   | x    | Surround visual selection (type delimiter to wrap)   |
+
+**Padding**: opening chars add spaces (`ysaw(` → `( word )`), closing chars don't (`ysaw)` → `(word)`). Configure with `surround_pad`.
+
+Unlike native text objects, SmartMotion pair text objects label ALL matching pairs on screen. `di(` shows hints on every `()` pair visible, pick the one you want.
+
+**Special surround types**: `t` prompts for a tag name (`ysiw t` → "Tag: " → type `div` → `<div>word</div>`). `f` prompts for a function name. `q` matches all three quote types at once. `cst` and `csf` use in-place editing instead of prompts -- see below.
+
+**Target expansion**: After picking a target with `ys` or `gza`, press `+` to grow forward, `-` to grow backward, `BS` to shrink. Wrap multiple words in one go: `ysaw` → pick → `++` → `(` → `( three words here )`.
+
+</details>
+
 <details>
 <summary><b>Misc</b>: repeat, history, pins, global pins, multi-cursor</summary>
 
@@ -369,6 +456,7 @@ With all presets enabled, SmartMotion consolidates:
 
 ```
 flash.nvim          →  search, treesitter, labels
+nvim-surround       →  ds, cs, ys, visual S + pair text objects + tags + function calls
 harpoon             →  pins (g1-g9, gp) + history (g.)
 nvim-treesitter-    →  af/if/ac/ic/aa/ia text objects
   textobjects
@@ -392,6 +480,9 @@ One plugin, one config. Your pins know about your history. Your text objects wor
 | Fuzzy search | | | | yes |
 | Treesitter navigation | | | yes | yes |
 | Treesitter text objects | | | | yes |
+| Surround (ds/cs/ys) | | | | yes |
+| Pair text objects (di(/a{) | | | | yes |
+| Target expansion (+/-) | | | | yes |
 | Composable d/y/c/p | | | partial | full |
 | Remote operations | | | yes | yes |
 | Multi-window | | via plugin | yes | yes |
@@ -436,6 +527,12 @@ SmartMotion wouldn't exist without these plugins. See [Why SmartMotion](https://
   max_pins = 9,                      -- maximum pin slots
   search_timeout_ms = 500,           -- auto-proceed after typing in search
   search_idle_timeout_ms = 2000,     -- exit search with no input
+  surround_pad = "opening",          -- "opening", "closing", or false
+  expansion_keys = {                  -- keys for target expansion (+ grows, - shrinks)
+    ["+"] = "expand_forward",
+    ["-"] = "expand_backward",
+    ["<BS>"] = "shrink",
+  },
   yank_highlight_duration = 150,     -- yank flash duration (ms)
   history_max_age_days = 30,         -- prune history entries older than this
   selection_keys = {                  -- key-action map during label selection

ROADMAP.md

@@ -65,3 +65,15 @@
 - Jump to Git Conflicts.
 - Search & Replace with Hints.
 - History review with labels.
+
+---
+
+## Phase 7: Surround & Text Objects (v1.3.0+)
+
+### Completed
+- ✅ Textobject registry (separate from composable motions, same key can exist in both)
+- ✅ Pair text objects (`i`/`a` + delimiter: parentheses, brackets, braces, quotes, tags)
+- ✅ Surround operators (`ds`, `cs`, `ys` — delete, change, add surrounding pairs)
+- ✅ Standalone surround (`gza` add surround, `gzp` paste surround, visual `S`)
+- ✅ Pattern-based pair detection fallback (works without treesitter)
+- ✅ Configurable padding (`surround_pad`)

docs/API-Reference.md

@@ -7,6 +7,7 @@ Complete reference for SmartMotion modules and data structures.
 ## Table of Contents
 
 - [Motion Registration](#motion-registration)
+- [Textobject Registration](#textobject-registration)
 - [Built-in Modules](#built-in-modules)
 - [Motion State](#motion-state)
 - [Context Object](#context-object)
@@ -113,6 +114,124 @@ require("smart-motion").map_motion("w")
 
 ---
 
+## Textobject Registration
+
+Text objects (`i`/`a` prefix) live in a separate registry from composable motions. The same key can exist in both registries (`f` composable = 2-char find, `f` textobject = function) because they are consulted in different contexts.
+
+### register
+
+```lua
+require("smart-motion").textobjects.register(key, entry)
+```
+
+Register a single textobject.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | string | Textobject key (e.g., `"("`, `"f"`, `"c"`) |
+| `entry` | table | Textobject entry |
+
+### register_many
+
+```lua
+require("smart-motion").textobjects.register_many(table)
+```
+
+Register multiple textobjects at once:
+
+```lua
+require("smart-motion").textobjects.register_many({
+  ["("] = { ... },
+  ["["] = { ... },
+  f = { ... },
+})
+```
+
+### get
+
+```lua
+require("smart-motion").textobjects.get(key)
+```
+
+Returns the textobject entry for `key`, or `nil` if not registered.
+
+### has
+
+```lua
+require("smart-motion").textobjects.has(key)
+```
+
+Returns `true` if a textobject is registered for `key`.
+
+### Entry Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `collector` | string | Yes | Collector module name |
+| `extractor` | string | Yes | Extractor module name |
+| `modifier` | string | No | Modifier module name |
+| `filter` | string | No | Filter module name |
+| `visualizer` | string | No | Visualizer module name |
+| `metadata` | table | No | Additional metadata |
+| `inside` | table | No | `motion_state` overrides merged when the `i` prefix is used |
+| `around` | table | No | `motion_state` overrides merged when the `a` prefix is used |
+| `surround` | table | No | `motion_state` overrides merged for surround operators (`ds`, `cs`) |
+| `default` | string | No | Which prefix to use when none is specified (`"inside"` or `"around"`) |
+
+The `inside`, `around`, and `surround` fields are plain `motion_state` fragments. When the user types a prefix (`i`, `a`, or a surround operator), the corresponding fragment is merged into `motion_state` before the pipeline runs.
+
+### Prefix Overrides (`_collector_override` / `_extractor_override`)
+
+A textobject's `inside`, `around`, or `surround` fragments can include `_collector_override` and `_extractor_override` fields. When present, these swap the textobject's collector and/or extractor for that prefix only. This allows a single textobject key to use completely different pipeline modules depending on whether it's accessed via `i`/`a` or via surround operators.
+
+**Example:** The `f` textobject uses `treesitter` collector for `dif`/`daf` (function bodies) but swaps to `function_calls` collector for `dsf`/`csf` (function call expressions):
+
+```lua
+f = {
+    collector = "treesitter",       -- default: function definitions
+    extractor = "pass_through",
+    -- ...
+    inside = { ts_inner_body = true },
+    around = {},
+    surround = {
+        _collector_override = "function_calls",  -- swap collector for surround
+        _extractor_override = "pairs",           -- swap extractor for surround
+        pair_scope = "surround",
+        is_surround = true,
+    },
+}
+```
+
+This pattern is useful when the same conceptual textobject key (`f` for "function") should behave differently in different contexts.
+
+### Example
+
+```lua
+-- Register a custom pair textobject
+require("smart-motion").textobjects.register("(", {
+  collector = "pairs",
+  extractor = "pairs",
+  visualizer = "hint_start",
+  inside = { pair_scope = "inside" },
+  around = { pair_scope = "around" },
+  surround = { pair_scope = "surround", is_surround = true },
+  default = "around",
+  metadata = {
+    label = "Parentheses",
+    open = "(",
+    close = ")",
+  },
+})
+
+-- Now di( deletes inside parens, da( deletes around parens,
+-- ds( deletes the surrounding parens, cs( changes the surrounding parens.
+-- All show hint labels so you can pick which pair to act on.
+```
+
+---
+
 ## Built-in Modules
 
 ### Collectors
@@ -121,6 +240,9 @@ require("smart-motion").map_motion("w")
 |------|-------------|
 | `lines` | All buffer lines |
 | `treesitter` | Syntax nodes (see Treesitter modes below) |
+| `pairs` | Matching delimiter pairs (treesitter + pattern fallback) |
+| `tags` | HTML/XML tag pairs (treesitter + pattern fallback) |
+| `function_calls` | Function call expressions (treesitter + pattern fallback) |
 | `diagnostics` | LSP diagnostics |
 | `git_hunks` | Git changed regions |
 | `quickfix` | Quickfix/location list entries |
@@ -145,6 +267,7 @@ require("smart-motion").map_motion("w")
 | `text_search_2_char_until` | Two char, exclude target (till) |
 | `live_search` | Incremental search |
 | `fuzzy_search` | Fuzzy matching |
+| `pairs` | Delimiter pair extraction (open/close ranges) |
 | `pass_through` | Collector output unchanged |
 
 ### Modifiers