yourjs-box 1.6.0 → 1.8.0

package/README.md

@@ -2,11 +2,13 @@
 
 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.
+Worker or the page itself.  TypeScript works too.
 
 **[Live demo](https://westc.github.io/yourjs-box/)** ·
 [Examples](https://westc.github.io/yourjs-box/examples/)
 
+![JS 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
@@ -61,10 +63,10 @@ If the editor already has code in it you are asked before it is replaced.
   history.
 - The **⋯** menu has:
   - **Text size**, which is remembered for every console on the same site.
-  - **Open**, which loads a JavaScript file as the code that the console starts
+  - **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).
   - **Save**, which saves the code that already ran and the code in the editor
-    as a JavaScript file that can be opened later.
+    as a JavaScript (or TypeScript) file that can be opened later.
   - **Pop out into a window**, which moves the console into a separate window
     while the code keeps running in the page (so in window mode the code can
     still change the page).  Close the window or click **Bring it back** to
@@ -99,12 +101,14 @@ objects and arrays) for a menu with:
 | 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 and Acorn from.  See "Self-Hosting the Libraries" 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. |
 
 ### Results
@@ -126,6 +130,36 @@ one block can be used in the next, but `await` can only be used inside of
 - Top-level declarations stay inside of their block, just like in a module.
   Use `globalThis` to share values between blocks.
 
+### TypeScript
+
+Add `data-language="typescript"` to write the code in TypeScript:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/yourjs-box@1/dist/yourjs-box.min.js" data-language="typescript">
+  // Describe a person \\
+  interface Person { name: string; born: number }
+  const people: Person[] = [{name: 'Ada', born: 1815}, {name: 'Grace', born: 1906}];
+
+  // Find the oldest \\
+  function oldest<T extends Person>(list: T[]): T {
+    return list.reduce((a, b) => a.born <= b.born ? a : b);
+  }
+  oldest(people)
+</script>
+```
+
+Before each block runs, [Babel](https://babeljs.io/) removes the types, which
+is how most TypeScript tools run code without a build step.  The types aren't
+checked, so code with type errors still runs, just like it would in
+JavaScript.  Enums, namespaces and parameter properties all work, and errors
+point to the lines and columns in the TypeScript code.
+
+TypeScript works with both block types.  Only type imports are removed (eg.
+`import type {Options} from 'x'` or the `type Options` part of
+`import {type Options, format} from 'x'`), so an import is never dropped just
+because nothing uses it yet.  Babel is only downloaded by consoles that use
+TypeScript.
+
 ### Importing Packages
 
 npm packages can be imported by name.  They are loaded from
@@ -158,7 +192,8 @@ To load packages from somewhere else set `data-imports-url` to a URL where
 
 The console's interface uses [Vue](https://vuejs.org/),
 [Ace](https://ace.c9.io/), [Prism](https://prismjs.com/) and
-[Acorn](https://github.com/acornjs/acorn), which are loaded from unpkg by
+[Acorn](https://github.com/acornjs/acorn) (plus
+[Babel](https://babeljs.io/) for TypeScript), which are loaded from unpkg by
 default.  Exact versions are always used so that a new release of one of them
 can't change how the console works.
 
@@ -179,6 +214,9 @@ next to their main files):
 
 ```bash
 npm install vue@3.5.43 ace-builds@1.44.0 prismjs@1.30.0 prism-themes@1.9.0 acorn@8.18.0
+
+# Only needed for TypeScript consoles
+npm install @babel/standalone@7.29.9
 ```
 
 The About window lists the versions that each version of JS Box uses.
@@ -190,14 +228,27 @@ 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.
 
+### 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
 
@@ -232,7 +283,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`, `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.
 
@@ -274,6 +325,8 @@ 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 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
@@ -281,18 +334,42 @@ 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
 
-- Open button - Load a JS file from the filesystem.
-- Save button - Save the current inputs as a JS file that can be opened later.
-- Add `@timeout` annotation to the special comments that will allow you to input the amount of seconds to wait since the last call to a console logging function before automatically running the next comment segmented block.
-- Allow for TypeScript
-- Allow for CoffeeScript
+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.
+- **`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.
+- **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