@backmatter/studio 0.0.15 → 0.0.17

package/src/fields/choose-field-input.ts

@@ -0,0 +1,64 @@
+// packages/studio/src/fields/choose-field-input.ts
+import type { SchemaField } from "../api";
+import { resolveFieldInput, type StudioDefinition } from "../define-studio";
+
+export type FieldInputKind =
+  | "custom"
+  | "select"
+  | "color"
+  | "slider"
+  | "relation"
+  | "object"
+  | "array"
+  | "media"
+  | "boolean"
+  | "number"
+  | "blocks"
+  | "text";
+
+export function chooseFieldInput(
+  definition: StudioDefinition,
+  field: SchemaField,
+  models: Array<{ type: string; external?: boolean }>,
+): FieldInputKind {
+  if (resolveFieldInput(definition, field)) {
+    return "custom";
+  }
+
+  if (field.kind === "text") {
+    if (field.options && field.options.length > 0) {
+      return "select";
+    }
+    if (field.input === "color") {
+      return "color";
+    }
+  }
+
+  if (field.kind === "number") {
+    if (typeof field.min === "number" && typeof field.max === "number") {
+      return "slider";
+    }
+  }
+
+  if (field.kind === "relation") {
+    const target = models.find((m) => m.type === field.relationTo);
+    if (target && !target.external) {
+      return "relation";
+    }
+    return "text";
+  }
+
+  if (field.kind === "object") {
+    return "object";
+  }
+  if (field.kind === "array") {
+    return "array";
+  }
+
+  if (field.kind === "media") return "media";
+  if (field.kind === "boolean") return "boolean";
+  if (field.kind === "number") return "number";
+  if (field.kind === "blocks") return "blocks";
+
+  return "text";
+}

package/src/fields/load-relation-documents.ts

@@ -0,0 +1,35 @@
+// packages/studio/src/fields/load-relation-documents.ts
+type DocListRow = { type: string; slug: string; status: string };
+type DocEntry = { slug: string; frontmatter: Record<string, unknown> };
+
+export async function loadRelationDocuments(
+  types: string[],
+  list: () => Promise<DocListRow[]>,
+  read: (type: string, slug: string) => Promise<{ frontmatter: Record<string, unknown> }>,
+): Promise<Record<string, DocEntry[]>> {
+  const wanted = new Set(types);
+  const grouped: Record<string, DocEntry[]> = Object.fromEntries(types.map((type) => [type, []]));
+  let rows: DocListRow[];
+  try {
+    rows = await list();
+  } catch {
+    return grouped;
+  }
+
+  const selected = rows.filter((row) => wanted.has(row.type) && row.status !== "deleted");
+  const loaded = await Promise.all(
+    selected.map(async (row) => {
+      try {
+        const { frontmatter } = await read(row.type, row.slug);
+        return { type: row.type, entry: { slug: row.slug, frontmatter } satisfies DocEntry };
+      } catch {
+        return null;
+      }
+    }),
+  );
+  for (const item of loaded) {
+    if (!item) continue;
+    grouped[item.type]!.push(item.entry);
+  }
+  return grouped;
+}

package/src/fields/omit-field.ts

@@ -0,0 +1,12 @@
+// packages/studio/src/fields/omit-field.ts
+export function omitField(
+  record: Record<string, unknown>,
+  name: string,
+  next: unknown,
+): Record<string, unknown> {
+  if (next === undefined) {
+    const { [name]: _removed, ...rest } = record;
+    return rest;
+  }
+  return { ...record, [name]: next };
+}

package/src/fields/relation-targets.ts

