add support for row- and column-span in tables

rdar://98017880

Author: QuietMisdreavus

Package.resolved

@@ -121,7 +121,7 @@ if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
     package.dependencies += [
         .package(url: "https://github.com/apple/swift-nio.git", .upToNextMinor(from: "2.31.2")),
         .package(url: "https://github.com/apple/swift-nio-ssl.git", .upToNextMinor(from: "2.15.0")),
-        .package(name: "swift-markdown", url: "https://github.com/apple/swift-markdown.git", .branch("main")),
+        .package(name: "swift-markdown", url: "https://github.com/QuietMisdreavus/swift-markdown.git", .branch("table-spans")),
         .package(name: "CLMDB", url: "https://github.com/apple/swift-lmdb.git", .branch("main")),
         .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "1.0.1")),
         .package(name: "SymbolKit", url: "https://github.com/apple/swift-docc-symbolkit", .branch("main")),

Package.swift

@@ -231,13 +231,16 @@ public enum RenderBlockContent: Equatable {
         public var header: HeaderType
         /// The rows in this table.
         public var rows: [TableRow]
+        /// Any extended information that describes cells in this table.
+        public var extendedData: Set<TableCellExtendedData>
         /// Additional metadata for this table, if present.
         public var metadata: RenderContentMetadata?
 
         /// Creates a new table with the given data.
-        public init(header: HeaderType, rows: [TableRow], metadata: RenderContentMetadata? = nil) {
+        public init(header: HeaderType, rows: [TableRow], extendedData: Set<TableCellExtendedData>, metadata: RenderContentMetadata? = nil) {
             self.header = header
             self.rows = rows
+            self.extendedData = extendedData
             self.metadata = metadata
         }
     }
@@ -378,6 +381,36 @@ public enum RenderBlockContent: Equatable {
             cells = try container.decode([Cell].self)
         }
     }
+
+    /// Extended data that may be applied to a table cell.
+    public struct TableCellExtendedData: Equatable, Hashable {
+        /// The row coordinate for the cell described by this data.
+        public let rowIndex: Int
+        /// The column coordinate for the cell described by this data.
+        public let columnIndex: Int
+
+        /// The number of columns this cell spans over.
+        ///
+        /// A value of 1 is the default. A value of zero means that this cell is being "spanned
+        /// over" by a previous cell in this row. A value of greater than 1 means that this cell
+        /// "spans over" later cells in this row.
+        public let colspan: UInt
+
+        /// The number of rows this cell spans over.
+        ///
+        /// A value of 1 is the default. A value of zero means that this cell is being "spanned
+        /// over" by another cell in a previous row. A value of greater than one means that this
+        /// cell "spans over" other cells in later rows.
+        public let rowspan: UInt
+
+        public init(rowIndex: Int, columnIndex: Int,
+                    colspan: UInt, rowspan: UInt) {
+            self.rowIndex = rowIndex
+            self.columnIndex = columnIndex
+            self.colspan = colspan
+            self.rowspan = rowspan
+        }
+    }
 
     /// A term definition.
     ///
@@ -429,6 +462,102 @@ public enum RenderBlockContent: Equatable {
     }
 }
 
