@thatopen/services 0.0.1 → 0.0.2

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

@@ -0,0 +1,128 @@
+# Coding Conventions
+
+General coding conventions that apply across all BIM components.
+
+---
+
+## No shorthand property declaration in constructors
+
+Declare properties explicitly on the class body. Never use TypeScript's constructor shorthand (`public`, `private`, `readonly` parameter modifiers):
+
+```ts
+// ✗ Avoid
+constructor(public position: THREE.Vector3) {}
+
+// ✓ Correct
+position: THREE.Vector3;
+
+constructor(position: THREE.Vector3) {
+  this.position = position;
+}
+```
+
+---
+
+## Private member naming
+
+Private **properties** use an underscore prefix. Private **methods** do not:
+
+```ts
+// Properties — underscore prefix
+private _enabled = true;
+private _mesh: THREE.Mesh | null = null;
+
+// Methods — no prefix
+private setupEvents() { ... }
+private calculateResult() { ... }
+```
+
+---
+
+## Backing fields with getter/setter
+
+When a property needs to trigger side effects on assignment — firing an event, propagating a value to Three.js objects — use a private backing field with a public getter/setter:
+
+```ts
+private _visible = true;
+
+get visible() {
+  return this._visible;
+}
+
+set visible(value: boolean) {
+  this._visible = value;
+  for (const mesh of this._meshes) {
+    mesh.visible = value;
+  }
+  this.onStateChanged.trigger(["visible"]);
+}
+```
+
+---
+
+## Throw in late-initialization getters
+
+When a property only exists after `setup()` or another explicit initialization step, the getter throws a descriptive error rather than returning `undefined`. This makes the missing initialization obvious at the call site:
+
+```ts
+private _data: Data | null = null;
+
+get data() {
+  if (!this._data) {
+    throw new Error("ActivityTracker: call setup() before accessing data.");
+  }
+  return this._data;
+}
+```
+
+---
+
+## `interface` vs `type`
+
+Use `interface` for object shapes that may be extended or implemented by other classes. Use `type` for everything else — unions, primitive aliases, computed types, and tuples:
+
+```ts
+// ✓ interface — extendable object shape
+export interface ActivityConfig {
+  color: THREE.Color;
+  autoColorize: boolean;
+}
+
+// ✓ type — union
+export type ActivityStatus = "notStarted" | "inProgress" | "completed";
+
+// ✓ type — primitive alias
+export type ActivityId = string;
+
+// ✓ type — tuple / computed
+export type SerializedMap = [string, number[]][];
+```
+
+---
+
+## Prefer `DataMap` and `DataSet` over native `Map` and `Set`
+
+When storing collections inside a component, always use `FRAGS.DataMap` and `FRAGS.DataSet` instead of the native `Map` and `Set`. They have an identical API but additionally emit lifecycle events (`onItemSet`, `onBeforeDelete`, `onItemDeleted`) that other parts of the app can react to.
+
+See [`./observable-collections.md`](./observable-collections.md) for usage patterns.
+
+---
+
+## `async/await` over `.then()/.catch()`
+
+Always prefer `async/await` for asynchronous code. It is more readable and consistent with the rest of the codebase:
+
+```ts
+// ✗ Avoid
+this.loadModel(buffer).then((model) => {
+  this.process(model);
+}).catch((err) => {
+  console.error(err);
+});
+
+// ✓ Correct
+async loadAndProcess(buffer: ArrayBuffer) {
+  const model = await this.loadModel(buffer);
+  await this.process(model);
+}
+```

package/docs/bim-components/element-collections.md

