@ericchen1990/pano-view 3.6.7 → 3.8.0

package/README.md

@@ -677,6 +677,12 @@ function FullscreenExample() {
 }
 ```
 
+iPhone Safari does not implement the HTML5 Fullscreen API. When `enterFullscreen()` or MobileVR runs on an iPhone, the viewer covers the visual viewport and scrolls the page in landscape so Safari’s URL and toolbar can collapse. If the bars stay visible, an on-screen prompt asks the user to swipe. Host pages should set:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
 ### Imperative scene switching
 
 Use `usePanoViewer()` to shorten parent-side commands to `viewer.setScene("roof")`. Keep using controlled `activeSceneId` when the host UI needs to render the current scene id reactively. For uncontrolled mode, `defaultActiveSceneId` still lets imperative calls update the internal state directly.

package/README.zh-CN.md

@@ -650,6 +650,12 @@ function FullscreenExample() {
 }
 ```
 
+iPhone Safari 不支持 HTML5 Fullscreen API。在 iPhone 上调用 `enterFullscreen()` 或进入 MobileVR 时，查看器会铺满 visual viewport，并在横屏滚动页面，以便收起 Safari 的地址栏和工具栏。若栏仍可见，界面会提示用户滑动。宿主页面应设置：
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
 ### 命令式切换场景
 
 使用 `usePanoViewer()` 可将父组件侧命令缩短为 `viewer.setScene("roof")`。当宿主 UI 需要响应式显示当前场景 id 时，仍建议继续使用受控 `activeSceneId`。若使用非受控模式，`defaultActiveSceneId` 依然允许命令式调用直接更新内部状态。

package/dist/data.cjs

