@liquidcars/atlas 0.1.37 → 0.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "Reusable 3D conceptual atlas Web Component for LiquidCars-style models",
   "type": "module",
   "scripts": {

package/src/liquidcars-atlas.js

@@ -1,4 +1,10 @@
 import * as THREE from "./three.module.js";
+import atlasPackage from "../package.json" with { type: "json" };
+
+// This value is bundled from the package manifest, so it always identifies
+// the Atlas module that is actually executing rather than the host
+// application's declared dependency.
+export const ATLAS_VERSION = atlasPackage.version;
 
 const DEFAULT_PALETTE = {
   component: "#8ae4d0",
@@ -10,50 +16,156 @@ const RELATION_RENDER_ORDER = 15;
 
 const GEOMETRY_DEFINITIONS = new Map();
 const GEOMETRY_ALIASES = new Map();
+const GEOMETRY_PACKS = new Map();
+
+function cloneGeometryMetadata(value) {
+  if (Array.isArray(value)) return value.map(cloneGeometryMetadata);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, item]) => typeof item !== "function" && item !== undefined)
+      .map(([key, item]) => [key, cloneGeometryMetadata(item)])
+  );
+}
+
+function normalizeGeometryAuthors(value) {
+  const authors = value == null ? [] : Array.isArray(value) ? value : [value];
+  return authors
+    .map(author => typeof author === "string" ? { name: author } : cloneGeometryMetadata(author))
+    .filter(author => author && String(author.name || "").trim())
+    .map(author => ({ ...author, name: String(author.name).trim() }));
+}
+
+function normalizeGeometryStringList(value) {
+  const values = value == null ? [] : Array.isArray(value) ? value : [value];
+  return [...new Set(values.map(item => String(item || "").trim()).filter(Boolean))];
+}
+
+function normalizeGeometryLicense(value) {
+  if (!value) return null;
+  return typeof value === "string" ? { spdx: value } : cloneGeometryMetadata(value);
+}
+
+function normalizeGeometrySource(source, index) {
+  const value = cloneGeometryMetadata(source || {});
+  const id = String(value.id || `source-${index + 1}`).trim();
+  if (!id) throw new TypeError("Geometry pack sources require an id.");
+  return {
+    ...value,
+    id,
+    authors: normalizeGeometryAuthors(value.authors ?? value.author),
+    license: normalizeGeometryLicense(value.license)
+  };
+}
+
+function normalizeGeometryResource(resource, index, sourceIds) {
+  const value = cloneGeometryMetadata(resource || {});
+  const id = String(value.id || "").trim();
+  if (!id) throw new TypeError(`Geometry pack resource at index ${index} requires an id.`);
+  const source = value.source == null ? null : String(value.source).trim();
+  if (source && !sourceIds.has(source)) {
+    throw new TypeError(`Geometry pack resource '${id}' references unknown source '${source}'.`);
+  }
+  return {
+    ...value,
+    id,
+    kind: String(value.kind || value.type || "asset"),
+    source,
+    authors: normalizeGeometryAuthors(value.authors ?? value.author),
+    license: normalizeGeometryLicense(value.license)
+  };
+}
+
+function normalizeGeometryPackMetadata(pack, namespace) {
+  const sources = (Array.isArray(pack.sources) ? pack.sources : []).map(normalizeGeometrySource);
+  const sourceIds = new Set(sources.map(source => source.id));
+  const resources = (Array.isArray(pack.resources) ? pack.resources : [])
+    .map((resource, index) => normalizeGeometryResource(resource, index, sourceIds));
+  if (new Set(resources.map(resource => resource.id)).size !== resources.length) {
+    throw new TypeError(`Geometry pack '${namespace}' contains duplicate resource ids.`);
+  }
+  return {
+    namespace,
+    name: String(pack.name || namespace),
+    version: String(pack.version || "0.0.0"),
+    description: String(pack.description || ""),
+    category: String(pack.category || pack.name || namespace),
+    homepage: pack.homepage ? String(pack.homepage) : "",
+    repository: cloneGeometryMetadata(pack.repository || null),
+    authors: normalizeGeometryAuthors(pack.authors ?? pack.author),
+    license: normalizeGeometryLicense(pack.license),
+    attribution: String(pack.attribution || ""),
+    collections: cloneGeometryMetadata(Array.isArray(pack.collections) ? pack.collections : []),
+    sources,
+    resources,
+    geometries: []
+  };
+}
 
 function publicGeometryDefinition(definition) {
-  const { create, ...metadata } = definition;
+  const { create, resourceMap, ...metadata } = definition;
   return {
-    ...metadata,
+    ...cloneGeometryMetadata(metadata),
     canonicalSize: [...definition.canonicalSize],
-    parameters: { ...definition.parameters },
-    palette: { ...definition.palette },
-    anchors: { ...definition.anchors }
+    parameters: cloneGeometryMetadata(definition.parameters),
+    palette: cloneGeometryMetadata(definition.palette),
+    anchors: cloneGeometryMetadata(definition.anchors)
   };
 }
 
