@byline/richtext-lexical 0.9.3

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@byline/richtext-lexical",
+  "private": false,
+  "type": "module",
+  "license": "MPL-2.0",
+  "version": "0.9.3",
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "description": "Byline CMS Lexical richtext editor adapter",
+  "keywords": [
+    "cms",
+    "headless cms",
+    "content management",
+    "richtext",
+    "lexical",
+    "editor"
+  ],
+  "homepage": "https://github.com/Byline-CMS/bylinecms.dev",
+  "bugs": {
+    "url": "https://github.com/Byline-CMS/bylinecms.dev/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byline-CMS/bylinecms.dev.git",
+    "directory": "packages/richtext-lexical"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "main": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "main": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "dependencies": {
+    "@infonomic/uikit": "^6.7.1",
+    "@lexical/clipboard": "0.44.0",
+    "@lexical/code": "0.44.0",
+    "@lexical/hashtag": "0.44.0",
+    "@lexical/headless": "0.44.0",
+    "@lexical/html": "0.44.0",
+    "@lexical/link": "0.44.0",
+    "@lexical/list": "0.44.0",
+    "@lexical/mark": "0.44.0",
+    "@lexical/markdown": "0.44.0",
+    "@lexical/overflow": "0.44.0",
+    "@lexical/react": "0.44.0",
+    "@lexical/rich-text": "0.44.0",
+    "@lexical/selection": "0.44.0",
+    "@lexical/table": "0.44.0",
+    "@lexical/utils": "0.44.0",
+    "classnames": "^2.5.1",
+    "lexical": "0.44.0",
+    "lodash-es": "^4.18.1",
+    "npm-run-all": "^4.1.5",
+    "prism-react-renderer": "^2.4.1",
+    "react-error-boundary": "^6.1.1",
+    "@byline/client": "0.9.3",
+    "@byline/core": "0.9.3",
+    "@byline/ui": "0.9.3"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.14",
+    "@rsbuild/plugin-react": "^2.0.0",
+    "@rslib/core": "^0.21.3",
+    "@types/lodash": "^4.17.24",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^25.6.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "lightningcss": "^1.32.0",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "rimraf": "^6.1.3",
+    "typescript": "6.0.3",
+    "typescript-plugin-css-modules": "^5.2.0",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "files": [
+      "dist/",
+      "src/"
+    ]
+  },
+  "scripts": {
+    "dev": "run-p dev:*",
+    "dev:code": "rslib build --watch",
+    "build": "run-s build:*",
+    "build:clean": "rimraf dist build",
+    "build:code": "rslib build",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf node_modules dist build types .turbo",
+    "lint": "biome check --write --unsafe --diagnostic-level=error",
+    "skip:test": "vitest"
+  }
+}

package/src/declarations.d.ts

@@ -0,0 +1,4 @@
+declare module '*.css' {
+  const classes: { [key: string]: string }
+  export default classes
+}

package/src/field/apply-value-plugin.tsx

