@thatopen/services 0.0.1 → 0.0.2

package/docs/bim-components/type-conventions.md

@@ -0,0 +1,49 @@
+# Type Conventions
+
+All types for a component live in `src/types.ts` — domain interfaces, event payloads, serialized equivalents — so there is a single place to look.
+
+---
+
+## Runtime vs serialized
+
+Components that implement `OBC.Serializable` need two versions of their data types: a runtime version that uses rich TypeScript types, and a serialized version that is JSON-safe.
+
+The serialized type is named `Serialized{TypeName}`:
+
+```ts
+// Runtime — uses Map, Set, Date, THREE.Color
+export interface Activity {
+  index: number;
+  name: string;
+  color: THREE.Color;
+  items: OBC.ModelIdMap;
+  dates: Set<string>;
+}
+
+// Serialized — JSON-safe equivalent
+export interface SerializedActivity {
+  index: number;
+  name: string;
+  color: string;             // THREE.Color → hex string
+  items: [string, number[]][]; // ModelIdMap → tuple array
+  dates: string[];           // Set → array
+}
+```
+
+Conversion happens inside `export()` and `import()` (see [`./save-and-restore-state.md`](./save-and-restore-state.md)).
+
+---
+
+## Generics that require `type`, not `interface`
+
+Some OBC and FRAGS generics enforce that their type parameter is a `type` alias. Passing an `interface` causes a TypeScript error. When in doubt, prefer `type` for types used as generic parameters:
+
+```ts
+// ✗ Fails — interface not assignable to the generic constraint
+export interface ActivityData { name: string; value: number }
+const list = new FRAGS.DataMap<string, ActivityData>(); // error
+
+// ✓ Correct
+export type ActivityData = { name: string; value: number }
+const list = new FRAGS.DataMap<string, ActivityData>();
+```

package/docs/bim-components/user-driven-object-creation.md

@@ -0,0 +1,56 @@
+# User-Driven Object Creation
+
+## `OBC.Createable`
+
+Implement when the component lets the user create objects in the scene through a multi-step interaction — click to start, click to confirm, Escape to cancel, click existing to delete.
+
+The key characteristic is **statefulness between clicks**: `create()` is called on every user click, but the first click initiates the workflow and the second confirms it by calling `endCreation()` internally.
+
+```ts
+export class ActivityTracker extends OBC.Component implements OBC.Createable {
+  private _temp: { isDragging: boolean; preview?: SomeObject } = {
+    isDragging: false,
+  };
+
+  create = () => {
+    if (!this.enabled) return;
+    if (!this._temp.isDragging) {
+      this._temp.isDragging = true;
+      this._temp.preview = new SomeObject();
+      return;
+    }
+    this.endCreation();
+  };
+
+  endCreation = () => {
+    if (!this._temp.preview) return;
+    this.list.add(this._temp.preview);
+    this._temp.isDragging = false;
+    this._temp.preview = undefined;
+  };
+
+  cancelCreation = () => {
+    this._temp.isDragging = false;
+    this._temp.preview?.dispose();
+    this._temp.preview = undefined;
+  };
+
+  delete = () => {
+    if (!this.world) return;
+    const casters = this.components.get(OBC.Raycasters);
+    const caster = casters.get(this.world);
+    const intersect = caster.castRayToObjects([...this._boundingBoxes]);
+    if (!intersect) return;
+    // identify and remove the hit object from list
+  };
+}
+```
+
+Wire up the Escape key in the component's `enabled` setter so `cancelCreation()` fires automatically when the component is disabled mid-flow:
+
+```ts
+set enabled(value: boolean) {
+  this._enabled = value;
+  if (!value) this.cancelCreation();
+}
+```

package/docs/cli-setup.md

