@mosetta/react 0.0.0-stage → 0.0.10

package/src/utils/previewSlots.tsx

@@ -0,0 +1,117 @@
+// SLOT DISCOVERY for the editor's preview.
+//
+// A slot is not declared anywhere ahead of time — it exists exactly when a module renders
+// `useChildren`, and only in the configuration where it does. That is a feature: the editor must
+// offer an insertion point where one truly is, not where a manifest once promised it. But nothing
+// observable comes out of a hook call, so under preview each rendered slot also plants a MARKER:
+// an empty anchor that registers itself here on mount and takes itself off on unmount. Whatever is
+// registered right now IS the set of places a block can go.
+//
+// Nothing of this happens outside preview: the registry stays disarmed, `useChildren` returns the
+// children and not a thing more, and production pages carry no markers at all.
+//
+// ARMING is deliberate, not automatic: the editor's agent arms the registry only after its channel
+// is open — that is, after mount. Markers appearing during the first client render would disagree
+// with the server's HTML and break hydration.
+import { useEffect } from 'react';
+
+/** what a module told the editor about a place it opened for children */
+export interface ISlotDeclaration {
+  /** the tree node whose module rendered the slot */
+  readonly ownerId: string;
+  readonly slot: string;
+  /** how many children fit — see IChildrenSlot */
+  readonly max: number | 'many';
+  readonly min: number;
+  /** how many the document has put there */
+  readonly filled: number;
+}
+
+/** the marker's identity in the DOM; the editor measures where the "+" should go by it */
+export const SLOT_ATTRIBUTE = 'data-mosetta-slot';
+
+export const slotKey = (ownerId: string, slot: string): string => `${ownerId}:${slot}`;
+
+class PreviewSlots {
+  private armed = false;
+
+  private readonly declarations = new Map<string, ISlotDeclaration>();
+
+  // two audiences, two subscriptions on purpose: `useChildren` only ever needs to know whether
+  // markers are wanted, and must NOT re-render every module on the page each time some other
+  // slot registers. The agent, which does want exactly that, subscribes to the declarations.
+  private readonly armedListeners = new Set<() => void>();
+
+  private readonly listeners = new Set<() => void>();
+
+  readonly isArmed = (): boolean => this.armed;
+
+  /** server snapshot: there are no markers in a server render, ever */
+  readonly neverArmed = (): boolean => false;
+
+  readonly subscribeArmed = (listener: () => void): (() => void) => {
+    this.armedListeners.add(listener);
+    return () => this.armedListeners.delete(listener);
+  };
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  /** the editor's agent is live — from now on rendered slots plant their markers */
+  arm(): void {
+    if (this.armed) return;
+    this.armed = true;
+    for (const listener of this.armedListeners) listener();
+  }
+
+  /** a slot is being rendered; the returned callback is its death notice */
+  register(declaration: ISlotDeclaration): () => void {
+    const key = slotKey(declaration.ownerId, declaration.slot);
+    this.declarations.set(key, declaration);
+    this.emit();
+    return () => {
+      // a re-registration under the same key may already have replaced it (settings edit) —
+      // only the current entry may remove itself
+      if (this.declarations.get(key) === declaration) {
+        this.declarations.delete(key);
+        this.emit();
+      }
+    };
+  }
+
+  /** the places a block can go, as of this moment */
+  list(): ISlotDeclaration[] {
+    return [...this.declarations.values()];
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
+export const previewSlots = new PreviewSlots();
+
+/**
+ * How tall the marker is when the module says nothing. A sizeless anchor was the first attempt —
+ * layout-neutral, but an empty slot then encloses nothing, and the editor had a "+" hovering over
+ * a hairline. A block of a few pixels gives every rendered slot something to see and aim at.
+ */
+export const DEFAULT_MARKER_HEIGHT = 15;
+
+/**
+ * The marker itself: an empty block at the exact spot where the next child would land. It exists
+ * only under an armed preview, so the room it takes is room in the EDITOR's view of the page,
+ * never in the published one.
+ */
+export function SlotMarker({ height, ...declaration }: ISlotDeclaration & { height?: number }) {
+  const { ownerId, slot, max, min, filled } = declaration;
+  useEffect(
+    () => previewSlots.register({ ownerId, slot, max, min, filled }),
+    [ownerId, slot, max, min, filled],
+  );
+  return <span aria-hidden="true"
+               {...{ [SLOT_ATTRIBUTE]: slotKey(ownerId, slot) }}
+               style={{ display: 'block', flex: '0 0 auto', minHeight: `${height ?? DEFAULT_MARKER_HEIGHT}px` }} />;
+}

package/src/utils/tileReference.ts

@@ -0,0 +1,59 @@
+// The canonical reference encoding, in one place: the parser (a full id string → its parts) and
+// the composer (parts → the css scope class, which IS the full id). Mirrors cli/runtime/naming —
+// the react binding only ever needs these two directions.
+import type { ITileReference } from '@mosetta/core';
+
+enum EModuleNameTokens {
+  NAMESPACE = '_ns_',
+  MODULE_TYPE = '_t_',
+  MODULE_NAME = '_n_',
+  MODULE_VERSION = '_v_',
+}
+
+enum EModuleNameRegexTokens {
+  MODULE_NAME = 'moduleName',
+  MODULE_TYPE = 'moduleType',
+  MODULE_VERSION = 'version',
+  MODULE_NAMESPACE = 'moduleNamespace',
+}
+
+const MODULE_NAME_REGEX = new RegExp([
+  '^',
+  `${EModuleNameTokens.NAMESPACE}(?<${EModuleNameRegexTokens.MODULE_NAMESPACE}>.+)`,
+  `${EModuleNameTokens.MODULE_TYPE}(?<${EModuleNameRegexTokens.MODULE_TYPE}>.+)`,
+  `${EModuleNameTokens.MODULE_NAME}(?<${EModuleNameRegexTokens.MODULE_NAME}>.+)`,
+  `${EModuleNameTokens.MODULE_VERSION}(?<${EModuleNameRegexTokens.MODULE_VERSION}>.+)`,
+  '$',
+].join(''));
+
+export function parseReference(reference: string): ITileReference {
+  const tokens = MODULE_NAME_REGEX.exec(reference)?.groups;
+
+  if (!tokens) {
+    throw new Error(`Invalid module reference: ${reference}`);
+  }
+
+  return {
+    namespace: tokens[EModuleNameRegexTokens.MODULE_NAMESPACE],
+    name: tokens[EModuleNameRegexTokens.MODULE_NAME],
+    version: tokens[EModuleNameRegexTokens.MODULE_VERSION],
+    type: tokens[EModuleNameRegexTokens.MODULE_TYPE],
+  };
+}
+
+/**
+ * The class a module's own css is scoped by — the one the renderer's scope host carries.
+ *
+ * Needed by any module that renders part of itself OUTSIDE its own subtree: a portal (an overlay,
+ * a popover, anything that must escape a scrolling panel) lands somewhere else in the document,
+ * where `.<reference> .thing` no longer matches and the markup arrives with no styles at all.
+ * Wrap what the portal renders in an element carrying this, and the module's css applies again.
+ */
+export function tileScopeClass({ namespace, name, type, version }: ITileReference): string {
+  return [
+    EModuleNameTokens.NAMESPACE, namespace,
+    EModuleNameTokens.MODULE_TYPE, type,
+    EModuleNameTokens.MODULE_NAME, name,
+    EModuleNameTokens.MODULE_VERSION, version,
+  ].join('');
+}

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../core/tsconfig.base.json"
+}