@@ -0,0 +1,104 @@
+'use client'
+
+import type * as React from 'react'
+import { useEffect, useRef } from 'react'
+
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
+import type { SerializedEditorState } from 'lexical'
+
+import { APPLY_VALUE_TAG } from './constants'
+import { hashSerializedState } from './utils/hashSerializedState'
+
+export function ApplyValuePlugin({
+  value,
+  incomingHash,
+  lastEmittedHashRef,
+  normalizedIncomingHashRef,
+  hasNormalizedBaselineRef,
+}: {
+  value?: SerializedEditorState | null
+  incomingHash?: string
+  lastEmittedHashRef: React.RefObject<string | undefined>
+  normalizedIncomingHashRef: React.RefObject<string | undefined>
+  hasNormalizedBaselineRef: React.RefObject<boolean>
+}): React.JSX.Element | null {
+  const [editor] = useLexicalComposerContext()
+  const lastAppliedHashRef = useRef<string | undefined>(undefined)
+
+  const cancelWaiterRef = useRef<() => void>(undefined)
+
+  useEffect(() => {
+    if (value == null) return
+
+    const nextRawHash = incomingHash
+
+    if (nextRawHash === lastEmittedHashRef.current) {
+      if (hasNormalizedBaselineRef.current !== true) {
+        hasNormalizedBaselineRef.current = true
+        if (cancelWaiterRef.current) {
+          cancelWaiterRef.current()
+          cancelWaiterRef.current = undefined
+        }
+      }
+      return
+    }
+
+    if (nextRawHash === lastAppliedHashRef.current) {
+      // If the incoming value matches what we last applied, we assume the previous
+      // waiter (if any) is still running or has completed.
+      // We do NOT want to cancel it just because of a re-render.
+      return
+    }
+
+    // We are about to apply a new external value.
+    // Cancel any pending waiter for the previous value.
+    if (cancelWaiterRef.current) {
+      cancelWaiterRef.current()
+      cancelWaiterRef.current = undefined
+    }
+
+    hasNormalizedBaselineRef.current = false
+
+    const nextState = editor.parseEditorState(value)
+
+    editor.update(
+      () => {
+        editor.setEditorState(nextState)
+      },
+      { tag: APPLY_VALUE_TAG }
+    )
+    lastAppliedHashRef.current = nextRawHash
+
+    let cancelled = false
+    cancelWaiterRef.current = () => {
+      cancelled = true
+    }
+
+    // Capture what Lexical *actually* settled on after applying + running immediate transforms.
+    // Two rAFs helps ensure we’re past the commit + plugin side-effects.
+    queueMicrotask(() => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          if (cancelled) return
+          const settled = editor.getEditorState().toJSON() as SerializedEditorState
+          normalizedIncomingHashRef.current = hashSerializedState(settled)
+          hasNormalizedBaselineRef.current = true
+        })
+      })
+    })
+
+    // Important: Do NOT cancel the waiter in the useEffect cleanup.
+    // If the component re-renders with the same value (hash), we want the existing waiter to continue.
+    // If the component unmounts, we also want the waiter to finish setting the baseline for the parent.
+    // We only cancel if we are about to apply a DIFFERENT value (handled above).
+  }, [
+    editor,
+    value,
+    incomingHash,
+    lastEmittedHashRef,
+    normalizedIncomingHashRef,
+    hasNormalizedBaselineRef,
+  ])
+
+  return null
+}

package/src/field/config/default.ts

@@ -0,0 +1,58 @@
+import type { EditorConfig as LexicalEditorConfig } from 'lexical'
+
+import { theme } from '../themes/lexical-editor-theme'
+import type { EditorConfig, EditorSettings } from './types'
+
+export const defaultEditorLexicalConfig: LexicalEditorConfig = {
+  namespace: 'LexicalRichText',
+  theme,
+}
+
+export const DEFAULT_EDITOR_SETTINGS: EditorSettings = {
+  options: {
+    disableBeforeInput: false,
+    autocomplete: false,
+    charLimit: false,
+    charLimitUtf8: false,
+    collab: false,
+    maxLength: false,
+    richText: true,
+    measureTypingPerf: false,
+    showNestedEditorTreeView: false,
+    showTableOfContents: false,
+    showTreeView: false,
+    textAlignment: true,
+    tablePlugin: true,
+    tableCellBackgroundColor: true,
+    tableCellMerge: true,
+    tableActionMenuPlugin: true,
+    layoutPlugin: true,
+    outputHTML: false,
+    outputMarkdown: false,
+    autoFocusPlugin: false,
+    autoLinkPlugin: false,
+    inlineImagePlugin: true,
+    admonitionPlugin: true,
+    checkListPlugin: true,
+    listPlugin: true,
+    codeHighlightPlugin: true,
+    horizontalRulePlugin: true,
+    markdownShortcutPlugin: false,
+    undoRedo: true,
+    textStyle: true,
+    inlineCode: true,
+    links: true,
+    floatingLinkEditorPlugin: true,
+    floatingTextFormatToolbarPlugin: false,
+    autoEmbedPlugin: true,
+    debug: false,
+  },
+  inlineImageUploadCollection: 'media',
+  placeholderText: 'Enter some rich text...',
+  embedRelationsOnSave: true,
+}
+
+export const defaultEditorConfig: EditorConfig = {
+  settings: DEFAULT_EDITOR_SETTINGS,
+  lexical: defaultEditorLexicalConfig,
+}

