yourjs-box 1.8.0 → 1.10.0

package/README.md

@@ -1,13 +1,14 @@
-# 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)
 
-![JS Box running code one block at a time, expanding an object, showing a table and an error](demo.gif)
+![YourJS Box running code one block at a time, expanding an object, showing a table and an error](demo.gif)
 
 ## Usage
 
@@ -35,6 +36,9 @@ script is also available from unpkg at
 A comment line that ends with `\\` is a header.  Headers split the code into
 blocks which are run one at a time each time the run button is clicked (or
 <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Enter</kbd> is pressed in the editor).
+<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> (or **Run all
+blocks** in the **&#8943;** menu) runs all of the remaining blocks, one after
+another and in order with any hidden blocks.
 
 Hovering over code that already ran shows a "Copy to editor" button which
 copies that code into the editor so that it can be run again, as is or modified.
@@ -43,8 +47,8 @@ If the editor already has code in it you are asked before it is replaced.
 ### Toolbar
 
 - The **&#8943;** button opens a menu (see below).
-- **Clear** removes everything from the console.  Code can also call
-  `console.clear()`.
+- **Clear** (or <kbd>Ctrl</kbd>+<kbd>L</kbd>) removes everything from the
+  console.  Code can also call `console.clear()`.
 - The **layout** button switches between showing the editor beside or below
   the console.
 - **Full screen** shows the console using the whole screen.  If the browser
@@ -62,6 +66,7 @@ If the editor already has code in it you are asked before it is replaced.
   code that hasn't been run yet comes back.  Hidden blocks aren't in the
   history.
 - The **&#8943;** menu has:
+  - **Run all blocks**, which runs all of the remaining blocks.
   - **Text size**, which is remembered for every console on the same site.
   - **Open**, which loads a JavaScript (or TypeScript) file as the code that the console starts
     with (its hidden blocks are hidden and Reset goes back to it).
@@ -78,7 +83,7 @@ If the editor already has code in it you are asked before it is replaced.
   - **Reset**, which clears the console and puts the original code back into
     the editor.  In worker mode this also stops any code that is still running
     (eg. an infinite loop) by starting a new worker.
-  - **About JS Box**
+  - **About YourJS Box**
 
 ### Right-Clicking Values
 
@@ -107,9 +112,12 @@ objects and arrays) for a menu with:
 | `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-empty-output` | `"true"` (default) 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-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-rulers` | The columns where lines are shown in the editor, eg. `"80, 120"`.  Defaults to `"80"` and `""` shows none. |
 | `data-theme` | `"light"` or `"dark"`.  Defaults to following the system's color scheme like the browser's dev tools. |
+| `data-word-wrap` | `"true"` wraps long lines in the editor instead of scrolling sideways. |
 
 ### Results
 
@@ -219,7 +227,7 @@ npm install vue@3.5.43 ace-builds@1.44.0 prismjs@1.30.0 prism-themes@1.9.0 acorn
 npm install @babel/standalone@7.29.9
 ```
 
-The About window lists the versions that each version of JS Box uses.
+The About window lists the versions that each version of YourJS Box uses.
 
 ### Console Functions
 
@@ -228,6 +236,22 @@ The About window lists the versions that each version of JS Box uses.
 `timeLog()`, `timeEnd()`, `trace()`, `group()`, `groupCollapsed()`,
 `groupEnd()` and `clear()` are all shown in the console.
 
+Like the browser's console, the first argument can use format specifiers:
+`%s` (string), `%d` or `%i` (integer), `%f` (number), `%o` and `%O` (a value
+that can be expanded), `%c` (CSS styles for the text after it) and `%%` (a
+percent sign).  For example:
+
+```js
+console.log('%cHello%c, %s!', 'color: white; background: #1a73e8; padding: 2px 6px; border-radius: 4px', '', 'world');
+```
+
+Like the browser, `%c` only allows CSS for things like colors, fonts, borders,
+margins and padding, and never anything that loads a URL.
+
+A message that is the same as the one logged right before it is shown once with
+a count instead of being repeated.  Messages that include objects are always
+shown again since the objects may have changed.
+
 ### Loading
 
 Like `<img loading="lazy">`, a console isn't loaded until it is about to be
@@ -283,9 +307,32 @@ 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. |
+| `runner`, `blockType`, `language`, `showResults`, `hidePrefix`, `hideEmptyOutput`, `dividerOrient`, `theme`, `wordWrap`, `rulers`, `importsUrl`, `librariesUrl`, `loading` | The same as the `data-*` attributes above.  `wordWrap`, `hideEmptyOutput` and `showResults` can be booleans and `rulers` can be an array (eg. `[80, 120]`). |
+
+`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>
+```
 
-`YourJSBox.version` is the version of JS Box that was loaded.
+- `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.
 
 ### Where Code Runs
 
@@ -310,15 +357,17 @@ 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`).
+- Before releasing, move the notes under **Unreleased** in
+  [CHANGELOG.md](CHANGELOG.md) into a section for the new version.
 - `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
@@ -327,6 +376,8 @@ Install the development dependencies by running `npm install`.
   `--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
+  page is shared) from the built files.
 - `npm run purge-cdn` purges jsDelivr's cache so that URLs like
   `yourjs-box@1` point to the latest version right away.
 - In VS Code, **Terminal &rarr; Run Task&hellip;** has tasks for all of these
@@ -343,15 +394,12 @@ 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:
 
-- **Format specifiers:** support `%s`, `%d`, `%i`, `%f`, `%o`, `%O` and `%c`
-  (CSS styles) in `console.log()` and the other logging functions.
-- **Repeated messages:** show identical messages logged in a row once with a
-  count, like the browser's console.
-- **Run all:** run every remaining block with <kbd>Ctrl</kbd> /
-  <kbd>&#8984;</kbd> + <kbd>Shift</kbd> + <kbd>Enter</kbd> or from the
-  **&#8943;** menu.
+- **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.
-- **Clear shortcut:** clear the console with <kbd>Ctrl</kbd> + <kbd>L</kbd>.
 - **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
   that they are still there after a reload.