@advui/editor 0.5.0

package/src/components/rich-text-editor/RichTextEditor.tsx

@@ -0,0 +1,330 @@
+import {
+  BoldIcon,
+  CodeIcon,
+  HeadingIcon,
+  ItalicIcon,
+  LinkIcon,
+  ListIcon,
+  ListOrderedIcon,
+  QuoteIcon,
+  StrikethroughIcon,
+} from '@advui/icons'
+import { type ReactElement, useId, useLayoutEffect, useRef, useState } from 'react'
+import { type GetProps, type TamaguiElement, View, XStack, isWeb } from 'tamagui'
+import {
+  Button,
+  IconButton,
+  Text,
+  Textarea,
+  fieldBoxStyle,
+  useControllableState,
+} from '@advui/core'
+import { RichTextContent } from './RichTextContent'
+import { type RichTextTool, type TextSelection, applyFormat, shortcuts } from './markdown'
+
+export interface RichTextEditorLabels {
+  toolbar: string
+  tools: Record<RichTextTool, string>
+  preview: string
+  /** Shown in the preview when there is nothing to show. */
+  empty: string
+  /** Character count with `maxLength`: "120 of 500 characters". */
+  count: (length: number, max: number) => string
+}
+
+const defaultLabels: RichTextEditorLabels = {
+  toolbar: 'Formatting',
+  tools: {
+    bold: 'Bold',
+    italic: 'Italic',
+    strikethrough: 'Strikethrough',
+    code: 'Code',
+    link: 'Link',
+    heading: 'Heading',
+    bulletList: 'Bulleted list',
+    orderedList: 'Numbered list',
+    quote: 'Quote',
+  },
+  preview: 'Preview',
+  empty: 'Nothing to preview.',
+  count: (length, max) => `${length} of ${max} characters`,
+}
+
+const icons: Record<RichTextTool, ReactElement> = {
+  bold: <BoldIcon />,
+  italic: <ItalicIcon />,
+  strikethrough: <StrikethroughIcon />,
+  code: <CodeIcon />,
+  link: <LinkIcon />,
+  heading: <HeadingIcon />,
+  bulletList: <ListIcon />,
+  orderedList: <ListOrderedIcon />,
+  quote: <QuoteIcon />,
+}
+
+const shortcutHints: Partial<Record<RichTextTool, string>> = { bold: 'B', italic: 'I', link: 'K' }
+
+export const defaultRichTextTools: RichTextTool[] = [
+  'bold',
+  'italic',
+  'strikethrough',
+  'heading',
+  'bulletList',
+  'orderedList',
+  'quote',
+  'link',
+  'code',
+]
+
+export interface RichTextEditorProps {
+  /** Markdown (controlled). */
+  value?: string
+  defaultValue?: string
+  onValueChange?: (value: string) => void
+  placeholder?: string
+  /** Toolbar buttons, in order. Default: all nine. */
+  tools?: RichTextTool[]
+  /** Minimum height of the text area. Default: `$32`. */
+  minHeight?: GetProps<typeof View>['minHeight']
+  maxLength?: number
+  disabled?: boolean
+  invalid?: boolean
+  id?: string
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  'aria-describedby'?: string
+  'aria-required'?: boolean
+  /** Native: help read after the name (Form Field sets it). */
+  accessibilityHint?: string
+  /** Toolbar, tool and preview names, for translation. */
+  labels?: Partial<Omit<RichTextEditorLabels, 'tools'>> & {
+    tools?: Partial<RichTextEditorLabels['tools']>
+  }
+}
+
+type Editable = TamaguiElement & {
+  selectionStart?: number
+  selectionEnd?: number
+  setSelectionRange?: (start: number, end: number) => void
+  setSelection?: (start: number, end: number) => void
+  focus?: () => void
+}
+
+/**
+ * A Markdown editor with a formatting toolbar and a preview. It stores plain
+ * Markdown, so the text is safe to save and shows the same on every platform
+ * with Rich Text Content.
+ */
+export function RichTextEditor({
+  value: valueProp,
+  defaultValue = '',
+  onValueChange,
+  placeholder,
+  tools = defaultRichTextTools,
+  minHeight = '$32',
+  maxLength,
+  disabled = false,
+  invalid = false,
+  id,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
+  'aria-required': ariaRequired,
+  accessibilityHint,
+  labels: labelsProp,
+}: RichTextEditorProps) {
+  const labels = {
+    ...defaultLabels,
+    ...labelsProp,
+    tools: { ...defaultLabels.tools, ...labelsProp?.tools },
+  }
+  const [value, setValue] = useControllableState({
+    value: valueProp,
+    defaultValue,
+    onChange: onValueChange,
+  })
+  const [preview, setPreview] = useState(false)
+  const [activeTool, setActiveTool] = useState(0)
+  const field = useRef<Editable | null>(null)
+  // Native reports the caret as it moves; web reads it from the textarea.
+  const selection = useRef<TextSelection>({ start: value.length, end: value.length })
+  const pending = useRef<TextSelection | null>(null)
+  const generatedId = useId()
+  const fieldId = id ?? `${generatedId}-field`
+  const countId = `${generatedId}-count`
+
+  // Put the selection where the tool left it, once the new text is in.
+  useLayoutEffect(() => {
+    const next = pending.current
+    const node = field.current
+    if (!next || !node) return
+    pending.current = null
+    node.focus?.()
+    if (node.setSelectionRange) node.setSelectionRange(next.start, next.end)
+    else node.setSelection?.(next.start, next.end)
+    selection.current = next
+  })
+
+  const apply = (tool: RichTextTool) => {
+    const node = field.current
+    const current =
+      isWeb && node?.selectionStart != null
+        ? { start: node.selectionStart, end: node.selectionEnd ?? node.selectionStart }
+        : selection.current
+    const result = applyFormat(value, current, tool)
+    if (maxLength != null && result.value.length > maxLength) return
+    pending.current = result.selection
+    setValue(result.value)
+  }
+
+  const onFieldKeyDown = (event: {
+    key: string
+    metaKey?: boolean
+    ctrlKey?: boolean
+    shiftKey?: boolean
+    altKey?: boolean
+    preventDefault: () => void
+  }) => {
+    if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey) return
+    const tool = shortcuts[event.key.toLowerCase()]
+    if (tool && tools.includes(tool)) {
+      event.preventDefault()
+      apply(tool)
+    }
+  }
+
+  // One tab stop for the toolbar; the arrow keys move along it (WAI-ARIA toolbar).
+  const onToolbarKeyDown = (event: { key: string; preventDefault: () => void }) => {
+    const last = tools.length - 1
+    const moves: Record<string, number> = {
+      ArrowRight: activeTool >= last ? 0 : activeTool + 1,
+      ArrowLeft: activeTool <= 0 ? last : activeTool - 1,
+      Home: 0,
+      End: last,
+    }
+    if (!(event.key in moves)) return
+    event.preventDefault()
+    const next = moves[event.key]!
+    setActiveTool(next)
+    document.getElementById(`${generatedId}-tool-${next}`)?.focus()
+  }
+
+  const toolsDisabled = disabled || preview
+
+  return (
+    <View
+      {...fieldBoxStyle}
+      {...(invalid && { borderColor: '$error' })}
+      opacity={disabled ? 0.5 : 1}
+      overflow="hidden"
+      width="100%"
+    >
+      <XStack
+        alignItems="center"
+        justifyContent="space-between"
+        gap="$2"
+        padding="$1"
+        borderBottomWidth={1}
+        borderColor="$border"
+      >
+        <XStack
+          flexWrap="wrap"
+          flex={1}
+          {...(isWeb && {
+            role: 'toolbar',
+            'aria-label': labels.toolbar,
+            'aria-controls': fieldId,
+            onKeyDown: onToolbarKeyDown,
+          })}
+        >
+          {tools.map((tool, i) => (
+            <IconButton
+              key={tool}
+              id={`${generatedId}-tool-${i}`}
+              size="sm"
+              icon={icons[tool]}
+              aria-label={labels.tools[tool]}
+              {...(isWeb && {
+                tabIndex: i === activeTool ? 0 : -1,
+                title: shortcutHints[tool]
+                  ? `${labels.tools[tool]} (Ctrl+${shortcutHints[tool]})`
+                  : labels.tools[tool],
+                // Keep the text selected while pressing a tool.
+                onMouseDown: (event: { preventDefault: () => void }) => event.preventDefault(),
+                onFocus: () => setActiveTool(i),
+              })}
+              disabled={toolsDisabled}
+              onPress={() => apply(tool)}
+            />
+          ))}
+        </XStack>
+        <Button
+          size="sm"
+          variant="ghost"
+          aria-pressed={preview}
+          disabled={disabled}
+          onPress={() => setPreview(!preview)}
+          {...(preview && { backgroundColor: '$accent' })}
+        >
+          {labels.preview}
+        </Button>
+      </XStack>
+      {preview ? (
+        <View
+          minHeight={minHeight}
+          padding="$3"
+          {...(isWeb && { role: 'region', 'aria-label': labels.preview })}
+        >
+          {value.trim() ? (
+            <RichTextContent>{value}</RichTextContent>
+          ) : (
+            <Text size="sm" tone="muted">
+              {labels.empty}
+            </Text>
+          )}
+        </View>
+      ) : (
+        <Textarea
+          ref={field as never}
+          id={fieldId}
+          value={value}
+          onChangeText={setValue}
+          placeholder={placeholder}
+          disabled={disabled}
+          invalid={invalid}
+          maxLength={maxLength}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          aria-required={ariaRequired}
+          {...(accessibilityHint && { accessibilityHint })}
+          aria-describedby={
+            [ariaDescribedBy, maxLength != null ? countId : null].filter(Boolean).join(' ') ||
+            undefined
+          }
+          minHeight={minHeight}
+          // The frame draws the border; the text area sits flush inside it.
+          borderWidth={0}
+          borderRadius={0}
+          backgroundColor="transparent"
+          focusVisibleStyle={{ outlineWidth: 0, outlineStyle: 'none' }}
+          onSelectionChange={(event: { nativeEvent: { selection: TextSelection } }) => {
+            selection.current = event.nativeEvent.selection
+          }}
+          {...(isWeb && { onKeyDown: onFieldKeyDown })}
+        />
+      )}
+      {maxLength != null ? (
+        <Text
+          id={countId}
+          size="xs"
+          tone="muted"
+          textAlign="right"
+          paddingHorizontal="$3"
+          paddingBottom="$2"
+        >
+          {labels.count(value.length, maxLength)}
+        </Text>
+      ) : null}
+    </View>
+  )
+}