package/src/field/config/editor-config-context.tsx

@@ -0,0 +1,60 @@
+'use client'
+
+import type * as React from 'react'
+import { createContext, useCallback, useContext, useMemo, useState } from 'react'
+
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
+
+import { DEFAULT_EDITOR_SETTINGS } from './default'
+import type { EditorSettings, OptionName } from './types'
+
+// Should always produce a 20 character pseudo-random string
+function generateQuickGuid(): string {
+  return Math.random().toString(36).substring(2, 12) + Math.random().toString(36).substring(2, 12)
+}
+interface ContextType {
+  setOption: (name: OptionName, value: boolean) => void
+  config: EditorSettings
+  uuid: string
+}
+
+const Context: React.Context<ContextType> = createContext({
+  setOption: (_name: OptionName, _value: boolean) => {},
+  config: DEFAULT_EDITOR_SETTINGS,
+  uuid: generateQuickGuid(),
+})
+
+export const EditorConfigContext = ({
+  children,
+  config: configFromProps,
+}: {
+  children: React.ReactNode
+  config?: EditorSettings
+}): React.JSX.Element => {
+  const [config, setConfig] = useState(configFromProps ?? DEFAULT_EDITOR_SETTINGS)
+  // State to store the UUID
+  const [uuid] = useState(() => generateQuickGuid())
+  const [editor] = useLexicalComposerContext()
+
+  const setOption = useCallback((option: OptionName, value: boolean) => {
+    setConfig((config) => {
+      const options = { ...config.options, [option as string]: value }
+      return { ...config, options }
+    })
+  }, [])
+
+  const editorContext = useMemo(
+    () => ({ setOption, config, uuid, editor }),
+    [setOption, config, uuid, editor]
+  )
+
+  return <Context.Provider value={editorContext}>{children}</Context.Provider>
+}
+
+export const useEditorConfig = (): ContextType => {
+  const context = useContext(Context)
+  if (context === undefined) {
+    throw new Error('useEditorConfig must be used within an EditorConfigContext')
+  }
+  return context
+}

package/src/field/config/types.ts

@@ -0,0 +1,67 @@
+import type { EditorConfig as LexicalEditorConfig } from 'lexical'
+
+export type OptionName =
+  | 'disableBeforeInput'
+  | 'autocomplete'
+  | 'charLimit'
+  | 'charLimitUtf8'
+  | 'collab'
+  | 'maxLength'
+  | 'richText'
+  | 'measureTypingPerf'
+  | 'showNestedEditorTreeView'
+  | 'showTableOfContents'
+  | 'showTreeView'
+  | 'textAlignment'
+  | 'tablePlugin'
+  | 'tableCellBackgroundColor'
+  | 'tableCellMerge'
+  | 'tableActionMenuPlugin'
+  | 'layoutPlugin'
+  | 'outputHTML'
+  | 'outputMarkdown'
+  | 'autoFocusPlugin'
+  | 'autoLinkPlugin'
+  | 'inlineImagePlugin'
+  | 'admonitionPlugin'
+  | 'checkListPlugin'
+  | 'listPlugin'
+  | 'codeHighlightPlugin'
+  | 'horizontalRulePlugin'
+  | 'markdownShortcutPlugin'
+  | 'undoRedo'
+  | 'textStyle'
+  | 'inlineCode'
+  | 'links'
+  | 'floatingLinkEditorPlugin'
+  | 'floatingTextFormatToolbarPlugin'
+  | 'autoEmbedPlugin'
+  | 'debug'
+
+export interface EditorSettings {
+  options: Record<OptionName, boolean>
+  inlineImageUploadCollection: string
+  placeholderText: string
+  /**
+   * Whether relation-bearing nodes (link, inline-image) embed the picker's
+   * resolved target fields (`title`, `path`, `altText`, `image`, `sizes`)
+   * into the persisted Lexical JSON at modal-save time. Defaults to `true`.
+   *
+   * Mirrors `RichTextField.embedRelationsOnSave`. The lexical wrapper
+   * (`richtext-field.tsx`) merges the field-level value over the resolved
+   * editor settings so each field gets the policy it asked for.
+   */
+  embedRelationsOnSave: boolean
+}
+
+export interface EditorSettingsOverride {
+  options?: Partial<Record<OptionName, boolean>>
+  inlineImageUploadCollection?: string
+  placeholderText?: string
+  embedRelationsOnSave?: boolean
+}
+
+export interface EditorConfig {
+  settings: EditorSettings
+  lexical: LexicalEditorConfig
+}

