@thatopen/services 0.3.14 → 0.3.16

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

@@ -0,0 +1,150 @@
+/* MD
+  ## Persisting project-scoped data with projectStorageContext
+  ---
+  Most non-trivial apps built on top-app eventually need to persist some of
+  their own data inside the project — user preferences, cached results,
+  domain state that isn't a 3D model or a regular CDE file. The naive
+  approach is for each panel/manager to talk to the CDE client directly:
+  resolve or create a folder under `__project_data`, resolve or create the
+  file, decide between uploading a new file and versioning an existing one.
+  That's the same handful of steps every single consumer ends up
+  re-implementing.
+
+  top-app centralizes exactly that plumbing behind `projectStorageContext`, a
+  `@lit/context` value any descendant can `@consume`. It provides a small,
+  stable service object — not reactive state, since `save`/`flush` are
+  actions, not values to observe:
+
+  ```ts
+  interface ProjectStorage {
+    save(path: string, blob: Blob): void;   // debounced (~2s), per path
+    flush(): Promise<void>;                 // cancel debounces, save everything NOW, await it
+  }
+  ```
+
+  `path` is resolved under `__project_data/`. Calling `save` schedules a
+  debounced upload — top-app creates whichever folders in the path don't
+  exist yet, creates the file the first time, and versions it (no explicit
+  `versionTag` needed — the backend assigns the next one) every time after.
+  Saves are debounced *per path*, so unrelated consumers saving around the
+  same time don't reset each other's timers, and a small floating indicator
+  (bottom-right, so it doesn't rely on the sidebar, which is optional and can
+  be hidden) reflects both phases distinctly: just the icon, no background/
+  border, while a save is debouncing (nothing to tell the user yet — it's
+  still waiting to see if more changes come in), and the full "Saving..."
+  pill once an upload is actually in flight. Each consumer only ever decides
+  *what* to save and *where* — never the CDE mechanics, nor the indicator.
+
+  Use `flush()` whenever you're about to do something that would conflict
+  with a save still in flight — e.g. triggering a cloud job that reads the
+  same file you just edited. It cancels any pending debounce, starts the
+  upload right away, and its returned promise resolves only once that
+  upload has actually finished.
+
+  By the end, you'll have a tiny "project notes" panel that autosaves free
+  text to `__project_data/notes/notes.json`, plus a "Save now" button that
+  demonstrates `flush()`.
+*/
+
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { consume } from "@lit/context";
+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 "../../index";
+import { projectStorageContext, type ProjectStorage } from "../../src/context";
+
+// The path is always relative to `__project_data/` — top-app creates
+// whichever folders in it don't exist yet.
+const NOTES_PATH = "notes/notes.json";
+
+function notesBlob(text: string): Blob {
+  return new Blob([JSON.stringify({ text, savedAt: new Date().toISOString() })], {
+    type: "application/json",
+  });
+}
+
+@customElement("notes-panel")
+class NotesPanel extends LitElement {
+  @consume({ context: projectStorageContext })
+  private _storage?: ProjectStorage;
+
+  @state() private _text = "";
+  @state() private _flushing = false;
+
+  render() {
+    return html`
+      <bim-panel label="Project Notes">
+        <bim-panel-section label="Notes" icon="tabler:notes">
+          <bim-text-input
+            vertical
+            type="area"
+            label="Note"
+            placeholder="Type something — autosaves as you go"
+            .value=${this._text}
+            @input=${(e: Event) => {
+              this._text = (e.target as HTMLInputElement).value ?? "";
+              // Debounced — top-app coalesces rapid edits into one upload.
+              this._storage?.save(NOTES_PATH, notesBlob(this._text));
+            }}
+          ></bim-text-input>
+          <bim-button
+            label="Save now"
+            icon="tabler:cloud-upload"
+            .loading=${this._flushing}
+            @click=${async () => {
+              // Same blob, but flush() cancels the debounce and waits for
+              // the upload to actually finish before this resolves.
+              this._storage?.save(NOTES_PATH, notesBlob(this._text));
+              this._flushing = true;
+              await this._storage?.flush();
+              this._flushing = false;
+            }}
+          ></bim-button>
+        </bim-panel-section>
+      </bim-panel>
+    `;
+  }
+}
+
+// ---- app wiring ----
+
+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();
+
+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-tools></top-viewer-tools></top-viewer>`,
+  panel: () => html`<notes-panel></notes-panel>`,
+};
+
+app.base = "viewer";
+app.layouts = {
+  main: { label: "Main", icon: "solar:home-bold", template: `"panel" 1fr / 22rem` },
+};
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";

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

@@ -1,160 +1,183 @@
-/* MD
-  ## clashes-panel
-  ---
-  BIM coordinators need a dedicated review environment where they can see all
-  detected clashes, filter by status, navigate to each issue in the 3D viewer,
-  and mark items as resolved — without writing any UI code themselves.
-
-  `clashes-panel` is a ready-made web component that delivers exactly that. It
-  connects to `ClashesManager` automatically and manages the entire review
-  workflow: the detection matrix, the clash table with status filters, sphere
-  markers and element highlights in the viewer, run controls with live progress,
-  and a loading skeleton while fresh data reloads after a run completes.
-
-  This tutorial covers the prerequisites before mounting the panel; dropping it
-  into a `top-app` layout alongside a 3D viewer; and a detailed breakdown of
-  everything the panel handles automatically so you know what you do not need to
-  implement yourself.
-
-  By the end, you'll have a fully working clash-review environment 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, ClashesManager } from "@thatopen/services";
-import type { App } from "../app/index";
-
-
-/* MD
-  ### ✅ Prerequisites
-
-  Two conditions must be met before the panel mounts:
-
-  1. **`UIManager` must be in the setup call.** It registers all platform web
-     components, including `<top-clashes-panel>` itself. Without it the element is
-     unknown to the browser and renders as an empty box.
-
-  2. **`ClashesManager.init(client)` must have resolved.** The panel reads all
-     its initial data from the manager in `connectedCallback`. If `init` has not
-     finished, the panel mounts into an empty state and never catches up because
-     it only subscribes to change events — it does not poll.
-
-  Both conditions are naturally satisfied when you call `init` 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: ClashesManager.uuid },
-)) as { components: OBC.Components };
-
-components.get(UIManager).init();
-
-// init must resolve before top-app (and therefore clashes-panel) mounts.
-await components.get(ClashesManager).init(client);
-
-/* MD
-  ### 🖥️ Wiring the panel
-
-  Add `clashes-panel` as a named area in `app.elements` and reference it in your
-  layout template. A side-by-side layout with the 3D viewer is the most natural
-  arrangement — the panel controls markers and highlights directly in the 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",
-  );
-
-  waitUntil(
-    (async () => {
-      const loader = components.get(OBC.IfcLoader);
-      await loader.setup();
-    })(),
-    "IFC Loader",
-  );
-
-  return { components, client };
-};
-
-app.elements = {
-  viewer:  () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
-  clashes: () => html`<top-clashes-panel></top-clashes-panel>`,
-};
-
-app.layouts = {
-  main: {
-    label:    "Main",
-    icon:     "solar:3d-square-bold",
-    template: `"viewer clashes" 1fr / 1fr 22rem`,
-  },
-};
-
-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, `clashes-panel` takes ownership of the following without any
-  further code from you:
-
-  **Data synchronization** — the panel subscribes to every `ClashesManager`
-  event (`onJobsChanged`, `onRunsChanged`, `onClashesChanged`,
-  `onClashStatusChanged`, `onQueriesChanged`, `onRunningJobsChanged`) and keeps
-  its tables in sync. Changes made programmatically through the manager API are
-  reflected in the panel immediately.
-
-  **Run lifecycle** — a progress callout appears as soon as a run starts
-  (`onRunProgress`), updates its percentage and message in real time, and
-  disappears when the run completes or errors. If a run was already in progress
-  when the page loaded, the panel calls `reconnectIfRunning` automatically when
-  the user opens that job.
-
-  **Post-run reload skeleton** — after a successful run the manager reloads clash
-  data from storage. During that window (`onReloadingChanged = true`) the panel
-  replaces its entire content with an animated skeleton so the user is never left
-  looking at stale results that appear final.
-
-  **Sphere markers** — entering a job view places colored spheres in the 3D scene
-  at each clash location, transformed from IFC world space to viewer space.
-  Selecting a clash in the table zooms the camera, ghosts unrelated elements, and
-  re-focuses the markers on the selection. Leaving the job view removes all
-  markers and restores the full scene.
-
-  **Element highlights** — element A is highlighted green and element B red for
-  every new or active clash in the current job. Selecting a single clash refines
-  the highlight to that pair only. Clearing the selection or changing status
-  restores the full job highlight.
-
-  **Model awareness** — the panel tracks which fragment models are currently
-  loaded in the scene. Markers and highlights are activated only when the relevant
-  models are present, and are cleaned up automatically if a model is disposed
-  while the panel is open.
-
-  **Save indicator** — a subtle indicator appears while auto-save is in progress
-  (`onSaveStart`) and disappears once the write confirms (`onSaveComplete`), so
-  users know their status changes and query edits are persisted.
-
-  **Disconnection cleanup** — when the panel is removed from the DOM it calls
-  `hideMarkers` and `clearClashHighlight` on the manager, leaving the 3D scene
-  clean regardless of what was selected at the time.
-*/
+/* MD
+  ## clashes-panel
+  ---
+  BIM coordinators need a dedicated review environment where they can see all
+  detected clashes, filter by status, navigate to each issue in the 3D viewer,
+  and mark items as resolved — without writing any UI code themselves.
+
+  `clashes-panel` is a ready-made web component that delivers exactly that. It
+  connects to `ClashesManager` automatically and manages the entire review
+  workflow: the detection matrix, the clash table with status filters, sphere
+  markers and element highlights in the viewer, run controls with live progress,
+  a loading skeleton while fresh data reloads after a run completes, and
+  turning a cluster of clashes into a tracked BCF topic in one click.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping it
+  into a `top-app` layout alongside a 3D viewer; and a detailed breakdown of
+  everything the panel handles automatically so you know what you do not need to
+  implement yourself.
+
+  By the end, you'll have a fully working clash-review environment 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, ClashesManager, TopicsManager } 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-clashes-panel>` itself. Without it the element is
+     unknown to the browser and renders as an empty box.
+
+  2. **`ClashesManager.init(client)` must have resolved.** The panel reads all
+     its initial data from the manager in `connectedCallback`. If `init` has not
+     finished, the panel mounts into an empty state and never catches up because
+     it only subscribes to change events — it does not poll.
+
+  3. **`TopicsManager.init(client)` must have resolved too.** The panel's
+     "Create topic" button (turns a selection of clashes into a tracked BCF
+     topic) needs `Viewpoints.world` set to capture the camera, and `BCFTopics`
+     configured with `version: "3"` for the clash↔topic link to survive a
+     reload — `TopicsManager.init` is what sets both up. Skip it and the button
+     still works, but the topic it creates is subtly broken.
+
+  All three are naturally satisfied when you call both `init`s 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: ClashesManager.uuid },
+  { uuid: TopicsManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// Both inits must resolve before top-app (and therefore clashes-panel) mounts.
+// Independent of each other — safe to run in parallel.
+await Promise.all([
+  components.get(ClashesManager).init(client),
+  components.get(TopicsManager).init(client),
+]);
+
+/* MD
+  ### 🖥️ Wiring the panel
+
+  Add `clashes-panel` as a named area in `app.elements` and reference it in your
+  layout template. A side-by-side layout with the 3D viewer is the most natural
+  arrangement — the panel controls markers and highlights directly in the 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",
+  );
+
+  waitUntil(
+    (async () => {
+      const loader = components.get(OBC.IfcLoader);
+      await loader.setup();
+    })(),
+    "IFC Loader",
+  );
+
+  return { components, client };
+};
+
+app.elements = {
+  viewer:  () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+  clashes: () => html`<top-clashes-panel></top-clashes-panel>`,
+};
+
+app.layouts = {
+  main: {
+    label:    "Main",
+    icon:     "solar:3d-square-bold",
+    template: `"viewer clashes" 1fr / 1fr 22rem`,
+  },
+};
+
+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, `clashes-panel` takes ownership of the following without any
+  further code from you:
+
+  **Data synchronization** — the panel subscribes to every `ClashesManager`
+  event (`onJobsChanged`, `onRunsChanged`, `onClashesChanged`,
+  `onClashStatusChanged`, `onQueriesChanged`, `onRunningJobsChanged`) and keeps
+  its tables in sync. Changes made programmatically through the manager API are
+  reflected in the panel immediately.
+
+  **Run lifecycle** — a progress callout appears as soon as a run starts
+  (`onRunProgress`), updates its percentage and message in real time, and
+  disappears when the run completes or errors. If a run was already in progress
+  when the page loaded, the panel calls `reconnectIfRunning` automatically when
+  the user opens that job.
+
+  **Post-run reload skeleton** — after a successful run the manager reloads clash
+  data from storage. During that window (`onReloadingChanged = true`) the panel
+  replaces its entire content with an animated skeleton so the user is never left
+  looking at stale results that appear final.
+
+  **Sphere markers** — entering a job view places colored spheres in the 3D scene
+  at each clash location, transformed from IFC world space to viewer space.
+  Selecting a clash in the table zooms the camera, ghosts unrelated elements, and
+  re-focuses the markers on the selection. Leaving the job view removes all
+  markers and restores the full scene.
+
+  **Element highlights** — element A is highlighted green and element B red for
+  every new or active clash in the current job. Selecting a single clash refines
+  the highlight to that pair only. Clearing the selection or changing status
+  restores the full job highlight.
+
+  **Model awareness** — the panel tracks which fragment models are currently
+  loaded in the scene. Markers and highlights are activated only when the relevant
+  models are present, and are cleaned up automatically if a model is disposed
+  while the panel is open.
+
+  **Create topic from clash** — selecting one or more clashes and clicking
+  "Create topic" builds a BCF topic with an auto-generated title/description
+  summarizing the pair(s) and a viewpoint capturing the same selection and
+  red/green coloring shown in the table. The link back to the source clash(es)
+  is recorded separately so it survives independently of the topic's own BCF
+  fields. The button is disabled while the camera is still flying to a
+  selection or no models are loaded yet, so it can't fire on an empty scene.
+
+  **Save indicator** — every persisted change (clashes, queries, matrices,
+  topics created from a selection) routes through `top-app`'s shared
+  `projectStorageContext`, the same one `topics-panel` uses. A small indicator
+  reflects the real debounce-then-upload cycle: just an icon while a save is
+  pending, the full "Saving..." pill once the upload is actually in flight.
+
+  **Disconnection cleanup** — when the panel is removed from the DOM it calls
+  `hideMarkers` and `clearClashHighlight` on the manager, leaving the 3D scene
+  clean regardless of what was selected at the time.
+*/