@fusion.dev/helix 0.0.0-dev

package/dist/sandbox/source/sandbox-source.d.ts

@@ -0,0 +1,105 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import type { CSSResultGroup, TemplateResult } from 'lit';
+/**
+ * @summary Editable source for a sandbox preview.
+ *
+ * @description
+ * A real `<textarea>`, not a contenteditable div with a syntax highlighter over
+ * it. Undo, selection, spellcheck suppression, mobile keyboards, and screen
+ * reader support all come from the platform, and every one of them is
+ * expensive to rebuild and easy to get subtly wrong.
+ *
+ * Tab inserts two spaces rather than leaving the field, because a code pane
+ * that cannot indent is not one. Escape then Tab still moves focus out, which
+ * is the documented escape hatch for exactly this trade.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Editor, Code pane
+ * @documentation https://helix.fusion.dev/sandbox/source
+ *
+ * @event {HelixBeforeEditEvent} helix-before-edit - Fired before the source is edited. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixCaretEvent} helix-caret - Fired when the cursor moves.
+ *
+ * @csspart source - The editable region.
+ *
+ * @cssproperty --sandbox-source-background-color - Fill behind the source.
+ * @cssproperty --sandbox-source-min-block-size - Minimum height of the pane.
+ */
+export declare class HelixSandboxSource extends HelixElement {
+    /**
+     * The source being edited.
+     */
+    value: string;
+    /**
+     * Which source this pane holds, echoed in every `helix-before-edit`.
+     *
+     * `html` and `css` are what the sandbox root routes on; any other name is
+     * passed through untouched for a consumer wiring their own panes.
+     *
+     * Not reflected: nothing selects on it, so it keeps a real default instead.
+     */
+    name: string;
+    /**
+     * Accessible name for the editable region.
+     */
+    fieldLabel: string;
+    /**
+     * Whether Tab indents rather than moving focus.
+     */
+    tabIndents: boolean;
+    /** Set by Escape, so the next Tab leaves the field. */
+    private escaped;
+    /**
+     * Reports where the cursor is, for a status bar to read.
+     *
+     * **The shipped shell could not fill its own readout before this.**
+     * `SandboxRoot` binds a `helix-caret` listener and writes `line` and `column`
+     * onto every slotted status bar, and `SandboxStatusBar` renders a `caret` part
+     * as soon as it has both, and both of those ship from `@fusion.dev/helix`. The one
+     * pane that reported a position was `SandboxEditor`, which is in
+     * `@fusion.dev/helix-sandbox` and is `private` while Helix is pre-release. So a
+     * consumer taking the published shell and this pane got a status bar that
+     * could never show a position, and the only fix available to them was a
+     * package they cannot install.
+     *
+     * That is the gap rather than a dead event: the editor has dispatched this
+     * since it was written, and `check:events` has always seen it. What was
+     * missing was the half of the pair that ships.
+     *
+     * The textarea is the only thing that knows, so this is where it belongs.
+     * One-based on both axes, which is what an editor shows and what the detail's
+     * own documentation says.
+     */
+    private readonly reportCaret;
+    /**
+     * Announces the edit, then applies it if nobody refused.
+     *
+     * **This was the other way round, so `helix-before-edit` was a `before` event
+     * that had already happened.** The value was assigned and the request
+     * dispatched after it, which means `preventDefault()` was accepted and
+     * ignored: a consumer refusing an edit kept the old value in their handler and
+     * the pane held the new one. Every other `before` event in this library is
+     * announced first and applied only if the request stands, and this is that.
+     *
+     * `restoreValue` because the textarea has already taken the character
+     * whichever way it goes, so a refusal has to put the text back, and it does so
+     * without sending the caret to the end. Exactly what `Input` does with the
+     * same helper for the same reason. */
+    private readonly handleInput;
+    /**
+     * The one place an edit is taken, so a refusal cannot be forgotten at one of them.
+     *
+     * Two paths reach it, a keystroke and the tab that indents, and the second had
+     * the same fault as the first with its own copy of the code.
+     */
+    private edit;
+    private readonly handleKeydown;
+    protected render(): TemplateResult;
+    static styles: CSSResultGroup;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-sandbox-source': HelixSandboxSource;
+    }
+}

package/dist/sandbox/source/sandbox-source.js

