@thatopen/services 0.0.2 → 0.0.3

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

@@ -1,113 +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()
-  })
-}
-```
+# 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

@@ -1,45 +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
+# 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

@@ -1,35 +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 |
+# 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

@@ -1,54 +1,71 @@
-# 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.
+# 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 on the public engine libraries. |
+| `bim-beta` | Same as `bim` but on the private **beta** engine libraries (`@thatopen-platform/*-beta`) — the line the platform currently runs. Use this for founding members (see below). |
+| `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`.
+
+## Beta libraries (founding members) — use the `bim-beta` template
+
+**Before scaffolding, ask the user whether they have beta access** and want the latest engine
+libraries. If so, scaffold with the `bim-beta` template:
+
+```bash
+thatopen create <app-name> -t bim-beta
+```
+
+`bim-beta` is the `bim` viewer wired directly to the private `@thatopen-platform/*-beta` packages —
+the **same library line the platform currently runs**. Prefer it whenever the user has beta access:
+the public `bim` template uses older libraries that can error at runtime against a beta platform.
+
+Founding members have **permanent** beta access. The beta packages are private, so the user must
+have their beta access token configured in npm, or `npm install` will fail with a 401/403.
+
+## 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

@@ -1,18 +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.
+# 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

@@ -1,39 +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.
+# 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.