@webcoder49/code-input 2.5.0 → 2.6.0

package/code-input.d.ts

@@ -1,4 +1,5 @@
 export as namespace codeInput;
+// ESM-SUPPORT-END-NOESM-SPECIFIC Do not (re)move this - it's needed for ESM generation
 
 /**
  * Plugins are imported from the plugins folder. They will then
@@ -45,8 +46,16 @@ export abstract class Plugin {
    * modifications to the `codeInput.Plugin.attributeChanged` method.
    */
   observedAttributes: Array<string>
+
+  /**
+   * Replace the values in destination with those from source where the keys match, in-place.
+   * @param {Object} destination Where to place the translated strings, already filled with the keys pointing to English strings.
+   * @param {Object} source The same keys, or some of them, mapped to translated strings. Keys not present here will retain the values they are maapped to in destination.
+   */
+  addTranslations(destination: Object, source: Object): void
 }
 
+// ESM-SUPPORT-START-NAMESPACE-1 Do not (re)move this - it's needed for ESM generation
 /**
  * Before using any plugin in this namespace, please ensure you import its JavaScript
  * files (in the plugins folder), or continue to get a more detailed error in the developer
@@ -62,6 +71,7 @@ export abstract class Plugin {
  * @type {Object}
  */
 export namespace plugins {
+  // ESM-SUPPORT-START-PLUGIN-test Do not (re)move this - it's needed for ESM generation
   /**
    * JavaScript example of a plugin, which brings extra,
    * non-central optional functionality to code-input.
@@ -75,7 +85,9 @@ export namespace plugins {
   class Test extends Plugin {
     constructor();
   }
+  // ESM-SUPPORT-END-PLUGIN-test Do not (re)move this - it's needed for ESM generation
 
+  // ESM-SUPPORT-START-PLUGIN-auto-close-brackets Do not (re)move this - it's needed for ESM generation
   /**
    * Automatically closes pairs of brackets/quotes/other syntaxes in code, but also lets you choose the brackets this
    * is activated for.
@@ -86,9 +98,11 @@ export namespace plugins {
      * 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);
+    constructor(bracketPairs?: Object);
   }
+  // ESM-SUPPORT-END-PLUGIN-auto-close-brackets Do not (re)move this - it's needed for ESM generation
 
+  // ESM-SUPPORT-START-PLUGIN-autocomplete Do not (re)move this - it's needed for ESM generation
   /**
    * 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
@@ -96,11 +110,13 @@ export namespace plugins {
   class Autocomplete extends Plugin {
     /**
      * 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).
+     * @param {(popupElement: HTMLElement, textarea: HTMLTextAreaElement, selectionEnd: number, selectionStart?: 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);
+    constructor(updatePopupCallback: (popupElem: HTMLElement, textarea: HTMLTextAreaElement, selectionEnd: number, selectionStart?: number) => void);
   }
+  // ESM-SUPPORT-END-PLUGIN-autocomplete Do not (re)move this - it's needed for ESM generation
 
+  // ESM-SUPPORT-START-PLUGIN-autodetect Do not (re)move this - it's needed for ESM generation
   /**
    * Autodetect the language live and change the `lang` attribute using the syntax highlighter's 
    * autodetect capabilities. Works with highlight.js only.
@@ -109,20 +125,9 @@ export namespace plugins {
   class Autodetect extends Plugin {
     constructor();
   }
+  // ESM-SUPPORT-END-PLUGIN-autodetect Do not (re)move this - it's needed for ESM generation
 
-  /**
-   * Debounce the update and highlighting function
-   * https://medium.com/@jamischarles/what-is-debouncing-2505c0648ff1
-   * Files: debounce-update.js
-   */
-  class DebounceUpdate extends Plugin {
-    /**
-     * Create a debounced update plugin to pass into a template.
-     * @param {Number} delayMs Delay, in ms, to wait until updating the syntax highlighting 
-     */
-    constructor(delayMs: number);
-  }
-
+  // ESM-SUPPORT-START-PLUGIN-find-and-replace Do not (re)move this - it's needed for ESM generation
   /**
    * 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
@@ -130,8 +135,8 @@ export namespace plugins {
   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 {boolean} useCtrlF Should Ctrl+F be overriden for find-and-replace find functionality? Either way, you can also 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? Either way, you can also 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,
@@ -163,7 +168,9 @@ export namespace plugins {
      */
     showPrompt(codeInputElement: CodeInput, replacePartExpanded: boolean): void;
   }
