@fusion.dev/helix-headless 0.170.0 → 0.172.0

package/dist/chat/composer/chat-composer.d.ts

@@ -25,7 +25,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * field taking more. A draft that fails them does not send, and the composer
  * takes `:state(invalid)` and `aria-invalid` once the reader has tried to send
  * it, the form was submitted, or the reader edited the field and left it.
- * Tabbing past an empty composer marks nothing.
+ * Sending an empty required composer counts as trying. Tabbing past an empty
+ * composer marks nothing.
+ *
+ * **`feedback` is a message of your own about the draft**, such as one your
+ * server sent back. While it is set, the composer is invalid at once, does
+ * not send or submit, shows the message under the field, and a screen reader
+ * hears it as it appears. Clear it to let the draft go.
  *
  * **`typing` says whether the user is writing**, and `helix-typing` is sent
  * each time it changes: when they start, and when they send or stop for
@@ -47,13 +53,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @csspart composer - The whole composer.
  * @csspart end - The box around the `end` slot.
+ * @csspart feedback - The `feedback` message, under the field while it is set.
  * @csspart field - The text field.
  * @csspart mark - The icon inside the send button.
  * @csspart send - The send button.
  * @csspart start - The box around the `start` slot.
  * @csspart tools - The row under the field.
  *
- * @cssstate invalid - The draft fails `required`, `minlength`, `maxlength`, or a custom error, and the reader has tried to send or submit it, or edited the field and left it.
+ * @cssstate invalid - The draft fails `required`, `minlength`, `maxlength`, or a custom error, and the reader has tried to send or submit it, or edited the field and left it. Or `feedback` is set.
  */
 export declare class HelixHeadlessChatComposer extends HelixFormElement {
     /**
@@ -61,6 +68,12 @@ export declare class HelixHeadlessChatComposer extends HelixFormElement {
      * `registerWords('de', { 'helix-chat-composer': { sendLabel: 'Senden' } })`.
      */
     static words: string;
+    /**
+     * A message about the draft, shown under the field. While set, the composer
+     * is invalid, does not send, and does not submit, as a field's `feedback`
+     * does, and the message is announced as it appears.
+     */
+    feedback: string;
     /**
      * The field's name, read by screen readers.
      */
@@ -122,6 +135,17 @@ export declare class HelixHeadlessChatComposer extends HelixFormElement {
     private writing;
     /** Whether the reader has tried to send or submit the draft, or edited it and left. */
     private touched;
+    /**
+     * Whether the reader has typed in the field since it last held a fresh
+     * draft: since it rendered, since a send cleared it, or since a reset.
+     *
+     * **A send clears the field, and the field still sends `change` as it is
+     * left**, because the platform compares the text with what it held when it
+     * was focused. Measured in Chromium before this: a required composer sent
+     * "hi", cleared, and on Tab showed itself invalid over an empty draft
+     * nobody had written.
+     */
+    private edited;
     /** Whether the composer shows that its draft is wrong. */
     private shownInvalid;
     /** The pause after which the user has stopped writing. */
@@ -146,10 +170,14 @@ export declare class HelixHeadlessChatComposer extends HelixFormElement {
      * back to. `value` does not reflect, so its attribute stays as written.
      */
     private get declared();
+    /** @internal `feedback` marks the composer invalid, as a field's does. */
+    protected get validityFeedback(): string;
     /** Puts back the draft the markup declared when the form is reset. */
     formResetCallback(): void;
     /** The reader has had a go at the draft, so whether it is wrong can be shown. */
     private readonly touch;
+    /** The field's `change`, which counts only after the reader typed in it. */
+    private readonly handleChange;
     /** Brings back the draft when the browser restores the form. */
     formStateRestoreCallback(state: string | File | FormData | null): void;
     /**

package/dist/chat/composer/chat-composer.js

@@ -13,6 +13,7 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFormElement {
     constructor() {
         super(...arguments);
+        this.feedback = '';
         this.label = 'Message';
         this.placeholder = '';
         this.required = false;
@@ -24,15 +25,22 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
         this.isChatComposer = true;
         this.writing = false;
         this.touched = false;
+        this.edited = false;
         this.shownInvalid = false;
         this.pause = new DelayController(this, { renders: false });
         this.touch = () => {
             this.touched = true;
             this.requestUpdate();
         };
+        this.handleChange = () => {
+            if (this.edited) {
+                this.touch();
+            }
+        };
         this.handleInput = (event) => {
             event.stopPropagation();
             this.value = event.target.value;
+            this.edited = true;
             this.dispatchEvent(new Event('input'));
             this.markTyping(this.value !== '');
         };
@@ -69,7 +77,13 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
     }
     send() {
         const value = this.value.trim();
-        if (value === '' || this.isDisabled) {
+        if (this.isDisabled) {
+            return false;
+        }
+        if (value === '') {
+            if (this.required) {
+                this.touch();
+            }
             return false;
         }
         if (!this.internals.validity.valid) {
@@ -81,16 +95,21 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
         }
         this.value = '';
         this.touched = false;
+        this.edited = false;
         this.markTyping(false);
         return true;
     }
     get declared() {
         return this.getAttribute('value') ?? '';
     }
+    get validityFeedback() {
+        return this.feedback;
+    }
     formResetCallback() {
         super.formResetCallback();
         this.value = this.declared;
         this.touched = false;
+        this.edited = false;
         this.requestUpdate();
     }
     formStateRestoreCallback(state) {
@@ -111,7 +130,7 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
         if (field?.validity) {
             this.internals.setValidity(field.validity, field.validationMessage, field);
         }
-        const invalid = this.touched && !this.internals.validity.valid;
+        const invalid = this.feedback !== '' || (this.touched && !this.internals.validity.valid);
         this.toggleState('invalid', invalid);
         this.internals.ariaInvalid = invalid ? 'true' : 'false';
         if (invalid !== this.shownInvalid) {
@@ -160,8 +179,9 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
         minlength=${this.minLength ?? nothing}
         maxlength=${this.maxLength ?? nothing}
         aria-invalid=${this.shownInvalid ? 'true' : nothing}
+        aria-describedby=${this.feedback === '' ? nothing : 'feedback'}
         ?disabled=${this.isDisabled}
-        @change=${this.touch}
+        @change=${this.handleChange}
         @input=${this.handleInput}
         @keydown=${this.handleKey}
       ></textarea>
@@ -170,9 +190,14 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
         <span part="end"><slot name="end"></slot></span>
         ${this.renderSend()}
       </div>
-    </div>`;
+    </div>${this.feedback === ''
+            ? nothing
+            : html `<p part="feedback" id="feedback" role="alert">${this.feedback}</p>`}`;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessChatComposer.prototype, "feedback", void 0);
 __decorate([
     words,
     property()

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

@@ -37,16 +37,31 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * `loading` while you fetch, then prepend the older turns. The turn the user
  * was reading stays in place on screen.
  *
+ * The transcript is a `log`, the role for content added in order where the
+ * newest matters most, and it answers the APG feed's keys. The `feed` role
+ * reads its articles as a list from the top, with no newest end to stay
+ * pinned to, so the log keeps the role a conversation has. While `loading` is
+ * set or older turns load, the log carries `aria-busy`, as the APG asks of a
+ * feed.
+ *
  * The log is `aria-live="off"`. A separate status region announces each new
  * turn once, when it has finished arriving. It skips the user's own turns
  * unless they failed to send, turns loaded as history, and the turns already
  * there when the transcript opened. A turn is said with its author first, such
  * as "Ada: It ships today" (`arrival-label`), where its author can be named.
  *
- * Pass the turns as children or as `turns` data. Do not use both. Children
- * render from the server and suit most conversations. `turns` draws a long
+ * Pass the turns as children or as `turns` data. Do not use both: a chat given
+ * both draws every turn from `turns` and then the children, and says so once
+ * in the console. Children render from the server and suit most
+ * conversations. `turns` draws a long
  * transcript one window at a time, so the log needs a block size of its own.
  *
+ * The log scrolls on this tier. It carries `data-scroller`, and `core` ships
+ * `[data-scroller] { overflow: auto }` into every shadow root, so pinning,
+ * history and the window work with no stylesheet. You still need to give the
+ * log a block size, such as `helix-headless-chat::part(log) { block-size:
+ * 20rem }`.
+ *
  * **A conversation is built from three elements.** The chat holds the
  * transcript, a `Chat.Message` stands for each turn, and a `Chat.Composer` sits
  * in the `composer` slot. When the user sends, `helix-send` reaches the chat:
@@ -60,7 +75,12 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * it takes them away. Anything slotted into `status` is drawn first.
  *
  * **Keyboard.** The transcript moves between turns the way a feed does. Each
- * turn says its place, such as "3 of 40", windowed or not.
+ * turn says its place, such as "3 of 40", windowed or not. The transcript is
+ * a tab stop while it holds a turn, and the turn a reader moved to is one
+ * too. Moving to an older turn unpins a transcript that scrolls and scrolls
+ * the turn into view, and moving to the newest pins it again. When the turn
+ * holding focus is removed, focus moves to the turn that took its place, or to
+ * the one before it where it was the last.
  *
  * | Key | What it does |
  * |---|---|
@@ -115,7 +135,7 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * @csspart indicator - The three dots before the words that say who is typing, which the styled tier animates as a message's are. Hidden from screen readers.
  * @csspart live - The region where screen readers announce each turn once it has arrived.
  * @csspart loading - Shown while the history loads.
- * @csspart log - The transcript, which scrolls.
+ * @csspart log - The transcript, which scrolls. On this tier, it needs only a block size.
  * @csspart message - The message drawn for a turn from `turns`, forwarded whole.
  * @csspart message-actions - The controls on a turn from `turns`, beside its time.
  * @csspart message-avatar - The avatar box of a turn from `turns`.
@@ -142,6 +162,11 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * @csspart status - The status region, outside the log.
  * @csspart turn - The wrapper around the message drawn for one turn from `turns`.
  * @csspart typing - The words that say who is typing, in the status band, while `typing` names someone.
+ *
+ * @cssstate empty - The conversation has no turns.
+ * @cssstate loading - Older turns are loading: `history` is `loading`.
+ * @cssstate pinned - The transcript follows its newest turn.
+ * @cssstate typing - `typing` names someone on the other side.
  */
 export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
     /**
@@ -362,13 +387,16 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
     /** The element that scrolls, once there is one. */
     private get log();
     /**
-     * Makes the log a tab stop while it scrolls, and takes the stop away when it
-     * does not.
+     * Makes the log a tab stop while it holds a turn or scrolls, and takes the
+     * stop away from an empty log.
      *
      * **A reader on a keyboard scrolls the history from the log itself.**
      * Chromium and Firefox make a box that scrolls focusable on their own, and
      * Safari does not, so there the arrow keys could not reach a long history.
-     * A log that fits is no stop at all, so Tab goes straight to the composer.
+     *
+     * **And it is where the turns are entered.** Page Down from the log goes to
+     * the turn at the top of the view. A log that fits was no stop at all, so a
+     * conversation whose turns held no control had no way into them by keyboard.
      */
     private markScroller;
     /** Whether the reader is within `threshold` of the bottom right now. */
@@ -491,6 +519,10 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
+    /** Whether the chat has said it was given turns both ways. */
+    private warnedMixed;
+    /** Says once that turns arrived both as children and as `turns`. */
+    private warnMixed;
     /**
      * Keeps the window on the same turns when the set changes around them.
      *
@@ -501,6 +533,27 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      */
     private follow;
     protected updated(changed: PropertyValues): void;
+    /** The turn focus is in, by its place and its identity, once a reader is in one. */
+    private held;
+    /** Notes the turn focus went into, or that it went somewhere else. */
+    private readonly handleFocusIn;
+    /**
+     * Forgets the turn once focus moves to something outside the transcript.
+     * A move to nothing is kept, since removing the turn that held focus is
+     * one.
+     */
+    private readonly handleFocusOut;
+    /**
+     * Moves focus to a neighbor where removing the turn that held it dropped
+     * focus to the body: the turn that took its place, or the one before it
+     * where it was the last.
+     *
+     * **Focus went to the body**, and Page Down did nothing until the reader
+     * tabbed back into the transcript. List and Virtual List move focus to a
+     * neighbor the same way, as React Aria's GridList does. Focus anywhere but
+     * the body is where you put it, and is left there.
+     */
+    private followRemoved;
     /**
      * Hands each turn written as a child the words it is named with, once it
      * has hydrated, so its first render is the server's.
@@ -522,6 +575,8 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * and never on a turn nobody moved to.
      */
     private focusTurn;
+    /** Draws turn `at` where it is windowed and not drawn, and visits it. */
+    private showTurn;
     /** The turn that is a tab stop because a reader moved to it. */
     private stop;
     /**
@@ -534,6 +589,17 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * `tabindex` you wrote on a turn is left as it is.
      */
     private visit;
+    /** Where this element last scrolled the transcript to show a turn, until the scroll that follows. */
+    private placed;
+    /**
+     * Scrolls the transcript, and nothing around it, until `turn` is in view,
+     * and notes the turn at the top as the reader's place. A pinned transcript
+     * is left at the bottom, which is where whoever holds the pin wants it.
+     *
+     * The edge nearest the turn moves the least, and a turn taller than the
+     * transcript is shown from its start.
+     */
+    private reveal;
     /** The first control in the regions `names` holds, in their order. */
     private firstControlIn;
     /**

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

@@ -5,7 +5,7 @@ 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, drawIcon, focusableElements, formatWords, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, requestChange, UpgradeController, VirtualizeController, whenHydrated, words, wordsConverter, } from '@fusion.dev/helix-core';
+import { ChildrenController, customElement, deepActiveElement, drawIcon, focusableElements, formatWords, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, reportRuntime, requestChange, UpgradeController, 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';
@@ -97,6 +97,22 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.handleResume = () => {
             this.resume();
         };
+        this.warnedMixed = false;
+        this.handleFocusIn = (event) => {
+            const at = this.turnFrom(event.composedPath());
+            if (at === undefined || at < 0) {
+                this.held = undefined;
+                return;
+            }
+            const id = this.fed ? this.identity(this.turns[at]) : this.messages[at];
+            this.held = { at, id };
+        };
+        this.handleFocusOut = (event) => {
+            const to = event.relatedTarget;
+            if (to instanceof Node && !this.contains(to) && !this.renderRoot?.contains?.(to)) {
+                this.held = undefined;
+            }
+        };
         this.handleKeydown = (event) => {
             if (event.defaultPrevented || event.altKey || event.metaKey || event.shiftKey) {
                 return;
@@ -138,6 +154,13 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         };
         this.handleScroll = () => {
             const log = this.log;
+            const placed = this.placed;
+            this.placed = undefined;
+            if (log && placed !== undefined && Math.abs(log.scrollTop - placed) < 1 && !this.pinned) {
+                this.remember();
+                this.reachHistory();
+                return;
+            }
             if (this.pinned && log && log.scrollTop >= this.stuckAt - 1 && !this.atBottom) {
                 this.stick();
             }
@@ -183,7 +206,8 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         if (!log) {
             return;
         }
-        if (log.scrollHeight > log.clientHeight) {
+        const turns = this.fed ? this.turns.length : this.messages.length;
+        if (turns > 0 || log.scrollHeight > log.clientHeight) {
             log.tabIndex = 0;
         }
         else {
@@ -414,6 +438,8 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('keydown', this.handleKeydown);
+        this.addEventListener('focusin', this.handleFocusIn);
+        this.addEventListener('focusout', this.handleFocusOut);
         this.settling = new MutationObserver(this.handleSettle);
         this.settling.observe(this, { attributeFilter: ['state'], subtree: true });
         this.opening = true;
@@ -427,6 +453,8 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('keydown', this.handleKeydown);
+        this.removeEventListener('focusin', this.handleFocusIn);
+        this.removeEventListener('focusout', this.handleFocusOut);
         this.settling?.disconnect();
         this.settling = undefined;
         this.grower?.disconnect();
@@ -449,6 +477,22 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         if (changed.has('turns')) {
             this.follow(changed.get('turns'));
         }
+        this.warnMixed();
+        this.toggleState('pinned', this.pinned);
+        this.toggleState('typing', this.typing !== '');
+        this.toggleState('loading', this.history === 'loading');
+        this.toggleState('empty', this.childrenKnown && this.turns.length === 0 && this.messages.length === 0);
+    }
+    warnMixed() {
+        if (this.warnedMixed || this.turns.length === 0 || this.messages.length === 0) {
+            return;
+        }
+        this.warnedMixed = true;
+        reportRuntime({
+            kind: 'mixed-turns',
+            message: `A chat was given ${this.messages.length} turns as children and ${this.turns.length} as \`turns\`, and draws the children after every turn from \`turns\`. Pass one or the other.`,
+            tag: this.localName,
+        });
     }
     follow(previous) {
         if (!previous?.length || this.turns.length === 0) {
@@ -481,6 +525,23 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.remember();
         this.reachHistory();
         this.announce();
+        this.followRemoved();
+    }
+    followRemoved() {
+        const held = this.held;
+        if (held === undefined) {
+            return;
+        }
+        const ids = this.fed ? this.turns.map((turn) => this.identity(turn)) : this.messages;
+        if (ids.includes(held.id)) {
+            return;
+        }
+        this.held = undefined;
+        const active = deepActiveElement();
+        if (ids.length === 0 || (active !== null && active !== document.body)) {
+            return;
+        }
+        void this.focusTurn(Math.min(held.at, ids.length - 1));
     }
     tellTurns() {
         const messages = this.messages;
@@ -526,9 +587,15 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         const count = this.fed ? this.turns.length : this.messages.length;
         const log = this.log;
         const scrolls = log !== null && log !== undefined && log.scrollHeight > log.clientHeight;
-        if (at < count - 1 && this.pinned && scrolls) {
-            this.requestPinned(false);
+        if (at < count - 1 && this.pinned && scrolls && this.requestPinned(false)) {
+            await this.updateComplete;
+        }
+        await this.showTurn(at);
+        if (at === count - 1 && !this.pinned && this.atBottom) {
+            this.requestPinned(true);
         }
+    }
+    async showTurn(at) {
         if (this.fed) {
             const drawn = () => this.renderRoot
                 ?.querySelector(`[part="turn"][data-index="${at}"]`)
@@ -559,7 +626,24 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
                 this.stop = turn;
             }
         }
-        turn.focus();
+        turn.focus({ preventScroll: true });
+        this.reveal(turn);
+    }
+    reveal(turn) {
+        const log = this.log;
+        if (!log || this.pinned) {
+            return;
+        }
+        const box = log.getBoundingClientRect();
+        const rect = turn.getBoundingClientRect();
+        const by = rect.top < box.top || rect.height > box.height
+            ? rect.top - box.top
+            : Math.max(0, rect.bottom - box.bottom);
+        if (Math.abs(by) >= 1) {
+            log.scrollTop += by;
+            this.placed = log.scrollTop;
+        }
+        this.remember();
     }
     firstControlIn(names) {
         for (const name of names) {
@@ -622,6 +706,7 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         part="log"
         role="log"
         aria-live="off"
+        data-scroller
         aria-label=${this.label || this.fallbackLabel}
         aria-busy=${busy ? 'true' : nothing}
         ?data-windowed=${fed}

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

@@ -18,7 +18,11 @@ import '../../copy-button/index.js';
  * 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
+ * highlighter's markup and lines that wrap. `added-lines` and
+ * `removed-lines` mark lines the same way as inserted and deleted, as
+ * Expressive Code's `ins` and `del` do, in code that is not a diff. The bands
+ * are drawn and hidden from screen readers, so say in the text around the
+ * block what a marked line means. 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.
@@ -93,6 +97,8 @@ import '../../copy-button/index.js';
  * @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.
+ * @slot expand-icon - An icon on the button that shows every line of a capped block, before its words.
+ * @slot label - The block's name in the header, such as a file icon beside the file name. Replaces `label` and `language` there, and draws the header.
  *
  * @event {Event} change - A file tab showed its file, whose name `file` now holds.
  * @event {HelixBeforeChangeEvent} helix-before-change - A file tab is about to show its file, with the file's name in `detail.value`. Cancelable: cancel it to keep the file shown.
@@ -134,7 +140,9 @@ 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 mark - The band behind a run of lines `mark-lines`, `added-lines` or `removed-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 mark-added - The band behind a run of lines `added-lines` names. Applied with `mark`.
+ * @csspart mark-removed - The band behind a run of lines `removed-lines` names. Applied with `mark`.
  * @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. 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`.
@@ -158,6 +166,11 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * `registerWords('de', { 'helix-code-block': { copyLabel: 'Code kopieren' } })`.
      */
     static words: string;
+    /**
+     * The lines to mark as inserted, as numbers and ranges counted from 1, such
+     * as `3-4`. Drawn as `mark-lines` is, in the added color. Not for a diff.
+     */
+    addedLines: string;
     /**
      * The name of a block that scrolls, which is a tab stop while it does.
      *
@@ -312,6 +325,11 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * `false`.
      */
     noCopy: boolean;
+    /**
+     * The lines to mark as deleted, as numbers and ranges counted from 1. Drawn
+     * as `mark-lines` is, in the removed color. Not for a diff.
+     */
+    removedLines: string;
     /**
      * The words of a button that shows a folded run of unchanged lines, in a
      * diff with `context-lines`. `{count}` is how many.

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

@@ -27,6 +27,7 @@ const nameOf = (block) => {
 let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
     constructor() {
         super(...arguments);
+        this.addedLines = '';
         this.codeLabel = 'Code';
         this.codeNameLabel = '{code}, {name}';
         this.collapseLabel = 'Show fewer lines';
@@ -43,6 +44,7 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         this.lineNumbers = false;
         this.markLines = '';
         this.noCopy = false;
+        this.removedLines = '';
         this.showUnchangedLabel = '{count, plural, one {Show # unchanged line} other {Show # unchanged lines}}';
         this.wrap = false;
         this.wrapLabel = 'Wrap lines';
@@ -223,7 +225,7 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
     }
     placeLines() {
         const code = this.renderRoot.querySelector('[part="code"]');
-        const marks = [...this.renderRoot.querySelectorAll('[part="mark"]')];
+        const marks = [...this.renderRoot.querySelectorAll('[part~="mark"]')];
         const numbers = [
             ...this.renderRoot.querySelectorAll('[part="gutter"] > [part="number"]'),
         ];
@@ -356,8 +358,13 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         catch (error) {
             globalThis.reportError?.(error);
         }
-        const runs = this.childrenKnown ? lineRuns(this.markLines) : [];
-        const marks = runs.map(([first, last]) => html `<span part="mark" aria-hidden="true" data-lines="${first}-${last}"></span>`);
+        const marks = this.childrenKnown
+            ? [
+                ...lineRuns(this.markLines).map(([first, last]) => html `<span part="mark" aria-hidden="true" data-lines="${first}-${last}"></span>`),
+                ...lineRuns(this.addedLines).map(([first, last]) => html `<span part="mark mark-added" aria-hidden="true" data-lines="${first}-${last}"></span>`),
+                ...lineRuns(this.removedLines).map(([first, last]) => html `<span part="mark mark-removed" aria-hidden="true" data-lines="${first}-${last}"></span>`),
+            ]
+            : [];
         const code = highlighted === undefined
             ? html `<code part="code">${marks}<slot @slotchange=${() => this.requestUpdate()}></slot></code>`
             : html `<code part="code">${marks}${unsafeHTML(highlighted)}</code><slot
@@ -376,7 +383,7 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
             : nothing;
         const name = this.label || this.language;
         const drawn = this.tabbed ? '' : name;
-        return html `${this.renderHeader(name, undefined, drawn)}
+        return html `${this.renderHeader(name, undefined, drawn, true)}
       <div part="frame">
         <pre id="block" part="block" translate="no">${gutter}${code}</pre>
         ${this.headed(drawn) ? nothing : this.renderCopy()}
@@ -396,16 +403,24 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
             this.toggleState('expanded', this.expanded);
         }}
     >
-      ${this.expanded ? this.collapseLabel : this.expandLabel}
+      ${this.slotted('expand-icon') ? html `<slot name="expand-icon"></slot>` : nothing}${this.expanded ? this.collapseLabel : this.expandLabel}
     </button>`;
     }
     headed(name) {
-        return name !== '' || (this.wrappable && !this.diff) || this.slotted('actions');
+        return (name !== '' ||
+            (this.wrappable && !this.diff) ||
+            this.slotted('actions') ||
+            (!this.diff && !this.tabbed && this.slotted('label')));
     }
-    renderHeader(name, value, drawn = name) {
+    renderHeader(name, value, drawn = name, own = false) {
         const acting = this.slotted('actions');
+        const label = own && !this.tabbed && this.slotted('label')
+            ? html `<span part="label"><slot name="label">${drawn}</slot></span>`
+            : drawn
+                ? html `<span part="label">${drawn}</span>`
+                : nothing;
         return this.headed(drawn)
-            ? html `<div part="header">${drawn ? html `<span part="label">${drawn}</span>` : nothing}${acting ? html `<span part="actions"><slot name="actions"></slot></span>` : nothing}${this.renderWrapToggle()}${this.renderCopy(value, name)}</div>`
+            ? html `<div part="header">${label}${acting ? html `<span part="actions"><slot name="actions"></slot></span>` : nothing}${this.renderWrapToggle()}${this.renderCopy(value, name)}</div>`
             : nothing;
     }
     renderWrapToggle() {
@@ -501,6 +516,9 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         })}<slot hidden @slotchange=${() => this.requestUpdate()}></slot>`;
     }
 };
+__decorate([
+    property({ attribute: 'added-lines' })
+], HelixHeadlessCodeBlock.prototype, "addedLines", void 0);
 __decorate([
     words,
     property({ attribute: 'code-label' })
@@ -567,6 +585,9 @@ __decorate([
 __decorate([
     property({ attribute: 'no-copy', reflect: true, type: Boolean })
 ], HelixHeadlessCodeBlock.prototype, "noCopy", void 0);
+__decorate([
+    property({ attribute: 'removed-lines' })
+], HelixHeadlessCodeBlock.prototype, "removedLines", void 0);
 __decorate([
     words,
     property({ attribute: 'show-unchanged-label' })