@fusion.dev/helix-headless 0.23.0 → 0.24.1

package/dist/code-block/root/code-block-root.d.ts

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../copy-button/index.js';
 /**
  * @summary A block of code, with somewhere to put its name and a way to take it.
@@ -23,6 +23,24 @@ import '../../copy-button/index.js';
  * A `Code` for a fragment inside a sentence. Separate families, because one
  * flows with prose and the other is a figure.
  *
+ * **`diff` reads the code as a change.** The content is then a unified diff,
+ * what `git diff` and `diff -u` write, in the same slot ordinary code goes in,
+ * and it is drawn as the lines it added and removed. The block reads a diff and
+ * never computes one, so the algorithm stays wherever the two versions are.
+ * Numbers come from the hunk headers, which makes them the file's; changed lines
+ * are `<ins>` and `<del>` with the `+` and `-` kept as text, so the change is not
+ * carried by color; the numbers are hidden from the accessibility tree. Each
+ * file in the patch is a block of its own under its own name, and its copy
+ * button takes the file as it now reads. `variant="split"` sets the old version
+ * beside the new, each removal opposite its replacement.
+ *
+ * **Before the script runs, a diff is its own text.** A server has no children
+ * to read, so it renders the slot as ordinary code, which for a diff is the
+ * patch in a `<pre>`: a legible diff, and the first render the client makes
+ * too, which is what keeps hydration clean. The drawn diff replaces it once the
+ * content can be read. Diff mode is experimental while the rest of the family
+ * is stable.
+ *
  * @since 0.1.0
  * @status stable
  * @category typography
@@ -31,20 +49,42 @@ import '../../copy-button/index.js';
  *
  * @slot - The code.
  *
+ * @csspart added - In a diff, a line only the new version has, an `<ins>`.
  * @csspart block - The scrolling `<pre>`.
  * @csspart code - The `<code>` inside it.
+ * @csspart context - In a diff, a line both versions share.
  * @csspart copy - The copy button.
  * @csspart copy-button - The inner button.
  * @csspart copy-mark - The clipboard glyph, and the confirmation that replaces it.
  * @csspart copy-tooltip - The bubble, forwarded from the tooltip inside.
  * @csspart copy-tooltip-arrow - The point, resting against the trigger.
+ * @csspart file - In a diff, one file's header and block.
+ * @csspart filler - In a split diff, the empty row opposite a line the other side does not have.
  * @csspart frame - The code and the copy button beside it.
  * @csspart header - The bar carrying the name, where there is one.
+ * @csspart hunk - In a diff, a `@@` line saying where the lines under it are.
  * @csspart label - The file name or language, where one is given.
+ * @csspart marker - In a diff, the `+`, `-` or space that opens a line.
+ * @csspart new - In a split diff, the new version's `<pre>`.
+ * @csspart number - In a diff, a line number.
+ * @csspart old - In a split diff, the old version's `<pre>`.
+ * @csspart removed - In a diff, a line only the old version has, a `<del>`.
+ * @csspart split - In a split diff, the two versions side by side.
+ * @csspart text - In a diff, a line's code.
  */
 export declare class HelixHeadlessCodeBlock extends HelixElement {
+    /**
+     * Whether the content is a unified diff, drawn as the lines it changed.
+     *
+     * Reflected, because the stylesheet paints a diff differently from code, and
+     * `false` reflects as no attribute at all.
+     */
+    diff: boolean;
     /**
      * What to call this block, usually a file name or a language.
+     *
+     * In a diff, each file is named from the patch, and this names a patch that
+     * carries no name of its own.
      */
     label: string;
     /**
@@ -70,27 +110,34 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      */
     noCopy: boolean;
     /**
-     * The code as text, read from the slot rather than stored.
+     * How a diff's two versions are arranged; nothing without `diff`.
+     *
+     * Absent is unified, each removal above its replacement, which fits any
+     * width. `split` sets the old version beside the new one. Optional rather
+     * than defaulted, so the host carries no attribute the consumer did not write.
+     */
+    variant?: 'split';
+    /** The last text read as a diff, and what it read as, so a render does not parse twice. */
+    private parsed;
+    /** The files in the content, when it is a diff and it can be read yet. */
+    private get files();
+    /**
+     * The code as text, read from what the default slot is given rather than
+     * stored.
+     *
+     * **The host's own children rather than the slot's assigned nodes**, which
+     * are the same nodes: text, and every element without a `slot`. A slot exists
+     * only once a render has made it, so reading through one left the first render
+     * with nothing to copy.
      *
      * Client only, and it has to be: the server has no children to read. The
      * copy button is a client-side affordance anyway, so nothing is lost, and
      * taking the text from a property instead would be a second copy of the code
-     * that goes stale the moment the slot changes.
+     * that goes stale the moment the slot changes. Empty while hydrating what a
+     * server sent, which rendered it empty.
      */
     private get text();
-    /**
-     * One more render, once there is a slot to read.
-     *
-     * The first render has no shadow children yet, so `text` is empty and the
-     * copy button is bound to nothing. `slotchange` normally schedules the render
-     * that fixes it, and leaning on that alone was measured to leave the button
-     * empty through four update cycles: the event is not guaranteed to have
-     * arrived, and in one environment never arrives at all. A component should not
-     * need an event to show its own content, so it asks for the second render
-     * itself and `slotchange` is left to handle the case it is actually for, which
-     * is content changing later.
-     */
-    protected firstUpdated(): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected render(): TemplateResult;
     /**
      * The button that takes the code, behind a seam the styled tier can move.
@@ -102,7 +149,25 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * base button, and a styled subclass that sets `tier` renders the styled one
      * from the same template.
      */
-    protected renderCopyButton(): TemplateResult;
+    protected renderCopyButton(value?: string): TemplateResult;
+    /** A number padded to the widest in its file, so the columns line up as text. */
+    private renderNumber;
+    private renderLine;
+    private renderHunk;
+    /**
+     * The old version beside the new one, row for row.
+     *
+     * The new side's hunk headers are hidden from the accessibility tree, being
+     * the old side's text again and there only to keep the rows level.
+     */
+    private renderSplit;
+    /**
+     * Each file as a block of its own, the way one block of code is drawn.
+     *
+     * The slot stays in the tree, hidden, because it is still where the content
+     * comes from: a diff edited later arrives by `slotchange` like any other.
+     */
+    private renderDiff;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -9,42 +9,119 @@ import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../copy-button/index.js';
+import { pairLines, parsePatch } from '../patch.js';
 let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
     constructor() {
         super(...arguments);
+        this.diff = false;
         this.label = '';
         this.noCopy = false;
+        this.parsed = { files: [], text: '' };
+    }
+    get files() {
+        if (!this.diff) {
+            return [];
+        }
+        const text = this.text;
+        if (text !== this.parsed.text) {
+            this.parsed = { files: parsePatch(text), text };
+        }
+        return this.parsed.files;
     }
     get text() {
-        const slot = this.renderRoot?.querySelector('slot');
-        return (slot?.assignedNodes() ?? []).map((node) => node.textContent ?? '').join('');
+        if (this.hydrating) {
+            return '';
+        }
+        return [...(this.childNodes ?? [])]
+            .filter((node) => node.nodeType === Node.TEXT_NODE ||
+            (node.nodeType === Node.ELEMENT_NODE && node.slot === ''))
+            .map((node) => node.textContent ?? '')
+            .join('');
     }
-    firstUpdated() {
-        this.requestUpdate();
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
     }
     render() {
+        const files = this.files;
+        if (files.length > 0) {
+            return this.renderDiff(files);
+        }
         return html `${this.label ? html `<div part="header"><span part="label">${this.label}</span></div>` : nothing}
       <div part="frame">
         <pre part="block"><code part="code"><slot @slotchange=${() => this.requestUpdate()}></slot></code></pre>
         ${this.noCopy ? nothing : this.renderCopyButton()}
       </div>`;
     }
-    renderCopyButton() {
+    renderCopyButton(value = this.text) {
         return html `<${this.tag('copy-button')}
       part="copy"
       exportparts="button: copy-button, mark: copy-mark, tooltip: copy-tooltip,
         tooltip-arrow: copy-tooltip-arrow"
       label="Copy code"
-      .value=${this.text}
+      .value=${value}
     ></${this.tag('copy-button')}>`;
     }
+    renderNumber(value, width) {
+        return html `<span part="number" aria-hidden="true">${String(value ?? '').padStart(width)} </span>`;
+    }
+    renderLine(line, width, side) {
+        const numbers = side
+            ? this.renderNumber(side === 'old' ? line.old : line.new, width)
+            : html `${this.renderNumber(line.old, width)}${this.renderNumber(line.new, width)}`;
+        const text = html `<span part="text">${line.text}\n</span>`;
+        if (line.kind === 'added') {
+            return html `<ins part="added">${numbers}<span part="marker">+</span>${text}</ins>`;
+        }
+        if (line.kind === 'removed') {
+            return html `<del part="removed">${numbers}<span part="marker">-</span>${text}</del>`;
+        }
+        return html `<span part="context">${numbers}<span part="marker"> </span>${text}</span>`;
+    }
+    renderHunk(hunk, hidden = false) {
+        return html `<span part="hunk" aria-hidden=${hidden ? 'true' : nothing}>${hunk.header}\n</span>`;
+    }
+    renderSplit(file, width) {
+        const hunks = file.hunks.map((hunk) => ({ hunk, rows: pairLines(hunk.lines) }));
+        const filler = html `<span part="filler" aria-hidden="true">\n</span>`;
+        return html `<div part="split">
+      <pre part="old"><code part="code">${hunks.map(({ hunk, rows }) => html `${this.renderHunk(hunk)}${rows.map(({ left }) => left ? this.renderLine(left, width, 'old') : filler)}`)}</code></pre>
+      <pre part="new"><code part="code">${hunks.map(({ hunk, rows }) => html `${this.renderHunk(hunk, true)}${rows.map(({ right }) => right ? this.renderLine(right, width, 'new') : filler)}`)}</code></pre>
+    </div>`;
+    }
+    renderDiff(files) {
+        return html `${files.map((file) => {
+            const name = file.name || this.label;
+            const widest = Math.max(0, ...file.hunks.flatMap((hunk) => hunk.lines.map((line) => Math.max(line.old ?? 0, line.new ?? 0))));
+            const width = String(widest).length;
+            const now = file.hunks
+                .flatMap((hunk) => hunk.lines.filter((line) => line.kind !== 'removed'))
+                .map((line) => line.text)
+                .join('\n');
+            return html `<div part="file">
+        ${name ? html `<div part="header"><span part="label">${name}</span></div>` : nothing}
+        <div part="frame">
+          ${this.variant === 'split'
+                ? this.renderSplit(file, width)
+                : html `<pre part="block"><code part="code">${file.hunks.map((hunk) => html `${this.renderHunk(hunk)}${hunk.lines.map((line) => this.renderLine(line, width))}`)}</code></pre>`}
+          ${this.noCopy ? nothing : this.renderCopyButton(now)}
+        </div>
+      </div>`;
+        })}<slot hidden @slotchange=${() => this.requestUpdate()}></slot>`;
+    }
 };
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessCodeBlock.prototype, "diff", void 0);
 __decorate([
     property()
 ], HelixHeadlessCodeBlock.prototype, "label", void 0);
 __decorate([
     property({ attribute: 'no-copy', reflect: true, type: Boolean })
 ], HelixHeadlessCodeBlock.prototype, "noCopy", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessCodeBlock.prototype, "variant", void 0);
 HelixHeadlessCodeBlock = __decorate([
     customElement('helix-headless-code-block')
 ], HelixHeadlessCodeBlock);