package/src/field/constants.ts

@@ -0,0 +1 @@
+export const APPLY_VALUE_TAG = 'payload-apply-value'

package/src/field/content-editable-inline.tsx

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type * as React from 'react'
+
+import { ContentEditable as LexicalContentEditable } from '@lexical/react/LexicalContentEditable'
+import cx from 'classnames'
+
+import './content-editable.css'
+
+// TODO: implement an inline version of content editable for
+// image captions that will not allow inserted paragraphs.
+// NOTE: we disable all config checks and draggable blocks
+// as in content-editable.tsx - because this version will
+// appear inside caption areas for images.
+export default function ContentEditableInline({
+  className,
+}: {
+  className?: string
+}): React.JSX.Element {
+  const classes = cx(className)
+  return <LexicalContentEditable className={classes} />
+}

package/src/field/content-editable.css

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+.ContentEditable__root {
+  border: 0;
+  font-size: 1.1rem;
+  line-height: 1.5;
+  display: block;
+  position: relative;
+  tab-size: 1;
+  outline: 0;
+  padding: 8px 2px;
+}
+
+.ContentEditable__with_draggable_blocks {
+  padding: 8px 2px 40px 22px;
+}
+
+@media (max-width: 1025px) {
+  .ContentEditable__root {
+    padding-left: 2px;
+    padding-right: 2px;
+  }
+}

package/src/field/content-editable.tsx

@@ -0,0 +1,27 @@
+'use client'
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type * as React from 'react'
+
+import { ContentEditable as LexicalContentEditable } from '@lexical/react/LexicalContentEditable'
+import cx from 'classnames'
+
+import { useEditorConfig } from './config/editor-config-context'
+
+import './content-editable.css'
+
+export function ContentEditable({ className }: { className?: string }): React.JSX.Element {
+  const { config } = useEditorConfig()
+  // const classes = cx('ContentEditable__root', className, {
+  //   ContentEditable__with_draggable_blocks: config.options.draggableBlocks
+  // })
+  const classes = cx('ContentEditable__root', className)
+
+  return <LexicalContentEditable className={classes} />
+}

package/src/field/context/shared-autocomplete-context.tsx

