@fusion.dev/helix-headless 0.146.0 → 0.148.0

package/dist/divider/root/divider-root.js

@@ -4,27 +4,48 @@ 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, markRegion } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, markRegion, toolbarAround, toolbarAxis, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
     constructor() {
         super(...arguments);
         this.announced = false;
+        this.decorative = false;
+    }
+    get drawn() {
+        const toolbar = this.orientation || this.hydrating ? null : toolbarAround(this);
+        if (toolbar) {
+            return toolbarAxis(toolbar) === 'vertical' ? 'horizontal' : 'vertical';
+        }
+        return this.orientation ?? 'horizontal';
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.requestUpdate();
     }
     markEmpty() {
         markRegion(this.renderRoot, 'content', ['']);
     }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.toggleState('vertical', this.drawn === 'vertical');
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
     updated(changed) {
         super.updated(changed);
         this.markEmpty();
     }
     render() {
+        const separator = this.announced || !this.decorative;
         return html `<div
       part="line"
-      role=${this.announced ? 'separator' : 'presentation'}
-      aria-labelledby=${this.announced ? 'content' : nothing}
-      aria-orientation=${this.announced ? (this.orientation ?? 'horizontal') : nothing}
+      role=${separator ? 'separator' : 'presentation'}
+      aria-labelledby=${separator ? 'content' : nothing}
+      aria-orientation=${separator ? this.drawn : nothing}
     ></div>
       <span id="content" part="content"><slot @slotchange=${() => this.markEmpty()}></slot></span>
       <div part="line" role="presentation"></div>`;
@@ -33,6 +54,9 @@ let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessDivider.prototype, "announced", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDivider.prototype, "decorative", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessDivider.prototype, "orientation", void 0);

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