+// Writing a manual Codable implementation for tables because the encoding of `extendedData` does
+// not follow from the struct layout.
+extension RenderBlockContent.Table: Codable {
+    // `extendedData` is encoded as a keyed container where the "keys" are the cell index, and
+    // the "values" are the remaining fields in the struct. The key is formatted as a string with
+    // the format "{row}_{column}", which is represented here as the `.index(row:column:)` enum
+    // case. This CodingKey implementation performs that parsing and formatting so that the
+    // Encodable/Decodable implementation can use the plain numbered indices.
+    enum CodingKeys: CodingKey, Equatable {
+        case header, rows, extendedData, metadata
+        case index(row: Int, column: Int)
+        case colspan, rowspan
+
+        var stringValue: String {
+            switch self {
+            case .header: return "header"
+            case .rows: return "rows"
+            case .extendedData: return "extendedData"
+            case .metadata: return "metadata"
+            case .colspan: return "colspan"
+            case .rowspan: return "rowspan"
+            case let .index(row, column): return "\(row)_\(column)"
+            }
+        }
+
+        init?(stringValue: String) {
+            switch stringValue {
+            case "header": self = .header
+            case "rows": self = .rows
+            case "extendedData": self = .extendedData
+            case "metadata": self = .metadata
+            case "colspan": self = .colspan
+            case "rowspan": self = .rowspan
+            default:
+                let coordinates = stringValue.split(separator: "_")
+                guard coordinates.count == 2,
+                      let rowIndex = Int(coordinates.first!),
+                      let columnIndex = Int(coordinates.last!) else {
+                    return nil
+                }
+                self = .index(row: rowIndex, column: columnIndex)
+            }
+        }
+
+        var intValue: Int? { nil }
+
+        init?(intValue: Int) {
+            return nil
+        }
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        var extendedData = Set<RenderBlockContent.TableCellExtendedData>()
+        if container.allKeys.contains(.extendedData) {
+            let dataContainer = try container.nestedContainer(keyedBy: CodingKeys.self, forKey: .extendedData)
+
+            for index in dataContainer.allKeys {
+                guard case let .index(row, column) = index else { continue }
+
+                let cellContainer = try dataContainer.nestedContainer(keyedBy: CodingKeys.self, forKey: index)
+                extendedData.insert(.init(rowIndex: row,
+                                          columnIndex: column,
+                                          colspan: try cellContainer.decode(UInt.self, forKey: .colspan),
+                                          rowspan: try cellContainer.decode(UInt.self, forKey: .rowspan)))
+            }
+        }
+
+        self = .init(header: try container.decode(RenderBlockContent.HeaderType.self, forKey: .header),
+                     rows: try container.decode([RenderBlockContent.TableRow].self, forKey: .rows),
+                     extendedData: extendedData,
+                     metadata: try container.decodeIfPresent(RenderContentMetadata.self, forKey: .metadata))
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+
+        try container.encode(header, forKey: .header)
+        try container.encode(rows, forKey: .rows)
+
+        if !extendedData.isEmpty {
+            var dataContainer = container.nestedContainer(keyedBy: CodingKeys.self, forKey: .extendedData)
+            for data in extendedData {
+                var cellContainer = dataContainer.nestedContainer(keyedBy: CodingKeys.self,
+                                                                  forKey: .index(row: data.rowIndex,
+                                                                                 column: data.columnIndex))
+                try cellContainer.encode(data.colspan, forKey: .colspan)
+                try cellContainer.encode(data.rowspan, forKey: .rowspan)
+            }
+        }
+
+        try container.encodeIfPresent(metadata, forKey: .metadata)
+    }
+}
+
 // Codable conformance
 extension RenderBlockContent: Codable {
     private enum CodingKeys: CodingKey {
@@ -475,11 +604,8 @@ extension RenderBlockContent: Codable {
         case .dictionaryExample:
             self = try .dictionaryExample(.init(summary: container.decodeIfPresent([RenderBlockContent].self, forKey: .summary), example: container.decode(CodeExample.self, forKey: .example)))
         case .table:
-            self = try .table(.init(
-                header: container.decode(HeaderType.self, forKey: .header),
-                rows: container.decode([TableRow].self, forKey: .rows),
-                metadata: container.decodeIfPresent(RenderContentMetadata.self, forKey: .metadata)
-            ))
+            // Defer to Table's own Codable implemenatation to parse `extendedData` properly.
+            self = try .table(.init(from: decoder))
         case .termList:
             self = try .termList(.init(items: container.decode([TermListItem].self, forKey: .items)))
         case .row:
@@ -551,9 +677,8 @@ extension RenderBlockContent: Codable {
             try container.encodeIfPresent(e.summary, forKey: .summary)
             try container.encode(e.example, forKey: .example)
         case .table(let t):
-            try container.encode(t.header, forKey: .header)
-            try container.encode(t.rows, forKey: .rows)
-            try container.encodeIfPresent(t.metadata, forKey: .metadata)
+            // Defer to Table's own Codable implemenatation to format `extendedData` properly.
+            try t.encode(to: encoder)
         case .termList(items: let l):
             try container.encode(l.items, forKey: .items)
         case .row(let row):

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -185,23 +185,32 @@ struct RenderContentCompiler: MarkupVisitor {
     }
 
     mutating func visitTable(_ table: Table) -> [RenderContent] {
+        var extendedData = Set<RenderBlockContent.TableCellExtendedData>()
+
         var headerCells = [RenderBlockContent.TableRow.Cell]()
         for cell in table.head.cells {
             let cellContent = cell.children.reduce(into: [], { result, child in result.append(contentsOf: visit(child))})
             headerCells.append([RenderBlockContent.paragraph(.init(inlineContent: cellContent as! [RenderInlineContent]))])
+            if cell.colspan != 1 || cell.rowspan != 1 {
+                extendedData.insert(.init(rowIndex: 0, columnIndex: cell.indexInParent, colspan: cell.colspan, rowspan: cell.rowspan))
+            }
         }
 
         var rows = [RenderBlockContent.TableRow]()
         for row in table.body.rows {
+            let rowIndex = row.indexInParent + 1
             var cells = [RenderBlockContent.TableRow.Cell]()
             for cell in row.cells {
                 let cellContent = cell.children.reduce(into: [], { result, child in result.append(contentsOf: visit(child))})
                 cells.append([RenderBlockContent.paragraph(.init(inlineContent: cellContent as! [RenderInlineContent]))])
+                if cell.colspan != 1 || cell.rowspan != 1 {
+                    extendedData.insert(.init(rowIndex: rowIndex, columnIndex: cell.indexInParent, colspan: cell.colspan, rowspan: cell.rowspan))
+                }
             }
             rows.append(RenderBlockContent.TableRow(cells: cells))
         }
 
-        return [RenderBlockContent.table(.init(header: .row, rows: [RenderBlockContent.TableRow(cells: headerCells)] + rows, metadata: nil))]
+        return [RenderBlockContent.table(.init(header: .row, rows: [RenderBlockContent.TableRow(cells: headerCells)] + rows, extendedData: extendedData, metadata: nil))]
     }
 
     mutating func visitStrikethrough(_ strikethrough: Strikethrough) -> [RenderContent] {

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

@@ -37,7 +37,7 @@ class RenderContentMetadataTests: XCTestCase {
             RenderInlineContent.text("Content"),
         ])
 
-        let table = RenderBlockContent.table(.init(header: .both, rows: [], metadata: metadata))
+        let table = RenderBlockContent.table(.init(header: .both, rows: [], extendedData: [], metadata: metadata))
         let data = try JSONEncoder().encode(table)
         let roundtrip = try JSONDecoder().decode(RenderBlockContent.self, from: data)
 
@@ -105,6 +105,58 @@ class RenderContentMetadataTests: XCTestCase {
             default: XCTFail("Unexpected element")
         }
     }
+
+    func testRenderingTableSpans() throws {
+        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        var renderContentCompiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleIdentifier: bundle.identifier, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = """
+        | one | two | three |
+        | --- | --- | ----- |
+        | big      || small |
+        | ^        || small |
+        """
+        let document = Document(parsing: source)
+
+        // Verifies that a markdown table renders correctly.
+
+        let result = try XCTUnwrap(renderContentCompiler.visit(document.child(at: 0)!))
+        let renderedTable = try XCTUnwrap(result.first as? RenderBlockContent)
+
+        let renderCell: ([RenderBlockContent]) -> String = { cell in
+            return cell.reduce(into: "") { (result, element) in
+                switch element {
+                    case .paragraph(let p):
+                    guard let para = p.inlineContent.first else { return }
+                        result.append(para.plainText)
+                    default: XCTFail("Unexpected element"); return
+                }
+            }
+        }
+
+        let expectedExtendedData: [RenderBlockContent.TableCellExtendedData] = [
+            .init(rowIndex: 1, columnIndex: 0, colspan: 2, rowspan: 2),
+            .init(rowIndex: 1, columnIndex: 1, colspan: 0, rowspan: 1),
+            .init(rowIndex: 2, columnIndex: 0, colspan: 2, rowspan: 0),
+            .init(rowIndex: 2, columnIndex: 1, colspan: 0, rowspan: 1)
+        ]
+
+        switch renderedTable {
+            case .table(let t):
+                XCTAssertEqual(t.header, .row)
+                XCTAssertEqual(t.rows.count, 3)
+                guard t.rows.count == 3 else { return }
+                XCTAssertEqual(t.rows[0].cells.map(renderCell), ["one", "two", "three"])
+                XCTAssertEqual(t.rows[1].cells.map(renderCell), ["big", "", "small"])
+                XCTAssertEqual(t.rows[2].cells.map(renderCell), ["", "", "small"])
+                for expectedData in expectedExtendedData {
+                    XCTAssert(t.extendedData.contains(expectedData))
+                }
+            default: XCTFail("Unexpected element")
+        }
+
+        try assertRoundTripCoding(renderedTable)
+    }
 
     func testStrikethrough() throws {
         let (bundle, context) = try testBundleAndContext(named: "TestBundle")