@thatopen/services 0.0.4 → 0.0.5

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

@@ -1,113 +0,0 @@
-# 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 +0,0 @@
-# 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 +0,0 @@
-# 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,71 +0,0 @@
-# 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 +0,0 @@
-# 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 +0,0 @@
-# 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.

package/docs/ui-components/data-table.md

@@ -1,185 +0,0 @@
-# Data Table
-
-> **Structural rule:** A `<bim-table>` always lives in its own dedicated UI component (e.g., `collisionsTable`, `elementsTable`). Never define a table inline inside another template such as a `panel-section`. The consuming template receives the table component as an external reference and composes it in.
-
-`BUI.Table<TData>` is the standard component for displaying tabular data. `TData` is a record type where each key is a column name and each value is the cell's data type.
-
-## Data Type
-
-Define a named type following the `{PascalCase(identifier)}Data` convention and export it from `src/types.ts`:
-
-```ts
-export type MyComponentTableData = {
-  Name: string
-  Count: number
-  Actions: string  // reserved for per-row interaction buttons
-}
-```
-
-`Actions: string` is the conventional column for per-row interaction buttons — typed as `string` (placeholder) and rendered via `dataTransform`.
-
-Column names follow a casing rule: **PascalCase** for columns displayed to the user (`Name`, `Count`), **camelCase** for internal data columns not meant to be shown (`id`, `modelId`).
-
-## Template
-
-The table element is created via `BUI.html` and configured imperatively once mounted using `BUI.ref`:
-
-```ts
-export const myTableTemplate: BUI.StatefullComponent<MyTableState> = ({ components }) => {
-  const onCreated = (e?: Element) => {
-    if (!e) return
-    const table = e as BUI.Table<MyTableData>
-    table.loadFunction = async () => {
-      // return BUI.TableGroupData<MyTableData>[]
-    }
-    table.loadData(true)
-  }
-
-  return BUI.html`
-    <bim-table ${BUI.ref(onCreated)}></bim-table>
-  `
-}
-```
-
-**For async data** — assign `loadFunction` and call `loadData()`. Passing `true` forces a fresh fetch. `loadData()` does nothing if data already exists — to re-trigger, first reset: `table.data = []`.
-
-**For synchronous data** — assign `table.data` directly:
-
-```ts
-table.data = items.map(item => ({ data: { Name: item.name, Count: item.count } }))
-```
-
-### Data Structure
-
-```ts
-{
-  data: { Name: "Juan", Count: 5 },  // required
-  children?: [...]                    // optional — nested rows
-}
-```
-
-The preferred pattern for hierarchical data is a **flat list combined with `groupedBy`**. Reserve `children` for fixed, explicit hierarchies.
-
-## Empty State
-
-```ts
-return BUI.html`
-  <bim-table ${BUI.ref(onCreated)}>
-    <div slot="missing-data" style="display: flex; flex-direction: column; align-items: center;">
-      <bim-label>No data loaded.</bim-label>
-      <bim-button @click=${() => table.loadData()} label="Load Data"></bim-button>
-    </div>
-  </bim-table>
-`
-```
-
-## Error State
-
-```ts
-return BUI.html`
-  <bim-table ${BUI.ref(onCreated)}>
-    <div slot="error-loading" style="display: flex; flex-direction: column; align-items: center;">
-      <bim-label data-table-element="error-message"></bim-label>
-      <bim-button @click=${() => table.loadData()} label="Try Again"></bim-button>
-    </div>
-  </bim-table>
-`
-```
-
-## Column Configuration and dataTransform
-
-Column layout, visibility, and `dataTransform` are fixed properties — configure them in `onInstanceCreated`, not in the template.
-
-```ts
-table.headersHidden = true
-table.noIndentation = true
-table.columns = [
-  "Name",
-  "Count",
-  { name: "Actions", width: "auto" },
-]
-table.groupedBy = ["Type"]
-table.preserveStructureOnFilter = true
-
-table.dataTransform = {
-  Name: (value) => BUI.html`<bim-label>${value}</bim-label>`,
-  Actions: (_, rowData) => {
-    const { id } = rowData
-    if (!id) return _
-    return BUI.html`<bim-button @click=${() => doSomething(id)}></bim-button>`
-  }
-}
-```
-
-> `noIndentation` and `groupedBy` are incompatible.
-
-**Column visibility:**
-```ts
-table.visibleColumns = ["Name", "Actions"]  // most columns hidden
-table.hiddenColumns = ["id", "extension"]   // most columns visible
-```
-
-> Everything rendered inside a table lives in the Shadow DOM. CSS classes cannot be applied — all styling must use inline styles.
-
-`rowData` can be mutated directly inside a transform:
-
-```ts
-table.dataTransform = {
-  LoadBearing: (value, rowData) => {
-    const onChange = (e: Event) => {
-      const input = e.target
-      if (!(input instanceof BUI.Checkbox)) return
-      rowData.LoadBearing = input.checked
-    }
-    return BUI.html`<bim-checkbox @change=${onChange} .checked=${value}></bim-checkbox>`
-  }
-}
-```
-
-## Grouping
-
-```ts
-table.groupedBy = ["Discipline", "State"]  // apply
-table.groupedBy = []                        // clear
-```
-
-`groupingTransform` maps column values to arrays defining multi-level hierarchy:
-
-```ts
-table.groupingTransform = {
-  State: (value) => {
-    if (value === "S0") return ["Work in Progress"]
-    if (value.includes(".")) return ["Shared States", parentState, value]
-    return ["Shared States", value]
-  }
-}
-```
-
-`BUI.Table.flattenData` flattens a nested group structure — useful for computing aggregate values:
-
-```ts
-const children = BUI.Table.flattenData(group.data.children)
-const total = children.reduce((sum, { data }) => sum + (Number(data.Count) || 0), 0)
-```
-
-## Row Events (rowcreated)
-
-```ts
-const rowHandlers = new WeakMap<Element, { handleClick: () => void }>()
-
-table.addEventListener("rowcreated", (e) => {
-  if (!("detail" in e)) return
-  const { row } = (e as { detail: BUI.RowCreatedEventDetail<MyTableData> }).detail
-
-  const existing = rowHandlers.get(row)
-  if (existing) row.removeEventListener("click", existing.handleClick)
-
-  const handleClick = () => {
-    if (!row.groupData?.data) return
-    const { Name } = row.groupData.data
-  }
-
-  rowHandlers.set(row, { handleClick })
-  row.addEventListener("click", handleClick)
-})
-```

