@thatopen/services 0.0.1 → 0.0.2

package/docs/ui-components/sections-layout.md

@@ -0,0 +1,123 @@
+# Panel Section Layout
+
+## Composition mental model
+
+A panel section has zones that follow a natural sequence reflecting how the user processes the panel: first they act on the context (controls), then understand the current state (messages), then operate on the selected item (toolbar), then see the data (main content), and finally execute high-impact actions (bottom).
+
+```
+<bim-panel-section label="..." icon="..." fixed?>
+  [controls bar]      ← search or selector + action buttons
+  [status messages]   ← conditional bim-labels (warn, success, info)
+  [actions toolbar]   ← bim-toolbar when there are many actions on the active item
+  [main content]      ← table, list, or sub-component
+  [primary actions]   ← 1-2 high-impact buttons at the bottom
+</bim-panel-section>
+```
+
+Not all zones are always present. This sequence is a guide, not a mandatory template — if the panel's content breaks that flow in a way that improves the experience, propose the layout that makes the most sense and explain the reasoning.
+
+### Forbidden nesting
+
+Inside a `<bim-panel-section>` it is **never** valid to place:
+
+- Another `<bim-panel-section>`
+- A `<bim-panel>`
+
+This mistake is most tempting when the user asks to "group" sections. The correct answer is **not** nesting — it is creating independent templates. A template does not decide how it is grouped with others; that is the consumer's responsibility. If the content truly belongs in one section, use the existing internal zones (`controls bar`, `toolbar`, `main content`). If it needs to be split into multiple sections, each section is its own independent template.
+
+---
+
+## Controls bar
+
+Always a `<div style="display: flex; gap: 0.5rem;">`. There are two main variants:
+
+**Search** — when the user filters over a list or table:
+```ts
+return BUI.html`
+  <bim-panel-section label="Elements">
+    <div style="display: flex; gap: 0.5rem;">
+      <bim-text-input @input=${onSearch} vertical placeholder="Search..."></bim-text-input>
+      <bim-button icon=${icons.ADD} @click=${onCreate}></bim-button>
+    </div>
+    ${table}
+  </bim-panel-section>
+`
+```
+
+**Selector** — when the user picks the active item from a dropdown. The gap is tighter (`0.25rem`) because the dropdown already takes most of the width:
+```ts
+return BUI.html`
+  <bim-panel-section label="Proposals">
+    <div style="display: flex; gap: 0.25rem;">
+      ${proposalsDropdown}
+      <bim-button icon=${icons.ADD} @click=${onCreate}></bim-button>
+    </div>
+    ${content}
+  </bim-panel-section>
+`
+```
+
+Action buttons in the controls bar are always icon-only (`icon=` without `label=`). The search `<bim-text-input>` always has `vertical` and `debounce="200"`.
+
+---
+
+## Status messages
+
+Conditional `<bim-label>` elements that appear between the controls and the content to communicate the state of the active item — warnings, confirmations, relevant info. Built as optional variables:
+
+```ts
+let statusMessage: BUI.TemplateResult | undefined
+if (item?.status === "sent") {
+  statusMessage = BUI.html`<bim-label>This item has been sent and can't be modified.</bim-label>`
+}
+
+return BUI.html`
+  <bim-panel-section label="...">
+    ${controls}
+    ${statusMessage}
+    ${content}
+  </bim-panel-section>
+`
+```
+
+---
+
+## Actions toolbar
+
+When there are many actions on the active item (more than 3-4 buttons), use `<bim-toolbar>` with `<bim-toolbar-section>` instead of a plain flex div. The toolbar goes after the status messages and before the main content:
+
+```ts
+const toolbar = BUI.html`
+  <bim-toolbar style="border: 1px solid var(--bim-ui_bg-contrast-20);">
+    <bim-toolbar-section>
+      ${addItemBtn}
+      <bim-button style="flex: 0" icon=${icons.SELECT} @click=${onSelect}></bim-button>
+      <bim-button style="flex: 0" icon=${icons.DELETE} @click=${onDelete}></bim-button>
+    </bim-toolbar-section>
+  </bim-toolbar>
+`
+```
+
+Buttons inside the toolbar always have `style="flex: 0"` to prevent them from stretching.
+
+---
+
+## Conditional content
+
+When the panel content changes completely based on state (e.g. "select something first" vs. showing data), assign to a variable before the `return`:
+
+```ts
+let content: BUI.TemplateResult
+if (hasSelection) {
+  content = BUI.html`<bim-table ...></bim-table>`
+} else {
+  content = BUI.html`<bim-label>Select an element to see its data.</bim-label>`
+}
+
+return BUI.html`
+  <bim-panel-section label="...">
+    ${controls}
+    ${content}
+  </bim-panel-section>
+`
+```

package/docs/update-grid-elements.md

@@ -0,0 +1,46 @@
+# Update Grid Elements
+
+## When to use
+
+`app.grid.updateComponent` pushes a state update to a specific named grid element. Use it when a BIM component event needs to refresh the state of a template-based section mounted in the grid.
+
+This is different from `uis.custom.get(...).updateInstances()` — that re-renders all instances of a UIManager template regardless of where they're mounted. `updateComponent` targets a **specific grid slot by name**, which makes it the right choice when the element lives in the grid and you want precise, typed control over what state it receives.
+
+---
+
+## API
+
+```ts
+app.grid.updateComponent[componentName](updatedState)
+```
+
+- **`componentName`** — the element name as declared in the `App` type (e.g. `"qtosSection"`)
+- **`updatedState`** — partial state; only the provided fields are merged
+
+The call is fully typed: the accepted state shape is inferred from the `{ComponentName}GridElement` type in `app.ts`.
+
+---
+
+## Where to call it
+
+In a setup file (`setups/{custom}.ts`), in response to a BIM component event:
+
+```ts
+// setups/qto-manager.ts
+export const qtoManager = (components: OBC.Components) => {
+  const app = getAppManager(components)
+  const qtoManager = components.get(QtoManager)
+
+  qtoManager.onResultsChanged.add((results) => {
+    app.grid.updateComponent["qtosSection"]({ results })
+  })
+}
+```
+
+Never call `updateComponent` from inside a template function — templates receive state passively and should not trigger updates themselves.
+
+---
+
+## Type safety
+
+Because `app.grid` is typed via the `App` type in `app.ts`, TypeScript knows which names are valid and what state shape each one accepts. Passing an unknown name or a mismatched state shape produces a type error at the call site.

package/docs/using-colors.md

@@ -0,0 +1,32 @@
+# Using Colors
+
+## `globals.ts` shape
+
+```ts
+export const colors = {
+  GREEN: "#00FF00",
+  SOFT_BLUE: "#5B8CFF",
+}
+```
+
+**Colors are always stored as full hex codes, including the `#`.** This is required because some systems (like the highlighter) use the string itself as a style identifier in addition to a color value.
+
+## Rules
+
+- No hardcoded inline colors — not in the highlighter, not in palettes, not in any component. Always imported from `globals.ts`.
+- Before adding a new color, check whether an existing one already works.
+
+## Example: highlighter
+
+```ts
+const highlighter = components.get(OBF.Highlighter)
+if (!highlighter.styles.has(colors.GREEN)) {
+  highlighter.styles.set(colors.GREEN, {
+    color: new THREE.Color(colors.GREEN),
+    renderedFaces: 1,
+    opacity: 1,
+    transparent: false,
+  })
+}
+highlighter.highlightByID(colors.GREEN, modelIdMap)
+```

