AI interfaces and text editor

1/*2 * Receta: RichTextToolbar sobre Tiptap (AMS-1787). Se copia tal cual a la3 * aplicacion; la guia `docs/rich-text-editor.md` la ensena entera y una prueba4 * comprueba que la guia y este fichero no se separan.5 *6 * Va sobre `@tiptap/core`, sin `@tiptap/react`: el gancho son cuarenta lineas y7 * asi no entran sus menus flotantes ni sus dependencias.8 *9 *   npm install @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-image10 */11import { Editor, type ChainedCommands } from '@tiptap/core'12import Image from '@tiptap/extension-image'13import StarterKit from '@tiptap/starter-kit'14import { useEffect, useRef, useState, type RefObject } from 'react'15 16import {17  RICH_TEXT_BLOCKS,18  RICH_TEXT_MARKS,19  type RichTextCommand,20  type RichTextControl,21  type RichTextFormat,22  type RichTextImage,23  type RichTextLink,24  type RichTextShortcuts,25  type RichTextState,26} from '@amset/ui'27 28/** Los atajos que trae Tiptap de serie, para que la barra los anuncie. */29export const TIPTAP_SHORTCUTS: RichTextShortcuts = {30  bold: 'Mod+B',31  italic: 'Mod+I',32  underline: 'Mod+U',33  strike: 'Mod+Shift+S',34  code: 'Mod+E',35  heading1: 'Mod+Alt+1',36  heading2: 'Mod+Alt+2',37  heading3: 'Mod+Alt+3',38  bulletList: 'Mod+Shift+8',39  orderedList: 'Mod+Shift+7',40  blockquote: 'Mod+Shift+B',41  codeBlock: 'Mod+Alt+C',42  undo: 'Mod+Z',43  redo: 'Mod+Shift+Z',44}45 46/** Cada formato, como pregunta a Tiptap: nombre del nodo o de la marca, y sus atributos. */47const ACTIVE: Readonly<Record<RichTextFormat, readonly [string, Record<string, unknown>?]>> = {48  bold: ['bold'],49  italic: ['italic'],50  underline: ['underline'],51  strike: ['strike'],52  code: ['code'],53  heading1: ['heading', { level: 1 }],54  heading2: ['heading', { level: 2 }],55  heading3: ['heading', { level: 3 }],56  bulletList: ['bulletList'],57  orderedList: ['orderedList'],58  blockquote: ['blockquote'],59  codeBlock: ['codeBlock'],60}61 62/** Cada orden de la barra, como cadena de Tiptap. Sin `.focus()`: la barra ya cuida del foco. */63const COMMANDS: Readonly<Record<RichTextCommand, (chain: ChainedCommands) => ChainedCommands>> = {64  bold: (chain) => chain.toggleBold(),65  italic: (chain) => chain.toggleItalic(),66  underline: (chain) => chain.toggleUnderline(),67  strike: (chain) => chain.toggleStrike(),68  code: (chain) => chain.toggleCode(),69  heading1: (chain) => chain.toggleHeading({ level: 1 }),70  heading2: (chain) => chain.toggleHeading({ level: 2 }),71  heading3: (chain) => chain.toggleHeading({ level: 3 }),72  bulletList: (chain) => chain.toggleBulletList(),73  orderedList: (chain) => chain.toggleOrderedList(),74  blockquote: (chain) => chain.toggleBlockquote(),75  codeBlock: (chain) => chain.toggleCodeBlock(),76  undo: (chain) => chain.undo(),77  redo: (chain) => chain.redo(),78  clearFormatting: (chain) => chain.unsetAllMarks().clearNodes(),79}80 81const ALL_COMMANDS: readonly RichTextCommand[] = [...RICH_TEXT_MARKS, ...RICH_TEXT_BLOCKS, 'undo', 'redo', 'clearFormatting']82 83/** Lo que hay donde esta el cursor, en el idioma de la barra. */84function readState(editor: Editor): RichTextState {85  const unavailable: RichTextControl[] = ALL_COMMANDS.filter((command) => !COMMANDS[command](editor.can().chain()).run())86  if (!editor.can().setLink({ href: 'https://example.com' })) unavailable.push('link')87  if (!editor.can().setImage({ src: 'https://example.com/a.png' })) unavailable.push('image')88  const link: unknown = editor.getAttributes('link')['href']89  return {90    active: [...RICH_TEXT_MARKS, ...RICH_TEXT_BLOCKS].filter((format) => editor.isActive(...ACTIVE[format])),91    unavailable,92    link:93      editor.isActive('link') && typeof link === 'string'94        ? { href: link, newTab: editor.getAttributes('link')['target'] === '_blank' }95        : undefined,96  }97}98 99export interface TiptapToolbar {100  /** Donde se monta el editor: un `<div>` vacio. */101  readonly hostRef: RefObject<HTMLDivElement | null>102  readonly editor: Editor | null103  readonly state: RichTextState104  readonly onCommand: (command: RichTextCommand) => void105  readonly onLinkChange: (link: RichTextLink | null) => void106  readonly onImageInsert: (image: RichTextImage) => void107}108 109export interface TiptapToolbarOptions {110  /** El HTML de partida. */111  readonly content: string112  /** El `id` del area editable: la barra la señala con `aria-controls`. */113  readonly id: string114  /** El nombre del area editable para el lector: el `id` de la etiqueta visible. */115  readonly labelledBy: string116  /** Se llama con el HTML en cada cambio, para guardarlo. */117  readonly onChange?: (html: string) => void118}119 120/** Monta Tiptap en `hostRef` y le da a la barra su estado y sus ordenes. */121export function useTiptapToolbar({ content, id, labelledBy, onChange }: TiptapToolbarOptions): TiptapToolbar {122  const hostRef = useRef<HTMLDivElement>(null)123  const [editor, setEditor] = useState<Editor | null>(null)124  const [state, setState] = useState<RichTextState>({ active: [] })125  // El contenido de partida solo se lee al montar, como el `defaultValue` de un campo.126  const initialContent = useRef(content)127  const onChangeRef = useRef(onChange)128  useEffect(() => {129    onChangeRef.current = onChange130  }, [onChange])131 132  useEffect(() => {133    const host = hostRef.current134    if (host === null) return undefined135    const instance = new Editor({136      element: host,137      content: initialContent.current,138      extensions: [StarterKit.configure({ link: { openOnClick: false, autolink: true, defaultProtocol: 'https' } }), Image],139      editorProps: {140        attributes: { id, class: 'amset-richtext__content', role: 'textbox', 'aria-multiline': 'true', 'aria-labelledby': labelledBy },141      },142    })143    const update = (): void => { setState(readState(instance)) }144    const notify = (): void => { onChangeRef.current?.(instance.getHTML()) }145    instance.on('transaction', update)146    instance.on('update', notify)147    setEditor(instance)148    update()149    return () => {150      instance.off('transaction', update)151      instance.off('update', notify)152      instance.destroy()153    }154  }, [id, labelledBy])155 156  return {157    hostRef,158    editor,159    state,160    onCommand: (command) => {161      if (editor !== null) COMMANDS[command](editor.chain()).run()162    },163    onLinkChange: (link) => {164      if (editor === null) return165      const chain = editor.chain().extendMarkRange('link')166      if (link === null) {167        chain.unsetLink().run()168        return169      }170      const attrs = { href: link.href, target: link.newTab ? '_blank' : null, rel: link.newTab ? 'noopener noreferrer' : null }171      // Sin nada seleccionado y fuera de un enlace, se escribe la direccion como texto del enlace.172      if (editor.state.selection.empty && !editor.isActive('link')) {173        chain.insertContent({ type: 'text', text: link.href, marks: [{ type: 'link', attrs }] }).run()174        return175      }176      chain.setLink(attrs).run()177    },178    onImageInsert: (image) => {179      editor?.chain().setImage({ src: image.src, alt: image.alt }).run()180    },181  }182}

import { useId, useState } from 'react'import { RichTextToolbar } from '@amset/ui'import { TIPTAP_SHORTCUTS, useTiptapToolbar } from './tiptap-toolbar' export function ProductDescription({ initialHtml }: { readonly initialHtml: string }) {  const labelId = useId()  const editorId = useId()  const [html, setHtml] = useState(initialHtml)  const toolbar = useTiptapToolbar({ content: initialHtml, id: editorId, labelledBy: labelId, onChange: setHtml })   return (    <>      <span id={labelId}>Product description</span>      <div className="amset-richtext__frame">        <RichTextToolbar          label="Description formatting"          aria-controls={editorId}          variant="flat"          state={toolbar.state}          onCommand={toolbar.onCommand}          onLinkChange={toolbar.onLinkChange}          onImageInsert={toolbar.onImageInsert}          shortcuts={TIPTAP_SHORTCUTS}        />        <div ref={toolbar.hostRef} />      </div>      <input type="hidden" name="description" value={html} />    </>  )}

1/*2 * Receta: RichTextToolbar sobre Lexical (AMS-1787). Se copia tal cual a la3 * aplicacion; la guia `docs/rich-text-editor.md` la ensena entera y una prueba4 * comprueba que la guia y este fichero no se separan.5 *6 * Va sobre el nucleo de Lexical, sin `@lexical/react`: ese paquete arrastra7 * `@floating-ui/react` y una docena de modulos que la barra no necesita.8 * Lexical no trae nodo de imagen ni bloque de codigo sin `@lexical/code`, asi9 * que esta receta los deja fuera de la barra (`blocks` sin `codeBlock`, sin10 * `onImageInsert`).11 *12 *   npm install lexical @lexical/rich-text @lexical/list @lexical/link @lexical/history @lexical/selection @lexical/utils13 */14import { createEmptyHistoryState, registerHistory } from '@lexical/history'15import { $isLinkNode, $toggleLink, LinkNode } from '@lexical/link'16import {17  INSERT_ORDERED_LIST_COMMAND,18  INSERT_UNORDERED_LIST_COMMAND,19  ListItemNode,20  ListNode,21  REMOVE_LIST_COMMAND,22  registerList,23} from '@lexical/list'24import { $createHeadingNode, $createQuoteNode, $isHeadingNode, $isQuoteNode, HeadingNode, QuoteNode, registerRichText } from '@lexical/rich-text'25import { $setBlocksType } from '@lexical/selection'26import { $findMatchingParent, $getNearestNodeOfType, mergeRegister } from '@lexical/utils'27import {28  $createParagraphNode,29  $getSelection,30  $isRangeSelection,31  $isRootNode,32  $isTextNode,33  CAN_REDO_COMMAND,34  CAN_UNDO_COMMAND,35  COMMAND_PRIORITY_LOW,36  FORMAT_TEXT_COMMAND,37  HISTORY_MERGE_TAG,38  REDO_COMMAND,39  UNDO_COMMAND,40  createEditor,41  type LexicalEditor,42  type RangeSelection,43  type TextFormatType,44} from 'lexical'45import { useEffect, useRef, useState, type RefObject } from 'react'46 47import {48  RICH_TEXT_MARKS,49  type RichTextBlock,50  type RichTextCommand,51  type RichTextControl,52  type RichTextFormat,53  type RichTextLink,54  type RichTextMark,55  type RichTextState,56} from '@amset/ui'57 58/** Los bloques que esta receta sabe hacer: sin `codeBlock`, que pide `@lexical/code`. */59export const LEXICAL_BLOCKS: readonly RichTextBlock[] = ['heading1', 'heading2', 'heading3', 'bulletList', 'orderedList', 'blockquote']60 61const MARKS: Readonly<Record<RichTextMark, TextFormatType>> = {62  bold: 'bold',63  italic: 'italic',64  underline: 'underline',65  strike: 'strikethrough',66  code: 'code',67}68 69/** Las clases que Lexical pone al texto: sin ellas, el subrayado y el tachado no se ven. */70const THEME = {71  text: {72    underline: 'amset-richtext__underline',73    strikethrough: 'amset-richtext__strike',74    underlineStrikethrough: 'amset-richtext__underline amset-richtext__strike',75  },76}77 78const HEADINGS = { heading1: 'h1', heading2: 'h2', heading3: 'h3' } as const79 80const MARK_NAMES: ReadonlySet<string> = new Set(RICH_TEXT_MARKS)81 82function isMark(command: RichTextCommand): command is RichTextMark {83  return MARK_NAMES.has(command)84}85 86/** El bloque donde empieza la seleccion, como formato de la barra. */87function $blockOf(selection: RangeSelection): RichTextBlock | undefined {88  const anchor = selection.anchor.getNode()89  const list = $getNearestNodeOfType(anchor, ListNode)90  if (list !== null) return list.getListType() === 'number' ? 'orderedList' : 'bulletList'91  if ($isRootNode(anchor)) return undefined92  const block = anchor.getTopLevelElementOrThrow()93  if ($isQuoteNode(block)) return 'blockquote'94  if (!$isHeadingNode(block)) return undefined95  const level = block.getTag()96  return level === 'h1' ? 'heading1' : level === 'h2' ? 'heading2' : level === 'h3' ? 'heading3' : undefined97}98 99function $readState(history: { readonly undo: boolean; readonly redo: boolean }): RichTextState {100  const unavailable: RichTextControl[] = ['codeBlock', 'image']101  if (!history.undo) unavailable.push('undo')102  if (!history.redo) unavailable.push('redo')103  const selection = $getSelection()104  if (!$isRangeSelection(selection)) return { active: [], unavailable }105  const marks = RICH_TEXT_MARKS.filter((mark) => selection.hasFormat(MARKS[mark]))106  const block = $blockOf(selection)107  const link = $findMatchingParent(selection.anchor.getNode(), $isLinkNode)108  return {109    active: block === undefined ? marks : [...marks, block],110    unavailable,111    link: $isLinkNode(link) ? { href: link.getURL(), newTab: link.getTarget() === '_blank' } : undefined,112  }113}114 115/** Pone un bloque, o lo quita (vuelve a parrafo) si ya era ese. */116function $toggleBlock(block: Exclude<RichTextBlock, 'bulletList' | 'orderedList' | 'codeBlock'>, active: boolean): void {117  const selection = $getSelection()118  if (!$isRangeSelection(selection)) return119  if (active) $setBlocksType(selection, () => $createParagraphNode())120  else if (block === 'blockquote') $setBlocksType(selection, () => $createQuoteNode())121  else $setBlocksType(selection, () => $createHeadingNode(HEADINGS[block]))122}123 124function $clearFormatting(): void {125  const selection = $getSelection()126  if (!$isRangeSelection(selection)) return127  for (const node of selection.getNodes()) {128    if ($isTextNode(node)) node.setFormat(0).setStyle('')129  }130}131 132function runCommand(editor: LexicalEditor, command: RichTextCommand, active: ReadonlySet<RichTextFormat>): void {133  if (isMark(command)) {134    editor.dispatchCommand(FORMAT_TEXT_COMMAND, MARKS[command])135    return136  }137  switch (command) {138    case 'undo':139      editor.dispatchCommand(UNDO_COMMAND, undefined)140      return141    case 'redo':142      editor.dispatchCommand(REDO_COMMAND, undefined)143      return144    case 'bulletList':145    case 'orderedList':146      if (active.has(command)) editor.dispatchCommand(REMOVE_LIST_COMMAND, undefined)147      else editor.dispatchCommand(command === 'bulletList' ? INSERT_UNORDERED_LIST_COMMAND : INSERT_ORDERED_LIST_COMMAND, undefined)148      return149    case 'clearFormatting':150      editor.update($clearFormatting)151      return152    case 'heading1':153    case 'heading2':154    case 'heading3':155    case 'blockquote':156      editor.update(() => { $toggleBlock(command, active.has(command)) })157      return158    default:159      return160  }161}162 163export interface LexicalToolbar {164  /** Donde se monta el editor: un `<div>` vacio. */165  readonly hostRef: RefObject<HTMLDivElement | null>166  readonly state: RichTextState167  readonly onCommand: (command: RichTextCommand) => void168  readonly onLinkChange: (link: RichTextLink | null) => void169}170 171export interface LexicalToolbarOptions {172  /** El nombre del editor para Lexical: unico en la pagina. */173  readonly namespace: string174  /** Escribe el contenido de partida con los nodos de Lexical. Corre una vez, dentro de `editor.update`. */175  readonly $initialContent?: () => void176  /** Se llama con el documento en cada cambio, como JSON de Lexical: es lo que se guarda y se vuelve a cargar. */177  readonly onChange?: (json: string) => void178}179 180/** Monta Lexical en `hostRef` y le da a la barra su estado y sus ordenes. */181export function useLexicalToolbar({ namespace, $initialContent, onChange }: LexicalToolbarOptions): LexicalToolbar {182  const hostRef = useRef<HTMLDivElement>(null)183  const editorRef = useRef<LexicalEditor | null>(null)184  const [state, setState] = useState<RichTextState>({ active: [] })185  // El contenido de partida solo se lee al montar, como el `defaultValue` de un campo.186  const initialContent = useRef($initialContent)187  const onChangeRef = useRef(onChange)188  useEffect(() => {189    onChangeRef.current = onChange190  }, [onChange])191 192  useEffect(() => {193    const host = hostRef.current194    if (host === null) return undefined195    const editor = createEditor({196      namespace,197      nodes: [HeadingNode, QuoteNode, ListNode, ListItemNode, LinkNode],198      theme: THEME,199      onError: (error) => { throw error },200    })201    const history = { undo: false, redo: false }202    const refresh = (): void => { editor.getEditorState().read(() => { setState($readState(history)) }) }203    editor.setRootElement(host)204    editorRef.current = editor205    const unregister = mergeRegister(206      registerRichText(editor),207      registerList(editor),208      registerHistory(editor, createEmptyHistoryState(), 300),209      editor.registerUpdateListener(({ editorState, dirtyElements, dirtyLeaves }) => {210        refresh()211        if (dirtyElements.size > 0 || dirtyLeaves.size > 0) onChangeRef.current?.(JSON.stringify(editorState.toJSON()))212      }),213      editor.registerCommand(CAN_UNDO_COMMAND, (can) => { history.undo = can; refresh(); return false }, COMMAND_PRIORITY_LOW),214      editor.registerCommand(CAN_REDO_COMMAND, (can) => { history.redo = can; refresh(); return false }, COMMAND_PRIORITY_LOW),215    )216    const write = initialContent.current217    // Fuera del historial: deshacer no tiene que borrar lo que ya estaba.218    if (write !== undefined) editor.update(write, { tag: HISTORY_MERGE_TAG })219    refresh()220    return () => {221      unregister()222      editor.setRootElement(null)223      editorRef.current = null224    }225  }, [namespace])226 227  const activeSet = new Set(state.active)228  return {229    hostRef,230    state,231    onCommand: (command) => {232      if (editorRef.current !== null) runCommand(editorRef.current, command, activeSet)233    },234    onLinkChange: (link) => {235      editorRef.current?.update(() => {236        if (link === null) $toggleLink(null)237        else $toggleLink({ url: link.href, target: link.newTab ? '_blank' : null, rel: link.newTab ? 'noopener noreferrer' : null })238      })239    },240  }241}

import { useId, useState } from 'react'import { RichTextToolbar } from '@amset/ui'import { LEXICAL_BLOCKS, useLexicalToolbar } from './lexical-toolbar' export function NewsBody() {  const labelId = useId()  const editorId = useId()  const [json, setJson] = useState('')  const toolbar = useLexicalToolbar({ namespace: editorId, onChange: setJson })   return (    <>      <span id={labelId}>News body</span>      <div className="amset-richtext__frame">        <RichTextToolbar          label="Body formatting"          aria-controls={editorId}          variant="flat"          blocks={LEXICAL_BLOCKS}          state={toolbar.state}          onCommand={toolbar.onCommand}          onLinkChange={toolbar.onLinkChange}        />        <div          ref={toolbar.hostRef}          id={editorId}          className="amset-richtext__content"          contentEditable          role="textbox"          aria-multiline="true"          aria-labelledby={labelId}        />      </div>      <input type="hidden" name="body" value={json} />    </>  )}