@fusion.dev/helix-core 0.0.0-dev

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

@@ -0,0 +1,201 @@
+import { type CSSResultOrNative, LitElement, type PropertyValues } from 'lit';
+import { type StaticValue } from 'lit/static-html.js';
+/**
+ * @summary Base class every Helix element extends.
+ *
+ * @description
+ * Owns only what is universal: normalizing `box-sizing` inside the shadow root,
+ * so component CSS can rely on border-box on both sides of the boundary.
+ *
+ * There is deliberately no `emit(name, detail)` helper. A dispatch through a
+ * generic helper cannot be named by the manifest analyzer, which recorded the
+ * parameter identifier and produced a phantom event on every element that
+ * inherited it. Components dispatch concrete event classes from `events.ts`,
+ * which the analyzer and TypeScript can both see.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @documentation https://helix.fusion.dev/core/helix-element
+ */
+export declare class HelixElement extends LitElement {
+    /**
+     * The prefix this tier registers its elements under.
+     *
+     * **A component that renders another renders its own tier's version of it**,
+     * so `helix-headless-pagination-size` composes `helix-headless-select` and
+     * `helix-pagination-size` composes `helix-select`. One template says
+     * `${this.tag('select')}` and each tier answers with its own name.
+     *
+     * It was the public tag in both tiers, on the argument that each imports its
+     * own element under that name. That works and costs three things: the name
+     * means two different things depending on what a consumer imported, the
+     * headless tier composes an element it does not ship, and the composition
+     * cannot be tested there at all, because there is no `helix-select` on that
+     * tier to test it against. Thirty-nine specs had to be moved back to
+     * `helix/styled` for exactly that reason.
+     *
+     * **A prefix rather than an override per composition**, which was the first
+     * plan and does not compile. An override re-renders the fragment from the
+     * subclass, and the fragment reads members the base keeps private:
+     * `PaginationSize` alone would have had to widen `options`, `current` and
+     * `handleChange` to `protected` so a subclass could say the same thing again.
+     * Sixteen families of that is a lot of encapsulation spent on saying one
+     * word differently.
+     */
+    static tier: string;
+    /**
+     * One composed tag, as a static value a template can interpolate.
+     *
+     * `unsafeStatic` is safe by construction: the name is a literal in our own
+     * source and the prefix is one of two strings this class defines. Called per
+     * render and not cached, which costs nothing, because `static-html` keys its
+     * template cache on the joined string rather than on the object.
+     */
+    protected tag(name: string): StaticValue;
+    /**
+     * The element's semantics, set without touching the DOM.
+     *
+     * `ElementInternals` sets the implicit role, which an author's own `role`
+     * attribute still overrides, and it writes no attribute. Setting `role` on the
+     * host directly would: that is an attribute the element gives itself after it
+     * upgrades, which a React consumer's server markup never had, and hydration
+     * reports it as a mismatch.
+     *
+     * Available during server rendering. Lit's shim implements `attachInternals`,
+     * so nothing here needs a guard.
+     */
+    protected readonly internals: ElementInternals;
+    /**
+     * Records a boolean fact about this element as a custom state.
+     *
+     * **The host belongs to whoever rendered it, and a component's own
+     * bookkeeping may not be kept there.** An attribute written on the first
+     * update is markup a consumer's server never sent, so a React consumer
+     * hydrates a DOM that has gained attributes since and reports a mismatch it
+     * will not patch up. A custom state is not in the DOM at all: it carries the
+     * fact to a stylesheet through `:state()` and leaves the markup alone, so the
+     * server's output and the client's agree by construction.
+     *
+     * `SETTLED` carries the long version of that argument and was the first to
+     * move. `checked`, `open`, `invalid` and `has-label` followed it on 27 Aug
+     * 2026, after the same fault was reported once more from the landing page's
+     * showcase: a `default-checked` switch, a `default-checked` checkbox and a
+     * `default-open` accordion item, each writing its own resolved state onto
+     * itself before React reached the node.
+     *
+     * **The deferral that had been holding it is not a fix and could not be.**
+     * The site imports the definitions from an effect so the upgrades fall the
+     * other side of hydration, which works only while hydration is one pass:
+     * anything that splits it, a streamed segment or a suspended boundary, puts
+     * an upgrade back inside the window. Timing cannot be the guarantee when the
+     * fact is kept somewhere React reconciles.
+     *
+     * Feature-tested rather than assumed, the way `hostAria` tests element
+     * references. An engine without `CustomStateSet` records nothing and keeps
+     * whatever the resting rule draws, which is the safe direction to fail, and
+     * Lit's server shim is one of them: a custom state is a fact about a running
+     * element, and a server has nothing to say about it.
+     */
+    protected toggleState(name: string, on: boolean): void;
+    /**
+     * Resolves a frame after the first update, when transitions are switched on.
+     *
+     * **Named `whenSettled` because `settled` was taken four times over.** Image
+     * and Splitter each have a private `settle`, and both color controls carry a
+     * `settled` of their own, all of them older than this and none of them about
+     * transitions. A base class takes the name every subclass then cannot use, so
+     * it takes the one nobody wanted.
+     *
+     * **The state it reports cannot be watched, which is why this exists.** A
+     * `MutationObserver` could see `[data-settled]` arrive and there is no
+     * equivalent for `ElementInternals.states`: a custom state is deliberately not
+     * in the DOM, which is the whole reason it replaced the attribute. Anything
+     * that used to wait on the attribute waits on this instead, and gets a better
+     * signal for it, an awaited promise being what the callers wanted rather than
+     * a mutation they had to interpret.
+     *
+     * Separate from `updateComplete`, which resolves in the microtask checkpoint
+     * the suppression is still active in. That is the distinction `readyToMove`
+     * in `@fusion.dev/helix-testing` was written around and the reason two checkbox specs
+     * were misread as a token fault for days.
+     *
+     * It never resolves where `requestAnimationFrame` never fires, which is a
+     * server, a hidden tab, and happy-dom. Callers that must not hang race it
+     * against a timeout; `readyToMove` does exactly that.
+     */
+    readonly whenSettled: Promise<void>;
+    /** Resolves `whenSettled`, once, from the frame that records the state. */
+    private resolveSettled;
+    constructor();
+    /**
+     * Announces an event, having first bound whatever React is holding for it.
+     *
+     * Every event this library sends passes through here, the concrete classes in
+     * `events.ts` and the relayed native ones alike, and `requestChange`
+     * dispatches through the host as well. One override therefore covers all
+     * ninety-seven of them, which is the reason it is here rather than at each
+     * dispatch. See `bindReactHandler`.
+     *
+     * @internal
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * Stops an inner control's own announcement at this element's boundary.
+     *
+     * **A composed control is one control to a consumer, and the natives had no
+     * equivalent of the stop the prefixed events already get.** `<helix-select>`
+     * renders a `<helix-listbox>`, and both announce: the listbox dispatches
+     * `input` and `change` from its own host, `input` is composed by
+     * specification, and a consumer listening on the select therefore heard one
+     * choice twice. Measured before this existed, on the styled tier, one choice
+     * on the inner listbox: select `input` twice and `change` three times,
+     * combobox, date input, time input and color input twice each. `Command` was
+     * the only one that was right, because it happened to reach for
+     * `stopImmediatePropagation` for a different reason.
+     *
+     * Bound on the child in the parent's template, so it runs while the event is
+     * still at the child and before it can cross. The guard is for the case where
+     * a component binds this on itself: an element must never stop its own
+     * announcement, which is the one it exists to make.
+     *
+     * This is the same job the `helix-before-*` handlers do with their own
+     * `stopPropagation`, and it is separate rather than folded into them because
+     * a consumer may legitimately refuse a request without the notification ever
+     * happening: the two travel at different times and one can be absent.
+     */
+    protected readonly stopInner: (event: Event) => void;
+    /**
+     * Re-emits a native event from the host, under its own name.
+     *
+     * A native event fired by an inner `<input>` or `<textarea>` is not composed,
+     * so it stops at the shadow boundary and a consumer listening on
+     * `<helix-input>` hears nothing. Re-dispatching it from the host is what
+     * makes the component behave like the control it wraps.
+     *
+     * The relayed event keeps the native name deliberately. `change` is `change`,
+     * which is what a consumer already knows to listen for, and it is what
+     * reaches React: its synthetic system claims `onChange` and wires it to that
+     * name, so a prefixed one would never arrive.
+     *
+     * `composed` is not forced. It defaults to the original event's own value, so
+     * a relayed `change` stops at the next shadow boundary exactly as a native
+     * one would. Pass it explicitly only where escaping is the intent, and say so
+     * where you do.
+     */
+    protected relayNativeEvent(event: Event, init?: EventInit): void;
+    /**
+     * Prepends the shadow-root reset to every subclass's styles, so no component
+     * has to remember to include it.
+     */
+    protected static finalizeStyles(styles?: CSSResultOrNative | CSSResultOrNative[]): CSSResultOrNative[];
+    /**
+     * Marks the component's first style resolution as done, so `SETTLED` stops
+     * suppressing transitions.
+     *
+     * A frame later, not now: see `SETTLED` for why `firstUpdated` itself is too
+     * early. SSR never calls this, which is correct, because the attribute
+     * describes something that happened in a browser and the server has no frame
+     * to wait for.
+     */
+    protected firstUpdated(changed: PropertyValues): void;
+}