package/dist/color-picker/root/color-picker-root.d.ts

@@ -143,9 +143,10 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
     /**
      * Whether this browser can sample a color off the screen.
      *
-     * Settled after the first render rather than at construction, because there is
-     * no `window` on the server, and a button that ships in the markup and does
-     * nothing in Firefox is worse than one that is never offered.
+     * Settled before each render rather than at construction, because a server
+     * has no `EyeDropper` and a button that ships in the markup and does nothing
+     * in Firefox is worse than one that is never offered. Not while hydrating a
+     * server's markup, which was rendered without it.
      */
     private sampling;
     /**

package/dist/color-picker/root/color-picker-root.js

@@ -103,7 +103,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinContr
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        this.sampling = 'EyeDropper' in globalThis;
+        this.finishHydration();
     }
     updated(changed) {
         super.updated(changed);
@@ -151,6 +151,9 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinContr
     willUpdate(changed) {
         super.willUpdate(changed);
         this.internals.ariaInvalid = this.invalid ? 'true' : null;
+        if (!this.hydrating) {
+            this.sampling = 'EyeDropper' in globalThis;
+        }
     }
     renderTools() {
         return html `<${this.tag('button-group')} part="actions" label="Color tools">

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

@@ -298,6 +298,7 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      * component: a form that received "jav" got the filter, not an option.
      */
     private sync;
