@cplace/mcp-server 1.12.1 → 1.12.2

package/dist/plugins/core/widget-specifications/cf.cplace.lowCodeWidgetBuilder.embeddedWidget/_meta.json

@@ -0,0 +1,8 @@
+{
+  "tags": [
+    "low-code",
+    "container",
+    "dashboard"
+  ],
+  "requiredApp": "cf.cplace.lowCodeWidgetRenderer"
+}

package/dist/plugins/core/widget-specifications/cf.cplace.lowCodeWidgetBuilder.embeddedWidget/_overview.md

@@ -0,0 +1,44 @@
+## Overview
+
+This is the **bridge widget** between two different "widget" worlds in cplace. It does not render anything itself — it embeds an *author-built* low-code widget into a layout.
+
+There are two distinct concepts that share the word "widget":
+
+- **Layout widgets** (charts, tables, KPI tiles, this Embedded Widget) — platform/app widgets you place directly in a layout via `layout.define(...)`. They are what `cplace_list_widget_definitions` describes.
+- **Low-Code Widget Builder widgets** — self-contained custom HTML/CSS/JS widgets authored in the Widget Builder and stored as **pages** of type `cf.cplace.lowCodeWidget.widgetDefinition`. They are *not* layout widgets and do not appear in the layout widget catalog.
+
+The Embedded Widget is the **only** way to surface a Widget Builder widget on a page: you point it at a widget-definition page and it renders that widget's approved code. Build the widget itself in the **Low-Code Widget Builder** first; this widget just places the result.
+
+## When to Use This Widget
+
+- You have (or will build) a custom HTML/CSS/JS widget in the Widget Builder and need to show it on a page or dashboard.
+- You need interactivity and write-back beyond what `lowCodeText` (read-only computed HTML) or `lowCodeButton` (a single action) offer.
+
+If you only need a computed number or a small read-only HTML fragment, prefer the **Low-Code Text** widget inside a rich string instead — it is much lighter than authoring a full Widget Builder widget.
+
+## Operating Modes (data source)
+
+The embedded widget can either run its own baked-in data source or take one from the embedding layout:
+
+- **Self-contained** (the default): the widget uses the `search` configured on its own definition. Best for landing pages and dashboards that should always show the same scope.
+- **Embedding-page override**: the embedding layout supplies the data source, so the same widget renders data scoped to the host record. Best for detail widgets (e.g. KPI tiles on a record page). This is toggled by the `useDataSource` attribute.
+
+## Design Considerations
+
+- **Author and approve the widget first.** This widget references an existing widget-definition page; it cannot create one. Widget code follows a Draft → Pending Review → Approved workflow, and the *renderer* shows the **approved** code. A widget that only has draft code will not render its latest edits here — approve it first.
+- **App split.** Displaying an embedded widget requires the **Low-Code Widget Renderer** app; *authoring* widgets requires the **Low-Code Widget Builder** app. A workspace may have the Renderer without the Builder (display-only).
+- **Height.** Embedded low-code widgets render in an isolated frame; if content is clipped, increase the configured height (or use auto height where appropriate).
+
+## Common Pitfalls
+
+- **Confusing the two widget worlds.** Looking for a low-code widget in the layout catalog will fail — it lives as a `widgetDefinition` page. Use this Embedded Widget to bring it into a layout.
+- **Pointing at an unapproved widget.** Only approved widget code renders; recent draft edits will not appear until the widget is approved.
+- **Expecting the embedding context for free.** Whether the widget sees the host record's data depends on the `useDataSource` setting — decide it deliberately.
+
+## Related Widgets
+
+| Widget | When to use instead |
+|--------|---------------------|
+| **Low-Code Text** (`cf.cplace.lowCodeWidgets.lowCodeText`) | Read-only computed text/HTML inside a rich string — no custom JS or write-back needed |
+| **Low-Code Button** (`cf.cplace.lowCodeWidgets.lowCodeButton`) | A single user-triggered action, not a full custom widget |
+| **Text without Widget Frame** (`cf.cplace.demoWidgets.demoRichString`) | Styled static HTML, or a host container for the lighter low-code widgets |

package/dist/plugins/core/widget-specifications/cf.cplace.lowCodeWidgetBuilder.embeddedWidget/_summary.md

@@ -0,0 +1 @@
+Embeds an author-built Low-Code Widget Builder widget (a `cf.cplace.lowCodeWidget.widgetDefinition` page) into a layout. Use it to place a custom HTML/CSS/JS widget — built and approved in the Widget Builder — onto a page or dashboard.

