kuinetic 0.1.3 → 0.2.0

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

@@ -0,0 +1,128 @@
+import type { EffectParams, ParamSpec } from './types.js';
+/**
+ * The slice of `PrepareContext` `resolveTarget`/`queryScoped` actually need.
+ *
+ * A real `PrepareContext` satisfies this structurally — it has both fields and more — so every
+ * existing call site (the primitives' own `prepare`, which is handed a full `PrepareContext`)
+ * keeps compiling unchanged. Declared narrow rather than importing `PrepareContext` itself so
+ * `animator.ts`'s `install` — which resolves a retargeted selector at compile-to-install time,
+ * before any primitive's `prepare` has run and therefore before a full `PrepareContext` exists —
+ * can build the two fields it actually has (`el.ownerDocument`, a warn callback) instead of
+ * fabricating the rest of the interface it does not.
+ */
+export interface TargetContext {
+    doc: Document;
+    warn(message: string): void;
+}
+/**
+ * `target:`/`scope:` resolution — one convention shared by every place in the library that lets an
+ * author name a selector instead of animating the element the attribute sits on.
+ *
+ * Lives in `core`, not `effects`, because `core/compile.ts` and `core/animator.ts` need it too:
+ * `target:` started as a per-primitive parameter six scroll/forms primitives read for themselves
+ * (`effects/step-marking.ts`'s `createStepMarker` still owns the step-index-specific half of that),
+ * but retargeting an *arbitrary* effect (`fade-up target:h1`) has to be decided at compile/install
+ * time, before any primitive's own `prepare` ever runs. `core` must not depend on `effects` — every
+ * import in this codebase already runs the other way — so the shared half of the mechanism lives
+ * here and `effects/step-marking.ts` imports it back, rather than `core` reaching into `effects`.
+ */
+/**
+ * Classify a selector as unusable, dangerously broad, or fine.
+ *
+ * `matches` against the two roots catches every selector that reaches the whole document — `*`,
+ * `html`, `body` and compounds like `*, a` with one rule and no bespoke parser — while leaving a
+ * deliberately scoped wildcard such as `.spy-nav > *` working, which a syntactic ban on `*` would
+ * not. `matches` throws on invalid syntax exactly as `querySelectorAll` does, so the same call
+ * still answers the validity question.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function selectorBreadth(selector: string, doc: Document): 'invalid' | 'document-wide' | 'ok';
+/**
+ * Resolve a `target:` selector once at setup, rejecting both the unusable and the over-broad.
+ *
+ * Two distinct failures, one warning channel. An invalid selector thrown from inside the shared
+ * scheduler's frame callback would skip every other subscriber on that root, not just this one. An
+ * over-broad one is worse for being silent: `target:*` is perfectly valid syntax, so a syntax-only
+ * check passed it straight through to stamp an attribute onto every element in the document, on
+ * every frame.
+ *
+ * Rejecting rather than silently narrowing is the honest response, because there is no narrower
+ * selector that could be meant. A selector reaching `<html>` or `<body>` is not naming a set of
+ * steps or a nav link, it is naming the page, and guessing which of its thousands of descendants
+ * the author meant would be worse than saying so.
+ *
+ * @param selector - The authored `target:` value; empty is the no-op default, not an error.
+ * @param ctx - Prepare context, for `doc` and the warning channel.
+ * @param effect - Effect name, so the warning says which attribute to go and fix.
+ * @returns The selector, or `''` when it must be ignored.
+ * @complexity O(1) time and space; `matches` walks the selector, not the document.
+ * @overallScore 100
+ */
+export declare function resolveTarget(selector: string, ctx: TargetContext, effect: string): string;
+/**
+ * Which tree a validated `target:` is searched in.
+ *
+ * `'self'` is the descendant reading — "search inside myself" — and is what `target:` means
+ * everywhere the word is used going forward. `'page'` is the whole document, which a handful of
+ * resolution sites need because the element they mark is deliberately somewhere else: `scroll-spy`'s
+ * nav link lives outside the section that activates it, and `media-scrub`'s frames may sit in a
+ * sibling figure.
+ *
+ * Two values, declared as a list rather than a boolean, so `'parent'` or `'section'` can be added
+ * later by extending {@link SCOPE_PARAM}'s `keywords` — a one-line change with no rename anywhere.
+ */
+export type TargetScope = 'self' | 'page';
+/**
+ * The one declaration of `scope:`, shared by every primitive that declares `target:`.
+ *
+ * Declared once rather than restated per primitive for the same reason `resolveTarget` lives here
+ * rather than in each caller: `target:`/`scope:` is one convention across the library, and six
+ * copies of a `keywords` list is six places for it to drift.
+ *
+ * `default: ''` is load-bearing, not a style choice. `readParams` (`core/js-params.ts`) seeds
+ * `out[name] = spec.default` for *every* declared parameter before reading authored values, and
+ * `createParams`' `text` accessor uses `??`, so a non-empty schema default would make the
+ * caller-supplied fallback in {@link scopeParam} unreachable. `scroll-spy` is one primitive with
+ * one `ParameterSchema` whose two forms need opposite defaults (`'page'` for the per-section form,
+ * `'self'` for the container form), so "unset" has to be spellable — which is exactly why `target`
+ * itself is already declared `default: ''` on every primitive that owns the parameter.
+ *
+ * `type: 'keyword'`, not `'text'`: a `text` param accepts any string that survives the escape
+ * screen, so `scope:pgae` would be accepted in silence and then read as unset. `keyword` is the
+ * type whose `keywords` list is the *whole* grammar, so a typo is named. The cost is that
+ * `--kui-scope` reaches
+ * `element.style` when authored, where nothing reads it; an inert custom property is a much smaller
+ * price than a typo that fails silently.
+ */
+export declare const SCOPE_PARAM: ParamSpec;
+/**
+ * Read `scope:`, falling back to the resolution site's own historical default.
+ *
+ * The fallback is per *call site*, not per primitive, because `scroll-spy` resolves the same
+ * declared parameter document-wide in one form and descendant-scoped in the other.
+ *
+ * @param params - The effect's validated parameters.
+ * @param fallback - What this site scoped to before `scope:` existed. Passing today's behaviour
+ *   here is what makes declaring the parameter a no-op for existing markup.
+ * @returns The authored scope, or `fallback` when unset or unrecognised.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function scopeParam(params: EffectParams, fallback: TargetScope): TargetScope;
+/**
+ * Resolve a validated `target:` selector under a scope.
+ *
+ * {@link resolveTarget} has already run: this does no validation of its own, so an invalid or
+ * document-wide selector must have been rejected before it gets here.
+ *
+ * @param el - The authored host. The search root under `'self'`.
+ * @param ctx - Prepare context, for `doc` — the search root under `'page'`.
+ * @param selector - A validated, non-empty `target:` value.
+ * @param scope - Which tree to search.
+ * @returns The matches, in document order.
+ * @complexity O(n) time and space in matches; the query itself is the DOM's.
+ * @overallScore 100
+ */
+export declare function queryScoped(el: Element, ctx: Pick<TargetContext, 'doc'>, selector: string, scope: TargetScope): Element[];