@@ -0,0 +1,69 @@
+# Element Collections
+
+`OBC.ModelIdMap` is the only acceptable way to reference a collection of elements in a `FragmentsModel`. Any method that operates on items — highlighting, hiding, filtering, calculating — takes or returns a `ModelIdMap`.
+
+---
+
+## `OBC.ModelIdMap`
+
+Maps a model ID to a `Set` of local IDs:
+
+```ts
+// Shape: { [modelId: string]: Set<number> }
+const items: OBC.ModelIdMap = {
+  "model-a": new Set([1, 2, 3]),
+  "model-b": new Set([7, 8]),
+};
+
+// Iterating
+for (const [modelId, localIds] of Object.entries(items)) {
+  const model = fragments.list.get(modelId);
+  for (const localId of localIds) { ... }
+}
+```
+
+---
+
+## `OBC.ModelIdDataMap<T>`
+
+Associates data of type `T` per item — a `DataMap<string, DataMap<number, T>>`. Used when a component stores per-item state:
+
+```ts
+const progress: OBC.ModelIdDataMap<{ startDate: Date }> = new FRAGS.DataMap();
+
+// Write
+let byLocalId = progress.get("model-a");
+if (!byLocalId) {
+  byLocalId = new FRAGS.DataMap();
+  progress.set("model-a", byLocalId);
+}
+byLocalId.set(42, { startDate: new Date() });
+
+// Read
+const itemProgress = progress.get("model-a")?.get(42);
+```
+
+---
+
+## `OBC.ModelIdMapUtils`
+
+Static utility class for operating on `ModelIdMap` collections. Use it to combine, filter, compare, and serialize selections rather than implementing those operations manually:
+
+```ts
+import * as OBC from "@thatopen/components"
+
+// Combine two selections
+const combined = OBC.ModelIdMapUtils.join([selectionA, selectionB]);
+
+// Remove deselected items from current selection
+OBC.ModelIdMapUtils.remove(current, deselected);
+
+// Guard before processing
+if (OBC.ModelIdMapUtils.isEmpty(items)) return;
+
+// Serialize for storage (Set<number> → number[])
+const raw = OBC.ModelIdMapUtils.toRaw(items);
+
+// Restore from storage
+const restored = OBC.ModelIdMapUtils.fromRaw(raw);
+```

package/docs/bim-components/expose-events.md

@@ -0,0 +1,84 @@
+# Expose Events
+
+## `OBC.Event<T>`
+
+Events are declared as `readonly` properties on the class. The type parameter `T` defines the payload — use `undefined` when there's nothing to pass.
+
+Payload types are defined in `src/types.ts`, not inline, following the `{EventName}Payload` convention:
+
+```ts
+// src/types.ts
+export type OperationCompletedPayload = { result: CalculationResult }
+
+// index.ts
+readonly onOperationCompleted = new OBC.Event<OperationCompletedPayload>();
+```
+
+**Triggering** — always after the fact, once the operation or change is done:
+
+```ts
+this.onOperationCompleted.trigger({ result });
+this.onDisposed.trigger(undefined);
+```
+
+**Subscribing** — done externally by consumers:
+
+```ts
+const tracker = components.get(ActivityTracker);
+tracker.onOperationCompleted.add(({ result }) => { ... });
+```
+
+---
+
+## `onStateChanged` pattern
+
+When a component has several reactive properties, a single `onStateChanged` event with a union payload is cleaner than one event per property:
+
+```ts
+readonly onStateChanged = new OBC.Event<("enabled" | "color" | "mode")[]>();
+
+private _enabled = true;
+
+get enabled() {
+  return this._enabled;
+}
+
+set enabled(value: boolean) {
+  this._enabled = value;
+  this.onStateChanged.trigger(["enabled"]);
+}
+```
+
+Consumers can inspect the payload to react only to the properties they care about:
+
+```ts
+tracker.onStateChanged.add((changed) => {
+  if (changed.includes("color")) updateColorUI();
+});
+```
+
+---
+
+## `OBC.Eventable` and `EventManager`
+
+Any component that exposes events must implement `OBC.Eventable` and use `EventManager`. Register every event in the constructor and call `events.reset()` in `dispose()`:
+
+```ts
+export class ActivityTracker extends OBC.Component implements OBC.Eventable {
+  readonly onDisposed = new OBC.Event<undefined>();
+  readonly onStateChanged = new OBC.Event<string[]>();
+
+  readonly events = new OBC.EventManager();
+
+  constructor(components: OBC.Components) {
+    super(components);
+    components.add(ActivityTracker.uuid, this);
+    this.events.list.add(this.onDisposed);
+    this.events.list.add(this.onStateChanged);
+  }
+
+  dispose() {
+    this.events.reset();
+  }
+}
+```

