kuinetic 0.2.1 → 0.2.3

package/README.md

@@ -10,7 +10,7 @@ wherever CSS can do it. Standalone, MIT, npm + CDN, framework-agnostic. No produ
 <h1 data-kui="fade-up">Hello.</h1>
 ```
 
-302 named effects across scroll reveals, hover/interaction, text, numbers, layout, SVG, 3D, and
+305 named effects across scroll reveals, hover/interaction, text, numbers, layout, SVG, 3D, and
 gesture-driven motion. 3,800+ unit tests. The jsdom suite holds `src/` at 100%
 line/branch/function/statement coverage with two carve-outs: the WebGL tier in `src/advanced/`
 (`shaders.ts`, `gl-utils.ts`, `fluid-cursor.ts`, `particles.ts`), whose GPU paths cannot execute
@@ -123,16 +123,23 @@ its readable, unminified twin, about twice the transfer size; use it only for de
 `kuinetic.advanced.min.js` is a tier: it needs core on the page, in either order, and never carries
 a copy of it.
 
-Every one of those browser bundles starts itself once the document is ready. `data-kui-manual` on a
-`<script>` tag turns that off for that file. Importing from npm does **not** start anything — a
-module import stays side-effect-free, which is the guarantee the bundler path is built on.
+Every one of those browser bundles starts itself once the document is ready. Importing from npm does
+**not** start anything — a module import stays side-effect-free, which is the guarantee the bundler
+path is built on.
+
+To drive it by hand, put `data-kui-manual` on the tag. On `kuinetic.js` that turns off the
+*auto-start* only: nothing is created or started until you call `kuinetic.kuinetic({ ... }).start()`,
+and any tier bundle you load (`kuinetic.advanced.js`, ...) still registers into the animator you
+build, in either tag order. On a tier's own tag it takes that tier out entirely.
 
 > **Changed in 0.2.** These bundles used to do nothing until you called
 > `kuinetic.kuinetic({ observe: true }).start()` yourself, and `kuinetic.all.js` started itself the
 > instant it parsed rather than at `DOMContentLoaded`. If you already write that call, it keeps
-> working and your animator is still the one the page uses — you will see one console line saying
-> the call is now redundant. Add `data-kui-manual` to the tag to silence it and go back to driving
-> everything by hand.
+> working and your animator is still the one the page uses. A call that names its own options — a
+> `reporter`, a scoped `root`, a `registry` — is how you configure the auto-started animator, and it
+> is adopted without comment. A call with no options, or only `{ observe: true }`, does nothing the
+> script tag has not already done, so you will see one console line saying it is now redundant. Delete
+> it, or add `data-kui-manual` to the tag to go back to driving everything by hand.
 
 ## Your first animation
 
@@ -179,7 +186,7 @@ untrusted input — see Getting Started for the full note.
 ## Docs
 
 - **Getting Started** — install, first animation, timing, composition, common mistakes.
-- **Catalog** — all 302 named effects, grouped by category, with renderer and channel metadata.
+- **Catalog** — all 305 named effects, grouped by category, with renderer and channel metadata.
 - **Architecture** — the attribute grammar, the composition model, and why the library is built
   the way it is (`docs/design.md` in this repo).
 

package/dist/esm/advanced/index.mjs

@@ -1836,7 +1836,7 @@ function parseAngleRadians(raw) {
   if (!match) return 0;
   const value = parseFloat(match[1]);
   if (!Number.isFinite(value)) return 0;
-  return value * (ANGLE_UNITS[(match[2] ?? "deg").toLowerCase()] ?? ANGLE_UNITS.deg);
+  return value * ANGLE_UNITS[(match[2] ?? "deg").toLowerCase()];
 }
 var PALETTE_SIZE = 5;
 var DEFAULT_PALETTE = [
@@ -2067,7 +2067,7 @@ function paintBoxOf(content, natural, cs) {
   if (bw <= 0 || bh <= 0) return content;
   const [dw, dh] = fittedSize(cs.objectFit || "fill", bw, bh, natural);
   const tokens = (cs.objectPosition || "50% 50%").trim().split(/\s+/);
-  const left = content.left + positionOffset(tokens[0] ?? "50%", bw - dw);
+  const left = content.left + positionOffset(tokens[0], bw - dw);
   const top = content.top + positionOffset(tokens[1] ?? "50%", bh - dh);
   return { left, top, right: left + dw, bottom: top + dh };
 }
@@ -2333,7 +2333,7 @@ function extractShaderOptions(params, createCanvas) {
     ...readDuotoneColors(c1Text, c2Text, createCanvas),
     blendMode: blendMap[params.text("blend", "normal")] ?? 0,
     to: params.text("to", ""),
-    progress: params.num ? params.num("progress", -1) : -1,
+    progress: params.num("progress", -1),
     // Compared against the one enabling word rather than "not `off`", so — exactly as with
     // `audioBand` below — a caller passing an unvalidated accessor, or an author who typed
     // `scrub: scrol`, cannot turn the bridge on by accident.
@@ -2770,7 +2770,7 @@ function restoreInstanceOpacity(el, state) {
   if (!state.hiddenByRenderer) return;
   state.hiddenByRenderer = false;
   const style = styleOf(state.ledgers, el);
-  if (style) style.set("opacity", style.peek("opacity") ?? "");
+  if (style) style.set("opacity", style.peek("opacity"));
 }
 var SHADER_TEXTURE_GRACE_MS = 5e3;
 function acquireRenderer(info, held) {
@@ -3938,7 +3938,7 @@ function prepareCameraScene(el, params, ctx) {
   const controller = new CameraController(htmlEl, options, resolvedEnv);
   const layerEls = ownedDescendants(htmlEl, "camera-scene", "camera-layer");
   for (const layer of layerEls) {
-    const kui = layer.getAttribute("data-kui") || "";
+    const kui = layer.getAttribute("data-kui");
     const zMatch = /z:([+-]?[0-9.]+)(?:px)?/.exec(kui);
     const depthZ = zMatch ? parseDepth(zMatch[1]) : 0;
     controller.addLayer(layer, depthZ);

package/dist/esm/{chunk-U43BX5O2.mjs → chunk-FASAEQDR.mjs}

@@ -36,6 +36,10 @@ function scopeParam(params, fallback) {
 function queryScoped(el, ctx, selector, scope) {
   return [...(scope === "page" ? ctx.doc : el).querySelectorAll(selector)];
 }
+function queryControls(el, ctx, selector) {
+  const inside = [...el.querySelectorAll(selector)];
+  return inside.length > 0 ? inside : [...ctx.doc.querySelectorAll(selector)];
+}
 
 // src/core/event-sources.ts
 function createEventSourceBindings() {
@@ -541,18 +545,25 @@ function defaultObserverFactory() {
   if (typeof IntersectionObserver === "undefined") return void 0;
   return (callback, init) => new IntersectionObserver(callback, init);
 }
+function onlyBoundLate(name, claims) {
+  const authorising = authorisingActivations(name);
+  if (!authorising.includes("enter")) return false;
+  const suits = (claim) => authorising.some((named) => claim.supported.includes(named));
+  if (!claims.some((claim) => claim.entrance && suits(claim))) return false;
+  return claims.every((claim) => suits(claim) || claim.supported.includes("load"));
+}
 function warnAboutActivation(request) {
   warnUnsupported(request);
   warnUnknownEvents(request);
 }
-function warnUnsupported({ el, spec, supported, reporter }) {
-  if (supported.length === 0) return;
+function warnUnsupported({ el, spec, supported, claims, reporter }) {
+  const declaredAny = supported.length > 0 || (claims?.some((claim) => claim.supported.length > 0) ?? false);
+  if (!declaredAny) return;
+  const shared = supported.length > 0 ? supported.join(", ") : "none in common across the composed effects";
   for (const name of spec.names) {
     if (authorisingActivations(name).some((named) => supported.includes(named))) continue;
-    reporter.warn(
-      `activation "${name}" is not supported by this effect (supports: ${supported.join(", ")})`,
-      el
-    );
+    if (claims && onlyBoundLate(name, claims)) continue;
+    reporter.warn(`activation "${name}" is not supported by this effect (supports: ${shared})`, el);
   }
 }
 function warnUnknownEvents({ el, spec, reporter }) {
@@ -615,6 +626,10 @@ var CHANNEL = {
    */
   skew: "skew"
 };
+function attributeChannel(attribute) {
+  return `attr:${attribute}`;
+}
+var SUBTREE_CHANNEL = "subtree";
 function inertInstance(destroy = () => {
 }) {
   return {
@@ -2055,6 +2070,21 @@ function emitLifecycle(el, type, detail) {
   el.dispatchEvent(new Ctor(type, { detail, bubbles: true, composed: true }));
 }
 
+// src/core/timing-contract.ts
+var ALL_TIMING_TOKENS = ["duration", "delay", "ease"];
+var CONTRACTS = /* @__PURE__ */ new WeakMap();
+function declareTimingContract(prepare, contract) {
+  CONTRACTS.set(prepare, contract);
+  return prepare;
+}
+function inheritTimingContract(inner, outer) {
+  const contract = CONTRACTS.get(inner);
+  return contract ? declareTimingContract(outer, contract) : outer;
+}
+function timingContractOf(primitive) {
+  return primitive.prepare ? CONTRACTS.get(primitive.prepare) : void 0;
+}
+
 // src/core/params.ts
 var DANGEROUS = /[;<]|\/\*|url\s*\(|expression\s*\(|@import|image-set\s*\(/i;
 var ABSOLUTE_OR_PROTOCOL_RELATIVE = /^(?:[a-z][a-z0-9+.-]*:|[/\\]{2})/i;
@@ -2682,11 +2712,20 @@ function createRootResolver(options) {
   const windowRoot = windowScrollRoot(win);
   return (el) => {
     for (let node = el.parentElement; node; node = node.parentElement) {
+      if (scrollsTheViewport(node, win)) return windowRoot;
       if (isScrollable(node)) return elementScrollRoot(node, win);
     }
     return windowRoot;
   };
 }
+function scrollsTheViewport(node, win) {
+  const root = win.document.documentElement;
+  if (node === root) return true;
+  if (node !== win.document.body) return false;
+  const rootStyle = win.getComputedStyle(root);
+  return !CLIPPING_OVERFLOW.has(rootStyle.overflowX) && !CLIPPING_OVERFLOW.has(rootStyle.overflowY);
+}
+var CLIPPING_OVERFLOW = /* @__PURE__ */ new Set(["auto", "scroll", "overlay", "hidden", "clip"]);
 var SCROLLABLE_OVERFLOW = /* @__PURE__ */ new Set(["auto", "scroll", "overlay"]);
 function defaultIsScrollable(win) {
   return (el) => {
@@ -2920,12 +2959,14 @@ export {
   SCOPE_PARAM,
   scopeParam,
   queryScoped,
+  queryControls,
   resolveActivationSpec,
   startKindOf,
   isOneShot,
   createActivationBinder,
   warnAboutActivation,
   ATTR,
+  BREAKPOINT_NAMES,
   gatedAnimationName,
   gateMatches,
   gatesOverlap,
@@ -2945,6 +2986,8 @@ export {
   warnAboutToggleActions,
   applyToggleVerb,
   CHANNEL,
+  attributeChannel,
+  SUBTREE_CHANNEL,
   inertInstance,
   SEGMENT_HOIST_KEYS,
   splitTopLevel,
@@ -2980,5 +3023,9 @@ export {
   createCssInstance,
   continuousSetup,
   deferredInstance,
-  deferPrepare
+  deferPrepare,
+  ALL_TIMING_TOKENS,
+  declareTimingContract,
+  inheritTimingContract,
+  timingContractOf
 };