@fusion.dev/helix 0.169.0 → 0.171.0

package/dist/chat/root/chat-root.css.js

@@ -1,6 +1,6 @@
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {display: grid;grid-template-rows: auto minmax(0, 1fr) auto auto auto;max-block-size: var(--chat-max-block-size, none);min-block-size: 0;}[part="header"] {grid-row: 1;}[part="log"] {grid-row: 2;}[part="resume"] {grid-row: 3;}[part="status"] {grid-row: 4;}[part="composer"] {grid-row: 5;}[part="log"] {display: flex;flex-direction: column;scrollbar-color: var(--chat-scrollbar-thumb-color, var(--helix-scrollbar-thumb-color))
-var(--chat-scrollbar-track-color, var(--helix-scrollbar-track-color));scrollbar-width: thin;gap: var(--chat-gap, var(--helix-space-md));overflow-y: auto;padding-block: var(--helix-space-md);padding-inline: var(--chat-padding-inline, var(--helix-space-md));justify-content: safe flex-end;}[part="log"]:hover {scrollbar-color: var(--chat-scrollbar-thumb-hover-color, var(--helix-scrollbar-thumb-hover-color))
+var(--chat-scrollbar-track-color, var(--helix-scrollbar-track-color));scrollbar-width: thin;gap: var(--chat-gap, var(--helix-space-md));overflow-y: auto;padding-block: var(--helix-space-md);padding-inline: var(--chat-padding-inline, var(--helix-space-md));justify-content: safe flex-end;}[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="log"]:hover {scrollbar-color: var(--chat-scrollbar-thumb-hover-color, var(--helix-scrollbar-thumb-hover-color))
 var(--chat-scrollbar-track-color, var(--helix-scrollbar-track-color));}[part="header"][hidden],
 [part="resume"][hidden],
 [part="composer"][hidden] {display: none;}[part="status"][data-empty] {padding-block: 0;}[part="header"] {--helix-size-tag: var(--helix-size-tag-sm);align-items: center;border-block-end: var(--helix-border-thin) solid var(--chat-rule, var(--helix-color-border));display: flex;gap: var(--helix-space-sm);justify-content: space-between;min-block-size: var(--helix-size-control);padding-block: var(--helix-space-2xs);padding-inline: var(--chat-padding-inline, var(--helix-space-md));}[part="header"] > [part="actions"] {--helix-size-control: var(--helix-size-control-sm);--helix-size-control-loose: calc(var(--helix-size-control) * 1.2);--helix-size-control-tight: calc(var(--helix-size-control) * 0.8);--helix-size-icon: var(--helix-size-icon-sm);--helix-size-icon-loose: calc(var(--helix-size-icon) * 1.2);--helix-size-icon-tight: calc(var(--helix-size-icon) * 0.8);align-items: center;display: flex;flex: 0 0 auto;gap: var(--helix-space-2xs);}[part="header"] > [part="actions"][hidden] {display: none;}[part="resume"] {display: grid;justify-items: center;margin-block-start: calc(var(--helix-space-xl) * -1);pointer-events: none;position: relative;}[part="resume"] > * {pointer-events: auto;}[part="resume"] slot::slotted(*) {border: var(--chat-resume-border-width, var(--helix-border-floating)) solid

package/dist/code-block/root/code-block-root.css.js

@@ -3,14 +3,22 @@ export const styles = createSheet(`:host {--_code-block-size: var(--code-block-f
 > :is([part="actions"], [part="wrap-toggle"])
 ~ :is([part="copy"], [part="wrap-toggle"]) {margin-inline-start: var(--helix-space-none);}[part="wrap-toggle"] {all: unset;box-sizing: border-box;border-radius: var(--helix-radii-sm);color: var(--code-block-label-color, var(--helix-color-foreground-muted));cursor: pointer;font-family: var(--helix-font-sans);font-size: var(--helix-text-xs);font-weight: var(--helix-weight-medium);margin-inline-start: auto;padding-block: var(--helix-space-2xs);padding-inline: var(--helix-space-xs);}[part="wrap-toggle"]:hover,
 [part="wrap-toggle"][aria-pressed="true"] {color: var(--helix-color-foreground);}[part="wrap-toggle"][aria-pressed="true"] {background-color: color-mix(in oklab, var(--helix-color-foreground) 8%, transparent);}[part="wrap-toggle"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: var(--helix-size-focus-offset);}[part="frame"] > [part="copy"] {font-size: var(--_code-block-size);inset-block-start: var(--_code-block-copy-inset);inset-inline-end: var(--_code-block-copy-inset);line-height: var(--_code-block-leading);position: absolute;}[part="block"] {backdrop-filter: var(--code-block-backdrop, none);background-color: var(--code-block-background-color, var(--helix-color-background));border: var(--helix-border-thin) solid var(--code-block-border-color, var(--helix-color-border));border-radius: var(--code-block-radius, var(--helix-radii-lg));margin: var(--helix-space-none);overflow-x: auto;padding-block: var(--helix-space-sm);padding-inline: var(--helix-space-md);}:host(:not([diff], [no-copy])) [part="frame"]:not([part="header"] + *) > [part="block"] {padding-inline-end: var(--_code-block-gutter);}[part="header"] + [part="frame"] [part="block"] {border-block-start-width: var(--helix-space-none);border-start-end-radius: var(--helix-radii-none);border-start-start-radius: var(--helix-radii-none);}[part="files"] {backdrop-filter: var(--code-block-backdrop, none);background-color: var(--code-block-header-background-color, var(--helix-color-surface-raised));border: var(--helix-border-thin) solid var(--code-block-border-color, var(--helix-color-border));border-block-end-width: var(--helix-space-none);border-start-end-radius: var(--code-block-radius, var(--helix-radii-lg));border-start-start-radius: var(--code-block-radius, var(--helix-radii-lg));display: flex;overflow-x: auto;padding-inline: var(--helix-space-xs);}[part="file-tab"] {background-color: transparent;border: none;border-block-end: var(--helix-border-thick) solid transparent;color: var(--code-block-label-color, var(--helix-color-foreground-muted));cursor: pointer;font-family: var(--helix-font-sans);font-size: var(--helix-text-xs);font-weight: var(--helix-weight-medium);padding-block: var(--helix-space-xs);padding-inline: var(--helix-space-sm);white-space: nowrap;}[part="file-tab"]:hover,
-[part="file-tab"][aria-selected="true"] {color: var(--helix-color-foreground);}[part="file-tab"][aria-selected="true"] {border-block-end-color: var(--helix-color-accent);}[part="file-tab"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: calc(var(--helix-size-focus-offset) * -1);}:host(:state(tabbed)) :is([part="header"], [part="block"]) {border-start-end-radius: var(--helix-radii-none);border-start-start-radius: var(--helix-radii-none);}[part="code"] {color: var(--code-block-color, var(--helix-color-foreground));font-family: var(--_code-block-face);font-size: var(--_code-block-size);line-height: var(--_code-block-leading);}:host(:not([diff])) [part="code"] {display: block;isolation: isolate;max-block-size: var(--code-block-max-block-size, none);overflow-x: auto;position: relative;}:host(:state(expanded)) [part="code"] {max-block-size: none;}[part="expand"] {all: unset;box-sizing: border-box;border-radius: var(--helix-radii-sm);color: var(--code-block-expand-color, var(--helix-color-foreground-muted));cursor: pointer;font-size: var(--helix-text-sm);padding: var(--helix-space-xs);}[part="expand"]:hover {color: var(--helix-color-foreground);}[part="expand"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: var(--helix-size-focus-offset);}[part="block"]:focus-visible,
+[part="file-tab"][aria-selected="true"] {color: var(--helix-color-foreground);}[part="file-tab"][aria-selected="true"] {border-block-end-color: var(--helix-color-accent);}[part="file-tab"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: calc(var(--helix-size-focus-offset) * -1);}:host(:state(tabbed)) :is([part="header"], [part="block"]) {border-start-end-radius: var(--helix-radii-none);border-start-start-radius: var(--helix-radii-none);}[part="code"] {color: var(--code-block-color, var(--helix-color-foreground));font-family: var(--_code-block-face);font-size: var(--_code-block-size);line-height: var(--_code-block-leading);}:host(:not([diff])) [part="code"] {display: block;isolation: isolate;max-block-size: var(--code-block-max-block-size, none);overflow-x: auto;position: relative;}:host(:state(expanded)) [part="code"] {max-block-size: none;}[part="expand"] {all: unset;box-sizing: border-box;border-radius: var(--helix-radii-sm);color: var(--code-block-expand-color, var(--helix-color-foreground-muted));cursor: pointer;font-size: var(--helix-text-sm);padding: var(--helix-space-xs);}::slotted([slot="expand-icon"]) {margin-inline-end: var(--helix-space-xs);vertical-align: middle;}[part="expand"]:hover {color: var(--helix-color-foreground);}[part="expand"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: var(--helix-size-focus-offset);}[part="block"]:focus-visible,
 [part="code"]:focus-visible,
 [part="old"]:focus-visible,
-[part="new"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: calc(var(--helix-size-focus-offset) * -1);}:host([wrap]:not([diff])) [part="code"] {overflow-wrap: anywhere;white-space: pre-wrap;}[part="mark"] {background-color: var(
+[part="new"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: calc(var(--helix-size-focus-offset) * -1);}:host([wrap]:not([diff])) [part="code"] {overflow-wrap: anywhere;white-space: pre-wrap;}[part~="mark"] {background-color: var(
 --code-block-mark-color,
 color-mix(in oklab, var(--helix-color-primary) 12%, transparent)
 );block-size: var(--code-block-mark-size, 0);border-inline-start: var(--helix-border-thick) solid
-var(--code-block-mark-edge-color, var(--helix-color-primary));box-sizing: border-box;inline-size: max(100%, var(--code-block-mark-inline-size, 100%));inset-block-start: var(--code-block-mark-start, 0);inset-inline-start: 0;pointer-events: none;position: absolute;z-index: var(--helix-layer-beneath);}:host([line-numbers]:not([diff])) [part="block"] {column-gap: var(--helix-space-md);display: grid;grid-template-columns: auto minmax(0, 1fr);}[part="gutter"] {color: var(--code-block-gutter-color, var(--helix-color-foreground-subtle));font-family: var(--_code-block-face);font-size: var(--_code-block-size);font-variant-numeric: tabular-nums;line-height: var(--_code-block-leading);text-align: end;user-select: none;}:host([diff]) {gap: var(--helix-space-md);}:host([diff]) [part="file"] {container-type: inline-size;display: flex;flex-direction: column;}:host([diff]) [part="block"],
+var(--code-block-mark-edge-color, var(--helix-color-primary));box-sizing: border-box;inline-size: max(100%, var(--code-block-mark-inline-size, 100%));inset-block-start: var(--code-block-mark-start, 0);inset-inline-start: 0;pointer-events: none;position: absolute;z-index: var(--helix-layer-beneath);}[part~="mark-added"] {background-color: color-mix(
+in oklab,
+var(--code-block-added-color, var(--helix-color-success)) 14%,
+transparent
+);border-inline-start-color: var(--code-block-added-color, var(--helix-color-success));}[part~="mark-removed"] {background-color: color-mix(
+in oklab,
+var(--code-block-removed-color, var(--helix-color-danger)) 14%,
+transparent
+);border-inline-start-color: var(--code-block-removed-color, var(--helix-color-danger));}:host([line-numbers]:not([diff])) [part="block"] {column-gap: var(--helix-space-md);display: grid;grid-template-columns: auto minmax(0, 1fr);}[part="gutter"] {color: var(--code-block-gutter-color, var(--helix-color-foreground-subtle));font-family: var(--_code-block-face);font-size: var(--_code-block-size);font-variant-numeric: tabular-nums;line-height: var(--_code-block-leading);text-align: end;user-select: none;}:host([diff]) {gap: var(--helix-space-md);}:host([diff]) [part="file"] {container-type: inline-size;display: flex;flex-direction: column;}:host([diff]) [part="block"],
 [part="old"],
 [part="new"] {backdrop-filter: var(--code-block-backdrop, none);background-color: var(--code-block-background-color, var(--helix-color-background));border: var(--helix-border-thin) solid var(--code-block-border-color, var(--helix-color-border));border-radius: var(--code-block-radius, var(--helix-radii-lg));margin: var(--helix-space-none);min-inline-size: 0;overflow-x: auto;padding-block: var(--helix-space-none) var(--helix-space-sm);padding-inline: var(--helix-space-none);}:host([diff]:not([no-copy]))
 [part="frame"]:not([part="header"] + *)

package/dist/data-table/root/data-table-root.css.js

@@ -1,5 +1,7 @@
 import { createSheet } from '@fusion.dev/helix-core';
-export const styles = createSheet(`:host {display: block;}[part="table"] {display: grid;grid-template-columns: var(--data-table-columns, var(--data-table-template, minmax(0, 1fr)));inline-size: 100%;overflow-x: auto;}[part="table"] {--_data-table-fade: to right;animation: data-table-edges linear both;animation-timeline: scroll(self inline);mask-image: linear-gradient(
+export const styles = createSheet(`:host {display: block;}[part="toolbar"],
+[part="table"],
+[part="footer"] {grid-column: 1 / -1;}[part="table"] {display: grid;grid-template-columns: var(--data-table-columns, var(--data-table-template, minmax(0, 1fr)));inline-size: 100%;overflow-x: auto;}[part="table"] {--_data-table-fade: to right;animation: data-table-edges linear both;animation-timeline: scroll(self inline);mask-image: linear-gradient(
 var(--_data-table-fade),
 transparent,
 #000 var(--_data-table-fade-start, 0rem),

package/dist/data-table/root/data-table-root.d.ts

@@ -19,15 +19,18 @@ import '../../table/index.js';
  * without `paginated` and with either `mode`, so a page or a chunk from a
  * server can be windowed.
  *
- * **The cell values do not server-render.** Use `helix-table` when the content
- * has to be in the served HTML.
+ * **Write the first page as rows, so the served HTML carries the values.**
+ * Write it under the columns as `helix-table-row` and `helix-table-cell`
+ * elements. `@fusion.dev/helix-styles/helix.css` lays them out as the table
+ * draws them before it upgrades, and the table shows them until `rows` holds a
+ * row.
  *
  * @since 0.1.0
  * @status stable
  * @category data
  * @documentation https://fusion.dev/helix/components/data-table
  *
- * @slot - The columns, as `TableColumn` elements.
+ * @slot - The columns, as `TableColumn` elements, and the first page served as `TableRow` elements, which show until `rows` holds a row.
  * @slot empty - Content shown when there are no rows to show and none are loading, such as a picture and a link. Falls back to `empty-text`, which the live region still says.
  * @slot error - Content shown while `error-text` is set, such as a button that tries again. Falls back to `error-text`, which the live region still says.
  * @slot footer - Content below the grid. It replaces the built-in pagination.

package/dist/filter-input/root/filter-input-root.css.js

@@ -5,4 +5,5 @@ border-color var(--helix-duration-fast) var(--helix-easing-standard),
 background-color var(--helix-duration-fast) var(--helix-easing-standard);}::slotted([slot="tags"]) {flex: 0 0 auto;max-inline-size: 100%;}[part="control"] {flex: 1 1 var(--filter-input-control-size, 6ch);}[part="lead"] {align-items: center;align-self: stretch;border-inline-end: var(--helix-border-thin) solid
 var(--filter-input-lead-border-color, var(--helix-color-border));display: flex;margin-block: calc(var(--helix-space-2xs) * -1);margin-inline-start: calc(var(--helix-space-xs) * -1);padding-inline: var(--helix-space-2xs);}[part="lead"][hidden] {display: none;}[part="lead"],
 slot[name="end"] {--button-size: var(--filter-input-action-size, var(--helix-size-tag));--icon-button-size: var(--filter-input-action-size, var(--helix-size-tag));--button-padding-inline: var(--filter-input-action-padding-inline, var(--helix-space-xs));}slot[name="start"]::slotted(*),
-slot[name="end"]::slotted(*) {color: var(--helix-color-foreground-subtle);flex: 0 0 auto;}[part="clear"] {--icon-size: 0.85em;all: unset;align-items: center;align-self: center;border-radius: var(--helix-radii-sm);box-sizing: border-box;color: var(--filter-input-clear-color, var(--helix-color-foreground-subtle));cursor: pointer;display: flex;flex: 0 0 auto;justify-content: center;min-block-size: var(--helix-size-icon-loose);min-inline-size: var(--helix-size-icon-loose);transition: color var(--helix-duration-fast) var(--helix-easing-standard);}[part="clear"]:hover {background-color: color-mix(in oklab, currentcolor 12%, transparent);color: var(--filter-input-clear-color-hover, var(--helix-color-foreground));}[part="clear"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: var(--helix-size-focus-offset);}:host(:disabled) [part="field"] {cursor: not-allowed;opacity: 0.5;}@media print {:host {print-color-adjust: exact;}}[part="surface"] {--_floating-border-color: var(--filter-input-border-color, var(--helix-color-border));--_floating-border-width: var(--filter-input-border-width, var(--helix-border-floating));--_floating-shadow: var(--filter-input-shadow, var(--helix-shadow-floating));box-sizing: border-box;inline-size: var(--filter-input-panel-size, var(--floating-anchor-inline-size, 100%));max-block-size: var(--floating-available-block-size, 20rem);min-inline-size: max-content;overflow-y: auto;padding-block: var(--helix-space-2xs);padding-inline: var(--helix-space-none);position: absolute;}`);
+slot[name="end"]::slotted(*) {color: var(--helix-color-foreground-subtle);flex: 0 0 auto;}[part="clear"] {--icon-size: 0.85em;all: unset;align-items: center;align-self: center;border-radius: var(--helix-radii-sm);box-sizing: border-box;color: var(--filter-input-clear-color, var(--helix-color-foreground-subtle));cursor: pointer;display: flex;flex: 0 0 auto;justify-content: center;min-block-size: var(--helix-size-icon-loose);min-inline-size: var(--helix-size-icon-loose);transition: color var(--helix-duration-fast) var(--helix-easing-standard);}[part="clear"]:hover {background-color: color-mix(in oklab, currentcolor 12%, transparent);color: var(--filter-input-clear-color-hover, var(--helix-color-foreground));}[part="clear"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: var(--helix-size-focus-offset);}:host(:disabled) [part="field"] {cursor: not-allowed;opacity: 0.5;}@media print {:host {print-color-adjust: exact;}}[part="surface"] {--_floating-border-color: var(--filter-input-border-color, var(--helix-color-border));--_floating-border-width: var(--filter-input-border-width, var(--helix-border-floating));--_floating-shadow: var(--filter-input-shadow, var(--helix-shadow-floating));box-sizing: border-box;inline-size: var(--filter-input-panel-size, var(--floating-anchor-inline-size, 100%));max-block-size: var(--floating-available-block-size, 20rem);min-inline-size: max-content;overflow-y: auto;padding-block: var(--helix-space-2xs);padding-inline: var(--helix-space-none);position: absolute;}[part="empty"],
+[part="loading"] {--_collection-inset-block: var(--helix-space-xs);--_collection-inset-inline: var(--helix-space-xs);}`);

package/dist/filter-input/root/filter-input-root.d.ts

@@ -46,6 +46,7 @@ import '../../option/index.js';
  * @cssproperty --filter-input-size - The height of the empty field. The field grows from this height.
  */
 export declare class HelixFilterInput extends HelixHeadlessFilterInput {
+    static tier: string;
     static styles: CSSResultGroup;
 }
 declare global {

package/dist/filter-input/root/filter-input-root.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement } from '@fusion.dev/helix-core';
 import { HelixHeadlessFilterInput } from '@fusion.dev/helix-headless/filter-input';
 import '../../option/index.js';
+import { styles as collectionStateStyles } from '../../shared/collection/state.css.js';
 import { styles as fieldStyles } from '../../shared/field/field.css.js';
 import { styles as fieldFrameStyles } from '../../shared/field/field-frame.css.js';
 import { styles as fieldStackedStyles } from '../../shared/field/field-stacked.css.js';
@@ -17,6 +18,7 @@ import { styles as liveStyles } from '../../shared/live/live.css.js';
 import { styles as tagRowStyles } from '../../shared/tags/tags.css.js';
 import { styles } from './filter-input-root.css.js';
 let HelixFilterInput = class HelixFilterInput extends HelixHeadlessFilterInput {
+    static { this.tier = 'helix-'; }
     static { this.styles = [
         liveStyles,
         glyphStyles,
@@ -26,6 +28,7 @@ let HelixFilterInput = class HelixFilterInput extends HelixHeadlessFilterInput {
         tagRowStyles,
         floatingPanelStyles,
         floatingEntranceStyles,
+        collectionStateStyles,
         styles,
     ]; }
 };

package/dist/sandbox/frame.d.ts

@@ -69,4 +69,12 @@ export declare const servePreview: (options?: ServePreviewOptions) => (() => voi
  * a sandbox's `js` pane adds to its `html` pane.
  */
 export declare const withScript: (source: string, script: string) => string;
-export declare const defaultFrame: () => string;
+/**
+ * The built-in document, with an import map for `imports` where there are any.
+ *
+ * **The map comes first in the head**, because a browser reads an import map
+ * only before the first module it loads, and the example's scripts are
+ * modules. `</` is escaped in the map as in the script, so a URL cannot close
+ * the element early.
+ */
+export declare const defaultFrame: (imports?: Readonly<Record<string, string>>) => string;

package/dist/sandbox/frame.js

@@ -169,10 +169,14 @@ export const servePreview = (options = {}) => serveWith(TOOLS, options);
 let builtIn;
 export const withScript = (source, script) => script === '' ? source : `${source}<script type="module">${script}${SCRIPT_END}`;
 const SCRIPT_END = ['<', 'script>'].join('/');
-export const defaultFrame = () => {
+export const defaultFrame = (imports) => {
     if (builtIn === undefined) {
         const script = `(${serveWith})({drawn:${drawn},isRender:${isRender},layoutRules:${JSON.stringify(LAYOUT_RULES)},loggedText:${loggedText},runScripts:${runScripts},withoutStylesheets:${withoutStylesheets}})`;
         builtIn = `<!doctype html><html><head><meta charset="utf-8"><meta content="width=device-width" name="viewport"><style>:root{color-scheme:light dark;font-family:system-ui,sans-serif}body{margin:0}</style></head><body><div id="preview-root"></div><script>${script.replaceAll('</', '<\\/')}${SCRIPT_END}</body></html>`;
     }
-    return builtIn;
+    if (!imports || Object.keys(imports).length === 0) {
+        return builtIn;
+    }
+    const map = JSON.stringify({ imports }).replaceAll('</', '<\\/');
+    return builtIn.replace('<head>', `<head><script type="importmap">${map}${SCRIPT_END}`);
 };

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

@@ -54,6 +54,15 @@ export type PreviewMessage = PreviewConsole | PreviewPress | PreviewReady | Prev
  * `servePreview` does. It defines no element, so an example that uses Helix
  * components needs a `src` that imports them.
  *
+ * **`imports` lets an example import packages by name** in the built-in
+ * document, as an import map: each name maps to the address of an ES module,
+ * such as `{"canvas-confetti": "https://esm.sh/canvas-confetti@1.9.3"}`, and
+ * `import confetti from 'canvas-confetti'` in the `js` pane then loads it. A
+ * CDN that serves npm packages as modules, such as esm.sh or jsDelivr's
+ * `+esm`, gives every package an address. A new map loads the document again,
+ * since a browser reads one only as a document starts. A `src` document
+ * declares its own.
+ *
  * **Examples render in a frame**, so an example's styles and scripts do not
  * affect the page around the sandbox, and `position: fixed` stays inside the
  * pane. The frame starts empty, with its own stylesheets and its own custom
@@ -134,6 +143,13 @@ export declare class HelixSandboxPreview extends HelixElement {
      * `colorMode` has to be sent rather than set.
      */
     direction?: 'rtl';
+    /**
+     * The packages an example can import by name in the built-in document,
+     * each mapped to the address of an ES module, as an import map's `imports`.
+     * Set it as JSON in the attribute or as an object. Not read where `src` is
+     * set.
+     */
+    imports?: Record<string, string>;
     /**
      * The frame's name, read by screen readers.
      */

package/dist/sandbox/preview/sandbox-preview.js

@@ -106,7 +106,7 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
         frame.title = this.label;
         frame.style.cssText = 'block-size: 100vh; border: none; display: block; inline-size: 100vw';
         if (this.src === '') {
-            frame.srcdoc = defaultFrame();
+            frame.srcdoc = defaultFrame(this.imports);
         }
         else {
             frame.src = this.frame?.src || this.src;
@@ -132,7 +132,7 @@ frame.onload = () => frame.contentWindow.postMessage(${JSON.stringify(this.messa
         }
         this.unready();
         if (this.src === '') {
-            frame.srcdoc = defaultFrame();
+            frame.srcdoc = defaultFrame(this.imports);
             return;
         }
         frame.src = this.src;
@@ -146,7 +146,7 @@ frame.onload = () => frame.contentWindow.postMessage(${JSON.stringify(this.messa
     }
     updated(changed) {
         super.updated(changed);
-        if (changed.has('src')) {
+        if (changed.has('src') || (changed.has('imports') && this.src === '')) {
             this.unready();
             return;
         }
@@ -174,7 +174,7 @@ frame.onload = () => frame.contentWindow.postMessage(${JSON.stringify(this.messa
       part="frame"
       @load=${this.handleFrameLoad}
       src=${this.src || nothing}
-      srcdoc=${this.src === '' ? defaultFrame() : nothing}
+      srcdoc=${this.src === '' ? defaultFrame(this.imports) : nothing}
       title=${this.label}
       allow="clipboard-write *; fullscreen *"
       sandbox=${SANDBOX}
@@ -191,6 +191,9 @@ __decorate([
 __decorate([
     property()
 ], HelixSandboxPreview.prototype, "direction", void 0);
+__decorate([
+    property({ type: Object })
+], HelixSandboxPreview.prototype, "imports", void 0);
 __decorate([
     words,
     property()

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

@@ -1,4 +1,4 @@
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {display: block;block-size: 100%;}[part="highlight"],
 [part="source"] {border: none;color: var(--helix-color-foreground-muted);font-family: var(--helix-font-mono);font-size: max(var(--helix-text-field-min), var(--helix-text-xs));inline-size: 100%;line-height: var(--helix-leading-normal);min-block-size: var(--sandbox-source-min-block-size, 12rem);padding: var(--helix-space-sm);tab-size: 2;}[part="source"] {background-color: var(--sandbox-source-background-color, var(--helix-color-background));block-size: 100%;display: block;resize: none;}[part="source"]:focus-visible {background-color: var(--helix-color-surface);outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: calc(var(--helix-size-focus-offset) * -1);}[part="field"] {background-color: var(--sandbox-source-background-color, var(--helix-color-background));block-size: 100%;display: grid;grid-template-rows: minmax(max-content, auto);overflow: auto;}[part="field"]:focus-within {background-color: var(--helix-color-surface);}[part="field"]:has(> [part="source"]:focus-visible) {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: calc(var(--helix-size-focus-offset) * -1);}[part="field"] > [part] {grid-area: 1 / 1;letter-spacing: normal;margin: 0;overflow-wrap: break-word;white-space: pre-wrap;}[part="field"] > [part="source"],
-[part="field"] > [part="source"]:focus-visible {-webkit-text-fill-color: transparent;align-self: stretch;background-color: transparent;block-size: auto;caret-color: var(--helix-color-foreground);color: transparent;outline: none;overflow: hidden;}[data-kind="callable"] {color: var(--sandbox-source-callable-color, var(--helix-color-syntax-callable));}[data-kind="comment"] {color: var(--sandbox-source-comment-color, var(--helix-color-syntax-comment));}[data-kind="constant"] {color: var(--sandbox-source-constant-color, var(--helix-color-syntax-constant));}[data-kind="invalid"] {color: var(--sandbox-source-invalid-color, var(--helix-color-syntax-invalid));}[data-kind="keyword"] {color: var(--sandbox-source-keyword-color, var(--helix-color-syntax-keyword));}[data-kind="name"] {color: var(--sandbox-source-name-color, var(--helix-color-syntax-name));}[data-kind="string"] {color: var(--sandbox-source-string-color, var(--helix-color-syntax-string));}[data-kind="tag"] {color: var(--sandbox-source-tag-color, var(--helix-color-syntax-tag));}`);
+[part="field"] > [part="source"]:focus-visible {-webkit-text-fill-color: transparent;align-self: stretch;background-color: transparent;block-size: auto;caret-color: var(--helix-color-foreground);color: transparent;outline: none;overflow: hidden;}:host([line-numbers]) [part="field"] > [part] {padding-inline-start: calc(var(--helix-space-sm) * 3 + var(--_sandbox-source-gutter, 1ch));}:host([line-numbers]) [part="highlight"] {counter-reset: line;}[part="line"] {counter-increment: line;display: block;min-block-size: 1lh;position: relative;}[part="line"]::before {color: var(--sandbox-source-line-number-color, var(--helix-color-foreground-subtle));content: counter(line);inset-inline-end: calc(100% + var(--helix-space-sm) * 2);position: absolute;text-align: end;}[data-kind="callable"] {color: var(--sandbox-source-callable-color, var(--helix-color-syntax-callable));}[data-kind="comment"] {color: var(--sandbox-source-comment-color, var(--helix-color-syntax-comment));}[data-kind="constant"] {color: var(--sandbox-source-constant-color, var(--helix-color-syntax-constant));}[data-kind="invalid"] {color: var(--sandbox-source-invalid-color, var(--helix-color-syntax-invalid));}[data-kind="keyword"] {color: var(--sandbox-source-keyword-color, var(--helix-color-syntax-keyword));}[data-kind="name"] {color: var(--sandbox-source-name-color, var(--helix-color-syntax-name));}[data-kind="string"] {color: var(--sandbox-source-string-color, var(--helix-color-syntax-string));}[data-kind="tag"] {color: var(--sandbox-source-tag-color, var(--helix-color-syntax-tag));}`);

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

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import type { CSSResultGroup, TemplateResult } from 'lit';
+import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
 import { type SandboxTokenizer } from '../tokens.js';
 /**
  * @summary An editable source pane for a sandbox preview.
@@ -24,6 +24,18 @@ import { type SandboxTokenizer } from '../tokens.js';
  * that throws leaves the source drawn plain and the field editable, and the
  * error is reported to the page as an uncaught one.
  *
+ * **`line-numbers` numbers each line** in a gutter beside the source. A line
+ * that wraps keeps one number. The numbers are drawn, and hidden from screen
+ * readers, which read the field.
+ *
+ * Enter keeps the indentation of the line it breaks, and the new line is
+ * undone with the next undo as typing is.
+ *
+ * **The source can be written inside the pane** where `value` is not set: its
+ * text, or the markup of a `<template>` it holds, without the indentation the
+ * page gave it. Markup goes in a template so the page does not render it or
+ * run its scripts. Text inside the pane is read once, when it connects.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases Editor, Code pane
@@ -33,8 +45,9 @@ import { type SandboxTokenizer } from '../tokens.js';
  * @event {HelixCaretEvent} helix-caret - Fired when the cursor moves.
  * @event {HelixEditEvent} helix-edit - Fired after the source was edited, with the new source.
  *
- * @csspart field - The box that scrolls the field and its colors together, under `tokenize`.
- * @csspart highlight - The colored copy of the source drawn under the field, under `tokenize`.
+ * @csspart field - The box that scrolls the field and its colors together, under `tokenize` or `line-numbers`.
+ * @csspart highlight - The colored copy of the source drawn under the field, under `tokenize` or `line-numbers`.
+ * @csspart line - One line of that copy, under `line-numbers`, numbered in the gutter by its `::before`.
  * @csspart source - The editable region.
  * @csspart token - One run of the source that has a kind, under `tokenize`.
  *
@@ -44,6 +57,7 @@ import { type SandboxTokenizer } from '../tokens.js';
  * @cssproperty --sandbox-source-constant-color - Color of a `constant` run, under `tokenize`. Defaults to `--helix-color-syntax-constant`.
  * @cssproperty --sandbox-source-invalid-color - Color of an `invalid` run, under `tokenize`. Defaults to `--helix-color-syntax-invalid`.
  * @cssproperty --sandbox-source-keyword-color - Color of a `keyword` run, under `tokenize`. Defaults to `--helix-color-syntax-keyword`.
+ * @cssproperty --sandbox-source-line-number-color - Color of the line numbers, under `line-numbers`. Defaults to `--helix-color-foreground-subtle`.
  * @cssproperty --sandbox-source-min-block-size - Minimum height of the pane.
  * @cssproperty --sandbox-source-name-color - Color of a `name` run, under `tokenize`. Defaults to `--helix-color-syntax-name`.
  * @cssproperty --sandbox-source-string-color - Color of a `string` run, under `tokenize`. Defaults to `--helix-color-syntax-string`.
@@ -74,6 +88,10 @@ export declare class HelixSandboxSource extends HelixElement {
      * holds several panes. Empty puts the pane's `name` on the tab.
      */
     label: string;
+    /**
+     * Whether each line of the source is numbered, in a gutter beside it.
+     */
+    lineNumbers: boolean;
     /**
      * Which source this pane holds. Every `helix-before-edit` event includes it.
      *
@@ -107,6 +125,22 @@ export declare class HelixSandboxSource extends HelixElement {
     value: string;
     /** Set by Escape, so the next Tab leaves the field. */
     private escaped;
+    /** Whether the source written inside the pane has been read. */
+    private read;
+    /**
+     * Takes the source written inside the pane where `value` is not set: a
+     * template's markup, or else the text. Client only, like every read of the
+     * light DOM, and once there is something to read.
+     *
+     * **As it connects, and again before its first render.** A pane that
+     * upgrades after the parser is done holds its text as it connects, which is
+     * before a sandbox around it reads `value` to seed its preview. A parser that
+     * connects the pane before its children, as one with the element already
+     * defined does, leaves the text for the render.
+     */
+    private readWritten;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
     /**
      * Reports where the cursor is, for a status bar to read.
      *
@@ -145,7 +179,13 @@ export declare class HelixSandboxSource extends HelixElement {
     private edit;
     private readonly handleKeydown;
     /**
-     * Writes the two spaces Tab inserts, as typing would.
+     * Breaks the line with the indentation it has, where it has some. A line at
+     * the margin is left to the platform's own Enter.
+     */
+    private breakLine;
+    /**
+     * Writes text at the caret, as typing would: the two spaces Tab inserts,
+     * and the indentation Enter keeps.
      *
      * **Through `insertText`, so undo takes the indent back.** Assigning
      * `field.value` empties the textarea's undo history: a reader who typed,
@@ -155,7 +195,7 @@ export declare class HelixSandboxSource extends HelixElement {
      * into whatever has focus, so it is used only while the field has it. Where it
      * is not supported, the field is written directly.
      */
-    private indent;
+    private insert;
     protected render(): TemplateResult;
     /** The field itself and its description, which is the whole pane without `tokenize`. */
     private renderField;

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

@@ -10,6 +10,30 @@ import { property } from 'lit/decorators.js';
 import { drawnRuns } from '../tokens.js';
 import { styles } from './sandbox-source.css.js';
 const MODIFIERS = new Set(['Alt', 'AltGraph', 'Control', 'Meta', 'Shift']);
+const dedent = (text) => {
+    const lines = text
+        .replace(/^(?:[ \t]*\n)+/, '')
+        .trimEnd()
+        .split('\n');
+    const shared = Math.min(...lines
+        .filter((line) => line.trim() !== '')
+        .map((line) => /^[ \t]*/.exec(line)?.[0].length ?? 0));
+    return Number.isFinite(shared) ? lines.map((line) => line.slice(shared)).join('\n') : '';
+};
+const linesOf = (runs) => {
+    const lines = [[]];
+    for (const { kind, text } of runs) {
+        text.split('\n').forEach((piece, at) => {
+            if (at > 0) {
+                lines.push([]);
+            }
+            if (piece !== '') {
+                lines.at(-1)?.push(kind ? { kind, text: piece } : { text: piece });
+            }
+        });
+    }
+    return lines;
+};
 let HelixSandboxSource = class HelixSandboxSource extends HelixElement {
     constructor() {
         super(...arguments);
@@ -17,10 +41,12 @@ let HelixSandboxSource = class HelixSandboxSource extends HelixElement {
         this.fieldNameLabel = '{field}, {name}';
         this.keysDescription = 'Tab inserts two spaces. To leave, press Escape and then Tab, or press Shift+Tab to go back.';
         this.label = '';
+        this.lineNumbers = false;
         this.name = 'html';
         this.tabIndents = true;
         this.value = '';
         this.escaped = false;
+        this.read = false;
         this.reportCaret = (event) => {
             const field = event.target;
             const at = field.selectionStart ?? 0;
@@ -43,15 +69,46 @@ let HelixSandboxSource = class HelixSandboxSource extends HelixElement {
             if (MODIFIERS.has(event.key)) {
                 return;
             }
+            if (event.key === 'Enter' &&
+                !event.isComposing &&
+                !(event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)) {
+                this.escaped = false;
+                this.breakLine(event);
+                return;
+            }
             if (event.key !== 'Tab' || event.shiftKey || !this.tabIndents || this.escaped) {
                 this.escaped = false;
                 return;
             }
             event.preventDefault();
-            this.indent(event.target);
+            this.insert(event.target, '  ');
         };
     }
     static { this.words = 'helix-sandbox-source'; }
+    readWritten() {
+        if (this.read ||
+            this.children === undefined ||
+            this.hasAttribute('value') ||
+            this.value !== '') {
+            return;
+        }
+        const template = this.querySelector(':scope > template');
+        const written = dedent(template ? template.innerHTML : (this.textContent ?? ''));
+        if (written !== '') {
+            this.read = true;
+            this.value = written;
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.readWritten();
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (!this.hasUpdated) {
+            this.readWritten();
+        }
+    }
     edit(field, next) {
         const request = new HelixBeforeEditEvent({ value: next });
         const accepted = this.dispatchEvent(request);
@@ -63,32 +120,50 @@ let HelixSandboxSource = class HelixSandboxSource extends HelixElement {
             this.dispatchEvent(new HelixEditEvent({ value: next }));
         }
     }
-    indent(field) {
+    breakLine(event) {
+        const field = event.target;
+        const at = field.selectionStart ?? 0;
+        const start = field.value.lastIndexOf('\n', at - 1) + 1;
+        const indent = /^[ \t]*/.exec(field.value.slice(start, at))?.[0] ?? '';
+        if (indent !== '') {
+            event.preventDefault();
+            this.insert(field, `\n${indent}`);
+        }
+    }
+    insert(field, text) {
         const { ownerDocument } = field;
         const focused = field.getRootNode().activeElement === field;
         if (focused &&
             typeof ownerDocument.execCommand === 'function' &&
-            ownerDocument.execCommand('insertText', false, '  ')) {
+            ownerDocument.execCommand('insertText', false, text)) {
             return;
         }
-        field.setRangeText('  ', field.selectionStart, field.selectionEnd, 'end');
+        field.setRangeText(text, field.selectionStart, field.selectionEnd, 'end');
         this.edit(field, field.value);
     }
     render() {
         const field = this.renderField();
-        if (!this.tokenize) {
+        if (!this.tokenize && !this.lineNumbers) {
             return field;
         }
         let given = [];
         try {
-            given = this.tokenize(this.value, this.name);
+            given = this.tokenize?.(this.value, this.name) ?? [];
         }
         catch (error) {
             globalThis.reportError?.(error);
         }
         const runs = drawnRuns(this.value, given);
+        const draw = (some) => some.map(({ kind, text }) => kind ? html `<span part="token" data-kind=${kind}>${text}</span>` : text);
+        if (this.lineNumbers) {
+            const lines = linesOf(runs);
+            return html `<div part="field" style="--_sandbox-source-gutter: ${String(lines.length).length}ch">
+        <pre part="highlight" aria-hidden="true">${lines.map((line) => html `<span part="line">${draw(line)}</span>`)}</pre>
+        ${field}
+      </div>`;
+        }
         return html `<div part="field">
-      <pre part="highlight" aria-hidden="true">${runs.map(({ kind, text }) => kind ? html `<span part="token" data-kind=${kind}>${text}</span>` : text)}${'\n'}</pre>
+      <pre part="highlight" aria-hidden="true">${draw(runs)}${'\n'}</pre>
       ${field}
     </div>`;
     }
@@ -126,6 +201,9 @@ __decorate([
 __decorate([
     property()
 ], HelixSandboxSource.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'line-numbers', reflect: true, type: Boolean })
+], HelixSandboxSource.prototype, "lineNumbers", void 0);
 __decorate([
     property()
 ], HelixSandboxSource.prototype, "name", void 0);