package/dist/plugins/core/widget-specifications/cf.cplace.lowCodeWidgetBuilder.embeddedWidget/useDataSource.md

@@ -0,0 +1,7 @@
+**Semantic Clarification**: Controls *where the widget's data comes from* — its own search vs. the embedding layout's.
+
+**Valid Values**:
+- `false` (self-contained, the common default): the widget uses the `search` baked into its own definition. Best for landing pages and dashboards that always show the same scope.
+- `true` (embedding override): the embedding layout's data source supplies the widget's `pages`, so the same widget renders data scoped to the host record. Best for detail widgets (e.g. KPI tiles on a record page).
+
+**Note**: When `false`, a `VALID_INCOMPLETE` warning about the `selection` attribute is expected and harmless. When `true`, configure the layout's data source (`search` / `tableWidgetId` / `selection`) accordingly.

package/dist/plugins/core/widget-specifications/cf.cplace.lowCodeWidgetBuilder.embeddedWidget/widgetReference.md

@@ -0,0 +1,10 @@
+**Warning**: This is the UID of a widget-*definition* page, not a layout widget kind.
+
+**Correct Usage**: Pass the page UID (e.g. `page/abc123…`) of a `cf.cplace.lowCodeWidget.widgetDefinition` page — a widget built in the Low-Code Widget Builder. The Embedded Widget renders that page's **approved** code.
+
+**Workflow**:
+1. Build and approve the widget in the Low-Code Widget Builder (it is a page of type `cf.cplace.lowCodeWidget.widgetDefinition`).
+2. Find that page's UID.
+3. Use the UID here.
+
+**Note**: If only draft code exists, the latest edits will not render until the widget is approved.

package/dist/plugins/core/widget-specifications/cf.cplace.lowCodeWidgets.lowCodeButton/_overview.md

@@ -147,3 +147,6 @@ Often used as a connected data source for the Low-Code Button. The table widget
 
 ### Attribute Group Widgets
 Common embedding containers for Low-Code Button widgets, allowing the button to be positioned alongside other page content.
+
+### Low-Code Widget Builder (Embedded Widget)
+Consider the **Low-Code Widget Builder** instead when you need more than a single button — a full custom widget with its own HTML/CSS/JS, client-side interactivity, and write-back. Those widgets are authored in the Widget Builder (as `cf.cplace.lowCodeWidget.widgetDefinition` pages) and placed via the Embedded Widget (`cf.cplace.lowCodeWidgetBuilder.embeddedWidget`). The Low-Code Button remains the right choice for a single user-triggered action.

package/dist/plugins/core/widget-specifications/cf.cplace.lowCodeWidgets.lowCodeText/_overview.md

@@ -62,6 +62,7 @@ This widget can **only** be embedded inside rich string widgets. It cannot be pl
 - For user-triggered actions -- use the **Low-Code Button** instead
 - For standalone chart visualizations -- use **cplaceJS Highcharts** or **cplaceJS Line Chart**
 - For simple static text -- use the **Rich String** widget directly
+- For a full custom widget with its own HTML/CSS/JS, client interactivity, and write-back -- build it in the **Low-Code Widget Builder** and embed it via the Embedded Widget (`cf.cplace.lowCodeWidgetBuilder.embeddedWidget`). Low-Code Text is read-only computed HTML inside a rich string; the Widget Builder is the right tool when you need an interactive, self-contained widget.
 
 ### Script Execution Considerations
 - Scripts execute synchronously during page rendering and on every re-evaluation

package/dist/plugins/core/widget-specifications/cf.cplace.lowcode.ai.chatWidget/_overview.md

@@ -56,6 +56,7 @@ The widget can access pages from multiple sources: search queries, explicit sele
 |--------|---------------------|
 | **Citizen AI Streaming Chat** | Recommended for all new use cases - this is the replacement for the deprecated Chat Widget |
 | **Ask Your Page Widget** (`cf.cplace.citizenAi.askYourPageWidget`) | When you need simple, pre-configured "Ask Your Page" functionality without custom scripting |
+| **Low-Code Widget Builder** (Embedded Widget `cf.cplace.lowCodeWidgetBuilder.embeddedWidget`) | When you need a full custom HTML/CSS/JS widget with your own UI and write-back rather than a chat interface — author it in the Widget Builder and embed it. AI calls can still be made from the widget's server script via Citizen AI. |
 
 ## Related Patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplace/mcp-server",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "description": "MCP server that provides Claude Desktop with tools to interact with cplace APIs",
   "main": "dist/public-api.js",
   "types": "dist/public-api.d.ts",