package/src/components/rich-text-editor/index.ts

@@ -0,0 +1,14 @@
+export { RichTextContent, type RichTextContentProps } from './RichTextContent'
+export {
+  RichTextEditor,
+  defaultRichTextTools,
+  type RichTextEditorLabels,
+  type RichTextEditorProps,
+} from './RichTextEditor'
+export {
+  applyFormat,
+  parseMarkdown,
+  type FormatResult,
+  type RichTextTool,
+  type TextSelection,
+} from './markdown'

package/src/components/rich-text-editor/markdown.ts

@@ -0,0 +1,244 @@
+/**
+ * The Markdown subset Rich Text Editor writes and Rich Text Content reads:
+ * **bold**, _italic_, ~~strike~~, `code`, [links](https://…), `#` headings,
+ * `-` and `1.` lists, and `>` quotes.
+ */
+
+export type RichTextTool =
+  | 'bold'
+  | 'italic'
+  | 'strikethrough'
+  | 'code'
+  | 'link'
+  | 'heading'
+  | 'bulletList'
+  | 'orderedList'
+  | 'quote'
+
+export interface TextSelection {
+  start: number
+  end: number
+}
+
+export interface FormatResult {
+  value: string
+  selection: TextSelection
+}
+
+const marks = { bold: '**', italic: '_', strikethrough: '~~', code: '`' } as const
+
+const linePatterns = {
+  heading: /^#{1,6} /,
+  bulletList: /^[-*] /,
+  orderedList: /^\d+\. /,
+  quote: /^> /,
+} as const
+
+/** Lists replace each other; a heading replaces a list. Quotes nest around anything. */
+const replaces: Record<keyof typeof linePatterns, RegExp[]> = {
+  heading: [linePatterns.heading, linePatterns.bulletList, linePatterns.orderedList],
+  bulletList: [linePatterns.bulletList, linePatterns.orderedList, linePatterns.heading],
+  orderedList: [linePatterns.orderedList, linePatterns.bulletList, linePatterns.heading],
+  quote: [linePatterns.quote],
+}
+
+/**
+ * Applies a toolbar tool to the text around the selection. Pressing a tool
+ * again removes it. Returns the new text and what to select next.
+ */
+export function applyFormat(
+  value: string,
+  selection: TextSelection,
+  tool: RichTextTool,
+  placeholder = tool === 'link' ? 'link text' : 'text',
+): FormatResult {
+  const start = Math.max(0, Math.min(selection.start, selection.end, value.length))
+  const end = Math.min(value.length, Math.max(selection.start, selection.end))
+  const selected = value.slice(start, end)
+
+  if (tool in marks) {
+    const mark = marks[tool as keyof typeof marks]
+    const n = mark.length
+    // The marks sit just outside the selection: remove them.
+    if (value.slice(start - n, start) === mark && value.slice(end, end + n) === mark) {
+      return {
+        value: value.slice(0, start - n) + selected + value.slice(end + n),
+        selection: { start: start - n, end: end - n },
+      }
+    }
+    // The selection includes the marks: remove them.
+    if (selected.length >= 2 * n && selected.startsWith(mark) && selected.endsWith(mark)) {
+      const inner = selected.slice(n, -n)
+      return {
+        value: value.slice(0, start) + inner + value.slice(end),
+        selection: { start, end: start + inner.length },
+      }
+    }
+    const text = selected || placeholder
+    return {
+      value: value.slice(0, start) + mark + text + mark + value.slice(end),
+      selection: { start: start + n, end: start + n + text.length },
+    }
+  }
+
+  if (tool === 'link') {
+    const url = 'https://'
+    const text = selected || placeholder
+    const inserted = `[${text}](${url})`
+    // With text selected the address is next to type; otherwise the text is.
+    const focus = selected
+      ? { start: start + text.length + 3, end: start + text.length + 3 + url.length }
+      : { start: start + 1, end: start + 1 + text.length }
+    return { value: value.slice(0, start) + inserted + value.slice(end), selection: focus }
+  }
+
+  // Line tools work on every line the selection touches.
+  const kind = tool as keyof typeof linePatterns
+  const lineStart = value.lastIndexOf('\n', start - 1) + 1
+  const endsAtBreak = end > start && value[end - 1] === '\n'
+  let lineEnd = value.indexOf('\n', endsAtBreak ? end - 1 : end)
+  if (lineEnd === -1) lineEnd = value.length
+  const lines = value.slice(lineStart, lineEnd).split('\n')
+  const filled = lines.filter((line) => line.trim() !== '')
+  const remove = filled.length > 0 && filled.every((line) => linePatterns[kind].test(line))
+  let number = 0
+  const next = lines.map((line) => {
+    if (remove) return line.replace(linePatterns[kind], '')
+    if (line.trim() === '' && lines.length > 1) return line
+    const bare = replaces[kind].reduce((text, pattern) => text.replace(pattern, ''), line)
+    number += 1
+    const prefix =
+      kind === 'heading'
+        ? '## '
+        : kind === 'bulletList'
+          ? '- '
+          : kind === 'orderedList'
+            ? `${number}. `
+            : '> '
+    return prefix + bare
+  })
+  const block = next.join('\n')
+  const result = value.slice(0, lineStart) + block + value.slice(lineEnd)
+  if (lines.length > 1) {
+    return { value: result, selection: { start: lineStart, end: lineStart + block.length } }
+  }
+  const delta = block.length - (lineEnd - lineStart)
+  return {
+    value: result,
+    selection: {
+      start: Math.max(lineStart, start + delta),
+      end: Math.max(lineStart, end + delta),
+    },
+  }
+}
+
+/** Keyboard shortcuts (with ⌘ or Ctrl). */
+export const shortcuts: Partial<Record<string, RichTextTool>> = {
+  b: 'bold',
+  i: 'italic',
+  k: 'link',
+}
+
+export type InlineNode =
+  | { type: 'text'; text: string }
+  | { type: 'code'; text: string }
+  | { type: 'bold' | 'italic' | 'strike'; children: InlineNode[] }
+  | { type: 'link'; href: string; children: InlineNode[] }
+
+export type BlockNode =
+  | { type: 'paragraph'; children: InlineNode[] }
+  | { type: 'heading'; level: number; children: InlineNode[] }
+  | { type: 'quote'; children: BlockNode[] }
+  | { type: 'list'; ordered: boolean; start: number; items: InlineNode[][] }
+
+const inlinePatterns: { type: InlineNode['type']; pattern: RegExp }[] = [
+  { type: 'code', pattern: /`([^`\n]+)`/ },
+  { type: 'link', pattern: /\[([^\]\n]+)\]\(([^)\s]+)\)/ },
+  { type: 'bold', pattern: /\*\*(.+?)\*\*/ },
+  { type: 'strike', pattern: /~~(.+?)~~/ },
+  { type: 'italic', pattern: /(?<![\w\\])_(.+?)_(?!\w)|(?<!\*)\*([^*\n]+)\*(?!\*)/ },
+]
+
+/** Only web and mail links are followed; anything else (e.g. `javascript:`) stays text. */
+export function safeHref(href: string) {
+  return /^(https?:\/\/|mailto:)/i.test(href) ? href : null
+}
+
+export function parseInline(text: string): InlineNode[] {
+  const nodes: InlineNode[] = []
+  let rest = text
+  while (rest) {
+    let first: { type: InlineNode['type']; match: RegExpExecArray } | null = null
+    for (const { type, pattern } of inlinePatterns) {
+      const match = pattern.exec(rest)
+      if (match && (!first || match.index < first.match.index)) first = { type, match }
+    }
+    if (!first) {
+      nodes.push({ type: 'text', text: rest })
+      break
+    }
+    const { type, match } = first
+    if (match.index > 0) nodes.push({ type: 'text', text: rest.slice(0, match.index) })
+    const inner = match[1] ?? match[2] ?? ''
+    if (type === 'code') nodes.push({ type: 'code', text: inner })
+    else if (type === 'link') {
+      const href = safeHref(match[2]!)
+      if (href) nodes.push({ type: 'link', href, children: parseInline(inner) })
+      else nodes.push(...parseInline(inner))
+    } else nodes.push({ type: type as 'bold', children: parseInline(inner) })
+    rest = rest.slice(match.index + match[0].length)
+  }
+  return nodes
+}
+
+export function parseMarkdown(source: string): BlockNode[] {
+  const blocks: BlockNode[] = []
+  const lines = source.replace(/\r\n?/g, '\n').split('\n')
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]!
+    if (line.trim() === '') {
+      i++
+      continue
+    }
+    const heading = /^(#{1,6}) (.*)$/.exec(line)
+    if (heading) {
+      blocks.push({
+        type: 'heading',
+        level: heading[1]!.length,
+        children: parseInline(heading[2]!),
+      })
+      i++
+      continue
+    }
+    if (/^> ?/.test(line)) {
+      const quoted: string[] = []
+      while (i < lines.length && /^> ?/.test(lines[i]!))
+        quoted.push(lines[i++]!.replace(/^> ?/, ''))
+      blocks.push({ type: 'quote', children: parseMarkdown(quoted.join('\n')) })
+      continue
+    }
+    const listItem = /^([-*]|\d+\.) (.*)$/.exec(line)
+    if (listItem) {
+      const ordered = listItem[1]!.endsWith('.')
+      const items: InlineNode[][] = []
+      while (i < lines.length) {
+        const item = /^([-*]|\d+\.) (.*)$/.exec(lines[i]!)
+        if (!item || item[1]!.endsWith('.') !== ordered) break
+        items.push(parseInline(item[2]!))
+        i++
+      }
+      blocks.push({ type: 'list', ordered, start: ordered ? parseInt(listItem[1]!, 10) : 1, items })
+      continue
+    }
+    const paragraph: string[] = []
+    while (
+      i < lines.length &&
+      lines[i]!.trim() !== '' &&
+      !/^(#{1,6} |> ?|[-*] |\d+\. )/.test(lines[i]!)
+    )
+      paragraph.push(lines[i++]!)
+    blocks.push({ type: 'paragraph', children: parseInline(paragraph.join('\n')) })
+  }
+  return blocks
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// Rich text editing: the Markdown editor, its viewer and the Markdown helpers they share.
+export * from './components/rich-text-editor'