@editframe/elements 0.6.0-beta.16 → 0.6.0-beta.18

package/src/elements/EFTemporal.ts

@@ -0,0 +1,231 @@
+import type { LitElement, ReactiveController } from "lit";
+import { consume, createContext } from "@lit/context";
+import { property, state } from "lit/decorators.js";
+import type { EFTimegroup } from "./EFTimegroup";
+
+import { durationConverter } from "./durationConverter";
+import { Task } from "@lit/task";
+import { EF_INTERACTIVE } from "../EF_INTERACTIVE";
+
+export const timegroupContext = createContext<EFTimegroup>(
+  Symbol("timeGroupContext"),
+);
+
+export declare class TemporalMixinInterface {
+  get hasOwnDuration(): boolean;
+  get durationMs(): number;
+  get startTimeMs(): number;
+  get startTimeWithinParentMs(): number;
+  get endTimeMs(): number;
+  get ownCurrentTimeMs(): number;
+
+  parentTimegroup?: EFTimegroup;
+  rootTimegroup?: EFTimegroup;
+
+  frameTask: Task<readonly unknown[], unknown>;
+}
+
+export const isEFTemporal = (obj: any): obj is TemporalMixinInterface =>
+  obj[EF_TEMPORAL];
+
+const EF_TEMPORAL = Symbol("EF_TEMPORAL");
+
+export const deepGetTemporalElements = (
+  element: Element,
+  temporals: TemporalMixinInterface[] = [],
+) => {
+  for (const child of element.children) {
+    if (isEFTemporal(child)) {
+      temporals.push(child);
+    }
+    deepGetTemporalElements(child, temporals);
+  }
+  return temporals;
+};
+
+export const deepGetElementsWithFrameTasks = (
+  element: Element,
+  elements: Array<HTMLElement & { frameTask: Task }> = [],
+) => {
+  for (const child of element.children) {
+    if ("frameTask" in child && child.frameTask instanceof Task) {
+      elements.push(child as HTMLElement & { frameTask: Task });
+    }
+    deepGetElementsWithFrameTasks(child, elements);
+  }
+  return elements;
+};
+
+export const shallowGetTemporalElements = (
+  element: Element,
+  temporals: TemporalMixinInterface[] = [],
+) => {
+  for (const child of element.children) {
+    if (isEFTemporal(child)) {
+      temporals.push(child);
+    } else {
+      shallowGetTemporalElements(child, temporals);
+    }
+  }
+  return temporals;
+};
+
+export class OwnCurrentTimeController implements ReactiveController {
+  constructor(
+    private host: EFTimegroup,
+    private temporal: TemporalMixinInterface & LitElement,
+  ) {
+    host.addController(this);
+  }
+
+  hostUpdated() {
+    this.temporal.requestUpdate("ownCurrentTimeMs");
+  }
+
+  remove() {
+    this.host.removeController(this);
+  }
+}
+
+type Constructor<T = {}> = new (...args: any[]) => T;
+
+export const EFTemporal = <T extends Constructor<LitElement>>(
+  superClass: T,
+) => {
+  class TemporalMixinClass extends superClass {
+    ownCurrentTimeController?: OwnCurrentTimeController;
+
+    #parentTimegroup?: EFTimegroup;
+    @consume({ context: timegroupContext, subscribe: true })
+    @property({ attribute: false })
+    set parentTimegroup(value: EFTimegroup | undefined) {
+      this.#parentTimegroup = value;
+      this.ownCurrentTimeController?.remove();
+      this.rootTimegroup = this.getRootTimegroup();
+      if (this.rootTimegroup) {
+        this.ownCurrentTimeController = new OwnCurrentTimeController(
+          this.rootTimegroup,
+          this,
+        );
+      }
+    }
+    get parentTimegroup() {
+      return this.#parentTimegroup;
+    }
+
+    @property({
+      type: String,
+      attribute: "offset",
+      converter: durationConverter,
+    })
+    private _offsetMs = 0;
+
+    @property({
+      type: Number,
+      attribute: "duration",
+      converter: durationConverter,
+    })
+    private _durationMs?: number;
+
+    @state()
+    rootTimegroup?: EFTimegroup = this.getRootTimegroup();
+
+    private getRootTimegroup(): EFTimegroup | undefined {
+      let parent =
+        this.tagName === "EF-TIMEGROUP" ? this : this.parentTimegroup;
+      while (parent?.parentTimegroup) {
+        parent = parent.parentTimegroup;
+      }
+      return parent as EFTimegroup | undefined;
+    }
+
+    get hasOwnDuration() {
+      return false;
+    }
+
+    // Defining this as a getter to a private property allows us to
+    // override it classes that include this mixin.
+    get durationMs() {
+      const durationMs =
+        this._durationMs || this.parentTimegroup?.durationMs || 0;
+      return durationMs || 0;
+    }
+
+    get offsetMs() {
+      return this._offsetMs || 0;
+    }
+
+    get parentTemporal() {
+      let parent = this.parentElement;
+      while (parent && !isEFTemporal(parent)) {
+        parent = parent.parentElement;
+      }
+      return parent;
+    }
+
+    get startTimeWithinParentMs() {
+      if (!this.parentTemporal) {
+        return 0;
+      }
+      return this.startTimeMs - this.parentTemporal.startTimeMs;
+    }
+
+    get startTimeMs(): number {
+      const parentTimegroup = this.parentTimegroup;
+      if (!parentTimegroup) {
+        return 0;
+      }
+      switch (parentTimegroup.mode) {
+        case "sequence": {
+          const siblingTemorals = shallowGetTemporalElements(parentTimegroup);
+          const ownIndex = siblingTemorals.indexOf(this);
+          if (ownIndex === 0) {
+            return parentTimegroup.startTimeMs;
+          }
+          const previous = siblingTemorals[ownIndex - 1];
+          if (!previous) {
+            throw new Error("Previous temporal element not found");
+          }
+          return previous.startTimeMs + previous.durationMs;
+        }
+        case "contain":
+        case "fixed":
+          return parentTimegroup.startTimeMs + this.offsetMs;
+        default:
+          throw new Error(`Invalid time mode: ${parentTimegroup.mode}`);
+      }
+    }
+
+    get endTimeMs(): number {
+      return this.startTimeMs + this.durationMs;
+    }
+
+    get ownCurrentTimeMs() {
+      if (this.rootTimegroup) {
+        return Math.min(
+          Math.max(0, this.rootTimegroup.currentTimeMs - this.startTimeMs),
+          this.durationMs,
+        );
+      }
+      return 0;
+    }
+
+    frameTask = new Task(this, {
+      autoRun: EF_INTERACTIVE,
+      args: () => [this.ownCurrentTimeMs] as const,
+      task: async ([], { signal: _signal }) => {
+        let fullyUpdated = await this.updateComplete;
+        while (!fullyUpdated) {
+          fullyUpdated = await this.updateComplete;
+        }
+      },
+    });
+  }
+
+  Object.defineProperty(TemporalMixinClass.prototype, EF_TEMPORAL, {
+    value: true,
+  });
+
+  return TemporalMixinClass as unknown as Constructor<TemporalMixinInterface> &
+    T;
+};