+function publicGeometryPack(pack) {
+  return cloneGeometryMetadata(pack);
+}
+
 export function registerGeometryPack(pack) {
   if (!pack || typeof pack !== "object") throw new TypeError("A geometry pack must be an object.");
   const namespace = String(pack.namespace || "").trim();
-  if (!/^[a-z][a-z0-9-]*$/i.test(namespace)) throw new TypeError("A geometry pack requires a valid namespace.");
+  if (!/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/i.test(namespace)) throw new TypeError("A geometry pack requires a valid dot-separated namespace.");
   if (!Array.isArray(pack.geometries) || !pack.geometries.length) throw new TypeError("A geometry pack requires at least one geometry.");
-  const registered = [];
+
+  const metadata = normalizeGeometryPackMetadata(pack, namespace);
+  const resourceMap = Object.freeze(Object.fromEntries(
+    metadata.resources.map(resource => [resource.id, Object.freeze(cloneGeometryMetadata(resource))])
+  ));
+  const definitions = [];
   for (const source of pack.geometries) {
     if (!source || typeof source !== "object" || !source.id) throw new TypeError(`Geometry pack '${namespace}' contains an invalid geometry.`);
     const localId = String(source.id).includes(".") ? String(source.id).split(".").pop() : String(source.id);
     const id = String(source.id).includes(".") ? String(source.id) : `${namespace}.${localId}`;
-    const definition = {
+    definitions.push({
       ...source,
       id,
       localId,
       namespace,
-      pack: pack.name || namespace,
-      packVersion: pack.version || "0.0.0",
-      category: source.category || pack.category || pack.name || namespace,
+      pack: metadata.name,
+      packVersion: metadata.version,
+      category: source.category || metadata.category,
+      collection: source.collection == null ? "" : String(source.collection).trim(),
+      tags: normalizeGeometryStringList(source.tags),
+      keywords: normalizeGeometryStringList(source.keywords),
       canonicalSize: Array.isArray(source.canonicalSize) && source.canonicalSize.length === 3 ? source.canonicalSize.map(Number) : [2.5, 1.5, 2.5],
       parameters: source.parameters && typeof source.parameters === "object" ? source.parameters : {},
       palette: { ...(pack.palette || {}), ...(source.palette || {}) },
-      anchors: { ...(pack.anchors || {}), ...(source.anchors || {}) }
-    };
-    GEOMETRY_DEFINITIONS.set(id, definition);
-    GEOMETRY_ALIASES.set(id, id);
-    for (const alias of source.aliases || []) GEOMETRY_ALIASES.set(String(alias), id);
-    registered.push(id);
+      anchors: { ...(pack.anchors || {}), ...(source.anchors || {}) },
+      resourceMap
+    });
   }
+
+  unregisterGeometryPack(namespace);
+  const registered = [];
+  for (const definition of definitions) {
+    GEOMETRY_DEFINITIONS.set(definition.id, definition);
+    GEOMETRY_ALIASES.set(definition.id, definition.id);
+    for (const alias of definition.aliases || []) GEOMETRY_ALIASES.set(String(alias), definition.id);
+    registered.push(definition.id);
+  }
+  metadata.geometries = [...registered];
+  GEOMETRY_PACKS.set(namespace, metadata);
+  const registeredPack = publicGeometryPack(metadata);
   if (typeof globalThis.dispatchEvent === "function" && typeof CustomEvent === "function") {
-    globalThis.dispatchEvent(new CustomEvent("lc-geometry-registry-change", { detail: { namespace, geometries: registered } }));
+    globalThis.dispatchEvent(new CustomEvent("lc-geometry-registry-change", { detail: { namespace, geometries: registered, pack: registeredPack } }));
   }
-  return { namespace, geometries: registered };
+  return registeredPack;
 }
 
 export function unregisterGeometryPack(namespace) {
@@ -64,6 +176,7 @@ export function unregisterGeometryPack(namespace) {
     removed.push(id);
   }
   for (const [alias, id] of GEOMETRY_ALIASES) if (removed.includes(id)) GEOMETRY_ALIASES.delete(alias);
+  GEOMETRY_PACKS.delete(namespace);
   return removed;
 }
 
