@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/content/publishModal.tsx

@@ -0,0 +1,92 @@
+// "Publish this?" — asked in a modal that names the publication: the revision goes by a name
+// in the versions list from then on (the draft's own words are offered, the author may say what
+// this publication was about instead). Portalled to the document body inside the hosting
+// module's scope class — the pages list and the canvas both ask, each with its own stylesheet.
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { tileScopeClass, useComponent } from '@mosetta/react';
+import { MAX_REVISION_TITLE } from '@mosetta/content';
+import './publishModal.css';
+
+export function PublishModal({ host, noun, route, suggested, live, publishing, error, onCancel, onConfirm }: {
+  /** the document the dialog goes into — the host module's own */
+  host: Document;
+  noun: string;
+  /** what is being published: the route, or a prefab's name */
+  route: string;
+  /** the name offered — the draft's words */
+  suggested: string;
+  /** the live revision this one replaces, or null for the first */
+  live: number | null;
+  publishing: boolean;
+  error: string | null;
+  onCancel: () => void;
+  onConfirm: (title: string) => void;
+}) {
+  const self = useComponent().reference;
+  const [title, setTitle] = useState(suggested);
+  const inputRef = useRef<HTMLInputElement>(null);
+  useEffect(() => {
+    inputRef.current?.focus();
+    inputRef.current?.select();
+  }, []);
+  return createPortal(
+    <div className={tileScopeClass(self)}
+         style={{ display: 'contents' }}>
+      <div className="publish-modal__overlay"
+           data-test-id="publish-modal"
+           onClick={() => {
+             if (!publishing) onCancel();
+           }}
+           onKeyDown={(e) => {
+             if (e.key === 'Escape' && !publishing) onCancel();
+           }}>
+        <div className="publish-modal"
+             role="dialog"
+             aria-label={`Publish this ${noun}`}
+             onClick={(e) => e.stopPropagation()}>
+          <div className="publish-modal__title">Publish {route}</div>
+          <div className="publish-modal__text">
+            {live !== null
+              ? `This draft becomes the live revision, in place of r${live}.`
+              : 'This draft becomes the live revision — the first one readers get.'}
+          </div>
+          <label className="publish-modal__label"
+                 htmlFor="publish-modal-title">Name this publication</label>
+          <input ref={inputRef}
+                 id="publish-modal-title"
+                 className="publish-modal__input"
+                 data-test-id="publish-modal-title"
+                 value={title}
+                 maxLength={MAX_REVISION_TITLE}
+                 spellCheck={false}
+                 disabled={publishing}
+                 onChange={(e) => setTitle(e.target.value)}
+                 onKeyDown={(e) => {
+                   if (e.key === 'Enter' && !publishing) onConfirm(title);
+                 }} />
+          <div className="publish-modal__hint">The name stays with the revision in the versions list — what this publication was about.</div>
+          {error ? <div className="publish-modal__error"
+                        data-test-id="publish-modal-error">{error}</div> : null}
+          <div className="publish-modal__buttons">
+            <button type="button"
+                    className="publish-modal__button"
+                    data-test-id="publish-modal-cancel"
+                    disabled={publishing}
+                    onClick={onCancel}>
+              Cancel
+            </button>
+            <button type="button"
+                    className="publish-modal__button publish-modal__button--primary"
+                    data-test-id="publish-modal-confirm"
+                    disabled={publishing}
+                    onClick={() => onConfirm(title)}>
+              {publishing ? 'Publishing…' : 'Publish'}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>,
+    host.body,
+  );
+}

package/tiles/content/refsEditing.ts