@@ -0,0 +1,54 @@
+# CLI Setup and Authentication
+
+Before you can scaffold or publish a That Open Platform app, two things must be in place: the `@thatopen/services` CLI installed globally, and a valid platform token for authentication.
+
+---
+
+## Step 1: Install or update the CLI
+
+Run the following command in the terminal. This installs the CLI if it isn't present, or updates it to the latest version if it already is:
+
+```bash
+npm i @thatopen/services@latest -g
+```
+
+Once done, verify it works:
+
+```bash
+thatopen --version
+```
+
+If this returns a version number, the CLI is ready. If `npm` is not found, install Node.js first — download the LTS version from [https://nodejs.org](https://nodejs.org), then retry.
+
+---
+
+## Step 2: Get a platform token
+
+Generate an access token from the platform:
+
+1. Go to [https://dev.platform.thatopen.com](https://dev.platform.thatopen.com)
+2. In the header, click **Data**
+3. Find the **Tokens** card and create a new token
+4. Enable the permissions: **Apps**, **Components** and **Storage**
+5. Copy the token
+
+---
+
+## Step 3: Authenticate
+
+Once you have the token, run:
+
+```bash
+npm run login -- --token <TOKEN>
+```
+
+where `<TOKEN>` is the token you copied. This stores credentials globally at `~/.thatopen/config.json` and persists across sessions — you only need to do this once per machine.
+
+---
+
+## When to use this guide
+
+Read this guide when:
+- You are starting a new app and haven't confirmed the CLI is installed
+- A `thatopen` command fails with a "command not found" or "not authenticated" error
+- You have never built a platform app before on this machine

package/docs/cloud-components.md

@@ -0,0 +1,74 @@
+# Cloud components & automations
+
+A **cloud component** is a piece of logic that runs **server-side** (Node.js) on the platform,
+on the shared project context, via the API. Use them to automate real operations — clash checks,
+validations, document generation — and to let apps offload heavy work.
+
+## Apps vs cloud components
+
+|  | Apps | Cloud components |
+|---|---|---|
+| **Runs in** | Browser (iframe on the platform) | Server (Node.js child process) |
+| **Item type** | `APP` | `TOOL` |
+| **Entry point** | Side effects in `main.ts` (renders UI) | `export async function main()` |
+| **Build output** | IIFE `dist/bundle.js` (all deps bundled) | IIFE `dist/bundle.js` (only `@thatopen/services` externalized) |
+| **Template** | `bim`, `default`, `test` | `cloud`, `cloud-test` |
+
+## Scaffold
+
+```bash
+thatopen create my-component --template cloud
+cd my-component
+```
+
+The component is an `export async function main()` that runs on the server. The execution engine
+injects these globals (do **not** import them; for `OBC`/`THREE`/`web-ifc` import them so the
+bundler includes them):
+
+| Global | Purpose |
+|--------|---------|
+| `thatOpenServices` | Authenticated `EngineServicesClient` |
+| `executionParams` | Parameters passed by the caller |
+| `executionContext` | `{ projectId?, executionId, toolId, toolVersion }` |
+| `executionReporter` | `{ message(msg), error(msg), progress(pct) }` for live feedback |
+| `OBC` | `@thatopen/components` — BIM engine (import it) |
+| `THREE` | `three` — 3D math/geometry (import it) |
+| `fs` | Node.js filesystem (import it) |
+
+## Run locally
+
+```bash
+npm run run                                 # build + test locally
+npx thatopen run --params '{"inputFile":"model.ifc"}'   # pass parameters
+```
+
+`thatopen local-server` starts an API-compatible local execution server (default `:4001`) so an
+app can call the component before it's deployed (set `client.localServerUrl`).
+
+## Authenticate & publish
+
+```bash
+npm run login -- --token <your-token>
+npm run publish
+```
+
+## Calling a component from an app
+
+```ts
+const { executionId } = await client.executeComponent(componentId, { param: "value" }, versionTag?);
+client.onExecutionProgress(executionId, (data) => {
+  // data.progressUpdate — percentage
+  // data.messageUpdate — status messages
+});
+```
+
+Include `projectId` in the execution params to scope the run to a project (the backend validates
+the component is linked to that project). See [CONTEXT.md](../CONTEXT.md) for the permissions contract.
+
+## Automations (event-triggered components)
+
+An **automation** is a cloud component that runs automatically in response to a platform **event**
+(rather than being invoked by hand) — e.g. "run the clash check whenever a model is updated."
+The component is the same; what differs is the trigger. Add it to a project, choose the event(s)
+that fire it, and the platform executes it on the shared project context, reporting progress and
+logs through `executionReporter`. Build and publish it exactly like any other cloud component above.

package/docs/connect-logic-to-ui.md

@@ -0,0 +1,113 @@
+# Connect Logic to UI
+
+Setup files are the bridge between custom BIM components (logic) and the platform UI. This is where event subscriptions, UI sync, and component wiring live — not in the component itself.
+
+## Structure
+
+```
+setups/
+├── index.ts          → barrel (always present)
+├── ui-manager.ts     → fixed boilerplate (always present)
+└── {custom}.ts       → one per custom BIM component
+```
+
+One file per component being initialized. Each file exports a single function that receives `components: OBC.Components`.
+
+---
+
+## `setups/ui-manager.ts` — Fixed boilerplate
+
+This is where all UI templates get registered in the platform (see the UI-component guide in `docs/`: [./ui-components/overview.md](./ui-components/overview.md)). The file always has this shape — the content changes (which templates are registered), but the structure never does.
+
+### `CustomUIs` type
+
+Maps every UI template to its element type and state. Add one entry per registered template:
+
+```ts
+export type CustomUIs = {
+  filesSection: { type: BUI.PanelSection; state: FilesSectionState }
+  collisionsTable: { type: BUI.Table<CollisionsTableData>; state: CollisionsTableState }
+  // one entry per registered template
+}
+```
+
+### `getUIManager` — typed accessor
+
+The typed accessor for `UIManager`. Defined here because `CustomUIs` lives here. Used everywhere else in `setups/` to interact with the UI registry — never access `UIManager` directly:
+
+```ts
+export const getUIManager = (components: OBC.Components) =>
+  components.get(UIManager<CustomUIs>)
+```
+
+`getUIManager` is the **only** valid way to access `UIManager` in an app. Never use `components.get(UIManager)` directly — it drops the `CustomUIs` type parameter and loses all type information about the registered templates.
+
+```ts
+// ✗ Avoid — loses the CustomUIs type
+const uis = components.get(UIManager)
+
+// ✓ Correct — fully typed
+const uis = getUIManager(components)
+```
+
+### `uiManager` setup function
+
+Registers each template and its optional `onInstanceCreated` callback, exported from the UI component:
+
+```ts
+export const uiManager = (components: OBC.Components) => {
+  const uis = getUIManager(components)
+  uis.registerTemplate("filesSection", {
+    template: filesSectionTemplate,
+    onInstanceCreated: onFilesSectionCreated
+  })
+  uis.registerTemplate("collisionsTable", {
+    template: collisionsTableTemplate
+  })
+}
+```
+
+### Composing UI components
+
+Templates can embed other registered components by creating instances via `uis.custom.get()`:
+
+```ts
+export const filesSectionTemplate: FilesSectionComponent = (state) => {
+  const uis = state.components.get(UIManager)
+  const [modelsList] = uis.custom.get("modelsList").create(state)
+  return BUI.html`
+    <bim-panel-section label="Files">
+      ${modelsList}
+    </bim-panel-section>
+  `
+}
+```
+
+### Keeping UIs in sync with `updateInstances()`
+
+To push a state update to all existing instances of a template, call `updateInstances()` from within a setup file — typically in response to engine events:
+
+```ts
+const updateUIs = () => uis.custom.get("modelsList").updateInstances()
+fragments.list.onItemSet.add(updateUIs)
+fragments.list.onItemDeleted.add(updateUIs)
+```
+
+---
+
+## Custom setup files
+
+Each setup file is the bridge between a custom BIM component and the platform (see the BIM-component guide in `docs/`: [./bim-components/overview.md](./bim-components/overview.md)). This is where wiring lands: event listeners, UI updates, and configuration go here — not in the component's constructor.
+
+```ts
+// setups/qto-manager.ts
+export const qtoManager = (components: OBC.Components) => {
+  const uis = getUIManager(components)
+  const qtoManager = components.get(QtoManager)
+
+  qtoManager.onStateChanged.add((states) => {
+    if (!states.includes("value")) return
+    uis.custom.get("qtosTable").updateInstances()
+  })
+}
+```

package/docs/previewing.md

@@ -0,0 +1,45 @@
+# Previewing Apps During Development
+
+That Open Platform apps can only be previewed correctly within the platform context — opening `localhost:4000` directly in the browser will just bring the app bundle. The app must be loaded from inside a project on the platform as it gives context.
+
+---
+
+## Step 1: Start the dev server
+
+In the project root, run:
+
+```bash
+npm run dev
+```
+
+This invokes `thatopen serve` under the hood — the same CLI installed during setup. It performs a special build and serves the bundle on **port 4000**. Keep this process running throughout your development session.
+
+---
+
+## Step 2: Open the app in the platform
+
+Once the dev server is running:
+
+1. Go to [https://dev.platform.thatopen.com](https://dev.platform.thatopen.com) and enter a project. If no project exists yet, create one first.
+2. In the project sidebar, click **Local App**.
+3. Click **Get Started**.
+
+The platform will load the locally-running app from port 4000 and render it inside the project context, with full access to its models, data, and users.
+
+The resulting URL follows this pattern:
+
+```
+https://dev.platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
+```
+
+where `{projectId}` is the ID of the project. Bookmark this URL to return quickly during development.
+
+> The dev server must be running before opening this URL. If the bundle is not being served on port 4000, the platform will fail to load the app.
+
+---
+
+## When to read this guide
+
+- When you want to see, run, or preview the app
+- When you have run `npm run dev` and don't know what to do next
+- When the app is not showing up in the platform

package/docs/publishing.md

@@ -0,0 +1,35 @@
+# Publishing an App
+
+Publishing to the That Open Platform is a two-step process: authenticate first, then publish.
+
+## Step 1: Authenticate
+
+```bash
+thatopen login
+```
+
+This stores credentials globally at `~/.thatopen/config.json`. Authentication persists across sessions — you only need to do this once per machine.
+
+**Options:**
+
+| Flag | Purpose |
+|---|---|
+| `--token <token>` | Non-interactive login (CI, scripts) |
+| `--local` | Store credentials in the project directory (`.thatopen`) instead of globally |
+
+## Step 2: Publish
+
+```bash
+thatopen publish
+```
+
+This builds the app and uploads it to the platform. The command handles the build step automatically unless told otherwise.
+
+**Common options:**
+
+| Flag | Purpose |
+|---|---|
+| `--name <name>` | Override the published app name |
+| `--version-tag <tag>` | Tag the release (e.g. `v1.2.0`) |
+| `--skip-build` | Skip the build step if the bundle is already built |
+| `--app-id <id>` | Publish to a specific existing app |

package/docs/scaffolding.md

@@ -0,0 +1,54 @@
+# Scaffolding a New App
+
+When starting a new platform app from scratch, **always use the CLI to scaffold the project — never create the files manually.** The CLI produces the exact project structure these docs describe, correctly configured and with dependencies installed. Writing the scaffold by hand defeats the purpose of the tool and risks inconsistencies.
+
+## Command
+
+```bash
+thatopen create <app-name>
+```
+
+Use `.` as the name to scaffold in the current directory:
+
+```bash
+thatopen create .
+```
+
+This copies the template files into the target directory and runs `npm install` automatically.
+
+## Templates
+
+Pass `--template <name>` to choose a template. The default is `bim`.
+
+| Template | When to use |
+|---|---|
+| `bim` (default) | Standard BIM viewer app — Three.js viewport, BIM viewer, platform UI components. This is the right starting point for almost every app. |
+| `default` | Minimal shell — just shows platform context. Use only when you explicitly want to start from scratch without any viewer. |
+
+If no template is specified, use `bim`.
+
+## What the scaffold produces
+
+The `bim` template generates the full structure described in the **Project Structure** section of [./app-architecture.md](./app-architecture.md):
+
+```
+src/
+├── bim-components/
+├── ui-components/
+├── setups/
+├── app.ts
+├── globals.ts
+└── main.ts
+```
+
+All platform built-ins (`AppManager`, `UIManager`, `ViewportsManager`) are already wired up in the generated `main.ts`. There is nothing to manually wire at the entry point — just extend from there.
+
+## Starting the dev server
+
+After scaffolding, start the local dev server:
+
+```bash
+thatopen serve
+```
+
+This launches an esbuild watch process that rebundles on every file change and serves the app with live reload. No configuration needed.

package/docs/ui-components/async-actions.md

@@ -0,0 +1,18 @@
+# Async Actions
+
+## Async button handler
+
+When a button triggers an async operation, set `target.loading = true` at the start and `false` when done — including in error paths:
+
+```ts
+const onClick = async ({ target }: { target: BUI.Button }) => {
+  target.loading = true
+  try {
+    await doSomething()
+  } finally {
+    target.loading = false
+  }
+}
+```
+
+Always restore `target.loading = false` in error paths. If an exception is thrown and loading is not reset, the button stays stuck in the loading state.

package/docs/ui-components/confirmation-dialog.md

@@ -0,0 +1,39 @@
+# Confirmation Dialog
+
+The standard way to ask the user to confirm a destructive or irreversible action is a `contextMenuTemplate` on a `bim-button`. The menu opens lazily when clicked and contains Confirm / Cancel buttons.
+
+## Setup
+
+`contextMenuTemplate` must always be assigned via `BUI.ref` — never inline in `BUI.html`:
+
+```ts
+const onBtnCreated = (e?: Element) => {
+  if (!e) return
+  const btn = e as BUI.Button
+  btn.contextMenuTemplate = () => {
+    const onConfirm = async ({ target }: { target: BUI.Button }) => {
+      target.loading = true
+      await doSomething()
+      target.loading = false
+      BUI.ContextMenu.removeMenus()
+    }
+
+    const onCancel = () => {
+      BUI.ContextMenu.removeMenus()
+    }
+
+    return BUI.html`
+      <bim-context-menu>
+        <bim-button @click=${onConfirm} label="Confirm"></bim-button>
+        <bim-button @click=${onCancel} label="Cancel"></bim-button>
+      </bim-context-menu>
+    `
+  }
+}
+
+return BUI.html`<bim-button ${BUI.ref(onBtnCreated)} icon="delete"></bim-button>`
+```
+
+## Closing the menu
+
+Call `BUI.ContextMenu.removeMenus()` after the action completes (or is cancelled) to dismiss the popup. Without it, the menu stays open after the user clicks.