@@ -71,6 +184,10 @@ export function getGeometryCatalog() {
   return [...GEOMETRY_DEFINITIONS.values()].map(publicGeometryDefinition);
 }
 
+export function getGeometryPackCatalog() {
+  return [...GEOMETRY_PACKS.values()].map(publicGeometryPack);
+}
+
 function geometryDefinition(kind) {
   const id = GEOMETRY_ALIASES.get(kind) || kind;
   return GEOMETRY_DEFINITIONS.get(id) || null;
@@ -116,7 +233,11 @@ registerGeometryPack({
   namespace: "geo",
   name: "Geometric primitives",
   version: "1",
+  description: "Built-in Atlas geometric primitives.",
   category: "Geometric primitives",
+  authors: [{ name: "LiquidCars S.L.", url: "https://liquidcars.net" }],
+  license: { spdx: "MIT", url: "https://opensource.org/license/mit" },
+  homepage: "https://github.com/gaelibus/atlas",
   geometries: CORE_GEOMETRIES.map(id => ({
     id,
     primitive: id,
@@ -383,7 +504,7 @@ function createGeometryContent(definition, entity, modelPalette, invalidate, rep
     ...(entity.geometryPalette || entity.geometry_palette || {})
   };
   let descriptor = typeof definition.create === "function"
-    ? definition.create({ parameters: { ...parameters }, colors: { ...localPalette }, entity: { ...entity } })
+    ? definition.create({ parameters: { ...parameters }, colors: { ...localPalette }, entity: { ...entity }, resources: definition.resourceMap || {} })
     : { parts: definition.parts || [] };
   if (Array.isArray(descriptor)) descriptor = { parts: descriptor };
   const parts = Array.isArray(descriptor?.parts) ? descriptor.parts : [];
@@ -678,11 +799,14 @@ export function captureRendererFrame(renderer, scene, camera, ownerDocument = gl
 }
 
 class LiquidCarsAtlas extends HTMLElement {
+  static version = ATLAS_VERSION;
+
   static get observedAttributes() { return ["height", "relation-mode", "selection-mode", "selection-navigation", "item-facing", "shell-labels", "toolbar", "panel", "focus-mode", "focus-effect", "focus-layout"]; }
 
   static registerGeometryPack(pack) { return registerGeometryPack(pack); }
   static unregisterGeometryPack(namespace) { return unregisterGeometryPack(namespace); }
   static getGeometryCatalog() { return getGeometryCatalog(); }
+  static getGeometryPackCatalog() { return getGeometryPackCatalog(); }
 
   constructor() {
     super();
@@ -1436,7 +1560,7 @@ class LiquidCarsAtlas extends HTMLElement {
     return this.panBy(-dx * worldPerPixel, dy * worldPerPixel);
   }
 
-  fit() {
+  fit(options = {}) {
     const bounds = new THREE.Box3();
     for (const node of this.nodes.values()) {
       const center = this._worldPosition(node);
@@ -1452,6 +1576,10 @@ class LiquidCarsAtlas extends HTMLElement {
     const baseDistance = this._baseCameraDistance();
     this.targetZoom = Math.max(MIN_ZOOM, Math.min(2.8, baseDistance / requiredDistance));
     this.targetFocus.copy(center);
+    if (options.animate === false) {
+      this.zoom = this.targetZoom;
+      this.focus.copy(this.targetFocus);
+    }
     this.invalidate();
     return this;
   }