package/dist/types/core/threshold-reachability.d.ts

@@ -0,0 +1,45 @@
+import type { Reporter } from './reporter.js';
+/** The subset of an observed binding's state this diagnostic reads and updates. */
+export interface ThresholdReachabilityState {
+    /** Where to report an unreachable threshold. `undefined` means nowhere — nothing to check for. */
+    reporter?: Reporter;
+    /**
+     * Whether this element has ever been geometrically inside the root, independent of whether it
+     * ever met the authored threshold. Tells a genuine leave (toured through, never got there) apart
+     * from the first delivery of an element that starts outside the root (never arrived yet) — both
+     * report `isIntersecting: false`, and only one of them is evidence of anything.
+     */
+    sawIntersecting: boolean;
+    /** Whether the threshold was ever actually met. A binding that got here has never met it. */
+    entered: boolean;
+    /** Set once this has warned, so a repeated tour past the same unreachable threshold stays quiet. */
+    thresholdWarned: boolean;
+}
+/**
+ * Say so when a full transit closes without an authored threshold ever being met, and the target's
+ * own geometry is why it never can be: it is larger than the root it scrolls through, so its
+ * intersection ratio has a hard ceiling below what was asked for. See {@link maxReachableRatio}.
+ *
+ * Checked only on a genuine leave — `!entry.isIntersecting` once {@link ThresholdReachabilityState.sawIntersecting}
+ * already recorded a real entry — rather than on whichever delivery arrives first. A target's
+ * measured size is a runtime fact, not an authored one, and the very first delivery for a freshly
+ * observed element can land before a lazy image has decoded, an accordion has expanded, or a web
+ * font has swapped in — any of which can measure a box taller *right now* than it will be once the
+ * page settles. A completed transit — inside the root and back out — gives layout the whole scroll
+ * past it to settle before its geometry is trusted for a diagnostic that, once given, cannot be
+ * unsaid. The cost is a symmetrical blind spot: a target that is too tall only *during* one transit
+ * (a mid-scroll resize) keeps quiet until the next full transit re-checks it — the same shape of
+ * tradeoff `meetsThreshold`'s own caveat already accepts for the threshold itself.
+ *
+ * An element that starts already outside the root also delivers `isIntersecting: false` on its very
+ * first entry — "hasn't arrived yet," not "toured through and failed" — which is exactly what
+ * `sawIntersecting` exists to tell apart from a real leave.
+ *
+ * Warns once per element (`thresholdWarned`), not once per delivery or per transit: an element that
+ * tours past its unreachable threshold repeatedly (a reader scrolling up and down) would otherwise
+ * repeat the same diagnostic every time.
+ *
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function checkThresholdReachability(binding: ThresholdReachabilityState, entry: IntersectionObserverEntry, ratio: number): void;

package/dist/types/core/time-scale.d.ts

@@ -0,0 +1,9 @@
+/** The ancestor marker read by library animation creation and the showcase speed control. */
+export declare const TIME_SCALE_ATTR = "data-kui-time-scale";
+/**
+ * Read the nearest time scale, including a marker on the element itself.
+ *
+ * @complexity O(h) in ancestor depth; O(1) space.
+ * @overallScore 100
+ */
+export declare function timeScaleOf(el: Element): number;

