renderer-package 1.2.32

package/HOST.md

@@ -0,0 +1,37 @@
+# Host integration (quick reference)
+
+Full guide: **[HOST_INTEGRATION.md](HOST_INTEGRATION.md)** (scoped root, **`normalizeWorkflowFormToRendererSchema`** before BFF payloads, styles import).
+
+Wrap **`FormRenderer`** with **`FORM_RENDERER_ROOT_CLASS`** (`'iq-fbr'`):
+
+```tsx
+import {
+  FormRenderer,
+  FORM_RENDERER_ROOT_CLASS,
+  FORM_RENDERER_GRID_ROW_HEIGHT_DEFAULT,
+} from 'iq-line-form-builder-renderer';
+
+<div className={FORM_RENDERER_ROOT_CLASS}>
+  <FormRenderer
+    schema={schema}
+    gridLayout={{
+      rowHeight: FORM_RENDERER_GRID_ROW_HEIGHT_DEFAULT,
+    }}
+  />
+</div>
+```
+
+- **No host-wide global CSS is required** for grid placement: wrap with `.iq-fbr`, optionally `import 'iq-line-form-builder-renderer/styles'`.
+- **`FORM_RENDERER_GRID_ROW_HEIGHT_DEFAULT`** matches default grid row tracks (`95px`).
+
+## Page widgets (`week_calendar` / `detail_card`)
+
+Generic dashboard widgets (not attendance-specific). Wire them with **`set_context`** so a click writes keys such as `selectedEventId` into page context. Sibling widgets refetch via `dataSource.requireContextKeys` and `requestBindings`.
+
+- Widget API query params use **backend** placeholders: `{selectedEventId}` or `{ctx:selectedEventId}`.
+- In-page href templates use **`{{selectedEventId}}`**.
+- Layout: existing `columns` (e.g. 70/30) with `week_calendar` and `detail_card`. Do not extend layout `card` for record details.
+
+## Button fields (`button` / `editButton`)
+
+In grid layout, **`button`** and **`editButton`** default to **intrinsic width** unless **`appearance`** sets width (`widthMode: 'full'`, `widthPercent`, etc.). For full-width, set **`appearance.widthMode: 'full'`** or **`appearance.widthPercent: 100`**. In tall / row-spanned cells, vertical default is **`start`**; use **`appearance.verticalAlign: 'stretch'`** to fill cell height.

package/HOST_INTEGRATION.md

