@fusion.dev/helix-headless 0.142.0 → 0.143.0

package/dist/date-picker/root/date-picker-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 { valueAsDate as asDate, customElement, dateAsValue as fromDate, HelixFormElement, HelixNavigateEvent, hostAria, inlineStep, MixinControllerValue, reportValues, requestChange, } from '@fusion.dev/helix-core';
+import { valueAsDate as asDate, customElement, fillTemplate, dateAsValue as fromDate, HelixFormElement, HelixNavigateEvent, hostAria, inlineStep, MixinControllerValue, reportValues, requestChange, writtenList, } from '@fusion.dev/helix-core';
 import { caretLeft, caretRight } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -31,6 +31,17 @@ const list = (value) => value
     .split(',')
     .map((entry) => entry.trim())
     .filter(Boolean);
+const weekStartOf = (locale) => {
+    try {
+        const tag = new Intl.Locale(locale);
+        const first = tag.getWeekInfo?.().firstDay ?? tag.weekInfo?.firstDay;
+        return first === undefined ? 0 : first % 7;
+    }
+    catch {
+        return 0;
+    }
+};
+const monthOf = (date) => `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
 const addDays = (date, days) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days));
 const sameMonth = (left, right) => left.getUTCFullYear() === right.getUTCFullYear() && left.getUTCMonth() === right.getUTCMonth();
 const addMonths = (date, months) => {
@@ -44,7 +55,6 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         this.defaultMonth = '';
         this.disableDates = '';
         this.disableDays = '';
-        this.firstDayOfWeek = 0;
         this.invalid = false;
         this.label = 'Date Picker';
         this.locale = '';
@@ -54,10 +64,10 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         this.months = 1;
         this.nextLabel = 'Next month';
         this.previousLabel = 'Previous month';
-        this.readOnly = false;
         this.focused = '';
+        this.choosing = false;
         this.handleKeydown = (event) => {
-            if (!KEYS.has(event.key) || this.disabled) {
+            if (!KEYS.has(event.key) || this.isDisabled) {
                 return;
             }
             const path = event.composedPath();
@@ -80,10 +90,10 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
                 this.moveTo(addDays(from, 7));
             }
             else if (event.key === 'Home') {
-                this.moveTo(addDays(from, -((from.getUTCDay() - this.firstDayOfWeek + 7) % 7)));
+                this.moveTo(addDays(from, -((from.getUTCDay() - this.weekStart + 7) % 7)));
             }
             else if (event.key === 'End') {
-                this.moveTo(addDays(from, 6 - ((from.getUTCDay() - this.firstDayOfWeek + 7) % 7)));
+                this.moveTo(addDays(from, 6 - ((from.getUTCDay() - this.weekStart + 7) % 7)));
             }
             else {
                 const step = event.key === 'PageUp' ? -1 : 1;
@@ -91,6 +101,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
             }
             event.preventDefault();
         };
+        this.readOnly = false;
         this.required = false;
         this.step = 1;
     }
@@ -105,6 +116,12 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
     get selected() {
         return list(this.value);
     }
+    get weekStart() {
+        if (this.firstDayOfWeek !== undefined && Number.isFinite(this.firstDayOfWeek)) {
+            return ((Math.floor(this.firstDayOfWeek) % 7) + 7) % 7;
+        }
+        return this.locale === '' ? 0 : weekStartOf(this.locale);
+    }
     get range() {
         const dates = this.selected;
         if (this.mode !== 'range' || dates.length < 2) {
@@ -141,7 +158,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         return shown;
     }
     weeksOf(month) {
-        const offset = (month.getUTCDay() - this.firstDayOfWeek + 7) % 7;
+        const offset = (month.getUTCDay() - this.weekStart + 7) % 7;
         const start = addDays(month, -offset);
         return Array.from({ length: 6 }, (_, week) => Array.from({ length: 7 }, (_, day) => addDays(start, week * 7 + day)));
     }
@@ -153,7 +170,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         if (this.max !== '' && iso > this.max) {
             return true;
         }
-        if (list(this.disableDays).includes(String(date.getUTCDay()))) {
+        if (writtenList(this.disableDays).includes(String(date.getUTCDay()))) {
             return true;
         }
         const step = Math.max(1, Math.floor(this.step) || 1);
@@ -164,13 +181,32 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
                 return true;
             }
         }
-        return list(this.disableDates).includes(iso);
+        return writtenList(this.disableDates).includes(iso);
+    }
+    clamp(date) {
+        const iso = fromDate(date);
+        const min = asDate(this.min);
+        const max = asDate(this.max);
+        if (min && iso < this.min) {
+            return min;
+        }
+        if (max && iso > this.max) {
+            return max;
+        }
+        return date;
+    }
+    get atStart() {
+        return asDate(this.min) !== null && monthOf(addMonths(this.shown, -1)) < this.min.slice(0, 7);
+    }
+    get atEnd() {
+        return (asDate(this.max) !== null &&
+            monthOf(addMonths(this.shown, this.monthCount)) > this.max.slice(0, 7));
     }
     show(date) {
-        if (this.disabled) {
+        if (this.isDisabled) {
             return;
         }
-        const next = `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+        const next = monthOf(date);
         if (next === this.month) {
             return;
         }
