@fusion.dev/helix-sandbox 0.0.0-dev

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fusion Development Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @fusion.dev/helix-sandbox
+
+A source editor for the Helix sandbox, and a code highlighter for Code Block.
+The editor is CodeMirror in a custom element. The highlighter is Lezer's
+grammars with no editor, so it also runs on a server.
+
+```sh
+npm install @fusion.dev/helix @fusion.dev/helix-styles @fusion.dev/helix-sandbox
+```
+
+| Entry | What it does |
+|---|---|
+| `@fusion.dev/helix-sandbox` | Exports what `/highlight` exports, and the editor's types. Registers nothing |
+| `@fusion.dev/helix-sandbox/code-block` | Colors every Code Block on the page |
+| `@fusion.dev/helix-sandbox/editor` | Registers `helix-sandbox-editor` |
+| `@fusion.dev/helix-sandbox/highlight` | Turns a snippet into highlighted HTML |
+
+The editor and the highlighter color code from the `--helix-color-syntax-*`
+tokens, which `@fusion.dev/helix-styles` defines, so load its `helix.css` on
+the page.
+
+## The editor
+
+`helix-sandbox-editor` is a source pane for the sandbox in
+`@fusion.dev/helix/sandbox`. Put it in the sandbox's `source` slot and name the
+source it holds, `html` or `css`, as you would a `helix-sandbox-source`:
+
+```html
+<helix-sandbox>
+  <helix-sandbox-editor
+    language="html"
+    name="html"
+    slot="source"
+    value="<p>Hello</p>"
+  ></helix-sandbox-editor>
+  <helix-sandbox-preview slot="preview"></helix-sandbox-preview>
+</helix-sandbox>
+```
+
+```js
+import '@fusion.dev/helix/sandbox'
+import '@fusion.dev/helix-sandbox/editor'
+```
+
+- `language` is `css`, `html`, `js`, `jsx`, `mjs`, `sh`, `ts`, or `tsx`. A
+  name the editor does not read draws the source plain, and the console says
+  so once.
+- `value` is the source. Setting it replaces the source and sends no edit
+  event.
+- `readonly` stops typing. A reader can still select and scroll.
+- `field-label` names the editable region for a screen reader.
+
+Each edit is `helix-before-edit` first, which you can cancel to refuse it, and
+`helix-edit` once the editor holds it. `helix-caret` reports the line and
+column for the sandbox's status bar. The editor is `:state(modified)` while it
+holds an edit, and `reset()` puts back the source it was given.
+
+Tab indents by two spaces. Escape, then Tab, moves focus out of the editor.
+
+The [Sandbox reference](https://fusion.dev/helix/components/sandbox#helix-sandbox-editor)
+lists every property, event, method, and state of the editor. The package
+ships its own `api.json` and `lint.json`, so `helix api family sandbox` lists
+the editor beside the shell, and `helix scan` checks the attributes you write
+on it.
+
+## The highlighter
+
+`highlight` turns a snippet into HTML with a span for each token. It runs
+anywhere, on a server included, so a static page can ship colored code with no
+script:
+
+```js
+import { highlight, syntaxHighlighter, syntaxRules } from '@fusion.dev/helix-sandbox/highlight'
+
+const markup = highlight('const total = 1', 'ts', syntaxHighlighter)
+```
+
+It reads `css`, `html`, `js`, `sh`, `ts`, and `tsx`, and `languageOf` reads the
+names a page writes for them, such as `TypeScript`, `jsx`, or `bash`. Each span
+carries Lezer's `tok-` classes unless you pass a highlighter of your own.
+`syntaxHighlighter` gives the editor's classes, and `syntaxRules` is the CSS
+that colors them.
+
+To color every Code Block on the page, import the `code-block` entry beside
+the block's:
+
+```js
+import '@fusion.dev/helix/code-block'
+import '@fusion.dev/helix-sandbox/code-block'
+```
+
+A block reads its `language` by any name `languageOf` reads, and a language it
+does not read is drawn plain. A block's own `highlight` wins.
+
+## With the sandbox
+
+The sandbox shell, its preview, and `helix-sandbox-source` are in
+`@fusion.dev/helix/sandbox`, and they work without this package. The preview
+runs each example in a frame of its own. The
+[sandbox guide](https://fusion.dev/helix/docs/sandbox) says how to give it a
+frame that loads your components.
+
+## Working on it
+
+```sh
+bunx turbo run build --filter @fusion.dev/helix-sandbox   # styles, analyze, tsc
+bun run --filter @fusion.dev/helix-sandbox test           # dom, then ssr
+```
+
+`helix/CONVENTIONS.md` applies here, and `helix component` holds the editor to
+it. The spec runner and `jsxToHtml`, which the sandbox page on fusion.dev
+uses, are in `helix/workbench`.

package/api.json

@@ -0,0 +1 @@
+{"families":[{"contributes":true,"elements":[{"attributes":[{"description":"Accessible name for the editable region.","name":"field-label","type":"string"},{"description":"The language of the source, which decides how it is highlighted. A name\nthe editor does not read draws the source plain.","name":"language","type":"'css' | 'html' | 'javascript' | 'js' | 'jsx' | 'mjs' | 'sh' | 'ts' | 'tsx'"},{"description":"Which source this pane holds, echoed in every change.","name":"name","type":"string"},{"description":"Whether the text can be changed.\n\n`EditorState.readOnly` rather than removing the editor's focus or its\nkeymap: a reader still needs to select the text, scroll it, and put a\ncursor in it to read a long line. What it stops is the typing.","name":"readonly","type":"boolean"},{"description":"The source being edited.","name":"value","type":"string"}],"cssParts":[{"description":"The element CodeMirror is mounted into.","name":"editor","type":""}],"cssProperties":[],"cssStates":[{"description":"While the source differs from the source the editor was given, until `reset()` or a new `value`.","name":"modified","type":""},{"description":"Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.","name":"settled","type":""}],"description":"CodeMirror, not a `<textarea>`. A textarea cannot highlight what it holds,\nnumber its lines, or say where the cursor is, and a status bar reading line\nand column has to ask something.\n\n**On its own path.** This is `@fusion.dev/helix-sandbox/editor`, and the\npackage's root exports its class as a type only, because CodeMirror is most\nof what the package weighs over the wire. A sandbox with no editable pane\npays for none, and neither does a site that registers its elements once.\n\n`language` names the grammar by the name a file or a sandbox pane carries:\n`css`, `html`, `js`, `jsx`, `mjs`, `sh`, `ts` or `tsx`. A name the editor\ndoes not read draws the source plain, and the console says so once.\n\nEach edit a reader makes is `helix-before-edit` first, which you can cancel\nto refuse the edit, and `helix-edit` once the source holds it, as\n`helix-sandbox-source` sends them. A `value` set from outside is the source the editor is given, and\nsends neither. **The editor is `:state(modified)` while its source differs\nfrom the source it was given**, the first `value` or the last one set from\noutside, and `reset()` puts that source back as an edit.\n\nThe view is built once and reconfigured, not rebuilt. Replacing it on every\nchange would throw away the undo history, the scroll position, and the\nselection, which is most of what an editor is.","entry":"editor","events":[{"bubbles":true,"description":"Fired before the source is edited. Cancelable: refusing it takes the decision and nothing moves.","name":"helix-before-edit","reactProp":"onhelix-before-edit","type":"HelixBeforeEditEvent"},{"bubbles":true,"description":"Fired when the cursor moves, with its line and column.","name":"helix-caret","reactProp":"onhelix-caret","type":"HelixCaretEvent"},{"bubbles":true,"description":"Fired after the source was edited, with the new source.","name":"helix-edit","reactProp":"onhelix-edit","type":"HelixEditEvent"}],"label":"Sandbox Editor","methods":[{"description":"Puts back the source the editor was given, as an edit: `helix-before-edit`\nis sent first and can refuse it, and a sandbox passes it to its preview.","name":"reset","type":"() => void"},{"description":"Moves focus into the text, not onto the host.\n\nThe host is not focusable: what a reader types into is CodeMirror's\ncontenteditable, several nodes down inside this shadow root. Without this,\n`editor.focus()` from outside silently does nothing.","name":"focus","type":"() => void"}],"package":"@fusion.dev/helix-sandbox","part":"Editor","properties":[{"default":"'Example source'","description":"Accessible name for the editable region.","name":"fieldLabel","readonly":false,"references":[],"type":"string"},{"default":"'html'","description":"The language of the source, which decides how it is highlighted. A name\nthe editor does not read draws the source plain.","name":"language","readonly":false,"references":[],"type":"'css' | 'html' | 'javascript' | 'js' | 'jsx' | 'mjs' | 'sh' | 'ts' | 'tsx'"},{"default":"'html'","description":"Which source this pane holds, echoed in every change.","name":"name","readonly":false,"references":[],"type":"string"},{"default":"false","description":"Whether the text can be changed.\n\n`EditorState.readOnly` rather than removing the editor's focus or its\nkeymap: a reader still needs to select the text, scroll it, and put a\ncursor in it to read a long line. What it stops is the typing.","name":"readOnly","readonly":false,"references":[],"type":"boolean"},{"default":"''","description":"The source being edited.","name":"value","readonly":false,"references":[],"type":"string"},{"default":"","description":"Whether the source differs from the source the editor was given: its\nfirst `value`, or the last one set from outside.","name":"modified","readonly":true,"references":[],"type":"boolean"},{"default":"","description":"Where the cursor is, counted from one, as an editor reports it.","name":"caret","readonly":true,"references":[],"type":"CaretDetail"},{"default":"new Promise<void>((resolve) => { this.resolveSettled = resolve })","description":"Resolves a frame after the first update, when transitions are switched on.\n\n**Named `whenSettled` because `settled` is taken four times over**, by\nImage, Splitter and both color controls, none of them about transitions. A\nbase class takes the name every subclass then cannot use.\n\n**The state it reports cannot be watched, which is why this exists.** A\ncustom state is deliberately not in the DOM, so there is no\n`MutationObserver` equivalent for `ElementInternals.states`. Await this\ninstead.\n\nSeparate from `updateComplete`, which resolves in the microtask checkpoint\nthe suppression is still active in. That is the distinction `readyToMove`\nin `@fusion.dev/helix-testing` is written around.\n\nIt never resolves where `requestAnimationFrame` never fires, which is a\nserver, a hidden tab, and happy-dom. Callers that must not hang there race\nit against a timeout, as the happy-dom harness's `readyToMove` does. The\nbrowser harness's awaits it alone: a browser always runs the frame, and a\ntimer beside it was a bet on how long one takes, which a busy run lost.","name":"whenSettled","readonly":true,"references":[],"type":"Promise<void>"}],"slots":[],"specifier":"@fusion.dev/helix-sandbox/editor","status":"experimental","summary":"An editable pane of source, with highlighting and line numbers.","tagName":"helix-sandbox-editor","tier":"styled","words":["fieldLabel"]}],"label":"Sandbox","package":"@fusion.dev/helix","slug":"sandbox"}],"package":"@fusion.dev/helix-sandbox"}