@fusion.dev/helix-headless 0.143.0 → 0.145.0

package/dist/chat/relative-clock.d.ts

@@ -0,0 +1,39 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What the clock reads from its host. */
+export interface RelativeClockOptions {
+    /** The locale the reading is written in. Empty is the runtime's own. */
+    locale: () => string;
+    /** The instant being read, or nothing where there is none. */
+    moment: () => Date | undefined;
+}
+/**
+ * The time a relative reading is drawn against, moved on when the reading
+ * would change.
+ *
+ * **One wakeup when the words go stale, and none in between.** `relativeTime`
+ * says how long its answer holds, so the clock asks core's shared ticker for
+ * exactly that moment: a turn a minute old wakes once a minute, an hour old
+ * once an hour. Every turn on the page shares the ticker's one timer.
+ *
+ * `Format Date` keeps the same arrangement inline, and the two belong in one
+ * core controller.
+ */
+export declare class RelativeClockController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** The time the host last drew against, in milliseconds. */
+    now: number;
+    private stop;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: RelativeClockOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Reads the clock again and schedules the next reading.
+     *
+     * The host calls it when the instant or the locale changes, and the ticker
+     * calls it when the words go stale. **Only on a page**: a server has nobody
+     * to update a reading for, and a subscription there holds the element after
+     * its markup is sent.
+     */
+    tick(): void;
+}

package/dist/chat/relative-clock.js

@@ -0,0 +1,31 @@
+import { relativeTime, subscribe } from '@fusion.dev/helix-core';
+export class RelativeClockController {
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        this.now = Date.now();
+        this.stop = undefined;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.tick();
+    }
+    hostDisconnected() {
+        this.stop?.();
+        this.stop = undefined;
+    }
+    tick() {
+        this.stop?.();
+        this.stop = undefined;
+        this.now = Date.now();
+        this.host.requestUpdate();
+        const moment = this.options.moment();
+        if (!moment || !this.host.isConnected) {
+            return;
+        }
+        const { next } = relativeTime(this.options.locale())(moment, new Date(this.now));
+        if (Number.isFinite(next)) {
+            this.stop = subscribe(next, () => this.tick());
+        }
+    }
+}

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

