@asciidoctor/core 4.0.1 → 4.0.3

package/src/extensions.js

@@ -54,6 +54,30 @@ import { MacroNameRx, CC_ANY } from './rx.js'
  * @typedef {ProcessorDslInterface & { prefer(): void; prepend(): void }} DocumentProcessorDslInterface
  */
 
+/**
+ * DSL interface for preprocessors.
+ *
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
+ *   process(fn: (this: PreprocessorDslInterface, document: Document, reader: Reader) => Reader | void): void;
+ * }} PreprocessorDslInterface
+ */
+
+/**
+ * DSL interface for tree processors.
+ *
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
+ *   process(fn: (this: TreeProcessorDslInterface, document: Document) => Document | void): void;
+ * }} TreeProcessorDslInterface
+ */
+
+/**
+ * DSL interface for postprocessors.
+ *
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
+ *   process(fn: (this: PostprocessorDslInterface, document: Document, output: string) => string): void;
+ * }} PostprocessorDslInterface
+ */
+
 /**
  * DSL interface for syntax processors (BlockProcessor, BlockMacroProcessor, InlineMacroProcessor).
  *
@@ -74,28 +98,35 @@ import { MacroNameRx, CC_ANY } from './rx.js'
 /**
  * DSL interface for include processors.
  *
- * @typedef {DocumentProcessorDslInterface & {
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
  *   handles(fn: (target: string) => boolean): void;
  *   handles(fn: (doc: Document, target: string) => boolean): void;
+ *   process(fn: (this: IncludeProcessorDslInterface, document: Document, reader: Reader, target: string, attributes: Record<string, string>) => void): void;
  * }} IncludeProcessorDslInterface
  */
 
 /**
  * DSL interface for docinfo processors.
  *
- * @typedef {DocumentProcessorDslInterface & {
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
  *   atLocation(value: string): void;
+ *   process(fn: (this: DocinfoProcessorDslInterface, document: Document) => string): void;
  * }} DocinfoProcessorDslInterface
  */
 
 /**
  * DSL interface for block processors.
  *
- * @typedef {SyntaxProcessorDslInterface & {
+ * The `process` callback is bound to the processor instance, so `this` inside it
+ * (and inside the registration function) exposes the `createBlock` helpers.
+ *
+ * @typedef {Omit<SyntaxProcessorDslInterface, 'process'> & {
  *   contexts(...value: (string | string[])[]): void;
  *   onContexts(...value: (string | string[])[]): void;
  *   onContext(...value: (string | string[])[]): void;
  *   bindTo(...value: (string | string[])[]): void;
+ *   createBlock(parent: AbstractBlock, context: string, source?: string | string[] | null, attrs?: object, opts?: object): Block;
+ *   process(fn: (this: BlockProcessorDslInterface, parent: AbstractBlock, reader: Reader, attributes: Record<string, unknown>) => AbstractBlock | void): void;
  * }} BlockProcessorDslInterface
  */
 
@@ -105,14 +136,31 @@ import { MacroNameRx, CC_ANY } from './rx.js'
  * @typedef {SyntaxProcessorDslInterface} MacroProcessorDslInterface
  */
 
+/**
+ * DSL interface for block macro processors.
+ *
+ * The `process` callback is bound to the processor instance, so `this` inside it
+ * (and inside the registration function) exposes the `createBlock` helpers.
+ *
+ * @typedef {Omit<MacroProcessorDslInterface, 'process'> & {
+ *   createBlock(parent: AbstractBlock, context: string, source?: string | string[] | null, attrs?: object, opts?: object): Block;
+ *   process(fn: (this: BlockMacroProcessorDslInterface, parent: AbstractBlock, target: string, attributes: Record<string, unknown>) => AbstractBlock | void): void;
+ * }} BlockMacroProcessorDslInterface
+ */
+
 /**
  * DSL interface for inline macro processors.
  *
- * @typedef {MacroProcessorDslInterface & {
+ * The `process` callback is bound to the processor instance, so `this` inside it
+ * (and inside the registration function) exposes the `createInline` helper.
+ *
+ * @typedef {Omit<MacroProcessorDslInterface, 'process'> & {
  *   format(value: string): void;
  *   matchFormat(value: string): void;
  *   usingFormat(value: string): void;
  *   match(value: RegExp): void;
+ *   createInline(parent: AbstractBlock, context: string, text: string, opts?: object): Inline;
+ *   process(fn: (this: InlineMacroProcessorDslInterface, parent: AbstractBlock, target: string, attributes: Record<string, unknown>) => Inline | void): void;
  * }} InlineMacroProcessorDslInterface
  */
 
