@ericchen1990/pano-view 3.5.0 → 3.6.0

package/dist/data.d.ts

@@ -45,6 +45,22 @@ type ViewerDocument = ViewerConfig & {
     schemaVersion: 1;
 };
 
+/** Camera-center limits in degrees. A yaw min greater than max crosses ±180°. */
+type PanoViewLimits = {
+    yaw?: {
+        min: number;
+        max: number;
+    };
+    pitch?: {
+        min: number;
+        max: number;
+    };
+    fov?: {
+        min: number;
+        max: number;
+    };
+};
+
 type CubeFaceCode = "f" | "r" | "b" | "l" | "u" | "d";
 type TileAddress = {
     face: CubeFaceCode;
@@ -179,11 +195,14 @@ type SphereTileProps = {
     onLevelChange?: (level: number) => void;
 };
 
-type TileScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & {
+type SceneViewOptions = {
+    viewLimits?: PanoViewLimits;
+};
+type TileScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & SceneViewOptions & {
     id: string;
     type: "tile";
 };
-type SphereTileScene = Omit<SphereTileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & {
+type SphereTileScene = Omit<SphereTileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & SceneViewOptions & {
     id: string;
     type: "sphereTile";
 };
@@ -209,6 +228,37 @@ type LoadSceneFromJsonOptions = Omit<SceneFromViewerConfigOptions, "baseUrl"> &
 declare function sceneFromViewerConfig(value: unknown, options: SceneFromViewerConfigOptions): TileScene | SphereTileScene;
 declare function loadSceneFromJson(url: string, options: LoadSceneFromJsonOptions): Promise<TileScene | SphereTileScene>;
 
+type ProjectPopupBlock = {
+    id: string;
+} & ({
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    src: string;
+    alt?: string;
+} | {
+    type: "video";
+    src: string;
+    poster?: string;
+} | {
+    type: "audio";
+    src: string;
+});
+type ProjectPopupDefinition = {
+    id: string;
+    title: string;
+    blocks: ProjectPopupBlock[];
+};
+type PopupAssetUrlContext = {
+    defaultUrl: string;
+    popupId: string;
+    blockId: string;
+    field: "src" | "poster";
+};
+type PopupAssetUrlResolver = (path: string, context: PopupAssetUrlContext) => string;
+declare function resolveProjectPopupAssets(popup: ProjectPopupDefinition, baseUrl: string, resolver?: PopupAssetUrlResolver): ProjectPopupDefinition;
+
 type HotspotPosition = {
     /** Horizontal panorama angle in degrees. Positive values look right. */
     yaw: number;
@@ -398,6 +448,7 @@ type VideoHotspotDefinition = PointHotspotDefinitionBase & {
 type AudioHotspotDefinition = PointHotspotDefinitionBase & {
     type: "audio";
     src: string | string[];
+    format?: string | string[];
     playing?: boolean;
     loop?: boolean;
     muted?: boolean;
@@ -449,12 +500,36 @@ type PointHotspotDefinition = ImageHotspotDefinition | GraphicHotspotDefinition
 /** A serializable, discriminated hotspot collection item. */
 type HotspotDefinition = PointHotspotDefinition | PolygonHotspotDefinition | PolylineHotspotDefinition;
 
+type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+declare const projectHotspotTriggers: readonly ["click", "pointerenter", "pointerleave"];
+type ProjectHotspotTrigger = typeof projectHotspotTriggers[number];
+type ProjectCustomHotspotAction = {
+    type: "custom";
+    actionId: string;
+    params?: JsonObject;
+};
+declare function hotspotAction(hotspot: ProjectHotspotDefinition, trigger: ProjectHotspotTrigger): ProjectHotspotAction | undefined;
+declare function setHotspotAction(hotspot: ProjectHotspotDefinition, trigger: ProjectHotspotTrigger, action?: ProjectHotspotAction): ProjectHotspotDefinition;
+type ProjectHotspotAction = ProjectCustomHotspotAction | {
+    type: "scene";
+    sceneId: string;
+} | {
+    type: "view";
+    view: PanoViewerState;
+    duration?: number;
+} | {
+    type: "popup";
+    popupId: string;
+};
 type ProjectHotspotDefinition = HotspotDefinition & {
-    action?: {
-        type: "scene";
-        sceneId: string;
-    };
+    /** Legacy click fallback. events.click takes precedence. */
+    action?: ProjectHotspotAction;
+    events?: Partial<Record<ProjectHotspotTrigger, ProjectHotspotAction>>;
 };
+declare function resolveHotspotAssets(hotspot: ProjectHotspotDefinition, baseUrl: string, sceneId: string, resolver?: AssetUrlResolver): ProjectHotspotDefinition;
 
 type PanoProjectSceneDefinition = {
     id: string;
@@ -469,6 +544,7 @@ type PanoProjectSceneDefinition = {
         baseUrl?: string;
     };
     initialView?: Partial<PanoViewerState>;
+    viewLimits?: PanoViewLimits;
     hotspots?: ProjectHotspotDefinition[];
 };
 type PanoProjectDefinition = {
@@ -476,6 +552,7 @@ type PanoProjectDefinition = {
     title?: string;
     initialSceneId?: string;
     scenes: PanoProjectSceneDefinition[];
+    popups?: ProjectPopupDefinition[];
 };
 type LoadedProjectScene = {
     scene: TileScene | SphereTileScene;
@@ -487,13 +564,18 @@ type LoadedPanoProject = {
     title?: string;
     initialSceneId: string;
     scenes: LoadedProjectScene[];
+    popups?: ProjectPopupDefinition[];
 };
 type LoadPanoProjectOptions = JsonRequestOptions & {
     /** Directory used for project-relative references. Required for object input. */
     baseUrl?: string;
     resolveAssetUrl?: AssetUrlResolver;
+    resolvePopupAssetUrl?: PopupAssetUrlResolver;
 };
-declare function parsePanoProject(value: unknown): PanoProjectDefinition;
+/** Drafts permit empty scenes and unfinished popup titles/media; loading and export always validate strictly. */
+declare function parsePanoProject(value: unknown, options?: {
+    draft?: boolean;
+}): PanoProjectDefinition;
 declare function loadPanoProject(source: string | PanoProjectDefinition, options?: LoadPanoProjectOptions): Promise<LoadedPanoProject>;
 
-export { type AssetUrlContext, type AssetUrlResolver, type CubemapViewerConfig, type JsonRequestOptions, type LoadPanoProjectOptions, type LoadSceneFromJsonOptions, type LoadedPanoProject, type LoadedProjectScene, PanoDataError, type PanoDataErrorCode, type PanoProjectDefinition, type PanoProjectSceneDefinition, type ProjectHotspotDefinition, type SceneFromViewerConfigOptions, type SphereViewerConfig, type ViewerConfig, type ViewerDocument, loadPanoProject, loadSceneFromJson, parsePanoProject, sceneFromViewerConfig };
+export { type AssetUrlContext, type AssetUrlResolver, type CubemapViewerConfig, type JsonObject, type JsonRequestOptions, type JsonValue, type LoadPanoProjectOptions, type LoadSceneFromJsonOptions, type LoadedPanoProject, type LoadedProjectScene, PanoDataError, type PanoDataErrorCode, type PanoProjectDefinition, type PanoProjectSceneDefinition, type PanoViewLimits, type PopupAssetUrlContext, type PopupAssetUrlResolver, type ProjectCustomHotspotAction, type ProjectHotspotAction, type ProjectHotspotDefinition, type ProjectHotspotTrigger, type ProjectPopupBlock, type ProjectPopupDefinition, type SceneFromViewerConfigOptions, type SphereViewerConfig, type ViewerConfig, type ViewerDocument, hotspotAction, loadPanoProject, loadSceneFromJson, parsePanoProject, projectHotspotTriggers, resolveHotspotAssets as resolveProjectHotspotAssets, resolveProjectPopupAssets, sceneFromViewerConfig, setHotspotAction };

package/dist/data.mjs

@@ -271,7 +271,152 @@ async function loadSceneFromJson(url, options) {
   });
 }
 
+// src/view-limits.ts
+function parseViewLimits(value) {
+  if (value === void 0) return void 0;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("viewLimits: expected an object");
+  const result = {};
+  for (const axis of ["yaw", "pitch", "fov"]) {
+    const input = value[axis];
+    if (input === void 0) continue;
+    if (!input || typeof input !== "object" || Array.isArray(input))
+      throw new Error(`viewLimits.${axis}: expected min and max`);
+    const { min, max } = input;
+    const lower = axis === "yaw" ? -180 : axis === "pitch" ? -90 : 1;
+    const upper = axis === "yaw" ? 180 : axis === "pitch" ? 90 : 179;
+    if (typeof min !== "number" || typeof max !== "number" || !Number.isFinite(min) || !Number.isFinite(max) || min < lower || min > upper || max < lower || max > upper)
+      throw new Error(`viewLimits.${axis}: expected finite min and max from ${lower} to ${upper}`);
+    if (axis !== "yaw" && min > max)
+      throw new Error(`viewLimits.${axis}: min must not exceed max`);
+    result[axis] = { min, max };
+  }
+  return result;
+}
+
+// src/data/popups.ts
+function parsePopups(value, draft = false) {
+  if (value === void 0) return void 0;
+  try {
+    if (!Array.isArray(value)) throw new Error("popups: expected an array");
+    const ids = /* @__PURE__ */ new Set();
+    const string = (input, field, allowEmpty = false) => {
+      if (typeof input !== "string" || !allowEmpty && !input.trim())
+        throw new Error(`${field}: expected a ${allowEmpty ? "string" : "nonempty string"}`);
+      return input;
+    };
+    return value.map((entry, index) => {
+      const field = `popups[${index}]`;
+      if (!isRecord(entry)) throw new Error(`${field}: expected an object`);
+      const id = requiredString(entry.id, `${field}.id`);
+      if (ids.has(id)) throw new Error(`${field}.id: duplicate popup ID`);
+      ids.add(id);
+      const title = string(entry.title, `${field}.title`, draft);
+      if (!Array.isArray(entry.blocks)) throw new Error(`${field}.blocks: expected an array`);
+      const blockIds = /* @__PURE__ */ new Set();
+      const blocks = entry.blocks.map((block, i) => {
+        const path = `${field}.blocks[${i}]`;
+        if (!isRecord(block)) throw new Error(`${path}: expected an object`);
+        const id2 = requiredString(block.id, `${path}.id`);
+        if (blockIds.has(id2)) throw new Error(`${path}.id: duplicate block ID`);
+        blockIds.add(id2);
+        if (block.type === "text") return { id: id2, type: "text", text: string(block.text, `${path}.text`, true) };
+        const src = string(block.src, `${path}.src`, draft);
+        if (src) resolveResource("https://popup.invalid/", src);
+        if (block.type === "image") return {
+          id: id2,
+          type: "image",
+          src,
+          ...block.alt === void 0 ? {} : { alt: string(block.alt, `${path}.alt`, true) }
+        };
+        if (block.type === "audio") return { id: id2, type: "audio", src };
+        if (block.type === "video") {
+          const poster = block.poster === void 0 ? void 0 : string(block.poster, `${path}.poster`, true);
+          if (poster) resolveResource("https://popup.invalid/", poster);
+          return { id: id2, type: "video", src, ...poster ? { poster } : {} };
+        }
+        throw new Error(`${path}.type: unsupported content block`);
+      });
+      return { id, title, blocks };
+    });
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : "Invalid popup content";
+    throw new PanoDataError("INVALID_PROJECT", message, { field: message.split(":")[0], cause });
+  }
+}
+function resolveProjectPopupAssets(popup, baseUrl, resolver) {
+  return { ...popup, blocks: popup.blocks.map((block) => {
+    if (block.type === "text") return { ...block };
+    const resolve = (path, field) => {
+      if (!path) throw new PanoDataError("INVALID_PROJECT", `${popup.id}/${block.id}.${field}: choose a resource`);
+      const context = { defaultUrl: resolveResource(baseUrl, path), popupId: popup.id, blockId: block.id, field };
+      const result = resolver ? resolver(path, context) : context.defaultUrl;
+      if (typeof result !== "string" || !result.startsWith("/") && !/^(https?:|blob:|data:)/i.test(result))
+        throw new PanoDataError("INVALID_CONFIG", "resolvePopupAssetUrl must return an absolute URL or a site-root path");
+      return result;
+    };
+    return { ...block, src: resolve(block.src, "src"), ...block.type === "video" && block.poster ? { poster: resolve(block.poster, "poster") } : {} };
+  }) };
+}
+
+// ../../shared/cursor-assets.ts
+function mapCursorAssets(cursor, resolve) {
+  return cursor.replace(
+    /url\(\s*(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|((?:\\.|[^)\\])*?))\s*\)/gi,
+    (_match, double, single, bare) => {
+      const path = (double ?? single ?? bare ?? "").replace(
+        /\\([\da-f]{1,6}\s?|.)/gi,
+        (_escape, value) => /^[\da-f]/i.test(value) ? String.fromCodePoint(
+          Math.min(parseInt(value.trim(), 16), 1114111)
+        ) : value
+      );
+      return `url(${JSON.stringify(resolve(path))})`;
+    }
+  );
+}
+
 // src/data/hotspots.ts
+var projectHotspotTriggers = ["click", "pointerenter", "pointerleave"];
+function hotspotAction(hotspot, trigger) {
+  return hotspot.events?.[trigger] ?? (trigger === "click" ? hotspot.action : void 0);
+}
+function setHotspotAction(hotspot, trigger, action) {
+  const events = { ...hotspot.events };
+  const next = { ...hotspot, events };
+  if (trigger === "click") delete next.action;
+  if (action) events[trigger] = action;
+  else delete events[trigger];
+  if (!Object.keys(events).length) delete next.events;
+  return next;
+}
+function jsonValue(value, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "object" || !value || seen.has(value)) throw new Error("params: expected JSON data");
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error("params: expected JSON data");
+  seen.add(value);
+  const result = Array.isArray(value) ? value.map((item) => jsonValue(item, seen)) : Object.fromEntries(Object.entries(value).map(([key, item]) => [key, jsonValue(item, seen)]));
+  seen.delete(value);
+  return result;
+}
+function parseAction(action) {
+  if (!isRecord(action)) throw new Error("action: expected an object");
+  if (action.type === "scene") return { type: "scene", sceneId: requiredString(action.sceneId, "action.sceneId") };
+  if (action.type === "popup") return { type: "popup", popupId: requiredString(action.popupId, "action.popupId") };
+  if (action.type === "custom") {
+    if (action.params !== void 0 && (!isRecord(action.params) || Array.isArray(action.params))) throw new Error("action.params: expected an object");
+    return { type: "custom", actionId: requiredString(action.actionId, "action.actionId"), ...action.params === void 0 ? {} : { params: jsonValue(action.params) } };
+  }
+  if (action.type === "view") {
+    const position = parsePosition(action.view, "action.view");
+    const fov = finite(action.view.fov, "action.view.fov");
+    if (fov <= 0 || fov >= 180) throw new Error("action.view.fov: expected 0 < fov < 180");
+    const duration = action.duration === void 0 ? void 0 : finite(action.duration, "action.duration");
+    if (duration !== void 0 && duration < 0) throw new Error("action.duration: expected a nonnegative number");
+    return { type: "view", view: { ...position, fov }, ...duration === void 0 ? {} : { duration } };
+  }
+  throw new Error("action.type: unsupported action");
+}
 var common = [
   "label",
   "visible",
@@ -314,6 +459,7 @@ var fields = {
   ],
   audio: [
     "src",
+    "format",
     "playing",
     "loop",
     "muted",
@@ -582,9 +728,10 @@ function parseHotspot(value, sceneId, field) {
         result[key] = n;
       } else if (key === "fontWeight" && typeof item === "number")
         result[key] = finite(item, key);
-      else if (key === "src" && kind === "audio" && Array.isArray(item)) {
-        if (!item.length) throw new Error("src: expected audio sources");
-        result[key] = item.map((src, i) => requiredString(src, `src[${i}]`));
+      else if ((key === "src" || key === "format") && kind === "audio" && Array.isArray(item)) {
+        if (!item.length)
+          throw new Error(`${key}: expected audio ${key === "src" ? "sources" : "formats"}`);
+        result[key] = item.map((entry, i) => requiredString(entry, `${key}[${i}]`));
       } else {
         if (typeof item !== "string")
           throw new Error(`${key}: expected a string`);
@@ -603,13 +750,19 @@ function parseHotspot(value, sceneId, field) {
       throw new Error("text: required");
     if (kind === "sequence" && !result.frameCount)
       throw new Error("frameCount: required");
-    if (value.action !== void 0) {
-      if (!isRecord(value.action) || value.action.type !== "scene")
-        throw new Error("action: expected a scene action");
-      result.action = {
-        type: "scene",
-        sceneId: requiredString(value.action.sceneId, "action.sceneId")
-      };
+    if (value.action !== void 0) result.action = parseAction(value.action);
+    if (value.events !== void 0) {
+      if (!isRecord(value.events)) throw new Error("events: expected an object");
+      const events = {};
+      for (const key of Object.keys(value.events)) {
+        if (!projectHotspotTriggers.includes(key)) throw new Error(`events.${key}: unsupported trigger`);
+        try {
+          events[key] = parseAction(value.events[key]);
+        } catch (error) {
+          throw new Error(`events.${key}.${error instanceof Error ? error.message : "invalid action"}`);
+        }
+      }
+      result.events = events;
     }
     return result;
   } catch (cause) {
@@ -633,6 +786,11 @@ function resolveHotspotAssets(hotspot, baseUrl, sceneId, resolver) {
     resolver
   ) : path;
   const result = { ...hotspot };
+  if (result.cursor) result.cursor = mapCursorAssets(result.cursor, resolve);
+  if (result.tooltipAppearance?.background) result.tooltipAppearance = {
+    ...result.tooltipAppearance,
+    background: mapCursorAssets(result.tooltipAppearance.background, resolve)
+  };
   if ("src" in result)
     result.src = Array.isArray(result.src) ? result.src.map(resolve) : resolve(result.src);
   if ("poster" in result && result.poster)
@@ -655,7 +813,7 @@ function resolveHotspotAssets(hotspot, baseUrl, sceneId, resolver) {
 function optionalString(record, key) {
   return record[key] === void 0 ? void 0 : requiredString(record[key], key);
 }
-function parsePanoProject(value) {
+function parsePanoProject(value, options = {}) {
   if (!isRecord(value))
     throw new PanoDataError("INVALID_PROJECT", "Expected a project object");
   if (value.schemaVersion !== 1)
@@ -665,7 +823,8 @@ function parsePanoProject(value) {
       { field: "schemaVersion" }
     );
   try {
-    if (!Array.isArray(value.scenes) || !value.scenes.length)
+    const popups = parsePopups(value.popups, options.draft);
+    if (!Array.isArray(value.scenes) || !options.draft && !value.scenes.length)
       throw new Error("scenes: expected a nonempty array");
     const ids = /* @__PURE__ */ new Set();
     const scenes = value.scenes.map(
@@ -689,6 +848,7 @@ function parsePanoProject(value) {
             viewerUrl: requiredString(src.viewerUrl, "source.viewerUrl"),
             baseUrl
           } : { viewerConfig: parseConfig(src.viewerConfig), baseUrl };
+          const viewLimits = parseViewLimits(entry.viewLimits);
           let initialView;
           if (entry.initialView !== void 0) {
             if (!isRecord(entry.initialView))
@@ -726,6 +886,7 @@ function parsePanoProject(value) {
             title: optionalString(entry, "title"),
             source,
             initialView,
+            ...viewLimits === void 0 ? {} : { viewLimits },
             hotspots
           };
         } catch (cause) {
@@ -743,8 +904,8 @@ function parsePanoProject(value) {
         }
       }
     );
-    const initialSceneId = optionalString(value, "initialSceneId") ?? scenes[0].id;
-    if (!ids.has(initialSceneId))
+    const initialSceneId = optionalString(value, "initialSceneId") ?? scenes[0]?.id;
+    if (initialSceneId !== void 0 && !ids.has(initialSceneId))
       throw new PanoDataError(
         "INVALID_REFERENCE",
         "initialSceneId: scene does not exist",
@@ -752,22 +913,31 @@ function parsePanoProject(value) {
       );
     for (const [index, scene] of scenes.entries()) {
       for (const [i, hotspot] of (scene.hotspots ?? []).entries()) {
-        if (hotspot.action && !ids.has(hotspot.action.sceneId))
-          throw new PanoDataError(
-            "INVALID_REFERENCE",
-            "Hotspot target scene does not exist",
-            {
+        for (const trigger of projectHotspotTriggers) {
+          const action = hotspotAction(hotspot, trigger);
+          if (action?.type === "popup" && !popups?.some((popup) => popup.id === action.popupId))
+            throw new PanoDataError("INVALID_REFERENCE", "Hotspot target popup does not exist", {
               sceneId: scene.id,
-              field: `scenes[${index}].hotspots[${i}].action.sceneId`
-            }
-          );
+              field: `scenes[${index}].hotspots[${i}].${hotspot.events?.[trigger] ? `events.${trigger}` : "action"}.popupId`
+            });
+          if (action?.type === "scene" && !ids.has(action.sceneId))
+            throw new PanoDataError(
+              "INVALID_REFERENCE",
+              "Hotspot target scene does not exist",
+              {
+                sceneId: scene.id,
+                field: `scenes[${index}].hotspots[${i}].${hotspot.events?.[trigger] ? `events.${trigger}` : "action"}.sceneId`
+              }
+            );
+        }
       }
     }
     return {
       schemaVersion: 1,
       title: optionalString(value, "title"),
       initialSceneId,
-      scenes
+      scenes,
+      ...popups === void 0 ? {} : { popups }
     };
   } catch (cause) {
     if (cause instanceof PanoDataError) throw cause;
@@ -828,6 +998,7 @@ async function loadPanoProject(source, options = {}) {
           baseUrl: sourceBase ?? root
         });
         aborted(controller.signal);
+        if (item.viewLimits !== void 0) scene.viewLimits = item.viewLimits;
         scenes[index] = {
           scene,
           title: item.title,
@@ -864,7 +1035,8 @@ async function loadPanoProject(source, options = {}) {
     return {
       title: definition.title,
       initialSceneId: definition.initialSceneId,
-      scenes
+      scenes,
+      ...definition.popups === void 0 ? {} : { popups: definition.popups.map((popup) => resolveProjectPopupAssets(popup, root, options.resolvePopupAssetUrl)) }
     };
   } finally {
     signal?.removeEventListener("abort", cancel);
@@ -872,9 +1044,14 @@ async function loadPanoProject(source, options = {}) {
 }
 export {
   PanoDataError,
+  hotspotAction,
   loadPanoProject,
   loadSceneFromJson,
   parsePanoProject,
-  sceneFromViewerConfig
+  projectHotspotTriggers,
+  resolveHotspotAssets as resolveProjectHotspotAssets,
+  resolveProjectPopupAssets,
+  sceneFromViewerConfig,
+  setHotspotAction
 };
 //# sourceMappingURL=data.mjs.map