@thatopen/services 0.17.0 → 0.18.0

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.

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

@@ -0,0 +1,189 @@
+/* MD
+  ## map-panel
+  ---
+  In a large site, the 3D camera alone is a poor way to get oriented: users
+  want a plan view to see where they are, where the GIS features are, and to
+  jump somewhere else with a click.
+
+  `map-panel` is a ready-made web component that delivers exactly that: a
+  top-down, north-up map of the GIS tiles with the project's vector layers drawn
+  over it, a marker for the 3D camera, and your own markers. It connects to
+  `GISManager` automatically, and everything on it stays synchronized with
+  the 3D view.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping it
+  into a `top-app` layout beside the 3D viewer; a breakdown of everything the
+  panel handles automatically; and how an application adds its own markers.
+
+  By the end, you'll have an interactive minimap 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-map-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 needs the 3D tiles to capture the map, and
+     `init` is what reads the layer manifest: the captured area is the box
+     of all the manifest's layers, so without `init` the area falls back to a
+     square around the origin and no layers are drawn over the map.
+
+  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 `map-panel` as a named area next to the viewer. The map can only be
+  captured once the 3D tiles are loaded, so this layout also mounts
+  `gis-panel`, which lets the user enter the token and load the map. Your
+  application can do the same by code with `GISManager.enableTiles()`. The
+  viewer also carries `top-viewer-gis-ghost-button` in a toolbar, which makes the
+  map see-through so its vector features can be picked.
+*/
+
+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-toolbar headless>
+        <top-viewer-gis-ghost-button></top-viewer-gis-ghost-button>
+      </top-viewer-toolbar>
+    </top-viewer>
+  `,
+  map:    () => html`<top-map-panel></top-map-panel>`,
+};
+
+app.layouts = {
+  main: {
+    label:    "Main",
+    icon:     "mdi:map-search-outline",
+    template: `"gis viewer map" 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, `map-panel` takes ownership of the following without any
+  further code from you:
+
+  **Capturing the map** — a "Capture map" button calls `minimap.captureMap()`.
+  It is disabled until the 3D tiles are loaded, with a hint saying so, and a
+  failed capture is reported as a toast. A map that has already been captured
+  stays on screen if the tiles are unloaded afterwards. The area is the box of
+  all the manifest's layers (a square around the origin when there are none),
+  and the image has a fixed resolution.
+
+  **Pan and zoom** — the wheel zooms around the cursor and dragging pans. The
+  zoom is limited by the image's resolution: the map never magnifies the image
+  beyond the point where it is just blur.
+
+  **Live vector layers** — the loaded layers are drawn as 2D vectors under the
+  captured image (so they stay crisp at any zoom), with the style of the
+  manifest. Where the terrain is opaque it hides them, just like in 3D.
+
+  **Hover and selection, in sync with 3D** — moving over a feature highlights it
+  on the map and in the 3D view, and the selected feature is highlighted in both.
+  Hovering and clicking features on the map only work while the terrain is
+  see-through, since you cannot pick what you cannot see. The
+  `<top-viewer-gis-ghost-button>` placed in the viewer toolbar above toggles it
+  (it is disabled until the tiles are loaded). An application without a toolbar
+  can call `GISManager.setTilesOpacity` with a value below 1 instead.
+
+  **Click to select and focus** — a click on a feature selects it, exactly like a
+  3D click (`onFeatureSelected` fires), and the 3D camera flies to it while the
+  map zooms to the same neighbourhood. A click on empty ground moves the 3D
+  camera there, keeping its height and viewing direction, and leaves the
+  selection alone.
+
+  **Camera indicator** — an arrow and a view cone show where the 3D camera is and
+  where it looks, live.
+
+  **Markers** — the markers added to `GISManager.minimap` are drawn over the map
+  and follow its zoom and pan (see the next section). Markers without their own
+  element are drawn as a default badge showing the label.
+
+  **Disconnection cleanup** — when the panel is removed from the DOM it
+  unsubscribes from the manager and clears the hover it had set. The capture and
+  the markers live in `GISManager`, so a recreated panel (for example after the
+  user switches layout) shows them again straight away.
+*/
+
+/* MD
+  ### 📍 Adding your own markers
+
+  The markers belong to `GISManager.minimap`, not to the panel. Add them with a
+  scene position (`vectorLayers.geoToWorld` converts a latitude and a longitude)
+  and, optionally, a `createElement` factory to draw them your way. Without the
+  factory the panel draws a badge with the label and reports the clicks through
+  `onMarkerClicked`.
+*/
+
+const gis = components.get(GISManager);
+
+gis.minimap.addMarker({
+  id: "site-office",
+  label: "Site office",
+  position: gis.vectorLayers.geoToWorld(gis.latitude, gis.longitude, gis.height),
+});
+
+gis.minimap.onMarkerClicked.add((id) => console.log("marker clicked:", id));