@@ -185,7 +221,8 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
             next,
         });
     }
-    moveTo(date) {
+    moveTo(wanted) {
+        const date = this.clamp(wanted);
         this.focused = fromDate(date);
         this.show(date);
         this.updateComplete.then(() => {
@@ -193,7 +230,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         });
     }
     select(date) {
-        if (this.disabled) {
+        if (this.isDisabled) {
             return;
         }
         if (this.barred(date)) {
@@ -212,8 +249,12 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
             next = [iso];
         }
         this.focused = iso;
+        this.choosing = true;
         this.requestValue(next.join(','));
     }
+    focus(options) {
+        this.renderRoot?.querySelector('[part~="cell"][tabindex="0"]')?.focus(options);
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('keydown', this.handleKeydown);
@@ -228,6 +269,37 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         }
         return super.requestValue(next);
     }
+    spoken(iso) {
+        const date = asDate(iso);
+        return date ? this.formats.long.format(date) : iso;
+    }
+    fault(iso) {
+        if (this.min !== '' && iso < this.min) {
+            return [
+                'rangeUnderflow',
+                fillTemplate(this.rangeUnderflowMessage || 'Choose a date on or after {min}.', {
+                    min: this.spoken(this.min),
+                }),
+            ];
+        }
+        if (this.max !== '' && iso > this.max) {
+            return [
+                'rangeOverflow',
+                fillTemplate(this.rangeOverflowMessage || 'Choose a date on or before {max}.', {
+                    max: this.spoken(this.max),
+                }),
+            ];
+        }
+        const date = asDate(iso);
+        if (!date || !this.barred(date)) {
+            return undefined;
+        }
+        const listed = writtenList(this.disableDates).includes(iso) ||
+            writtenList(this.disableDays).includes(String(date.getUTCDay()));
+        return listed
+            ? ['badInput', this.unavailableMessage || 'Choose a date that is available.']
+            : ['stepMismatch', this.stepMismatchMessage || 'Choose one of the dates the calendar offers.'];
+    }
     reportRequired() {
         const anchor = this.partNamed('grid') ?? undefined;
         if (this.required && this.value === '') {
@@ -242,11 +314,27 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
                     : 'Enter dates as YYYY-MM-DD, separated by commas.'), anchor);
             return;
         }
