mindoodb-app-sdk 0.0.59 → 0.0.61

package/README.md

@@ -391,6 +391,74 @@ session.onIncomingContent(async (content) => {
 
 Register the handler once, early. Haven waits for it before delivering, so a launch started for a delivery receives it as soon as the handler exists. `item.path` is relative (`assets/logo.png` inside a shared folder) and never absolute. What the app does with the content is up to the app. The returned `status` and `message` are shown to the user; a throwing handler counts as `rejected`. In tests, `createMockMindooDBAppSession().emitIncomingContent({ acceptId, items })` plays Haven's part.
 
+### Components: embedding another app's editor
+
+An app can offer an editor to other apps, and an app can show such an editor inside
+its own page — like an embedded control. TeamGrid offers its spreadsheet this way; a
+CRM shows it next to its own folder tree without knowing about TeamGrid beforehand.
+
+**Offering a component** (in `haven-app.json`):
+
+```json
+"components": [
+  {
+    "id": "sheet",
+    "label": { "en": "Spreadsheet", "de": "Tabelle" },
+    "icon": "icons/sheet.svg",
+    "intents": ["create", "edit", "view"],
+    "match": { "form": "teamgrid" },
+    "create": { "title": "" },
+    "children": { "linkField": "parentId", "match": { "type": "sheetChunk" } }
+  }
+]
+```
+
+`match` names the fields a root document carries; `children` (optional) says which
+documents belong to a root. When a host opens the component, Haven copies the root and
+its children into an in-memory sandbox and launches the app with that sandbox as its
+only database. The launch context then carries `embed` (`docId`, `databaseId`,
+`intent`, `hostAppLabel`): open that document, hide "New"/"Open", and finish with
+
+```ts
+await session.embedding.complete({ title }); // or session.embedding.cancel()
+```
+
+Haven writes every change back to the host's database as it happens and only lets the
+component create documents that are children of the root.
+
+**Embedding a component** (host app):
+
+```ts
+const [sheet] = await session.components.list({ intent: "create" });
+const doc = await db.documents.create({ set: { ...sheet.createFields, crm: { folders: ["Offers"] } } });
+const embed = await session.embeds.open({
+  componentKey: sheet.key,
+  databaseId: "crm",
+  docId: doc.id,
+  container: panel, // a positioned element; the component fills it
+});
+const closed = await embed.closed; // { reason: "completed" | "cancelled" | "closed" | "error", result? }
+```
+
+The SDK puts a frame into `container`, so the component is part of the host's page: it
+scrolls, clips and resizes with it, and the host's menus and dialogs cover it like any
+other element. The frame holds a page from Haven's origin that loads the component and
+hands its connection to Haven, so the host cannot reach into the component or its data
+channel. Haven tells the SDK where the container is (for the component's own menus);
+the SDK follows the container's size and position by itself.
+
+Havens that predate this lay the component over the container instead, above the host's
+frame (`embed.placement === "overlay"`). The host then cannot draw on top of it: hide it
+with `embed.setVisible(false)` while a menu or dialog of the host should be visible.
+Without a `container`, pass `rect` (in this app's viewport) and keep it current with
+`embed.setRect` to get that overlay explicitly.
+
+The first time a host embeds a component, Haven asks the user.
+In tests, `createMockMindooDBAppSession({ components })` records embeds
+(`listEmbeds`, `closeEmbed`), and the `/__haven-test/` page draws a stand-in with
+Done/Cancel buttons over the container. `createFakeBridgeHost({ embedFrameUrl })`
+answers like a current Haven, so the SDK frames that URL in the container.
+
 ### Databases and capabilities
 
 Each database mapped to your app carries a set of **capabilities** that Haven controls. Your app should check capabilities before attempting operations and adapt its UI accordingly.