@thatopen/services 0.16.1 → 0.18.0

package/src/built-in/GISManager/example.ts

@@ -0,0 +1,326 @@
+/* MD
+  ## GISManager
+  ---
+  Georeferenced BIM projects need their surroundings: the real terrain and
+  buildings around the model, and the project's GIS layers (parcels, networks,
+  boundaries) drawn at the right place in the 3D scene and on a 2D map.
+
+  GISManager is the component that owns all of that. It streams Cesium Ion 3D
+  Tiles (Google Photorealistic 3D Tiles by default) around the project origin,
+  loads vector layers (shapefile zip or GeoJSON) declared in the project's
+  layer manifest, and renders a 2D minimap with markers.
+
+  This tutorial covers initializing the manager from the platform client;
+  enabling the 3D tiles; the layer manifest and how heights, styles and
+  coordinate systems are read; selecting and focusing features; and the 2D
+  minimap with its markers. The recommended UI is provided by `top-gis-panel`,
+  `top-map-panel` and `top-gis-properties-panel`.
+
+  GISManager reads the project origin from `ProjectManager`, so initialize
+  `ProjectManager` first.
+
+  ### 🖖 Importing our libraries
+*/
+
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as BUI from "@thatopen/ui";
+import * as THREE from "three";
+import * as FRAGS from "@thatopen/fragments";
+import { PlatformClient, GISManager, ProjectManager } from "@thatopen/services";
+
+
+/* MD
+  ### 🚀 Initializing GISManager
+  Both components are set up through the platform client.
+  `client.setup(...)` resolves the shared `OBC.Components` instance.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: ProjectManager.uuid },
+  { uuid: GISManager.uuid },
+)) as { components: OBC.Components };
+
+await components.get(ProjectManager).init(client);
+
+const gis = components.get(GISManager);
+
+/* MD
+  `init(client)` restores the project origin from `ProjectManager` and reads
+  the project's layer manifest (see below). It never throws: with no project or
+  no stored file the manager just keeps its defaults, and an empty layer list.
+*/
+
+await gis.init(client);
+console.log("layers:", gis.vectorLayersConfig);
+
+/* MD
+  ### 🌍 3D tiles
+  Streaming the tiles needs a Cesium Ion token. The component does not persist
+  the token anywhere: your application provides it (from its own settings, or
+  typed by the user in `top-gis-panel`) before enabling the tiles.
+
+  `enableTiles()` resolves once the first tiles are loaded and rejects with a
+  readable message if the token is invalid or has no access to the tileset (the
+  same message is also fired through `onLoadError`).
+*/
+
+gis.onLoadError.add((message) => console.warn("GIS tiles:", message));
+
+gis.apiToken = "<your Cesium Ion token>";
+await gis.enableTiles();
+
+/* MD
+  `onStateChanged` fires whenever the token, origin, tiles visibility, tiles
+  offset or tiles opacity change, with a plain snapshot of all of them.
+  `setTilesOpacity(0.5)` makes the tiles see-through (1 = opaque), which lets
+  you see vector layers that run underground. `disableTiles()` unloads
+  everything.
+
+  On hosts whose engine supports the deferred postproduction pipeline, the
+  tiles and the vector layers are drawn through an occlusion pass, which is what
+  makes the see-through effect possible. On other hosts they are added to the
+  scene directly and stay opaque. You do not need to do anything for this: the
+  component detects it.
+*/
+
+gis.onStateChanged.add((state) => console.log("tiles visible:", state.tilesVisible));
+gis.setTilesOpacity(0.6);
+
+/* MD
+  A small East/North/Up correction (in metres) can be applied to the tiles to
+  compensate for the tileset's own positioning error. Persist it with
+  `saveTilesOffset()`; it is stored in the same file as the layer manifest and
+  restored by `init`.
+*/
+
+gis.onOffsetSaveComplete.add((success) => console.log("offset saved:", success));
+gis.setTilesOffset(0.5, -0.3, 0);
+gis.saveTilesOffset();
+
+/* MD
+  ### 🗂️ The layer manifest
+  The vector layers of a project are declared in one JSON file,
+  `{GISManager.uuid}.json`, stored loose in the project's `__project_data`
+  folder. `init(client)` reads it into `gis.vectorLayersConfig`; it only holds
+  metadata (the geometry stays in the layer's own file, referenced by `fileId`
+  and downloaded when the layer is loaded).
+
+  There is no user interface to register layers yet: the manifest is written by
+  your application (or by hand). The component only reads it, and rewrites it
+  (keeping `layers` as they are) when the tiles offset is saved.
+
+  Each entry of `layers` has:
+
+  - `id` — unique id, used by every API below.
+  - `name` — display name (shown by the panels).
+  - `fileId` — id of the layer's file in the project.
+  - `type` — `"shapefile"` (a zip with the `.shp`, `.dbf`, `.prj`… files) or
+    `"geojson"`. If it is missing or unrecognised the downloaded bytes decide:
+    a zip signature means shapefile, a leading `{` means GeoJSON.
+  - `style` — `stroke` (CSS colour), `stroke-width` (pixels), `fill` (CSS
+    colour, polygons) and `fill-opacity` (0 to 1). All optional.
+  - `height` — optional, how features get their height (next section).
+
+  Here is a complete manifest with a points layer whose vertices carry their
+  own height, and a lines layer whose heights come from its attributes:
+
+  ```json
+  {
+    "layers": [
+      {
+        "id": "manholes",
+        "name": "Manholes",
+        "fileId": "<file id of manholes.zip>",
+        "type": "shapefile",
+        "style": { "stroke": "#ffb300", "stroke-width": 6 },
+        "height": { "source": "geometry" }
+      },
+      {
+        "id": "pipes",
+        "name": "Pipes",
+        "fileId": "<file id of pipes.geojson>",
+        "type": "geojson",
+        "style": { "stroke": "#1e88e5", "stroke-width": 3 },
+        "height": {
+          "source": "attributes",
+          "startProperty": "z_start",
+          "endProperty": "z_end",
+          "startDepthProperty": "depth_start",
+          "endDepthProperty": "depth_end",
+          "nodeLayers": ["manholes"],
+          "nodeSnapDistance": 0.5
+        }
+      }
+    ],
+    "tilesOffset": { "east": 0.5, "north": -0.3, "up": 0 }
+  }
+  ```
+
+  Once `init` has read it, every layer can be loaded and unloaded by id.
+  `loadVectorLayer` downloads and parses the file; it never throws, failures
+  are reported through `onVectorLayerError`.
+*/
+
+gis.onLayersLoaded.add((layers) => console.log("manifest read:", layers.length, "layers"));
+gis.onVectorLayerError.add(({ id, message }) => console.warn(`Layer ${id}:`, message));
+
+await gis.loadVectorLayer("manholes");
+await gis.loadVectorLayer("pipes");
+
+console.log("loaded:", gis.vectorLayers.isLayerLoaded("pipes"));
+
+gis.unloadVectorLayer("manholes");
+
+/* MD
+  ### 📏 Layer heights
+  The `height` option of a layer decides at what height its features are drawn:
+
+  - **No `height`** — the layer is drawn flat, at the origin's height.
+  - **`{ "source": "geometry" }`** — every vertex is placed at its own Z (the
+    third GeoJSON coordinate). If any vertex of the layer has no Z, the whole
+    layer is drawn flat instead (with a console warning).
+  - **`{ "source": "attributes", … }`** — for line features only (other
+    geometry types are drawn flat). A line gets a height at its first vertex
+    and at its last one, and the vertices in between are interpolated along
+    the line. Each end is resolved in this order:
+      1. its own height property (`startProperty` / `endProperty`);
+      2. otherwise the surface height of the nearest node minus its depth
+         property (`startDepthProperty` / `endDepthProperty`). Nodes are the
+         points with a Z found in the layers listed in `nodeLayers`, and
+         "nearest" means within `nodeSnapDistance` metres (0.5 by default) of
+         the line end;
+      3. otherwise the height resolved for the other end (the line is drawn
+         level);
+      4. otherwise the surface height of the nearest node.
+
+    A property counts as missing when it is not a finite number or is exactly
+    `0`. Rules 1 and 2 are tried on both ends before rule 3 is applied, so a
+    copied height never comes from another copy. A line for which no rule can
+    give a height to both ends is not drawn (one console warning per layer
+    summarizes how many).
+
+  All heights are orthometric (the usual survey heights above the geoid). The
+  component adds the project's geoid undulation, taken from the `ProjectManager`
+  CRS, to place them in the scene, and re-places the loaded layers if it changes.
+*/
+
+/* MD
+  ### 🧭 GeoJSON coordinate systems
+  Shapefiles are read with their `.prj`. For GeoJSON layers, the coordinate
+  system comes from the legacy `crs` member of the file:
+
+  - Longitude/latitude (`CRS84`, or `EPSG:4326`) is read as it is.
+  - `EPSG:3857` and the UTM zones (`EPSG:326xx`, `327xx`, `258xx` and `269xx`)
+    are reprojected to longitude/latitude when the layer loads.
+  - Any other declared CRS is rejected, and so are projected coordinates in a
+    file that declares no `crs`.
+
+  A rejected layer is not loaded, and the reason (for example `Unsupported CRS
+  "EPSG:2154"…`) is delivered through `onVectorLayerError`, which is what the
+  GIS panel shows as a toast.
+*/
+
+/* MD
+  ### 🖱️ Selection and focus
+  Clicking a feature in the 3D view selects it. `onFeatureSelected` delivers
+  the selection (`layerId`, `layerName`, `featureIndex`, `geometryType` and the
+  feature's `properties`), or `null` when the selection is cleared. The current
+  selection can also be read at any time from `gis.vectorLayers.selection`.
+
+  Your application can select a feature too, optionally flying the camera to
+  it. `onFocusRequested` fires with the bounding sphere the camera is sent to,
+  which is how the 2D map follows.
+*/
+
+gis.onFeatureSelected.add((selection) => {
+  if (!selection) return console.log("selection cleared");
+  console.log(selection.layerName, selection.geometryType, selection.properties);
+});
+
+gis.onFocusRequested.add(({ layerId, featureIndex, sphere }) => {
+  console.log("focusing", layerId, featureIndex, "radius:", sphere.radius);
+});
+
+gis.selectVectorFeature("pipes", 0, { focus: true });
+gis.vectorLayers.clearSelection();
+
+/* MD
+  ### 🗺️ The 2D minimap
+  `gis.minimap` renders a top-down, north-up image of the 3D tiles that
+  `top-map-panel` draws together with the vector layers, the camera and the
+  markers.
+
+  `captureMap()` takes the picture. The 3D tiles must be loaded (without them
+  the image is empty). The captured area is the bounding box of all the
+  manifest's layers, whether they are displayed or not; with no usable layers it
+  is a square of `2 * halfExtent` metres (250 by default) centred on the origin.
+  The image has a fixed side of `resolution` pixels (2048 by default, limited by
+  the GPU), so the larger the area, the coarser the map.
+*/
+
+gis.minimap.onCaptured.add((capture) => console.log("map captured:", capture.size, "px"));
+
+gis.minimap.halfExtent = 400;
+gis.minimap.resolution = 4096;
+const capture = await gis.minimap.captureMap();
+document.body.appendChild(capture.image);
+
+/* MD
+  `worldToMap` converts a scene position into normalized image coordinates
+  (0 to 1, origin at the top-left), and `mapToWorld` does the opposite for a
+  horizontal plane at a given height. Both return `null` until a map has been
+  captured.
+*/
+
+const point = gis.vectorLayers.geoToWorld(gis.latitude, gis.longitude, gis.height);
+const onMap = gis.minimap.worldToMap(point);
+console.log("origin on the map:", onMap);
+console.log("back to the scene:", onMap && gis.minimap.mapToWorld(onMap.x, onMap.y, point.y));
+
+/* MD
+  ### 📍 Minimap markers
+  Markers are HTML elements drawn over the map by `top-map-panel`. They live in
+  the minimap, not in the panel, so they survive the panel being recreated.
+
+  A marker has an `id`, a scene `position` (read on every redraw, so changing
+  it moves the marker), an optional `label` and an optional `createElement`
+  factory. Without the factory the panel draws a default badge with the label
+  and reports its clicks through `onMarkerClicked`. With it, the marker is your
+  own element and it owns its click behaviour. It is a factory and not an
+  element because each panel needs its own DOM node.
+
+  `geoToWorld(lat, lon, height)` turns a geographic position into a scene
+  position.
+*/
+
+gis.minimap.onMarkersChanged.add(({ kind, id }) => console.log("markers:", kind, id));
+gis.minimap.onMarkerClicked.add((id) => console.log("clicked:", id));
+
+gis.minimap.addMarker({
+  id: "site-office",
+  label: "Site office",
+  position: gis.vectorLayers.geoToWorld(gis.latitude, gis.longitude, gis.height),
+});
+
+gis.minimap.addMarker({
+  id: "crane",
+  position: new THREE.Vector3(-20, 0, 35),
+  createElement: () => {
+    const pin = document.createElement("div");
+    pin.textContent = "🏗️";
+    pin.style.fontSize = "1.4rem";
+    pin.style.cursor = "pointer";
+    pin.onclick = () => console.log("crane clicked");
+    return pin;
+  },
+});
+
+gis.minimap.updateMarker("site-office", { label: "Main office" });
+console.log("markers:", [...gis.minimap.markers.keys()]);
+
+gis.minimap.removeMarker("crane");
+gis.minimap.clearMarkers();

