@thatopen/services 0.0.6 → 0.1.3

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

@@ -1,115 +1,115 @@
-import * as OBC from "@thatopen/components";
-import * as BUI from "@thatopen/ui";
-
-import appManagerDef from "../AppManager/index";
-import tabbedNavDef from "./index";
-
-const AppManager = appManagerDef.componentDefinition;
-const TabbedNavigation = tabbedNavDef.componentDefinition;
-
-// ── App type ──────────────────────────────────────────────────────────
-
-type PanelState = { label: string };
-
-interface NavApp {
-  icons: ["DASHBOARD", "FILES", "SETTINGS"];
-  grid: BUI.Grid<
-    ["Dashboard", "Files", "Settings"],
-    [
-      { name: "tabs"; state: null },
-      { name: "dashboard"; state: PanelState },
-      { name: "files"; state: PanelState },
-      { name: "settings"; state: PanelState }
-    ]
-  >;
-}
-
-// ── Initialise OBC & BUI ──────────────────────────────────────────────
-
-BUI.Manager.init();
-const components = new OBC.Components();
-
-const app = components.get(AppManager<NavApp>);
-const tabs = components.get(TabbedNavigation);
-
-// ── Templates ─────────────────────────────────────────────────────────
-
-const makePanel = (): BUI.StatefullComponent<PanelState> =>
-  ({ label }) => BUI.html`
-    <bim-panel active label=${label}>
-      <bim-panel-section label="Content">
-        <bim-label>Current screen: ${label}</bim-label>
-      </bim-panel-section>
-    </bim-panel>
-  `;
-
-// The grid caches elements by template-function identity, so each tab area
-// needs its own function reference — otherwise the grid reuses the same
-// panel element across layouts.
-const dashboardPanel = makePanel();
-const filesPanel = makePanel();
-const settingsPanel = makePanel();
-
-// We'll fill the tabs element after init.
-let tabsElement: HTMLElement | null = null;
-
-// ── Init ──────────────────────────────────────────────────────────────
-
-app.init({
-  icons: {
-    DASHBOARD: "mdi:view-dashboard",
-    FILES: "mdi:file-multiple",
-    SETTINGS: "mdi:cog",
-  },
-  grid: (grid) => {
-    grid.elements = {
-      tabs: (() => {
-        // Lazy placeholder — TabbedNavigation attaches here after app.init().
-        const slot = document.createElement("div");
-        slot.style.cssText = "display: flex; padding: 0.5rem;";
-        tabsElement = slot;
-        return slot;
-      })(),
-      dashboard: { template: dashboardPanel, initialState: { label: "Dashboard" } },
-      files: { template: filesPanel, initialState: { label: "Files" } },
-      settings: { template: settingsPanel, initialState: { label: "Settings" } },
-    };
-    grid.layouts = {
-      Dashboard: {
-        template: `
-          "tabs" auto
-          "dashboard" 1fr
-          / 1fr
-        `,
-        icon: app.icons.DASHBOARD,
-      },
-      Files: {
-        template: `
-          "tabs" auto
-          "files" 1fr
-          / 1fr
-        `,
-        icon: app.icons.FILES,
-      },
-      Settings: {
-        template: `
-          "tabs" auto
-          "settings" 1fr
-          / 1fr
-        `,
-        icon: app.icons.SETTINGS,
-      },
-    };
-    grid.layout = "Dashboard";
-  },
-  container: document.getElementById("container")!,
-});
-
-// Create the tab bar now that the grid exists.
-const { element: tabBar } = tabs.create();
-tabsElement?.appendChild(tabBar);
-
-// Hide the default sidebar — tabs replace it.
-app.showSidebar = false;
-
-components.init();
+import * as OBC from "@thatopen/components";
+import * as BUI from "@thatopen/ui";
+
+import appManagerDef from "../AppManager/index";
+import tabbedNavDef from "./index";
+
+const AppManager = appManagerDef.componentDefinition;
+const TabbedNavigation = tabbedNavDef.componentDefinition;
+
+// ── App type ──────────────────────────────────────────────────────────
+
+type PanelState = { label: string };
+
+interface NavApp {
+  icons: ["DASHBOARD", "FILES", "SETTINGS"];
+  grid: BUI.Grid<
+    ["Dashboard", "Files", "Settings"],
+    [
+      { name: "tabs"; state: null },
+      { name: "dashboard"; state: PanelState },
+      { name: "files"; state: PanelState },
+      { name: "settings"; state: PanelState }
+    ]
+  >;
+}
+
+// ── Initialise OBC & BUI ──────────────────────────────────────────────
+
+BUI.Manager.init();
+const components = new OBC.Components();
+
+const app = components.get(AppManager<NavApp>);
+const tabs = components.get(TabbedNavigation);
+
+// ── Templates ─────────────────────────────────────────────────────────
+
+const makePanel = (): BUI.StatefullComponent<PanelState> =>
+  ({ label }) => BUI.html`
+    <bim-panel active label=${label}>
+      <bim-panel-section label="Content">
+        <bim-label>Current screen: ${label}</bim-label>
+      </bim-panel-section>
+    </bim-panel>
+  `;
+
+// The grid caches elements by template-function identity, so each tab area
+// needs its own function reference — otherwise the grid reuses the same
+// panel element across layouts.
+const dashboardPanel = makePanel();
+const filesPanel = makePanel();
+const settingsPanel = makePanel();
+
+// We'll fill the tabs element after init.
+let tabsElement: HTMLElement | null = null;
+
+// ── Init ──────────────────────────────────────────────────────────────
+
+app.init({
+  icons: {
+    DASHBOARD: "mdi:view-dashboard",
+    FILES: "mdi:file-multiple",
+    SETTINGS: "mdi:cog",
+  },
+  grid: (grid) => {
+    grid.elements = {
+      tabs: (() => {
+        // Lazy placeholder — TabbedNavigation attaches here after app.init().
+        const slot = document.createElement("div");
+        slot.style.cssText = "display: flex; padding: 0.5rem;";
+        tabsElement = slot;
+        return slot;
+      })(),
+      dashboard: { template: dashboardPanel, initialState: { label: "Dashboard" } },
+      files: { template: filesPanel, initialState: { label: "Files" } },
+      settings: { template: settingsPanel, initialState: { label: "Settings" } },
+    };
+    grid.layouts = {
+      Dashboard: {
+        template: `
+          "tabs" auto
+          "dashboard" 1fr
+          / 1fr
+        `,
+        icon: app.icons.DASHBOARD,
+      },
+      Files: {
+        template: `
+          "tabs" auto
+          "files" 1fr
+          / 1fr
+        `,
+        icon: app.icons.FILES,
+      },
+      Settings: {
+        template: `
+          "tabs" auto
+          "settings" 1fr
+          / 1fr
+        `,
+        icon: app.icons.SETTINGS,
+      },
+    };
+    grid.layout = "Dashboard";
+  },
+  container: document.getElementById("container")!,
+});
+
+// Create the tab bar now that the grid exists.
+const { element: tabBar } = tabs.create();
+tabsElement?.appendChild(tabBar);
+
+// Hide the default sidebar — tabs replace it.
+app.showSidebar = false;
+
+components.init();

package/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";

package/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";

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

@@ -0,0 +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";