@webcoder49/code-input 2.1.0 → 2.5.0

package/CONTRIBUTING.md

@@ -6,7 +6,15 @@
 * The `code-input` element should be easy to use with all popular syntax-highlighting libraries.
 * Any modifications of `code-input` that would be useful for the open-source community but are not core to this functionality should be available as optional plugins in the `plugins` folder. Here's where most feature contributions will go.
 
-To keep this community productive and enjoyable, please [don't break the code of conduct here](https://github.com/WebCoder49/code-input/blob/main/CODE_OF_CONDUCT.md).
+We will generally *not* consider the following contributions:
+* Excess functionality and/or complexity in the main code-input files - these types of contributions should go in the plugin folder instead.
+* Issues that have been closed as not planned in the past (you can search the issue list to check), unless you bring a change that overcomes the reason they were not planned.
+
+This said, if you're not sure whether your change will be accepted, please ask in an issue.
+
+---
+
+To keep this community productive and enjoyable, please [don't break our code of conduct](https://github.com/WebCoder49/code-input/blob/main/CODE_OF_CONDUCT.md).
 
 ---
 # Ways you could contribute:
@@ -22,4 +30,6 @@ Firstly, thank you for doing this! This is probably the most time consuming way
 
 Please first open an issue if one doesn't already exist, and assign yourself to it. Then, [make a fork of the repo and submit a pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
 
+In the pull request, include the code updates for your feature / bug, and if you're adding a new feature make sure you comment your code so it's understandable to future contributors, and if you can, add unit tests for it in tests/tester.js. If you have any questions, just let me (@WebCoder49) know! 
+
 If an issue is open but already assigned to someone, it is probably already being worked on - you could still suggest a method of fixing it in the comments but shouldn't open a pull request as it would waste your time.

package/README.md

@@ -2,9 +2,9 @@
 
 ![Click to Switch](https://img.shields.io/static/v1?label=&message=Click%20to%20Switch:%20&color=grey&style=for-the-badge)[![GitHub](https://img.shields.io/static/v1?label=&message=GitHub&color=navy&style=for-the-badge&logo=github)](https://github.com/WebCoder49/code-input)[![NPM](https://img.shields.io/static/v1?label=&message=NPM&color=red&style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@webcoder49/code-input)
 
-[![View License](https://img.shields.io/github/license/webcoder49/code-input?style=for-the-badge)](LICENSE) [![View Releases](https://img.sHields.io/github/v/release/webcoder49/code-input?style=for-the-badge)](https://github.com/WebCoder49/code-input/releases) [![View the demo on CodePen](https://img.shields.io/static/v1?label=Demo&message=on%20CodePen&color=orange&logo=codepen&style=for-the-badge)](https://codepen.io/WebCoder49/details/jOypJOx)
+[![View License](https://img.shields.io/github/license/webcoder49/code-input?style=for-the-badge)](LICENSE) [![View Releases](https://img.sHields.io/github/v/release/webcoder49/code-input?style=for-the-badge)](https://github.com/WebCoder49/code-input/releases) [![View the demo on CodePen](https://img.shields.io/static/v1?label=Demo&message=on%20CodePen&color=orange&logo=codepen&style=for-the-badge)](https://codepen.io/WebCoder49/full/jOypJOx)
 
-> ___Fully customisable, editable syntax-highlighted textareas that can be placed in any HTML form.___ [[🚀 View the Demo](https://codepen.io/WebCoder49/details/jOypJOx)]
+> ___Fully customisable, editable syntax-highlighted textareas that can be placed in any HTML form.___ [[🚀 View the Demo](https://codepen.io/WebCoder49/full/jOypJOx)]
 
 ![Using code-input with many different themes](https://user-images.githubusercontent.com/69071853/133924472-05edde5c-23e7-4350-a41b-5a74d2dc1a9a.gif)
 *This demonstration uses themes from [Prism.js](https://prismjs.com/) and [highlight.js](https://highlightjs.org/), two syntax-highlighting programs which work well with and have compatibility built-in with code-input.*
@@ -15,7 +15,7 @@
 ---
 
 ## What does it do?
-**`code-input`** lets you **turn any ordinary JavaScript syntax-highlighting theme and program into customisable syntax-highlighted textareas** using an HTML custom element. It uses vanilla CSS to superimpose a `textarea` on a `pre code` block, then handles indentations, scrolling and fixes any resulting bugs with JavaScript. To see how it works in more detail, please see [this CSS-Tricks article](https://css-tricks.com/creating-an-editable-textarea-that-supports-syntax-highlighted-code/ "Creating an Editable Textarea That Supports Syntax-Highlighted Code") I wrote.
+**`code-input`** lets you **turn any ordinary JavaScript syntax-highlighting theme and program into customisable syntax-highlighted textareas** using an HTML custom element. It uses vanilla CSS to superimpose a `textarea` on a `pre code` block, then handles indentations, scrolling and fixes any resulting bugs with JavaScript. To see how it works behind the scenes (not how to use this library), please see [this CSS-Tricks article](https://css-tricks.com/creating-an-editable-textarea-that-supports-syntax-highlighted-code/ "Creating an Editable Textarea That Supports Syntax-Highlighted Code") I wrote.
 
 ## What are the advantages of using code-input, and what can it be used for?
 Unlike other front-end code-editor projects, the simplicity of how `code-input` works means it is **highly customisable**. As it is not a full-featured editor, you can **choose what features you want it to include, and use your favourite syntax-highlighting algorithms and themes**.
@@ -28,6 +28,8 @@ The `<code-input>` element works like a `<textarea>` and therefore **works in HT
 
 ## [`code-input` also supports TypeScript (click)](https://github.com/WebCoder49/code-input-for-typescript)
 
+**You can follow the instructions below, or use the starter code available [here for highlight.js](https://codepen.io/WebCoder49/pen/vYMpMoJ?editors=1100) and [here for Prism.js](https://codepen.io/WebCoder49/pen/ExzNRyb?editors=1100).**
+
 `code-input` is designed to be **both easy to use and customisable**. Here's how to use it to create syntax-highlighted textareas: 
 
 ### 1. Import `code-input`
@@ -52,8 +54,8 @@ From JSDelivr CDN (click)
 
 ```html
 <!--In the <head>-->
-<script src="https://cdn.jsdelivr.net/gh/WebCoder49/code-input@2.0/code-input.min.js"></script>
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/WebCoder49/code-input@2.0/code-input.min.css">
+<script src="https://cdn.jsdelivr.net/gh/WebCoder49/code-input@2.5/code-input.min.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/WebCoder49/code-input@2.5/code-input.min.css">
 ```
 </details>
 
@@ -76,9 +78,18 @@ The next step is to set up a `template` to link `code-input` to your syntax-high
     function(result_element) { /* Highlight function - with `pre code` code element */
       /* Highlight code in result_element - code is already escaped so it doesn't become HTML */
     },
-    true, /* Optional - Is the `pre` element styled as well as the `code` element? Changing this to false uses the code element as the scrollable one rather than the pre element */
-    true, /* Optional - This is used for editing code - setting this to true sets the `code` element's class to `language-<the code-input's lang attribute>` */
-    false /* Optional - Setting this to true passes the `<code-input>` element as a second argument to the highlight function to be used for getting data- attribute values and using the DOM for the code-input */,
+
+    true, /* Optional - Is the `pre` element styled as well as the `code` element?
+           * Changing this to false uses the code element as the scrollable one rather
+           * than the pre element */
+          
+    true, /* Optional - This is used for editing code - setting this to true sets the `code`
+           * element's class to `language-<the code-input's lang attribute>` */
+
+    false /* Optional - Setting this to true passes the `<code-input>` element as a second
+           * argument to the highlight function to be used for getting data- attribute values
+           * and using the DOM for the code-input */,
+
     [] // Array of plugins (see below)
   ));
   ```
@@ -106,18 +117,22 @@ The next step is to set up a `template` to link `code-input` to your syntax-high
 </script>
 ```
 
+> ⚠️ Unfortunately placing multiple plugins of the same type in a template can currently cause errors and undefined behaviour, even if such a configuration makes logical sense. [This is issue #118](https://github.com/WebCoder49/code-input/issues/118) and will be fixed as soon as possible - if you'd like to help and have the time you're welcome, but it's also at the top of the maintainer's To-Do list.
+
 To see a full list of plugins and their functions, please see [plugins/README.md](./plugins/README.md).
 
 ### 4. Using the component
-Now that you have registered a template, you can use the custom `<code-input>` element in HTML. If you have more than one template registered, you need to add the template name as the `template` attribute. With the element, using the `lang` attribute will add a `language-{value}` class to the `pre code` block. You can now use HTML attributes and events to make your element as simple or interactive as you like! 
+Now that you have registered a template, you can use the custom `<code-input>` element in HTML. If you have more than one template registered, you need to add the template name as the `template` attribute. With the element, using the `language` attribute will add a `language-{value}` class to the `pre code` block. You can now use HTML attributes and events, as well as CSS styles, to make your element as simple or interactive as you like, as if it were a `textarea` element! 
   ```HTML
-  <code-input lang="HTML"></code-input>
+  <code-input language="HTML"></code-input>
   ```
   *or*
   ```HTML
-  <code-input lang="HTML" placeholder="Type code here" template="syntax-highlighted" onchange="console.log('Your code is', this.value)">&lt; href='https://github.com/WebCoder49/code-input'>code-input&lt;/a></code-input>
+  <code-input language="HTML" placeholder="Type code here" template="syntax-highlighted" onchange="console.log('Your code is', this.value)">&lt; href='https://github.com/WebCoder49/code-input'>code-input&lt;/a></code-input>
   ```
 
+> ⚠️ At the moment, you need to set the `--padding` property rather than `padding` for a `code-input` element's CSS. All other properties should work as normal.
+
 ## Contributing
 If you have any features you would like to add to `code-input` as plugins or core functionality, or have found any bugs, please [open an issue](https://github.com/WebCoder49/code-input/issues) or [fork and submit a pull request](https://github.com/WebCoder49/code-input/fork)! All contributions to this open-source project will be greatly appreciated. You can see [more info in our `CONTRIBUTING.md` file](CONTRIBUTING.md).
 

package/code-input.css

@@ -4,26 +4,33 @@
 
 
 code-input {
-  /* Allow other elems to be inside */
+  /* Allow other elements to be inside */
+  display: block;
+  overflow-y: auto;
+  overflow-x: auto;
   position: relative;
   top: 0;
   left: 0;
-  display: block;
-  /* Only scroll inside elems */
-  overflow: hidden;
 
   /* Normal inline styles */
   margin: 8px;
   --padding: 16px;
   height: 250px;
-
-  font-size: normal;
+  font-size: inherit;
   font-family: monospace;
   line-height: 1.5; /* Inherited to child elements */
   tab-size: 2;
   caret-color: darkgrey;
   white-space: pre;
-  padding: 0!important; /* Use --padding */
+  padding: 0!important; /* Use --padding to set the code-input element's padding */
+  display: grid;
+  grid-template-columns: 100%;
+  grid-template-rows: 100%;
+}
+
+
+code-input:not(.code-input_loaded) {
+  padding: var(--padding, 16px)!important;
 }
 
 code-input textarea, code-input:not(.code-input_pre-element-styled) pre code, code-input.code-input_pre-element-styled pre {
@@ -31,15 +38,18 @@ code-input textarea, code-input:not(.code-input_pre-element-styled) pre code, co
   margin: 0px!important;
   padding: var(--padding, 16px)!important;
   border: 0;
-  width: calc(100% - var(--padding, 16px) * 2);
-  height: calc(100% - var(--padding, 16px) * 2);
+  min-width: calc(100% - var(--padding) * 2);
+  min-height: calc(100% - var(--padding) * 2);
+  overflow: hidden;
+  resize: none;
+  grid-row: 1;
+  grid-column: 1;
+  display: block;
 }
 
-code-input:not(.code-input_loaded) {
-  margin: 0px!important;
-  margin-bottom: calc(-1 * var(--padding, 16px))!important;
-  padding: var(--padding, 16px)!important;
-  border: 0;
+code-input:not(.code-input_pre-element-styled) pre code, code-input.code-input_pre-element-styled pre {
+  height: max-content;
+  width: max-content;
 }
 
 code-input:not(.code-input_pre-element-styled) pre, code-input.code-input_pre-element-styled pre code {
@@ -56,17 +66,29 @@ code-input textarea, code-input pre, code-input pre * {
   font-family: inherit!important;
   line-height: inherit!important;
   tab-size: inherit!important;
+  text-align: inherit!important;
+}
+
+/* Make changing the text direction propogate */
+code-input textarea[dir=auto] + pre {
+  unicode-bidi: plaintext;
+}
+
+code-input textarea[dir=ltr] + pre {
+  direction: ltr;
+}
+
+code-input textarea[dir=rtl] + pre {
+  direction: rtl;
 }
 
 
 code-input textarea, code-input pre {
   /* In the same place */
-  position: absolute;
-  top: 0;
-  left: 0;
+  grid-column: 1;
+  grid-row: 1;
 }
 
-
 /* Move the textarea in front of the result */
 
 code-input textarea {
@@ -76,13 +98,6 @@ code-input pre {
   z-index: 0;
 }
 
-code-input:not(.code-input_loaded) pre, code-input:not(.code-input_loaded) textarea {
-  opacity: 0;
-}
-code-input:not(.code-input_loaded)::after {
-  color: #ccc;
-}
-
 /* Make textarea almost completely transparent, except for caret and placeholder */
 
 code-input textarea {
@@ -96,23 +111,105 @@ code-input textarea::placeholder {
 
 /* Can be scrolled */
 code-input textarea, code-input pre {
-  overflow: auto!important;
-
   white-space: inherit;
   word-spacing: normal;
   word-break: normal;
   word-wrap: normal;
 }
 
-/* No resize on textarea; stop outline */
+/* No resize on textarea; transfer outline on focus to code-input element */
 code-input textarea {
   resize: none;
   outline: none!important;
 }
+code-input:has(textarea:focus):not(.code-input_mouse-focused) {
+  outline: 2px solid black;
+}
+
+/* Before registering give a hint about how to register. */
+code-input:not(.code-input_registered) {
+  overflow: hidden;
+  display: block;
+  box-sizing: border-box; /* Include padding in width/height */
+}
 
 code-input:not(.code-input_registered)::after {
   /* Display message to register */
   content: "Use codeInput.registerTemplate to set up.";
   display: block;
-  color: grey;
+  position: absolute;
+  bottom: var(--padding);
+  left: var(--padding);
+  width: calc(100% - 2 * var(--padding));
+
+  border-top: 1px solid grey;
+  outline: var(--padding) solid white;
+  background-color: white;
+}
+
+code-input:not(.code-input_loaded) pre, code-input:not(.code-input_loaded) textarea {
+  opacity: 0;
+}
+
+/* Contains dialog boxes that might appear as the result of a plugin.
+Sticks to the top of the code-input element */
+
+code-input .code-input_dialog-container {
+  z-index: 2;
+  
+  position: sticky;
+  grid-row: 1;
+  grid-column: 1;
+  
+  top: 0;
+  left: 0;
+
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 0;
+
+  /* Dialog boxes' text is based on text-direction */
+  text-align: inherit;
+}
+[dir=rtl] code-input .code-input_dialog-container, code-input[dir=rtl] .code-input_dialog-container {
+  left: unset;
+  right: 0;
+}
+
+/* Instructions specific to keyboard navigation set by plugins that override Tab functionality. */
+code-input .code-input_dialog-container .code-input_keyboard-navigation-instructions {
+  top: 0;
+  left: 0;
+
+  display: block;
+  position: absolute;
+  background-color: black;
+  color: white;
+  padding: 2px;
+  padding-left: 10px;
+  margin: 0;
+  text-wrap: balance;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  width: calc(100% - 12px);
+  max-height: 3em;
+}
+code-input:has(pre[dir=rtl]) .code-input_dialog-container .code-input_keyboard-navigation-instructions {
+  left: unset;
+  right: 0;
+}
+
+code-input:not(:has(textarea:focus)) .code-input_dialog-container .code-input_keyboard-navigation-instructions,
+code-input.code-input_mouse-focused .code-input_dialog-container .code-input_keyboard-navigation-instructions,
+code-input .code-input_dialog-container .code-input_keyboard-navigation-instructions:empty {
+  /* When not keyboard-focused / no instructions don't show instructions */
+  display: none;
+}
+
+/* Things with padding when instructions are present */
+code-input:not(:has(.code-input_keyboard-navigation-instructions:empty)):has(textarea:focus):not(.code-input_mouse-focused) textarea,
+code-input:not(:has(.code-input_keyboard-navigation-instructions:empty)):has(textarea:focus):not(.code-input_mouse-focused):not(.code-input_pre-element-styled) pre code,
+code-input:not(:has(.code-input_keyboard-navigation-instructions:empty)):has(textarea:focus):not(.code-input_mouse-focused).code-input_pre-element-styled pre {
+  padding-top: calc(var(--padding) + 3em)!important;
 }

package/code-input.d.ts

@@ -76,14 +76,27 @@ export namespace plugins {
     constructor();
   }
 
+  /**
+   * Automatically closes pairs of brackets/quotes/other syntaxes in code, but also lets you choose the brackets this
+   * is activated for.
+   * Files: auto-close-brackets.js
+   */
+  class AutoCloseBrackets extends Plugin {
+    /**
+     * Create an auto-close brackets plugin to pass into a template
+     * @param {Object} bracketPairs Opening brackets mapped to closing brackets, default and example {"(": ")", "[": "]", "{": "}", '"': '"'}. All brackets must only be one character.
+     */
+    constructor(bracketPairs: Object);
+  }
+
   /**
    * Display a popup under the caret using the text in the code-input element. This works well with autocomplete suggestions.
    * Files: autocomplete.js / autocomplete.css
    */
   class Autocomplete extends Plugin {
     /**
-     * Pass in a function to display the popup that takes in (popup element, textarea, textarea.selectionEnd).
-     * @param {function} updatePopupCallback  a function to display the popup that takes in (popup element, textarea, textarea.selectionEnd).
+     * Pass in a function to create a plugin that displays the popup that takes in (popup element, textarea, textarea.selectionEnd).
+     * @param {(popupElement: HTMLElement, textarea: HTMLTextAreaElement, selectionEnd: number) => void} updatePopupCallback  a function to display the popup that takes in (popup element, textarea, textarea.selectionEnd).
      */
     constructor(updatePopupCallback: (popupElem: HTMLElement, textarea: HTMLTextAreaElement, selectionEnd: number) => void);
   }
@@ -110,6 +123,69 @@ export namespace plugins {
     constructor(delayMs: number);
   }
 
+  /**
+   * Add Find-and-Replace (Ctrl+F for find, Ctrl+H for replace by default) functionality to the code editor.
+   * Files: find-and-replace.js / find-and-replace.css
+   */
+  class FindAndReplace extends Plugin {
+    /**
+     * Create a find-and-replace command plugin to pass into a template
+     * @param {boolean} useCtrlF Should Ctrl+F be overriden for find-and-replace find functionality? If not, you can trigger it yourself using (instance of this plugin)`.showPrompt(code-input element, false)`.
+     * @param {boolean} useCtrlH Should Ctrl+H be overriden for find-and-replace replace functionality? If not, you can trigger it yourself using (instance of this plugin)`.showPrompt(code-input element, true)`.
+     * @param {Object} instructionTranslations: user interface string keys mapped to translated versions for localisation. Look at the find-and-replace.js source code for the English text.
+     */
+    constructor(useCtrlF?: boolean, useCtrlH?: boolean,
+                instructionTranslations?: {
+                  start?: string;
+                  none?: string;
+                  oneFound?: string;
+                  matchIndex?: (index: Number, count: Number) => string;
+                  error?: (message: string) => string;
+                  infiniteLoopError?: string;
+                  closeDialog?: string;
+                  findPlaceholder?: string;
+                  findCaseSensitive?: string;
+                  findRegExp?: string;
+                  replaceTitle?: string;
+                  replacePlaceholder?: string;
+                  findNext?: string;
+                  findPrevious?: string;
+                  replaceActionShort?: string;
+                  replaceAction?: string;
+                  replaceAllActionShort?: string;
+                  replaceAllAction?: string
+                }
+              );
+    /**
+     * Show a find-and-replace dialog.
+     * @param {codeInput.CodeInput} codeInputElement the `<code-input>` element.
+     * @param {boolean} replacePartExpanded whether the replace part of the find-and-replace dialog should be expanded
+     */
+    showPrompt(codeInputElement: CodeInput, replacePartExpanded: boolean): void;
+  }
+  
+  /**
+   * Add basic Go-To-Line (ctrl-G by default) functionality to the code editor.
+   * Files: go-to-line.js / go-to-line.css
+   */
+  class GoToLine extends Plugin {
+    /**
+     * Create a go-to-line command plugin to pass into a template
+     * @param {boolean} useCtrlG Should Ctrl+G be overriden for go-to-line functionality? If not, you can trigger it yourself using (instance of this plugin)`.showPrompt(code-input element)`.
+     * @param {Object} instructionTranslations: user interface string keys mapped to translated versions for localisation. Look at the go-to-line.js source code for the English text.
+     */
+    constructor(useCtrlG: boolean,
+                instructionTranslations?: {
+                  closeDialog?: string;
+                  input?: string;
+                });
+    /**
+     * Show a search-like dialog prompting line number.
+     * @param {codeInput.CodeInput} codeInput the `<code-input>` element.
+    */
+    showPrompt(codeInput: CodeInput): void;
+  }
+
   /**
    * Adds indentation using the `Tab` key, and auto-indents after a newline, as well as making it 
    * possible to indent/unindent multiple lines using Tab/Shift+Tab
@@ -118,10 +194,65 @@ export namespace plugins {
   class Indent extends Plugin {
     /**
      * Create an indentation plugin to pass into a template
-     * @param {Boolean} defaultSpaces Should the Tab key enter spaces rather than tabs? Defaults to false.
+     * @param {boolean} defaultSpaces Should the Tab key enter spaces rather than tabs? Defaults to false.
      * @param {Number} numSpaces How many spaces is each tab character worth? Defaults to 4.
+     * @param {Object} bracketPairs Opening brackets mapped to closing brackets, default and example {"(": ")", "[": "]", "{": "}"}. All brackets must only be one character, and this can be left as null to remove bracket-based indentation behaviour.
+     * @param {boolean} escTabToChangeFocus Whether pressing the Escape key before (Shift+)Tab should make this keypress focus on a different element (Tab's default behaviour). You should always either enable this or use this plugin's disableTabIndentation and enableTabIndentation methods linked to other keyboard shortcuts, for accessibility.
+     * @param {Object} instructionTranslations: user interface string keys mapped to translated versions for localisation. Look at the go-to-line.js source code for the English text.
      */
-    constructor(defaultSpaces?: boolean, numSpaces?: Number);
+    constructor(defaultSpaces?: boolean, numSpaces?: Number, bracketPairs?: Object, escTabToChangeFocus?: boolean, instructionTranslations?: {
+      tabForIndentation?: string;
+      tabForNavigation?: string;
+    });
+  }
+
+  /**
+   * Make tokens in the <pre><code> element that are included within the selected text of the <code-input>
+   * gain a CSS class while selected, or trigger JavaScript callbacks.
+   * Files: select-token-callbacks.js
+   */
+  class SelectTokenCallbacks extends Plugin {
+    /**
+     * Set up the behaviour of tokens text-selected in the `<code-input>` element, and the exact definition of a token being text-selected.
+     * 
+     * All parameters are optional. If you provide no arguments to the constructor, this will dynamically apply the "code-input_select-token-callbacks_selected" class to selected tokens only, for you to style via CSS.
+     * 
+     * @param {codeInput.plugins.SelectTokenCallbacks.TokenSelectorCallbacks} tokenSelectorCallbacks What to do with text-selected tokens. See docstrings for the TokenSelectorCallbacks class.
+     * @param {boolean} onlyCaretNotSelection If true, tokens will only be marked as selected when no text is selected but rather the caret is inside them (start of selection == end of selection). Default false.
+     * @param {boolean} caretAtStartIsSelected Whether the caret or text selection's end being just before the first character of a token means said token is selected. Default true.
+     * @param {boolean} caretAtEndIsSelected Whether the caret or text selection's start being just after the last character of a token means said token is selected. Default true.
+     * @param {boolean} createSubTokens Whether temporary `<span>` elements should be created inside partially-selected tokens containing just the selected text and given the selected class. Default false.
+     * @param {boolean} partiallySelectedTokensAreSelected Whether tokens for which only some of their text is selected should be treated as selected. Default true.
+     * @param {boolean} parentTokensAreSelected Whether all parent tokens of selected tokens should be treated as selected. Default true.
+     */
+    constructor(tokenSelectorCallbacks?: codeInput.plugins.SelectTokenCallbacks.TokenSelectorCallbacks, onlyCaretNotSelection?: boolean, caretAtStartIsSelected?: boolean, caretAtEndIsSelected?: boolean, createSubTokens?: boolean, partiallySelectedTokensAreSelected?: boolean, parentTokensAreSelected?: boolean);
+  }
+
+  namespace SelectTokenCallbacks {
+    /**
+     * A data structure specifying what should be done with tokens when they are selected, and also allows for previously selected
+     * tokens to be dealt with each time the selection changes. See the constructor and the createClassSynchronisation static method.
+     */
+    class TokenSelectorCallbacks {
+      /**
+       * Pass any callbacks you want to customise the behaviour of selected tokens via JavaScript.
+       * 
+       * (If the behaviour you want is just differently styling selected tokens _via CSS_, you should probably use the createClassSynchronisation static method.) 
+       * @param {(token: HTMLElement) => void} tokenSelectedCallback Runs multiple times when the text selection inside the code-input changes, each time inputting a single (part of the highlighted `<pre><code>`) token element that is selected in the new text selection.
+       * @param {(tokenContainer: HTMLElement) => void} selectChangedCallback Each time the text selection inside the code-input changes, runs once before any tokenSelectedCallback calls, inputting the highlighted `<pre><code>`'s `<code>` element that contains all token elements.
+       */
+      constructor(tokenSelectedCallback: (token: HTMLElement) => void, selectChangedCallback: (tokenContainer: HTMLElement) => void);
+      
+      /**
+       * Use preset callbacks which ensure all tokens in the selected text range in the `<code-input>`, and only such tokens, are given a certain CSS class.
+       * 
+       * (If the behaviour you want requires more complex behaviour or JavaScript, you should use TokenSelectorCallbacks' constructor.) 
+       * 
+       * @param {string} selectedClass The CSS class that will be present on tokens only when they are part of the selected text in the `<code-input>` element. Defaults to "code-input_select-token-callbacks_selected".
+       * @returns {TokenSelectorCallbacks} A new TokenSelectorCallbacks instance that encodes this behaviour.
+       */
+      static createClassSynchronisation(selectedClass: string): codeInput.plugins.SelectTokenCallbacks.TokenSelectorCallbacks;
+    }
   }
 
   /**
@@ -133,7 +264,7 @@ export namespace plugins {
      * Create a special characters plugin instance.
      * Default = covers many non-renderable ASCII characters.
      * @param {Boolean} colorInSpecialChars Whether or not to give special characters custom background colors based on their hex code
-     * @param {Boolean} inheritTextColor If `colorInSpecialChars` is false, forces the color of the hex code to inherit from syntax highlighting. Otherwise, the base color of the `pre code` element is used to give contrast to the small characters.
+     * @param {Boolean} inheritTextColor If `inheritTextColor` is false, forces the color of the hex code to inherit from syntax highlighting. Otherwise, the base color of the `pre code` element is used to give contrast to the small characters.
      * @param {RegExp} specialCharRegExp The regular expression which matches special characters
      */
     constructor(colorInSpecialChars?: boolean, inheritTextColor?: boolean, specialCharRegExp?: RegExp);
@@ -160,32 +291,43 @@ export class Template {
    * 
    * Constructor to create a custom template instance. Pass this into `codeInput.registerTemplate` to use it.
    * I would strongly recommend using the built-in simpler template `codeInput.templates.prism` or `codeInput.templates.hljs`.
-   * @param {Function} highlight - a callback to highlight the code, that takes an HTML `<code>` element inside a `<pre>` element as a parameter
+   * @param {(codeElement: HTMLElement) => void} highlight - a callback to highlight the code, that takes an HTML `<code>` element inside a `<pre>` element as a parameter
    * @param {boolean} preElementStyled - is the `<pre>` element CSS-styled as well as the `<code>` element? If true, `<pre>` element's scrolling is synchronised; if false, `<code>` element's scrolling is synchronised.
    * @param {boolean} isCode - is this for writing code? If true, the code-input's lang HTML attribute can be used, and the `<code>` element will be given the class name 'language-[lang attribute's value]'.
    * @param {false} includeCodeInputInHighlightFunc - Setting this to true passes the `<code-input>` element as a second argument to the highlight function.
+   * @param {boolean} autoDisableDuplicateSearching - Leaving this as true uses code-input's default fix for preventing duplicate results in Ctrl+F searching from the input and result elements, and setting this to false indicates your highlighting function implements its own fix. The default fix works by moving text content from elements to CSS `::before` pseudo-elements after highlighting.
    * @param {codeInput.Plugin[]} plugins - An array of plugin objects to add extra features - see `codeInput.Plugin`
    * @returns template object
    */
-  constructor(highlight?: (code: HTMLElement) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: false, plugins?: Plugin[])
+  constructor(highlight?: (codeElement: HTMLElement) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: false, autoDisableDuplicateSearching?: boolean, plugins?: Plugin[])
   /**
    * **When `includeCodeInputInHighlightFunc` is `true`, `highlight` takes two parameters: the `<pre><code>` element, and the `<code-input>` element.**
    * 
    * Constructor to create a custom template instance. Pass this into `codeInput.registerTemplate` to use it.
    * I would strongly recommend using the built-in simpler template `codeInput.templates.prism` or `codeInput.templates.hljs`.
-   * @param {Function} highlight - a callback to highlight the code, that takes an HTML `<code>` element inside a `<pre>` element as a parameter
+   * @param {(codeElement: HTMLElement, codeInput: CodeInput) => void} highlight - a callback to highlight the code, that takes an HTML `<code>` element inside a `<pre>` element as a parameter
    * @param {boolean} preElementStyled - is the `<pre>` element CSS-styled as well as the `<code>` element? If true, `<pre>` element's scrolling is synchronised; if false, `<code>` element's scrolling is synchronised.
    * @param {boolean} isCode - is this for writing code? If true, the code-input's lang HTML attribute can be used, and the `<code>` element will be given the class name 'language-[lang attribute's value]'.
    * @param {true} includeCodeInputInHighlightFunc - Setting this to true passes the `<code-input>` element as a second argument to the highlight function.
+   * @param {boolean} autoDisableDuplicateSearching - Leaving this as true uses code-input's default fix for preventing duplicate results in Ctrl+F searching from the input and result elements, and setting this to false indicates your highlighting function implements its own fix. The default fix works by moving text content from elements to CSS `::before` pseudo-elements after highlighting.
    * @param {codeInput.Plugin[]} plugins - An array of plugin objects to add extra features - see `codeInput.Plugin`
    * @returns template object
    */
-  constructor(highlight?: (code: HTMLElement, codeInput: CodeInput) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: true, plugins?: Plugin[])
+  constructor(highlight?: (codeElement: HTMLElement, codeInput: CodeInput) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: true, autoDisableDuplicateSearching?: boolean, plugins?: Plugin[])
   highlight: Function
   preElementStyled: boolean
   isCode: boolean
   includeCodeInputInHighlightFunc: boolean
+  autoDisableDuplicateSearching: boolean
   plugins: Plugin[]
+  /**
+   * @deprecated Please give a value for the `autoDisableDuplicateSearching` parameter.
+   */
+  constructor(highlight?: (code: HTMLElement) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: false, plugins?: Plugin[])
+  /**
+   * @deprecated Please give a value for the `autoDisableDuplicateSearching` parameter.
+   */
+  constructor(highlight?: (code: HTMLElement, codeInput: CodeInput) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: true, plugins?: Plugin[])
 }
 
 /** 
@@ -225,7 +367,7 @@ export namespace templates {
   /**
    * Constructor to create a proof-of-concept template that shows text in a repeating series of colors.
    * @param {string[]} rainbowColors - An array of CSS colors, in the order each color will be shown
-   * @param {string} delimiter - The character used to split up parts of text where each part is a different colour (e.g. "" = characters, " " = words)
+   * @param {string} delimiter - The character used to split up parts of text where each part is a different color (e.g. "" = characters, " " = words)
    * @param {codeInput.Plugin[]} plugins - An array of plugin objects to add extra features - see `codeInput.plugins`
    * @returns template object
    */
@@ -244,4 +386,4 @@ export class CodeInput extends HTMLElement { }
  * @param {string} templateName - the name to register the template under
  * @param {Object} template - a Template object instance - see `codeInput.templates`  
  */
-export function registerTemplate(templateName: string, template: Template): void;
+export function registerTemplate(templateName: string, template: Template): void;