@webcoder49/code-input 2.5.0 → 2.6.0

package/docs/i18n/_index.md

@@ -0,0 +1,52 @@
++++
+title = 'Internationalising code-input.js'
++++
+
+# Internationalising code-input.js
+
+> Contributors: 2025 Oliver Geer
+
+## Languages
+
+code-input.js defaults to using English text for its interface, but when you want it in a different language you can provide the translated text:
+
+**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.

package/docs/interface/_index.md

@@ -0,0 +1,3 @@
++++
+title = 'How `code-input.js` works with native HTML+CSS+JS features - swap out any `textarea`'
++++

package/docs/interface/css/_index.md

@@ -0,0 +1,12 @@
++++
+title = 'Styling `code-input` elements with CSS'
++++
+
+# Styling `code-input` elements with CSS
+
+> Contributors: 2025 Oliver Geer
+
+`code-input` elements can be styled like `textarea` elements in most cases; however, there are some exceptions:
+* The CSS variable `--padding` should be used rather than the property `padding` (e.g. `<code-input style="--padding: 10px;">...`)
+* Background colours set on `code-input` elements will not work with highlighters that set background colours themselves - use `(code-input's selector) pre[class*="language-"]` for Prism.js or `.hljs` for highlight.js to target the highlighted element with higher specificity than the highlighter's theme. You may also set the `background-color` of the code-input element for its appearance when its template is unregistered / there is no JavaScript.
+* For now, elements on top of `code-input` elements should have a CSS `z-index` at least 3 greater than the `code-input` element.

package/docs/interface/forms/_index.md

@@ -0,0 +1,17 @@
++++
+title = '`code-input` in HTML5 Forms'
++++
+
+# `code-input` in HTML5 Forms
+
+> Contributors: 2025 Oliver Geer
+
+`code-input` elements support [HTML5 forms](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_forms#the_anatomy_of_a_form). Form-related HTML5 attributes and events on them will be passed to a `textarea` element inside them when they are registered, and whenever the attributes or events are later changed.
+
+This is a good time to make use of the fallback textarea which is used when JavaScript is disabled; the following code will send data to the HTML5 form correctly whether or not JavaScript is enabled:
+```html
+<form>
+    <code-input><textarea data-code-input-fallback name="code"></textarea></code-input>
+    <input type="submit"/>
+</form>
+```

package/docs/interface/js/_index.md

@@ -0,0 +1,11 @@
++++
+title = '`code-input` vs the `textarea` in JavaScript'
++++
+
+# `code-input` vs the `textarea` in JavaScript
+
+> Contributors: 2025 Oliver Geer
+
+Once registered, `code-input` elements support most of the JavaScript properties and events used with a `textarea` element, because they are built around them. Try swapping out your `textarea` element in your JavaScript application for a `code-input`! If it doesn't work, [submit a bug report](https://github.com/WebCoder49/code-input/issues).
+
+If you want to replace a `textarea` with a `code-input` in an application that doesn't need JavaScript, [look here](../forms). We support HTML5 forms, and progressive enhancement so JavaScript isn't needed!

package/docs/modules-and-frameworks/_index.md

@@ -0,0 +1,3 @@
++++
+title = 'Using `code-input.js` with Module Systems and Web Frameworks'
++++

package/docs/modules-and-frameworks/custom/_index.md

@@ -0,0 +1,9 @@
++++
+title = 'Using code-input.js with custom highlighting algorihms in projects which use modules or frameworks'
++++
+
+# Using code-input.js with custom highlighting algorithms in projects which use modules or frameworks
+
+> 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 vanilla code for code-input and custom highlighting algorithms](../../#playground-preset-custom).

package/docs/modules-and-frameworks/hljs/_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)