package/dist/types/core/toggle-actions.d.ts

@@ -0,0 +1,141 @@
+import type { InstanceControl } from './types.js';
+/**
+ * The four crossings, and what an author can ask for at each.
+ *
+ * A scroll trigger has four distinct moments, not two. Travelling down the page an element *enters*
+ * the viewport and later *leaves* it out of the top; travelling back up it re-enters from the top
+ * and leaves again out of the bottom. `data-kui-on="enter/leave"` covers two of them, with the only
+ * two verbs being "play" and "play backwards" — so the thing an author most often wants from a
+ * scroll trigger, *pause where you are and carry on from there when I come back*, could not be
+ * written at all.
+ *
+ * This module is the vocabulary: what the four crossings are called, what the eight verbs mean, and
+ * how one authored string becomes a verb per crossing. It touches no DOM and holds no state.
+ * `activation.ts` decides *which* crossing happened — it is the only thing holding the observer
+ * entry that can tell — and `animator.ts` owns the element and supplies the two element-level
+ * transitions the verbs are built from. Neither of them has to know the vocabulary, and this file
+ * does not have to know either of them.
+ *
+ * **Nothing here animates anything.** Every verb is composed from `InstanceControl` —
+ * `pause`/`resume`/`seek`, which `control.ts` has exposed as public API since runtime control
+ * shipped — plus `activate` and `reverse`, which only the animator can own because they are
+ * transitions of the element's whole state machine rather than of one playhead.
+ */
+/**
+ * One of the four moments a scroll crossing can happen at, named from the reader's direction of
+ * travel rather than the element's: `enter` and `leave` happen while scrolling *down*, the two
+ * `-back` crossings while scrolling back *up*.
+ *
+ * Hyphenated rather than camel-cased because these names are quoted back to authors in warnings,
+ * and every other word this library asks an author to read is hyphenated.
+ */
+export type Crossing = 'enter' | 'leave' | 'enter-back' | 'leave-back';
+/** The four crossings in the order an author writes them — GSAP's `toggleActions` order. */
+export declare const CROSSINGS: readonly Crossing[];
+/**
+ * What to do at a crossing.
+ *
+ * The same eight GSAP's `toggleActions` takes, and the same words, because an author arriving from
+ * it should not have to learn a second vocabulary for an identical idea. What each one means here
+ * is stated in {@link applyToggleVerb}, which is also where the ones that cannot be honest about an
+ * element that has not started yet are handled.
+ */
+export type ToggleVerb = 'play' | 'pause' | 'resume' | 'reverse' | 'reset' | 'restart' | 'complete' | 'none';
+/** A verb per crossing. Every slot is always present; an unwritten one is `none`. */
+export type ToggleActions = Readonly<Record<Crossing, ToggleVerb>>;
+/**
+ * Parse an authored `actions:` value into a verb per crossing.
+ *
+ * Total by construction: an unrecognised verb becomes `none` rather than failing the element, and
+ * every rejection is named. Trailing slots the author left off are `none` too, so `actions:play` is
+ * "play on the way in and nothing else" — which is both GSAP's own default and this library's
+ * existing behaviour for an unpaired `on:enter`.
+ *
+ * @param value - Authored text, e.g. `play/pause/resume/none`.
+ * @param warnings - Sink for the diagnostics. Optional so a pure parse can ignore them.
+ * @complexity O(1) time and space — at most four tokens.
+ * @overallScore 100
+ */
+export declare function parseToggleActions(value: string, warnings?: string[]): ToggleActions;
+/**
+ * Diagnose an authored `actions:` value without a document — the shape-only half.
+ *
+ * Mirrors `validateActivation`'s contract exactly, including where it stops: this is the part
+ * `parse.ts` can run with nothing but the attribute text. Whether the *element* can honour the
+ * verbs needs its compiled plan, and lives in {@link warnAboutToggleActions}.
+ *
+ * @returns Zero warnings when every token is a verb.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function validateToggleActions(value: string): string[];
+/** What {@link warnAboutToggleActions} needs to know about the element, with no DOM in it. */
+export interface ToggleDiagnostics {
+    actions: ToggleActions;
+    /** Whether this element's activation is delivered by the intersection observer at all. */
+    observed: boolean;
+    /** The authored activation, quoted back when it is not an observed one. */
+    activation: string;
+    /** Names of the composed effects rendered in JavaScript — they expose no playhead. */
+    jsEffectNames: readonly string[];
+    /** Whether the element's progress belongs to the scroller rather than to a clock. */
+    progressDriven: boolean;
+}
+/**
+ * Report every way an authored `actions:` cannot do what it says.
+ *
+ * All three of these produce a knob that exists and does nothing, which this codebase treats as
+ * worse than a missing knob — and all three are invisible from the markup, because the element
+ * still animates, just not the way the attribute claims.
+ *
+ * @returns One message per problem; empty when the element can honour every verb.
+ * @complexity O(1) time and space — four crossings.
+ * @overallScore 100
+ */
+export declare function warnAboutToggleActions(request: ToggleDiagnostics): string[];
+/** The element a verb is being applied to, reduced to what the verbs actually need. */
+export interface ToggleTarget {
+    /**
+     * Whether the element has been activated at all.
+     *
+     * The distinction two of the verbs cannot be honest without. An element that has never started is
+     * already sitting at its from-state, so `reset` there is a no-op rather than a seek, and `resume`
+     * means *start* rather than *unpause* — going straight to the ledger's play-state would open the
+     * compiled gate behind the animator's back, leaving `data-kui-state` reading `ready` on a visibly
+     * running element and no `kui:start` ever dispatched.
+     */
+    started: boolean;
+    /** The element's reachable playheads. Empty for a JS-rendered or scroll-driven element. */
+    controls: readonly InstanceControl[];
+    /** Start, or turn a reversing playhead back around — `Animator.activate`. */
+    activate(): void;
+    /** Play out backwards to the from-state — `Animator.reverseFrom`. */
+    reverse(): void;
+}
+/**
+ * Do one verb.
+ *
+ * Every branch is composed from things that already existed. `play` and `reverse` are the element's
+ * two directional transitions, which only the animator owns; the other five are `InstanceControl`
+ * calls. Nothing here touches an `Animation` object, and nothing here decides *when* — that is the
+ * observer's job.
+ *
+ * The three jump verbs are worth stating precisely, because "a jump" and "a state machine" are easy
+ * to get wrong together:
+ *
+ * - **`reset`** rewinds to the from-state and stops there. On an element that never started there
+ *   is nothing to rewind — it is already at the from-state — so this does nothing at all rather
+ *   than seeking playheads still sitting behind the compiled gate.
+ * - **`restart`** rewinds and keeps going. It activates first, so an element crossing for the first
+ *   time starts properly — with its `kui:start`, its state attribute and its settle — rather than
+ *   being seeked while still gated. On an already-running element `activate` returns at its own
+ *   guard, so no second settle is armed and the seek simply replays the run.
+ * - **`complete`** jumps to the end state, and activates first for the same reason. It deliberately
+ *   does *not* pause afterwards: an animation seeked to its end while still playing reaches
+ *   `finished` on its own, and that is what resolves the settle and dispatches `kui:finish`.
+ *   Pausing it there would strand the element at `running` forever with nothing moving.
+ *
+ * @complexity O(n) time in the element's controllable instances; O(1) space.
+ * @overallScore 100
+ */
+export declare function applyToggleVerb(verb: ToggleVerb, target: ToggleTarget): void;

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