package/docs/ui-components/display-text.md

@@ -1,39 +0,0 @@
-# Display Text
-
-Always use `<bim-label>` for all text content inside templates.
-
-## Static text
-
-```ts
-return BUI.html`<bim-label>Fixed text</bim-label>`
-```
-
-## Dynamic text (template interpolation)
-
-```ts
-return BUI.html`<bim-label>${someText}</bim-label>`
-```
-
-## Updating text imperatively
-
-Use `.textContent` to update a `bim-label` from outside the template. Never use `.label` — that property belongs to other components (`bim-button`, `bim-option`, etc.), not to `bim-label`:
-
-```ts
-const label = section.querySelector("bim-label")!
-label.textContent = "Updated text"  // ✓ correct
-label.label = "Updated text"        // ✗ avoid — .label is not a property of bim-label
-```
-
-## The label attribute belongs to other components
-
-`label` is an attribute/property of interactive components that display a text caption alongside an icon or control:
-
-```ts
-// ✓ correct — label attribute on button, option, etc.
-BUI.html`<bim-button label="Confirm"></bim-button>`
-BUI.html`<bim-option label="Model A"></bim-option>`
-BUI.html`<bim-text-input label="Name" vertical></bim-text-input>`
-
-// ✗ avoid — label is not a property of bim-label
-BUI.html`<bim-label label="Some text"></bim-label>`
-```

package/docs/ui-components/inline-form.md

@@ -1,44 +0,0 @@
-# Inline Form (Context Menu)
-
-To let the user create or edit an entity without leaving the current view, place a `<bim-panel-section fixed>` acting as a form inside a `contextMenuTemplate`. The form opens as a popup anchored to the trigger button.
-
-```ts
-const onBtnCreated = (e?: Element) => {
-  if (!e) return
-  const btn = e as BUI.Button
-  btn.contextMenuTemplate = () => {
-    const onSubmit = async ({ target }: { target: BUI.Button }) => {
-      const section = target.parentElement as BUI.PanelSection
-      section.valueTransform = {
-        name: (value: string) => value.trim(),
-        description: (value: string) => value.trim() || undefined,
-      }
-      const data = section.value as { name: string; description?: string }
-      target.loading = true
-      await doSomething(data)
-      target.loading = false
-      BUI.ContextMenu.removeMenus()
-    }
-
-    return BUI.html`
-      <bim-context-menu style="padding: 0; max-height: none;">
-        <bim-panel-section style="width: 16rem;" label="New Item" fixed>
-          <bim-text-input vertical name="name" label="Name"></bim-text-input>
-          <bim-text-input vertical name="description" type="area" label="Description"></bim-text-input>
-          <bim-button @click=${onSubmit} label="Create"></bim-button>
-        </bim-panel-section>
-      </bim-context-menu>
-    `
-  }
-}
-
-return BUI.html`<bim-button ${BUI.ref(onBtnCreated)} label="New Item"></bim-button>`
-```
-
-## Rules
-
-- `contextMenuTemplate` must be assigned via `BUI.ref`, never inline in `BUI.html`.
-- Inputs inside the form require the `name` attribute for `section.value` to pick them up.
-- The `<bim-panel-section>` acting as a form always has `fixed` so it can't be collapsed.
-- Use `section.valueTransform` to sanitize or coerce values before reading them.
-- Call `BUI.ContextMenu.removeMenus()` after a successful submit to close the popup.

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

@@ -1,24 +0,0 @@
-# Library Examples
-
-Before writing any BUI component implementation, check whether an official example covers the pattern you need. Official examples are the best starting point: they show correct usage of BUI elements, proper rendering patterns, and idiomatic API usage.
-
-## How to find an example
-
-1. Fetch the `paths.json` below. 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.
-
-Note that some components have multiple examples for different use cases — `Table` for instance has separate entries for `Searching`, `Grouping`, `ExportingData`, and `DataTransform`. Check all relevant ones.
-
----
-
-## Repository
-
-### engine_ui-components
-BUI primitives from `@thatopen/ui` — the `packages/core/` entries.
-
-- **paths.json**: `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/examples/paths.json`
-- **Base URL**: `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/`
-
-> The paths.json also contains entries under `packages/obc/` (OBC-connected tables and charts like `SpatialTree`, `ModelsList`, etc.). Those are also valid UI components — feel free to check them if the user needs that kind of structured data display.