@fusion.dev/helix-core 0.143.0 → 0.144.0

package/dist/mixins/mixin-segmented-field/mixin-segmented-field.js

@@ -0,0 +1,243 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { isPartial, isTwelveHourLayout, segmentKey, segmentLayout, segmentName, segmentRange, segmentsOf, segmentsValue, segmentText, segmentValueText, shownValue, } from '../../utils/date-segments/date-segments.js';
+import { inlineStep } from '../../utils/inline-step/inline-step.js';
+export const MixinSegmentedField = (Base) => {
+    class SegmentedFieldElement extends Base {
+        constructor() {
+            super(...arguments);
+            this.emptySegmentLabel = 'Empty';
+            this.segmented = false;
+            this.parts = {};
+            this.typed = '';
+            this.own = false;
+            this.entered = undefined;
+            this.handleSegmentKeydown = (event) => {
+                const element = event.currentTarget;
+                const kind = element.dataset.segment;
+                const twelve = isTwelveHourLayout(this.layout);
+                if (event.key === 'ArrowDown' && event.altKey) {
+                    event.preventDefault();
+                    this.handleTriggerClick();
+                    return;
+                }
+                const along = inlineStep(this, event.key);
+                if (along !== 0) {
+                    event.preventDefault();
+                    this.typed = '';
+                    this.moveFocus(element, along);
+                    return;
+                }
+                if (event.key === 'Tab') {
+                    this.typed = '';
+                    if (this.open) {
+                        this.requestOpen(false);
+                    }
+                    return;
+                }
+                if (event.metaKey || event.ctrlKey || event.altKey) {
+                    this.typed = '';
+                    return;
+                }
+                if (this.readOnly || this.isDisabled) {
+                    return;
+                }
+                const edit = segmentKey(event.key, {
+                    kind,
+                    locale: this.segmentLocale,
+                    segments: this.parts,
+                    twelve,
+                    typed: this.typed,
+                });
+                if (edit) {
+                    event.preventDefault();
+                    this.typed = edit.typed;
+                    this.take(edit.segments);
+                    if (edit.advance) {
+                        this.moveFocus(element, 1);
+                    }
+                }
+            };
+            this.handleSegmentsFocusIn = (event) => {
+                this.typed = '';
+                if (!this.segmentElements.includes(event.relatedTarget)) {
+                    this.entered = this.value;
+                }
+            };
+            this.handleSegmentsFocusOut = (event) => {
+                if (this.segmentElements.includes(event.relatedTarget)) {
+                    return;
+                }
+                if (this.entered !== undefined && this.entered !== this.value) {
+                    this.announceChange();
+                }
+                this.entered = undefined;
+            };
+            this.handleLabelPress = (event) => {
+                if (!this.segmentsShown || this.isDisabled) {
+                    return;
+                }
+                const label = this.renderRoot?.querySelector?.('[part~="label"]');
+                if (label && event.composedPath().includes(label)) {
+                    this.anchor?.focus();
+                }
+            };
+        }
+        get segmentable() {
+            return true;
+        }
+        get segmentsShown() {
+            return this.segmented && this.segmentable;
+        }
+        get segmentedKind() {
+            return 'date';
+        }
+        get segmentLocale() {
+            return '';
+        }
+        get segmentOptions() {
+            return {};
+        }
+        get layout() {
+            return segmentLayout(this.segmentedKind, this.segmentLocale, this.segmentOptions);
+        }
+        get anchor() {
+            if (this.segmentsShown) {
+                return this.renderRoot?.querySelector('[part~="segment"]') ?? null;
+            }
+            return super.anchor;
+        }
+        get segmentGroup() {
+            return this.renderRoot?.querySelector('[part="segments"]') ?? null;
+        }
+        get segmentElements() {
+            return [...(this.renderRoot?.querySelectorAll('[part~="segment"]') ?? [])];
+        }
+        take(next) {
+            this.parts = next;
+            const value = segmentsValue(this.segmentedKind, next, this.layout);
+            if (value === this.value) {
+                this.sync();
+                return;
+            }
+            this.own = true;
+            if (!this.requestValue(value)) {
+                this.own = false;
+                this.parts = segmentsOf(this.segmentedKind, this.value);
+            }
+        }
+        moveFocus(from, by) {
+            const all = this.segmentElements;
+            all[all.indexOf(from) + by]?.focus();
+        }
+        willUpdate(changed) {
+            super.willUpdate(changed);
+            const own = this.own;
+            this.own = false;
+            if (!own &&
+                this.segmentsShown &&
+                segmentsValue(this.segmentedKind, this.parts, this.layout) !== this.value) {
+                this.parts = segmentsOf(this.segmentedKind, this.value);
+            }
+        }
+        formResetCallback() {
+            super.formResetCallback();
+            this.parts = {};
+            this.typed = '';
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this.addEventListener('click', this.handleLabelPress);
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.removeEventListener('click', this.handleLabelPress);
+        }
+        get blocksImplicitSubmission() {
+            return this.segmentsShown || super.blocksImplicitSubmission;
+        }
+        sync() {
+            super.sync();
+            if (!this.segmentsShown) {
+                return;
+            }
+            const anchor = this.anchor ?? undefined;
+            const partial = isPartial(this.segmentedKind, this.parts, this.layout);
+            const message = this.validate();
+            if (partial) {
+                this.internals.setValidity({ badInput: true }, this.badInputMessage ||
+                    (this.segmentedKind === 'date' ? 'Enter a whole date.' : 'Enter a whole time.'), anchor);
+            }
+            else if (this.required && this.value === '') {
+                this.internals.setValidity({ valueMissing: true }, this.valueMissingMessage ||
+                    (this.segmentedKind === 'date' ? 'Enter a date.' : 'Enter a time.'), anchor);
+            }
+            else if (message !== '') {
+                this.internals.setValidity({ badInput: true }, message, anchor);
+            }
+            else {
+                this.internals.setValidity({});
+            }
+            this.refreshFeedback();
+        }
+        renderSegments() {
+            const layout = this.layout;
+            const twelve = isTwelveHourLayout(layout);
+            const locale = this.segmentLocale;
+            return html `<div
+        part="segments"
+        id=${this.controlId}
+        role="group"
+        aria-labelledby=${this.labeled ? this.labelId : nothing}
+        aria-describedby=${this.describedBy ?? nothing}
+        aria-invalid=${this.invalidity ?? nothing}
+        @focusin=${this.handleSegmentsFocusIn}
+        @focusout=${this.handleSegmentsFocusOut}
+        @keypress=${this.handleKeypress}
+      >
+        ${layout.map((slot) => {
+                if ('literal' in slot) {
+                    return html `<span part="literal" aria-hidden="true">${slot.literal}</span>`;
+                }
+                const kind = slot.kind;
+                const shown = shownValue(kind, this.parts, twelve);
+                const { max, min } = segmentRange(kind, this.parts, twelve);
+                const text = segmentText(kind, this.parts, twelve, locale);
+                const empty = shown === undefined;
+                return html `<span
+            part="segment${empty ? ' segment-placeholder' : ''}"
+            data-segment=${kind}
+            role="spinbutton"
+            tabindex=${this.isDisabled ? '-1' : '0'}
+            inputmode=${kind === 'dayPeriod' ? nothing : 'numeric'}
+            aria-label=${segmentName(kind, locale)}
+            aria-valuemin=${min}
+            aria-valuemax=${max}
+            aria-valuenow=${shown ?? nothing}
+            aria-valuetext=${empty ? this.emptySegmentLabel : segmentValueText(kind, this.parts, twelve, locale)}
+            aria-disabled=${this.isDisabled ? 'true' : nothing}
+            aria-readonly=${this.readOnly ? 'true' : nothing}
+            @keydown=${this.handleSegmentKeydown}
+            >${text}</span
+          >`;
+            })}
+      </div>`;
+        }
+    }
+    __decorate([
+        property({ attribute: 'empty-segment-label' })
+    ], SegmentedFieldElement.prototype, "emptySegmentLabel", void 0);
+    __decorate([
+        property({ type: Boolean })
+    ], SegmentedFieldElement.prototype, "segmented", void 0);
+    __decorate([
+        state()
+    ], SegmentedFieldElement.prototype, "parts", void 0);
+    return SegmentedFieldElement;
+};

