@qaecy/cue-sdk 0.0.14 → 0.0.16

package/README.md

@@ -155,6 +155,17 @@ const data = await cue.api.sparql(
 );
 ```
 
+### `cue.api.language` / `cue.api.setLanguage(lang)`
+
+Active language used for language-sensitive SPARQL label queries (e.g. schema category labels and document text fields). Defaults to `'en'`. All project classes (`CueProjectSchema`, `CueProjectDocuments`, `CueProjectEntities`) read this shared value at query time.
+
+```typescript
+cue.api.setLanguage('da');
+console.log(cue.api.language); // 'da'
+```
+
+When using `CueProjectView`, prefer calling `view.setLanguage(lang)` — it updates `api.language` **and** reloads language-sensitive cached data (schema labels, document subjects/summaries) for the new language.
+
 ## Projects
 
 Manage Cue projects via `cue.api.projects` (`CueProjects`).
@@ -188,6 +199,34 @@ const project = await cue.api.projects.createProject({
 });
 ```
 
+## Entities
+
+Entity data for a project is accessed via a `CueProjectView`. Create a view with `cue.createProjectView(projectId)` and use `view.entities` (`CueProjectEntities`) for all entity-level operations.
+
+### `view.entities.buildSummaryGraph(format?)`
+
+Fetches a project-level summary of entity category relationships: how many times entities of one category point to entities of another via each predicate, ordered by descending occurrence count.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `format` | `'graph'` \| `'md'` \| `undefined` | `'graph'` returns structured nodes + edges (`SummaryGraphData`); `'md'` returns a compact aligned text table; omit for the raw SPARQL JSON result |
+
+```typescript
+// Structured graph — nodes and edges separated
+const g = await view.entities.buildSummaryGraph('graph');
+// g.entities  → [{ iri: 'https://…FloorPlanDrawing' }, …]
+// g.relations → [{ sourceID, predicate, targetID, weight }, …]
+
+// Compact markdown table
+const md = await view.entities.buildSummaryGraph('md');
+// qcy:FloorPlanDrawing -> qcy:includesBuildingEntity -> qcy:BuildingZone     (5652)
+// qcy:Activity         -> qcy:involvesBuildingEntity -> qcy:BuildingElement  (4003)
+// qcy:BuildingElement  -> qcy:elementHasMaterial     -> qcy:Material         (3551)
+
+// Raw SPARQL JSON result
+const raw = await view.entities.buildSummaryGraph();
+```
+
 ## Node.js — file sync
 
 For server-side or CLI use with file-sync capabilities, import from `@qaecy/cue-sdk/node`:
@@ -237,6 +276,118 @@ Returns a `SyncResult`:
 | `totalSize` | `number` | Total size across all files |
 | `rdfWritten` | `boolean` | Whether any RDF metadata was written |
 
+## GIS
+
+Reactive GIS service for querying spatial features within a map viewport. Accessed via the lazy getter `cue.gis` — the `CueGis` instance is created on first access and reused for the lifetime of the `Cue` object.
+
+The `js/cue-gis` library (gateway routing, adapters, OpenStreetMap, Matrikel, etc.) is **bundled inside the SDK** — no extra install needed.
+
+### Quick example
+
+```typescript
+const gis = cue.gis;
+
+// Set the active project (drives the Cue-authenticated data source)
+gis.setProjectId('my-project-id');
+
+// Subscribe to results
+const unsubCats = gis.onAvailableCategories((cats) => {
+  console.log('Available categories:', cats.map(c => c.label));
+});
+
+const unsubFeatures = gis.onFeaturesChange((featuresMap) => {
+  for (const [category, features] of featuresMap) {
+    console.log(`${category}: ${features.length} features`);
+  }
+});
+
+gis.onLoadingChange((loading) => console.log('Loading:', loading));
+
+// On every map pan/zoom (e.g. from a Mapbox moveend event):
+map.on('moveend', () => {
+  const b = map.getBounds();
+  gis.setBbox([b.getWest(), b.getSouth(), b.getEast(), b.getNorth()]);
+});
+
+// When the user toggles a category:
+gis.setSelectedCategories(new Set(['cadastre', 'building']));
+
+// Cleanup (e.g. on sign-out or component destroy):
+unsubCats();
+unsubFeatures();
+gis.destroy();
+```
+
+### `cue.gis.setProjectId(projectId)`
+
+Set the active project. Triggers a new query when a bbox is set. Pass `null` to clear.
+
+```typescript
+cue.gis.setProjectId('my-project-id');
+cue.gis.setProjectId(null); // clear
+```
+
+### `cue.gis.setBbox(bbox)`
+
+Set the current map viewport as `[west, south, east, north]` (WGS-84). Triggers a debounced query (1.5 s) to list available categories and reload selected features.
+
+```typescript
+cue.gis.setBbox([8.5, 47.3, 8.6, 47.4]);
+```
+
+### `cue.gis.setSelectedCategories(categories)`
+
+Replace the full set of selected categories. Features for newly selected categories are fetched immediately; deselected ones are dropped from the results.
+
+```typescript
+cue.gis.setSelectedCategories(new Set(['cadastre', 'building', 'greenspace']));
+```
+
+### `cue.gis.onAvailableCategories(callback)` → unsubscribe
+
+Subscribe to the list of feature-category descriptors available in the current viewport. Replays the current value immediately.
+
+```typescript
+const unsub = cue.gis.onAvailableCategories((cats) => {
+  // cats: GisCategoryDescriptor[]
+  renderCategoryPanel(cats);
+});
+```
+
+### `cue.gis.onFeaturesChange(callback)` → unsubscribe
+
+Subscribe to the live feature map (category → features). Replays the current value immediately.
+
+```typescript
+const unsub = cue.gis.onFeaturesChange((map) => {
+  // map: Map<FeatureCategory, GisFeature[]>
+  for (const [cat, features] of map) renderLayer(cat, features);
+});
+```
+
+### `cue.gis.onLoadingChange(callback)` → unsubscribe
+
+Subscribe to the global loading state. `true` while any query is in flight.
+
+```typescript
+const unsub = cue.gis.onLoadingChange((loading) => showSpinner(loading));
+```
+
+### `cue.gis.destroy()`
+
+Cancel all in-flight requests, clear all listeners, and reset internal state. Call on sign-out or component teardown.
+
+### Types
+
+| Type | Description |
+|---|---|
+| `GisBBox` | `[west, south, east, north]` — WGS-84 decimal degrees |
+| `FeatureCategory` | `'address' \| 'poi' \| 'railway' \| 'natural' \| 'manmade' \| 'cadastre' \| 'building' \| 'greenspace' \| 'paved' \| 'zone'` |
+| `GisCategoryDescriptor` | `{ category, label, description, preferredColor }` |
+| `GisFeature` | Full feature record with geometry, properties, tier, source info |
+| `GisFeaturesMap` | `Map<FeatureCategory, GisFeature[]>` |
+| `CueGis` | The class exposed via `cue.gis` |
+
 ## Advanced
 
 Access the raw Firebase `Auth` instance for advanced use cases: