classes.c41_rich_text

  1from typing import TYPE_CHECKING
  2from html.parser import HTMLParser
  3import markdown
  4import drawBot
  5
  6# Avoid circular import issues, hide from runtime, but keep for type checking
  7if TYPE_CHECKING:
  8    from datatypes import DParagraphProps
  9
 10
 11class KRichText:
 12    """Converts Markdown text to DrawBot FormattedString with configurable styles.
 13
 14    Maps Markdown elements (headings, paragraphs, blockquotes, horizontal rules) to
 15    DParagraphProps style definitions. Supports CSS class-based style overrides via
 16    Python-Markdown's attr_list extension.
 17
 18    Example:
 19        ```python
 20        from classes import KRichText
 21        from datatypes import DParagraphProps
 22
 23        styles = {
 24            "h1": DParagraphProps(fontSize=32, leading=1.1, paragraphTopSpacing=20),
 25            "p": DParagraphProps(fontSize=14, leading=1.4, paragraphTopSpacing=4),
 26            "p.big": DParagraphProps(fontSize=18, leading=1.3),  # Override for .big class
 27        }
 28
 29        richText = KRichText(styles)
 30
 31        markdown_content = '''
 32        # Heading
 33
 34        Normal paragraph.
 35
 36        Big paragraph.
 37        {: .big }
 38        '''
 39
 40        fs = richText.compose(markdown_content)
 41        drawBot.textBox(fs, (50, 50, 500, 700))
 42        ```
 43
 44    Supported Markdown elements:
 45        - `# h1`, `## h2`, `### h3` - Headings
 46        - Paragraphs (`<p>`)
 47        - `> blockquote`
 48        - `---` horizontal rule (rendered as vertical spacing)
 49
 50    Class-based overrides:
 51        Use `{: .classname }` after any block element to apply a class-specific style.
 52        Style dict key format: `"tag.classname"` (e.g., `"p.big"`, `"h2.subtitle"`)
 53    """
 54
 55    def __init__(self, styles: dict[str, "DParagraphProps"]):
 56        """Initialize with a mapping of HTML tags to paragraph style definitions.
 57
 58        Args:
 59            styles: Dictionary mapping tag names (optionally with .class suffix) to
 60                    DParagraphProps instances. Examples: "h1", "p", "p.big", "blockquote"
 61        """
 62        self.styles = styles
 63
 64    def compose(self, text: str) -> drawBot.FormattedString:
 65        """Convert Markdown text to a styled FormattedString.
 66
 67        Args:
 68            text: Markdown-formatted text string
 69
 70        Returns:
 71            DrawBot FormattedString with styles applied per element
 72        """
 73        # Convert Markdown to HTML with attr_list extension for class support
 74        html = markdown.markdown(text, extensions=["attr_list"])
 75
 76        # Create FormattedString and parse HTML into it
 77        fStr = drawBot.FormattedString()
 78        parser = self._Parser(self.styles, fStr)
 79        parser.feed(html)
 80
 81        return fStr
 82
 83    class _Parser(HTMLParser):
 84        """Internal HTML parser that populates a FormattedString with styled runs."""
 85
 86        def __init__(
 87            self,
 88            styles: dict[str, "DParagraphProps"],
 89            fStr: drawBot.FormattedString,
 90        ):
 91            super().__init__()
 92            self.styles = styles
 93            self.fStr = fStr
 94            self.current_tag = None
 95            self.current_class = None
 96
 97        def handle_starttag(self, tag: str, attrs: list[tuple[str, str]]):
 98            """Process opening tags and apply paragraph-level formatting."""
 99            self.current_tag = tag
100
101            # Extract class attribute for style lookup
102            attrs_dict = dict(attrs)
103            self.current_class = attrs_dict.get("class", None)
104
105            # Look up style: try "tag.class" first, fall back to "tag"
106            style = self._get_style(tag, self.current_class)
107
108            if not style:
109                return
110
111            # Handle <hr> as self-closing element (spacing only, no visible content)
112            if tag == "hr":
113                self.fStr.append("\n")
114                return
115
116            # Apply paragraph-level properties via FormattedString methods
117            # These affect the next append() call
118            self.fStr.paragraphTopSpacing(style.paragraphTopSpacing)
119            self.fStr.paragraphBottomSpacing(style.paragraphBottomSpacing)
120            self.fStr.indent(style.indent)
121            self.fStr.tailIndent(style.tailIndent)
122
123        def handle_data(self, data: str):
124            """Append text content with the current tag's style."""
125            if not data.strip():
126                return
127
128            style = self._get_style(self.current_tag, self.current_class)
129
130            if style:
131                self.fStr.append(data, **style.calc())
132            else:
133                # Unstyled fallback (should rarely happen)
134                self.fStr.append(data)
135
136        def handle_endtag(self, tag: str):
137            """Add line breaks after block elements."""
138            # Block elements need newlines to terminate paragraphs
139            block_elements = ("h1", "h2", "h3", "h4", "h5", "h6", "p", "blockquote")
140            if tag in block_elements:
141                self.fStr.append("\n")
142
143            self.current_tag = None
144            self.current_class = None
145
146        def _get_style(
147            self, tag: str, class_name: str = None
148        ) -> "DParagraphProps | None":
149            """Look up style with class fallback logic.
150
151            Priority: "tag.class" > "tag" > None
152            """
153            if tag is None:
154                return None
155
156            # Try class-specific style first
157            if class_name:
158                class_key = f"{tag}.{class_name}"
159                if class_key in self.styles:
160                    return self.styles[class_key]
161
162            # Fall back to base tag style
163            return self.styles.get(tag, None)