package/dist/utils/arrow/arrow.d.ts

@@ -0,0 +1,15 @@
+import type { Placement, Side } from '../../controllers/floating-controller/floating-controller.js';
+/**
+ * How far a panel's arrow reaches past the edge it sits on, which is what the
+ * panel's offset adds so the gap is measured to the point.
+ *
+ * A square of side `n` turned forty-five degrees about its center reaches
+ * `n / sqrt(2)` from it, and the arrow is placed with its center on the
+ * panel's edge. Read from the element rather than assumed, because the size
+ * is a hook a theme may move. `offsetWidth` rather than a rect, which reports
+ * the turned box and would count the reach twice. Zero for no arrow, and while
+ * the panel is closed and unrendered, when there is nothing to place.
+ */
+export declare const arrowReach: (arrow: HTMLElement | null | undefined) => number;
+/** The side of its anchor a placement puts a panel on: `top-start` is `top`. */
+export declare const sideOf: (placement: Placement) => Side;

package/dist/utils/arrow/arrow.js

@@ -0,0 +1,2 @@
+export const arrowReach = (arrow) => (arrow?.offsetWidth ?? 0) / Math.SQRT2;
+export const sideOf = (placement) => placement.split('-')[0];

package/dist/utils/audit-name/audit-name.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Whether an element has an accessible name, by the routes a page names a
+ * control: its own `aria-label`, `aria-labelledby` or `title`, a `<label>`, a
+ * `placeholder`, and its content where its role is named by its content.
+ *
+ * **An estimate, cheap on purpose.** It answers whether any route holds words,
+ * which is what the warning is about, and leaves the order the routes win in
+ * to the browser.
+ */
+export declare const hasName: (element: HTMLElement) => boolean;
+/**
+ * Warns once, through the runtime channel, when a control has no accessible
+ * name: none on the host, and none on the control inside it.
+ *
+ * **Read a task after the control first renders**, so a label that arrives in
+ * the same pass counts: slotted, written by a framework beside the control, or
+ * forwarded from a `<label for>`. One timer serves every control that asked in
+ * that task, and an element is read once in its life, so a name taken away
+ * later is not reported.
+ *
+ * **In every build.** Every runtime warning in the library reports through the
+ * same channel whatever the build, and a project that wants the console quiet
+ * tells `@fusion.dev/helix-diagnostics` with `core.warnings: false`.
+ *
+ * `also` answers for a name the component gave through its internals, which no
+ * attribute shows. `fix` is the sentence that says how to name it.
+ */
+export declare const auditName: (host: HTMLElement, control: () => HTMLElement | null, fix: string, also?: () => boolean) => void;