package/src/built-in/UIManager/src/models-list/example.ts

@@ -7,7 +7,7 @@
 
   A behaviour worth knowing: registering a loader does NOT control whether a file shows up in the tree — the tree always mirrors the project's real storage folders, so an unrecognized file is still listed as long as it's a source (IFC/LAS/PLY) or derivative (`.frag`/`.potree`/`.splat`) extension; the loaders registry only decides whether a file's row gets a load action or none.
 
-  Known gaps (intentionally deferred, not forgotten): file upload and the base-model/auto-coordinate settings aren't ported, so `allow-upload` is currently a no-op. Everything else per-file is here, including editable attach/detach via a picker — MINUS delete, dropped on purpose. See `models-list/legacy-example.ts` + `models-list/impl.ts` for the retired implementation those gaps would be ported from.
+  Known gaps (intentionally deferred, not forgotten): the base-model/auto-coordinate settings aren't ported, and the panel has no default upload of its own: `allow-upload` is opt-in (off by default) and adds an "Upload file" item to the row menu of the root and folder rows, which hands each picked file to the uploader you registered for its extension (see the uploader section below) — files with no uploader aren't uploaded. Everything else per-file is here, including editable attach/detach via a picker — MINUS delete, dropped on purpose. See `models-list/legacy-example.ts` + `models-list/impl.ts` for the retired implementation those gaps would be ported from.
 
   By the end you'll have a files tree that knows how to load a custom format and how to run a custom IFC conversion, with the panel's UI untouched.
 */
@@ -57,7 +57,9 @@ const modelsList = document.createElement("top-models-list") as ModelsListV2;
 // ── Extension point 1: a custom loader, keyed by file extension ──────────────
 // A ModelLoader is `(fileId, ctx) => void | Promise<void>`. The panel calls it
 // when the user loads a file whose extension matches. `ctx` gives you everything
