feat: add examples for UIManager including floating layout, sidebar navigation, and notifications

Author: HoyosJuan

docs/builtin/paths.json

@@ -1,8 +1,4 @@
 [
-  {
-    "path": "src/built-in/AppManager/example.ts",
-    "description": ""
-  },
   {
     "path": "src/built-in/CDEManager/example.ts",
     "description": "CDEManager — CDEManager is the central state machine for a Common Data Environment. It holds files, folders, metadata schemas, viewer groups, and user permissions, and exposes a typed state machine that all file operations — selecting, editing, uploading, viewing — route through. It has no DOM or Three.js dependencies and can run in Node, a browser, or a server-side worker wherever `@thatopen/components` is available."
@@ -48,7 +44,27 @@
     "description": ""
   },
   {
-    "path": "src/built-in/ViewportsManager/example.ts",
-    "description": ""
+    "path": "src/built-in/UIManager/src/app/example.ts",
+    "description": "top-app — Front-end developers building BIM web apps need to coordinate several async initialization steps before the UI can be shown — loading the engine, preparing fragment workers, registering loaders — and users need visible feedback on what is happening during that wait, rather than a blank screen."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/AppState/example.ts",
+    "description": "Shared reactive state with AppState — Developers building interactive BIM panels often need sibling components — a filter selector and a results table, for example — to stay in sync without a shared parent. Lifting state to a common ancestor and threading it down as props works for shallow trees but becomes unwieldy as the component tree grows."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Contexts/example.ts",
+    "description": "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."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/FloatingLayout/example.ts",
+    "description": "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."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Notifications/example.ts",
+    "description": "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."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Sidebar/example.ts",
+    "description": "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."
   }
 ]

src/built-in/UIManager/src/app/example.ts

@@ -0,0 +1,99 @@
+/* MD
+  ## top-app
+  ---
+  Front-end developers building BIM web apps need to coordinate several async
+  initialization steps before the UI can be shown — loading the engine, preparing
+  fragment workers, registering loaders — and users need visible feedback on what
+  is happening during that wait, rather than a blank screen.
+
+  top-app is the platform's root shell element. It manages the full boot sequence,
+  tracks each async setup task individually, shows a labelled loading screen until
+  every task completes, and then mounts the app's visual layout.
+
+  This tutorial covers initializing the platform client and registering all
+  platform web components; registering two async setup tasks — the fragment worker
+  and the IFC loader — each with its own loading-screen label; declaring a named
+  layout area as a CSS grid template; wiring a 3D viewer into that layout; and
+  using a flag to keep the loading screen visible during development.
+
+  By the end, you'll have a working app shell that boots the engine, shows a
+  step-by-step loading screen, and mounts a 3D viewer once every setup task
+  resolves.
+*/
+
+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();
+
+// UIManager must be in the setup call: it registers all platform web components
+// (top-app, top-viewer, top-viewer-tools, etc.) before the DOM renders.
+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;
+
+// setup runs synchronously and returns { components, client }.
+// waitUntil registers async tasks that appear as labelled steps in the loading screen.
+// All tasks run in parallel; top-app mounts only after every promise resolves.
+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 };
+};
+
+// Each key must match an area name used in at least one layout template.
+app.elements = {
+  viewer: () =>
+    html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+};
+
+// CSS grid-template shorthand. Area names are the keys for app.elements.
+// "." creates an empty unnamed cell and is never rendered.
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:3d-square-bold",
+    template: `"viewer" 1fr / 1fr`,
+  },
+};
+
+app.layout = "main";
+
+// forceLoading keeps the boot screen visible even after setup completes.
+// Useful during development to inspect the loading UI without real async tasks.
+// app.forceLoading = true;
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";

src/built-in/UIManager/src/app/examples/AppState/example.ts

@@ -0,0 +1,142 @@
+/* MD
+  ## Shared reactive state with AppState
+  ---
+  Developers building interactive BIM panels often need sibling components — a
+  filter selector and a results table, for example — to stay in sync without a
+  shared parent. Lifting state to a common ancestor and threading it down as props
+  works for shallow trees but becomes unwieldy as the component tree grows.
+
+  top-app provides a typed reactive state object available to every component in
+  the tree through context. Any component can write to it, and all subscribers
+  re-render automatically — no shared parent required.
+
+  This tutorial covers defining a typed payload for custom app state; building a
+  filter selector that updates shared state on button click; building a results
+  counter that reads the current filter and count from shared state; composing both
+  into a panel inside a top-app layout; and noting when the shared state is
+  available relative to the engine boot sequence.
+
+  By the end, you'll have two independent components that stay in sync through
+  shared reactive state — a filter selector and a results counter that reflect each
+  other's changes without any direct coupling between them.
+*/
+
+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 } from "thatopen-services";
+import uiManagerDef from "../../../../index";
+import {
+  appStateContext,
+  AppState,
+  AppStateController,
+  type App,
+} from "../../index";
+
+// Define a typed payload for this app's custom state.
+type MyAppState = { selectedFilter: string; count: number };
+
+// AppStateController subscribes to appStateContext and triggers a re-render
+// on every setCustom call — across any component in the tree that holds one.
+@customElement("filter-selector")
+class FilterSelector extends LitElement {
+  @consume({ context: appStateContext, subscribe: true })
+  @state()
+  private _appState?: AppState;
+
+  // Declare the controller — the LitElement lifecycle handles subscription.
+  private _stateCtrl = new AppStateController<MyAppState>(this, () => this._appState);
+
+  render() {
+    const filters = ["All", "Walls", "Slabs", "Columns"];
+    const active = this._stateCtrl.custom?.selectedFilter ?? "All";
+    return html`
+      <bim-panel-section label="Filter" icon="solar:filter-bold">
+        ${filters.map(
+          (f) => html`
+            <bim-button
+              .label=${f}
+              ?active=${active === f}
+              @click=${() => {
+                this._appState?.setCustom<MyAppState>({ selectedFilter: f, count: 0 });
+              }}
+            ></bim-button>
+          `,
+        )}
+      </bim-panel-section>
+    `;
+  }
+}
+
+@customElement("result-counter")
+class ResultCounter extends LitElement {
+  @consume({ context: appStateContext, subscribe: true })
+  @state()
+  private _appState?: AppState;
+
+  private _stateCtrl = new AppStateController<MyAppState>(this, () => this._appState);
+
+  render() {
+    const { selectedFilter = "All", count = 0 } = this._stateCtrl.custom ?? {};
+    return html`
+      <bim-panel-section label="Results" icon="solar:list-bold">
+        <bim-label>${count} elements match "${selectedFilter}"</bim-label>
+      </bim-panel-section>
+    `;
+  }
+}
+
+// ---- 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;
+
+// appState is available immediately — before setup completes — so components
+// that only consume appStateContext can render while the engine is still booting.
+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 = {
+  panel: () => html`
+    <bim-panel label="State Demo">
+      <filter-selector></filter-selector>
+      <result-counter></result-counter>
+    </bim-panel>
+  `,
+};
+
+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";