@@ -0,0 +1,412 @@
+// REFERENCES, the editor's half. A form edits VALUES; this turns its edits into document changes
+// when a field is a reference: the value is read through the provider's adapter, a write goes to
+// the provider node's settings, binding a field points it at a provider's key (an existing one
+// picked, or a fresh one holding the field's text). Plain logic over the session's document and
+// the modules loaded in this realm — the provider's adapter is the same code the page runs, loaded
+// here like the palette loads a specimen. ONE instance per workbench (ensureRefsEditing): every
+// host of settings — the canvas popover, a settings panel — shares what was loaded.
+import { SingleDiToken } from '@mosetta/di';
+import { unitOf } from '@mosetta/content/units';
+import type { DiContainer } from '@mosetta/di';
+import {
+  bindableFields,
+  canBind,
+  findRefProvider,
+  instanceRefProviders,
+  isRefValue,
+  TILES_HOLDER_TOKEN,
+  parseRef,
+  providerAddressOf,
+  reachableRefProviders,
+  refValue,
+  resolveRefs,
+  treeNodes,
+} from '@mosetta/runtime/client';
+import type { IBindableField, ITilesHolder, IRefContext, IRefEntry, IRefProviderDeclaration, IRefTreeNode, IRefValue, TBindableDeclaration } from '@mosetta/runtime/client';
+
+/** what a component module may declare about references */
+interface IReferenceDeclarations {
+  readonly provides?: IRefProviderDeclaration;
+  readonly bindable?: TBindableDeclaration;
+  /** its editor facet has a standing control for the canvas (see IComponentSide.editorChrome) */
+  readonly editorChrome?: boolean;
+}
+
+/** one node's settings change — what EditingSession.updateNodesSettings applies as one step */
+export interface ISettingsPatch {
+  readonly nodeId: string;
+  readonly patch: Record<string, unknown>;
+}
+
+/** a node's id within its own document — an expanded prefab's nodes carry their place's id in front */
+const localId = (id: string): string => id.slice(id.lastIndexOf('/') + 1);
+
+/** a provider as a field's picker shows it */
+export interface IRefOption {
+  /** how the reference addresses it: the role (`i18n`), or the instance (`#prices`) */
+  readonly name: string;
+  readonly nodeId: string;
+  /** where it sits, in words the author recognizes */
+  readonly where: string;
+  readonly entries: readonly IRefEntry[];
+  /** it can keep a NEW value — the field's current text becomes one of its keys */
+  readonly canCreate: boolean;
+  /** key → the nodes in its scope that read it (`hero-title`, `hero-image.alt`) */
+  readonly usedBy: Readonly<Record<string, readonly string[]>>;
+}
+
+type TViews = Readonly<Record<string, unknown>>;
+
+// a live unit (a layout, a distribution's prefab) is a reference to a tree, not a component module
+const isUnit = (reference: string): boolean => unitOf(reference) !== null;
+
+const ctxOf = (views: TViews, name: string): IRefContext => ({ view: views[name] ?? null, route: null });
+
+const shortNameOf = (reference: string): string => /_n_(.+?)_v_/.exec(reference)?.[1] ?? reference;
+
+export class RefsEditing {
+  private readonly pending = new Set<string>();
+
+  private readonly failed = new Set<string>();
+
+  private readonly listeners = new Set<() => void>();
+
+  constructor(private readonly holder: ITilesHolder | null) {}
+
+  /** told when a module this realm was loading arrived — whatever was resolved may now differ */
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /**
+   * What a component module declares, when it is loaded in this realm; a module not loaded yet
+   * starts loading and answers nothing until then (subscribers are told when to ask again).
+   */
+  declarations(reference: string): IReferenceDeclarations | null {
+    if (!this.holder || isUnit(reference) || this.failed.has(reference)) return null;
+    let loaded: { module?: unknown; error?: unknown } | undefined;
+    try {
+      loaded = this.holder.getModule(reference);
+    } catch {
+      loaded = undefined;
+    }
+    if (loaded?.module) return loaded.module;
+    if (loaded?.error) return null;
+    if (this.holder.loadModule && !this.pending.has(reference)) {
+      this.pending.add(reference);
+      void this.holder.loadModule(reference)
+        .then((module) => {
+          if (module?.error) this.failed.add(reference);
+        }, () => {
+          this.failed.add(reference);
+        })
+        .finally(() => {
+          this.pending.delete(reference);
+          for (const listener of [...this.listeners]) listener();
+        });
+    }
+    return null;
+  }
+
+  /** the settings a block declares may be references */
+  bindable(reference: string): readonly string[] {
+    return this.bindableFields(reference).map(({ field }) => field);
+  }
+
+  /** …each with the type of what it holds (null: declared without one) */
+  bindableFields(reference: string): readonly IBindableField[] {
+    return bindableFields(this.declarations(reference)?.bindable);
+  }
+
+  /** the type a field of a block holds — null when undeclared, or not a bindable field at all */
+  private typeOf(reference: string, field: string): IBindableField['type'] {
+    return this.bindableFields(reference).find((entry) => entry.field === field)?.type ?? null;
+  }
+
+  /** every component module of the tree loaded — what a scope-wide operation must wait for */
+  async loadAll(doc: IRefTreeNode): Promise<void> {
+    const references = new Set<string>();
+    for (const node of treeNodes(doc)) {
+      if (!isUnit(node.reference)) references.add(node.reference);
+    }
+    await Promise.all([...references].map(async (reference) => {
+      if (this.declarations(reference) || !this.holder?.loadModule) return;
+      await this.holder.loadModule(reference).catch(() => undefined);
+    }));
+  }
+
+  private readonly provides = (reference: string): IRefProviderDeclaration | null => this.declarations(reference)?.provides ?? null;
+
+  read(doc: IRefTreeNode, nodeId: string, ref: IRefValue, views: TViews): unknown {
+    const parsed = parseRef(ref.$ref);
+    if (!parsed) return undefined;
+    const found = findRefProvider(doc, nodeId, parsed.name, this.provides);
+    if (!found) return undefined;
+    try {
+      return found.provides.refs.read(found.node.settings ?? {}, parsed.key, ctxOf(views, parsed.name));
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** the node's settings with every reference read — what a form shows */
+  resolve(doc: IRefTreeNode, nodeId: string, settings: Record<string, unknown>, views: TViews): Record<string, unknown> {
+    return resolveRefs(settings, (ref) => this.read(doc, nodeId, ref, views));
+  }
+
+  /**
+   * A form's patch as document changes: literal fields change the node itself, a field bound to
+   * a provider changes the provider's settings through its adapter. A bound field whose provider
+   * is gone becomes a literal — the author's words are never dropped.
+   */
+  writePatches(doc: IRefTreeNode, nodeId: string, settings: Record<string, unknown>, patch: Record<string, unknown>, views: TViews): ISettingsPatch[] {
+    const own: Record<string, unknown> = {};
+    const providers = new Map<string, { node: IRefTreeNode; settings: Record<string, unknown> }>();
+    for (const [field, value] of Object.entries(patch)) {
+      const current = settings[field];
+      const parsed = isRefValue(current) ? parseRef(current.$ref) : null;
+      const found = parsed ? findRefProvider(doc, nodeId, parsed.name, this.provides) : null;
+      if (!parsed || !found) {
+        own[field] = value;
+        continue;
+      }
+      const held = providers.get(found.node.id) ?? { node: found.node, settings: found.node.settings ?? {} };
+      held.settings = found.provides.refs.write(held.settings, parsed.key, value, ctxOf(views, parsed.name));
+      providers.set(found.node.id, held);
+    }
+    return [
+      ...(Object.keys(own).length ? [{ nodeId, patch: own }] : []),
+      ...[...providers.values()].map(({ node, settings: next }) => ({ nodeId: node.id, patch: next })),
+    ];
+  }
+
+  /**
+   * Every provider a node's field could point at: the nearest of each role, then the instances of
+   * its document — of them, with a `field` named, only those whose type the field's admits (a
+   * provider of words is no source for an address).
+   */
+  private candidates(doc: IRefTreeNode, nodeId: string, field?: string) {
+    const all = [...reachableRefProviders(doc, nodeId, this.provides), ...instanceRefProviders(doc, nodeId, this.provides)];
+    if (field === undefined) return all;
+    const node = [...treeNodes(doc)].find((candidate) => candidate.id === nodeId);
+    const fieldType = node ? this.typeOf(node.reference, field) : null;
+    return all.filter((found) => canBind(fieldType, found.provides.type, true));
+  }
+
+  /** the providers a node can point at, by address — for `field`, the ones of its type */
+  reachable(doc: IRefTreeNode, nodeId: string, field?: string): string[] {
+    return this.candidates(doc, nodeId, field).map((found) => found.name);
+  }
+
+  /** where a node sits, for a person: its parent's block name, or the page itself */
+  private whereOf(doc: IRefTreeNode, nodeId: string): string {
+    for (const node of treeNodes(doc)) {
+      if (!node.children?.some((child) => child.id === nodeId)) continue;
+      return node.id === doc.id ? 'page root' : `in ${shortNameOf(node.reference)}`;
+    }
+    return nodeId === doc.id ? 'the page' : '';
+  }
+
+  /** what a field's picker offers: every reachable provider of the field's type, with the values it hands out */
+  options(doc: IRefTreeNode, nodeId: string, views: TViews, field?: string): IRefOption[] {
+    return this.candidates(doc, nodeId, field).map((found) => {
+      let entries: readonly IRefEntry[] = [];
+      try {
+        entries = found.provides.refs.list?.(found.node.settings ?? {}, ctxOf(views, found.name)) ?? [];
+      } catch {
+        entries = [];
+      }
+      const usedBy: Record<string, string[]> = {};
+      for (const reader of this.scopeOf(doc, found.node, found.name)) {
+        for (const [setting, value] of Object.entries(reader.settings ?? {})) {
+          const parsed = isRefValue(value) ? parseRef(value.$ref) : null;
+          if (parsed?.name !== found.name) continue;
+          const where = `${localId(reader.id)}${setting === 'text' ? '' : `.${setting}`}`;
+          usedBy[parsed.key] = [...(usedBy[parsed.key] ?? []), where];
+        }
+      }
+      return {
+        name: found.name,
+        nodeId: found.node.id,
+        where: this.whereOf(doc, found.node.id),
+        entries,
+        canCreate: typeof found.provides.refs.create === 'function',
+        usedBy,
+      };
+    });
+  }
+
+  /**
+   * `field` becomes a reference to `name`: to `key` when one was picked, otherwise to a fresh key
+   * holding the value the field holds now (a provider that cannot keep new values answers nothing).
+   */
+  bindPatches(doc: IRefTreeNode, nodeId: string, settings: Record<string, unknown>, field: string, name: string, views: TViews, key?: string): ISettingsPatch[] {
+    const found = findRefProvider(doc, nodeId, name, this.provides);
+    if (!found) return [];
+    if (key !== undefined) return [{ nodeId, patch: { [field]: refValue(name, key) } }];
+    const create = found.provides.refs.create;
+    if (!create) return [];
+    // re-binding a field that already points somewhere starts from the text it SHOWS
+    const current = isRefValue(settings[field]) ? this.read(doc, nodeId, settings[field], {}) : settings[field];
+    const created = create(found.node.settings ?? {}, current, ctxOf(views, name), { node: localId(nodeId), setting: field });
+    return [
+      { nodeId: found.node.id, patch: created.settings },
+      { nodeId, patch: { [field]: refValue(name, created.key) } },
+    ];
+  }
+
+  /** `field` becomes a literal again, holding what it shows in the original (no view) */
+  unbindPatches(doc: IRefTreeNode, nodeId: string, settings: Record<string, unknown>, field: string): ISettingsPatch[] {
+    const current = settings[field];
+    if (!isRefValue(current)) return [];
+    return [{ nodeId, patch: { [field]: this.read(doc, nodeId, current, {}) ?? '' } }];
+  }
+
+  /** the provider node a bound field reads from — what the picker's "show" points at */
+  providerOf(doc: IRefTreeNode, nodeId: string, value: unknown): string | null {
+    const parsed = isRefValue(value) ? parseRef(value.$ref) : null;
+    return parsed ? findRefProvider(doc, nodeId, parsed.name, this.provides)?.node.id ?? null : null;
+  }
+
+  /** the nodes whose references named like `provider` resolve to it */
+  private scopeOf(doc: IRefTreeNode, provider: IRefTreeNode, name: string): IRefTreeNode[] {
+    const out: IRefTreeNode[] = [];
+    for (const node of treeNodes(doc)) {
+      if (node.id === provider.id) continue;
+      if (findRefProvider(doc, node.id, name, this.provides)?.node.id === provider.id) out.push(node);
+    }
+    return out;
+  }
+
+  private providerAt(doc: IRefTreeNode, providerId: string): { node: IRefTreeNode; provides: IRefProviderDeclaration; name: string } | null {
+    const node = [...treeNodes(doc)].find((candidate) => candidate.id === providerId);
+    const provides = node ? this.provides(node.reference) : null;
+    return node && provides ? { node, provides, name: providerAddressOf(provides, node.id) } : null;
+  }
+
+  /**
+   * Every non-empty literal a block in `providerId`'s scope declares `bindable` — of the
+   * provider's type (canBind: nobody looks at each field, so both must say the same type) —
+   * becomes a reference to it; the provider's own settings grow one key per field. Modules must
+   * be loaded (loadAll) for the declarations to be known; a provider that cannot keep new values
+   * binds nothing.
+   */
+  bindScopePatches(doc: IRefTreeNode, providerId: string, views: TViews): { patches: ISettingsPatch[]; bound: number } {
+    const provider = this.providerAt(doc, providerId);
+    const create = provider?.provides.refs.create;
+    if (!provider || !create) return { patches: [], bound: 0 };
+    let providerSettings = provider.node.settings ?? {};
+    const patches: ISettingsPatch[] = [];
+    let bound = 0;
+    for (const node of this.scopeOf(doc, provider.node, provider.name)) {
+      const patch: Record<string, unknown> = {};
+      for (const { field, type } of this.bindableFields(node.reference)) {
+        if (!canBind(type, provider.provides.type, false)) continue;
+        const value = node.settings?.[field];
+        if (typeof value !== 'string' || !value.trim()) continue;
+        const created = create(providerSettings, value, ctxOf(views, provider.name), { node: localId(node.id), setting: field });
+        providerSettings = created.settings;
+        patch[field] = refValue(provider.name, created.key);
+        bound += 1;
+      }
+      if (Object.keys(patch).length) patches.push({ nodeId: node.id, patch });
+    }
+    if (bound) patches.unshift({ nodeId: providerId, patch: providerSettings });
+    return { patches, bound };
+  }
+
+  /**
+   * The keys of `providerId`'s values its scope references, in the page's order, each with WHAT
+   * reads it — the block and its setting (`heading · text`, `button · text`): what a translator
+   * needs to know about a string besides the string.
+   */
+  outline(doc: IRefTreeNode, providerId: string): { key: string; role: string; nodes: string[] }[] {
+    const provider = this.providerAt(doc, providerId);
+    if (!provider) return [];
+    const roles = new Map<string, { roles: string[]; nodes: string[] }>();
+    for (const node of this.scopeOf(doc, provider.node, provider.name)) {
+      const block = /_n_(.+?)_v_/.exec(node.reference)?.[1] ?? 'block';
+      for (const [field, value] of Object.entries(node.settings ?? {})) {
+        const parsed = isRefValue(value) ? parseRef(value.$ref) : null;
+        if (parsed?.name !== provider.name) continue;
+        const role = `${block} · ${field}`;
+        const known = roles.get(parsed.key) ?? { roles: [], nodes: [] };
+        if (!known.roles.includes(role)) known.roles.push(role);
+        if (!known.nodes.includes(node.id)) known.nodes.push(node.id);
+        roles.set(parsed.key, known);
+      }
+    }
+    // the nodes that read a key — where to point the author when its words are missing somewhere
+    return [...roles].map(([key, { roles: list, nodes }]) => ({ key, role: list.join(', '), nodes }));
+  }
+
+  /**
+   * The links blocks that just ARRIVED (inserted, pasted — `arrived` and everything under them)
+   * get from the providers around them that take new blocks under their wing (a node's
+   * `autoBind`): each non-empty literal of a bindable field goes to the nearest such provider of
+   * its type, as a fresh key. Modules must be loaded (loadAll); what is not known is left alone.
+   */
+  autoBindPatches(doc: IRefTreeNode, arrived: readonly string[], views: TViews): ISettingsPatch[] {
+    const nodes = new Map<string, IRefTreeNode>();
+    for (const id of arrived) {
+      const top = [...treeNodes(doc)].find((candidate) => candidate.id === id);
+      if (top) for (const node of treeNodes(top)) nodes.set(node.id, node);
+    }
+    const providerSettings = new Map<string, Record<string, unknown>>();
+    const patches: ISettingsPatch[] = [];
+    for (const node of nodes.values()) {
+      const fields = this.bindableFields(node.reference);
+      if (!fields.length) continue;
+      // the providers this node reaches that take new blocks — nearest first, as the lookup orders them
+      const keepers = reachableRefProviders(doc, node.id, this.provides)
+        .filter((found) => (found.node as { autoBind?: boolean }).autoBind === true && typeof found.provides.refs.create === 'function');
+      if (!keepers.length) continue;
+      const patch: Record<string, unknown> = {};
+      for (const { field, type } of fields) {
+        const value = node.settings?.[field];
+        if (typeof value !== 'string' || !value.trim()) continue;
+        const keeper = keepers.find((found) => canBind(type, found.provides.type, false));
+        if (!keeper) continue;
+        const before = providerSettings.get(keeper.node.id) ?? keeper.node.settings ?? {};
+        const created = keeper.provides.refs.create!(before, value, ctxOf(views, keeper.name), { node: localId(node.id), setting: field });
+        providerSettings.set(keeper.node.id, created.settings);
+        patch[field] = refValue(keeper.name, created.key);
+      }
+      if (Object.keys(patch).length) patches.push({ nodeId: node.id, patch });
+    }
+    return [...[...providerSettings].map(([nodeId, patch]) => ({ nodeId, patch })), ...patches];
+  }
+
+  /** whether a node provides references that can keep new values — what may take new blocks under its wing */
+  canKeep(reference: string): { readonly type: IBindableField['type'] } | null {
+    const provides = this.provides(reference);
+    return provides && typeof provides.refs.create === 'function' ? { type: provides.type ?? null } : null;
+  }
+
+  /** the keys of `providerId`'s values that some node in its scope references */
+  usedKeys(doc: IRefTreeNode, providerId: string): string[] {
+    const provider = this.providerAt(doc, providerId);
+    if (!provider) return [];
+    const keys = new Set<string>();
+    for (const node of this.scopeOf(doc, provider.node, provider.name)) {
+      for (const value of Object.values(node.settings ?? {})) {
+        const parsed = isRefValue(value) ? parseRef(value.$ref) : null;
+        if (parsed?.name === provider.name) keys.add(parsed.key);
+      }
+    }
+    return [...keys];
+  }
+}
+
+const REFS_EDITING_TOKEN = new SingleDiToken<RefsEditing>('EDITOR_REFS_EDITING_TOKEN');
+
+/** the workbench's one reference editor — the modules it loaded are shared by every host */
+export function ensureRefsEditing(di: DiContainer): RefsEditing {
+  if (!di.hasByToken(REFS_EDITING_TOKEN)) {
+    di.registerValueOfToken(REFS_EDITING_TOKEN, new RefsEditing(di.hasByToken(TILES_HOLDER_TOKEN) ? di.getByToken(TILES_HOLDER_TOKEN) : null));
+  }
+  return di.getByToken(REFS_EDITING_TOKEN);
+}

package/tiles/content/scaledStage.ts

@@ -0,0 +1,63 @@
+// A LIVE SPECIMEN in a card (the Distributions wall, a block's variants): the block's application
+// mounted once the card comes into sight — a wall of applications all mounted at once would be paid
+// for blocks nobody scrolls to — laid out at a stage width and scaled to the card's.
+import { useEffect, useState } from 'react';
+import type { RefObject } from 'react';
+import type { DiContainer } from '@mosetta/di';
+import { useMountedTree } from './useMountedTree';
+import type { IMountSpec } from './mountedTree';
+
+/** the width a specimen is laid out at — the card shows it scaled to its own width */
+export const STAGE_WIDTH = 520;
+
+/** whether the element has come into sight (with a margin) — once seen, always seen */
+export function useSeen(element: RefObject<HTMLElement | null>): boolean {
+  const [seen, setSeen] = useState(false);
+  useEffect(() => {
+    const target = element.current;
+    if (!target || seen) return undefined;
+    const view = target.ownerDocument.defaultView;
+    if (!view?.IntersectionObserver) {
+      setSeen(true);
+      return undefined;
+    }
+    const watch = new view.IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) setSeen(true);
+    }, { rootMargin: '200px' });
+    watch.observe(target);
+    return () => watch.disconnect();
+  }, [element, seen]);
+  return seen;
+}
+
+/**
+ * The specimen's application in the stage the returned ref points at, laid out at `STAGE_WIDTH` and
+ * scaled to `card`'s width: the scale to apply, and the height the card should give it.
+ */
+export function useScaledStage(card: RefObject<HTMLElement | null>, spec: IMountSpec | null, parentDi?: DiContainer): {
+  stage: React.MutableRefObject<HTMLDivElement | null>;
+  failed: boolean;
+  scale: number;
+  height: number;
+} {
+  const { ref: stage, failed } = useMountedTree(spec, parentDi);
+  const [scale, setScale] = useState(0.5);
+  const [height, setHeight] = useState(0);
+  const mounted = spec !== null;
+  useEffect(() => {
+    const frame = card.current;
+    const element = stage.current;
+    if (!frame || !element || typeof ResizeObserver === 'undefined') return undefined;
+    const measure = () => {
+      const next = Math.min(1, frame.clientWidth / STAGE_WIDTH);
+      setScale(next);
+      setHeight(element.scrollHeight * next);
+    };
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    observer.observe(frame);
+    measure();
+    return () => observer.disconnect();
+  }, [card, stage, mounted]);
+  return { stage, failed, scale, height };
+}

