@thatopen/services 0.0.2 → 0.0.4

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

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

@@ -1,69 +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);
-```
+# 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

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

@@ -1,28 +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/`
+# 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/`