punctilio 4.3.0 → 5.0.0

package/src/quotes.ts

@@ -1,31 +1,41 @@
-import { DEFAULT_SEPARATOR, UNICODE_SYMBOLS } from "./constants.js"
-import { classifyAndRenderQuotes, type PunctuationStyle } from "./quote-classifier.js"
+import { cachedRegExp, UNICODE_SYMBOLS } from "./constants.js"
+import { classifyAndRenderQuotes, convertPrimeMarks, type PunctuationStyle } from "./quote-classifier.js"
+import { overInput, type ProseView, replaceAllInView } from "./prose-view.js"
 
 const { RIGHT_SINGLE_QUOTE, MODIFIER_LETTER_APOSTROPHE } = UNICODE_SYMBOLS
 
 export { PUNCTUATION_STYLES, type PunctuationStyle, type QuoteRole } from "./quote-classifier.js"
 
 export interface QuoteOptions {
-  /** Boundary marker for HTML element boundaries. Default: "\uE000\uE001" */
-  separator?: string
   /** "american" (inside), "british" (outside), "none". Default: "american" */
   punctuationStyle?: PunctuationStyle
-}
-
-function processQuotes(text: string, options: QuoteOptions, apostrophe: string): string {
-  const separator = options.separator ?? DEFAULT_SEPARATOR
-  const punctuationStyle = options.punctuationStyle ?? "american"
-  if (punctuationStyle === "none") return text
-  return classifyAndRenderQuotes(text, separator, punctuationStyle, apostrophe)
+  /**
+   * Convert prime-mark candidates (5'10" → 5′10″) before quote
+   * classification. `false` leaves them to the quote rules. Applies to
+   * `niceQuotes` only; `classifyApostrophes` never converts primes.
+   * Default: true
+   */
+  primes?: boolean
 }
 
 /** Convert straight quotes to smart quotes. */
