@fusion.dev/helix-headless 0.152.0 → 0.154.0

package/dist/area-chart/root/area-chart-root.d.ts

@@ -17,7 +17,7 @@ export interface AreaStack {
     /** Each column's own reading, not yet summed. */
     values: number[][];
 }
-declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
+declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartStatusInterface);
 /**
  * @summary A chart that shows how a total is made up over time, as bands stacked on one another.
  *
@@ -73,24 +73,39 @@ declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args:
  * tap or key, and `helix-reading-press` says a reading was clicked, tapped, or
  * pressed with Enter or Space, for a page that opens what a reading stands for.
  *
+ * **`data` takes the readings as data** where the page has no table to point
+ * `for` at, in a table's shape: the column headings, then one row per reading
+ * with its label first. A table is still the better source where the page can
+ * show one, since it reads before any script runs.
+ *
+ * **A chart with nothing to draw says so.** A table with no readings shows
+ * `empty-text`, "No readings", in the plot, and `loading` shows `loading-text`
+ * there until readings arrive. The `empty` and `loading` slots take markup in
+ * their place, such as a link to add the first reading.
+ *
  * @since 0.1.0
  * @status stable
  * @category charts
  * @aliases Stacked Area Chart, Composition Chart, Banded Chart
  * @documentation https://fusion.dev/helix/components/area-chart
  *
+ * @slot empty - Content shown in place of the drawing when the table has no readings, such as a link to add the first. Falls back to `empty-text`.
+ * @slot loading - Content shown in place of the drawing while `loading` is set and there are no readings yet. Falls back to `loading-text`.
+ *
  * @event {HelixReadingChangeEvent} helix-reading-change - The reading shown moved, or was put away: `index` is the row, or `-1` for none, with its `label`, the `series` the keys rest on, and the `pointerType` that moved it.
  * @event {HelixReadingPressEvent} helix-reading-press - A reading was clicked, tapped, or pressed with Enter or Space, with the same detail as `helix-reading-change`.
  *
  * @csspart area - One part's band.
  * @csspart axis - The numbers of the scale beside the plot, under `value-axis`.
  * @csspart baseline - The rule at zero, which is the floor of the drawing.
+ * @csspart empty - The words in place of the drawing when the table has no readings: the `empty` slot, falling back to `empty-text`. Not drawn while the table cannot be read yet, on the server and during hydration.
  * @csspart gridline - One rule across the plot, under `gridlines`.
  * @csspart guide - A rule down the reading a pointer is resting on.
  * @csspart label - One reading's name.
  * @csspart labels - The row of reading names.
  * @csspart line - The top edge of one part's band.
  * @csspart live - The readout: a polite live region that says the reading the keys moved to. Hide it visually.
+ * @csspart loading - The words in place of the drawing while `loading` is set and there are no readings: the `loading` slot, falling back to `loading-text`.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart plot - The drawing, which takes focus to be read by key.
  * @csspart summary - The total and each part's share at the latest reading, written as a sentence for screen readers.

package/dist/area-chart/root/area-chart-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { CHART_PLOT, customElement, drawTooltip, drawValueAxis, formatNumbers, formatWords, HelixElement, HelixReadingChangeEvent, HelixReadingPressEvent, linear, linePath, MixinChartSource, PLOT_HEIGHT, PLOT_WIDTH, reportRuntime, seriesIndex, ticks, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { CHART_PLOT, customElement, drawTooltip, drawValueAxis, formatNumbers, formatWords, HelixElement, HelixReadingChangeEvent, HelixReadingPressEvent, linear, linePath, MixinChartSource, MixinChartStatus, PLOT_HEIGHT, PLOT_WIDTH, reportRuntime, seriesIndex, ticks, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import '../../tooltip/index.js';
@@ -20,7 +20,7 @@ const percentIn = (locale) => {
     }
     return found;
 };
-let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSource(HelixElement) {
+let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartStatus(MixinChartSource(HelixElement)) {
     constructor() {
         super(...arguments);
         this.overlap = false;
@@ -96,7 +96,7 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
         const rows = this.sourceRows;
         const stack = this.stack;
         if (rows.length === 0 || stack.columns.length === 0) {
-            return html `<div id=${CHART_PLOT} part="plot"></div>`;
+            return html `<div id=${CHART_PLOT} part="plot">${this.renderStatus()}</div>`;
         }
         const top = this.overlap
             ? Math.max(0, ...stack.layers.flat())

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

@@ -35,6 +35,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * button "Inbox 8 unread", and stays current as the count changes. The styled
  * tier's `placement="inline"` draws the mark in the line for that case.
  *
+ * **An icon goes inside the mark** through the `icon` slot, before the count,
+ * as Web Awesome's badge takes one at its start. With no `value` the icon is
+ * the whole mark, such as a check on an avatar, drawn where the dot would be.
+ * The icon is hidden from screen readers: the count and `label` are what the
+ * mark says.
+ *
  * @since 0.1.0
  * @status stable
  * @category markers
@@ -42,12 +48,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/badge
  *
  * @slot - The element being decorated.
+ * @slot icon - An icon inside the mark, before the count, or the whole mark when there is no value. Hidden from screen readers.
  *
- * @csspart indicator - The count, or the dot when there is no value.
+ * @csspart icon - The slot the icon arrives through, inside the indicator. A slot draws no box, so it passes inherited properties, such as color, to the icon.
+ * @csspart indicator - The count, or the dot when there is no value. Carries `data-dot` when there is no value, `data-single` when the count is one character, and `data-blank` when the value is zero.
  *
  * @cssstate blank - The value is zero, so there is no mark.
  * @cssstate capped - The count is past `max`, so the mark shows `{max}+`.
- * @cssstate dot - There is no value, so the mark is a dot.
+ * @cssstate dot - There is no value and no icon, so the mark is a dot.
+ * @cssstate has-icon - Something is slotted into `icon`, so it is drawn inside the mark.
  */
 export declare class HelixHeadlessBadge extends HelixElement {
     /**
@@ -98,6 +107,10 @@ export declare class HelixHeadlessBadge extends HelixElement {
      * is showing a count must not lose the count for being handed one.
      */
     value: number | string;
+    /** Whether something is slotted into `icon`, read from the children. */
+    private hasIcon;
+    /** Reads whether an icon is slotted, from the children where they can be known. */
+    private readonly readIcon;
     /** The value as text, whatever it was set to. */
     private get given();
     /** Whether the value counts nothing, in which case there is no mark. */

package/dist/badge/root/badge-root.js

@@ -6,7 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { customElement, focusTarget, HelixElement, wordsLocale } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 import { badgeBlank, badgeCapped, badgeText, badgeWords } from '../count.js';
 let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     constructor() {
@@ -14,6 +14,10 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
         this.label = '';
         this.locale = '';
         this.value = '';
+        this.hasIcon = false;
+        this.readIcon = () => {
+            this.hasIcon = this.knownChildren.some((child) => child.slot === 'icon');
+        };
         this.handleSlotchange = () => {
             this.describe();
         };
@@ -81,9 +85,13 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
+        if (!this.hasUpdated) {
+            this.readIcon();
+        }
         this.toggleState('capped', this.capped);
-        this.toggleState('dot', this.given.trim() === '');
+        this.toggleState('dot', this.given.trim() === '' && !this.hasIcon);
         this.toggleState('blank', this.blank);
+        this.toggleState('has-icon', this.hasIcon);
     }
     updated(changed) {
         super.updated(changed);
@@ -97,10 +105,16 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
       <span
         part="indicator"
         data-blank=${blank ? '' : nothing}
+        data-dot=${this.given.trim() === '' ? '' : nothing}
         data-single=${text.length <= 1 ? '' : nothing}
         role="status"
         aria-label=${announced ? this.words : nothing}
-        >${blank ? html `<span aria-hidden="true">${text}</span>` : text}</span
+        ><slot
+          aria-hidden="true"
+          name="icon"
+          part="icon"
+          @slotchange=${this.readIcon}
+        ></slot>${blank ? html `<span aria-hidden="true">${text}</span>` : text}</span
       >`;
     }
 };
@@ -119,6 +133,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessBadge.prototype, "value", void 0);
+__decorate([
+    state()
+], HelixHeadlessBadge.prototype, "hasIcon", void 0);
 HelixHeadlessBadge = __decorate([
     customElement('helix-headless-badge')
 ], HelixHeadlessBadge);

package/dist/bar-chart/root/bar-chart-root.d.ts

@@ -1,7 +1,7 @@
 import { HelixElement, type Series } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
-declare const HelixHeadlessBarChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
+declare const HelixHeadlessBarChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartStatusInterface);
 /**
  * @summary A chart that draws a table's categories as columns.
  *
@@ -35,12 +35,25 @@ declare const HelixHeadlessBarChart_base: typeof HelixElement & (new (...args: a
  * tap or key, and `helix-reading-press` says a reading was clicked, tapped, or
  * pressed with Enter or Space, for a page that opens what a reading stands for.
  *
+ * **`data` takes the readings as data** where the page has no table to point
+ * `for` at, in a table's shape: the column headings, then one row per reading
+ * with its label first. A table is still the better source where the page can
+ * show one, since it reads before any script runs.
+ *
+ * **A chart with nothing to draw says so.** A table with no readings shows
+ * `empty-text`, "No readings", in the plot, and `loading` shows `loading-text`
+ * there until readings arrive. The `empty` and `loading` slots take markup in
+ * their place, such as a link to add the first reading.
+ *
  * @since 0.1.0
  * @status stable
  * @category charts
  * @aliases Column Chart, Categorical Chart
  * @documentation https://fusion.dev/helix/components/bar-chart
  *
+ * @slot empty - Content shown in place of the drawing when the table has no readings, such as a link to add the first. Falls back to `empty-text`.
+ * @slot loading - Content shown in place of the drawing while `loading` is set and there are no readings yet. Falls back to `loading-text`.
+ *
  * @event {HelixReadingChangeEvent} helix-reading-change - The reading shown moved, or was put away: `index` is the row, or `-1` for none, with its `label`, the `series` the keys rest on, and the `pointerType` that moved it.
  * @event {HelixReadingPressEvent} helix-reading-press - A reading was clicked, tapped, or pressed with Enter or Space, with the same detail as `helix-reading-change`.
  *
@@ -50,6 +63,7 @@ declare const HelixHeadlessBarChart_base: typeof HelixElement & (new (...args: a
  * @csspart bar-wash-end - The far stop of a bar's gradient, where one is used.
  * @csspart bar-wash-start - The stop of a bar's gradient at its base.
  * @csspart baseline - The line the columns stand on.
+ * @csspart empty - The words in place of the drawing when the table has no readings: the `empty` slot, falling back to `empty-text`. Not drawn while the table cannot be read yet, on the server and during hydration.
  * @csspart gridline - One gridline across the plot, drawn when `gridlines` is set.
  * @csspart group - One category's columns, together.
  * @csspart group-active - The group the tooltip describes. Set together with `group`.
@@ -57,6 +71,7 @@ declare const HelixHeadlessBarChart_base: typeof HelixElement & (new (...args: a
  * @csspart labels - The row of category names.
  * @csspart line - A series drawn as a line, named in `lines`.
  * @csspart live - The readout: a polite live region that says the reading the keys moved to. Hide it visually.
+ * @csspart loading - The words in place of the drawing while `loading` is set and there are no readings: the `loading` slot, falling back to `loading-text`.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart plot - The drawing, which takes focus to be read by key.
  * @csspart summary - The chart's name and each series' highest reading, written as a sentence for screen readers. Hide it visually.

package/dist/bar-chart/root/bar-chart-root.js

@@ -4,12 +4,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { byRow, CHART_PLOT, customElement, drawTooltip, extent, formatNumbers, formatWords, HelixElement, HelixReadingChangeEvent, HelixReadingPressEvent, linear, linePath, MixinChartSource, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, seriesKey, seriesNames, ticks, unbroken, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { byRow, CHART_PLOT, customElement, drawTooltip, extent, formatNumbers, formatWords, HelixElement, HelixReadingChangeEvent, HelixReadingPressEvent, linear, linePath, MixinChartSource, MixinChartStatus, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, seriesKey, seriesNames, ticks, unbroken, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import { stackEnds, stackedReadings, stackSpans } from '../stack.js';
 import '../../tooltip/index.js';
-let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource(HelixElement) {
+let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartStatus(MixinChartSource(HelixElement)) {
     constructor() {
         super(...arguments);
         this.highestLabel = 'Highest';
@@ -44,7 +44,7 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
         const series = this.series;
         const categories = series.length === 0 ? [] : this.sourceRows.map((row) => row.label);
         if (categories.length === 0) {
-            return html `<div id=${CHART_PLOT} part="plot"></div>`;
+            return html `<div id=${CHART_PLOT} part="plot">${this.renderStatus()}</div>`;
         }
         const scaled = this.scaled;
         const own = (one) => scaled.has(seriesKey(one.name));

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

@@ -13,13 +13,17 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * through with `::part`.
  *
  * Name the card with `label`, as a Stat Group is named, or with `aria-label`
- * or `aria-labelledby`. These are the only names that work with server
- * rendering, because reading a title from the light DOM needs a DOM, and the
- * server has none. `label` is set through `ElementInternals`, so it writes no
- * attribute onto the card. **A named card is a group**, so a
+ * or `aria-labelledby`. `label` is set through `ElementInternals`, so it
+ * writes no attribute onto the card. **A named card is a group**, so a
  * reader entering it hears its name; an unnamed one has no role, since a group
  * with no name only adds "group" to what a reader says.
  *
+ * **With none of those, a heading in `header` names the card**, such as the
+ * `<h2>` of its title, by reference, so the name follows the heading's words.
+ * Reading a heading needs a DOM, so a served card is named by it once the
+ * script runs; `label`, `aria-label` and `aria-labelledby` are the names a
+ * server writes.
+ *
  * Each region's slot is a part of the same name, `body` for the main content,
  * as Web Awesome's card names its regions. A slot draws no box, so a part
  * passes inherited properties to what is slotted, and a page wanting a box
@@ -29,7 +33,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * header's and the footer's line, as Web Awesome's card does. While one holds
  * something, its line is a `header-row` or `footer-row` part; otherwise there
  * is no wrapper and every region is a bare slot. A server cannot see slotted
- * content, so served actions sit on their own line until the script runs.
+ * content, so a served card has no row; the styled tier sets served actions at
+ * the end of their line from the stylesheet alone, so they do not move when
+ * the script runs.
  *
  * **The card says which regions it holds**, as `:state(has-media)`,
  * `:state(has-header)` and `:state(has-footer)`, so a sheet can draw a card
@@ -87,20 +93,34 @@ export declare class HelixHeadlessCard extends HelixElement {
      */
     mediaPlacement?: 'end';
     /**
-     * @internal The host's `aria-labelledby`, observed so the card becomes a
-     * group once it is named. Not reflected: the attribute is the consumer's.
+     * Hears a name written on the card, which no property mirrors.
+     *
+     * Lit observes the attributes of its own properties only, and `ariaLabel`
+     * and `ariaLabelledByElements` belong to the platform. Observed here rather
+     * than through a property, so the manifest lists no attribute of the card's
+     * own for them.
      */
-    protected labelledBy: string | null;
+    static get observedAttributes(): string[];
     /**
-     * @internal The host's `aria-label`, observed for the same reason as
-     * `labelledBy`. Not reflected: the attribute is the consumer's.
+     * Called by the browser when an observed attribute changes. A name written
+     * or taken off asks for an update, because it decides whether the card is a
+     * group and whether its heading names it.
      */
-    protected namedBy: string | null;
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
     /** Whether `footer-actions` holds something, read from the slot. */
     private footerActions;
     /** Whether `header-actions` holds something, read from the slot. */
     private headerActions;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Says what the card is and what names it. On the host, since the host is
+     * the box, and from `willUpdate`, which the server calls too.
+     *
+     * **A heading in `header` is the name only where nothing else is**, and it
+     * names the card by reference, so a renamed heading renames the card. An
+     * engine without element references hears its words.
+     */
+    private writeName;
     protected updated(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     private readonly readRegions;

package/dist/card/root/card-root.js

@@ -4,15 +4,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, hostAria, slotFilled } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, headingIn, hostAria, slotFilled, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
 let HelixHeadlessCard = class HelixHeadlessCard extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = '';
-        this.labelledBy = null;
-        this.namedBy = null;
         this.footerActions = false;
         this.headerActions = false;
         this.readRegions = () => {
@@ -22,12 +20,34 @@ let HelixHeadlessCard = class HelixHeadlessCard extends HelixElement {
             this.toggleState('has-media', filled('media'));
             this.toggleState('has-header', this.headerActions || filled('header'));
             this.toggleState('has-footer', this.footerActions || filled('footer'));
+            this.writeName();
         };
     }
+    static get observedAttributes() {
+        return [...super.observedAttributes, 'aria-label', 'aria-labelledby'];
+    }
+    attributeChangedCallback(name, old, value) {
+        super.attributeChangedCallback(name, old, value);
+        if (name === 'aria-label' || name === 'aria-labelledby') {
+            this.requestUpdate();
+        }
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
-        const named = Boolean(this.label.trim() || this.namedBy?.trim() || this.labelledBy?.trim());
-        hostAria(this.internals, { label: this.label, role: named ? 'group' : '' });
+        this.writeName();
+    }
+    writeName() {
+        const attribute = (name) => Boolean(this.getAttribute?.(name)?.trim());
+        const named = this.label.trim() !== '' || attribute('aria-label') || attribute('aria-labelledby');
+        const heading = named
+            ? null
+            : headingIn(this.knownChildren.filter((child) => child.slot === 'header'));
+        const references = 'ariaLabelledByElements' in this.internals;
+        hostAria(this.internals, {
+            label: heading && !references ? (heading.textContent ?? '').trim() : this.label,
+            labelledBy: heading ? [heading] : [],
+            role: named || heading ? 'group' : '',
+        });
     }
     updated(changed) {
         super.updated(changed);
@@ -64,12 +84,6 @@ __decorate([
 __decorate([
     property({ attribute: 'media-placement', reflect: true })
 ], HelixHeadlessCard.prototype, "mediaPlacement", void 0);
-__decorate([
-    property({ attribute: 'aria-labelledby' })
-], HelixHeadlessCard.prototype, "labelledBy", void 0);
-__decorate([
-    property({ attribute: 'aria-label' })
-], HelixHeadlessCard.prototype, "namedBy", void 0);
 __decorate([
     state()
 ], HelixHeadlessCard.prototype, "footerActions", void 0);

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

@@ -8,6 +8,13 @@ import { type TemplateResult } from 'lit';
  * tools and document search. A styled span carries no such meaning, and a
  * screen reader announces nothing about it.
  *
+ * **Set `translate="no"` on the element to keep a page translator off the
+ * code.** A translator that rewrites prose would also rewrite an identifier.
+ * The slotted text takes its translation mode from the element, its parent in
+ * the page, and the element writes nothing onto itself, so the attribute is
+ * yours to set. The `<code>` inside carries `translate="no"` for anything the
+ * element draws itself.
+ *
  * `Code` is inline only and never scrolls. For a block of code with its own
  * box, its own overflow, and copying, use `CodeBlock`, which is a separate
  * family.

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

@@ -8,7 +8,7 @@ import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 let HelixHeadlessCode = class HelixHeadlessCode extends HelixElement {
     render() {
-        return html `<code part="code"><slot></slot></code>`;
+        return html `<code part="code" translate="no"><slot></slot></code>`;
     }
 };
 HelixHeadlessCode = __decorate([

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

@@ -38,6 +38,18 @@ import '../../copy-button/index.js';
  * and its copy button copies the new version of the file. `variant="split"`
  * shows the old version beside the new, each removal opposite its replacement.
  *
+ * **A block that scrolls is a tab stop.** While its lines run past its width or
+ * its cap, the scroller is a region named for the block, such as "Code,
+ * app.ts", that Tab reaches, so a keyboard scrolls it with the arrow keys in
+ * every browser. Chromium and Firefox make a scrolling box focusable on their
+ * own, and Safari does not. A block that fits is no stop at all.
+ *
+ * **The code the block draws is marked untranslated**, `translate="no"` on
+ * its `<pre>`, so a page translator leaves highlighted lines and a diff as
+ * written. Code in the slot takes its translation mode from the element, which
+ * writes nothing onto itself, so set `translate="no"` on the element to keep a
+ * translator off plain code too.
+ *
  * On the server, the slot renders as ordinary code, so a diff first appears as
  * the patch text in a `<pre>`. The client makes the same first render, which
  * keeps hydration clean, and draws the diff once it can read the content. Diff
@@ -95,6 +107,18 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * `registerWords('de', { 'helix-code-block': { copyLabel: 'Code kopieren' } })`.
      */
     static words: string;
+    /**
+     * The name of a block that scrolls, which is a tab stop while it does.
+     *
+     * Where the block has a name, the scroller says it too, such as "Code,
+     * app.ts", as `code-name-label` puts it.
+     */
+    codeLabel: string;
+    /**
+     * The name of a block that scrolls, where the block has a name. `{code}` is
+     * `code-label` and `{name}` the block's name.
+     */
+    codeNameLabel: string;
     /**
      * The expand button's words while the block shows every line.
      */
@@ -249,7 +273,7 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
     private capped;
     /** Whether the expand button has shown every line. */
     private expanded;
-    /** Watches the block's size, while it is expandable. */
+    /** Watches the block's size. */
     private sizes;
     /**
      * Reads whether the cap hides lines: the scroller is taller inside than it
@@ -258,6 +282,18 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * everything.
      */
     private readonly measure;
+    /**
+     * Makes each box that scrolls a tab stop and a region named for its block,
+     * and takes both away from a box that fits.
+     *
+     * **A reader on a keyboard scrolls the code from the box itself.** Chromium
+     * and Firefox make a scrolling box focusable on their own, and Safari does
+     * not, so there the arrow keys could not reach the end of a long line. A
+     * box counts while its sheet lets it scroll and its content is wider or
+     * taller than it is drawn: an unstyled `<pre>` overflows without scrolling,
+     * and a stop on it would scroll nothing.
+     */
+    private markScrollers;
     protected updated(changed: PropertyValues): void;
     connectedCallback(): void;
     disconnectedCallback(): void;

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

@@ -16,6 +16,8 @@ import { pairLines, parsePatch } from '../patch.js';
 let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
     constructor() {
         super(...arguments);
+        this.codeLabel = 'Code';
+        this.codeNameLabel = '{code}, {name}';
         this.collapseLabel = 'Show fewer lines';
         this.copiedLabel = 'Copied';
         this.copyLabel = 'Copy code';
@@ -31,6 +33,7 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         this.capped = false;
         this.expanded = false;
         this.measure = () => {
+            this.markScrollers();
             if (!this.expanded) {
                 this.capped =
                     this.expandable &&
@@ -60,9 +63,31 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
             .map((node) => node.textContent ?? '')
             .join('');
     }
+    markScrollers() {
+        for (const box of this.renderRoot.querySelectorAll('[part="block"], [part="code"], [part="old"], [part="new"]')) {
+            const style = getComputedStyle(box);
+            const scrolls = (value) => value === 'auto' || value === 'scroll';
+            const overflows = (scrolls(style.overflowX) && box.scrollWidth > box.clientWidth + 1) ||
+                (scrolls(style.overflowY) && box.scrollHeight > box.clientHeight + 1);
+            if (overflows) {
+                const name = box.closest('[part="file"]')?.querySelector('[part="label"]')?.textContent;
+                const named = name ?? (this.label || this.language);
+                box.tabIndex = 0;
+                box.setAttribute('role', 'region');
+                box.setAttribute('aria-label', named
+                    ? formatWords(this, 'codeNameLabel', { code: this.codeLabel, name: named })
+                    : this.codeLabel);
+            }
+            else {
+                box.removeAttribute('tabindex');
+                box.removeAttribute('role');
+                box.removeAttribute('aria-label');
+            }
+        }
+    }
     updated(changed) {
         super.updated(changed);
-        if (this.expandable && typeof ResizeObserver !== 'undefined') {
+        if (typeof ResizeObserver !== 'undefined') {
             this.sizes ??= new ResizeObserver(this.measure);
             this.sizes.observe(this);
         }
@@ -114,7 +139,7 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         const name = this.label || this.language;
         return html `${this.renderHeader(name)}
       <div part="frame">
-        <pre id="block" part="block">${gutter}${code}</pre>
+        <pre id="block" part="block" translate="no">${gutter}${code}</pre>
         ${name ? nothing : this.renderCopy()}
       </div>${this.renderExpand()}`;
     }
@@ -179,8 +204,8 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         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>
+      <pre part="old" translate="no"><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" translate="no"><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) {
@@ -197,13 +222,21 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         <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>`}
+                : html `<pre part="block" translate="no"><code part="code">${file.hunks.map((hunk) => html `${this.renderHunk(hunk)}${hunk.lines.map((line) => this.renderLine(line, width))}`)}</code></pre>`}
           ${name ? nothing : this.renderCopy(now)}
         </div>
       </div>`;
         })}<slot hidden @slotchange=${() => this.requestUpdate()}></slot>`;
     }
 };