package/src/elements/EFTimegroup.browsertest.ts

@@ -0,0 +1,333 @@
+import { describe, test, assert, beforeEach } from "vitest";
+import {
+  LitElement,
+  type TemplateResult,
+  html,
+  render as litRender,
+} from "lit";
+import { EFTimegroup } from "./EFTimegroup";
+import "./EFTimegroup";
+import { customElement } from "lit/decorators/custom-element.js";
+import { EFTemporal } from "./EFTemporal";
+
+beforeEach(() => {
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (typeof key !== "string") continue;
+    localStorage.removeItem(key);
+  }
+  while (document.body.children.length) {
+    document.body.children[0]?.remove();
+  }
+});
+
+@customElement("test-temporal")
+class TestTemporal extends EFTemporal(LitElement) {
+  get hasOwnDuration(): boolean {
+    return true;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "test-temporal": TestTemporal;
+  }
+}
+
+const renderTimegroup = (result: TemplateResult) => {
+  const container = document.createElement("div");
+  litRender(result, container);
+  const firstChild = container.firstElementChild;
+  if (!firstChild) {
+    throw new Error("No first child found");
+  }
+  if (!(firstChild instanceof EFTimegroup)) {
+    throw new Error("First child is not an EFTimegroup");
+  }
+  document.body.appendChild(firstChild);
+  return firstChild;
+};
+
+describe(`<ef-timegroup mode="fixed">`, () => {
+  test("can explicitly set a duration in seconds", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup mode="fixed" duration="10s"></ef-timegroup>`,
+    );
+    assert.equal(timegroup.durationMs, 10_000);
+  });
+
+  test("can explicitly set a duration in milliseconds", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup mode="fixed" duration="10ms"></ef-timegroup>`,
+    );
+    assert.equal(timegroup.durationMs, 10);
+  });
+});
+
+describe(`<ef-timegroup mode="sequence">`, () => {
+  test("fixed duration is ignored", () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup mode="sequence" duration="10s"></ef-timegroup>`,
+    );
+    assert.equal(timegroup.durationMs, 0);
+  });
+
+  test("duration is the sum of child time groups", async () => {
+    const timegroup = renderTimegroup(
+      html`
+        <ef-timegroup mode="sequence">
+          <ef-timegroup mode="fixed" duration="5s"></ef-timegroup>
+          <ef-timegroup mode="fixed" duration="5s"></ef-timegroup>
+        </ef-timegroup>
+      `,
+    );
+    assert.equal(timegroup.durationMs, 10_000);
+  });
+
+  test("duration can include any element with a durationMs value", async () => {
+    const timegroup = renderTimegroup(
+      html`
+        <ef-timegroup mode="sequence">
+          <ef-timegroup mode="fixed" duration="5s"></ef-timegroup>
+          <test-temporal duration="5s"></test-temporal>
+        </ef-timegroup>
+      `,
+    );
+
+    assert.equal(timegroup.durationMs, 10_000);
+  });
+
+  test("arbitrary html does not factor into the calculation of a sequence duration", () => {
+    const timegroup = renderTimegroup(
+      html`
+        <ef-timegroup mode="sequence">
+          <div>
+            <ef-timegroup mode="fixed" duration="5s"></ef-timegroup>
+          </div>
+        </ef-timegroup>
+      `,
+    );
+    assert.equal(timegroup.durationMs, 5_000);
+  });
+
+  test("nested time groups do not factor into the calculation of a sequence duration", async () => {
+    const timegroup = renderTimegroup(
+      html`
+        <ef-timegroup mode="sequence">
+          <ef-timegroup mode="fixed" duration="5s">
+            <ef-timegroup mode="fixed" duration="5s"></ef-timegroup>
+          </ef-timegroup>
+        </ef-timegroup>
+      `,
+    );
+    assert.equal(timegroup.durationMs, 5_000);
+  });
+});
+
+describe(`<ef-timegroup mode="contain">`, () => {
+  test("fixed duration is ignored", () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup mode="contain" duration="10s"></ef-timegroup>`,
+    );
+    assert.equal(timegroup.durationMs, 0);
+  });
+
+  test("duration is the maximum of it's child time groups", async () => {
+    const timegroup = renderTimegroup(
+      html`
+        <ef-timegroup mode="contain">
+          <ef-timegroup mode="fixed" duration="5s"></ef-timegroup>
+          <ef-timegroup mode="fixed" duration="10s"></ef-timegroup>
+        </ef-timegroup>
+      `,
+    );
+    assert.equal(timegroup.durationMs, 10_000);
+  });
+});
+
+describe("startTimeMs", () => {
+  test("is computed relative to the root time group", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup id="root" mode="sequence">
+        <ef-timegroup id="a" mode="fixed" duration="5s"></ef-timegroup>
+        <ef-timegroup id="b" mode="sequence">
+          <ef-timegroup id="c" mode="fixed" duration="5s"></ef-timegroup>
+          <ef-timegroup id="d" mode="contain">
+            <ef-timegroup id="e" mode="fixed" duration="5s"></ef-timegroup>
+            <ef-timegroup id="f" mode="fixed" duration="5s"></ef-timegroup>
+          </ef-timegroup>
+        </ef-timegroup>
+      </ef-timegroup>`,
+    );
+
+    const a = timegroup.querySelector("#a") as EFTimegroup;
+    const b = timegroup.querySelector("#b") as EFTimegroup;
+    const c = timegroup.querySelector("#c") as EFTimegroup;
+    const d = timegroup.querySelector("#d") as EFTimegroup;
+    const e = timegroup.querySelector("#e") as EFTimegroup;
+    const f = timegroup.querySelector("#f") as EFTimegroup;
+
+    assert.equal(a.startTimeMs, 0);
+    assert.equal(b.startTimeMs, 5_000);
+    assert.equal(c.startTimeMs, 5_000);
+    assert.equal(d.startTimeMs, 10_000);
+    assert.equal(e.startTimeMs, 10_000);
+    assert.equal(f.startTimeMs, 10_000);
+  });
+
+  //   // TODO: Rethink offset math, it shouldn't effect the duration of a temporal item
+  //   // but actually change the start and end time.
+  //   litTest.skip("can be offset with offset attribute", async ({ container }) => {
+  //     render(
+  //       html`<ef-timegroup id="root" mode="contain">
+  //         <test-temporal id="a" duration="5s" offset="5s"></test-temporal>
+  //       </ef-timegroup> `,
+  //       container,
+  //     );
+
+  //     const root = container.querySelector("#root") as EFTimegroup;
+  //     const a = container.querySelector("#a") as TestTemporal;
+
+  //     assert.equal(a.durationMs, 5_000);
+  //     assert.equal(root.durationMs, 10_000);
+  //     assert.equal(a.startTimeMs, 5_000);
+  //   });
+
+  // litTest.skip(
+  //   "offsets do not affect start time when in a sequence group",
+  //   async ({ container }) => {
+  //     render(
+  //       html`<ef-timegroup id="root" mode="sequence">
+  //         <test-temporal id="a" duration="5s"></test-temporal>
+  //         <test-temporal id="b" duration="5s" offset="5s"></test-temporal>
+  //       </ef-timegroup> `,
+  //       container,
+  //     );
+
+  //     const root = container.querySelector("#root") as EFTimegroup;
+  //     const a = container.querySelector("#a") as TestTemporal;
+  //     const b = container.querySelector("#b") as TestTemporal;
+
+  //     assert.equal(root.durationMs, 10_000);
+  //     assert.equal(a.startTimeMs, 0);
+  //     assert.equal(b.startTimeMs, 5_000);
+  //   },
+  // );
+
+  test("temporal elements default to expand to fill a timegroup", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup id="root" mode="fixed" duration="10s">
+        <test-temporal id="a"></test-temporal>
+      </ef-timegroup> `,
+    );
+
+    const a = timegroup.querySelector("#a") as TestTemporal;
+
+    assert.equal(timegroup.durationMs, 10_000);
+    assert.equal(a.durationMs, 10_000);
+  });
+
+  test("element's parentTimegroup updates as they move", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const timegroup1 = document.createElement("ef-timegroup");
+    timegroup1.setAttribute("mode", "fixed");
+    timegroup1.setAttribute("duration", "5s");
+
+    const timegroup2 = document.createElement("ef-timegroup");
+    timegroup2.setAttribute("mode", "fixed");
+    timegroup2.setAttribute("duration", "5s");
+
+    container.appendChild(timegroup1);
+    container.appendChild(timegroup2);
+
+    const temporal = document.createElement("test-temporal");
+
+    timegroup1.appendChild(temporal);
+
+    assert.equal(temporal.parentTimegroup, timegroup1);
+
+    timegroup2.appendChild(temporal);
+    assert.equal(temporal.parentTimegroup, timegroup2);
+  });
+
+  test("elements can access their root temporal element", async () => {
+    const root = renderTimegroup(
+      html`<ef-timegroup id="root" mode="contain" duration="10s">
+        <ef-timegroup id="a" mode="contain">
+          <div>
+            <ef-timegroup id="b" mode="contain">
+              <div>
+                <test-temporal id="c" duration="5s"></test-temporal>
+              </div>
+            </ef-timegroup>
+          </div>
+        </ef-timegroup>
+      </ef-timegroup> `,
+    );
+
+    const a = root.querySelector("#a") as EFTimegroup;
+    const b = root.querySelector("#b") as EFTimegroup;
+    const c = root.querySelector("#c") as TestTemporal;
+
+    assert.equal(root.rootTimegroup, root);
+
+    assert.equal(a.rootTimegroup, root);
+    assert.equal(b.rootTimegroup, root);
+    assert.equal(c.rootTimegroup, root);
+  });
+});
+
+describe("setting currentTime", () => {
+  test("persists in localStorage if the timegroup has an id and is in the dom", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup id="root" mode="fixed" duration="10s"></ef-timegroup>`,
+    );
+    document.body.appendChild(timegroup);
+    assert.isNull(localStorage.getItem(timegroup.storageKey));
+    timegroup.currentTime = 5_000;
+    assert.equal(localStorage.getItem(timegroup.storageKey), "5000");
+    timegroup.remove();
+  });
+
+  test("does not persist in localStorage if the timegroup has no id", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup mode="fixed" duration="10s"></ef-timegroup>`,
+    );
+    document.body.appendChild(timegroup);
+    timegroup.currentTime = 5_000;
+    timegroup.removeAttribute("id");
+    assert.throws(() => {
+      assert.isNull(localStorage.getItem(timegroup.storageKey));
+    }, "Timegroup must have an id to use localStorage");
+    timegroup.remove();
+  });
+
+  test("nested items derive their ownCurrentTimeMs", async () => {
+    const timegroup = renderTimegroup(
+      html`
+        <ef-timegroup id="root" mode="sequence">
+          <ef-timegroup id="a" mode="fixed" duration="5s"> </ef-timegroup>
+          <ef-timegroup id="b" mode="fixed" duration="5s"> </ef-timegroup>
+        </ef-timegroup>
+      `,
+    );
+
+    const root = timegroup;
+    const a = timegroup.querySelector("#a") as EFTimegroup;
+    const b = timegroup.querySelector("#b") as EFTimegroup;
+
+    assert.equal(a.ownCurrentTimeMs, 0);
+    assert.equal(b.ownCurrentTimeMs, 0);
+
+    root.currentTimeMs = 2_500;
+
+    assert.equal(a.ownCurrentTimeMs, 2_500);
+    assert.equal(b.ownCurrentTimeMs, 0);
+
+    root.currentTimeMs = 7_500;
+
+    assert.equal(a.ownCurrentTimeMs, 5_000);
+    assert.equal(b.ownCurrentTimeMs, 2_500);
+  });
+});