add list of valid context names to findBy docs

packages/core/src/asciidoctor-core-api.js

@@ -679,11 +679,157 @@ AbstractBlock.prototype.convert = function () {
   return this.$convert()
 }
 
+/**
+ * @namespace
+ * @extends BuiltInContext
+ */
+Opal.Asciidoctor.BuiltInContext = {
+  /**
+   * One of five admonition blocks.
+   */
+  Admonition: 'admonition',
+  /**
+   * An audio block.
+   */
+  Audio: 'audio',
+  /**
+   * A callout list.
+   */
+  CalloutList: 'colist',
+  /**
+   * A description list.
+   */
+  DescriptionList: 'dlist',
+  /**
+   * The top-level document or the document in an AsciiDoc table cell.
+   */
+  Document: 'document',
+  /**
+   * An example block.
+   */
+  Example: 'example',
+  /**
+   * A discrete heading.
+   */
+  FloatingTitle: 'floating_title',
+  /**
+   * An image block.
+   */
+  Image: 'image',
+  /**
+   * An item in an ordered, unordered, or description list (only relevant inside a list or description list block). In a description list, this block is used to represent the term and the description.
+   */
+  ListItem: 'list_item',
+  /**
+   * A listing block.
+   */
+  Listing: 'list_item',
+  /**
+   * A literal block.
+   */
+  Literal: 'list_item',
+  /**
+   * An ordered list.
+   */
+  OrderedList: 'olist',
+  /**
+   * An open block.
+   */
+  Open: 'open',
+  /**
+   * A page break.
+   */
+  PageBreak: 'page_break',
+  /**
+   * A paragraph.
+   */
+  Paragraph: 'paragraph',
+  /**
+   * A passthrough block.
+   */
+  Passthrough: 'pass',
+  /**
+   * The preamble of the document.
+   */
+  Preamble: 'preamble',
+  /**
+   * A quote block (aka blockquote).
+   */
+  Quote: 'quote',
+  /**
+   * A section. May also be a part, chapter, or special section.
+   */
+  Section: 'section',
+  /**
+   * A sidebar block.
+   */
+  Sidebar: 'sidebar',
+  /**
+   * A table block.
+   */
+  Table: 'table',
+  /**
+   * A table cell (only relevant inside a table block).
+   */
+  TableCell: 'table_cell',
+  /**
+   * A thematic break (aka horizontal rule).
+   */
+  ThematicBreak: 'thematic_break',
+  /**
+   * A TOC block.
+   */
+  TableOfContent: 'toc',
+  /**
+   * An unordered list.
+   */
+  UnorderedList: 'ulist',
+  /**
+   * An unordered list.
+   */
+  Verse: 'verse',
+  /**
+   * A video block.
+   */
+  Video: 'video'
+}
+
 /**
  * Query for all descendant block-level nodes in the document tree
  * that match the specified selector (context, style, id, and/or role).
  * If a function block is given, it's used as an additional filter.
  * If no selector or function block is supplied, all block-level nodes in the tree are returned.
+ * Valid context names include:
+ * <ul>
+ * <li>admonition - One of five admonition blocks.</li>
+ * <li>audio - An audio block</li>
+ * <li>colist - A callout list.</li>
+ * <li>dlist - A description list.</li>
+ * <li>document - The top-level document or the document in an AsciiDoc table cell.</li>
+ * <li>example - An example block.</li>
+ * <li>floating_title - A discrete heading</li>
+ * <li>image - An image block.</li>
+ * <li>list_item - An item in an ordered, unordered, or description list (only relevant inside a list or description list block). In a description list, this block is used to represent the term and the description.</li>
+ * <li>listing - A listing block.</li>
+ * <li>literal - A literal block.</li>
+ * <li>olist - An ordered list.</li>
+ * <li>open - An open block.</li>
+ * <li>page_break - A page break.</li>
+ * <li>paragraph - A paragraph.</li>
+ * <li>pass - A passthrough block.</li>
+ * <li>preamble - The preamble of the document.</li>
+ * <li>quote - A quote block (aka blockquote).</li>
+ * <li>section - A section. May also be a part, chapter, or special section.</li>
+ * <li>sidebar - A sidebar block.</li>
+ * <li>table - A table block.</li>
+ * <li>table_cell - A table cell (only relevant inside a table block).</li>
+ * <li>thematic_break - A thematic break (aka horizontal rule).</li>
+ * <li>toc - A TOC block (to designate custom TOC placement).</li>
+ * <li>ulist - An unordered list.</li>
+ * <li>verse - A verse block.</li>
+ * <li>video - A video block.</li>
+ * </ul>
+ * @see https://docs.asciidoctor.org/asciidoc/latest/blocks/#summary-of-built-in-contexts
  * @param {Object} [selector]
  * @param {function} [block]
  * @example

packages/core/types/index.d.ts

@@ -605,7 +605,123 @@ export namespace Asciidoctor {
     }
   }
 
+  /**
+   * List of the contexts of all the built-in blocks in AsciiDoc.
+   * @see https://docs.asciidoctor.org/asciidoc/latest/blocks/#summary-of-built-in-contexts
+   */
+  enum BuiltInContext {
+    /**
+     * One of five admonition blocks.
+     */
+    Admonition = "admonition",
+    /**
+     * An audio block.
+     */
+    Audio = "audio",
+    /**
+     * A callout list.
+     */
+    CalloutList = "colist",
+    /**
+     * A description list.
+     */
+    DescriptionList = "dlist",
+    /**
+     * The top-level document or the document in an AsciiDoc table cell.
+     */
+    Document = "document",
+    /**
+     * An example block.
+     */
+    Example = "example",
+    /**
+     * A discrete heading.
+     */
+    FloatingTitle = "floating_title",
+    /**
+     * An image block.
+     */
+    Image = "image",
+    /**
+     * An item in an ordered, unordered, or description list (only relevant inside a list or description list block). In a description list, this block is used to represent the term and the description.
+     */
+    ListItem = "list_item",
+    /**
+     * A listing block.
+     */
+    Listing = "list_item",
+    /**
+     * A literal block.
+     */
+    Literal = "list_item",
+    /**
+     * An ordered list.
+     */
+    OrderedList = "olist",
+    /**
+     * An open block.
+     */
+    Open = "open",
+    /**
+     * A page break.
+     */
+    PageBreak = "page_break",
+    /**
+     * A paragraph.
+     */
+    Paragraph = "paragraph",
+    /**
+     * A passthrough block.
+     */
+    Passthrough = "pass",
+    /**
+     * The preamble of the document.
+     */
+    Preamble = "preamble",
+    /**
+     * A quote block (aka blockquote).
+     */
+    Quote = "quote",
+    /**
+     * A section. May also be a part, chapter, or special section.
+     */
+    Section = "section",
+    /**
+     * A sidebar block.
+     */
+    Sidebar = "sidebar",
+    /**
+     * A table block.
+     */
+    Table = "table",
+    /**
+     * A table cell (only relevant inside a table block).
+     */
+    TableCell = "table_cell",
+    /**
+     * A thematic break (aka horizontal rule).
+     */
+    ThematicBreak = "thematic_break",
+    /**
+     * A TOC block.
+     */
+    TableOfContent = "toc",
+    /**
+     * An unordered list.
+     */
+    UnorderedList = "ulist",
+    /**
+     * An unordered list.
+     */
+    Verse = "verse",
+    /**
+     * A video block.
+     */
+    Video = "video",
+  }
+
   interface Selector {
+    context: BuiltInContext | string
     [key: string]: any;
   }
 
