kuinetic 0.2.2 → 0.2.4

package/dist/esm/{chunk-K2M7O6W5.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() {
@@ -622,6 +626,10 @@ var CHANNEL = {
    */
   skew: "skew"
 };
+function attributeChannel(attribute) {
+  return `attr:${attribute}`;
+}
+var SUBTREE_CHANNEL = "subtree";
 function inertInstance(destroy = () => {
 }) {
   return {
@@ -2062,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;
@@ -2936,12 +2959,14 @@ export {
   SCOPE_PARAM,
   scopeParam,
   queryScoped,
+  queryControls,
   resolveActivationSpec,
   startKindOf,
   isOneShot,
   createActivationBinder,
   warnAboutActivation,
   ATTR,
+  BREAKPOINT_NAMES,
   gatedAnimationName,
   gateMatches,
   gatesOverlap,
@@ -2961,6 +2986,8 @@ export {
   warnAboutToggleActions,
   applyToggleVerb,
   CHANNEL,
+  attributeChannel,
+  SUBTREE_CHANNEL,
   inertInstance,
   SEGMENT_HOIST_KEYS,
   splitTopLevel,
@@ -2996,5 +3023,9 @@ export {
   createCssInstance,
   continuousSetup,
   deferredInstance,
-  deferPrepare
+  deferPrepare,
+  ALL_TIMING_TOKENS,
+  declareTimingContract,
+  inheritTimingContract,
+  timingContractOf
 };

package/dist/esm/{chunk-BBQ22D7A.mjs → chunk-MZQG2VMG.mjs}

@@ -1,5 +1,7 @@
 import {
+  ALL_TIMING_TOKENS,
   ATTR,
+  BREAKPOINT_NAMES,
   KUI_EVENT,
   Registry,
   SEGMENT_HOIST_KEYS,
@@ -13,6 +15,7 @@ import {
   createRootResolver,
   createScrollScheduler,
   cssEasingValue,
+  decimalNumber,
   directionValue,
   emitLifecycle,
   gateMatches,
@@ -37,11 +40,13 @@ import {
   splitTopLevel,
   startKindOf,
   suggest,
+  timingContractOf,
   timingProperty,
   toMilliseconds,
+  validate,
   warnAboutActivation,
   warnAboutToggleActions
-} from "./chunk-K2M7O6W5.mjs";
+} from "./chunk-FASAEQDR.mjs";
 import {
   createLedgerSet
 } from "./chunk-AEQGC2KM.mjs";
@@ -3442,11 +3447,206 @@ function runQuietly(cleanup) {
   }
 }
 
+// src/core/describe.ts
+var POSITIONAL = [
+  { slot: "duration", accepts: "time" },
+  { slot: "delay", accepts: "time" },
+  { slot: "ease", accepts: "easing" }
+];
+function describeEffect(registry, name, notes = {}) {
+  const resolved = registry.resolve(name);
+  if (!resolved) return void 0;
+  const { preset, primitive } = resolved;
+  const declared = primitive.parameters;
+  const contract = timingContractOf(primitive);
+  const honours = contract ? contract.honours ?? [] : ALL_TIMING_TOKENS;
+  const positionalOrder = POSITIONAL.map((slot) => ({
+    ...slot,
+    ...Object.hasOwn(declared, slot.slot) ? { param: slot.slot } : {},
+    honoured: honours.includes(slot.slot)
+  }));
+  const params = Object.entries(declared).map(([param, spec]) => {
+    const override = preset.params?.[param];
+    const note = findNote(spec.note, notes, [preset.name, primitive.id, "*"], param);
+    return {
+      name: param,
+      type: spec.type,
+      default: override ?? spec.default,
+      presetDefault: override !== void 0,
+      required: note?.required === true,
+      spellings: spellingsFor(spec, override ?? spec.default),
+      ...optionalFields(spec, param, note)
+    };
+  });
+  const described = {
+    name: preset.name,
+    primitive: primitive.id,
+    renderer: primitive.renderer,
+    params,
+    positionalOrder
+  };
+  if (contract && honours.length < ALL_TIMING_TOKENS.length) described.unhonouredBecause = contract.because;
+  return described;
+}
+function optionalFields(spec, param, note) {
+  const out = {};
+  if (spec.keywords) out.keywords = spec.keywords;
+  if (spec.minimum !== void 0) out.minimum = spec.minimum;
+  if (spec.maximum !== void 0) out.maximum = spec.maximum;
+  if (spec.integer) out.integer = true;
+  const index = POSITIONAL.findIndex((slot) => slot.slot === param);
+  if (index >= 0) out.positionalIndex = index;
+  if (note) out.note = note.why;
+  if (note?.whenOmitted) out.whenOmitted = note.whenOmitted;
+  return out;
+}
+function describeAttribute(registry, value, notes = {}) {
+  return describeSpecs(registry, parse(value).specs, notes);
+}
+function describeElementAttribute(registry, value, notes = {}) {
+  const parsed = parse(value);
+  const written = {};
+  for (const [field, key] of Object.entries(ELEMENT_KEYS)) {
+    const set = parsed[field];
+    if (set !== void 0) written[key.key] = set;
+  }
+  return { steps: describeSpecs(registry, parsed.specs, notes), keys: describeKeys(notes), written };
+}
+function describeKeys(notes = {}) {
+  const element = Object.values(ELEMENT_KEYS).map((key) => keyRow(key, "element", notes));
+  return [...element, ...STEP_KEY_LIST.map((key) => keyRow(key, "step", notes))];
+}
+function describeSpecs(registry, specs, notes) {
+  return specs.map((spec) => {
+    const written = { written: writtenArgs(spec), writtenKeys: writtenStepKeys(spec) };
+    const described = describeEffect(registry, spec.name, notes);
+    if (described) return { ...described, ...written };
+    const suggestion = suggest(spec.name, registry.names());
+    const unknown = suggestion ? { name: spec.name, unknown: true, suggestion } : { name: spec.name, unknown: true };
+    return { ...unknown, ...written };
+  });
+}
+function writtenArgs(spec) {
+  const written = { ...spec.params };
+  if (spec.duration !== void 0) written.duration = spec.duration;
+  if (spec.delay !== void 0) written.delay = spec.delay;
+  if (spec.easing !== void 0) written.ease = spec.easing;
+  return written;
+}
+function writtenStepKeys(spec) {
+  const written = {};
+  if (spec.at !== void 0) written.at = spec.at;
+  Object.assign(written, spec.gate);
+  if (spec.repeat !== void 0) written.repeat = spec.repeat;
+  if (spec.yoyo !== void 0) written.yoyo = String(spec.yoyo);
+  for (const [field, value] of Object.entries(spec.hoists ?? {})) {
+    written[ELEMENT_KEYS[field].key] = value;
+  }
+  return written;
+}
+var KEY_NOTE_OWNER = "data-kui";
+function keyRow(key, scope, notes) {
+  const note = findNote(void 0, notes, [KEY_NOTE_OWNER], key.key);
+  const row = {
+    name: key.key,
+    type: key.type,
+    default: key.default,
+    presetDefault: false,
+    required: false,
+    spellings: [...key.spellings],
+    scope
+  };
+  if (key.keywords) row.keywords = key.keywords;
+  if (note) row.note = note.why;
+  if (note?.whenOmitted) row.whenOmitted = note.whenOmitted;
+  return row;
+}
+var TIMELINES2 = Object.keys({ time: 0, view: 0, scroll: 0, pointer: 0, pin: 0 });
+var RM_POLICIES = Object.keys({ shorten: 0, crossfade: 0, disable: 0 });
+var ELEMENT_KEYS = {
+  activation: { key: "on", type: "text", default: "", spellings: ["enter", "load", "hover", "click", "hover/unhover"] },
+  actions: { key: "actions", type: "text", default: "", spellings: ["play/pause/resume/reset", "play/none/none/reset"] },
+  timeline: { key: "timeline", type: "keyword", default: "", spellings: TIMELINES2, keywords: TIMELINES2 },
+  threshold: { key: "threshold", type: "percentage", default: "", spellings: ["0%", "25%"] },
+  cascade: { key: "cascade", type: "time", default: "", spellings: ["90ms", "0.09s"] },
+  spread: { key: "spread", type: "time", default: "", spellings: ["600ms", "0.6s"] },
+  order: { key: "order", type: "text", default: "", spellings: ["start", "end", "center", "edges", "random", "3"] },
+  cols: { key: "cols", type: "text", default: "", spellings: ["auto", "4"] },
+  along: { key: "along", type: "keyword", default: "", spellings: ["x", "y"], keywords: ["x", "y"] },
+  rm: { key: "rm", type: "keyword", default: "", spellings: RM_POLICIES, keywords: RM_POLICIES },
+  func: { key: "func", type: "text", default: "", spellings: ["onRevealDone"] }
+};
+var gateKey = (key) => ({
+  key,
+  type: "keyword",
+  default: "",
+  spellings: BREAKPOINT_NAMES,
+  keywords: BREAKPOINT_NAMES
+});
+var STEP_KEYS = {
+  at: { key: "at", type: "text", default: "", spellings: ["after", "with", "-200ms", "with+100ms"] },
+  gate: { above: gateKey("above"), below: gateKey("below"), wide: gateKey("wide"), narrow: gateKey("narrow") },
+  repeat: { key: "repeat", type: "text", default: "", spellings: ["infinite", "3"] },
+  yoyo: { key: "yoyo", type: "keyword", default: "", spellings: ["true", "false"], keywords: ["true", "false"] }
+};
+var STEP_KEY_LIST = Object.values(STEP_KEYS).flatMap(
+  (entry) => "key" in entry ? [entry] : Object.values(entry)
+);
+function findNote(inline, notes, owners, param) {
+  const key = owners.map((owner) => `${owner}.${param}`).find((k) => Object.hasOwn(notes, k));
+  const note = inline ?? (key === void 0 ? void 0 : notes[key]);
+  if (note === void 0) return void 0;
+  return typeof note === "string" ? { why: note } : note;
+}
+var NUMBER = /^-?(?:\d+(?:\.\d+)?|\.\d+)/;
+function spellingsFor(spec, fallback = spec.default) {
+  const value = validate(fallback, spec).ok ? fallback.trim() : "";
+  return EXAMPLES[spec.type](value, spec.keywords ?? []);
+}
+var EXAMPLES = {
+  angle: (value) => angleForms(value),
+  "angle|keyword": (value, keywords) => [...angleForms(keywords.includes(value) ? "" : value), ...keywords],
+  keyword: (_, keywords) => [...keywords],
+  time: timeForms,
+  number: (value) => [value || "1"],
+  percentage: (value) => [value || "50%"],
+  "number|percentage": alphaForms,
+  length: (value) => [value || "24px", "calc(1rem + 4px)"],
+  "length|percentage": (value) => [value || "24px", "50%"],
+  color: (value) => [value || "#e4f222", "rgb(228 242 34)", "currentcolor"],
+  easing: (value) => [value || "ease-out", "linear", "cubic-bezier(.2, .8, .2, 1)", "spring"],
+  path: () => ["M0,0L100,0"],
+  text: () => []
+};
+function angleForms(value) {
+  const n = NUMBER.exec(value)?.[0];
+  const degrees = value.endsWith("deg") || /^-?[\d.]+d?$/.test(value);
+  const base = degrees && n ? n : "45";
+  const forms = [base, `${base}d`, `${base}deg`];
+  return degrees || !value ? forms : [value, ...forms];
+}
+function timeForms(value) {
+  const n = NUMBER.exec(value)?.[0];
+  if (!n) return ["600ms", "0.6s"];
+  return value.endsWith("ms") ? [value, `${decimalNumber(n, -3)}s`] : [value, `${decimalNumber(n, 3)}ms`];
+}
+function alphaForms(value) {
+  const n = NUMBER.exec(value)?.[0];
+  if (!n) return ["0.5", "50%"];
+  return value.endsWith("%") ? [`${decimalNumber(n, -2)}`, value] : [value, `${decimalNumber(n, 2)}%`];
+}
+
 export {
   detect,
   consoleReporter,
   silentReporter,
   collectingReporter,
   Animator,
-  createAnimator
+  createAnimator,
+  describeEffect,
+  describeAttribute,
+  describeElementAttribute,
+  describeKeys,
+  KEY_NOTE_OWNER,
+  spellingsFor
 };

package/dist/esm/core/index.mjs

@@ -1,41 +1,59 @@
 import {
   Animator,
+  KEY_NOTE_OWNER,
   collectingReporter,
   consoleReporter,
   createAnimator,
+  describeAttribute,
+  describeEffect,
+  describeElementAttribute,
+  describeKeys,
   detect,
-  silentReporter
-} from "../chunk-BBQ22D7A.mjs";
+  silentReporter,
+  spellingsFor
+} from "../chunk-MZQG2VMG.mjs";
 import {
   ATTR,
   CHANNEL,
   KUI_EVENT,
   Registry,
+  SUBTREE_CHANNEL,
+  attributeChannel,
   control,
   createActivationBinder,
   inertInstance,
   play,
   resolveActivationSpec,
   resolveTargets,
+  timingContractOf,
   toAttributeValue
-} from "../chunk-K2M7O6W5.mjs";
+} from "../chunk-FASAEQDR.mjs";
 import "../chunk-AEQGC2KM.mjs";
 export {
   ATTR,
   Animator,
   CHANNEL,
+  KEY_NOTE_OWNER,
   KUI_EVENT,
   Registry,
+  SUBTREE_CHANNEL,
+  attributeChannel,
   collectingReporter,
   consoleReporter,
   control,
   createActivationBinder,
   createAnimator,
+  describeAttribute,
+  describeEffect,
+  describeElementAttribute,
+  describeKeys,
   detect,
   inertInstance,
   play,
   resolveActivationSpec,
   resolveTargets,
   silentReporter,
+  spellingsFor,
+  timingContractOf,
   toAttributeValue
 };

package/dist/esm/effects/index.mjs

@@ -17,8 +17,8 @@ import {
   registerThreeD,
   registerTween,
   registerViewTransitions
-} from "../chunk-XDDJVANU.mjs";
-import "../chunk-K2M7O6W5.mjs";
+} from "../chunk-EHS45PIK.mjs";
+import "../chunk-FASAEQDR.mjs";
 import "../chunk-AEQGC2KM.mjs";
 export {
   COMBOS,

package/dist/esm/index.mjs

@@ -1,30 +1,39 @@
 import {
   Animator,
+  KEY_NOTE_OWNER,
   collectingReporter,
   consoleReporter,
   createAnimator,
+  describeAttribute,
+  describeEffect,
+  describeElementAttribute,
+  describeKeys,
   detect,
-  silentReporter
-} from "./chunk-BBQ22D7A.mjs";
+  silentReporter,
+  spellingsFor
+} from "./chunk-MZQG2VMG.mjs";
 import {
   COMBOS,
   PRESETS,
   PRIMITIVES,
   createRegistry
-} from "./chunk-XDDJVANU.mjs";
+} from "./chunk-EHS45PIK.mjs";
 import {
   ATTR,
   CHANNEL,
   KUI_EVENT,
   Registry,
+  SUBTREE_CHANNEL,
+  attributeChannel,
   control,
   createActivationBinder,
   inertInstance,
   play,
   resolveActivationSpec,
   resolveTargets,
+  timingContractOf,
   toAttributeValue
-} from "./chunk-K2M7O6W5.mjs";
+} from "./chunk-FASAEQDR.mjs";
 import "./chunk-AEQGC2KM.mjs";
 
 // src/index.ts
@@ -32,15 +41,28 @@ function kuinetic(options = {}) {
   return new Animator({ registry: createRegistry(), ...options });
 }
 var src_default = kuinetic;
+var catalog;
+function describe(name, options = {}) {
+  return describeEffect(options.registry ?? (catalog ??= createRegistry()), name, options.notes);
+}
+function describeSteps(value, options = {}) {
+  return describeAttribute(options.registry ?? (catalog ??= createRegistry()), value, options.notes);
+}
+function describeElement(value, options = {}) {
+  return describeElementAttribute(options.registry ?? (catalog ??= createRegistry()), value, options.notes);
+}
 export {
   ATTR,
   Animator,
   CHANNEL,
   COMBOS,
+  KEY_NOTE_OWNER,
   KUI_EVENT,
   PRESETS,
   PRIMITIVES,
   Registry,
+  SUBTREE_CHANNEL,
+  attributeChannel,
   collectingReporter,
   consoleReporter,
   control,
@@ -48,6 +70,13 @@ export {
   createAnimator,
   createRegistry,
   src_default as default,
+  describe,
+  describeAttribute,
+  describeEffect,
+  describeElement,
+  describeElementAttribute,
+  describeKeys,
+  describeSteps,
   detect,
   inertInstance,
   kuinetic,
@@ -55,5 +84,7 @@ export {
   resolveActivationSpec,
   resolveTargets,
   silentReporter,
+  spellingsFor,
+  timingContractOf,
   toAttributeValue
 };