@thatopen/services 0.16.1 → 0.18.0

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

@@ -149,28 +149,33 @@ document.body.style.margin = "0";
   gotcha below), then appended as the toolbar's light-DOM content:
 
   ```ts
+  import { html, render } from "lit";
+
   const headlessBar = document.createElement("top-viewer-toolbar");
   headlessBar.toggleAttribute("headless", true);
 
-  const customButtons = document.createElement("bim-toolbar") as unknown as HTMLElement;
-  customButtons.setAttribute("style", "pointer-events: auto;");
+  // A plain container — the `<bim-toolbar>` itself is rendered inside it.
+  const toolbarHost = document.createElement("div");
+  toolbarHost.style.pointerEvents = "auto";
   render(
     html`
-      <bim-toolbar-section label-hidden style="background: transparent;">
-        <top-viewer-mode-toggle-button></top-viewer-mode-toggle-button>
-        <top-viewer-hide-button></top-viewer-hide-button>
-        <top-viewer-select-button></top-viewer-select-button>
-      </bim-toolbar-section>
-      <bim-toolbar-section label-hidden style="background: transparent;">
-        <bim-button
-          icon="mdi:fit-to-page-outline"
-          @click=${() => myOwnFitToViewLogic()}
-        ><bim-tooltip placement="top">Zoom to fit</bim-tooltip></bim-button>
-      </bim-toolbar-section>
+      <bim-toolbar>
+        <bim-toolbar-section label-hidden style="background: transparent;">
+          <top-viewer-mode-toggle-button></top-viewer-mode-toggle-button>
+          <top-viewer-hide-button></top-viewer-hide-button>
+          <top-viewer-select-button></top-viewer-select-button>
+        </bim-toolbar-section>
+        <bim-toolbar-section label-hidden style="background: transparent;">
+          <bim-button
+            icon="mdi:fit-to-page-outline"
+            @click=${() => myOwnFitToViewLogic()}
+          ><bim-tooltip placement="top">Zoom to fit</bim-tooltip></bim-button>
+        </bim-toolbar-section>
+      </bim-toolbar>
     `,
-    customButtons,
+    toolbarHost,
   );
-  headlessBar.appendChild(customButtons);
+  headlessBar.appendChild(toolbarHost);
   // headlessBar can now be appended anywhere inside <top-viewer>.
   ```
 
@@ -208,7 +213,7 @@ document.body.style.margin = "0";
     Custom Elements v1 forbids for elements created imperatively —
     `document.createElement("bim-button")` throws `NotSupportedError`.
     Render them with lit's `render(html\`...\`, container)` instead, exactly
-    like the `customButtons` bar above — never build them by hand.
+    like the `toolbarHost` container above — never build them by hand.
   - **`bim-button` sizes itself** — square when it's icon-only, a consistent
     height when it has a label. Don't set `width`/`height`/`min-width`
     inline on it; that only fights its own layout and produces buttons that
@@ -225,7 +230,13 @@ document.body.style.margin = "0";
   ### 🧩 Standalone buttons reference
 
   Every button the default bar uses is independently importable/usable as
-  its own custom element:
+  its own custom element. They render icon-only with a tooltip; set the
+  optional `label` attribute on any of them to show text next to the icon
+  (the tooltip stays as it is):
+
+  ```html
+  <top-viewer-hide-button label="Hide"></top-viewer-hide-button>
+  ```
 
   | Element | Does |
   |---|---|
