@thatopen/services 0.0.6 → 0.1.3

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

@@ -0,0 +1,92 @@
+/* MD
+  ## Floating layout
+  ---
+  Developers building BIM coordination tools often want the 3D model to fill the
+  entire window while control panels float above it — but standard grid layouts
+  give every area equal standing, shrinking the viewer into one cell and leaving
+  visible seams between it and the panels.
+
+  top-app supports a floating mode where one element is mounted as an absolute
+  background that fills the container edge-to-edge, and all other layout areas
+  render as a transparent overlay on top of it with independent pointer events.
+
+  This tutorial covers assigning the viewer as the absolute background of the app;
+  defining an overlay layout where a side panel floats above the viewer without
+  sharing grid space; and annotating why the base element is excluded from the
+  layout template.
+
+  By the end, you'll have a full-screen 3D viewer with a floating side panel
+  hovering above it, with the model filling the entire window and the panel
+  receiving its own pointer events.
+*/
+
+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 } from "thatopen-services";
+import uiManagerDef from "../../../../index";
+import type { App } from "../../index";
+
+const UIManager = uiManagerDef.componentDefinition;
+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" is referenced by app.base — rendered as a position:absolute layer
+  // behind all layout content so it fills the container edge-to-edge.
+  viewer: () =>
+    html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+
+  // Panels declared here appear in the floating content grid on top of the viewer.
+  // Their container has pointer-events: none; each child re-enables them individually.
+  panel: () => html`
+    <bim-panel>
+      <bim-panel-section label="Models" icon="solar:layers-bold">
+        <bim-label>Load models here</bim-label>
+      </bim-panel-section>
+    </bim-panel>
+  `,
+};
+
+// Setting app.base to an element key mounts that element as the absolute background.
+// Layout templates then only list the floating overlay areas — not the base element.
+// Without app.base, every area in the template is a peer grid cell (inline mode).
+app.base = "viewer";
+
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:home-bold",
+    // Only overlay areas appear here. "viewer" is not listed because it is the base.
+    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/Notifications/example.ts

@@ -0,0 +1,161 @@
+/* MD
+  ## Toasts, file drop, and cross-component notifications
+  ---
+  Developers building BIM processing UIs need to surface status updates, errors,
+  and file-drop feedback to users from different points in the component tree —
+  but reaching back to the app root to trigger a notification from a deeply nested
+  component requires threading a reference through every layer in between.
+
+  top-app provides a built-in toast system that any descendant can trigger by
+  dispatching a standard DOM event, a drag-and-drop overlay that activates
+  automatically when files enter the window, and a drop-zone message that can be
+  computed from live state at render time rather than set once at initialization.
+
+  This tutorial covers showing a success toast when the app finishes booting;
+  building a component that dispatches notification events to report async progress
+  and completion without a reference to the root; handling dropped files, filtering
+  them by extension, and showing a warning when none are supported; and setting the
+  drop-zone message as a function that reads a live model counter.
+
+  By the end, you'll have an app with a full notification layer — a boot
+  confirmation toast, async status reporting from a child component, and a
+  drag-and-drop zone whose message updates as models are loaded.
+*/
+
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+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 } from "thatopen-services";
+import uiManagerDef from "../../../../index";
+import type { App, AppReadyEvent } from "../../index";
+
+// A child component that dispatches top:notification to surface messages
+// to the nearest top-app ancestor — no reference to the app element needed.
+@customElement("status-reporter")
+class StatusReporter extends LitElement {
+  @state() private _busy = false;
+
+  private _simulateWork() {
+    this._busy = true;
+
+    // Dispatching top:notification from any descendant of top-app shows a toast.
+    // bubbles:true + composed:true lets it cross shadow-DOM boundaries.
+    this.dispatchEvent(
+      new CustomEvent("top:notification", {
+        bubbles: true,
+        composed: true,
+        detail: { message: "Analysis started", type: "info" },
+      }),
+    );
+
+    setTimeout(() => {
+      this._busy = false;
+      this.dispatchEvent(
+        new CustomEvent("top:notification", {
+          bubbles: true,
+          composed: true,
+          detail: {
+            message: "Analysis complete",
+            type: "success",
+            description: "Found 342 elements across 5 categories.",
+          },
+        }),
+      );
+    }, 2000);
+  }
+
+  render() {
+    return html`
+      <bim-panel label="Reporter">
+        <bim-panel-section label="Actions" icon="solar:play-bold">
+          <bim-button
+            label="Run Analysis"
+            icon="solar:play-bold"
+            .loading=${this._busy}
+            @click=${this._simulateWork}
+          ></bim-button>
+        </bim-panel-section>
+      </bim-panel>
+    `;
+  }
+}
+
+// ---- app wiring ----
+
+const UIManager = uiManagerDef.componentDefinition;
+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`<status-reporter></status-reporter>`,
+};
+
+app.base = "viewer";
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:home-bold",
+    template: `"panel" 1fr / 22rem`,
+  },
+};
+app.layout = "main";
+
+// dropMessage as a function is called at render time so it can read live state.
+// Here it reads how many models are already loaded and adjusts the hint text.
+let loadedCount = 0;
+app.dropMessage = () =>
+  loadedCount === 0
+    ? "Drop an IFC or FRAG file to load your first model"
+    : `Drop a file to add to the ${loadedCount} loaded model${loadedCount === 1 ? "" : "s"}`;
+
+// top:files-dropped fires when the user drops files onto the window.
+// e.detail.files is a File[]. Handle upload, load, or validation here.
+app.addEventListener("top:files-dropped", (e) => {
+  const { files } = (e as CustomEvent<{ files: File[] }>).detail;
+  const supported = files.filter((f) =>
+    f.name.endsWith(".ifc") || f.name.endsWith(".frag"),
+  );
+  if (!supported.length) {
+    app.showToast("No supported files dropped", "warning");
+    return;
+  }
+  app.showToast(`Loading ${supported.length} file${supported.length === 1 ? "" : "s"}…`, "info");
+  loadedCount += supported.length;
+});
+
+// thatopen:app-ready fires after all waitUntil promises resolve.
+// e.detail.app is a reference to the top-app element itself.
+app.addEventListener("thatopen:app-ready", (e) => {
+  const { app: readyApp } = (e as AppReadyEvent).detail;
+  readyApp.showToast("App ready", "success");
+});
+
+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