+  // ESM-SUPPORT-END-PLUGIN-find-and-replace Do not (re)move this - it's needed for ESM generation
   
+  // ESM-SUPPORT-START-PLUGIN-go-to-line Do not (re)move this - it's needed for ESM generation
   /**
    * Add basic Go-To-Line (ctrl-G by default) functionality to the code editor.
    * Files: go-to-line.js / go-to-line.css
@@ -171,13 +178,18 @@ export namespace plugins {
   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 {boolean} useCtrlG Should Ctrl+G be overriden for go-to-line functionality? Either way, 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,
+    constructor(useCtrlG?: boolean,
                 instructionTranslations?: {
                   closeDialog?: string;
                   input?: string;
+                  guidanceFormat?: string;
+                  guidanceLineRange?: (current:Number, max: Number) => string;
+                  guidanceColumnRange?: (line: Number, current: Number, max: Number) => string;
+                  guidanceValidLine?: (line: Number) => string;
+                  guidanceValidColumn?: (line: Number, column: Number) => string;
                 });
     /**
      * Show a search-like dialog prompting line number.
@@ -185,7 +197,9 @@ export namespace plugins {
     */
     showPrompt(codeInput: CodeInput): void;
   }
+  // ESM-SUPPORT-END-PLUGIN-go-to-line Do not (re)move this - it's needed for ESM generation
 
+  // ESM-SUPPORT-START-PLUGIN-indent Do not (re)move this - it's needed for ESM generation
   /**
    * 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
@@ -200,12 +214,14 @@ export namespace plugins {
      * @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, bracketPairs?: Object, escTabToChangeFocus?: boolean, instructionTranslations?: {
+    constructor(defaultSpaces?: boolean, numSpaces?: Number, bracketPairs?: Object, escTabToChangeFocus?: boolean, instructionTwranslations?: {
       tabForIndentation?: string;
       tabForNavigation?: string;
     });
   }
+  // ESM-SUPPORT-END-PLUGIN-indent Do not (re)move this - it's needed for ESM generation
 
+  // ESM-SUPPORT-START-PLUGIN-select-token-callbacks Do not (re)move this - it's needed for ESM generation
   /**
    * 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.
@@ -251,35 +267,42 @@ export namespace plugins {
        * @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;
+      static createClassSynchronisation(selectedClass?: string): codeInput.plugins.SelectTokenCallbacks.TokenSelectorCallbacks;
     }
   }
+  // ESM-SUPPORT-END-PLUGIN-select-token-callbacks Do not (re)move this - it's needed for ESM generation
 
+  // ESM-SUPPORT-START-PLUGIN-special-chars Do not (re)move this - it's needed for ESM generation
   /**
    * Render special characters and control characters as a symbol with their hex code.
    * Files: special-chars.js, special-chars.css
+   *
+   * WARNING:
+   *
+   * This plugin is currently unstable when used with other plugins,
+   * Unicode characters, or highlight.js. I hope to fix much of this by
+   * major version 3, and if you could help that would be amazing!
+   *
+   * See https://github.com/WebCoder49/code-input/issues?q=is%3Aissue%20state%3Aopen%20specialchars
    */
   class SpecialChars extends Plugin {
     /**
      * 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 `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
+     * @param {Boolean} colorInSpecialChars Whether or not to give special characters custom background colors based on their hex code. Defaults to false.
+     * @param {Boolean} inheritTextColor If true, forces the color of the hex code to inherit from syntax highlighting. If false, the base color of the `pre code` element is used to give contrast to the small characters. Defaults to false.
+     * @param {RegExp} specialCharRegExp The regular expression which matches special characters. Defaults to many non-renderable ASCII characters (which characters are renderable depends on the browser and OS).
      */
     constructor(colorInSpecialChars?: boolean, inheritTextColor?: boolean, specialCharRegExp?: RegExp);
   }
