feat: a bare figure fence is one figure of ordered panels

src/ast.ts

@@ -380,6 +380,27 @@ export interface Figure extends BaseNode {
   shortCaption?: InlineNode[]
 }
 
+/**
+ * A composite figure: a bare `::: figure` fence (PART 9 §4c).
+ *
+ * `children` are ordinary blocks in source order; the PANELS are the `figure`
+ * and `table` nodes among them, derived by type rather than repeated under a
+ * second key, so the two can never disagree. `caption` is the group caption
+ * (the `^ ` line after the CLOSING fence); absent means uncaptioned, not empty.
+ *
+ * Discriminated by `type`, deliberately: every `figure` carries a `target`,
+ * the group does not, and a consumer probing for the missing field instead of
+ * reading the type string would break silently the day either shape grows a
+ * field. No `title`, no `label`, no `shortCaption` - that design space belongs
+ * to markup-carve/carve#1118 and markup-carve/carve#1121 and is not claimed
+ * here.
+ */
+export interface FigureGroup extends BaseNode {
+  type: 'figure_group'
+  children: BlockNode[]
+  caption?: InlineNode[]
+}
+
 export interface AbbreviationDef extends BaseNode {
   type: 'abbreviation_def'
   abbr: string
@@ -436,6 +457,7 @@ export type BlockNode =
   | LineBlock
   | DefinitionList
   | Figure
+  | FigureGroup
   | Image
   | AbbreviationDef
   | LinkReferenceDefinition

src/footnote-numbering.ts

@@ -101,6 +101,10 @@ function walkBlockInlines(
       if (node.target.type === 'block_quote' || node.target.type === 'table')
         walkBlockInlines(node.target, visit, depth + 1)
       break
+    case 'figure_group':
+      if (node.caption) visit(node.caption)
+      node.children.forEach((c) => walkBlockInlines(c, visit, depth + 1))
+      break
     default:
       break
   }

src/heading-ids.ts

@@ -14,8 +14,10 @@ import type {
   CaptionNumber,
   Document,
   Figure,
+  FigureGroup,
   Image,
   InlineNode,
+  Table,
   Text,
 } from './ast.js'
 import { SMART_PUNCTUATION_GLYPHS } from './ast.js'
@@ -649,6 +651,9 @@ export function resolveHeadingIds(
         case 'figure':
           if (b.target.type === 'block_quote') assignIds(b.target.children, true)
           break
+        case 'figure_group':
+          assignIds(b.children, inBlockquote)
+          break
         default:
           break
       }
@@ -992,6 +997,10 @@ export function resolveHeadingIds(
         if (b.target.type === 'block_quote' || b.target.type === 'table')
           walkBlock(b.target, fn)
         break
+      case 'figure_group':
+        if (b.caption) fn(b.caption)
+        b.children.forEach((c) => walkBlock(c, fn))
+        break
       default:
         break
     }
@@ -1014,18 +1023,19 @@ export function resolveHeadingIds(
   // these on an ingested tree (carve#758). What stays here is the crossref
   // target registration, which only makes sense while resolution is running.
   const numberBlocks = (blocks: BlockNode[]): void => {
-    numberCaptionsIn(blocks, counters, (labelNodes, next, attrs) => {
+    numberCaptionsIn(blocks, counters, (labelNodes, next, attrs, suffix) => {
       const id = attrs?.id
       if (id === undefined || targets.has(id)) return
       // Clean "Label N" auto-text: clone the label inlines, trim trailing
       // whitespace on the final text node, then append " N". Markup in the
-      // label is preserved.
+      // label is preserved. A composite figure's PANEL arrives with a letter
+      // suffix (`Figure 2a`, §4c) on the group's own number.
       const autoNodes = labelNodes.map((n) => ({ ...n })) as InlineNode[]
       const last = autoNodes[autoNodes.length - 1]
       if (last && last.type === 'text') {
         last.value = last.value.replace(RE_TRAILING_LABEL_WS, '')
       }
-      autoNodes.push({ type: 'text', value: ` ${next}` } as Text)
+      autoNodes.push({ type: 'text', value: ` ${next}${suffix ?? ''}` } as Text)
       targets.set(id, autoNodes)
     })
   }
@@ -1265,6 +1275,7 @@ export function promoteBlockImages(blocks: BlockNode[], figuresOnly = false): vo
       case 'block_quote':
       case 'admonition':
       case 'div':
+      case 'figure_group':
         promoteBlockImages(b.children, figuresOnly)
         break
       case 'list':
@@ -1288,8 +1299,37 @@ type CaptionNumbered = (
   labelNodes: InlineNode[],
   n: number,
   attrs: Attrs | undefined,
+  /**
+   * PART 9 §4c: a composite figure's PANEL takes the GROUP's number plus a
+   * letter (`a`, `b`, …) derived from its order among the panels. The letter
+   * arrives here as a suffix on the registered auto-text (`Figure 2a`); the
+   * group's own registration and every non-panel caption pass none.
+   */
+  suffix?: string,
 ) => void
 
+/**
+ * The §4c panel letter for panel index `k` (0-based): `a`..`z`, then `aa`,
+ * `ab`, … - bijective base 26, matching the executable spec's `panelLetter`.
+ */
+function panelLetter(k: number): string {
+  let s = ''
+  k++
+  while (k > 0) {
+    k--
+    s = String.fromCharCode(97 + (k % 26)) + s
+    k = Math.floor(k / 26)
+  }
+  return s
+}
+
+/** The §4c panels of a group: its `figure` and `table` children, in order. */
+export function figureGroupPanels(group: FigureGroup): (Figure | Table)[] {
+  return group.children.filter(
+    (c): c is Figure | Table => c.type === 'figure' || c.type === 'table',
+  )
+}
+
 /**
  * Assign `caption_number.n` per label, in document order, over `blocks`.
  *
@@ -1308,49 +1348,83 @@ export function numberCaptionsIn(
   counters: Map<string, number>,
   onNumbered?: CaptionNumbered,
 ): void {
-  const numberCaption = (caption: InlineNode[], attrs: Attrs | undefined): void => {
+  const numberCaption = (caption: InlineNode[], attrs: Attrs | undefined): number | undefined => {
     const idx = caption.findIndex((n) => n.type === 'caption_number')
-    if (idx === -1) return
+    if (idx === -1) return undefined
     const labelNodes = caption.slice(0, idx)
     const label = inlineText(labelNodes).replace(RE_TRAILING_LABEL_WS, '')
     const next = (counters.get(label) ?? 0) + 1
     counters.set(label, next)
     ;(caption[idx] as CaptionNumber).n = next
     onNumbered?.(labelNodes, next, attrs)
+    return idx
   }
 
-  const walk = (bs: BlockNode[]): void => {
+  // PART 9 §4c: a PANEL of a composite figure is not a sequence unit. Its
+  // caption's `#` placeholder draws no number and registers nothing - the
+  // caption_number node STAYS in the tree, un-numbered, and every renderer
+  // emits its authored spelling (the unresolved-reference precedent: keep the
+  // typed node, render what the author wrote). Decided here, in the one
+  // shared numbering pass, so the parse path and the AST-JSON ingest path
+  // (carve#758) publish the same wire shape as carve-php and carve-rs.
+  const walk = (bs: BlockNode[], inPanel: boolean): void => {
     for (const b of bs) {
       if (b.type === 'figure') {
-        numberCaption(b.caption, b.attrs)
+        if (!inPanel) numberCaption(b.caption, b.attrs)
       } else if (b.type === 'table' && b.caption) {
-        numberCaption(b.caption, b.attrs)
+        if (!inPanel) numberCaption(b.caption, b.attrs)
       }
       switch (b.type) {
         case 'block_quote':
         case 'admonition':
         case 'div':
-          walk(b.children)
+          walk(b.children, inPanel)
           break
         case 'list':
-          for (const it of b.items) walk(it.children)
+          for (const it of b.items) walk(it.children, inPanel)
           break
         case 'definition_list':
-          for (const it of b.items) for (const d of it.definitions) walk(d)
+          for (const it of b.items) for (const d of it.definitions) walk(d, inPanel)
           break
         case 'figure':
           // A figure wraps an image / blockquote / table; descend into a
           // blockquote or table target so a nested captioned element is
           // numbered too (mirrors walkBlock's figure-target descent).
-          if (b.target.type === 'block_quote') walk(b.target.children)
-          else if (b.target.type === 'table' && b.target.caption)
+          if (b.target.type === 'block_quote') walk(b.target.children, inPanel)
+          else if (b.target.type === 'table' && b.target.caption && !inPanel) {
             numberCaption(b.target.caption, b.target.attrs)
+          }
           break
+        case 'figure_group': {
+          // The group is ONE numbering unit (§4c): only its own caption draws
+          // from the sequence, and its draw also registers the panel ids with
+          // letters - so `</#panel-id>` resolves as "Figure 2a". A group with
+          // no numbered caption registers nothing for its panels either.
+          const panels = figureGroupPanels(b)
+          if (!inPanel && b.caption) {
+            const labelIdx = numberCaption(b.caption, b.attrs)
+            if (labelIdx !== undefined && onNumbered) {
+              const labelNodes = b.caption.slice(0, labelIdx)
+              const n = (b.caption[labelIdx] as CaptionNumber).n!
+              panels.forEach((panel, k) => {
+                onNumbered(labelNodes, n, panel.attrs, panelLetter(k))
+              })
+            }
+          }
+          // Children walk: panels are not sequence units, and everything a
+          // panel CONTAINS is suppressed with it; non-panel stray content
+          // numbers normally, exactly as it would outside the group.
+          for (const c of b.children) {
+            const isPanel = c.type === 'figure' || c.type === 'table'
+            walk([c], inPanel || isPanel)
+          }
+          break
+        }
         default:
           break
       }
     }
   }
 
-  walk(blocks)
+  walk(blocks, false)
 }

src/heading-level-shift.ts

@@ -21,6 +21,7 @@ function shiftBlock(node: BlockNode, shift: number): void {
     case 'block_quote':
     case 'div':
     case 'admonition':
+    case 'figure_group':
       node.children.forEach((c) => shiftBlock(c, shift))
       break
     case 'list':

src/heading-numbers.ts

@@ -165,6 +165,7 @@ function walkHeadings(
       }
       case 'div':
       case 'admonition':
+      case 'figure_group':
         descend((b as { children?: unknown }).children, inBlockquote)
         break
       case 'definition_list': {

src/heading-reference.ts

@@ -144,6 +144,7 @@ function walkBlock(
     case 'block_quote':
     case 'div':
     case 'admonition':
+    case 'figure_group':
       node.children.forEach((c) => walkBlock(c, targets, counts))
       break
     case 'list':

src/html-import.ts

@@ -3,6 +3,7 @@ import type {
   Attrs,
   BlockNode,
   Document,
+  FigureGroup,
   InlineNode,
   List,
   TableCell,
@@ -362,6 +363,12 @@ class Importer {
   }
 
   private figure(node: P5Node, path: string, depth: number, attrs?: Attrs): BlockNode[] {
+    // Our own composite-figure shape (PART 9 §4c): the group class marks the
+    // wrapper, the panels div holds the children. Own-output round trip only;
+    // a foreign nested figure without the class keeps the unwrap below.
+    if ((this.attr(node, 'class') ?? '').split(/\s+/).includes('carve-figure-group')) {
+      return this.figureGroup(node, path, depth, attrs)
+    }
     const captionNode = node.childNodes?.find((n) => n.tagName === 'figcaption')
     const body = (node.childNodes ?? []).filter((n) => n !== captionNode)
     const targets = this.blocks(body, path, depth + 1)
@@ -515,6 +522,57 @@ class Importer {
       )
     }
   }
+
+  /** A copy of `attrs` without one class, `undefined` when nothing remains. */
+  private stripClass(attrs: Attrs | undefined, className: string): Attrs | undefined {
+    if (!attrs?.classes) return attrs
+    const classes = attrs.classes.filter((c) => c !== className)
+    const next: Attrs = { ...attrs }
+    if (classes.length) next.classes = classes
+    else delete next.classes
+    if (next.id === undefined && next.classes === undefined && next.keyValues === undefined) {
+      return undefined
+    }
+    return next
+  }
+
+  /**
+   * Our own `carve-figure-group` output back to a `figure_group` node (PART 9
+   * §4c). The panels div unwraps; a `carve-figure-panel` figure comes back as
+   * the panel it rendered from - a bare `<figure><table/></figure>` wrapper
+   * (the table panel, which carries no figcaption) unwraps to the table so the
+   * table's own caption and attrs stay its own.
+   */
+  private figureGroup(node: P5Node, path: string, depth: number, attrs?: Attrs): BlockNode[] {
+    const captionNode = node.childNodes?.find((n) => n.tagName === 'figcaption')
+    const panelsDiv = node.childNodes?.find(
+      (n) => n.tagName === 'div' && (this.attr(n, 'class') ?? '').split(/\s+/).includes('carve-figure-panels'),
+    )
+    const bodyNodes = panelsDiv
+      ? panelsDiv.childNodes ?? []
+      : (node.childNodes ?? []).filter((n) => n !== captionNode)
+    const children = this.blocks(bodyNodes, path, depth + 1)
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i]!
+      if (child.type !== 'figure' || !child.attrs?.classes?.includes('carve-figure-panel')) continue
+      const stripped = this.stripClass(child.attrs, 'carve-figure-panel')
+      if (stripped) child.attrs = stripped
+      else delete child.attrs
+      // The explicit table-panel wrapper renders with no figcaption; the
+      // generic figure import gave it an empty caption, which is not a shape
+      // the parser produces - unwrap back to the table itself.
+      if (child.target.type === 'table' && child.caption.length === 0 && child.attrs === undefined) {
+        children[i] = child.target
+      }
+    }
+    const group: FigureGroup = { type: 'figure_group', children }
+    if (captionNode) {
+      group.caption = this.inlines(captionNode.childNodes ?? [], `${path}/figcaption[1]`, depth + 1)
+    }
+    const groupAttrs = this.stripClass(attrs, 'carve-figure-group')
+    if (groupAttrs) group.attrs = groupAttrs
+    return [group]
+  }
 }
 
 export function htmlToAst(html: string, options: HtmlImportOptions = {}): HtmlImportResult<Document> {