@meshmakers/octo-ui 3.4.1450 → 3.4.1490

package/README.md

@@ -137,6 +137,7 @@ export class CustomerDataSourceDirective extends OctoGraphQlDataSource<CustomerD
 | `FieldFilterEditorComponent` | Visual filter editor for queries |
 | `EntityIdInfoComponent` | Entity ID display with copy-to-clipboard dropdown |
 | `OctoLoaderComponent` | Animated OctoMesh logo loading indicator |
+| `PageComponent` (`MM_PAGE`) | `<mm-page>` page layout: optional header (title, subtitle, actions) + scrolling content, no footer |
 
 ## Available Services
 
@@ -207,6 +208,113 @@ See [`src/lib/branding/BRANDING_USAGE.md`](./src/lib/branding/BRANDING_USAGE.md)
 for the full list of CSS variables the library updates and the host-app
 contract for the surface ladder.
 
+## Page layout (`mm-page`)
+
+`<mm-page>` (`PageComponent`) is the token-based page frame that replaces the
+LCARS header / content panel / footer triple: an optional header (title,
+subtitle, `[mmPageActions]`) and a scrolling content area, no footer. Import
+`MM_PAGE` (component + slot directives); the title defaults to heading level 2
+and the header is a plain `<div>`. See
+[`src/lib/page/README.md`](./src/lib/page/README.md).
+
+```html
+<mm-page pageTitle="Adapters" pageSubtitle="12 registered">
+  <div mmPageActions><button kendoButton themeColor="primary">New adapter</button></div>
+  <mm-list-view …></mm-list-view>
+</mm-page>
+```
+
+## Theme tokens (overridable CSS variables)
+
+`@include octo.theme()` emits the "Deep Sea" token set on `:root` (dark
+default, light via `prefers-color-scheme` or `data-theme="light"`); source:
+`src/lib/runtime-browser/styles/_theme.scss`. Hosts may override any of these
+custom properties after the include. All `--theme-*` names of the former
+theme are kept; tokens marked *new* were added in AB#5519.
+
+| Group | Tokens |
+|---|---|
+| Surfaces | `--theme-bg-app`, `--theme-bg-app-end`, `--theme-bg-surface`, `--theme-bg-elevated`, `--theme-bg-overlay`, `--theme-bg-input`, *new:* `--theme-bg-sunken`, `--theme-bg-selected`, `--theme-bg-hover` |
+| Text | `--theme-text-primary`, `--theme-text-secondary`, `--theme-text-muted`, `--theme-text-on-accent`, `--theme-text-accent`, *new:* `--theme-text-code` |
+| Borders | `--theme-border-subtle`, `--theme-border-strong`, `--theme-border-divider` (= subtle), *new:* `--theme-border-default`, `--theme-focus-ring` (a `box-shadow` value) |
+| Accent / AI (*new*) | `--theme-accent`, `--theme-accent-hover`, `--theme-accent-subtle`, `--theme-accent-2`, `--theme-ai`, `--theme-ai-subtle` |
+| Status | `--theme-status-success`, `-warning`, `-error`, `-info`, *new:* `--theme-status-neutral`, `--theme-status-{success,warning,error,info,neutral}-subtle` |
+| Effects | `--theme-shadow-panel`, `--theme-shadow-popup`; `--theme-glow-primary`, `--theme-glow-accent` (both `none`); `--theme-gradient-page`, `--theme-gradient-header`, `--theme-accent-bar`, `--theme-accent-line`, `--theme-panel-rule` (now flat colours) |
+| Charts | `--theme-chart-1` … `--theme-chart-8` |
+| Ink overlays | `--theme-ink-02` … `--theme-ink-70` (text colour at n % — flips with the theme) |
+| Typography (*new*, theme-invariant) | `--theme-font-display` (Montserrat), `--theme-font-ui` (Roboto), `--theme-font-mono` (Roboto Mono) |
+| Spacing (*new*) | `--theme-space-1` … `--theme-space-8` (4 px grid: 4, 8, 12, 16, 20, 24, 28, 32 px) |
+| Radius (*new*) | `--theme-radius-xs` 2 px (chips), `-sm` 4 px (buttons, inputs), `-md` 6 px (cards, panels), `-lg` 8 px (dialogs, popovers) |
+| Motion (*new*) | `--theme-motion-fast` 120 ms, `--theme-motion-base` 200 ms, `--theme-motion-easing`; both durations become `0ms` under `prefers-reduced-motion: reduce` |
+
+Legacy aliases (AB#5526 phase 2): only `--lcars-font-primary` →
+`--theme-font-display`, `--lcars-font-mono` → `--theme-font-mono` and
+`--lcars-transition-fast` → `--theme-motion-fast` + easing remain, kept for the
+Meshmakers App until it migrates. All other `--lcars-*` variables (glows,
+button bases, input focus, radii, panel tokens, `--lcars-transition-normal`)
+were deleted — use the `--theme-*` tokens.
+
+Body text: `octo.styles()` sets `body { font-family: var(--theme-font-ui) }`
+(Roboto) since AB#5526; `h1`–`h3`, page and dialog titles, `mm-page` titles and
+KPI numbers use `--theme-font-display` (Montserrat 600).
+
+### Component styling in `octo.styles()` (Deep Sea, AB#5526)
+
+- **Buttons are flat**: primary = `--theme-accent` with `--theme-text-on-accent`
+  (hover `--theme-accent-hover`), base = `--theme-bg-elevated` with a
+  `--theme-border-default` hairline (hover `--theme-bg-hover` +
+  `--theme-border-strong`), outline/flat variants transparent; error =
+  `--theme-status-error`. Sentence case, `--theme-font-ui`, `--theme-radius-sm`,
+  keyboard focus `--theme-focus-ring`. Both themes use the same rules, so the
+  former light-only button overrides are no-ops.
+- **No decoration**: no gradients (sliders included), glows, pulses, scanlines
+  or text-shadows; grid headers, tabs (Kendo and dockview), process designer
+  palette/inspector headers, dialog titles and context menus are sentence case
+  in `--theme-font-ui` (the only uppercase left is the avatar initials); popups,
+  dialogs and menus use `--theme-bg-overlay` + `--theme-border-default` +
+  `--theme-shadow-popup`; the drawer is flat `--theme-bg-elevated`.
+- **`theme-overrides()`**: `light-theme-surface-overrides` was reduced to what
+  the tokens cannot express (the old light card, `#d7ebe5` table band, drawer
+  and app-bar treatments are gone — both themes agree now). It also emits a
+  sentence-case rule (`html:root .k-label, kendo-label, .section-title`) that
+  outranks host component styles in both themes.
+- **Legacy LCARS page classes — kept only for the Meshmakers App** (AB#5526
+  phase 2; the Refinery Studio no longer uses them): `.lcars-page-header`,
+  `.page-title` / `.title-prefix` / `.title-main`, `.header-content` and
+  `.lcars-content-panel` (surface card, with its `.k-grid` rule) keep a neutral
+  Deep Sea definition; `.lcars-header-accent`, `.lcars-header-line`,
+  `.panel-accent-top/-bottom`, `.lcars-footer` and `.footer-*` render nothing
+  (`display: none`). Everything else was deleted: `.header-stats`,
+  `.stat-badge`, `.lcars-panel`, `.lcars-panel-asymmetric`, `.lcars-header-bar`,
+  `.lcars-divider`, `.lcars-text-*`, `.lcars-bg-*`, `.lcars-border-mint`, the
+  glow/scanline/pulse utilities, and the `_lcars-button.scss`,
+  `_lcars-flat-btn.scss` and `_lcars-input.scss` mixin files (now the internal
+  `_button.scss` / `octo-button`, `_flat-button.scss` / `flat-button` and
+  `_field-input.scss` / `field-input`). New pages use `<mm-page>`.
+
+Deviations from concept §6.2 (contrast-driven): light `--theme-text-accent` /
+`--theme-accent` `#2c7d6d` (concept `#2e8473`, 4.16:1 on the light canvas →
+4.55:1), light `--theme-accent-hover` `#24685a` (concept `#266f61`),
+`--theme-text-muted` dark `#77869c` (concept `#687890`) and light `#657189`
+(concept `#75829a`), both ≥ 4.5:1 on `--theme-bg-input`. The Kendo bridge points `--kendo-color-primary`,
+`--kendo-color-surface(-alt)`, `--kendo-color-border`, `--kendo-color-base*`,
+`--kendo-border-radius-*` and `--kendo-font-family` at these tokens.
+
+Fonts are not bundled: the host loads Montserrat, Roboto and Roboto Mono
+(the Refinery Studio does so via Google Fonts in `index.html`).
+
+## Secondary Entry Points
+
+Heavy admin editors live in their own entry points so apps that do not use them keep the
+primary bundle small. Each one imports only the public API of `@meshmakers/octo-ui`.
+
+| Entry point | Contents |
+|-------------|----------|
+| `@meshmakers/octo-ui/branding` | Branding services, `provideOctoBranding`, theme switcher |
+| `@meshmakers/octo-ui/branding-settings` | Branding settings page (`BRANDING_ROUTES`) |
+| `@meshmakers/octo-ui/tree-navigation-settings` | Editor for `System.UI/TreeNavigationConfiguration` |
+| `@meshmakers/octo-ui/entity-forms` | Form-driven entity list / create / edit pages (`<mm-entity-page>`, `<mm-entity-list>`, `<mm-entity-form>`, `entityFormRoutes()`), driven by `System.UI/EntityForm` — see [`entity-forms/README.md`](./entity-forms/README.md) |
+
 ## Build
 
 ```bash

package/entity-forms/README.md

@@ -0,0 +1,460 @@
+# @meshmakers/octo-ui/entity-forms
+
+Form-driven list, create and edit pages for OctoMesh runtime entities (AB#5522).
+
+The layout of a page — sections, field order, labels, help texts, editors, visibility rules,
+list columns, capabilities — comes from the tenant's `System.UI/EntityForm` entities
+(System.UI ≥ 2.8.0, seeded by the `System.UI.EntityForms` blueprint). Types without a form, and
+tenants without System.UI, fall back to a built-in copy of the seeded `form-default`, so every
+CK type gets a usable page.
+
+This is a **secondary entry point**: it imports only the public API of `@meshmakers/octo-ui`
+and other packages, and hosts that do not use it keep the primary bundle unchanged.
+
+## Building blocks
+
+| Export | Purpose |
+|--------|---------|
+| `<mm-entity-page>` (`EntityPageComponent`) | Route component: list, create, edit and singleton flows, save, delete, unsaved-changes guard, breadcrumbs |
+| `entityFormRoutes(opts?)` | The three child routes `''` / `new` / `:rtId` of a page |
+| `<mm-entity-list>` (`EntityListComponent`) | `mm-list-view` of a resolved form (columns, Copy ID, delete, "New" incl. subtype picker) |
+| `<mm-entity-form>` (`EntityFormComponent`) | The form itself (sections, editors, validation, change set) |
+| `EntityFormService` | Loads forms + CK metadata (cached per tenant) and resolves the form for a type or form key |
+| `EntityFormDataService` | Reads values / secret state / associations; create, update (incl. `clearSecretAttributes`), delete |
+| `parseEntityForms`, `pickEntityForm`, `resolveEntityForm`, … | Pure functions behind the service, e.g. for a forms editor |
+| `entityFormCatalog(forms)`, `entityFormKey(form)` | Settings overview: one entry per target type whose effective form has a `Category`, with the URL key |
+| `EntityFormsMessages`, `DEFAULT_ENTITY_FORMS_MESSAGES` | All UI strings (English defaults; pass `Partial<…>` via `messages`) |
+| `ENTITY_FORM_FALLBACK_FORMS`, `provideEntityFormFallbacks`, `selectFallbackForms` | Host-provided built-in forms that apply per type where the resolution would end at `form-default` (see below) |
+| `ENTITY_FORM_ACTION_CONFIRMATION` | Optional host hook asked before a delete (e.g. a production-mode check) |
+| `ENTITY_FORM_DANGER_CONFIRMATION`, `entityDeleteConfirmation` | Optional host replacement of the delete danger confirmation (AB#5579) |
+
+## Usage
+
+### Routes (recommended)
+
+```ts
+import { entityFormRoutes } from '@meshmakers/octo-ui/entity-forms';
+
+export const routes: Routes = [
+  {
+    path: 'sftp',
+    children: entityFormRoutes({
+      formKey: 'sftp-configuration',          // or ckTypeId: 'System.Communication/SftpConfiguration'
+      breadcrumbUrl: 'communication/sftp',    // optional; adds {{entityFormTitle}} / {{entityName}} crumbs
+      canWrite: true,                         // optional; default true
+    }),
+  },
+];
+```
+
+The host must provide what the library services expect:
+
+- `provideOctoUi()` — includes `provideMmSharedUi()` (`ConfirmationService`,
+  `NotificationDisplayService`, `EntitySelectDialogService` for the reference picker) and
+  `CkTypeSelectorDialogService` (subtype picker). Hosts that do not use `provideOctoUi()` must
+  call `provideMmSharedUi()` themselves.
+- A `<div kendoDialogContainer></div>` (record row dialog, confirmations) and
+  `<div kendoWindowContainer></div>` (CK type selector) in the app shell.
+- Apollo for the tenant; optionally `TENANT_ID_PROVIDER` (cache scope per tenant) and
+  `BreadCrumbService` (breadcrumb labels; skipped when absent).
+
+### Route-parameter contract (stable; used by the Refinery Studio, AB#5523)
+
+| URL (relative to the mount point) | Page state |
+|-----------------------------------|------------|
+| `''` | List. A **singleton** form skips the list and opens its entity (see below). |
+| `new` | Create form. Route data `rtId: 'new'`. |
+| `new?type=<rtCkTypeId>` | Create form for a concrete subtype (required for abstract types; set by the list's subtype picker). |
+| `:rtId` | Edit form; read-only view when `canWrite` is false or the form has `CanEdit: false`. |
+| `:rtId?type=<rtCkTypeId>` | Edit form for an entity of a derived type (set when the list opens such a row). Without it the page detects the type after loading and re-resolves. |
+
+Optional `entityFormRoutes` options for the page heading and list: `title` (route data
+`entityListTitle`) replaces the resolved form title as the list heading and breadcrumb label
+(e.g. "All configurations" over `System/Configuration`); `showTypeColumn` (route data
+`entityListTypeColumn`) adds a "Type" column with the display name of each row's CK type: the
+`Name` of the type's entity form (`entityFormTypeTitles` / `ckTypeDisplayName`), else
+`humanizeCkTypeName` — sentence case with known acronyms and brands (`EMailReceiverConfiguration`
+→ "E-mail receiver configuration", `FinApiConfiguration` → "finAPI configuration",
+`SftpConfiguration` → "SFTP configuration"; AB#5524). A
+**singleton** form is titled with its form name (e.g. "Tenant mode"), never "Edit <entity name>".
+
+Page inputs (bound by `withComponentInputBinding()` from route params / data, otherwise read from
+`ActivatedRoute` — params, route data of the route and its ancestors, query params):
+
+| Input | Source fallback | Meaning |
+|-------|-----------------|---------|
+| `formKey` | `data.formKey`, then `params.formKey` | `form-sftp-configuration` (rtWellKnownName) or the kebab type key `sftp-configuration`. Wins over `ckTypeId`. |
+| `ckTypeId` | `data.ckTypeId`, then `params.ckTypeId` | Runtime CK type id of the target type. |
+| `rtId` | `params.rtId`, `data.rtId` | Absent = list; `'new'` = create; otherwise edit. |
+| `canWrite` | `data.canWrite`, then `true` | Write permission; the host maps roles to it (the library knows no role names). |
+| `messages` | `data.messages` | `Partial<EntityFormsMessages>`. |
+| `routerNavigation` | — | Default `true`. Set `false` and handle the `navigate` output to drive navigation yourself. |
+
+The query parameter is deliberately named `type`, not `ckTypeId`, so input binding never
+overwrites the page's `ckTypeId` (the form's target type).
+
+Navigation is always **relative** (`..`, `new`, `:rtId`, with `replaceUrl` after a create), so
+the routes work under any mount point. The `navigate` output (`{ kind: 'list'|'create'|'edit', rtId?, ckTypeId? }`)
+is emitted for every transition.
+
+Two more outputs let a host that embeds the page (e.g. the Studio's Data Explorer peek) keep its
+own lists current:
+
+| Output | Payload | When |
+|--------|---------|------|
+| `saved` | `{ kind: 'create' \| 'update', rtId, ckTypeId }` | After a successful create or update (not for an empty change set) |
+| `deleted` | `{ rtId, ckTypeId }` | After the open entity was deleted from the form, before the navigation to the list |
+
+Breadcrumb labels set via `BreadCrumbService.updateBreadcrumbLabels`: `entityFormTitle` (the
+resolved form title) and `entityName` (entity `name`, else `rtWellKnownName`, else `rtId`; the
+create title on `new`).
+
+### Singleton forms
+
+`Singleton: true` skips the list:
+
+1. With `SingletonWellKnownName` the entity is loaded by that well-known name.
+2. Without it, the first entity of the type is used.
+3. If none exists, the create form opens (with write permission) and the well-known name is
+   written on first save; afterwards the page stays on the same URL in edit mode.
+
+### Saving
+
+`saveChanges(): Promise<boolean>` (also called by `UnsavedChangesGuard` on "Yes"):
+
+- invalid form → all fields touched, warning, `false`;
+- create → `EntityFormDataService.create`, then navigation to `:rtId` (replacing `new`);
+- edit → only the changed attributes are sent (empty change set = "no changes"), then the
+  values are read again.
+- a host `beforeSave` hook (see below) runs after validation and before the server call; a
+  veto shows a warning (the hook's message or `saveVetoed`), an error shows `saveError`, and
+  nothing is saved in either case.
+
+### Before-save hook (`beforeSave`, AB#5623)
+
+Normalise or derive values, or stop the save, right before it happens. Sync or async
+(`Promise` / `Observable`, first value counts):
+
+```ts
+const normaliseContact: EntityFormBeforeSaveHook = (changeSet) => {
+  for (const a of changeSet.attributes) {
+    if (typeof a.value === 'string') a.value = a.value.trim();
+    if (a.attributeName === 'iban' && typeof a.value === 'string') a.value = a.value.replace(/\s+/g, '').toUpperCase();
+  }
+  const email = changeSet.attributes.find((a) => a.attributeName === 'email');
+  if (email) {
+    if (typeof email.value === 'string' && email.value && !email.value.includes('@')) {
+      throw new EntityFormSaveVeto(translate('CONTACT.INVALID_EMAIL'));
+    }
+    changeSet.attributes.push({ attributeName: 'normalizedEmail', value: String(email.value ?? '').toLowerCase() });
+  }
+  // returning nothing saves the (mutated) change set; return a new change set to replace it,
+  // or null / false to veto silently
+};
+```
+
+- Where: `mm-entity-page [beforeSave]` > route option `beforeSave` (data `entityFormBeforeSave`)
+  > `ENTITY_FORM_BEFORE_SAVE`. `mm-entity-form [beforeSave]` (or the token) applies through
+  `getChangeSetForSave({ rtId })` for hosts that save themselves; the form never notifies.
+- The hook gets a copy of the change set plus `{ mode, ckTypeId, rtId?, form }`. Attribute names
+  are camelCase; edit mode holds only the changed attributes, so derive from a source attribute
+  only when it is in the change set. An edit without changes skips the hook.
+- **Secrets:** nothing beyond the change set reaches the hook. A SECRET attribute appears only as
+  the write value the user just typed (or in `clearSecretAttributes`), never as a stored value —
+  the form never reads stored secrets. Do not log the change set.
+
+### Embedding without routes
+
+```html
+<mm-entity-list [model]="model" [canWrite]="canWrite" (openRequested)="open($event)" (createRequested)="create($event)" />
+<mm-entity-form [model]="model" mode="edit" [state]="state" (dirtyChange)="dirty = $event" />
+```
+
+Resolve `model` with `EntityFormService.resolve(rtCkTypeId)` / `resolveByFormKey(key)` and the
+state with `EntityFormDataService.load(model, { rtId })`.
+
+## Settings overview (catalog)
+
+`entityFormCatalog(await formService.getForms())` returns one entry per target type whose
+**effective** form (tenant form before seeded, then higher `Priority`) has a `Category`:
+`key`, `category` (lower case), `title` (form `Name`, else the humanized type name),
+`description`, `icon`, `targetCkTypeId`, `includeDerivedTypes`, `singleton`.
+`form-default` has no category and never appears. A tenant form replaces the delivered entry
+(and can move it to another category, or hide it by leaving `Category` empty).
+
+`entityFormKey(form)` is the URL key: the well-known name without `form-`
+(`form-email-sender-configuration` → `email-sender-configuration`), otherwise the kebab type
+name. The catalog prefers a delivered `form-*` name of the type, so URLs survive a tenant
+override. `resolveByFormKey` accepts both forms.
+
+`EntityFormDataService.count(ckTypeId, includeDerivedTypes?)` counts entities without reading
+attributes (`attributeNames: []`); without `includeDerivedTypes` only the exact type is counted.
+
+## Fallback forms (`ENTITY_FORM_FALLBACK_FORMS` / `provideEntityFormFallbacks`)
+
+A host can ship built-in copies of delivered forms, for example while a new version of the
+seeding blueprint has not been rolled out yet (AB#5524). Two ways to provide them:
+
+```ts
+// root (pulls the entry point into the initial bundle):
+providers: [{ provide: ENTITY_FORM_FALLBACK_FORMS, useValue: MY_FALLBACK_FORMS }]
+// or on every lazy route that renders entity forms (registers them in the root service, one cache):
+{ path: 'settings', providers: [provideEntityFormFallbacks(MY_FALLBACK_FORMS)], loadChildren: … }
+```
+
+- `EntityFormService.getForms()` appends a fallback **only where the normal resolution would end
+  at the chain end** — no form at all, or `form-default` (a form on `System/Entity`). A tenant or
+  seeded form for the exact type, or for an ancestor with `IncludeDerivedTypes`, always wins
+  (`selectFallbackForms`). Fallbacks for types the tenant does not have (no CK metadata) are
+  dropped. The first fallback per type wins. The result feeds `resolve`, `resolveByFormKey` and
+  `entityFormCatalog` unchanged.
+- Fallbacks are also used when the forms cannot be loaded (no System.UI ≥ 2.8.0, query error).
+- `registerFallbackForms(forms)` (behind `provideEntityFormFallbacks`) is idempotent per array and
+  drops the cached forms and resolutions once.
+- They count as delivered forms (`isTenantForm` is forced to `false`, `source: 'seeded'`). Use the
+  delivered `rtWellKnownName` (`form-<kebab-type>`) so URL keys do not change when the seeded form
+  arrives, and leave `rtId` empty.
+- A tenant form for the type without `Category` hides the entry, exactly like it hides a seeded one.
+
+This is the per-type counterpart of the built-in `form-default` safety net; the host is
+responsible for keeping its copies in step with the seed.
+
+## Action confirmation (`ENTITY_FORM_ACTION_CONFIRMATION`)
+
+Optional `(request: { action: 'delete', ckTypeId, count, description }) => Promise<boolean>`,
+asked by `mm-entity-list` and `mm-entity-page` **before** their own danger confirmation; `false` (or a
+throwing hook) cancels. The Refinery Studio maps it to its production-mode confirmation.
+
+## Delete confirmation (`ENTITY_FORM_DANGER_CONFIRMATION`, AB#5579)
+
+Deletes ask `ConfirmationService.showDangerConfirm` (shared-ui action guideline): the title names the
+entity ("Delete Primary?") or the count ("Delete 3 entities?"), the confirming button says
+"Delete entity" / "Delete entities", Cancel keeps the initial focus. Texts: the optional
+`confirmDelete*` keys of `EntityFormsMessages` (the former `confirmDeleteTitle` / `confirmDeleteMessage` /
+`confirmDeleteManyMessage` are no longer shown). A host that adds environment knowledge provides
+`ENTITY_FORM_DANGER_CONFIRMATION: (options: DangerConfirmationOptions, request) => Promise<boolean>`
+instead of the built-in dialog — e.g. the Studio's `DangerConfirmService.confirm` (production = type the
+name); it then no longer needs the production check in `ENTITY_FORM_ACTION_CONFIRMATION`.
+
+## `<mm-entity-list>`
+
+- Inputs: `model` (required), `canWrite = true`, `messages`, `listStateKey`.
+- Outputs: `createRequested { ckTypeId }`, `openRequested { rtId, ckTypeId }`, `deleted { rtId, ckTypeId }[]`.
+- Rows are flattened (`rtId`, `ckTypeId`, `rtWellKnownName`, `rtDisplayName`,
+  `rtCreationDateTime`, `rtChangedDateTime`, `<attributeName>: value`), so a column `field`
+  equals the GraphQL attribute path and server-side sort / filter / search work.
+- Derived types are listed when the form has `IncludeDerivedTypes` or the type is abstract;
+  otherwise a `ckTypeId EQUALS` field filter restricts the list to the exact type
+  (`runtimeEntities(ckId)` returns derived types by default).
+- Column display: `chip` → badge, `date` → localized date, `mono` → monospace cell, else text.
+  Cells are formatted by the CK value type of the attribute like the reference display (AB#5547):
+  ENUM → the enum value's name (the API returns the key, e.g. `0`), BOOLEAN → yes / no
+  (`toggleOn` / `toggleOff` messages); a `chip` column maps the keys via `badgeMapping`.
+- Context menu: **Copy ID** (RtId / CkTypeId / RtCkTypeId / RtEntityId), then — only with
+  `canWrite && CanDelete` — Delete with a confirmation. Toolbar "New" only with
+  `canWrite && CanCreate`.
+- **Abstract types** (`createRequiresSubtype`): "New" opens `CkTypeSelectorDialogService`
+  restricted to concrete subtypes (`derivedFromRtCkTypeId`, `allowAbstract: false`);
+  cancelling emits nothing.
+
+## Host extensions (AB#5623)
+
+All optional; without them the components behave as before.
+
+| Need | API |
+|---|---|
+| Save / Cancel below the form | `mm-entity-page [actionBarPosition]="'bottom'"` (route option `actionBarPosition`, data `entityPageActionBarPosition`) |
+| Extra page actions (Export, Prefill, ...) | `<ng-template mmEntityPageActions let-ctx>` inside `mm-entity-page` — rendered in the list header and in the form's action bar; `ctx` = `EntityPageActionsContext` (`view`, `mode`, `rtId`, `ckTypeId`, `model`, `saving`, `page`) |
+| Extra list actions | `mm-entity-list` `toolbarActions` / `rowActions` (icon buttons) / `rowMenuActions` (context menu); on the page `listToolbarActions` / `listRowActions` / `listRowMenuActions`. Plain `CommandItem`s; `onClick` gets the row as `e.data` |
+| Default list order | `listDefaultSort` in a host fallback form, or `defaultSort` on list / page (route option `defaultSort`). A user sort (also a remembered one) wins; the header shows no marker for the default order |
+| Translated labels / enum texts | `ENTITY_FORM_LABEL_RESOLVER` or the `labelResolver` input: `(request) => string \| null`; `request.kind` = `field`, `help`, `placeholder`, `section`, `sectionDescription`, `formTitle`, `formDescription`, `listColumn`, `recordColumn`, `enumOption`. Read a signal (language) inside to re-render on change; controls are not rebuilt |
+| Fixed texts incl. Copy ID | `messages` (`copyId`, `copyIdTooltip`, `copiedId`, `copyFailed`, ...); `mm-entity-id-info` has `buttonText` / `tooltip` / `copiedMessage` / `copyFailedMessage` |
+| Prefill a create form | `mm-entity-form [initialValues]` / `mm-entity-page [initialValues]` (object or `({ ckTypeId }) => values`; route option `initialValues`), or `entityFormPrefillState(values)` as `state` |
+| Normalise / veto before saving | `beforeSave` on `mm-entity-page` / `mm-entity-form`, route option `beforeSave`, or `ENTITY_FORM_BEFORE_SAVE` — see [Before-save hook](#before-save-hook-beforesave-ab5623) |
+| Set values from a host action | `EntityFormComponent.patchValues(values)` / `EntityPageComponent.patchFormValues(values)` — values count as edits (dirty, saved); secrets and read-only fields are skipped |
+| Placeholder values of legacy STRING secrets | `ENTITY_FORM_SECRET_PLACEHOLDER_VALUES` (exact values that read "Not set"). SECRET-typed attributes (AB#5528) need nothing: their state comes from the server |
+| Create / edit in a dialog over the list | `mm-entity-page [editMode]="'dialog'"` (route option `editMode`, data `entityPageEditMode`) — see [Dialog mode](#dialog-mode-editmode-dialog-ab5623) |
+| CSS classes per list row (e.g. disabled rows) | `mm-entity-list [rowClass]` / `mm-entity-page [listRowClass]` (route option `rowClass`, data `entityListRowClass`) or `ENTITY_LIST_ROW_CLASS`: `(row) => string \| string[] \| Record<string, boolean> \| null`. Classes land on the grid's `<tr>`: style them globally (or `::ng-deep`) |
+| Placeholder values of NON-secret config fields | `ENTITY_FORM_UNSET_PLACEHOLDER_VALUES` — see [Unset placeholders](#unset-placeholders-entity_form_unset_placeholder_values-ab5623) |
+
+### Dialog mode (`editMode: 'dialog'`, AB#5623)
+
+"New", row click and Edit / View open the form in a Kendo dialog over the list; the URL does not
+change and no `navigate` events are emitted.
+
+- Same form behaviour as the page: `beforeSave`, `initialValues`, `labelResolver`, secrets,
+  `patchFormValues`, the record row dialog. Host page actions (`mmEntityPageActions`) render in the
+  dialog with `ctx.view === 'form'`.
+- Bottom bar (`kendo-dialog-actions`, right-aligned like the record row dialog): page actions,
+  Cancel (Close when read-only), Delete (edit, with permission), Save (primary, right-most).
+- Cancel, the title-bar close button and Escape ask before discarding unsaved changes
+  (`unsavedChangesTitle` / `unsavedChangesMessage` / `discardChanges` / `keepEditing`). A route
+  change while the dialog has changes goes through `UnsavedChangesGuard` (save / discard / stay).
+- After a successful save (also "no changes") or delete the dialog closes; after a write the list
+  reloads (`saved` / `deleted` are emitted as on the page). Focus returns to the element that opened
+  the dialog (the list when that element is gone).
+- A load error or a missing entity shows an error notification; the list stays.
+- The `new` / `:rtId` routes keep working as pages (deep links); singleton forms always use the page.
+
+### Unset placeholders (`ENTITY_FORM_UNSET_PLACEHOLDER_VALUES`, AB#5623)
+
+Seeded placeholder values of non-secret configuration attributes (e.g. `TODO_SET_AZURE_TENANT_ID`)
+read as "not configured":
+
+```ts
+providers: [{
+  provide: ENTITY_FORM_UNSET_PLACEHOLDER_VALUES,
+  // a plain list applies to every attribute; or per attribute (any casing) and/or global:
+  useValue: { attributes: { azureTenantId: ['TODO_SET_AZURE_TENANT_ID'], clientId: ['TODO_SET_CLIENT_ID'] } },
+}]
+```
+
+- Exact, case-sensitive match on string values.
+- List: the cell shows `messages.notConfigured` ("Not configured"; text, mono and chip columns).
+- Form: the field starts empty with `notConfigured` as placeholder hint; the value counts as unset
+  (a required field is invalid, `VisibleWhen` sees no value).
+- Save: the form never writes a placeholder back. Untouched = not in the change set (the stored
+  placeholder stays and keeps reading "not configured"); a typed value replaces it; emptying the
+  field again is "no change". To remove the placeholder from the store, write `null` yourself
+  (e.g. in `beforeSave`). In create mode a placeholder default / prefill is left out of the create.
+- Never applies to secrets (SECRET decision AB#5528: secret placeholders are dropped; secrets use
+  `secretIsSet`): fields with `secret` (value type `SECRET`, CK metadata, credential-name rule, form
+  decision) and attributes in `secretFields` are skipped even when listed. Legacy STRING secrets
+  keep using `ENTITY_FORM_SECRET_PLACEHOLDER_VALUES`.
+
+## Secrets (write-only)
+
+Secret values never reach the browser (AB#5522 D5, AB#5542, AB#5544 item 4, decisions 2026-10-06).
+
+**Which fields are secret**
+
+- The **SECRET value type** (AB#5528) is always secret and maps automatically to a write-only
+  field — no form definition needed; `Secret: false` is ignored with a warning. Compatible
+  editors: `password` (default) and `multiline` (PEM keys, `EntityFormField.Editor: multiline`);
+  any other editor falls back to `password` with a warning.
+- Fallback for attributes that are not SECRET yet (older models): the form says `Secret: true`,
+  **or its editor is `password`** (always write-only), or the CK attribute carries the metadata
+  `secret=true`, or a textual attribute has a credential-like name (shared rule
+  `isSecretAttributeCandidate` of `@meshmakers/octo-services`).
+
+**Reading**
+
+- Value reads, the list and the reference picker use documents whose `$attributeNames` is
+  declared `[String]!` and always pass explicit names. Never add a document that selects
+  `attributes` without that argument — **omitting it makes the server return every attribute,
+  secrets included.**
+- SECRET fields (`ResolvedEntityForm.secretStateFields`) are part of that list: the server
+  returns `value: null` plus `secretIsSet`, giving `EntityFormValueState.secretStates`
+  (`isSet`, `keyMissing`, `setAt`) from `secretIsSet` / `secretKeyMissing` / `secretSetAt`
+  (selected since the SECRET round-2 schema).
+- Fallback secrets are never listed; whether they are set is read with an `IS_NOT_NULL` field
+  filter — plus `NOT_EQUALS ""` for STRING secrets — and `totalCount`. (Never use that probe on a
+  SECRET: the server refuses every filter but `IS_NULL` / `IS_NOT_NULL` there.)
+
+**UI** (field shell badge + `mm-entity-form-secret-editor`)
+
+- Badge next to the label, visible to read-only users too (Q15): **Set · set at …** (or **Set**
+  for legacy values without a timestamp), **Not set**, **Key missing — re-enter** (a value is
+  stored but its key is not in this environment's key ring; it reads as not set for consumers but
+  counts as present for "required"), **Will be cleared** (staged clear). Create mode shows
+  "Secret".
+- The input is never prefilled; placeholder "Leave empty to keep" when a value is stored.
+  Read-only users get no input, no "Show" and no "Clear".
+- **Show** reveals only the value typed in this session, never a stored one; it is disabled while
+  the input is empty (Q10).
+- **Multiline** (PEM keys): the text area renders its text transparent until **Show** (caret,
+  selection and placeholder stay visible) and a status line reports only the number of lines
+  entered. This works in every browser — Firefox has no reliable `-webkit-text-security`, and a
+  password input would drop the PEM line breaks.
+- **Clear** (optional SECRET fields with a stored value, edit mode, write access) is staged and
+  sent on Save as `clearSecretAttributes` (Q8). Clear and a new value are mutually exclusive:
+  Clear is disabled while a value is typed; a staged clear replaces the input by a note with
+  **Undo**. Required secrets cannot be cleared; fallback secrets cannot be cleared either (the
+  server accepts `clearSecretAttributes` only for SECRET attributes).
+- **No key ring** (Q17): when the host provides `ENTITY_FORM_SECRET_KEY_RING_CONFIGURED`
+  (a `Signal<boolean | null | undefined>`) and it is `false`, secret inputs are disabled with a
+  hint. Only **SECRET-typed** fields (and SECRET record members) are gated — fallback secrets
+  (name rule / metadata) are plain values server-side and stay writable. Without a provider (or
+  while the signal is `null` / `undefined`) secrets are writable.
+  The signal may change after the form was built (status loaded asynchronously): the controls
+  follow it. In **create** mode a visible, required secret that cannot be entered blocks the form:
+  the field stays required (marker + hint), `isValid()` is `false` and the public signal
+  `saveBlockedReason()` names the fields — `mm-entity-page` disables Save with that text as
+  tooltip and the form shows it as a notice; other hosts should do the same. Edit mode is not
+  blocked (the server enforces required secrets only on create). The Studio provides the token
+  app-wide from the bot status endpoint `GET {tenantId}/v1/secrets/status`
+  (`SecretEnvironmentStatusService`, fail-open).
+
+**Writing**
+
+- An empty secret is left out of the change set (unchanged). A required secret is required
+  only on create or while it is not present (set or key missing).
+- Secret list columns are dropped. The update mutation selects no attributes (no echo).
+- Record members of value type SECRET: the generic read returns `value: null` + `secretIsSet` per
+  member; the form keeps that state (never a value). The records grid and the row editor show the
+  shared status badge (**Set** / **Not set** / **Key missing — re-enter**); the row editor offers
+  an empty password input (read-only users: badge only). A typed value replaces the member
+  (grid: "New value (unsaved)"); an empty input keeps it — on save the member is **omitted** and
+  the server carries the stored value over from the element with the same record key (handover
+  §2). Changing an element's record key therefore drops its stored secret. A state object is
+  never sent back. Without a key ring the member input is disabled with the hint (badge stays).
+- The CK description of `EntityFormField.Secret` says "masked … revealed on demand"; the concept
+  (§5.8, write-only) wins.
+
+## Editors (MVP)
+
+| Editor | Implementation |
+|--------|----------------|
+| text, multiline, email, url, password, number, toggle, enum, datetime | Kendo inputs; email / url validators by editor; `Min`/`Max` on numbers, `Pattern` on text |
+| chips | Array editor for `STRING_ARRAY` / `INT_ARRAY` |
+| cron | shared-ui `mm-cron-builder` |
+| **json / yaml** | Monospace `kendo-textarea` (no Monaco / YAML library in the workspace). `json` validates with `JSON.parse`, `yaml` is not validated. Both are stored as STRING. The Studio can swap in Monaco later via `CustomComponent`. |
+| **reference** | shared-ui `mm-entity-select-input` (typeahead plus its **grid dialog**, multi-select for `N` roles) on a secret-safe data source that selects only the target's non-secret `name` attribute (literal `attributeNames: ["name"]`). Labels (picker and current value): a real `rtDisplayName` > `name` > `rtWellKnownName` > the synthetic `<type>@<rtId>` (so a pool shows "Default Cloud", not its well-known name `CommunicationPool`). Deviates from concept §5.4, which names `mm-entity-selector-dialog` — that one is a perspective tree picker without type filter or multi-select, and configuration types are not in a tree. A form field's `referenceDisplayAttributes` (CK `EntityFormField.ReferenceDisplayAttributes`, System.UI ≥ 2.9.0, read through the generic EntityForm query — no typed schema field, so older models simply lack it; host fallback forms may set it too; e.g. `['repositoryUrl', 'channel']`): the picker then reads exactly those non-secret target attributes with `entityFormGetReferenceOptionsWithAttributes` (explicit `[String]!` `attributeNames`) and shows `name · value · value` — in the picker rows and for the current value (looked up by rtId; the field value keeps its plain name). Values are formatted by the target's CK value type (`EntityFormService.resolve` attaches `reference.displayAttributeInfo`): ENUM key → enum name (e.g. channel `0` → "Release"), BOOLEAN → the `toggleOn`/`toggleOff` labels, DATE_TIME → localized date and time, arrays comma-separated, records skipped (AB#5547; never list a secret attribute — attributes marked secret on the target are dropped, and a SECRET value is never returned anyway). |
+| records | Table with add / remove / move / edit; rows are edited in a dialog generated from the record's CK attributes. Nested records are read-only. |
+| unsupported (BINARY, GEOSPATIAL_POINT, TIME_SPAN, …) | Read-only display |
+
+**Runtime state is never generated as an editable field.** Generated fields (`form-default`,
+"Further attributes") whose attribute is in `RUNTIME_STATE_ATTRIBUTES` (`core/attribute-path.ts`:
+deployment / communication / configuration state, last errors and their timestamps, status
+message, last synced sequence number, lifecycle state, last activity, on-demand flags) are
+read-only, like the engine-stamped `rtBlueprint*` attributes. It is a documented list because the
+CK `ownership: RuntimeState` marker is not in the schema the library is generated from; a field a
+form defines explicitly keeps its own `ReadOnly`.
+
+## Form resolution (summary)
+
+1. Forms targeting the exact type win; otherwise the nearest ancestor with forms that set
+   `IncludeDerivedTypes` supplies the candidates (`form-default` targets `System/Entity`).
+2. Tenant forms beat seeded forms (empty `RtBlueprintSource`), then higher `Priority`, then
+   `rtWellKnownName` / `rtId` ascending (deterministic tie-break).
+3. No match → built-in default form with a warning. Forms are never merged.
+4. Attribute paths match case-insensitively (forms write `Host`, CK names are `host`); unknown
+   paths are skipped, dotted paths are skipped with a warning; unmentioned attributes go to a
+   generated "Further attributes" section unless `GenerateRemainingFields: false`.
+
+## Known backend limits
+
+- **CK record attributes always report `isOptional: false`.** Record sub-fields are therefore
+  treated as optional in the UI; the server still enforces mandatory sub-attributes and answers
+  `ASSET1004`.
+- **The `attributeNames` filter is applied inside records too.** Reading a record attribute
+  returns its rows with empty `attributes` unless the record's sub-attribute names are listed as
+  well, so `readAttributeNames` contains them. When a sub-attribute name equals a fallback
+  (non-SECRET) secret top-level attribute name it is dropped and the record field becomes
+  read-only (warning), so a save cannot erase that sub-value. A top-level SECRET name does not block
+  only when every record member of that name is a SECRET too (the server redacts both). If a
+  NON-SECRET member shares the name, listing it would return that member in clear text: the name is
+  not listed, the record field becomes read-only and the SECRET falls back to the presence probe.
+- The edit flow relies on a partial `RtEntityUpdate` keeping the attributes that are not sent
+  (unchanged values, secrets). That is what makes the write-only secret handling safe.
+
+## Tests
+
+Specs live next to the sources and run with the octo-ui test target
+(`../**/*.spec.ts`). `@meshmakers/octo-ui` resolves to `dist`, so build first:
+
+```bash
+npm run build:octo-ui && npm run test:octo-ui
+```
+
+Demo: `demo-app` → `demos/entity-forms` (SFTP configuration form).