@@ -0,0 +1,44 @@
+// packages/studio/src/fields/relation-targets.ts
+import type { SchemaField } from "../api";
+import { resolveObjectFields } from "./resolve-object-fields";
+
+type ModelRef = { type: string; external?: boolean };
+type ObjectDef = { name: string; fields: Record<string, SchemaField> };
+
+function collectFromFields(
+  fields: Record<string, SchemaField>,
+  models: ModelRef[],
+  objects: ObjectDef[],
+  visiting: Set<string>,
+  targets: Set<string>,
+): void {
+  for (const field of Object.values(fields)) {
+    if (field.kind === "relation" && field.relationTo) {
+      const target = models.find((model) => model.type === field.relationTo);
+      if (target && !target.external) {
+        targets.add(field.relationTo);
+      }
+    }
+
+    const nested = resolveObjectFields(field, objects);
+    if (!nested) continue;
+
+    let nextVisiting = visiting;
+    if (field.object && (field.kind === "object" || field.kind === "array")) {
+      if (visiting.has(field.object)) continue;
+      nextVisiting = new Set(visiting).add(field.object);
+    }
+
+    collectFromFields(nested, models, objects, nextVisiting, targets);
+  }
+}
+
+export function relationTargets(
+  fields: Record<string, SchemaField>,
+  models: ModelRef[],
+  objects: ObjectDef[],
+): string[] {
+  const targets = new Set<string>();
+  collectFromFields(fields, models, objects, new Set<string>(), targets);
+  return [...targets].sort();
+}

package/src/fields/resolve-object-fields.ts

@@ -0,0 +1,21 @@
+// packages/studio/src/fields/resolve-object-fields.ts
+import type { SchemaField } from "../api";
+
+export function resolveObjectFields(
+  field: SchemaField,
+  objects: Array<{ name: string; fields: Record<string, SchemaField> }>,
+): Record<string, SchemaField> | null {
+  if (field.fields) {
+    return field.fields;
+  }
+  if (field.object) {
+    const entry = objects.find((object) => object.name === field.object);
+    return entry?.fields ?? null;
+  }
+  return null;
+}
+
+export function nestedStartsCollapsed(ancestorObjectNames: string[], objectName: string | undefined): boolean {
+  if (!objectName) return false;
+  return ancestorObjectNames.includes(objectName);
+}

package/src/host-pointer-bootstrap.ts

@@ -0,0 +1,11 @@
+// packages/studio/src/host-pointer-bootstrap.ts
+// Built into the script the code session sandbox injects. The source of truth
+// is bindHostPointer, the same pointer the document editor's preview uses.
+import { bindHostPointer } from "./host-pointer";
+
+function start() {
+  bindHostPointer(document);
+}
+
+if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
+else start();

package/src/host-pointer.ts