@@ -2134,6 +2250,8 @@ export namespace Asciidoctor {
      * that match the specified selector (context, style, id, and/or role).
      * If a function block is given, it's used as an additional filter.
      * If no selector or function block is supplied, all block-level nodes in the tree are returned.
+     * Valid context names include {@link BuiltInContext}.
+     *
      * @example
      * doc.findBy({'context': 'section'});
      * // => { level: 0, title: "Hello, AsciiDoc!", blocks: 0 }
@@ -3678,6 +3796,8 @@ export class Asciidoctor {
    */
   getVersion(): string;
 
+  BuiltInContext: typeof Asciidoctor.BuiltInContext;
+
   Block: typeof Asciidoctor.Block;
 
   Section: typeof Asciidoctor.Section;

packages/core/types/tests.ts

@@ -525,6 +525,7 @@ const result = docWithParagraphs.findBy((candidate) => {
   } else if (ctx === 'paragraph') {
     return true;
   }
+  return false;
 });
 assert(result.length === 2);
 assert(result[0].getContext() === 'paragraph');
@@ -1114,35 +1115,35 @@ assert(rowsBySection[2][0] === 'foot');
 
 const docWithParagraph = processor.load(`paragraph`);
 const paragraphBlock = docWithParagraph.getBlocks()[0];
-assert(paragraphBlock.resolveSubstitutions('attributes+', 'block')[0] === 'attributes');
+assert(paragraphBlock.resolveSubstitutions('attributes+', 'block')?.[0] === 'attributes');
 const blockSubs1 = paragraphBlock.resolveBlockSubstitutions('specialchars,attributes,quotes,replacements,macros,post_replacements', 'block');
 assert(blockSubs1.length === 6);
-assert(blockSubs1[0] === 'specialcharacters');
+assert(blockSubs1?.[0] === 'specialcharacters');
 assert(blockSubs1[1] === 'attributes');
 assert(blockSubs1[2] === 'quotes');
 assert(blockSubs1[3] === 'replacements');
 assert(blockSubs1[4] === 'macros');
 assert(blockSubs1[5] === 'post_replacements');
 const blockSubs2 = paragraphBlock.resolveBlockSubstitutions('attributes+,+replacements,-callouts', ['verbatim', 'quotes', 'callouts']);
 assert(blockSubs2.length === 4);
-assert(blockSubs2[0] === 'attributes');
+assert(blockSubs2?.[0] === 'attributes');
 assert(blockSubs2[1] === 'verbatim');
 assert(blockSubs2[2] === 'quotes');
 assert(blockSubs2[3] === 'replacements');
 const blockSubs3 = paragraphBlock.resolveBlockSubstitutions('normal');
 assert(blockSubs3.length === 6);
-assert(blockSubs3[0] === 'specialcharacters');
+assert(blockSubs3?.[0] === 'specialcharacters');
 assert(blockSubs3[1] === 'quotes');
 assert(blockSubs3[2] === 'attributes');
 assert(blockSubs3[3] === 'replacements');
 assert(blockSubs3[4] === 'macros');
 assert(blockSubs3[5] === 'post_replacements');
 const blockSubs4 = paragraphBlock.resolvePassSubstitutions('macros');
 assert(blockSubs4.length === 1);
-assert(blockSubs4[0] === 'macros');
+assert(blockSubs4?.[0] === 'macros');
 const blockSubs5 = paragraphBlock.resolvePassSubstitutions('verbatim');
 assert(blockSubs5.length === 1);
-assert(blockSubs5[0] === 'specialcharacters');
+assert(blockSubs5?.[0] === 'specialcharacters');
 
 const docWithImages = processor.load(`
 [#img-sunset]
@@ -1183,6 +1184,7 @@ const outerParagraphs = docWithExample.findBy((candidate) => {
   } else if (ctx === 'paragraph') {
     return true;
   }
+  return false;
 });
 assert(outerParagraphs.length === 2);
 assert(outerParagraphs[0].getContext() === 'paragraph');
@@ -1233,7 +1235,7 @@ a|
 :foo: foo
 AsciiDoc cell
 |===`);
-const tableWithAsciiDocCell = docWithAsciiDocCell.findBy({context: 'table'})[0] as Asciidoctor.Table;
+const tableWithAsciiDocCell = docWithAsciiDocCell.findBy({context: processor.BuiltInContext.Table})[0] as Asciidoctor.Table;
 const normalCell = tableWithAsciiDocCell.getBodyRows()[0][0];
 const asciidocCell = tableWithAsciiDocCell.getBodyRows()[1][0];
 assert(typeof normalCell.getInnerDocument() === 'undefined');