package/docs/bim-components/library-examples.md

@@ -0,0 +1,28 @@
+# Library Examples
+
+Before writing any implementation that uses That Open Engine — whether you know the component name or are trying to figure out how to achieve something — check whether an official example covers it. Official examples are the best starting point: they show correct initialization sequences, idiomatic API usage, and working patterns from the source authors.
+
+## How to find an example
+
+1. Fetch the `paths.json` for each repo below (you can do all three in parallel). Do not summarize the response — retain the full JSON in context and use the descriptions to reason about which examples are relevant.
+2. Use the descriptions in the JSON to reason about which examples best match the user's intent. Prefer semantic matching over path name matching — a description may cover what the user needs even if the component name doesn't match exactly.
+3. Only proceed to fetch an example if its description confirms that it directly covers the user's intent, or that it can serve as a building block for composing a new custom component. Do not fetch speculatively.
+4. Construct the full URL: `{base_url}{path_entry}` and fetch the example file to use as your implementation reference.
+
+Path names are descriptive — `VisibilityOperations`, `EditElements`, `SteelDetailing` — so matching by intent works well even when the user hasn't named a specific component.
+
+---
+
+## Repositories
+
+### engine_components
+Components from `@thatopen/components` (OBC) and `@thatopen/components-front` (OBF).
+
+- **paths.json**: `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/examples/paths.json`
+- **Base URL**: `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/`
+
+### engine_fragment
+The `@thatopen/fragments` low-level library. There are no named OBC components here — users typically describe what they want to do (e.g., "edit model properties", "modify elements", "work with visibility").
+
+- **paths.json**: `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/examples/paths.json`
+- **Base URL**: `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/`

package/docs/bim-components/observable-collections.md

@@ -0,0 +1,83 @@
+# Observable Collections
+
+`FRAGS.DataMap` and `FRAGS.DataSet` are lifecycle-aware extensions of `Map` and `Set`. The only difference from their native counterparts is that they emit events when items are added or removed, making the collection observable.
+
+Use `DataMap` when there is a clear key to identify each item. Use `DataSet` when the item itself is the identifier. `DataMap` is the default choice in most cases.
+
+---
+
+## `FRAGS.DataMap<K, V>`
+
+### Declaration
+
+The primary collection of a component is conventionally named `list`:
+
+```ts
+import * as FRAGS from "@thatopen/fragments"
+
+readonly list = new FRAGS.DataMap<string, SpotElevation>();
+```
+
+### Reactive events
+
+```ts
+this.list.onItemSet.add(({ key, value }) => {
+  // called after an item is added
+});
+
+this.list.onBeforeDelete.add(({ key, value }) => {
+  // called before an item is removed — use to clean up resources
+});
+
+this.list.onItemDeleted.add(({ key }) => {
+  // called after an item is removed
+});
+```
+
+### Get-or-create
+
+When inserting into a `DataMap` where the entry may not exist yet, use a get-or-create pattern:
+
+```ts
+let entry = this.list.get(key);
+if (!entry) {
+  entry = new SpotElevation();
+  this.list.set(key, entry);
+}
+entry.doSomething();
+```
+
+### Guard
+
+A guard runs before every `set()` call and can block the insertion by returning `false`:
+
+```ts
+this.list.guard = (key, value) => {
+  return value.isValid;
+};
+```
+
+---
+
+## `FRAGS.DataSet<T>`
+
+Same API as `DataMap` but without keys — the item itself is the identifier:
+
+```ts
+readonly list = new FRAGS.DataSet<SpotElevation>();
+
+this.list.onItemSet.add(({ value }) => { ... });
+this.list.onBeforeDelete.add(({ value }) => { ... });
+```
+
+---
+
+## Collections of auxiliary class instances
+
+When a component manages instances of its own auxiliary classes, cleanup typically happens in `onBeforeDelete`:
+
+```ts
+this.list.onBeforeDelete.add(({ value: spotElevation }) => {
+  spotElevation.dispose();
+});
+```

