@thatopen/services 0.0.2 → 0.0.3

package/docs/app-layout.md

@@ -1,139 +1,139 @@
-# Configure App Layout
-
-## Grid element constraint
-
-Every entry in `grid.elements` must be a single `bim-panel-section`. This is a hard constraint of the platform — the grid only knows how to host panel sections, not arbitrary HTML containers.
-
-**Correct:** one `grid.elements` entry = one `bim-panel-section`
-**Wrong:** a UI component that returns a `<div>` wrapping multiple `<bui-panel-section>` elements used as a grid entry
-
-If you need multiple sections in one area, register each section separately in `grid.elements` and group them using `panel:` or `tabs:` in the grid template — never wrap them in a container component.
-
-```ts
-// ✗ Wrong — MyDashboard returns <div><bui-panel-section>...</bui-panel-section><bui-panel-section>...</bui-panel-section></div>
-grid.elements = {
-  dashboard: { template: uis.custom.get("myDashboard").template, initialState: { components } },
-}
-
-// ✓ Correct — each section is its own grid element; grouping happens in the template
-grid.elements = {
-  stats:  { template: uis.custom.get("statsSection").template,  initialState: { components } },
-  charts: { template: uis.custom.get("chartsSection").template, initialState: { components } },
-}
-// Then in the layout template:
-// "panel:right(stats,charts) viewer" 1fr / 22rem 1fr
-```
-
----
-
-## Grid sync rules
-
-Any change to the grid requires updates in multiple places. Never update one without the others.
-
-**Adding or removing a layout:**
-1. `app.ts` → first argument of `BUI.Grid<[layouts], ...>`
-2. `main.ts` → `grid.layouts` (add/remove the definition) and `grid.layout` if it was the initial layout
-
-**Adding or removing an element:**
-1. `app.ts` → second argument of `BUI.Grid<..., [elements]>`
-2. `main.ts` → `grid.elements`, `grid.areaGroups` (if applicable), and any layout templates that reference it
-
-**Renaming an element** — the name originates in the component, so the change cascades outward:
-1. Rename the folder in `ui-components/` (kebab-case of the new name)
-2. Update all internal identifiers: types (`{ComponentName}State`, `{ComponentName}Component`, `{ComponentName}GridElement`), functions (`{camelCase}Template`, `on{PascalCase}Created`)
-3. Update the `ui-components/index.ts` barrel to point to the renamed folder
-4. `app.ts` → second argument of `BUI.Grid` reflects the new `{ComponentName}GridElement`
-5. `main.ts` → `grid.elements` and all layout templates that use that area name
-
----
-
-## Defining layouts
-
-```ts
-grid.layouts = {
-  Viewer: {
-    template: `"viewer" 1fr / 1fr`,
-  },
-  Quantities: {
-    icon: app.icons.QUANTITY,
-    template: `
-      "qtos viewer" 1fr
-      /40rem 1fr
-    `,
-  },
-}
-grid.layout = "Collider"
-```
-
----
-
-## Special area tokens
-
-```
-{groupType}:{areaName}(elementA, elementB)
-```
-
-There are two group types: `tabs` and `panel`.
-
-### `tabs:` — one element at a time
-
-Shows one element at a time with tab switchers. The user picks which section is visible. Supports nested sub-groups:
-
-```
-tabs:{areaName}({groupName}[elementA, elementB], elementC)
-```
-
-```ts
-Collider: {
-  icon: appIcons.COLLISION,
-  template: `
-    "tabs:left(group[collider,qtos],collider) viewer" 1fr
-    /30rem 1fr
-  `,
-}
-```
-
-`areaGroups` options for `tabs:`: `switchersCompact` or `switchersFull`.
-
-### `panel:` — all elements stacked vertically
-
-Stacks all elements and keeps them all visible simultaneously, scrollable as a single panel. Use when sections are related and should all be visible at once (e.g. an inspector with multiple info sections):
-
-```ts
-app: {
-  template: `
-    "tabs:left viewport panel:right" 1fr
-    / 22rem 1fr 20rem
-  `,
-}
-```
-
-`areaGroups` options for `panel:`: `label` to give the panel a title.
-
-### Choosing between `tabs:` and `panel:`
-
-- Use `tabs:` when sections are **alternatives** — the user focuses on one at a time
-- Use `panel:` when sections are **complementary** — the user needs all of them visible together
-
----
-
-## `grid.elements` and `grid.areaGroups`
-
-```ts
-grid.elements = {
-  viewer: viewport,
-  qtos: {
-    template: uis.custom.get("qtosSection").template,
-    initialState: { components },
-    label: "Quantities",
-  },
-}
-
-grid.areaGroups = {
-  left:  { switchersFull: true },
-  right: { label: "Inspector" },
-  group: { label: "Configuration", icon: appIcons.APPLY },
-}
-```
-
-> **Grouping sections always happens at the grid level.** To group, combine, or stack panel sections together, the answer is always `tabs:` or `panel:` in the grid template — never nesting one section inside another in the template code.
+# Configure App Layout
+
+## Grid element constraint
+
+Every entry in `grid.elements` must be a single `bim-panel-section`. This is a hard constraint of the platform — the grid only knows how to host panel sections, not arbitrary HTML containers.
+
+**Correct:** one `grid.elements` entry = one `bim-panel-section`
+**Wrong:** a UI component that returns a `<div>` wrapping multiple `<bui-panel-section>` elements used as a grid entry
+
+If you need multiple sections in one area, register each section separately in `grid.elements` and group them using `panel:` or `tabs:` in the grid template — never wrap them in a container component.
+
+```ts
+// ✗ Wrong — MyDashboard returns <div><bui-panel-section>...</bui-panel-section><bui-panel-section>...</bui-panel-section></div>
+grid.elements = {
+  dashboard: { template: uis.custom.get("myDashboard").template, initialState: { components } },
+}
+
+// ✓ Correct — each section is its own grid element; grouping happens in the template
+grid.elements = {
+  stats:  { template: uis.custom.get("statsSection").template,  initialState: { components } },
+  charts: { template: uis.custom.get("chartsSection").template, initialState: { components } },
+}
+// Then in the layout template:
+// "panel:right(stats,charts) viewer" 1fr / 22rem 1fr
+```
+
+---
+
+## Grid sync rules
+
+Any change to the grid requires updates in multiple places. Never update one without the others.
+
+**Adding or removing a layout:**
+1. `app.ts` → first argument of `BUI.Grid<[layouts], ...>`
+2. `main.ts` → `grid.layouts` (add/remove the definition) and `grid.layout` if it was the initial layout
+
+**Adding or removing an element:**
+1. `app.ts` → second argument of `BUI.Grid<..., [elements]>`
+2. `main.ts` → `grid.elements`, `grid.areaGroups` (if applicable), and any layout templates that reference it
+
+**Renaming an element** — the name originates in the component, so the change cascades outward:
+1. Rename the folder in `ui-components/` (kebab-case of the new name)
+2. Update all internal identifiers: types (`{ComponentName}State`, `{ComponentName}Component`, `{ComponentName}GridElement`), functions (`{camelCase}Template`, `on{PascalCase}Created`)
+3. Update the `ui-components/index.ts` barrel to point to the renamed folder
+4. `app.ts` → second argument of `BUI.Grid` reflects the new `{ComponentName}GridElement`
+5. `main.ts` → `grid.elements` and all layout templates that use that area name
+
+---
+
+## Defining layouts
+
+```ts
+grid.layouts = {
+  Viewer: {
+    template: `"viewer" 1fr / 1fr`,
+  },
+  Quantities: {
+    icon: app.icons.QUANTITY,
+    template: `
+      "qtos viewer" 1fr
+      /40rem 1fr
+    `,
+  },
+}
+grid.layout = "Collider"
+```
+
+---
+
+## Special area tokens
+
+```
+{groupType}:{areaName}(elementA, elementB)
+```
+
+There are two group types: `tabs` and `panel`.
+
+### `tabs:` — one element at a time
+
+Shows one element at a time with tab switchers. The user picks which section is visible. Supports nested sub-groups:
+
+```
+tabs:{areaName}({groupName}[elementA, elementB], elementC)
+```
+
+```ts
+Collider: {
+  icon: appIcons.COLLISION,
+  template: `
+    "tabs:left(group[collider,qtos],collider) viewer" 1fr
+    /30rem 1fr
+  `,
+}
+```
+
+`areaGroups` options for `tabs:`: `switchersCompact` or `switchersFull`.
+
+### `panel:` — all elements stacked vertically
+
+Stacks all elements and keeps them all visible simultaneously, scrollable as a single panel. Use when sections are related and should all be visible at once (e.g. an inspector with multiple info sections):
+
+```ts
+app: {
+  template: `
+    "tabs:left viewport panel:right" 1fr
+    / 22rem 1fr 20rem
+  `,
+}
+```
+
+`areaGroups` options for `panel:`: `label` to give the panel a title.
+
+### Choosing between `tabs:` and `panel:`
+
+- Use `tabs:` when sections are **alternatives** — the user focuses on one at a time
+- Use `panel:` when sections are **complementary** — the user needs all of them visible together
+
+---
+
+## `grid.elements` and `grid.areaGroups`
+
+```ts
+grid.elements = {
+  viewer: viewport,
+  qtos: {
+    template: uis.custom.get("qtosSection").template,
+    initialState: { components },
+    label: "Quantities",
+  },
+}
+
+grid.areaGroups = {
+  left:  { switchersFull: true },
+  right: { label: "Inspector" },
+  group: { label: "Configuration", icon: appIcons.APPLY },
+}
+```
+
+> **Grouping sections always happens at the grid level.** To group, combine, or stack panel sections together, the answer is always `tabs:` or `panel:` in the grid template — never nesting one section inside another in the template code.

