@thatopen/services 0.0.1 → 0.0.2

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

@@ -0,0 +1,185 @@
+# 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

@@ -0,0 +1,39 @@
+# 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

@@ -0,0 +1,44 @@
+# 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

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

package/docs/ui-components/overview.md

@@ -0,0 +1,194 @@
+# UI Component Creation
+
+Guides and best practices for creating UI components with That Open Engine (BUI/OBC) — panels, tables, dropdowns, buttons, inputs, or any visual element.
+
+## Working mode
+
+Before doing anything else, **read [`./library-examples.md`](./library-examples.md) and fetch the `paths.json` for `engine_ui-components` to understand what BUI components are already available.**
+
+Only after that, **propose an implementation plan and wait for the user's approval.**
+
+The proposal must describe:
+- Which templates will be created or modified
+- What state (`State`) each template will need
+- Whether any template needs an `onInstanceCreated` callback
+- Whether it composes other existing templates
+
+Only proceed with changes after the user explicitly confirms the plan. If the scope is unclear, ask first — do not assume.
+
+---
+
+## Creating a UI Component
+
+### Step 1 — Define the component name
+
+The component name is the source of truth. Everything else derives from it.
+
+Given a name like *Files Section* or *Models List*, the full naming cascade is:
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Folder | kebab-case | `files-section/`, `models-list/` |
+| Component identifier | camelCase | `filesSection`, `modelsList` |
+| Types prefix | PascalCase | `FilesSection`, `ModelsList` |
+| Template function | `{camelCase}Template` | `filesSectionTemplate` |
+| Callback | `on{PascalCase}Created` | `onFilesSectionCreated` |
+
+The identifier suffix describes what the component *is* from the consumer's perspective — typically the BUI element name:
+
+| Identifier | Root element |
+|---|---|
+| `filesSection` | `<bim-panel-section>` |
+| `collisionsTable` | `<bim-table>` |
+| `modelsDropdown` | `<bim-dropdown>` |
+| `actionsToolbar` | `<div>` |
+
+> **Exception:** `<bim-panel-section>` uses the suffix `*Section`, not `*PanelSection`.
+
+---
+
+### Step 2 — Create the file structure
+
+Each component lives in its own folder:
+
+```
+files-section/
+  index.ts        → template, onInstanceCreated (if needed), re-exports ./src
+  src/
+    index.ts      → re-exports types and support files
+    types.ts      → state types and any supporting types
+```
+
+The `src/` subfolder holds types and any support files the template needs — helpers, constants, sub-types, etc. If `index.ts` is growing too long, move the extra logic into `src/`.
+
+---
+
+### Step 3 — Define types in `src/types.ts`
+
+Every component needs at minimum these types:
+
+```ts
+import * as OBC from "@thatopen/components"
+import * as BUI from "@thatopen/ui"
+
+export interface FilesSectionState {
+  components: OBC.Components
+  // ...additional state
+}
+
+export type FilesSectionComponent = BUI.StatefullComponent<FilesSectionState>
+```
+
+- **`{ComponentName}State`** — the reactive state passed to the template on every render. Must always include `components: OBC.Components`.
+- **`{ComponentName}Component`** — type alias for `BUI.StatefullComponent<{ComponentName}State>`. Used to type the template function.
+
+Additional types depend on the component. For example, tables also need `{ComponentName}Data` — which must be a `type` alias, not an `interface`, as `BUI.Table<T>` requires a type alias:
+
+```ts
+// ✗ Avoid — interface does not satisfy BUI.Table<T>
+export interface MyTableData { Name: string }
+
+// ✓ Correct
+export type MyTableData = { Name: string }
+```
+
+#### `components` is the only entry point to the engine
+
+Inside a template, any engine component must be accessed via `components.get()`. State must never receive component instances directly:
+
+```ts
+// ✗ Avoid — receiving a component instance directly
+const myTemplate = (state: { highlighter: OBF.Highlighter }) => { ... }
+
+// ✓ Correct — access everything through components
+const myTemplate = ({ components }: FilesSectionState) => {
+  const highlighter = components.get(OBF.Highlighter)
+}
+```
+
+#### How much logic belongs in a template?
+
+In the ideal case, a template is a thin facade: it reads state from BIM components via `components.get()` and triggers actions on them — nothing more.
+
+In practice, some UI-level logic is fine to keep in the template:
+
+- **Local coordination** — passing data from one sub-component to another within the same section
+- **Transient UI state** — loading flags, intermediate form values before the user confirms
+- **Orchestration** — calling several BIM components in sequence for a single user action
+
+What doesn't belong in a template is **domain logic**: calculations, data transformations, business rules. If a template starts computing things beyond what's needed to render, that logic belongs in a BIM component instead.
+
+The guiding question: *does this logic exist because the UI needs it, or because the domain requires it?* If the domain requires it, move it to a BIM component. See [`../connect-logic-to-ui.md`](../connect-logic-to-ui.md) for how UI templates connect to BIM components.
+
+---
+
+### Step 4 — Implement the template in `index.ts`
+
+### Rules
+
+- **Always prefer BUI components over native HTML elements.** Before using `<select>`, `<input>`, `<button>`, `<dialog>`, etc., use the `paths.json` descriptions fetched in the working mode step to identify what's available. If you need the full list of available elements, fetch https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/packages/core/src/components/index.ts. Before implementing any BUI component, check [`./library-examples.md`](./library-examples.md) for an official example of the element you're working with — it's the best starting point for correct usage patterns. See [`./rendering-patterns.md`](./rendering-patterns.md) for general rendering patterns. For displaying and updating text dynamically, see [`./display-text.md`](./display-text.md).
+- **Never use `<table>`.** The only acceptable element for tabular data is `<bim-table>`. A `<bim-table>` must always be its own standalone UI component — never defined inline inside another template. The consuming template instantiates the table component and composes it in. See [`./data-table.md`](./data-table.md) for how to build a table component.
+- **For async actions** (loading states, async button handlers, etc.), see [`./async-actions.md`](./async-actions.md). **Before triggering a destructive or irreversible action**, always ask the user to confirm — see [`./confirmation-dialog.md`](./confirmation-dialog.md).
+- **Do not configure element properties inside the template** that a consumer might want to override after instantiation — they will be reset on every render. Use `onInstanceCreated` instead.
+- **Never nest sections.** If the user asks to group content, create independent templates — one per section. See [`./sections-layout.md`](./sections-layout.md).
+
+#### Template
+
+A `{ComponentName}Component` function that receives the current state and returns a `BUI.html` tagged template. Re-runs on every state update.
+
+```ts
+export const filesSectionTemplate: FilesSectionComponent = ({ components }) => {
+  return BUI.html`<bim-panel-section></bim-panel-section>`
+}
+```
+
+#### `onInstanceCreated` — one-time setup
+
+Called once when an instance is created. Use it for imperative, one-time configuration: event listeners, fixed element properties, etc. For building a create/edit form anchored to a button, see [`./inline-form.md`](./inline-form.md).
+
+Receives the tuple `[element, updateFn, componentUtils]`:
+
+- `element` — the created HTML element
+- `updateFn` — triggers a re-render with a partial state update
+- `componentUtils` — provides `getCurrentState()`, which always returns fresh state. Use it inside closures to avoid stale state captures:
+
+```ts
+export const onFilesSectionCreated = (
+  [section, update, { getCurrentState }]: [
+    BUI.PanelSection,
+    BUI.UpdateFunction<FilesSectionState>,
+    BUI.ComponentUtils<FilesSectionState>
+  ]
+) => {
+  section.addEventListener("click", () => {
+    const { components } = getCurrentState() // always fresh state
+    const highlighter = components.get(OBF.Highlighter)
+    // ...
+  })
+}
+```
+
+---
+
+### 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 "./files-section"
+```
+
+When planning a new UI component, **always consider breaking it into smaller, reusable templates** rather than building a single monolithic one. Discuss the granularity with the developer — but the default stance is to favor small, composable units.
+
+---
+
+## See also
+
+- [`./library-examples.md`](./library-examples.md) — Find official usage examples and discover what BUI provides
+- [`./data-table.md`](./data-table.md) — Display data in a table, load columns, group rows
+- [`./sections-layout.md`](./sections-layout.md) — Organize the layout of a panel section (zones, toolbar, status messages)
+- [`./inline-form.md`](./inline-form.md) — Create or edit an entity in a popup form anchored to a button
+- [`./confirmation-dialog.md`](./confirmation-dialog.md) — Ask for confirmation before a destructive or irreversible action
+- [`./async-actions.md`](./async-actions.md) — Handle an async action with loading state on a button
+- [`./rendering-patterns.md`](./rendering-patterns.md) — General rendering patterns (BUI.ref, requestUpdate, data-active)
+- [`./display-text.md`](./display-text.md) — Display text, update text dynamically, `bim-label` vs `.label`

package/docs/ui-components/rendering-patterns.md

@@ -0,0 +1,129 @@
+# Rendering Patterns
+
+Common patterns that apply across all BUI components.
+
+## Lit and LitElement
+
+All components in `@thatopen/ui` are Web Components built with [Lit](https://lit.dev/) and extend `LitElement`. Since `BUI.html` is Lit's `html` tagged template, the full Lit template syntax applies — property bindings, boolean attributes, event listeners, directives, etc.
+
+## requestUpdate()
+
+Reassigning a reactive property (like `table.data`) automatically schedules a re-render. **Mutating a property in place** does not — call `requestUpdate()` manually in those cases:
+
+```ts
+// Reassignment → automatic update
+table.data = newData
+
+// In-place mutation → manual update required
+table.data.push(newRow)
+table.requestUpdate()
+```
+
+## BUI.ref
+
+`BUI.ref(callback)` provides an imperative reference to an element inside a `BUI.html` template. The callback is called once the element is mounted in the DOM:
+
+```ts
+// Initialization
+const onTableCreated = (e?: Element) => {
+  if (!e) return
+  const table = e as BUI.Table<MyTableData>
+  table.loadFunction = async () => { ... }
+  table.loadData(true)
+}
+
+return BUI.html`<bim-table ${BUI.ref(onTableCreated)}></bim-table>`
+```
+
+```ts
+// Capture
+let input: BUI.TextInput | undefined
+
+const onInputCreated = (e?: Element) => {
+  if (!(e instanceof BUI.TextInput)) return
+  input = e
+}
+
+return BUI.html`
+  <bim-text-input ${BUI.ref(onInputCreated)}></bim-text-input>
+  <bim-button @click=${() => console.log(input?.value)}></bim-button>
+`
+```
+
+## Creating Elements
+
+When an element must be created imperatively outside of `BUI.html`, use `BUI.Component.create` instead of `document.createElement`:
+
+```ts
+// ✗ Avoid
+const button = document.createElement("bim-button")
+
+// ✓ Correct
+const button = BUI.Component.create(() => BUI.html`<bim-button label="Click me"></bim-button>`)
+```
+
+## Visual State with data-active
+
+Use `toggleAttribute("data-active")` to reflect an element's active/inactive state visually:
+
+```ts
+target.toggleAttribute("data-active")           // toggle
+target.toggleAttribute("data-active", true)     // force active
+target.toggleAttribute("data-active", false)    // force inactive
+```
+
+## Event Handlers
+
+```ts
+return BUI.html`
+  <bim-text-input @input=${onSearch}></bim-text-input>
+  <bim-button @click=${onClick}></bim-button>
+`
+```
+
+## BUI.Manager.newRandomId()
+
+Use when a template needs to associate DOM elements by ID. Since templates can be instantiated multiple times, hardcoded IDs would cause collisions:
+
+```ts
+const inputId = BUI.Manager.newRandomId()
+
+return BUI.html`
+  <label for=${inputId}>Name</label>
+  <input id=${inputId} type="text" />
+`
+```
+
+## Triggering re-renders from inside a template (update)
+
+`BUI.StatefullComponent` receives an optional second parameter `update`:
+
+```ts
+export const myTemplate: BUI.StatefullComponent<MyState> = (state, update) => {
+  const onAdd = () => {
+    doSomething()
+    update()              // re-render with same state
+    update({ count: 5 }) // re-render with partial state change
+  }
+}
+```
+
+Avoid calling `update` in response to changes that themselves trigger another `update` — this causes an infinite render loop.
+
+## Role-based rendering
+
+When content depends on a user role or any runtime condition, use an optional variable before the `return`:
+
+```ts
+let actionArea: BUI.TemplateResult | undefined
+if (userHasPermission) {
+  actionArea = BUI.html`<bim-button label="Run Action" @click=${onRun}></bim-button>`
+}
+
+return BUI.html`
+  <bim-panel-section label="...">
+    ${content}
+    ${actionArea}
+  </bim-panel-section>
+`
+```