+    protected firstUpdated(changed: PropertyValues): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     /**

package/dist/combobox/root/combobox-root.js

@@ -10,6 +10,7 @@ import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
+import { optionsAmong } from '../../option/root/option-root.js';
 import '../../listbox/index.js';
 import '../../tag/index.js';
 const isInsertion = (event) => !event.inputType?.startsWith('delete');
@@ -138,7 +139,7 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         return this.value === '' ? [] : this.value.split(',');
     }
     get chosen() {
-        const options = this.listbox?.options ?? [];
+        const options = optionsAmong(this.knownChildren);
         const known = options.length > 0;
         const words = new Map(options.map((option) => [option.value, option.text]));
         return this.values
@@ -214,6 +215,10 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         this.internals.setFormValue(this.value === '' ? null : this.value);
         this.reportRequired(this.value === '', 'Choose one to continue.', 'control');
     }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         this.internals.ariaExpanded = this.open ? 'true' : 'false';

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

@@ -86,6 +86,11 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * child element, which is the slot, so `:not(:has(*))` on it is never true
      * and an empty footer would draw its rule and its padding over nothing. Steps
      * was caught by the same thing.
+     *
+     * Read from the children before each render, and heard from the slot when
+     * they change. The slot alone left the first render without its footer and a
+     * second to follow, and a hydrated palette without one for good: a
+     * declarative shadow root reports its slots before anything listens.
      */
     private footed;
     private get listbox();
@@ -144,6 +149,8 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
     private readonly swallowOptionSelect;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     /**
      * The surface the palette opens in, behind a seam the styled tier can move.

package/dist/command/root/command-root.js

@@ -95,6 +95,16 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
         this.removeEventListener('click', this.handleAlternate, { capture: true });
         document.removeEventListener('keydown', this.handleHotkey);
     }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (this.childrenKnown) {
+            this.footed = this.knownChildren.some((child) => child.slot === 'footer');
+        }
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
     updated(changed) {
         super.updated?.(changed);
         if (!changed.has('open')) {