@heylemon/lemonade 0.1.6 → 0.1.7

package/skills/docx/scripts/create_doc.py

@@ -2,34 +2,79 @@
 """
 Pro Docs — Document Creation Engine
 Takes a JSON document spec and produces a professionally formatted .docx file.
+
+Usage:
+    python create_doc.py spec.json output.docx [--template report|memo|proposal|letter|brief]
+
+The JSON spec format:
+{
+    "title": "Document Title",
+    "subtitle": "Optional subtitle",
+    "author": "Author Name",
+    "date": "auto",  // or "January 2026"
+    "template": "report",  // report, memo, proposal, letter, brief
+    "include_toc": true,
+    "include_page_numbers": true,
+    "header_text": "Company Name",
+    "footer_text": "",
+    "brand": {
+        "primary_color": "1B3A5C",
+        "accent_color": "2E86AB",
+        "font_heading": "Arial",
+        "font_body": "Arial"
+    },
+    "sections": [
+        {
+            "heading": "Section Title",
+            "level": 1,
+            "content": "Paragraph text...",
+            "items": ["bullet 1", "bullet 2"],  // optional bullet list
+            "numbered": false,  // true for numbered list
+            "table": {  // optional
+                "headers": ["Col A", "Col B"],
+                "rows": [["val1", "val2"], ["val3", "val4"]]
+            },
+            "callout": "Important note text",  // optional highlighted box
+            "page_break_before": false
+        }
+    ]
+}
 """
 
 import json
 import sys
+import os
 from datetime import datetime
 
 try:
     from docx import Document
-    from docx.shared import Inches, Pt, RGBColor
+    from docx.shared import Inches, Pt, Cm, RGBColor, Emu
     from docx.enum.text import WD_ALIGN_PARAGRAPH
     from docx.enum.table import WD_TABLE_ALIGNMENT
-    from docx.oxml.ns import nsdecls
+    from docx.enum.section import WD_ORIENT
+    from docx.oxml.ns import qn, nsdecls
     from docx.oxml import parse_xml
 except ImportError:
     print("ERROR: python-docx not installed. Run: pip install python-docx --break-system-packages")
     sys.exit(1)
 
 
+# ═══════════════════════════════════════════
+# DEFAULT BRAND — Professional, clean, modern
+# ═══════════════════════════════════════════
 DEFAULT_BRAND = {
-    "primary_color": "1B3A5C",
-    "accent_color": "2E86AB",
-    "light_accent": "E8F4F8",
-    "text_color": "2C3E50",
-    "muted_color": "7F8C8D",
+    "primary_color": "1B3A5C",     # Dark navy
+    "accent_color": "2E86AB",      # Teal blue
+    "light_accent": "E8F4F8",      # Light teal bg
+    "text_color": "2C3E50",        # Near-black
+    "muted_color": "7F8C8D",       # Gray for secondary text
     "font_heading": "Arial",
     "font_body": "Arial",
 }
 
