kuinetic 0.1.4 → 0.2.0

package/dist/types/browser/boot.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The self-start shared by every distributed browser bundle.
+ *
+ * ## Why this file imports nothing
+ *
+ * The npm/ESM path's guarantee is that importing kUInetic has no side effects — nothing is scanned
+ * and the document is not touched until `.start()` is called (see `src/index.ts`'s doc comment and
+ * `docs/design.md` §1a). That guarantee is for module consumers, and it still holds absolutely.
+ *
+ * The `<script src="...">` path has the opposite need: zero lines of JavaScript from the author.
+ * Loading the file is the entire integration.
+ *
+ * Both come out of one source because **this module is not in the library's module graph**. It
+ * imports nothing — not from `src/`, not from anywhere — and is reached only by
+ * `scripts/build-tiers.mjs`, which bundles it separately and *appends* it to the IIFE outputs. No
+ * ESM entry point references `src/browser/`, and nothing under `src/` imports this file, so the
+ * side effect is not "tree-shaken away" from `dist/esm/*` — it is unreachable from it.
+ * `scripts/verify-tiers.mjs` fails the build if that ever stops being true.
+ *
+ * Everything it needs, it reads off globals. Everything it is told, it is told through `boot()`'s
+ * options by the one call line the build script appends after it.
+ *
+ * ## The handshake
+ *
+ * `window.__kuineticRuntime` is a plain data object on purpose. The bug this whole scheme exists to
+ * route around is `instanceof` across two independently-bundled copies of the same class (see
+ * `asRegistry` in `src/advanced/base.ts`), so nothing here is ever an instance of anything, and no
+ * bundle ever tests another bundle's object against its own class.
+ *
+ * - **Core is the sole animator creator.** Tiers only queue a registration. A tier without core
+ *   cannot do anything useful, so instead of half-working it names the missing tag in a warning.
+ * - **The boot runs at `DOMContentLoaded`** (or immediately, if the document is already past
+ *   parsing). Plain and `defer` script tags are all guaranteed to have executed by then, in any tag
+ *   order — which is what makes tag order irrelevant by construction rather than by luck. No bundle
+ *   reads a global at parse time and gives up, and nothing polls.
+ * - The pre-JS cloak (`html[data-kui-cloak]` plus the `kui.cloak` layer, `src/css/base.css`) is
+ *   pure CSS and covers the window between first paint and the boot, so deferring `start()` this
+ *   far introduces no flash of un-animated content.
+ *
+ * ## Opt-out
+ *
+ * `data-kui-manual` on a bundle's own `<script>` tag means "this bundle does not auto-init". Put it
+ * on every tag to get exactly the pre-auto-start behaviour back. Marking *core* manual necessarily
+ * disables the whole chain, because core is the only thing that creates an animator — so a tier
+ * that sees core go manual stays quiet rather than complaining that core is missing.
+ */
+/** Only what this file calls. Structural, because it cannot import the real types. */
+interface AnimatorLike {
+    start(): unknown;
+    scan(root?: ParentNode): unknown;
+    reset(el: Element): void;
+}
+type Options = Record<string, unknown>;
+/** The IIFE namespace object a bundle built with `--global-name=kuinetic` exposes. */
+interface CoreNamespace {
+    kuinetic(options?: Options): AnimatorLike;
+}
+export interface BootOptions {
+    /** Names the bundle in warnings: `'core'`, `'advanced'`, `'3d'`. */
+    tier: string;
+    /** Core passes its own IIFE namespace; a tier passes nothing. */
+    core?: CoreNamespace | null;
+    /** The global the bundle was built under, so the double-animator guard can rebind it. */
+    globalName?: string;
+    /** A tier passes its `registerX` function; core passes nothing. */
+    register?: ((animator: AnimatorLike) => unknown) | null;
+}
+/**
+ * Called once per bundle, by the single line `scripts/build-tiers.mjs` appends after this file.
+ */
+export declare function boot(options: BootOptions): void;
+export {};

package/dist/types/core/activation.d.ts

