yourjs-box 1.3.1 → 1.5.0

package/README.md

@@ -24,7 +24,8 @@ should be loaded into the console inside of the script tag:
 </div>
 ```
 
-The console fills its container.  The script is also available from unpkg at
+The console fills its container (and is never less than 150px tall).  The
+script is also available from unpkg at
 `https://unpkg.com/yourjs-box@1/dist/yourjs-box.min.js`.
 
 ### Code Blocks
@@ -51,6 +52,10 @@ If the editor already has code in it you are asked before it is replaced.
   console's settings and keyboard shortcuts.
 - The **&#8943;** button opens a menu with:
   - **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
+    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.
   - **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
@@ -70,6 +75,7 @@ If the editor already has code in it you are asked before it is replaced.
 | --- | --- |
 | `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-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-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. |
@@ -91,10 +97,38 @@ one block can be used in the next, but `await` can only be used inside of
 `<script type="module">` instead:
 
 - Top-level `await` works.
-- `import` works (eg. `import {camelCase} from 'https://cdn.jsdelivr.net/npm/lodash-es/+esm';`).
+- `import` works (eg. `import {camelCase} from 'lodash-es';`).
 - Top-level declarations stay inside of their block, just like in a module.
   Use `globalThis` to share values between blocks.
 
+### Importing Packages
+
+npm packages can be imported by name.  They are loaded from
+[esm.sh](https://esm.sh/), which turns npm packages into modules that work in
+the browser:
+
+```js
+// In module blocks (data-block-type="module")
+import _ from 'lodash';
+import {format} from 'date-fns@4';
+
+// In any block (including classic blocks), inside of async code
+const {default: dayjs} = await import('dayjs');
+```
+
+Relative paths (eg. `./utils.js`), URLs (eg. `https://example.com/x.js`) and
+`node:` imports are left alone.  Packages that need Node.js (eg. ones that use
+`fs`) can't run in a browser.
+
+To load packages from somewhere else set `data-imports-url` to a URL where
+`{specifier}` is replaced with what was imported (eg. `lodash@4/fp`):
+
+| Where | `data-imports-url` |
+| --- | --- |
+| esm.sh (the default) | `https://esm.sh/{specifier}` |
+| jsDelivr | `https://cdn.jsdelivr.net/npm/{specifier}/+esm` |
+| Turned off (only URLs and paths can be imported) | `""` |
+
 ### Self-Hosting the Libraries
 
 The console's interface uses [Vue](https://vuejs.org/),
@@ -140,6 +174,43 @@ 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
+
+Loading the script also provides `YourJSBox` for creating consoles from
+JavaScript (eg. in React, Vue or any page that adds content dynamically).  A
+script tag in the `<head>` only provides the API, while one in the `<body>` is
+also replaced by a console (with the code inside of it) as usual.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/yourjs-box@1/dist/yourjs-box.min.js"></script>
+```
+
+```js
+const box = YourJSBox.create({
+  target: '#lesson',
+  code: "// Say hello \\\\\nconsole.log('Hello!');",
+  theme: 'dark',
+});
+
+// Later (eg. when a component is removed):
+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:
+
+| Option | Description |
+| --- | --- |
+| `target` | Required.  The element (or a CSS selector for it) that the console is placed relative to. |
+| `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. |
+
+`YourJSBox.version` is the version of JS Box that was loaded.
+
 ### Where Code Runs
 
 The console's interface is always in an IFRAME so that its styles and the
@@ -171,6 +242,16 @@ Install the development dependencies by running `npm install`.
   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`).
+- `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.
+- `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
+  (eg. Build, Dev server, Test, Release&hellip; and Redeploy GitHub Pages).
 - `npm start` builds and then rebuilds whenever one of the files in `src/`
   changes (without serving anything).
 
@@ -186,7 +267,6 @@ test `dist/yourjs-box.js` or `dist/yourjs-box.min.js` instead of
 - 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
-- Allow code to run in main window.
 
 ## License