-// you need: { name, ext, components, client, getAlignment, setAlignment }. Do
+// you need: { name, ext, components, client, getAlignment, setAlignment, progress }.
+// For a long-running load call `ctx.progress(percent, label?)` to show it on the
+// row (omit `percent` while unknown). Do
 // whatever it takes to put the file in the scene — fetch it via the client,
 // parse it, and add geometry to a world from `components`.
 modelsList.registerLoader("xyz", async (fileId, ctx) => {
@@ -87,6 +89,63 @@ modelsList.registerLoader("xyz", async (fileId, ctx) => {
 //     },
 //   });
 
+// ── Upload: opt in, then register an uploader per file extension ─────────────
+// `allow-upload` adds an "Upload file" item to the row menu of the root and
+// folder rows. It opens a file picker and hands each picked file to the
+// uploader registered for its extension, which fully owns that upload. Files
+// whose extension has no uploader are not uploaded (the user gets a warning).
+// `ctx` carries { name, ext, folderId, projectId, components, client };
+// `folderId` is undefined when the upload was started from the root row. While
+// the uploader runs, the panel shows a temporary row for the file; call
+// `ctx.progress(percent, label?)` to drive its progress bar (omit `percent`
+// while unknown for a spinner). The list refreshes once an uploader has run.
+modelsList.setAttribute("allow-upload", "");
+modelsList.registerUploader("ifc", async (file, ctx) => {
+  // Create the file in `ctx.folderId` (or the project root) with `ctx.client`,
+  // upload `file`'s bytes, and report success/failure however your app does.
+  ctx.progress(undefined, "Preparing…");
+  ctx.progress(50);
+  console.log(`[ifc uploader] would upload "${file.name}" to`, ctx.folderId ?? "the project root");
+});
+
+// Declarative form: modelsList.uploaders = { ifc: async (file, ctx) => { ... } };
+
+// ── File actions: extra entries in a file row's three-dots menu ──────────────
+// The menu already holds the panel's own items (fit camera, attach/detach); the
+// actions you register for an extension are added after them. Pass a fixed list,
+// or a resolver that runs every time the menu opens (it may be async — the menu
+// shows a loading state meanwhile). While an action runs the file's row shows
+// its status instead of its buttons: call `ctx.progress(percent, label?)` to
+// drive it, and `ctx.reload()` if the action added/removed/renamed files.
+modelsList.registerActions("ifc", [
+  {
+    label: "Re-index",
+    icon: "mdi:database-refresh-outline",
+    run: async (fileId, ctx) => {
+      ctx.progress(undefined, "Indexing…");
+      // await ctx.client.…
+      ctx.progress(100);
+      console.log(`[ifc action] re-indexed "${ctx.name}" (${fileId})`);
+    },
+  },
+]);
+modelsList.registerActions("ply", async (fileId, ctx) => {
+  // Build the menu from state fetched when it opens, e.g. whether a derived
+  // file already exists for `fileId` (using `ctx.client`).
+  const alreadyConverted = false;
+  return [
+    {
+      label: "Regenerate 3D tiles",
+      icon: "mdi:cube-scan",
+      disabled: !alreadyConverted,
+      run: async (_id, actionCtx) => {
+        actionCtx.progress(25, "Converting…");
+        await actionCtx.reload();
+      },
+    },
+  ];
+});
+
 // ── Extension point 2: override the IFC → fragments converter ────────────────
 // OMIT this to keep the built-in default (drives the project's IfcFragmenter
 // cloud component via the platform client). Provide it to run conversion

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

@@ -94,10 +94,12 @@ components.get(UIManager).init();
   ghost, show all, clear selection) that also registers the actual keyboard
   shortcuts while mounted.
 
-  **Search box** — filters every section's own rows by label, stock or
-  custom, as long as a section opts in (see below).
+  **Search box** — sits at the top of the panel, above the sections, and
+  filters every section's own rows by label, stock or custom, as long as a
+  section opts in (see below).
 
-  **Restore defaults** — a two-click-confirm button that resets every
+  **Restore defaults** — a two-click-confirm button in the panel header that
+  resets every
   section with persisted state (currently: Graphics) back to its defaults.
 
   ### 🧩 Building your own section

package/src/built-in/UIManager/src/viewer-toolbar/example.ts

@@ -245,8 +245,9 @@ document.body.style.margin = "0";
   | `<top-viewer-show-button>` | Un-hides the target set |
   | `<top-viewer-isolate-button>` | Shows only the target set |
   | `<top-viewer-ghost-button>` | Renders the target set semi-transparent |
+  | `<top-viewer-gis-ghost-button>` | Makes the GIS map (the 3D tiles of `GISManager`) see-through ⇄ opaque; disabled until the tiles are loaded; the optional `opacity` attribute (0 to 1, default `0.3`) sets the see-through level |
   | `<top-viewer-focus-button>` | Frames the camera on the target set |
-  | `<top-viewer-reset-button>` | Restores full visibility + opacity (global) |
+  | `<top-viewer-reset-button>` | Shows everything and clears ghosting (global); the optional `reset` attribute can also remove sections and measurements (see below) |
   | `<top-viewer-select-button>` | Activates the default Select tool |
   | `<top-viewer-clip-button>` | Clipping planes: face-placing mode by default, or axis planes / a mode menu via `modes` (see below) |
   | `<top-viewer-measure-length-button>` | Activates length measurement |
@@ -349,4 +350,27 @@ document.body.style.margin = "0";
     same first-person navigation `<top-viewer-walkthrough-button>` toggles.
   - The button's icon always shows the current mode, and the button is active
     while first-person is on. In the menu, the current mode's entry is marked.
+  ### ♻️ Reset button options
+
+  By default `<top-viewer-reset-button>` restores full visibility and clears
+  ghosting. The optional `reset` attribute lists what it resets — any of
+  `visibility`, `sections` (every clipping plane and its section styling)
+  and `measurements` (every measurement), whitespace- or comma-separated,
+  case-insensitive, unknown tokens ignored:
+
+  ```html
+  <!-- default: visibility only -->
+  <top-viewer-reset-button></top-viewer-reset-button>
+
+  <!-- reset everything -->
+  <top-viewer-reset-button reset="visibility sections measurements"></top-viewer-reset-button>
+  ```
+
+  - Parts always run in the order visibility, sections, measurements, and one
+    failing part doesn't stop the others.
+  - When `sections` or `measurements` is listed, the viewer returns to the
+    default Select tool afterwards, so nobody is left inside a half-finished
+    measure or clip mode.
+  - The tooltip describes what the button resets, and first-person navigation
+    is left as it is.
 */