@thatopen/services 0.3.15 → 0.4.0

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/app/examples/Sidebar/example.ts

@@ -1,102 +1,102 @@
-/* MD
-  ## Sidebar navigation
-  ---
-  Product teams building BIM apps often need multiple distinct views — a 3D model
-  viewer, a data browser, a settings screen — but wiring a custom nav bar and
-  managing view transitions from scratch adds complexity before any real feature
-  work begins.
-
-  top-app supports named layouts with a built-in sidebar navigation bar that
-  switches the active grid template on click, so teams get multi-view navigation
-  without building the scaffolding themselves.
-
-  This tutorial covers defining three named layouts with their own grid templates
-  and icons; providing a dedicated element for each view; enabling the sidebar nav
-  bar; and setting the initial active layout.
-
-  By the end, you'll have a multi-view BIM app with a persistent sidebar that lets
-  users switch between a 3D viewer, a data panel, and a settings screen.
-*/
-
-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 "../../index";
-
-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>`,
-
-  data: () => html`
-    <bim-panel label="Data">
-      <bim-panel-section label="Properties" icon="solar:document-bold">
-        <bim-label>Select an element in the viewer to inspect its properties.</bim-label>
-      </bim-panel-section>
-    </bim-panel>
-  `,
-
-  settings: () => html`
-    <bim-panel label="Settings">
-      <bim-panel-section label="Appearance" icon="solar:settings-bold">
-        <bim-checkbox label="Show grid" checked></bim-checkbox>
-        <bim-checkbox label="Show axes"></bim-checkbox>
-      </bim-panel-section>
-    </bim-panel>
-  `,
-};
-
-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.
-  viewer: {
-    label: "Viewer",
-    icon: "solar:3d-square-bold",
-    template: `"viewer" 1fr / 1fr`,
-  },
-  data: {
-    label: "Data",
-    icon: "solar:document-bold",
-    template: `"data" 1fr / 1fr`,
-  },
-  settings: {
-    label: "Settings",
-    icon: "solar:settings-bold",
-    template: `"settings" 1fr / 1fr`,
-  },
-};
-
-// sidebar=true adds a vertical nav column on the left with one button per layout.
-// Each button shows the layout's label and icon and activates that layout on click.
-app.sidebar = true;
-app.layout = "viewer";
-
-const container = document.getElementById("that-open-app") ?? document.body;
-container.appendChild(app);
-document.body.style.margin = "0";
+/* MD
+  ## Sidebar navigation
+  ---
+  Product teams building BIM apps often need multiple distinct views — a 3D model
+  viewer, a data browser, a settings screen — but wiring a custom nav bar and
+  managing view transitions from scratch adds complexity before any real feature
+  work begins.
+
+  top-app supports named layouts with a built-in sidebar navigation bar that
+  switches the active grid template on click, so teams get multi-view navigation
+  without building the scaffolding themselves.
+
+  This tutorial covers defining three named layouts with their own grid templates
+  and icons; providing a dedicated element for each view; enabling the sidebar nav
+  bar; and setting the initial active layout.
+
+  By the end, you'll have a multi-view BIM app with a persistent sidebar that lets
+  users switch between a 3D viewer, a data panel, and a settings screen.
+*/
+
+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 "../../index";
+
+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>`,
+
+  data: () => html`
+    <bim-panel label="Data">
+      <bim-panel-section label="Properties" icon="solar:document-bold">
+        <bim-label>Select an element in the viewer to inspect its properties.</bim-label>
+      </bim-panel-section>
+    </bim-panel>
+  `,
+
+  settings: () => html`
+    <bim-panel label="Settings">
+      <bim-panel-section label="Appearance" icon="solar:settings-bold">
+        <bim-checkbox label="Show grid" checked></bim-checkbox>
+        <bim-checkbox label="Show axes"></bim-checkbox>
+      </bim-panel-section>
+    </bim-panel>
+  `,
+};
+
+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.
+  viewer: {
+    label: "Viewer",
+    icon: "solar:3d-square-bold",
+    template: `"viewer" 1fr / 1fr`,
+  },
+  data: {
+    label: "Data",
+    icon: "solar:document-bold",
+    template: `"data" 1fr / 1fr`,
+  },
+  settings: {
+    label: "Settings",
+    icon: "solar:settings-bold",
+    template: `"settings" 1fr / 1fr`,
+  },
+};
+
+// sidebar=true adds a vertical nav column on the left with one button per layout.
+// Each button shows the layout's label and icon and activates that layout on click.
+app.sidebar = true;
+app.layout = "viewer";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";