@@ -0,0 +1,147 @@
+// packages/studio/src/host-pointer.ts
+//
+// Page side of the preview channel for a framed host that is not running the
+// preview client. The document editor's preview page uses the same pointer and
+// the same messages (hello, point, grab, highlight). This does not accept a
+// document push.
+import {
+  createWindowPreviewTransport,
+  samePreviewRef,
+  type PreviewChannelRef,
+  type PreviewWindowLike,
+} from "@backmatter/core/preview";
+import { installPreviewPointer } from "./install-preview-pointer";
+import { findPointedElement, highlightPointedElement } from "./site-pointer";
+
+const POINTER_STYLE = "html.backmatter-pointing, html.backmatter-pointing * { cursor: crosshair !important; }";
+
+function parentOrigin(view: Window): string {
+  try {
+    if (view.document.referrer) return new URL(view.document.referrer).origin;
+  } catch {
+    // A malformed referrer means we cannot name the framing Studio.
+  }
+  const ancestors = (view.location as Location & { ancestorOrigins?: DOMStringList }).ancestorOrigins;
+  if (ancestors && ancestors.length > 0) return ancestors.item(0) ?? "";
+  return "";
+}
+
+/** The document the page announces. A missing marker falls back to the route. */
+export function hostPointerRef(doc: Document): PreviewChannelRef {
+  const marker = doc.querySelector("[data-backmatter-doc]");
+  const type = marker?.getAttribute("data-type");
+  const slug = marker?.getAttribute("data-slug");
+  if (type && slug) return { type, slug };
+  const path = doc.defaultView?.location.pathname || "/";
+  return { type: "route", slug: path };
+}
+
+/**
+ * Tell the framing Studio this page can be pointed at, and arm when it asks.
+ * No-ops on a top-level page and on a page that already runs the preview client.
+ */
+export function bindHostPointer(doc: Document): () => void {
+  const view = doc.defaultView;
+  if (!view || view.parent === view) return () => {};
+  if (doc.querySelector("[data-backmatter-preview]")) return () => {};
+  const flagged = view as Window & { __backmatterHostPointer?: boolean };
+  if (flagged.__backmatterHostPointer) return () => {};
+
+  const origin = parentOrigin(view);
+  if (!origin) return () => {};
+  flagged.__backmatterHostPointer = true;
+
+  const ref = hostPointerRef(doc);
+  if (!doc.querySelector("[data-backmatter-pointer-style]")) {
+    const style = doc.createElement("style");
+    style.setAttribute("data-backmatter-pointer-style", "");
+    style.textContent = POINTER_STYLE;
+    doc.head.appendChild(style);
+  }
+
+  const transport = createWindowPreviewTransport({
+    target: view.parent,
+    targetOrigin: origin,
+    allowedOrigins: [origin],
+    host: view as unknown as PreviewWindowLike,
+  });
+    function sendGrab(grab: {
+      blockId: string | null;
+      blockType: string | null;
+      blockIndex: number | null;
+      quote: string;
+      shift: boolean;
+      component?: string | null;
+      file?: string | null;
+      line?: number | null;
+      column?: number | null;
+      stack?: string[];
+    }) {
+      transport.send({
+        type: "backmatter:grab",
+        v: 1,
+        ref,
+        blockId: grab.blockId,
+        blockType: grab.blockType,
+        blockIndex: grab.blockIndex,
+        quote: grab.quote,
+        shift: grab.shift,
+        ...(grab.component ? { component: grab.component } : {}),
+        ...(grab.file ? { file: grab.file } : {}),
+        ...(grab.line ? { line: grab.line } : {}),
+        ...(grab.column ? { column: grab.column } : {}),
+        ...(grab.stack && grab.stack.length > 0 ? { stack: grab.stack } : {}),
+      });
+    }
+    const pointer = installPreviewPointer(doc, {
+    bar: () => doc.querySelector("[data-backmatter-devbar]"),
+    includeUnmarked: true,
+    ignore: (target) => {
+      if (!(target instanceof view.Element)) return true;
+      if (target.closest("[data-backmatter-panel]")) return true;
+      return target.closest("iframe") !== null;
+    },
+    onEditorGrab: sendGrab,
+    onUnmarkedGrab: sendGrab,
+    onDevbarGrab: () => {},
+    onEscape: (source) => {
+      if (source !== "editor") return;
+      transport.send({ type: "backmatter:point", v: 1, ref, on: false });
+    },
+  });
+  const unsubscribe = transport.subscribe((message) => {
+    if (message.type === "backmatter:hotkey" || message.type === "backmatter:hello") return;
+    if (!("ref" in message)) return;
+    // Studio binds after the first hello on a reload. A message for another
+    // document is the cue to announce this page again.
+    if (!samePreviewRef(message.ref, ref)) {
+      if (message.type === "backmatter:point" || message.type === "backmatter:highlight") hello();
+      return;
+    }
+    if (message.type === "backmatter:point") {
+      if (message.on) pointer.arm("editor");
+      else if (pointer.source() === "editor") pointer.disarm();
+      return;
+    }
+    if (message.type === "backmatter:highlight") {
+      const target = message.blockId
+        ? findPointedElement(doc, { blockId: message.blockId, quote: "" })
+        : null;
+      highlightPointedElement(doc, target);
+    }
+  });
+
+  function hello() {
+    transport.send({ type: "backmatter:hello", v: 1, ref, capabilities: ["point"] });
+  }
+  hello();
+  const retries = [100, 500].map((ms) => view.setTimeout(hello, ms));
+
+  return () => {
+    for (const id of retries) view.clearTimeout(id);
+    unsubscribe();
+    pointer.dispose();
+    transport.close();
+    flagged.__backmatterHostPointer = false;
+  };
+}

package/src/install-preview-pointer.ts