package/docs/using-icons.md

@@ -0,0 +1,37 @@
+# Using Icons
+
+## Icon registry rules
+
+**All icons in a platform app must be declared in `globals.ts` and accessed through `AppManager`.** This is not optional.
+
+The flow is always:
+1. Declare the icon in `globals.ts` with a `UPPER_SNAKE_CASE` key
+2. `app.ts` — the `App` type's `icons` field is typed as `(keyof typeof icons)[]`, which means any new key added to the registry is automatically reflected in the type — no manual update needed per icon, but this field must be present in the `App` type
+3. Pass the registry to `app.init()` as `icons: appIcons`
+4. Access icons elsewhere via `app.icons.KEY_NAME` (always through `getAppManager(components)`)
+
+```ts
+// ✗ Forbidden — inline icon string anywhere in the app
+<bim-button icon="ic:round-warning"></bim-button>
+grid.layouts = { Viewer: { icon: "ic:round-warning", template: `...` } }
+
+// ✓ Correct — always via the registry
+const app = getAppManager(components)
+<bim-button icon=${app.icons.WARNING}></bim-button>
+grid.layouts = { Viewer: { icon: app.icons.WARNING, template: `...` } }
+```
+
+## Before adding a new icon
+
+Before declaring a new icon in `globals.ts`, check if an existing one in the registry already serves the purpose. Reuse an existing icon when it communicates the same intent — avoid registry bloat.
+
+If no existing icon fits, add it to `globals.ts` first — then use it through `app.icons`.
+
+## `globals.ts` shape
+
+```ts
+export const icons = {
+  WARNING: "ic:round-warning",
+  COLLISION: "fa7-solid:explosion",
+}
+```

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.0.1",
+  "version": "0.0.2",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,8 @@
     "dist",
     "src/cli/templates",
     "src/built-in",