+__decorate([
+    words,
+    property({ attribute: 'code-label' })
+], HelixHeadlessCodeBlock.prototype, "codeLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'code-name-label' })
+], HelixHeadlessCodeBlock.prototype, "codeNameLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'collapse-label' })

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

@@ -17,7 +17,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * Every region is a bare slot. There is no `empty-state-heading` or
  * `empty-state-actions` element: assign your own heading and actions to the
- * slots.
+ * slots. The icon, the message and the actions slots are parts of the same
+ * names, as Card's regions are. A slot draws no box, so a part passes
+ * inherited properties, such as color and font, to what is slotted, and a
+ * page wanting a box there gives it one with `display`, such as a row of
+ * actions with `display: flex`.
+ *
+ * **The view says which regions it holds**, as `:state(has-icon)` and
+ * `:state(has-actions)`, so a sheet can space a view with no icon or no
+ * actions differently. Read in the browser, so a served view carries neither
+ * until the script runs.
  *
  * **Or give the heading as words.** `heading` draws them in a `heading` part
  * that is a heading at `heading-level`, 3 where it is not set, so a page
@@ -42,8 +51,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot heading - The heading, which names what is missing. A heading element, such as an `<h3>`, keeps its level; any other element is read as a heading at `heading-level`. Replaces the one `heading` draws.
  * @slot icon - An icon above the heading.
  *
+ * @csspart actions - The slot the actions arrive through. A slot draws no box, so it passes inherited properties to the actions; `display: flex` lays them out in a row.
  * @csspart heading - The heading at `heading-level`: the one `heading` draws while nothing is slotted into `heading`, or the one around a slotted element that is no heading.
+ * @csspart icon - The slot the icon arrives through, drawing no box, as `actions` does.
  * @csspart live - A copy of the heading and the message, in a live region that screen readers announce when the view appears. Visually hidden in the styled tier.
+ * @csspart message - The slot the message arrives through, drawing no box, as `actions` does.
+ *
+ * @cssstate has-actions - Something is slotted into `actions`.
+ * @cssstate has-icon - Something is slotted into `icon`.
  */
 export declare class HelixHeadlessEmpty extends HelixElement {
     /**
@@ -75,6 +90,9 @@ export declare class HelixHeadlessEmpty extends HelixElement {
     private looseHeading;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** Says which regions hold something, one call apiece so each pairs with its `@cssstate`. */
+    private readonly readRegions;
     protected readonly arrival: ArrivalController;
     /**
      * The `heading` slot, with the heading `heading` draws as its fallback, so