Added text insertion action to Cursorless public api (#1875)

Fixes #1754

## Checklist

- [x] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [x] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [/] I have not broken the cheatsheet

---------

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>

Author: AndreasArvidsson

cursorless-talon-dev/src/cursorless_test.talon

@@ -7,6 +7,10 @@ test api command <user.cursorless_target>:
     user.cursorless_command("setSelection", cursorless_target)
 test api command bring <user.cursorless_target>:
     user.cursorless_command("replaceWithTarget", cursorless_target)
+test api insert <user.word> <user.cursorless_destination>:
+    user.cursorless_insert(cursorless_destination, word)
+test api insert <user.word> and <user.word> <user.cursorless_destination>:
+    user.cursorless_insert(cursorless_destination, word_list)
 test api insert snippet:
     user.cursorless_insert_snippet("Hello, $foo!  My name is $bar!")
 test api insert snippet by name:

cursorless-talon/src/actions/actions.py

@@ -1,10 +1,17 @@
+from typing import Union
+
 from talon import Module, actions
 
-from ..targets.target_types import CursorlessTarget, ImplicitDestination
+from ..targets.target_types import (
+    CursorlessDestination,
+    CursorlessTarget,
+    ImplicitDestination,
+)
 from .bring_move import BringMoveTargets
 from .call import cursorless_call_action
 from .execute_command import cursorless_execute_command_action
 from .homophones import cursorless_homophones_action
+from .replace import cursorless_replace_action
 
 mod = Module()
 
@@ -111,6 +118,14 @@ def cursorless_ide_command(command_id: str, target: CursorlessTarget):
         """Perform ide command on cursorless target"""
         return cursorless_execute_command_action(command_id, target)
 
+    def cursorless_insert(
+        destination: CursorlessDestination, text: Union[str, list[str]]
+    ):
+        """Perform text insertion on Cursorless destination"""
+        if isinstance(text, str):
+            text = [text]
+        cursorless_replace_action(destination, text)
+
     def private_cursorless_action_or_ide_command(
         instruction: dict, target: CursorlessTarget
     ):

cursorless-talon/src/actions/homophones.py

@@ -1,5 +1,6 @@
 from talon import actions, app
 
+from ..targets.target_types import PrimitiveDestination
 from .get_text import cursorless_get_text_action
 from .replace import cursorless_replace_action
 
@@ -12,7 +13,8 @@ def cursorless_homophones_action(target: dict):
     except LookupError as e:
         app.notify(str(e))
         return
-    cursorless_replace_action(target, updated_texts)
+    destination = PrimitiveDestination("to", target)
+    cursorless_replace_action(destination, updated_texts)
 
 
 def get_next_homophone(word: str):

cursorless-talon/src/actions/reformat.py

@@ -1,6 +1,6 @@
 from talon import Module, actions
 
-from ..targets.target_types import CursorlessTarget
+from ..targets.target_types import CursorlessTarget, PrimitiveDestination
 from .get_text import cursorless_get_text_action
 from .replace import cursorless_replace_action
 
@@ -15,4 +15,5 @@ def private_cursorless_reformat(target: CursorlessTarget, formatters: str):
         """Execute Cursorless reformat action. Reformat target with formatter"""
         texts = cursorless_get_text_action(target, show_decorations=False)
         updated_texts = [actions.user.reformat_text(text, formatters) for text in texts]
-        cursorless_replace_action(target, updated_texts)
+        destination = PrimitiveDestination("to", target)
+        cursorless_replace_action(destination, updated_texts)

cursorless-talon/src/actions/replace.py

@@ -1,14 +1,16 @@
 from talon import actions
 
-from ..targets.target_types import CursorlessTarget, PrimitiveDestination
+from ..targets.target_types import CursorlessDestination
 
 
-def cursorless_replace_action(target: CursorlessTarget, replace_with: list[str]):
+def cursorless_replace_action(
+    destination: CursorlessDestination, replace_with: list[str]
+):
     """Execute Cursorless replace action. Replace targets with texts"""
     actions.user.private_cursorless_command_and_wait(
         {
             "name": "replace",
             "replaceWith": replace_with,
-            "destination": PrimitiveDestination("to", target),
+            "destination": destination,
         }
     )

docs/user/customization.md

@@ -118,6 +118,9 @@ Cursorless exposes a couple talon actions and captures that you can use to defin
 - `user.cursorless_ide_command(command_id: str, target: cursorless_target)`:
   Performs a built-in IDE command on the given target
   eg: `user.cursorless_ide_command("editor.action.addCommentLine", cursorless_target)`
+- `user.cursorless_insert(destination: CursorlessDestination, text: Union[str, List[str]])`:
+  Insert text at destination.
+  eg: `user.cursorless_insert(cursorless_destination, "hello")`
 
 #### Snippet actions
 

packages/cursorless-engine/src/test/fixtures/talonApi.fixture.ts

@@ -1,4 +1,7 @@
-import { ActionDescriptor } from "@cursorless/common";
+import {
+  ActionDescriptor,
+  PartialPrimitiveTargetDescriptor,
+} from "@cursorless/common";
 import { spokenFormTest } from "./spokenFormTest";
 
 // See cursorless-talon-dev/src/cursorless_test.talon
@@ -11,11 +14,29 @@ const setSelectionAction: ActionDescriptor = {
 };
 const replaceWithTargetAction: ActionDescriptor = {
   name: "replaceWithTarget",
-  source: {
+  source: decoratedPrimitiveTarget("a"),
+  destination: { type: "implicit" },
+};
+const insertSingleWordTargetAction: ActionDescriptor = {
+  name: "replace",
+  destination: {
     type: "primitive",
-    mark: { type: "decoratedSymbol", symbolColor: "default", character: "a" },
+    insertionMode: "to",
+    target: decoratedPrimitiveTarget("a"),
   },
-  destination: { type: "implicit" },
+  replaceWith: ["hello"],
+};
+const insertMultipleWordsTargetAction: ActionDescriptor = {
+  name: "replace",
+  destination: {
+    type: "primitive",
+    insertionMode: "after",
+    target: {
+      type: "list",
+      elements: [decoratedPrimitiveTarget("a"), decoratedPrimitiveTarget("b")],
+    },
+  },
+  replaceWith: ["hello", "world"],
 };
 const insertSnippetAction: ActionDescriptor = {
   name: "insertSnippet",
@@ -66,6 +87,11 @@ const wrapWithSnippetByNameAction: ActionDescriptor = {
 export const talonApiFixture = [
   spokenFormTest("test api command this", setSelectionAction),
   spokenFormTest("test api command bring air", replaceWithTargetAction),
+  spokenFormTest("test api insert hello to air", insertSingleWordTargetAction),
+  spokenFormTest(
+    "test api insert hello and world after air and bat",
+    insertMultipleWordsTargetAction,
+  ),
   spokenFormTest("test api insert snippet", insertSnippetAction),
   spokenFormTest("test api insert snippet by name", insertSnippetByNameAction),
   spokenFormTest("test api wrap with snippet this", wrapWithSnippetAction),
@@ -74,3 +100,12 @@ export const talonApiFixture = [
     wrapWithSnippetByNameAction,
   ),
 ];
+
+function decoratedPrimitiveTarget(
+  character: string,
+): PartialPrimitiveTargetDescriptor {
+  return {
+    type: "primitive",
+    mark: { type: "decoratedSymbol", symbolColor: "default", character },
+  };
+}