package/docs/bim-components/overview.md

@@ -0,0 +1,160 @@
+# BIM Component Creation
+
+Architecture, patterns, and step-by-step guide for creating BIM components with That Open Engine (OBC/OBF) — the domain-logic layer that wraps fragments, IFC data, measurements, selections, or any non-UI behavior.
+
+## Working mode
+
+Before doing anything else, **read [`./library-examples.md`](./library-examples.md) and fetch the `paths.json` for both `engine_components` and `engine_fragment` in parallel.** Review all descriptions to understand what the engine already provides before forming any opinion about what needs to be built.
+
+Only after that, **propose an implementation plan and wait for the user's approval.**
+
+The proposal must describe:
+- Whether the need is covered by an existing engine component (consume via `components.get()`)
+- Whether existing components can be composed to cover it
+- Only if neither applies: which new component(s) will be created, what properties, events, and public methods it will expose, and whether it needs lifecycle, serialization, render loop, or interactive creation interfaces
+
+Only proceed with changes after the user explicitly confirms the plan. If the scope is unclear, ask first — do not assume.
+
+---
+
+## What is a BIM Component?
+
+That Open Engine is the collection of packages that power the app: `@thatopen/components`, `@thatopen/components-front`, `@thatopen/fragments`, `@thatopen/ui`, and `@thatopen/ui-obc`. BIM components are built on top of this ecosystem.
+
+A BIM component is a class that extends `OBC.Component` and encapsulates domain logic — IFC queries, calculations, data management, fragment operations, etc. It exposes that logic through a clean, event-driven interface that UI templates and other components can consume.
+
+### The engine works with Fragments
+
+That Open Engine does not work with IFC STEP files directly. It works with **Fragments** — an open binary format (`.frag`) built for performance: a 2 GB IFC file becomes ~80 MB, loads in seconds at 60fps in the browser.
+
+The runtime representation of a loaded model is a `FragmentsModel`. Its data schema usually mirrors the IFC SCHEMA (local IDs map to IFC express IDs, the spatial structure parallels IFC hierarchy, properties follow IFC attributes and relations), but it is not IFC STEP — it is Fragments. Any component that queries elements, reads properties, or operates on geometry works through the `FragmentsModel` API.
+
+For loading models, querying elements, or reading properties, fetch the relevant example from [`./library-examples.md`](./library-examples.md) before writing any implementation code.
+
+### When to create one
+
+Create a BIM component when custom domain logic is needed.
+
+After reviewing the `paths.json` descriptions fetched in the working mode step:
+
+- If an existing component covers the need → consume it via `this.components.get()` and fetch its example. Do not reimplement.
+- If existing components can be composed to cover it → compose them, fetching the relevant examples as building blocks.
+- Only if the need is genuinely not covered → propose creating a custom component.
+
+Custom components can themselves consume built-in components via `this.components.get()`, so examples remain useful even when building something new.
+
+---
+
+## Step 1 — Define the component
+
+Names should be short but descriptive. Use PascalCase for both folder and class, matching exactly:
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Folder | PascalCase | `ActivityTracker/` |
+| Class | PascalCase | `ActivityTracker` |
+| Types prefix | PascalCase matching class | `ActivityTrackerConfig`, `ActivityTrackerResult` |
+
+Use the `Manager` suffix when the component creates instances of something or governs a broad concern — consistent with `FragmentsManager`, `Classifier`, etc. For focused, single-responsibility components, omit it.
+
+---
+
+## Step 2 — Create the file structure
+
+```
+ActivityTracker/
+  index.ts        → class definition + re-exports ./src
+  src/
+    index.ts      → re-exports types and support files
+    types.ts      → interfaces, type aliases, enums
+    SpotElevation.ts → auxiliary class (if needed)
+```
+
+Only one class per component extends `OBC.Component` — the main one in `index.ts`. Any other classes the component defines or instantiates are plain TypeScript classes that live in `src/` alongside `types.ts`, and never extend `OBC.Component`.
+
+---
+
+## Step 3 — Implement the class in `index.ts`
+
+### Skeleton
+
+Every component needs a unique, hardcoded static UUID — a fixed string literal defined once and never changed. The constructor must call `super(components)` and register the instance with `components.add(UUID, this)` so it becomes globally retrievable via `components.get(ActivityTracker)`.
+
+Before writing the implementation, read [`./coding-conventions.md`](./coding-conventions.md) for naming rules, backing fields, and async patterns that apply throughout the class.
+
+```ts
+import * as OBC from "@thatopen/components"
+
+export class ActivityTracker extends OBC.Component {
+  static readonly uuid = "1b43361b-ef43-4207-9c40-dbed37bec0b6" as const;
+
+  enabled = true;
+
+  constructor(components: OBC.Components) {
+    super(components);
+    components.add(ActivityTracker.uuid, this);
+  }
+}
+
+export * from "./src"
+```
+
+### Interfaces
+
+OBC defines capability interfaces that components can implement to stay consistent with each other and with the engine. Pick the resource that matches your need:
+
+| I need... | Resource |
+|---|---|
+| Initialize the component with config, or clean up resources when it's destroyed | [`./setup-and-cleanup.md`](./setup-and-cleanup.md) |
+| Save and restore state across sessions | [`./save-and-restore-state.md`](./save-and-restore-state.md) |
+| Run logic on every frame of the render loop | [`./per-frame-updates.md`](./per-frame-updates.md) |
+| Implement a flow where the user creates objects in the scene step by step | [`./user-driven-object-creation.md`](./user-driven-object-creation.md) |
+| Expose events or react to state changes | [`./expose-events.md`](./expose-events.md) |
+
+### Accessing other components
+
+Resolve dependencies at call time — never store component instances as fields as it may create memory leaks:
+
+```ts
+const fragments = this.components.get(OBC.FragmentsManager);
+const highlighter = this.components.get(OBF.Highlighter);
+```
+
+---
+
+## Step 4 — Define types in `src/types.ts`
+
+Types are defined in parallel as the class needs them, not upfront. All typing for the component lives here — domain interfaces, event payloads, serialized types — so there is a single place to look.
+
+See [`./type-conventions.md`](./type-conventions.md) for common patterns (runtime vs serialized types, generics, etc.).
+
+---
+
+## Step 5 — Export from the barrel
+
+Re-export the component from the project's barrel index so it's accessible from a single import point:
+
+```ts
+export * from "./ActivityTracker"
+```
+
+---
+
+## Wiring up
+
+Instantiating the component and connecting it to engine events is not the component's responsibility — that belongs in external initialization code. The constructor should never call other components. See [`../app-wiring.md`](../app-wiring.md) for how this is done.
+
+---
+
+## See also
+
+- [`./library-examples.md`](./library-examples.md) — Find official usage examples and discover what the engine provides
+- [`./element-collections.md`](./element-collections.md) — Represent or combine element collections across components
+- [`./observable-collections.md`](./observable-collections.md) — Store component-internal data with reactive notifications
+- [`./expose-events.md`](./expose-events.md) — Expose events for other components or the UI to react to
+- [`./setup-and-cleanup.md`](./setup-and-cleanup.md) — Initialize the component with config or clean up resources on destroy
+- [`./save-and-restore-state.md`](./save-and-restore-state.md) — Persist and restore state across sessions
+- [`./per-frame-updates.md`](./per-frame-updates.md) — Run logic on every frame of the render loop
+- [`./user-driven-object-creation.md`](./user-driven-object-creation.md) — Let the user create objects in the scene step by step
+- [`./type-conventions.md`](./type-conventions.md) — Define component types (runtime vs serialized, generics)
+- [`./coding-conventions.md`](./coding-conventions.md) — Code conventions (naming, backing fields, async)