+  // ESM-SUPPORT-END-PLUGIN-special-chars Do not (re)move this - it's needed for ESM generation
 }
+// ESM-SUPPORT-END-NAMESPACE-1 Do not (re)move this - it's needed for ESM generation
 
 /**
- * Register a plugin class under `codeInput.plugins`.
- * @param {string} pluginName The identifier of the plugin: if it is `"foo"`, `new codeInput.plugins.foo(`...`)` will instantiate it, etc.
- * @param {Object} pluginClass The class of the plugin, created with `class extends codeInput.plugin {`...`}`
- */
-export function registerPluginClass(pluginName: string, pluginClass: Object): void;
-
-/**
- * Please see `codeInput.templates.prism` or `codeInput.templates.hljs`.
+ * If you're using one of the two named highlighters, please see
+ * `codeInput.templates.prism` or `codeInput.templates.hljs`.
+ * Otherwise please see this class' constructor.
  * Templates are used in `<code-input>` elements and once registered with
  * `codeInput.registerTemplate` will be in charge of the highlighting
  * algorithm and settings for all code-inputs with a `template` attribute
@@ -292,44 +315,34 @@ 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 {(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} preElementStyled - is the `<pre>` element CSS-styled (if so set to true), or the `<code>` element (false)?
    * @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?: (codeElement: HTMLElement) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: false, autoDisableDuplicateSearching?: boolean, plugins?: Plugin[])
+  constructor(highlight?: (codeElement: HTMLElement) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: false, 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 {(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} preElementStyled - is the `<pre>` element CSS-styled (if so set to true), or the `<code>` element (false)?
    * @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?: (codeElement: HTMLElement, codeInput: CodeInput) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: true, autoDisableDuplicateSearching?: boolean, plugins?: Plugin[])
+  constructor(highlight?: (codeElement: HTMLElement, codeInput: CodeInput) => void, preElementStyled?: boolean, isCode?: boolean, includeCodeInputInHighlightFunc?: true, 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[])
+  plugins: Plugin[] 
 }
 
+// ESM-SUPPORT-START-NAMESPACE-2 Do not (re)move this - it's needed for ESM generation
 /** 
  * Shortcut functions for creating templates.
  * Each code-input element has a template attribute that 
@@ -344,18 +357,42 @@ export class Template {
  * For adding small pieces of functionality, please see `codeInput.plugins`.
  */
 export namespace templates {
+  // ESM-SUPPORT-START-TEMPLATE-prism Do not (re)move this - it's needed for ESM generation
   /**
-   * Constructor to create a template that uses Prism.js syntax highlighting (https://prismjs.com/)
-   * @param {Object} prism Import Prism.js, then after that import pass the `Prism` object as this parameter.
-   * @param {codeInput.Plugin[]} plugins - An array of plugin objects to add extra features - see `codeInput.plugins`
-   * @returns template object
+   * A template that uses Prism.js syntax highlighting (https://prismjs.com/).
+   */
+  class Prism extends Template {
+    /**
+    * Constructor to create a template that uses Prism.js syntax highlighting (https://prismjs.com/)
+    * @param {Object} prism Import Prism.js, then after that import pass the `Prism` object as this parameter.
+    * @param {codeInput.Plugin[]} plugins - An array of plugin objects to add extra features - see `codeInput.plugins`
+    * @param {boolean} preElementStyled - Defaults to true, which should be right for most themes. If the styling is broken, change to false. (See `codeInput.Template` constructor's definition.)
+    * @returns template object
+    */
+    constructor(prism: Object, plugins?: Plugin[], preElementStyled?: boolean)
+  }
+  // ESM-SUPPORT-END-TEMPLATE-prism Do not (re)move this - it's needed for ESM generation
+  /**
+   * @deprecated Please use `new codeInput.templates.Prism(...)`
    */
   function prism(prism: Object, plugins?: Plugin[]): Template
+  // ESM-SUPPORT-START-TEMPLATE-hljs Do not (re)move this - it's needed for ESM generation
   /**
-   * Constructor to create a template that uses highlight.js syntax highlighting (https://highlightjs.org/)
-   * @param {Object} hljs Import highlight.js, then after that import pass the `hljs` object as this parameter.
-   * @param {codeInput.Plugin[]} plugins - An array of plugin objects to add extra features - see `codeInput.plugins`
-   * @returns template object
+   * A template that uses highlight.js syntax highlighting (https://highlightjs.org/).
+   */
+  class Hljs extends Template {
+    /**
+    * Constructor to create a template that uses highlight.js syntax highlighting (https://highlightjs.org/)
+    * @param {Object} hljs Import highlight.js, then after that import pass the `hljs` object as this parameter.
+    * @param {codeInput.Plugin[]} plugins - An array of plugin objects to add extra features - see `codeInput.plugins`
+    * @param {boolean} preElementStyled - Defaults to false, which should be right for most themes. If the styling is broken, change to true. (See `codeInput.Template` constructor's definition.)
+    * @returns template object
+    */
+    constructor(hljs: Object, plugins?: Plugin[], preElementStyled?: boolean)
+  }
+  // ESM-SUPPORT-END-TEMPLATE-hljs Do not (re)move this - it's needed for ESM generation
+  /**
+   * @deprecated Please use `new codeInput.templates.Hljs(...)`
    */
   function hljs(hljs: Object, plugins?: Plugin[]): Template
   /**
@@ -373,12 +410,51 @@ export namespace templates {
    */
   function rainbowText(rainbowColors?: string[], delimiter?: string, plugins?: Plugin[]): Template
 }
