@thatopen/services 0.11.0 → 0.12.0

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

@@ -0,0 +1,163 @@
+/* MD
+  ## ProjectManager
+  ---
+  Project-level configuration and data — GIS origin, georeferencing, app
+  settings, and other project-scoped concerns — need a single canonical place
+  to live. Without it, every builtin that needs to persist something at the
+  project level (not per-file, not per-user) ends up inventing its own file,
+  its own save/load pattern, and its own place to put it.
+
+  ProjectManager is that canonical store. It persists one JSON file
+  (`${ProjectManager.uuid}.json`) loose directly inside `__project_data` — the
+  same folder convention `GISManager` already used — rather than in a
+  per-app subfolder like `collider`/`cde`, which are reserved for secondary,
+  per-builtin data.
+
+  This tutorial covers initializing the manager from the platform client; the
+  `origin` and `graphicsSettings` singletons; the `bimCoordinates` sites
+  collection used for BIM georeferencing; the `assetCoordinates` collection
+  used for splats and point clouds; auto-save and its events; and the
+  read-only namespace introspection API.
+
+  ProjectManager has no built-in UI panel — it's a pure data layer. Apps that
+  need georeferencing or project-settings UI (like Aqualia's viewer) build it
+  on top of this.
+
+  ### 🖖 Importing our libraries
+*/
+
+import * as OBC from "@thatopen/components";
+import { PlatformClient, ProjectManager } from "@thatopen/services";
+
+
+/* MD
+  ### 🚀 Initializing ProjectManager
+  Like any other built-in, ProjectManager is set up through the platform
+  client. `client.setup(...)` resolves the shared `OBC.Components` instance
+  and gives us back everything we need.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC },
+  { uuid: ProjectManager.uuid },
+)) as { components: OBC.Components };
+
+const manager = components.get(ProjectManager);
+
+/* MD
+  `init(client)` loads the persisted JSON for the current project — or
+  creates it with the default schema if it doesn't exist yet. `manager.ready`
+  flips to `true` once that's done, and the entity accessors below are only
+  safe to use after that.
+*/
+
+await manager.init(client);
+console.log("ready:", manager.ready);
+console.log("namespaces:", manager.getNamespaces());
+
+manager.onSaveStart.add(() => console.log("[event] onSaveStart"));
+manager.onSaveComplete.add((success) => console.log("[event] onSaveComplete:", success));
+
+/* MD
+  ### 📍 origin — a singleton entity
+  `origin` holds the project's GIS origin: latitude, longitude, height, and
+  rotation. Singletons expose `get`/`set`/`update`; `set` replaces the whole
+  value, `update` merges a partial one. Both schedule a debounced auto-save —
+  call `flush()` to force it immediately and await completion.
+*/
+
+console.log("origin before:", manager.origin.get());
+
+await manager.origin.set({ lat: 40.4164, lon: -3.7038, height: 700, rotation: 0 });
+await manager.origin.update({ height: 710 });
+await manager.flush();
+
+console.log("origin after update+flush:", manager.origin.get());
+
+/* MD
+  ### 🗺️ bimCoordinates — the sites collection
+  Sites are how a project keeps georeferencing for more than one BIM model,
+  each with its own origin and transform matrix. Because sites are created by
+  users at runtime, their ids are opaque and generated internally —
+  `createSite` mints the id and returns it, while `setSite` only updates a
+  site that already exists (it throws otherwise). This split keeps storage
+  keys decoupled from mutable data like a site's label.
+*/
+
+const siteId = await manager.bimCoordinates.createSite({
+  label: "Site 1",
+  description: "Primary IFC export.",
+  lat: 40.41647848134075,
+  lon: -3.703451491164702,
+  height: 699.970526176243,
+  rotation: 0,
+  baseMatrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, -498477.20216, -719.2375, 4389662.11289, 1],
+});
+
+await manager.bimCoordinates.setDefaultSite(siteId);
+await manager.flush();
+
+console.log("default site:", manager.bimCoordinates.getDefaultSite());
+console.log("all sites:", manager.bimCoordinates.getSites());
+
+/* MD
+  Updating an existing site goes through `setSite`, not `createSite`:
+*/
+
+await manager.bimCoordinates.setSite(siteId, {
+  ...manager.bimCoordinates.getSite(siteId)!,
+  label: "Site 1 (revised)",
+});
+await manager.flush();
+
+console.log("site after update:", manager.bimCoordinates.getSite(siteId));
+
+/* MD
+  ### 🖼️ assetCoordinates — the files collection
+  `assetCoordinates` georeferences individual files — splats, point clouds —
+  that live outside the BIM model tree. Unlike sites, entries are keyed by
+  the caller-supplied `fileId`, since that id already comes from the platform
+  and is stable by construction.
+*/
+
+await manager.assetCoordinates.set("splat_1", {
+  type: "splat",
+  lat: 40.416600807789145,
+  lon: -3.703739209785748,
+  height: 727.2700125737748,
+  rotation: 0,
+});
+await manager.flush();
+
+console.log("splats:", manager.assetCoordinates.getByType("splat"));
+console.log("splat_1:", manager.assetCoordinates.get("splat_1"));
+
+/* MD
+  ### ⚙️ graphicsSettings — another singleton
+  Same shape as `origin` — `get`/`set`/`update`, debounced auto-save.
+*/
+
+await manager.graphicsSettings.update({ /* project-wide graphics defaults */ } as any);
+await manager.flush();
+
+console.log("graphicsSettings:", manager.graphicsSettings.get());
+
+/* MD
+  ### 🔍 Namespaces — read-only introspection
+  `getNamespaces()` lists the closed set of namespaces the schema defines;
+  `getNamespace(key)` returns every entity registered under one. Useful for
+  debugging or building a generic project-data inspector — not for reading
+  values you already know the shape of, which is what the entity accessors
+  above are for.
+*/
+
+console.log("georeferencing namespace:", manager.getNamespace("georeferencing"));
+
+/* MD
+  ### 🤖 What's not covered here
+  ProjectManager ships without a UI panel — everything above is the data
+  layer only. Building georeferencing or project-settings UI on top of
+  `origin`/`bimCoordinates`/`assetCoordinates` is up to the consuming app.
+*/

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

