@thatopen/services 0.5.0 → 0.7.0

package/src/built-in/CDEManager/examples/ProjectConfig/example.ts

@@ -1,177 +1,177 @@
-/* MD
-  ## Project configuration — read, write, and reload persistent data
-  ---
-  A CDE application needs to store two kinds of configuration: project-wide settings
-  that all team members share (the metadata schema, custom naming rules) and personal
-  settings that belong to one user (which columns are visible, which metadata views
-  are pinned). Both live inside the project's file storage under a reserved system
-  folder, so they travel with the project and don't rely on a separate configuration
-  service.
-
-  CDEManager exposes a simple read/write API that handles the folder structure
-  automatically: finding or creating the right system folders, detecting whether a
-  file already exists and versioning it instead of duplicating, and returning the
-  parsed JSON on read. The metadata schema and user config are pre-wired shortcuts on
-  top of this same mechanism — they just target fixed paths.
-
-  This tutorial covers writing and reading arbitrary JSON under a named application
-  namespace; demonstrating that writing the same file twice creates a new version
-  rather than a duplicate; loading a user's personal config and verifying the round-
-  trip; and writing a metadata schema then loading it back through `loadMetadataSchema`
-  to confirm the schema is applied to CDEManager correctly.
-
-  By the end, you'll see the full persistence layer that backs the schema editor and
-  user preferences, and understand how any part of the platform can store structured
-  data without managing the folder hierarchy directly.
-*/
-
-import * as OBC from "@thatopen/components";
-// In production platform apps, CDEManager is loaded through the platform client:
-//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
-// Here we import directly from source for local testing.
-import { CDEManager } from "../../index";
-
-/* MD
-  ### 🛠️ Setting up
-  Project data operations require an active client context throughout — they make real
-  API calls to create folders and files. We use a stateful mock that behaves like a
-  real backend: folders and files are created on demand and stored in memory, so reads
-  always return what was last written.
-*/
-
-const components = new OBC.Components();
-const cde = components.get(CDEManager);
-
-const output = document.getElementById("output") as HTMLPreElement;
-const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
-
-// In-memory store that simulates the project file storage.
-const store = {
-  folders: [] as any[],
-  files:   [] as any[],
-  data:    new Map<string, any>(),
-  fIdx: 0,
-  dIdx: 0,
-};
-
-const mockClient = {
-  checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
-  getProjectData: async () => ({
-    project: { title: "Demo Project" },
-    users: [],
-    currentUser: { user: { _id: "user-alice" } },
-  }),
-  listFolders: async ({ parentFolderId }: any) =>
-    store.folders.filter(f =>
-      parentFolderId !== undefined
-        ? String(f.parentId) === String(parentFolderId)
-        : !f.parentId
-    ),
-  createFolder: async (name: string, parentId?: string) => {
-    const folder = { _id: `folder-${store.fIdx++}`, name, parentId: parentId ?? null };
-    store.folders.push(folder);
-    return folder;
-  },
-  listFiles: async () => store.files,
-  createFile: async ({ file: blob, name, versionTag, parentFolderId }: any) => {
-    const id = `doc-${store.dIdx++}`;
-    store.data.set(id, JSON.parse(await blob.text()));
-    store.files.push({ _id: id, name, folderId: parentFolderId, versionTag });
-    return {
-      item: { _id: id, name, folderId: parentFolderId, createdAt: new Date().toISOString(), createdBy: "mock", itemType: "FILE" },
-      version: { tag: versionTag },
-    };
-  },
-  listVersions: async (fileId: string) => {
-    const f = store.files.find(f => f._id === fileId);
-    return f ? [{ _id: `v-${fileId}`, tag: f.versionTag ?? "v1" }] : [];
-  },
-  createVersion: async (fileId: string, blob: any, tag: string) => {
-    store.data.set(fileId, JSON.parse(await blob.text()));
-    const f = store.files.find(f => f._id === fileId);
-    if (f) f.versionTag = tag;
-    return { tag };
-  },
-  downloadFile: async (id: string) => ({
-    json: async () => store.data.get(id) ?? null,
-    arrayBuffer: async () => new ArrayBuffer(0),
-  }),
-};
-
-cde.ctx = { client: mockClient as any, projectId: "mock" };
-await cde.loadFolders();
-
-/* MD
-  ### 📝 Writing and reading project data
-  `writeProjectData` takes an application namespace and a filename. The first time a
-  file is written, it is created under `__project_data/{app}/`. Subsequent writes to
-  the same path create a new version instead of a new file, keeping the full history
-  while the read path always returns the latest content.
-*/
-
-log("\n--- write and read ---");
-const payload = { lastRun: "2026-06-10", status: "ok", count: 42 };
-const tag1 = await cde.writeProjectData("my-app", "run-log.json", payload);
-log(`  write v1 tag: ${tag1}`);
-
-const read1 = await cde.readProjectData("my-app", "run-log.json");
-log(`  read back: status="${read1.status}", count=${read1.count}`);
-
-/* MD
-  ### 🔄 Versioning on repeated writes
-  Writing to the same path a second time detects the existing file and creates a new
-  version. The read always returns the latest version, so the caller doesn't need to
-  track version tags — they just write and read at the same path.
-*/
-
-log("\n--- auto-versioning ---");
-const updated = { ...payload, count: 99, lastRun: "2026-06-11" };
-const tag2 = await cde.writeProjectData("my-app", "run-log.json", updated);
-log(`  write v2 tag: ${tag2}`);
-
-const read2 = await cde.readProjectData("my-app", "run-log.json");
-log(`  read after update: count=${read2.count}`);
-
-/* MD
-  ### 👤 User configuration round-trip
-  `saveUserConfig` and `loadUserConfig` are thin wrappers around `writeProjectData`
-  and `readProjectData` that target a user-specific path (`cde/user_{id}.json`). They
-  accept and return the same config shape as the rest of the CDE — visible columns and
-  metadata views — so the schema editor and column picker can persist their state
-  without knowing the path structure.
-*/
-
-log("\n--- user config round-trip ---");
-const userConfig = {
-  visibleColumns: ["name", "discipline", "phase", "createdAt"],
-  metadataViews: [{ id: "view-str", name: "Structural", fields: ["discipline", "phase"] }],
-};
-await cde.saveUserConfig(userConfig);
-
-const loaded = await cde.loadUserConfig();
-log(`  visibleColumns: [${loaded?.visibleColumns?.join(", ")}]`);
-log(`  views: ${loaded?.metadataViews?.length} view(s)`);
-
-/* MD
-  ### 🗂️ Schema persistence via loadMetadataSchema
-  `loadMetadataSchema` reads `cde/config.json` from the project storage and applies
-  the `metadataSchema` section to CDEManager. Writing the config file manually (via
-  `writeProjectData`) then calling `loadMetadataSchema` is the setup path used by the
-  schema editor after a successful save — the same round-trip that happens in
-  production when the app boots.
-*/
-
-log("\n--- schema persistence ---");
-const schemaPayload = {
-  metadataSchema: {
-    discipline: { label: "Discipline", type: "string", required: true },
-    phase:      { label: "Phase",      type: "string", required: false },
-    zone:       { label: "Zone",       type: "string", required: false },
-  },
-};
-await cde.writeProjectData("cde", "config.json", schemaPayload);
-
-await cde.loadMetadataSchema();
-log(`  schema keys after load: [${Object.keys(cde.metadataSchema).join(", ")}]`);
-log(`  discipline.required: ${cde.metadataSchema["discipline"]?.required}`);
-log(`  zone exists: ${"zone" in cde.metadataSchema}`);
+/* MD
+  ## Project configuration — read, write, and reload persistent data
+  ---
+  A CDE application needs to store two kinds of configuration: project-wide settings
+  that all team members share (the metadata schema, custom naming rules) and personal
+  settings that belong to one user (which columns are visible, which metadata views
+  are pinned). Both live inside the project's file storage under a reserved system
+  folder, so they travel with the project and don't rely on a separate configuration
+  service.
+
+  CDEManager exposes a simple read/write API that handles the folder structure
+  automatically: finding or creating the right system folders, detecting whether a
+  file already exists and versioning it instead of duplicating, and returning the
+  parsed JSON on read. The metadata schema and user config are pre-wired shortcuts on
+  top of this same mechanism — they just target fixed paths.
+
+  This tutorial covers writing and reading arbitrary JSON under a named application
+  namespace; demonstrating that writing the same file twice creates a new version
+  rather than a duplicate; loading a user's personal config and verifying the round-
+  trip; and writing a metadata schema then loading it back through `loadMetadataSchema`
+  to confirm the schema is applied to CDEManager correctly.
+
+  By the end, you'll see the full persistence layer that backs the schema editor and
+  user preferences, and understand how any part of the platform can store structured
+  data without managing the folder hierarchy directly.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+
+/* MD
+  ### 🛠️ Setting up
+  Project data operations require an active client context throughout — they make real
+  API calls to create folders and files. We use a stateful mock that behaves like a
+  real backend: folders and files are created on demand and stored in memory, so reads
+  always return what was last written.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+// In-memory store that simulates the project file storage.
+const store = {
+  folders: [] as any[],
+  files:   [] as any[],
+  data:    new Map<string, any>(),
+  fIdx: 0,
+  dIdx: 0,
+};
+
+const mockClient = {
+  checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+  getProjectData: async () => ({
+    project: { title: "Demo Project" },
+    users: [],
+    currentUser: { user: { _id: "user-alice" } },
+  }),
+  listFolders: async ({ parentFolderId }: any) =>
+    store.folders.filter(f =>
+      parentFolderId !== undefined
+        ? String(f.parentId) === String(parentFolderId)
+        : !f.parentId
+    ),
+  createFolder: async (name: string, parentId?: string) => {
+    const folder = { _id: `folder-${store.fIdx++}`, name, parentId: parentId ?? null };
+    store.folders.push(folder);
+    return folder;
+  },
+  listFiles: async () => store.files,
+  createFile: async ({ file: blob, name, versionTag, parentFolderId }: any) => {
+    const id = `doc-${store.dIdx++}`;
+    store.data.set(id, JSON.parse(await blob.text()));
+    store.files.push({ _id: id, name, folderId: parentFolderId, versionTag });
+    return {
+      item: { _id: id, name, folderId: parentFolderId, createdAt: new Date().toISOString(), createdBy: "mock", itemType: "FILE" },
+      version: { tag: versionTag },
+    };
+  },
+  listVersions: async (fileId: string) => {
+    const f = store.files.find(f => f._id === fileId);
+    return f ? [{ _id: `v-${fileId}`, tag: f.versionTag ?? "v1" }] : [];
+  },
+  createVersion: async (fileId: string, blob: any, tag: string) => {
+    store.data.set(fileId, JSON.parse(await blob.text()));
+    const f = store.files.find(f => f._id === fileId);
+    if (f) f.versionTag = tag;
+    return { tag };
+  },
+  downloadFile: async (id: string) => ({
+    json: async () => store.data.get(id) ?? null,
+    arrayBuffer: async () => new ArrayBuffer(0),
+  }),
+};
+
+cde.ctx = { client: mockClient as any, projectId: "mock" };
+await cde.loadFolders();
+
+/* MD
+  ### 📝 Writing and reading project data
+  `writeProjectData` takes an application namespace and a filename. The first time a
+  file is written, it is created under `__project_data/{app}/`. Subsequent writes to
+  the same path create a new version instead of a new file, keeping the full history
+  while the read path always returns the latest content.
+*/
+
+log("\n--- write and read ---");
+const payload = { lastRun: "2026-06-10", status: "ok", count: 42 };
+const tag1 = await cde.writeProjectData("my-app", "run-log.json", payload);
+log(`  write v1 tag: ${tag1}`);
+
+const read1 = await cde.readProjectData("my-app", "run-log.json");
+log(`  read back: status="${read1.status}", count=${read1.count}`);
+
+/* MD
+  ### 🔄 Versioning on repeated writes
+  Writing to the same path a second time detects the existing file and creates a new
+  version. The read always returns the latest version, so the caller doesn't need to
+  track version tags — they just write and read at the same path.
+*/
+
+log("\n--- auto-versioning ---");
+const updated = { ...payload, count: 99, lastRun: "2026-06-11" };
+const tag2 = await cde.writeProjectData("my-app", "run-log.json", updated);
+log(`  write v2 tag: ${tag2}`);
+
+const read2 = await cde.readProjectData("my-app", "run-log.json");
+log(`  read after update: count=${read2.count}`);
+
+/* MD
+  ### 👤 User configuration round-trip
+  `saveUserConfig` and `loadUserConfig` are thin wrappers around `writeProjectData`
+  and `readProjectData` that target a user-specific path (`cde/user_{id}.json`). They
+  accept and return the same config shape as the rest of the CDE — visible columns and
+  metadata views — so the schema editor and column picker can persist their state
+  without knowing the path structure.
+*/
+
+log("\n--- user config round-trip ---");
+const userConfig = {
+  visibleColumns: ["name", "discipline", "phase", "createdAt"],
+  metadataViews: [{ id: "view-str", name: "Structural", fields: ["discipline", "phase"] }],
+};
+await cde.saveUserConfig(userConfig);
+
+const loaded = await cde.loadUserConfig();
+log(`  visibleColumns: [${loaded?.visibleColumns?.join(", ")}]`);
+log(`  views: ${loaded?.metadataViews?.length} view(s)`);
+
+/* MD
+  ### 🗂️ Schema persistence via loadMetadataSchema
+  `loadMetadataSchema` reads `cde/config.json` from the project storage and applies
+  the `metadataSchema` section to CDEManager. Writing the config file manually (via
+  `writeProjectData`) then calling `loadMetadataSchema` is the setup path used by the
+  schema editor after a successful save — the same round-trip that happens in
+  production when the app boots.
+*/
+
+log("\n--- schema persistence ---");
+const schemaPayload = {
+  metadataSchema: {
+    discipline: { label: "Discipline", type: "string", required: true },
+    phase:      { label: "Phase",      type: "string", required: false },
+    zone:       { label: "Zone",       type: "string", required: false },
+  },
+};
+await cde.writeProjectData("cde", "config.json", schemaPayload);
+
+await cde.loadMetadataSchema();
+log(`  schema keys after load: [${Object.keys(cde.metadataSchema).join(", ")}]`);
+log(`  discipline.required: ${cde.metadataSchema["discipline"]?.required}`);
+log(`  zone exists: ${"zone" in cde.metadataSchema}`);

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

@@ -1,97 +1,97 @@
-/* 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, UIManager } from "@thatopen/services";
-import type { App } from "./index";
-
-
-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";
+/* 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, UIManager } from "@thatopen/services";
+import type { App } from "./index";
+
+
+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";