@@ -7,6 +7,8 @@ export interface ChatTurn {
     at?: string;
     /** Who said it: `me`, `them`, or a name the consumer styles. */
     author?: string;
+    /** Who said it, as a screen reader names the turn, as on `ChatMessage`. */
+    authorLabel?: string;
     /**
      * What identifies it across changes to the set.
      *
@@ -44,6 +46,20 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * 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.
  *
+ * **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:
+ * add their turn with `author="me"` and `state="sending"`, then set `state` to
+ * `sent` or `failed` when your server answers. Add the reply as a turn with
+ * `state="streaming"`, write its text as it arrives, and set `state` to `sent`
+ * when it is complete. While the user types, the composer sends
+ * `helix-typing`, which you can pass on to the other side. Show the other
+ * side's typing in the `status` slot.
+ *
+ * A screen reader names each turn by its author and its time, such as "You, 2
+ * minutes ago". Set `me-label` and `message-label` to say it in your language,
+ * and give each turn by `them` an `author-label`.
+ *
  * A turn from `turns` is drawn in the chat's shadow root, so style it through
  * the forwarded `message-*` parts. A turn by `me` also gets each part with
  * `-mine` added, and the turn's state adds `message-meta-failed`,
@@ -141,6 +157,16 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * The conversation's name, read by screen readers.
      */
     label: string;
+    /**
+     * The word a screen reader says for `me` when it names a turn.
+     */
+    meLabel: string;
+    /**
+     * The name a screen reader gives a turn with both an author and a time.
+     * `{author}` is who wrote it and `{time}` is when, as the turn shows it. A
+     * turn with only one of the two is named by that one.
+     */
+    messageLabel: string;
     /**
      * Whether the transcript follows new turns to the bottom.
      *
@@ -186,6 +212,11 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
     /** The last thing said, and how many times something has been. */
     private announcement;
     private said;
+    /**
+     * The words every turn is named with, kept as one object between changes so
+     * a turn is told again only when they change.
+     */
+    private words;
     /** Watches for turns arriving, since a manual slot hears nothing about them. */
     private watcher;
     /** Watches the turns' own `state`, which is when one of them settles. */
@@ -353,6 +384,11 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      */
     private follow;
     protected updated(changed: PropertyValues): void;
+    /**
+     * 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.
+     */
+    private tellTurns;
     private readonly handleSlotChange;
     private readonly handleSettle;
     /**

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

@@ -5,13 +5,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessChat_1;
-import { customElement, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, requestChange, VirtualizeController, } from '@fusion.dev/helix-core';
+import { customElement, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, requestChange, VirtualizeController, whenHydrated, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { keyed } from 'lit/directives/keyed.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { html } from 'lit/static-html.js';
 import { FAILED_LABEL } from '../message/chat-message.js';
+import { TURN_WORDS } from '../naming.js';
 const REGIONS = ['header', 'actions', 'resume', 'status', 'composer'];
 const SECOND_NAMES = {
     author: {
@@ -39,11 +40,14 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.history = '';
         this.historyText = 'Loading earlier messages';
         this.label = '';
+        this.meLabel = 'You';
+        this.messageLabel = '{author}, {time}';
         this.threshold = 48;
         this.turns = [];
         this.pinnedState = undefined;
         this.announcement = '';
         this.said = 0;
+        this.words = TURN_WORDS;
         this.watcher = undefined;
         this.settling = undefined;
         this.grower = undefined;
@@ -361,6 +365,9 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label || 'Conversation', role: 'region' });
+        if (changed.has('meLabel') || changed.has('messageLabel')) {
+            this.words = { me: this.meLabel, sentence: this.messageLabel };
+        }
         this.countRegions();
         if (changed.has('history')) {
             this.asked = false;
@@ -389,6 +396,7 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     updated(changed) {
         super.updated(changed);
         this.assign();
+        this.tellTurns();
         if (this.pinned) {
             this.stick();
         }
@@ -403,6 +411,13 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.reachHistory();
         this.announce();
     }
+    tellTurns() {
+        for (const message of this.messages) {
+            whenHydrated(message, () => {
+                message.turnWords = this.words;
+            });
+        }
+    }
     renderTurns() {
         const { after, before, first, last } = this.virtualize.window;
         const message = this.tag('chat-message');
@@ -414,7 +429,9 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
                 meta: message-meta, retry: message-retry, sources: message-sources,
                 state: message-state, time: message-time${secondNames(SECOND_NAMES.author, turn.author)}${secondNames(SECOND_NAMES.state, turn.state)}"
               author=${turn.author ?? nothing}
+              author-label=${turn.authorLabel ?? nothing}
               at=${turn.at ?? nothing}
+              .turnWords=${this.words}
               state=${turn.state ?? nothing}
             >${turn.text}</${message}>
           </div>`)}
@@ -469,6 +486,12 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessChat.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'me-label' })
+], HelixHeadlessChat.prototype, "meLabel", void 0);
+__decorate([
+    property({ attribute: 'message-label' })
+], HelixHeadlessChat.prototype, "messageLabel", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessChat.prototype, "pinned", null);

package/dist/checkbox/root/checkbox-root.js

@@ -86,7 +86,9 @@ let HelixHeadlessCheckbox = class HelixHeadlessCheckbox extends MixinControllerC
           ?required=${this.required}
           aria-describedby=${this.describedBy ?? nothing}
           aria-invalid=${this.invalidity ?? nothing}
+          aria-readonly=${this.readOnly ? 'true' : nothing}
           @change=${this.handleChange}
+          @click=${this.holdReadOnly}
           @input=${this.stopInner}
         />
         <span

package/dist/checkbox-group/root/checkbox-group-root.d.ts

@@ -1,6 +1,7 @@
 import { DisabledCascadeController, HelixFormElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import { HelixHeadlessCheckbox } from '../../checkbox/root/checkbox-root.js';
+import '../../checkbox/index.js';
 declare const HelixHeadlessCheckboxGroup_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
  * @summary A group of related checkboxes under one label, with one value for the set.
@@ -19,6 +20,11 @@ declare const HelixHeadlessCheckboxGroup_base: (new (...args: any[]) => import("
  * checkboxes are written, read from the boxes themselves. Setting it checks
  * exactly those values and unchecks the rest.
  *
+ * `select-all` draws a box above the set that checks every enabled box, or
+ * unchecks them all once every one is checked. It shows a dash while only some
+ * are checked, and changes the set through the same cancelable
+ * `helix-before-change` a box does.
+ *
  * A checkbox is a member wherever it sits inside the group, in a row or a grid
  * cell of your own, unless another group inside this one holds it. A field of
  * another kind inside the group, such as an "Other" text field, sends its own
@@ -47,19 +53,47 @@ declare const HelixHeadlessCheckboxGroup_base: (new (...args: any[]) => import("
  * @csspart hint - The help under the checkboxes.
  * @csspart items - The element that holds the checkboxes, laid out by `orientation`.
  * @csspart label - The group's label, above the checkboxes.
+ * @csspart select-all - The box that checks or unchecks every box, under `select-all`.
+ * @csspart select-all-box - The select-all box's box, under the mark.
+ * @csspart select-all-control - The select-all box's native input.
+ * @csspart select-all-feedback - The select-all box's own message, which it never shows.
+ * @csspart select-all-field - The row that holds the select-all box and its label.
+ * @csspart select-all-hint - The select-all box's own help, which it never shows.
+ * @csspart select-all-label - The words beside the select-all box.
+ * @csspart select-all-mark - The select-all box's check mark, or its dash while only some boxes are checked.
+ * @csspart select-all-mark-checked - Added to `select-all-mark` while every box is checked.
+ * @csspart select-all-mark-dash - Added to `select-all-mark` while only some boxes are checked, and kept until every one is.
+ * @csspart select-all-mark-indeterminate - Added to `select-all-mark` while only some boxes are checked.
  *
  * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessCheckboxGroup extends HelixHeadlessCheckboxGroup_base {
+    /**
+     * Whether a box above the set checks or unchecks every enabled box.
+     */
+    selectAll: boolean;
+    /**
+     * The words beside the box `select-all` draws.
+     */
+    selectAllLabel: string;
     /**
      * The checked values, comma separated.
      *
      * Read from the boxes once they are known, so a box a script ticks directly
-     * is in it at once. Written, it is pushed onto the boxes.
+     * is in it at once. Written, it is pushed onto the boxes. A box whose value
+     * holds a comma cannot be named here: use `values`.
      */
     get value(): string;
     set value(next: string);
-    /** The value last written, which the boxes are given at the next update. */
+    /**
+     * The checked values, as a list, in the order the boxes are written.
+     *
+     * The same set as `value`, and the one to use where a value may hold a
+     * comma. Written, it checks exactly those boxes and unchecks the rest.
+     */
+    get values(): string[];
+    set values(next: string[]);
+    /** The values last written, which the boxes are given at the next update. */
     private declared;
     /**
      * Whether `declared` has yet to reach the boxes.
@@ -179,6 +213,22 @@ export declare class HelixHeadlessCheckboxGroup extends HelixHeadlessCheckboxGro
      */
     private validate;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Checks every enabled box, or unchecks them all once every one is checked.
+     *
+     * The box's own request is refused, since the box shows what the set holds
+     * and the set is moved here, through one cancelable `helix-before-change`
+     * for the whole set, as a box moves it.
+     */
+    private readonly handleSelectAll;
+    /**
+     * The box above the set that checks or unchecks every box, under
+     * `select-all`, behind a seam a tier can move.
+     *
+     * Checked while every box is, and showing a dash while only some are. It is
+     * in this shadow root, so it is no member of the set and submits nothing.
+     */
+    protected renderSelectAll(): TemplateResult | typeof nothing;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/checkbox-group/root/checkbox-group-root.js

@@ -5,19 +5,23 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessCheckboxGroup_1;
-import { customElement, DisabledCascadeController, HelixBeforeChangeEvent, HelixFormElement, hostAria, MixinField, } from '@fusion.dev/helix-core';
-import { html } from 'lit';
+import { commaList, customElement, DisabledCascadeController, HelixBeforeChangeEvent, HelixFormElement, hostAria, MixinField, } from '@fusion.dev/helix-core';
+import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { html } from 'lit/static-html.js';
 import { HelixHeadlessCheckbox } from '../../checkbox/root/checkbox-root.js';
+import '../../checkbox/index.js';
 let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadlessCheckboxGroup extends MixinField(HelixFormElement) {
     constructor() {
         super(...arguments);
-        this.declared = '';
+        this.selectAll = false;
+        this.selectAllLabel = 'Select all';
+        this.declared = [];
         this.pending = false;
         this.watched = new Set();
         this.member = {
             hostUpdated: () => {
-                if (this.isConnected && this.value !== this.judged) {
+                if (this.isConnected && (this.selectAll || this.value !== this.judged)) {
                     this.requestUpdate();
                 }
             },
@@ -38,13 +42,12 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
             const wanted = event.detail.checked;
             const next = this.boxes
                 .filter((box) => (box === changed ? wanted : box.checked))
-                .map((box) => box.value)
-                .join(',');
-            if (!this.dispatchEvent(new HelixBeforeChangeEvent({ value: next }))) {
+                .map((box) => box.value);
+            if (!this.dispatchEvent(new HelixBeforeChangeEvent({ value: next.join(',') }))) {
                 event.preventDefault();
                 return;
             }
-            this.value = next;
+            this.values = next;
             this.announceInput();
             this.announceChange();
         };
@@ -53,22 +56,40 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
                 event.stopImmediatePropagation();
             }
         };
+        this.handleSelectAll = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            const enabled = this.boxes.filter((box) => !box.isDisabled);
+            const every = enabled.length > 0 && enabled.every((box) => box.checked);
+            const next = this.boxes
+                .filter((box) => (enabled.includes(box) ? !every : box.checked))
+                .map((box) => box.value);
+            if (!this.dispatchEvent(new HelixBeforeChangeEvent({ value: next.join(',') }))) {
+                return;
+            }
+            this.values = next;
+            this.announceInput();
+            this.announceChange();
+        };
     }
     get value() {
+        return this.values.join(',');
+    }
+    set value(next) {
+        this.values = commaList(next);
+    }
+    get values() {
         if (this.pending || !this.hasUpdated || !this.childrenKnown) {
-            return this.declared;
+            return [...this.declared];
         }
         const boxes = this.boxes;
         return boxes.length === 0
-            ? this.declared
-            : boxes
-                .filter((box) => box.checked)
-                .map((box) => box.value)
-                .join(',');
+            ? [...this.declared]
+            : boxes.filter((box) => box.checked).map((box) => box.value);
     }
-    set value(next) {
-        const previous = this.declared;
-        this.declared = next;
+    set values(next) {
+        const previous = this.value;
+        this.declared = [...next];
         this.pending = true;
         this.requestUpdate('value', previous);
     }
@@ -105,10 +126,7 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
             return;
         }
         this.pending = false;
-        const wanted = new Set(this.declared
-            .split(',')
-            .map((entry) => entry.trim())
-            .filter(Boolean));
+        const wanted = new Set(this.declared);
         for (const box of boxes) {
             box.checked = wanted.has(box.value);
         }
@@ -159,8 +177,30 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
         this.validate();
         this.linkHost();
     }
