@fusion.dev/helix-headless 0.147.0 → 0.148.0

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

@@ -148,8 +148,11 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
     /**
      * Opens the section find in page has matched in, before the match is shown.
      *
-     * The browser removes `hidden` itself. A refusal puts it back, so the trigger
-     * and the region still agree.
+     * A refusal puts `hidden` back, so the trigger and the region still agree.
+     * The browser removes the attribute after this event's listeners have
+     * returned, and after the microtasks they queued, so writing it here or in a
+     * microtask is undone at once. A mutation observer hears the removal itself
+     * and runs before the next paint or key press.
      */
     private readonly handleBeforeMatch;
     /** Whether the item was open at the last update, and `undefined` before one. */

package/dist/accordion/item/accordion-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 { closestInstance, customElement, HelixElement, headingLevel, MixinControllerOpen, onUnlessFalse, } from '@fusion.dev/helix-core';
+import { animationsFinished, closestInstance, customElement, HelixElement, headingLevel, MixinControllerOpen, onUnlessFalse, } from '@fusion.dev/helix-core';
 import { caretDown } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -23,8 +23,14 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
             if (this.open || this.requestOpen(true)) {
                 return;
             }
-            ;
-            event.currentTarget.setAttribute('hidden', 'until-found');
+            const content = event.currentTarget;
+            const observer = new MutationObserver(() => {
+                observer.disconnect();
+                if (!this.open && !this.closing && !content.hasAttribute('hidden')) {
+                    content.setAttribute('hidden', 'until-found');
+                }
+            });
+            observer.observe(content, { attributeFilter: ['hidden'] });
         };
         this.wasOpen = undefined;
         this.handleToggle = () => {
@@ -72,13 +78,11 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
         }
     }
     finishClosing() {
-        const running = this.partNamed('content')?.getAnimations?.({ subtree: true }) ?? [];
-        const done = () => {
+        void animationsFinished(this.partNamed('content')).then(() => {
             if (!this.open) {
                 this.closing = false;
             }
-        };
-        Promise.all(running.map((animation) => animation.finished)).then(done, done);
+        });
     }
     get accordion() {
         return closestInstance(this, HelixHeadlessAccordion);

package/dist/accordion/root/accordion-root.js

@@ -4,16 +4,14 @@ 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, KeyboardNavigationController, onUnlessFalse, whenHydrated, } from '@fusion.dev/helix-core';
+import { customElement, focusItemOf, HelixElement, KeyboardNavigationController, onUnlessFalse, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
-const navigable = (item) => ({
-    contains: (node) => node === item,
+const navigable = (item) => focusItemOf(item, {
     disabled: item.disabled,
-    focusItem: () => item.focusTrigger(),
-    select: () => { },
-    selected: false,
+    focus: () => item.focusTrigger(),
+    owns: (node) => node === item,
 });
 let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
     constructor() {

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

@@ -1,5 +1,5 @@
 import { ArrivalController, HelixElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
 /**
  * @summary A message for the whole page, shown above its header, that can be dismissed.
@@ -29,6 +29,23 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  * announcement beside it, move focus yourself, for example to the page's main
  * heading.
  *
+ * **The announcement is a landmark region**, named by `label`, "Announcement"
+ * unless you set it, so a screen reader lists it among the page's regions.
+ * `hotkey`, F6 unless you set it, moves focus to the announcement's first
+ * control, an action or the dismiss button, and pressed there moves focus
+ * back to where it was, as React Aria's toast region does. An announcement
+ * with no control leaves the key to the browser. When an announcement that
+ * the key moved focus into is removed with focus still inside, focus goes
+ * back to where it was before the key.
+ *
+ * **Set `queued` to show several announcements one at a time.** A queued
+ * announcement waits while a queued announcement before it in the same parent
+ * is still there, and shows when that one is removed: its message is then
+ * read out, and its `duration` starts. While it waits it renders nothing,
+ * is no region, and carries `:state(waiting)`. A server cannot see the
+ * announcements beside it, so a served page shows every one until the script
+ * runs.
+ *
  * Set `duration` to dismiss it after a time. The clock stops while the pointer
  * or focus is on the announcement, and continues from what was left, so a
  * reader partway through is not cut off. It stops while the page is hidden too,
@@ -57,6 +74,7 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  * @csspart live - A copy of the message in a live region, read by screen readers when the announcement appears after the page has loaded, and emptied seven seconds later. Visually hidden in the styled tier.
  *
  * @cssstate paused - The clock `duration` started is stopped, while the pointer or focus is on the announcement or the page is hidden.
+ * @cssstate waiting - The announcement is `queued` behind another, and renders nothing until that one is removed.
  */
 export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement_base {
     /**
@@ -67,6 +85,28 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
      * own. The clock stops while the pointer or focus is on the announcement.
      */
     duration?: number;
+    /**
+     * The key that moves focus to the announcement's first control, and back
+     * to where it was, written as keys joined by `+`, such as `F6` or `Alt+A`.
+     *
+     * F6 by default, the key React Aria's regions answer to. Empty turns it
+     * off. With several announcements, the first one in the page takes focus.
+     */
+    hotkey: string;
+    /**
+     * The name of the announcement's region, which screen readers list among
+     * the page's landmarks. Translate it with the rest of your interface.
+     *
+     * Empty leaves the announcement no region.
+     */
+    label: string;
+    /**
+     * Whether the announcement waits its turn behind the queued announcements
+     * before it in the same parent, showing when the last of them is removed.
+     *
+     * Off by default, so every announcement on a page shows at once.
+     */
+    queued: boolean;
     /**
      * The band's color.
      *
@@ -90,18 +130,29 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
      * axes, which is the test the registry answers to.
      */
     tone?: 'accent' | 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
+    /** Whether a queued announcement before this one is still there. */
+    private waiting;
+    /** Watches the parent for the announcements before this one leaving. */
+    private queue;
+    /** Whether a queued announcement comes before this one in its parent. */
+    private behind;
     protected readonly arrival: ArrivalController;
     /** The time `duration` gives it, held while a reader is on it. */
     private readonly countdown;
-    /** Whether the page being hidden is one of the reasons the clock is held. */
-    private heldHidden;
-    private readonly handleVisibility;
+    private readonly scope;
+    /** Where focus was when `hotkey` moved it in. */
+    private origin;
+    /** Whether focus is inside the announcement, kept as it moves. */
+    private focused;
+    private readonly handleHotkey;
+    protected willUpdate(changed: PropertyValues): void;
     private readonly handleHold;
     private readonly handleRelease;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    private watchQueue;
     /**
      * Says on the `actions` region whether anything is in it.
      *
@@ -126,7 +177,7 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
      * draws a tone mark. An announcement has no tone mark at all.
      */
     protected renderDismissIcon(): TemplateResult;
-    protected render(): TemplateResult;
+    protected render(): TemplateResult | typeof nothing;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/announcement/root/announcement-root.js

@@ -4,54 +4,109 @@ 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, CountdownController, customElement, HelixElement, MixinDismissible, markRegion, reportRuntime, slottedWords, } from '@fusion.dev/helix-core';
+var HelixHeadlessAnnouncement_1;
+import { ArrivalController, ariaChord, CountdownController, customElement, deepActiveElement, FocusScopeController, HelixElement, hostAria, MixinDismissible, markRegion, matchesChord, onApple, reportRuntime, slottedWords, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDismissible(HelixElement) {
+let HelixHeadlessAnnouncement = HelixHeadlessAnnouncement_1 = class HelixHeadlessAnnouncement extends MixinDismissible(HelixElement) {
     constructor() {
         super(...arguments);
+        this.hotkey = 'F6';
+        this.label = 'Announcement';
+        this.queued = false;
+        this.waiting = false;
         this.arrival = new ArrivalController(this, {
             arriving: () => !this.serverRendered && document.readyState === 'complete',
-            text: () => slottedWords(this, ['']),
+            text: () => (this.waiting ? '' : slottedWords(this, [''])),
         });
         this.countdown = new CountdownController(this, {
             done: () => {
                 this.dismiss();
             },
+            holdWhileHidden: true,
             paused: (paused) => {
                 this.toggleState('paused', paused);
             },
         });
-        this.heldHidden = false;
-        this.handleVisibility = () => {
-            if (document.hidden && !this.heldHidden) {
-                this.heldHidden = true;
-                this.countdown.hold();
+        this.scope = new FocusScopeController(this, {
+            contents: () => [
+                ...(this.renderRoot
+                    ?.querySelector('slot[name="actions"]')
+                    ?.assignedElements({ flatten: true }) ?? []),
+                ...[...(this.renderRoot?.querySelectorAll('[part="dismiss"]') ?? [])],
+            ],
+            surface: () => null,
+        });
+        this.focused = false;
+        this.handleHotkey = (event) => {
+            if (event.defaultPrevented || !matchesChord(event, this.hotkey, onApple())) {
+                return;
+            }
+            if (this.scope.holdsFocus) {
+                if (this.scope.leave()) {
+                    event.preventDefault();
+                }
+                this.origin = undefined;
+                return;
             }
-            else if (!document.hidden && this.heldHidden) {
-                this.heldHidden = false;
-                this.countdown.release();
+            const other = event
+                .composedPath()
+                .some((node) => node !== this && node instanceof HelixHeadlessAnnouncement_1);
+            if (other || this.scope.controls.length === 0) {
+                return;
             }
+            event.preventDefault();
+            const active = deepActiveElement();
+            this.origin = active instanceof HTMLElement ? active : undefined;
+            this.scope.enter();
         };
-        this.handleHold = () => {
+        this.handleHold = (event) => {
+            this.focused ||= event.type === 'focusin';
             this.countdown.hold();
         };
-        this.handleRelease = () => {
+        this.handleRelease = (event) => {
+            if (event.type === 'focusout') {
+                queueMicrotask(() => {
+                    this.focused = this.matches(':focus-within');
+                });
+            }
             this.countdown.release();
         };
     }
+    behind() {
+        if (!this.queued || (this.shadowRoot !== null && !this.hasUpdated)) {
+            return false;
+        }
+        for (let at = this.previousElementSibling; at; at = at.previousElementSibling) {
+            if (at instanceof HelixHeadlessAnnouncement_1 && at.queued) {
+                return true;
+            }
+        }
+        return false;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, {
+            label: this.label,
+            role: this.label.trim() && !this.waiting ? 'region' : '',
+        });
+        if ('ariaKeyShortcuts' in this.internals) {
+            this.internals.ariaKeyShortcuts = ariaChord(this.hotkey, onApple()) || null;
+        }
+    }
     connectedCallback() {
+        this.waiting = this.behind();
         super.connectedCallback();
+        this.watchQueue();
         this.addEventListener('mouseenter', this.handleHold);
         this.addEventListener('mouseleave', this.handleRelease);
         this.addEventListener('focusin', this.handleHold);
         this.addEventListener('focusout', this.handleRelease);
-        document.addEventListener('visibilitychange', this.handleVisibility);
+        document.addEventListener('keydown', this.handleHotkey);
         if (this.hasUpdated) {
             this.countdown.resume();
-            this.handleVisibility();
         }
     }
     disconnectedCallback() {
@@ -60,13 +115,26 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
         this.removeEventListener('mouseleave', this.handleRelease);
         this.removeEventListener('focusin', this.handleHold);
         this.removeEventListener('focusout', this.handleRelease);
-        document.removeEventListener('visibilitychange', this.handleVisibility);
-        this.heldHidden = false;
+        document.removeEventListener('keydown', this.handleHotkey);
+        this.queue?.disconnect();
+        const origin = this.focused ? this.origin : undefined;
+        this.focused = false;
+        this.origin = undefined;
+        if (origin) {
+            requestAnimationFrame(() => {
+                const active = deepActiveElement();
+                if (origin.isConnected && (active === null || active === document.body)) {
+                    origin.focus({ preventScroll: true });
+                }
+            });
+        }
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        this.countdown.start(this.duration);
-        this.handleVisibility();
+        this.watchQueue();
+        if (!this.waiting) {
+            this.countdown.start(this.duration);
+        }
         if (this.querySelector(':scope > [slot="icon"]')) {
             reportRuntime({
                 kind: 'deprecated',
@@ -78,6 +146,26 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
     updated(changed) {
         super.updated(changed);
         this.markEmpty();
+        if (changed.has('queued')) {
+            this.watchQueue();
+        }
+        this.toggleState('waiting', this.waiting);
+        if (changed.has('waiting') && this.waiting) {
+            this.arrival.say();
+        }
+        else if (changed.get('waiting') === true) {
+            this.countdown.start(this.duration);
+        }
+    }
+    watchQueue() {
+        this.queue?.disconnect();
+        this.waiting = this.behind();
+        if (this.queued && this.parentElement && typeof MutationObserver !== 'undefined') {
+            this.queue ??= new MutationObserver(() => {
+                this.waiting = this.behind();
+            });
+            this.queue.observe(this.parentElement, { childList: true });
+        }
     }
     markEmpty() {
         markRegion(this.renderRoot, 'actions', ['actions']);
@@ -92,6 +180,9 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
     >`;
     }
     render() {
+        if (this.waiting) {
+            return nothing;
+        }
         return html `<div aria-hidden=${this.arrival.said === '' ? nothing : 'true'} part="content"
         ><slot @slotchange=${() => this.arrival.say()}></slot
       ></div>
@@ -112,10 +203,22 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
 __decorate([
     property({ type: Number })
 ], HelixHeadlessAnnouncement.prototype, "duration", void 0);
+__decorate([
+    property()
+], HelixHeadlessAnnouncement.prototype, "hotkey", void 0);
+__decorate([
+    property()
+], HelixHeadlessAnnouncement.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessAnnouncement.prototype, "queued", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessAnnouncement.prototype, "tone", void 0);
-HelixHeadlessAnnouncement = __decorate([
+__decorate([
+    state()
+], HelixHeadlessAnnouncement.prototype, "waiting", void 0);
+HelixHeadlessAnnouncement = HelixHeadlessAnnouncement_1 = __decorate([
     customElement('helix-headless-announcement')
 ], HelixHeadlessAnnouncement);
 export { HelixHeadlessAnnouncement };

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

@@ -37,7 +37,7 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
     get stack() {
         const rows = this.sourceRows;
         const columns = this.plottedColumns;
-        const names = columns.map((column) => rows.find((row) => row.cells[column])?.cells[column]?.name ?? '');
+        const names = columns.map((column) => this.columnName(column));
         const values = columns.map((column, depth) => rows.map((row) => {
             if (!this.showsSeries(names[depth] ?? '')) {
                 return 0;
@@ -186,9 +186,8 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
             ]
             : []);
         const named = this.named ? `${this.named}, ` : '';
-        return html `<p id="helix-chart-summary" part="summary">
-      ${named}${rows[last]?.label ?? ''}: ${this.totalLabel} ${format(total)}; ${shares.join(', ')}.
-    </p>`;
+        const words = `${named}${rows[last]?.label ?? ''}: ${this.totalLabel} ${format(total)}; ${shares.join(', ')}.`;
+        return html `<p id="helix-chart-summary" part="summary">${words}</p>`;
     }
     tallied(rows, stack) {
         const format = formatNumbers(this.locale);

package/dist/badge/count.d.ts

@@ -0,0 +1,14 @@
+/** Whether the value counts nothing, in which case there is no mark. */
+export declare const badgeBlank: (given: string) => boolean;
+/** Whether the count is past `max`, which the mark shows as `{max}+`. */
+export declare const badgeCapped: (given: string, max: number | undefined) => boolean;
+/**
+ * What the mark reads once the cap has been applied: the value as given, or
+ * written with `options` in `locale` where they are set and it is a number.
+ */
+export declare const badgeText: (given: string, max: number | undefined, locale: string, options: Intl.NumberFormatOptions | undefined) => string;
+/**
+ * What a reader hears for the mark: `label` with `{count}` filled, or the text
+ * alone, and nothing for a blank mark or an unnamed dot.
+ */
+export declare const badgeWords: (text: string, label: string, blank: boolean) => string;

package/dist/badge/count.js

@@ -0,0 +1,20 @@
+import { fillTemplate, formatNumber } from '@fusion.dev/helix-core';
+export const badgeBlank = (given) => given.trim() !== '' && Number(given) === 0;
+export const badgeCapped = (given, max) => {
+    const count = Number(given);
+    return max !== undefined && Number.isFinite(count) && count > max;
+};
+export const badgeText = (given, max, locale, options) => {
+    const write = (count) => options ? formatNumber(count, locale, options) : String(count);
+    if (badgeCapped(given, max)) {
+        return `${write(max)}+`;
+    }
+    const count = Number(given);
+    return options && given.trim() !== '' && Number.isFinite(count) ? write(count) : given;
+};
+export const badgeWords = (text, label, blank) => {
+    if (blank || (text === '' && label === '')) {
+        return '';
+    }
+    return fillTemplate(label, { count: text }) || text;
+};

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

@@ -4,9 +4,10 @@ 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, fillTemplate, formatNumber, HelixElement } from '@fusion.dev/helix-core';
+import { customElement, focusTarget, HelixElement } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { badgeBlank, badgeCapped, badgeText, badgeWords } from '../count.js';
 let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     constructor() {
         super(...arguments);
@@ -21,28 +22,16 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
         return String(this.value ?? '');
     }
     get blank() {
-        return this.given.trim() !== '' && Number(this.given) === 0;
+        return badgeBlank(this.given);
     }
     get capped() {
-        const count = Number(this.given);
-        return this.max !== undefined && Number.isFinite(count) && count > this.max;
+        return badgeCapped(this.given, this.max);
     }
     get text() {
-        const write = (count) => this.formatOptions ? formatNumber(count, this.locale, this.formatOptions) : String(count);
-        if (this.capped) {
-            return `${write(this.max)}+`;
-        }
-        const count = Number(this.given);
-        return this.formatOptions && this.given.trim() !== '' && Number.isFinite(count)
-            ? write(count)
-            : this.given;
+        return badgeText(this.given, this.max, this.locale, this.formatOptions);
     }
     get words() {
-        const text = this.text;
-        if (this.blank || (text === '' && this.label === '')) {
-            return '';
-        }
-        return fillTemplate(this.label, { count: text }) || text;
+        return badgeWords(this.text, this.label, this.blank);
     }
     wrapped() {
         const found = this.renderRoot
@@ -50,10 +39,7 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
             ?.assignedElements({ flatten: true })
             .find((element) => element instanceof HTMLElement &&
             (element.tabIndex >= 0 || element.shadowRoot?.delegatesFocus === true));
-        const inner = found?.shadowRoot?.delegatesFocus
-            ? found.shadowRoot.querySelector('a[href], button, input, select, textarea')
-            : null;
-        return inner ?? found;
+        return found && focusTarget(found);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -113,7 +99,7 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
         data-blank=${blank ? '' : nothing}
         data-single=${text.length <= 1 ? '' : nothing}
         role="status"
-        aria-label=${announced ? fillTemplate(this.label, { count: text }) || text : nothing}
+        aria-label=${announced ? this.words : nothing}
         >${blank ? html `<span aria-hidden="true">${text}</span>` : text}</span
       >`;
     }

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

@@ -1,16 +1,36 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { type CSSResultGroup, type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A passage set off from the prose around it.
  *
  * @description
- * Renders a `<figure>` holding the `<blockquote>` and a `<figcaption>` for the
+ * Renders a figure holding the `<blockquote>` and a caption for the
  * attribution, the structure the HTML spec describes. The attribution sits
  * outside the quotation because it is about the quotation, and it names the
  * figure, so a screen reader reads the source as the figure's caption.
  *
- * The figure keeps the browser's default margins on this tier. Set
- * `::part(figure) { margin: 0 }` where they are unwanted.
+ * **The figure is a `<div role="figure">`**, so the headless tier draws no
+ * space around the quotation. A `<figure>` takes a 40px indent and a line of
+ * space above and below from the browser's own sheet, which every page had to
+ * reset. The `<blockquote>` keeps its own margins, as a bare one does. A
+ * screen reader meets the same figure, named by its caption.
+ *
+ * **A figure only while there is an attribution.** With nothing in the caption
+ * the figure has no name and nothing to say, so the role and its name are
+ * dropped and a reader meets the quotation alone. A server cannot see what is
+ * slotted, so it serves the figure, and the client drops it after hydration;
+ * an `attribution` written as words is served exactly.
+ *
+ * **Quotation marks follow the language**, under `marks`. The opening mark is
+ * the one the browser sets for a `<q>` in the element's language, „ under
+ * `lang="de"` and « under `lang="fr"`, and a `Quote` inside the passage takes
+ * the inner marks. The mark is drawn, not read: a screen reader hears the
+ * passage. A passage under `marks` that starts with a mark typed into the text
+ * would show two, and warns once, with the runtime kind `typed-marks`.
+ *
+ * **`cite` is the source's URL**, which the browser keeps and does not show.
+ * Words in it, such as the author's name, warn once, with the runtime kind
+ * `cite-not-url`.
  *
  * For a quotation inside a sentence, use `Quote`.
  *
@@ -21,17 +41,37 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/blockquote
  *
  * @slot - The quoted passage.
- * @slot attribution - Who said it, and where.
+ * @slot attribution - Who said it, and where. Replaces the words of `attribution`.
  *
- * @csspart attribution - The `<figcaption>` carrying the source.
+ * @csspart attribution - The caption carrying the source.
  * @csspart blockquote - The quotation.
- * @csspart figure - The `<figure>` holding the quotation and its attribution.
+ * @csspart figure - The figure holding the quotation and its attribution, a `<div>` with `role="figure"` while the attribution has words.
  */
 export declare class HelixHeadlessBlockquote extends HelixElement {
+    static styles: CSSResultGroup;
     /**
-     * The URL of the source the passage came from.
+     * Who said it, and where, as words, such as "Maria Lopez, operations
+     * manager". The `attribution` slot replaces them, for markup such as a link.
+     *
+     * Words are served with the figure they name, where a server cannot see a
+     * slotted attribution.
+     */
+    attribution: string;
+    /**
+     * The URL of the source the passage came from. Who said it goes in
+     * `attribution`: a `cite` with words in it warns once, with the runtime kind
+     * `cite-not-url`.
      */
     cite: string;
+    /**
+     * Whether to draw an opening quotation mark before the passage, in the
+     * element's language. Leave the marks out of the text.
+     */
+    marks: boolean;
+    /** Whether this blockquote has said its passage starts with a typed mark, so it says so once. */
+    private warned;
+    /** Whether this blockquote has said its `cite` holds words, so it says so once. */
+    private citeWarned;
     /**
      * Says on the caption whether there is an attribution in it.
      *
@@ -44,8 +84,26 @@ export declare class HelixHeadlessBlockquote extends HelixElement {
      * rendered, which React reports on hydration.
      */
     private markEmpty;
+    /**
+     * Reads the passage for a mark typed at its start, which `marks` would
+     * double. Only the start: the mark drawn is an opening one.
+     */
+    private readonly readPassage;
+    /**
+     * Reads `cite` for words where the source's URL belongs, the common mistake
+     * of naming the author there. A URL holds no spaces, so words with a space
+     * between them are enough to tell.
+     */
+    private readCite;
+    protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
+    /**
+     * The caption, with the words of `attribution` as its slot's fallback,
+     * behind a seam a tier can move. The words are in an element, so the region
+     * counts them as its own.
+     */
+    protected renderAttribution(): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {