@nan0web/ui-payload 3.3.0

package/src/richtext/Nan0ComponentNode.js

@@ -0,0 +1,98 @@
+/**
+ * Nan0ComponentNode
+ * Represents a NaN0Web component inside the Lexical tree
+ * (e.g. `App.Header`, `Card.Details`, `App.Deposits.Calculator`).
+ *
+ * Serialized shape:
+ * ```json
+ * {
+ *   "type": "nan0-component",
+ *   "version": 1,
+ *   "component": "Card.Details",
+ *   "props": { "card": "$" }
+ * }
+ * ```
+ *
+ * Renders in the editor as a read-only placeholder for now. A future
+ * phase adds React components + props forms for editing.
+ */
+import { DecoratorNode, $applyNodeReplacement } from 'lexical'
+
+export class Nan0ComponentNode extends DecoratorNode {
+  /** @type {string} */ __component
+  /** @type {Record<string, any>} */ __props
+
+  constructor({ component, props = {}, key }) {
+    super(key)
+    this.__component = component
+    this.__props = props
+  }
+
+  static clone(node) {
+    return new this({ component: node.__component, props: { ...node.__props }, key: node.__key })
+  }
+
+  static getType() {
+    return 'nan0-component'
+  }
+
+  static importJSON(serializedNode) {
+    return $createNan0ComponentNode({
+      component: serializedNode.component,
+      props: serializedNode.props || {},
+    })
+  }
+
+  exportJSON() {
+    return {
+      ...super.exportJSON(),
+      type: 'nan0-component',
+      version: 1,
+      component: this.__component,
+      props: this.__props,
+    }
+  }
+
+  getComponent() {
+    return this.getLatest().__component
+  }
+
+  getProps() {
+    return this.getLatest().__props
+  }
+
+  isInline() {
+    return false
+  }
+
+  createDOM() {
+    const el = document.createElement('div')
+    el.setAttribute('data-nan0-component', this.__component)
+    el.className = 'nan0-component-placeholder'
+    el.style.border = '1px dashed #c8a'
+    el.style.padding = '8px'
+    el.style.margin = '4px 0'
+    el.style.borderRadius = '4px'
+    el.style.background = '#fdf6ff'
+    el.style.fontSize = '0.85em'
+    el.style.color = '#a55'
+    el.textContent = `[component: ${this.__component}]`
+    return el
+  }
+
+  updateDOM() {
+    return false
+  }
+
+  decorate() {
+    return null
+  }
+}
+
+export function $createNan0ComponentNode({ component, props = {} }) {
+  return $applyNodeReplacement(new Nan0ComponentNode({ component, props }))
+}
+
+export function $isNan0ComponentNode(node) {
+  return node instanceof Nan0ComponentNode
+}

package/src/richtext/Nan0ElementNode.js

@@ -0,0 +1,93 @@
+/**
+ * Nan0ElementNode
+ * Lossless wrapper for NaN0HTML elements that carry `$`-attributes.
+ *
+ * Serialized shape:
+ * ```json
+ * { "type": "nan0-element", "version": 1, "tag": "div", "attributes": { "class": "..." }, "children": [...] }
+ * ```
+ *
+ * This node is used when a native Lexical node cannot represent the attributes
+ * without data loss. Clean elements (no attributes) use native nodes directly.
+ */
+import { ElementNode, $applyNodeReplacement } from 'lexical'
+
+export class Nan0ElementNode extends ElementNode {
+  /** @type {string} */ __tag
+  /** @type {Record<string, any>} */ __attributes
+
+  constructor({ tag, attributes = {}, key }) {
+    super(key)
+    this.__tag = tag
+    this.__attributes = attributes
+  }
+
+  static clone(node) {
+    return new this({ tag: node.__tag, attributes: { ...node.__attributes }, key: node.__key })
+  }
+
+  static getType() {
+    return 'nan0-element'
+  }
+
+  static importJSON(serializedNode) {
+    const node = $createNan0ElementNode({
+      tag: serializedNode.tag,
+      attributes: serializedNode.attributes || {},
+    })
+    return node
+  }
+
+  exportJSON() {
+    return {
+      ...super.exportJSON(),
+      type: 'nan0-element',
+      version: 1,
+      tag: this.__tag,
+      attributes: this.__attributes,
+    }
+  }
+
+  getTag() {
+    return this.getLatest().__tag
+  }
+
+  getAttributes() {
+    return this.getLatest().__attributes
+  }
+
+  isInline() {
+    return false
+  }
+
+  canBeEmpty() {
+    return true
+  }
+
+  createDOM(config) {
+    const element = document.createElement(this.__tag || 'div')
+    const attrs = this.__attributes || {}
+    for (const [key, value] of Object.entries(attrs)) {
+      if (key === 'class') {
+        element.className = Array.isArray(value) ? value.join(' ') : String(value)
+      } else if (key === 'style' && typeof value === 'string') {
+        element.setAttribute('style', value)
+      } else if (typeof value === 'string' || typeof value === 'number') {
+        element.setAttribute(key, String(value))
+      }
+    }
+    return element
+  }
+
+  updateDOM() {
+    return false
+  }
+}
+
+export function $createNan0ElementNode({ tag, attributes = {} }) {
+  return $applyNodeReplacement(new Nan0ElementNode({ tag, attributes }))
+}
+
+export function $isNan0ElementNode(node) {
+  return node instanceof Nan0ElementNode
+}