+# ═══════════════════════════════════════════
+# TYPOGRAPHY SCALE — Consistent sizing
+# ═══════════════════════════════════════════
 SIZES = {
     "title": Pt(26),
     "subtitle": Pt(14),
@@ -38,50 +83,83 @@ SIZES = {
     "h3": Pt(12),
     "body": Pt(11),
     "small": Pt(9),
+    "caption": Pt(8),
+}
+
+SPACING = {
+    "after_title": Pt(6),
+    "before_h1": Pt(24),
+    "after_h1": Pt(8),
+    "before_h2": Pt(18),
+    "after_h2": Pt(6),
+    "before_h3": Pt(12),
+    "after_h3": Pt(4),
+    "after_paragraph": Pt(8),
+    "line_spacing": Pt(16),  # ~1.3x for 11pt body
 }
 
 
-def hex_to_rgb(hex_color: str) -> RGBColor:
-    h = hex_color.lstrip("#")
+def hex_to_rgb(hex_color):
+    """Convert hex string to RGBColor."""
+    h = hex_color.lstrip('#')
     return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
 
 
-def set_cell_shading(cell, color_hex: str) -> None:
+def set_cell_shading(cell, color_hex):
+    """Set table cell background color."""
     shading = parse_xml(f'<w:shd {nsdecls("w")} w:fill="{color_hex}" w:val="clear"/>')
     cell._tc.get_or_add_tcPr().append(shading)
 
 
-def set_cell_border(cell, color="D5D8DC") -> None:
+def set_cell_border(cell, color="D5D8DC"):
+    """Set thin borders on a table cell."""
     tc = cell._tc
-    tc_pr = tc.get_or_add_tcPr()
+    tcPr = tc.get_or_add_tcPr()
     borders = parse_xml(
         f'<w:tcBorders {nsdecls("w")}>'
         f'  <w:top w:val="single" w:sz="4" w:space="0" w:color="{color}"/>'
         f'  <w:left w:val="single" w:sz="4" w:space="0" w:color="{color}"/>'
         f'  <w:bottom w:val="single" w:sz="4" w:space="0" w:color="{color}"/>'
         f'  <w:right w:val="single" w:sz="4" w:space="0" w:color="{color}"/>'
-        f"</w:tcBorders>"
+        f'</w:tcBorders>'
     )
-    tc_pr.append(borders)
+    tcPr.append(borders)
 
 
 class ProDocBuilder:
+    """Builds professional documents from a JSON spec."""
+
     def __init__(self, spec):
         self.spec = spec
         self.brand = {**DEFAULT_BRAND, **spec.get("brand", {})}
         self.doc = Document()
+        self.template = spec.get("template", "report")
         self._setup_styles()
         self._setup_page()
 
     def _setup_page(self):
+        """Configure page size, margins, headers, footers."""
         section = self.doc.sections[0]
+        # US Letter
         section.page_width = Inches(8.5)
         section.page_height = Inches(11)
+        # Professional margins: 1 inch sides, 0.8 top/bottom
         section.top_margin = Inches(0.8)
         section.bottom_margin = Inches(0.8)
         section.left_margin = Inches(1)
         section.right_margin = Inches(1)
 
+        # Header
+        header_text = self.spec.get("header_text", "")
+        if header_text:
+            header = section.header
+            hp = header.paragraphs[0]
+            hp.text = header_text
+            hp.style.font.size = SIZES["small"]
+            hp.style.font.color.rgb = hex_to_rgb(self.brand["muted_color"])
+            hp.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+
+        # Footer with page numbers
         if self.spec.get("include_page_numbers", True):
             footer = section.footer
             fp = footer.paragraphs[0]
@@ -89,22 +167,36 @@ class ProDocBuilder:
             run = fp.add_run()
             run.font.size = SIZES["small"]
             run.font.color.rgb = hex_to_rgb(self.brand["muted_color"])
-            fld_char1 = parse_xml(f'<w:fldChar {nsdecls("w")} w:fldCharType="begin"/>')
-            run._r.append(fld_char1)
-            instr = parse_xml(
-                f'<w:instrText {nsdecls("w")} xml:space="preserve"> PAGE </w:instrText>'
-            )
-            run._r.append(instr)
-            fld_char2 = parse_xml(f'<w:fldChar {nsdecls("w")} w:fldCharType="end"/>')
-            run._r.append(fld_char2)
+            # Add page number field
+            fldChar1 = parse_xml(f'<w:fldChar {nsdecls("w")} w:fldCharType="begin"/>')
+            run._r.append(fldChar1)
+            instrText = parse_xml(f'<w:instrText {nsdecls("w")} xml:space="preserve"> PAGE </w:instrText>')
+            run._r.append(instrText)
+            fldChar2 = parse_xml(f'<w:fldChar {nsdecls("w")} w:fldCharType="end"/>')
+            run._r.append(fldChar2)
+
+        footer_text = self.spec.get("footer_text", "")
+        if footer_text:
+            footer = section.footer
+            if footer.paragraphs:
+                fp = footer.paragraphs[0]
+                # Add footer text before page number
+                run = fp.runs[0] if fp.runs else fp.add_run()
+                fp.insert_paragraph_before(footer_text).alignment = WD_ALIGN_PARAGRAPH.CENTER
 
     def _setup_styles(self):
-        style = self.doc.styles["Normal"]
-        style.font.name = self.brand["font_body"]
-        style.font.size = SIZES["body"]
-        style.font.color.rgb = hex_to_rgb(self.brand["text_color"])
+        """Configure document-wide typography."""
+        style = self.doc.styles['Normal']
+        font = style.font
+        font.name = self.brand["font_body"]
+        font.size = SIZES["body"]
+        font.color.rgb = hex_to_rgb(self.brand["text_color"])
+        pf = style.paragraph_format
+        pf.space_after = SPACING["after_paragraph"]
+        pf.line_spacing = SPACING["line_spacing"]
 
     def _add_title_block(self):
+        """Add the title page / title block."""
         title = self.spec.get("title", "Untitled Document")
         subtitle = self.spec.get("subtitle", "")
         author = self.spec.get("author", "")
@@ -112,126 +204,264 @@ class ProDocBuilder:
         if date_str == "auto":
             date_str = datetime.now().strftime("%B %d, %Y")
 
+        # Title
         p = self.doc.add_paragraph()
         p.alignment = WD_ALIGN_PARAGRAPH.LEFT
+        p.paragraph_format.space_before = Pt(48)
+        p.paragraph_format.space_after = SPACING["after_title"]
         run = p.add_run(title)
         run.font.size = SIZES["title"]
         run.font.bold = True
         run.font.color.rgb = hex_to_rgb(self.brand["primary_color"])
         run.font.name = self.brand["font_heading"]
 
+        # Accent line under title
+        p2 = self.doc.add_paragraph()
+        p2.paragraph_format.space_before = Pt(0)
+        p2.paragraph_format.space_after = Pt(12)
+        # Add a colored horizontal rule via border
+        pPr = p2._p.get_or_add_pPr()
+        pBdr = parse_xml(
+            f'<w:pBdr {nsdecls("w")}>'
+            f'  <w:bottom w:val="single" w:sz="12" w:space="1" w:color="{self.brand["accent_color"]}"/>'
+            f'</w:pBdr>'
+        )
+        pPr.append(pBdr)
+
+        # Subtitle
         if subtitle:
-            p2 = self.doc.add_paragraph()
-            r2 = p2.add_run(subtitle)
-            r2.font.size = SIZES["subtitle"]
-            r2.font.color.rgb = hex_to_rgb(self.brand["muted_color"])
-            r2.font.name = self.brand["font_heading"]
+            p3 = self.doc.add_paragraph()
+            p3.paragraph_format.space_after = Pt(4)
+            run = p3.add_run(subtitle)
+            run.font.size = SIZES["subtitle"]
+            run.font.color.rgb = hex_to_rgb(self.brand["muted_color"])
+            run.font.name = self.brand["font_heading"]
 
+        # Author and date
         if author or date_str:
-            p3 = self.doc.add_paragraph()
-            r3 = p3.add_run(" · ".join([x for x in [author, date_str] if x]))
-            r3.font.size = SIZES["small"]
-            r3.font.color.rgb = hex_to_rgb(self.brand["muted_color"])
+            meta_parts = []
+            if author:
+                meta_parts.append(author)
+            if date_str:
+                meta_parts.append(date_str)
+            p4 = self.doc.add_paragraph()
+            p4.paragraph_format.space_after = Pt(24)
+            run = p4.add_run(" · ".join(meta_parts))
+            run.font.size = SIZES["small"]
+            run.font.color.rgb = hex_to_rgb(self.brand["muted_color"])
+
+    def _add_toc(self):
+        """Add a Table of Contents field."""
+        p = self.doc.add_paragraph()
+        p.paragraph_format.space_before = Pt(12)
+        run = p.add_run("Table of Contents")
+        run.font.size = SIZES["h2"]
+        run.bold = True
+        run.font.color.rgb = hex_to_rgb(self.brand["primary_color"])
+        run.font.name = self.brand["font_heading"]
+
+        # TOC field code
+        p2 = self.doc.add_paragraph()
+        run = p2.add_run()
+        fldChar1 = parse_xml(f'<w:fldChar {nsdecls("w")} w:fldCharType="begin"/>')
+        run._r.append(fldChar1)
+        instrText = parse_xml(
+            f'<w:instrText {nsdecls("w")} xml:space="preserve"> TOC \\o "1-3" \\h \\z \\u </w:instrText>'
+        )
+        run._r.append(instrText)
+        fldChar2 = parse_xml(f'<w:fldChar {nsdecls("w")} w:fldCharType="separate"/>')
+        run._r.append(fldChar2)
+        toc_run = p2.add_run("[Right-click → Update Field to populate]")
+        toc_run.font.color.rgb = hex_to_rgb(self.brand["muted_color"])
+        toc_run.font.size = SIZES["small"]
+        fldChar3 = parse_xml(f'<w:fldChar {nsdecls("w")} w:fldCharType="end"/>')
+        run2 = p2.add_run()
+        run2._r.append(fldChar3)
+
+        # Page break after TOC
+        self.doc.add_page_break()
 
     def _add_heading(self, text, level=1):
+        """Add a styled heading."""
         heading = self.doc.add_heading(text, level=level)
         for run in heading.runs:
             run.font.color.rgb = hex_to_rgb(self.brand["primary_color"])
             run.font.name = self.brand["font_heading"]
+            if level == 1:
+                run.font.size = SIZES["h1"]
+            elif level == 2:
+                run.font.size = SIZES["h2"]
+            elif level == 3:
+                run.font.size = SIZES["h3"]
+
+        pf = heading.paragraph_format
+        if level == 1:
+            pf.space_before = SPACING["before_h1"]
+            pf.space_after = SPACING["after_h1"]
+        elif level == 2:
+            pf.space_before = SPACING["before_h2"]
+            pf.space_after = SPACING["after_h2"]
+        else:
+            pf.space_before = SPACING["before_h3"]
+            pf.space_after = SPACING["after_h3"]
+
         return heading
 
     def _add_paragraph(self, text):
+        """Add a body paragraph."""
         p = self.doc.add_paragraph(text)
+        p.paragraph_format.space_after = SPACING["after_paragraph"]
+        p.paragraph_format.line_spacing = SPACING["line_spacing"]
         for run in p.runs:
             run.font.name = self.brand["font_body"]
             run.font.size = SIZES["body"]
             run.font.color.rgb = hex_to_rgb(self.brand["text_color"])
+        return p
 
     def _add_bullets(self, items, numbered=False):
-        style = "List Number" if numbered else "List Bullet"
+        """Add a bullet or numbered list."""
         for item in items:
+            style = 'List Number' if numbered else 'List Bullet'
             p = self.doc.add_paragraph(item, style=style)
+            p.paragraph_format.space_after = Pt(3)
+            p.paragraph_format.line_spacing = SPACING["line_spacing"]
             for run in p.runs:
                 run.font.name = self.brand["font_body"]
                 run.font.size = SIZES["body"]
 
     def _add_table(self, table_spec):
+        """Add a professionally formatted table."""
         headers = table_spec.get("headers", [])
         rows = table_spec.get("rows", [])
         if not headers and not rows:
             return
+
         num_cols = len(headers) if headers else len(rows[0])
         table = self.doc.add_table(rows=0, cols=num_cols)
         table.alignment = WD_TABLE_ALIGNMENT.CENTER
 
+        # Header row
         if headers:
             row = table.add_row()
-            for i, h in enumerate(headers):
+            for i, header_text in enumerate(headers):
                 cell = row.cells[i]
-                cell.text = str(h)
-                for p in cell.paragraphs:
-                    for run in p.runs:
+                cell.text = str(header_text)
+                # Style header
+                for paragraph in cell.paragraphs:
+                    paragraph.alignment = WD_ALIGN_PARAGRAPH.LEFT
+                    for run in paragraph.runs:
                         run.font.bold = True
+                        run.font.size = SIZES["body"]
                         run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)
                         run.font.name = self.brand["font_heading"]
                 set_cell_shading(cell, self.brand["primary_color"])
                 set_cell_border(cell, self.brand["primary_color"])
 
