@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/content/nodeSettings.tsx

@@ -0,0 +1,963 @@
+// THE SELECTED NODE'S SETTINGS, as any host shows them — the canvas popover beside the block, or a
+// settings panel a workbench still docks. What the workbench owns around the block's own form:
+// the ssr flag, the page's meta on the root, and the REFERENCE PICKERS.
+//
+// HOSTS, not renders (ADR-0034): the block's form is a MOUNTED application — the block's own
+// library's root mounts it when it ships one, the editor's otherwise. The draft it edits lives in
+// the workbench's container (SETTINGS_DRAFT_TOKEN, read through the parent door).
+//
+// The pickers are drawn BY THE EDITOR, next to the fields the form marks with `data-field`, for
+// the settings the block declares `bindable` — the Unity object-picker circle: grey for a value
+// written here, blue for a value taken from a provider; a click lists what the reachable providers
+// hand out. The form knows nothing of them.
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import type { ReactNode, RefObject } from 'react';
+import { DI_CONTAINER_TOKEN, SingleDiToken } from '@mosetta/di';
+import type { DiContainer } from '@mosetta/di';
+import { useComponent, useDi, useDiOptional } from '@mosetta/react';
+import { useServerAction } from '@mosetta/react/server-action';
+import { EditingSession, editingSessionHubOf, findNodeDoc, unitOf } from '@mosetta/content';
+import type { ICatalogEntry, IEditingState, IPageMeta } from '@mosetta/content';
+import { parseLanguages } from '@mosetta/content/i18n';
+import { isRefValue, TILES_HOLDER_TOKEN, parseRef } from '@mosetta/runtime/client';
+import type { IRefTreeNode } from '@mosetta/runtime/client';
+import './workbenchScale.css';
+import './nodeSettings.css';
+import { SearchField } from './searchField';
+import { listComponentsToken, projectConfigToken } from './contentCommon';
+import { ensureEditorViews, ensureSettingsDraft } from './settingsDraft';
+import { useFeedProjectConfig } from './projectConfig';
+import { formRootOf } from './formRoot';
+import { ensureMediaUpload } from './mediaUpload';
+import { hostedPage, hostFallbackOf } from './mountedTree';
+import { useMountedTree } from './useMountedTree';
+import { ensureRefsEditing } from './refsEditing';
+import type { IRefOption } from './refsEditing';
+import { OpenFieldsForm, PrefabInstanceForm } from './prefabFields';
+import { useFeedPrefabTrees, useProjectPrefabs } from './projectPrefabs';
+import { isPartId, openInPrefab, prefabPartOf } from './prefabParts';
+import { disconnectedOf, useDisconnection } from './disconnected';
+import { upgradeChanges, useUpgrades } from './blockUpgrades';
+import type { IOutdatedNode } from './blockUpgrades';
+import { noticesOf } from './editingNotices';
+import type { IPrefabPart } from './prefabParts';
+import { WORKSPACE_TOKEN } from '../workbench/workspace';
+import { useFeedThemeVariables } from './themeVariables';
+import { FORM_HOST_CLASS, INSPECTOR_TAB_ATTRIBUTE, tabOf } from '../canvas/settingsTabs';
+import { blockSchemas, nodeSettingsIssues } from '@mosetta/settings/check';
+import type { INodeSettingsIssue } from '@mosetta/settings/check';
+import { removalPatch, SettingsIssues } from './settingsIssues';
+import type { TSettingsTab } from '../canvas/settingsTabs';
+
+/** a section of the editor's own settings, under the tab of the popover it belongs to */
+function Section({ tab, children }: { tab: TSettingsTab; children: ReactNode }) {
+  return <div {...{ [INSPECTOR_TAB_ATTRIBUTE]: tab }}
+              className="settings__section">{children}</div>;
+}
+
+/**
+ * The page's own words: title, description, cover and date. They ride in the document (versioned
+ * with it), feed the head, the article lists and the share card. A field emptied leaves the doc.
+ * A project of several languages gets a language picker: in another language only the WORDS are
+ * edited (the title and description a reader of that language gets — the original shows through
+ * where one is empty); the cover, the date and the rest are the page's in every language.
+ */
+function PageMetaForm({ session, meta }: { session: EditingSession; meta: IPageMeta }) {
+  const config = useServerAction({ token: projectConfigToken, input: {} });
+  const { languages, defaultLanguage } = parseLanguages(config.isSuccess() && config.serverData.ok ? config.serverData.config : null);
+  const [picked, setPicked] = useState<string | null>(null);
+  const lang = picked && picked !== defaultLanguage && languages.includes(picked) ? picked : null;
+  const words = lang ? meta.i18n?.[lang] ?? {} : null;
+  const field = (key: 'title' | 'description' | 'image' | 'date' | 'category', label: string, placeholder: string, type = 'text') => {
+    const own = meta[key];
+    const value = words ? words[key as 'title' | 'description'] : own;
+    return (
+      <label className="settings__meta-field">
+        <span className="settings__meta-label">{label}</span>
+        <input className="settings__meta-input"
+               type={type}
+               data-test-id={`settings-meta-${key}`}
+               data-field={key}
+               value={typeof value === 'string' ? value : ''}
+               // in a translation the original shows through — what the reader gets while it is empty
+               placeholder={words && typeof own === 'string' && own ? own : placeholder}
+               onChange={(e) => (lang
+                 ? session.setPageMetaWords({ [lang]: { [key]: e.target.value } })
+                 : session.setPageMeta({ [key]: e.target.value }))} />
+      </label>
+    );
+  };
+  return (
+    <div className="settings__meta"
+         data-test-id="settings-meta"
+         data-meta-lang={lang ?? defaultLanguage}>
+      <div className="settings__target">Page</div>
+      {languages.length > 1 ? (
+        <div className="settings__lang">
+          <select className="settings__lang-select"
+                  aria-label="Language of the page's words"
+                  data-test-id="settings-meta-lang"
+                  value={lang ?? ''}
+                  onChange={(e) => setPicked(e.target.value || null)}>
+            <option value="">{`${defaultLanguage} · original`}</option>
+            {languages.filter((l) => l !== defaultLanguage).map((l) => (
+              <option key={l}
+                      value={l}>{`${l}${meta.i18n?.[l] ? '' : ' · not translated'}`}</option>
+            ))}
+          </select>
+        </div>
+      ) : null}
+      {field('title', 'Title', 'what the tab and the list show')}
+      {field('description', 'Description', 'one or two sentences')}
+      {lang ? (
+        <span className="settings__meta-label">The cover, the date and the category are the same in every language</span>
+      ) : (
+        <>
+          {field('image', 'Cover image URL', 'https://…')}
+          {field('date', 'Date', '', 'date')}
+          {field('category', 'Category', 'a key: english_grammar')}
+          <label className="settings__meta-flag"
+                 data-tooltip="Search engines will not show this page: it gets robots noindex and stays out of the sitemap">
+            <input type="checkbox"
+                   data-test-id="settings-meta-noindex"
+                   checked={meta.noindex === true}
+                   onChange={(e) => session.setPageMeta({ noindex: e.target.checked })} />
+            <span className="settings__meta-label">Hide from search engines</span>
+          </label>
+        </>
+      )}
+    </div>
+  );
+}
+
+interface IFieldBox {
+  readonly field: string;
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** the picker's greatest height (nodeSettings.css: .settings__picker max-height) plus its shadow */
+const PICKER_HEIGHT = 430;
+
+/** where the marked fields of a mounted form sit, relative to `container` — re-measured as the form changes */
+function useFieldBoxes(container: RefObject<HTMLElement | null>, fields: readonly string[]): IFieldBox[] {
+  const [boxes, setBoxes] = useState<IFieldBox[]>([]);
+  const key = fields.join('|');
+  useEffect(() => {
+    const root = container.current;
+    if (!root || !fields.length) {
+      setBoxes([]);
+      return undefined;
+    }
+    // the popover's tab shown (settingsTabs.ts): a field on another tab is out of sight, and so is its circle
+    const tabbed = root.closest('[data-settings-tab]');
+    const measure = () => {
+      const origin = root.getBoundingClientRect();
+      const showing = tabbed?.getAttribute('data-settings-tab') ?? null;
+      const next: IFieldBox[] = [];
+      for (const field of fields) {
+        // a selector would have to quote the field's name; scanning is simpler and cannot misfire
+        const element = [...root.querySelectorAll('[data-field]')].find((el) => el.getAttribute('data-field') === field);
+        if (!element || (showing && tabOf(element) !== showing)) continue;
+        const rect = element.getBoundingClientRect();
+        next.push({ field, top: rect.top - origin.top, left: rect.left - origin.left, width: rect.width, height: rect.height });
+      }
+      // the mounted form's own height rides along — a picker taller than the rest of the form
+      // reserves the room it needs (see FieldRefs)
+      const form = root.firstElementChild;
+      next.push({ field: '', top: 0, left: 0, width: 0, height: form ? form.getBoundingClientRect().height : 0 });
+      setBoxes((prev) => (JSON.stringify(prev) === JSON.stringify(next) ? prev : next));
+    };
+    measure();
+    // the observers of the element's OWN window: a host realm may not expose them as globals
+    const view = root.ownerDocument.defaultView;
+    const mutations = view?.MutationObserver ? new view.MutationObserver(measure) : null;
+    mutations?.observe(root, { subtree: true, childList: true, attributes: true, characterData: true });
+    const resize = view?.ResizeObserver ? new view.ResizeObserver(measure) : null;
+    resize?.observe(root);
+    const switches = tabbed && view?.MutationObserver ? new view.MutationObserver(measure) : null;
+    if (tabbed) switches?.observe(tabbed, { attributes: true, attributeFilter: ['data-settings-tab'] });
+    return () => {
+      mutations?.disconnect();
+      resize?.disconnect();
+      switches?.disconnect();
+    };
+  }, [container, key]);
+  return boxes;
+}
+
+const text = (value: unknown): string => (typeof value === 'string' ? value : value == null ? '' : JSON.stringify(value));
+
+/** the list a picker circle opens: every reachable provider, what it hands out, and the way back */
+function RefPicker({ top, field, current, options, shown, onPick, onCreate, onUnbind, onShow, onClose }: {
+  top: number;
+  field: string;
+  current: { name: string; key: string } | null;
+  options: readonly IRefOption[];
+  shown: unknown;
+  onPick(name: string, key: string): void;
+  onCreate(name: string): void;
+  onUnbind(): void;
+  onShow(): void;
+  onClose(): void;
+}) {
+  const [query, setQuery] = useState('');
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const away = (event: MouseEvent) => {
+      if (!ref.current?.contains(event.target as Node)) onClose();
+    };
+    const escape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onClose();
+    };
+    document.addEventListener('mousedown', away, true);
+    document.addEventListener('keydown', escape, true);
+    return () => {
+      document.removeEventListener('mousedown', away, true);
+      document.removeEventListener('keydown', escape, true);
+    };
+  }, [onClose]);
+  // the value in use is where the list opens — not somewhere the author has to scroll to
+  useLayoutEffect(() => {
+    const picker = ref.current;
+    const row = picker?.querySelector<HTMLElement>('.settings__picker-row--current');
+    if (picker && row) picker.scrollTop = Math.max(0, row.offsetTop - (picker.clientHeight - row.offsetHeight) / 2);
+  }, []);
+  const needle = query.trim().toLowerCase();
+  const matches = (label: string, value: unknown, where: readonly string[]) => !needle
+    || [label, text(value), ...where].some((part) => part.toLowerCase().includes(needle));
+  return (
+    <div ref={ref}
+         className="settings__picker"
+         style={{ top }}
+         data-test-id="settings-ref-picker"
+         data-ref-field={field}>
+      <SearchField className="settings__picker-search-field">
+        <input className="settings__picker-search"
+               autoFocus
+               placeholder="Search values"
+               value={query}
+               onChange={(e) => setQuery(e.target.value)} />
+      </SearchField>
+      {options.length === 0 ? <div className="settings__picker-empty">No block around hands out values</div> : null}
+      {options.map((option) => (
+        <div key={option.name}
+             data-ref-provider={option.name}>
+          <div className="settings__picker-group">
+            <span>{option.name}</span>
+            <span className="settings__picker-where">{option.where}</span>
+          </div>
+          {option.entries.filter((entry) => matches(entry.label, entry.value, option.usedBy[entry.key] ?? [])).map((entry) => {
+            const isCurrent = current?.name === option.name && current.key === entry.key;
+            // who reads it, unless the name already says so (a key made after its node)
+            const readers = (option.usedBy[entry.key] ?? []).filter((where) => !entry.label.startsWith(where));
+            return (
+              <button key={entry.key}
+                      type="button"
+                      className={`settings__picker-row${isCurrent ? ' settings__picker-row--current' : ''}`}
+                      data-ref-entry={entry.key}
+                      onClick={() => onPick(option.name, entry.key)}>
+                <span className="settings__picker-key">
+                  {entry.label}
+                  {readers.length ? <span className="settings__picker-where">{` · ${readers.join(', ')}`}</span> : null}
+                </span>
+                <span className="settings__picker-value">{text(entry.value)}</span>
+              </button>
+            );
+          })}
+          {option.canCreate ? (
+            <button type="button"
+                    className="settings__picker-row"
+                    data-ref-create={option.name}
+                    onClick={() => onCreate(option.name)}>
+              <span>+ New value in {option.name}</span>
+            </button>
+          ) : null}
+        </div>
+      ))}
+      {current ? (
+        <>
+          <button type="button"
+                  className="settings__picker-action"
+                  data-ref-show
+                  onClick={onShow}>
+            Show {current.name}
+          </button>
+          <button type="button"
+                  className="settings__picker-action"
+                  data-ref-unbind
+                  onClick={onUnbind}>
+            None · keep “{text(shown)}” as text
+          </button>
+        </>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * The circles beside the form's bindable fields, and the picker one of them opens. Reads and
+ * writes through the workbench's reference editor, as one undoable step per choice.
+ */
+function FieldRefs({ container, session, state, node }: {
+  container: RefObject<HTMLElement | null>;
+  session: EditingSession;
+  state: IEditingState;
+  node: IRefTreeNode;
+}) {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const refs = ensureRefsEditing(di);
+  const [, setLoads] = useState(0);
+  useEffect(() => refs.subscribe(() => setLoads((n) => n + 1)), [refs]);
+  const [open, setOpen] = useState<string | null>(null);
+  useEffect(() => setOpen(null), [node.id]);
+  const fields = refs.bindable(node.reference);
+  const measured = useFieldBoxes(container, fields);
+  const formHeight = measured.find((box) => box.field === '')?.height ?? 0;
+  const boxes = measured.filter((box) => box.field !== '');
+  const opened = boxes.find((box) => box.field === open);
+  // an open picker hangs below its field; the area grows to hold it (the popover scrolls, never clips)
+  const reserve = opened ? Math.max(0, opened.top + opened.height + 4 + PICKER_HEIGHT - formHeight) : 0;
+  const doc = state.doc as unknown as IRefTreeNode | null;
+  const settings = node.settings ?? {};
+  // a bound field wears the editor's colour on its OWN border (nodeSettings.css) — its own shape,
+  // whatever the form drew; kept on the field when the form renders it anew
+  const boundFields = fields.filter((field) => isRefValue(settings[field])).join('|');
+  useLayoutEffect(() => {
+    const root = container.current;
+    if (!root) return undefined;
+    const bound = new Set(boundFields ? boundFields.split('|') : []);
+    const mark = () => {
+      for (const el of root.querySelectorAll('[data-field]')) {
+        const on = bound.has(el.getAttribute('data-field') ?? '');
+        if (on !== el.hasAttribute('data-mosetta-bound')) {
+          if (on) el.setAttribute('data-mosetta-bound', '');
+          else el.removeAttribute('data-mosetta-bound');
+        }
+      }
+    };
+    mark();
+    const view = root.ownerDocument.defaultView;
+    const watch = view?.MutationObserver ? new view.MutationObserver(mark) : null;
+    watch?.observe(root, { subtree: true, childList: true });
+    return () => {
+      watch?.disconnect();
+      for (const el of root.querySelectorAll('[data-mosetta-bound]')) el.removeAttribute('data-mosetta-bound');
+    };
+  }, [container, boundFields]);
+  if (!doc || !boxes.length) return null;
+  const views = state.views;
+  const apply = (patches: ReturnType<typeof refs.bindPatches>) => {
+    session.updateNodesSettings(patches);
+    setOpen(null);
+  };
+  return (
+    <>
+      {reserve ? <div style={{ height: reserve }} /> : null}
+      {boxes.map((box) => {
+        const value = settings[box.field];
+        const bound = isRefValue(value) ? parseRef(value.$ref) : null;
+        return (
+          <div key={box.field}>
+            <button type="button"
+                    className={`settings__ref${bound ? ' settings__ref--bound' : ''}`}
+                    // beside its field, centred on it by its own css — a narrow field keeps it close
+                    style={{ top: box.top + box.height / 2, left: box.left + box.width + 6 }}
+                    data-tooltip={bound
+                      ? `The value comes from ${bound.name} · ${bound.key} — click to pick another or unlink it`
+                      : 'Take the value from another block — click to pick one'}
+                    aria-label={bound ? `${box.field}: from ${bound.name}` : `${box.field}: pick a value`}
+                    data-test-id="settings-ref"
+                    data-ref-field={box.field}
+                    data-ref-bound={bound ? bound.name : undefined}
+                    onClick={() => setOpen(open === box.field ? null : box.field)} />
+            {open === box.field ? (
+              <RefPicker top={box.top + box.height + 4}
+                         field={box.field}
+                         current={bound}
+                         options={refs.options(doc, node.id, views, box.field)}
+                         shown={bound ? refs.read(doc, node.id, value as { $ref: string }, {}) : value}
+                         onPick={(name, key) => apply(refs.bindPatches(doc, node.id, settings, box.field, name, views, key))}
+                         onCreate={(name) => apply(refs.bindPatches(doc, node.id, settings, box.field, name, views))}
+                         onUnbind={() => apply(refs.unbindPatches(doc, node.id, settings, box.field))}
+                         onShow={() => {
+                           // the Unity "ping": the provider lights up in the tree and the canvas
+                           const providerId = refs.providerOf(doc, node.id, value);
+                           if (!providerId) return;
+                           session.hoverNode(providerId);
+                           setTimeout(() => session.hoverNode(null), 1500);
+                         }}
+                         onClose={() => setOpen(null)} />
+            ) : null}
+          </div>
+        );
+      })}
+    </>
+  );
+}
+
+/**
+ * For a block that hands out values it can keep new ones of (a provider with `create` — i18n):
+ * whether it takes NEW blocks under its wing — every block placed in its reach from now on gets
+ * its fields of the provider's type linked to it at once (autoBind.ts), nothing to press.
+ */
+function AutoBindToggle({ session, node }: { session: EditingSession; node: { id: string; reference: string; autoBind?: boolean } }) {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const refs = ensureRefsEditing(di);
+  // the provider's declaration is module code: known once its module is in (the refs say when)
+  const keeps = useSyncExternalStore(refs.subscribe, () => refs.canKeep(node.reference)?.type ?? (refs.canKeep(node.reference) ? '' : null));
+  if (keeps === null) return null;
+  const what = keeps ? `${keeps} fields` : 'fields';
+  return (
+    <Section tab="main">
+      <label className="settings__ssr"
+             title={`Blocks placed in this block's reach get their ${what} linked to it at once — a text is counted, and translated, from its first moment`}>
+        <input type="checkbox"
+               data-test-id="settings-auto-bind"
+               data-settings-auto-bind={node.id}
+               checked={node.autoBind === true}
+               onChange={(e) => session.setNodeAutoBind(node.id, e.target.checked)} />
+        {`Link new blocks' ${what} to this block`}
+      </label>
+    </Section>
+  );
+}
+
+/**
+ * A PREFAB's own block, selected on a page: what it is, why it cannot be changed here, and the
+ * ways on — to the prefab, where it is changed, and to the prefab node, the page's own block.
+ */
+function PrefabPartNotice({ session, part }: { session: EditingSession; part: IPrefabPart }) {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const workspace = useDiOptional(WORKSPACE_TOKEN);
+  const working = editingSessionHubOf(di)?.active ?? session;
+  return (
+    <div className="settings__part"
+         data-test-id="settings-prefab-part"
+         data-prefab={part.prefab.name}>
+      <p className="settings__part-text">
+        A block of the prefab <b>{part.prefab.name}</b> — seen here, changed in the prefab: a change
+        there shows on every page that places it.
+      </p>
+      <div className="settings__part-actions">
+        {workspace ? (
+          <button type="button"
+                  className="settings__part-action settings__part-action--main"
+                  data-test-id="settings-part-open"
+                  onClick={() => openInPrefab(workspace, working, part)}>
+            Open in prefab
+          </button>
+        ) : null}
+        <button type="button"
+                className="settings__part-action"
+                data-test-id="settings-part-owner"
+                onClick={() => session.selectNode(part.owner.id)}>
+          Select the prefab
+        </button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * A block with a NEWER VERSION (ADR-0061): the page keeps the version it was placed with until the
+ * author says otherwise — here, for this block (the toolbar's Updates does a page at once). Its
+ * settings move through the new version's own `upgrade`, under its new defaults; one undoable step.
+ */
+function UpgradeLine({ session, node, readOnly }: { session: EditingSession; node: IOutdatedNode; readOnly: boolean }) {
+  const holder = useDi(TILES_HOLDER_TOKEN);
+  const notices = noticesOf(useDi(DI_CONTAINER_TOKEN));
+  const { components } = useUpgrades(null);
+  const [busy, setBusy] = useState(false);
+  const { name, fromVersion, toVersion } = node.upgrade;
+  const update = async () => {
+    setBusy(true);
+    try {
+      session.upgradeNodes(await upgradeChanges(holder, [node], components));
+      notices?.show('publish', `Updated ${name} to ${toVersion}`);
+    } catch {
+      notices?.show('refuse', `Could not update ${name} to ${toVersion}`);
+    } finally {
+      setBusy(false);
+    }
+  };
+  return (
+    <div className="settings__part settings__part--up"
+         data-test-id="settings-upgrade"
+         data-from={fromVersion}
+         data-to={toVersion}>
+      <p className="settings__part-text">
+        {`${name} ${fromVersion} → ${toVersion}`}
+      </p>
+      {readOnly ? null : (
+        <div className="settings__part-actions">
+          <button type="button"
+                  className="settings__part-action settings__part-action--main"
+                  data-test-id="settings-upgrade-button"
+                  disabled={busy}
+                  onClick={() => void update()}>
+            {busy ? 'Updating…' : `Update to ${toVersion}`}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * A block of a distribution the project DISCONNECTED (ADR-0059): the site leaves it out, so its
+ * form would set what nobody sees. What is left to do with it is said instead — take it out, or
+ * connect the distribution again where the project's settings are.
+ */
+function DisconnectedNotice({ session, nodeId, title, readOnly, platformOrigin }: {
+  session: EditingSession; nodeId: string; title: string; readOnly: boolean; platformOrigin: string | null;
+}) {
+  return (
+    <div className="settings__part settings__part--off"
+         data-test-id="settings-disconnected"
+         data-disconnected={title}>
+      <p className="settings__part-text">
+        <b>{title}</b> is disconnected from this project, so the site does not show this block — not
+        on the page, not in its previews. Delete it, or connect {title} again in the project’s settings.
+      </p>
+      <div className="settings__part-actions">
+        {readOnly ? null : (
+          <button type="button"
+                  className="settings__part-action settings__part-action--main"
+                  data-test-id="settings-disconnected-delete"
+                  onClick={() => session.removeNode(nodeId)}>
+            Delete the block
+          </button>
+        )}
+        {platformOrigin ? (
+          <a className="settings__part-action"
+             data-test-id="settings-disconnected-settings"
+             href={`${platformOrigin}/`}
+             target="_blank"
+             rel="noreferrer">
+            Project settings ↗
+          </a>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+/** how long the form's markup must hold still to count as arrived — a part of it loading on its own would change it again */
+const FORM_SETTLE_MS = 150;
+/** a form that draws nothing — or very late — is shown as it is after this */
+const FORM_PATIENCE_MS = 4000;
+
+/**
+ * Whether the block's own form has ARRIVED in its element. Its module loads after the settings
+ * open, and until then the element is empty (the hosted root renders nothing around the tree):
+ * arrived is markup in it that held still a moment — or patience run out. The host marks the
+ * form `data-form-loading` until then; the canvas popover stays unseen meanwhile, so it does not
+ * show a half of itself in one place and the whole in another.
+ */
+function useFormArrived(host: RefObject<HTMLElement | null>): boolean {
+  const [arrived, setArrived] = useState(false);
+  useEffect(() => {
+    const element = host.current;
+    if (!element || arrived) return undefined;
+    let settle: ReturnType<typeof setTimeout> | undefined;
+    const done = () => setArrived(true);
+    const look = () => {
+      if (settle !== undefined) clearTimeout(settle);
+      settle = element.childElementCount > 0 ? setTimeout(done, FORM_SETTLE_MS) : undefined;
+    };
+    const patience = setTimeout(done, FORM_PATIENCE_MS);
+    const view = element.ownerDocument.defaultView;
+    const watch = view?.MutationObserver ? new view.MutationObserver(look) : null;
+    watch?.observe(element, { subtree: true, childList: true, characterData: true });
+    look();
+    return () => {
+      clearTimeout(patience);
+      if (settle !== undefined) clearTimeout(settle);
+      watch?.disconnect();
+    };
+  }, [host, arrived]);
+  return arrived;
+}
+
+/** the block's own form, mounted, with the editor's reference pickers beside its fields */
+function HostedForm({ session, state, node, spec, header, readOnly = false, issues = [] }: {
+  session: EditingSession;
+  state: IEditingState;
+  node: IRefTreeNode;
+  spec: Parameters<typeof useMountedTree>[0];
+  header: ReactNode;
+  /** shown, not changed (a prefab's block): no reference pickers beside the fields */
+  readOnly?: boolean;
+  /** what the node's settings hold that its block does not take */
+  issues?: readonly INodeSettingsIssue[];
+}) {
+  const { ref, failed } = useMountedTree(spec);
+  const arrived = useFormArrived(ref);
+  const area = useRef<HTMLDivElement>(null);
+  // the gutter for the reference circles is kept only where a field can have one — known from the
+  // block's declaration, before the circles are measured in (no shift when they appear)
+  const refs = ensureRefsEditing(useDi(DI_CONTAINER_TOKEN));
+  const bindable = useSyncExternalStore(refs.subscribe, () => !readOnly && refs.bindable(node.reference).length > 0);
+  return (
+    <>
+      {header}
+      {/* on every tab: an issue of the styles is as much in the way as one of the words */}
+      <SettingsIssues issues={issues}
+                      container={area}
+                      onRemove={readOnly ? undefined : (path) => session.updateNodesSettings([{ nodeId: node.id, patch: removalPatch(node.settings ?? {}, path) }])} />
+      {failed && (
+        <Section tab="main">
+          <div className="settings__hint"
+               data-host-failed>Could not render this form</div>
+        </Section>
+      )}
+      <div className="settings__form"
+           ref={area}
+           data-bindable={bindable || undefined}
+           data-form-loading={arrived || failed ? undefined : ''}>
+        {/* the element the form's own application lives in — nothing of ours goes inside it; the
+            pickers are its siblings, in the gutter to the right. What the form leaves unnamed is
+            its main settings (settingsTabs.ts) */}
+        <div ref={ref}
+             className={FORM_HOST_CLASS} />
+        {readOnly ? null : (
+          <FieldRefs container={area}
+                     session={session}
+                     state={state}
+                     node={node} />
+        )}
+      </div>
+    </>
+  );
+}
+
+function NodeSettingsBody({ session, state }: { session: EditingSession; state: IEditingState }) {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  // what the workbench EXPOSES to hosted forms, in its own container — the form's side of the
+  // door is useSettingsDraft (PARENT_DI_TOKEN → SETTINGS_DRAFT_TOKEN)
+  ensureSettingsDraft(di, session);
+  // what a provider's form reads beside its draft: the author's views, the project's config
+  ensureEditorViews(di, session);
+  useFeedProjectConfig();
+  // the styler's theme variables: the themes around the node the form is about
+  useFeedThemeVariables(state);
+  const self = useComponent().reference;
+  // the media uploader the hosted forms find through the parent chain
+  ensureMediaUpload(di);
+  // shares the palette's cache entry (same token+input) — no extra request
+  const catalog = useServerAction({ token: listComponentsToken, input: {} });
+  const project = useProjectPrefabs();
+  // the settings draft reads a prefab's blocks through these trees
+  useFeedPrefabTrees(di, project);
+  const node = state.doc && state.selectedNodeId ? findNodeDoc(state.doc, state.selectedNodeId) : null;
+  // a PREFAB's own block selected on the page (prefabParts.ts): shown as its prefab holds it
+  const part = !node && state.doc && isPartId(state.selectedNodeId) ? prefabPartOf(state.doc, state.selectedNodeId, project.treeOf) : null;
+  const shown = node ?? part?.node ?? null;
+  const components: readonly ICatalogEntry[] = catalog.isSuccess() && catalog.serverData.ok
+    ? catalog.serverData.components
+    : [];
+  const entry = shown ? components.find((c) => c.id === shown.reference) : undefined;
+  // what the selected block holds that it does not take — by its catalog entry's schema, its raw
+  // settings (a reference stands where the block lets one stand)
+  const schemaOf = useMemo(() => blockSchemas(components), [components]);
+  const issues = useMemo(() => (node ? nodeSettingsIssues(node, schemaOf) : []), [node, schemaOf]);
+  // a block without a form of its own has no fields to mark — the plaque alone speaks
+  const noForm = useRef<HTMLDivElement>(null);
+  // a block with a newer version says so above its form (ADR-0061)
+  const { outdated } = useUpgrades(state.doc);
+  const outdatedNode = node ? outdated.find((o) => o.nodeId === node.id) : undefined;
+  const upgradeLine = outdatedNode ? (
+    <Section tab="main">
+      <UpgradeLine session={session}
+                   node={outdatedNode}
+                   readOnly={state.revision !== null} />
+    </Section>
+  ) : null;
+  // a block of a disconnected distribution has no form to show: the site leaves it out
+  const disconnection = useDisconnection();
+  const offNamespace = node && state.doc && node.id !== state.doc.id ? disconnectedOf(node.reference, disconnection.disabled) : null;
+  const hosted = Boolean(shown && state.doc && (part || shown.id !== state.doc.id) && entry?.hasEditor && !offNamespace);
+
+  // the root that will mount the form: the block's own library ships one → it renders its own
+  // blocks and their forms; otherwise ours
+  const rootReference = useMemo(() => (shown ? formRootOf(components, shown.reference, self) : null), [components, shown?.reference, self.namespace, self.version]);
+
+  const spec = useMemo(() => (hosted && shown && rootReference && state.selectedNodeId
+    ? {
+      rootReference,
+      tree: hostedPage(rootReference, [{
+        id: `settings-form-${state.selectedNodeId}`,
+        reference: shown.reference.replace('_t_component_', '_t_editor_'),
+        settings: { placement: 'settings' },
+        children: [],
+      }], hostFallbackOf(self)),
+    }
+    : null), [hosted, state.selectedNodeId, shown?.reference, rootReference, self.namespace, self.version]);
+
+  // which draft the shown selection belongs to — the anchor's identity, visible to tests
+  const anchorDraft = state.draftId ?? undefined;
+  if (state.doc && part) {
+    return (
+      <div className="settings"
+           data-test-id="settings"
+           data-settings-part={state.selectedNodeId}
+           data-settings-draft={anchorDraft}>
+        <PrefabPartNotice session={session}
+                          part={part} />
+        {/* what this page sets of the block — the fields the prefab opens (the prefab node's own
+            settings); a published revision sets nothing */}
+        <fieldset className="settings__fieldset"
+                  disabled={state.revision !== null}>
+          <Section tab="main">
+            <PrefabInstanceForm session={session}
+                                node={part.owner}
+                                prefab={part.prefab}
+                                only={part.node.id} />
+          </Section>
+        </fieldset>
+        {/* the block's own settings, as the prefab has them: shown, every control disabled */}
+        <fieldset className="settings__fieldset"
+                  disabled
+                  data-read-only>
+          {!entry ? (
+            <div className="settings__hint"
+                 data-form-loading="">Loading the blocks…</div>
+          ) : entry.hasEditor ? (
+            <HostedForm session={session}
+                        state={state}
+                        node={part.node}
+                        spec={spec}
+                        header={null}
+                        readOnly />
+          ) : (
+            <Section tab="main">
+              <div className="settings__hint">The block has no settings form</div>
+            </Section>
+          )}
+        </fieldset>
+      </div>
+    );
+  }
+  if (!state.doc || !node) {
+    return <div className="settings settings__hint"
+                data-test-id="settings"
+                data-settings-empty>Select a node in the Tree</div>;
+  }
+  // node-level ssr flag (SSR epic stage 4): the ROOT checkbox enables server rendering of the
+  // whole page; on any other node the checkbox opts its BRANCH out (ssr:false — cannot be
+  // re-enabled deeper, no islands). Unchecked → the field is removed from the doc.
+  const flags = node as { ssr?: boolean };
+  const isRoot = node.id === state.doc.id;
+  const ssrToggle = (
+    <Section tab="other">
+      <label className="settings__ssr">
+        <input type="checkbox"
+               data-test-id="settings-ssr-toggle"
+               data-settings-ssr={node.id}
+               checked={isRoot ? flags.ssr === true : flags.ssr === false}
+               onChange={(e) => session.setNodeSsr(
+                 node.id,
+                 e.target.checked ? (isRoot ? true : false) : undefined,
+               )} />
+        {isRoot ? 'Render the page on the server (SSR)' : 'Disable server rendering for this branch'}
+      </label>
+    </Section>
+  );
+  if (isRoot) {
+    // the root's block: the catalog's page roots (stamped isRoot by the build) and the editor's
+    // own generic root, which every workbench ships — the current one is listed even if the
+    // catalog does not know it (a library that left), so the select never lies
+    const fallback = `_ns_${self.namespace}_t_component_n_page_v_${self.version}`;
+    // a root at several deployed versions is told apart by its version
+    const several = (c: ICatalogEntry) => components.some((o) => o.isRoot && o.reference.name === c.reference.name && o.reference.namespace === c.reference.namespace && o.id !== c.id);
+    const roots = components.filter((c) => c.isRoot).map((c) => ({ id: c.id, label: several(c) ? `${c.reference.name} ${c.reference.version}` : c.reference.name }));
+    if (!roots.some((root) => root.id === fallback)) roots.push({ id: fallback, label: 'page (editor default)' });
+    if (!roots.some((root) => root.id === node.reference)) roots.push({ id: node.reference, label: node.reference });
+    return (
+      <div className="settings"
+           data-test-id="settings"
+           data-settings-root
+           data-settings-draft={anchorDraft}>
+        {upgradeLine}
+        {/* a page's root is a technicality next to its words (Other); a prefab's frame is what
+            the prefab is shown in, its first question (Main) */}
+        <Section tab={state.kind === 'prefabs' ? 'main' : 'other'}>
+          <label className="settings__root">
+            <span className="settings__root-label">{state.kind === 'prefabs' ? 'Frame' : 'Root component'}</span>
+            <select className="settings__root-select"
+                    data-test-id="settings-root-select"
+                    value={node.reference}
+                    onChange={(e) => session.setRootReference(e.target.value)}>
+              {roots.map((root) => (
+                <option key={root.id}
+                        value={root.id}>
+                  {root.label}
+                </option>
+              ))}
+            </select>
+            <span className="settings__root-hint">
+              {state.kind === 'prefabs'
+                ? 'What the prefab previews inside here; on a page, only its blocks are placed'
+                : 'The block the whole page renders inside — its shell, styles and scripts'}
+            </span>
+          </label>
+        </Section>
+        {ssrToggle}
+        <Section tab="main">
+          <PageMetaForm session={session}
+                        meta={state.doc.meta ?? {}} />
+        </Section>
+      </div>
+    );
+  }
+  if (offNamespace) {
+    const distributions = catalog.isSuccess() && catalog.serverData.ok ? catalog.serverData.distributions ?? [] : [];
+    return (
+      <div className="settings"
+           data-test-id="settings"
+           data-settings-disconnected={node.id}
+           data-settings-draft={anchorDraft}>
+        <Section tab="main">
+          <DisconnectedNotice session={session}
+                              nodeId={node.id}
+                              title={distributions.find((d) => d.namespace === offNamespace)?.title ?? offNamespace}
+                              readOnly={state.revision !== null}
+                              platformOrigin={disconnection.platformOrigin} />
+        </Section>
+      </div>
+    );
+  }
+  // a PREFAB placed on the page: its blocks are the prefab's — only the fields it opens are set here
+  if (unitOf(node.reference)) {
+    return (
+      <div className="settings"
+           data-test-id="settings"
+           data-settings-prefab={node.id}
+           data-settings-draft={anchorDraft}>
+        <Section tab="main">
+          <PrefabInstanceForm session={session}
+                              node={node}
+                              prefab={project.treeOf(node.reference)} />
+        </Section>
+      </div>
+    );
+  }
+  // in a prefab, a block's settings can be opened to the pages that place it
+  const openFields = state.kind === 'prefabs'
+    ? (
+      <Section tab="other">
+        <OpenFieldsForm session={session}
+                        doc={state.doc}
+                        node={node} />
+      </Section>
+    )
+    : null;
+  if (!entry) {
+    return <div className="settings settings__hint"
+                data-form-loading="">Loading the blocks…</div>;
+  }
+  if (!entry.hasEditor) {
+    return (
+      <div className="settings"
+           data-no-editor={node.reference}
+           data-settings-draft={anchorDraft}>
+        {upgradeLine}
+        {ssrToggle}
+        <SettingsIssues issues={issues}
+                        container={noForm}
+                        onRemove={state.revision !== null ? undefined : (path) => session.updateNodesSettings([{ nodeId: node.id, patch: removalPatch(node.settings ?? {}, path) }])} />
+        <Section tab="main">
+          <div className="settings__hint">The block has no settings form</div>
+        </Section>
+        {openFields}
+      </div>
+    );
+  }
+
+  return (
+    <div className="settings"
+         data-test-id="settings"
+         data-settings-form={node.id}
+         data-settings-draft={anchorDraft}>
+      <HostedForm session={session}
+                  state={state}
+                  node={node}
+                  spec={spec}
+                  issues={issues}
+                  header={(
+                    <>
+                      {upgradeLine}
+                      {ssrToggle}
+                      <AutoBindToggle session={session}
+                                      node={node} />
+                    </>
+                  )} />
+      {openFields}
+    </div>
+  );
+}
+
+/**
+ * The selected node's settings. A published revision is read-only (versions are immutable — the
+ * session refuses every edit), and the settings look it rather than look editable (the canvas
+ * toolbar already says why): everything sits in a DISABLED FIELDSET, and the browser disables every control inside it — the ssr flag, the
+ * meta, the reference pickers and the block's own mounted form alike, whatever binding drew it.
+ */
+export function NodeSettings({ session, state }: { session: EditingSession; state: IEditingState }) {
+  const readOnly = state.revision !== null;
+  return (
+    // a prefab's block is shown read-only anyway, and its ways on (to the prefab, to its node)
+    // lead out of the revision — they stay pressable (its body disables the rest itself)
+    <fieldset className="settings__fieldset"
+              disabled={readOnly && !isPartId(state.selectedNodeId)}
+              data-read-only={readOnly || undefined}>
+      <NodeSettingsBody session={session}
+                        state={state} />
+    </fieldset>
+  );
+}
+
+// ---- which host shows the settings --------------------------------------------------------
+
+/**
+ * How many settings PANELS the workbench has mounted. A workbench that still docks one keeps its
+ * forms there; otherwise the canvas shows them in a popover beside the selected block.
+ */
+export class SettingsPanels {
+  private count = 0;
+
+  private readonly listeners = new Set<() => void>();
+
+  readonly snapshot = (): number => this.count;
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /** a panel came up; the returned function is its going away */
+  mount(): () => void {
+    this.count += 1;
+    this.notify();
+    return () => {
+      this.count -= 1;
+      this.notify();
+    };
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners]) listener();
+  }
+}
+
+const SETTINGS_PANELS_TOKEN = new SingleDiToken<SettingsPanels>('EDITOR_SETTINGS_PANELS_TOKEN');
+
+export function ensureSettingsPanels(di: DiContainer): SettingsPanels {
+  if (!di.hasByToken(SETTINGS_PANELS_TOKEN)) di.registerValueOfToken(SETTINGS_PANELS_TOKEN, new SettingsPanels());
+  return di.getByToken(SETTINGS_PANELS_TOKEN);
+}