yourjs-box 1.1.2 → 1.3.0

package/README.md

@@ -39,30 +39,97 @@ If the editor already has code in it you are asked before it is replaced.
 
 ### Toolbar
 
-- Clicking the **logo** opens the About window, which
-  shows the version, this console's settings and keyboard shortcuts.  Its
-  **Copy as HTML** tab gives you the HTML for this console (with its current
-  code, its original code or no code) as an embed snippet or a full page that
-  you can copy or download.  Only the `data-*` attributes that were set on the
-  script tag are included.
 - **Clear** removes everything from the console.  Code can also call
   `console.clear()`.
-- **Reset** 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.
-- The layout button switches between showing the editor below or beside the
-  console.
+- **Full screen** shows the console using the whole screen.  If the browser
+  doesn't allow that (eg. on an iPhone) the console fills the browser window
+  instead.  Press <kbd>Esc</kbd> to exit.
 - **Run** runs the next block of code.
+- Clicking the **logo** opens the About window, which shows the version, this
+  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.
+  - **Editor beside / below the console** to change the layout.
+  - **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
+    move the console back into the page.
+  - **Copy as HTML**, which gives you the HTML for this console (with its
+    current code, its original code or no code) as an embed snippet or a full
+    page that you can copy or download.  Only the `data-*` attributes that were
+    set on the script tag are included.
+  - **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**
 
 ### 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-show-results` | `"false"` stops the value of the last expression in each block from being shown. |
+| `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. |
 | `data-hide-prefix` | Any block whose header starts with this prefix is hidden. See below. |
 | `data-theme` | `"light"` or `"dark"`.  Defaults to following the system's color scheme like the browser's dev tools. |
 
+### Results
+
+Like the browser's console, if the last statement in a block is an expression
+(eg. `2 + 2` or `numbers.map(n => n * 2)`) its value is shown after the block
+runs, unless it is `undefined`.  Results aren't shown for hidden blocks.  Use
+`data-show-results="false"` to turn this off.
+
+### Module Blocks
+
+By default each block runs like a regular `<script>`, so variables declared in
+one block can be used in the next, but `await` can only be used inside of
+`async` functions.  With `data-block-type="module"` each block runs like a
+`<script type="module">` instead:
+
+- Top-level `await` works.
+- `import` works (eg. `import {camelCase} from 'https://cdn.jsdelivr.net/npm/lodash-es/+esm';`).
+- Top-level declarations stay inside of their block, just like in a module.
+  Use `globalThis` to share values between blocks.
+
+### Self-Hosting the Libraries
+
+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
+default.  Exact versions are always used so that a new release of one of them
+can't change how the console works.
+
+To load them from somewhere else (eg. your own site, an intranet or another
+CDN) set `data-libraries-url` to a URL where `{name}` and `{version}` are
+replaced with each library's package name and version.  Relative URLs are
+relative to the page.
+
+| Where | `data-libraries-url` |
+| --- | --- |
+| unpkg (the default) | `https://unpkg.com/{name}@{version}/` |
+| jsDelivr | `https://cdn.jsdelivr.net/npm/{name}@{version}/` |
+| Your own copy of `node_modules` | `/node_modules/{name}/` |
+
+To host them yourself, install these exact versions and serve the whole
+package folders (Ace and Prism load other files, such as language modes, from
+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
+```
+
+The About window lists the versions that each version of JS Box uses.
+
+### Console Functions
+
+`console.log()`, `info()`, `warn()`, `error()`, `debug()`, `dir()`,
+`dirxml()`, `table()`, `assert()`, `count()`, `countReset()`, `time()`,
+`timeLog()`, `timeEnd()`, `trace()`, `group()`, `groupCollapsed()`,
+`groupEnd()` and `clear()` are all shown in the console.
+
 ### Hidden Code
 
 If `data-hide-prefix="HIDE"` is specified then a block with a header like
@@ -98,6 +165,11 @@ Install the development dependencies by running `npm install`.
   and serves the examples at http://localhost:3000/examples/ with the browser
   reloading automatically after each rebuild.
 - `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`).
 - `npm start` builds and then rebuilds whenever one of the files in `src/`
   changes (without serving anything).