yourjs-box 1.9.0 → 1.11.0

package/README.md

@@ -1,11 +1,12 @@
-# yourjs-box
+# YourJS Box
 
 Embed an interactive JavaScript console on any web page with one script tag.
 Step-by-step code blocks, DevTools-style output, and code that runs in a Web
 Worker or the page itself.  TypeScript works too.
 
 **[Live demo](https://westc.github.io/yourjs-box/)** ·
-[Examples](https://westc.github.io/yourjs-box/examples/)
+[Examples](https://westc.github.io/yourjs-box/#examples) ·
+[Changelog](CHANGELOG.md)
 
 ![YourJS Box running code one block at a time, expanding an object, showing a table and an error](demo.gif)
 
@@ -100,20 +101,28 @@ objects and arrays) for a menu with:
 - **Refresh** (for objects, arrays, etc.), which shows the value as it is now
   if the code has changed it.  Anything that was expanded stays expanded.
 
-### Attributes
-
-| Attribute | Description |
-| --- | --- |
-| `data-block-type` | `"classic"` (default) runs each block like a regular `<script>` so top-level declarations are shared between blocks.  `"module"` runs each block like a `<script type="module">`.  See below. |
-| `data-language` | `"javascript"` (default) or `"typescript"`.  See "TypeScript" below. |
-| `data-show-results` | `"false"` stops the value of the last expression in each block from being shown. |
-| `data-imports-url` | Where packages imported by name are loaded from.  See "Importing Packages" below. |
-| `data-libraries-url` | Where to load Vue, Ace, Prism, Acorn and Babel from.  See "Self-Hosting the Libraries" below. |
-| `data-runner` | `"worker"` (default) runs the code in a Web Worker.  `"window"` runs it directly in the page.  See below. |
-| `data-divider-orient` | `"vertical"` puts the editor beside the output and `"horizontal"` puts it below.  If not specified the editor is beside the output unless the console is narrower than 600px. |
-| `data-hide-prefix` | Any block whose header starts with this prefix is hidden. See below. |
-| `data-loading` | `"lazy"` (default) waits to load the console until it is about to be scrolled into view (or, if it is hidden, shown).  `"eager"` loads it right away.  See "Loading" below. |
-| `data-theme` | `"light"` or `"dark"`.  Defaults to following the system's color scheme like the browser's dev tools. |
+### Options
+
+Each option can be set with a `data-*` attribute on the script tag or, with
+the [JavaScript API](#javascript-api), as an option of `YourJSBox.create()` or
+`YourJSBox.from()`.  Attribute values are always strings, while the API also
+takes booleans for the true/false options and an array for `rulers`.
+
+| Attribute | API option | Default | Description |
+| --- | --- | --- | --- |
+| `data-runner` | `runner` | `"worker"` | `"worker"` runs the code in a Web Worker.  `"window"` runs it directly in the page.  See "Where Code Runs" below. |
+| `data-block-type` | `blockType` | `"classic"` | `"classic"` runs each block like a regular `<script>` so top-level declarations are shared between blocks.  `"module"` runs each block like a `<script type="module">`.  See "Module Blocks" below. |
+| `data-language` | `language` | `"javascript"` | `"javascript"` or `"typescript"`.  See "TypeScript" below. |
+| `data-show-results` | `showResults` | `"true"` | `"false"` stops the value of the last expression in each block from being shown.  See "Results" below. |
+| `data-hide-prefix` | `hidePrefix` | None | Any block whose header starts with this prefix is hidden but still runs.  See "Hidden Code" below. |
+| `data-hide-empty-output` | `hideEmptyOutput` | `"true"` | `"true"` only shows the editor until there is something in the output (eg. once code is run).  The output then stays (even after Clear) until the console is reset.  `"false"` always shows the output. |
+| `data-divider-orient` | `dividerOrient` | Automatic | `"vertical"` puts the editor beside the output and `"horizontal"` puts it below.  If not given, the editor is beside the output unless the console is narrower than 600px. |
+| `data-theme` | `theme` | The system's | `"light"` or `"dark"`.  If not given, it follows the system's color scheme like the browser's dev tools. |
+| `data-word-wrap` | `wordWrap` | `"false"` | `"true"` wraps long lines in the editor instead of scrolling sideways. |
+| `data-rulers` | `rulers` | `"80"` | The columns where lines are shown in the editor, eg. `"80, 120"` (or `[80, 120]` with the API).  `""` shows none. |
+| `data-loading` | `loading` | `"lazy"` | `"lazy"` waits to load the console until it is about to be scrolled into view (or, if it is hidden, shown).  `"eager"` loads it right away.  See "Loading" below. |
+| `data-imports-url` | `importsUrl` | esm.sh | Where packages imported by name are loaded from.  `""` turns this off.  See "Importing Packages" below. |
+| `data-libraries-url` | `librariesUrl` | unpkg | Where to load Vue, Ace, Prism, Acorn and Babel from.  See "Self-Hosting the Libraries" below. |
 
 ### Results
 
@@ -295,7 +304,7 @@ box.destroy();
 `YourJSBox.create(options)` returns `{element, destroy}` where `element` is the
 console's IFRAME and `destroy()` removes it, stops its code and closes its
 pop-out window (in window mode it also restores the page's `console`
-functions).  The options are:
+functions).  Its own options are:
 
 | Option | Description |
 | --- | --- |
@@ -303,9 +312,42 @@ functions).  The options are:
 | `placement` | Where the console goes:  `"fill"` (default) replaces the target's contents, `"append"` and `"prepend"` add it inside of the target, `"replace"` replaces the target itself and `"before"` and `"after"` add it next to the target. |
 | `height` | The CSS height of the console (a number is treated as pixels).  Defaults to `"100%"` so the console fills its container.  It is never less than 150px. |
 | `code` | The code that the console starts with. |
-| `runner`, `blockType`, `language`, `showResults`, `hidePrefix`, `dividerOrient`, `theme`, `importsUrl`, `librariesUrl`, `loading` | The same as the `data-*` attributes above. |
 
-`YourJSBox.version` is the version of JS Box that was loaded.
+It also takes every option in [Options](#options) (eg. `theme` or `wordWrap`).
+
+`YourJSBox.from(elements, options)` turns existing elements (eg. the code blocks
+in a page made from Markdown) into consoles that start with their code:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/yourjs-box@1/dist/yourjs-box.min.js"></script>
+<script>YourJSBox.from('pre > code.language-js');</script>
+```
+
+- `elements` is a CSS selector, an element or a list of elements (eg. an array
+  or a `NodeList`).
+- Each element's text is the console's code, so code that was already
+  highlighted (eg. by Prism or highlight.js) works too.  A `<code>` that is the
+  only thing in a `<pre>` is treated as the `<pre>`.
+- `options` are the same as for `create()` (except `target` and `code`) and
+  apply to every console.  `placement` defaults to `"replace"` and `height`
+  defaults to a height that fits the code (from 250px to 600px).
+- The `data-*` attributes of each element (or its `<pre>`) override the
+  options for that console (eg. `data-theme="dark"` or `data-height="400"`)
+  and a `language-ts` or `language-typescript` class turns on TypeScript.
+- It returns an array with `{element, destroy}` for each console, in the same
+  order as the elements.  Destroying a console that replaced its element puts
+  the element back.
+
+`YourJSBox.version` is the version of YourJS Box that was loaded.
+
+The package includes TypeScript types for `YourJSBox` (`dist/yourjs-box.d.ts`),
+which also give you autocomplete in VS Code.  Install the package (eg.
+`npm install --save-dev yourjs-box`, even if the script itself comes from a
+CDN) and add this line to the top of a TypeScript or JavaScript file:
+
+```js
+/// <reference types="yourjs-box" />
+```
 
 ### Where Code Runs
 
@@ -330,21 +372,25 @@ between blocks.
 Install the development dependencies by running `npm install`.
 
 - `npm run dev` builds, rebuilds whenever one of the files in `src/` changes
-  and serves the examples at http://localhost:3000/examples/ (opening them in
-  your default browser) with the browser reloading automatically after each
-  rebuild.  Use `BROWSER=none npm run dev` to keep it from opening a browser.
+  and serves the landing page and examples at http://localhost:3000/ (opening
+  it in your default browser) with the browser reloading automatically after
+  each rebuild.  Use `BROWSER=none npm run dev` to keep it from opening a browser.
 - `npm run build` builds the files in `dist/` once.
 - `npm test` builds and then runs the browser tests in `test/run.js` using your
   installed copy of Google Chrome (set `CHROME_PATH` to use another Chromium
   based browser).  An internet connection is needed because the console loads
   its libraries from CDNs.  Pass part of a test's name to run only matching
   tests (eg. `node test/run.js module`).
+- As you make changes, add notes for them under **Unreleased** in
+  [CHANGELOG.md](CHANGELOG.md).
 - `npm run release -- <patch|minor|major>` releases a new version:  it checks
-  that you're on an up to date, clean `main`, runs the tests, runs
-  `npm version`, pushes `main` and then the tag (separately, because GitHub
-  Pages doesn't always deploy when they are pushed together), publishes to npm
-  and, once npm lists the new version, purges jsDelivr's cache.  Add
-  `--dry-run` to see what it would do or `--skip-tests` to skip the tests.
+  that you're on an up to date, clean `main` and that CHANGELOG.md has notes
+  under **Unreleased**, runs the tests, runs `npm version` (which also moves
+  those notes into a dated section for the new version), pushes `main` and then
+  the tag (separately, because GitHub Pages doesn't always deploy when they are
+  pushed together), publishes to npm and, once npm lists the new version,
+  purges jsDelivr's cache.  Add `--dry-run` to see what it would do or
+  `--skip-tests` to skip the tests.
 - `npm run record-demo` records `demo.gif` (shown at the top of this README)
   from the built files.  It needs [ffmpeg](https://ffmpeg.org/).
 - `npm run og-image` makes `og-image.png` (the picture shown when the landing
@@ -365,6 +411,11 @@ The options are kept in the URL so the page can be reloaded or shared as is.
 
 Ideas for future versions, roughly from easiest to hardest:
 
+- **Smaller Acorn:** Acorn's package only has an unminified build (about 60 KB
+  compressed).  A minified copy is about 35 KB (jsDelivr makes one
+  automatically, but unpkg and self-hosted copies don't), so Acorn could be
+  loaded from jsDelivr by default or a minified copy could be published with
+  this package.
 - **`data-autorun`:** run every visible block when the page loads.
 - **Autocomplete:** turn on Ace's keyword and snippet completion in the editor.
 - **`data-remember`:** save the editor's code and history in the browser so

package/dist/yourjs-box.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Types for the `YourJSBox` global that loading YourJS Box provides.  See
+ * https://github.com/westc/yourjs-box#javascript-api for more details.
+ *
+ * Use them in TypeScript (or in JavaScript checked by VS Code) with:
+ *   /// <reference types="yourjs-box" />
+ */
+
+declare namespace YourJSBox {
+  /**
+   * The options that can also be set with the `data-*` attributes of a script
+   * tag (eg. `wordWrap` is the same as `data-word-wrap`).
+   */
+  interface ConsoleOptions {
+    /**
+     * `"worker"` (default) runs the code in a Web Worker.  `"window"` runs it
+     * directly in the page.
+     */
+    runner?: 'worker' | 'window';
+    /**
+     * `"classic"` (default) runs each block like a regular `<script>` so
+     * top-level declarations are shared between blocks.  `"module"` runs each
+     * block like a `<script type="module">`.
+     */
+    blockType?: 'classic' | 'module';
+    /** `"javascript"` (default) or `"typescript"`. */
+    language?: 'javascript' | 'typescript';
+    /**
+     * Whether the value of the last expression in each block is shown.
+     * Defaults to `true`.
+     */
+    showResults?: boolean | 'true' | 'false';
+    /** Any block whose header starts with this prefix is hidden but still runs. */
+    hidePrefix?: string;
+    /**
+     * Whether only the editor is shown until there is something in the
+     * output.  Defaults to `true`.
+     */
+    hideEmptyOutput?: boolean | 'true' | 'false';
+    /**
+     * `"vertical"` puts the editor beside the output and `"horizontal"` puts
+     * it below.  If not given, the editor is beside the output unless the
+     * console is narrower than 600px.
+     */
+    dividerOrient?: 'vertical' | 'horizontal';
+    /** If not given, the theme follows the system's color scheme. */
+    theme?: 'light' | 'dark';
+    /** Whether long lines wrap in the editor.  Defaults to `false`. */
+    wordWrap?: boolean | 'true' | 'false';
+    /**
+     * The columns where lines are shown in the editor (eg. `[80, 120]` or
+     * `"80, 120"`).  Defaults to `80` and `""` (or `[]`) shows none.
+     */
+    rulers?: number | number[] | string;
+    /**
+     * `"lazy"` (default) waits to load the console until it is about to be
+     * scrolled into view.  `"eager"` loads it right away.
+     */
+    loading?: 'lazy' | 'eager';
+    /**
+     * Where packages imported by name are loaded from, where `{specifier}` is
+     * replaced by the package (eg. `"https://esm.sh/{specifier}"`, which is
+     * the default).  `""` turns this off.
+     */
+    importsUrl?: string;
+    /**
+     * Where to load Vue, Ace, Prism, Acorn and Babel from, where `{name}` and
+     * `{version}` are replaced by each library's name and version (eg.
+     * `"/node_modules/{name}/"`).  Defaults to unpkg.
+     */
+    librariesUrl?: string;
+  }
+
+  /** Where a console goes relative to its target. */
+  type Placement = 'fill' | 'append' | 'prepend' | 'replace' | 'before' | 'after';
+
+  interface CreateOptions extends ConsoleOptions {
+    /** The element (or a CSS selector for it) that the console is placed relative to. */
+    target: string | Element;
+    /**
+     * `"fill"` (default) replaces the target's contents, `"append"` and
+     * `"prepend"` add the console inside of the target, `"replace"` replaces
+     * the target itself and `"before"` and `"after"` add it next to the target.
+     */
+    placement?: Placement;
+    /**
+     * The CSS height of the console (a number is treated as pixels).
+     * Defaults to `"100%"`.  It is never less than 150px.
+     */
+    height?: string | number;
+    /** The code that the console starts with. */
+    code?: string;
+  }
+
+  interface FromOptions extends ConsoleOptions {
+    /** Defaults to `"replace"`. */
+    placement?: Placement;
+    /**
+     * The CSS height of each console (a number is treated as pixels).
+     * Defaults to a height that fits the code (from 250px to 600px).
+     */
+    height?: string | number;
+  }
+
+  /** A console that was created. */
+  interface Box {
+    /** The console's IFRAME. */
+    readonly element: HTMLIFrameElement;
+    /**
+     * Removes the console, stops its code and closes its pop-out window (in
+     * window mode it also restores the page's `console` functions).  For a
+     * console made by `from()` that replaced its element, the element is put
+     * back.
+     */
+    destroy(): void;
+  }
+}
+
+declare const YourJSBox: {
+  /** The version of YourJS Box that was loaded (eg. `"1.10.0"`). */
+  readonly version: string;
+  /**
+   * Creates a console.
+   * @throws {TypeError} If the target or the placement isn't valid.
+   */
+  create(options: YourJSBox.CreateOptions): YourJSBox.Box;
+  /**
+   * Turns existing elements (eg. the code blocks in a page made from Markdown)
+   * into consoles that start with their code.  The `data-*` attributes of each
+   * element override `options` and a `language-ts` class turns on TypeScript.
+   * @param elements
+   *   A CSS selector, an element or a list of elements (eg. a `NodeList`).
+   * @returns The consoles in the same order as the elements.
+   */
+  from(
+    elements: string | Element | ArrayLike<Element> | Iterable<Element>,
+    options?: YourJSBox.FromOptions
+  ): YourJSBox.Box[];
+};
+
+interface Window {
+  YourJSBox: typeof YourJSBox;
+}