@fusion.dev/helix-headless 0.160.0 → 0.161.0

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

@@ -5,7 +5,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessChat_1;
-import { ChildrenController, customElement, formatWords, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, requestChange, VirtualizeController, whenHydrated, words, wordsConverter, } from '@fusion.dev/helix-core';
+import { ChildrenController, customElement, drawIcon, focusableElements, formatWords, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, requestChange, VirtualizeController, whenHydrated, words, wordsConverter, } from '@fusion.dev/helix-core';
+import { arrowDown } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { keyed } from 'lit/directives/keyed.js';
@@ -51,6 +52,7 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.label = '';
         this.meLabel = 'You';
         this.messageLabel = '{author}, {time}';
+        this.resumeLabel = 'Jump to latest';
         this.threshold = 48;
         this.turnLabel = 'Message';
         this.turns = [];
@@ -94,6 +96,38 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.handleResume = () => {
             this.resume();
         };
+        this.handleKeydown = (event) => {
+            if (event.defaultPrevented || event.altKey || event.metaKey || event.shiftKey) {
+                return;
+            }
+            const step = event.key === 'PageDown' ? 1 : event.key === 'PageUp' ? -1 : 0;
+            const leave = event.ctrlKey && (event.key === 'End' || event.key === 'Home');
+            if ((step === 0 || event.ctrlKey) && !leave) {
+                return;
+            }
+            const at = this.turnFrom(event.composedPath());
+            if (at === undefined) {
+                return;
+            }
+            if (leave) {
+                const target = event.key === 'End'
+                    ? this.firstControlIn(['composer'])
+                    : (this.firstControlIn(['header', 'actions']) ??
+                        (this.log?.hasAttribute('tabindex') ? this.log : undefined));
+                if (target) {
+                    event.preventDefault();
+                    target.focus();
+                }
+                return;
+            }
+            const count = this.fed ? this.turns.length : this.messages.length;
+            if (count === 0) {
+                return;
+            }
+            event.preventDefault();
+            const next = at < 0 ? this.topTurn() : Math.max(0, Math.min(count - 1, at + step));
+            void this.focusTurn(next);
+        };
         this.handleSlotChange = () => {
             this.assign();
             this.requestUpdate();
@@ -378,6 +412,7 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     }
     connectedCallback() {
         super.connectedCallback();
+        this.addEventListener('keydown', this.handleKeydown);
         this.settling = new MutationObserver(this.handleSettle);
         this.settling.observe(this, { attributeFilter: ['state'], subtree: true });
         this.opening = true;
@@ -390,6 +425,7 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.removeEventListener('keydown', this.handleKeydown);
         this.settling?.disconnect();
         this.settling = undefined;
         this.grower?.disconnect();
@@ -446,11 +482,87 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.announce();
     }
     tellTurns() {
-        for (const message of this.messages) {
+        const messages = this.messages;
+        messages.forEach((message, at) => {
             whenHydrated(message, () => {
                 message.turnWords = this.words;
+                message.turnPosition = at + 1;
+                message.turnCount = messages.length;
             });
+        });
+    }
+    turnFrom(path) {
+        for (const target of path) {
+            if (!(target instanceof HTMLElement)) {
+                continue;
+            }
+            if (this.fed && target.getAttribute('part') === 'turn') {
+                return Number(target.dataset.index);
+            }
+            if (!this.fed && 'isChatMessage' in target) {
+                const at = this.messages.indexOf(target);
+                if (at >= 0) {
+                    return at;
+                }
+            }
+            if (target === this.log) {
+                return -1;
+            }
+        }
+        return undefined;
+    }
+    topTurn() {
+        const id = this.anchor?.id;
+        if (id === undefined) {
+            return 0;
         }
+        const at = this.fed
+            ? this.turns.findIndex((turn) => this.identity(turn) === id)
+            : this.messages.indexOf(id);
+        return Math.max(0, at);
+    }
+    async focusTurn(at) {
+        const count = this.fed ? this.turns.length : this.messages.length;
+        if (at < count - 1 && this.pinned) {
+            this.requestPinned(false);
+        }
+        if (this.fed) {
+            const drawn = () => this.renderRoot
+                ?.querySelector(`[part="turn"][data-index="${at}"]`)
+                ?.querySelector(':scope > *');
+            if (!drawn()) {
+                this.virtualize.reveal(at);
+                this.virtualize.measure();
+                this.requestUpdate();
+                await this.updateComplete;
+            }
+            drawn()?.focus();
+            return;
+        }
+        const message = this.messages[at];
+        if (!message) {
+            return;
+        }
+        if (!message.hasAttribute('tabindex')) {
+            message.setAttribute('tabindex', '-1');
+        }
+        message.focus();
+    }
+    firstControlIn(names) {
+        for (const name of names) {
+            for (const child of this.given(name)) {
+                if (child instanceof HTMLElement) {
+                    const found = child.localName.includes('-') ||
+                        child.matches('button, a[href], input, textarea, select, [tabindex]')
+                        ? child
+                        : focusableElements(child)[0];
+                    if (found) {
+                        return found;
+                    }
+                }
+            }
+        }
+        return undefined;
     }
     renderTurns() {
         const { after, before, first, last } = this.virtualize.window;
@@ -467,12 +579,22 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
               at=${turn.at ?? nothing}
               style=${ownEntry(this.authorStyles, turn.author) ?? nothing}
               .turnWords=${this.words}
+              .turnPosition=${first + offset + 1}
+              .turnCount=${this.turns.length}
+              tabindex="-1"
               .failedLabel=${this.failedLabel}
               state=${turn.state ?? nothing}
             >${turn.text}</${message}>
           </div>`)}
       <div part="after" role="presentation" style="block-size: ${after}px; flex: none"></div>`;
     }
+    renderResume() {
+        return html `<slot name="resume"
+      ><button part="resume-button" type="button">
+        <span part="resume-mark" aria-hidden="true">${drawIcon(arrowDown)}</span>${this.resumeLabel}
+      </button></slot
+    >`;
+    }
     render() {
         const away = !this.pinned;
         const fed = this.fed;
@@ -499,8 +621,8 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         ${this.renderStatus(fed || this.messages.length > 0 || !this.childrenKnown)}
       </div>
       <span part="live" role="status">${keyed(this.said, this.announcement)}</span>
-      <div part="resume" ?hidden=${!away || !this.has('resume')} @click=${this.handleResume}>
-        <slot name="resume"></slot>
+      <div part="resume" ?hidden=${!away} @click=${this.handleResume}>
+        ${this.renderResume()}
       </div>
       <div part="status" role="status" ?data-empty=${!this.has('status') && this.typing === ''}>
         <slot name="status"></slot>${this.typing === ''
@@ -558,6 +680,10 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessChat.prototype, "pinned", null);
+__decorate([
+    words,
+    property({ attribute: 'resume-label' })
+], HelixHeadlessChat.prototype, "resumeLabel", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessChat.prototype, "threshold", void 0);

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

@@ -11,3 +11,15 @@ export declare const lineCount: (code: string) => number;
  * `<pre>` draws beside the code. The stylesheet aligns them to the end.
  */
 export declare const gutterNumbers: (count: number) => string;
+/**
+ * The runs of lines a list of numbers and ranges names, such as `2, 4-6`, as
+ * `[first, last]` pairs counted from 1, in order and merged where they touch.
+ * Anything that is not a whole number or a range of them is passed over, and
+ * a range written backward is read forward.
+ */
+export declare const lineRuns: (list: string) => Array<[number, number]>;
+/**
+ * Where each line of `text` starts and ends, as character offsets, the line
+ * break left out. A final line break ends the last line, as `lineCount` reads it.
+ */
+export declare const lineSpans: (text: string) => Array<[number, number]>;

package/dist/code-block/lines.js

@@ -1,2 +1,43 @@
 export const lineCount = (code) => code === '' ? 0 : code.replace(/\r?\n$/, '').split(/\r?\n/).length;
 export const gutterNumbers = (count) => Array.from({ length: count }, (_, index) => String(index + 1)).join('\n');
+export const lineRuns = (list) => {
+    const runs = [];
+    for (const piece of list.split(/[\s,]+/)) {
+        const range = /^(\d+)(?:-(\d+))?$/.exec(piece);
+        if (!range) {
+            continue;
+        }
+        const a = Number(range[1]);
+        const b = Number(range[2] ?? range[1]);
+        if (a < 1 || b < 1) {
+            continue;
+        }
+        runs.push([Math.min(a, b), Math.max(a, b)]);
+    }
+    runs.sort((x, y) => x[0] - y[0]);
+    const merged = [];
+    for (const run of runs) {
+        const last = merged.at(-1);
+        if (last && run[0] <= last[1] + 1) {
+            last[1] = Math.max(last[1], run[1]);
+        }
+        else {
+            merged.push([run[0], run[1]]);
+        }
+    }
+    return merged;
+};
+export const lineSpans = (text) => {
+    const spans = [];
+    const body = text.replace(/\r?\n$/, '');
+    if (body === '' && text === '') {
+        return spans;
+    }
+    let start = 0;
+    for (const match of body.matchAll(/\r?\n/g)) {
+        spans.push([start, match.index]);
+        start = match.index + match[0].length;
+    }
+    spans.push([start, body.length]);
+    return spans;
+};

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

@@ -15,7 +15,18 @@ import '../../copy-button/index.js';
  * For a fragment of code inside a sentence, use `Code`.
  *
  * Set `line-numbers` to number the lines in a gutter beside the code, hidden
- * from the accessibility tree and left out of a copy. Set `highlight` to a
+ * from the accessibility tree and left out of a copy. Set `mark-lines` to
+ * mark lines a reader should look at, such as `2, 4-6`: the block draws a
+ * band behind each run, placed where the lines are laid out, so it follows a
+ * highlighter's markup and lines that wrap. Set `wrap` to wrap long lines
+ * rather than scroll them; a gutter then numbers each line where it starts.
+ * Set `wrappable` for a button in the header that turns `wrap` on and off,
+ * pressed while the lines wrap.
+ *
+ * The header holds the name, the `actions` slot, and the copy button. Slot a
+ * control into `actions`, such as a button that sets `wrap` or one that opens
+ * the code in an editor, and the block draws a header for it even with no
+ * name. `copy-icon` and `copied-icon` replace the copy button's two icons. Set `highlight` to a
  * function that turns the code into highlighted markup, such as one wrapping
  * Shiki or Prism, and the block draws what it returns; it is handed the
  * block's `language`, so one function serves every block. The code stays in
@@ -62,7 +73,14 @@ import '../../copy-button/index.js';
  * @documentation https://fusion.dev/helix/components/code-block
  *
  * @slot - The code.
+ * @slot actions - Controls for the block, in the header before the copy button.
+ * @slot copied-icon - The copy button's icon after a copy. Defaults to a check mark.
+ * @slot copy-icon - The copy button's icon before a copy. Defaults to a clipboard.
+ *
+ * @event {HelixBeforeToggleEvent} helix-before-toggle - The wrap button was pressed, with the `wrap` it asks for in `detail.checked`. Cancelable: cancel it to keep the lines as they are.
+ * @event {HelixToggleEvent} helix-toggle - Fired after the wrap button changed `wrap`, with the new value in `detail.checked`.
  *
+ * @csspart actions - The box in the header that holds the `actions` slot, drawn while something is slotted there.
  * @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.
@@ -91,13 +109,20 @@ import '../../copy-button/index.js';
  * @csspart header - The bar that holds the name and the copy button, shown when there is a name.
  * @csspart hunk - In a diff, a `@@` line saying where the lines under it are.
  * @csspart label - The block's name: its `label`, or its `language` where it has no label.
+ * @csspart mark - The band behind a run of lines `mark-lines` names. The block writes where the run is laid out into `--code-block-mark-start`, `--code-block-mark-size`, and `--code-block-mark-inline-size` on it. Hidden from the accessibility tree.
  * @csspart marker - In a diff, the `+`, `-`, or space that starts a line.
  * @csspart new - In a split diff, the new version's `<pre>`.
- * @csspart number - In a diff, a line number.
+ * @csspart number - In a diff, a line number. In a `wrap` block with `line-numbers`, one line's number in the gutter, which the block makes as tall as the line it numbers through `--code-block-line-size`.
  * @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.
+ * @csspart wrap-toggle - The button in the header that wraps the lines and unwraps them, drawn when `wrappable` is set.
+ *
+ * @cssproperty --code-block-line-size - Written by the block on each `number` in a `wrap` block with `line-numbers`: how tall the line it numbers is laid out. Do not set it.
+ * @cssproperty --code-block-mark-inline-size - Written by the block on each `mark`: how wide the code is, scrolled part included. Do not set it.
+ * @cssproperty --code-block-mark-size - Written by the block on each `mark`: how tall its run of lines is. Do not set it.
+ * @cssproperty --code-block-mark-start - Written by the block on each `mark`: how far down the code its run of lines starts. Do not set it.
  *
  * @cssstate expanded - The expand button has shown every line of a capped block.
  */
@@ -210,6 +235,12 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * whether or not this is set.
      */
     lineNumbers: boolean;
+    /**
+     * The lines to mark, as numbers and ranges counted from 1, such as `2, 4-6`.
+     * Each run is drawn as a band behind its lines. Not for a diff, which marks
+     * its own changes.
+     */
+    markLines: string;
     /**
      * Whether to leave the copy button off.
      *
@@ -240,6 +271,26 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * than defaulted, so the host carries no attribute the consumer did not write.
      */
     variant?: 'split';
+    /**
+     * Whether long lines wrap. Without it they scroll.
+     *
+     * Off by default, so long lines scroll, because a line break can be
+     * significant in code and a wrapped line reads as two. For prose-like code,
+     * such as a long command or a log line, a wrap reads better than a scroll.
+     * With `line-numbers`, each number stands beside the line it numbers
+     * however many rows that line takes. Reflected, because the stylesheet
+     * wraps the lines.
+     */
+    wrap: boolean;
+    /** The wrap button's name, which it keeps whether it is pressed or not. */
+    wrapLabel: string;
+    /**
+     * Whether the header has a button that wraps the lines and unwraps them. The
+     * block draws a header for it even with no name.
+     */
+    wrappable: boolean;
+    /** Asks to wrap or unwrap the lines, and says so once it has. */
+    private toggleWrap;
     /** 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. */
@@ -294,6 +345,20 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * and a stop on it would scroll nothing.
      */
     private markScrollers;
+    /**
+     * Where each line of the code is laid out in the `<code>`, from the top of
+     * its content, as the browser placed the text: one row, or several where it
+     * wraps.
+     */
+    private lineBoxes;
+    /**
+     * Places each mark behind its run of lines, and makes each number in a
+     * wrapping gutter as tall as its line, from where the lines are laid out.
+     *
+     * **Written onto the elements as custom properties**, which are facts the
+     * block computed and CSS cannot, and no render follows from them.
+     */
+    private placeLines;
     protected updated(changed: PropertyValues): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -305,6 +370,8 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * measure, so a served block draws none and the client adds it.
      */
     private renderExpand;
+    /** Whether the block draws a header: it has a name, a wrap button, or a control in `actions`. */
+    private headed;
     /**
      * The name with the copy button beside it, or nothing when there is no name.
      *
@@ -313,11 +380,19 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * diff cannot: its washes run to the edge, so the button stood on the hunk
      * line and the line under it. In the header it is over nothing.
      *
-     * **No name draws no header**, rather than a bar to hold one button, which
-     * turned a `Usage` section of one-line imports into a run of empty strips.
-     * The button then stands beside the code, in room the block keeps for it.
+     * **No name draws no header**, unless the page put a control in `actions`
+     * or asked for the wrap button. A bar holding the copy button alone turned a
+     * `Usage` section of one-line imports into a run of empty strips. The button
+     * then stands beside the code, in room the block keeps for it.
      */
     private renderHeader;
+    /** The button that wraps the lines and unwraps them, where `wrappable` asks for one. Not for a diff. */
+    private renderWrapToggle;
+    /**
+     * Whether the page slotted something into `name`. Not known on a server or
+     * while hydrating what one sent, which render as though nothing were.
+     */
+    private slotted;
     private renderCopy;
     /**
      * The button that takes the code, behind a seam the styled tier can move.
@@ -333,6 +408,14 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * @param name The name of what it copies, which its label carries.
      */
     protected renderCopyButton(value?: string, name?: string): TemplateResult;
+    /**
+     * The page's own icons for the copy button, passed on through slots of the
+     * block's, where the page slotted them. A slot passed on with nothing in it
+     * would stand in for the button's own icon and draw nothing, so it is drawn
+     * only for an icon the page gave. In a diff, the first file's button takes
+     * them, a slotted element going to one slot.
+     */
+    private renderCopyIcons;
     /** A number padded to the widest in its file, so the columns line up as text. */
     private renderNumber;
     private renderLine;