@@ -1,11 +1,198 @@
-import type { Activation, Cleanup } from './types.js';
+import type { Reporter } from './reporter.js';
+import type { Crossing } from './toggle-actions.js';
+import type { Activation, Cleanup, NamedActivation } from './types.js';
+/**
+ * Activations — one concern, three parts, in the order a value travels through them.
+ *
+ * First the vocabulary: what an authored `data-kui-on` value *means*, as tables and pure functions
+ * with no DOM anywhere in sight, so `parse.ts`, `element-config.ts` and `style-plan.ts` can each
+ * ask their own question of it without pulling in a document. Then the binder: how a resolved spec
+ * is actually attached to an element, sharing one `IntersectionObserver` per threshold. Then the
+ * diagnostics: what the library can still tell an author about a value once the list is open,
+ * which needs an element and so cannot live with the first part.
+ */
+/**
+ * What an authored `data-kui-on` value *means*, with no DOM anywhere in sight.
+ *
+ * Kept DOM-free, and kept as a table, because four call sites each need a different slice of the
+ * same knowledge and none of them wants the others' dependencies. `parse.ts` has to validate an
+ * authored value without touching a document; `element-config.ts` has to do the same for the
+ * longhand attribute; `style-plan.ts` only needs to know whether the value starts immediately; the
+ * binder below needs the event types to actually listen for. Writing the table once here is what
+ * stops those four from drifting apart — which is exactly how the old closed list ended up
+ * duplicated as a `Set` in `parse.ts`, a second `Set` in `element-config.ts`, and a `Record` in
+ * the binder, three copies that all had to be edited to add one name.
+ */
+/**
+ * How one half of an activation is delivered.
+ *
+ * A tagged union rather than a bare event-name list because the four delivery mechanisms are
+ * genuinely different machinery — `load` runs now, `manual` runs never, `enter`/`leave` share an
+ * `IntersectionObserver`, and everything else is `addEventListener`. Naming them keeps the
+ * binder's dispatch flat, which is the property the binder's own architecture note below asks for.
+ */
+export type ActivationTrigger = {
+    readonly kind: 'immediate';
+} | {
+    readonly kind: 'manual';
+} | {
+    readonly kind: 'observed';
+    readonly when: 'enter' | 'leave';
+} | {
+    readonly kind: 'events';
+    readonly types: readonly string[];
+};
+/** One resolved `data-kui-on` value: what starts the effects, and what plays them back out. */
+export interface ActivationSpec {
+    /** The authored value, verbatim, so `data-kui-on` round-trips and fingerprints stay stable. */
+    readonly source: Activation;
+    /** The authored halves, verbatim — `['pointerenter', 'pointerleave']`. One or two entries. */
+    readonly names: readonly string[];
+    readonly start: ActivationTrigger;
+    /** Present only when the author wrote a pair. */
+    readonly end?: ActivationTrigger;
+}
+/**
+ * Separator between the two halves of a pair: `data-kui-on="pointerenter/pointerleave"`.
+ *
+ * A slash rather than a comma, a space, or a second attribute. A comma and a space are both
+ * already structural in `parse.ts`'s tokenizer, so either would have forced authors to quote the
+ * inline spelling (`on:"pointerenter, pointerleave"`) for the commonest case in the feature — and
+ * a second attribute (`data-kui-off`) proliferates attributes for something that is one decision
+ * about one element. A slash is inert to the tokenizer, so `on:pointerenter/pointerleave` needs no
+ * quoting, and reads the way CSS already writes paired values (`grid-area: 1 / 2`).
+ */
+export declare const PAIR_SEPARATOR = "/";
+export declare function isNamedActivation(name: string): name is NamedActivation;
+/**
+ * Resolve a `data-kui-on` value into its start and (optional) end triggers.
+ *
+ * Total by construction: an unvalidated or malformed value still resolves, to a listener for an
+ * event that will simply never fire. That is the open list's own contract — the library cannot
+ * know that `cart:updated` is real and `clik` is not — and the diagnostics that make a typo
+ * visible live in `validateActivation` and in `animator.ts`, not here.
+ *
+ * @param activation - Authored value, e.g. `enter`, `pointerenter/pointerleave`, `cart:updated`.
+ * @complexity O(n) time in the value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function resolveActivationSpec(activation: Activation): ActivationSpec;
+/**
+ * Diagnose an authored `data-kui-on` value without a document.
+ *
+ * Returns the reasons the value cannot be used at all, so the caller can fall back to the default
+ * activation rather than binding something meaningless. It deliberately does *not* police whether
+ * an event name is real — that is the open list's whole point, and the check that can be made
+ * (does this document know the name?) needs an element, so it lives in `animator.ts`.
+ *
+ * @returns Zero warnings when the value is usable.
+ * @complexity O(n) time in the value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function validateActivation(value: string): string[];
+/**
+ * Which kind of machinery starts this activation.
+ *
+ * Exported so `style-plan.ts` can ask "does this start on its own?" without importing the whole
+ * trigger union — it used to compare `config.activation === 'load'`, which a pair like
+ * `load/pointerleave` would have quietly failed.
+ *
+ * @complexity O(n) time in the value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function startKindOf(activation: Activation): ActivationTrigger['kind'];
+/**
+ * Whether this activation is spent by its first firing.
+ *
+ * One-shot `enter` is the library's default and a great deal of existing markup depends on it —
+ * the effect plays once and stays. Pairing it is what opts out: an author who wrote an exit half
+ * is asking for the binding to stay live, because an exit that fires once and then stops
+ * responding is not an exit. Observed activations are the only ones that were ever one-shot;
+ * `hover` and `click` deliberately stay bound so a card can flip back.
+ *
+ * @complexity O(n) time in the value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function isOneShot(spec: ActivationSpec): boolean;
+/**
+ * The named activations, any one of which authorises `name` against a primitive's declared
+ * `supportedActivations`. See `SUPPORT_PROXIES`.
+ *
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function authorisingActivations(name: string): readonly NamedActivation[];
+/**
+ * Whether this library recognises `type` as a real event name on its own, without asking a
+ * document. A `-`, `:` or `.` is treated as a deliberate custom-event namespace and always
+ * vouched for — `cart:updated` and `htmx-after-swap` are legitimate activations that no document
+ * will ever recognise, and warning about them would make the warning useless.
+ *
+ * @complexity O(n) time in the list length; O(1) space.
+ * @overallScore 100
+ */
+export declare function isKnownEventType(type: string): boolean;
+/**
+ * Offer the closest activation or event name to a near miss, for a warning that says what to do
+ * instead of only what went wrong.
+ *
+ * @returns The suggestion, or `undefined` when nothing is close enough to be worth offering.
+ * @complexity O(k * n * m) time over the candidate list; O(m) space. Only ever runs on the
+ * diagnostic path for a name the environment already rejected.
+ * @overallScore 100
+ */
+export declare function suggestActivation(name: string): string | undefined;
+/**
+ * Bind an authored activation to an element.
+ *
+ * The delivery mechanisms live in the table above rather than in a switch here, so adding an
+ * activation stays a data change and this binder's branch count stays flat —
+ * the original architecture note, kept through the change from a closed list of six names to an
+ * open one. What used to be `Record<Activation, string[]>` is now a tagged union of four kinds,
+ * for the same reason: an event-name list could not express "any name at all" without also
+ * claiming that `enter` was an event.
+ */
+/** Everything one binding needs, grouped so the call site reads as one request. */
+export interface ActivationRequest {
+    /** `IntersectionObserver` threshold, used only by observed activations. */
+    threshold: string;
+    /** Selector for the foreign elements whose events drive this animation. */
+    from?: string;
+    /** Start the effects. */
+    activate(): void;
+    /**
+     * Play them back out.
+     *
+     * Called only for the exit half of a pair, so a binder consumer that has nothing to reverse can
+     * leave it off and the exit half simply goes unbound.
+     */
+    deactivate?(): void;
+    /**
+     * Deliver the four crossings individually instead of the two `activate`/`deactivate` sides.
+     *
+     * Present only when the element authored `actions:`. The binder's job stops at naming which
+     * crossing happened — what a crossing *does* is the animator's, because every verb is either a
+     * transition of the element's state machine or a call on a playhead, and the binder owns neither.
+     */
+    cross?(crossing: Crossing): void;
+}
 export interface ActivationBinder {
-    bind(el: Element, activation: Activation, threshold: string, onActivate: () => void): Cleanup;
+    bind(el: Element, activation: Activation, request: ActivationRequest): Cleanup;
     destroy(): void;
 }
 export interface ActivationBinderOptions {
     /** Injected so tests can supply a controllable observer and assert without layout. */
     createObserver?: (callback: IntersectionObserverCallback, options: IntersectionObserverInit) => IntersectionObserver;
+    /**
+     * Where {@link checkThresholdReachability} reports an unreachable `threshold:`, if anywhere.
+     *
+     * Bound once for the whole binder rather than threaded through every `bind` call: every observed
+     * binding the binder ever makes shares the one diagnostic sink, the same way they already share
+     * observers per threshold. Optional because most of this file's own tests construct a binder with
+     * nothing to warn into, and the diagnostic is a courtesy the binder degrades out of silently, not
+     * a contract it enforces.
+     */
+    reporter?: Reporter;
 }
 /**
  * Bind activations to elements, sharing one IntersectionObserver per distinct threshold.
@@ -19,3 +206,41 @@ export interface ActivationBinderOptions {
  * @overallScore 100
  */
 export declare function createActivationBinder(options?: ActivationBinderOptions): ActivationBinder;
