@ericchen1990/pano-view 3.6.7 → 3.8.0

package/dist/data.d.ts

@@ -209,7 +209,7 @@ type SphereTileScene = Omit<SphereTileProps, "loadMode" | "visible" | "onReady"
 
 type AssetUrlContext = {
     defaultUrl: string;
-    kind: "tile" | "preview" | "hotspot";
+    kind: "tile" | "preview" | "hotspot" | "map";
     sceneId: string;
     hotspotId?: string;
 };
@@ -531,6 +531,106 @@ type ProjectHotspotDefinition = HotspotDefinition & {
 };
 declare function resolveHotspotAssets(hotspot: ProjectHotspotDefinition, baseUrl: string, sceneId: string, resolver?: AssetUrlResolver): ProjectHotspotDefinition;
 
+type PanoMapCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+type PanoMapGradientStop = {
+    offset: number;
+    color: string;
+    opacity?: number;
+};
+type PanoMapSectorGradient = {
+    type: "radial" | "linear";
+    stops: PanoMapGradientStop[];
+};
+type PanoMapSectorDefinition = {
+    /** Sector opening angle in degrees. */
+    angle: number;
+    /** Sector radius in CSS pixels; does not scale with the floor image. */
+    radius: number;
+    /** When true, sector angle follows the current horizontal FOV. */
+    followFov?: boolean;
+    /** Solid fill color when `gradient` is omitted. */
+    color?: string;
+    /**
+     * Overall fill opacity in [0, 1].
+     * Applies in both solid and gradient modes; gradient stop opacities only
+     * describe the relative fade shape and are normalized against this value.
+     */
+    opacity?: number;
+    /** Optional sector outline color. */
+    strokeColor?: string;
+    /** Outline width in CSS pixels. */
+    strokeWidth?: number;
+    /** Outline opacity in [0, 1]. Defaults to 1 when stroke is set. */
+    strokeOpacity?: number;
+    /**
+     * Optional fill gradient. When omitted, the sector uses a solid `color`.
+     * Stop colors are independent of `color` unless the author keeps them in sync.
+     */
+    gradient?: PanoMapSectorGradient;
+};
+type PanoMapSpotDefinition = {
+    id: string;
+    sceneId: string;
+    /** Normalized image X in [0, 1], origin at the top-left. */
+    x: number;
+    /** Normalized image Y in [0, 1], origin at the top-left. */
+    y: number;
+    /**
+     * Clockwise degrees from image up when viewer yaw is 0.
+     * Runtime sector rotation is `heading + yaw`.
+     */
+    heading: number;
+    icon?: string;
+};
+type PanoMapControlsDefinition = {
+    /** Show expand/collapse on a docked panel. */
+    collapse?: boolean;
+    /** Show zoom-in and zoom-out buttons. */
+    zoom?: boolean;
+};
+type PanoMapDockedPresentation = {
+    mode: "docked";
+    corner?: PanoMapCorner;
+    width?: number;
+    height?: number;
+    offsetX?: number;
+    offsetY?: number;
+};
+type PanoMapDialogPresentation = {
+    mode: "dialog";
+    corner?: PanoMapCorner;
+    offsetX?: number;
+    offsetY?: number;
+    width?: number;
+    height?: number;
+};
+type PanoMapPresentation = PanoMapDockedPresentation | PanoMapDialogPresentation;
+type PanoMapDefinition = {
+    image: string;
+    /**
+     * Pointer interaction with the floor image.
+     * - `fixed`: fit-only; no wheel/pan zoom (zoom buttons are also suppressed).
+     * - `zoom`: wheel/pan zoom and optional zoom buttons.
+     */
+    interaction?: "fixed" | "zoom";
+    presentation?: PanoMapPresentation;
+    controls?: PanoMapControlsDefinition;
+    /** Spot icon edge length in CSS pixels. */
+    iconSize?: number;
+    /**
+     * Maximum zoom multiplier relative to the contain-fit scale.
+     * Only applies when `interaction` is `"zoom"`. Defaults to 8.
+     */
+    maxScale?: number;
+    spots: PanoMapSpotDefinition[];
+    sector?: PanoMapSectorDefinition;
+};
+/** Parse an optional project floor plan. Scene IDs must already be collected. */
+declare function parsePanoMap(value: unknown, sceneIds: Set<string>, options?: {
+    draft?: boolean;
+}): PanoMapDefinition | undefined;
+declare function resolvePanoMapAssets(map: PanoMapDefinition, baseUrl: string, resolveAssetUrl?: AssetUrlResolver): PanoMapDefinition;
+
 type PanoProjectSceneDefinition = {
     id: string;
     title?: string;
@@ -553,6 +653,7 @@ type PanoProjectDefinition = {
     initialSceneId?: string;
     scenes: PanoProjectSceneDefinition[];
     popups?: ProjectPopupDefinition[];
+    map?: PanoMapDefinition;
 };
 type LoadedProjectScene = {
     scene: TileScene | SphereTileScene;
@@ -565,6 +666,7 @@ type LoadedPanoProject = {
     initialSceneId: string;
     scenes: LoadedProjectScene[];
     popups?: ProjectPopupDefinition[];
+    map?: PanoMapDefinition;
 };
 type LoadPanoProjectOptions = JsonRequestOptions & {
     /** Directory used for project-relative references. Required for object input. */
@@ -578,4 +680,4 @@ declare function parsePanoProject(value: unknown, options?: {
 }): PanoProjectDefinition;
 declare function loadPanoProject(source: string | PanoProjectDefinition, options?: LoadPanoProjectOptions): Promise<LoadedPanoProject>;
 
-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 };
+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 PanoMapControlsDefinition, type PanoMapCorner, type PanoMapDefinition, type PanoMapDialogPresentation, type PanoMapDockedPresentation, type PanoMapGradientStop, type PanoMapPresentation, type PanoMapSectorDefinition, type PanoMapSectorGradient, type PanoMapSpotDefinition, 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, parsePanoMap, parsePanoProject, projectHotspotTriggers, resolvePanoMapAssets, resolveHotspotAssets as resolveProjectHotspotAssets, resolveProjectPopupAssets, sceneFromViewerConfig, setHotspotAction };

package/dist/data.mjs

@@ -809,10 +809,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");
@@ -843,7 +1045,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
@@ -883,7 +1085,7 @@ function parsePanoProject(value, options = {}) {
           );
           return {
             id,
-            title: optionalString(entry, "title"),
+            title: optionalString2(entry, "title"),
             source,
             initialView,
             ...viewLimits === void 0 ? {} : { viewLimits },
@@ -904,7 +1106,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",
@@ -932,12 +1134,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;
@@ -1036,7 +1240,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);
@@ -1047,8 +1258,10 @@ export {
   hotspotAction,
   loadPanoProject,
   loadSceneFromJson,
+  parsePanoMap,
   parsePanoProject,
   projectHotspotTriggers,
+  resolvePanoMapAssets,
   resolveHotspotAssets as resolveProjectHotspotAssets,
   resolveProjectPopupAssets,
   sceneFromViewerConfig,