feat(07): close native text pagination semantics loop

2026-05-22 20:39:26 +08:00
parent 21c8bbb23a
commit d7339aa255
15 changed files with 722 additions and 22 deletions
@@ -42,6 +42,9 @@ struct RDEPUBTextLayouter {
                    blockRange: adjusted.blockRange,
                    attachmentRanges: adjusted.attachmentRanges,
                    attachmentKinds: adjusted.attachmentKinds,
+                    blockKinds: adjusted.blockKinds,
+                    semanticHints: adjusted.semanticHints,
+                    attachmentPlacements: adjusted.attachmentPlacements,
                    trailingFragmentID: trailingFragmentID,
                    diagnostics: adjusted.diagnostics
                )
@@ -67,9 +70,15 @@ struct RDEPUBTextLayouter {
        blockRange: NSRange?,
        attachmentRanges: [NSRange],
        attachmentKinds: [RDEPUBTextAttachmentKind],
+        blockKinds: [RDEPUBTextBlockKind],
+        semanticHints: [RDEPUBTextSemanticHint],
+        attachmentPlacements: [RDEPUBTextAttachmentPlacement],
        diagnostics: [String]
    ) {
        let pageEnd = proposedRange.location + proposedRange.length
+        let proposedBlockKinds = blockKinds(in: proposedRange)
+        let proposedSemanticHints = semanticHints(in: proposedRange)
+        let proposedAttachmentPlacements = attachmentPlacements(in: proposedRange)
        guard pageEnd < totalLength else {
            return (
                range: proposedRange,
@@ -77,11 +86,17 @@ struct RDEPUBTextLayouter {
                blockRange: blockRange(at: max(proposedRange.location, pageEnd - 1)),
                attachmentRanges: attachmentRanges(in: proposedRange),
                attachmentKinds: attachmentKinds(in: proposedRange),
+                blockKinds: proposedBlockKinds,
+                semanticHints: proposedSemanticHints,
+                attachmentPlacements: proposedAttachmentPlacements,
                diagnostics: diagnostics(
                    reason: .chapterEnd,
                    range: proposedRange,
                    attachmentRanges: attachmentRanges(in: proposedRange),
-                    blockRange: blockRange(at: max(proposedRange.location, pageEnd - 1))
+                    blockRange: blockRange(at: max(proposedRange.location, pageEnd - 1)),
+                    blockKinds: proposedBlockKinds,
+                    semanticHints: proposedSemanticHints,
+                    attachmentPlacements: proposedAttachmentPlacements
                )
            )
        }
@@ -92,6 +107,36 @@ struct RDEPUBTextLayouter {
        let currentBlockRange = blockRange(at: max(proposedRange.location, pageEnd - 1))
        let currentAttachmentRanges = attachmentRanges(in: proposedRange)
        let currentAttachmentKinds = attachmentKinds(in: proposedRange)
+        let currentBlockKinds = proposedBlockKinds
+        let currentSemanticHints = proposedSemanticHints
+        let currentAttachmentPlacements = proposedAttachmentPlacements
+
+        if let semanticBoundary = preferredSemanticBoundary(
+            in: proposedRange,
+            minimumEnd: minimumEnd
+        ) {
+            let adjustedRange = NSRange(location: proposedRange.location, length: semanticBoundary.location - proposedRange.location)
+            return (
+                range: adjustedRange,
+                breakReason: .semanticBoundary,
+                blockRange: currentBlockRange,
+                attachmentRanges: currentAttachmentRanges,
+                attachmentKinds: currentAttachmentKinds,
+                blockKinds: currentBlockKinds,
+                semanticHints: currentSemanticHints,
+                attachmentPlacements: currentAttachmentPlacements,
+                diagnostics: diagnostics(
+                    reason: .semanticBoundary,
+                    range: adjustedRange,
+                    attachmentRanges: currentAttachmentRanges,
+                    blockRange: currentBlockRange,
+                    blockKinds: currentBlockKinds,
+                    semanticHints: currentSemanticHints,
+                    attachmentPlacements: currentAttachmentPlacements,
+                    trigger: semanticBoundary.trigger
+                )
+            )
+        }

        if let attachmentBoundary = preferredAttachmentBoundary(
            in: proposedRange,
@@ -104,11 +149,17 @@ struct RDEPUBTextLayouter {
                blockRange: currentBlockRange,
                attachmentRanges: currentAttachmentRanges,
                attachmentKinds: currentAttachmentKinds,
+                blockKinds: currentBlockKinds,
+                semanticHints: currentSemanticHints,
+                attachmentPlacements: currentAttachmentPlacements,
                diagnostics: diagnostics(
                    reason: .attachmentBoundary,
                    range: adjustedRange,
                    attachmentRanges: currentAttachmentRanges,
-                    blockRange: currentBlockRange
+                    blockRange: currentBlockRange,
+                    blockKinds: currentBlockKinds,
+                    semanticHints: currentSemanticHints,
+                    attachmentPlacements: currentAttachmentPlacements
                )
            )
        }
@@ -124,11 +175,17 @@ struct RDEPUBTextLayouter {
                blockRange: currentBlockRange,
                attachmentRanges: currentAttachmentRanges,
                attachmentKinds: currentAttachmentKinds,
+                blockKinds: currentBlockKinds,
+                semanticHints: currentSemanticHints,
+                attachmentPlacements: currentAttachmentPlacements,
                diagnostics: diagnostics(
                    reason: .blockBoundary,
                    range: adjustedRange,
                    attachmentRanges: currentAttachmentRanges,
-                    blockRange: currentBlockRange
+                    blockRange: currentBlockRange,
+                    blockKinds: currentBlockKinds,
+                    semanticHints: currentSemanticHints,
+                    attachmentPlacements: currentAttachmentPlacements
                )
            )
        }
@@ -139,15 +196,62 @@ struct RDEPUBTextLayouter {
            blockRange: currentBlockRange,
            attachmentRanges: currentAttachmentRanges,
            attachmentKinds: currentAttachmentKinds,
+            blockKinds: currentBlockKinds,
+            semanticHints: currentSemanticHints,
+            attachmentPlacements: currentAttachmentPlacements,
            diagnostics: diagnostics(
                reason: .frameLimit,
                range: proposedRange,
                attachmentRanges: currentAttachmentRanges,
-                blockRange: currentBlockRange
+                blockRange: currentBlockRange,
+                blockKinds: currentBlockKinds,
+                semanticHints: currentSemanticHints,
+                attachmentPlacements: currentAttachmentPlacements
            )
        )
    }

+    private func preferredSemanticBoundary(
+        in range: NSRange,
+        minimumEnd: Int
+    ) -> (location: Int, trigger: String)? {
+        var boundary: (location: Int, trigger: String)?
+        attributedString.enumerateAttribute(.rdPageSemanticHints, in: range) { value, attributeRange, stop in
+            guard let rawValue = value as? String else { return }
+            let hints = rawValue
+                .split(separator: ",")
+                .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
+            guard !hints.isEmpty else { return }
+
+            if hints.contains(.pageBreakBefore),
+               attributeRange.location > range.location,
+               attributeRange.location >= minimumEnd {
+                boundary = (attributeRange.location, RDEPUBTextSemanticHint.pageBreakBefore.rawValue)
+                stop.pointee = true
+                return
+            }
+
+            let attributeEnd = attributeRange.location + attributeRange.length
+            if hints.contains(.pageBreakAfter),
+               attributeEnd > minimumEnd,
+               attributeEnd < range.location + range.length {
+                boundary = (attributeEnd, RDEPUBTextSemanticHint.pageBreakAfter.rawValue)
+                stop.pointee = true
+                return
+            }
+
+            if hints.contains(.avoidPageBreakInside),
+               attributeRange.location > range.location,
+               attributeRange.location < range.location + range.length,
+               attributeRange.location >= minimumEnd,
+               attributeEnd > range.location + range.length {
+                boundary = (attributeRange.location, RDEPUBTextSemanticHint.avoidPageBreakInside.rawValue)
+                stop.pointee = true
+            }
+        }
+        return boundary
+    }
+
    private func preferredAttachmentBoundary(in range: NSRange, minimumEnd: Int) -> Int? {
        var boundary: Int?
        attributedString.enumerateAttribute(.rdPageAttachmentKind, in: range) { value, attributeRange, stop in
@@ -216,6 +320,43 @@ struct RDEPUBTextLayouter {
        return kinds
    }

+    private func blockKinds(in range: NSRange) -> [RDEPUBTextBlockKind] {
+        var kinds: [RDEPUBTextBlockKind] = []
+        attributedString.enumerateAttribute(.rdPageBlockKind, in: range) { value, _, _ in
+            guard let rawValue = value as? String,
+                  let kind = RDEPUBTextBlockKind(rawValue: rawValue),
+                  !kinds.contains(kind) else {
+                return
+            }
+            kinds.append(kind)
+        }
+        return kinds
+    }
+
+    private func semanticHints(in range: NSRange) -> [RDEPUBTextSemanticHint] {
+        var hints: [RDEPUBTextSemanticHint] = []
+        attributedString.enumerateAttribute(.rdPageSemanticHints, in: range) { value, _, _ in
+            guard let rawValue = value as? String else { return }
+            for hint in rawValue.split(separator: ",").compactMap({ RDEPUBTextSemanticHint(rawValue: String($0)) }) where !hints.contains(hint) {
+                hints.append(hint)
+            }
+        }
+        return hints
+    }
+
+    private func attachmentPlacements(in range: NSRange) -> [RDEPUBTextAttachmentPlacement] {
+        var placements: [RDEPUBTextAttachmentPlacement] = []
+        attributedString.enumerateAttribute(.rdPageAttachmentPlacement, in: range) { value, _, _ in
+            guard let rawValue = value as? String,
+                  let placement = RDEPUBTextAttachmentPlacement(rawValue: rawValue),
+                  !placements.contains(placement) else {
+                return
+            }
+            placements.append(placement)
+        }
+        return placements
+    }
+
    private func nearestTrailingFragmentID(
        endingAt location: Int,
        fragmentOffsets: [String: Int]
@@ -230,7 +371,11 @@ struct RDEPUBTextLayouter {
        reason: RDEPUBTextPageBreakReason,
        range: NSRange,
        attachmentRanges: [NSRange],
-        blockRange: NSRange?
+        blockRange: NSRange?,
+        blockKinds: [RDEPUBTextBlockKind],
+        semanticHints: [RDEPUBTextSemanticHint],
+        attachmentPlacements: [RDEPUBTextAttachmentPlacement],
+        trigger: String? = nil
    ) -> [String] {
        var items = ["page break: \(reason.rawValue)", "page range: \(NSStringFromRange(range))"]
        if let blockRange {
@@ -239,6 +384,18 @@ struct RDEPUBTextLayouter {
        if !attachmentRanges.isEmpty {
            items.append("attachment ranges: \(attachmentRanges.map(NSStringFromRange).joined(separator: ","))")
        }
+        if !blockKinds.isEmpty {
+            items.append("block kinds: \(blockKinds.map(\.rawValue).joined(separator: ","))")
+        }
+        if !semanticHints.isEmpty {
+            items.append("semantic hints: \(semanticHints.map(\.rawValue).joined(separator: ","))")
+        }
+        if !attachmentPlacements.isEmpty {
+            items.append("attachment placements: \(attachmentPlacements.map(\.rawValue).joined(separator: ","))")
+        }
+        if let trigger, !trigger.isEmpty {
+            items.append("semantic trigger: \(trigger)")
+        }
        return items
    }
 }