@fusion.dev/helix 0.0.0-dev

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

@@ -0,0 +1,324 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import '../../splitter/index.js';
+import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
+/**
+ * @summary Pairs an editable source pane with a live preview.
+ *
+ * @description
+ * Coordination is by event, the same way the accordion does it: a source pane
+ * dispatches `helix-before-edit`, which bubbles, and the sandbox hands the value to
+ * whatever preview is slotted into it. Neither child knows the other exists, so
+ * either can be replaced or used alone.
+ *
+ * The event carries the pane's `name`, which is what lets one sandbox hold
+ * several panes without the root identifying senders by reference. `html` is
+ * the preview's markup and `css` is its stylesheet. A pane named anything else
+ * is showing something rather than driving it, and is ignored: the sandbox has
+ * a pane rendering the example as JSX, and guessing would have put the text of
+ * a React component into the preview.
+ *
+ * **The dividers are two nested `helix-splitter`s, not a grid this element
+ * drags itself.** It had its own: a five row grid, a stylesheet written to on
+ * every pointer move, three pointer handlers, a keyboard handler reading which
+ * axes each divider was allowed to move, and a corner placed by hand into the
+ * cell where two tracks met. All of it is the splitter's now, including the
+ * corner, which arrives on its own wherever a nested splitter crosses the one it
+ * is in.
+ *
+ * The panes are the inner splitter and the panel is the outer one, which is the
+ * order that makes the panel span the full width: the outer divider runs edge to
+ * edge and the inner stops at it.
+ *
+ * **Both are controlled from here, so `split` and `panel-size` stay the truth.**
+ * A splitter that owned its own position would leave this element reporting one
+ * arrangement and showing another, and a consumer restoring a saved layout
+ * writes to these two properties. Each splitter announces where it wants to go
+ * and this answers, which is the same contract a form control has with a
+ * framework.
+ *
+ * **The panel is in pixels here and a percentage in the splitter, and the
+ * conversion belongs here.** A terminal wants a number of lines rather than a
+ * share of the window, so its height should not change when the window does. A
+ * splitter has no business knowing that, so it stays percentage-pure and this
+ * element, which does know what is in the panel, holds the box and converts.
+ * That is also what keeps a stored `panelSize` from a previous visit meaning
+ * what it meant when it was written.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category tooling
+ * @aliases Playground, REPL, Editor
+ * @documentation https://helix.fusion.dev/sandbox
+ *
+ * @slot panel - A panel under both panes, usually a terminal.
+ * @slot preview - The live preview. Second unless `lead` says otherwise.
+ * @slot source - The editable source pane. First unless `lead` says otherwise.
+ * @slot status - A status bar, spanning both panes at the bottom.
+ * @slot toolbar - A bar across the top, spanning both panes.
+ *
+ * @event {HelixBeforePanelResizeEvent} helix-before-panel-resize - Fired before the panel's divider is let go, with its height in pixels. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeSplitEvent} helix-before-split - Fired before the panes' divider is let go, with the lead pane's share. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart body - The splitter holding the panes above the panel.
+ * @csspart corner - The handle where the two dividers cross.
+ * @csspart pane - Either pane.
+ * @csspart panel - The box holding whatever was slotted as the panel.
+ * @csspart panes - The splitter holding the source and preview panes.
+ * @csspart separator - Either divider.
+ *
+ * @cssproperty --sandbox-grab - The invisible width of a divider's drag target.
+ * @cssproperty --sandbox-min-block-size - Minimum height of the sandbox.
+ * @cssproperty --sandbox-separator-color - Color of the divider.
+ */
+export declare class HelixSandbox extends HelixElement {
+    /**
+     * Whether the panes sit side by side or stacked.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Which pane comes first, before the divider.
+     *
+     * A sandbox is read in one of two directions and the two are not a
+     * preference. A workbench is a place to write, so the source leads and the
+     * preview answers it. A reference page is a place to look, so the preview
+     * leads and the source is what a reader opens if they want to know how it was
+     * done. Same component, opposite reading order, and no consumer should have
+     * to slot a preview into a hole named `source` to get it.
+     *
+     * Not reflected, because no rule selects on it: the panes already carry
+     * `data-pane`, which is what the stylesheet reaches for, and swapping the
+     * names below keeps that true whichever way round they sit.
+     *
+     * `split` follows the lead pane rather than the source, so `split="30"` means
+     * the same thing in both directions: thirty percent to whatever comes first.
+     */
+    lead: 'source' | 'preview';
+    /**
+     * Percentage of the sandbox given to the source pane.
+     */
+    split: number;
+    /**
+     * Where a reset puts the divider, where nothing declared it.
+     *
+     * Separate from `split` for the reason `Splitter` keeps `default-position`
+     * separate from `position`, and the bug is worth recording because this
+     * element had it after that one was fixed. A double click reset to whatever
+     * `split` held on the first render, which is the declared arrangement only
+     * when nobody owns the property. The workbench owns it, restores it from the
+     * address bar and from storage, so the first value it ever held was the
+     * reader's last session: double clicking reset the sandbox to the size it
+     * already was, which is to say it did nothing at all.
+     *
+     * Declared rather than captured, so it is a number a consumer states and can
+     * change, and it needs no first frame to be read on.
+     */
+    defaultSplit: number;
+    /**
+     * Height of the panel, in pixels.
+     */
+    panelSize: number;
+    /**
+     * What a reset makes the panel, in pixels.
+     *
+     * The pair to `panel-size`.
+     */
+    defaultPanelSize: number;
+    /**
+     * What the panel's height becomes when it is closed.
+     *
+     * Zero closes it outright. A panel whose contents include the control that
+     * reopens it, a row of tabs being the usual one, wants that row left showing,
+     * and only whoever slotted it knows how tall that is.
+     */
+    panelCollapsedSize: number;
+    /**
+     * Accessible name for the panel's divider.
+     */
+    panelLabel: string;
+    /**
+     * Accessible name for the divider that moves both at once.
+     */
+    cornerLabel: string;
+    /**
+     * Accessible name for the divider.
+     */
+    separatorLabel: string;
+    /**
+     * Whether anything is in the panel region.
+     *
+     * The divider above the panel is only meaningful when there is a panel to
+     * size, and there is no way to ask in CSS: `:host(:has([slot="panel"]))` is
+     * invalid, and the server has no children to look at. `slotchange` is the
+     * platform answering on the client, which is where a divider is any use.
+     */
+    private hasPanel;
+    /**
+     * The body's height, which is what a pixel panel is a fraction of.
+     *
+     * The panel is given in pixels and the splitter takes a percentage, so the two
+     * only agree at one height: let the window change without recomputing and a
+     * panel asked for at 192px quietly keeps whatever share of the old height that
+     * was.
+     *
+     * **Measured at render rather than cached from the observer**, which is the
+     * second design here. The first held the number the observer last reported and
+     * was correct only while the observer was firing, and a `ResizeObserver`
+     * callback is delivered from the rendering lifecycle: a background tab runs
+     * none, so the value went stale with nothing to say so. Reading the box at
+     * render leaves one source of truth, and the observer's only job is to say
+     * that a render is due.
+     *
+     * Cheap, because renders are rare. A drag no longer goes through this element
+     * at all: the splitter follows the pointer itself and announces once, when it
+     * settles.
+     */
+    private bodyHeight;
+    /**
+     * Asks for a render when the body changes size.
+     *
+     * The box watched is the splitter itself, not the panel. Its size changes when
+     * the window does and not when the divider moves, so answering it cannot feed
+     * back into the position that answered it.
+     */
+    private readonly watch;
+    /** The panel as a share of the body, which is what the splitter takes. */
+    private get panelShare();
+    /**
+     * Where the outer divider goes: everything the panel is not.
+     *
+     * A hundred with no panel, which puts the divider on the floor of the sandbox
+     * with the panes filling it. The line itself is hidden by the stylesheet in
+     * that case, because a boundary needs two sides.
+     */
+    private get panelPosition();
+    /** Where the panel divider goes on a reset, in the splitter's own units. */
+    private get homePanelPosition();
+    /** `panel-collapsed-size` in the units the splitter works in. */
+    private get panelSliver();
+    /**
+     * Whether a change came from inside this sandbox's source region.
+     *
+     * Structural rather than a type check. It was `instanceof
+     * HelixSandboxSource`, which was right until there was a second kind of
+     * pane: the editor is `@fusion.dev/helix-sandbox/editor`, on its own path because it
+     * carries CodeMirror, and naming its class here would pull that back into
+     * this module for every consumer. Where the event came from is a question
+     * about the tree, and the tree can answer it.
+     */
+    private fromSource;
+    /**
+     * Takes a change from one of this sandbox's own source panes.
+     *
+     * The origin is checked, and has to be. `helix-before-edit` bubbles and composes,
+     * so anything a consumer slots into a sandbox sends one up here too. A
+     * sandbox hears a great deal that is not its source.
+     */
+    private readonly handleSourceChange;
+    /**
+     * Writes the cursor position onto any status bar slotted here.
+     *
+     * The same shape as the source-to-preview hand-off, and for the same reason:
+     * the editor and the bar never speak, so either can be absent. It goes
+     * straight to the element rather than through a property a framework owns,
+     * because this fires on every keystroke and every arrow press.
+     */
+    private readonly handleCaret;
+    /**
+     * The parts of this sandbox it drives, wherever they sit inside it.
+     *
+     * Descendants, not children. A preview and a status bar happen to be slotted
+     * directly, but a terminal lives inside the tab set that holds the panel, so
+     * a search of `children` found none and the console went nowhere. Where a
+     * consumer nests a pane is their arrangement to make.
+     *
+     * Client only: the server has no children to read.
+     */
+    private parts;
+    private get previews();
+    /**
+     * Hands a console line from the preview to any terminal slotted here.
+     *
+     * Every `helix-console` is forwarded, with no check on where it came from.
+     * Unlike a change, which any form control in a sandbox emits, this event is
+     * dispatched by exactly one thing: a preview relaying what the document
+     * inside its frame wrote. There is nothing else here it could be confused
+     * with.
+     */
+    private readonly handleConsole;
+    private get terminals();
+    private get statusBars();
+    /**
+     * The orientation in force.
+     *
+     * Unset is horizontal, and stays unset: the default is the absent attribute,
+     * so a reflected default cannot appear on the host after hydration.
+     */
+    private get axis();
+    /**
+     * Says the panes' divider has settled, so a consumer can keep it.
+     *
+     * When it settles, not while it moves. A drag is a stream of positions and
+     * only the one it ends at is a preference; announcing each would ask whoever
+     * is listening to write to storage a hundred times to record one decision.
+     *
+     * The sandbox does not keep it. Where a preference lives, and whether it
+     * should be kept at all, is the consumer's to decide, and a component that
+     * wrote to storage on its own would be deciding for all of them under a key
+     * it chose.
+     *
+     * **A verb each, where this was one `helix-before-resize` carrying which of the
+     * two had moved.** Both dividers are this element's, so `composedPath()[0]` is
+     * the same host for either and the name is the only thing that can separate
+     * them. It was the last caller of a field every request in the library carried
+     * for it. See 306.
+     */
+    private splitSettled;
+    /** As `splitSettled`, for the panel, whose value is pixels rather than a share. */
+    private panelSettled;
+    /**
+     * Answers a divider that has asked to move.
+     *
+     * Both splitters are controlled from here, so neither applies anything on its
+     * own: each announces where it wants to go and this decides. That is what
+     * keeps `split` and `panelSize` the truth about the arrangement rather than a
+     * stale copy of it.
+     *
+     * `target` against `currentTarget`, because a source pane's own change bubbles
+     * up through these same elements on its way to the host. Only a splitter
+     * speaking for itself is one of ours, and only those are stopped: the sandbox
+     * announces `arrangement` and a consumer never sees the two inside it.
+     */
+    private readonly handlePanesChange;
+    private readonly handlePanelChange;
+    connectedCallback(): void;
+    /** Watches the body, whose height is what the pane sizes are computed from. */
+    private watchBody;
+    /**
+     * Takes the body's height before each render, so the conversion is current.
+     *
+     * Guarded on `hasUpdated`, because there is no shadow root to measure before
+     * the first render, and on the method existing, because the server's element
+     * shim carries attributes but not tree traversal.
+     */
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    /**
+     * Notes whether there is a panel, which is what its dividers depend on.
+     *
+     * Asked of the light DOM rather than of the slot. `slotchange` is the event
+     * that says it changed, and it is listened for, but it is not the only way
+     * to know: a sandbox whose panel was in the markup all along has nothing to
+     * change, and an environment that does not dispatch the event at all leaves
+     * the dividers permanently absent. What is slotted into a named slot is a
+     * question the host can answer directly.
+     */
+    private readonly readPanel;
+    protected render(): TemplateResult;
+    static styles: CSSResultGroup;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-sandbox': HelixSandbox;
+    }
+}