+        for (const one of held) {
+            const fault = this.fault(one);
+            if (fault) {
+                this.internals.setValidity({ [fault[0]]: true }, fault[1], anchor);
+                return;
+            }
+        }
         this.internals.setValidity({});
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { label: this.label, role: 'group' });
+        if (changed.has('value') && !this.choosing) {
+            this.focused = '';
+        }
+        this.choosing = false;
+        const outside = this.label === 'Date Picker' ? [...(this.internals.labels ?? [])] : [];
+        hostAria(this.internals, {
+            label: this.label,
+            labelledBy: outside,
+            role: 'group',
+        });
         this.internals.ariaDisabled = this.isDisabled ? 'true' : null;
         this.internals.ariaInvalid = this.invalid ? 'true' : null;
         this.report();
@@ -256,7 +344,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         this.reportRequired();
     }
     report() {
-        if (this.disabled) {
+        if (this.isDisabled) {
             this.internals.setFormValue(null);
             return;
         }
@@ -274,6 +362,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
             full: new Intl.DateTimeFormat(locale, { dateStyle: 'full', timeZone: 'UTC' }),
             heading: new Intl.DateTimeFormat(locale, { month: 'long', timeZone: 'UTC', year: 'numeric' }),
             locale: this.locale,
+            long: new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }),
             weekday: new Intl.DateTimeFormat(locale, { timeZone: 'UTC', weekday: 'short' }),
         };
         this.cachedFormats = built;
@@ -308,17 +397,20 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
                 part="previous"
                 type="button"
                 aria-label=${this.previousLabel}
+                ?disabled=${this.isDisabled || this.atStart}
                 @click=${() => this.show(addMonths(this.shown, -1))}
               >
                 ${this.renderPreviousMark()}
               </button>`
             : nothing}
-        <span part="heading">${heading.format(month)}</span>
+        ${''}
+        <span part="heading" aria-live="polite">${heading.format(month)}</span>
         ${last
             ? html `<button
                 part="next"
                 type="button"
                 aria-label=${this.nextLabel}
+                ?disabled=${this.isDisabled || this.atEnd}
                 @click=${() => this.show(addMonths(this.shown, 1))}
               >
                 ${this.renderNextMark()}
@@ -329,6 +421,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
         part="grid"
         role="grid"
         aria-label=${heading.format(month)}
+        aria-readonly=${this.readOnly ? 'true' : nothing}
         data-unset=${this.value === '' ? '' : nothing}
       >
         <div part="week" role="row">
@@ -346,7 +439,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
             return html `<span
                 part="cell${start ? ' cell-range-start' : ''}${middle ? ' cell-range-middle' : ''}${end ? ' cell-range-end' : ''}"
                 role="gridcell"
-                aria-disabled=${disabled ? 'true' : nothing}
+                aria-disabled=${disabled || outside ? 'true' : nothing}
                 aria-label=${full.format(date)}
                 aria-current=${iso === today ? 'date' : nothing}
                 aria-selected=${!outside && selected ? 'true' : nothing}
@@ -355,7 +448,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControl
                 data-range-middle=${middle ? '' : nothing}
                 data-range-start=${start ? '' : nothing}
                 data-today=${iso === today ? '' : nothing}
-                tabindex=${!outside && iso === anchor ? '0' : '-1'}
+                tabindex=${!outside && iso === anchor && !this.isDisabled ? '0' : '-1'}
                 @click=${outside ? nothing : () => this.select(date)}
                 ><span
                   part="day${!outside && selected && !middle ? ' day-selected' : ''}${iso === today ? ' day-today' : ''}${outside ? ' day-outside' : ''}${disabled ? ' day-disabled' : ''}"
@@ -433,17 +526,29 @@ __decorate([
     property({ attribute: 'previous-label' })
 ], HelixHeadlessDatePicker.prototype, "previousLabel", void 0);
 __decorate([
-    property({ attribute: 'readonly', reflect: true, type: Boolean })
-], HelixHeadlessDatePicker.prototype, "readOnly", void 0);
+    property({ attribute: 'range-overflow-message' })
+], HelixHeadlessDatePicker.prototype, "rangeOverflowMessage", void 0);
 __decorate([
     state()
 ], HelixHeadlessDatePicker.prototype, "focused", void 0);
+__decorate([
+    property({ attribute: 'range-underflow-message' })
+], HelixHeadlessDatePicker.prototype, "rangeUnderflowMessage", void 0);
+__decorate([
+    property({ attribute: 'readonly', reflect: true, type: Boolean })
+], HelixHeadlessDatePicker.prototype, "readOnly", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessDatePicker.prototype, "required", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessDatePicker.prototype, "step", void 0);
+__decorate([
+    property({ attribute: 'step-mismatch-message' })
+], HelixHeadlessDatePicker.prototype, "stepMismatchMessage", void 0);
+__decorate([
+    property({ attribute: 'unavailable-message' })
+], HelixHeadlessDatePicker.prototype, "unavailableMessage", void 0);
 __decorate([
     property({ attribute: 'value-missing-message' })
 ], HelixHeadlessDatePicker.prototype, "valueMissingMessage", void 0);

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

@@ -1,4 +1,4 @@
-import { CommandController, HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, CommandController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
@@ -19,6 +19,10 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  * keeps your state in step, so the dialog never closes while your state still
  * says it is open, which would leave it impossible to reopen.
  *
+ * The dialog's name is `label` when you set it. Otherwise it is the heading in
+ * the `header` slot, or the elements an `aria-labelledby` on the host names.
+ * While it is open, the page behind it does not scroll.
+ *
  * @since 0.1.0
  * @status stable
  * @category overlays
@@ -33,7 +37,7 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  * @event {Event} close - Sent from the host after the dialog closes, because the native `close` event does not leave the shadow root.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {Event} toggle - Sent when the dialog opens or closes, with `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - Sent when the dialog opens or closes, with `newState` and `oldState`.
  *
  * @csspart dialog - The native dialog element.
  *