package/docs/modules-and-frameworks/hljs/esm/_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/",
+      }
+  }
+  ```

package/docs/modules-and-frameworks/hljs/nuxt/_index.md

@@ -0,0 +1,250 @@
++++
+title = 'How to use code-input and highlight.js with Nuxt'
++++
+
+# How to use code-input and highlight.js with Nuxt
+
+> Contributors: 2025 Paul Rosen, 2025 Oliver Geer; **code samples licensed [MIT/Expat](https://spdx.org/licenses/MIT)**
+
+[Vue](../vue) and Nuxt have some similarities, but there is one big difference in how they can use this library. In Nuxt there is server side rendering (SSR) that will attempt to create the final HTML before sending the page to the browser. This cannot use any browser-specific things so the `code-input` component must be excluded from rendering until hydration in the browser.
+ 
+## 1. Create a Nuxt app
+
+First, create a Nuxt project. (If you already have a Nuxt project then you can skip this step). On a command line, use your package manager to do so, for example by typing one of these:
+```bash
+yarn create nuxt syntax-highlighter
+# OR
+npm create nuxt@latest syntax-highlighter
+```
+
+At the time this tutorial was created, the output was the following:
+```plaintext
+Need to install the following packages:
+create-nuxt@3.27.0
+Ok to proceed? (y) y
+
+
+> npx
+> "create-nuxt" syntax-highlighter
+
+
+        .d$b.
+       i$$A$$L  .d$b
+     .$$F` `$$L.$$A$$.
+    j$$'    `4$$:` `$$.
+   j$$'     .4$:    `$$.
+  j$$`     .$$:      `4$L
+ :$$:____.d$$:  _____.:$$:
+ `4$$$$$$$$P` .i$$$$$$$$P`
+
+ℹ Welcome to Nuxt!
+ℹ Creating a new project in syntax-highlighter.
+
+✔ Which package manager would you like to use?
+npm
+◐ Installing dependencies...
+
+> postinstall
+> nuxt prepare
+
+✔ Types generated in .nuxt
+
+added 882 packages, and audited 884 packages in 5m
+
+185 packages are looking for funding
+  run `npm fund` for details
+
+found 0 vulnerabilities
+✔ Installation completed.
+
+✔ Initialize git repository?
+No
+
+✔ Would you like to install any of the official modules?
+Yes
+
+✔ Pick the modules to install:
+none
+
+✨ Nuxt project has been created with the v4 template. Next steps:
+ › cd syntax-highlighter
+ › Start development server with npm run dev
+
+```
+
+And just like the above instructions mention, do the following:
+```bash
+cd syntax-highlighter
+
+yarn run dev
+# OR
+npm run dev
+# or your package manager's equivalent command
+```
+
+You should be able to open your browser to the path that it prints out and see a working Nuxt app. If so, congratulations! Hit Ctrl-C in the command line to stop it.
+
+## 2. Add dependencies
+
+> This tutorial will use `highlight.js` for the syntax highlighting. If you are using a different method then adjust as needed.
+
+Type these 2 commands:
+```bash
+yarn add @webcoder49/code-input
+# OR
+npm install @webcoder49/code-input
+# or your package manager's equivalent command
+
+yarn add highlight.js
+# OR
+npm install highlight.js
+# or your package manager's equivalent command
+```
+
+In the file `nuxt.config.ts`, after the line `compatibilityDate`, add this so that Vue knows that `code-input` is not a Vue component:
+
+```javascript
+vue: {
+  compilerOptions: {
+    isCustomElement: (tag) => tag === "code-input",
+  },
+},
+``` 
+
+> You might want to replace the second file with your own theme, but you need the first file.
+
+## 3. Initialize a code-input element
+
+Create a component with whatever name you want. Perhaps `app/components/CodeEditor.vue`. Read the following code then paste it into the file:
+
+```html
+<template>
+  <!--Attributes that make sense on a
+  textarea element are both on the code-
+  input element for when full
+  functionality is present, and on the
+  fallback textarea for when it's not
+  (e.g. bug or outdated browser).-->
+  <code-input
+    ref="elem"
+    template="code-editor"
+    :name="name"
+    :value="value"
+    :language="language"
+    @input="value = elem.value; emit('input', elem.value)"
+    @code-input_load="loaded"
+  >
+    <textarea
+      ref="fallback"
+      :name="name"
+      :value="value"
+      @input="value = fallback.value; emit('input', fallback.value)"
+      data-code-input-fallback
+    ></textarea>
+  </code-input>
+</template>
+
+<script lang="ts" setup>
+// For loading a highlighting engine - this example uses highlight.js
+import hljs from 'highlight.js/lib/core';
+// You can import and register (in onBeforeMount below) whichever languages you will use,
+// or if you will use many import all, following the instructions at https://highlightjs.org/#usage.
+import javascript from 'highlight.js/lib/languages/javascript';
+
+// The following are optional.
+const emit = defineEmits<{
+  // If you want a listener when the user changes the contents.
+  (e: "input", value: string): void;
+  // If you want to do more initialization after code-input is ready.
+  (e: "ready", element: HTMLElement): void;
+}>();
+
+const props = defineProps<{
+  value: string; // The starting value for the code-input element
+  name: string; // The name that is used when the code-input element is in a form
+  language: string; // The programming language name given to highlight.js, which must also be imported above and registered below with highlight.js.
+}>();
+
+// This contains the HTMLElement of the code-input component
+const elem = ref()
+
+// Before it appears on the page, code-input needs to be initialized.
+// This must be onBeforeMount and not onMount!
+onBeforeMount(async () => {
+  // Only if we're in the client
+  // so that no server-side rendering is done on the code-input component
+  if (import.meta.browser) {
+    // Dynamically import code-input so that it is only in the browser
+    const codeInput = await import("@webcoder49/code-input");
+    const Template = (await import("@webcoder49/code-input/templates/hljs.mjs")).default;
+    // Set up highlight.js
+    hljs.registerLanguage('javascript', javascript);
+    // Register that engine with code-input
+    // You can also add plugins as shown below, and at https://code-input-js.org/plugins
+    const Indent = (await import("@webcoder49/code-input/plugins/indent.mjs")).default;
+    codeInput.registerTemplate("code-editor", new Template(hljs, [new Indent()]));
+  }
+})
+
+function loaded() {
+  // This is called after the code-input is initialized.
+  // If you have some further initialization for the code-input element, then do it in this event.
+  emit("ready", elem)
+}
+</script>
+
+<style scoped>
+.rich-editor {
+  border: 1px solid #bbbbbb;
+}
+code-input {
+  resize: both; /* if you want the resizing control that textarea has */
+  margin: 0; /* you can override other styles */
+  font-family: monospace;
+  
+  background: #f1f1f1; /* As explained below, this is required to set the colour of the code-input element if it
+                          falls back to having no highlighting, and while it loads. */
+}
+</style>
+
+<style>
+/* These are necessary styles to make code-input work */
+@import '@webcoder49/code-input/code-input.css';
+/* This is one possibility of styles to use for highlighting */
+@import 'highlight.js/styles/default.min.css';
+
+/* Notice that these styles aren't scoped */
+.hljs {
+  background: #f1f1f1;  /* This is a style specific to highlighted code, so needs to use highlight.js' selector.
+                           A side effect of this is that it will not affect unregistered/unloaded code-input elements. */
+}
+/* If you want to change the color of selected text during editing */
+code-input textarea::selection {
+  background: #6781ef;
+  color: #ffffff;
+}
+</style>
+```
+## 4. Using the component
+
+In the generated file `app.vue`, place the following line after the "NuxtRouteAnnouncer" line:
+```html
+<CodeEditor value="function hello() { console.log('world'); }" name="myEditor" />
+```
+
+Nuxt will have already imported it by default, so you don't need to import the component in JavaScript.
+
+Restart the server:
+```bash
+yarn run dev
+# OR
+npm run dev
+# or your package manager's equivalent command
+```
+
+If all went well, you should see the following in the browser:
+
+![An editable syntax-highlighted textarea added to the Nuxt starter page.](nuxt-demo-screenshot.png)
+
+## Please Note
+* Hot module replacement (the updating of a running app when files are changed) will not work completely correctly when the `CodeEditor` component is changed but will work when files that use it are changed. This is only important when running a development server.