+/**
+ * Convert an IntersectionObserver threshold from `"30%"` or `"0.3"` into a clamped ratio.
+ *
+ * Lives here rather than with the rest of the attribute reading in `element-config.ts`, where it
+ * used to sit: the binder above is its only caller, and leaving it there would have made
+ * `activation.ts` and `element-config.ts` import each other — a cycle, once `validateActivation`
+ * moved into this file. `.dependency-cruiser.cjs` forbids those for a reason, and the honest fix
+ * is that a threshold is activation machinery, not element configuration.
+ *
+ * @param raw - Authored threshold value.
+ * @returns A ratio in [0, 1]; unparseable input yields 0 rather than throwing.
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function toThresholdRatio(raw: string): number;
+/**
+ * What the library can still tell an author about an authored activation once the list is open.
+ *
+ * Separate from the vocabulary above because these checks need an element and that half is
+ * deliberately DOM-free; separate from `animator.ts` because they are the diagnostics half of one
+ * decision and the animator is already at its line budget. Nothing here changes behaviour — every
+ * value that reaches these functions has already been bound.
+ */
+/** Everything the checks need, grouped so the call site reads as one request. */
+export interface ActivationDiagnosticsRequest {
+    el: Element;
+    spec: ActivationSpec;
+    /** Declared support from the composed primitives; empty means no primitive claimed anything. */
+    supported: NamedActivation[];
+    reporter: Reporter;
+}
+/**
+ * Report every way an authored activation looks like a mistake.
+ *
+ * @complexity O(s * a) time in the authored halves and the declared list, both single-digit.
+ * @overallScore 100
+ */
+export declare function warnAboutActivation(request: ActivationDiagnosticsRequest): void;