@@ -54,9 +58,11 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
      */
     closedBy?: 'any' | 'closerequest' | 'none';
     /**
-     * Accessible name for the dialog.
+     * Accessible name for the dialog. When it is empty, the heading in the
+     * `header` slot names the dialog.
      */
     label: string;
+    protected readonly aria: AriaForwardController;
     protected readonly commands: CommandController;
     /**
      * Stops Escape and a press on the backdrop from closing the dialog.
@@ -120,20 +126,42 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
      * saying otherwise would be a lie the next `showModal()` would trip over.
      */
     private readonly handleClose;
+    /**
+     * A `<form method="dialog">` slotted into the dialog, closed the way the
+     * platform closes its own.
+     *
+     * **The platform cannot find this dialog from the form.** A submit with the
+     * `dialog` method closes the nearest `<dialog>` ancestor, and a slotted form's
+     * ancestors are the light DOM, where there is none. So the submit is read
+     * here, and the submitter's `value` is the `returnValue`, as it would be.
+     */
+    private readonly handleSubmit;
+    /** Whether the `header` slot's heading is what currently names the dialog. */
+    private namedByHeader;
+    /**
+     * Names the dialog by its heading, where nothing else names it.
+     *
+     * An element reference, because the heading is in the light DOM and the
+     * `<dialog>` is in this shadow root, which an IDREF cannot cross. `label` and
+     * an `aria-labelledby` on the host come first, so this steps aside for
+     * either. A browser without element reflection keeps the fallback name.
+     */
+    private nameByHeader;
     protected willUpdate(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;
     /** Opens once anything slotted has had its first render. See `updated`. */
     private openWhenSlotted;
     /**
      * A press on the backdrop, which lands on the dialog element itself.
      *
-     * **The target alone is not enough here, where it is for `Drawer`.** A modal
-     * `<dialog>` attributes backdrop clicks to itself, which is the usual trick,
-     * and this panel also carries `--dialog-padding` of padding: a press in that
-     * padding has the same target as a press on the backdrop, so the trick alone
-     * closes a dialog when a reader clicks just inside its own edge. The drawer
-     * escapes that because its panel is flush against the window and its content
-     * fills it. So the point is compared against the panel's box.
+     * **The target alone is not enough.** A modal `<dialog>` attributes backdrop
+     * clicks to itself, which is the usual trick, and this panel also carries
+     * `--dialog-padding` of padding: a press in that padding has the same target
+     * as a press on the backdrop, so the trick alone closes a dialog when a reader
+     * clicks just inside its own edge. So the point is compared against the
+     * panel's box. `Drawer` does the same.
      */
     private readonly handleBackdrop;
     /**

package/dist/dialog/root/dialog-root.js

@@ -4,13 +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 { CommandController, customElement, HelixElement, hostAria, MixinControllerOpen, } from '@fusion.dev/helix-core';
+import { AriaForwardController, CommandController, customElement, HelixElement, hostAria, lockScroll, MixinControllerOpen, unlockScroll, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
         this.label = '';
+        this.aria = new AriaForwardController(this, { target: () => this.dialog });
         this.commands = new CommandController(this, {
             commands: {
                 '--close': () => this.close(),
@@ -33,6 +34,20 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
             }
             this.relayNativeEvent(event);
         };
+        this.handleSubmit = (event) => {
+            const form = event.target;
+            if (!(form instanceof HTMLFormElement) || form.closest('dialog')) {
+                return;
+            }
+            const submitter = event.submitter;
+            const method = submitter?.hasAttribute('formmethod') ? submitter.formMethod : form.method;
+            if (method !== 'dialog') {
+                return;
+            }
+            event.preventDefault();
+            this.close(submitter?.hasAttribute('value') ? submitter.value : undefined);
+        };
+        this.namedByHeader = false;
         this.handleBackdrop = (event) => {
             const panel = this.dialog;
             if (!panel || event.target !== panel) {
@@ -77,12 +92,44 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
             this.returnValue = previous;
         }
     }
+    nameByHeader() {
+        const dialog = this.dialog;
+        if (!dialog || !('ariaLabelledByElements' in dialog)) {
+            return;
+        }
+        const slot = this.renderRoot.querySelector('slot[name="header"]');
+        const heading = this.label || this.hasAttribute('aria-labelledby') ? [] : headingsIn(slot);
+        if (heading.length > 0) {
+            dialog.ariaLabelledByElements = heading;
+            this.namedByHeader = true;
+        }
+        else if (this.namedByHeader) {
+            dialog.ariaLabelledByElements = null;
+            this.namedByHeader = false;
+        }
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label });
     }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('submit', this.handleSubmit);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('submit', this.handleSubmit);
+        unlockScroll(this);
+    }
     updated(changed) {
         super.updated(changed);
+        this.nameByHeader();
+        if (this.open) {
+            lockScroll(this);
+        }
+        else {
+            unlockScroll(this);
+        }
         const dialog = this.dialog;
         if (!dialog) {
             return;
@@ -132,7 +179,7 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
       @close=${this.handleClose}
     >
       <slot name="icon"></slot>
-      <slot name="header"></slot>
+      <slot name="header" @slotchange=${this.nameByHeader}></slot>
       <slot></slot>
       <slot name="footer"></slot>
     </dialog>`;
@@ -151,3 +198,9 @@ HelixHeadlessDialog = __decorate([
     customElement('helix-headless-dialog')
 ], HelixHeadlessDialog);
 export { HelixHeadlessDialog };
+const headingsIn = (slot) => {
+    const assigned = slot?.assignedElements({ flatten: true }) ?? [];
+    const heading = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
+    const found = assigned.flatMap((one) => one.matches(heading) ? [one] : [...one.querySelectorAll(heading)].slice(0, 1));
+    return found.length > 0 ? found.slice(0, 1) : assigned;
+};

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

@@ -1,6 +1,15 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
+/** One slice: its share of the whole, where it starts, and the row it was read from. */
+export interface DonutShare {
+    /** The slice's share of the whole, from 0 to 1. */
+    fraction: number;
+    /** The table row the slice was read from, counting from zero. */
+    row: number;
+    /** Where the slice starts, as a share of the whole. */
+    start: number;
+}
 declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
  * @summary A chart that shows parts of a whole as a ring, read from a table.
@@ -15,13 +24,17 @@ declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args:
  * **Negative values are skipped.** An arc cannot show a negative number, so
  * those rows are left out and the total is the sum of the remaining rows.
  *
+ * The ring is `aria-hidden`. The `summary` part names the chart, from `label`
+ * or the table's caption, and gives each slice's share, and the table beside
+ * the chart has every amount.
+ *
  * @since 0.1.0
  * @status stable
  * @category charts
  * @aliases Pie Chart, Ring Chart, Share Chart
  * @documentation https://fusion.dev/helix/components/donut-chart
  *
- * @slot - Content in the middle of the ring, usually a total.
+ * @slot - Content in the middle of the ring, usually a total. It is read by screen readers, while the ring itself is hidden from them.
  *
  * @csspart center - The middle of the ring, holding whatever is slotted.
  * @csspart mark - The invisible point the tooltip is anchored to.
@@ -29,6 +42,7 @@ declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args:
  * @csspart segment - One slice.
  * @csspart segment-active - The slice under the pointer. Set alongside `segment`.
  * @csspart segment-edge - One slice as a closed shape, used to draw its outline.
+ * @csspart summary - The chart's name and each slice's share, written as a sentence for screen readers. Hide it visually.
  * @csspart tooltip - The bubble, forwarded from `Tooltip`.
  * @csspart tooltip-anchor - The `Tooltip` element itself.
  * @csspart tooltip-arrow - The bubble's point, forwarded from `Tooltip`.
@@ -131,18 +145,34 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
     private get thickness();
     /** The ring's radius, which follows its thickness so the outer edge holds. */
     private get radius();
+    /**
+     * Each slice's share of the circle, where it starts, and the row it was read
+     * from.
+     *
+     * The row because a slice is not its row once a row is left out: a value
+     * that does not parse has no slice, and the tooltip counting slices against
+     * the table's rows named the row before the one under the pointer.
+     */
     private get shares();
     protected render(): TemplateResult;
+    /**
+     * What a reader who cannot see the ring is told: the chart's name and each
+     * slice's share of the whole.
+     *
+     * The shares, because they are what the ring shows and the table does not:
+     * the table holds the amounts, and the percentages are this chart's
+     * arithmetic. In the ring's order, which is the table's and the legend's.
+     */
+    protected renderSummary(shares: DonutShare[]): TemplateResult;
     /**
      * The ring itself, behind a seam the styled tier can move.
      *
-     * `aria-hidden`, because the table it was read from is the readable version
-     * and a screen reader hearing both hears the same numbers twice.
+     * The drawing is `aria-hidden`, because the table it was read from is the
+     * readable version and a screen reader hearing both hears the same numbers
+     * twice. The middle is not: a total slotted there is usually a number the
+     * table does not hold.
      */
-    protected renderPlot(shares: {
-        fraction: number;
-        start: number;
-    }[]): TemplateResult;
+    protected renderPlot(shares: DonutShare[]): TemplateResult;
     /**
      * The view box, cropped to what is actually drawn.
      *
@@ -155,10 +185,7 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      */
     private get frame();
     /** One slice, as a dash the length of its share. */
-    protected renderSegment(share: {
-        fraction: number;
-        start: number;
-    }, index: number): TemplateResult;
+    protected renderSegment(share: DonutShare, index: number): TemplateResult;
     /**
      * The same slice again, as a shape with an inside.
      *
@@ -189,10 +216,7 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      * `transform-box: fill-box`, so it spins each element about its own bounding
      * box, which is the ring's center for a circle and is not for a sector.
      */
-    protected renderEdge(share: {
-        fraction: number;
-        start: number;
-    }, index: number): TemplateResult;
+    protected renderEdge(share: DonutShare, index: number): TemplateResult;
     /**
      * What a pointer resting on a slice shows.
      *