@@ -0,0 +1,173 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixBeforeEditEvent, HelixCaretEvent, HelixElement, onUnlessFalse, restoreValue, } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { styles } from './sandbox-source.css.js';
+/**
+ * @summary Editable source for a sandbox preview.
+ *
+ * @description
+ * A real `<textarea>`, not a contenteditable div with a syntax highlighter over
+ * it. Undo, selection, spellcheck suppression, mobile keyboards, and screen
+ * reader support all come from the platform, and every one of them is
+ * expensive to rebuild and easy to get subtly wrong.
+ *
+ * Tab inserts two spaces rather than leaving the field, because a code pane
+ * that cannot indent is not one. Escape then Tab still moves focus out, which
+ * is the documented escape hatch for exactly this trade.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Editor, Code pane
+ * @documentation https://helix.fusion.dev/sandbox/source
+ *
+ * @event {HelixBeforeEditEvent} helix-before-edit - Fired before the source is edited. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixCaretEvent} helix-caret - Fired when the cursor moves.
+ *
+ * @csspart source - The editable region.
+ *
+ * @cssproperty --sandbox-source-background-color - Fill behind the source.
+ * @cssproperty --sandbox-source-min-block-size - Minimum height of the pane.
+ */
+let HelixSandboxSource = class HelixSandboxSource extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * The source being edited.
+         */
+        this.value = '';
+        /**
+         * Which source this pane holds, echoed in every `helix-before-edit`.
+         *
+         * `html` and `css` are what the sandbox root routes on; any other name is
+         * passed through untouched for a consumer wiring their own panes.
+         *
+         * Not reflected: nothing selects on it, so it keeps a real default instead.
+         */
+        this.name = 'html';
+        /**
+         * Accessible name for the editable region.
+         */
+        this.fieldLabel = 'Example source';
+        /**
+         * Whether Tab indents rather than moving focus.
+         */
+        this.tabIndents = true;
+        /** Set by Escape, so the next Tab leaves the field. */
+        this.escaped = false;
+        /**
+         * Reports where the cursor is, for a status bar to read.
+         *
+         * **The shipped shell could not fill its own readout before this.**
+         * `SandboxRoot` binds a `helix-caret` listener and writes `line` and `column`
+         * onto every slotted status bar, and `SandboxStatusBar` renders a `caret` part
+         * as soon as it has both, and both of those ship from `@fusion.dev/helix`. The one
+         * pane that reported a position was `SandboxEditor`, which is in
+         * `@fusion.dev/helix-sandbox` and is `private` while Helix is pre-release. So a
+         * consumer taking the published shell and this pane got a status bar that
+         * could never show a position, and the only fix available to them was a
+         * package they cannot install.
+         *
+         * That is the gap rather than a dead event: the editor has dispatched this
+         * since it was written, and `check:events` has always seen it. What was
+         * missing was the half of the pair that ships.
+         *
+         * The textarea is the only thing that knows, so this is where it belongs.
+         * One-based on both axes, which is what an editor shows and what the detail's
+         * own documentation says.
+         */
+        this.reportCaret = (event) => {
+            const field = event.target;
+            const at = field.selectionStart ?? 0;
+            const before = field.value.slice(0, at);
+            this.dispatchEvent(new HelixCaretEvent({
+                column: at - (before.lastIndexOf('\n') + 1) + 1,
+                line: before.split('\n').length,
+            }));
+        };
+        /**
+         * Announces the edit, then applies it if nobody refused.
+         *
+         * **This was the other way round, so `helix-before-edit` was a `before` event
+         * that had already happened.** The value was assigned and the request
+         * dispatched after it, which means `preventDefault()` was accepted and
+         * ignored: a consumer refusing an edit kept the old value in their handler and
+         * the pane held the new one. Every other `before` event in this library is
+         * announced first and applied only if the request stands, and this is that.
+         *
+         * `restoreValue` because the textarea has already taken the character
+         * whichever way it goes, so a refusal has to put the text back, and it does so
+         * without sending the caret to the end. Exactly what `Input` does with the
+         * same helper for the same reason. */
+        this.handleInput = (event) => {
+            const field = event.target;
+            this.edit(field, field.value);
+            this.reportCaret(event);
+        };
+        this.handleKeydown = (event) => {
+            if (event.key === 'Escape') {
+                this.escaped = true;
+                return;
+            }
+            if (event.key !== 'Tab' || !this.tabIndents || this.escaped) {
+                this.escaped = false;
+                return;
+            }
+            event.preventDefault();
+            const field = event.target;
+            const { selectionEnd, selectionStart, value } = field;
+            field.value = `${value.slice(0, selectionStart)}  ${value.slice(selectionEnd)}`;
+            field.selectionStart = selectionStart + 2;
+            field.selectionEnd = field.selectionStart;
+            this.edit(field, field.value);
+        };
+    }
+    /**
+     * The one place an edit is taken, so a refusal cannot be forgotten at one of them.
+     *
+     * Two paths reach it, a keystroke and the tab that indents, and the second had
+     * the same fault as the first with its own copy of the code.
+     */
+    edit(field, next) {
+        const request = new HelixBeforeEditEvent({ value: next });
+        if (this.dispatchEvent(request)) {
+            this.value = next;
+        }
+        restoreValue(field, this.value);
+    }
+    render() {
+        return html `<textarea
+      part="source"
+      aria-label=${this.fieldLabel}
+      spellcheck="false"
+      .value=${this.value}
+      @focus=${this.reportCaret}
+      @input=${this.handleInput}
+      @keydown=${this.handleKeydown}
+      @keyup=${this.reportCaret}
+      @pointerup=${this.reportCaret}
+    ></textarea>`;
+    }
+    static { this.styles = styles; }
+};
+__decorate([
+    property()
+], HelixSandboxSource.prototype, "value", void 0);
+__decorate([
+    property()
+], HelixSandboxSource.prototype, "name", void 0);
+__decorate([
+    property({ attribute: 'field-label' })
+], HelixSandboxSource.prototype, "fieldLabel", void 0);
+__decorate([
+    property({ attribute: 'tab-indents', converter: onUnlessFalse })
+], HelixSandboxSource.prototype, "tabIndents", void 0);
+HelixSandboxSource = __decorate([
+    customElement('helix-sandbox-source')
+], HelixSandboxSource);
+export { HelixSandboxSource };

