@thatopen/services 0.0.6 → 0.2.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/FileList/example.ts

@@ -1,107 +1,107 @@
-import * as OBC from "@thatopen/components";
-import * as BUI from "@thatopen/ui";
-import type { EngineServicesClient, Item } from "thatopen-services";
-
-import appManagerDef from "../AppManager/index";
-import fileListDef from "./index";
-
-const AppManager = appManagerDef.componentDefinition;
-const FileList = fileListDef.componentDefinition;
-
-// ── A tiny in-memory fake client for the example ──────────────────────
-// Real apps should pass their `EngineServicesClient` instance here — this
-// stub just implements the subset of the API the FileList component uses.
-
-let nextId = 1;
-const mkFile = (name: string, ext?: string): Item => ({
-  _id: `file-${nextId++}`,
-  name,
-  fileExtension: ext,
-  itemType: "FILE",
-  internalId: `internal-${nextId}`,
-  createdAt: new Date(),
-  creatingUser: "demo-user",
-});
-
-const files: Item[] = [
-  mkFile("site-plan", "pdf"),
-  mkFile("structural-model", "ifc"),
-  mkFile("mep-coordination", "ifc"),
-  mkFile("bcf-issues", "bcf"),
-];
-
-const fakeClient = {
-  async listFiles() {
-    // Small delay to show the loading state.
-    await new Promise((r) => setTimeout(r, 150));
-    return files.filter((f) => !f.archived);
-  },
-  async downloadFile(id: string) {
-    const file = files.find((f) => f._id === id)!;
-    const body = `Pretend contents of ${file.name}`;
-    return new Response(body, { headers: { "Content-Type": "text/plain" } });
-  },
-  async updateFile(id: string, data: { name?: string }) {
-    const file = files.find((f) => f._id === id)!;
-    if (data.name) file.name = data.name;
-    return { item: file };
-  },
-  async archiveFile(id: string) {
-    const file = files.find((f) => f._id === id)!;
-    file.archived = true;
-    return file;
-  },
-} as unknown as EngineServicesClient;
-
-// ── App type ──────────────────────────────────────────────────────────
-
-type FilesState = { components: OBC.Components };
-
-interface FileListApp {
-  icons: ["FILES"];
-  grid: BUI.Grid<
-    ["Files"],
-    [{ name: "files"; state: FilesState }]
-  >;
-}
-
-// ── Initialise OBC & BUI ──────────────────────────────────────────────
-
-BUI.Manager.init();
-const components = new OBC.Components();
-
-const app = components.get(AppManager<FileListApp>);
-const fileList = components.get(FileList);
-
-// ── Create a file list instance ───────────────────────────────────────
-
-const { element: fileListElement } = fileList.create({ client: fakeClient });
-
-const filesPanel: BUI.StatefullComponent<FilesState> = (_state) => BUI.html`
-  <bim-panel active label="Files" style="display: flex; flex-direction: column;">
-    <bim-panel-section label="Project files" style="flex: 1; min-height: 0;">
-      ${fileListElement}
-    </bim-panel-section>
-  </bim-panel>
-`;
-
-// ── Init ──────────────────────────────────────────────────────────────
-
-app.init({
-  icons: { FILES: "mdi:file-multiple" },
-  grid: (grid) => {
-    grid.elements = {
-      files: { template: filesPanel, initialState: { components } },
-    };
-    grid.layouts = {
-      Files: {
-        template: `"files" 1fr / 1fr`,
-        icon: app.icons.FILES,
-      },
-    };
-    grid.layout = "Files";
-  },
-  container: document.getElementById("container")!,
-});
-
-components.init();
+import * as OBC from "@thatopen/components";
+import * as BUI from "@thatopen/ui";
+import type { EngineServicesClient, Item } from "thatopen-services";
+
+import appManagerDef from "../AppManager/index";
+import fileListDef from "./index";
+
+const AppManager = appManagerDef.componentDefinition;
+const FileList = fileListDef.componentDefinition;
+
+// ── A tiny in-memory fake client for the example ──────────────────────
+// Real apps should pass their `EngineServicesClient` instance here — this
+// stub just implements the subset of the API the FileList component uses.
+
+let nextId = 1;
+const mkFile = (name: string, ext?: string): Item => ({
+  _id: `file-${nextId++}`,
+  name,
+  fileExtension: ext,
+  itemType: "FILE",
+  internalId: `internal-${nextId}`,
+  createdAt: new Date(),
+  creatingUser: "demo-user",
+});
+
+const files: Item[] = [
+  mkFile("site-plan", "pdf"),
+  mkFile("structural-model", "ifc"),
+  mkFile("mep-coordination", "ifc"),
+  mkFile("bcf-issues", "bcf"),
+];
+
+const fakeClient = {
+  async listFiles() {
+    // Small delay to show the loading state.
+    await new Promise((r) => setTimeout(r, 150));
+    return files.filter((f) => !f.archived);
+  },
+  async downloadFile(id: string) {
+    const file = files.find((f) => f._id === id)!;
+    const body = `Pretend contents of ${file.name}`;
+    return new Response(body, { headers: { "Content-Type": "text/plain" } });
+  },
+  async updateFile(id: string, data: { name?: string }) {
+    const file = files.find((f) => f._id === id)!;
+    if (data.name) file.name = data.name;
+    return { item: file };
+  },
+  async archiveFile(id: string) {
+    const file = files.find((f) => f._id === id)!;
+    file.archived = true;
+    return file;
+  },
+} as unknown as EngineServicesClient;
+
+// ── App type ──────────────────────────────────────────────────────────
+
+type FilesState = { components: OBC.Components };
+
+interface FileListApp {
+  icons: ["FILES"];
+  grid: BUI.Grid<
+    ["Files"],
+    [{ name: "files"; state: FilesState }]
+  >;
+}
+
+// ── Initialise OBC & BUI ──────────────────────────────────────────────
+
+BUI.Manager.init();
+const components = new OBC.Components();
+
+const app = components.get(AppManager<FileListApp>);
+const fileList = components.get(FileList);
+
+// ── Create a file list instance ───────────────────────────────────────
+
+const { element: fileListElement } = fileList.create({ client: fakeClient });
+
+const filesPanel: BUI.StatefullComponent<FilesState> = (_state) => BUI.html`
+  <bim-panel active label="Files" style="display: flex; flex-direction: column;">
+    <bim-panel-section label="Project files" style="flex: 1; min-height: 0;">
+      ${fileListElement}
+    </bim-panel-section>
+  </bim-panel>
+`;
+
+// ── Init ──────────────────────────────────────────────────────────────
+
+app.init({
+  icons: { FILES: "mdi:file-multiple" },
+  grid: (grid) => {
+    grid.elements = {
+      files: { template: filesPanel, initialState: { components } },
+    };
+    grid.layouts = {
+      Files: {
+        template: `"files" 1fr / 1fr`,
+        icon: app.icons.FILES,
+      },
+    };
+    grid.layout = "Files";
+  },
+  container: document.getElementById("container")!,
+});
+
+components.init();