pymdownx-mahjong 1.0.0__py3-none-any.whl

pymdownx_mahjong/renderer.py

@@ -0,0 +1,468 @@
+"""Renderer for Mahjong hands"""
+
+from __future__ import annotations
+
+import html
+import importlib.resources
+import re
+from pathlib import Path
+
+from .parser import Hand, Meld, MeldType, Tile
+from .tiles import TileInfo, get_special_tile
+
+# Pre-compiled regex patterns for SVG processing
+_RE_XML_DECL = re.compile(r"<\?xml[^?]*\?>")
+_RE_SODIPODI_SELF = re.compile(r"<sodipodi:namedview[^>]*/>")
+_RE_SODIPODI_FULL = re.compile(r"<sodipodi:namedview[^>]*>.*?</sodipodi:namedview>", re.DOTALL)
+_RE_METADATA = re.compile(r"<metadata[^>]*>.*?</metadata>", re.DOTALL)
+_RE_WIDTH = re.compile(r'width="[^"]*"')
+_RE_HEIGHT = re.compile(r'height="[^"]*"')
+# Pattern to find IDs in SVGs
+_RE_ID = re.compile(r'id="([^"]+)"')
+
+
+class MahjongRenderer:
+    """Renders mahjong hands as HTML with inline SVG tiles.
+
+    Configuration options:
+        theme: 'light', 'dark', or 'auto'
+        css_class: CSS class for the container
+        show_labels: Whether to show tile names as titles
+        inline_svg: Whether to inline SVG or use img tags
+    """
+
+    DEFAULT_TILE_WIDTH = 45
+    DEFAULT_TILE_HEIGHT = 60
+    DEFAULT_TILE_GAP = 2
+    DEFAULT_MELD_GAP = 12
+
+    def __init__(
+        self,
+        theme: str = "light",
+        css_class: str = "mahjong-hand",
+        show_labels: bool = True,
+        inline_svg: bool = True,
+        assets_path: str | Path | None = None,
+    ) -> None:
+        """Initialize the renderer.
+
+        Args:
+            theme: Color theme ('light', 'dark', or 'auto')
+            css_class: CSS class for the container element
+            show_labels: Show tile names as title attributes
+            inline_svg: Inline SVG content vs img tags
+            assets_path: Custom path to SVG assets
+        """
+        self.theme = theme
+        self.tile_width = self.DEFAULT_TILE_WIDTH
+        self.tile_height = self.DEFAULT_TILE_HEIGHT
+        self.tile_gap = self.DEFAULT_TILE_GAP
+        self.meld_gap = self.DEFAULT_MELD_GAP
+        self.css_class = css_class
+        self.show_labels = show_labels
+        self.inline_svg = inline_svg
+        self.assets_path = Path(assets_path) if assets_path else None
+        self._svg_cache: dict[tuple[str, str], str] = {}
+        self._svg_id_counter = 0
+
+    def render(
+        self,
+        hand: Hand,
+        title: str | None = None,
+        notation: str | None = None,
+    ) -> str:
+        """Render a hand as HTML.
+
+        Args:
+            hand: Parsed Hand object
+            title: Optional caption/title for the hand
+            notation: Original notation string for data attribute
+
+        Returns:
+            HTML string with rendered tiles
+        """
+        parts: list[str] = []
+
+        # Container opening
+        data_attr = f' data-notation="{self._escape_html(notation)}"' if notation else ""
+        parts.append(f'<figure class="{self.css_class}"{data_attr}>')
+
+        # Dora indicators section (above hand, left-aligned, on same line)
+        if hand.dora_indicators or hand.uradora_indicators:
+            parts.append('<div class="mahjong-dora-row">')
+
+            if hand.dora_indicators:
+                parts.append('<div class="mahjong-dora">')
+                parts.append('<span class="mahjong-dora-label">Dora:</span>')
+                parts.append('<span class="mahjong-dora-tiles">')
+                for tile in hand.dora_indicators:
+                    parts.append(self._render_tile(tile))
+                parts.append("</span>")
+                parts.append("</div>")
+
+            if hand.uradora_indicators:
+                parts.append('<div class="mahjong-dora mahjong-uradora">')
+                parts.append('<span class="mahjong-dora-label">Uradora:</span>')
+                parts.append('<span class="mahjong-dora-tiles">')
+                for tile in hand.uradora_indicators:
+                    parts.append(self._render_tile(tile))
+                parts.append("</span>")
+                parts.append("</div>")
+
+            parts.append("</div>")
+
+        parts.append('<div class="mahjong-hand-row">')
+
+        # Left section: closed tiles
+        parts.append('<div class="mahjong-hand-left">')
+        parts.append('<div class="mahjong-tiles">')
+
+        # Render all closed tiles
+        for tile in hand.closed_tiles:
+            parts.append(self._render_tile(tile))
+
+        parts.append("</div>")
+        parts.append("</div>")
+
+        # Draw tile section (only if explicitly specified)
+        if hand.draw_tile:
+            parts.append('<div class="mahjong-hand-draw">')
+            parts.append('<div class="mahjong-tiles">')
+            parts.append(self._render_tile(hand.draw_tile))
+            parts.append("</div>")
+            parts.append("</div>")
+
+        # Melds section (after draw tile)
+        if hand.melds:
+            parts.append('<div class="mahjong-hand-melds">')
+            parts.append('<div class="mahjong-tiles">')
+            for meld in hand.melds:
+                parts.append(self._render_meld(meld))
+            parts.append("</div>")
+            parts.append("</div>")
+
+        parts.append("</div>")
+
+        # Caption
+        if title:
+            parts.append(f'<figcaption class="mahjong-caption">{self._escape_html(title)}</figcaption>')
+
+        parts.append("</figure>")
+
+        return "".join(parts)
+
+    def render_tiles(self, tiles: list[Tile]) -> str:
+        """Render a simple list of tiles.
+
+        Args:
+            tiles: List of Tile objects
+
+        Returns:
+            HTML string with rendered tiles
+        """
+        parts = [f'<span class="{self.css_class}">']
+        for tile in tiles:
+            parts.append(self._render_tile(tile))
+        parts.append("</span>")
+        return "".join(parts)
+
+    def _render_tile(self, tile: Tile) -> str:
+        """Render a single tile.
+
+        Args:
+            tile: Tile to render
+
+        Returns:
+            HTML string for the tile
+        """
+        info = tile.info
+        if not info:
+            return f'<span class="mahjong-tile mahjong-tile-unknown" data-tile="{tile.notation}">?</span>'
+
+        classes = ["mahjong-tile"]
+        if tile.is_rotated:
+            classes.append("mahjong-tile-rotated")
+        if tile.is_added:
+            classes.append("mahjong-tile-added")
+
+        class_str = " ".join(classes)
+        title_attr = f' title="{info.display_name}"' if self.show_labels else ""
+
+        if self.inline_svg:
+            svg_content = self._get_themed_svg_content(info)
+            return f'<span class="{class_str}" data-tile="{tile.notation}"{title_attr}>{svg_content}</span>'
+        else:
+            asset_path = self._get_asset_url(info)
+            return (
+                f'<span class="{class_str}" data-tile="{tile.notation}"{title_attr}>'
+                f'<img src="{asset_path}" alt="{info.display_name}" '
+                f'width="{self.tile_width}" height="{self.tile_height}">'
+                f"</span>"
+            )
+
+    def _render_meld(self, meld: Meld) -> str:
+        """Render a meld (called tile group).
+
+        Args:
+            meld: Meld to render
+
+        Returns:
+            HTML string for the meld
+        """
+        classes = ["mahjong-meld"]
+
+        if meld.is_open:
+            classes.append("mahjong-meld-open")
+        else:
+            classes.append("mahjong-meld-closed")
+
+        class_str = " ".join(classes)
+        parts = [f'<span class="{class_str}">']
+
+        if meld.meld_type == MeldType.KAN_ADDED:
+            # Added kan (shouminkan): stacked pair position depends on source
+            # Find which tile (0, 1, or 2) is rotated to determine stack position
+            if meld.tiles[0].is_rotated:
+                # Stack on left: [stack], upright, upright
+                parts.append('<span class="mahjong-tile-stack">')
+                parts.append(self._render_tile(meld.tiles[0]))
+                parts.append(self._render_tile(meld.tiles[3]))
+                parts.append("</span>")
+                parts.append(self._render_tile(meld.tiles[1]))
+                parts.append(self._render_tile(meld.tiles[2]))
+            elif meld.tiles[2].is_rotated:
+                # Stack on right: upright, upright, [stack]
+                parts.append(self._render_tile(meld.tiles[0]))
+                parts.append(self._render_tile(meld.tiles[1]))
+                parts.append('<span class="mahjong-tile-stack">')
+                parts.append(self._render_tile(meld.tiles[2]))
+                parts.append(self._render_tile(meld.tiles[3]))
+                parts.append("</span>")
+            else:
+                # Stack in middle (default): upright, [stack], upright
+                parts.append(self._render_tile(meld.tiles[0]))
+                parts.append('<span class="mahjong-tile-stack">')
+                parts.append(self._render_tile(meld.tiles[1]))
+                parts.append(self._render_tile(meld.tiles[3]))
+                parts.append("</span>")
+                parts.append(self._render_tile(meld.tiles[2]))
+        else:
+            for i, tile in enumerate(meld.tiles):
+                # For closed kan, show back tiles for middle two
+                if meld.meld_type == MeldType.KAN_CLOSED and i in (1, 2):
+                    parts.append(self._render_back_tile())
+                else:
+                    parts.append(self._render_tile(tile))
+
+        parts.append("</span>")
+        return "".join(parts)
+
+    def _render_back_tile(self) -> str:
+        """Render a face-down tile.
+
+        Returns:
+            HTML string for a back tile
+        """
+        info = get_special_tile("back")
+        if not info:
+            return '<span class="mahjong-tile mahjong-tile-back">?</span>'
+
+        if self.inline_svg:
+            svg_content = self._get_themed_svg_content(info)
+            return f'<span class="mahjong-tile mahjong-tile-back">{svg_content}</span>'
+        else:
+            asset_path = self._get_asset_url(info)
+            return (
+                f'<span class="mahjong-tile mahjong-tile-back">'
+                f'<img src="{asset_path}" alt="Face Down" '
+                f'width="{self.tile_width}" height="{self.tile_height}">'
+                f"</span>"
+            )
+
+    def _get_svg_content(self, info: TileInfo, theme: str | None = None) -> str:
+        """Get the SVG content for a tile, with unique IDs.
+
+        Args:
+            info: Tile information
+            theme: Optional theme override ('light' or 'dark')
+
+        Returns:
+            SVG content string with unique IDs
+        """
+        theme = theme or (self.theme if self.theme != "auto" else "light")
+        cache_key = (theme, info.asset_name)
+
+        # Cache raw loaded SVG content (before ID uniquification)
+        if cache_key not in self._svg_cache:
+            svg_content = self._load_svg(info, theme)
+            # Process but don't add unique IDs yet - cache the base processed version
+            svg_content = self._process_svg(svg_content, unique_prefix=None)
+            self._svg_cache[cache_key] = svg_content
+
+        # Get cached SVG and make IDs unique for this instance
+        svg_content = self._svg_cache[cache_key]
+        self._svg_id_counter += 1
+        return self._make_ids_unique(svg_content, f"mj{self._svg_id_counter}_")
+
+    def _get_themed_svg_content(self, info: TileInfo) -> str:
+        """Get SVG content that respects theme switching.
+
+        For 'auto' theme, embeds both light and dark SVGs with CSS to toggle.
+        For specific themes, returns a single SVG.
+
+        Args:
+            info: Tile information
+
+        Returns:
+            SVG content string (possibly wrapped in theme-aware containers)
+        """
+        if self.theme == "auto":
+            # Load both light and dark SVGs
+            light_svg = self._get_svg_content(info, "light")
+            dark_svg = self._get_svg_content(info, "dark")
+
+            # Wrap each in a container with appropriate display logic
+            # CSS will handle the display switching based on theme
+            return (
+                f'<span class="mahjong-tile-light">{light_svg}</span><span class="mahjong-tile-dark">{dark_svg}</span>'
+            )
+        else:
+            # Single theme - return appropriate SVG
+            return self._get_svg_content(info)
+
+    def _load_svg(self, info: TileInfo, theme: str | None = None) -> str:
+        """Load SVG content from file.
+
+        Args:
+            info: Tile information
+            theme: Theme to load ('light' or 'dark')
+
+        Returns:
+            Raw SVG content
+        """
+        theme = theme or (self.theme if self.theme != "auto" else "light")
+
+        # Try custom assets path first
+        if self.assets_path:
+            svg_path = self.assets_path / theme / f"{info.asset_name}.svg"
+            if svg_path.exists():
+                return svg_path.read_text(encoding="utf-8")
+
+        # Fall back to package assets
+        try:
+            assets = importlib.resources.files("pymdownx_mahjong") / "assets" / theme
+            svg_file = assets / f"{info.asset_name}.svg"
+            return svg_file.read_text(encoding="utf-8")
+        except (FileNotFoundError, TypeError):
+            # Return a placeholder SVG
+            return self._placeholder_svg(info)
+
+    def _process_svg(self, svg_content: str, unique_prefix: str | None = None) -> str:
+        """Process SVG content for inline use.
+
+        - Removes XML declaration
+        - Removes unnecessary metadata
+        - Adds sizing attributes
+        - Makes IDs unique to avoid conflicts when multiple SVGs are on the same page
+
+        Args:
+            svg_content: Raw SVG content
+            unique_prefix: Optional prefix to make IDs unique
+
+        Returns:
+            Processed SVG content
+        """
+        # Remove XML declaration
+        svg_content = _RE_XML_DECL.sub("", svg_content)
+
+        # Remove Inkscape/Sodipodi metadata namespaces from content
+        svg_content = _RE_SODIPODI_SELF.sub("", svg_content)
+        svg_content = _RE_SODIPODI_FULL.sub("", svg_content)
+        svg_content = _RE_METADATA.sub("", svg_content)
+
+        # Update width/height to our tile size while preserving viewBox
+        svg_content = _RE_WIDTH.sub(f'width="{self.tile_width}"', svg_content, count=1)
+        svg_content = _RE_HEIGHT.sub(f'height="{self.tile_height}"', svg_content, count=1)
+
+        # Make IDs unique if prefix is provided
+        if unique_prefix:
+            svg_content = self._make_ids_unique(svg_content, unique_prefix)
+
+        return svg_content.strip()
+
+    def _make_ids_unique(self, svg_content: str, prefix: str) -> str:
+        """Make all IDs in an SVG unique by adding a prefix.
+
+        Args:
+            svg_content: SVG content
+            prefix: Prefix to add to all IDs
+
+        Returns:
+            SVG content with unique IDs
+        """
+        # Find all IDs in the SVG
+        ids = set(_RE_ID.findall(svg_content))
+
+        # Replace each ID and its references
+        for old_id in ids:
+            new_id = f"{prefix}{old_id}"
+            # Replace id="old_id"
+            svg_content = svg_content.replace(f'id="{old_id}"', f'id="{new_id}"')
+            # Replace href="#old_id" and xlink:href="#old_id"
+            svg_content = svg_content.replace(f'href="#{old_id}"', f'href="#{new_id}"')
+            # Replace url(#old_id)
+            svg_content = svg_content.replace(f"url(#{old_id})", f"url(#{new_id})")
+
+        return svg_content
+
+    def _placeholder_svg(self, info: TileInfo) -> str:
+        """Generate a placeholder SVG for missing assets.
+
+        Args:
+            info: Tile information
+
+        Returns:
+            Placeholder SVG content
+        """
+        w, h = self.tile_width, self.tile_height
+        return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{w}" height="{h}" viewBox="0 0 300 400">
+  <rect width="300" height="400" fill="#f0f0f0" stroke="#ccc" stroke-width="4" rx="20"/>
+  <text x="150" y="220" text-anchor="middle" font-size="48" fill="#999">{info.display_name}</text>
+</svg>"""
+
+    def _get_asset_url(self, info: TileInfo) -> str:
+        """Get the URL for a tile asset.
+
+        Args:
+            info: Tile information
+
+        Returns:
+            Asset URL string
+        """
+        theme = self.theme if self.theme != "auto" else "light"
+        return f"assets/{theme}/{info.asset_name}.svg"
+
+    def _escape_html(self, text: str) -> str:
+        """Escape HTML special characters.
+
+        Args:
+            text: Text to escape
+
+        Returns:
+            Escaped text
+        """
+        return html.escape(text, quote=True)
+
+
+def render_hand(hand: Hand, **kwargs) -> str:
+    """Convenience function to render a hand.
+
+    Args:
+        hand: Parsed Hand object
+        **kwargs: Renderer options
+
+    Returns:
+        HTML string
+    """
+    renderer = MahjongRenderer(**kwargs)
+    return renderer.render(hand)

pymdownx_mahjong/superfences.py

@@ -0,0 +1,126 @@
+"""Superfences integration for pymdownx-mahjong.
+
+Provides custom fence formatter and validator for use with pymdownx.superfences.
+"""
+
+from __future__ import annotations
+
+from html import escape
+from typing import Any
+
+from .parser import MahjongParser, ParseError
+from .renderer import MahjongRenderer
+from .utils import apply_hand_options, parse_block_content
+
+
+class _SuperfencesState:
+    """Encapsulates global state for superfences integration.
+
+    Uses lazy initialization to create parser/renderer on first use.
+    """
+
+    def __init__(self) -> None:
+        self._renderer: MahjongRenderer | None = None
+        self._parser: MahjongParser | None = None
+
+    @property
+    def renderer(self) -> MahjongRenderer:
+        """Get or create the renderer instance."""
+        if self._renderer is None:
+            self._renderer = MahjongRenderer(
+                theme="auto",
+                show_labels=True,
+                inline_svg=True,
+            )
+        return self._renderer
+
+    @property
+    def parser(self) -> MahjongParser:
+        """Get or create the parser instance."""
+        if self._parser is None:
+            self._parser = MahjongParser()
+        return self._parser
+
+
+# Single state instance
+_state = _SuperfencesState()
+
+
+def superfences_validator(
+    language: str,
+    inputs: dict[str, str],
+    options: dict[str, Any],
+    attrs: dict[str, Any],
+    md: Any,
+) -> bool:
+    """Validator for superfences custom fence.
+
+    Args:
+        language: The language specified (should be 'mahjong')
+        inputs: Input attributes from the fence
+        options: Options dict to populate
+        attrs: Attributes dict
+        md: Markdown instance
+
+    Returns:
+        True if this is a valid mahjong fence
+    """
+    return language == "mahjong"
+
+
+def superfences_formatter(
+    source: str,
+    language: str,
+    class_name: str,
+    options: dict[str, Any],
+    md: Any,
+    **kwargs: Any,
+) -> str:
+    """Formatter for superfences custom fence.
+
+    Args:
+        source: The content inside the fence
+        language: The language specified
+        class_name: CSS class name
+        options: Options from the fence
+        md: Markdown instance
+        **kwargs: Additional arguments
+
+    Returns:
+        Rendered HTML string
+    """
+    parser = _state.parser
+    renderer = _state.renderer
+
+    # Parse the content
+    content = source.strip()
+    notation, block_options = parse_block_content(content)
+
+    if not notation:
+        return _error_block("No hand notation provided")
+
+    try:
+        hand = parser.parse(notation)
+    except ParseError as e:
+        return _error_block(str(e))
+
+    apply_hand_options(hand, parser, block_options)
+
+    # Render the hand
+    return renderer.render(
+        hand,
+        title=block_options.get("title"),
+        notation=notation,
+    )
+
+
+def _error_block(message: str) -> str:
+    """Generate an error block.
+
+    Args:
+        message: Error message
+
+    Returns:
+        HTML error block
+    """
+    return f'<div class="mahjong-error"><strong>Mahjong Error:</strong> {escape(message)}</div>'

pymdownx_mahjong/tiles.py

@@ -0,0 +1,85 @@
+"""Tile database and asset mapping for Riichi Mahjong tiles."""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class TileInfo(NamedTuple):
+    """Information about a tile type."""
+
+    asset_name: str
+    display_name: str
+
+
+TILE_DATABASE: dict[tuple[str, int], TileInfo] = {
+    # Manzu
+    ("m", 1): TileInfo("1m", "1 Man"),
+    ("m", 2): TileInfo("2m", "2 Man"),
+    ("m", 3): TileInfo("3m", "3 Man"),
+    ("m", 4): TileInfo("4m", "4 Man"),
+    ("m", 5): TileInfo("5m", "5 Man"),
+    ("m", 6): TileInfo("6m", "6 Man"),
+    ("m", 7): TileInfo("7m", "7 Man"),
+    ("m", 8): TileInfo("8m", "8 Man"),
+    ("m", 9): TileInfo("9m", "9 Man"),
+    ("m", 0): TileInfo("0m", "Red 5 Man"),
+    # Pinzu
+    ("p", 1): TileInfo("1p", "1 Pin"),
+    ("p", 2): TileInfo("2p", "2 Pin"),
+    ("p", 3): TileInfo("3p", "3 Pin"),
+    ("p", 4): TileInfo("4p", "4 Pin"),
+    ("p", 5): TileInfo("5p", "5 Pin"),
+    ("p", 6): TileInfo("6p", "6 Pin"),
+    ("p", 7): TileInfo("7p", "7 Pin"),
+    ("p", 8): TileInfo("8p", "8 Pin"),
+    ("p", 9): TileInfo("9p", "9 Pin"),
+    ("p", 0): TileInfo("0p", "Red 5 Pin"),
+    # Souzu
+    ("s", 1): TileInfo("1s", "1 Sou"),
+    ("s", 2): TileInfo("2s", "2 Sou"),
+    ("s", 3): TileInfo("3s", "3 Sou"),
+    ("s", 4): TileInfo("4s", "4 Sou"),
+    ("s", 5): TileInfo("5s", "5 Sou"),
+    ("s", 6): TileInfo("6s", "6 Sou"),
+    ("s", 7): TileInfo("7s", "7 Sou"),
+    ("s", 8): TileInfo("8s", "8 Sou"),
+    ("s", 9): TileInfo("9s", "9 Sou"),
+    ("s", 0): TileInfo("0s", "Red 5 Sou"),
+    # Winds
+    ("z", 1): TileInfo("1z", "East"),
+    ("z", 2): TileInfo("2z", "South"),
+    ("z", 3): TileInfo("3z", "West"),
+    ("z", 4): TileInfo("4z", "North"),
+    # Dragons
+    ("z", 5): TileInfo("5z", "White Dragon"),
+    ("z", 6): TileInfo("6z", "Green Dragon"),
+    ("z", 7): TileInfo("7z", "Red Dragon"),
+}
+
+SPECIAL_TILES: dict[str, TileInfo] = {
+    "back": TileInfo("back", "Face Down"),
+    "blank": TileInfo("blank", "Blank"),
+    "front": TileInfo("front", "Front"),
+}
+
+
+def get_tile_info(suit: str, number: int) -> TileInfo | None:
+    """Get tile information for a given suit and number."""
+    return TILE_DATABASE.get((suit, number))
+
+
+def get_special_tile(name: str) -> TileInfo | None:
+    """Get special tile information."""
+    return SPECIAL_TILES.get(name.lower())
+
+
+def is_valid_tile(suit: str, number: int) -> bool:
+    """Check if a tile notation is valid."""
+    if suit not in ("m", "p", "s", "z"):
+        return False
+
+    if suit == "z":
+        return 1 <= number <= 7
+    else:
+        return 0 <= number <= 9