package/dist/sandbox/status-bar/sandbox-status-bar.css.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/sandbox/status-bar/sandbox-status-bar.css.js

@@ -0,0 +1,23 @@
+// Generated from src/sandbox/status-bar/sandbox-status-bar.css by `bun run styles`. Do not edit.
+import { createSheet } from '@fusion.dev/helix-core';
+export const styles = createSheet(`:host {
+align-items: center;
+background-color: var(--helix-color-background);
+border-block-start: var(--helix-border-thin) solid var(--helix-color-border);
+color: var(--sandbox-status-bar-color, var(--helix-color-foreground-subtle));
+display: flex;
+font-size: var(--helix-text-xs);
+gap: var(--helix-space-sm);
+line-height: var(--helix-leading-tight);
+padding: var(--helix-space-2xs) var(--helix-space-sm);
+
+user-select: none;
+}
+
+slot:first-child + * {
+margin-inline-start: auto;
+}
+
+[part="caret"] {
+font-variant-numeric: tabular-nums;
+}`);

package/dist/sandbox/status-bar/sandbox-status-bar.d.ts

@@ -0,0 +1,59 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import type { CSSResultGroup, TemplateResult } from 'lit';
+/**
+ * @summary Reports where the cursor is and what is being edited.
+ *
+ * @description
+ * Slotted into a sandbox, which feeds it: the editor dispatches `helix-caret`
+ * on every keystroke and every arrow press, the sandbox hears it and writes the
+ * position here. Nothing about that reaches the consumer's framework, which is
+ * the point. A caret position routed through React state would re-render the
+ * workbench on every cursor move, to update two numbers.
+ *
+ * **Not a live region.** The readout changes on every keystroke, so announcing
+ * it would talk over the reader continuously while they type. It is text they
+ * can navigate to, which is what a status bar is in every editor that has one.
+ *
+ * A readout with nothing to say is not rendered at all rather than rendered
+ * empty, or the bar keeps a gap where a value is not.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Status line
+ * @documentation https://helix.fusion.dev/sandbox/status-bar
+ *
+ * @slot - Items at the start of the bar.
+ * @slot end - Items after the readouts, at the end of the bar.
+ *
+ * @csspart caret - The line and column readout.
+ * @csspart language - The language readout.
+ *
+ * @cssproperty --sandbox-status-bar-color - Color of the bar's text.
+ */
+export declare class HelixSandboxStatusBar extends HelixElement {
+    /**
+     * One-based column of the cursor.
+     *
+     * Absent shows no readout.
+     */
+    column?: number;
+    /**
+     * The language being edited, as a name or one the editor knows.
+     */
+    language?: string;
+    /**
+     * One-based line of the cursor.
+     *
+     * Absent shows no readout.
+     */
+    line?: number;
+    /** How the position reads, or nothing when there is no cursor to report. */
+    private get position();
+    protected render(): TemplateResult;
+    static styles: CSSResultGroup;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-sandbox-status-bar': HelixSandboxStatusBar;
+    }
+}