package/dist/utils/audit-name/audit-name.js

@@ -0,0 +1,95 @@
+import { reportRuntime } from '../report-runtime/report-runtime.js';
+const nameText = (node) => {
+    if (node instanceof HTMLSlotElement) {
+        return node.assignedNodes({ flatten: true }).map(nameText).join('');
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent ?? '';
+    }
+    if (!(node instanceof Element)) {
+        return '';
+    }
+    if ((node instanceof HTMLElement && node.hidden) || node.getAttribute('aria-hidden') === 'true') {
+        return '';
+    }
+    const said = node.getAttribute('aria-label') ?? node.getAttribute('alt');
+    if (said?.trim()) {
+        return said;
+    }
+    return [...node.childNodes].map(nameText).join('');
+};
+const namesWithWords = (ids, from) => {
+    const root = from.getRootNode();
+    return (ids ?? '')
+        .split(/\s+/)
+        .filter(Boolean)
+        .some((id) => {
+        const found = root.getElementById?.(id);
+        return found ? nameText(found).trim() !== '' : false;
+    });
+};
+const NAMED_BY_CONTENT = new Set([
+    'button',
+    'checkbox',
+    'link',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'radio',
+    'switch',
+    'tab',
+]);
+export const hasName = (element) => {
+    for (const attribute of ['aria-label', 'title', 'placeholder']) {
+        if (element.getAttribute(attribute)?.trim()) {
+            return true;
+        }
+    }
+    if (namesWithWords(element.getAttribute('aria-labelledby'), element)) {
+        return true;
+    }
+    const referenced = element
+        .ariaLabelledByElements;
+    if ((referenced ?? []).some((one) => nameText(one).trim() !== '')) {
+        return true;
+    }
+    const labels = element.labels;
+    if ([...(labels ?? [])].some((label) => nameText(label).trim() !== '')) {
+        return true;
+    }
+    const role = element.getAttribute('role') ?? (element.localName === 'button' ? 'button' : '');
+    return NAMED_BY_CONTENT.has(role) && nameText(element).trim() !== '';
+};
+const audited = new WeakSet();
+const waiting = new Map();
+const readWaiting = () => {
+    const checks = [...waiting.values()];
+    waiting.clear();
+    for (const check of checks) {
+        check();
+    }
+};
+export const auditName = (host, control, fix, also) => {
+    if (audited.has(host) || waiting.has(host)) {
+        return;
+    }
+    if (waiting.size === 0) {
+        setTimeout(readWaiting, 0);
+    }
+    waiting.set(host, () => {
+        if (!host.isConnected) {
+            return;
+        }
+        audited.add(host);
+        const inner = control();
+        if (also?.() || hasName(host) || (inner !== null && hasName(inner))) {
+            return;
+        }
+        reportRuntime({
+            kind: 'missing-name',
+            message: `<${host.localName}> has no accessible name, so a screen reader announces it by its role alone. ${fix}`,
+            tag: host.localName,
+        });
+    });
+};

