yourjs-box 1.7.0 → 1.9.0

package/README.md

@@ -7,6 +7,8 @@ Worker or the page itself.  TypeScript works too.
 **[Live demo](https://westc.github.io/yourjs-box/)** ·
 [Examples](https://westc.github.io/yourjs-box/examples/)
 
+![YourJS Box running code one block at a time, expanding an object, showing a table and an error](demo.gif)
+
 ## Usage
 
 Add the script wherever you want the console to appear and put the code that
@@ -33,6 +35,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.
@@ -41,8 +46,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
@@ -60,6 +65,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).
@@ -76,7 +82,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
 
@@ -106,6 +112,7 @@ objects and arrays) for a menu with:
 | `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. |
 
 ### Results
@@ -216,7 +223,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
 
@@ -225,14 +232,43 @@ 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
+scrolled into view, so a page with many consoles (eg. a long tutorial) only
+loads the ones that are read.  A console that is hidden (eg. in a closed tab)
+loads once it is shown.  Its space in the page is kept while it waits, so
+nothing moves around when it loads.
+
+Until a console loads none of its code runs, including hidden blocks, and in
+window mode the page's `console` functions aren't captured yet.  Add
+`data-loading="eager"` to load a console right away (eg. if its hidden blocks
+set up something that the page needs).
+
 ### Hidden Code
 
 If `data-hide-prefix="HIDE"` is specified then a block with a header like
 `// HIDE: Setup \\` will not be shown in the editor.  Instead it runs
-automatically as soon as all of the code that came before it has run.  It shows
-up in the output as a collapsed block labelled with whatever came after the
-prefix (and optional colon), or "Hidden code" if nothing did.  Clicking the
-label shows or hides the code.
+automatically (once the console loads) as soon as all of the code that came
+before it has run.  It shows up in the output as a collapsed block labelled
+with whatever came after the prefix (and optional colon), or "Hidden code" if
+nothing did.  Clicking the label shows or hides the code.
 
 ### JavaScript API
 
@@ -267,7 +303,7 @@ 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` | The same as the `data-*` attributes above. |
+| `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.
 
@@ -309,6 +345,10 @@ Install the development dependencies by running `npm install`.
   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
+  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
@@ -316,10 +356,34 @@ Install the development dependencies by running `npm install`.
 - `npm start` builds and then rebuilds whenever one of the files in `src/`
   changes (without serving anything).
 
-The kitchen sink example (`examples/kitchen-sink.html`) has several consoles
-which cover every feature.  Add `?build=standard` or `?build=min` to its URL to
-test `dist/yourjs-box.js` or `dist/yourjs-box.min.js` instead of
-`dist/yourjs-box.full.js`.
+The kitchen sink example (`examples/kitchen-sink.html`) has a sidebar for
+choosing an example and every option, including which build is loaded
+(`dist/yourjs-box.full.js`, `dist/yourjs-box.js` or `dist/yourjs-box.min.js`).
+The options are kept in the URL so the page can be reloaded or shared as is.
+
+## Roadmap
+
+Ideas for future versions, roughly from easiest to hardest:
+
+- **`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
+  that they are still there after a reload.
+- **Copy output:** copy everything in the console as text from the **&#8943;**
+  menu.
+- **Clickable error locations:** clicking `snippet-2.js:3:7` in an error
+  highlights that line in the code that ran.
+- **More JavaScript API:** `box.run()`, `box.runAll()`, `box.reset()`,
+  `box.setCode()` and events (eg. `box.on('log', ...)`) so that a page can
+  control the console.
+- **Output filter:** search the output and show only errors, warnings or logs.
+- **Exercises:** hidden blocks that check the code above them and show which
+  checks passed (eg. "`sum(2, 3)` should be `5`").
+- **`@timeout`:** an annotation in a block's header that runs the block
+  automatically once nothing has been logged for the given number of seconds.
+- **Long output:** keep the console fast when thousands of messages are logged.
+- **Accessibility:** announce new output to screen readers and make every value
+  and menu reachable with the keyboard.
 
 ## License