@fusion.dev/helix-core 0.0.0-dev

package/dist/helix-form-element/helix-form-element.d.ts

@@ -0,0 +1,152 @@
+import type { PropertyValues } from 'lit';
+import { HelixElement } from '../helix-element/helix-element.js';
+/**
+ * @summary Base for every element that participates in a form.
+ *
+ * @description
+ * This has to be a class rather than a mixin or controller, and that is not a
+ * style preference: the browser reads `formAssociated` off the constructor
+ * during element upgrade, which cannot be delegated to a composed object.
+ *
+ * `internals` comes from `HelixElement`, which attaches it for every component.
+ * `attachInternals()` throws on a second call, so there is exactly one owner.
+ *
+ * Deliberately small. It carries what every form participant needs and nothing
+ * more; `value`, validity, and the reset and restore callbacks land when the
+ * first input does, rather than being designed against components that do not
+ * exist yet.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @documentation https://helix.fusion.dev/core/form-element
+ */
+export declare class HelixFormElement extends HelixElement {
+    /** Opts the element into form ownership, labels, and submission. */
+    static readonly formAssociated = true;
+    /**
+     * Whether the control is non-interactive.
+     *
+     * Reflected, because the styled tier selects on it, and mirrored to
+     * `aria-disabled` rather than removing the element from the accessibility
+     * tree, so a screen reader can still announce that the control exists.
+     *
+     * The mirror is below and was for a while only a sentence: this paragraph
+     * described it, four components had their own copies of it, and the class
+     * itself did nothing. Here is where it belongs, because here is where
+     * `disabled` is.
+     */
+    disabled: boolean;
+    /**
+     * Whether an ancestor `<fieldset disabled>` has switched this control off.
+     *
+     * The platform tells a form-associated element through `formDisabledCallback`
+     * and nothing here implemented it, so a control inside a disabled fieldset
+     * stayed fully typeable and announced itself as enabled. Measured: a
+     * `helix-input` in one accepted text, reported `disabled` as false, and
+     * carried no `aria-disabled`.
+     *
+     * What the platform already did on its own is the submission half. The same
+     * measurement showed the fieldset's controls absent from the form's entry
+     * list and the host matching `:disabled`, so the value never went anywhere.
+     * What was missing is everything a reader can see or touch.
+     *
+     * State rather than the `disabled` property. Writing that would reflect an
+     * attribute the consumer's server markup does not have, which React reports
+     * on hydration and does not patch up, and it would also silently overwrite
+     * what the consumer set.
+     */
+    protected formDisabled: boolean;
+    /**
+     * Whether the control is off, by its own attribute or by an ancestor.
+     *
+     * What a component should bind to rather than `disabled`, which is only the
+     * half of it the consumer wrote.
+     *
+     * @internal Read by the component itself and by nothing outside it: every
+     * call in the library is `this.isDisabled`. Public, it printed a row on
+     * twenty-four families in both tiers, forty-eight in all, on every form
+     * control's reference page, and it is the largest single entry in those
+     * tables.
+     *
+     * **A consumer loses nothing, which was measured rather than assumed.**
+     * `element.matches(':disabled')` answers the same question, is the platform's
+     * own, and works on a native control too. Checked in a browser across the
+     * three cases: a control disabled by its own attribute, one inside a
+     * `<fieldset>` before and after that fieldset is disabled, and one that is
+     * neither. `:disabled` agreed with `isDisabled` in every one, including the
+     * inheritance case that is the only reason this getter exists.
+     *
+     * Documented away rather than made `protected`, because a subclass in
+     * `helix/styled` binds to it and that is exactly what it is for.
+     */
+    get isDisabled(): boolean;
+    /**
+     * The platform's notice that an ancestor fieldset changed.
+     *
+     * **The argument is the effective state, and taking it whole is what latched
+     * every control in the library.** The platform calls this for the element's
+     * own `disabled` as well as for a fieldset, and our own arrives here at the
+     * worst possible moment: reflecting `disabled` to the attribute happens
+     * inside Lit's `update()`, the UA fires this synchronously from that write,
+     * and a reactive write during an update is a change-in-update Lit does not
+     * re-render for. So `formDisabled` ran exactly one update behind forever.
+     *
+     * Measured on Slider, logging what `render` saw:
+     *
+     * ```
+     * set true    disabled true   formDisabled false  isDisabled true
+     * set false   disabled false  formDisabled true   isDisabled true   <- stale
+     * (no third render)
+     * ```
+     *
+     * The host came out right every time, `disabled` false, `:disabled` not
+     * matching, and the inner control kept the attribute, so a control disabled
+     * once could never be re-enabled. It only shows when something re-enables,
+     * which is the same shape of bug `inheritDisabled` was written for.
+     *
+     * Our own half is already in `this.disabled` and `isDisabled` is an or, so
+     * this records only what the fieldset adds. That also removes the write
+     * entirely on the own-disabled path rather than moving it.
+     *
+     * The one case this cannot see is a control that is disabled itself *and*
+     * inside a disabled fieldset, whose own `disabled` is then removed: the
+     * effective state does not change, so the platform does not call again, and
+     * the fieldset's hold is not recorded. There is no callback to learn it from
+     * and reading `:disabled` here would answer about the attribute we are in the
+     * middle of removing.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Name submitted with the form.
+     *
+     * **Reflected, and it is the exception to "reflect only what CSS selects
+     * on".** The platform builds a form's entry list from the `name` *content
+     * attribute*, not from the property, so a control named through the property
+     * submitted under no name at all and was silently dropped. Measured: two
+     * inputs in one form, one named by attribute and one by property, and the
+     * form carried a single entry.
+     *
+     * Safe for a React consumer, which is what the rule is protecting: React
+     * renders a custom element's props as attributes on the server, so the name
+     * is already in the markup being hydrated and reflecting it writes what is
+     * there. It is only a change to the markup when a consumer assigns it
+     * imperatively later, and nothing is hydrating by then.
+     *
+     * Here rather than on each control, where it was declared eight times and
+     * reflected none of them.
+     */
+    name: string;
+    /**
+     * The form this control belongs to, if any.
+     *
+     * @reference https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements form-associated custom elements
+     */
+    get form(): HTMLFormElement | null;
+    /**
+     * Labels associated with this control.
+     *
+     * @reference https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements form-associated custom elements
+     */
+    get labels(): NodeList;
+}