package/dist/utils/calendar/calendar.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Today, in the reader's own timezone.
+ *
+ * **`toISOString` converts to UTC first, which makes "today" a different day
+ * for most of the planet.** Anywhere west of UTC, from late afternoon onward,
+ * `fromDate(new Date())` names tomorrow. The parts are read locally instead and
+ * pasted together, which is the only way to get a calendar date out of a `Date`
+ * without a conversion happening on the way.
+ */
+export declare const localToday: (now?: Date) => string;
+/**
+ * The first day of the week where a language is spoken, `0` for Sunday.
+ *
+ * From `Intl.Locale`'s week information, which an engine offers as
+ * `getWeekInfo()` or, in older versions, as `weekInfo`. Sunday where it offers
+ * neither, as Firefox does not, or where the tag cannot be read.
+ */
+export declare const weekStartOf: (locale: string) => number;
+/** A month as `YYYY-MM`. */
+export declare const monthOf: (date: Date) => string;
+/** A date some days away, which may be negative, at midnight UTC. */
+export declare const addDays: (date: Date, days: number) => Date;
+/** Whether two dates fall in the same month of the same year. */
+export declare const sameMonth: (left: Date, right: Date) => boolean;
+/**
+ * A date some months away, clamped, so the last of a long month lands on the
+ * last of a short one instead of rolling into the month after it.
+ */
+export declare const addMonths: (date: Date, months: number) => Date;
+/** What bars a date, besides `min` and `max`. */
+export interface Barring {
+    /** Dates as `YYYY-MM-DD`, separated by commas or spaces. */
+    disableDates: string;
+    /** Days of the week, `0` for Sunday, separated by commas or spaces. */
+    disableDays: string;
+    /** A consumer's own rule, asked of each date. */
+    isDateUnavailable?: ((date: string) => boolean) | undefined;
+    /** Where `step` counts from, or empty for 1 January 1970. */
+    min: string;
+    /** How far apart the selectable dates are, in days. */
+    step: number;
+}
+/**
+ * Why a date cannot be chosen, besides `min` and `max`, or `null` where it can.
+ *
+ * `listed` is a date the rules name: in `disable-dates`, on a day in
+ * `disable-days`, or one `isDateUnavailable` refuses. `step` is a date `step`
+ * skips, counted from `min` where there is one and from the epoch where there is
+ * not, which is the platform's own base. Whole days, because both ends are
+ * midnight UTC and neither carries a time.
+ */
+export declare const barredBy: (date: Date, rules: Barring) => 'listed' | 'step' | null;
+/** The views a calendar can show: the days of a month, the months of a year, or a page of years. */
+export type CalendarView = 'day' | 'month' | 'year';
+/** How many years the year view shows at once, in rows of three. */
+export declare const YEARS_SHOWN = 12;
+/** The first year on the page of years that holds `year`. */
+export declare const yearPageOf: (year: number) => number;
+/**
+ * Where a key moves within the months of a year or a page of years, laid out
+ * in rows of three, as an offset from `at`, the index on the page.
+ *
+ * `along` is which way the inline keys go, `1` or `-1`, or `0` for a key that
+ * is not one. The vertical keys move a row, Home and End to the ends of a row,
+ * and PageUp and PageDown a whole page. `null` is a key the grid leaves alone.
+ */
+export declare const periodMove: (key: string, at: number, along: number) => number | null;
+/** Whether a month, as its first day, lies wholly outside `min` and `max`, either of which may be empty. */
+export declare const monthOut: (first: Date, min: string, max: string) => boolean;
+/** Whether a year lies wholly outside `min` and `max`, either of which may be empty. */
+export declare const yearOut: (year: number, min: string, max: string) => boolean;
+/** One month or year in the months or the years view. */
+export interface PeriodCell {
+    /** The month's index in its year, or the year. */
+    at: number;
+    /** Whether it is the month or year the calendar shows. */
+    chosen: boolean;
+    /** Whether today falls in it. */
+    current: boolean;
+    /** Its first day. */
+    first: Date;
+    /** Whether it lies wholly outside `min` and `max`. */
+    out: boolean;
+}
+/** What the months or the years view is drawn from. */
+export interface PeriodPage {
+    /** The latest date, or empty. */
+    max: string;
+    /** The earliest date, or empty. */
+    min: string;
+    /** The year the months view is on, or any year on the page of years. */
+    page: number;
+    /** The first of the month the calendar shows. */
+    shown: Date;
+    /** Today, as `YYYY-MM-DD`. */
+    today: string;
+    /** Which view: `month` for the months of a year, `year` for a page of years. */
+    view: 'month' | 'year';
+}
+/**
+ * The twelve cells of the months or the years view, in reading order: the
+ * months of `page`, or the page of years that holds it.
+ */
+export declare const periodCells: ({ max, min, page, shown, today, view }: PeriodPage) => PeriodCell[];
+/**
+ * Where a key takes the tab stop in the months or the years, or `null` for a
+ * key the grid leaves alone.
+ *
+ * `stop` is the month's index or the year the stop is on, `year` the year the
+ * months view shows, and `along` which way the inline keys go, as
+ * `periodMove` takes it. A move off the months of one year lands in the next
+ * or the last, and a move off a page of years turns the page.
+ */
+export declare const periodKey: (view: 'month' | 'year', stop: number, year: number, key: string, along: number) => {
+    focus: number;
+    pageYear: number;
+} | null;

