@mosetta/runtime 0.0.0-stage → 0.0.9

package/src/client/pageManager.ts

@@ -0,0 +1,55 @@
+import { DiService, SingleDiToken } from '@mosetta/di';
+import type { IBlueprint } from '@mosetta/core';
+
+// moved here from the legacy @mosetta/page package (its node-SSR remainder is deleted) —
+// the page manager is a client-runtime concern; the react hook (usePage) lives in the binding
+// (@mosetta/react), the manager itself is framework-agnostic.
+//
+// The page is MUTABLE and observable. Not for navigation — a route change means a new document and
+// a new closure — but for LIVE COMPOSITION: the editor's preview swaps the tree under an already
+// mounted application instead of reloading the frame around it, and everything the realm has built
+// up (loaded modules, the server-action cache, whatever a module holds in state) survives the
+// swap. Outside that one use the page is set at birth and never moves.
+export abstract class PageManager {
+  abstract getCurrentPageImpl(): IBlueprint;
+
+  getCurrentPage(): IBlueprint {
+    return this.getCurrentPageImpl();
+  }
+
+  /** render this tree from now on; subscribers are told */
+  abstract setCurrentPage(page: IBlueprint): void;
+
+  /** the useSyncExternalStore contract — the returned function unsubscribes */
+  abstract subscribe(listener: () => void): () => void;
+}
+
+export const PAGE_MANAGER_TOKEN = new SingleDiToken<PageManager>('PAGE_MANAGER_TOKEN');
+
+@DiService(PAGE_MANAGER_TOKEN)
+export class DefaultPageManager extends PageManager {
+  private readonly listeners = new Set<() => void>();
+
+  constructor(private page: IBlueprint) {
+    super();
+  }
+
+  getCurrentPageImpl(): IBlueprint {
+    return this.page;
+  }
+
+  setCurrentPage(page: IBlueprint): void {
+    if (page === this.page) return; // snapshots are compared by identity — this would be a lie
+    this.page = page;
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  // an arrow property rather than a method: useSyncExternalStore resubscribes whenever the
+  // function it was handed changes identity
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+}

package/src/client/refs.ts

@@ -0,0 +1,319 @@
+import { SingleDiToken } from '@mosetta/di';
+import type { IRouteMatch } from '@mosetta/core';
+
+// REFERENCES IN SETTINGS. A setting's value may be a literal or a reference to a value another
+// block hands out: `{ "$ref": "i18n/k3" }` — provider name, slash, key. The block that hands it
+// out is the PROVIDER: it declares a name and an adapter over its own settings in its module
+// definition, and the same adapter answers in the page (resolution while rendering) and in the
+// editor (a form reading and writing through the reference). This file is the framework-agnostic
+// half: the value shape, the adapter contract and where a reference looks for its provider.
+
+/** a setting that points at a value a provider hands out */
+export interface IRefValue {
+  readonly $ref: string;
+}
+
+export const isRefValue = (value: unknown): value is IRefValue => typeof value === 'object'
+  && value !== null
+  && !Array.isArray(value)
+  && typeof (value as { $ref?: unknown }).$ref === 'string';
+
+export const refValue = (name: string, key: string): IRefValue => ({ $ref: `${name}/${key}` });
+
+/** `i18n/k3` → { name: 'i18n', key: 'k3' }; anything without both halves is not a reference */
+export function parseRef(ref: string): { readonly name: string; readonly key: string } | null {
+  const at = ref.indexOf('/');
+  if (at <= 0 || at === ref.length - 1) return null;
+  return { name: ref.slice(0, at), key: ref.slice(at + 1) };
+}
+
+/**
+ * What a provider reads a value against: the VIEW the editor chose for it (i18n: which language
+ * is being edited — null outside the editor) and the ROUTE of the request (null in the editor).
+ */
+export interface IRefContext {
+  readonly view: unknown;
+  readonly route: IRouteMatch | null;
+}
+
+/** one value a provider offers for picking: its key, what a person recognizes it by, and the value */
+export interface IRefEntry {
+  readonly key: string;
+  readonly label: string;
+  readonly value: unknown;
+}
+
+/**
+ * A provider's values, as pure functions over its OWN settings. Pure on purpose: the page runs
+ * them while rendering, the editor runs them on the document it holds — one code, two realms.
+ */
+/** where a value a provider is asked to keep comes from: a node's setting */
+export interface IRefOrigin {
+  readonly node: string;
+  readonly setting: string;
+}
+
+export interface IRefAdapter<TSettings = Record<string, unknown>> {
+  read(settings: TSettings, key: string, ctx: IRefContext): unknown;
+  /** the provider's settings with `key` holding `value` */
+  write(settings: TSettings, key: string, value: unknown, ctx: IRefContext): TSettings;
+  /**
+   * A fresh key holding `value` — how a literal setting becomes a reference to a value the
+   * provider will now keep (i18n). `origin` — the node and setting the value comes from, for a
+   * key a person recognizes (`hero-title`). Absent: the provider only hands out values it has.
+   */
+  create?(settings: TSettings, value: unknown, ctx: IRefContext, origin?: IRefOrigin): { readonly settings: TSettings; readonly key: string };
+  /** the values a person may pick from (the editor's reference picker) */
+  list?(settings: TSettings, ctx: IRefContext): readonly IRefEntry[];
+}
+
+/**
+ * What a component module declares to become a provider (`provides` in its definition). Two ways
+ * to be addressed, the provider's choice:
+ * - by ROLE (`addressedBy: 'name'`, the default): `i18n/t3` means "the nearest i18n around me" —
+ *   a block copied to another page, or living in a layout or a prefab, finds that page's provider;
+ * - by INSTANCE (`addressedBy: 'id'`): `#prices/pro` means "the node `prices` of this document" —
+ *   three tables of one kind on a page are three different things to point at.
+ */
+export interface IRefProviderDeclaration<TSettings = Record<string, unknown>> {
+  /** the role name references use (`<name>/<key>`) */
+  readonly name: string;
+  readonly addressedBy?: 'name' | 'id';
+  readonly refs: IRefAdapter<TSettings>;
+  /**
+   * The TYPE of the values it hands out (`'text'` — words a person reads: i18n). A field declared
+   * bindable with a type is offered only providers of that type, and only such fields are linked
+   * to it in bulk or automatically (bindableFields, canBind). Absent: a provider of anything.
+   */
+  readonly type?: TBindableType;
+}
+
+/**
+ * What a setting holds, as far as references go — the tag that matches a field to the providers
+ * that can feed it: `'text'` (words a person reads, translatable), or a kind of the provider's
+ * own naming (`'url'`, `'image'`, …).
+ */
+export type TBindableType = 'text' | (string & {});
+
+/**
+ * Which settings of a block may be references, as its module declares them (`bindable`): a map
+ * of setting → type, or — the first form, kept working — a list of settings of no declared type.
+ */
+export type TBindableDeclaration = readonly string[] | Readonly<Record<string, TBindableType>>;
+
+/** one bindable setting and its type — null for a setting declared without one */
+export interface IBindableField {
+  readonly field: string;
+  readonly type: TBindableType | null;
+}
+
+/** a module's bindable declaration as fields with their types */
+export function bindableFields(declaration: TBindableDeclaration | undefined): IBindableField[] {
+  if (!declaration) return [];
+  if (Array.isArray(declaration)) return (declaration as readonly string[]).map((field) => ({ field, type: null }));
+  return Object.entries(declaration as Readonly<Record<string, TBindableType>>).map(([field, type]) => ({ field, type }));
+}
+
+/**
+ * Whether a field may be bound to a provider. `manual` — the author picking one in a field's
+ * picker: anything not known to differ (a side without a type takes any). Otherwise — linking in
+ * bulk or automatically, nobody looking at each field: both sides must SAY the same type, so a
+ * provider of words never takes an address, a colour or a count.
+ */
+export function canBind(fieldType: TBindableType | null, providerType: TBindableType | undefined, manual: boolean): boolean {
+  if (manual) return !fieldType || !providerType || fieldType === providerType;
+  return fieldType !== null && providerType !== undefined && fieldType === providerType;
+}
+
+/** the part of a tree node the lookup reads */
+export interface IRefTreeNode {
+  readonly id: string;
+  readonly reference: string;
+  readonly settings?: Record<string, unknown>;
+  readonly children?: readonly IRefTreeNode[];
+}
+
+/**
+ * The document a node belongs to. A layout's blocks are expanded into the page with their ids
+ * prefixed by the layout node's id (`n1/hdr`, see the content package's unit expansion), a page's
+ * own blocks keep bare ids. References never cross documents: an article's words are stored in
+ * the article, a layout's in the layout.
+ */
+export const documentOf = (id: string): string => {
+  const at = id.indexOf('/');
+  return at > 0 ? id.slice(0, at) : '';
+};
+
+/** an instance address: `#<node id>` */
+export const INSTANCE_REF_PREFIX = '#';
+
+/** how a reference names this provider node: its role, or `#<id>` (the id inside its own document) */
+export function providerAddressOf(declaration: IRefProviderDeclaration, nodeId: string): string {
+  if (declaration.addressedBy !== 'id') return declaration.name;
+  const doc = documentOf(nodeId);
+  return `${INSTANCE_REF_PREFIX}${doc ? nodeId.slice(doc.length + 1) : nodeId}`;
+}
+
+const parentMaps = new WeakMap<IRefTreeNode, Map<string, IRefTreeNode>>();
+
+function parentsOf(root: IRefTreeNode): Map<string, IRefTreeNode> {
+  let parents = parentMaps.get(root);
+  if (!parents) {
+    parents = new Map();
+    const walk = (node: IRefTreeNode) => {
+      for (const child of node.children ?? []) {
+        parents!.set(child.id, node);
+        walk(child);
+      }
+    };
+    walk(root);
+    parentMaps.set(root, parents);
+  }
+  return parents;
+}
+
+/** every node of the tree, depth first */
+export function* treeNodes(root: IRefTreeNode): Generator<IRefTreeNode> {
+  yield root;
+  for (const child of root.children ?? []) yield* treeNodes(child);
+}
+
+export function findNode(root: IRefTreeNode, id: string): IRefTreeNode | null {
+  if (root.id === id) return root;
+  const parent = parentsOf(root).get(id);
+  return parent?.children?.find((child) => child.id === id) ?? null;
+}
+
+export interface IFoundProvider {
+  readonly node: IRefTreeNode;
+  readonly provides: IRefProviderDeclaration;
+  /** how a reference addresses it: the role, or `#<id>` */
+  readonly name: string;
+}
+
+/**
+ * Every provider `consumerId` can reach, nearest first, one per name. LEXICAL, by the document:
+ * a provider serves its parent's subtree (its siblings and everything under them) and its own;
+ * walking up from the consumer, the nearest level that holds a name wins it, children before
+ * the level's own node. Only providers of the consumer's own document count. A pure function of
+ * the tree — the same answer on the server, in the browser and in the editor, whatever order
+ * things render in.
+ */
+export function reachableRefProviders(
+  root: IRefTreeNode,
+  consumerId: string,
+  declarationOf: (reference: string) => IRefProviderDeclaration | null | undefined,
+  only?: string,
+): IFoundProvider[] {
+  const doc = documentOf(consumerId);
+  const parents = parentsOf(root);
+  const found: IFoundProvider[] = [];
+  const names = new Set<string>();
+  const consider = (node: IRefTreeNode): boolean => {
+    if (documentOf(node.id) !== doc) return false;
+    const declaration = declarationOf(node.reference);
+    // instance providers are addressed by id wherever they sit — not by the nearest-role walk
+    if (!declaration || declaration.addressedBy === 'id') return false;
+    const name = declaration.name;
+    if (names.has(name) || (only !== undefined && name !== only)) return false;
+    names.add(name);
+    found.push({ node, provides: declaration, name });
+    return only !== undefined;
+  };
+  let level: IRefTreeNode | null | undefined = findNode(root, consumerId);
+  let first = true;
+  while (level) {
+    for (const child of level.children ?? []) {
+      if (child.id !== consumerId && consider(child)) return found;
+    }
+    if (!first && consider(level)) return found;
+    first = false;
+    level = parents.get(level.id);
+  }
+  return found;
+}
+
+/**
+ * The provider a reference named `name` in `consumerId`'s settings resolves against: the nearest
+ * one playing that role, or — for `#<id>` — that node of the consumer's own document, wherever it
+ * sits, as long as it provides by instance.
+ */
+export function findRefProvider(
+  root: IRefTreeNode,
+  consumerId: string,
+  name: string,
+  declarationOf: (reference: string) => IRefProviderDeclaration | null | undefined,
+): IFoundProvider | null {
+  if (name.startsWith(INSTANCE_REF_PREFIX)) {
+    const doc = documentOf(consumerId);
+    const id = name.slice(INSTANCE_REF_PREFIX.length);
+    const node = findNode(root, doc ? `${doc}/${id}` : id);
+    const declaration = node ? declarationOf(node.reference) : null;
+    return node && declaration?.addressedBy === 'id' ? { node, provides: declaration, name } : null;
+  }
+  return reachableRefProviders(root, consumerId, declarationOf, name)[0] ?? null;
+}
+
+/** every instance-addressed provider of `consumerId`'s document — what a picker offers beside the reachable roles */
+export function instanceRefProviders(
+  root: IRefTreeNode,
+  consumerId: string,
+  declarationOf: (reference: string) => IRefProviderDeclaration | null | undefined,
+): IFoundProvider[] {
+  const doc = documentOf(consumerId);
+  const out: IFoundProvider[] = [];
+  for (const node of treeNodes(root)) {
+    if (node.id === consumerId || documentOf(node.id) !== doc) continue;
+    const declaration = declarationOf(node.reference);
+    if (declaration?.addressedBy === 'id') out.push({ node, provides: declaration, name: providerAddressOf(declaration, node.id) });
+  }
+  return out;
+}
+
+/** every reference in a settings object resolved (top-level values only); the same object when none */
+export function resolveRefs(
+  settings: Record<string, unknown>,
+  resolve: (ref: IRefValue) => unknown,
+): Record<string, unknown> {
+  let out: Record<string, unknown> | null = null;
+  for (const [field, value] of Object.entries(settings)) {
+    if (!isRefValue(value)) continue;
+    out ??= { ...settings };
+    out[field] = resolve(value);
+  }
+  return out ?? settings;
+}
+
+/**
+ * The views the editor chose for providers, by provider name (i18n → { lang: 'ru' }). Every
+ * application gets an empty store at birth; in a preview the editor's bridge fills it, on a live
+ * page it stays empty — every view is null there.
+ */
+export interface IRefViews {
+  snapshot(): Readonly<Record<string, unknown>>;
+  subscribe(listener: () => void): () => void;
+  set(views: Readonly<Record<string, unknown>>): void;
+}
+
+export const REF_VIEWS_TOKEN = new SingleDiToken<IRefViews>('REF_VIEWS_TOKEN');
+
+export class MemoryRefViews implements IRefViews {
+  private views: Readonly<Record<string, unknown>> = Object.freeze({});
+
+  private readonly listeners = new Set<() => void>();
+
+  readonly snapshot = (): Readonly<Record<string, unknown>> => this.views;
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  set(views: Readonly<Record<string, unknown>>): void {
+    if (views === this.views) return;
+    this.views = views;
+    for (const listener of [...this.listeners]) listener();
+  }
+}