package/dist/helix-form-element/helix-form-element.js

@@ -0,0 +1,194 @@
+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 { property, state } from 'lit/decorators.js';
+import { HelixElement } from '../helix-element/helix-element.js';
+/**
+ * @summary Base for every element that participates in a form.
+ *
+ * @description
+ * This has to be a class rather than a mixin or controller, and that is not a
+ * style preference: the browser reads `formAssociated` off the constructor
+ * during element upgrade, which cannot be delegated to a composed object.
+ *
+ * `internals` comes from `HelixElement`, which attaches it for every component.
+ * `attachInternals()` throws on a second call, so there is exactly one owner.
+ *
+ * Deliberately small. It carries what every form participant needs and nothing
+ * more; `value`, validity, and the reset and restore callbacks land when the
+ * first input does, rather than being designed against components that do not
+ * exist yet.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @documentation https://helix.fusion.dev/core/form-element
+ */
+export class HelixFormElement extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether the control is non-interactive.
+         *
+         * Reflected, because the styled tier selects on it, and mirrored to
+         * `aria-disabled` rather than removing the element from the accessibility
+         * tree, so a screen reader can still announce that the control exists.
+         *
+         * The mirror is below and was for a while only a sentence: this paragraph
+         * described it, four components had their own copies of it, and the class
+         * itself did nothing. Here is where it belongs, because here is where
+         * `disabled` is.
+         */
+        this.disabled = false;
+        /**
+         * Whether an ancestor `<fieldset disabled>` has switched this control off.
+         *
+         * The platform tells a form-associated element through `formDisabledCallback`
+         * and nothing here implemented it, so a control inside a disabled fieldset
+         * stayed fully typeable and announced itself as enabled. Measured: a
+         * `helix-input` in one accepted text, reported `disabled` as false, and
+         * carried no `aria-disabled`.
+         *
+         * What the platform already did on its own is the submission half. The same
+         * measurement showed the fieldset's controls absent from the form's entry
+         * list and the host matching `:disabled`, so the value never went anywhere.
+         * What was missing is everything a reader can see or touch.
+         *
+         * State rather than the `disabled` property. Writing that would reflect an
+         * attribute the consumer's server markup does not have, which React reports
+         * on hydration and does not patch up, and it would also silently overwrite
+         * what the consumer set.
+         */
+        this.formDisabled = false;
+        /**
+         * Name submitted with the form.
+         *
+         * **Reflected, and it is the exception to "reflect only what CSS selects
+         * on".** The platform builds a form's entry list from the `name` *content
+         * attribute*, not from the property, so a control named through the property
+         * submitted under no name at all and was silently dropped. Measured: two
+         * inputs in one form, one named by attribute and one by property, and the
+         * form carried a single entry.
+         *
+         * Safe for a React consumer, which is what the rule is protecting: React
+         * renders a custom element's props as attributes on the server, so the name
+         * is already in the markup being hydrated and reflecting it writes what is
+         * there. It is only a change to the markup when a consumer assigns it
+         * imperatively later, and nothing is hydrating by then.
+         *
+         * Here rather than on each control, where it was declared eight times and
+         * reflected none of them.
+         */
+        this.name = '';
+    }
+    /** Opts the element into form ownership, labels, and submission. */
+    static { this.formAssociated = true; }
+    /**
+     * Whether the control is off, by its own attribute or by an ancestor.
+     *
+     * What a component should bind to rather than `disabled`, which is only the
+     * half of it the consumer wrote.
+     *
+     * @internal Read by the component itself and by nothing outside it: every
+     * call in the library is `this.isDisabled`. Public, it printed a row on
+     * twenty-four families in both tiers, forty-eight in all, on every form
+     * control's reference page, and it is the largest single entry in those
+     * tables.
+     *
+     * **A consumer loses nothing, which was measured rather than assumed.**
+     * `element.matches(':disabled')` answers the same question, is the platform's
+     * own, and works on a native control too. Checked in a browser across the
+     * three cases: a control disabled by its own attribute, one inside a
+     * `<fieldset>` before and after that fieldset is disabled, and one that is
+     * neither. `:disabled` agreed with `isDisabled` in every one, including the
+     * inheritance case that is the only reason this getter exists.
+     *
+     * Documented away rather than made `protected`, because a subclass in
+     * `helix/styled` binds to it and that is exactly what it is for.
+     */
+    get isDisabled() {
+        return this.disabled || this.formDisabled;
+    }
+    /**
+     * The platform's notice that an ancestor fieldset changed.
+     *
+     * **The argument is the effective state, and taking it whole is what latched
+     * every control in the library.** The platform calls this for the element's
+     * own `disabled` as well as for a fieldset, and our own arrives here at the
+     * worst possible moment: reflecting `disabled` to the attribute happens
+     * inside Lit's `update()`, the UA fires this synchronously from that write,
+     * and a reactive write during an update is a change-in-update Lit does not
+     * re-render for. So `formDisabled` ran exactly one update behind forever.
+     *
+     * Measured on Slider, logging what `render` saw:
+     *
+     * ```
+     * set true    disabled true   formDisabled false  isDisabled true
+     * set false   disabled false  formDisabled true   isDisabled true   <- stale
+     * (no third render)
+     * ```
+     *
+     * The host came out right every time, `disabled` false, `:disabled` not
+     * matching, and the inner control kept the attribute, so a control disabled
+     * once could never be re-enabled. It only shows when something re-enables,
+     * which is the same shape of bug `inheritDisabled` was written for.
+     *
+     * Our own half is already in `this.disabled` and `isDisabled` is an or, so
+     * this records only what the fieldset adds. That also removes the write
+     * entirely on the own-disabled path rather than moving it.
+     *
+     * The one case this cannot see is a control that is disabled itself *and*
+     * inside a disabled fieldset, whose own `disabled` is then removed: the
+     * effective state does not change, so the platform does not call again, and
+     * the fieldset's hold is not recorded. There is no callback to learn it from
+     * and reading `:disabled` here would answer about the attribute we are in the
+     * middle of removing.
+     */
+    formDisabledCallback(disabled) {
+        this.formDisabled = disabled && !this.disabled;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // Off for either reason, and said once for every control in the library.
+        this.internals.ariaDisabled = this.isDisabled ? 'true' : null;
+    }
+    /**
+     * The form this control belongs to, if any.
+     *
+     * @reference https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements form-associated custom elements
+     */
+    get form() {
+        return this.internals.form;
+    }
+    /**
+     * Labels associated with this control.
+     *
+     * @reference https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements form-associated custom elements
+     */
+    get labels() {
+        return this.internals.labels;
+    }
+}
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixFormElement.prototype, "disabled", void 0);
+__decorate([
+    state()
+], HelixFormElement.prototype, "formDisabled", void 0);
+__decorate([
+    property({
+        /* Empty means absent, which plain reflection cannot say. `name = ''` is the
+           default and Lit reflects it as `name=""`, so every button, switch and
+           calendar in the library shipped an empty name attribute the consumer
+           never wrote, and six SSR specs said so. Returning `null` removes the
+           attribute instead. Same trap `hostAria` exists for: a name of no
+           characters is not the absence of one. */
+        converter: {
+            fromAttribute: (value) => value ?? '',
+            toAttribute: (value) => (value === '' ? null : value),
+        },
+        reflect: true,
+    })
+], HelixFormElement.prototype, "name", void 0);

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+export { AriaForwardController, type AriaForwardOptions, } from './controllers/aria-forward-controller/aria-forward-controller.js';
+export { ChartPointerController, type ChartPointerHost, } from './controllers/chart-pointer-controller/chart-pointer-controller.js';
+export { CommandController, type CommandOptions, HelixFallbackCommandEvent, supportsInvokers, } from './controllers/command-controller/command-controller.js';
+export { CopyController, type CopyOptions, } from './controllers/copy-controller/copy-controller.js';
+export { DisabledCascadeController, type DisabledCascadeOptions, } from './controllers/disabled-cascade-controller/disabled-cascade-controller.js';
+export { DismissController, type DismissOptions, } from './controllers/dismiss-controller/dismiss-controller.js';
+export { DrilldownController, type DrilldownOptions, } from './controllers/drilldown-controller/drilldown-controller.js';
+export { FloatingController, type FloatingOptions, type Placement, } from './controllers/floating-controller/floating-controller.js';
+export { FocusTrapController } from './controllers/focus-trap-controller/focus-trap-controller.js';
+export { IndicatorController, type IndicatorOptions, } from './controllers/indicator-controller/indicator-controller.js';
+export { KeyboardNavigationController, type KeyboardNavigationOptions, type NavigableItem, } from './controllers/keyboard-navigation-controller/keyboard-navigation-controller.js';
+export { PopoverController, type PopoverOptions, } from './controllers/popover-controller/popover-controller.js';
+export { SourceController, type SourceHost, } from './controllers/source-controller/source-controller.js';
+export { type TokenColor, TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
+export { VirtualizeController, type VirtualizeOptions, type Window as VirtualizeWindow, } from './controllers/virtualize-controller/virtualize-controller.js';
+export { eventsForTag, registerElementEvents } from './events/element-events.js';
+export { type CaretDetail, type ChangeDetail, type CompleteDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFilterEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type NavigateDetail, type OpenDetail, type ReadDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type ToggleDetail, } from './events/events.js';
+export { HelixElement } from './helix-element/helix-element.js';
+export { HelixFormElement } from './helix-form-element/helix-form-element.js';
+export { MixinChartSource, type MixinChartSourceInterface, PALETTE, seriesIndex, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { type CollectionElement, MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
+export { MixinControllerActive, type MixinControllerActiveInterface, } from './mixins/mixin-controller-active/mixin-controller-active.js';
+export { MixinControllerChecked, type MixinControllerCheckedInterface, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';
+export { MixinControllerOpen, type MixinControllerOpenInterface, } from './mixins/mixin-controller-open/mixin-controller-open.js';
+export { MixinControllerValue, type MixinControllerValueInterface, } from './mixins/mixin-controller-value/mixin-controller-value.js';
+export { type DismissibleElement, MixinDismissible, } from './mixins/mixin-dismissible/mixin-dismissible.js';
+export { MixinField, type MixinFieldInterface } from './mixins/mixin-field/mixin-field.js';
+export { anchorElement } from './utils/anchor-element/anchor-element.js';
+export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
+export { closestInstance } from './utils/closest-instance/closest-instance.js';
+export { createSheet } from './utils/create-sheet/create-sheet.js';
+export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
+export { type DrawIconOptions, drawIcon } from './utils/draw-icon/draw-icon.js';
+export { drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
+export { elapsedTime } from './utils/elapsed-time/elapsed-time.js';
+export { deepActiveElement, deepContains, focusableElements, } from './utils/focusable-elements/focusable-elements.js';
+export { formatNumbers } from './utils/format-numbers/format-numbers.js';
+export { type HostAria, hostAria } from './utils/host-aria/host-aria.js';
+export { type DisableableItem, forgetDisabled, inheritDisabled, } from './utils/inherit-disabled/inherit-disabled.js';
+export { type Curve, linePath, type Point } from './utils/line-path/line-path.js';
+export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
+export { type Row, type RowCell, readRows, readSeries, type Series, type SeriesPoint, } from './utils/read-series/read-series.js';
+export { type Relative, relativeTime, } from './utils/relative-time/relative-time.js';
+export { type ChangeRequestOptions, requestChange, } from './utils/request-change/request-change.js';
+export { type ActivatableItem, resolveActiveItem, } from './utils/resolve-active-item/resolve-active-item.js';
+export { holdCaret, restoreValue } from './utils/restore-value/restore-value.js';
+export { extent, linear, type Scale } from './utils/scale/scale.js';
+export { ticks } from './utils/scale/ticks.js';
+export { type ScrollItemOptions, scrollItemIntoView, } from './utils/scroll-item-into-view/scroll-item-into-view.js';
+export { slotFilled } from './utils/slot-filled/slot-filled.js';
+export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
+export { subscribe } from './utils/ticker/ticker.js';
+export { type HelixStatusTone, TONE_MARKS, type ToneMark, toneMark, } from './utils/tone-marks/tone-marks.js';
+export { dateAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';

package/dist/index.js

@@ -0,0 +1,54 @@
+export { AriaForwardController, } from './controllers/aria-forward-controller/aria-forward-controller.js';
+export { ChartPointerController, } from './controllers/chart-pointer-controller/chart-pointer-controller.js';
+export { CommandController, HelixFallbackCommandEvent, supportsInvokers, } from './controllers/command-controller/command-controller.js';
+export { CopyController, } from './controllers/copy-controller/copy-controller.js';
+export { DisabledCascadeController, } from './controllers/disabled-cascade-controller/disabled-cascade-controller.js';
+export { DismissController, } from './controllers/dismiss-controller/dismiss-controller.js';
+export { DrilldownController, } from './controllers/drilldown-controller/drilldown-controller.js';
+export { FloatingController, } from './controllers/floating-controller/floating-controller.js';
+export { FocusTrapController } from './controllers/focus-trap-controller/focus-trap-controller.js';
+export { IndicatorController, } from './controllers/indicator-controller/indicator-controller.js';
+export { KeyboardNavigationController, } from './controllers/keyboard-navigation-controller/keyboard-navigation-controller.js';
+export { PopoverController, } from './controllers/popover-controller/popover-controller.js';
+export { SourceController, } from './controllers/source-controller/source-controller.js';
+export { TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
+export { VirtualizeController, } from './controllers/virtualize-controller/virtualize-controller.js';
+export { eventsForTag, registerElementEvents } from './events/element-events.js';
+export { HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFilterEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, } from './events/events.js';
+export { HelixElement } from './helix-element/helix-element.js';
+export { HelixFormElement } from './helix-form-element/helix-form-element.js';
+export { MixinChartSource, PALETTE, seriesIndex, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
+export { MixinControllerActive, } from './mixins/mixin-controller-active/mixin-controller-active.js';
+export { MixinControllerChecked, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';
+export { MixinControllerOpen, } from './mixins/mixin-controller-open/mixin-controller-open.js';
+export { MixinControllerValue, } from './mixins/mixin-controller-value/mixin-controller-value.js';
+export { MixinDismissible, } from './mixins/mixin-dismissible/mixin-dismissible.js';
+export { MixinField } from './mixins/mixin-field/mixin-field.js';
+export { anchorElement } from './utils/anchor-element/anchor-element.js';
+export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
+export { closestInstance } from './utils/closest-instance/closest-instance.js';
+export { createSheet } from './utils/create-sheet/create-sheet.js';
+export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
+export { drawIcon } from './utils/draw-icon/draw-icon.js';
+export { drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
+export { elapsedTime } from './utils/elapsed-time/elapsed-time.js';
+export { deepActiveElement, deepContains, focusableElements, } from './utils/focusable-elements/focusable-elements.js';
+export { formatNumbers } from './utils/format-numbers/format-numbers.js';
+export { hostAria } from './utils/host-aria/host-aria.js';
+export { forgetDisabled, inheritDisabled, } from './utils/inherit-disabled/inherit-disabled.js';
+export { linePath } from './utils/line-path/line-path.js';
+export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
+export { readRows, readSeries, } from './utils/read-series/read-series.js';
+export { relativeTime, } from './utils/relative-time/relative-time.js';
+export { requestChange, } from './utils/request-change/request-change.js';
+export { resolveActiveItem, } from './utils/resolve-active-item/resolve-active-item.js';
+export { holdCaret, restoreValue } from './utils/restore-value/restore-value.js';
+export { extent, linear } from './utils/scale/scale.js';
+export { ticks } from './utils/scale/ticks.js';
+export { scrollItemIntoView, } from './utils/scroll-item-into-view/scroll-item-into-view.js';
+export { slotFilled } from './utils/slot-filled/slot-filled.js';
+export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
+export { subscribe } from './utils/ticker/ticker.js';
+export { TONE_MARKS, toneMark, } from './utils/tone-marks/tone-marks.js';
+export { dateAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';

package/dist/mixins/mixin-chart-source/mixin-chart-source.d.ts

@@ -0,0 +1,137 @@
+import { ChartPointerController } from '../../controllers/chart-pointer-controller/chart-pointer-controller.js';
+import type { HelixElement } from '../../helix-element/helix-element.js';
+import { type Row, type Series } from '../../utils/read-series/read-series.js';
+type Constructor<T> = new (...args: any[]) => T;
+/**
+ * How many colours the series palette has, and so where it starts over.
+ *
+ * Here rather than in each chart, which is what it was. Four families held the
+ * same `const PALETTE = 24` and the legend held a fifth: when the palette went
+ * from eight to twenty-four, one of them was missed and drew every ninth series
+ * in the first color again while the legend beside it named the ninth. A
+ * number two files have to agree on is a number that will stop agreeing.
+ */
+export declare const PALETTE = 24;
+/** The palette slot for the nth series, counting from one and wrapping. */
+export declare const seriesIndex: (depth: number) => number;
+/**
+ * The public surface `MixinChartSource` adds.
+ *
+ * Declared separately because TypeScript cannot emit declarations for an
+ * anonymous class that has private or protected members (TS4094), and every
+ * class extending `HelixElement` inherits protected `willUpdate` and `updated`.
+ * Returning the class directly was tried and refused for exactly that.
+ *
+ * **Every member here is documented twice, and that is the convention rather
+ * than an oversight.** TypeScript reads this interface; the analyzer reads the
+ * inner class. Documented only here, `helix-convention-lint` failed the build
+ * with six `Public member has no description` on three charts that had just
+ * been given a shared, fully documented property.
+ *
+ * **The protected members are declared here too, and have to be.** Cast to an
+ * interface holding only `for` and `label`, `series` and `named` vanished from
+ * the emitted `.d.ts` and every chart failed with `Property 'series' does not
+ * exist`. A mixin's interface is not its public API, it is everything a
+ * subclass can see.
+ *
+ * **The series palette, and the one property every chart's mark reads.** A
+ * chart knows which series a bar belongs to and CSS cannot count it, so the
+ * headless tier writes `--chart-series: var(--chart-series-3)` onto the
+ * rectangle and each styled sheet is one rule rather than twenty-four.
+ *
+ * Declared here because this is where `seriesIndex` and `PALETTE` live, and
+ * because a hook repeated on four families is a hook four families have to keep
+ * agreeing about, which is the mistake the `PALETTE` comment above already
+ * records somebody making.
+ *
+ * The numbered twenty-four are the seam between the tiers: `chart/series.css`
+ * points each at a semantic token, which is a decision and so belongs to the
+ * styled tier, and a consumer on `headless` sets the same names to whatever
+ * they like. The headless examples set them to a ramp of grays.
+ *
+ * @cssproperty --chart-series - The color of the mark this is set on. Written by the component, read by the sheet that paints.
+ * @cssproperty --chart-series-1 - The color of series 1. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-2 - The color of series 2. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-3 - The color of series 3. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-4 - The color of series 4. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-5 - The color of series 5. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-6 - The color of series 6. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-7 - The color of series 7. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-8 - The color of series 8. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-9 - The color of series 9. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-10 - The color of series 10. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-11 - The color of series 11. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-12 - The color of series 12. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-13 - The color of series 13. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-14 - The color of series 14. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-15 - The color of series 15. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-16 - The color of series 16. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-17 - The color of series 17. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-18 - The color of series 18. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-19 - The color of series 19. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-20 - The color of series 20. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-21 - The color of series 21. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-22 - The color of series 22. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-23 - The color of series 23. The styled tier points it at a palette token.
+ * @cssproperty --chart-series-24 - The color of series 24. The styled tier points it at a palette token.
+ */
+export declare class MixinChartSourceInterface {
+    /**
+     * The id of the table to read.
+     *
+     * Resolved through `getRootNode()`, so a chart inside another component's
+     * shadow root names a table in that root rather than in the document. A
+     * `<table>` or anything built from grid roles, including `helix-table`.
+     *
+     * **In React this arrives as a property and not as an attribute**, the way
+     * `Tooltip.for` does, so it does not reflect and nothing styles on it.
+     */
+    for: string;
+    /**
+     * The drawing's name, for a pointer resting on it.
+     *
+     * Absent falls back to the table's own caption, which is usually the right
+     * words and is already written.
+     */
+    label: string;
+    /**
+     * The columns of the table, one series each, or none if there is no table.
+     */
+    get series(): Series[];
+    /**
+     * What to call the drawing, the consumer's word or the table's own.
+     */
+    get named(): string;
+    /**
+     * Every row of the table, with each cell's text as well as its number.
+     */
+    get sourceRows(): Row[];
+    /**
+     * How many readings there are, which is what the pointer maps onto.
+     */
+    get readings(): number;
+    /**
+     * Which reading a pointer is nearest, for a tooltip to sit on.
+     */
+    pointer: ChartPointerController;
+}
+/**
+ * The half of a chart that is about finding its numbers rather than drawing.
+ *
+ * Four families had written this out separately, and the row that asked for it
+ * set the bar: two copies is a coincidence and three is a pattern. There were
+ * five copies of `for`, four of `label` and three of the caption fallback by the
+ * time the line and donut charts landed, which is why this arrives now and not
+ * when the second chart did.
+ *
+ * **A mixin rather than a controller**, by the rule the tier notes give: it
+ * introduces `for` and `label`, which a consumer writes. `SourceController` is
+ * the other half and stays a controller, because resolving an id and watching
+ * for changes is behavior nobody calls.
+ *
+ * **`Legend` deliberately does not take this.** It reads a table and has no
+ * drawing to title, so `label` would be API it never uses, and a mixin applied
+ * for four fifths of a fit is how a shared thing starts drifting.
+ */
+export declare const MixinChartSource: <T extends Constructor<HelixElement>>(Base: T) => T & Constructor<MixinChartSourceInterface>;
+export {};