@platecms/delta-cast 0.4.1 → 0.7.0

package/README.md

@@ -51,3 +51,63 @@ const castTree = {
 const hast = toHast(castTree);
 const htmlString = toHtml(hast);
 ```
+
+
+# Normalization
+
+A CAST tree can and should be normalized to ensure that it is in a consistent and predictable state. Different trees that represent the same content should be normalized to a single, canonical form.
+
+## Usage
+
+```typescript
+import { normalizeCast } from '@platecms/delta-cast';
+
+const normalizedTree = normalizeCast(castTree);
+```
+
+## Normalization Rules
+
+The `normalizeCast` function applies the following normalization rules in an iterative process:
+
+### 1. Adjacent Node Merging
+- **Text nodes**: Merge adjacent `text` nodes by concatenating their values
+- **Formatting nodes**: Merge adjacent formatting nodes of the same type by combining their children
+- **Mergeable types**: `text`, `bold`, `italic`, `underline`, `strikethrough`, `highlight`
+- **Non-mergeable types**: `contentValue`, `externalLink`, `internalLink`, `inlineCode`
+
+### 2. Formatting Node Nesting Order
+Formatting nodes are reordered to follow a consistent hierarchy:
+```
+bold -> italic -> underline -> strikethrough -> highlight
+```
+
+### 3. Duplicate Formatting Removal
+- Remove duplicate formatting nodes in a single path (e.g., `bold` containing `bold`)
+- This prevents redundant nesting that doesn't change the visual output
+
+### 4. Empty Node Cleanup
+- Remove empty formatting (inline) nodes that contain no children
+- Block-level container nodes (paragraphs, headings, lists, etc.) are preserved even when empty
+
+## Special Behavior
+
+- **ContentValue nodes**: Completely untouched - their nested CAST trees are never normalized
+- **Property preservation**: All node properties (`url`, `target`, `prn`, `level`, `lang`, etc.) are preserved
+- **Iterative process**: Normalization is an iterative process that continues until no more changes are detected
+- **Immutable**: Returns a new tree without modifying the input
+
+## Formatting Priority
+
+The `FORMATTING_PRIORITY` constant defines the canonical nesting order for formatting nodes:
+
+```typescript
+export const FORMATTING_PRIORITY = {
+  'bold': 1,        // Highest priority
+  'italic': 2,
+  'underline': 3,
+  'strikethrough': 4,
+  'highlight': 5    // Lowest priority
+} as const;
+```
+
+This constant should be used across all packages (e.g., `cast-util-to-slate`, `cast-util-from-slate`) to ensure consistent formatting hierarchy throughout the platform.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@platecms/delta-cast",
   "description": "Package containing the definition of CAST",
-  "version": "0.4.1",
+  "version": "0.7.0",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,6 @@
     "tslib": "2.8.1"
   },
   "peerDependencies": {
-    "@platecms/delta-plate-resource-notation": "0.4.1"
-  },
-  "type": "commonjs"
+    "@platecms/delta-plate-resource-notation": "0.7.0"
+  }
 }

package/src/{index.d.ts → index.ts}

@@ -1,3 +1,4 @@
 export type * from "./lib/schemas/schema";
 export * from "./lib/validate-cast";
 export * from "./lib/invalid-cast.error";
+export * from "./lib/normalize-cast";

package/src/lib/invalid-cast.error.ts

@@ -0,0 +1,6 @@
+export class InvalidCastError extends Error {
+  public constructor(message?: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}