@@ -0,0 +1,61 @@
+'use client'
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type * as React from 'react'
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from 'react'
+
+type Suggestion = null | string
+type CallbackFn = (newSuggestion: Suggestion) => void
+type SubscribeFn = (callbackFn: CallbackFn) => () => void
+type PublishFn = (newSuggestion: Suggestion) => void
+type ContextShape = [SubscribeFn, PublishFn]
+type HookShape = [suggestion: Suggestion, setSuggestion: PublishFn]
+
+const Context: React.Context<ContextShape> = createContext([
+  (_cb) => () => {},
+  (_newSuggestion: Suggestion) => {},
+])
+
+export const SharedAutocompleteContext = ({
+  children,
+}: {
+  children: ReactNode
+}): React.JSX.Element => {
+  const context: ContextShape = useMemo(() => {
+    let suggestion: Suggestion | null = null
+    const listeners = new Set<CallbackFn>()
+    return [
+      (cb: (newSuggestion: Suggestion) => void) => {
+        cb(suggestion)
+        listeners.add(cb)
+        return () => {
+          listeners.delete(cb)
+        }
+      },
+      (newSuggestion: Suggestion) => {
+        suggestion = newSuggestion
+        for (const listener of listeners) {
+          listener(newSuggestion)
+        }
+      },
+    ]
+  }, [])
+  return <Context.Provider value={context}>{children}</Context.Provider>
+}
+
+export const useSharedAutocompleteContext = (): HookShape => {
+  const [subscribe, publish]: ContextShape = useContext(Context)
+  const [suggestion, setSuggestion] = useState<Suggestion>(null)
+  useEffect(() => {
+    return subscribe((newSuggestion: Suggestion) => {
+      setSuggestion(newSuggestion)
+    })
+  }, [subscribe])
+  return [suggestion, publish]
+}

package/src/field/context/shared-history-context.tsx

@@ -0,0 +1,30 @@
+'use client'
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type * as React from 'react'
+import { createContext, type ReactNode, useContext, useMemo } from 'react'
+
+import type { HistoryState } from '@lexical/react/LexicalHistoryPlugin'
+import { createEmptyHistoryState } from '@lexical/react/LexicalHistoryPlugin'
+
+interface ContextShape {
+  historyState?: HistoryState
+}
+
+const Context: React.Context<ContextShape> = createContext({})
+
+export const SharedHistoryContext = ({ children }: { children: ReactNode }): React.JSX.Element => {
+  const historyContext = useMemo(() => ({ historyState: createEmptyHistoryState() }), [])
+  return <Context.Provider value={historyContext}>{children}</Context.Provider>
+}
+
+export const useSharedHistoryContext = (): ContextShape => {
+  return useContext(Context)
+}

package/src/field/context/shared-on-change-context.tsx

@@ -0,0 +1,32 @@
+'use client'
+
+import type * as React from 'react'
+import { createContext, type ReactNode, useContext, useMemo } from 'react'
+
+import type { EditorState, LexicalEditor } from 'lexical'
+
+interface ContextType {
+  onChange?: (editorState: EditorState, editor: LexicalEditor, tags: Set<string>) => void
+}
+
+const Context: React.Context<ContextType> = createContext({})
+
+export const SharedOnChangeContext = ({
+  children,
+  onChange,
+}: {
+  children: ReactNode
+  onChange: (editorState: EditorState, editor: LexicalEditor, tags: Set<string>) => void
+}): React.JSX.Element => {
+  const sharedOnChangeContext = useMemo(() => ({ onChange }), [onChange])
+  return <Context.Provider value={sharedOnChangeContext}>{children}</Context.Provider>
+}
+
+export const useSharedOnChange = (): ContextType => {
+  const context = useContext(Context)
+  if (context === undefined) {
+    throw new Error('useSharedOnChange must be used within an SharedOnChangeProvider')
+  } else {
+    return context
+  }
+}

package/src/field/debug.tsx

@@ -0,0 +1,39 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+'use client'
+
+import type * as React from 'react'
+
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
+import { CLEAR_EDITOR_COMMAND } from 'lexical'
+
+export function Debug(): React.JSX.Element {
+  const [editor] = useLexicalComposerContext()
+
+  function handleOnSave(): void {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(editor.getEditorState()))
+  }
+
+  function handleOnClear(): void {
+    editor.dispatchCommand(CLEAR_EDITOR_COMMAND, undefined)
+    editor.focus()
+  }
+
+  return (
+    <div className="editor-actions">
+      <button type="button" onClick={handleOnSave}>
+        Save
+      </button>
+      <button type="button" onClick={handleOnClear}>
+        Clear
+      </button>
+    </div>
+  )
+}