@@ -0,0 +1,72 @@
+# Host integration
+
+## Scoped root (required)
+
+Wrap **`FormRenderer`** with a container using **`FORM_RENDERER_ROOT_CLASS`** (`'iq-fbr'`) so bundled layout and CSS stay scoped under `.iq-fbr`. The package does not rely on global `body` / `html` / `*` rules.
+
+```tsx
+import {
+  FormRenderer,
+  FORM_RENDERER_ROOT_CLASS,
+  normalizeWorkflowFormToRendererSchema,
+} from 'iq-line-form-builder-renderer';
+
+const schema = normalizeWorkflowFormToRendererSchema(rawSchemaFromBff);
+
+<div className={FORM_RENDERER_ROOT_CLASS}>
+  <FormRenderer schema={schema} />
+</div>
+```
+
+Optional global tokens/components for default visuals:
+
+```ts
+import 'iq-line-form-builder-renderer/styles';
+```
+
+## Prefer normalization before `FormRenderer`
+
+When the payload comes from a **BFF or workflow API** (field rows with `fieldKey`, `fieldType`, `positionRow`, string `metadata`, etc.), call **`normalizeWorkflowFormToRendererSchema`** before passing the schema to **`FormRenderer`**.
+
+**`FormRenderer` already runs this normalizer internally**, so plain Studio-shaped schemas still behave as before. Calling the helper yourself is recommended when your host currently duplicates mapping logic (synonyms, metadata merge, appearance), so Studio preview, sms-frontend, and this package share one code path and you can delete duplicate mappers over time.
+
+The normalizer:
+
+- Maps **`fieldType` → `type`**, **`fieldKey` → `name`**, and **`positionRow` / `positionColumn` / `positionWidth` / `positionRowSpan`** (and related API keys) into **`position.order` / `column` / `columnSpan` / `rowSpan`** (aligned with workflow runtime mapping).
+- Merges parsed **`metadata`** and **`apidata`** into **`properties`** (existing **`properties` win**).
+- Preserves top-level **`appearance`** and deep-merges **`metadata.appearance`** and legacy flat metadata keys (**`hideLabel`**, **`contentAlign`**, etc.) only where the authoritative **`appearance`** does not already define a key.
+
+It does **not** rewrite workflow **rule** payloads or **`conditionExpression`** shapes (FormRenderer and workflow helpers still attach **conditions** from rules). It does **not** rebuild **table** parent/column graphs (see `backendToFormSchema` / your backend loader).
+
+## Form-level sections (`config.sections`)
+
+SMS Studio can define logical sections on the root grid (not the `section` field type): `id`, `name`, `fieldNames`, `showBorder`, optional `collapsible` / `defaultCollapsed`, and optional `heading` (`template`, `mode: fixed|increment`, `headingFieldName`).
+
+- **Expand/collapse**: when `showBorder: true` and `collapsible: true`, each section instance (block 0 and each Add More block) shows a chevron header; `defaultCollapsed: true` starts collapsed. Field values remain in the store when collapsed (submit unchanged).
+- **Add More** `linkedSectionIds` expands each section’s `fieldNames` into the clone set (union with `linkedFieldNames`, deduped by name). Synthetic values still use `{base}__addmore__{addMore}__{blockId}`.
+- **Headings**: block 0 may override a root `sectionHeading` when `headingFieldName` matches; additional Add More blocks render a dedicated heading from `heading.template` (they do **not** clone `sectionHeading`).
+- **`mode: increment`**: `{n}` in the template is replaced with the 1-based block index (default row = 1; first Add More block = 2).
+- **`mode: fixed`**: template is shown as-is (optional `{n}` is not substituted unless you use increment mode).
+- **Prepopulate**: `addMoreFieldKeyMap` still maps **base** field names only; no new keys for section expansion.
+- Schemas without `config.sections` are unchanged.
+
+## Grid row height
+
+Align designer row tracks with the renderer using `schema.config.grid` / `gridLayout.rowHeight`, or import **`FORM_RENDERER_GRID_ROW_HEIGHT_DEFAULT`** (`95px`) so defaults stay in sync.
+
+## Grid cell sizing (Studio parity)
+
+SMS Studio persists **`appearance.widthPercent`** (integer **1–100**) as a fraction of the **grid cell** width. The field shell applies **`width: N%` / `maxWidth: 100%`**; when width is under 100%, **`contentAlign: 'center'`** uses **`mx-auto`** and **`'end'`** uses **`ml-auto`** on that shell (**`start`** / **`stretch`** / unset: no extra horizontal margin). Legacy payloads may include **`heightPercent`** in metadata; the renderer **does not apply** it (Studio has no height-% UI). Use **`normalizeWorkflowFormToRendererSchema`** so metadata **`widthPercent`** lands on **`appearance`**.
+
+## Page widgets (`week_calendar` / `detail_card`)
+
+These are **PageRenderer** widgets, not form fields. Compose them in a `columns` layout.
+
+- Calendar click writes page context via **`set_context`** (typical keys: `selectedEventId`, `selectedEvent`, `week_start`).
+- Detail (and table/stat) widgets skip fetch until **`dataSource.requireContextKeys`** are set.
+- Widget HTTP query values use backend placeholders **`{selectedEventId}`** / **`{ctx:selectedEventId}`**. In-page hrefs use **`{{selectedEventId}}`**.
+- `set_context` is handled inside the renderer; hosts do not need to implement it in `onAction`.
+
+## Button fields (`button` / `editButton`)
+
+In grid layout, these default to **intrinsic width** unless **`appearance`** sets width explicitly (`widthMode`, `widthPercent`). Set **`appearance.contentAlign: 'stretch'`** (or **`horizontalAlign: 'stretch'`**; Studio uses lowercase) so the control fills the **full width** of the grid cell on the cross-axis, matching the designer. Default vertical placement in tall cells is **`start`** unless **`verticalAlign`** is set (e.g. **`stretch`** to fill height). See **[HOST.md](HOST.md)** for the short reference.