package/tiles/content/searchField.css

@@ -0,0 +1,32 @@
+/* The search field: the glass sits over the input's left padding, out of the pointer's way. The
+   wrapper is a flex row standing where the input stood (the input keeps its own class and
+   sizing); the input only makes room on the left. */
+.search-field {
+  position: relative;
+  display: flex;
+  align-items: center;
+  flex: 1;
+  min-width: 0;
+}
+
+.search-field > input {
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+  padding-left: 28px !important;
+}
+
+.search-field__glass {
+  position: absolute;
+  top: 50%;
+  left: 9px;
+  display: flex;
+  transform: translateY(-50%);
+  color: #a1a1aa;
+  pointer-events: none;
+}
+
+.search-field__glass svg {
+  width: var(--mosetta-wb-icon-sm, 12px);
+  height: var(--mosetta-wb-icon-sm, 12px);
+}

package/tiles/content/searchField.tsx

@@ -0,0 +1,32 @@
+// A SEARCH FIELD: the input the caller gives, with a magnifying glass in its left corner — the
+// one sign every search box wears (the pages, the blocks, the reference values). The wrapper
+// takes the input's place in the layout; the input keeps its own class and gets the room for
+// the glass from the shared stylesheet.
+import type { ReactNode } from 'react';
+import './searchField.css';
+
+const GlassIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <circle cx="7"
+            cy="7"
+            r="4.2"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.5" />
+    <path d="M10.2 10.2L13.5 13.5"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.6"
+          strokeLinecap="round" />
+  </svg>
+);
+
+export function SearchField({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <span className={`search-field${className ? ` ${className}` : ''}`}>
+      <span className="search-field__glass">{GlassIcon}</span>
+      {children}
+    </span>
+  );
+}