@@ -8,6 +8,7 @@ import { CHART_PLOT, customElement, drawTooltip, HelixElement, MixinChartSource,
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import '../../tooltip/index.js';
+import { sliceLabelAt } from '../slice-label.js';
 const PERCENTS = new Map();
 const percentIn = (locale) => {
     let found = PERCENTS.get(locale);
@@ -124,16 +125,22 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
     }
     renderSliceLabels(shares) {
         const half = this.sweep === 'half';
-        const top = half ? CENTER - EDGE : 0;
-        const tall = half ? EDGE + this.thickness / 2 : PLOT_HEIGHT;
+        const ring = {
+            center: CENTER,
+            origin: this.origin,
+            radius: this.radius,
+            span: this.span,
+            tall: half ? EDGE + this.thickness / 2 : PLOT_HEIGHT,
+            top: half ? CENTER - EDGE : 0,
+            width: PLOT_WIDTH,
+        };
         const format = percentIn(this.locale);
         return html `${shares.map((share, index) => {
-            if (share.fraction < 0.05) {
+            const place = sliceLabelAt(share, ring);
+            if (!place) {
                 return nothing;
             }
-            const angle = (share.start + share.fraction / 2) * 2 * Math.PI * this.span + this.origin;
-            const x = ((CENTER + Math.cos(angle) * this.radius) / PLOT_WIDTH) * 100;
-            const y = ((CENTER + Math.sin(angle) * this.radius - top) / tall) * 100;
+            const { x, y } = place;
             return html `<span
         aria-hidden="true"
         data-series=${seriesIndex(index)}

package/dist/donut-chart/slice-label.d.ts

@@ -0,0 +1,35 @@
+/** A slice's place on the ring, as shares of the whole from 0 to 1. */
+export interface SliceShare {
+    /** How much of the ring the slice takes. */
+    fraction: number;
+    /** Where the slice starts, as the share of the ring before it. */
+    start: number;
+}
+/** The ring a slice label is placed on, in the drawing's own units. */
+export interface RingGeometry {
+    /** The center, on both axes. */
+    center: number;
+    /** Where the ring's turn starts, in radians: a quarter turn back is twelve o'clock. */
+    origin: number;
+    /** The radius of the band's middle, where a label sits. */
+    radius: number;
+    /** How much of a turn the ring takes: 1 for a ring, a half for an arc. */
+    span: number;
+    /** How tall the box the labels are placed in is. */
+    tall: number;
+    /** Where the top of that box is. */
+    top: number;
+    /** How wide the drawing is. */
+    width: number;
+}
+/** The smallest share that takes a label: a twentieth of the ring. */
+export declare const SMALLEST_LABELED = 0.05;
+/**
+ * Where a slice's label goes, as percentages of the box from the left and the
+ * top: the middle of its band at its mid-angle. Nothing for a slice under a
+ * twentieth, whose label would not fit on it.
+ */
+export declare const sliceLabelAt: (share: SliceShare, ring: RingGeometry) => {
+    x: number;
+    y: number;
+} | undefined;

package/dist/donut-chart/slice-label.js

@@ -0,0 +1,11 @@
+export const SMALLEST_LABELED = 0.05;
+export const sliceLabelAt = (share, ring) => {
+    if (share.fraction < SMALLEST_LABELED) {
+        return undefined;
+    }
+    const angle = (share.start + share.fraction / 2) * 2 * Math.PI * ring.span + ring.origin;
+    return {
+        x: ((ring.center + Math.cos(angle) * ring.radius) / ring.width) * 100,
+        y: ((ring.center + Math.sin(angle) * ring.radius - ring.top) / ring.tall) * 100,
+    };
+};

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, CommandController, HelixElement, OpenPhaseController, SwipeController } from '@fusion.dev/helix-core';
+import { AriaForwardController, CommandController, FocusScopeController, HelixElement, OpenPhaseController, SwipeController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
@@ -11,7 +11,8 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  *
  * The drawer is modal by default, which means four things:
  *
- * - focus is trapped inside
+ * - focus is trapped inside: `Tab` from the last control goes to the first,
+ *   and `Shift+Tab` from the first to the last, as in `Dialog`
  * - Escape and a press outside close it
  * - the page behind is covered
  * - the page behind does not scroll
@@ -233,6 +234,7 @@ export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
      * key is read here, and comes through the same request.
      */
     private readonly handleKeydown;
+    protected readonly scope: FocusScopeController;
     /** The panel, which is a real `<dialog>`. */
     private get panel();
     /**

package/dist/drawer/root/drawer-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 { AriaForwardController, CommandController, customElement, drawDismiss, drawDismissGlyph, edgeOffset, HelixElement, headingsIn, isRtl, lockScroll, MixinControllerOpen, OpenPhaseController, onUnlessFalse, parseSnapPoints, reflectElements, SwipeController, settleSwipe, snapTravel, swipeAxis, swipeEdge, towardEdge, unlockScroll, } from '@fusion.dev/helix-core';
+import { AriaForwardController, CommandController, customElement, drawDismiss, drawDismissGlyph, edgeOffset, FocusScopeController, HelixElement, headingsIn, isRtl, lockScroll, MixinControllerOpen, nearest, OpenPhaseController, onUnlessFalse, parseSnapPoints, reflectElements, SwipeController, settleSwipe, snapTravel, swipeAxis, swipeEdge, towardEdge, unlockScroll, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { beyondWindow } from '../reveal.js';
@@ -64,6 +64,16 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
             event.preventDefault();
             this.requestOpen(false);
         };
+        this.scope = new FocusScopeController(this, {
+            contain: () => this.open && this.modal,
+            contents: () => [
+                ...['header', '', 'footer'].flatMap((name) => this.renderRoot
+                    ?.querySelector(name ? `slot[name="${name}"]` : 'slot:not([name])')
+                    ?.assignedElements({ flatten: true }) ?? []),
+                ...[...(this.panel?.children ?? [])].filter((one) => one.localName === 'button'),
+            ],
+            surface: () => this.panel,
+        });
         this.handleCancel = (event) => {
             event.preventDefault();
             this.requestOpen(false);
@@ -153,8 +163,10 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
             return;
         }
         const points = parseSnapPoints(this.snapPoints);
-        const nearest = points.reduce((best, one) => Math.abs(one - point) < Math.abs(best - point) ? one : best);
-        this.restAt(nearest);
+        const at = nearest(points, point);
+        if (at !== undefined) {
+            this.restAt(at);
+        }
     }
     show() {
         this.requestOpen(true);

package/dist/drilldown/item/drilldown-item.d.ts

@@ -13,6 +13,8 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * - On the page that is showing, it renders its row.
  * - When its own page is showing, it renders only that page's rows. Its row
  *   belongs to the page above.
+ * - When a page further down its own is showing, it renders its page's slot
+ *   alone, so the rows below reach the page.
  * - Otherwise it renders nothing. The rows stay in the light DOM untouched, so
  *   there is no state to keep.
  *
@@ -23,6 +25,10 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * `aria-haspopup`, the same way `Menu` marks a row with a submenu. The server
  * render leaves both out, because the server cannot see the children.
  *
+ * The row is named by its label alone. Words in `description`, a line under
+ * the label, and in `end` describe it instead, through `aria-describedby`, as
+ * `Menu.Item` does: a reader hears "Theme", then "Dark".
+ *
  * @since 0.1.0
  * @status stable
  * @aliases Panel item, Drill row
@@ -30,7 +36,8 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  *
  * @slot - The row's label.
  * @slot chevron - Replaces the caret of a row that opens a page, such as with your own icon.
- * @slot end - Content after the label, usually an icon or a count.
+ * @slot description - A line under the label that describes the row. It describes the row to a screen reader and is not part of its name.
+ * @slot end - Content after the label, such as the setting a page holds or a count. It describes the row and is not part of its name.
  * @slot page - The rows of the page this row opens.
  * @slot start - Content before the label, usually an icon.
  *
@@ -71,6 +78,11 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      * event handler is why it is kept off the typings.
      */
     onPage: boolean;
+    /**
+     * @internal Whether the page showing is below this row's own, deeper than one
+     * level. Written by the stack.
+     */
+    onPath: boolean;
     /**
      * @internal Whether this row's own page is the one showing. Written by the
      * stack.
@@ -89,6 +101,10 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      * render would open with no caret on the row that leads to it.
      */
     private page;
+    /** Whether anything is slotted under the label, read the way `page` is. */
+    private description;
+    /** Whether anything is slotted after the label, read the way `page` is. */
+    private end;
     /**
      * Reads the children before each render, where they can be known.
      *
@@ -109,6 +125,10 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      * the same note.
      */
     private readonly readPage;
+    /** Re-reads whether the line under the label or the words after it are filled. */
+    private readonly readWords;
+    /** What describes the row: the line under its label and the words after it. */
+    private get describedBy();
     /** Moves focus onto the row itself. */
     focusItem(): void;
     /**

package/dist/drilldown/item/drilldown-item.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 { customElement, deepActiveElement, HelixElement, HelixSelectEvent, } from '@fusion.dev/helix-core';
+import { customElement, deepActiveElement, HelixElement, HelixSelectEvent, slotFilled, slotNamed, } from '@fusion.dev/helix-core';
 import { caretRight } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -16,24 +16,40 @@ let HelixHeadlessDrilldownItem = class HelixHeadlessDrilldownItem extends HelixE
         this.focusable = false;
         this.isDrilldownItem = true;
         this.onPage = true;
+        this.onPath = false;
         this.showingPage = false;
         this.value = '';
         this.page = false;
+        this.description = false;
+        this.end = false;
         this.readPage = () => {
             const slot = this.renderRoot.querySelector('slot[name="page"]');
             this.page = (slot?.assignedElements().length ?? 0) > 0;
         };
+        this.readWords = () => {
+            this.description = slotFilled(slotNamed(this.renderRoot, 'description'));
+            this.end = slotFilled(slotNamed(this.renderRoot, 'end'));
+        };
     }
     willUpdate(changed) {
         super.willUpdate(changed);
         if (this.childrenKnown) {
-            this.page = this.knownChildren.some((child) => child.slot === 'page');
+            const named = (name) => this.knownChildren.some((child) => child.slot === name);
+            this.page = named('page');
+            this.description = named('description');
+            this.end = named('end');
         }
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
     }
+    get describedBy() {
+        const ids = [this.description ? 'description' : '', this.end ? 'end' : '']
+            .filter((id) => id !== '')
+            .join(' ');
+        return ids === '' ? nothing : ids;
+    }
     focusItem() {
         this.partNamed('item')?.focus();
     }
@@ -58,7 +74,7 @@ let HelixHeadlessDrilldownItem = class HelixHeadlessDrilldownItem extends HelixE
     >`;
     }
     render() {
-        if (this.showingPage) {
+        if (this.showingPage || this.onPath) {
             return html `<slot name="page" @slotchange=${this.readPage}></slot>`;
         }
         if (!this.onPage) {
@@ -68,14 +84,23 @@ let HelixHeadlessDrilldownItem = class HelixHeadlessDrilldownItem extends HelixE
       part="item"
       type="button"
       role="menuitem"
+      aria-describedby=${this.describedBy}
       aria-disabled=${this.disabled ? 'true' : nothing}
       aria-haspopup=${this.page ? 'menu' : nothing}
       tabindex=${this.focusable ? '0' : '-1'}
+      ?data-described=${this.description}
       @click=${() => this.select()}
     >
       <slot name="start"></slot>
       <span part="label"><slot></slot></span>
-      <slot name="end"></slot>
+      <slot
+        id="description"
+        name="description"
+        aria-hidden="true"
+        ?data-empty=${!this.description}
+        @slotchange=${this.readWords}
+      ></slot>
+      <slot id="end" name="end" aria-hidden="true" @slotchange=${this.readWords}></slot>
       ${this.page ? this.renderMark() : nothing}
     </button>
     <div hidden><slot name="page" @slotchange=${this.readPage}></slot></div>`;
@@ -90,6 +115,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessDrilldownItem.prototype, "onPage", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessDrilldownItem.prototype, "onPath", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessDrilldownItem.prototype, "showingPage", void 0);
@@ -99,6 +127,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessDrilldownItem.prototype, "page", void 0);
+__decorate([
+    state()
+], HelixHeadlessDrilldownItem.prototype, "description", void 0);
+__decorate([
+    state()
+], HelixHeadlessDrilldownItem.prototype, "end", void 0);
 HelixHeadlessDrilldownItem = __decorate([
     customElement('helix-headless-drilldown-item')
 ], HelixHeadlessDrilldownItem);

package/dist/drilldown/root/drilldown-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 { AriaForwardController, customElement, DrilldownController, HelixElement, inlineStep, KeyboardNavigationController, keyClaimed, MixinCollection, slottedWords, typeaheadBy, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, DrilldownController, HelixElement, inlineStep, KeyboardNavigationController, keyClaimed, MixinCollection, slottedWords, typeaheadByWords, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -38,7 +38,7 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
             })),
             reserved: () => ['ArrowLeft', 'ArrowRight'],
             selects: () => false,
-            typeahead: typeaheadBy((item) => item.words),
+            typeahead: typeaheadByWords(),
         });
         this.handleFocusIn = (event) => {
             const item = this.drilldown.rows.find((row) => row.contains(event.target));
@@ -162,6 +162,7 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
     mark(item, page, onPage) {
         item.onPage = onPage;
         item.showingPage = item === page;
+        item.onPath = page !== null && item !== page && item.contains(page);
         for (const child of item.children) {
             if (child instanceof HelixHeadlessDrilldownItem && child.slot === 'page') {
                 this.mark(child, page, item === page);

package/dist/element-events.generated.js

@@ -5,6 +5,7 @@ registerElementEvents({
     'helix-headless-app-header': ['helix-scrolled'],
     'helix-headless-avatar': ['error', 'load'],
     'helix-headless-button': ['helix-press'],
+    'helix-headless-button-group': ['change', 'helix-before-change'],
     'helix-headless-callout': ['helix-dismiss'],
     'helix-headless-canvas': [
         'helix-before-move',
@@ -115,7 +116,7 @@ registerElementEvents({
         'helix-graph-signal',
         'helix-graph-zoom',
     ],
-    'helix-headless-heatmap': ['helix-resize'],
+    'helix-headless-heatmap': ['change', 'helix-before-change', 'helix-resize'],
     'helix-headless-icon': ['error', 'load'],
     'helix-headless-icon-button': ['helix-press'],
     'helix-headless-image': ['error', 'load'],
@@ -166,6 +167,7 @@ registerElementEvents({
     'helix-headless-megamenu': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-menu': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],
     'helix-headless-menu-item': ['helix-before-toggle', 'helix-select'],
+    'helix-headless-meter': ['helix-band'],
     'helix-headless-notification': ['helix-dismiss', 'helix-read'],
     'helix-headless-notification-group': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-notifications': ['helix-dismiss', 'helix-load-more', 'helix-read'],
@@ -186,6 +188,7 @@ registerElementEvents({
     'helix-headless-pagination-size': ['change', 'helix-before-change', 'input'],
     'helix-headless-pin-input': ['change', 'helix-before-change', 'helix-complete', 'input'],
     'helix-headless-popover': ['helix-before-close', 'helix-before-open', 'toggle'],
+    'helix-headless-progress': ['helix-complete'],
     'helix-headless-qr-code': ['error'],
     'helix-headless-radio': ['helix-select'],
     'helix-headless-radio-group': ['change', 'helix-before-change', 'helix-select', 'input'],
@@ -220,6 +223,7 @@ registerElementEvents({
         'helix-before-resize',
         'helix-collapse',
         'helix-resized',
+        'input',
     ],
     'helix-headless-step': ['helix-select'],
     'helix-headless-steps': ['helix-activate', 'helix-before-activate', 'helix-select'],

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

@@ -1,5 +1,5 @@
 import { ArrivalController, HelixElement } from '@fusion.dev/helix-core';
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A message that a region has nothing in it, and the next step to take.
  *
@@ -19,6 +19,18 @@ import { type TemplateResult } from 'lit';
  * `empty-state-actions` element: assign your own heading and actions to the
  * slots.
  *
+ * **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
+ * rendering from data or on a server gets a heading a reader finds in the
+ * outline without writing the element. A heading slotted in replaces it.
+ *
+ * **Whatever is slotted into `heading` is read as a heading.** An element that
+ * is no heading, such as a `<span>` or a `<p>`, is set inside the `heading`
+ * part at `heading-level`, so a screen reader still finds it in the outline.
+ * A heading element, or an element holding one, keeps its own level. A server
+ * cannot see the slotted element, so a served `<span>` becomes a heading once
+ * the script runs.
+ *
  * @since 0.1.0
  * @status stable
  * @category feedback
@@ -27,12 +39,27 @@ import { type TemplateResult } from 'lit';
  *
  * @slot - The message: why the region is empty, and what to do about it.
  * @slot actions - The action that would put something in the region.
- * @slot heading - The heading, which names what is missing. Slot a heading element, such as an `<h3>`, so a reader can find it in the page's outline.
+ * @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 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 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.
  */
 export declare class HelixHeadlessEmpty extends HelixElement {
+    /**
+     * The heading as words, such as "No results", drawn as a heading when
+     * nothing is slotted into `heading`.
+     *
+     * Absent draws none, and the `heading` slot is the only heading.
+     */
+    heading: string;
+    /**
+     * The level of the heading `heading` draws, from 1 to 6.
+     *
+     * Absent is 3, the level of a heading inside a page's section. Set it to fit
+     * the outline the empty view sits in. A slotted heading keeps its own.
+     */
+    headingLevel?: number;
     /**
      * Whether the state is announced when it appears.
      *
@@ -41,7 +68,24 @@ export declare class HelixHeadlessEmpty extends HelixElement {
      * has nothing to announce because nothing changed.
      */
     noAnnounce: boolean;
+    /**
+     * Whether the `heading` slot holds elements and none of them is or holds a
+     * heading, read from the children before each render.
+     */
+    private looseHeading;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected readonly arrival: ArrivalController;
+    /**
+     * The `heading` slot, with the heading `heading` draws as its fallback, so
+     * one slotted in replaces it; no fallback while `heading` holds no words.
+     *
+     * A method, so a tier above can draw its own, as the slot lets a page.
+     *
+     * @param hidden Whether the live copy holds the heading's words, which
+     * hides them from readers until it empties.
+     */
+    protected renderHeading(hidden: boolean): TemplateResult;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/empty/root/empty-root.js

@@ -4,30 +4,75 @@ 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 { ArrivalController, customElement, HelixElement, slottedWords, } from '@fusion.dev/helix-core';
+import { ArrivalController, customElement, HelixElement, headingIn, headingLevel, slottedWords, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessEmpty = class HelixHeadlessEmpty extends HelixElement {
     constructor() {
         super(...arguments);
+        this.heading = '';
         this.noAnnounce = false;
+        this.looseHeading = false;
         this.arrival = new ArrivalController(this, {
             arriving: () => !this.serverRendered && document.readyState === 'complete',
-            text: () => slottedWords(this, ['heading', '']),
+            text: () => [slottedWords(this, ['heading']) || this.heading.trim(), slottedWords(this, [''])]
+                .filter(Boolean)
+                .join(' '),
         });
     }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (this.childrenKnown) {
+            const slotted = this.knownChildren.filter((child) => child.slot === 'heading');
+            this.looseHeading = slotted.length > 0 && headingIn(slotted) === null;
+        }
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
+    renderHeading(hidden) {
+        const level = headingLevel(this.headingLevel);
+        const slot = html `<slot
+      aria-hidden=${hidden && !this.looseHeading ? 'true' : nothing}
+      name="heading"
+      @slotchange=${() => {
+            this.arrival.say();
+            this.requestUpdate();
+        }}
+      >${this.heading.trim()
+            ? html `<div aria-level=${level} part="heading" role="heading">
+              ${this.heading}
+            </div>`
+            : nothing}</slot
+    >`;
+        return this.looseHeading
+            ? html `<div
+          aria-hidden=${hidden ? 'true' : nothing}
+          aria-level=${level}
+          part="heading"
+          role="heading"
+        >${slot}</div>`
+            : slot;
+    }
     render() {
         const say = () => this.arrival.say();
-        const copied = this.arrival.said !== '' && !this.noAnnounce ? 'true' : nothing;
+        const held = this.arrival.said !== '' && !this.noAnnounce;
         return html `<slot name="icon"></slot>
-      <slot aria-hidden=${copied} name="heading" @slotchange=${say}></slot>
-      <slot aria-hidden=${copied} @slotchange=${say}></slot>
+      ${this.renderHeading(held)}
+      <slot aria-hidden=${held ? 'true' : nothing} @slotchange=${say}></slot>
       <slot name="actions"></slot>
       ${this.noAnnounce
             ? nothing
             : html `<span part="live" role="status">${this.arrival.said}</span>`}`;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessEmpty.prototype, "heading", void 0);
+__decorate([
+    property({ attribute: 'heading-level', type: Number })
+], HelixHeadlessEmpty.prototype, "headingLevel", void 0);
 __decorate([
     property({ attribute: 'no-announce', reflect: true, type: Boolean })
 ], HelixHeadlessEmpty.prototype, "noAnnounce", void 0);