package/src/richtext/Nan0HTMLFeature.js

@@ -0,0 +1,94 @@
+/**
+ * Nan0HTMLFeature
+ * Payload Lexical feature that registers the NaN0 custom nodes
+ * (nan0-element, nan0-raw, nan0-component) for server + client.
+ *
+ * Usage in a Payload collection:
+ * ```js
+ * editor: lexicalEditor({
+ *   features: ({ defaultFeatures }) => [
+ *     ...defaultFeatures,
+ *     Nan0HTMLFeature(),
+ *   ],
+ * })
+ * ```
+ */
+import { createServerFeature } from '@payloadcms/richtext-lexical'
+import { convertLexicalNodesToHTML } from '@payloadcms/richtext-lexical'
+import { createNode } from '@payloadcms/richtext-lexical'
+import { Nan0ElementNode } from './Nan0ElementNode.js'
+import { Nan0RawNode } from './Nan0RawNode.js'
+import { Nan0ComponentNode } from './Nan0ComponentNode.js'
+
+export const Nan0HTMLFeature = createServerFeature({
+  key: 'nan0html',
+  feature: {
+    ClientFeature: '@nan0web/ui-payload/richtext/client#Nan0HTMLFeatureClient',
+    nodes: [
+      createNode({
+        node: Nan0ElementNode,
+        converters: {
+          html: {
+            converter: async ({
+              converters,
+              currentDepth,
+              depth,
+              draft,
+              node,
+              overrideAccess,
+              parent,
+              req,
+              showHiddenFields,
+            }) => {
+              const childrenText = await convertLexicalNodesToHTML({
+                converters,
+                currentDepth,
+                depth,
+                draft,
+                lexicalNodes: node.children,
+                overrideAccess,
+                parent: { ...node, parent },
+                req,
+                showHiddenFields,
+              })
+              const attrs = node.getAttributes() || {}
+              const attrString = Object.entries(attrs)
+                .filter(([k]) => k !== 'class' && k !== 'style')
+                .map(([k, v]) => `${k}="${String(v).replaceAll('"', '"')}"`)
+                .join(' ')
+              const classAttr = attrs.class ? ` class="${Array.isArray(attrs.class) ? attrs.class.join(' ') : attrs.class}"` : ''
+              const styleAttr = attrs.style ? ` style="${String(attrs.style).replaceAll('"', '"')}"` : ''
+              return `<${node.getTag()}${classAttr}${styleAttr}${attrString ? ' ' + attrString : ''}>${childrenText}</${node.getTag()}>`
+            },
+            nodeTypes: [Nan0ElementNode.getType()],
+          },
+        },
+      }),
+      createNode({
+        node: Nan0RawNode,
+        converters: {
+          html: {
+            converter: ({ node }) => {
+              const source = node.getSource() || {}
+              return `<!-- nan0-raw:${source.tag || 'unknown'} -->`
+            },
+            nodeTypes: [Nan0RawNode.getType()],
+          },
+        },
+      }),
+      createNode({
+        node: Nan0ComponentNode,
+        converters: {
+          html: {
+            converter: ({ node }) => {
+              return `<!-- nan0-component:${node.getComponent()} -->`
+            },
+            nodeTypes: [Nan0ComponentNode.getType()],
+          },
+        },
+      }),
+    ],
+  },
+})
+
+export default Nan0HTMLFeature

package/src/richtext/Nan0RawNode.js