@@ -234,19 +245,132 @@ 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>` | Activates the Clip 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 |
   | `<top-viewer-measure-area-button>` | Activates area measurement |
   | `<top-viewer-measure-angle-button>` | Activates angle measurement |
   | `<top-viewer-measure-edge-button>` | Activates edge measurement |
   | `<top-viewer-measure-face-button>` | Activates face measurement |
   | `<top-viewer-measure-volume-button>` | Activates volume measurement |
+  | `<top-viewer-measure-button>` | All measurement modes in one button (a menu by default), or a chosen subset via `modes` (see below) |
   | `<top-viewer-projection-toggle-button>` | Toggles Perspective ⇄ Orthographic |
   | `<top-viewer-walkthrough-button>` | Toggles first-person walkthrough |
+  | `<top-viewer-navigation-button>` | Switches between orbit and first-person navigation (a menu by default), or a single chosen mode via `modes` (see below) |
 
   Each one self-wires from context — drop it anywhere under `<top-viewer>`
   and it works, with no props to pass in.
+
+  ### ✂️ Clip button modes
+
+  Without any attribute, `<top-viewer-clip-button>` enters face-placing mode:
+  double-click a face in the model and a clip plane is dropped on it. The
+  optional `modes` attribute changes what the button offers — a whitespace-
+  (or comma-) separated list of `x`, `y`, `z` and `face` (case-insensitive;
+  unknown tokens are ignored, duplicates dropped, the order you write is the
+  order shown):
+
+  ```html
+  <!-- a menu with four entries: X axis, Y axis, Z axis, Face -->
+  <top-viewer-clip-button modes="x y z face"></top-viewer-clip-button>
+
+  <!-- one mode = no menu; a click creates a horizontal cut right away -->
+  <top-viewer-clip-button modes="y"></top-viewer-clip-button>
+
+  <!-- default: face-placing mode -->
+  <top-viewer-clip-button></top-viewer-clip-button>
+  ```
+
+  - **One mode** — the button runs it directly on click. `face` is the
+    default face-placing behavior.
+  - **Two or more** — clicking opens a menu with one entry per mode ("X
+    axis", "Y axis", "Z axis", "Face"); picking one runs it and closes the
+    menu.
+  - **Axis modes** create a single plane through the center of the bounding
+    box of all loaded models (nothing happens if no model is loaded). Axes
+    follow the three.js convention — **Y is vertical**, so `y` is a
+    horizontal cut. The plane's normal is the *negative* axis — `(-1, 0, 0)`,
+    `(0, -1, 0)`, `(0, 0, -1)` — so the plane clips what lies on the
+    positive side of the axis (`y` removes everything above the middle of
+    the model). Axis planes behave exactly like face-placed ones: same
+    section styling, listed in the objects outliner, draggable by their
+    gizmo, removable with Delete.
+  - The button shows as active only while face-placing mode is on.
+
+  ### 📏 Measure button modes
+
+  `<top-viewer-measure-button>` puts the measurement tools behind a single
+  button. Without any attribute it offers all six modes — `length`, `area`,
+  `angle`, `edge`, `face`, `volume` — in a menu. The optional `modes`
+  attribute picks a subset (whitespace- or comma-separated, case-insensitive;
+  unknown tokens are ignored, duplicates dropped, your order is kept):
+
+  ```html
+  <!-- default: a menu with all six modes -->
+  <top-viewer-measure-button></top-viewer-measure-button>
+
+  <!-- a menu with just these three, in this order -->
+  <top-viewer-measure-button modes="length area volume"></top-viewer-measure-button>
+
+  <!-- one mode = no menu; a click starts that measurement right away -->
+  <top-viewer-measure-button modes="length"></top-viewer-measure-button>
+  ```
+
+  - **One mode** — a click activates it directly, exactly like the matching
+    standalone button (`length` and `area` measure freely; `edge` and `face`
+    snap to edges and faces).
+  - **Two or more** — a click opens a menu with one text-labelled entry per
+    mode ("Length", "Area", "Angle", "Edge", "Face", "Volume"); picking one
+    activates it and closes the menu.
+  - The button shows as active while any of its modes is the active
+    measurement mode, and its icon switches to that mode's icon (a ruler
+    otherwise). In the menu, the active mode's entry is marked.
+
+  ### 🧭 Navigation button modes
+
+  `<top-viewer-navigation-button>` switches how the camera moves. Without any
+  attribute it offers both modes — `orbit` and `first-person` — in a menu.
+  The optional `modes` attribute narrows or reorders them (whitespace- or
+  comma-separated, case-insensitive; unknown tokens are ignored, duplicates
+  dropped, your order is kept):
+
+  ```html
+  <!-- default: a menu with "Orbit" and "First person" -->
+  <top-viewer-navigation-button></top-viewer-navigation-button>
+
+  <!-- one mode = no menu; a click switches straight to it -->
+  <top-viewer-navigation-button modes="orbit"></top-viewer-navigation-button>
+  ```
+
+  - `orbit` turns first-person navigation off (nothing happens if it already
+    is); `first-person` turns it on (nothing happens if it already is) — the
+    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.
 */