@@ -0,0 +1,59 @@
+/**
+ * Which way the reader is travelling, and which side of a scroll root that puts things on.
+ *
+ * Split out of `activation.ts` because it answers a question about the *reader* rather than about
+ * any element or any authored spec: one page-wide signal, sampled from one listener, that the
+ * four-way crossing delivery consults and nothing else in the binder cares about.
+ */
+/**
+ * Which side of the observer's root an element sits on, in the reader's direction of travel:
+ * `before` is the side already scrolled past, `after` the side not reached yet.
+ *
+ * Named by travel rather than by geometry so one word covers both axes — `before` is above a
+ * vertically scrolled root and to the left of a horizontally scrolled one.
+ */
+export type RootSide = 'before' | 'after';
+/** Which way the reader is travelling, phrased as the side an element entering *now* came from. */
+export interface TravelTracker {
+    /**
+     * The side an element entering at `time` must have arrived from, or `undefined` when the reader's
+     * travel does not explain a delivery at that moment.
+     */
+    arrivedFrom(time: number): RootSide | undefined;
+    /** Start listening, if this is the first four-way binding to ask. */
+    retain(): void;
+    /** Stop listening, if this was the last. */
+    release(): void;
+    /** Stop listening regardless of the count, for a binder torn down with bindings still on it. */
+    reset(): void;
+}
+/**
+ * Track which way the reader is travelling, so an entering delivery can be classified by what is
+ * happening *now* rather than by memory of a crossing that may never have been delivered.
+ *
+ * `deliverCrossing` used to answer "first entry or re-entry?" purely from `binding.outside`, the
+ * side recorded by the last *leaving* delivery. A scroll that lands in a single frame — an
+ * `<a href="#anchor">` click, `scrollIntoView()`, `scrollTo({ behavior: 'instant' })`, scroll
+ * restoration — carrying the element from "not intersecting" straight past to "not intersecting" on
+ * the far side changes neither `isIntersecting` nor the threshold ratio at any frame the browser
+ * samples, so the observer delivers *nothing at all* and the remembered side is left describing a
+ * position the reader is no longer anywhere near. The next real delivery is then classified against
+ * it and comes out backwards: measured in Chrome, a reader scrolling back up through a skipped
+ * element got `enter` where `enter-back` was authored. A denser threshold array does not help,
+ * because the browser paints no intermediate frame for it to sample; nor does re-reading the
+ * geometry, because an entering element is inside the root and so is on no side to read.
+ *
+ * The reader's direction of travel answers it without needing to know anything about the skipped
+ * crossing, and the two agree wherever nothing was skipped, so the ordinary path is unchanged.
+ *
+ * One listener for every binding on the page, mirroring `activation.ts`'s one-observer-per-threshold:
+ * direction is a property of the reader, not of an element, so per-element listeners would buy
+ * nothing for their cost. It is retained only by four-way bindings — a page of plain `on:enter`
+ * effects adds no listener at all.
+ *
+ * @returns A tracker whose `retain`/`release` ref-count the single shared listener.
+ * @complexity O(1) time per scroll event, independent of how many elements are bound; O(s) space in
+ *   the number of distinct scrollers the reader has actually touched.
+ * @overallScore 100
+ */
+export declare function createTravelTracker(): TravelTracker;