package/docs/app-wiring.md

@@ -1,123 +1,123 @@
-# App Wiring
-
-## `app.ts` — App Identity
-
-Defines the app's typed shape and the typed accessor for `AppManager`. The `App` type uses `GridElement` types exported from `ui-components/`:
-
-```ts
-import * as OBC from "@thatopen/components"
-import * as BUI from "@thatopen/ui"
-import { AppManager } from "@thatopen/services"
-import { icons } from "./globals"
-import { FilesSectionGridElement, QtosSectionGridElement } from "./ui-components"
-
-export type App = {
-  icons: (keyof typeof icons)[]
-  grid: BUI.Grid<
-    ["Viewer", "Quantities", "Collider"],
-    [
-      "viewer",
-      FilesSectionGridElement,
-      QtosSectionGridElement,
-    ]
-  >
-}
-
-export const getAppManager = (components: OBC.Components) =>
-  components.get(AppManager<App>)
-```
-
-`getAppManager` is the **only** valid way to access `AppManager` in an app. Never use `components.get(AppManager)` directly — it drops the `App` type parameter and loses all type information about the app's icons, grid layout, and grid elements.
-
-```ts
-// ✗ Avoid — loses the App type
-const app = components.get(AppManager)
-
-// ✓ Correct — fully typed
-const app = getAppManager(components)
-```
-
-### Grid element types
-
-- Raw elements → typed as a string literal: `"viewer"`
-- Template-based sections → typed as `{ComponentName}GridElement`, defined in the component's `src/types.ts` and exported through `ui-components/index.ts`
-
-```ts
-// ui-components/files-section/src/types.ts
-export type FilesSectionGridElement = {
-  name: "filesSection"
-  state: FilesSectionState
-}
-```
-
----
-
-## `main.ts` — Entry Point
-
-`main.ts` boots the platform and calls `app.init()`. No business logic belongs here.
-
-```ts
-async function main() {
-  const client = EngineServicesClient.fromPlatformContext()
-
-  const { components } = await client.setup(
-    { OBC, OBF, BUI, CUI, THREE, FRAGS },
-    { uuid: ViewportsManager.uuid },
-    { uuid: AppManager.uuid },
-    { uuid: UIManager.uuid },
-  ) as { components: OBC.Components }
-
-  await viewportsManager(components)
-  const viewports = components.get(ViewportsManager)
-  // @ts-ignore
-  const { element: viewport } = [...viewports._instances.values()][0]
-
-  const app = getAppManager(components)
-  await app.init({
-    client,
-    icons: appIcons,
-    componentSetups: { ... },
-    grid: (grid) => { ... },
-  })
-}
-
-main().catch(console.error)
-```
-
-### `client.setup()` — Platform initialization
-
-- **First argument** — libraries object (`OBC`, `OBF`, `BUI`, `CUI`, `THREE`, `FRAGS`, etc.)
-- **Subsequent arguments** — `{ uuid }` for each platform built-in component needed. Always present: `ViewportsManager`, `AppManager`, `UIManager`
-
-Custom components (from `bim-components/`) do not need to be listed here — they self-register via `components.add()` in their constructor.
-
----
-
-## `componentSetups` in `app.init()`
-
-```ts
-componentSetups: {
-  core: [uiManager, fragmentsManager, highlighter, ifcLoader],
-  lazy: [
-    { uuid: MyComponent.uuid, fn: myComponentSetup },
-  ]
-}
-```
-
-**`core`** — runs before the grid mounts, in parallel. `uiManager` always goes here. Other engine component setups (fragments, highlighter, IFC loader) also typically go here.
-
-**`lazy`** — runs the first time the corresponding component is instantiated. The `uuid` is imported from the `bim-components/` barrel. Use for custom components that can be loaded on demand.
-
-The `uuid` of each custom component — a static property defined on the class — is imported from the `bim-components/` barrel when referencing it in `lazy`:
-
-```ts
-import { MyComponent } from "../bim-components"
-
-componentSetups: {
-  lazy: [
-    { uuid: MyComponent.uuid, fn: myComponentSetup },
-  ]
-}
-```
-
-When it's not obvious whether a custom component should be `core` or `lazy`, **decide based on whether the component is needed at boot or only on demand.**
+# App Wiring
+
+## `app.ts` — App Identity
+
+Defines the app's typed shape and the typed accessor for `AppManager`. The `App` type uses `GridElement` types exported from `ui-components/`:
+
+```ts
+import * as OBC from "@thatopen/components"
+import * as BUI from "@thatopen/ui"
+import { AppManager } from "@thatopen/services"
+import { icons } from "./globals"
+import { FilesSectionGridElement, QtosSectionGridElement } from "./ui-components"
+
+export type App = {
+  icons: (keyof typeof icons)[]
+  grid: BUI.Grid<
+    ["Viewer", "Quantities", "Collider"],
+    [
+      "viewer",
+      FilesSectionGridElement,
+      QtosSectionGridElement,
+    ]
+  >
+}
+
+export const getAppManager = (components: OBC.Components) =>
+  components.get(AppManager<App>)
+```
+
+`getAppManager` is the **only** valid way to access `AppManager` in an app. Never use `components.get(AppManager)` directly — it drops the `App` type parameter and loses all type information about the app's icons, grid layout, and grid elements.
+
+```ts
+// ✗ Avoid — loses the App type
+const app = components.get(AppManager)
+
+// ✓ Correct — fully typed
+const app = getAppManager(components)
+```
+
+### Grid element types
+
+- Raw elements → typed as a string literal: `"viewer"`
+- Template-based sections → typed as `{ComponentName}GridElement`, defined in the component's `src/types.ts` and exported through `ui-components/index.ts`
+
+```ts
+// ui-components/files-section/src/types.ts
+export type FilesSectionGridElement = {
+  name: "filesSection"
+  state: FilesSectionState
+}
+```
+
+---
+
+## `main.ts` — Entry Point
+
+`main.ts` boots the platform and calls `app.init()`. No business logic belongs here.
+
+```ts
+async function main() {
+  const client = EngineServicesClient.fromPlatformContext()
+
+  const { components } = await client.setup(
+    { OBC, OBF, BUI, CUI, THREE, FRAGS },
+    { uuid: ViewportsManager.uuid },
+    { uuid: AppManager.uuid },
+    { uuid: UIManager.uuid },
+  ) as { components: OBC.Components }
+
+  await viewportsManager(components)
+  const viewports = components.get(ViewportsManager)
+  // @ts-ignore
+  const { element: viewport } = [...viewports._instances.values()][0]
+
+  const app = getAppManager(components)
+  await app.init({
+    client,
+    icons: appIcons,
+    componentSetups: { ... },
+    grid: (grid) => { ... },
+  })
+}
+
+main().catch(console.error)
+```
+
+### `client.setup()` — Platform initialization
+
+- **First argument** — libraries object (`OBC`, `OBF`, `BUI`, `CUI`, `THREE`, `FRAGS`, etc.)
+- **Subsequent arguments** — `{ uuid }` for each platform built-in component needed. Always present: `ViewportsManager`, `AppManager`, `UIManager`
+
+Custom components (from `bim-components/`) do not need to be listed here — they self-register via `components.add()` in their constructor.
+
+---
+
+## `componentSetups` in `app.init()`
+
+```ts
+componentSetups: {
+  core: [uiManager, fragmentsManager, highlighter, ifcLoader],
+  lazy: [
+    { uuid: MyComponent.uuid, fn: myComponentSetup },
+  ]
+}
+```
+
+**`core`** — runs before the grid mounts, in parallel. `uiManager` always goes here. Other engine component setups (fragments, highlighter, IFC loader) also typically go here.
+
+**`lazy`** — runs the first time the corresponding component is instantiated. The `uuid` is imported from the `bim-components/` barrel. Use for custom components that can be loaded on demand.
+
+The `uuid` of each custom component — a static property defined on the class — is imported from the `bim-components/` barrel when referencing it in `lazy`:
+
+```ts
+import { MyComponent } from "../bim-components"
+
+componentSetups: {
+  lazy: [
+    { uuid: MyComponent.uuid, fn: myComponentSetup },
+  ]
+}
+```
+
+When it's not obvious whether a custom component should be `core` or `lazy`, **decide based on whether the component is needed at boot or only on demand.**