@editframe/elements 0.12.0-beta.8 → 0.13.0-beta.1

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@editframe/elements",
-  "version": "0.12.0-beta.8",
+  "version": "0.13.0-beta.1",
   "description": "",
   "exports": {
     ".": {
       "import": {
         "types": "./dist/index.d.ts",
-        "default": "./dist/elements/src/index.js"
+        "default": "./dist/index.js"
       }
     },
     "./styles.css": "./dist/style.css"
@@ -15,12 +15,13 @@
   "scripts": {
     "typecheck": "tsc --noEmit --emitDeclarationOnly false",
     "build": "vite build",
-    "build:watch": "vite build --watch"
+    "build:watch": "vite build --watch",
+    "typedoc": "typedoc --json ../../docs/elements.json --plugin typedoc-plugin-zod --excludeExternals ./src"
   },
   "author": "",
   "license": "UNLICENSED",
   "dependencies": {
-    "@editframe/assets": "0.12.0-beta.8",
+    "@editframe/assets": "0.13.0-beta.1",
     "@lit/context": "^1.1.2",
     "@lit/task": "^1.0.1",
     "d3": "^7.9.0",

package/src/elements/EFAudio.ts

@@ -1,8 +1,8 @@
+import { Task } from "@lit/task";
 import { html } from "lit";
-import { createRef, ref } from "lit/directives/ref.js";
 import { customElement, property } from "lit/decorators.js";
-import { EFMedia } from "./EFMedia.ts";
-import { Task } from "@lit/task";
+import { createRef, ref } from "lit/directives/ref.js";
+import { EFMedia } from "./EFMedia.js";
 
 @customElement("ef-audio")
 export class EFAudio extends EFMedia {

package/src/elements/EFCaptions.browsertest.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import "../gui/EFPreview.ts";
-import "./EFCaptions.ts";
-import "./EFVideo.ts";
+import "../gui/EFPreview.js";
+import "./EFCaptions.js";
+import "./EFVideo.js";
 import { v4 } from "uuid";
 
 describe("EFCaptions", () => {

package/src/elements/EFCaptions.ts

@@ -1,15 +1,15 @@
 import { Task } from "@lit/task";
 import { LitElement, type PropertyValueMap, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
-import type { GetISOBMFFFileTranscriptionResult } from "../../../api/src/index.ts";
-import { EF_INTERACTIVE } from "../EF_INTERACTIVE.ts";
-import { EF_RENDERING } from "../EF_RENDERING.ts";
-import { CrossUpdateController } from "./CrossUpdateController.ts";
-import { EFAudio } from "./EFAudio.ts";
-import { EFSourceMixin } from "./EFSourceMixin.ts";
-import { EFTemporal } from "./EFTemporal.ts";
-import { EFVideo } from "./EFVideo.ts";
-import { FetchMixin } from "./FetchMixin.ts";
+import type { GetISOBMFFFileTranscriptionResult } from "../../../api/src/index.js";
+import { EF_INTERACTIVE } from "../EF_INTERACTIVE.js";
+import { EF_RENDERING } from "../EF_RENDERING.js";
+import { CrossUpdateController } from "./CrossUpdateController.js";
+import { EFAudio } from "./EFAudio.js";
+import { EFSourceMixin } from "./EFSourceMixin.js";
+import { EFTemporal } from "./EFTemporal.js";
+import { EFVideo } from "./EFVideo.js";
+import { FetchMixin } from "./FetchMixin.js";
 
 interface WordSegment {
   text: string;

package/src/elements/EFImage.browsertest.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import "./EFImage.ts";
-import "../gui/EFPreview.ts";
+import "./EFImage.js";
+import "../gui/EFPreview.js";
 import { v4 } from "uuid";
 
 describe("EFImage", () => {

package/src/elements/EFImage.ts

@@ -2,10 +2,10 @@ import { Task } from "@lit/task";
 import { LitElement, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { createRef, ref } from "lit/directives/ref.js";
-import { EF_INTERACTIVE } from "../EF_INTERACTIVE.ts";
-import { EF_RENDERING } from "../EF_RENDERING.ts";
-import { EFSourceMixin } from "./EFSourceMixin.ts";
-import { FetchMixin } from "./FetchMixin.ts";
+import { EF_INTERACTIVE } from "../EF_INTERACTIVE.js";
+import { EF_RENDERING } from "../EF_RENDERING.js";
+import { EFSourceMixin } from "./EFSourceMixin.js";
+import { FetchMixin } from "./FetchMixin.js";
 
 @customElement("ef-image")
 export class EFImage extends EFSourceMixin(FetchMixin(LitElement), {

package/src/elements/EFMedia.browsertest.ts

@@ -1,12 +1,12 @@
 import { customElement } from "lit/decorators.js";
 import { v4 } from "uuid";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import { EFMedia } from "./EFMedia.ts";
-import "../gui/EFWorkbench.ts";
-import "../gui/EFPreview.ts";
-import "./EFTimegroup.ts";
-import { createTestFragmentIndex } from "TEST/createTestFragmentIndex.ts";
-import { useMockWorker } from "TEST/useMockWorker.ts";
+import { EFMedia } from "./EFMedia.js";
+import "../gui/EFWorkbench.js";
+import "../gui/EFPreview.js";
+import "./EFTimegroup.js";
+import { createTestFragmentIndex } from "TEST/createTestFragmentIndex.js";
+import { useMockWorker } from "TEST/useMockWorker.js";
 import { http, HttpResponse } from "msw";
 
 @customElement("test-media")

package/src/elements/EFMedia.ts

@@ -10,12 +10,12 @@ import type { TrackFragmentIndex, TrackSegment } from "@editframe/assets";
 
 import { VideoAsset } from "@editframe/assets/EncodedAsset.js";
 import { MP4File } from "@editframe/assets/MP4File.js";
-import { EF_INTERACTIVE } from "../EF_INTERACTIVE.ts";
-import { EF_RENDERING } from "../EF_RENDERING.ts";
-import { apiHostContext } from "../gui/apiHostContext.ts";
-import { EFSourceMixin } from "./EFSourceMixin.ts";
-import { EFTemporal, isEFTemporal } from "./EFTemporal.ts";
-import { FetchMixin } from "./FetchMixin.ts";
+import { EF_INTERACTIVE } from "../EF_INTERACTIVE.js";
+import { EF_RENDERING } from "../EF_RENDERING.js";
+import { apiHostContext } from "../gui/apiHostContext.js";
+import { EFSourceMixin } from "./EFSourceMixin.js";
+import { EFTemporal, isEFTemporal } from "./EFTemporal.js";
+import { FetchMixin } from "./FetchMixin.js";
 
 const log = debug("ef:elements:EFMedia");
 
@@ -54,6 +54,12 @@ export class EFMedia extends EFSourceMixin(EFTemporal(FetchMixin(LitElement)), {
   efHost?: string;
 
   #assetId: string | null = null;
+
+  /**
+   * The unique identifier for the media asset.
+   * This property can be set programmatically or via the "asset-id" attribute.
+   * @domAttribute "asset-id"
+   */
   @property({ type: String, attribute: "asset-id", reflect: true })
   set assetId(value: string | null) {
     this.#assetId = value;
@@ -314,9 +320,10 @@ export class EFMedia extends EFSourceMixin(EFTemporal(FetchMixin(LitElement)), {
       this.style.display = "";
 
       const animations = this.getAnimations({ subtree: true });
+
       this.style.setProperty("--ef-duration", `${this.durationMs}ms`);
       this.style.setProperty(
-        "--ef-transition--duration",
+        "--ef-transition-duration",
         `${this.parentTimegroup?.overlapMs ?? 0}ms`,
       );
       this.style.setProperty(

package/src/elements/EFSourceMixin.ts

@@ -1,9 +1,9 @@
 import { consume } from "@lit/context";
-import type { LitElement } from "lit";
-import { state } from "lit/decorators/state.js";
 import { Task } from "@lit/task";
+import type { LitElement } from "lit";
 import { property } from "lit/decorators/property.js";
-import { apiHostContext } from "../gui/apiHostContext.ts";
+import { state } from "lit/decorators/state.js";
+import { apiHostContext } from "../gui/apiHostContext.js";
 
 export declare class EFSourceMixinInterface {
   apiHost?: string;

package/src/elements/EFTemporal.browsertest.ts

@@ -1,7 +1,7 @@
 import { LitElement } from "lit";
 import { customElement } from "lit/decorators/custom-element.js";
 import { describe, expect, test } from "vitest";
-import { EFTemporal } from "./EFTemporal.ts";
+import { EFTemporal } from "./EFTemporal.js";
 
 @customElement("test-temporal")
 class TestTemporal extends EFTemporal(LitElement) {}

package/src/elements/EFTemporal.ts

@@ -1,11 +1,11 @@
 import { consume, createContext } from "@lit/context";
 import type { LitElement, ReactiveController } from "lit";
 import { property, state } from "lit/decorators.js";
-import type { EFTimegroup } from "./EFTimegroup.ts";
+import type { EFTimegroup } from "./EFTimegroup.js";
 
 import { Task } from "@lit/task";
-import { EF_INTERACTIVE } from "../EF_INTERACTIVE.ts";
-import { durationConverter } from "./durationConverter.ts";
+import { EF_INTERACTIVE } from "../EF_INTERACTIVE.js";
+import { durationConverter } from "./durationConverter.js";
 
 export const timegroupContext = createContext<EFTimegroup>(
   Symbol("timeGroupContext"),
@@ -13,14 +13,76 @@ export const timegroupContext = createContext<EFTimegroup>(
 
 export declare class TemporalMixinInterface {
   get hasOwnDuration(): boolean;
+
+  /**
+   * Used to trim the start of the media.
+   *
+   * This can be set in either seconds or milliseconds.
+   *
+   * For example, `trimstart="10s"` is equivalent to `trimstart="10000ms"`.
+   *
+   * @domAttribute "trimstart"
+   */
   get trimStartMs(): number;
+
+  /**
+   * Used to trim the end of the media.
+   *
+   * This can be set in either seconds or milliseconds.
+   *
+   * For example, `trimend="10s"` is equivalent to `trimend="10000ms"`.
+   *
+   * @domAttribute "trimend"
+   */
   get trimEndMs(): number;
+
   set trimStartMs(value: number);
   set trimEndMs(value: number);
   set trimstart(value: string);
   set trimend(value: string);
 
+  /**
+   * The source in time of the element.
+   *
+   * This is an amount of time to trim off the beginning of the media.
+   *
+   * This can be set in either seconds or milliseconds.
+   *
+   * For example, `sourcein="10s"` is equivalent to `sourcein="10000ms"`.
+   *
+   * If the sourcein time is greater than the duration of the media, the media
+   * will not be played.
+   *
+   * If the media is 20 seconds long, and the `sourcein` value is set to `10s`, the
+   * media will play for 10 seconds, starting at the 10 second mark.
+   *
+   * Can be used in conjunction with `sourceout` to create a trimmed media.
+   *
+   * @domAttribute "sourcein"
+   */
   get sourceInMs(): number;
+
+  /**
+   * The source out time of the element.
+   *
+   * This is the point in time in the media that will be treated as the end of
+   * the media.
+   *
+   * This can be set in either seconds or milliseconds.
+   *
+   * For example, `sourceout="10s"` is equivalent to `sourceout="10000ms"`.
+   *
+   * If the sourceout time is greater than the duration of the media, the media
+   * will play until the end of the media.
+   *
+   * If the media is 20 seconds long, and the `sourceout` value is set to `10s`,
+   * the media will play for 10 seconds, starting at zero seconds and ending at
+   * the 10 second mark.
+   *
+   * Can be used in conjunction with `sourcein` to create a trimmed media.
+   *
+   * @domAttribute "sourceout"
+   */
   get sourceOutMs(): number;
 
   set sourceInMs(value: number);
@@ -28,17 +90,106 @@ export declare class TemporalMixinInterface {
   set sourcein(value: string);
   set sourceout(value: string);
 
+  /**
+   * @domAttribute "duration"
+   */
   get durationMs(): number;
+
+  /**
+   * The start time of the element within its root timegroup in milliseconds.
+   *
+   * This is an absolute time according to the highest scoped timegroup the media element is contained within.
+   *
+   * The calculated value will depend on the mode of the timegroup and the offset of the media element.
+   *
+   * If the parent time group is in `sequence` mode, the start time will be the
+   * start time of the previous sibling element plus the previous sibling's duration
+   * minus the overlap of the previous sibling and the current sibling.
+   *
+   * If the parent time group is in `contain` or `fixed` mode, the start time will be
+   * the start time of the parent time group plus the offset of the media element.
+   */
   get startTimeMs(): number;
-  get startTimeWithinParentMs(): number;
+  /**
+   * The end time of the element within its root timegroup in milliseconds.
+   *
+   * This is an absolute time according to the highest scoped timegroup the media
+   * element is contained within. Computed by adding the media's duration to its
+   * start time.
+   *
+   * If the media element has been trimmed, its end time will be calculated according it
+   * its trimmed duration, not its original duration.
+   */
   get endTimeMs(): number;
+  /**
+   * The start time of the element within its parent timegroup in milliseconds.
+   *
+   * This is a relative time according to the closest timegroup the media element
+   * is contained within. Unless the media element has been given any kind of specific offset
+   * it is common for this time to be zero.
+   */
+  get startTimeWithinParentMs(): number;
+
+  /**
+   * The current time of the element in milliseconds.
+   *
+   * This is a relative time according to the closest timegroup the media element
+   * is contained within.
+   *
+   * This is suitable for determining the percentage of the media that has been
+   * played.
+   */
   get ownCurrentTimeMs(): number;
+  /**
+   * The current time of the element in milliseconds, adjusted for trimming.
+   *
+   * This is suitable for mapping to internal media time codes for audio/video
+   * elements.
+   *
+   * For example, if the media has a `sourcein` value of 10s, when `ownCurrentTimeMs` is 0s,
+   * `trimAdjustedOwnCurrentTimeMs` will be 10s.
+   *
+   *            sourcein=10s     sourceout=10s
+   * /         /                /
+   * |--------|=================|---------|
+   *          ^
+   *          |_
+   *            trimAdjustedOwnCurrentTimeMs === 10s
+   *          |_
+   *            ownCurrentTimeMs === 0s
+   */
   get trimAdjustedOwnCurrentTimeMs(): number;
 
   set duration(value: string);
   get duration(): string;
 
+  /**
+   * The offset of the element within its parent timegroup in milliseconds.
+   *
+   * This can be set in either seconds or milliseconds.
+   *
+   * For example, `offset="10s"` is equivalent to `offset="10000ms"`.
+   *
+   * This can be used to create a negative or positive offset for the start time of the media.
+   *
+   * This will change the start time of the media relative to it's otherwise normal start time.
+   *
+   * The duration of the element, or it's parent, or the start and end time of it's temporal siblings will not
+   * be affected by this offset.
+   *
+   * @domAttribute "offset"
+   */
+  set offset(value: string);
+  get offset(): string;
+
+  /**
+   * A convenience property for getting the nearest containing timegroup of the media element.
+   */
   parentTimegroup?: EFTimegroup;
+
+  /**
+   * A convenience property for getting the root timegroup of the media element.
+   */
   rootTimegroup?: EFTimegroup;
 
   frameTask: Task<readonly unknown[], unknown>;
@@ -151,6 +302,7 @@ export const EFTemporal = <T extends Constructor<LitElement>>(
         );
       }
     }
+
     get parentTimegroup() {
       return this.#parentTimegroup;
     }
@@ -340,6 +492,9 @@ export const EFTemporal = <T extends Constructor<LitElement>>(
       return parent;
     }
 
+    /**
+     * The start time of the element within its parent timegroup.
+     */
     get startTimeWithinParentMs() {
       if (!this.parentTemporal) {
         return 0;

package/src/elements/EFTimegroup.browsertest.ts

@@ -5,13 +5,13 @@ import {
   render as litRender,
 } from "lit";
 import { assert, beforeEach, describe, test } from "vitest";
-import { EFTimegroup } from "./EFTimegroup.ts";
-import "./EFTimegroup.ts";
+import { EFTimegroup } from "./EFTimegroup.js";
+import "./EFTimegroup.js";
 import { customElement } from "lit/decorators/custom-element.js";
-import { ContextMixin } from "../gui/ContextMixin.ts";
-import { EFTemporal } from "./EFTemporal.ts";
+import { ContextMixin } from "../gui/ContextMixin.js";
+import { EFTemporal } from "./EFTemporal.js";
 // Need workbench to make workbench wrapping occurs
-import "../gui/EFWorkbench.ts";
+import "../gui/EFWorkbench.js";
 
 beforeEach(() => {
   for (let i = 0; i < localStorage.length; i++) {