@@ -0,0 +1,104 @@
+/* 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 } from "thatopen-services";
+import uiManagerDef from "../../../../index";
+import type { App } from "../../index";
+
+const UIManager = uiManagerDef.componentDefinition;
+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";

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

@@ -1,106 +1,106 @@
-import * as THREE from "three";
-import * as OBC from "@thatopen/components";
-import * as BUI from "@thatopen/ui";
-
-import appManagerDef from "../AppManager/index";
-import viewportManagerDef from "./index";
-
-const AppManager = appManagerDef.componentDefinition;
-const ViewportManager = viewportManagerDef.componentDefinition;
-
-// ── App type ──────────────────────────────────────────────────────────
-
-type PanelState = { components: OBC.Components };
-
-interface ViewportApp {
-  icons: ["LOAD", "VIEW", "SPLIT"];
-  grid: BUI.Grid<
-    ["Viewer", "Split"],
-    [
-      { name: "viewer"; state: null },
-      { name: "panel"; state: PanelState }
-    ]
-  >;
-}
-
-// ── Initialise OBC & BUI ──────────────────────────────────────────────
-
-BUI.Manager.init();
-const components = new OBC.Components();
-
-const app = components.get(AppManager<ViewportApp>);
-const viewports = components.get(ViewportManager);
-
-// ── Create a viewport ─────────────────────────────────────────────────
-
-const { element: viewerElement, world } = await viewports.create({
-  backgroundColor: "#202932",
-});
-
-// ── Add a simple cube to the scene ────────────────────────────────────
-
-const geometry = new THREE.BoxGeometry(3, 3, 3);
-const material = new THREE.MeshStandardMaterial({ color: "#6528D7" });
-const cube = new THREE.Mesh(geometry, material);
-cube.position.set(0, 1.5, 0);
-world.scene.three.add(cube);
-
-await world.camera.controls.setLookAt(10, 8, 10, 0, 1.5, 0);
-
-// Load a sample model
-const loadModel = async () => {
-  const fragments = components.get(OBC.FragmentsManager);
-  const file = await fetch(
-    "https://thatopen.github.io/engine_components/resources/frags/school_arq.frag",
-  );
-  const buffer = await file.arrayBuffer();
-  await fragments.core.load(buffer, { modelId: "school_arq" });
-  await fragments.core.update(true);
-};
-
-// ── Templates ─────────────────────────────────────────────────────────
-
-const panelTemplate: BUI.StatefullComponent<PanelState> = (_state) => {
-  return BUI.html`
-    <bim-panel active label="App Info">
-      <bim-panel-section label="Actions">
-        <bim-button @click=${loadModel} label="Load School Model"></bim-button>
-      </bim-panel-section>
-      <bim-panel-section label="Info">
-        <bim-label>Use the sidebar to switch layouts.</bim-label>
-      </bim-panel-section>
-    </bim-panel>
-  `;
-};
-
-// ── Init ──────────────────────────────────────────────────────────────
-
-app.init({
-  icons: {
-    LOAD: "solar:upload-bold",
-    VIEW: "mdi:monitor",
-    SPLIT: "solar:settings-bold",
-  },
-  grid: (grid) => {
-    grid.elements = {
-      viewer: viewerElement,
-      panel: { template: panelTemplate, initialState: { components } },
-    };
-    grid.layouts = {
-      Viewer: {
-        template: `"viewer" 1fr / 1fr`,
-        icon: app.icons.VIEW,
-      },
-      Split: {
-        template: `"panel viewer" 1fr / 20rem 1fr`,
-        icon: app.icons.SPLIT,
-      },
-    };
-    grid.layout = "Viewer";
-  },
-  container: document.getElementById("container")!,
-});
-
-app.showSidebar = true;
-
-components.init();
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as BUI from "@thatopen/ui";
+
+import appManagerDef from "../AppManager/index";
+import viewportManagerDef from "./index";
+
+const AppManager = appManagerDef.componentDefinition;
+const ViewportManager = viewportManagerDef.componentDefinition;
+
+// ── App type ──────────────────────────────────────────────────────────
+
+type PanelState = { components: OBC.Components };
+
+interface ViewportApp {
+  icons: ["LOAD", "VIEW", "SPLIT"];
+  grid: BUI.Grid<
+    ["Viewer", "Split"],
+    [
+      { name: "viewer"; state: null },
+      { name: "panel"; state: PanelState }
+    ]
+  >;
+}
+
+// ── Initialise OBC & BUI ──────────────────────────────────────────────
+
+BUI.Manager.init();
+const components = new OBC.Components();
+
+const app = components.get(AppManager<ViewportApp>);
+const viewports = components.get(ViewportManager);
+
+// ── Create a viewport ─────────────────────────────────────────────────
+
+const { element: viewerElement, world } = await viewports.create({
+  backgroundColor: "#202932",
+});
+
+// ── Add a simple cube to the scene ────────────────────────────────────
+
+const geometry = new THREE.BoxGeometry(3, 3, 3);
+const material = new THREE.MeshStandardMaterial({ color: "#6528D7" });
+const cube = new THREE.Mesh(geometry, material);
+cube.position.set(0, 1.5, 0);
+world.scene.three.add(cube);
+
+await world.camera.controls.setLookAt(10, 8, 10, 0, 1.5, 0);
+
+// Load a sample model
+const loadModel = async () => {
+  const fragments = components.get(OBC.FragmentsManager);
+  const file = await fetch(
+    "https://thatopen.github.io/engine_components/resources/frags/school_arq.frag",
+  );
+  const buffer = await file.arrayBuffer();
+  await fragments.core.load(buffer, { modelId: "school_arq" });
+  await fragments.core.update(true);
+};
+
+// ── Templates ─────────────────────────────────────────────────────────
+
+const panelTemplate: BUI.StatefullComponent<PanelState> = (_state) => {
+  return BUI.html`
+    <bim-panel active label="App Info">
+      <bim-panel-section label="Actions">
+        <bim-button @click=${loadModel} label="Load School Model"></bim-button>
+      </bim-panel-section>
+      <bim-panel-section label="Info">
+        <bim-label>Use the sidebar to switch layouts.</bim-label>
+      </bim-panel-section>
+    </bim-panel>
+  `;
+};
+
+// ── Init ──────────────────────────────────────────────────────────────
+
+app.init({
+  icons: {
+    LOAD: "solar:upload-bold",
+    VIEW: "mdi:monitor",
+    SPLIT: "solar:settings-bold",
+  },
+  grid: (grid) => {
+    grid.elements = {
+      viewer: viewerElement,
+      panel: { template: panelTemplate, initialState: { components } },
+    };
+    grid.layouts = {
+      Viewer: {
+        template: `"viewer" 1fr / 1fr`,
+        icon: app.icons.VIEW,
+      },
+      Split: {
+        template: `"panel viewer" 1fr / 20rem 1fr`,
+        icon: app.icons.SPLIT,
+      },
+    };
+    grid.layout = "Viewer";
+  },
+  container: document.getElementById("container")!,
+});
+
+app.showSidebar = true;
+
+components.init();