@@ -8,12 +8,25 @@ import {
   type PointerGrab,
 } from "./site-pointer";
 
+function placeOf(grab: PointerGrab) {
+  return {
+    ...(grab.component ? { component: grab.component } : {}),
+    ...(grab.file ? { file: grab.file } : {}),
+    ...(grab.line ? { line: grab.line } : {}),
+    ...(grab.column ? { column: grab.column } : {}),
+    ...(grab.stack.length > 0 ? { stack: grab.stack } : {}),
+  };
+}
+
 export function installPreviewPointer(
   doc: Document,
   options: {
     bar: () => Element | null;
     ignore?: (target: EventTarget | null) => boolean;
-    onEditorGrab: (grab: RoutedGrab) => void;
+    /** Armed clicks that are not page blocks. The document editor leaves this off. */
+    includeUnmarked?: boolean;
+    onEditorGrab: (grab: RoutedGrab & ReturnType<typeof placeOf>) => void;
+    onUnmarkedGrab?: (grab: PointerGrab & { shift: boolean }) => void;
     onDevbarGrab: (grab: PointerGrab) => void;
     onEscape?: (source: PointerArmSource) => void;
   },
@@ -27,8 +40,11 @@ export function installPreviewPointer(
 
   function deliver(grab: PointerGrab, shift: boolean) {
     const route = routePointerHit(source, { ...grab, shift });
-    if (route.to === "editor") options.onEditorGrab(route.grab);
-    else if (route.to === "devbar") options.onDevbarGrab(route.grab);
+    if (route.to === "editor") options.onEditorGrab({ ...route.grab, ...placeOf(grab) });
+    else if (route.to === "devbar") options.onDevbarGrab(grab);
+    else if (options.includeUnmarked && source === "editor" && (grab.quote || grab.component || grab.file)) {
+      options.onUnmarkedGrab?.({ ...grab, shift });
+    }
   }
 
   const pointer = installSitePointer(doc, {

package/src/pages/BlockSettingsDialog.tsx

@@ -3,30 +3,32 @@ import { useState } from "react";
 import { Dialog } from "@base-ui/react/dialog";
 import * as stylex from "@stylexjs/stylex";
 import type { SchemaField } from "../api";
-import { useFieldInput } from "../define-studio";
+import { FieldControl } from "../fields/FieldControl";
+import { omitField } from "../fields/omit-field";
 import { colors, radius, space, type, z } from "../styles/tokens.stylex";
 import { Button } from "../ui/Button";
 import { Field } from "../ui/Field";
-import { Input, Textarea } from "../ui/Input";
 import { cx, isTransitioning } from "../ui/popup";
-import { MediaFieldInput } from "./MediaFieldInput";
+
+type ModelRef = { type: string; external?: boolean; fields?: Record<string, SchemaField> };
+type RelationDocumentLists = Record<
+  string,
+  Array<{ slug: string; frontmatter: Record<string, unknown> }>
+>;
 
 function fieldLabel(name: string, field: SchemaField) {
   if ("label" in field && typeof field.label === "string" && field.label) return field.label;
   return name.charAt(0).toUpperCase() + name.slice(1);
 }
 
-function compositeText(value: unknown): string {
-  if (value == null || value === "") return "";
-  if (typeof value === "string") return value;
-  return JSON.stringify(value, null, 2);
-}
-
 export function BlockSettingsDialog({
   name,
   title,
   fields,
   value,
+  models,
+  objects = [],
+  documentLists,
   readOnly,
   onOpenChange,
   onSave,
@@ -36,32 +38,19 @@ export function BlockSettingsDialog({
   title?: string;
   fields: Record<string, SchemaField>;
   value: Record<string, unknown>;
+  models: ModelRef[];
+  objects?: Array<{ name: string; fields: Record<string, SchemaField> }>;
+  documentLists?: RelationDocumentLists;
   readOnly?: boolean;
   onOpenChange: (open: boolean) => void;
   onSave: (props: Record<string, unknown>) => void;
   onRemove: () => void;
 }) {
   const [draft, setDraft] = useState(value);
-  const [error, setError] = useState<string | null>(null);
   const names = Object.keys(fields);
 
   function save() {
-    const next = { ...draft };
-    for (const [fieldName, field] of Object.entries(fields)) {
-      if (field.kind !== "object" && field.kind !== "array") continue;
-      const raw = next[fieldName];
-      if (typeof raw !== "string" || raw.trim() === "") {
-        next[fieldName] = raw === "" ? "" : raw;
-        continue;
-      }
-      try {
-        next[fieldName] = JSON.parse(raw);
-      } catch {
-        setError(`${fieldLabel(fieldName, field)} needs valid JSON.`);
-        return;
-      }
-    }
-    onSave(next);
+    onSave(draft);
   }
 
   return (
@@ -100,17 +89,18 @@ export function BlockSettingsDialog({
                       name={fieldName}
                       field={field}
                       value={draft[fieldName]}
+                      models={models}
+                      objects={objects}
+                      documentLists={documentLists}
                       readOnly={readOnly}
                       onChange={(next) => {
-                        setError(null);
-                        setDraft((current) => ({ ...current, [fieldName]: next }));
+                        setDraft((current) => omitField(current, fieldName, next));
                       }}
                     />
                   </Field>
                 );
               })
             )}
-            {error ? <p {...stylex.props(styles.error)}>{error}</p> : null}
             <div {...stylex.props(styles.actions)}>
               {readOnly ? null : (
                 <Button variant="danger" onClick={onRemove}>
@@ -137,82 +127,6 @@ export function BlockSettingsDialog({
   );
 }
 
-function FieldControl({
-  name,
-  field,
-  value,
-  readOnly,
-  onChange,
-}: {
-  name: string;
-  field: SchemaField;
-  value: unknown;
-  readOnly?: boolean;
-  onChange: (value: unknown) => void;
-}) {
-  const CustomInput = useFieldInput(field);
-  if (CustomInput) {
-    return (
-      <CustomInput name={name} field={field} value={value} readOnly={readOnly} onChange={onChange} />
-    );
-  }
-  if (field.kind === "media") {
-    return <MediaFieldInput name={name} value={value} readOnly={readOnly} onChange={onChange} />;
-  }
-  if (field.kind === "boolean") {
-    return (
-      <input
-        type="checkbox"
-        checked={value === true}
-        disabled={readOnly}
-        onChange={(event) => onChange(event.target.checked)}
-        {...stylex.props(styles.check)}
-      />
-    );
-  }
-  if (field.kind === "number") {
-    return (
-      <Input
-        type="number"
-        value={value == null || value === "" ? "" : String(value)}
-        readOnly={readOnly}
-        onChange={(event) => {
-          const raw = event.target.value;
-          onChange(raw === "" ? "" : Number(raw));
-        }}
-      />
-    );
-  }
-  if ("multiline" in field && field.multiline) {
-    return (
-      <Textarea
-        rows={4}
-        value={value == null ? "" : String(value)}
-        readOnly={readOnly}
-        onChange={(event) => onChange(event.target.value)}
-      />
-    );
-  }
-  if (field.kind === "object" || field.kind === "array") {
-    return (
-      <Textarea
-        rows={4}
-        value={compositeText(value)}
-        readOnly={readOnly}
-        spellCheck={false}
-        onChange={(event) => onChange(event.target.value)}
-      />
-    );
-  }
-  return (
-    <Input
-      value={value == null ? "" : String(value)}
-      readOnly={readOnly}
-      onChange={(event) => onChange(event.target.value)}
-    />
-  );
-}
-
 const styles = stylex.create({
   backdrop: {
     position: "fixed",
@@ -282,16 +196,6 @@ const styles = stylex.create({
     color: colors.textMuted,
     fontSize: type.sm,
   },
-  error: {
-    margin: 0,
-    color: colors.danger,
-    fontSize: type.sm,
-  },
-  check: {
-    width: 16,
-    height: 16,
-    margin: 0,
-  },
   actions: {
     display: "flex",
     alignItems: "center",