package/docs/bim-components/per-frame-updates.md

@@ -0,0 +1,20 @@
+# Per-Frame Updates
+
+## `OBC.Updateable`
+
+Implement when the component needs to execute logic on every frame — animating objects, polling state, updating visual feedback.
+
+```ts
+export class ActivityTracker extends OBC.Component implements OBC.Updateable {
+  readonly onBeforeUpdate = new OBC.Event<undefined>();
+  readonly onAfterUpdate = new OBC.Event<undefined>();
+
+  update(delta?: number) {
+    this.onBeforeUpdate.trigger(undefined);
+    // per-frame logic
+    this.onAfterUpdate.trigger(undefined);
+  }
+}
+```
+
+The component is driven externally — a world or a setup file calls `update()` each frame. The component never drives itself.

package/docs/bim-components/save-and-restore-state.md

@@ -0,0 +1,21 @@
+# Save and Restore State
+
+## `OBC.Serializable<D, S>`
+
+Implement when the component must persist its state — to a file, to the cloud, or across sessions.
+
+`D` is the runtime type, `S` is the serialized (JSON-safe) equivalent. Both are defined in `src/types.ts`. See [`./type-conventions.md`](./type-conventions.md) for the serialization patterns, including the `localId` → GUID conversion that must happen before storing any item references.
+
+```ts
+export class ActivityTracker extends OBC.Component
+  implements OBC.Serializable<ActivityTrackerData, SerializedActivityTrackerData> {
+
+  export(): SerializedActivityTrackerData {
+    // convert runtime state to JSON-safe structure
+  }
+
+  import(data: SerializedActivityTrackerData) {
+    // restore runtime state from serialized structure
+  }
+}
+```