package/dist/sandbox/status-bar/sandbox-status-bar.js

@@ -0,0 +1,86 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { styles } from './sandbox-status-bar.css.js';
+/**
+ * How a language is written out, for the ones an editor knows.
+ *
+ * A map rather than the raw value, because `html` in a status bar reads as a
+ * variable name where `HTML` reads as a language. Anything unlisted shows as
+ * given, so a consumer naming their own language is not silently blanked.
+ */
+const LABELS = {
+    css: 'CSS',
+    html: 'HTML',
+    javascript: 'JavaScript',
+    tsx: 'TSX',
+};
+/**
+ * @summary Reports where the cursor is and what is being edited.
+ *
+ * @description
+ * Slotted into a sandbox, which feeds it: the editor dispatches `helix-caret`
+ * on every keystroke and every arrow press, the sandbox hears it and writes the
+ * position here. Nothing about that reaches the consumer's framework, which is
+ * the point. A caret position routed through React state would re-render the
+ * workbench on every cursor move, to update two numbers.
+ *
+ * **Not a live region.** The readout changes on every keystroke, so announcing
+ * it would talk over the reader continuously while they type. It is text they
+ * can navigate to, which is what a status bar is in every editor that has one.
+ *
+ * A readout with nothing to say is not rendered at all rather than rendered
+ * empty, or the bar keeps a gap where a value is not.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Status line
+ * @documentation https://helix.fusion.dev/sandbox/status-bar
+ *
+ * @slot - Items at the start of the bar.
+ * @slot end - Items after the readouts, at the end of the bar.
+ *
+ * @csspart caret - The line and column readout.
+ * @csspart language - The language readout.
+ *
+ * @cssproperty --sandbox-status-bar-color - Color of the bar's text.
+ */
+let HelixSandboxStatusBar = class HelixSandboxStatusBar extends HelixElement {
+    /** How the position reads, or nothing when there is no cursor to report. */
+    get position() {
+        if (this.line === undefined || this.column === undefined) {
+            return undefined;
+        }
+        return `Ln ${this.line}, Col ${this.column}`;
+    }
+    render() {
+        const language = this.language;
+        const position = this.position;
+        return html `<slot></slot>
+      ${position === undefined ? nothing : html `<span part="caret">${position}</span>`}
+      ${language === undefined
+            ? nothing
+            : html `<span part="language">${LABELS[language] ?? language}</span>`}
+      <slot name="end"></slot>`;
+    }
+    static { this.styles = styles; }
+};
+__decorate([
+    property({ type: Number })
+], HelixSandboxStatusBar.prototype, "column", void 0);
+__decorate([
+    property()
+], HelixSandboxStatusBar.prototype, "language", void 0);
+__decorate([
+    property({ type: Number })
+], HelixSandboxStatusBar.prototype, "line", void 0);
+HelixSandboxStatusBar = __decorate([
+    customElement('helix-sandbox-status-bar')
+], HelixSandboxStatusBar);
+export { HelixSandboxStatusBar };

package/dist/sandbox/terminal/sandbox-terminal.css.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/sandbox/terminal/sandbox-terminal.css.js

