@platecms/delta-cast 1.15.3 → 1.16.0

package/README.md

@@ -10,48 +10,318 @@ that adheres to the [**Unified collective**](https://github.com/unifiedjs/unifie
 The schema is defined in [schema.ts](src/lib/schemas/schema.ts), and is rendered into JSON Schema format
 in [schema.json](src/lib/schemas/schema.json).
 
-## Utils
+## Node types
 
-To work with CAST documents, we implement the following utitlities:
+CAST nodes follow the unist tree model. Each document has a single `root`. Block nodes make up the document structure.
+Inline nodes appear inside block (and some inline) parents.
 
-- `InvalidCastError`: An error that is thrown when a CAST document is invalid.
-- `validateCast`: Validates any input against the schema. Throws `InvalidCastError` if the input is invalid.
+### Root
 
-### **WIP** fromSlate (Or some other editor)
+#### `root`
 
-As Delta uses [Slate](https://www.slatejs.org) as a wysiwyg editor, we need to convert ~Slate~ documents to CAST
-documents, in order to process them in Delta.
+The root of a CAST document. Every document has exactly one root. Children may be any `Content` (block content, inline
+content, or `castSuggestion`).
 
-### **WIP** toSlate
+```json
+{
+  "type": "root",
+  "children": [
+    {
+      "type": "paragraph",
+      "children": [{ "type": "text", "value": "Hello world" }]
+    }
+  ]
+}
+```
+
+### Block content
+
+#### `paragraph`
+
+A paragraph of inline content.
+
+- **`children`**: `InlineContent[]`
+
+```json
+{
+  "type": "paragraph",
+  "children": [{ "type": "text", "value": "Hello, world!" }]
+}
+```
+
+#### `heading`
 
-As Delta uses Slate as a wysiwyg editor, we need to convert CAST documents to ~Slate~ documents, in order to display
-them in the editor.
+A heading.
 
-### **WIP** toHast
+- **`level`**: `1 | 2 | 3 | 4 | 5 | 6`
+- **`children`**: `InlineContent[]`
 
-To display CAST documents in a web browser, we need to convert them to [HAST](https://github.com/syntax-tree/hast). From
-a HAST tree, we can then use [**hast-util-to-html**](https://github.com/syntax-tree/hast-util-to-html) to create an HTML
-string or [**hast-util-to-dom**](https://github.com/syntax-tree/hast-util-to-dom) to create a DOM tree.
+```json
+{
+  "type": "heading",
+  "level": 1,
+  "children": [{ "type": "text", "value": "Heading" }]
+}
+```
+
+#### `list`
+
+An ordered or unordered list. Children must be `listItem` nodes only.
 
-Example usage of cast-utils-to-hast to render a CAST tree to a HTML string:
+- **`ordered`**: whether the list is ordered
+- **`start`**: optional start number for an ordered list
+- **`children`**: `ListItem[]`
 
-```ts
-const castTree = {
-  type: 'root',
-  children: [
+```json
+{
+  "type": "list",
+  "ordered": true,
+  "start": 1,
+  "children": [
     {
-      type: 'paragraph',
-      children: [
-        { type: 'text', value: 'Hello, world!' }
-      ]
+      "type": "listItem",
+      "children": [{ "type": "text", "value": "Item" }]
     }
   ]
 }
+```
+
+#### `listItem`
+
+A single item in a list. Only used as a child of `list`.
+
+- **`children`**: `InlineContent[]`
+
+```json
+{
+  "type": "listItem",
+  "children": [{ "type": "text", "value": "Item" }]
+}
+```
+
+#### `blockquote`
+
+A block quotation of inline content.
+
+- **`children`**: `InlineContent[]`
+
+```json
+{
+  "type": "blockquote",
+  "children": [{ "type": "text", "value": "Blockquote text" }]
+}
+```
+
+#### `code`
+
+A code block. Children must be `text` nodes.
+
+- **`lang`**: optional language of the code block
+- **`children`**: `Text[]`
+
+```json
+{
+  "type": "code",
+  "lang": "javascript",
+  "children": [{ "type": "text", "value": "console.log('Hello, world!');" }]
+}
+```
+
+### Inline content
+
+#### `text`
+
+A text literal.
+
+- **`value`**: string
+
+```json
+{
+  "type": "text",
+  "value": "Hello, world!"
+}
+```
+
+#### `bold`
+
+Bold formatting. Children are inline content.
+
+- **`children`**: `InlineContent[]`
 
-const hast = toHast(castTree);
-const htmlString = toHtml(hast);
+```json
+{
+  "type": "bold",
+  "children": [{ "type": "text", "value": "Bold text" }]
+}
 ```
 
+#### `italic`
+
+Italic formatting. Children are inline content.
+
+- **`children`**: `InlineContent[]`
+
+```json
+{
+  "type": "italic",
+  "children": [{ "type": "text", "value": "Italic text" }]
+}
+```
+
+#### `underline`
+
+Underline formatting. Children are inline content.
+
+- **`children`**: `InlineContent[]`
+
+```json
+{
+  "type": "underline",
+  "children": [{ "type": "text", "value": "Underline text" }]
+}
+```
+
+#### `strikethrough`
+
+Strikethrough formatting. Children are inline content.
+
+- **`children`**: `InlineContent[]`
+
+```json
+{
+  "type": "strikethrough",
+  "children": [{ "type": "text", "value": "Strikethrough text" }]
+}
+```
+
+#### `highlight`
+
+Highlight formatting. Children are inline content.
+
+- **`children`**: `InlineContent[]`
+
+```json
+{
+  "type": "highlight",
+  "children": [{ "type": "text", "value": "Highlight text" }]
+}
+```
+
+#### `inlineCode`
+
+An inline code literal.
+
+- **`value`**: string
+
+```json
+{
+  "type": "inlineCode",
+  "value": "code"
+}
+```
+
+#### `contentValue`
+
+An interpolated Content Value. The referenced value is stored elsewhere and inserted into the document at request-time.
+Nested CAST trees on `value` are not normalized.
+
+- **`prn`**: PRN of the referenced Content Value
+- **`value`**: optional nested CAST tree (`root`) of the referenced Content Value.
+
+**CAST example**
+```json
+{
+  "type": "contentValue",
+  "prn": "prn:plate-dev:1234:cms:test:abcd",
+  "value": {
+    "type": "root",
+    "children": [
+      {
+        "type": "paragraph",
+        "children": [{ "type": "text", "value": "Resolved value" }]
+      }
+    ]
+  }
+}
+```
+
+**Create input**
+```json
+{
+  "type": "contentValue",
+  "prn": "prn:plate-dev:1234:cms:test:abcd",
+}
+```
+
+#### `externalLink`
+
+A link to an external URL. Children must be `text` nodes.
+
+- **`url`**: URL of the link
+- **`target`**: optional `"_parent" | "_top" | "blank" | "self"`
+- **`children`**: `Text[]`
+
+```json
+{
+  "type": "externalLink",
+  "url": "https://www.google.com",
+  "target": "blank",
+  "children": [{ "type": "text", "value": "External link" }]
+}
+```
+
+#### `internalLink`
+
+A link to a Path Part or Grid Placement. Children must be `text` nodes. `url` is always defined when retrieving an
+internal link, but is not required when saving one.
+
+- **`prn`**: PRN of the referenced Path Part or Grid Placement
+- **`url`**: optional URL (channel and path part, optionally with a grid placement reference such as `#anchor-name`)
+- **`target`**: optional `"_parent" | "_top" | "blank" | "self"`
+- **`children`**: `Text[]`
+
+**CAST example**
+```json
+{
+  "type": "internalLink",
+  "prn": "prn:plate-dev:1234:cms:test:abcd",
+  "url": "https://www.example.test",
+  "target": "self",
+  "children": [{ "type": "text", "value": "Internal link" }]
+}
+```
+
+```json
+{
+  "type": "internalLink",
+  "prn": "prn:plate-dev:1234:cms:test:abcd#grid-placement",
+  "url": "https://www.example.test",
+  "target": "self",
+  "children": [{ "type": "text", "value": "Internal link" }]
+}
+```
+
+**Create input**
+URL is ommitted here as it generated by the system to keep it up to date.
+```json
+{
+  "type": "internalLink",
+  "prn": "prn:plate-dev:1234:cms:test:abcd",
+  "target": "self",
+  "children": [{ "type": "text", "value": "Internal link" }]
+}
+```
+
+# Utilities
+
+Related packages for converting, rendering, and authoring CAST trees:
+
+- [cast-util-from-slate](../cast-util-from-slate/README.md) — convert Slate editor documents to CAST
+- [cast-util-to-slate](../cast-util-to-slate/README.md) — convert CAST trees to Slate editor documents
+- [cast-util-to-hast](../cast-util-to-hast/README.md) — convert CAST trees to HAST
+- [cast-util-to-html](../cast-util-to-html/README.md) — convert CAST trees to sanitized HTML (via HAST)
+- [cast-util-to-plaintext](../cast-util-to-plaintext/README.md) — convert CAST trees to plaintext
+- [castscript](../castscript/README.md) — scriptable helper for building CAST trees
 
 # Normalization
 

package/package.json

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