package/docs/bim-components/setup-and-cleanup.md

@@ -0,0 +1,64 @@
+# Setup and Cleanup
+
+Two interfaces govern a component's lifecycle: `OBC.Configurable` for one-time initialization before use, and `OBC.Disposable` for cleanup when the component is destroyed.
+
+---
+
+## `OBC.Configurable<TManager, TConfig>`
+
+Implement when the component requires one-time initialization. This separates construction (cheap, no side effects) from setup (resolves dependencies, applies config, registers event listeners).
+
+```ts
+export interface ActivityTrackerConfig {
+  color: THREE.Color;
+  autoColorize: boolean;
+}
+
+export class ActivityTracker extends OBC.Component
+  implements OBC.Configurable<ActivityTrackerConfigManager, ActivityTrackerConfig> {
+
+  isSetup = false;
+  readonly onSetup = new OBC.Event<undefined>();
+
+  protected _defaultConfig: ActivityTrackerConfig = {
+    color: new THREE.Color("#6528d7"),
+    autoColorize: false,
+  };
+
+  setup(config?: Partial<ActivityTrackerConfig>) {
+    if (this.isSetup) return;
+    const fullConfig = { ...this._defaultConfig, ...config };
+    // apply config, resolve dependencies...
+    this.isSetup = true;
+    this.onSetup.trigger(undefined);
+  }
+}
+```
+
+The `if (this.isSetup) return` guard ensures setup only runs once. The constructor must never call other components — that belongs in `setup()`.
+
+---
+
+## `OBC.Disposable`
+
+Implement when the component holds resources that must be explicitly released — Three.js geometries and materials, event subscriptions to external components, workers.
+
+```ts
+export class ActivityTracker extends OBC.Component implements OBC.Disposable {
+  readonly onDisposed = new OBC.Event<undefined>();
+
+  dispose() {
+    // 1. Release Three.js resources
+    this._mesh?.geometry.dispose();
+    this._material.dispose();
+
+    // 2. Reset all events (if OBC.Eventable is also implemented)
+    this.events.reset();
+
+    // 3. Signal disposal — always last
+    this.onDisposed.trigger(undefined);
+  }
+}
+```
+
+`onDisposed` must be triggered at the end of `dispose()`, after all cleanup is done.