javascript-code-library

a growing collection of ready-to-use UI components (built on preact+htm) and utility functions for JavaScript and TypeScript

This library contains the functions and preact components I am using to build my tools and web apps

work-in-progress: this library is currently modified quite often - and sometimes there may be even breaking changes. As a consequence, you may probably do not want to use it yourself right now - it exists just to allow for its import into other code

Input components protect, where needed, against external changes (e.g. from other CRDT nodes) overwriting a user's in-progress local input.

Markdown rendering (MarkdownView, MarkdownAsText/MarkdownAsHTML) recognizes $...$/$$...$$ KaTeX math only when it is set off by whitespace, punctuation or a line boundary - not when directly adjacent to other characters - so that stray dollar signs (prices, $HOME, ...) are not misread as formulas.

Installation

javascript-code-library is a pure ECMAScript module (ESM).

You may either install the package into your build environment using NPM with the command

npm install javascript-code-library

and bundle it with your application - in that case, no code needs to be loaded from any third party at runtime for the "core" of the library (preact, htm, detect-it and javascript-interface-library are bundled right into the single ESM file). mammoth and pdfjs-dist - needed for DOCX and PDF conversion, respectively - ship as separate chunk files alongside it and are loaded (from your own server, never from a third party) only when DOCXasText/DOCXasHTML/DOCXasMarkdown or PDFasText are actually called, so unused conversions never cost anything.

For buildless setups, it is recommended to host the module yourself: simply download the ready-made file javascript-code-library.esm.js and serve it from your own web server:

<script type="module">
  import * as JCL from '/js/javascript-code-library.esm.js'
</script>

Serving the file from your own origin keeps your visitors' IP addresses away from third-party servers - which may be relevant for GDPR compliance: loading assets from public CDNs (such as unpkg, jsDelivr or cdnjs) or other third-party hosts discloses visitor IPs to those parties and may require consent. For quick experiments, importing the module directly from rozek.github.io (also a third-party host) is still the fastest way to get started.

Optional, lazily-loaded peer libraries

A few of the heavier UI components (RichTextEditor, CodeEditor, Spreadsheet, ...) do not bundle their underlying third-party libraries (squire-rte, dompurify, CodeMirror, jspreadsheet-ce, jsuites, ...). Instead, they are loaded lazily at runtime via plain, bare-specifier import() calls, which are resolved through an Import Map on the hosting page - no bundler required for them, and unused components never pay their cost. See docs/ for step-by-step instructions on how to build and host these optional bundles yourself:

• docs/bundling-npm-packages-as-esm.md - general recipe (e.g. for squire-rte+dompurify)
• docs/bundling-jspreadsheet.md - jspreadsheet-ce+jsuites+formulajs
• docs/codemirror-bundles.md - CodeMirror 6 core + per-language bundles

Access

Import the functions and values you actually need

import { ValueIsListSatisfying, ValueIsOrdinal, capitalized } from 'javascript-code-library'

or import the complete module as a namespace

import * as JCL from 'javascript-code-library'

All module functions and values are exported individually, thus allowing your bundler to perform "tree-shaking" in order to include actually used functions or values (together with their dependencies) only - importing JCL causes no module-level side effects of its own, which is verified with agadoo as part of the build (see "Notes on the build" below).

Usage of the UI components

UI components are built with preact and htm and are rendered through JCL's own, already bundled render/html functions (exported as JCL.ui.render/ JCL.ui.html) - you do not need to install preact or htm yourself:

import * as JCL from 'javascript-code-library'
const { render, html } = JCL.ui

render(html`
  <${JCL.ui.vertical}>
    <${JCL.ui.Title} Value="Hello, World!"/>
  <//>
`, document.getElementById('rendering-target'))

Documentation

javascript-code-library bundles its exports into four curated namespaces - JCL.net, JCL.misc, JCL.ui and JCL.ai (all individual members are also available as named exports). Each has its own Programming Manual and API Reference:

| Package | Contains | Programming Manual | API Reference | |---|---|---|---| | JCL.net | connectivity checks, a hardened fetch() wrapper, content-negotiated fetchers, HTTP status helpers, a SearXNG search client | net-programming-manual.md | net-api-reference.md | | JCL.misc | reading Files, HTML/Markdown/DOCX/PDF conversion, a small HTML parser, HTML-attribute (un)escaping | misc-programming-manual.md | misc-api-reference.md | | JCL.ui | preact/htm re-exports, hooks, layout & content primitives, and ~125 native/styled/legacy UI components, plus the <jcl-applet> custom element | ui-programming-manual.md | ui-api-reference.md |

Everything else exported by the package (mostly re-exported from javascript-interface-library) is documented in that library's own README.

Status: these guides were generated from the current source as a first cut and will be extended over time - in particular, the ~125 native/styled/legacy components in JCL.ui are so far only listed by name in the API reference, without individual prop signatures, and JCL.ai (its most recent addition) has no dedicated guide yet.

Build Instructions

You may easily build this package yourself.

Just install the NPM package manager for node.js, if you have not already done so, and follow these steps:

1. clone the GitHub repository of this package
2. open a terminal window and navigate to the root directory of this repository
3. run npm install in order to install the complete build environment
4. execute npm run build to create a new build (from TypeScript sources)

You may also change the source code and run npm run test:run in order to run a quick sanity/smoke test suite (found in src/*.test.ts) - the more extensive, interactive smoke tests and demo applets that live alongside the original sources (BBN) are not (yet) part of this repository.

Notes on the build

• like javascript-interface-library, this package is checked with agadoo as part of npm run build: merely importing (any part of) JCL causes no module-level side effects any more - not even injecting global <style> rules or registering the jcl-applet custom element. Every UI component installs its own (scoped) stylesheet lazily, upon its first rendering only, and defineJCLApplet() must be called explicitly to register <jcl-applet>.
• since agadoo cannot see through bundled peer dependencies (and some of them, like preact, have legitimate side effects of their own upon loading), the build additionally produces a "slim" variant (dist/javascript-code-library.slim.esm.js, see vite.slim.config.ts) which keeps preact, htm, detect-it, javascript-interface-library, mammoth and pdfjs-dist external - that slim file is the one agadoo actually checks; it is not meant for direct use, only the regular, self-contained javascript-code-library.esm.js is.
• agadoo's own parser does not yet understand private class fields (#foo), which JCL's source relies on - a small patch (applied automatically via patch-package on npm install, see patches/) fixes that.
• mammoth and pdfjs-dist (unlike the optional peer libraries mentioned above, which need an Import Map on the hosting page) are always part of the package, just not loaded eagerly: they are imported dynamically upon first use, so the build also emits dist/mammoth-*.js and dist/pdfjs-dist-*.js chunk files (with content hashes in their names, which change from build to build) - keep them alongside the main ESM file when deploying.
• pdfjs-dist's worker file is copied into dist/ as part of the build (see vite.config.ts), since PDFFileReadAsText/PDFasText resolve it relative to the bundle's own URL at runtime.
• a handful of pre-existing strict-mode TypeScript diagnostics remain in src/javascript-code-library.ts (mostly Set<unknown> vs. Set<string> and DOM event-listener overload mismatches) - they do not stop npm run build (which only transpiles, it does not type-check) but are worth cleaning up over time.

License

MIT License