@@ -0,0 +1,182 @@
+/* MD
+  ## top-viewer
+  ---
+  Every BIM app needs a 3D viewport: a scene, a camera, a grid, element
+  highlighting, and the plumbing to keep loaded models framed and rendering
+  efficiently as they stream in. Building that from scratch is a project on
+  its own, before a single button or panel gets wired to it.
+
+  `top-viewer` is a ready-made web component that delivers exactly that. Drop
+  it into a `top-app` layout and it creates the 3D world, wires camera
+  controls, sets up the highlighter, keeps every loaded fragment model framed
+  and culled correctly, and exposes four docking slots so toolbars and tools
+  can attach to it without any manual overlay/positioning code.
+
+  This tutorial covers the prerequisites; the minimal mount; what the
+  viewport does automatically; how docking works; and loading your first
+  model into it.
+
+  By the end, you'll have a fully working 3D viewport 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 } from "@thatopen/services";
+import type { App } from "../app/index";
+
+/* MD
+  ### ✅ Prerequisites
+
+  Two conditions must be met before `<top-viewer>` does anything useful:
+
+  1. **`UIManager` must be in the setup call.** It registers all platform web
+     components, including `<top-viewer>` itself. Without it the element is
+     unknown to the browser and renders as an empty box.
+
+  2. **`OBC.FragmentsManager` must be initialized** (`fragments.init(...)`)
+     before you try to load any model. `top-viewer` itself doesn't need this
+     to mount — its world, camera, and grid are ready the moment it connects
+     — but nothing will load until the fragments worker is up.
+
+  Both are naturally satisfied when you do the setup shown below before
+  appending `top-app` to the document.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+/* MD
+  ### 🖥️ Minimal mount
+
+  `<top-viewer>` alone is a fully working, empty viewport — camera controls,
+  grid, and highlighter are already set up, no further code needed:
+
+  ```html
+  <top-viewer></top-viewer>
+  ```
+
+  It does **not** come with a toolbar. If you want the built-in one, add
+  `<top-viewer-toolbar>` as a child (see that component's own tutorial) — a
+  bare `<top-viewer>` is intentionally just the viewport.
+*/
+
+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 = {
+  viewer: () => html`<top-viewer></top-viewer>`,
+};
+
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:3d-square-bold",
+    template: `"viewer" 1fr / 1fr`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What's handled automatically
+
+  Once mounted, `<top-viewer>` takes ownership of the following without any
+  further code from you:
+
+  **World + camera** — an `OBC.SimpleWorld` with a transparent-background
+  scene, an `OBC.OrthoPerspectiveCamera` (orbit controls, perspective by
+  default), and a reference grid.
+
+  **Highlighter** — `OBF.Highlighter` is set up for the world, ready for any
+  built-in or custom code to select/highlight elements.
+
+  **Model framing** — every model loaded through `OBC.FragmentsManager`
+  (anywhere in your app, not just inside this component) is automatically
+  added to the scene, told which camera to use for culling/LOD, and factored
+  into the camera's far-plane distance so large models never get clipped.
+  You never need to call `scene.add()` or `useCamera()` yourself.
+
+  **Navigation tools** — the navigation gizmo and active-tool HUD are baked
+  onto the viewport overlay the moment the world is ready.
+
+  **Context for descendants** — `<top-viewer>` provides `worldContext` (the
+  `OBC.World` instance) to any descendant, regardless of shadow-DOM
+  boundaries. `<top-viewer-toolbar>` and its standalone buttons consume it
+  this way — you never pass `world` around by hand.
+
+  **Cleanup** — disposes the world (and the highlighter) automatically when
+  the element is removed from the DOM.
+
+  ### 🧩 Docking slots
+
+  `<top-viewer>` exposes four named slots for toolbars/tools, arranged around
+  the viewport: `"bottom"`, `"top"`, `"left"`, `"right"`. Any element can use
+  them, not just `<top-viewer-toolbar>`:
+
+  ```html
+  <top-viewer>
+    <top-viewer-toolbar></top-viewer-toolbar>            <!-- no slot → auto-docks "bottom" -->
+    <my-custom-panel slot="right"></my-custom-panel>
+  </top-viewer>
+  ```
+
+  A `<top-viewer-toolbar>` added **without** a `slot` attribute is
+  auto-docked into `"bottom"` for you — that's the only slot with special
+  handling; every other element (or every other slot) needs its `slot`
+  attribute set explicitly.
+
+  ### ⚠️ Gotchas
+
+  - **No toolbar is added for you.** A bare `<top-viewer>` has no bottom bar,
+    no buttons — just the viewport. If your app expects one, you must add
+    `<top-viewer-toolbar>` yourself.
+  - **Only `"bottom"`, `"top"`, `"left"`, `"right"` are recognized slot
+    names.** Anything else (a typo, or an app-specific name) is not placed
+    into any docking area and simply doesn't render where you'd expect.
+  - **`worldContext` starts out `undefined`.** World creation is asynchronous
+    — any custom descendant consuming the context must handle the
+    not-yet-ready case, the same way `<top-viewer-toolbar>` does.
+  - **The host needs real, resolved dimensions from its parent.** `width:
+    100%; height: 100%` alone isn't enough if the parent's own size hasn't
+    resolved (e.g. an unsized grid area) — give the viewer's container an
+    explicit size.
+
+  ### 📥 Loading a model
+
+  Load any `.frag` through the shared `OBC.FragmentsManager` — `<top-viewer>`
+  picks it up and frames it automatically, no matter where in your app the
+  load happens:
+
+  ```ts
+  const fragments = components.get(OBC.FragmentsManager);
+  const file = await fetch("https://your-storage.example.com/model.frag");
+  const buffer = await file.arrayBuffer();
+  await fragments.core.load(buffer, { modelId: "example-model" });
+  ```
+*/

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