package/dist/utils/calendar/calendar.js

@@ -0,0 +1,96 @@
+import { valueAsDate as asDate, dateAsValue as fromDate } from '../value-as/value-as.js';
+import { writtenList } from '../written-list/written-list.js';
+export const localToday = (now = new Date()) => {
+    const month = `${now.getMonth() + 1}`.padStart(2, '0');
+    const day = `${now.getDate()}`.padStart(2, '0');
+    return `${now.getFullYear()}-${month}-${day}`;
+};
+export 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;
+    }
+};
+export const monthOf = (date) => `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+export const addDays = (date, days) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days));
+export const sameMonth = (left, right) => left.getUTCFullYear() === right.getUTCFullYear() && left.getUTCMonth() === right.getUTCMonth();
+export const addMonths = (date, months) => {
+    const target = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + months, 1));
+    const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth(), Math.min(date.getUTCDate(), last)));
+};
+export const barredBy = (date, rules) => {
+    const iso = fromDate(date);
+    if (writtenList(rules.disableDates).includes(iso) ||
+        writtenList(rules.disableDays).includes(String(date.getUTCDay())) ||
+        rules.isDateUnavailable?.(iso) === true) {
+        return 'listed';
+    }
+    const step = Math.max(1, Math.floor(rules.step) || 1);
+    if (step > 1) {
+        const base = rules.min === '' ? 0 : (asDate(rules.min)?.getTime() ?? 0);
+        if (Math.round((date.getTime() - base) / 86_400_000) % step !== 0) {
+            return 'step';
+        }
+    }
+    return null;
+};
+export const YEARS_SHOWN = 12;
+export const yearPageOf = (year) => Math.floor(year / YEARS_SHOWN) * YEARS_SHOWN;
+export const periodMove = (key, at, along) => {
+    if (along !== 0) {
+        return along;
+    }
+    switch (key) {
+        case 'ArrowUp':
+            return -3;
+        case 'ArrowDown':
+            return 3;
+        case 'Home':
+            return -(at % 3);
+        case 'End':
+            return 2 - (at % 3);
+        case 'PageUp':
+            return -12;
+        case 'PageDown':
+            return 12;
+        default:
+            return null;
+    }
+};
+export const monthOut = (first, min, max) => {
+    const month = monthOf(first);
+    return (min !== '' && month < min.slice(0, 7)) || (max !== '' && month > max.slice(0, 7));
+};
+export const yearOut = (year, min, max) => (min !== '' && year < Number(min.slice(0, 4))) || (max !== '' && year > Number(max.slice(0, 4)));
+export const periodCells = ({ max, min, page, shown, today, view }) => {
+    const years = view === 'year';
+    const start = years ? yearPageOf(page) : page;
+    return Array.from({ length: 12 }, (_, index) => {
+        const at = years ? start + index : index;
+        const first = new Date(Date.UTC(years ? at : start, years ? 0 : index, 1));
+        return {
+            at,
+            chosen: years ? at === shown.getUTCFullYear() : monthOf(first) === monthOf(shown),
+            current: years ? String(at) === today.slice(0, 4) : monthOf(first) === today.slice(0, 7),
+            first,
+            out: years ? yearOut(at, min, max) : monthOut(first, min, max),
+        };
+    });
+};
+export const periodKey = (view, stop, year, key, along) => {
+    const index = view === 'year' ? stop - yearPageOf(stop) : stop;
+    const delta = periodMove(key, index, along);
+    if (delta === null) {
+        return null;
+    }
+    if (view === 'year') {
+        return { focus: stop + delta, pageYear: stop + delta };
+    }
+    const months = year * 12 + stop + delta;
+    return { focus: ((months % 12) + 12) % 12, pageYear: Math.floor(months / 12) };
+};

package/dist/utils/chord/chord.d.ts

@@ -0,0 +1,43 @@
+/** The keys of a chord, in the order written, with spaces and empty entries dropped. */
+export declare const chordParts: (keys: string) => string[];
+/**
+ * A chord as `aria-keyshortcuts` writes it: `mod+k` is `Meta+K` on an Apple
+ * keyboard and `Control+K` elsewhere. A letter is written in capitals and a
+ * symbol as itself. Empty for no keys.
+ */
+export declare const ariaChord: (keys: string, apple: boolean) => string;
+/**
+ * Whether a chord types a character, and so is indistinguishable from typing.
+ *
+ * One code point means a character rather than a name: `/` and `?` are
+ * printable, `escape` and `enter` are not. **Shift is allowed beside it**,
+ * because Shift is how a character is typed: `shift+?` and `shift+a` are a
+ * question mark and a capital A in a field.
+ */
+export declare const printableChord: (keys: string) => boolean;
+/** What a key press carries that a chord is compared against. */
+export interface ChordPress {
+    altKey: boolean;
+    ctrlKey: boolean;
+    key: string;
+    metaKey: boolean;
+    shiftKey: boolean;
+}
+/**
+ * Whether a press is the chord, modifiers and all.
+ *
+ * `mod` is one key, the platform's: Command where `apple` and Control
+ * elsewhere. The other one is then checked like any modifier the chord does
+ * not name, so Control and Command together do not answer `mod+k`. `cmd` and
+ * `meta` are Command, `alt` and `opt` are Option.
+ *
+ * **A symbol is typed with Shift, so Shift says nothing about it.** On a US
+ * layout `?` arrives as `?` with `shiftKey` set, and a chord of `?` that
+ * refused Shift could never be pressed at all. A letter has a shifted form of
+ * its own, so `a` still refuses Shift and `shift+a` still asks for it.
+ *
+ * Every other modifier is checked in both directions, so `mod+k` is not
+ * answered by `shift+mod+k`: a chord a reader did not press is a chord that
+ * should go to whatever did want it.
+ */
+export declare const matchesChord: (press: ChordPress, keys: string, apple: boolean) => boolean;