@@ -0,0 +1,92 @@
+/**
+ * Nan0RawNode
+ * Fallback for unknown NaN0HTML tags and structures that do not yet have
+ * a native or nan0-element adapter.
+ *
+ * Serialized shape:
+ * ```json
+ * {
+ *   "type": "nan0-raw",
+ *   "version": 1,
+ *   "source": {
+ *     "tag": "legacy-widget",
+ *     "attributes": { "data-mode": "legacy" },
+ *     "children": []
+ *   }
+ * }
+ * ```
+ *
+ * In the editor, this renders as a read-only block showing the tag name
+ * so the user knows something is stored but not yet editable natively.
+ * A future migration can replace nan0-raw with the appropriate node.
+ */
+import { ElementNode, $applyNodeReplacement } from 'lexical'
+
+export class Nan0RawNode extends ElementNode {
+  /** @type {{ tag: string, attributes: Record<string, any>, children: any[] }} */ __source
+
+  constructor({ source, key }) {
+    super(key)
+    this.__source = source
+  }
+
+  static clone(node) {
+    return new this({ source: { ...node.__source }, key: node.__key })
+  }
+
+  static getType() {
+    return 'nan0-raw'
+  }
+
+  static importJSON(serializedNode) {
+    return $createNan0RawNode({ source: serializedNode.source || { tag: 'unknown', attributes: {}, children: [] } })
+  }
+
+  exportJSON() {
+    return {
+      ...super.exportJSON(),
+      type: 'nan0-raw',
+      version: 1,
+      source: this.__source,
+    }
+  }
+
+  getSource() {
+    return this.getLatest().__source
+  }
+
+  isInline() {
+    return false
+  }
+
+  canBeEmpty() {
+    return true
+  }
+
+  createDOM(config) {
+    const el = document.createElement('div')
+    el.setAttribute('data-nan0-raw', this.__source.tag)
+    el.className = 'nan0-raw-fallback'
+    el.style.border = '1px dashed #ccc'
+    el.style.padding = '8px'
+    el.style.margin = '4px 0'
+    el.style.borderRadius = '4px'
+    el.style.background = '#fafafa'
+    el.style.fontSize = '0.85em'
+    el.style.color = '#888'
+    el.textContent = `[nan0-raw: ${this.__source.tag}]`
+    return el
+  }
+
+  updateDOM() {
+    return false
+  }
+}
+
+export function $createNan0RawNode({ source }) {
+  return $applyNodeReplacement(new Nan0RawNode({ source }))
+}
+
+export function $isNan0RawNode(node) {
+  return node instanceof Nan0RawNode
+}

package/src/richtext/client/index.js

@@ -0,0 +1,20 @@
+/**
+ * Nan0HTMLFeatureClient
+ * Client-side registration of NaN0 custom nodes for the Lexical editor.
+ * Imported via the Payload import map from `@nan0web/ui-payload/richtext/client`.
+ */
+'use client'
+
+import { Nan0ElementNode } from '../Nan0ElementNode.js'
+import { Nan0RawNode } from '../Nan0RawNode.js'
+import { Nan0ComponentNode } from '../Nan0ComponentNode.js'
+
+export const Nan0HTMLFeatureClient = (props = {}) => ({
+  clientFeatureProps: props,
+  feature: () => ({
+    nodes: [Nan0ElementNode, Nan0RawNode, Nan0ComponentNode],
+    sanitizedClientFeatureProps: props,
+  }),
+})
+
+export default Nan0HTMLFeatureClient

package/src/richtext/fromNan0Html.js