@@ -0,0 +1,69 @@
+// Generated from src/sandbox/terminal/sandbox-terminal.css by `bun run styles`. Do not edit.
+import { createSheet } from '@fusion.dev/helix-core';
+export const styles = createSheet(`:host {
+
+block-size: var(--sandbox-terminal-size, 100%);
+display: grid;
+grid-template-rows: minmax(0, 1fr);
+min-block-size: 0;
+}
+
+[part="log"] {
+font-family: var(--helix-font-mono);
+font-size: var(--helix-text-xs);
+line-height: var(--helix-leading-normal);
+overflow: auto;
+padding: var(--helix-space-xs) var(--helix-space-sm);
+}
+
+[part="log"]:focus-visible {
+outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);
+outline-offset: calc(var(--helix-size-focus-offset) * -1);
+}
+
+[part="empty"] {
+color: var(--helix-color-foreground-subtle);
+margin: var(--helix-space-none);
+}
+
+[part="entry"] {
+align-items: baseline;
+color: var(--helix-color-foreground-muted);
+display: grid;
+gap: var(--helix-space-xs);
+grid-template-columns: 3.5rem minmax(0, 1fr) auto;
+padding-block: var(--helix-space-2xs);
+}
+
+[part="level"] {
+color: var(--helix-color-foreground-subtle);
+text-transform: uppercase;
+}
+
+[part="message"] {
+white-space: pre-wrap;
+word-break: break-word;
+}
+
+[part="count"] {
+background-color: var(--helix-color-surface-sunken);
+border-radius: var(--helix-radii-full);
+color: var(--helix-color-foreground-subtle);
+padding-inline: var(--helix-space-2xs);
+}
+
+[part="entry"][data-level="warn"] {
+color: var(--helix-color-warning);
+}
+
+[part="entry"][data-level="warn"] [part="level"] {
+color: var(--helix-color-warning);
+}
+
+[part="entry"][data-level="error"] {
+color: var(--helix-color-danger);
+}
+
+[part="entry"][data-level="error"] [part="level"] {
+color: var(--helix-color-danger);
+}`);

package/dist/sandbox/terminal/sandbox-terminal.d.ts

@@ -0,0 +1,71 @@
+import { type ConsoleDetail, HelixElement } from '@fusion.dev/helix-core';
+import type { CSSResultGroup, TemplateResult } from 'lit';
+/**
+ * @summary Shows what the previewed example wrote to the console.
+ *
+ * @description
+ * Fed by the sandbox, which hears `helix-console` from the preview and hands it
+ * here. The preview is a separate document, so what arrives has already crossed
+ * `postMessage`: text, not values.
+ *
+ * **Repeats collapse.** An example with a render loop can write the same
+ * warning hundreds of times, and two hundred identical lines say nothing that
+ * one line and a count does not. Only consecutive repeats collapse, so the
+ * order of what happened survives.
+ *
+ * A `role="log"` rather than a live region by hand. It is the semantic for an
+ * append-only stream, and it means a reader is told about new output without
+ * the whole panel being re-announced each time.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Console, Output
+ * @documentation https://helix.fusion.dev/sandbox/terminal
+ *
+ * @csspart count - How many times a repeated line arrived.
+ * @csspart empty - Shown while nothing has been written.
+ * @csspart entry - One line.
+ * @csspart level - The level a line came in at.
+ * @csspart log - The scrolling region.
+ * @csspart message - The text of a line.
+ *
+ * @cssproperty --sandbox-terminal-size - Height of the scrolling region.
+ */
+export declare class HelixSandboxTerminal extends HelixElement {
+    /**
+     * What to show before anything has been written.
+     */
+    emptyLabel: string;
+    /**
+     * Accessible name for the log.
+     */
+    label: string;
+    private entries;
+    /**
+     * Whether the reader is at the bottom, and so wants to follow new output.
+     *
+     * Read before the render that adds a line and applied after it. Scrolling to
+     * the bottom on every line would drag a reader off whatever they had scrolled
+     * up to look at, which for a log of errors is the one thing they are doing.
+     */
+    private following;
+    private get log();
+    /**
+     * Adds a line, collapsing it into the one above when they are identical.
+     *
+     * `write` rather than `append`, which every element already has from
+     * `ParentNode` and which takes nodes. Shadowing it would break
+     * `terminal.append(node)` for anyone who reasonably expected the DOM method.
+     */
+    write(detail: ConsoleDetail): void;
+    /** Empties the log. */
+    clear(): void;
+    protected updated(): void;
+    protected render(): TemplateResult;
+    static styles: CSSResultGroup;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-sandbox-terminal': HelixSandboxTerminal;
+    }
+}