@thatopen/services 0.0.2 → 0.0.4

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

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