@heylemon/lemonade 0.1.6 → 0.1.8

package/skills/pptx/pptxgenjs.md

@@ -0,0 +1,666 @@
+# PptxGenJS API Tutorial
+
+PptxGenJS is a JavaScript library for generating PowerPoint presentations programmatically. This guide covers the most practical patterns for building professional slides.
+
+## Setup & Basic Structure
+
+Create a new presentation and configure it:
+
+```javascript
+const PptxGenJS = require("pptxgenjs");
+const pres = new PptxGenJS();
+
+pres.layout = "LAYOUT_16x9";
+pres.author = "Your Name";
+pres.title = "Presentation Title";
+pres.subject = "Subtitle or description";
+
+// Add slides
+const slide1 = pres.addSlide();
+
+// Save to file
+pres.writeFile({ fileName: "output.pptx" });
+```
+
+Key point: Always create a fresh `PptxGenJS()` instance per presentation. Don't reuse across multiple presentations.
+
+## Layout Dimensions
+
+Standard 16:9 layout is 10 inches wide by 5.625 inches tall. All positioning is in inches.
+
+```javascript
+// Slide area — HARD LIMITS (nothing may exceed these)
+const W = 10;          // Width (inches)
+const H = 5.625;       // Height (inches)
+const M = 0.5;         // Margin (standard)
+const contentWidth = W - 2 * M;  // 9 inches usable
+
+// Common positioning
+const titleY = M;                // Top margin
+const contentStartY = M + 0.8;  // After title (y = 1.3)
+const maxContentY = H - M;      // 5.125 — absolute bottom of content
+const contentHeight = maxContentY - contentStartY;  // ~3.8" available
+
+// BOUNDARY CHECK — use before placing every element:
+// if (elementY + elementH > H) → content will overflow, reduce or split slide
+```
+
+**CRITICAL: Every element must satisfy `y + h ≤ 5.625`.** If an element's bottom edge exceeds the slide height, it will be cut off in presentation mode. Always calculate remaining space before placing elements:
+```javascript
+const remainingHeight = H - currentY - M;  // available space below current position
+if (cardHeight > remainingHeight) {
+    // Split to next slide or reduce content
+}
+```
+
+## Text & Formatting
+
+### Basic Text
+
+```javascript
+slide.addText("Hello World", {
+    x: 0.5, y: 1, w: 9, h: 0.5,
+    fontSize: 16,
+    fontFace: "Arial",
+    color: "000000",
+    bold: true,
+    align: "left",
+    valign: "top"
+});
+```
+
+### Multi-line Text with Rich Formatting
+
+Use an array to mix formatted segments:
+
+```javascript
+slide.addText([
+    { text: "This is bold", options: { bold: true } },
+    { text: " and this is ", options: {} },
+    { text: "italic", options: { italic: true } }
+], {
+    x: 0.5, y: 2, w: 9, h: 1,
+    fontSize: 14,
+    fontFace: "Arial",
+    color: "1E293B",
+    align: "left"
+});
+```
+
+### Bullets & Line Breaks
+
+Always use `bullet: true` with `breakLine: true` between items:
+
+```javascript
+slide.addText([
+    { text: "First point", options: { bullet: true, breakLine: true } },
+    { text: "Second point", options: { bullet: true, breakLine: true } },
+    { text: "Third point", options: { bullet: true, breakLine: false } }  // Last item
+], {
+    x: 0.7, y: 2, w: 8.6, h: 2,
+    fontSize: 14,
+    fontFace: "Arial",
+    color: "1E293B",
+    paraSpaceAfter: 6,  // Space after each paragraph
+    valign: "top"
+});
+```
+
+**Never use Unicode bullets** like `•` or `◦`. Always use `bullet: true`.
+
+### Text Block with Padding
+
+Use `margin` to add internal padding:
+
+```javascript
+slide.addText("This text has padding", {
+    x: 1, y: 1, w: 8, h: 2,
+    fontSize: 14,
+    margin: [0.2, 0.3, 0.2, 0.3],  // [top, right, bottom, left]
+    align: "left"
+});
+```
+
+## Shapes
+
+### Rectangle
+
+```javascript
+slide.addShape(pres.shapes.RECTANGLE, {
+    x: 1, y: 1, w: 4, h: 2,
+    fill: { color: "E74C3C" },
+    line: { color: "C0392B", width: 2 },  // Border
+    shadow: {
+        type: "outer",
+        color: "000000",
+        blur: 6,
+        offset: 2,
+        angle: 135,
+        opacity: 0.1
+    }
+});
+```
+
+### Oval / Circle
+
+```javascript
+slide.addShape(pres.shapes.OVAL, {
+    x: 1, y: 1, w: 1.5, h: 1.5,  // Width and height equal = circle
+    fill: { color: "F5A623" }
+});
+```
+
+### Rounded Rectangle
+
+```javascript
+slide.addShape(pres.shapes.ROUNDED_RECTANGLE, {
+    x: 1, y: 1, w: 4, h: 2,
+    fill: { color: "FFFFFF" },
+    rectRadius: 0.1,  // Corner radius in inches
+    shadow: { type: "outer", color: "000000", blur: 4, offset: 1, angle: 135, opacity: 0.08 }
+});
+```
+
+### Line
+
+```javascript
+slide.addShape(pres.shapes.LINE, {
+    x: 1, y: 2, w: 4, h: 0,  // Height 0 for horizontal line
+    line: { color: "F5A623", width: 3 }
+});
+```
+
+### Shape Properties Reference
+
+| Property | Type | Notes |
+|---|---|---|
+| `x, y, w, h` | number | Position (inches) and size |
+| `fill` | object | `{ color: "HEX" }` or `{ type: "solid", color: "HEX", transparency: 0 }` |
+| `line` | object | `{ color: "HEX", width: 2, dashType: "solid" \| "dash" }` |
+| `shadow` | object | `{ type: "outer", color, blur, offset, angle, opacity }` |
+| `transparency` | number | 0-100. Use `fill.transparency`, not color string. |
+| `rotate` | number | Degrees (0-360) |
+
+## Images
+
+### From File Path
+
+```javascript
+slide.addImage({
+    path: "/path/to/image.jpg",
+    x: 5, y: 1, w: 4, h: 2.5
+});
+```
+
+### From URL
+
+```javascript
+slide.addImage({
+    url: "https://example.com/logo.png",
+    x: 5, y: 1, w: 4, h: 2.5
+});
+```
+
+### From Base64
+
+```javascript
+const base64Data = "data:image/png;base64,iVBORw0KGgo...";
+slide.addImage({
+    data: base64Data,
+    x: 5, y: 1, w: 4, h: 2.5
+});
+```
+
+### Sizing Modes
+
+```javascript
+slide.addImage({
+    path: "/image.jpg",
+    x: 1, y: 1, w: 4, h: 2.5,
+    sizing: {
+        type: "cover",  // "cover" = crop to fill, "contain" = fit inside
+        w: 4,
+        h: 2.5
+    }
+});
+```
+
+## Icons
+
+Convert React Icons to base64 PNG and embed:
+
+```javascript
+// 1. Generate SVG from react-icons, save as .svg
+// 2. Convert to PNG with sharp: sharp('icon.svg').png().toFile('icon.png')
+// 3. Convert PNG to base64
+const fs = require('fs');
+const iconBase64 = fs.readFileSync('icon.png', 'base64');
+const iconDataUri = `data:image/png;base64,${iconBase64}`;
+
+// 4. Add to slide
+slide.addShape(pres.shapes.OVAL, {
+    x: 1, y: 1, w: 0.4, h: 0.4,
+    fill: { color: "F5A623" }
+});
+slide.addImage({
+    data: iconDataUri,
+    x: 1.05, y: 1.05, w: 0.3, h: 0.3
+});
+```
+
+## Slide Backgrounds
+
+### Solid Color
+
+```javascript
+const slide = pres.addSlide();
+slide.background = { color: "1E2761" };
+```
+
+### Gradient
+
+```javascript
+slide.background = {
+    type: "solid",
+    fill: "F8FAFC"
+};
+```
+
+## Tables
+
+### Basic Table
+
+```javascript
+const tableData = [
+    [
+        { text: "Header A", options: { bold: true, color: "FFFFFF", fill: { color: "1E2761" } } },
+        { text: "Header B", options: { bold: true, color: "FFFFFF", fill: { color: "1E2761" } } }
+    ],
+    [
+        { text: "Row 1, Col A", options: {} },
+        { text: "Row 1, Col B", options: { fill: { color: "F8FAFC" } } }
+    ],
+    [
+        { text: "Row 2, Col A", options: { fill: { color: "F8FAFC" } } },
+        { text: "Row 2, Col B", options: {} }
+    ]
+];
+
+slide.addTable(tableData, {
+    x: 0.5, y: 2, w: 9, h: 2,
+    colW: [4.5, 4.5],  // Column widths
+    border: { pt: 1, color: "E2E8F0" },
+    fontFace: "Arial",
+    fontSize: 12
+});
+```
+
+### Table with Merged Cells
+
+```javascript
+const tableData = [
+    [
+        { text: "Merged", options: {}, colspan: 2 },  // Spans 2 columns
+        { text: "Normal", options: {} }
+    ]
+];
+```
+
+## Charts
+
+### Bar Chart
+
+```javascript
+const barData = [
+    {
+        name: "Series 1",
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        values: [15, 22, 18, 25]
+    },
+    {
+        name: "Series 2",
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        values: [12, 20, 16, 23]
+    }
+];
+
+slide.addChart(pres.ChartTypes.bar, barData, {
+    x: 1, y: 1, w: 8, h: 3,
+    chartColors: ["2E86AB", "F5A623"],
+    showLegend: true,
+    dataLabelPosition: "outEnd"  // Outside bars
+});
+```
+
+### Line Chart
+
+```javascript
+const lineData = [
+    {
+        name: "Revenue",
+        labels: ["Jan", "Feb", "Mar", "Apr"],
+        values: [100, 120, 140, 160]
+    }
+];
+
+slide.addChart(pres.ChartTypes.line, lineData, {
+    x: 1, y: 1, w: 8, h: 3,
+    lineSize: 2,
+    chartColors: ["F5A623"],
+    dataLabelPosition: "outEnd"
+});
+```
+
+### Pie Chart
+
+```javascript
+const pieData = [
+    {
+        name: "Category",
+        labels: ["Segment A", "Segment B", "Segment C"],
+        values: [30, 25, 45]
+    }
+];
+
+slide.addChart(pres.ChartTypes.pie, pieData, {
+    x: 1, y: 1, w: 4, h: 3,
+    chartColors: ["2E86AB", "F5A623", "E74C3C"],
+    dataLabelPosition: "ctr"  // Center
+});
+```
+
+### Chart Options
+
+| Option | Values | Notes |
+|---|---|---|
+| `chartColors` | Array of hex colors | Controls bar/line/pie segment colors |
+| `dataLabelPosition` | `"outEnd"`, `"ctr"`, `"inEnd"`, `"ctrH"` | Where labels appear |
+| `dataLabelFontSize` | number | Font size of data labels |
+| `gridLines` | object | `{ style: "solid", color: "E0E0E0", size: 1 }` |
+| `showLegend` | boolean | Show legend on chart |
+| `legendPos` | `"b"`, `"r"`, `"t"`, `"l"` | Legend position (bottom, right, top, left) |
+
+## Slide Masters
+
+Define a master slide template and reuse it:
+
+```javascript
+// Define master
+pres.defineLayout({ name: "MASTER_CONTENT" }, (slide) => {
+    slide.background = { color: "F8FAFC" };
+
+    // Add a footer
+    slide.addText("© 2024 Company", {
+        x: 0.5, y: H - 0.4, w: 9, h: 0.3,
+        fontSize: 8,
+        color: "64748B",
+        align: "right"
+    });
+});
+
+// Use master
+const slide = pres.addSlide("MASTER_CONTENT");
+```
+
+## Common Pitfalls
+
+### Colors
+
+- **NEVER use `#` with hex colors** — `"#FF0000"` corrupts the file. Always use `"FF0000"`.
+- **NEVER encode opacity in hex** — Don't try `"FF0000CC"`. Use `fill: { color: "FF0000", transparency: 50 }` instead.
+
+### Bullets
+
+- **Always use `bullet: true`** — Never try to build bullets manually with Unicode bullets.
+- **Always use `breakLine: true` between items** — This is required for proper spacing.
+- **Avoid `lineSpacing` with bullets** — Use `paraSpaceAfter: 6` instead for better control.
+
+### Objects & Mutations
+
+- **Create fresh option objects for each call** — PptxGenJS mutates option objects. Reusing the same object across multiple `addShape` or `addText` calls causes unexpected behavior.
+
+```javascript
+// WRONG: Shadow object reused
+const shadow = { type: "outer", color: "000000", blur: 6, offset: 2, opacity: 0.1 };
+slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 2, h: 1, shadow });
+slide.addShape(pres.shapes.RECTANGLE, { x: 4, y: 1, w: 2, h: 1, shadow });
+
+// RIGHT: Fresh shadow for each shape
+slide.addShape(pres.shapes.RECTANGLE, {
+    x: 1, y: 1, w: 2, h: 1,
+    shadow: { type: "outer", color: "000000", blur: 6, offset: 2, opacity: 0.1 }
+});
+slide.addShape(pres.shapes.RECTANGLE, {
+    x: 4, y: 1, w: 2, h: 1,
+    shadow: { type: "outer", color: "000000", blur: 6, offset: 2, opacity: 0.1 }
+});
+```
+
+### Shadow Offsets
+
+- **Shadow `offset` must be non-negative** — Negative values cause file corruption. Use positive values only.
+- **Typical shadow: blur 6, offset 2, opacity 0.08-0.1** — This creates a subtle drop shadow.
+
+### Rounded Rectangles
+
+- **Don't pair rounded rectangles with accent borders** — Rounded rectangles with thick borders (> 2pt) look awkward. Use subtle shadows instead.
+
+## Quick Reference
+
+### Shape Types
+```javascript
+pres.shapes.RECTANGLE
+pres.shapes.OVAL
+pres.shapes.LINE
+pres.shapes.ROUNDED_RECTANGLE
+pres.shapes.DIAMOND
+pres.shapes.TRIANGLE
+```
+
+### Chart Types
+```javascript
+pres.ChartTypes.bar
+pres.ChartTypes.line
+pres.ChartTypes.pie
+pres.ChartTypes.doughnut
+pres.ChartTypes.area
+pres.ChartTypes.scatter
+```
+
+### Text Alignment
+```javascript
+align: "left" | "center" | "right"
+valign: "top" | "middle" | "bottom"
+```
+
+### Common Font Faces
+```javascript
+"Arial"
+"Arial Black"
+"Calibri"
+"Georgia"
+"Trebuchet MS"
+"Helvetica"
+```
+
+### Sizing Guidelines
+
+| Element | Size (pt) |
+|---|---|
+| Slide title | 20-28 |
+| Section heading | 18 |
+| Body text | 14 |
+| Bullet text | 14 |
+| Captions | 10-11 |
+| Stat numbers | 60 |
+| Stat labels | 12 |
+| Table header | 11-12 |
+| Table body | 11 |
+
+### Spacing Guidelines
+
+| Element | Value |
+|---|---|
+| Slide margins | 0.5" |
+| Content block gap | 0.3-0.5" |
+| Line height multiplier | 1.3 |
+| Bullet spacing | `paraSpaceAfter: 6` |
+| Card shadow blur | 6 |
+| Card shadow offset | 2 |
+| Card shadow opacity | 0.08-0.1 |
+| Accent bar height | 0.06" |
+
+## Pattern: Professional Stat Card
+
+```javascript
+// Background card
+slide.addShape(pres.shapes.RECTANGLE, {
+    x: 1, y: 1, w: 2.5, h: 2,
+    fill: { color: "FFFFFF" },
+    shadow: { type: "outer", color: "000000", blur: 6, offset: 2, opacity: 0.08 }
+});
+
+// Color bar at top
+slide.addShape(pres.shapes.RECTANGLE, {
+    x: 1, y: 1, w: 2.5, h: 0.06,
+    fill: { color: "F5A623" }
+});
+
+// Large number
+slide.addText("3x", {
+    x: 1, y: 1.4, w: 2.5, h: 0.8,
+    fontSize: 60,
+    fontFace: "Arial Black",
+    color: "F5A623",
+    bold: true,
+    align: "center"
+});
+
+// Label
+slide.addText("User Growth", {
+    x: 1.2, y: 2.3, w: 2.1, h: 0.5,
+    fontSize: 12,
+    fontFace: "Arial",
+    color: "64748B",
+    align: "center"
+});
+```
+
+## Pattern: Two-Column Layout
+
+```javascript
+const colW = (9 - 0.3) / 2;  // Two equal columns
+
+// Left column
+slide.addText([
+    { text: "Point 1", options: { bullet: true, breakLine: true } },
+    { text: "Point 2", options: { bullet: true, breakLine: true } },
+    { text: "Point 3", options: { bullet: true, breakLine: false } }
+], {
+    x: 0.5, y: 1.5, w: colW, h: 3,
+    fontSize: 14,
+    fontFace: "Arial",
+    color: "1E293B",
+    valign: "top",
+    paraSpaceAfter: 6
+});
+
+// Right column
+slide.addText([
+    { text: "Benefit 1", options: { bullet: true, breakLine: true } },
+    { text: "Benefit 2", options: { bullet: true, breakLine: true } },
+    { text: "Benefit 3", options: { bullet: true, breakLine: false } }
+], {
+    x: 0.5 + colW + 0.3, y: 1.5, w: colW, h: 3,
+    fontSize: 14,
+    fontFace: "Arial",
+    color: "1E293B",
+    valign: "top",
+    paraSpaceAfter: 6
+});
+```
+
+## Example: Complete Slide
+
+```javascript
+const PptxGenJS = require("pptxgenjs");
+const pres = new PptxGenJS();
+pres.layout = "LAYOUT_16x9";
+pres.author = "Jane Doe";
+pres.title = "Q4 Results";
+
+const slide = pres.addSlide();
+const W = 10, H = 5.625, M = 0.5, CW = 9;
+
+// Background
+slide.background = { color: "F8FAFC" };
+
+// Title
+slide.addText("Revenue Beat Target by 15%", {
+    x: M, y: M, w: CW, h: 0.6,
+    fontSize: 20,
+    fontFace: "Arial Black",
+    color: "1E293B",
+    bold: true
+});
+
+// Accent underline
+slide.addShape(pres.shapes.RECTANGLE, {
+    x: M, y: M + 0.6, w: 0.8, h: 0.04,
+    fill: { color: "F5A623" }
+});
+
+// Body text
+slide.addText("We exceeded quarterly targets across all regions.", {
+    x: M, y: M + 1, w: CW, h: 0.6,
+    fontSize: 14,
+    fontFace: "Arial",
+    color: "1E293B"
+});
+
+// Bullet points
+slide.addText([
+    { text: "Sales team landed 3 enterprise deals", options: { bullet: true, breakLine: true } },
+    { text: "Product revenue grew 22% MoM", options: { bullet: true, breakLine: true } },
+    { text: "Customer retention at 96%", options: { bullet: true, breakLine: false } }
+], {
+    x: M + 0.2, y: M + 1.8, w: CW - 0.4, h: 2,
+    fontSize: 14,
+    fontFace: "Arial",
+    color: "1E293B",
+    paraSpaceAfter: 6,
+    valign: "top"
+});
+
+pres.writeFile({ fileName: "output.pptx" });
+```
+
+## Common Pitfalls: Stat Cards & Large Numbers
+
+**Large numbers overflow their text boxes.** At 48pt+ with bold fonts like Arial Black, values like "12.4K", "$156K", or "$48K" are often wider than narrow card text boxes (2-3 inches). When they overflow, the text wraps and produces broken-looking results — e.g. "12.4" on one line and "K" huge on the next.
+
+**Always use `shrinkText: true` on stat values:**
+```javascript
+slide.addText("$156K", {
+    x: cardX, y: cardY + 0.5, w: cardW, h: 1,
+    fontSize: 52,
+    fontFace: "Arial Black",
+    color: accentColor,
+    bold: true,
+    align: "center",
+    valign: "middle",
+    shrinkText: true  // CRITICAL — auto-scales text to fit the box
+});
+```
+
+This tells PowerPoint to auto-shrink the font size if the text doesn't fit. It's invisible when text fits fine, but prevents wrapping when values are wider than expected.
+
+**When to use `shrinkText: true`:**
+- All stat card values (any font ≥ 36pt in a box < 3" wide)
+- Slide titles on section dividers (large font + long titles)
+- Any text box where the content length is unpredictable
+
+**Alternative approaches if `shrinkText` isn't sufficient:**
+- Reduce font size for longer values: `fontSize: value.length > 4 ? 40 : 52`
+- Widen cards: use 3 cards per row instead of 4
+- Abbreviate values: "$156K" instead of "$156,000"