@fusion.dev/helix-headless 0.0.0-dev

package/dist/data-table/root/order.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Filter, sort, then window. In that order, over the whole set, every time.
+ *
+ * **This is the file that stops the classic virtualization bug.** Sorting the
+ * rendered window looks completely correct on the first screen and is wrong
+ * everywhere else, and it is the natural thing to write once rows are data and
+ * only some of them are drawn. Keeping the three operations here, as functions
+ * over an array with no knowledge of what is on screen, is what makes that
+ * mistake hard to make: nothing in this module can see a window, and `window()`
+ * is the last thing applied rather than the first.
+ *
+ * The order is not a preference. Filtering after sorting sorts rows that are
+ * about to be thrown away, which is only slower; paging before either is the bug.
+ * Filter narrows, sort arranges what is left, the page is a slice of that, and
+ * the count a reader is shown is the length after filtering rather than the
+ * length of the data, or the pagination promises pages that are empty.
+ */
+/**
+ * A row, which is whatever the consumer's data is.
+ *
+ * Not `DataRow`: `@fusion.dev/helix-core` already exports one, for a cell read out of a
+ * chart series, and the headless barrel re-exports both. Two different `DataRow`s
+ * reaching a consumer through one package is the kind of ambiguity TypeScript
+ * refuses outright, which is how this was caught.
+ */
+export type DataRow = Readonly<Record<string, unknown>>;
+/** One column's contribution, reduced to the two functions this module needs. */
+export interface Axis {
+    /** The field this axis is named by, matched against a sort spec. */
+    field: string;
+    /** The value to compare and match on, which is not always what the cell shows. */
+    order: (row: DataRow) => unknown;
+}
+/** A parsed `field:direction`. */
+export interface Sort {
+    direction: 'asc' | 'desc';
+    field: string;
+}
+/**
+ * `field:asc` and `field:desc`, and nothing else.
+ *
+ * A bare `field` parses as ascending, because that is what a URL query usually
+ * carries and refusing it would make the common case the verbose one. Anything
+ * unparseable is no sort rather than an error: this value arrives from a query
+ * string as often as from code, and a bad one should leave the table in the
+ * order the data came in rather than break the page.
+ */
+export declare const parse: (spec: string) => Sort | undefined;
+/** A `Sort` written back out, so the property and the attribute agree. */
+export declare const format: (sort: Sort | undefined) => string;
+/**
+ * What a reader gets on the next click of a sortable heading.
+ *
+ * Ascending, descending, then none. **The third state is not an omission to be
+ * tidied away**: the order rows arrived in is information the data came with,
+ * often the server's own relevance ranking, and a two-state cycle makes it
+ * unreachable once a reader has sorted once.
+ */
+export declare const cycle: (current: Sort | undefined, field: string) => Sort | undefined;
+/**
+ * Rows matching a query, across every axis.
+ *
+ * One query over all columns rather than a predicate per column, which is what a
+ * reader means by a search box above a table. Per-column predicates are a
+ * different feature and compose with this rather than replacing it.
+ *
+ * Case-insensitive and substring, on the ordering value rather than the rendered
+ * one: a cell showing a formatted date should be findable by the text a reader
+ * sees, and a cell showing an icon should be findable by the value behind it.
+ * Where those differ, `compare` on the column is what decides, which is the same
+ * function sorting uses, so search and sort cannot disagree about what a column
+ * holds.
+ */
+export declare const filter: (rows: readonly DataRow[], query: string, axes: readonly Axis[]) => DataRow[];
+/**
+ * Rows in the asked-for order, stably.
+ *
+ * **Stable, and that is load-bearing rather than tidy.** `Array.prototype.sort`
+ * is required to be stable since ES2019, so equal rows keep the order they
+ * arrived in, which means sorting by one column and then another leaves the
+ * first as the tiebreak. A reader who sorts by status and then by name expects
+ * exactly that, and an unstable sort would shuffle equal rows on every
+ * re-render, which reads as the table twitching.
+ */
+export declare const sort: (rows: readonly DataRow[], spec: Sort | undefined, axes: readonly Axis[]) => DataRow[];
+/**
+ * One page of rows, clamped.
+ *
+ * A page past the end returns the last page rather than nothing, because the
+ * usual way to be past the end is a bookmarked link after the result shrank, and
+ * an empty table is a worse answer than the last page of a smaller one. The
+ * same clamp `helix-pagination` already applies to what it reports.
+ */
+export declare const window_: (rows: readonly DataRow[], page: number, size: number) => DataRow[];
+/** What one pass over the data produces: the window, and the counts around it. */
+export interface Ordered {
+    /** Rows after filtering, before paging. The number a pagination must page. */
+    matched: number;
+    /** The rows to draw. */
+    rows: DataRow[];
+    /** Rows before filtering, which is what tells a reader a filter is on. */
+    total: number;
+}
+/**
+ * The whole pass, in the one order that is correct.
+ *
+ * Exported as a single function so a caller cannot get the order wrong by
+ * calling the three in the sequence that reads naturally, which is the sequence
+ * that pages before it sorts.
+ */
+export declare const ordered: (rows: readonly DataRow[], axes: readonly Axis[], { page, query, size, spec }: {
+    page: number;
+    query: string;
+    size: number;
+    spec: string;
+}) => Ordered;