@@ -24,8 +24,10 @@ __export(data_exports, {
   hotspotAction: () => hotspotAction,
   loadPanoProject: () => loadPanoProject,
   loadSceneFromJson: () => loadSceneFromJson,
+  parsePanoMap: () => parsePanoMap,
   parsePanoProject: () => parsePanoProject,
   projectHotspotTriggers: () => projectHotspotTriggers,
+  resolvePanoMapAssets: () => resolvePanoMapAssets,
   resolveProjectHotspotAssets: () => resolveHotspotAssets,
   resolveProjectPopupAssets: () => resolveProjectPopupAssets,
   sceneFromViewerConfig: () => sceneFromViewerConfig,
@@ -844,10 +846,212 @@ function resolveHotspotAssets(hotspot, baseUrl, sceneId, resolver) {
   return result;
 }
 
-// src/data/project.ts
+// src/data/map.ts
+var CORNERS = /* @__PURE__ */ new Set([
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right"
+]);
+function optionalNumber(record, key, options = {}) {
+  const value = record[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value))
+    throw new Error(`${key}: expected a finite number`);
+  if (options.min !== void 0 && value < options.min)
+    throw new Error(`${key}: expected a number >= ${options.min}`);
+  if (options.max !== void 0 && value > options.max)
+    throw new Error(`${key}: expected a number <= ${options.max}`);
+  if (options.exclusiveMin !== void 0 && value <= options.exclusiveMin)
+    throw new Error(`${key}: expected a number > ${options.exclusiveMin}`);
+  if (options.exclusiveMax !== void 0 && value >= options.exclusiveMax)
+    throw new Error(`${key}: expected a number < ${options.exclusiveMax}`);
+  return value;
+}
+function requiredNumber(record, key, options = {}) {
+  const value = optionalNumber(record, key, options);
+  if (value === void 0) throw new Error(`${key}: expected a finite number`);
+  return value;
+}
 function optionalString(record, key) {
   return record[key] === void 0 ? void 0 : requiredString(record[key], key);
 }
+function parseGradientStop(value, field) {
+  if (!isRecord(value)) throw new Error(`${field}: expected an object`);
+  const offset = requiredNumber(value, "offset", { min: 0, max: 1 });
+  const color = requiredString(value.color, `${field}.color`);
+  const opacity = optionalNumber(value, "opacity", { min: 0, max: 1 });
+  return {
+    offset,
+    color,
+    ...opacity === void 0 ? {} : { opacity }
+  };
+}
+function parseSector(value, field) {
+  if (!isRecord(value)) throw new Error(`${field}: expected an object`);
+  const angle = requiredNumber(value, "angle", { exclusiveMin: 0, exclusiveMax: 360 });
+  const radius = requiredNumber(value, "radius", { exclusiveMin: 0 });
+  const followFov = value.followFov === void 0 ? void 0 : value.followFov === true ? true : value.followFov === false ? false : (() => {
+    throw new Error(`${field}.followFov: expected a boolean`);
+  })();
+  const color = optionalString(value, "color");
+  const opacity = optionalNumber(value, "opacity", { min: 0, max: 1 });
+  const strokeColor = optionalString(value, "strokeColor");
+  const strokeWidth = optionalNumber(value, "strokeWidth", { min: 0 });
+  const strokeOpacity = optionalNumber(value, "strokeOpacity", { min: 0, max: 1 });
+  let gradient;
+  if (value.gradient !== void 0) {
+    if (!isRecord(value.gradient))
+      throw new Error(`${field}.gradient: expected an object`);
+    const type = value.gradient.type;
+    if (type !== "radial" && type !== "linear")
+      throw new Error(`${field}.gradient.type: expected "radial" or "linear"`);
+    if (!Array.isArray(value.gradient.stops) || value.gradient.stops.length < 2)
+      throw new Error(`${field}.gradient.stops: expected at least two stops`);
+    gradient = {
+      type,
+      stops: value.gradient.stops.map(
+        (stop, index) => parseGradientStop(stop, `${field}.gradient.stops[${index}]`)
+      )
+    };
+  }
+  return {
+    angle,
+    radius,
+    ...followFov === void 0 ? {} : { followFov },
+    ...color === void 0 ? {} : { color },
+    ...opacity === void 0 ? {} : { opacity },
+    ...strokeColor === void 0 ? {} : { strokeColor },
+    ...strokeWidth === void 0 ? {} : { strokeWidth },
+    ...strokeOpacity === void 0 ? {} : { strokeOpacity },
+    ...gradient === void 0 ? {} : { gradient }
+  };
+}
+function parsePresentation(value, field) {
+  if (!isRecord(value)) throw new Error(`${field}: expected an object`);
+  const mode = value.mode;
+  if (mode !== "docked" && mode !== "dialog")
+    throw new Error(`${field}.mode: expected "docked" or "dialog"`);
+  const cornerValue = value.corner;
+  const corner = cornerValue === void 0 ? void 0 : typeof cornerValue === "string" && CORNERS.has(cornerValue) ? cornerValue : (() => {
+    throw new Error(
+      `${field}.corner: expected top-left, top-right, bottom-left, or bottom-right`
+    );
+  })();
+  const width = optionalNumber(value, "width", { exclusiveMin: 0 });
+  const height = optionalNumber(value, "height", { exclusiveMin: 0 });
+  const offsetX = optionalNumber(value, "offsetX", { min: 0 });
+  const offsetY = optionalNumber(value, "offsetY", { min: 0 });
+  return {
+    mode,
+    ...corner === void 0 ? {} : { corner },
+    ...width === void 0 ? {} : { width },
+    ...height === void 0 ? {} : { height },
+    ...offsetX === void 0 ? {} : { offsetX },
+    ...offsetY === void 0 ? {} : { offsetY }
+  };
+}
+function parseControls(value, field) {
+  if (!isRecord(value)) throw new Error(`${field}: expected an object`);
+  const collapse = value.collapse === void 0 ? void 0 : value.collapse === true ? true : value.collapse === false ? false : (() => {
+    throw new Error(`${field}.collapse: expected a boolean`);
+  })();
+  const zoom = value.zoom === void 0 ? void 0 : value.zoom === true ? true : value.zoom === false ? false : (() => {
+    throw new Error(`${field}.zoom: expected a boolean`);
+  })();
+  return {
+    ...collapse === void 0 ? {} : { collapse },
+    ...zoom === void 0 ? {} : { zoom }
+  };
+}
+function parseSpot(value, field, sceneIds) {
+  if (!isRecord(value)) throw new Error(`${field}: expected an object`);
+  const id = requiredString(value.id, `${field}.id`);
+  const sceneId = requiredString(value.sceneId, `${field}.sceneId`);
+  if (!sceneIds.has(sceneId))
+    throw new Error(`${field}.sceneId: scene does not exist`);
+  const x = requiredNumber(value, "x", { min: 0, max: 1 });
+  const y = requiredNumber(value, "y", { min: 0, max: 1 });
+  const heading = requiredNumber(value, "heading");
+  const icon = optionalString(value, "icon");
+  if (icon) resolveResource("https://map.invalid/", icon);
+  return {
+    id,
+    sceneId,
+    x,
+    y,
+    heading,
+    ...icon === void 0 ? {} : { icon }
+  };
+}
+function parsePanoMap(value, sceneIds, options = {}) {
+  if (value === void 0) return void 0;
+  try {
+    if (!isRecord(value)) throw new Error("map: expected an object");
+    if (typeof value.image !== "string" || !options.draft && !value.image.trim())
+      throw new Error("map.image: expected a nonempty string");
+    const image = value.image;
+    if (image.trim()) resolveResource("https://map.invalid/", image);
+    const interaction = value.interaction === void 0 ? void 0 : value.interaction === "fixed" || value.interaction === "zoom" ? value.interaction : (() => {
+      throw new Error('map.interaction: expected "fixed" or "zoom"');
+    })();
+    const presentation = value.presentation === void 0 ? void 0 : parsePresentation(value.presentation, "map.presentation");
+    const controls = value.controls === void 0 ? void 0 : parseControls(value.controls, "map.controls");
+    const iconSize = optionalNumber(value, "iconSize", { exclusiveMin: 0 });
+    const maxScale = optionalNumber(value, "maxScale", { min: 1 });
+    if (!Array.isArray(value.spots)) throw new Error("map.spots: expected an array");
+    const spotIds = /* @__PURE__ */ new Set();
+    const spots = value.spots.map((spot, index) => {
+      const parsed = parseSpot(spot, `map.spots[${index}]`, sceneIds);
+      if (spotIds.has(parsed.id))
+        throw new Error(`map.spots[${index}].id: duplicate spot ID`);
+      spotIds.add(parsed.id);
+      return parsed;
+    });
+    const sector = value.sector === void 0 ? void 0 : parseSector(value.sector, "map.sector");
+    return {
+      image,
+      ...interaction === void 0 ? {} : { interaction },
+      ...presentation === void 0 ? {} : { presentation },
+      ...controls === void 0 ? {} : { controls },
+      ...iconSize === void 0 ? {} : { iconSize },
+      ...maxScale === void 0 ? {} : { maxScale },
+      spots,
+      ...sector === void 0 ? {} : { sector }
+    };
+  } catch (cause) {
+    if (cause instanceof PanoDataError) throw cause;
+    const message = cause instanceof Error ? cause.message : "Invalid map";
+    throw new PanoDataError("INVALID_PROJECT", message, {
+      field: message.split(":")[0],
+      cause
+    });
+  }
+}
+function resolvePanoMapAssets(map, baseUrl, resolveAssetUrl) {
+  const resolve = (path, spotId) => mapResource(
+    path,
+    {
+      defaultUrl: resolveResource(baseUrl, path),
+      kind: "map",
+      sceneId: spotId ?? "",
+      hotspotId: spotId
+    },
+    resolveAssetUrl
+  );
+  return {
+    ...map,
+    image: resolve(map.image),
+    spots: map.spots.map(
+      (spot) => spot.icon ? { ...spot, icon: resolve(spot.icon, spot.id) } : { ...spot }
+    )
+  };
+}
+
+// src/data/project.ts
+function optionalString2(record, key) {
+  return record[key] === void 0 ? void 0 : requiredString(record[key], key);
+}
 function parsePanoProject(value, options = {}) {
   if (!isRecord(value))
     throw new PanoDataError("INVALID_PROJECT", "Expected a project object");
@@ -878,7 +1082,7 @@ function parsePanoProject(value, options = {}) {
             throw new Error(
               "source: provide exactly one of viewerUrl or viewerConfig"
             );
-          const baseUrl = optionalString(src, "baseUrl");
+          const baseUrl = optionalString2(src, "baseUrl");
           const source = src.viewerUrl !== void 0 ? {
             viewerUrl: requiredString(src.viewerUrl, "source.viewerUrl"),
             baseUrl
@@ -918,7 +1122,7 @@ function parsePanoProject(value, options = {}) {
           );
           return {
             id,
-            title: optionalString(entry, "title"),
+            title: optionalString2(entry, "title"),
             source,
             initialView,
             ...viewLimits === void 0 ? {} : { viewLimits },
@@ -939,7 +1143,7 @@ function parsePanoProject(value, options = {}) {
         }
       }
     );
-    const initialSceneId = optionalString(value, "initialSceneId") ?? scenes[0]?.id;
+    const initialSceneId = optionalString2(value, "initialSceneId") ?? scenes[0]?.id;
     if (initialSceneId !== void 0 && !ids.has(initialSceneId))
       throw new PanoDataError(
         "INVALID_REFERENCE",
@@ -967,12 +1171,14 @@ function parsePanoProject(value, options = {}) {
         }
       }
     }
+    const map = parsePanoMap(value.map, ids, options);
     return {
       schemaVersion: 1,
-      title: optionalString(value, "title"),
+      title: optionalString2(value, "title"),
       initialSceneId,
       scenes,
-      ...popups === void 0 ? {} : { popups }
+      ...popups === void 0 ? {} : { popups },
+      ...map === void 0 ? {} : { map }
     };
   } catch (cause) {
     if (cause instanceof PanoDataError) throw cause;
@@ -1071,7 +1277,14 @@ async function loadPanoProject(source, options = {}) {
       title: definition.title,
       initialSceneId: definition.initialSceneId,
       scenes,
-      ...definition.popups === void 0 ? {} : { popups: definition.popups.map((popup) => resolveProjectPopupAssets(popup, root, options.resolvePopupAssetUrl)) }
+      ...definition.popups === void 0 ? {} : { popups: definition.popups.map((popup) => resolveProjectPopupAssets(popup, root, options.resolvePopupAssetUrl)) },
+      ...definition.map === void 0 ? {} : {
+        map: resolvePanoMapAssets(
+          definition.map,
+          root,
+          options.resolveAssetUrl
+        )
+      }
     };
   } finally {
     signal?.removeEventListener("abort", cancel);