Update documentation and docstrings for plugins, i18n and ESM+hljs

Author: WebCoder49

code-input.css

@@ -138,7 +138,7 @@ code-input:not(.code-input_registered) {
 
 code-input:not(.code-input_registered)::after {
   /* Display message to register */
-  content: "No-JavaScript fallback. For highlighting and plugins: as a user use a newer browser/enable JavaScript support; as a developer use codeInput.registerTemplate.";
+  content: "No highlighting. JavaScript support is disabled or insufficient, or codeInput.registerTemplate has not been called.";
   display: block;
   position: absolute;
   bottom: 0;

code-input.d.ts

@@ -46,6 +46,13 @@ 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
@@ -128,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,
@@ -171,7 +178,7 @@ 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,
@@ -269,14 +276,22 @@ export namespace plugins {
   /**
    * 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);
   }

code-input.js

@@ -367,9 +367,9 @@ var codeInput = {
         }
 
         /**
-         * Replace the keys in destination with any source
+         * 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.
+         * @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, source) {
             for(const key in source) {

docs/_index.md

@@ -47,7 +47,7 @@ console.log("Hello, World!");</textarea></code-input>
 
 ### Tutorials by Example
 
-#### Prism.js Code Editor (use **with vanilla HTML here** or [with ECMAScript Modules/Vue/Nuxt](frameworks/prism)) {#playground-preset-prism}
+#### Prism.js Code Editor (use **with vanilla HTML here** or [with ECMAScript Modules/Vue/Nuxt](modules-and-frameworks/prism)) {#playground-preset-prism}
 
 ```
 <!DOCTYPE html>
@@ -103,7 +103,7 @@ console.log("Hello, World!");</textarea></code-input>
 </html>
 ```
 
-#### highlight.js Code Editor (use **with vanilla HTML here** or [with ECMAScript Modules/Vue/Nuxt](frameworks/hljs)) {#playground-preset-hljs}
+#### highlight.js Code Editor (use **with vanilla HTML here** or [with ECMAScript Modules/Vue/Nuxt](modules-and-frameworks/hljs)) {#playground-preset-hljs}
 
 ```
 <!DOCTYPE html>
@@ -160,7 +160,7 @@ console.log("Hello, World!");</textarea></code-input>
 </html>
 ```
 
-#### Editor with Custom Highlighting Algorithm (use **with vanilla HTML here** or [with ECMAScript Modules/Vue/Nuxt](frameworks/custom)) {#playground-preset-custom}
+#### Editor with Custom Highlighting Algorithm (use **with vanilla HTML here** or [with ECMAScript Modules/Vue/Nuxt](modules-and-frameworks/custom)) {#playground-preset-custom}
 
 ```
 <!DOCTYPE html>
@@ -279,7 +279,7 @@ Widely Usable and Progressively Enhanced
 </dt>
 <dd>
 
-Works on any modern browser independent of whether a framework is used, with the standardised web component API. Integrates well into modular setups and web frameworks with TypeScript definitions, an ECMAScript Module build and tutorials. Falls back to a `textarea` element when there is insufficient JavaScript support. The fallback even works on Lynx.
+Works on any modern browser independent of whether a framework is used, with the standardised web component API. Integrates well into modular setups and web frameworks with TypeScript definitions, an ECMAScript Module build and [tutorials](modules-and-frameworks). Falls back to a `textarea` element when there is insufficient JavaScript support. The fallback even works on Lynx.
 
 </dd>
 </dl>
@@ -297,4 +297,4 @@ something like [CodeMirror](https://codemirror.net/),
 [Monaco](https://microsoft.github.io/monaco-editor/).
 
 ## Read Enough?
-**If you don't need web framework integration, get started with the commented tutorials by example on this page, for [Prism.js](#playground-preset-prism), [highlight.js](#playground-preset-hljs), or [another highlighter](#playground-preset-custom). If you're using a web framework, start [here](frameworks).**
+**If you don't need web framework integration, get started with the commented tutorials by example on this page, for [Prism.js](#playground-preset-prism), [highlight.js](#playground-preset-hljs), or [another highlighter](#playground-preset-custom). If you're using ECMAScript modules or a web framework, start [here](modules-and-frameworks).**

docs/frameworks/hljs/_index.md

@@ -0,0 +1,50 @@
++++
+title = 'Internationalising code-input.js'
++++
+
+# Internationalising code-input.js
+
+> Contributors: 2021 Oliver Geer
+
+## Languages
+
+code-input.js defaults to using English text, but when want the interface in a different language you can provide text in a different language.
+
+**The core of code-input.js** contains one message shown only when CSS is supported but JavaScript has not been used to register the element. Translate it by writing the following CSS rule, replacing the text with its localised version.
+```css
+code-input:not(.code-input_registered)::after {
+  content: "No highlighting. JavaScript support is disabled or insufficient, or codeInput.registerTemplate has not been called."!important;
+}
+```
+It is only present for debugging and explanatory purposes when highlighting cannot be seen, and should not contain important or specific information about the editor state; if you need such information, especially for screen reader users, add separate text to your application which disappears after registering the code-input without errors.
+
+**Plugins** sometimes come with user interface features (e.g. the find-and-replace dialog) which contain text to be translated. The text is provided as an extra argument to the plugin constructor containing translated strings or functions to produce them for each translation key, with the keys and their English values found in either the `code-input.d.ts` or the plugin's source code file. Here's an example:
+```javascript
+// CC-BY; Attribution: Translated by Oliver Geer with some help from English Wiktionary
+let findAndReplaceTranslations = {
+    start: "Buscar términos en su código.",
+    none: "No hay sucesos",
+    oneFound: "1 suceso encontrado.",
+    matchIndex: (index, count) => `${index} de ${count} sucesos.`,
+    error: (message) => `Error: ${message}`,
+    infiniteLoopError: "Causa un ciclo infinito",
+    closeDialog: "Cerrar el Diálogo y Regresar al Editor",
+    findPlaceholder: "Buscar",
+    findCaseSensitive: "Prestar atención a las minúsculas/mayúsculas",
+    findRegExp: "Utilizar expresión regular de JavaScript",
+    replaceTitle: "Reemplazar",
+    replacePlaceholder: "Reemplazar con",
+    findNext: "Buscar Suceso Próximo",
+    findPrevious: "Buscar Suceso Previo",
+    replaceActionShort: "Reemplazar",
+    replaceAction: "Reemplazar este Suceso",
+    replaceAllActionShort: "Reemplazar Todos",
+    replaceAllAction: "Reemplazar Todos los Sucesos"
+};
+// ...
+// passed when the plugin is constructed:
+new codeInput.plugins.FindAndReplace(true, true, findAndReplaceTranslations),
+```
+
+## Other
+* code-input.js has supported text bidirectionality using the HTML `dir` attribute since version 2.5.

docs/i18n/_index.md

@@ -6,4 +6,4 @@ title = 'Using code-input.js with custom highlighting algorihms in projects whic
 
 > Contributors: 2025 Oliver Geer
 
-We plan to get documentation for this soon (contributions via a pull request are welcome!), but for now please use [the corresponding article for highlight.js](../hljs) and [the demo frameworkless code for code-input and custom highlighting algorithms](../../#playground-preset-custom).
+We plan to get documentation for this soon (contributions via a pull request are welcome!), but for now please use [the corresponding article for highlight.js](../hljs) and [the demo vanilla code for code-input and custom highlighting algorithms](../../#playground-preset-custom).

docs/frameworks/_index.md docs/modules-and-frameworks/_index.mddocs/frameworks/_index.md renamed to docs/modules-and-frameworks/_index.md

@@ -0,0 +1,13 @@
++++
+title = 'Using code-input.js with highlight.js in projects which use modules or frameworks'
++++
+# Using code-input.js with highlight.js in projects which use modules or frameworks
+
+> Contributors: 2025 Oliver Geer
+
+## Quickstart with Frameworks
+* [Vue](vue) (with ESM)
+* [Nuxt](nuxt) (with ESM)
+
+## Quickstart with Module Systems
+* [ECMAScript Modules (ESM)](esm)

docs/frameworks/custom/_index.md …/modules-and-frameworks/custom/_index.mddocs/frameworks/custom/_index.md renamed to docs/modules-and-frameworks/custom/_index.md docs/frameworks/custom/_index.md renamed to docs/modules-and-frameworks/custom/_index.md

@@ -0,0 +1,71 @@
++++
+title = 'How to use code-input and highlight.js with ECMAScript Modules (not framework-specific)'
++++
+
+# How to use code-input and highlight.js with ECMAScript Modules (not framework-specific)
+
+> Contributors: 2025 Oliver Geer
+
+These instructions will work anywhere [ECMAScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) are supported. If you want a tutorial specific to a web framework, please [look here](..).
+
+This is a client-side library so will not work in Node.js or similar environments. It is assumed that you have already researched and run an example frontend ECMAScript module (ESM) project using either a bundler like [esbuild](https://esbuild.github.io/) or [webpack](https://webpack.js.org), or newer browsers' direct ESM support (less browser compatibility but easier when debugging); setting them up is not described here. You can [learn about ESM from the very basics here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).
+
+## Building
+
+The ECMAScript modules in version 2 of the code-input.js library need to be "built" from the source files, because the source files are not in the ESM format.
+
+For builds from package managers like Yarn and NPM, the ESM files have already been built and are in the `esm` directory.
+
+When the code is downloaded or cloned from `git` source, the ESM directory contains files to do the building but not the built modules yet; follow the instructions in `esm/README.md` to run the build.
+
+## Usage
+
+Here's how to use code-input and highlight.js with ECMAScript modules.
+
+```javascript
+// Access the registerTemplate function and CodeInput (extends HTMLElement),
+// Template (custom highlighter) and Plugin (abstract class) classes inside the 
+// imported codeInput object.
+import codeInput from "@webcoder49/code-input/code-input.mjs";
+
+// Alternatively, use:
+// import { registerTemplate, CodeInput, Template, Plugin } from "@webcoder49/code-input/code-input.mjs"
+
+// Templates must be imported separately to avoid redundant code being imported
+// Use any name for the default import, not just "Template"
+import Template from "@webcoder49/code-input/templates/hljs.mjs";
+
+// Plugins must be imported separately to avoid redundant code being imported
+// See them all at https://code-input-js.org/plugins
+// Use any name for the default import, not just "Indent"
+import Indent from "@webcoder49/code-input/plugins/indent.mjs";
+
+// As per https://highlightjs.org/usage
+// You can import and register (in onMounted below) whichever languages you will use,
+// or if you will use many import all, following the instructions at https://highlightjs.org/#usage.
+import hljs from 'highlight.js/lib/core';
+import javascript from 'highlight.js/lib/languages/javascript';
+// Set up the highlighting engine first
+hljs.registerLanguage('javascript', javascript);
+
+
+// Register using the imported objects
+codeInput.registerTemplate("code-editor", new Template(hljs, [new Indent()]));
+```
+
+Note the `.mjs` extensions on code-input.js import paths. They are needed, and also make the next part easier:
+
+## Import Paths
+
+The import paths above assume a package manager and `package.json` export paths are being used.
+
+In some setups, this will not work. You have two options (replace `node_modules/@webcoder49/code-input` with the relative path to the library, if it is different):
+* use relative paths instead: replace `"@webcoder49/code-input/path/to/file.mjs"` with `"node_modules/@webcoder49/code-input/esm/path/to/file.mjs"` (note the `esm` directory). Also replace `"@webcoder49/code-input/path/to/file.mjs"` with `"node_modules/@highlightjs/cdn-assets/es/path/to/file.mjs"` (note the `es` directory) *If you're not using an import map yet, I recommend this option because import maps are not supported on as many browsers.*
+* If you're using an [import map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#importing_modules_using_import_maps), add the following to it:
+  ```json
+  {
+      "imports": {
+          "@webcoder49/code-input": "./node_modules/@webcoder49/code-input/esm/",
+      }
+  }
+  ```