@thatopen/services 0.2.0 → 0.3.0

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

@@ -1,125 +1,125 @@
-/* MD
-  ## Consuming platform contexts in child components
-  ---
-  Developers building custom BIM panels need access to the 3D engine, the platform
-  API, and the current project's metadata — but threading these objects down through
-  props across multiple component layers forces every intermediate element to know
-  about data it doesn't use, making trees brittle and hard to refactor.
-
-  top-app publishes the engine instance, the platform client, and the current
-  project data as named reactive contexts, so any descendant component can subscribe
-  to exactly what it needs without any prop drilling from the root.
-
-  This tutorial covers defining a custom panel that subscribes to the engine
-  context, the platform client context, and the project data context; handling the
-  intermediate loading state before contexts become available after boot; and
-  mounting the panel inside a top-app layout.
-
-  By the end, you'll have a custom info panel that reads the project name and engine
-  state directly from context, with no objects passed down as props from the app root.
-*/
-
-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, ProjectData } from "thatopen-services";
-import uiManagerDef from "../../../../index";
-import {
-  componentsContext,
-  clientContext,
-  projectDataContext,
-  appStateContext,
-  type App,
-  type AppState,
-} from "../../index";
-
-// appStateContext is provided by top-app immediately — before setup completes.
-// componentsContext, clientContext, and projectDataContext become available only
-// after app.setup returns and all waitUntil promises resolve.
-@customElement("project-info-panel")
-class ProjectInfoPanel extends LitElement {
-  @consume({ context: appStateContext, subscribe: true })
-  @state()
-  private _appState?: AppState;
-
-  @consume({ context: componentsContext, subscribe: true })
-  @state()
-  private _components?: OBC.Components;
-
-  @consume({ context: clientContext, subscribe: true })
-  @state()
-  private _client?: PlatformClient;
-
-  @consume({ context: projectDataContext, subscribe: true })
-  @state()
-  private _projectData?: ProjectData;
-
-  render() {
-    if (!this._components || !this._client || !this._projectData) {
-      return html`<bim-label>Loading…</bim-label>`;
-    }
-    return html`
-      <bim-panel label="Project Info">
-        <bim-panel-section label="Project" icon="solar:buildings-bold">
-          <bim-label .value=${this._projectData.name}></bim-label>
-        </bim-panel-section>
-        <bim-panel-section label="Engine" icon="solar:cpu-bold">
-          <bim-label>Components ready</bim-label>
-        </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>`,
-
-  // Any element rendered inside top-app can consume the contexts above.
-  info: () => html`<project-info-panel></project-info-panel>`,
-};
-
-app.base = "viewer";
-app.layouts = {
-  main: {
-    label: "Main",
-    icon: "solar:home-bold",
-    template: `"info" 1fr / 22rem`,
-  },
-};
-app.layout = "main";
-
-const container = document.getElementById("that-open-app") ?? document.body;
-container.appendChild(app);
-document.body.style.margin = "0";
+/* MD
+  ## Consuming platform contexts in child components
+  ---
+  Developers building custom BIM panels need access to the 3D engine, the platform
+  API, and the current project's metadata — but threading these objects down through
+  props across multiple component layers forces every intermediate element to know
+  about data it doesn't use, making trees brittle and hard to refactor.
+
+  top-app publishes the engine instance, the platform client, and the current
+  project data as named reactive contexts, so any descendant component can subscribe
+  to exactly what it needs without any prop drilling from the root.
+
+  This tutorial covers defining a custom panel that subscribes to the engine
+  context, the platform client context, and the project data context; handling the
+  intermediate loading state before contexts become available after boot; and
+  mounting the panel inside a top-app layout.
+
+  By the end, you'll have a custom info panel that reads the project name and engine
+  state directly from context, with no objects passed down as props from the app root.
+*/
+
+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, ProjectData } from "thatopen-services";
+import uiManagerDef from "../../../../index";
+import {
+  componentsContext,
+  clientContext,
+  projectDataContext,
+  appStateContext,
+  type App,
+  type AppState,
+} from "../../index";
+
+// appStateContext is provided by top-app immediately — before setup completes.
+// componentsContext, clientContext, and projectDataContext become available only
+// after app.setup returns and all waitUntil promises resolve.
+@customElement("project-info-panel")
+class ProjectInfoPanel extends LitElement {
+  @consume({ context: appStateContext, subscribe: true })
+  @state()
+  private _appState?: AppState;
+
+  @consume({ context: componentsContext, subscribe: true })
+  @state()
+  private _components?: OBC.Components;
+
+  @consume({ context: clientContext, subscribe: true })
+  @state()
+  private _client?: PlatformClient;
+
+  @consume({ context: projectDataContext, subscribe: true })
+  @state()
+  private _projectData?: ProjectData;
+
+  render() {
+    if (!this._components || !this._client || !this._projectData) {
+      return html`<bim-label>Loading…</bim-label>`;
+    }
+    return html`
+      <bim-panel label="Project Info">
+        <bim-panel-section label="Project" icon="solar:buildings-bold">
+          <bim-label .value=${this._projectData.name}></bim-label>
+        </bim-panel-section>
+        <bim-panel-section label="Engine" icon="solar:cpu-bold">
+          <bim-label>Components ready</bim-label>
+        </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>`,
+
+  // Any element rendered inside top-app can consume the contexts above.
+  info: () => html`<project-info-panel></project-info-panel>`,
+};
+
+app.base = "viewer";
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:home-bold",
+    template: `"info" 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/FileDrop/example.ts

@@ -0,0 +1,126 @@
+/* MD
+  ## File drag-and-drop with top:files-dropped
+  ---
+  Desktop BIM workflows often rely on dragging files straight from the OS file
+  manager onto the browser window — but wiring a document-level dragenter,
+  dragover, dragleave, and drop handler that correctly tracks nested enter/leave
+  counts, shows a visual overlay, and forwards the files to the right component
+  is tedious boilerplate to repeat for every app.
+
+  top-app handles all of that automatically. It listens for file drag events on
+  the document, shows a configurable overlay while files are in flight, and fires
+  a single top:files-dropped event when the user releases the files. The drop
+  message can be a static string or a function evaluated at render time, so it
+  can reflect live application state.
+
+  This tutorial covers receiving dropped files via top:files-dropped; filtering
+  them by extension and surfacing a warning when none are supported; setting
+  dropMessage as a function that reads a live model counter so the hint text
+  updates as models are loaded; and showing a toast on success using the
+  top:notification event from the same handler.
+
+  By the end, you'll have an app with a drag-and-drop zone whose overlay message
+  adapts to how many models are already loaded, and that reports unsupported
+  files with a warning toast.
+*/
+
+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, AppReadyEvent } 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>`,
+};
+
+app.base = "viewer";
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:home-bold",
+    template: `"_" 1fr / 1fr`,
+  },
+};
+app.layout = "main";
+
+// dropMessage as a function is evaluated 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"),
+  );
+
+  // Dispatch top:notification to surface feedback without a reference to top-app.
+  if (!supported.length) {
+    app.dispatchEvent(
+      new CustomEvent("top:notification", {
+        bubbles: true,
+        composed: true,
+        detail: { message: "No supported files dropped", type: "warning" },
+      }),
+    );
+    return;
+  }
+
+  loadedCount += supported.length;
+  app.dispatchEvent(
+    new CustomEvent("top:notification", {
+      bubbles: true,
+      composed: true,
+      detail: {
+        message: `${supported.length} file${supported.length === 1 ? "" : "s"} received`,
+        type: "success",
+        description: supported.map((f) => f.name).join(", "),
+      },
+    }),
+  );
+});
+
+app.addEventListener("top:app-ready", (e) => {
+  const { app: readyApp } = (e as AppReadyEvent).detail;
+  readyApp.showToast("App ready — try dropping an IFC or FRAG file", "info");
+});
+
+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/FloatingLayout/example.ts

@@ -1,92 +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";
+/* 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";