package/src/built-in/UIManager/src/app/examples/Sidebar/example.ts

@@ -73,8 +73,11 @@ app.elements = {
 };
 
 app.layouts = {
-  // Each layout defines its own CSS grid template. Only areas used in a template
-  // are rendered for that layout — unused elements are not created.
+  // Each layout defines its own CSS grid template. The app mounts the UNION
+  // of every layout's areas ONCE and switching layouts toggles which are
+  // visible (the rest stay mounted with display:none), so panel state
+  // survives a switch - element factories run on mount, not per layout.
+  // To react to a switch, listen for the `top:layout-changed` event.
   viewer: {
     label: "Viewer",
     icon: "solar:3d-square-bold",

package/src/built-in/UIManager/src/gis-panel/example.ts

@@ -0,0 +1,163 @@
+/* MD
+  ## gis-panel
+  ---
+  A georeferenced project is much easier to review with its real surroundings
+  around the model, and with the GIS layers of the site (networks, parcels,
+  boundaries) switched on and off from a list. Streaming the terrain and
+  buildings needs a Cesium Ion token and a way to load and unload them, and
+  fine-tuning their position needs a few controls.
+
+  `gis-panel` is a ready-made web component that delivers all of that. It
+  connects to `GISManager` automatically and gives the user the token input, the
+  button that loads the 3D map, the position fine-tune and the list of the
+  project's vector layers.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping it
+  into a `top-app` layout next to a 3D viewer; and a breakdown of everything the
+  panel handles automatically so you know what you do not need to implement
+  yourself.
+
+  By the end, you'll have the GIS controls of your project running in your
+  application with a single line of markup.
+*/
+
+import { html } from "lit";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient, UIManager, GISManager, ProjectManager } from "@thatopen/services";
+import type { App } from "../app/index";
+
+
+/* MD
+  ### ✅ Prerequisites
+
+  Three conditions must be met before the panel mounts:
+
+  1. **`UIManager` must be in the setup call.** It registers all platform web
+     components, including `<top-gis-panel>` itself. Without it the element is
+     unknown to the browser and renders as an empty box.
+
+  2. **`ProjectManager.init(client)` must have resolved.** `GISManager` takes
+     the project origin from it: without it the 3D tiles and the vector layers
+     are placed around a default origin instead of the project's.
+
+  3. **`GISManager.init(client)` must have resolved**, after `ProjectManager`.
+     The panel reads the manager's state when it is
+     connected to the document (the token, the tiles state, the tiles offset and
+     the layer list), then follows its events. Without `init`, the manifest is
+     never read, so the layer list stays empty, and the tiles offset cannot be
+     saved.
+
+  Both are satisfied by awaiting the two `init`s, in that order, before
+  appending `top-app` to the document, which is the pattern shown below.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+  { uuid: ProjectManager.uuid },
+  { uuid: GISManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// Order matters: GISManager reads the origin that ProjectManager has loaded.
+await components.get(ProjectManager).init(client);
+await components.get(GISManager).init(client);
+
+/* MD
+  ### 🖥️ Wiring the panel
+
+  Add `gis-panel` as a named area in `app.elements` and reference it in your
+  layout template. A narrow column on the left of the 3D viewer is the natural
+  arrangement: the tiles and the layers are drawn in the viewer's scene.
+*/
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  waitUntil(
+    (async () => {
+      const fragments = components.get(OBC.FragmentsManager);
+      const workerUrl = await FRAGS.FragmentsModels.getWorker();
+      fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+    })(),
+    "Fragments Core",
+  );
+
+  return { components, client };
+};
+
+app.elements = {
+  gis:    () => html`<top-gis-panel></top-gis-panel>`,
+  viewer: () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+};
+
+app.layouts = {
+  main: {
+    label:    "Main",
+    icon:     "mdi:earth",
+    template: `"gis viewer" 1fr / 22rem 1fr`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What the panel manages automatically
+
+  Once mounted, `gis-panel` takes ownership of the following without any
+  further code from you:
+
+  **Cesium Ion token** — a password field holds the token. It is written to
+  `GISManager.apiToken` as the user types. The panel does not store it: if
+  you want it to survive a reload, set `gis.apiToken` yourself before the
+  panel mounts.
+
+  **Loading the 3D map** — the "Load GIS Map" button calls `enableTiles()`
+  (disabled until there is a token) and turns into "Unload GIS Map", which calls
+  `disableTiles()`. While the tiles load the button shows its loading state. A
+  success toast confirms the load, and a failure shows the readable message
+  coming from `onLoadError` (invalid token, no access to the tileset, rate
+  limit, no connection).
+
+  **Tiles fine-tune offset** — three sliders (East, North, Up, in metres) move
+  the tiles through `setTilesOffset`. Once the offset differs from the saved
+  one, a "Save offset" button appears. It calls `saveTilesOffset()`, which
+  writes the offset into the project's layer manifest, and a toast reports
+  whether the save worked. The offset is restored by `GISManager.init` the next
+  time the project is opened.
+
+  **Vector layers** — a table lists the layers declared in the manifest
+  (`vectorLayersConfig`), each with a checkbox. Checking it loads the layer
+  (`loadVectorLayer`), unchecking it removes it (`unloadVectorLayer`), and the
+  row shows "(loading…)" in between. If a layer cannot be read, for example an
+  unsupported coordinate system, an error toast carries the reason reported by
+  `onVectorLayerError`. The list updates by itself if the manifest is read
+  after the panel mounts.
+
+  **Registering layers** — the panel only lists and toggles the layers the
+  manifest already declares. There is no user interface to upload a shapefile or
+  a GeoJSON file, name it and style it yet: your application writes the
+  manifest (see the `GISManager` tutorial for its format).
+
+  **Origin** — the project origin is not edited here. It belongs to
+  `ProjectManager`, and it is set from the "Coordinates" section of the settings
+  panel. The tiles and the layers follow it live.
+
+  **Notifications** — every toast is a `top:notification` event that bubbles up
+  to `top-app`, which displays it.
+
+  **Disconnection cleanup** — when the panel is removed from the DOM it
+  unsubscribes from every `GISManager` event. The 3D map and the layers stay
+  loaded.
+*/

package/src/built-in/UIManager/src/gis-properties-panel/example.ts

@@ -0,0 +1,168 @@
+/* MD
+  ## gis-properties-panel
+  ---
+  A GIS feature (a pipe, a parcel, a manhole) is useless without its
+  attributes: diameter, material, owner, installation date. Users want to
+  click a feature, in the 3D view or on the map, and read them.
+
+  `gis-properties-panel` is a ready-made web component that delivers exactly
+  that. It connects to `GISManager` automatically and shows the attribute table of
+  the selected vector feature, with a filter and readable values.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping it
+  into a `top-app` layout next to the map; a breakdown of everything the panel
+  handles automatically; and how an application can use one properties column
+  for both BIM and GIS selections.
+
+  By the end, you'll have GIS attributes on screen with a single line of markup.
+*/
+
+import { html } from "lit";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient, UIManager, GISManager, ProjectManager } from "@thatopen/services";
+import type { App } from "../app/index";
+
+
+/* MD
+  ### ✅ Prerequisites
+
+  Three conditions must be met before the panel mounts:
+
+  1. **`UIManager` must be in the setup call.** It registers all platform web
+     components, including `<top-gis-properties-panel>` itself. Without it the element is
+     unknown to the browser and renders as an empty box.
+
+  2. **`ProjectManager.init(client)` must have resolved.** `GISManager` takes
+     the project origin from it: without it the 3D tiles and the vector layers
+     are placed around a default origin instead of the project's.
+
+  3. **`GISManager.init(client)` must have resolved**, after `ProjectManager`.
+     The panel itself only listens to selections, but
+     without `init` the manifest is never read, so there are no layers to
+     select. A panel created after a selection already exists shows that
+     selection straight away.
+
+  Both are satisfied by awaiting the two `init`s, in that order, before
+  appending `top-app` to the document, which is the pattern shown below.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+  { uuid: ProjectManager.uuid },
+  { uuid: GISManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// Order matters: GISManager reads the origin that ProjectManager has loaded.
+await components.get(ProjectManager).init(client);
+await components.get(GISManager).init(client);
+
+/* MD
+  ### 🖥️ Wiring the panel
+
+  Add `gis-properties-panel` as a named area. Next to the map is the usual
+  place: the user clicks a feature on the map or in the 3D view, and reads
+  its attributes in the column beside it. Selecting features on the map requires
+  `map-panel` (and, as it is documented there, see-through terrain).
+*/
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  waitUntil(
+    (async () => {
+      const fragments = components.get(OBC.FragmentsManager);
+      const workerUrl = await FRAGS.FragmentsModels.getWorker();
+      fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+    })(),
+    "Fragments Core",
+  );
+
+  return { components, client };
+};
+
+app.elements = {
+  gis:        () => html`<top-gis-panel></top-gis-panel>`,
+  viewer:     () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+  map:        () => html`<top-map-panel></top-map-panel>`,
+  properties: () => html`<top-gis-properties-panel></top-gis-properties-panel>`,
+};
+
+app.layouts = {
+  main: {
+    label:    "Main",
+    icon:     "mdi:information-outline",
+    template: `"gis viewer map" 1fr "gis viewer properties" 1fr / 20rem 1fr 26rem`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What the panel manages automatically
+
+  Once mounted, `gis-properties-panel` takes ownership of the following without
+  any further code from you:
+
+  **Selection tracking** — the panel subscribes to `GISManager.onFeatureSelected`,
+  so it shows the selected feature whether the click came from the 3D view, the
+  map, or your own call to `selectVectorFeature`.
+
+  **Attribute table** — the section is titled with the layer's name, shows the
+  geometry type, and lists every attribute of the feature as a name and a value.
+
+  **Filter** — a search box filters the table by attribute name or by visible
+  value.
+
+  **Value formatting** — numbers and text are shown as they are, booleans as
+  Yes/No, dates as `YYYY-MM-DD` (with the time when they have one) and complex
+  values as JSON. Empty values (null, blank text, invalid dates, non-finite
+  numbers) are shown as a dimmed dash, and are not matched by the filter.
+
+  **Empty state** — with no selection the panel explains that an element of a
+  vector layer has to be selected, and it goes back to that state when the
+  selection is cleared.
+
+  **Disconnection cleanup** — when the panel is removed from the DOM it
+  unsubscribes from the manager.
+*/
+
+/* MD
+  ### 🔀 One properties column for BIM and GIS
+
+  The panel only knows about GIS features. If your application has a single
+  properties column, switch what it shows from the selection events: the GIS
+  panel when a vector feature is selected, the BIM `top-properties-panel` when
+  a BIM element is. Keep both elements alive and swap them inside one stable
+  container.
+*/
+
+const gis = components.get(GISManager);
+
+const bimProperties = document.createElement("top-properties-panel");
+const gisProperties = document.createElement("top-gis-properties-panel");
+const column = document.createElement("div");
+column.style.height = "100%";
+column.append(bimProperties);
+
+gis.onFeatureSelected.add((selection) => {
+  if (selection) column.replaceChildren(gisProperties);
+});
+
+components.get(OBF.Highlighter).events.select.onHighlight.add(() => {
+  column.replaceChildren(bimProperties);
+});
+
+// Render `column` from the `properties` element of the layout above.