@byline/richtext-lexical 0.9.3

package/src/richtext-field.module.css

@@ -0,0 +1,29 @@
+/**
+ * RichTextField — Lexical rich text editor field.
+ *
+ * Override handles:
+ *   .byline-field-richtext        — outer wrapper
+ *   .byline-field-richtext-label  — label row containing label + locale badge
+ *   .byline-field-richtext-body   — vertical stack containing editor + error
+ */
+
+.wrapper,
+:global(.byline-field-richtext) {
+  display: flex;
+  flex: 1 1 0%;
+  height: 100%;
+}
+
+.label-row,
+:global(.byline-field-richtext-label) {
+  display: flex;
+  align-items: center;
+}
+
+.body,
+:global(.byline-field-richtext-body) {
+  display: flex;
+  flex: 1 1 0%;
+  flex-direction: column;
+  gap: 0.25rem;
+}

package/src/richtext-field.tsx

@@ -0,0 +1,113 @@
+/**
+ * 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
+ */
+
+import type React from 'react'
+
+import type { RichTextField as FieldType } from '@byline/core'
+import { LocaleBadge, useFieldError, useFieldValue } from '@byline/ui'
+import { ErrorText, Label } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { defaultEditorConfig } from './field/config/default'
+import { EditorField } from './field/editor-field'
+import styles from './richtext-field.module.css'
+import type { EditorConfig } from './field/config/types'
+
+interface Props {
+  field: FieldType
+  readonly?: boolean
+  instanceKey?: string
+  value?: any
+  defaultValue?: any
+  editorConfig?: EditorConfig
+  onChange?: (value: any) => void
+  path?: string
+  /** When provided, renders a LocaleBadge next to the field label. */
+  locale?: string
+}
+
+export const RichTextField = ({
+  field,
+  value,
+  defaultValue,
+  editorConfig,
+  readonly = false,
+  instanceKey,
+  onChange,
+  path,
+  locale,
+}: Props) => {
+  const fieldPath = path ?? field.name
+  const fieldError = useFieldError(fieldPath)
+  const fieldValue = useFieldValue<any>(fieldPath)
+  const incomingValue = value ?? fieldValue
+  const incomingDefault = defaultValue
+
+  const fieldId = instanceKey ? `${field.name}-${instanceKey}` : field.name
+
+  // Resolve the editor config with field-level priority:
+  //   1. `field.editorConfig` — set on the schema field itself (most specific).
+  //   2. `editorConfig` prop  — baked in at registration via `lexicalEditor()`.
+  //   3. `defaultEditorConfig` — package default.
+  // The schema-level value is typed as `unknown` at the `@byline/core` boundary,
+  // so the cast lives here where the Lexical config shape is known.
+  const baseEditorConfig: EditorConfig =
+    (field.editorConfig as EditorConfig | undefined) ?? editorConfig ?? defaultEditorConfig
+
+  // Adapter-agnostic field-level lever — when present, override the resolved
+  // editor settings so the inline-image / link modals see this field's policy.
+  const resolvedEditorConfig: EditorConfig =
+    field.embedRelationsOnSave === undefined
+      ? baseEditorConfig
+      : {
+          ...baseEditorConfig,
+          settings: {
+            ...baseEditorConfig.settings,
+            embedRelationsOnSave: field.embedRelationsOnSave,
+          },
+        }
+
+  // Assemble the label node here (a Byline-level concern) so that the editor
+  // component itself stays free of any Byline-specific dependencies.
+  const labelNode: React.ReactNode =
+    locale && field.label ? (
+      <div className={cx('byline-field-richtext-label', styles['label-row'])}>
+        <Label
+          id={`${fieldId}-label`}
+          label={field.label}
+          htmlFor={fieldId}
+          required={!field.optional}
+        />
+        <LocaleBadge locale={locale} />
+      </div>
+    ) : (
+      field.label
+    )
+
+  return (
+    <div className={cx('byline-field-richtext', field.name, styles.wrapper)}>
+      <div className={cx('byline-field-richtext-body', styles.body)}>
+        <EditorField
+          onChange={onChange}
+          editorConfig={resolvedEditorConfig}
+          id={fieldId}
+          name={field.name}
+          description={field.helpText}
+          readonly={readonly}
+          label={labelNode}
+          required={!field.optional}
+          value={incomingValue}
+          defaultValue={incomingDefault}
+          // Ensure React fully remounts when instanceKey changes
+          key={fieldId}
+        />
+        {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError} />}
+      </div>
+    </div>
+  )
+}

package/src/server.ts

