@platecms/delta-cast 0.6.0 → 0.8.0

package/src/lib/normalize-cast.ts

@@ -0,0 +1,390 @@
+import { Content, Parent, Root } from "./schemas/schema";
+
+/**
+ * Formatting node priority for nesting order (lower number = higher priority)
+ * This constant should be used across all packages to ensure consistent formatting hierarchy.
+ */
+export const FORMATTING_PRIORITY = {
+  bold: 1,
+  italic: 2,
+  underline: 3,
+  strikethrough: 4,
+  highlight: 5,
+} as const;
+
+/**
+ * Type guard to check if a node has children
+ */
+function hasChildren(node: Content | Parent): node is Content & { children: Content[] } {
+  return "children" in node && Array.isArray((node as { children: unknown }).children);
+}
+
+/**
+ * Type guard to check if a node is a formatting node
+ */
+function isFormattingNode(node: Content): boolean {
+  const formattingTypes = ["bold", "italic", "underline", "strikethrough", "highlight"];
+  return formattingTypes.includes(node.type);
+}
+
+/**
+ * Determines if two nodes can be merged
+ */
+function canMerge(node1: Content, node2: Content): boolean {
+  // Formatting nodes: merge if same type and mergeable
+  const mergeableTypes = ["bold", "italic", "underline", "strikethrough", "highlight", "text"];
+  if (mergeableTypes.includes(node1.type) && node1.type === node2.type) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Merges two nodes by combining their content
+ */
+function mergeNodes(source: Content, target: Content): void {
+  if (source.type === "text" && target.type === "text") {
+    // Concatenate text values
+    target.value = source.value + target.value;
+  } else if (source.type === target.type && hasChildren(source) && hasChildren(target)) {
+    // Combine children arrays for formatting nodes
+    const sourceWithChildren = source as Content & { children: Content[] };
+    const targetWithChildren = target as Content & { children: Content[] };
+    targetWithChildren.children = [...sourceWithChildren.children, ...targetWithChildren.children];
+  }
+}
+
+/**
+ * Determines if a child formatting node should be above its parent in the hierarchy
+ */
+function shouldChildBeAboveParent(childType: string, parentType: string): boolean {
+  const childPriority = FORMATTING_PRIORITY[childType as keyof typeof FORMATTING_PRIORITY] || 999;
+  const parentPriority = FORMATTING_PRIORITY[parentType as keyof typeof FORMATTING_PRIORITY] || 999;
+
+  return childPriority < parentPriority;
+}
+
+/**
+ * Splits a parent node into separate nodes while preserving other grandparent children.
+ * Gets all the siblings before and after the child, and creates at most two new parent nodes which are inserted
+ * before and after the original parent node in the grandparent node, containing the original before and after children respectively.
+ * Example:
+ * Input:
+ * {
+ *   type: 'italic',
+ *   children: [
+ *     { type: 'text', value: 'Another parent' },
+ *     { type: 'bold', children: [
+ *       { type: 'text', value: 'Before' },
+ *       { type: 'text', value: 'Child node' },
+ *       { type: 'text', value: 'After' }
+ *     ] },
+ *     { type: 'text', value: 'Even more parents' }
+ *   ]
+ * }
+ * Output:
+ * {
+ *   type: 'italic',
+ *   children: [
+ *     { type: 'text', value: 'Another parent' },
+ *     { type: 'bold', children: [
+ *       { type: 'text', value: 'Before' },
+ *     ] },
+ *     { type: 'bold', children: [
+ *       { type: 'text', value: 'Child node' },
+ *     ] },
+ *     { type: 'bold', children: [
+ *       { type: 'text', value: 'After' },
+ *     ] },
+ *     { type: 'text', value: 'Even more parents' }
+ *   ]
+ * }
+ * @param grandParent
+ * @param parent
+ * @param child
+ * @param parentIndexInGrandParent
+ * @param childIndexInParent
+ * @returns The number of new parent nodes inserted before the original parent node
+ */
+function splitParentIntoSeparateNodes(
+  grandParent: Parent,
+  parent: Parent,
+  child: Parent,
+  parentIndexInGrandParent: number,
+  childIndexInParent: number,
+): number {
+  const siblingsBeforeChild = parent.children.slice(0, childIndexInParent);
+  const siblingsAfterChild = parent.children.slice(childIndexInParent + 1);
+
+  let insertionOffset = 0;
+  if (siblingsBeforeChild.length > 0) {
+    const newBeforeParent: Parent = { ...parent, children: siblingsBeforeChild };
+    grandParent.children.splice(parentIndexInGrandParent, 0, newBeforeParent as Content);
+    insertionOffset = 1;
+  }
+
+  if (siblingsAfterChild.length > 0) {
+    const newAfterParent: Parent = { ...parent, children: siblingsAfterChild };
+    grandParent.children.splice(parentIndexInGrandParent + 1 + insertionOffset, 0, newAfterParent as Content);
+  }
+
+  parent.children = [child as Content];
+
+  return insertionOffset;
+}
+
+/**
+ * Processes a formatting child to determine if it should be flipped with its parent.
+ * This assumes that both the parent and child are formatting nodes.
+ */
+function processFormattingChild(
+  grandParent: Parent,
+  parent: Parent,
+  child: Parent,
+  parentIndexInGrandParent: number,
+  childIndexInParent: number,
+): boolean {
+  if (!shouldChildBeAboveParent(child.type, parent.type)) {
+    return false;
+  }
+
+  let parentIndexInGrandParentOffset = 0;
+  if (parent.children.length > 1) {
+    parentIndexInGrandParentOffset += splitParentIntoSeparateNodes(
+      grandParent,
+      parent,
+      child,
+      parentIndexInGrandParent,
+      childIndexInParent,
+    );
+  }
+
+  parent.children = child.children;
+  child.children = [parent as Content];
+  grandParent.children[parentIndexInGrandParent + parentIndexInGrandParentOffset] = child as Content;
+  return true;
+}
+
+/**
+ * Single pass of the bubble sort algorithm for formatting nodes
+ */
+function bubbleFormattingNodes(node: Parent, parent?: Parent, nodeIndexInParent?: number): boolean {
+  let hasChanges = false;
+
+  if (!hasChildren(node)) {
+    return hasChanges;
+  }
+
+  // DFS: process children first
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i];
+    if (hasChildren(child)) {
+      hasChanges = bubbleFormattingNodes(child, node, i) || hasChanges;
+    }
+  }
+
+  // If not a formatting node, return
+  if (!isFormattingNode(node)) {
+    return hasChanges;
+  }
+
+  // If no parent is provided, we are at the root, and we don't need to check for formatting nodes
+  if (!parent || nodeIndexInParent === undefined) {
+    return hasChanges;
+  }
+
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i];
+    if (isFormattingNode(child) && hasChildren(child)) {
+      hasChanges = processFormattingChild(parent, node, child, nodeIndexInParent, i) || hasChanges;
+    }
+  }
+
+  return hasChanges;
+}
+
+/**
+ * Determines if a node should be removed because it's empty
+ */
+function shouldRemoveEmptyNode(node: Content): boolean {
+  // Only remove empty formatting (inline) nodes
+  if (!isFormattingNode(node)) {
+    return false;
+  }
+
+  // For formatting nodes with children, check if they're empty
+  if (!hasChildren(node) || node.children.length === 0) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Merges adjacent nodes that can be combined (text nodes and same-type formatting nodes)
+ * Example:
+ * Input:
+ * {
+ *   type: 'root',
+ *   children: [
+ *     { type: 'text', value: 'Hello' },
+ *     { type: 'text', value: ' world' }
+ *   ]
+ * }
+ * Output:
+ * {
+ *   type: 'root',
+ *   children: [
+ *     { type: 'text', value: 'Hello world' }
+ *   ]
+ * }
+ */
+function mergeAdjacentNodes(node: Parent): boolean {
+  let hasChanges = false;
+
+  // Process current level
+  for (let i = 0; i < node.children.length - 1; i++) {
+    const current = node.children[i];
+    const next = node.children[i + 1];
+
+    if (canMerge(current, next)) {
+      // Merge current into next, remove current
+      mergeNodes(current, next);
+      node.children.splice(i, 1);
+      hasChanges = true;
+      i--; // Check the same position again since we removed an element
+    }
+  }
+
+  // Recursively process children
+  for (const child of node.children) {
+    if (hasChildren(child)) {
+      hasChanges = mergeAdjacentNodes(child) || hasChanges;
+    }
+  }
+
+  return hasChanges;
+}
+
+/**
+ * Reorders formatting nodes to follow the standard hierarchy using bubble sort approach
+ */
+function reorderFormattingNodes(node: Parent): boolean {
+  let hasChanges = true;
+  let anyChanges = false;
+
+  // Keep bubbling until no more changes (like bubble sort)
+  while (hasChanges) {
+    hasChanges = false;
+    hasChanges = bubbleFormattingNodes(node) || hasChanges;
+    if (hasChanges) {
+      anyChanges = true;
+    }
+  }
+
+  return anyChanges;
+}
+
+/**
+ * Removes duplicate formatting nodes using bottom-up consolidation approach
+ */
+function removeDuplicateFormatting(
+  node: Parent,
+  ancestorsFormattingNodeTypes: string[],
+  parent?: Parent,
+  nodeIndexInParent?: number,
+): boolean {
+  let hasChanges = false;
+
+  if (!hasChildren(node)) {
+    return hasChanges;
+  }
+
+  // Create new array with current node's type if it's a formatting node
+  const newAncestorsFormattingNodeTypes = isFormattingNode(node)
+    ? [...ancestorsFormattingNodeTypes, node.type]
+    : ancestorsFormattingNodeTypes;
+
+  // DFS: process children first
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i];
+    if (hasChildren(child)) {
+      hasChanges = removeDuplicateFormatting(child, newAncestorsFormattingNodeTypes, node, i) || hasChanges;
+    }
+  }
+
+  if (!parent || nodeIndexInParent === undefined) {
+    return hasChanges;
+  }
+
+  // Then process current level for duplicate formatting
+  if (ancestorsFormattingNodeTypes.includes(node.type)) {
+    parent.children.splice(nodeIndexInParent, 1, ...node.children);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}
+
+/**
+ * Removes empty nodes from the CAST tree
+ */
+function cleanupEmptyNodes(node: Parent): boolean {
+  let hasChanges = false;
+
+  if (!hasChildren(node)) {
+    return hasChanges;
+  }
+
+  // DFS: process children first
+  for (let i = node.children.length - 1; i >= 0; i--) {
+    const child = node.children[i];
+    if (hasChildren(child)) {
+      hasChanges = cleanupEmptyNodes(child) || hasChanges;
+    }
+  }
+
+  // Then process current level - remove empty children
+  // Iterate backwards to avoid index issues when removing items
+  for (let i = node.children.length - 1; i >= 0; i--) {
+    const child = node.children[i];
+
+    if (shouldRemoveEmptyNode(child)) {
+      node.children.splice(i, 1);
+      hasChanges = true;
+    }
+  }
+
+  return hasChanges;
+}
+/**
+ * Normalizes a CAST tree to ensure it is in a consistent and predictable state.
+ * This function applies various normalization rules to merge equivalent nodes,
+ * reorder formatting, and clean up empty structures.
+ *
+ * @param root - The CAST root node to normalize
+ * @returns A normalized copy of the CAST tree
+ */
+export function normalizeCast(root: Root): Root {
+  let hasChanges = true;
+  const currentRoot = JSON.parse(JSON.stringify(root)) as Root;
+
+  while (hasChanges) {
+    hasChanges = false;
+
+    // Pass 1: Merge adjacent nodes
+    hasChanges = mergeAdjacentNodes(currentRoot) || hasChanges;
+
+    // Pass 2: Reorder formatting nodes
+    hasChanges = reorderFormattingNodes(currentRoot) || hasChanges;
+
+    // Pass 3: Remove duplicate formatting
+    hasChanges = removeDuplicateFormatting(currentRoot, []) || hasChanges;
+
+    // Pass 4: Clean up empty nodes
+    hasChanges = cleanupEmptyNodes(currentRoot) || hasChanges;
+  }
+
+  return currentRoot;
+}