@@ -0,0 +1,252 @@
+/* MD
+  ## top-viewer-toolbar
+  ---
+  A 3D viewport is only as useful as the controls around it: selecting a
+  target set, hiding/isolating/ghosting elements, clipping, measuring,
+  walking through the model. Building that toolbar — and keeping every
+  button in sync with tool state and with each other — is real work, before
+  you've customized anything.
+
+  `top-viewer-toolbar` is a ready-made web component that delivers exactly
+  that. Mounted as-is, it's a complete, self-wiring bottom toolbar. But it's
+  also built out of standalone, individually-importable
+  `<top-viewer-*-button>` elements — so if the default layout isn't what your
+  app needs, you can drop the bar it builds for you and compose your own out
+  of the same pieces, mixed freely with your own custom buttons.
+
+  This tutorial covers the prerequisites; the default, batteries-included
+  toolbar; what it manages automatically; composing a custom layout with
+  `headless`; docking a vertical toolbar; and the full list of standalone
+  buttons available.
+
+  By the end, you'll have both a working default toolbar and a fully custom
+  one running side by side in the same viewport.
+*/
+
+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 } from "@thatopen/services";
+import type { App } from "../app/index";
+
+/* MD
+  ### ✅ Prerequisites
+
+  `<top-viewer-toolbar>` must be mounted as a descendant of `<top-viewer>` —
+  it consumes the `componentsContext`/`worldContext` that `<top-viewer>`
+  provides, and the standalone buttons it's built from consume the same
+  contexts. `UIManager` must be in the setup call so both custom elements are
+  registered. Nothing else is required — no manager to `init`, no extra
+  config.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+/* MD
+  ### 🖥️ Default toolbar (batteries included)
+
+  Add it as a plain child of `<top-viewer>` — no `slot` needed, it docks
+  into `"bottom"` on its own:
+
+  ```html
+  <top-viewer>
+    <top-viewer-toolbar></top-viewer-toolbar>
+  </top-viewer>
+  ```
+*/
+
+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 = {
+  viewer: () => html`
+    <top-viewer>
+      <top-viewer-toolbar></top-viewer-toolbar>
+    </top-viewer>
+  `,
+};
+
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:3d-square-bold",
+    template: `"viewer" 1fr / 1fr`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What the default toolbar manages automatically
+
+  **Target mode** — a toggle between "Selected" and "Unselected", which every
+  visibility button below operates on. Empty selection while targeting
+  "Selected" means the target is empty (actions no-op); targeting
+  "Unselected" with an empty selection means the target is the whole model.
+
+  **Visibility actions** (each reversible via Show/Reset) — Hide, Show,
+  Isolate, Ghost (semi-transparent), Focus, and a global Reset that restores
+  full visibility and opacity regardless of target mode.
+
+  **Inspect tab** — Select (default tool), Clip, and six measurement modes
+  (length, area, angle, edge, face, volume), all sharing one active-tool
+  manager so switching tools un-highlights whichever was active before.
+
+  **Projection + walkthrough** — a Perspective⇄Orthographic toggle and a
+  first-person walkthrough toggle, each reflecting live state.
+
+  **Active-tool HUD** — a floating overlay over the 3D viewport itself
+  showing context for whichever tool is currently active (e.g. clip plane
+  controls, measurement readouts).
+
+  All of the above are per-`components` singletons — any other UI in your
+  app that resolves the same tool (e.g. via `components.get(...)`) shares
+  the exact same state, not a second, independent instance.
+
+  ### 🧱 Composing a custom layout with `headless`
+
+  Set the `headless` attribute to skip the default bar's own assembly, while
+  everything else — providing context to descendants, the active-tool HUD —
+  keeps running. Slot your own buttons as light-DOM children: they consume
+  the same context the default bar's buttons do, wherever you place them.
+
+  ```html
+  <top-viewer>
+    <top-viewer-toolbar headless>
+      <!-- your own content goes here as light-DOM children -->
+    </top-viewer-toolbar>
+  </top-viewer>
+  ```
+
+  Mixing standalone buttons with a plain, app-owned `bim-button` in the same
+  bar — built with lit's `render`/`html` into a plain container element
+  (never `document.createElement` for the `bim-*` tags themselves, see the
+  gotcha below), then appended as the toolbar's light-DOM content:
+
+  ```ts
+  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;");
+  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>
+    `,
+    customButtons,
+  );
+  headlessBar.appendChild(customButtons);
+  // headlessBar can now be appended anywhere inside <top-viewer>.
+  ```
+
+  ### 📐 Docking a vertical toolbar
+
+  The host centers its own content via flexbox, controllable through CSS
+  custom properties — including flipping to a vertical stack for a
+  sidebar-style dock:
+
+  ```html
+  <top-viewer-toolbar
+    headless
+    slot="right"
+    style="--top-viewer-toolbar-direction: column;"
+  >
+    ...
+  </top-viewer-toolbar>
+  ```
+
+  - `--top-viewer-toolbar-direction` — `row` (default) or `column`.
+  - `--top-viewer-toolbar-justify` — alignment along the main axis (default
+    `center`).
+  - `--top-viewer-toolbar-align` — alignment along the cross axis (default
+    `center`).
+
+  Pair `--top-viewer-toolbar-direction: column` with `bim-toolbar`'s own
+  `vertical` attribute on the content you render inside, so the buttons
+  themselves stack the same way the bar does.
+
+  ### ⚠️ Gotchas
+
+  - **Never `document.createElement` a `bim-*` element.** `bim-button`,
+    `bim-toolbar`, `bim-toolbar-section`, and every other `@thatopen/ui`
+    component set attributes on themselves in their own constructor, which
+    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.
+  - **`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
+    look inconsistent next to the rest of the bar.
+  - **Centering/alignment belongs on the toolbar's host**, via the CSS custom
+    properties above — not on the content you slot into it. Setting
+    `justify-self` (or similar) on your own buttons instead of using
+    `--top-viewer-toolbar-justify` only works by accident, if at all.
+  - **A standalone button works from anywhere in the DOM**, as long as it
+    ends up a descendant of a `<top-viewer-toolbar>` inside a `<top-viewer>`
+    — context requests bubble through shadow-DOM boundaries. It does *not*
+    need to be a direct child of the bar it visually sits in.
+
+  ### 🧩 Standalone buttons reference
+
+  Every button the default bar uses is independently importable/usable as
+  its own custom element:
+
+  | Element | Does |
+  |---|---|
+  | `<top-viewer-mode-toggle-button>` | Toggles target: Selected ⇄ Unselected |
+  | `<top-viewer-hide-button>` | Hides the target set |
+  | `<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-focus-button>` | Frames the camera on the target set |
+  | `<top-viewer-reset-button>` | Restores full visibility + opacity (global) |
+  | `<top-viewer-select-button>` | Activates the default Select tool |
+  | `<top-viewer-clip-button>` | Activates the Clip tool |
+  | `<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-projection-toggle-button>` | Toggles Perspective ⇄ Orthographic |
+  | `<top-viewer-walkthrough-button>` | Toggles first-person walkthrough |
+
+  Each one self-wires from context — drop it anywhere under `<top-viewer>`
+  and it works, with no props to pass in.
+*/