+    "docs",
+    "AGENTS.md",
     "CONTEXT.md"
   ],
   "scripts": {

package/src/cli/templates/bim/CONTEXT.md

@@ -46,7 +46,7 @@ Always use `npm run dev` which runs `thatopen serve` under the hood.
 | `@thatopen/ui` | `BUI` | UI web components (`<bim-panel>`, `<bim-grid>`, etc.) |
 | `@thatopen/ui-obc` | `CUI` | Pre-built OBC UI tables (used by ModelsPanel) |
 | `three` | `THREE` | 3D rendering engine |
-| `thatopen-services` | `EngineServicesClient` | Platform API client + built-in components |
+| `@thatopen/services` | `EngineServicesClient` | Platform API client + built-in components |
 
 ## Architecture pattern
 
@@ -85,7 +85,7 @@ They are fetched, evaluated, and registered with the OBC component system.
 | **ScreenshotAnnotator** | Modal for annotating screenshots (arrows, text, freehand) via MarkerJS |
 
 **Full API reference**: Each component has detailed JSDoc with `@example` blocks in the
-`thatopen-services` package source (`src/built-in/index.ts`). Read that file for config
+`@thatopen/services` package source (`src/built-in/index.ts`). Read that file for config
 interfaces, method signatures, and code examples.
 
 ### Loading pattern
@@ -93,7 +93,7 @@ interfaces, method signatures, and code examples.
 Use `setup` to create the component system and load built-in components in one call:
 
 ```ts
-import { PlatformClient, AppManager, ViewportsManager } from "thatopen-services";
+import { PlatformClient, AppManager, ViewportsManager } from "@thatopen/services";
 
 const client = PlatformClient.fromPlatformContext();
 

package/src/cli/templates/bim/package.json

@@ -15,7 +15,7 @@
     "@thatopen/fragments": "~3.4.0",
     "@thatopen/ui": "~3.4.0",
     "@thatopen/ui-obc": "~3.4.0",
-    "thatopen-services": "file:../../../..",
+    "@thatopen/services": "file:../../../..",
     "three": "^0.182.0"
   },
   "devDependencies": {

package/src/cli/templates/bim/src/app.ts

@@ -1,6 +1,6 @@
 import * as OBC from "@thatopen/components";
 import * as BUI from "@thatopen/ui";
-import { AppManager } from "thatopen-services";
+import { AppManager } from "@thatopen/services";
 import { icons } from "./globals";
 import { AppInfoSectionGridElement, CloudRunnerSectionGridElement } from "./ui-components";
 

package/src/cli/templates/bim/src/bim-components/CloudRunner/index.ts

@@ -1,5 +1,5 @@
 import * as OBC from "@thatopen/components";
-import { AppManager } from "thatopen-services";
+import { AppManager } from "@thatopen/services";
 import { CloudRunnerStatus } from "./src";
 
 export class CloudRunner extends OBC.Component {

package/src/cli/templates/bim/src/main.ts

@@ -10,7 +10,7 @@ import {
   AppManager,
   ViewportsManager,
   UIManager,
-} from "thatopen-services";
+} from "@thatopen/services";
 
 import { getAppManager } from "./app";
 import { uiManager, cloudRunner, viewportsManager, getUIManager } from "./setups";

package/src/cli/templates/bim/src/setups/ui-manager.ts

@@ -1,6 +1,6 @@
 import * as OBC from "@thatopen/components";
 import * as BUI from "@thatopen/ui";
-import { UIManager } from "thatopen-services";
+import { UIManager } from "@thatopen/services";
 import {
   appInfoSectionTemplate,
   AppInfoSectionState,

package/src/cli/templates/bim/src/setups/viewports-manager.ts

@@ -1,5 +1,5 @@
 import * as OBC from "@thatopen/components";
-import { ViewportsManager } from "thatopen-services";
+import { ViewportsManager } from "@thatopen/services";
 
 export const viewportsManager = async (components: OBC.Components) => {
   const viewports = components.get(ViewportsManager);

package/src/cli/templates/cloud/CONTEXT.md

@@ -7,7 +7,7 @@ It runs on the server as a Node.js process, triggered via the platform API.
 
 - **Entry point**: `src/main.ts` — must export an `async function main()`.
 - **Parameter schema**: `declarations.json` — the list of parameters this component accepts. Bundled next to the code so the platform, the UI, and `thatopen run` know what to pass in.
-- **Build output**: `dist/bundle.js` — an IIFE built by Vite with `thatopen-services` externalized.
+- **Build output**: `dist/bundle.js` — an IIFE built by Vite with `@thatopen/services` externalized.
 - **Execution**: The platform (or `thatopen run` locally) wraps the bundle in an execution engine that provides globals and calls `main()`.
 
 ## Parameters (`declarations.json`)
@@ -57,7 +57,7 @@ npx thatopen local-server --port 5000    # Custom port
 Then in your app or test script:
 
 ```ts
-import { EngineServicesClient } from "thatopen-services";
+import { EngineServicesClient } from "@thatopen/services";
 
 const client = new EngineServicesClient(token, apiUrl, {
   localServerUrl: "http://localhost:4001",
@@ -89,7 +89,7 @@ Libraries like `@thatopen/components`, `three`, `web-ifc`, or Node's `fs` are **
 Already declared in `src/main.ts`. Keep them there for type checking:
 
 ```ts
-declare const thatOpenServices: import("thatopen-services").EngineServicesClient;
+declare const thatOpenServices: import("@thatopen/services").EngineServicesClient;
 declare const executionParams: Record<string, unknown>;
 declare const executionContext: {
   projectId?: string;
@@ -197,7 +197,7 @@ if (!hasPermission) {
 ## Build configuration
 
 - `vite.config.js` builds to IIFE format.
-- Only `thatopen-services` is externalized — the wrapper provides it at runtime via `require()`. Everything else (including any third-party npm dependency you install) is bundled into `dist/bundle.js`.
+- Only `@thatopen/services` is externalized — the wrapper provides it at runtime via `require()`. Everything else (including any third-party npm dependency you install) is bundled into `dist/bundle.js`.
 - The build output has a footer `var main = ThatOpenComponent.main;` so the engine can find the entry point as a top-level `main` variable.
 
 ## Configuration

package/src/cli/templates/cloud/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@thatopen/components": "~3.4.0",
-    "thatopen-services": "^{{VERSION}}",
+    "@thatopen/services": "^{{VERSION}}",
     "three": "^0.182.0"
   },
   "devDependencies": {

package/src/cli/templates/cloud/src/main.ts

@@ -22,7 +22,7 @@
 
 // Globals injected by the execution engine at runtime — keep these for type checking
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-declare const thatOpenServices: import("thatopen-services").EngineServicesClient;
+declare const thatOpenServices: import("@thatopen/services").EngineServicesClient;
 declare const executionParams: Record<string, unknown>;
 declare const executionContext: {
   projectId?: string;

package/src/cli/templates/cloud-test/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@thatopen/components": "~3.4.0",
-    "thatopen-services": "^{{VERSION}}",
+    "@thatopen/services": "^{{VERSION}}",
     "three": "^0.182.0"
   },
   "devDependencies": {

package/src/cli/templates/cloud-test/src/main.ts

@@ -3,7 +3,7 @@
 // Generated by: thatopen create --template cloud-test
 
 // Globals injected by the execution engine at runtime
-declare const thatOpenServices: import("thatopen-services").EngineServicesClient;
+declare const thatOpenServices: import("@thatopen/services").EngineServicesClient;
 declare const executionParams: Record<string, unknown>;
 declare const executionReporter: {
   message(msg: string): void;

package/src/cli/templates/default/CONTEXT.md

@@ -41,7 +41,7 @@ Always use `npm run dev` which runs `thatopen serve` under the hood.
 To add 3D BIM viewing, install the BIM dependencies:
 
 ```bash
-npm install @thatopen/components @thatopen/ui three thatopen-services
+npm install @thatopen/components @thatopen/ui three @thatopen/services
 ```
 
 Then follow the BIM app pattern:
@@ -53,7 +53,7 @@ import * as OBF from "@thatopen/components-front";
 import * as FRAGS from "@thatopen/fragments";
 import * as BUI from "@thatopen/ui";
 import * as CUI from "@thatopen/ui-obc";
-import { PlatformClient, AppManager, ViewportManager } from "thatopen-services";
+import { PlatformClient, AppManager, ViewportManager } from "@thatopen/services";
 
 const client = PlatformClient.fromPlatformContext();
 const { components } = await client.setup(
@@ -67,10 +67,10 @@ const { element, world } = await viewports.create();
 
 ## EngineServicesClient API
 
-If you install `thatopen-services`, you can make API calls:
+If you install `@thatopen/services`, you can make API calls:
 
 ```ts
-import { PlatformClient } from "thatopen-services";
+import { PlatformClient } from "@thatopen/services";
 
 const client = PlatformClient.fromPlatformContext();
 

package/src/cli/templates/default/package.json

@@ -8,6 +8,9 @@
     "login": "thatopen login --local",
     "publish": "thatopen publish"
   },
+  "dependencies": {
+    "@thatopen/services": "^{{VERSION}}"
+  },
   "devDependencies": {
     "typescript": "^5.2.0",
     "vite": "^5.2.0"

package/src/cli/templates/default/src/main.ts

@@ -10,11 +10,11 @@
 //   apiUrl      — base URL for the That Open API
 //
 // To add BIM capabilities (3D viewer, model loading), install:
-//   npm install @thatopen/components @thatopen/ui three thatopen-services
+//   npm install @thatopen/components @thatopen/ui three @thatopen/services
 // Then see the "bim" template for the full pattern.
 
-import { PlatformClient } from "thatopen-services";
-import type { ThatOpenContext, ProjectData } from "thatopen-services";
+import { PlatformClient } from "@thatopen/services";
+import type { ThatOpenContext, ProjectData } from "@thatopen/services";
 
 declare global {
   interface Window {

package/src/cli/templates/shared/AGENTS.md

@@ -0,0 +1,23 @@
+# Working on this That Open Platform project — Agent Guide
+
+You're an AI assistant helping build/extend this project (a BIM app or cloud component) on the
+That Open Platform. Read this first.
+
+## Rules (always apply)
+1. **All business logic lives in a BIM component** (`src/bim-components/`). `setups/` only wire;
+   `ui-components/` only render; `main.ts` only boots. New logic → a new (or existing) component.
+2. **Check engine components first** — `@thatopen/components` (`OBC`) / `@thatopen/components-front`
+   (`OBF`) — before building anything custom.
+3. **Propose a short plan and get the user's OK** before changing files.
+
+## Where the full build guides live
+The complete, up-to-date guides ship with the library. Read them from the installed package:
+- `node_modules/@thatopen/services/AGENTS.md` — the router; **start here**
+- `node_modules/@thatopen/services/docs/` — detailed guides (app wiring, layout, connecting logic
+  to UI, building BIM/UI components, cloud components, publishing, icons, colors, …)
+- `node_modules/@thatopen/services/CONTEXT.md` — library API reference (`PlatformClient` vs
+  `EngineServicesClient`, permissions)
+
+## This project
+- `CONTEXT.md` (this folder) — the context for *this specific* project.
+- `package.json` scripts — `npm run dev` (preview), `npm run login`, `npm run publish`.

package/src/cli/templates/shared/CLAUDE.md

@@ -0,0 +1 @@
+See [AGENTS.md](./AGENTS.md) for how to work on this project, the rules to follow, and where the full That Open Platform build guides live.

package/src/cli/templates/shared/cloud/vite.config.js

@@ -14,11 +14,11 @@ export default defineConfig({
     },
     outDir: 'dist',
     rollupOptions: {
-      // Only thatopen-services is externalized — the execution wrapper
-      // provides it at runtime via require('thatopen-services'). Every
+      // Only @thatopen/services is externalized — the execution wrapper
+      // provides it at runtime via require('@thatopen/services'). Every
       // other dependency (including @thatopen/components, three, web-ifc,
       // or any npm package you install) must be bundled into bundle.js.
-      external: ['thatopen-services'],
+      external: ['@thatopen/services'],
       output: {
         footer: 'var main = ThatOpenComponent.main;',
       },

package/src/cli/templates/test/package.json

@@ -14,7 +14,7 @@
     "@thatopen/fragments": "~3.4.0",
     "@thatopen/ui": "~3.4.0",
     "@thatopen/ui-obc": "~3.4.0",
-    "thatopen-services": "^{{VERSION}}",
+    "@thatopen/services": "^{{VERSION}}",
     "three": "^0.182.0"
   },
   "devDependencies": {

package/src/cli/templates/test/src/main.ts

@@ -12,8 +12,8 @@ import {
   PlatformClient,
   AppManager,
   ViewportManager,
-} from "thatopen-services";
-import type { ThatOpenContext } from "thatopen-services";
+} from "@thatopen/services";
+import type { ThatOpenContext } from "@thatopen/services";
 
 declare global {
   interface Window {