+        # Data rows
         for ri, row_data in enumerate(rows):
             row = table.add_row()
             for ci, cell_text in enumerate(row_data):
                 cell = row.cells[ci]
                 cell.text = str(cell_text)
+                for paragraph in cell.paragraphs:
+                    for run in paragraph.runs:
+                        run.font.size = SIZES["body"]
+                        run.font.name = self.brand["font_body"]
+                        run.font.color.rgb = hex_to_rgb(self.brand["text_color"])
+                # Alternating row shading
                 if ri % 2 == 0:
                     set_cell_shading(cell, self.brand.get("light_accent", "F8F9FA"))
                 set_cell_border(cell, "D5D8DC")
 
+        # Set column widths evenly
+        content_width = Inches(6.5)  # 8.5 - 2 margins
+        col_width = content_width // num_cols
+        for row in table.rows:
+            for cell in row.cells:
+                cell.width = col_width
+
     def _add_callout(self, text):
+        """Add a highlighted callout/note box."""
         p = self.doc.add_paragraph()
-        p_pr = p._p.get_or_add_pPr()
-        p_bdr = parse_xml(
+        p.paragraph_format.space_before = Pt(8)
+        p.paragraph_format.space_after = Pt(8)
+
+        # Left border + background shading
+        pPr = p._p.get_or_add_pPr()
+        # Left border accent
+        pBdr = parse_xml(
             f'<w:pBdr {nsdecls("w")}>'
             f'  <w:left w:val="single" w:sz="24" w:space="8" w:color="{self.brand["accent_color"]}"/>'
-            f"</w:pBdr>"
+            f'</w:pBdr>'
+        )
+        pPr.append(pBdr)
+        # Background shading
+        shd = parse_xml(
+            f'<w:shd {nsdecls("w")} w:fill="{self.brand.get("light_accent", "E8F4F8")}" w:val="clear"/>'
         )
-        p_pr.append(p_bdr)
+        pPr.append(shd)
+        # Indent to make it feel like a box
+        ind = parse_xml(f'<w:ind {nsdecls("w")} w:left="360" w:right="360"/>')
+        pPr.append(ind)
+
         run = p.add_run(text)
         run.font.size = SIZES["body"]
         run.font.name = self.brand["font_body"]
         run.font.color.rgb = hex_to_rgb(self.brand["text_color"])
 
     def _process_section(self, section):
+        """Process a single content section from the spec."""
+        # Page break
         if section.get("page_break_before", False):
             self.doc.add_page_break()
 
-        heading = section.get("heading", "")
-        if heading:
-            self._add_heading(heading, section.get("level", 1))
+        # Heading
+        heading_text = section.get("heading", "")
+        level = section.get("level", 1)
+        if heading_text:
+            self._add_heading(heading_text, level)
 
+        # Body content — handle both string and list of paragraphs
         content = section.get("content", "")
         if isinstance(content, list):
             for para in content:
                 self._add_paragraph(para)
         elif content:
-            for para in content.split("\n\n"):
+            # Split on double newlines for multiple paragraphs
+            paragraphs = content.split("\n\n")
+            for para in paragraphs:
                 self._add_paragraph(para.strip())
 
+        # Bullet or numbered list
         items = section.get("items", [])
         if items:
-            self._add_bullets(items, section.get("numbered", False))
+            numbered = section.get("numbered", False)
+            self._add_bullets(items, numbered)
 
+        # Table
         table_spec = section.get("table")
         if table_spec:
             self._add_table(table_spec)
 
+        # Callout
         callout = section.get("callout", "")
         if callout:
             self._add_callout(callout)
 
     def build(self, output_path):
+        """Build the complete document and save."""
+        # Title block
         self._add_title_block()
+
+        # Table of contents
+        if self.spec.get("include_toc", False):
+            self._add_toc()
+
+        # Sections
         for section in self.spec.get("sections", []):
             self._process_section(section)
+
+        # Save
         self.doc.save(output_path)
         return output_path
 
@@ -241,11 +471,18 @@ def main():
         print("Usage: python create_doc.py spec.json output.docx")
         sys.exit(1)
 
-    with open(sys.argv[1], "r", encoding="utf-8") as f:
+    spec_path = sys.argv[1]
+    output_path = sys.argv[2]
+
+    with open(spec_path, 'r') as f:
         spec = json.load(f)
+
     builder = ProDocBuilder(spec)
-    builder.build(sys.argv[2])
-    print(f"Document created: {sys.argv[2]}")
+    builder.build(output_path)
+    print(f"Document created: {output_path}")
+    print(f"  Title: {spec.get('title', 'Untitled')}")
+    print(f"  Template: {spec.get('template', 'report')}")
+    print(f"  Sections: {len(spec.get('sections', []))}")
 
 
 if __name__ == "__main__":