@@ -839,7 +887,15 @@ export class IncludeProcessor extends Processor {
   }
 
   /**
-   * @param {Document} doc - The document being parsed.
+   * Decide whether this include processor handles the given target.
+   *
+   * Override this method in a subclass. The override may accept either just the
+   * target string (Ruby-style, arity 1) or both the document and the target
+   * (arity 2) — an arity-1 override is adapted at registration time so the
+   * parser can always invoke it as `handles(doc, target)`. The first parameter
+   * is therefore typed `Document | string` so both override shapes type-check.
+   *
+   * @param {Document|string} doc - The document being parsed, or (for a Ruby-style arity-1 override) the include target.
    * @param {string} target - The target of the include directive.
    * @returns {boolean} true if this processor handles the given target.
    */
@@ -1251,6 +1307,14 @@ export class Registry {
    *   this.process(function (doc, reader) { ... })
    * })
    *
+   * @overload
+   * @param {typeof Preprocessor} processor - A Preprocessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: PreprocessorDslInterface) => void} fn - Registration function bound to the preprocessor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -1284,6 +1348,14 @@ export class Registry {
   /**
    * Register a TreeProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof TreeProcessor} processor - A TreeProcessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: TreeProcessorDslInterface) => void} fn - Registration function bound to the tree processor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -1337,6 +1409,14 @@ export class Registry {
   /**
    * Register a Postprocessor with the extension registry.
    *
+   * @overload
+   * @param {typeof Postprocessor} processor - A Postprocessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: PostprocessorDslInterface) => void} fn - Registration function bound to the postprocessor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -1370,6 +1450,14 @@ export class Registry {
   /**
    * Register an IncludeProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof IncludeProcessor} processor - An IncludeProcessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: IncludeProcessorDslInterface) => void} fn - Registration function bound to the include processor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -1408,6 +1496,14 @@ export class Registry {
   /**
    * Register a DocinfoProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof DocinfoProcessor} processor - A DocinfoProcessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: DocinfoProcessorDslInterface) => void} fn - Registration function bound to the docinfo processor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -1475,6 +1571,20 @@ export class Registry {
    *   this.process(function (parent, reader, attrs) { ... })
    * })
    *
+   * @overload
+   * @param {typeof BlockProcessor} processor - A BlockProcessor subclass.
+   * @param {string} [name] - Optional explicit block name.
+   * @returns {ProcessorExtension} an Extension proxy object.
+   *
+   * @overload
+   * @param {string} name - The block name.
+   * @param {(this: BlockProcessorDslInterface) => void} fn - Registration function bound to the block DSL.
+   * @returns {ProcessorExtension} an Extension proxy object.
+   *
+   * @overload
+   * @param {(this: BlockProcessorDslInterface) => void} fn - Registration function bound to the block DSL.
+   * @returns {ProcessorExtension} an Extension proxy object.
+   *
    * @param {...*} args - Class constructor, instance, block function, or name + one of those.
    * @returns {ProcessorExtension} an Extension proxy object.
    */
@@ -1525,6 +1635,20 @@ export class Registry {
   /**
    * Register a BlockMacroProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof BlockMacroProcessor} processor - A BlockMacroProcessor subclass.
+   * @param {string} [name] - Optional explicit macro name.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {string} name - The macro name.
+   * @param {(this: BlockMacroProcessorDslInterface) => void} fn - Registration function bound to the block macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: BlockMacroProcessorDslInterface) => void} fn - Registration function bound to the block macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -1580,6 +1704,20 @@ export class Registry {
   /**
    * Register an InlineMacroProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof InlineMacroProcessor} processor - An InlineMacroProcessor subclass.
+   * @param {string} [name] - Optional explicit macro name.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {string} name - The macro name.
+   * @param {(this: InlineMacroProcessorDslInterface) => void} fn - Registration function bound to the inline macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: InlineMacroProcessorDslInterface) => void} fn - Registration function bound to the inline macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */

package/src/index.js

@@ -40,11 +40,15 @@ import {
 /**
  * @typedef {import('./extensions.js').ProcessorDslInterface} ProcessorDslInterface
  * @typedef {import('./extensions.js').DocumentProcessorDslInterface} DocumentProcessorDslInterface
+ * @typedef {import('./extensions.js').PreprocessorDslInterface} PreprocessorDslInterface
+ * @typedef {import('./extensions.js').TreeProcessorDslInterface} TreeProcessorDslInterface
+ * @typedef {import('./extensions.js').PostprocessorDslInterface} PostprocessorDslInterface
  * @typedef {import('./extensions.js').SyntaxProcessorDslInterface} SyntaxProcessorDslInterface
  * @typedef {import('./extensions.js').IncludeProcessorDslInterface} IncludeProcessorDslInterface
  * @typedef {import('./extensions.js').DocinfoProcessorDslInterface} DocinfoProcessorDslInterface
  * @typedef {import('./extensions.js').BlockProcessorDslInterface} BlockProcessorDslInterface
  * @typedef {import('./extensions.js').MacroProcessorDslInterface} MacroProcessorDslInterface
+ * @typedef {import('./extensions.js').BlockMacroProcessorDslInterface} BlockMacroProcessorDslInterface
  * @typedef {import('./extensions.js').InlineMacroProcessorDslInterface} InlineMacroProcessorDslInterface
  */
 import {

package/types/abstract_node.d.ts

@@ -234,9 +234,10 @@ export abstract class AbstractNode {
      * Construct a URI reference or data URI to the target image.
      *
      * If the target image is already a URI it is left untouched (unless data-uri
-     * conversion is requested). The image is resolved relative to the directory
-     * named by assetDirKey. When data-uri is enabled and the safe level permits,
-     * the image is embedded as a Base64 data URI.
+     * conversion is requested). If the target image is a data URI, then it is
+     * already an embedded image, so it is returned as-is. The image is resolved
+     * relative to the directory named by assetDirKey. When data-uri is enabled and
+     * the safe level permits, the image is embedded as a Base64 data URI.
      *
      * NOTE: When the document has both 'data-uri' and 'allow-uri-read' enabled
      * and the resolved image URL is a remote URI, this method returns a Promise

package/types/document.d.ts

@@ -469,10 +469,26 @@ export class Document extends AbstractBlock<string> {
      * @returns {string[]} The list of substitutions to apply.
      */
     private _resolveDocinfoSubs;
+    /**
+     * @private
+     * Restore the document attributes to a previously captured snapshot, discarding any
+     * body-level (re)assignments replayed while pre-computing text. Mirrors Ruby's
+     * restore_attributes-before-convert invariant.
+     * @param {Object} snapshot - The attributes snapshot to restore.
+     */
+    private _restoreAttributeSnapshot;
     /**
      * @private
      * Walk the block tree and pre-compute all async text values.
      * Handles titles (AbstractBlock), list item text, table cell text, and reftexts.
+     *
+     * Runs in two passes (see {@link parse}): with `resolveContent` false only titles and
+     * reftexts are substituted (so the reftext→id map can be built); with `resolveContent`
+     * true the list item / table cell / dlist text is substituted, resolving any natural
+     * cross-references against the now-complete map. Title/reftext pre-computation is
+     * idempotent (results are cached), so running it in both passes is a no-op the second time.
+     * @param {AbstractBlock} block - The block to resolve.
+     * @param {boolean} resolveContent - Whether to substitute list item / cell / dlist text.
      */
     private _resolveAllTexts;
     /**