package/src/lib/schemas/schema.json

@@ -603,3 +603,4 @@
     },
     "description": "The root node of a CAST document. The unist tree starts here. Each CAST document has one root node.\n\n```json\n{\n  \"type\": \"root\",\n  \"children\": [\n    ...\n  ]\n}"
 }
+

package/src/lib/schemas/schema.ts

@@ -0,0 +1,234 @@
+import { Node, Literal as UnistLiteral, Parent as UnistParent } from "unist";
+
+export type Content = BlockContent | InlineContent;
+
+export type BlockContent = BlockContentMap[keyof BlockContentMap];
+export type InlineContent = InlineContentMap[keyof InlineContentMap];
+
+export interface BlockContentMap {
+  paragraph: Paragraph;
+  heading: Heading;
+  list: List;
+  // List item should not be used anywhere except in the list's children
+  listItem: ListItem;
+  blockquote: Blockquote;
+  code: Code;
+}
+
+export interface InlineContentMap {
+  text: Text;
+  bold: Bold;
+  italic: Italic;
+  underline: Underline;
+  strikethrough: Strikethrough;
+  inlineCode: InlineCode;
+  highlight: Highlight;
+  contentValue: InterpolatedContentValue;
+  externalLink: ExternalLink;
+  internalLink: InternalLink;
+}
+
+export interface Parent extends UnistParent {
+  children: Content[];
+}
+
+export interface Literal extends UnistLiteral {
+  value: string;
+}
+
+/*
+ ** Specific CAST Definitions
+ */
+
+/**
+ * The root node of a CAST document. The unist tree starts here. Each CAST document has one root node.
+ *
+ * ```json
+ * {
+ *   "type": "root",
+ *   "children": [
+ *     ...
+ *   ]
+ * }
+ */
+export interface Root extends Parent {
+  type: "root";
+}
+
+/*
+ ** Block Content
+ */
+export interface Paragraph extends Parent {
+  type: "paragraph";
+
+  /**
+   * The children of a paragraph are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Heading extends Parent {
+  type: "heading";
+
+  /**
+   * The level of a heading is a number between 1 and 6.
+   */
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+
+  /**
+   * The children of a heading are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface List extends Parent {
+  type: "list";
+
+  children: ListItem[];
+
+  /**
+   * Whether the list is ordered or not.
+   */
+  ordered: boolean;
+
+  /**
+   * The start of an ordered list.
+   */
+  start?: number;
+}
+
+export interface ListItem extends Parent {
+  type: "listItem";
+
+  /**
+   * The children of a list item are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Blockquote extends Parent {
+  type: "blockquote";
+
+  /**
+   * The children of a blockquote are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Code extends Parent {
+  type: "code";
+
+  /**
+   * The language of the code block.
+   */
+  lang?: string;
+
+  children: Text[];
+}
+
+/*
+ ** Inline Content
+ */
+export interface Text extends Literal {
+  type: "text";
+}
+
+export interface Bold extends Parent {
+  type: "bold";
+
+  /**
+   * The children of a bold node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Italic extends Parent {
+  type: "italic";
+
+  /**
+   * The children of an italic node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Underline extends Parent {
+  type: "underline";
+
+  /**
+   * The children of an underline node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Strikethrough extends Parent {
+  type: "strikethrough";
+
+  /**
+   * The children of a strikethrough node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface InlineCode extends Literal {
+  type: "inlineCode";
+}
+
+export interface Highlight extends Parent {
+  type: "highlight";
+
+  /**
+   * The children of a highlight node are inline content
+   */
+  children: InlineContent[];
+}
+
+/**
+ * Represents an interpolated Content Value. Interpolated values are values that are stored elsewhere in the database
+ * and inserted into the document at request-time.
+ */
+export interface InterpolatedContentValue extends Node {
+  type: "contentValue";
+
+  /**
+   * The PRN (identifier) of the referenced Content Value.
+   */
+  prn: string;
+
+  /**
+   * The nested CAST tree of the referenced Content Value.
+   */
+  value?: Root;
+}
+
+export interface ExternalLink extends Parent {
+  type: "externalLink";
+
+  children: Text[];
+
+  /**
+   * The URL of the link.
+   */
+  url: string;
+
+  target?: "_parent" | "_top" | "blank" | "self";
+}
+
+export interface InternalLink extends Parent {
+  type: "internalLink";
+
+  children: Text[];
+
+  /**
+   * The PRN (identifier) of the referenced Path Part or Grid Placement.
+   */
+  prn: string;
+
+  /**
+   * The URL of the link. Consists of the channel and the path part. Optionally includes a grid placement reference (e.g. #anchor-name).
+   * Even though the URL is marked as optional, it is always defined when retrieving an internal link.
+   * It is not required when saving an internal link.
+   */
+  url?: string;
+
+  target?: "_parent" | "_top" | "blank" | "self";
+}