@@ -0,0 +1,294 @@
+/**
+ * fromNan0Html
+ * Converts a NaN0HTML AST (page.content / content) into a Payload Lexical state JSON.
+ *
+ * NaN0HTML AST shape:
+ *   - array       → sequence of blocks
+ *   - string      → text content
+ *   - object      → element with keys: `$attr` for attributes, lowercase tag keys for
+ *                   child elements, `Uppercase.With.Dot` keys for NaN0 components
+ *   - `tag: true` → void element (e.g. `br`, `hr`)
+ *
+ * Strategy:
+ *   - Clean elements (no attributes) map to native Lexical nodes where possible.
+ *   - Elements carrying any `$`-attribute are preserved losslessly as a `nan0-element`
+ *     node (tag + attributes + children) so round-trip back to NaN0HTML is lossless.
+ *   - Unknown tags fall back to a `nan0-raw` node and are recorded in the inventory.
+ *   - NaN0 components (`App.Header`, `Card.Details`, ...) become `nan0-component` nodes.
+ *
+ * The converter returns a plain structure; localization is handled at the Payload
+ * collection level, not here.
+ */
+
+// Lexical text format bitmask
+export const FORMAT = Object.freeze({
+  bold: 1 << 0,
+  italic: 1 << 1,
+  underline: 1 << 2,
+  strikethrough: 1 << 3,
+})
+
+// Native block-level tags we can represent without a custom node.
+const BLOCK_TAGS = new Set([
+  'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'ul', 'ol', 'li',
+  'blockquote', 'hr', 'br',
+  'table', 'thead', 'tbody', 'tr', 'td', 'th',
+])
+
+// Tags that map to native Lexical nodes.
+const NATIVE_TAG_MAP = {
+  p: 'paragraph',
+  h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading',
+  blockquote: 'blockquote',
+  hr: 'horizontalrule',
+  br: 'linebreak',
+}
+
+// Inline formatting tags → format bit added to descendant text nodes.
+const INLINE_FORMAT = {
+  strong: FORMAT.bold,
+  b: FORMAT.bold,
+  em: FORMAT.italic,
+  i: FORMAT.italic,
+  u: FORMAT.underline,
+}
+
+/**
+ * Recursively walk the NaN0HTML AST and collect unknown constructs.
+ * @param {any} node
+ * @param {Array<{tag: string, attributes: Object, parent: string}>} out
+ * @param {string} parent
+ */
+export function inventoryNan0Html(node, out = [], parent = 'root') {
+  if (node == null) return out
+  if (Array.isArray(node)) {
+    for (const child of node) inventoryNan0Html(child, out, parent)
+    return out
+  }
+  if (typeof node !== 'object') return out
+  for (const [key, value] of Object.entries(node)) {
+    if (key.startsWith('$')) continue
+    if (/^[a-z][a-z0-9]*$/.test(key)) {
+      if (!BLOCK_TAGS.has(key) && key !== 'a' && key !== 'img' && key !== 'span' && key !== 'div' && key !== 'wbr' && key !== 'small' && key !== 'sup') {
+        out.push({ tag: key, parent, attributes: collectAttrs(value) })
+      }
+      inventoryNan0Html(value, out, key)
+    } else if (/^[A-Z]/.test(key) && key.includes('.')) {
+      out.push({ component: key, parent })
+      inventoryNan0Html(value, out, key)
+    } else {
+      inventoryNan0Html(value, out, parent)
+    }
+  }
+  return out
+}
+
+function collectAttrs(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  const attrs = {}
+  for (const [k, v] of Object.entries(value)) {
+    if (k.startsWith('$')) attrs[k.slice(1)] = v
+  }
+  return attrs
+}
+
+/**
+ * Convert a NaN0HTML AST into a Payload Lexical root state.
+ * @param {any} content NaN0HTML AST (array of blocks, or a single block)
+ * @returns {{ root: { type: string, version: number, children: any[] } }}
+ */
+export function fromNan0Html(content) {
+  const children = convertBlock(content, 0)
+  return {
+    root: {
+      type: 'root',
+      version: 1,
+      children,
+    },
+  }
+}
+
+/**
+ * Convert a block (array of elements, or a single element) into Lexical children.
+ */
+function convertBlock(node, format) {
+  if (node == null) return []
+  if (Array.isArray(node)) {
+    const out = []
+    for (const child of node) {
+      out.push(...convertBlock(child, format))
+    }
+    return out
+  }
+  if (typeof node === 'string') {
+    return [textNode(node, format)]
+  }
+  if (typeof node !== 'object') return []
+  // Object: split `$`-attributes from element keys.
+  const attrs = {}
+  const elements = []
+  for (const [key, value] of Object.entries(node)) {
+    if (key.startsWith('$')) {
+      attrs[key.slice(1)] = value
+      continue
+    }
+    elements.push([key, value])
+  }
+  const out = []
+  for (const [tag, value] of elements) {
+    out.push(...convertElement(tag, value, attrs, format))
+  }
+  return out
+}
+
+/**
+ * Convert a single tag element into Lexical nodes.
+ * `attrs` are the attributes collected at the same object level.
+ */
+function convertElement(tag, value, attrs, format) {
+  // NaN0 component
+  if (/^[A-Z]/.test(tag) && tag.includes('.')) {
+    const props = value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+    return [componentNode(tag, props)]
+  }
+
+  // Inline formatting tags alter the text format of descendants.
+  if (INLINE_FORMAT[tag] != null) {
+    const childFormat = format | INLINE_FORMAT[tag]
+    return convertBlock(value, childFormat)
+  }
+
+  let children = []
+  if (value === true) {
+    // void element
+    children = []
+  } else if (Array.isArray(value) || typeof value === 'string') {
+    children = convertBlock(value, format)
+  } else if (value && typeof value === 'object') {
+    children = convertBlock(value, format)
+  }
+
+  const hasAttrs = Object.keys(attrs).length > 0
+
+  switch (tag) {
+    case 'p':
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [blockNode('paragraph', children)]
+    case 'h1': case 'h2': case 'h3': case 'h4': case 'h5': case 'h6':
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [blockNode('heading', children, { tag })]
+    case 'blockquote':
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [blockNode('blockquote', children)]
+    case 'hr':
+      if (hasAttrs) return [elementNode(tag, attrs, [])]
+      return [{ type: 'horizontalrule', version: 1 }]
+    case 'br':
+      if (hasAttrs) return [elementNode(tag, attrs, [])]
+      return [{ type: 'linebreak', version: 1 }]
+    case 'ul': case 'ol':
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [listNode(tag, value, children)]
+    case 'li':
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [{ type: 'listitem', version: 1, value: 1, children }]
+    case 'a': {
+      const url = attrs.href || '#'
+      const linkAttrs = { url, linkType: 'custom' }
+      if (attrs.target) linkAttrs.newTab = String(attrs.target) === '_blank'
+      if (attrs.rel) linkAttrs.rel = attrs.rel
+      const node = { type: 'link', version: 1, fields: linkAttrs, children }
+      // Preserve extra attributes losslessly.
+      return [wrapElementIfNeeded(tag, attrs, node)]
+    }
+    case 'img': {
+      const src = attrs.src || ''
+      const node = {
+        type: 'upload',
+        version: 1,
+        fields: { relationTo: 'media', value: src },
+        children: [],
+      }
+      return [wrapElementIfNeeded(tag, attrs, node)]
+    }
+    case 'table': case 'thead': case 'tbody':
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [{ type: 'table', version: 1, children }]
+    case 'tr':
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [{ type: 'tablerow', version: 1, children }]
+    case 'td': case 'th': {
+      const cell = { type: 'tablecell', version: 1, header: tag === 'th', children }
+      return [wrapElementIfNeeded(tag, attrs, cell)]
+    }
+    case 'span': case 'div': case 'section': case 'header': case 'nav':
+    case 'figure': case 'caption': case 'small': case 'sup': case 'wbr':
+    case 'picture': case 'source':
+      // These are either inline or block wrappers; preserve attributes if any.
+      if (hasAttrs) return [elementNode(tag, attrs, children)]
+      return [blockNode('paragraph', children)]
+    default:
+      // Unknown tag → preserve losslessly as nan0-raw.
+      return [rawNode(tag, attrs, children)]
+  }
+}
+
+/**
+ * If the element carries attributes beyond those consumed by the native node,
+ * wrap it in a lossless `nan0-element` node so nothing is dropped.
+ */
+function wrapElementIfNeeded(tag, attrs, node) {
+  if (!attrs) return [node]
+  return [elementNode(tag, attrs, node.children || [])]
+}
+
+function textNode(text, format) {
+  return { type: 'text', text, format }
+}
+
+function blockNode(type, children, extra = {}) {
+  return { type, version: 1, ...extra, children }
+}
+
+function listNode(tag, value, children) {
+  const listType = tag === 'ol' ? 'number' : 'bullet'
+  let start = 1
+  if (value && typeof value === 'object' && !Array.isArray(value) && value.$start != null) {
+    start = Number(value.$start) || 1
+  }
+  return { type: 'list', version: 1, listType, start, tag, children }
+}
+
+function elementNode(tag, attrs, children) {
+  return {
+    type: 'nan0-element',
+    version: 1,
+    tag,
+    attributes: attrs,
+    children,
+  }
+}
+
+function componentNode(component, props) {
+  return {
+    type: 'nan0-component',
+    version: 1,
+    component,
+    props,
+  }
+}
+
+function rawNode(tag, attrs, children) {
+  return {
+    type: 'nan0-raw',
+    version: 1,
+    source: {
+      tag,
+      attributes: attrs,
+      children,
+    },
+  }
+}
+
+export default fromNan0Html

package/src/richtext/index.js

@@ -0,0 +1,10 @@
+/**
+ * richtext package index
+ * NaN0HTML → Payload Lexical conversion toolkit.
+ *
+ * Pure functions (fromNan0Html, inventoryNan0Html) are safe to import
+ * from any context. Custom node classes (Nan0ElementNode, etc.) require
+ * `lexical` to be resolvable and are available via direct import paths.
+ */
+export { default as fromNan0Html, inventoryNan0Html, FORMAT } from './fromNan0Html.js'
+export { default as toNan0Html } from './toNan0Html.js'