package/dist/data-table/root/order.js

@@ -0,0 +1,175 @@
+/**
+ * Filter, sort, then window. In that order, over the whole set, every time.
+ *
+ * **This is the file that stops the classic virtualization bug.** Sorting the
+ * rendered window looks completely correct on the first screen and is wrong
+ * everywhere else, and it is the natural thing to write once rows are data and
+ * only some of them are drawn. Keeping the three operations here, as functions
+ * over an array with no knowledge of what is on screen, is what makes that
+ * mistake hard to make: nothing in this module can see a window, and `window()`
+ * is the last thing applied rather than the first.
+ *
+ * The order is not a preference. Filtering after sorting sorts rows that are
+ * about to be thrown away, which is only slower; paging before either is the bug.
+ * Filter narrows, sort arranges what is left, the page is a slice of that, and
+ * the count a reader is shown is the length after filtering rather than the
+ * length of the data, or the pagination promises pages that are empty.
+ */
+/**
+ * `field:asc` and `field:desc`, and nothing else.
+ *
+ * A bare `field` parses as ascending, because that is what a URL query usually
+ * carries and refusing it would make the common case the verbose one. Anything
+ * unparseable is no sort rather than an error: this value arrives from a query
+ * string as often as from code, and a bad one should leave the table in the
+ * order the data came in rather than break the page.
+ */
+export const parse = (spec) => {
+    const trimmed = spec.trim();
+    if (trimmed === '') {
+        return undefined;
+    }
+    const [field = '', direction = 'asc'] = trimmed.split(':');
+    if (field === '' || (direction !== 'asc' && direction !== 'desc')) {
+        return undefined;
+    }
+    return { direction, field };
+};
+/** A `Sort` written back out, so the property and the attribute agree. */
+export const format = (sort) => sort ? `${sort.field}:${sort.direction}` : '';
+/**
+ * What a reader gets on the next click of a sortable heading.
+ *
+ * Ascending, descending, then none. **The third state is not an omission to be
+ * tidied away**: the order rows arrived in is information the data came with,
+ * often the server's own relevance ranking, and a two-state cycle makes it
+ * unreachable once a reader has sorted once.
+ */
+export const cycle = (current, field) => {
+    if (current?.field !== field) {
+        return { direction: 'asc', field };
+    }
+    return current.direction === 'asc' ? { direction: 'desc', field } : undefined;
+};
+/**
+ * Rows matching a query, across every axis.
+ *
+ * One query over all columns rather than a predicate per column, which is what a
+ * reader means by a search box above a table. Per-column predicates are a
+ * different feature and compose with this rather than replacing it.
+ *
+ * Case-insensitive and substring, on the ordering value rather than the rendered
+ * one: a cell showing a formatted date should be findable by the text a reader
+ * sees, and a cell showing an icon should be findable by the value behind it.
+ * Where those differ, `compare` on the column is what decides, which is the same
+ * function sorting uses, so search and sort cannot disagree about what a column
+ * holds.
+ */
+export const filter = (rows, query, axes) => {
+    const needle = query.trim().toLocaleLowerCase();
+    if (needle === '') {
+        return [...rows];
+    }
+    return rows.filter((row) => axes.some((axis) => text(axis.order(row)).toLocaleLowerCase().includes(needle)));
+};
+/**
+ * Rows in the asked-for order, stably.
+ *
+ * **Stable, and that is load-bearing rather than tidy.** `Array.prototype.sort`
+ * is required to be stable since ES2019, so equal rows keep the order they
+ * arrived in, which means sorting by one column and then another leaves the
+ * first as the tiebreak. A reader who sorts by status and then by name expects
+ * exactly that, and an unstable sort would shuffle equal rows on every
+ * re-render, which reads as the table twitching.
+ */
+export const sort = (rows, spec, axes) => {
+    const axis = spec ? axes.find((one) => one.field === spec.field) : undefined;
+    if (!spec || !axis) {
+        return [...rows];
+    }
+    const sign = spec.direction === 'asc' ? 1 : -1;
+    return [...rows].sort((left, right) => compare(axis.order(left), axis.order(right), sign));
+};
+/**
+ * One page of rows, clamped.
+ *
+ * A page past the end returns the last page rather than nothing, because the
+ * usual way to be past the end is a bookmarked link after the result shrank, and
+ * an empty table is a worse answer than the last page of a smaller one. The
+ * same clamp `helix-pagination` already applies to what it reports.
+ */
+export const window_ = (rows, page, size) => {
+    if (size <= 0) {
+        return [...rows];
+    }
+    const pages = Math.max(1, Math.ceil(rows.length / size));
+    const wanted = Math.min(pages, Math.max(1, Math.floor(page) || 1));
+    const from = (wanted - 1) * size;
+    return rows.slice(from, from + size);
+};
+/**
+ * A value as text, for matching.
+ *
+ * `null` and `undefined` become empty rather than their own names, so a search
+ * for "null" does not match every hole in the data.
+ */
+const text = (value) => {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return String(value);
+};
+/**
+ * Two cell values ordered, with the types a table actually holds.
+ *
+ * **Numbers compare as numbers and strings collate.** `String(a) < String(b)`
+ * puts 10 before 9 and puts every accented word after every unaccented one, and
+ * both look like the sort is broken while every value in the column is correct.
+ * `localeCompare` handles the second, and the numeric branch handles the first.
+ *
+ * **Holes sort last in both directions**, which is deliberate and is the one
+ * choice here a reader could disagree with. A missing value is not smaller than
+ * a present one, it is absent, and burying the holes at the end is what a reader
+ * scanning for the largest or smallest actual value wants. Reversing them with
+ * the direction puts every hole first on a descending sort, which is the least
+ * useful screen the data can produce.
+ *
+ * **`sign` is applied in here rather than to the result**, and that is why it is
+ * a parameter rather than the caller's multiplication. Written the obvious way,
+ * as `sign * compare(a, b)`, the constant this returns for a hole flips with the
+ * direction and the holes lead a descending sort: the comment above it claimed
+ * otherwise for as long as it took the spec to be written, which is the argument
+ * for writing the spec.
+ */
+const compare = (left, right, sign) => {
+    const leftMissing = left === null || left === undefined || left === '';
+    const rightMissing = right === null || right === undefined || right === '';
+    if (leftMissing || rightMissing) {
+        return leftMissing && rightMissing ? 0 : leftMissing ? 1 : -1;
+    }
+    if (typeof left === 'number' && typeof right === 'number') {
+        return sign * (left - right);
+    }
+    if (typeof left === 'boolean' && typeof right === 'boolean') {
+        return sign * (Number(left) - Number(right));
+    }
+    if (left instanceof Date && right instanceof Date) {
+        return sign * (left.getTime() - right.getTime());
+    }
+    return (sign * text(left).localeCompare(text(right), undefined, { numeric: true, sensitivity: 'base' }));
+};
+/**
+ * The whole pass, in the one order that is correct.
+ *
+ * Exported as a single function so a caller cannot get the order wrong by
+ * calling the three in the sequence that reads naturally, which is the sequence
+ * that pages before it sorts.
+ */
+export const ordered = (rows, axes, { page, query, size, spec }) => {
+    const matched = filter(rows, query, axes);
+    const arranged = sort(matched, parse(spec), axes);
+    return { matched: matched.length, rows: window_(arranged, page, size), total: rows.length };
+};

