@preference-sl/pref-viewer 2.16.0 → 2.16.2-beta.0

package/index.d.ts

@@ -1,24 +1,385 @@
 import type React from "react";
 
+/** Render mode. `loadConfig`/`loadDrawing` pick the matching one on their own. */
+export type PrefViewerMode = "2d" | "3d";
+
+/** Animation state as reported by `getAnimations()` and `prefviewer-animation-changed`. */
+export type PrefViewerAnimationState = 0 | 1 | 2 | 3 | 4;
+
+/** Action accepted by `playAnimation`. */
+export type PrefViewerAnimationAction = "open" | "close" | "pause" | "goToOpened" | "goToClosed";
+
+/**
+ * An IndexedDB pointer. The SDK writes the asset and hands you the record id;
+ * the viewer reads it back itself, so you never fetch or decode the bytes.
+ */
+export interface PrefViewerStoragePointer {
+  db: string;
+  table: string;
+  id: string;
+}
+
+/** A storage pointer or a plain URL — every asset slot accepts either. */
+export type PrefViewerSource = PrefViewerStoragePointer | { url: string };
+
+export interface PrefViewerAsset {
+  storage: PrefViewerSource;
+  visible?: boolean;
+}
+
+/** Payload for `loadConfig`. Pass the object; a JSON string is also accepted. */
+export interface PrefViewerConfig {
+  model?: PrefViewerAsset;
+  scene?: PrefViewerAsset;
+  materials?: PrefViewerAsset;
+  drawing?: PrefViewerAsset;
+  options?: Record<string, unknown>;
+}
+
+export interface PrefViewerAnimation {
+  name: string;
+  state: PrefViewerAnimationState;
+  progress: number;
+  loop: boolean;
+  nodes: string[];
+}
+
+/**
+ * `<pref-viewer>` shadows the standard `Element.getAnimations()` with its own snapshot of the
+ * model's opening animations. The two signatures are incompatible, so the method is not declared
+ * on `PrefViewer` — reach it through this view:
+ *
+ * ```ts
+ * const animations = (viewer as unknown as PrefViewerAnimationsApi).getAnimations()
+ * ```
+ */
+export interface PrefViewerAnimationsApi {
+  getAnimations(): PrefViewerAnimation[];
+}
+
+// ── Semantic selection and turnable state ──
+
+export interface PrefViewerSelectionItem {
+  id: string;
+  highlights: string[];
+}
+
+export interface PrefViewerSelectionDescriptor {
+  id?: string;
+  Id?: string;
+  highlights?: string[];
+  Highlights?: string[];
+}
+
+export interface PrefViewerSelectionState {
+  selectableIds: string[];
+  selectedIds: string[];
+  selectedItems: PrefViewerSelectionItem[];
+}
+
+export type PrefViewerElementDescriptor = string | { id?: string; Id?: string };
+
+export interface PrefViewerSelectionInput {
+  selectableIds?: PrefViewerElementDescriptor[];
+  selectables?: PrefViewerElementDescriptor[];
+  selectedItems?: Array<string | PrefViewerSelectionDescriptor>;
+  selectedIds?: PrefViewerElementDescriptor[];
+  selected?: Array<string | PrefViewerSelectionDescriptor>;
+}
+
+export interface PrefViewerElementClickDetail {
+  ids: string[];
+}
+
+/** Optional speed/direction for `startTurnable` / `toggleTurnable`. */
+export interface PrefViewerTurnableOptions {
+  speed?: number;
+  direction?: string;
+}
+
+export interface PrefViewerTurnableState {
+  running: boolean;
+  speed: number;
+  direction: string;
+}
+
+// ── Event details ──
+
+/** Which containers a load touched, and which of them succeeded. */
+export interface PrefViewerContainerFlags {
+  model?: boolean;
+  scene?: boolean;
+  materials?: boolean;
+}
+
+export interface PrefViewerSceneLoadedDetail {
+  tried: PrefViewerContainerFlags;
+  success: PrefViewerContainerFlags;
+}
+
+export interface PrefViewerSceneOptionsDetail {
+  success: boolean;
+  detail: PrefViewerSceneLoadedDetail;
+}
+
+export interface PrefViewerDrawingLoadedDetail {
+  success: boolean;
+  error: Error | null;
+}
+
+export interface PrefViewerErrorDetail {
+  error: Error;
+}
+
+export interface PrefViewerAnimationChangedDetail {
+  name: string;
+  state: PrefViewerAnimationState;
+  progress: number;
+  loop: boolean;
+}
+
+export interface PrefViewerInitializedDetail {
+  isInitialized: boolean;
+}
+
+/** The 2D pan/zoom viewport, as reported after every pan or zoom. */
+export interface PrefViewerViewportChangedDetail {
+  x: number;
+  y: number;
+  scale: number;
+  moved: boolean;
+  scaled: boolean;
+  maximized: boolean;
+  minimized: boolean;
+}
+
+/**
+ * Root-scoped events (`pref-viewer-loading` / `-loaded` / `-error`) fire for both modes and
+ * carry the mode they happened in; the 2D- and 3D-scoped events do not.
+ */
+export interface PrefViewerRootLoadingDetail {
+  mode: PrefViewerMode;
+}
+
+export interface PrefViewerRootLoadedDetail {
+  mode: PrefViewerMode;
+  result: PrefViewerSceneLoadedDetail | PrefViewerDrawingLoadedDetail | null;
+}
+
+export interface PrefViewerRootErrorDetail {
+  mode: PrefViewerMode;
+  error: Error | null;
+}
+
+/**
+ * Events dispatched by `<pref-viewer>`. All bubble and are composed, so a listener
+ * on an ancestor outside the shadow root still receives them.
+ *
+ * The `scene-*` / `drawing-*` names are the legacy aliases: each is still emitted
+ * alongside its `pref-viewer-3d-*` / `pref-viewer-2d-*` equivalent, with the same detail.
+ */
+export interface PrefViewerEventMap {
+  "pref-viewer-initialized": CustomEvent<PrefViewerInitializedDetail>;
+
+  // Root scope — either mode, and the detail says which.
+  "pref-viewer-loading": CustomEvent<PrefViewerRootLoadingDetail>;
+  "pref-viewer-loaded": CustomEvent<PrefViewerRootLoadedDetail>;
+  "pref-viewer-error": CustomEvent<PrefViewerRootErrorDetail>;
+
+  // 3D scope (and its legacy aliases).
+  "pref-viewer-3d-loading": CustomEvent<undefined>;
+  "pref-viewer-3d-loaded": CustomEvent<PrefViewerSceneLoadedDetail | Record<string, never>>;
+  "pref-viewer-3d-error": CustomEvent<PrefViewerErrorDetail | Record<string, never>>;
+  "pref-viewer-3d-turnable-changed": CustomEvent<{ state: PrefViewerTurnableState }>;
+  "scene-loading": CustomEvent<undefined>;
+  "scene-loaded": CustomEvent<PrefViewerSceneLoadedDetail | undefined>;
+  "scene-error": CustomEvent<PrefViewerErrorDetail>;
+
+  // 2D scope (and its legacy aliases).
+  "pref-viewer-2d-loading": CustomEvent<undefined>;
+  "pref-viewer-2d-loaded": CustomEvent<PrefViewerDrawingLoadedDetail | Record<string, never>>;
+  "pref-viewer-2d-error": CustomEvent<PrefViewerErrorDetail | Record<string, never>>;
+  "pref-viewer-2d-viewport-changed": CustomEvent<PrefViewerViewportChangedDetail>;
+  "pref-viewer-2d-element-click": CustomEvent<PrefViewerElementClickDetail>;
+  "drawing-loading": CustomEvent<undefined>;
+  "drawing-loaded": CustomEvent<PrefViewerDrawingLoadedDetail>;
+  "drawing-error": CustomEvent<PrefViewerErrorDetail>;
+  "drawing-zoom-changed": CustomEvent<{ zoom: number }>;
+
+  // Semantic selection.
+  "pref-viewer-element-click": CustomEvent<PrefViewerElementClickDetail>;
+  "pref-viewer-selection-state-changed": CustomEvent<PrefViewerSelectionState>;
+
+  /** Re-dispatched from the 3D component; not emitted by the root element. */
+  "prefviewer-animation-changed": CustomEvent<PrefViewerAnimationChangedDetail>;
+}
+
 export declare class PrefViewer extends HTMLElement {
-  /**
-   * The URL or blob string of the GLTF model
-   */
-  set model(v: string | null);
+  // ── Property setters (each mirrors the attribute of the same name) ──
+  set config(v: PrefViewerConfig | string | null);
+  set culture(v: string | null);
+  set drawing(v: PrefViewerAsset | string | null);
+  set materials(v: PrefViewerAsset | string | null);
+  set mode(v: PrefViewerMode | null);
+  /** The URL or storage pointer of the glTF model. */
+  set model(v: PrefViewerAsset | string | null);
+  set options(v: Record<string, unknown> | string | null);
+  set scene(v: PrefViewerAsset | string | null);
+  /** Supported style overrides; currently `{ colorPrimary }`. */
+  set styles(v: Record<string, unknown> | string | null);
+
+  // ── Read-only state ──
+  get culture(): string;
+  get isInitialized(): boolean;
+  get isLoaded(): boolean;
+  get isLoading(): boolean;
+
+  // ── Loading ──
+  /** Returns false when the config is unusable; otherwise queues the work. */
+  loadConfig(config: PrefViewerConfig | string): boolean | void;
+  loadDrawing(drawing: PrefViewerAsset | string): boolean | void;
+  loadMaterials(materials: PrefViewerAsset | string): boolean | void;
+  loadModel(model: PrefViewerAsset | string): boolean | void;
+  loadScene(scene: PrefViewerAsset | string): boolean | void;
+
+  // ── Runtime ──
+  setCulture(cultureId: string): void;
+  setMode(mode?: PrefViewerMode): void;
+  /** Cheaper than a full `loadConfig` when only options changed — no visible reload. */
+  setOptions(options: Record<string, unknown> | string): void;
+  /** Convenience wrapper for `setOptions({ ibl })`. False when the payload is unusable. */
+  setIBL(ibl: Record<string, unknown> | string): boolean | void;
+  /** Runtime style overrides; currently `{ colorPrimary }`. False when unusable. */
+  setStyles(styles: Record<string, unknown> | string): boolean | void;
+  /** 3D runtime diagnostics, or null before the 3D component exists. */
+  getDebugInfo(): Record<string, unknown> | null;
+
+  // ── Visibility and framing ──
+  showModel(): void;
+  hideModel(): void;
+  showScene(): void;
+  hideScene(): void;
+  zoomCenter(): void;
+  zoomExtentsAll(): void;
+  zoomIn(): void;
+  zoomOut(): void;
+
+  // ── Semantic selection ──
+  setSelectableElements(elements?: PrefViewerElementDescriptor[]): PrefViewerSelectionState;
+  setSelectedElements(elements?: Array<string | PrefViewerSelectionDescriptor>): PrefViewerSelectionState;
+  applySelectionState(state?: PrefViewerSelectionInput): PrefViewerSelectionState;
+  clearSelectedElements(): PrefViewerSelectionState;
+  clearSelectableElements(): PrefViewerSelectionState;
+  clearSelectionState(): PrefViewerSelectionState;
+  getSelectionState(): PrefViewerSelectionState;
+  notifyElementClick(
+    element: PrefViewerElementDescriptor | PrefViewerElementDescriptor[] | { ids: PrefViewerElementDescriptor[] },
+  ): void;
+  appendSvgNode(id: string, svgId: string, svg: SVGElement): boolean;
+  removeAppendedSvgNodes(): void;
+
+  // ── Turnable (auto-rotate) state ──
+  startTurnable(options?: PrefViewerTurnableOptions): PrefViewerTurnableState;
+  stopTurnable(): PrefViewerTurnableState;
+  toggleTurnable(options?: PrefViewerTurnableOptions): PrefViewerTurnableState;
+  getTurnableState(): PrefViewerTurnableState;
+
+  // ── Dialog ──
+  openDialog(title: string, content: string | Node, footer?: string | Node): void;
+  closeDialog(): void;
+
+  // ── Animations (3D only) ──
+  // `getAnimations()` is deliberately absent here: the component shadows the standard
+  // `Element.getAnimations()` with an incompatible return, and TypeScript cannot model an
+  // incompatible override without making PrefViewer unassignable to HTMLElement. Read it
+  // through PrefViewerAnimationsApi instead. Renaming the runtime method would fix this
+  // properly, but that is a breaking change for the component's API (TEC-3490).
+  /** False when no animation of that name exists. */
+  playAnimation(name: string, action: PrefViewerAnimationAction): boolean;
+  setAnimationProgress(name: string, progress: number): boolean;
+  setAnimationLoop(name: string, loop: boolean): boolean;
+
+  // ── Downloads ──
+  downloadModelGLB(): void;
+  downloadModelGLTF(): void;
+  downloadModelUSDZ(): void;
+  downloadSceneGLB(): void;
+  downloadSceneGLTF(): void;
+  downloadSceneUSDZ(): void;
+  downloadModelAndSceneGLB(): void;
+  downloadModelAndSceneGLTF(): void;
+  downloadModelAndSceneUSDZ(): void;
+
+  addEventListener<K extends keyof PrefViewerEventMap>(
+    type: K,
+    listener: (this: PrefViewer, ev: PrefViewerEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  removeEventListener<K extends keyof PrefViewerEventMap>(
+    type: K,
+    listener: (this: PrefViewer, ev: PrefViewerEventMap[K]) => unknown,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void;
+}
+
+/**
+ * The observed attributes. Structured payloads (`config`, `model`, `scene`,
+ * `materials`, `drawing`, `options`, `styles`) are JSON strings when written as attributes —
+ * pass the objects through the matching method or property instead.
+ */
+export interface PrefViewerAttributes {
+  config?: string;
+  culture?: string;
+  drawing?: string;
+  materials?: string;
+  mode?: PrefViewerMode;
+  model?: string;
+  scene?: string;
+  options?: string;
+  styles?: string;
+  "show-model"?: boolean | "true" | "false";
+  "show-scene"?: boolean | "true" | "false";
+  "show-render-menu"?: boolean | "true" | "false";
 }
 
+/** <pref-viewer mode="3d" style="display:block; width:100%; height:600px" /> */
+type PrefViewerJsxProps = React.DetailedHTMLProps<
+  React.HTMLAttributes<PrefViewer> & PrefViewerAttributes,
+  PrefViewer
+>;
+
 declare global {
+  interface HTMLElementTagNameMap {
+    "pref-viewer": PrefViewer;
+  }
+
+  // React <= 18 (@types/react 18) resolves intrinsics through the global JSX namespace.
+  namespace JSX {
+    interface IntrinsicElements {
+      "pref-viewer": PrefViewerJsxProps;
+    }
+  }
+}
+
+// React 19 (@types/react 19) dropped the global JSX namespace: intrinsics resolve through
+// React.JSX instead. Declaring only the global one above leaves the element unknown on any
+// modern setup, which is why `<pref-viewer mode="3d" />` failed to compile (TEC-3490).
+declare module "react" {
   namespace JSX {
     interface IntrinsicElements {
-      /**
-       * <pref-viewer model="…" />
-       */
-      "pref-viewer": React.DetailedHTMLProps<
-        React.HTMLAttributes<HTMLElement> & { model?: string },
-        HTMLElement
-      >;
+      "pref-viewer": PrefViewerJsxProps;
     }
   }
 }
 
-export {};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.16.0",
+    "version": "2.16.2-beta.0",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -25,6 +25,7 @@
     "types": "index.d.ts",
     "exports": {
         ".": {
+            "types": "./index.d.ts",
             "import": "./src/index.js",
             "require": "./src/index.js"
         }

package/src/babylonjs-animation-opening.js

@@ -8,7 +8,7 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - Tracks animation state (paused, closed, opened, opening, closing).
  *  - Synchronizes animation progress and UI controls.
  *  - Handles loop mode and progress threshold logic.
- *  - Dispatches `prefviewer-animation-update` events with animation state snapshots.
+ *  - Dispatches `pref-viewer-3d-animation-changed` events with animation state snapshots.
  *  - Provides methods for play, pause, go to opened/closed, and progress control.
  *  - Manages the animation control menu (OpeningAnimationMenu) and its callbacks.
  *
@@ -20,12 +20,17 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - pause(): Pauses the current animation.
  *  - goToOpened(): Moves animation to the fully opened state.
  *  - goToClosed(): Moves animation to the fully closed state.
+ *  - setProgress(progress): Seeks the animation to a normalized position (0–1), snapping to ends when within the threshold.
+ *  - setLoop(loop): Enables or disables loop mode and syncs the control menu if visible.
  *  - showControls(canvas, openingAnimations): Displays the animation control menu and sets up callbacks.
  *  - hideControls(): Hides the animation control menu.
  *  - isControlsVisible(): Returns true if the control menu is visible for this animation.
  *
  * Public Properties:
- *  - state: Returns the current animation state.
+ *  - state: Returns the current animation state (one of OpeningAnimation.states).
+ *  - progress: Returns the normalized progress (0–1) derived from the current frame position.
+ *  - loop: Returns whether loop mode is currently enabled.
+ *  - nodes: Returns a copy of the node ID array affected by this animation.
  *
  * Private Methods:
  *  - #getNodesFromAnimationGroups(): Collects node IDs affected by the animation groups.
@@ -39,7 +44,7 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - #getProgress(): Calculates progress (0-1) from current frame.
  *  - #getPrefViewer3DComponent(): Resolves and caches the nearest `pref-viewer-3d` host element.
  *  - #checkProgress(progress): Applies threshold logic to progress.
- *  - #notifyStateChange(): Emits `prefviewer-animation-update` with state/progress/loop metadata.
+ *  - #notifyStateChange(): Emits `pref-viewer-3d-animation-changed` with state/progress/loop metadata.
  *  - #updateControlsSlider(): Updates the slider in the control menu.
  *  - #updateControls(): Emits state updates and syncs controls when the menu is visible.
  */
@@ -315,7 +320,7 @@ export default class OpeningAnimation {
     }
 
     /**
-     * Dispatches a `prefviewer-animation-update` CustomEvent from the nearest `pref-viewer-3d` host.
+     * Dispatches a `pref-viewer-3d-animation-changed` CustomEvent from the nearest `pref-viewer-3d` host.
      * The event bubbles and crosses shadow DOM boundaries, exposing the current animation snapshot
      * (`name`, `state`, `progress`, and `loop`) in `event.detail`.
      * @private
@@ -329,6 +334,7 @@ export default class OpeningAnimation {
 
         const customEventOptions = {
             bubbles: true,
+            cancelable: false,
             composed: true,
             detail: {
                 name: this.name,
@@ -337,7 +343,7 @@ export default class OpeningAnimation {
                 loop: this.#loop,
             },
         };
-        this.#prefViewer3D.dispatchEvent(new CustomEvent("prefviewer-animation-changed", customEventOptions));
+        this.#prefViewer3D.dispatchEvent(new CustomEvent("pref-viewer-3d-animation-changed", customEventOptions));
         return true;
     }