+    renderSelectAll() {
+        if (!this.selectAll) {
+            return nothing;
+        }
+        const boxes = this.childrenKnown ? this.boxes : [];
+        const ticked = boxes.filter((box) => box.checked).length;
+        const every = boxes.length > 0 && ticked === boxes.length;
+        const box = this.tag('checkbox');
+        return html `<${box}
+      part="select-all"
+      exportparts="box: select-all-box, control: select-all-control,
+        feedback: select-all-feedback, field: select-all-field, hint: select-all-hint,
+        label: select-all-label, mark: select-all-mark, mark-checked: select-all-mark-checked,
+        mark-dash: select-all-mark-dash, mark-indeterminate: select-all-mark-indeterminate"
+      .checked=${every}
+      .indeterminate=${ticked > 0 && !every}
+      ?disabled=${this.isDisabled}
+      label=${this.selectAllLabel}
+      @helix-before-toggle=${this.handleSelectAll}
+      @input=${(event) => event.stopPropagation()}
+    ></${box}>`;
+    }
     render() {
-        return html `${this.renderGroupLabel()}
+        return html `${this.renderGroupLabel()}${this.renderSelectAll()}
       <div part="items">
         ${''}
         <slot @slotchange=${() => this.requestUpdate()}></slot>
@@ -168,9 +208,18 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
       ${this.renderHint()}${this.renderFeedback()}`;
     }
 };
+__decorate([
+    property({ attribute: 'select-all', type: Boolean })
+], HelixHeadlessCheckboxGroup.prototype, "selectAll", void 0);
+__decorate([
+    property({ attribute: 'select-all-label' })
+], HelixHeadlessCheckboxGroup.prototype, "selectAllLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessCheckboxGroup.prototype, "value", null);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessCheckboxGroup.prototype, "values", null);
 HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = __decorate([
     customElement('helix-headless-checkbox-group')
 ], HelixHeadlessCheckboxGroup);

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

@@ -0,0 +1,13 @@
+/**
+ * How many lines a block of code shows.
+ *
+ * A final line break ends the last line rather than starting another, which is
+ * how an editor counts a file and how the block draws one: `a\nb\n` is two
+ * lines. A Windows line break is one break. Empty code has no lines.
+ */
+export declare const lineCount: (code: string) => number;
+/**
+ * The numbers for a gutter of `count` lines, one to a line, as the text a
+ * `<pre>` draws beside the code. The stylesheet aligns them to the end.
+ */
+export declare const gutterNumbers: (count: number) => string;

package/dist/code-block/lines.js

@@ -0,0 +1,2 @@
+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');

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

@@ -14,6 +14,12 @@ 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
+ * function that turns the code into highlighted markup, such as one wrapping
+ * Shiki or Prism, and the block draws what it returns; the code stays in the
+ * slot, so the copy button and the page's own text are the code as written.
+ *
  * Set `diff` to show a change. Put a unified diff, the output of `git diff` or
  * `diff -u`, in the same slot, and the block draws the lines it added and
  * removed. The block never computes a diff itself. Line numbers come from the
@@ -42,6 +48,7 @@ import '../../copy-button/index.js';
  * @csspart context - In a diff, a line both versions share.
  * @csspart copy - The copy button. It sits in the header when there is one, and beside the code otherwise.
  * @csspart copy-button - The inner button.
+ * @csspart copy-live - The copy button's live region, which speaks while the button is pending.
  * @csspart copy-mark - The clipboard icon, and the check mark that replaces it after a copy.
  * @csspart copy-text - The words on that button, trimmed to their capitals and baseline.
  * @csspart copy-tooltip - The copy button's tooltip.
@@ -57,6 +64,7 @@ import '../../copy-button/index.js';
  * @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 where there is no header.
+ * @csspart gutter - The line numbers beside the code, shown when `line-numbers` is set.
  * @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 file name or language, where one is given.
@@ -75,6 +83,10 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
     copiedLabel: string;
     /**
      * The copy button's name and tooltip text before a copy.
+     *
+     * Where the block has a name, the button says it too, such as "Copy code,
+     * app.ts", so each copy button on a page with several blocks is told apart.
+     * In a diff, that is each file's own name.
      */
     copyLabel: string;
     /**
@@ -84,6 +96,19 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * `false` reflects as no attribute at all.
      */
     diff: boolean;
+    /**
+     * Turns the code into highlighted markup, which the block draws in place of
+     * the plain text.
+     *
+     * Called with the code as written and returning HTML, such as the output of
+     * Shiki's `codeToHtml` or Prism's `highlight`. **The markup is drawn as
+     * given**, so it has to escape the code it was handed, which those
+     * highlighters do. Bind the language in the function you pass. The code
+     * stays in the slot, so the copy button copies it as written and a reader
+     * without the script still has it. Not called on a server, which has no code
+     * to read, nor for a diff.
+     */
+    highlight?: (code: string) => string;
     /**
      * The block's name, usually a file name or a language.
      *
@@ -91,6 +116,15 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * carries no name of its own.
      */
     label: string;
+    /**
+     * Whether the lines are numbered in a gutter beside the code.
+     *
+     * The numbers are hidden from the accessibility tree and are not part of a
+     * copy, which takes the code alone. Reflected, because the stylesheet lays
+     * the gutter out beside the code. A diff numbers its lines from its hunks
+     * whether or not this is set.
+     */
+    lineNumbers: boolean;
     /**
      * Whether to leave the copy button off.
      *
@@ -177,8 +211,11 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * interpolated rather than written, so `tier` resolves it: this renders the
      * base button, and a styled subclass that sets `tier` renders the styled one
      * from the same template.
+     *
+     * @param value The text the button copies.
+     * @param name The name of what it copies, which its label carries.
      */
-    protected renderCopyButton(value?: string): TemplateResult;
+    protected renderCopyButton(value?: string, name?: string): TemplateResult;
     /** A number padded to the widest in its file, so the columns line up as text. */
     private renderNumber;
     private renderLine;