@kieransimkin/dancemoves 3.0.2

package/lib/react.cjs

@@ -0,0 +1,154 @@
+"use client";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// .build/modules/react.mjs
+var react_exports = {};
+__export(react_exports, {
+  DanceMovesProvider: () => DanceMovesProvider,
+  PageMetadataEditor: () => PageMetadataEditor,
+  Rudiment: () => Rudiment,
+  useCue: () => useCue,
+  useDanceMoves: () => useDanceMoves,
+  useDanceMovesContext: () => useDanceMovesContext,
+  useLyric: () => useLyric,
+  useRudiment: () => useRudiment
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+var import_index = require("./index.cjs");
+var EMPTY = Object.freeze({});
+var Context = (0, import_react.createContext)(null);
+function useDanceMoves(rootRef, options = EMPTY) {
+  const [result, setResult] = (0, import_react.useState)({ runtime: null, error: null });
+  (0, import_react.useEffect)(() => {
+    if (!rootRef.current) return;
+    let active = true, runtime;
+    try {
+      runtime = (0, import_index.createDanceMoves)({ ...options, root: rootRef.current });
+      setResult({ runtime, error: null });
+      runtime.ready.catch((error) => {
+        if (active) setResult({ runtime, error });
+      });
+    } catch (error) {
+      setResult({ runtime: null, error });
+    }
+    return () => {
+      active = false;
+      runtime?.destroy();
+    };
+  }, [rootRef, options]);
+  return result;
+}
+function DanceMovesProvider({ options = EMPTY, children, className = "", ...attributes }) {
+  const root = (0, import_react.useRef)(null);
+  const result = useDanceMoves(root, options);
+  return (0, import_react.createElement)("div", { ...attributes, ref: root, className: `ks-epk ${className}`.trim() }, (0, import_react.createElement)(Context.Provider, { value: result }, children));
+}
+function useDanceMovesContext() {
+  const value = (0, import_react.useContext)(Context);
+  if (!value) throw new Error("useDanceMovesContext requires DanceMovesProvider");
+  return value;
+}
+function useCue(runtime, name, callback) {
+  const latest = (0, import_react.useRef)(callback);
+  latest.current = callback;
+  (0, import_react.useEffect)(() => runtime?.onCue(name, (detail) => latest.current(detail)), [runtime, name]);
+}
+function useLyric(runtime) {
+  const [lyric, setLyric] = (0, import_react.useState)(null);
+  (0, import_react.useEffect)(() => {
+    setLyric(null);
+    if (!runtime) return;
+    const remove = runtime.onLyric(setLyric);
+    const clear = () => setLyric(null);
+    const events = ["pause", "ended", "seeking"];
+    events.forEach((type) => runtime.root.addEventListener(type, clear, true));
+    return () => {
+      remove();
+      events.forEach((type) => runtime.root.removeEventListener(type, clear, true));
+    };
+  }, [runtime]);
+  return lyric;
+}
+function useRudiment(runtime, targetRef, options) {
+  const [result, setResult] = (0, import_react.useState)({ controller: null, error: null });
+  (0, import_react.useEffect)(() => {
+    if (!runtime || !targetRef.current) return;
+    let active = true, controller;
+    try {
+      controller = runtime.rudiments.animate({ ...options, root: runtime.root, target: targetRef.current });
+      setResult({ controller, error: null });
+      controller.ready.catch((error) => {
+        if (active) setResult({ controller, error });
+      });
+    } catch (error) {
+      setResult({ controller: null, error });
+    }
+    return () => {
+      active = false;
+      controller?.destroy();
+    };
+  }, [runtime, targetRef, options]);
+  return result;
+}
+function Rudiment({ runtime, options, children, ...attributes }) {
+  const ref = (0, import_react.useRef)(null);
+  useRudiment(runtime, ref, options);
+  return (0, import_react.createElement)("div", { ...attributes, ref }, children);
+}
+function PageMetadataEditor({ value = EMPTY, onSave }) {
+  const [draft, setDraft] = (0, import_react.useState)(() => ({ ...value })), [message, setMessage] = (0, import_react.useState)(""), [busy, setBusy] = (0, import_react.useState)(false);
+  (0, import_react.useEffect)(() => setDraft({ ...value }), [value]);
+  const input = (key, label, type = "text") => (0, import_react.createElement)("label", { key }, label, (0, import_react.createElement)("input", {
+    type,
+    value: draft[key] ?? "",
+    step: type === "number" ? "0.001" : void 0,
+    onChange: (e) => setDraft({ ...draft, [key]: type === "number" ? e.target.value === "" ? void 0 : Number(e.target.value) : e.target.value })
+  }));
+  return (0, import_react.createElement)(
+    "form",
+    { onSubmit: async (event) => {
+      event.preventDefault();
+      setBusy(true);
+      setMessage("");
+      try {
+        await onSave((0, import_index.validatePageConfig)(draft));
+        setMessage("Saved");
+      } catch (error) {
+        setMessage(error.message);
+      } finally {
+        setBusy(false);
+      }
+    } },
+    input("bpm", "BPM", "number"),
+    input("lyricTimingUrl", "Lyric timing URL"),
+    input("cueTimingUrl", "Cue timing URL"),
+    input("masterDurationMilliseconds", "Master duration (milliseconds)", "number"),
+    (0, import_react.createElement)("label", null, (0, import_react.createElement)("input", { type: "checkbox", checked: !!draft.lyricPopupsEnabled, onChange: (e) => setDraft({ ...draft, lyricPopupsEnabled: e.target.checked }) }), "Timed lyric pop-ups"),
+    (0, import_react.createElement)("label", null, "Ambient effect", (0, import_react.createElement)(
+      "select",
+      { value: draft.effect || "", onChange: (e) => setDraft({ ...draft, effect: e.target.value }) },
+      (0, import_react.createElement)("option", { value: "" }, "None"),
+      (0, import_react.createElement)("option", { value: "paper-planes" }, "Paper planes")
+    )),
+    (0, import_react.createElement)("button", { type: "submit", disabled: busy }, busy ? "Saving\u2026" : "Save metadata"),
+    (0, import_react.createElement)("output", { "aria-live": "polite" }, message)
+  );
+}

package/lib/react.d.ts

@@ -0,0 +1,12 @@
+import type {ReactNode,RefObject,HTMLAttributes} from 'react';
+import type {DanceMoves,Options,PageConfig,Cue,Lyric} from './index';
+import type {RudimentOptions,RudimentAnimation} from './rudiments';
+export interface MountState {runtime:DanceMoves|null;error:Error|null}
+export function useDanceMoves(root:RefObject<HTMLElement|null>,options?:Omit<Options,'root'>):MountState;
+export function DanceMovesProvider(props:HTMLAttributes<HTMLDivElement> & {options?:Omit<Options,'root'>;children?:ReactNode}):ReactNode;
+export function useDanceMovesContext():MountState;
+export function useCue(runtime:DanceMoves|null,name:string,callback:(cue:Cue)=>void):void;
+export function useLyric(runtime:DanceMoves|null):Lyric|null;
+export function useRudiment(runtime:DanceMoves|null,target:RefObject<HTMLElement|null>,options:Omit<RudimentOptions,'root'|'target'>):{controller:RudimentAnimation|null;error:Error|null};
+export function Rudiment(props:HTMLAttributes<HTMLDivElement> & {runtime:DanceMoves|null;options:Omit<RudimentOptions,'root'|'target'>;children?:ReactNode}):ReactNode;
+export function PageMetadataEditor(props:{value?:PageConfig;onSave:(config:PageConfig)=>void|Promise<unknown>}):ReactNode;

package/lib/react.mjs

@@ -0,0 +1,135 @@
+"use client";
+"use client";
+
+// .build/modules/react.mjs
+import { createContext, createElement as h, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { createDanceMoves, validatePageConfig } from "./index.mjs";
+var EMPTY = Object.freeze({});
+var Context = createContext(null);
+function useDanceMoves(rootRef, options = EMPTY) {
+  const [result, setResult] = useState({ runtime: null, error: null });
+  useEffect(() => {
+    if (!rootRef.current) return;
+    let active = true, runtime;
+    try {
+      runtime = createDanceMoves({ ...options, root: rootRef.current });
+      setResult({ runtime, error: null });
+      runtime.ready.catch((error) => {
+        if (active) setResult({ runtime, error });
+      });
+    } catch (error) {
+      setResult({ runtime: null, error });
+    }
+    return () => {
+      active = false;
+      runtime?.destroy();
+    };
+  }, [rootRef, options]);
+  return result;
+}
+function DanceMovesProvider({ options = EMPTY, children, className = "", ...attributes }) {
+  const root = useRef(null);
+  const result = useDanceMoves(root, options);
+  return h("div", { ...attributes, ref: root, className: `ks-epk ${className}`.trim() }, h(Context.Provider, { value: result }, children));
+}
+function useDanceMovesContext() {
+  const value = useContext(Context);
+  if (!value) throw new Error("useDanceMovesContext requires DanceMovesProvider");
+  return value;
+}
+function useCue(runtime, name, callback) {
+  const latest = useRef(callback);
+  latest.current = callback;
+  useEffect(() => runtime?.onCue(name, (detail) => latest.current(detail)), [runtime, name]);
+}
+function useLyric(runtime) {
+  const [lyric, setLyric] = useState(null);
+  useEffect(() => {
+    setLyric(null);
+    if (!runtime) return;
+    const remove = runtime.onLyric(setLyric);
+    const clear = () => setLyric(null);
+    const events = ["pause", "ended", "seeking"];
+    events.forEach((type) => runtime.root.addEventListener(type, clear, true));
+    return () => {
+      remove();
+      events.forEach((type) => runtime.root.removeEventListener(type, clear, true));
+    };
+  }, [runtime]);
+  return lyric;
+}
+function useRudiment(runtime, targetRef, options) {
+  const [result, setResult] = useState({ controller: null, error: null });
+  useEffect(() => {
+    if (!runtime || !targetRef.current) return;
+    let active = true, controller;
+    try {
+      controller = runtime.rudiments.animate({ ...options, root: runtime.root, target: targetRef.current });
+      setResult({ controller, error: null });
+      controller.ready.catch((error) => {
+        if (active) setResult({ controller, error });
+      });
+    } catch (error) {
+      setResult({ controller: null, error });
+    }
+    return () => {
+      active = false;
+      controller?.destroy();
+    };
+  }, [runtime, targetRef, options]);
+  return result;
+}
+function Rudiment({ runtime, options, children, ...attributes }) {
+  const ref = useRef(null);
+  useRudiment(runtime, ref, options);
+  return h("div", { ...attributes, ref }, children);
+}
+function PageMetadataEditor({ value = EMPTY, onSave }) {
+  const [draft, setDraft] = useState(() => ({ ...value })), [message, setMessage] = useState(""), [busy, setBusy] = useState(false);
+  useEffect(() => setDraft({ ...value }), [value]);
+  const input = (key, label, type = "text") => h("label", { key }, label, h("input", {
+    type,
+    value: draft[key] ?? "",
+    step: type === "number" ? "0.001" : void 0,
+    onChange: (e) => setDraft({ ...draft, [key]: type === "number" ? e.target.value === "" ? void 0 : Number(e.target.value) : e.target.value })
+  }));
+  return h(
+    "form",
+    { onSubmit: async (event) => {
+      event.preventDefault();
+      setBusy(true);
+      setMessage("");
+      try {
+        await onSave(validatePageConfig(draft));
+        setMessage("Saved");
+      } catch (error) {
+        setMessage(error.message);
+      } finally {
+        setBusy(false);
+      }
+    } },
+    input("bpm", "BPM", "number"),
+    input("lyricTimingUrl", "Lyric timing URL"),
+    input("cueTimingUrl", "Cue timing URL"),
+    input("masterDurationMilliseconds", "Master duration (milliseconds)", "number"),
+    h("label", null, h("input", { type: "checkbox", checked: !!draft.lyricPopupsEnabled, onChange: (e) => setDraft({ ...draft, lyricPopupsEnabled: e.target.checked }) }), "Timed lyric pop-ups"),
+    h("label", null, "Ambient effect", h(
+      "select",
+      { value: draft.effect || "", onChange: (e) => setDraft({ ...draft, effect: e.target.value }) },
+      h("option", { value: "" }, "None"),
+      h("option", { value: "paper-planes" }, "Paper planes")
+    )),
+    h("button", { type: "submit", disabled: busy }, busy ? "Saving\u2026" : "Save metadata"),
+    h("output", { "aria-live": "polite" }, message)
+  );
+}
+export {
+  DanceMovesProvider,
+  PageMetadataEditor,
+  Rudiment,
+  useCue,
+  useDanceMoves,
+  useDanceMovesContext,
+  useLyric,
+  useRudiment
+};

package/lib/rudiments.d.ts

@@ -0,0 +1,124 @@
+/** DanceMoves rudiment animation API v1; available on WordPress Page requests. */
+export type RudimentName = 'bounce' | 'sway' | 'circle' | 'figure_eight' | 'step_touch' |
+  'box_step' | 'helix' | 'clay_background' | 'single_stroke_roll' | 'double_stroke_roll' |
+  'multiple_bounce_roll' | 'single_paradiddle' | 'flam' | 'drag' | 'five_stroke_roll';
+export type Offset3 = Readonly<{ x: number; y: number; z: number }>;
+export type RudimentClock = 'page' | 'audio' | 'auto';
+export type RudimentStatus = 'loading' | 'running' | 'paused' | 'disabled' | 'hidden' |
+  'offscreen' | 'reduced-motion' | 'forced-colors' | 'audio-paused' | 'seeking' |
+  'ended' | 'error' | 'destroyed';
+export interface RudimentInfo {
+  readonly name: RudimentName;
+  readonly description: string;
+  readonly periodPips: number;
+  readonly dimensions: 1 | 2 | 3;
+  /** Internal order in this pinned catalogue, not a stable cross-version ID. */
+  readonly index: number;
+}
+export interface RudimentFrame {
+  readonly id: string;
+  readonly root: Element;
+  readonly target: Element;
+  readonly audio: HTMLAudioElement | null;
+  readonly rudiment: RudimentName;
+  readonly clock: 'page' | 'audio';
+  readonly sourceBeats: number;
+  readonly bpm: number;
+  readonly rate: number;
+  /** Wrapped integer pip; null for a neutral disabled/accessibility pose. */
+  readonly pip: number | null;
+  readonly positionPips: number | null;
+  /** Continuous clock phase; positions themselves remain integer-pip samples. */
+  readonly loopProgress: number;
+  /** Loop duration at playbackRate=1, derived from page BPM and rudiment rate. */
+  readonly durationMilliseconds: number;
+  readonly offset: Offset3;
+  /** Pixel-scaled offset for the default CSS renderer. */
+  readonly position: Offset3;
+  readonly reason: RudimentStatus | 'frame';
+}
+export interface RudimentOptions {
+  readonly id: string;
+  readonly rudiment: RudimentName;
+  readonly target: Element | string;
+  readonly root?: Element | string;
+  readonly clock?: RudimentClock;
+  readonly audio?: HTMLAudioElement | string;
+  readonly rate?: number;
+  readonly phasePips?: number;
+  readonly amplitude?: number | Partial<Offset3>;
+  readonly enabled?: boolean;
+  readonly css?: boolean;
+  readonly cssPrefix?: string;
+  readonly offscreen?: boolean;
+  readonly resetOnCue?: boolean | string;
+  readonly renderEveryFrame?: boolean;
+  readonly render?: (detail: RudimentFrame) => void;
+}
+export interface RudimentAnimationSnapshot {
+  readonly id: string;
+  readonly rudiment: RudimentName;
+  readonly status: RudimentStatus;
+  readonly enabled: boolean;
+  readonly clock: RudimentClock;
+  readonly rate: number;
+  readonly phasePips: number;
+  readonly destroyed: boolean;
+  readonly loaded: boolean;
+  readonly error: string | null;
+  readonly updates: number;
+  readonly pip: number | null;
+  readonly sourceClock: 'page' | 'audio' | null;
+  readonly position: Offset3 | null;
+  readonly framePending: boolean;
+}
+export interface RudimentAnimation {
+  readonly id: string;
+  readonly ready: Promise<RudimentAnimation>;
+  pause(): void;
+  resume(): void;
+  setEnabled(enabled: boolean): void;
+  reset(): void;
+  refresh(): void;
+  snapshot(): RudimentAnimationSnapshot;
+  destroy(): void;
+  teardown(): void;
+}
+export interface RudimentApi {
+  readonly version: '1.0.0';
+  readonly upstreamVersion: string;
+  readonly upstreamCommit: string;
+  readonly pipsPerBeat: 64;
+  readonly ticksPerBeat: 16;
+  readonly pipsPerTick: 4;
+  ready(): Promise<RudimentApi>;
+  catalogue(): readonly RudimentInfo[];
+  describe(name: string): RudimentInfo | null;
+  sample(name: RudimentName, pip: number): Offset3;
+  pipsFromTicks(ticks: number): number;
+  pipsFromSeconds(seconds: number, bpm?: number): number;
+  animate(options: RudimentOptions): RudimentAnimation;
+  get(id: string): RudimentAnimation | null;
+  snapshot(): Readonly<{ version: '1.0.0'; upstreamVersion: string; loaded: boolean;
+    error: string | null; framePending: boolean; instances: readonly RudimentAnimationSnapshot[] }>;
+  destroyAll(): void;
+}
+export interface ClayRudimentApi {
+  readonly root: Element;
+  teardown(): void;
+  snapshot(): Readonly<{ status: 'loading' | 'active' | 'suspended' | 'fallback' | 'destroyed';
+    error: string | null; destroyed: boolean; loaded: boolean; rudiment: 'clay_background';
+    cycleBeats: 8; rate: 0.5; controller: RudimentAnimationSnapshot | null }>;
+}
+declare global {
+  interface Window {
+    DanceMovesRudiments?: RudimentApi;
+    DanceMovesClayRudiment?: ClayRudimentApi;
+  }
+  interface DocumentEventMap {
+    'dance-moves-rudiments-ready': CustomEvent<{
+      api: RudimentApi; version: string; upstreamVersion: string; upstreamCommit: string;
+    }>;
+    'dance-moves-rudiments-error': CustomEvent<{ id: string | null; message: string }>;
+  }
+}