+// ESM-SUPPORT-END-NAMESPACE-2 Do not (re)move this - it's needed for ESM generation
 
 /**
  * A `<code-input>` element, an instance of an `HTMLElement`, and the result
- * of `document.createElement("code-input")`.
+ * of `document.createElement("code-input")`. Attributes are only set when
+ * the element's template has been registered, and before this are null.
  */
-export class CodeInput extends HTMLElement { }
+export class CodeInput extends HTMLTextAreaElement { // Tries to implement textarea interface
+  /**
+   * When the code-input's template is registered, this contains its codeInput.Template object.
+   */
+  templateObject?: readonly Template
+  /**
+   * Exposed child textarea element for user to input code in; in this version of code-input you shouldn't need to access
+   * it because most textarea functionality is present on the code-input element itself.
+   */
+  textareaElement?: HTMLTextAreaElement
+  /**
+   * Exposed child pre element where syntax-highlighted code is outputted.
+   * Contains this.codeElement as its only child.
+   */
+  preElement?: HTMLPreElement
+  /**
+   * Exposed child pre element's child code element where syntax-highlighted code is outputted.
+   * Has this.preElement as its parent.
+   */
+  codeElement?: HTMLElement
+  /**
+   * Exposed non-scrolling element designed to contain dialog boxes etc. from plugins,
+   * that shouldn't scroll with the code-input element.
+   */
+  dialogContainerElement?: HTMLElement
+  /**
+   * Show some instructions to the user only if they are using keyboard navigation - for example, a prompt on how to navigate with the keyboard if Tab is repurposed.
+   * @param {string} instructions The instructions to display only if keyboard navigation is being used. If it's blank, no instructions will be shown.
+   * @param {boolean} includeAriaDescriptionFirst Whether to include the aria-description of the code-input element before the keyboard navigation instructions for a screenreader. Keep this as true when the textarea is first focused.
+   */
+  setKeyboardNavInstructions(instructions: string, includeAriaDescriptionFirst: boolean): void
+  /**
+   * Allows plugins to store data in the scope of a single element.
+   * Key - name of the plugin, in camelCase
+   * Value - object of data to be stored; different plugins may use this differently.
+   */
+  pluginData: Object
+}
 
 /**
  * Register a template so code-input elements with a template attribute that equals the templateName will use the template.