feat(richtext-lexical): client-side block markdown shortcuts, code block (#13813)

This PR:
- adds support for client-side markdown shortcuts for blocks with the
`admin.jsx` property. This was previously only supported server-side.
The code mimics the server-side implementation, as this could be used
for full markdown imports on the client-side, rather than just simple
markdown shortcuts
- exports a pre-made `CodeBlock` that can be used within the
`BlocksFeature`. Video Example:


https://github.com/user-attachments/assets/31f2d66b-64e9-4e9d-a2b6-89ddefda3a84



---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211217132290839

Author: AlessioGr

docs/rich-text/official-features.mdx

@@ -418,6 +418,69 @@ BlocksFeature({
 })
 ```
 
+#### Code Blocks
+
+Payload exports a premade CodeBlock that you can import and use in your project. It supports syntax highlighting, dynamically selecting the language and loading in external type definitions:
+
+```ts
+import { BlocksFeature, CodeBlock } from '@payloadcms/richtext-lexical'
+
+// ...
+BlocksFeature({
+  blocks: [
+    CodeBlock({
+      defaultLanguage: 'ts',
+      languages: {
+        js: 'JavaScript',
+        plaintext: 'Plain Text',
+        ts: 'TypeScript',
+      },
+    }),
+  ],
+}),
+// ...
+```
+
+When using TypeScript, you can also pass in additional type definitions that will be available in the editor. Here's an example of how to make `payload` and `react` available in the editor:
+
+```ts
+import { BlocksFeature, CodeBlock } from '@payloadcms/richtext-lexical'
+
+// ...
+BlocksFeature({
+  blocks: [
+    CodeBlock({
+      slug: 'PayloadCode',
+      languages: {
+        ts: 'TypeScript',
+      },
+      typescript: {
+        fetchTypes: [
+          {
+            // The index.bundled.d.ts contains all the types for Payload in one file, so that Monaco doesn't need to fetch multiple files.
+            // This file may be removed in the future and is not guaranteed to be available in future versions of Payload.
+            url: 'https://unpkg.com/[email protected]/dist/index.bundled.d.ts',
+            filePath: 'file:///node_modules/payload/index.d.ts',
+          },
+          {
+            url: 'https://unpkg.com/@types/[email protected]/index.d.ts',
+            filePath: 'file:///node_modules/@types/react/index.d.ts',
+          },
+        ],
+        paths: {
+          payload: ['file:///node_modules/payload/index.d.ts'],
+          react: ['file:///node_modules/@types/react/index.d.ts'],
+        },
+        typeRoots: ['node_modules/@types', 'node_modules/payload'],
+        // Enable type checking. By default, only syntax checking is enabled.
+        enableSemanticValidation: true,
+      },
+    }),
+  ],
+}),
+// ...
+```
+
 ### TreeViewFeature
 
 - Description: Provides a debug panel below the editor showing the editor's internal state, DOM tree, and time travel debugging.

packages/payload/src/fields/config/types.ts

@@ -1061,6 +1061,7 @@ export type CodeField = {
       Label?: CustomComponent<CodeFieldLabelClientComponent | CodeFieldLabelServerComponent>
     } & FieldAdmin['components']
     editorOptions?: EditorProps['options']
+    editorProps?: Partial<EditorProps>
     language?: string
   } & FieldAdmin
   maxLength?: number
@@ -1070,8 +1071,9 @@ export type CodeField = {
 } & Omit<FieldBase, 'admin' | 'validate'>
 
 export type CodeFieldClient = {
-  // @ts-expect-error - vestiges of when tsconfig was not strict. Feel free to improve
-  admin?: AdminClient & Pick<CodeField['admin'], 'editorOptions' | 'language'>
+  admin?: AdminClient &
+    // @ts-expect-error - vestiges of when tsconfig was not strict. Feel free to improve
+    Partial<Pick<CodeField['admin'], 'editorOptions' | 'editorProps' | 'language'>>
 } & Omit<FieldBaseClient, 'admin'> &
   Pick<CodeField, 'maxLength' | 'minLength' | 'type'>
 

packages/richtext-lexical/src/exports/client/index.ts

@@ -150,6 +150,9 @@ export { BlockEditButton } from '../../features/blocks/client/component/componen
 export { BlockRemoveButton } from '../../features/blocks/client/component/components/BlockRemoveButton.js'
 export { useBlockComponentContext } from '../../features/blocks/client/component/BlockContent.js'
 export { getRestPopulateFn } from '../../features/converters/utilities/restPopulateFn.js'
+export { codeConverterClient } from '../../features/blocks/premade/CodeBlock/converterClient.js'
+export { CodeComponent } from '../../features/blocks/premade/CodeBlock/Component/Code.js'
+export { CodeBlockBlockComponent } from '../../features/blocks/premade/CodeBlock/Component/Block.js'
 
 export { RenderLexical } from '../../field/RenderLexical/index.js'
 export { buildEditorState } from '../../utilities/buildEditorState.js'

packages/richtext-lexical/src/features/blocks/client/component/BlockContent.tsx

@@ -1,23 +1,63 @@
 'use client'
+import type { CollapsibleProps } from '@payloadcms/ui/elements/Collapsible'
 import type { ClientField, FormState } from 'payload'
 
+import { useLexicalEditable } from '@lexical/react/useLexicalEditable'
 import { RenderFields, useFormSubmitted } from '@payloadcms/ui'
 import React, { createContext, useMemo } from 'react'
 
-type Props = {
+export type BlockCollapsibleProps = {
+  /**
+   * Replace the top-right portion of the header that renders the Edit and Remove buttons with custom content.
+   * If this property is provided, the `removeButton` and `editButton` properties are ignored.
+   */
+  Actions?: React.ReactNode
+  children?: React.ReactNode
+  /**
+   * Additional className to the collapsible wrapper
+   */
+  className?: string
+  /**
+   * Props to pass to the underlying Collapsible component. You could use this to override the `Header` entirely, for example.
+   */
+  collapsibleProps?: Partial<CollapsibleProps>
+  /**
+   * Whether to disable rendering the block name field in the header Label
+   * @default false
+   */
+  disableBlockName?: boolean
+  /**
+   * Whether to show the Edit button
+   * If `Actions` is provided, this property is ignored.
+   * @default true
+   */
+  editButton?: boolean
+  /**
+   * Replace the default Label component with a custom Label
+   */
+  Label?: React.ReactNode
+  /**
+   * Replace the default Pill component component that's rendered within the default Label component with a custom Pill.
+   * This property has no effect if you provide a custom Label component via the `Label` property.
+   */
+  Pill?: React.ReactNode
+  /**
+   * Whether to show the Remove button
+   * If `Actions` is provided, this property is ignored.
+   * @default true
+   */
+  removeButton?: boolean
+}
+
+export type BlockCollapsibleWithErrorProps = {
+  errorCount?: number
+  fieldHasErrors?: boolean
+} & BlockCollapsibleProps
+
+export type BlockContentProps = {
   baseClass: string
   BlockDrawer: React.FC
-  Collapsible: React.FC<{
-    children?: React.ReactNode
-    editButton?: boolean
-    errorCount?: number
-    fieldHasErrors?: boolean
-    /**
-     * Override the default label with a custom label
-     */
-    Label?: React.ReactNode
-    removeButton?: boolean
-  }>
+  Collapsible: React.FC<BlockCollapsibleWithErrorProps>
   CustomBlock: React.ReactNode
   EditButton: React.FC
   errorCount: number
@@ -29,24 +69,20 @@ type Props = {
 }
 
 type BlockComponentContextType = {
-  BlockCollapsible?: React.FC<{
-    children?: React.ReactNode
-    editButton?: boolean
-    /**
-     * Override the default label with a custom label
-     */
-    Label?: React.ReactNode
-    removeButton?: boolean
-  }>
-  EditButton?: React.FC
-  initialState: false | FormState | undefined
-
-  nodeKey?: string
-  RemoveButton?: React.FC
-}
+  BlockCollapsible: React.FC<BlockCollapsibleProps>
+} & Omit<BlockContentProps, 'Collapsible'>
 
 const BlockComponentContext = createContext<BlockComponentContextType>({
+  baseClass: 'lexical-block',
+  BlockCollapsible: () => null,
+  BlockDrawer: () => null,
+  CustomBlock: null,
+  EditButton: () => null,
+  errorCount: 0,
+  formSchema: [],
   initialState: false,
+  nodeKey: '',
+  RemoveButton: () => null,
 })
 
 export const useBlockComponentContext = () => React.use(BlockComponentContext)
@@ -56,56 +92,33 @@ export const useBlockComponentContext = () => React.use(BlockComponentContext)
  * scoped to the block. All format operations in here are thus scoped to the block's form, and
  * not the whole document.
  */
-export const BlockContent: React.FC<Props> = (props) => {
-  const {
-    BlockDrawer,
-    Collapsible,
-    CustomBlock,
-    EditButton,
-    errorCount,
-    formSchema,
-    initialState,
-    nodeKey,
-    RemoveButton,
-  } = props
+export const BlockContent: React.FC<BlockContentProps> = (props) => {
+  const { Collapsible, ...contextProps } = props
+
+  const { BlockDrawer, CustomBlock, errorCount, formSchema } = contextProps
 
   const hasSubmitted = useFormSubmitted()
 
   const fieldHasErrors = hasSubmitted && errorCount > 0
+  const isEditable = useLexicalEditable()
 
   const CollapsibleWithErrorProps = useMemo(
-    () =>
-      (props: {
-        children?: React.ReactNode
-        editButton?: boolean
-
-        /**
-         * Override the default label with a custom label
-         */
-        Label?: React.ReactNode
-        removeButton?: boolean
-      }) => (
-        <Collapsible
-          editButton={props.editButton}
-          errorCount={errorCount}
-          fieldHasErrors={fieldHasErrors}
-          Label={props.Label}
-          removeButton={props.removeButton}
-        >
-          {props.children}
+    () => (props: BlockCollapsibleProps) => {
+      const { children, ...rest } = props
+      return (
+        <Collapsible errorCount={errorCount} fieldHasErrors={fieldHasErrors} {...rest}>
+          {children}
         </Collapsible>
-      ),
+      )
+    },
     [Collapsible, fieldHasErrors, errorCount],
   )
 
   return CustomBlock ? (
     <BlockComponentContext
       value={{
+        ...contextProps,
         BlockCollapsible: CollapsibleWithErrorProps,
-        EditButton,
-        initialState,
-        nodeKey,
-        RemoveButton,
       }}
     >
       {CustomBlock}
@@ -120,6 +133,7 @@ export const BlockContent: React.FC<Props> = (props) => {
         parentPath={''}
         parentSchemaPath=""
         permissions={true}
+        readOnly={!isEditable}
       />
     </CollapsibleWithErrorProps>
   )

packages/richtext-lexical/src/features/blocks/client/component/components/BlockCollapsible.tsx

@@ -1,23 +1,11 @@
 'use client'
 import React from 'react'
 
-import { useBlockComponentContext } from '../BlockContent.js'
+import { type BlockCollapsibleProps, useBlockComponentContext } from '../BlockContent.js'
 
-export const BlockCollapsible: React.FC<{
-  children?: React.ReactNode
-  editButton?: boolean
-
-  /**
-   * Override the default label with a custom label
-   */
-  Label?: React.ReactNode
-  removeButton?: boolean
-}> = ({ children, editButton, Label, removeButton }) => {
+export const BlockCollapsible: React.FC<BlockCollapsibleProps> = (props) => {
+  const { children, ...rest } = props
   const { BlockCollapsible } = useBlockComponentContext()
 
-  return BlockCollapsible ? (
-    <BlockCollapsible editButton={editButton} Label={Label} removeButton={removeButton}>
-      {children}
-    </BlockCollapsible>
-  ) : null
+  return BlockCollapsible ? <BlockCollapsible {...rest}>{children}</BlockCollapsible> : null
 }

packages/richtext-lexical/src/features/blocks/client/component/index.scss

@@ -98,6 +98,8 @@
 
     &__editButton.btn {
       margin: 0;
+      width: 24px;
+
       &:hover {
         background-color: var(--theme-elevation-200);
       }