package/dist/date-input/index.d.ts

@@ -0,0 +1 @@
+export * from './root/date-input-root.js';

package/dist/date-input/index.js

@@ -0,0 +1 @@
+export * from './root/date-input-root.js';

package/dist/date-input/root/date-input-root.d.ts

@@ -0,0 +1,361 @@
+import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../date-picker/index.js';
+import '../../tag/index.js';
+declare const HelixHeadlessDateInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A date, typed or picked from a calendar.
+ *
+ * @description
+ * **The calendar is `helix-date-picker`, not a second one written here.** It
+ * already knows about months, ranges, disabled days, the first day of the week
+ * and every keyboard rule a grid owes a reader, and a picker that reimplemented
+ * a tenth of that would be a worse grid that also had to be maintained. This
+ * element is the field, the overlay, and the translation between them.
+ *
+ * **Typed as well as picked, and the typing is the reason it is not
+ * `<input type="date">`.** The native control gives a free picker and a free
+ * locale and takes almost all styling with it, which is a fair trade until a
+ * product needs the calendar to match everything around it. What is kept from
+ * the native one is the part worth keeping: a real text field, so a reader who
+ * knows the date types it and never opens anything.
+ *
+ * **The value is `YYYY-MM-DD`, always.** That is what a form submits, what
+ * `min` and `max` compare against, and what the calendar speaks. What the field
+ * *shows* is the same string: a locale-formatted display would have to be parsed
+ * back on every keystroke, and half-typed input does not survive a round trip
+ * through a formatter. The same reasoning the sandbox records for its two
+ * syntaxes, which is that a document being edited must not be a rendering of
+ * something else.
+ *
+ * **Opening does not commit.** The calendar announces a date, this element takes
+ * it, and the overlay shuts, because a single date has nothing more to say. A
+ * consumer who owns `value` answers the announcement the way they answer any
+ * other control here.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases DatePicker, DateField, InputDate
+ * @documentation https://helix.fusion.dev/components/date-input
+ *
+ * @slot feedback - What is wrong with it.
+ * @slot hint - Help under the field.
+ * @slot trigger - The mark on the field saying a calendar opens.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the date changes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the calendar opens. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} input - Announced once the value has moved.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart control - The text input.
+ * @csspart date - One held date, as a tag, in `multiple`.
+ * @csspart date-dismiss - The remove button, when `dismissible`.
+ * @csspart date-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart date-prefix - The category before the label.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The box holding the text and the trigger.
+ * @csspart hint - Help under the field, while nothing is wrong.
+ * @csspart label - The question, over the field.
+ * @csspart picker - The date picker inside it.
+ * @csspart picker-cell - One column of a row, which is what a range paints.
+ * @csspart picker-day - The shape inside a cell, which is what a single date paints.
+ * @csspart picker-grid - The grid of days.
+ * @csspart picker-header - The month name and its controls.
+ * @csspart picker-heading - The month and year being shown.
+ * @csspart picker-month - One month, its header and its grid.
+ * @csspart picker-months - The run of months.
+ * @csspart picker-next - The control that moves to the next month.
+ * @csspart picker-next-mark - The glyph on the next month control.
+ * @csspart picker-previous - The control that moves to the previous month.
+ * @csspart picker-previous-mark - The glyph on the previous month control.
+ * @csspart picker-week - One row of days.
+ * @csspart picker-weekday - A column header naming a day of the week.
+ * @csspart rest - How many dates are held beyond the ones shown.
+ * @csspart surface - The floating panel.
+ * @csspart trigger - The control that opens the calendar.
+ * @csspart trigger-icon - The mark on the button that opens the calendar.
+ */
+export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base {
+    protected readonly aria: AriaForwardController;
+    /**
+     * What the browser may autofill here, as one of the platform's own tokens.
+     *
+     * Empty leaves the attribute off, which is the browser's default and is what
+     * lets autofill work at all. This used to be hardcoded `off`, so a reader
+     * could never have a birthday or a postal code filled in for them and a
+     * consumer had no way to ask for it. See 295.
+     */
+    autocomplete: string;
+    /**
+     * How many dates can be held at once.
+     *
+     * Absent is one. `range` holds a start and an end, `multiple` holds any
+     * number, and both are carried as one comma-separated value: a form field
+     * submits a string, and two fields for one question is a different control.
+     */
+    mode?: 'range' | 'multiple';
+    /**
+     * How many months the calendar shows, side by side.
+     *
+     * Worth more than one mainly for a range, where picking a start in March and
+     * an end in April otherwise means paging between them and losing sight of the
+     * first. The panel is sized by its content, so this widens it.
+     */
+    months: number;
+    /**
+     * How many dates are shown as tags before the rest are counted, in `multiple`.
+     *
+     * `0` is all of them, and is the default: a cap that guesses is worse than no
+     * cap, because the number that fits depends on the width of the field and the
+     * length of what is in it, neither of which this element knows. What a cap is
+     * genuinely for is a field in a row or a table cell, where a set of twelve
+     * dates would push everything below it down a line at a time.
+     *
+     * The remainder is counted rather than hidden. "3 more" is a fact a reader can
+     * act on, where a row that silently stops is a field that appears to have lost
+     * what was put in it, and the count is what tells them there is more to see.
+     */
+    maxTags: number;
+    /**
+     * Earliest date that can be chosen, as `YYYY-MM-DD`.
+     */
+    min: string;
+    /**
+     * How far apart the selectable dates are, in days.
+     *
+     * `<input type="date" step>`'s own unit, handed to the calendar this renders
+     * so the field and the grid agree about which dates exist. Counted from `min`
+     * where there is one and from 1 January 1970 where there is not, which is the
+     * platform's base.
+     */
+    step: number;
+    /**
+     * Latest date that can be chosen, as `YYYY-MM-DD`.
+     */
+    max: string;
+    /**
+     * Dates that cannot be chosen, as a comma-separated `YYYY-MM-DD` list.
+     */
+    disableDates: string;
+    /**
+     * Days of the week that cannot be chosen, `0` for Sunday through `6`.
+     */
+    disableDays: string;
+    /**
+     * First column of the week in the calendar, `0` for Sunday through `6`.
+     */
+    firstDayOfWeek: number;
+    /**
+     * How a date is written in the field: `short` through `full`, or ISO.
+     *
+     * **The field renders when it is idle and holds the value when it is being
+     * edited.** A written date is a rendering, and a document being edited must
+     * not be a rendering of something else: `Intl.DateTimeFormat` formats and does
+     * not parse, so `4 August 2026` cannot be typed back, and writing a parser per
+     * locale is how a field ends up rejecting what it just displayed.
+     *
+     * The way out is not to choose between the two but to separate them in time.
+     * Idle, the field shows `4 August 2026`, which is what a date is for reading.
+     * Focused, it shows `2026-08-04`, which is what a date is for typing, and it
+     * goes back on the way out. Nothing parses a rendering, and nothing is
+     * read-only, which is what an earlier version of this settled for.
+     *
+     * A range is the exception that needs no swap: the dash between its two dates
+     * is a separator this element understands, so that much reads back either way.
+     *
+     * `iso` turns the rendering off, for a field whose reader is entering data
+     * rather than reading it, or where the ISO form is itself the point.
+     *
+     * The value is always `YYYY-MM-DD` regardless, because that is what a form
+     * submits and what `min` and `max` compare against.
+     */
+    dateStyle: 'full' | 'iso' | 'long' | 'medium' | 'short';
+    /**
+     * Language tag the calendar names its months and days in.
+     */
+    locale: string;
+    /**
+     * What the field says before a date is in it.
+     */
+    placeholder: string;
+    /**
+     * Accessible name for the control that opens the calendar.
+     */
+    triggerLabel: string;
+    /**
+     * The overlay, placed against the field rather than the trigger.
+     *
+     * Against the field because that is the box a reader sees as the control: a
+     * calendar hung off a small button at one end of a wide field reads as
+     * belonging to the button. `Select` anchors to its trigger for the opposite
+     * reason, its trigger being the whole control.
+     */
+    protected readonly panel: PopoverController;
+    private get control();
+    /**
+     * What the calendar should show, which is only ever a whole date.
+     *
+     * Half-typed input reaches here on every keystroke, and `2026-08-1` is not a
+     * date: handing it to the calendar would move the month under a reader
+     * mid-word. So the grid follows the field only once the field says something
+     * complete.
+     */
+    private get picked();
+    /** One date, written the way `dateStyle` asks for. */
+    private written;
+    private get display();
+    /**
+     * Whether the caret is in the field, which is when it holds the value.
+     */
+    private editing;
+    /**
+     * What is being typed but not yet held, for `multiple` only.
+     *
+     * The other modes type into the value directly, because one date and a range
+     * are both a whole answer at the moment they are complete. A multiple is not:
+     * it is a set being added to, so the field needs somewhere to hold a date
+     * before it joins the set and somewhere to leave a half-typed one that is not
+     * a date yet.
+     */
+    private draft;
+    /** Relayed under this element's name, so a consumer hears one control. */
+    private readonly handleInput;
+    /** Adds what was typed to the set, or takes the last one back out. */
+    private readonly handleDraftKey;
+    /** The dates that get a tag, which is all of them until `maxTags` says not. */
+    private get shownDates();
+    /** How many are held beyond the ones shown. */
+    private get restCount();
+    /** Takes one date back out of the set. */
+    private readonly removeDate;
+    private readonly handleCalendarChange;
+    /**
+     * Puts the field back where the answer differs from what was typed.
+     *
+     * `requestValue` is the mixin's, and it announces and decides; this is the
+     * other half, which `Input` needs for the same reason: the native control has
+     * already changed, so wherever the answer does not follow it, it has to be
+     * restored. A refusal and a consumer who owns `value` and has not given a new
+     * one are the same thing from here.
+     */
+    private restore;
+    /** Reports the value and the validity the host stands behind. */
+    private sync;
+    /** Escape shuts the calendar without moving the date. */
+    private readonly handleKeydown;
+    /**
+     * Whether the control refuses changes while still submitting its value.
+     *
+     * **Enforced by refusing every request in one place**, which is the seam this
+     * component already has: `requestValue` is what every path here comes through,
+     * and gating it once is what stops the next call site from being written
+     * without the check.
+     *
+     * Not `disabled`, which is the confusion worth naming: a disabled control
+     * submits nothing and leaves the tab order, and a read-only one submits its
+     * value and stays reachable, which is what a form showing a value somebody
+     * else set needs.
+     */
+    readOnly: boolean;
+    /** Refuses every change while read-only. See `readOnly`. */
+    requestValue(next: string): boolean;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Puts the caret back in the field without the field reopening the calendar.
+     *
+     * Focus opens the calendar, so handing focus back after a pick reopens the
+     * thing that was just answered. `relatedTarget` was the guard and it is not
+     * enough on its own: it catches a hand-off from the trigger, and it does not
+     * catch this, because the cell that had focus is gone by the time the caret
+     * moves and the document has fallen back to something outside this element.
+     *
+     * **Reasoned rather than measured, and worth saying which.** In a focused
+     * document: the reader presses a day, the cell has focus, the panel is hidden,
+     * the browser moves focus off the removed cell to the body, and the caret is
+     * then put back here with `relatedTarget` pointing at the body, which is
+     * outside this element and reads as an arrival. Every step is ordinary browser
+     * behavior and none of it can be exercised here: `focus()` dispatches no
+     * event in an unfocused document, which is what both the test runtime and the
+     * available browser pane are. A spec was written for it and passed with the
+     * guard removed, so it was covering nothing and has been taken out rather than
+     * left to look like proof.
+     *
+     * A flag rather than a better guess, because this element is the one moving
+     * the focus and is the only thing that can know so. Cleared synchronously,
+     * since `focus()` dispatches before it returns.
+     */
+    private returning;
+    private returnFocus;
+    private readonly handleBlur;
+    private readonly handleFocus;
+    /** Puts the caret in the field, the way a label pointing at one would. */
+    focus(options?: FocusOptions): void;
+    /**
+     * The calendar the field opens, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    protected renderPicker(): TemplateResult;
+    /**
+     * One chosen date, as a tag, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    protected renderTag(date: string): TemplateResult;
+    /**
+     * The mark on the button that opens the calendar, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding.
+     *
+     * **A named import rather than `<helix-icon>`, and that is a reversal.** The
+     * element looked like the tidier of the two and loses on three counts.
+     * `helix-icon` indexes the whole icon map at runtime, `icons[this.name]`, and
+     * no bundler can shake a runtime lookup, so every consumer of any component
+     * that renders one ships all 50kB of path data; a named import ships one
+     * path. The import is checked when the package compiles, where a `name`
+     * string is checked only when `check:icons` runs. And `helix-icon` is not
+     * registered on the headless tier at all, which registers `helix-headless-icon`,
+     * so a headless consumer got an inert unknown element and no mark whatsoever.
+     */
+    protected renderTrigger(): TemplateResult;
+    protected render(): TemplateResult;
+    /**
+     * The value as a `Date`, at midnight UTC, or `null` while there is no date.
+     *
+     * The platform's own pair on `<input type="date">`, and this control holds the
+     * same `YYYY-MM-DD` string, so a consumer moving from one to the other reads
+     * the same two properties. UTC because the platform chose UTC: a date that is
+     * the same date everywhere must not become a different one by crossing a
+     * timezone, and midnight local would do exactly that for anybody west of
+     * Greenwich.
+     *
+     * `null` while the value is half typed, which is most of the keystrokes a
+     * reader makes in one of these.
+     */
+    get valueAsDate(): Date | null;
+    set valueAsDate(date: Date | null);
+    /** The value as milliseconds since the epoch, or `NaN` while there is no date. */
+    get valueAsNumber(): number;
+    set valueAsNumber(ms: number);
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-date-input': HelixHeadlessDateInput;
+    }
+}
+export {};