@bettercms-ai/richtext 0.12.1 → 0.16.0

package/src/write-refusals.ts

@@ -0,0 +1,114 @@
+/**
+ * What a rich-text WRITE may not hold, refused by name and never removed (RT0, properties R4, R8).
+ *
+ * Both read the value and answer a list. Neither changes it, so a caller that writes after an
+ * empty answer writes exactly what it was given: there is no strip step for content to vanish in.
+ * Callers that judge a stored value should judge only what the write introduces, as the field-key
+ * rules do: values written before a rule existed must keep saving.
+ */
+import { richTextRefusal, type UiRefusal } from "@bettercms-ai/types";
+import { acceptFor } from "./accept";
+import { ptSchemaFor } from "./schema";
+import { PT_TYPES, isPortableTextBlock, type PortableText, type PortableTextNode } from "./types";
+
+/**
+ * R4: every node, style, list, mark or annotation a field's features do not accept, judged against
+ * `ptSchemaFor(acceptFor(features))`, the same schema the editor offers. One refusal per name:
+ * `richtext.block_not_accepted:<name>`, where name is a block object's or inline object's `_type`,
+ * a style (`h2`), a list (`check`), a decorator (`strong`) or an annotation's `_type` (`link`).
+ */
+export function notAcceptedProblems(value: PortableText, features: readonly string[]): UiRefusal[] {
+  const accepted = acceptFor(features);
+  const schema = ptSchemaFor(accepted);
+  // One `link` annotation carries both: a plain link needs a link element, a button the button one.
+  const linkOk = accepted.includes("link") || accepted.includes("internalLink");
+  const buttonOk = accepted.includes("button");
+  const names = (list: { name: string }[]) => new Set(list.map((x) => x.name));
+  const styles = names(schema.styles);
+  const lists = names(schema.lists);
+  const decorators = names(schema.decorators);
+  const annotations = names(schema.annotations);
+  const blockObjects = names(schema.blockObjects);
+  const inlineObjects = names(schema.inlineObjects);
+
+  const out: UiRefusal[] = [];
+  const refused = new Set<string>();
+  const refuse = (name: string) => {
+    if (refused.has(name)) return;
+    refused.add(name);
+    out.push(richTextRefusal("block_not_accepted", name));
+  };
+
+  const judge = (node: PortableText[number]) => {
+    if (!isPortableTextBlock(node)) {
+      if (!blockObjects.has(node._type)) refuse(node._type);
+      // RT7: a column's text is the field's text too, judged by the same features.
+      if (node._type === PT_TYPES.columns && Array.isArray((node as { columns?: unknown }).columns)) {
+        for (const col of (node as unknown as { columns: { content?: unknown }[] }).columns) {
+          if (Array.isArray(col?.content)) for (const b of col.content as PortableText) judge(b);
+        }
+      }
+      return;
+    }
+    if (!styles.has(node.style ?? "normal")) refuse(node.style);
+    if (node.listItem !== undefined && !lists.has(node.listItem)) refuse(node.listItem);
+    const defs = new Set<string>();
+    for (const def of node.markDefs ?? []) {
+      defs.add(def._key);
+      if (def._type === "link") {
+        if (def.button === true ? !buttonOk : !linkOk) refuse(def.button === true ? "button" : "link");
+      } else if (!annotations.has(def._type)) refuse(def._type);
+    }
+    for (const child of node.children ?? []) {
+      if (child._type !== "span") {
+        if (!inlineObjects.has(child._type)) refuse(child._type);
+        continue;
+      }
+      // A mark is a markDef key (its annotation was judged above) or a decorator name.
+      for (const mark of (child as { marks?: string[] }).marks ?? []) if (!defs.has(mark) && !decorators.has(mark)) refuse(mark);
+    }
+  };
+  for (const node of value) judge(node);
+  return out;
+}
+
+/**
+ * What each V2 block computes at render time and never stores (kit-richtext-blocks-gap.md, the
+ * "Derived" line of each block). `posts[].title` means that key on every entry of `posts`. Each RT
+ * step confirms its row when it builds the type; a key outside its row is not judged here.
+ */
+export const DERIVED_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  footnote: ["number"],
+  embed: ["provider", "shape", "src"],
+  columns: ["cols"],
+  tableOfContents: ["outline"],
+  // RT8 (G-RT8): what a reference resolves to is never stored, on the block or as a `resolved` map.
+  authorBio: ["name", "avatar", "bio", "resolved"],
+  relatedPosts: ["posts[].title", "posts[].slug", "posts[].url", "posts[].cover", "posts[].category", "resolved"],
+};
+
+/** Whether a node holds a derived path: `key`, or `list[].key` on any entry of the list. */
+const holds = (node: Record<string, unknown>, path: string): boolean => {
+  const [list, key] = path.split("[].");
+  if (key === undefined) return Object.hasOwn(node, path);
+  const items = node[list];
+  return Array.isArray(items) && items.some((item) => item !== null && typeof item === "object" && Object.hasOwn(item, key));
+};
+
+/**
+ * R8: every derived key a write carries, top-level nodes and inline children alike, refused as
+ * `richtext.derived_field:<_type>.<path>` (`embed.provider`, `relatedPosts.posts[].title`).
+ */
+export function derivedFieldProblems(value: PortableText): UiRefusal[] {
+  const out: UiRefusal[] = [];
+  const judge = (node: PortableTextNode) => {
+    for (const path of DERIVED_FIELDS[node._type] ?? []) {
+      if (holds(node as unknown as Record<string, unknown>, path)) out.push(richTextRefusal("derived_field", `${node._type}.${path}`));
+    }
+  };
+  for (const node of value) {
+    judge(node);
+    if (isPortableTextBlock(node)) for (const child of node.children ?? []) judge(child);
+  }
+  return out;
+}