## 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 |