@@ -0,0 +1,85 @@
+/**
+ * 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
+ */
+
+/**
+ * Server-side entry point for the Lexical adapter — registered into
+ * `ServerConfig.fields.richText.populate`. No React, no DOM, no Lexical
+ * runtime — safe to import from server-only modules.
+ *
+ * @example
+ * ```ts
+ * // apps/webapp/byline/server.config.ts
+ * import { lexicalEditorServer } from '@byline/richtext-lexical/server'
+ * import { defineServerConfig } from '@byline/core'
+ * import { getAdminBylineClient } from '@/lib/byline-client'
+ *
+ * defineServerConfig({
+ *   // …
+ *   fields: {
+ *     richText: { populate: lexicalEditorServer({ getClient: getAdminBylineClient }) },
+ *   },
+ * })
+ * ```
+ */
+
+import type { BylineClient } from '@byline/client'
+import type { RichTextPopulateContext, RichTextPopulateFn } from '@byline/core'
+
+import { type LexicalNodeVisitor, runLexicalPopulate } from './field/lexical-populate-shared'
+import { inlineImageVisitor } from './field/plugins/inline-image-plugin/populate'
+import { linkVisitor } from './field/plugins/link-plugin/populate'
+
+export { inlineImageVisitor } from './field/plugins/inline-image-plugin/populate'
+export { linkVisitor } from './field/plugins/link-plugin/populate'
+export type {
+  LexicalNodeLike,
+  LexicalNodeVisitor,
+  PendingHydration,
+} from './field/lexical-populate-shared'
+
+export interface LexicalServerOptions {
+  /**
+   * Returns the server-side `BylineClient` used to batch-fetch target
+   * documents. Typically the host application's cached singleton (e.g.
+   * `getAdminBylineClient` in the webapp). Resolved lazily on every
+   * populate call so registration order doesn't matter.
+   */
+  getClient: () => BylineClient
+  /**
+   * Override the visitor list. Defaults to every visitor the package
+   * ships — currently `[inlineImageVisitor, linkVisitor]`. Useful when a
+   * host wants to register additional custom visitors alongside the
+   * built-ins, or temporarily disable a built-in:
+   *
+   * ```ts
+   * lexicalEditorServer({
+   *   getClient,
+   *   visitors: [inlineImageVisitor, linkVisitor, myCustomEmbedVisitor],
+   * })
+   * ```
+   */
+  visitors?: LexicalNodeVisitor[]
+}
+
+/**
+ * Build the registered `RichTextPopulateFn`. Composes every supplied
+ * visitor and runs them in a single tree walk per call. The framework
+ * invokes this function once per rich-text leaf it discovers in a
+ * document tree, gated by each leaf field's `populateRelationsOnRead`.
+ */
+export function lexicalEditorServer(options: LexicalServerOptions): RichTextPopulateFn {
+  const visitors = options.visitors ?? [inlineImageVisitor, linkVisitor]
+  return async (ctx: RichTextPopulateContext): Promise<void> => {
+    await runLexicalPopulate({
+      client: options.getClient(),
+      readContext: ctx.readContext,
+      visitors,
+      values: [ctx.value],
+    })
+  }
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+import type { EditorConfig as LexicalEditorConfig, SerializedEditorState } from 'lexical'
+
+import type { EditorConfig, EditorSettings } from './field/config/types'
+
+export interface LexicalEditorProps {
+  settings?: (config: EditorSettings) => EditorSettings
+  lexical?: LexicalEditorConfig
+}
+
+export type EditorFieldProps = {
+  name: string
+  id: string
+  /**
+   * Accepts a plain string (EditorComponent wraps it in a Label with htmlFor/required)
+   * or a pre-composed ReactNode for callers that need to inject extra elements (e.g. a
+   * locale badge). When a ReactNode is passed, the caller is responsible for setting
+   * htmlFor and required on any Label it renders.
+   */
+  label?: React.ReactNode
+  description?: string
+  required?: boolean
+  readonly?: boolean
+  placeholder?: string
+  className?: string
+  minHeight?: number | string
+  maxHeight?: number | string
+  editorConfig: EditorConfig
+  defaultValue?: SerializedEditorState
+  value?: SerializedEditorState
+  // NOTE: Temporary feature props via React nodes.
+  // These must be replaced with serializable config options that map to
+  // import maps for feature components and plugins in the future.
+  featureBeforeEditor?: React.ReactNode[]
+  featureAfterEditor?: React.ReactNode[]
+  featureChildren?: React.ReactNode[]
+  onChange?: (value: SerializedEditorState) => void
+  validate?: (
+    value: SerializedEditorState | undefined,
+    options: { required?: boolean }
+  ) => string | boolean | Promise<string | boolean>
+  onError?: (error: Error) => void
+  lexicalEditorProps?: LexicalEditorProps
+}

package/src/validate/createEmptyEditorState.ts

@@ -0,0 +1,52 @@
+import type {
+  SerializedEditorState,
+  SerializedLexicalNode,
+  SerializedParagraphNode,
+  SerializedRootNode,
+} from 'lexical'
+
+/**
+ * createEmptyEditorState
+ * @returns 
+ * "root": {
+        "children": [{
+                "children": [],
+                "direction": null,
+                "format": "",
+                "indent": 0,
+                "type": "paragraph",
+                "version": 1,
+                "textFormat": 0,
+                "textStyle": ""
+            }
+        ],
+        "direction": null,
+        "format": "",
+        "indent": 0,
+        "type": "root",
+        "version": 1
+    }
+ */
+export function createEmptyEditorState(): SerializedEditorState<SerializedLexicalNode> {
+  const emptyParagraphNode: SerializedParagraphNode = {
+    children: [],
+    direction: null,
+    format: '',
+    indent: 0,
+    type: 'paragraph',
+    version: 1,
+    textFormat: 0,
+    textStyle: '',
+  }
+
+  const rootNode: SerializedRootNode = {
+    children: [emptyParagraphNode],
+    direction: null,
+    format: '',
+    indent: 0,
+    type: 'root',
+    version: 1,
+  }
+
+  return { root: rootNode }
+}

package/src/validate/hasText.test.ts

@@ -0,0 +1,89 @@
+import type {
+  SerializedEditorState,
+  SerializedLexicalNode,
+  SerializedParagraphNode,
+  SerializedRootNode,
+  SerializedTextNode,
+} from 'lexical'
+import { describe, expect, it } from 'vitest'
+
+import { hasText } from './hasText'
+
+type State = SerializedEditorState<SerializedLexicalNode>
+
+import { createEmptyEditorState } from './createEmptyEditorState'
+
+function rootState(children: SerializedRootNode['children']): State {
+  return {
+    root: {
+      children,
+      direction: null,
+      format: '',
+      indent: 0,
+      type: 'root',
+      version: 1,
+    } as SerializedRootNode,
+  }
+}
+
+function emptyParagraph(
+  children: SerializedParagraphNode['children'] = []
+): SerializedParagraphNode {
+  return {
+    children,
+    direction: null,
+    format: '',
+    indent: 0,
+    type: 'paragraph',
+    version: 1,
+    textFormat: 0,
+    textStyle: '',
+  } as SerializedParagraphNode
+}
+
+function textNode(text: string): SerializedTextNode {
+  return {
+    detail: 0,
+    format: 0,
+    mode: 'normal',
+    style: '',
+    text,
+    type: 'text',
+    version: 1,
+  } as SerializedTextNode
+}
+
+describe('hasText', () => {
+  it('returns false for null/undefined', () => {
+    expect(hasText(null)).toBe(false)
+    expect(hasText(undefined)).toBe(false)
+  })
+
+  it('returns false when root has no children', () => {
+    expect(hasText(rootState([]))).toBe(false)
+  })
+
+  it('returns false for createEmptySerializedEditorState()', () => {
+    expect(hasText(createEmptyEditorState())).toBe(false)
+  })
+
+  it('returns false for a single empty paragraph (no children)', () => {
+    expect(hasText(rootState([emptyParagraph([])]))).toBe(false)
+  })
+
+  it('returns false for a single empty paragraph with one empty text node', () => {
+    expect(hasText(rootState([emptyParagraph([textNode('')])]))).toBe(false)
+  })
+
+  it('returns true for a single paragraph with non-empty text', () => {
+    expect(hasText(rootState([emptyParagraph([textNode('Hello')])]))).toBe(true)
+  })
+
+  it('returns true when there are multiple root children', () => {
+    expect(
+      hasText(
+        rootState([emptyParagraph([textNode('')]), emptyParagraph([textNode('Still counts')])])
+      )
+    ).toBe(true)
+  })
+})

package/src/validate/hasText.ts

@@ -0,0 +1,34 @@
+import type {
+  SerializedEditorState,
+  SerializedLexicalNode,
+  SerializedParagraphNode,
+  SerializedTextNode,
+} from 'lexical'
+
+export function hasText(
+  value: SerializedEditorState<SerializedLexicalNode> | null | undefined
+): boolean {
+  if (value === null || value === undefined) return false
+
+  const rootChildren = value.root?.children
+  if (rootChildren === null || rootChildren === undefined) return false
+  if (rootChildren.length === 0) return false
+
+  // Treat a single empty paragraph as "no content".
+  if (rootChildren.length === 1 && rootChildren[0]?.type === 'paragraph') {
+    const paragraphNode = rootChildren[0] as SerializedParagraphNode
+    const paragraphChildren = paragraphNode.children
+
+    if (paragraphChildren === null || paragraphChildren === undefined) return false
+    if (paragraphChildren.length === 0) return false
+
+    if (paragraphChildren.length === 1 && paragraphChildren[0]?.type === 'text') {
+      const textNode = paragraphChildren[0] as SerializedTextNode
+      const text = textNode.text
+      if (text === null || text === undefined) return false
+      if (text.length === 0) return false
+    }
+  }
+
+  return true
+}

package/src/validate/validate.ts

@@ -0,0 +1,18 @@
+import type { SerializedEditorState } from 'lexical'
+
+import { hasText } from './hasText'
+
+export const richTextValidate = async (
+  value: SerializedEditorState | undefined,
+  options: { required?: boolean }
+) => {
+  // TODO: use i18n client translation provider
+  // const { t, required } = options
+  const { required } = options
+
+  if (required && hasText(value) === false) {
+    return 'validation:required'
+  }
+
+  return true
+}