react-native-enriched-markdown-scaffold 1.0.2-scaffold.1 → 1.0.2-scaffold.10

package/src/types/MarkdownTextProps.ts

@@ -1,4 +1,11 @@
-import type { ColorValue, ViewProps, ViewStyle, TextStyle } from 'react-native';
+import type { ReactNode, RefObject } from 'react';
+import type {
+  ColorValue,
+  HostInstance,
+  ViewProps,
+  ViewStyle,
+  TextStyle,
+} from 'react-native';
 import type { MarkdownStyle, Md4cFlags } from './MarkdownStyle';
 import type { AccessibilityLabels } from './AccessibilityLabels';
 import type {
@@ -6,8 +13,50 @@ import type {
   LinkLongPressEvent,
   TaskListItemPressEvent,
   CopyPressEvent,
+  CopyEvent,
+  SelectionChangeEvent,
 } from './events';
 
+/** Imperative handle of `EnrichedMarkdownText`, reached through its `ref`. */
+export interface EnrichedMarkdownTextInstance {
+  /**
+   * Clears the text selection (and any long-pressed block) and fires
+   * `onSelectionChange` with `active: false`.
+   * @platform ios, android
+   */
+  clearSelection: () => void;
+  measure: HostInstance['measure'];
+  measureInWindow: HostInstance['measureInWindow'];
+  measureLayout: HostInstance['measureLayout'];
+}
+
+/**
+ * A rect in dp, relative to the component's content box (inside any
+ * `containerStyle` padding).
+ */
+export interface LinkRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Layout of one rendered link, passed to `renderLinkDecoration`. */
+export interface LinkDecorationInfo {
+  /** Position of the link in the document (0-based) — stable key for a link. */
+  index: number;
+  url: string;
+  /** The link's visible text. */
+  text: string;
+  /**
+   * Anchor rect. Native: the drawn chip (glyphs + padding) of the link's last
+   * line fragment. Web: the link's inline box.
+   */
+  rect: LinkRect;
+  /** Every line fragment of the link (several when it wraps). Web: `[rect]`. */
+  rects: LinkRect[];
+}
+
 /**
  * Public context menu item. Each item includes a JS-side `onPress` callback
  * that is called when the user taps the item in the selection context menu.
@@ -57,22 +106,31 @@ export interface SelectionMenuPluralLabels {
  * Controls the built-in items added to the native text selection menu and
  * lets you localize their labels.
  *
- * Each item accepts an object: `{ enabled }` toggles visibility (the system
- * `copy` item can't be hidden — only relabeled) and `label` overrides the
- * English default. Wire `label` to your i18n library to match the rest of your
- * app's UI. Labels apply to the main text selection menu as well as the table
- * and math block copy menus.
+ * Each item accepts an object: `{ enabled }` toggles visibility and `label`
+ * overrides the English default. Wire `label` to your i18n library to match
+ * the rest of your app's UI. Items and labels apply to the main text selection
+ * menu as well as the table, math and code block copy menus.
+ *
+ * `copy.enabled`, `copy.format` and `systemItems` are ignored on macOS.
  *
  * @platform ios, android, macos
  */
 export interface SelectionMenuConfig {
   /**
-   * The system "Copy" item. It can't be hidden — only its label is configurable.
-   * @default { label: "Copy" }
+   * The "Copy" item.
+   * - `enabled`: `false` removes it from the text selection menu, the table /
+   *   math / code block menus and the code block VoiceOver copy action.
+   * - `format`: `'rich'` copies rich text (plain + HTML, plus RTF on iOS) from
+   *   text selections and the raw content from blocks; `'markdown'` copies
+   *   Markdown as plain text everywhere the item appears (inline math becomes
+   *   `$…$`, math blocks `$$…$$`, code blocks are fenced). The code block header
+   *   button and VoiceOver action always copy the raw code.
+   * @default { enabled: true, label: "Copy", format: "rich" }
    */
-  copy?: { label?: string };
+  copy?: { enabled?: boolean; label?: string; format?: 'rich' | 'markdown' };
   /**
-   * The built-in "Copy as Markdown" action for text selections.
+   * The built-in "Copy as Markdown" action, in the text selection menu and in
+   * the table / math / code block menus.
    * @default { enabled: true, label: "Copy as Markdown" }
    */
   copyAsMarkdown?: { enabled?: boolean; label?: string };
@@ -87,6 +145,23 @@ export interface SelectionMenuConfig {
     label?: string;
     pluralLabels?: SelectionMenuPluralLabels;
   };
+  /**
+   * Which system items the text selection menu keeps.
+   * - `'default'`: keep everything the OS adds (Select All, Look Up, Share,
+   *   Translate, app text actions…), with Copy replaced by the built-in one.
+   * - `'none'`: drop every system item; the menu only holds the built-in items
+   *   above and `contextMenuItems`.
+   * @default 'default'
+   * @platform ios, android
+   */
+  systemItems?: 'default' | 'none';
+  /**
+   * The copy button in the code block header. `false` hides the button; the
+   * header and language label stay.
+   * @default { enabled: true }
+   * @platform ios, android, macos
+   */
+  codeBlockCopyButton?: { enabled?: boolean };
 }
 
 export interface StreamingConfig {
@@ -114,6 +189,11 @@ export interface StreamingConfig {
 }
 
 export interface EnrichedMarkdownTextProps extends Omit<ViewProps, 'style'> {
+  /**
+   * Imperative handle: `clearSelection()` plus the host `measure*` methods.
+   * @platform ios, android
+   */
+  ref?: RefObject<EnrichedMarkdownTextInstance | null>;
   /**
    * Markdown content to render.
    * @platform ios, android, web
@@ -151,6 +231,21 @@ export interface EnrichedMarkdownTextProps extends Omit<ViewProps, 'style'> {
    * @platform ios, android, web
    */
   onLinkLongPress?: (event: LinkLongPressEvent) => void;
+  /**
+   * Renders a decoration (e.g. a badge or icon) over each link. The returned
+   * node is placed in an absolutely positioned box matching `info.rect` (the
+   * link's last line fragment, including chip padding) with
+   * `pointerEvents="box-none"`; position content relative to it (negative
+   * offsets overflow the box). Return `null` to leave a link undecorated.
+   *
+   * Native caveats: rects arrive from native after layout, so decorations
+   * appear one frame after the text; links inside tables (`flavor="github"`)
+   * are not reported; content overflowing the component bounds does not
+   * receive touches on Android. Toggling this prop between set and unset
+   * remounts the native view.
+   * @platform ios, android, web
+   */
+  renderLinkDecoration?: (info: LinkDecorationInfo) => ReactNode | null;
   /**
    * Callback fired when a task list checkbox is tapped.
    *
@@ -179,13 +274,44 @@ export interface EnrichedMarkdownTextProps extends Omit<ViewProps, 'style'> {
    * Callback fired when code is copied from a fenced code block, via the header
    * copy button, the long-press context-menu "Copy" action, or the VoiceOver
    * copy action. Receives the copied code and its language. Does not fire for
-   * "Copy as Markdown".
+   * "Copy as Markdown", nor for the context-menu "Copy" when
+   * `selectionMenuConfig.copy.format` is `'markdown'`.
    *
    * Only fires when `flavor="github"` (the copy button is part of the GitHub
    * flavor's container-based code block renderer).
    * @platform ios, android, macos
    */
   onCopyPress?: (event: CopyPressEvent) => void;
+  /**
+   * Takes over the "Copy" item of the text selection menu and of the table /
+   * math / code block menus. When set, native does **not** write the
+   * clipboard: it calls this with the copied content and the handler writes
+   * whatever it wants (e.g. with `expo-clipboard`). Overrides
+   * `selectionMenuConfig.copy.format`; `copy.enabled: false` still hides the
+   * item. "Copy as Markdown", the code block header button and the VoiceOver
+   * copy action are unaffected, and `onCopyPress` does not fire for an
+   * intercepted Copy.
+   * @platform ios, android
+   */
+  onCopy?: (event: CopyEvent) => void;
+  /**
+   * Reports the text selection so the app can draw its own menu (pair it with
+   * `contextMenuHidden`). Fires at most once per frame while the selection
+   * changes, and with `active: false` once it is gone. With
+   * `contextMenuHidden`, a long press on a table / math / code block fires it
+   * too (`source` is the block kind, `whole: true`), since those blocks have no
+   * text selection of their own. Only one part of a component holds a
+   * selection at a time; clearing the selection of *other* components is up to
+   * the app (`ref.current.clearSelection()`).
+   *
+   * Rects are relative to the view that `ref.current.measureInWindow`
+   * measures — add that origin to position UI on screen. On iOS, `adjusting`
+   * is `true` while a selection handle is dragged: hide the menu until it is
+   * `false` again. Android reports every step of the drag instead (with
+   * `adjusting: false`), so debounce before showing a menu there.
+   * @platform ios, android
+   */
+  onSelectionChange?: (event: SelectionChangeEvent) => void;
   /**
    * Controls whether the system link preview is shown on long press (iOS only).
    *
@@ -199,6 +325,16 @@ export interface EnrichedMarkdownTextProps extends Omit<ViewProps, 'style'> {
    * @platform ios
    */
   enableLinkPreview?: boolean;
+  /**
+   * When `true`, long-pressing a link selects its label and shows the
+   * selection edit menu, like a manual text selection, instead of the system
+   * link preview. Takes precedence over `enableLinkPreview` and
+   * `onLinkLongPress`.
+   *
+   * @default false
+   * @platform ios
+   */
+  linkLongPressSelects?: boolean;
   /**
    * Controls text selection.
    * - iOS: Controls text selection and link previews on long press.
@@ -315,6 +451,10 @@ export interface EnrichedMarkdownTextProps extends Omit<ViewProps, 'style'> {
    *
    * It does not suppress the system "Save to Camera Roll / Copy" sheet that
    * UIKit shows when long-pressing an image.
+   *
+   * On Android no selection toolbar is created at all, so ROMs that draw
+   * their own (MIUI) stay hidden too. A selection made while this is on
+   * keeps no menu if it is turned off mid-selection; the next one gets it.
    * @default false
    * @platform ios, android, macos
    */

package/src/types/MarkdownTextProps.web.ts

@@ -1,4 +1,4 @@
-import type { CSSProperties, HTMLAttributes } from 'react';
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
 import type { MarkdownStyle, Md4cFlags } from './MarkdownStyle';
 import type {
   LinkPressEvent,
@@ -6,6 +6,33 @@ import type {
   TaskListItemPressEvent,
 } from './events';
 
+/**
+ * A rect in dp, relative to the component's content box (inside any
+ * `containerStyle` padding).
+ */
+export interface LinkRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Layout of one rendered link, passed to `renderLinkDecoration`. */
+export interface LinkDecorationInfo {
+  /** Position of the link in the document (0-based) — stable key for a link. */
+  index: number;
+  url: string;
+  /** The link's visible text. */
+  text: string;
+  /**
+   * Anchor rect. Native: the drawn chip (glyphs + padding) of the link's last
+   * line fragment. Web: the link's inline box.
+   */
+  rect: LinkRect;
+  /** Every line fragment of the link (several when it wraps). Web: `[rect]`. */
+  rects: LinkRect[];
+}
+
 export interface EnrichedMarkdownTextProps extends Omit<
   HTMLAttributes<HTMLDivElement>,
   'style' | 'dir'
@@ -47,6 +74,21 @@ export interface EnrichedMarkdownTextProps extends Omit<
    * @platform ios, android, web
    */
   onLinkLongPress?: (event: LinkLongPressEvent) => void;
+  /**
+   * Renders a decoration (e.g. a badge or icon) over each link. The returned
+   * node is placed in an absolutely positioned box matching `info.rect` (the
+   * link's last line fragment, including chip padding) with
+   * `pointerEvents="box-none"`; position content relative to it (negative
+   * offsets overflow the box). Return `null` to leave a link undecorated.
+   *
+   * Native caveats: rects arrive from native after layout, so decorations
+   * appear one frame after the text; links inside tables (`flavor="github"`)
+   * are not reported; content overflowing the component bounds does not
+   * receive touches on Android. Toggling this prop between set and unset
+   * remounts the native view.
+   * @platform ios, android, web
+   */
+  renderLinkDecoration?: (info: LinkDecorationInfo) => ReactNode | null;
   /**
    * Callback fired when a task list checkbox is tapped.
    *

package/src/types/events.ts

@@ -17,6 +17,75 @@ export interface CopyPressEvent {
   language: string;
 }
 
+/**
+ * Payload of `onCopy`: what the Copy item would have copied. With `onCopy`
+ * set, native writes nothing to the clipboard — the handler owns the write.
+ */
+export interface CopyEvent {
+  /** Which menu the Copy item belongs to. */
+  source: 'selection' | 'math' | 'table' | 'code';
+  /**
+   * Markdown of the copied content — what `copy.format: 'markdown'` writes.
+   * Text selections: the original source when `whole`, otherwise rebuilt from
+   * the rendered styles (falls back to `text`). Blocks: `$$…$$`, the table as
+   * Markdown, or the fenced code block.
+   */
+  markdown: string;
+  /** Rendered text of the selection, or the block's raw content. */
+  text: string;
+  /**
+   * `true` when the selection covers the whole component, so `markdown` is the
+   * original source. Always `true` for blocks.
+   */
+  whole: boolean;
+}
+
+/**
+ * A rect in dp, relative to the component's native view: add the origin from
+ * the component ref's `measureInWindow` to get window coordinates.
+ */
+export interface SelectionRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Payload of `onSelectionChange`: the current text selection, or a table /
+ * math / code block long-pressed while `contextMenuHidden` is on. Content
+ * fields carry what `onCopy` would receive for the same selection.
+ */
+export interface SelectionChangeEvent {
+  /** `false` once the selection is gone; every other field is then empty / zero. */
+  active: boolean;
+  /** `'selection'` for text; the block kind for a long-pressed block. */
+  source: CopyEvent['source'];
+  /** Rendered text of the selection, or the block's raw content. */
+  text: string;
+  /** Same as `CopyEvent.markdown` for this selection. */
+  markdown: string;
+  /** Same as `CopyEvent.whole`. Always `true` for blocks. */
+  whole: boolean;
+  /**
+   * Bounding box of the selection (full content width when it spans several
+   * lines); the block's frame for blocks.
+   */
+  rect: SelectionRect;
+  /** Selected part of the first line (block: same as `rect`). */
+  startRect: SelectionRect;
+  /** Selected part of the last line (block: same as `rect`). */
+  endRect: SelectionRect;
+  /**
+   * `true` while a selection handle is dragged (or the loupe is held), with the
+   * selection as it was when the drag began; `false` again, with the new
+   * selection, once the finger lifts. Hide your menu while it is `true`.
+   * Always `false` on Android, which reports the selection continuously
+   * during the drag.
+   */
+  adjusting: boolean;
+}
+
 /**
  * Native-level context menu item config sent to the native component.
  * Does not include the `onPress` callback — callbacks are managed on the JS side.

package/src/web/EnrichedMarkdownText.tsx

@@ -9,7 +9,7 @@ import {
 import { parseMarkdown } from './parseMarkdown';
 import { RenderNode } from './renderers';
 import type { ASTNode, RendererCallbacks, RenderCapabilities } from './types';
-import { indexTaskItems, markInlineImages } from './utils';
+import { indexLinks, indexTaskItems, markInlineImages } from './utils';
 import { loadKaTeX } from './katex';
 import type { KaTeXInstance } from './katex';
 import { ENRM_TEXT_CLASS, ENRM_SELECTION_BG_VAR } from './globalStyles';
@@ -27,6 +27,7 @@ export const EnrichedMarkdownText = ({
   selectable = true,
   dir,
   selectionColor,
+  renderLinkDecoration,
   ...rest
 }: EnrichedMarkdownTextProps) => {
   const normalizedStyle = useMemo(
@@ -66,6 +67,7 @@ export const EnrichedMarkdownText = ({
       .then(([result, katexInstance]) => {
         if (!cancelled) {
           indexTaskItems(result);
+          indexLinks(result);
           markInlineImages(result);
 
           setParseError(false);
@@ -99,8 +101,13 @@ export const EnrichedMarkdownText = ({
   ]);
 
   const callbacks = useMemo<RendererCallbacks>(
-    () => ({ onLinkPress, onLinkLongPress, onTaskListItemPress }),
-    [onLinkPress, onLinkLongPress, onTaskListItemPress]
+    () => ({
+      onLinkPress,
+      onLinkLongPress,
+      onTaskListItemPress,
+      renderLinkDecoration,
+    }),
+    [onLinkPress, onLinkLongPress, onTaskListItemPress, renderLinkDecoration]
   );
 
   const capabilities = useMemo<RenderCapabilities>(

package/src/web/renderers/InlineRenderers.tsx

@@ -1,8 +1,16 @@
-import type { MouseEvent } from 'react';
+import {
+  useLayoutEffect,
+  useRef,
+  useState,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import type { LinkRect } from '../../types/MarkdownTextProps.web';
 import type { RendererProps, RendererMap } from '../types';
 import { extractNodeText } from '../utils';
 import { KaTeXRenderer } from './KaTeXRenderer';
 import { linkStyleForUrl } from '../styles';
+import type { CSSProperties } from 'react';
 
 function TextRenderer({ node }: RendererProps) {
   return <>{node.content ?? ''}</>;
@@ -78,16 +86,116 @@ function LinkRenderer({
     }
   };
 
+  const linkStyle = linkStyleForUrl(style, url);
+  const children = renderChildren(node);
+
+  if (callbacks.renderLinkDecoration) {
+    return (
+      <DecoratedLink
+        url={url}
+        index={node.attributes?.linkIndex ?? 0}
+        text={extractNodeText(node)}
+        linkStyle={linkStyle}
+        renderLinkDecoration={callbacks.renderLinkDecoration}
+        onClick={handleClick}
+        onContextMenu={handleContextMenu}
+      >
+        {children}
+      </DecoratedLink>
+    );
+  }
+
   return (
     <a
       href={url}
-      style={linkStyleForUrl(style, url)}
+      style={linkStyle}
       target="_blank"
       rel="noopener noreferrer"
       onClick={handleClick}
       onContextMenu={handleContextMenu}
     >
-      {renderChildren(node)}
+      {children}
+    </a>
+  );
+}
+
+const EMPTY_RECT: LinkRect = { x: 0, y: 0, width: 0, height: 0 };
+
+const decorationLayerStyle: CSSProperties = {
+  position: 'absolute',
+  inset: 0,
+  pointerEvents: 'none',
+};
+
+const decorationContentStyle: CSSProperties = { pointerEvents: 'auto' };
+
+/**
+ * A link with a `renderLinkDecoration` overlay. Unlike native, the overlay
+ * anchors to the link's whole inline box (not the last line fragment of a
+ * wrapping link), and `rect` is that box relative to itself.
+ */
+function DecoratedLink({
+  url,
+  index,
+  text,
+  linkStyle,
+  renderLinkDecoration,
+  onClick,
+  onContextMenu,
+  children,
+}: {
+  url: string;
+  index: number;
+  text: string;
+  linkStyle: ReturnType<typeof linkStyleForUrl>;
+  renderLinkDecoration: NonNullable<
+    RendererProps['callbacks']['renderLinkDecoration']
+  >;
+  onClick: (event: MouseEvent) => void;
+  onContextMenu: (event: MouseEvent) => void;
+  children: ReactNode;
+}) {
+  const anchorRef = useRef<HTMLAnchorElement>(null);
+  const [rect, setRect] = useState<LinkRect>(EMPTY_RECT);
+
+  // The overlay itself is sized by CSS (inset: 0); `rect` is informational, so
+  // re-measuring when the content or chip style changes is enough.
+  useLayoutEffect(() => {
+    const anchor = anchorRef.current;
+    if (!anchor) return;
+    const { width, height } = anchor.getBoundingClientRect();
+    setRect((prev) =>
+      prev.width === width && prev.height === height
+        ? prev
+        : { x: 0, y: 0, width, height }
+    );
+  }, [text, linkStyle]);
+
+  const decoration = renderLinkDecoration({
+    index,
+    url,
+    text,
+    rect,
+    rects: [rect],
+  });
+
+  return (
+    <a
+      ref={anchorRef}
+      href={url}
+      style={{ ...linkStyle, position: 'relative' }} // eslint-disable-line react-native/no-inline-styles
+      target="_blank"
+      rel="noopener noreferrer"
+      onClick={onClick}
+      onContextMenu={onContextMenu}
+    >
+      {children}
+      {decoration != null && (
+        <span aria-hidden style={decorationLayerStyle}>
+          {/* Mirrors native pointerEvents="box-none": only the decoration itself is hit-testable. */}
+          <span style={decorationContentStyle}>{decoration}</span>
+        </span>
+      )}
     </a>
   );
 }

package/src/web/styles.ts

@@ -323,6 +323,12 @@ export function linkStyleForUrl(
     variantIndex !== -1 ? style.linkVariants[variantIndex]! : base;
 
   const backgroundColor = resolved.backgroundColor;
+  const hasBorder =
+    resolved.borderWidth > 0 &&
+    !!resolved.borderColor &&
+    resolved.borderColor !== 'transparent';
+  const hasPadding =
+    resolved.paddingHorizontal > 0 || resolved.paddingVertical > 0;
   return {
     color: resolved.color,
     fontFamily: normalizeFontFamily(base.fontFamily),
@@ -330,6 +336,25 @@ export function linkStyleForUrl(
     ...(backgroundColor && backgroundColor !== 'transparent'
       ? { backgroundColor }
       : undefined),
+    // Chip: inline padding reserves horizontal space like native; vertical
+    // padding only paints (inline boxes don't grow the line box). `clone`
+    // rounds and pads each fragment of a wrapping link.
+    ...(hasPadding
+      ? {
+          padding: `${resolved.paddingVertical}px ${resolved.paddingHorizontal}px`,
+        }
+      : undefined),
+    ...(resolved.borderRadius > 0
+      ? { borderRadius: resolved.borderRadius }
+      : undefined),
+    ...(hasBorder
+      ? {
+          border: `${resolved.borderWidth}px solid ${resolved.borderColor}`,
+        }
+      : undefined),
+    ...(hasPadding || hasBorder || resolved.borderRadius > 0
+      ? { boxDecorationBreak: 'clone', WebkitBoxDecorationBreak: 'clone' }
+      : undefined),
   };
 }
 

package/src/web/types.ts

@@ -6,6 +6,7 @@ import type {
   LinkLongPressEvent,
   TaskListItemPressEvent,
 } from '../types/events';
+import type { LinkDecorationInfo } from '../types/MarkdownTextProps.web';
 import type { KaTeXInstance } from './katex';
 
 export type NodeType =
@@ -52,6 +53,8 @@ export interface NodeAttributes {
   taskIndex?: number;
   /** Stamped by markInlineImages() — not present in the raw WASM output. */
   isInline?: boolean;
+  /** Stamped by indexLinks() — document-order link index, not in the raw WASM output. */
+  linkIndex?: number;
   colCount?: string;
   headRowCount?: string;
   bodyRowCount?: string;
@@ -72,6 +75,7 @@ export interface RendererCallbacks {
   onLinkPress?: (event: LinkPressEvent) => void;
   onLinkLongPress?: (event: LinkLongPressEvent) => void;
   onTaskListItemPress?: (event: TaskListItemPressEvent) => void;
+  renderLinkDecoration?: (info: LinkDecorationInfo) => ReactNode | null;
 }
 
 export interface RenderCapabilities {

package/src/web/utils.ts

@@ -30,6 +30,14 @@ export function indexTaskItems(node: ASTNode, counter = { value: 0 }): void {
   node.children?.forEach((child) => indexTaskItems(child, counter));
 }
 
+/** Stamps Link nodes with their document-order index (the `renderLinkDecoration` key). */
+export function indexLinks(node: ASTNode, counter = { value: 0 }): void {
+  if (node.type === 'Link') {
+    node.attributes = { ...node.attributes, linkIndex: counter.value++ };
+  }
+  node.children?.forEach((child) => indexLinks(child, counter));
+}
+
 /**
  * Stamps Image nodes with `isInline` when they appear inside a paragraph
  * that also contains other content (text, links, etc.).