-export function niceQuotes(text: string, options: QuoteOptions = {}): string {
-  // Apostrophes render as U+2019, the same glyph as closing single quotes,
-  // per the Unicode Standard. Any U+02BC already in the input is normalized
-  // to U+2019 as well (including under punctuationStyle "none").
-  return processQuotes(text, options, RIGHT_SINGLE_QUOTE)
-    .replaceAll(MODIFIER_LETTER_APOSTROPHE, RIGHT_SINGLE_QUOTE)
+export function niceQuotes(input: string, options?: QuoteOptions): string
+export function niceQuotes(input: ProseView, options?: QuoteOptions): void
+export function niceQuotes(input: string | ProseView, options: QuoteOptions = {}): string | void {
+  const punctuationStyle = options.punctuationStyle ?? "american"
+  return overInput(input, (view) => {
+    if (punctuationStyle !== "none") {
+      if (options.primes !== false) {
+        convertPrimeMarks(view)
+      }
+      // Apostrophes render as U+2019, the same glyph as closing single quotes,
+      // per the Unicode Standard.
+      classifyAndRenderQuotes(view, punctuationStyle, RIGHT_SINGLE_QUOTE)
+    }
+    // Any U+02BC already in the input is normalized to U+2019 as well
+    // (including under punctuationStyle "none").
+    replaceAllInView(view, cachedRegExp(MODIFIER_LETTER_APOSTROPHE, "g"), () => RIGHT_SINGLE_QUOTE)
+  })
 }
 
 /**
@@ -38,6 +48,13 @@ export function niceQuotes(text: string, options: QuoteOptions = {}): string {
  * For display output, use {@link niceQuotes} or `transform()` instead,
  * which use U+2019 for both per the Unicode Standard.
  */
-export function classifyApostrophes(text: string, options: QuoteOptions = {}): string {
-  return processQuotes(text, options, MODIFIER_LETTER_APOSTROPHE)
+export function classifyApostrophes(input: string, options?: QuoteOptions): string
+export function classifyApostrophes(input: ProseView, options?: QuoteOptions): void
+export function classifyApostrophes(input: string | ProseView, options: QuoteOptions = {}): string | void {
+  const punctuationStyle = options.punctuationStyle ?? "american"
+  return overInput(input, (view) => {
+    if (punctuationStyle !== "none") {
+      classifyAndRenderQuotes(view, punctuationStyle, MODIFIER_LETTER_APOSTROPHE)
+    }
+  })
 }

package/src/rehype.ts

@@ -3,14 +3,13 @@ import type { Transformer } from "unified"
 
 import { SKIP, visitParents } from "unist-util-visit-parents"
 
-import { transform, TRANSFORM_OPTION_KEYS, type TransformOptions } from "./index.js"
-import { DEFAULT_SEPARATOR, MAX_RECURSION_DEPTH } from "./constants.js"
+import { transformView } from "./index.js"
+import { TRANSFORM_OPTION_KEYS, type TransformOptions } from "./transform-options.js"
+import { MAX_RECURSION_DEPTH } from "./constants.js"
 import { assertKnownOptionKeys, formatErrorString } from "./utils.js"
-import { buildProseView, runLegacyPass } from "./prose-view.js"
+import { buildProseView, type ProsePass, type ProseView } from "./prose-view.js"
 
-type ElementPredicate = (node: Element) => boolean
-
-type TextTransformer = (input: string) => string
+export type ElementPredicate = (node: Element) => boolean
 
 /** Per-text-node skip predicate, called after element-level `shouldSkip`. */
 export type TextNodeSkipPredicate = (
@@ -186,50 +185,101 @@ export function assertSmartQuotesMatch(input: string): void {
   }
 }
 
+export interface ProseViewOfOptions extends ElementTransformOptions {
+  /** Element-level skip predicate; skipped subtrees contribute no text nodes. */
+  shouldSkip?: ElementPredicate
+}
+
 /**
- * Transforms element text using the separator-marking technique. When
- * `checkInvariance` is true, verifies `stripMarkers(transform(marked)) ===
- * transform(stripMarkers(text))` for debugging marker interactions.
+ * Builds a ProseView over the element's transformable text nodes, honoring
+ * the element-level `shouldSkip` and per-text-node `shouldSkipText`
+ * predicates. Returns null when the element holds no transformable text.
  */
-export function transformElement(
-  node: Element,
-  transformFn: TextTransformer,
-  shouldSkip: ElementPredicate,
-  separator: string,
-  checkInvariance: boolean = false,
-  options?: ElementTransformOptions
-): void {
+export function proseViewOf(element: Element, options: ProseViewOfOptions = {}): ProseView | null {
   /* istanbul ignore if -- defensive: elements should always have children array */
-  if (!node?.children) {
-    return
+  if (!element?.children) {
+    return null
   }
 
-  const textNodes = flattenTextNodes(node, shouldSkip, options)
+  const shouldSkip = options.shouldSkip ?? (() => false)
+  const textNodes = flattenTextNodes(element, shouldSkip, options)
   if (textNodes.length === 0) {
-    return
+    return null
   }
 
-  // Capture marked content before transformation for invariance check
-  const markedContent = checkInvariance
-    ? textNodes.map((n) => n.value + separator).join("")
-    : ""
-
-  const view = buildProseView(textNodes)
-  runLegacyPass(view, transformFn, separator)
-
-  if (checkInvariance) {
-    const transformedContent = textNodes.map((n) => n.value + separator).join("")
-    const stripSep = (s: string) => s.replaceAll(separator, "")
-    const strippedTransformed = stripSep(transformedContent)
-    const expected = transformFn(stripSep(markedContent))
-
-    if (expected !== strippedTransformed) {
-      throw new Error(
-        `Transform invariance check failed: ` +
-          `expected ${formatErrorString(expected, "expected")} ` +
-          `but got ${formatErrorString(strippedTransformed, "actual")}`
-      )
+  return buildProseView(textNodes)
+}
+
+/**
+ * One entry in an `applyPasses` sequence: a bare pass, or a pass with its own
+ * skip predicates layered on top of the base options (the per-transform
+ * skip-set case, e.g. a fractions pass that additionally skips `<a>`).
+ */
+export type PassEntry =
+  | ProsePass
+  | { pass: ProsePass; shouldSkip?: ElementPredicate; shouldSkipText?: TextNodeSkipPredicate }
+
+interface ResolvedPassEntry {
+  pass: ProsePass
+  shouldSkip?: ElementPredicate
+  shouldSkipText?: TextNodeSkipPredicate
+}
+
+function resolvePassEntry(entry: PassEntry): ResolvedPassEntry {
+  return typeof entry === "function" ? { pass: entry } : entry
+}
+
+/** OR-combines an optional entry predicate onto an optional base predicate. */
+function mergePredicates<Args extends unknown[]>(
+  base: ((...args: Args) => boolean) | undefined,
+  extra: ((...args: Args) => boolean) | undefined,
+): ((...args: Args) => boolean) | undefined {
+  if (!base) return extra
+  if (!extra) return base
+  return (...args) => base(...args) || extra(...args)
+}
+
+/**
+ * Runs `passes` in order over `element`'s transformable text, owning the
+ * ProseView lifecycle so callers never touch a view directly. Each pass
+ * commits its edits before the next runs, so passes see each other's
+ * committed output — the same sequencing `transform()`'s pipeline uses.
+ *
+ * Entries whose predicates match the previous entry's share one view;
+ * an entry with different `shouldSkip`/`shouldSkipText` predicates gets a
+ * fresh view (built after the previous pass committed) over the text nodes
+ * that survive both the base `options` predicates and its own.
+ */
+export function applyPasses(
+  element: Element,
+  passes: readonly PassEntry[],
+  options: ProseViewOfOptions = {},
+): void {
+  let currentView: ProseView | null = null
+  let currentPredicates: Pick<ResolvedPassEntry, "shouldSkip" | "shouldSkipText"> | null = null
+
+  for (const entry of passes) {
+    const { pass, shouldSkip, shouldSkipText } = resolvePassEntry(entry)
+
+    const samePredicates =
+      currentPredicates !== null &&
+      currentPredicates.shouldSkip === shouldSkip &&
+      currentPredicates.shouldSkipText === shouldSkipText
+    if (!samePredicates) {
+      currentView = proseViewOf(element, {
+        shouldSkip: mergePredicates(options.shouldSkip, shouldSkip),
+        shouldSkipText: mergePredicates(options.shouldSkipText, shouldSkipText),
+      })
+      currentPredicates = { shouldSkip, shouldSkipText }
+    }
+
+    // No transformable text under this entry's predicates; later entries may
+    // still see text (their skip sets differ), so keep going.
+    if (currentView === null) {
+      continue
     }
+
+    pass(currentView)
   }
 }
 
@@ -334,12 +384,72 @@ function hasTextDescendant(
   return false
 }
 
-export function collectTransformableElements(
+export interface CollectProseBlocksOptions {
+  /**
+   * HTML tag names to skip. Default: the plugin's default skip list
+   * ("code", "pre", "script", ...).
+   */
+  skipTags?: string[]
+  /** CSS class names whose elements (and their subtrees) are skipped. Default: [] */
+  skipClasses?: string[]
+  /** Additional element-level skip predicate, OR-ed with the tag/class skips. */
+  shouldSkip?: ElementPredicate
+  /** Invert the element model as in {@link RehypePunctilioOptions.transformAllElements}. Default: false */
+  transformAllElements?: boolean
+}
+
+/** Skip predicate and transformable-tag test resolved from the options. */
+interface ResolvedCollectOptions {
+  shouldSkip: ElementPredicate
+  isTransformable: (tagName: string) => boolean
+}
+
+function resolveCollectOptions(options: CollectProseBlocksOptions): ResolvedCollectOptions {
+  const { skipTags = DEFAULT_SKIP_TAGS, skipClasses = [], shouldSkip, transformAllElements = false } = options
+
+  // In inverted mode, form-value elements join the skip-list so their literal
+  // values are neither transformed nor flattened into a transformable ancestor.
+  const skipTagSet = new Set(transformAllElements ? [...skipTags, ...FORM_VALUE_TAGS] : skipTags)
+  const skipClassSet = new Set(skipClasses)
+
+  const hasSkipClass = (node: Element): boolean => {
+    if (skipClassSet.size === 0) return false
+    const classNames = node.properties?.className
+    const classes = Array.isArray(classNames)
+      ? classNames.filter((c): c is string => typeof c === "string")
+      : typeof classNames === "string" ? classNames.split(/\s+/) : []
+    return classes.some((cls) => skipClassSet.has(cls))
+  }
+
+  return {
+    shouldSkip: (node) =>
+      skipTagSet.has(node.tagName) || hasSkipClass(node) || (shouldSkip?.(node) ?? false),
+    // Inverted mode transforms every non-skipped element except non-prose
+    // containers; the default keeps the `TRANSFORMABLE_ELEMENTS` allowlist
+    // (plus custom elements).
+    isTransformable: transformAllElements
+      ? (tagName) => !NON_PROSE_CONTAINER_TAGS.has(tagName)
+      : isTransformableElement,
+  }
+}
+
+/**
+ * Collects the elements under `root` (inclusive) whose text should be
+ * transformed as one prose block: transformable elements with direct text or
+ * inline-only text descendants. Elements with block-level children recurse so
+ * each block transforms independently.
+ */
+export function collectProseBlocks(root: Element, options: CollectProseBlocksOptions = {}): Element[] {
+  const { shouldSkip, isTransformable } = resolveCollectOptions(options)
+  return collectProseBlocksImpl(root, shouldSkip, 0, undefined, isTransformable)
+}
+
+function collectProseBlocksImpl(
   node: Element,
   shouldSkip: ElementPredicate,
-  depth: number = 0,
-  alreadyTransformed?: ReadonlySet<Element>,
-  isTransformable: (tagName: string) => boolean = isTransformableElement
+  depth: number,
+  alreadyTransformed: ReadonlySet<Element> | undefined,
+  isTransformable: (tagName: string) => boolean
 ): Element[] {
   /* istanbul ignore if -- defensive: prevents stack overflow from malicious HTML */
   if (depth > MAX_RECURSION_DEPTH) {
@@ -371,7 +481,7 @@ export function collectTransformableElements(
     // children that should be independent, or has no text to transform.
     for (const child of node.children) {
       if (child.type === "element") {
-        const childResults = collectTransformableElements(child, shouldSkip, depth + 1, alreadyTransformed, isTransformable)
+        const childResults = collectProseBlocksImpl(child, shouldSkip, depth + 1, alreadyTransformed, isTransformable)
         for (const r of childResults) results.push(r)
       }
     }
@@ -400,53 +510,21 @@ export function rehypePunctilio(
   assertKnownOptionKeys(options, REHYPE_OPTION_KEYS, "rehypePunctilio")
 
   const {
-    skipTags = DEFAULT_SKIP_TAGS,
-    skipClasses = [],
-    separator = DEFAULT_SEPARATOR,
+    skipTags,
+    skipClasses,
     shouldSkipText,
-    transformAllElements = false,
+    transformAllElements,
     ...transformOptions
   } = options
 
-  // In inverted mode, form-value elements join the skip-list so their literal
-  // values are neither transformed nor flattened into a transformable ancestor.
-  const skipTagSet = new Set(transformAllElements ? [...skipTags, ...FORM_VALUE_TAGS] : skipTags)
-  const skipClassSet = new Set(skipClasses)
-
-  // Inverted mode transforms every non-skipped element except non-prose
-  // containers; the default keeps the `TRANSFORMABLE_ELEMENTS` allowlist (plus
-  // custom elements).
-  const isTransformable = transformAllElements
-    ? (tagName: string) => !NON_PROSE_CONTAINER_TAGS.has(tagName)
-    : isTransformableElement
-
-  const hasSkipClass = (node: Element): boolean => {
-    if (skipClassSet.size === 0) return false
-    const classNames = node.properties?.className
-    const classes = Array.isArray(classNames)
-      ? classNames.filter((c): c is string => typeof c === "string")
-      : typeof classNames === "string" ? classNames.split(/\s+/) : []
-    return classes.some((cls) => skipClassSet.has(cls))
-  }
-
-  const shouldSkip = (node: Element): boolean =>
-    skipTagSet.has(node.tagName) || hasSkipClass(node)
-
-  const pluginOptions = {
-    ...transformOptions,
-    separator,
-  }
-
-  const transformFn = (text: string): string => {
-    return transform(text, pluginOptions)
-  }
+  const { shouldSkip, isTransformable } = resolveCollectOptions({ skipTags, skipClasses, transformAllElements })
 
   // Allocate the per-element options object once; it's read-only inside
-  // transformElement, so sharing across calls is safe and avoids a fresh
+  // proseViewOf, so sharing across calls is safe and avoids a fresh
   // allocation per transformable element.
-  const elementOptions: ElementTransformOptions | undefined = shouldSkipText
-    ? { shouldSkipText }
-    : undefined
+  const viewOptions: ProseViewOfOptions = shouldSkipText
+    ? { shouldSkip, shouldSkipText }
+    : { shouldSkip }
 
   return (tree: Root) => {
     // Track transformed elements to avoid double-processing
@@ -463,10 +541,13 @@ export function rehypePunctilio(
       }
 
       // Collect and transform elements with text content
-      const elementsToTransform = collectTransformableElements(node, shouldSkip, 0, transformed, isTransformable)
+      const elementsToTransform = collectProseBlocksImpl(node, shouldSkip, 0, transformed, isTransformable)
       for (const elt of elementsToTransform) {
         if (!transformed.has(elt)) {
-          transformElement(elt, transformFn, shouldSkip, separator, false, elementOptions)
+          const view = proseViewOf(elt, viewOptions)
+          if (view !== null) {
+            transformView(view, transformOptions)
+          }
           transformed.add(elt)
           // Mark all descendants as processed since their text was included
           markDescendants(elt, transformed)

package/src/remark.ts

@@ -3,9 +3,11 @@ import type { Transformer } from "unified"
 
 import { visitParents } from "unist-util-visit-parents"
 
-import { transform, TRANSFORM_OPTION_KEYS, type TransformOptions } from "./index.js"
-import { DEFAULT_SEPARATOR, MAX_RECURSION_DEPTH } from "./constants.js"
-import { assertKnownOptionKeys, transformTextNodes } from "./utils.js"
+import { transformView } from "./index.js"
+import { TRANSFORM_OPTION_KEYS, type TransformOptions } from "./transform-options.js"
+import { MAX_RECURSION_DEPTH } from "./constants.js"
+import { buildProseView } from "./prose-view.js"
+import { assertKnownOptionKeys } from "./utils.js"
 
 /**
  * Same options as `transform()`, except `nbsp` defaults to `false`:
@@ -49,19 +51,12 @@ export function remarkPunctilio(
 ): Transformer<Root, Root> {
   assertKnownOptionKeys(options, TRANSFORM_OPTION_KEYS, "remarkPunctilio")
 
-  const separator = options.separator ?? DEFAULT_SEPARATOR
-
   // Markdown is a source format, so default `nbsp` to false (`?? false`
   // rather than spread defaults so an explicit `nbsp: undefined` also gets
   // the Markdown default instead of falling through to transform's).
   const pluginOptions = {
     ...options,
     nbsp: options.nbsp ?? false,
-    separator,
-  }
-
-  const transformFn = (text: string): string => {
-    return transform(text, pluginOptions)
   }
 
   return (tree: Root) => {
@@ -88,7 +83,7 @@ export function remarkPunctilio(
         return
       }
 
-      transformTextNodes(textNodes, transformFn, separator)
+      transformView(buildProseView(textNodes), pluginOptions)
     })
   }
 }