dataface 0.1.2__py3-none-any.whl

mdsvg/style.py

@@ -0,0 +1,355 @@
+"""Style configuration for SVG rendering."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any, Literal, Optional
+
+# Code block overflow options
+CodeBlockOverflow = Literal["wrap", "show", "hide", "ellipsis"]
+
+# Text alignment options
+TextAlign = Literal["left", "center", "right"]
+
+
+@dataclass(frozen=True)
+class Style:
+    """
+    Configuration for styling rendered SVG output.
+
+    All style properties are immutable. Use `with_updates()` to create
+    a modified copy of a style.
+
+    Attributes:
+        font_family: Primary font stack for body text.
+        mono_font_family: Font stack for code elements.
+        base_font_size: Base font size in pixels.
+        line_height: Line height multiplier.
+        text_color: Default text color (CSS color value).
+        heading_color: Color for headings (defaults to text_color if None).
+        link_color: Color for links.
+        link_underline: Whether to underline links.
+        code_color: Color for inline code text.
+        code_background: Background color for code elements.
+        blockquote_color: Color for blockquote text.
+        blockquote_border_color: Color for blockquote left border.
+        h1_scale: Font size multiplier for h1 (used when h1_size is None).
+        h2_scale: Font size multiplier for h2 (used when h2_size is None).
+        h3_scale: Font size multiplier for h3 (used when h3_size is None).
+        h4_scale: Font size multiplier for h4 (used when h4_size is None).
+        h5_scale: Font size multiplier for h5 (used when h5_size is None).
+        h6_scale: Font size multiplier for h6 (used when h6_size is None).
+        h1_size: Absolute h1 font size in px. Overrides h1_scale × base_font_size.
+        h2_size: Absolute h2 font size in px. Overrides h2_scale × base_font_size.
+        h3_size: Absolute h3 font size in px. Overrides h3_scale × base_font_size.
+        h4_size: Absolute h4 font size in px. Overrides h4_scale × base_font_size.
+        h5_size: Absolute h5 font size in px. Overrides h5_scale × base_font_size.
+        h6_size: Absolute h6 font size in px. Overrides h6_scale × base_font_size.
+        heading_font_weight: Font weight for headings.
+        heading_line_height: Line height multiplier for headings; falls back
+            to ``line_height`` when None. Headings typically want a tighter
+            multiplier than body text (~1.1-1.25 vs 1.5-1.6).
+        heading_margin_top: Top margin for headings (em units).
+        heading_margin_bottom: Bottom margin for headings (em units).
+        paragraph_spacing: Space between paragraphs in pixels.
+        list_indent: Indentation for list items in pixels.
+        list_item_spacing: Space between list items in pixels.
+        code_block_padding: Padding inside code blocks in pixels.
+        code_block_border_radius: Border radius for code blocks in pixels.
+        blockquote_padding: Left padding for blockquotes in pixels.
+        blockquote_border_width: Width of blockquote left border in pixels.
+        table_border_color: Color for table borders.
+        table_header_background: Background color for table headers.
+        table_cell_padding: Padding inside table cells in pixels.
+        hr_color: Color for horizontal rules.
+        hr_height: Height of horizontal rules in pixels.
+        image_width: Fixed image width in pixels (None = full container width).
+        image_height: Fixed image height in pixels (None = auto from aspect ratio).
+        image_fallback_aspect_ratio: Aspect ratio when dimensions unknown (default 16:9).
+        image_enforce_aspect_ratio: Skip fetching dimensions, always use fallback ratio.
+        image_preserve_aspect_ratio: SVG preserveAspectRatio attribute (default "xMidYMid meet").
+        char_width_ratio: Reference regular-text ratio used to normalize
+            bold/italic scaling.
+        bold_char_width_ratio: Character width ratio for bold text.
+        text_align: Horizontal text alignment ("left", "center", "right").
+    """
+
+    # Fonts
+    font_family: str = (
+        "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
+    )
+    mono_font_family: str = "ui-monospace, 'SF Mono', Menlo, Consolas, monospace"
+    base_font_size: float = 14.0
+    line_height: float = 1.5
+
+    # Colors
+    text_color: str = "#1a1a1a"
+    heading_color: Optional[str] = None  # Falls back to text_color
+    link_color: str = "#2563eb"
+    link_underline: bool = True
+    code_color: str = "#be185d"
+    code_background: str = "#f3f4f6"
+    blockquote_color: str = "#6b7280"
+    blockquote_border_color: str = "#d1d5db"
+
+    # Heading scales (multipliers of base_font_size)
+    h1_scale: float = 2.0
+    h2_scale: float = 1.6
+    h3_scale: float = 1.35
+    h4_scale: float = 1.15
+    h5_scale: float = 1.0
+    h6_scale: float = 0.9
+    # Absolute per-level sizes (px). When set, override the scale × base_font_size
+    # calculation. Lets a caller pin headings to an absolute type stack.
+    h1_size: Optional[float] = None
+    h2_size: Optional[float] = None
+    h3_size: Optional[float] = None
+    h4_size: Optional[float] = None
+    h5_size: Optional[float] = None
+    h6_size: Optional[float] = None
+    heading_font_weight: str | int = "bold"
+    # Optional tighter line-height multiplier for headings; None falls back to
+    # the body line_height. Body multipliers (1.5-1.6) read too loose between
+    # wrapped heading lines.
+    heading_line_height: Optional[float] = None
+    heading_margin_top: float = 1.5  # em
+    heading_margin_bottom: float = 0.5  # em
+
+    # Spacing
+    paragraph_spacing: float = 12.0
+    list_indent: float = 24.0
+    list_item_spacing: float = 4.0
+    code_block_padding: float = 12.0
+    code_block_border_radius: float = 4.0
+    code_block_overflow: CodeBlockOverflow = "wrap"  # wrap, show, hide, ellipsis
+    blockquote_padding: float = 16.0
+    blockquote_border_width: float = 3.0
+
+    # Table
+    table_border_color: str = "#e5e7eb"
+    table_header_background: str = "#f9fafb"
+    table_cell_padding: float = 8.0
+
+    # Horizontal rule
+    hr_color: str = "#e5e7eb"
+    hr_height: float = 1.0
+
+    # Images
+    image_width: Optional[float] = None  # None = full width (100% of container)
+    image_height: Optional[float] = (
+        None  # None = auto (based on fetched/fallback ratio)
+    )
+    image_fallback_aspect_ratio: float = (
+        16 / 9
+    )  # Used when dimensions can't be detected
+    image_enforce_aspect_ratio: bool = False  # Skip fetching, always use fallback ratio
+    image_preserve_aspect_ratio: str = "xMidYMid meet"  # SVG preserveAspectRatio attr
+
+    # Text measurement
+    char_width_ratio: float = 0.48  # Reference ratio for bold/italic scaling
+    bold_char_width_ratio: float = 0.58  # Wider for bold (~20% wider than regular)
+    italic_char_width_ratio: float = 0.52  # Wider for italic (~8% wider than regular)
+    # Text alignment
+    text_align: TextAlign = "left"  # Horizontal alignment: "left", "center", "right"
+
+    def with_updates(self, **kwargs: Any) -> Style:
+        """
+        Create a new Style with updated values.
+
+        Args:
+            **kwargs: Style properties to update.
+
+        Returns:
+            A new Style instance with the specified updates.
+
+        Example:
+            >>> style = Style()
+            >>> dark_style = style.with_updates(
+            ...     text_color="#ffffff",
+            ...     code_background="#1f2937"
+            ... )
+        """
+        return replace(self, **kwargs)
+
+    def get_heading_scale(self, level: int) -> float:
+        """
+        Get the font size scale for a heading level.
+
+        Args:
+            level: Heading level (1-6).
+
+        Returns:
+            The font size multiplier for that heading level.
+        """
+        scales = {
+            1: self.h1_scale,
+            2: self.h2_scale,
+            3: self.h3_scale,
+            4: self.h4_scale,
+            5: self.h5_scale,
+            6: self.h6_scale,
+        }
+        return scales.get(level, 1.0)
+
+    def get_heading_size(self, level: int) -> float:
+        """
+        Get the absolute font size in pixels for a heading level.
+
+        If the corresponding ``h*_size`` field is set, return it directly.
+        Otherwise fall back to ``base_font_size × get_heading_scale(level)``.
+
+        Args:
+            level: Heading level (1-6).
+
+        Returns:
+            Font size in pixels for that heading level.
+        """
+        sizes = {
+            1: self.h1_size,
+            2: self.h2_size,
+            3: self.h3_size,
+            4: self.h4_size,
+            5: self.h5_size,
+            6: self.h6_size,
+        }
+        absolute = sizes.get(level)
+        if absolute is not None:
+            return absolute
+        return self.base_font_size * self.get_heading_scale(level)
+
+    def get_heading_color(self) -> str:
+        """Get the color for headings, falling back to text_color."""
+        return self.heading_color or self.text_color
+
+    def get_text_anchor(self) -> str:
+        """Get the SVG text-anchor value corresponding to text_align."""
+        anchor_map = {
+            "left": "start",
+            "center": "middle",
+            "right": "end",
+        }
+        return anchor_map.get(self.text_align, "start")
+
+
+# Pre-built themes
+LIGHT_THEME = Style()
+
+DARK_THEME = Style(
+    text_color="#e5e7eb",
+    heading_color="#f9fafb",
+    link_color="#60a5fa",
+    code_color="#f472b6",
+    code_background="#374151",
+    blockquote_color="#9ca3af",
+    blockquote_border_color="#4b5563",
+    table_border_color="#4b5563",
+    table_header_background="#374151",
+    hr_color="#4b5563",
+)
+
+GITHUB_THEME = Style(
+    font_family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif",
+    mono_font_family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace",
+    base_font_size=16.0,
+    text_color="#1f2328",
+    heading_color="#1f2328",
+    link_color="#0969da",
+    code_color="#1f2328",
+    code_background="#f6f8fa",
+    blockquote_color="#59636e",
+    blockquote_border_color="#d1d9e0",
+)
+
+
+# Style presets for different use cases
+# These control spacing/margins rather than colors/fonts
+
+
+class StylePresets:
+    """
+    Pre-configured style presets optimized for different rendering contexts.
+
+    Presets adjust spacing and margins while preserving color and font settings.
+    Combine with themes for full customization:
+
+        >>> from mdsvg import render, COMPACT_PRESET, DARK_THEME
+        >>> style = COMPACT_PRESET.with_updates(**vars(DARK_THEME))
+
+    Or use the merge_styles helper:
+
+        >>> from mdsvg import merge_styles, COMPACT_PRESET, DARK_THEME
+        >>> style = merge_styles(COMPACT_PRESET, DARK_THEME)
+    """
+
+    # Document preset: generous whitespace for long-form reading (original defaults)
+    DOCUMENT = Style(
+        heading_margin_top=1.5,  # 1.5em above headings
+        heading_margin_bottom=0.5,  # 0.5em below headings
+        paragraph_spacing=12.0,  # 12px between paragraphs
+        list_item_spacing=4.0,  # 4px between list items
+    )
+
+    # Compact preset: tighter spacing for dashboards, cards, and UI components
+    COMPACT = Style(
+        heading_margin_top=0.3,  # Reduced from 1.5em
+        heading_margin_bottom=0.3,  # Reduced from 0.5em
+        paragraph_spacing=8.0,  # Reduced from 12px
+        list_item_spacing=3.0,  # Slightly tighter list spacing
+    )
+
+    # Minimal preset: very tight spacing for tooltips and constrained spaces
+    MINIMAL = Style(
+        heading_margin_top=0.1,  # Minimal top margin
+        heading_margin_bottom=0.1,  # Minimal bottom margin
+        paragraph_spacing=4.0,  # Tight paragraph spacing
+        list_item_spacing=2.0,  # Tight list spacing
+    )
+
+
+# Export presets as top-level constants for easy access
+DOCUMENT_PRESET = StylePresets.DOCUMENT
+COMPACT_PRESET = StylePresets.COMPACT
+MINIMAL_PRESET = StylePresets.MINIMAL
+
+
+def merge_styles(*styles: Style) -> Style:
+    """
+    Merge multiple Style objects, with later styles overriding earlier ones.
+
+    This is useful for combining presets (spacing) with themes (colors):
+
+        >>> from mdsvg import merge_styles, COMPACT_PRESET, DARK_THEME
+        >>> style = merge_styles(COMPACT_PRESET, DARK_THEME)
+
+    Only non-default values from each style are applied:
+
+        >>> base = Style(text_color="red")
+        >>> overlay = Style(link_color="blue")
+        >>> merged = merge_styles(base, overlay)
+        >>> merged.text_color
+        'red'
+        >>> merged.link_color
+        'blue'
+
+    Args:
+        *styles: Style objects to merge, in order of priority (later wins).
+
+    Returns:
+        A new Style with merged values.
+    """
+    if not styles:
+        return Style()
+
+    # Start with default style
+    default = Style()
+    result_kwargs: dict[str, Any] = {}
+
+    for style in styles:
+        # Get all fields that differ from default
+        for field_name in style.__dataclass_fields__:
+            style_value = getattr(style, field_name)
+            default_value = getattr(default, field_name)
+            if style_value != default_value:
+                result_kwargs[field_name] = style_value
+
+    return Style(**result_kwargs)

mdsvg/types.py

@@ -0,0 +1,200 @@
+"""AST node types for representing parsed Markdown."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional, Union
+
+
+class SpanType(Enum):
+    """Types of inline text spans."""
+
+    TEXT = "text"
+    BOLD = "bold"
+    ITALIC = "italic"
+    BOLD_ITALIC = "bold_italic"
+    CODE = "code"
+    LINK = "link"
+    IMAGE = "image"
+
+
+@dataclass(frozen=True)
+class Span:
+    """An inline text span with styling."""
+
+    text: str
+    span_type: SpanType = SpanType.TEXT
+    url: Optional[str] = None
+    title: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """Validate span configuration."""
+        if self.span_type == SpanType.LINK and not self.url:
+            raise ValueError("Link spans must have a URL")
+        if self.span_type == SpanType.IMAGE and not self.url:
+            raise ValueError("Image spans must have a URL")
+
+
+class BlockType(Enum):
+    """Types of block-level elements."""
+
+    PARAGRAPH = "paragraph"
+    HEADING = "heading"
+    CODE_BLOCK = "code_block"
+    BLOCKQUOTE = "blockquote"
+    UNORDERED_LIST = "unordered_list"
+    ORDERED_LIST = "ordered_list"
+    LIST_ITEM = "list_item"
+    HORIZONTAL_RULE = "horizontal_rule"
+    TABLE = "table"
+    IMAGE = "image"
+    HTML_BLOCK = "html_block"
+
+
+@dataclass(frozen=True)
+class Block:
+    """Base class for block-level elements."""
+
+    block_type: BlockType
+
+
+@dataclass(frozen=True)
+class Paragraph(Block):
+    """A paragraph containing inline spans."""
+
+    spans: tuple[Span, ...] = field(default_factory=tuple)
+    block_type: BlockType = field(default=BlockType.PARAGRAPH, init=False)
+
+
+@dataclass(frozen=True)
+class Heading(Block):
+    """A heading (h1-h6)."""
+
+    level: int
+    spans: tuple[Span, ...] = field(default_factory=tuple)
+    block_type: BlockType = field(default=BlockType.HEADING, init=False)
+
+    def __post_init__(self) -> None:
+        """Validate heading level."""
+        if not 1 <= self.level <= 6:
+            raise ValueError(f"Heading level must be 1-6, got {self.level}")
+
+
+@dataclass(frozen=True)
+class CodeBlock(Block):
+    """A fenced or indented code block."""
+
+    code: str
+    language: Optional[str] = None
+    block_type: BlockType = field(default=BlockType.CODE_BLOCK, init=False)
+
+
+@dataclass(frozen=True)
+class Blockquote(Block):
+    """A blockquote containing other blocks."""
+
+    blocks: tuple[Block, ...] = field(default_factory=tuple)
+    block_type: BlockType = field(default=BlockType.BLOCKQUOTE, init=False)
+
+
+@dataclass(frozen=True)
+class ListItem(Block):
+    """A single item in a list."""
+
+    spans: tuple[Span, ...] = field(default_factory=tuple)
+    block_type: BlockType = field(default=BlockType.LIST_ITEM, init=False)
+
+
+@dataclass(frozen=True)
+class UnorderedList(Block):
+    """An unordered (bullet) list."""
+
+    items: tuple[ListItem, ...] = field(default_factory=tuple)
+    block_type: BlockType = field(default=BlockType.UNORDERED_LIST, init=False)
+
+
+@dataclass(frozen=True)
+class OrderedList(Block):
+    """An ordered (numbered) list."""
+
+    items: tuple[ListItem, ...] = field(default_factory=tuple)
+    start: int = 1
+    block_type: BlockType = field(default=BlockType.ORDERED_LIST, init=False)
+
+
+@dataclass(frozen=True)
+class HorizontalRule(Block):
+    """A horizontal rule/divider."""
+
+    block_type: BlockType = field(default=BlockType.HORIZONTAL_RULE, init=False)
+
+
+@dataclass(frozen=True)
+class TableCell:
+    """A single cell in a table."""
+
+    spans: tuple[Span, ...] = field(default_factory=tuple)
+    align: Optional[str] = None  # "left", "center", "right"
+
+
+@dataclass(frozen=True)
+class TableRow:
+    """A row in a table."""
+
+    cells: tuple[TableCell, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class Table(Block):
+    """A table with header and body rows."""
+
+    header: TableRow
+    rows: tuple[TableRow, ...] = field(default_factory=tuple)
+    block_type: BlockType = field(default=BlockType.TABLE, init=False)
+
+
+@dataclass(frozen=True)
+class ImageBlock(Block):
+    """A standalone image block.
+
+    Attributes:
+        url: The image URL (may be relative or absolute).
+        alt: Alt text for accessibility.
+        title: Optional title attribute.
+        width: Explicit width in pixels (from markdown {width=X} syntax).
+        height: Explicit height in pixels (from markdown {height=Y} syntax).
+    """
+
+    url: str
+    alt: str = ""
+    title: Optional[str] = None
+    width: Optional[float] = None
+    height: Optional[float] = None
+    block_type: BlockType = field(default=BlockType.IMAGE, init=False)
+
+
+@dataclass(frozen=True)
+class RawHtmlBlock(Block):
+    """A raw HTML block to be rendered via foreignObject when enabled."""
+
+    html: str
+    block_type: BlockType = field(default=BlockType.HTML_BLOCK, init=False)
+
+
+# Type alias for any block
+AnyBlock = Union[
+    Paragraph,
+    Heading,
+    CodeBlock,
+    Blockquote,
+    UnorderedList,
+    OrderedList,
+    HorizontalRule,
+    Table,
+    ImageBlock,
+    RawHtmlBlock,
+]
+
+# Type alias for list of blocks (the AST)
+Document = List[AnyBlock]

mdsvg/utils.py

@@ -0,0 +1,86 @@
+"""Utility functions for markdown-svg."""
+
+from __future__ import annotations
+
+import html
+import re
+from typing import List
+
+
+def escape_xml(text: str) -> str:
+    """
+    Escape text for safe inclusion in XML/SVG.
+
+    Args:
+        text: Raw text string.
+
+    Returns:
+        XML-escaped string.
+    """
+    return html.escape(text, quote=True)
+
+
+def escape_svg_text(text: str) -> str:
+    """
+    Escape text for inclusion in SVG text elements.
+
+    This handles special characters that could break SVG rendering.
+
+    Args:
+        text: Raw text string.
+
+    Returns:
+        Escaped string safe for SVG.
+    """
+    # Escape XML entities
+    result = escape_xml(text)
+    # Preserve single spaces but collapse multiple spaces
+    result = re.sub(r"  +", " ", result)
+    return result
+
+
+def normalize_whitespace(text: str) -> str:
+    """
+    Normalize whitespace in text (collapse multiple spaces, strip edges).
+
+    Args:
+        text: Text with potentially irregular whitespace.
+
+    Returns:
+        Normalized text.
+    """
+    return " ".join(text.split())
+
+
+def split_lines(text: str) -> List[str]:
+    """
+    Split text into lines, handling different line endings.
+
+    Args:
+        text: Text with line breaks.
+
+    Returns:
+        List of lines (without line ending characters).
+    """
+    return text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+
+
+def format_number(n: float, precision: int = 2) -> str:
+    """
+    Format a number for SVG attribute output.
+
+    Removes unnecessary trailing zeros and decimal points.
+
+    Args:
+        n: Number to format.
+        precision: Decimal precision.
+
+    Returns:
+        Formatted number string.
+    """
+    if n == int(n):
+        return str(int(n))
+    formatted = f"{n:.{precision}f}"
+    # Remove trailing zeros
+    formatted = formatted.rstrip("0").rstrip(".")
+    return formatted