canva-pptx 1.0.0

package/src/layout/checkerboard.js

@@ -0,0 +1,36 @@
+/**
+ * Returns zones for alternating text/image rows.
+ * Row 1: Text Left, Image Right
+ * Row 2: Image Left, Text Right
+ */
+function getCheckerboardLayout(rows = 2, options = {}) {
+  const { 
+    x = 0.5, y = 0.5, w = 9, h = 4.63, 
+    gap = 0.5 
+  } = options;
+
+  const rowHeight = (h - (rows - 1) * gap) / rows;
+  const colWidth = (w - gap) / 2;
+  const zones = [];
+
+  for (let i = 0; i < rows; i++) {
+    const isEven = i % 2 === 0;
+    const curY = y + i * (rowHeight + gap);
+
+    if (isEven) {
+      zones.push({
+        text:  { x: x, y: curY, w: colWidth, h: rowHeight },
+        media: { x: x + colWidth + gap, y: curY, w: colWidth, h: rowHeight }
+      });
+    } else {
+      zones.push({
+        media: { x: x, y: curY, w: colWidth, h: rowHeight },
+        text:  { x: x + colWidth + gap, y: curY, w: colWidth, h: rowHeight }
+      });
+    }
+  }
+
+  return zones;
+}
+
+module.exports = { getCheckerboardLayout };

package/src/layout/filmStrip.js

@@ -0,0 +1,29 @@
+/**
+ * Returns a horizontal strip of items, potentially overflowing the slide width 
+ * (though in PPT, we clamp or fit them).
+ */
+function getFilmStripLayout(count = 5, options = {}) {
+  const { 
+    x = 0, y = 2, w = 10, h = 1.5, 
+    gap = 0.2 
+  } = options;
+
+  // Calculate item width to fit ALL in the specific width
+  const totalGap = (count - 1) * gap;
+  const itemW = (w - (x * 2) - totalGap) / count;
+
+  const positions = [];
+
+  for (let i = 0; i < count; i++) {
+    positions.push({
+      x: x + i * (itemW + gap),
+      y: y,
+      w: itemW,
+      h: h
+    });
+  }
+
+  return positions;
+}
+
+module.exports = { getFilmStripLayout };

package/src/layout/gallery.js

@@ -0,0 +1,50 @@
+/**
+ * Returns an array of coordinate objects for N items.
+ * Automatically calculates columns based on item count if not specified.
+ */
+function getGalleryLayout(count = 6, options = {}) {
+  const {
+    x = 0.5,
+    y = 0.5,
+    w = 9,
+    h = 4.63,
+    gap = 0.2,
+    cols = undefined // if undefined, auto-calculate
+  } = options;
+
+  // Auto-determine columns if not provided
+  // 1-3 items = 1 row (count cols)
+  // 4 items = 2 cols
+  // 5-6 items = 3 cols
+  // 7+ items = 4 cols
+  let calculatedCols = cols;
+  if (!calculatedCols) {
+    if (count <= 3) calculatedCols = count;
+    else if (count === 4) calculatedCols = 2;
+    else if (count <= 6) calculatedCols = 3;
+    else calculatedCols = 4;
+  }
+
+  const rows = Math.ceil(count / calculatedCols);
+  
+  const itemW = (w - (calculatedCols - 1) * gap) / calculatedCols;
+  const itemH = (h - (rows - 1) * gap) / rows;
+
+  const positions = [];
+
+  for (let i = 0; i < count; i++) {
+    const colIndex = i % calculatedCols;
+    const rowIndex = Math.floor(i / calculatedCols);
+
+    positions.push({
+      x: x + colIndex * (itemW + gap),
+      y: y + rowIndex * (itemH + gap),
+      w: itemW,
+      h: itemH
+    });
+  }
+
+  return positions;
+}
+
+module.exports = { getGalleryLayout };

package/src/layout/grid.js

@@ -0,0 +1,37 @@
+/**
+ * Create a grid system inside a container
+ * Container can be full slide or a subsection
+ */
+function createGrid(container, options = {}) {
+  const {
+    x = 0,
+    y = 0,
+    w = 10,
+    h = 5.63, // default slide height
+    cols = 2,
+    rows = 1,
+    gap = 0.2,
+  } = options;
+
+  const colWidth = (w - gap * (cols - 1)) / cols;
+  const rowHeight = (h - gap * (rows - 1)) / rows;
+
+  function getCell(col, row) {
+    return {
+      x: x + col * (colWidth + gap),
+      y: y + row * (rowHeight + gap),
+      w: colWidth,
+      h: rowHeight,
+    };
+  }
+
+  return {
+    getCell,
+    colWidth,
+    rowHeight,
+    cols,
+    rows,
+  };
+}
+
+module.exports = { createGrid };

package/src/layout/hero.js

@@ -0,0 +1,30 @@
+/**
+ * Returns zones for a Title, Subtitle, and Background Image.
+ * @param {Object} options - { align: 'center'|'left' }
+ */
+function getHeroLayout(options = {}) {
+  const {
+    align = "center",
+    w = 10,
+    h = 5.63,
+    padding = 1
+  } = options;
+
+  // Background is always full slide
+  const background = { x: 0, y: 0, w: w, h: h };
+
+  // Content zones based on alignment
+  let title, subtitle;
+
+  if (align === "center") {
+    title = { x: 0, y: h * 0.4, w: w, h: 1 };
+    subtitle = { x: 0, y: h * 0.4 + 1, w: w, h: 1 };
+  } else if (align === "left") {
+    title = { x: padding, y: h * 0.4, w: w - padding * 2, h: 1 };
+    subtitle = { x: padding, y: h * 0.4 + 1, w: w - padding * 2, h: 1 };
+  }
+
+  return { background, title, subtitle };
+}
+
+module.exports = { getHeroLayout };

package/src/layout/magazine.js

@@ -0,0 +1,39 @@
+/**
+ * Returns a magazine-style layout: One main focus item, multiple side items.
+ */
+function getMagazineLayout(sideItemCount = 3, options = {}) {
+  const { 
+    x = 0.5, y = 0.5, w = 9, h = 4.63, 
+    gap = 0.2, 
+    focusPosition = "left" // 'left' or 'right'
+  } = options;
+
+  // Focus takes up 60% width
+  const focusW = w * 0.6 - gap;
+  const sideW = w * 0.4;
+  
+  const sideItemH = (h - (sideItemCount - 1) * gap) / sideItemCount;
+
+  const focusZone = { 
+    x: focusPosition === "left" ? x : x + sideW + gap,
+    y: y,
+    w: focusW,
+    h: h
+  };
+
+  const sideZones = [];
+  const sideX = focusPosition === "left" ? x + focusW + gap : x;
+
+  for (let i = 0; i < sideItemCount; i++) {
+    sideZones.push({
+      x: sideX,
+      y: y + i * (sideItemH + gap),
+      w: sideW,
+      h: sideItemH
+    });
+  }
+
+  return { focus: focusZone, side: sideZones };
+}
+
+module.exports = { getMagazineLayout };

package/src/layout/radial.js

@@ -0,0 +1,34 @@
+/**
+ * Returns coordinates for N items arranged in a circle.
+ * @param {number} count - Number of items
+ */
+function getRadialLayout(count = 5, options = {}) {
+  const { 
+    x = 5, y = 2.8, // Center of slide
+    radius = 2, 
+    itemSize = 1 
+  } = options;
+
+  const positions = [];
+  const angleStep = (2 * Math.PI) / count;
+
+  for (let i = 0; i < count; i++) {
+    // Start from top (-PI/2)
+    const angle = i * angleStep - Math.PI / 2;
+
+    const curX = x + radius * Math.cos(angle) - (itemSize / 2);
+    const curY = y + radius * Math.sin(angle) - (itemSize / 2);
+
+    positions.push({
+      x: curX,
+      y: curY,
+      w: itemSize,
+      h: itemSize,
+      angle: (angle * 180) / Math.PI // Return angle in degrees for rotation if needed
+    });
+  }
+
+  return positions;
+}
+
+module.exports = { getRadialLayout };

package/src/layout/sidebar.js

@@ -0,0 +1,26 @@
+/**
+ * Returns coordinates for a sidebar layout.
+ * @param {Object} options - { position: 'left'|'right', width: 2.5 }
+ */
+function getSidebarLayout(options = {}) {
+  const {
+    position = "left",
+    width = 2.5,
+    w = 10,
+    h = 5.63
+  } = options;
+
+  if (position === "left") {
+    return {
+      sidebar: { x: 0, y: 0, w: width, h: h },
+      main:    { x: width, y: 0, w: w - width, h: h }
+    };
+  } else {
+    return {
+      main:    { x: 0, y: 0, w: w - width, h: h },
+      sidebar: { x: w - width, y: 0, w: width, h: h }
+    };
+  }
+}
+
+module.exports = { getSidebarLayout };

package/src/layout/splitScreen.js

@@ -0,0 +1,36 @@
+/**
+ * Returns coordinates for a split screen layout.
+ * @param {Object} options - { type: 'vertical'|'horizontal', ratio: 0.5, gutter: 0.2 }
+ */
+function getSplitScreen(options = {}) {
+  const {
+    type = "vertical", // 'vertical' (left/right) or 'horizontal' (top/bottom)
+    ratio = 0.5,       // Split ratio (0.5 = 50/50)
+    gutter = 0,        // Space between panels
+    w = 10,
+    h = 5.63,
+    x = 0,
+    y = 0
+  } = options;
+
+  if (type === "vertical") {
+    const width1 = (w * ratio) - (gutter / 2);
+    const width2 = (w * (1 - ratio)) - (gutter / 2);
+    
+    return {
+      left: { x: x, y: y, w: width1, h: h },
+      right: { x: x + width1 + gutter, y: y, w: width2, h: h }
+    };
+  } else {
+    // Horizontal (Top/Bottom)
+    const height1 = (h * ratio) - (gutter / 2);
+    const height2 = (h * (1 - ratio)) - (gutter / 2);
+    
+    return {
+      top: { x: x, y: y, w: w, h: height1 },
+      bottom: { x: x, y: y + height1 + gutter, w: w, h: height2 }
+    };
+  }
+}
+
+module.exports = { getSplitScreen };

package/src/layout/zPattern.js

@@ -0,0 +1,29 @@
+/**
+ * Returns 4 coordinate zones in a Z-pattern.
+ * Useful for guiding the eye through 4 key points.
+ */
+function getZPattern(options = {}) {
+  const {
+    w = 10,
+    h = 5.63,
+    margin = 0.5,
+    gap = 0.4
+  } = options;
+
+  // Workable area
+  const safeW = w - (margin * 2);
+  const safeH = h - (margin * 2);
+  
+  // Dimensions for each quadrant
+  const itemW = (safeW - gap) / 2;
+  const itemH = (safeH - gap) / 2;
+
+  return {
+    topLeft:     { x: margin, y: margin, w: itemW, h: itemH },
+    topRight:    { x: margin + itemW + gap, y: margin, w: itemW, h: itemH },
+    bottomLeft:  { x: margin, y: margin + itemH + gap, w: itemW, h: itemH },
+    bottomRight: { x: margin + itemW + gap, y: margin + itemH + gap, w: itemW, h: itemH }
+  };
+}
+
+module.exports = { getZPattern };

package/src/system/animation.js

@@ -0,0 +1,36 @@
+/**
+ * Animation helper.
+ * Usage: animate(slide).addText(...).withEffect('fadeIn')
+ */
+class AnimationBuilder {
+  constructor(slide) {
+    this.slide = slide;
+  }
+
+  addShape(type, options) {
+    this.lastShape = this.slide.addShape(type, options);
+    return this;
+  }
+  
+  addText(text, options) {
+    this.lastShape = this.slide.addText(text, options);
+    return this;
+  }
+
+  // Chainable animation
+  withEffect(effectType = "fadeIn", duration = 1000) {
+    // Note: pptxgenjs usually applies animation in the options object of addShape/addText.
+    // If the object was already created, modifying it is hard.
+    // A true sequencer usually wraps the *creation*.
+    // Here we assume the user calls this wrapper to generate the options.
+    console.log("Animation metadata attached (Concept only in this wrapper)");
+    // In real implementation, we'd merge { animation: { type: effectType } } into options
+    return this;
+  }
+}
+
+function animate(slide) {
+  return new AnimationBuilder(slide);
+}
+
+module.exports = { animate };

package/src/system/contrastChecker.js

@@ -0,0 +1,35 @@
+/**
+ * Checks contrast ratio between text and background.
+ * Logs a warning if ratio is below 4.5:1 (WCAG AA).
+ * * Note: This runs in the console during generation, not on the slide itself.
+ */
+function checkContrast(slideName, textColorHex, bgColorHex) {
+  // Helper to get luminance
+  const getLum = (hex) => {
+    const rgb = parseInt(hex.replace("#", ""), 16);
+    const r = (rgb >> 16) & 0xff;
+    const g = (rgb >>  8) & 0xff;
+    const b = (rgb >>  0) & 0xff;
+    
+    // WCAG formula
+    const a = [r, g, b].map(v => {
+      v /= 255;
+      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+    });
+    return a[0] * 0.2126 + a[1] * 0.7152 + a[2] * 0.0722;
+  };
+
+  const lum1 = getLum(textColorHex || "000000");
+  const lum2 = getLum(bgColorHex || "FFFFFF");
+  const brightest = Math.max(lum1, lum2);
+  const darkest = Math.min(lum1, lum2);
+  const ratio = (brightest + 0.05) / (darkest + 0.05);
+
+  if (ratio < 4.5) {
+    console.warn(`⚠️  ACCESSIBILITY WARN [${slideName}]: Low contrast ratio (${ratio.toFixed(2)}). Text: #${textColorHex} on Bg: #${bgColorHex}`);
+  } else {
+    // console.log(`✅ Contrast OK: ${ratio.toFixed(2)}`);
+  }
+}
+
+module.exports = { checkContrast };

package/src/system/dataAdapter.js

@@ -0,0 +1,36 @@
+/**
+ * Converts array of objects to Table rows.
+ * Input: [{ id: 1, name: 'A'}, { id: 2, name: 'B' }]
+ * Output: [['id', 'name'], [1, 'A'], [2, 'B']]
+ */
+function jsonToTableData(jsonArray) {
+  if (!jsonArray || jsonArray.length === 0) return [];
+  
+  const headers = Object.keys(jsonArray[0]);
+  const rows = jsonArray.map(obj => Object.values(obj));
+  
+  return [headers, ...rows];
+}
+
+/**
+ * Converts CSV string to Table rows.
+ */
+function csvToTableData(csvString) {
+  const rows = csvString.trim().split("\n");
+  return rows.map(r => r.split(",").map(c => c.trim()));
+}
+
+/**
+ * Converts JSON to Chart Data format for pptxgenjs.
+ * Input: [{ label: "Q1", value: 10 }, { label: "Q2", value: 20 }]
+ * Output: [{ name: "Series1", labels: ["Q1", "Q2"], values: [10, 20] }]
+ */
+function jsonToChartData(jsonArray, labelKey, valueKey, seriesName = "Series 1") {
+  return [{
+    name: seriesName,
+    labels: jsonArray.map(i => i[labelKey]),
+    values: jsonArray.map(i => i[valueKey])
+  }];
+}
+
+module.exports = { jsonToTableData, csvToTableData, jsonToChartData };

package/src/system/layoutDebugger.js

@@ -0,0 +1,40 @@
+/**
+ * Visual Debugger
+ * Draws a 1-inch grid and safe-zone borders to help align content.
+ */
+function debugSlide(slide, options = {}) {
+  const { color = "FF0000", showGrid = true, showSafeZone = true } = options;
+
+  // 1. Safe Zone Border (Margin)
+  if (showSafeZone) {
+    slide.addShape("rect", {
+      x: 0.5, y: 0.5, w: 9, h: 4.63,
+      fill: { color: undefined },
+      line: { color: color, width: 1, dashType: "dash" }
+    });
+  }
+
+  // 2. Grid Lines (Every 1 inch)
+  if (showGrid) {
+    // Vertical Lines (0 to 10)
+    for (let i = 1; i < 10; i++) {
+      slide.addShape("line", {
+        x: i, y: 0, w: 0, h: 5.63,
+        line: { color: "E0E0E0", width: 1 } // Light grey
+      });
+    }
+    // Horizontal Lines (0 to 5.63)
+    for (let i = 1; i < 6; i++) {
+      slide.addShape("line", {
+        x: 0, y: i, w: 10, h: 0,
+        line: { color: "E0E0E0", width: 1 }
+      });
+    }
+  }
+
+  // 3. Center Crosshair
+  slide.addShape("line", { x: 5, y: 2.7, w: 0, h: 0.2, line: { color: color } }); // V
+  slide.addShape("line", { x: 4.9, y: 2.815, w: 0.2, h: 0, line: { color: color } }); // H
+}
+
+module.exports = { debugSlide };

package/src/system/markdownEngine.js

@@ -0,0 +1,45 @@
+const { addSlide } = require("../components/slide");
+const { addText } = require("../components/text");
+
+/**
+ * Parses markdown string and generates slides.
+ * Separator: "---" creates a new slide.
+ * # Title
+ * ## Subtitle
+ * - Bullet point
+ */
+function renderMarkdown(manager, markdown) {
+  const pptx = manager.getPptx();
+  const slides = markdown.split(/\n---\n/); // Split by horizontal rule
+
+  slides.forEach(content => {
+    const slide = addSlide(pptx);
+    const lines = content.trim().split("\n");
+    let yPos = 1.0;
+
+    lines.forEach(line => {
+      line = line.trim();
+      if (!line) return;
+
+      if (line.startsWith("# ")) {
+        // H1 Title
+        addText(slide, line.replace("# ", ""), { x: 0.5, y: 0.5, fontSize: 32, bold: true, w: 9 });
+        yPos = 1.5;
+      } else if (line.startsWith("## ")) {
+        // H2 Subtitle
+        addText(slide, line.replace("## ", ""), { x: 0.5, y: yPos, fontSize: 20, color: "666666", w: 9 });
+        yPos += 0.8;
+      } else if (line.startsWith("- ")) {
+        // Bullet
+        addText(slide, line.replace("- ", ""), { x: 1, y: yPos, fontSize: 16, bullet: true, w: 8, h: 0.5 });
+        yPos += 0.6;
+      } else {
+        // Regular Paragraph
+        addText(slide, line, { x: 1, y: yPos, fontSize: 14, w: 8 });
+        yPos += 0.6;
+      }
+    });
+  });
+}
+
+module.exports = { renderMarkdown };

package/src/system/masterOverlay.js

@@ -0,0 +1,50 @@
+/**
+ * Applies a layout master function to a slide.
+ * Useful for logos, footers, and page numbers.
+ */
+function applyMaster(slide, options = {}) {
+  const {
+    logo,
+    footerText,
+    showPageNumber = true,
+    accentColor = "007AFF"
+  } = options;
+
+  // 1. Logo (Top Right)
+  if (logo) {
+    slide.addImage({ 
+      path: logo, 
+      x: 9.0, y: 0.2, w: 0.8, h: 0.8, 
+      sizing: { type: "contain", w: 0.8, h: 0.8 } 
+    });
+  }
+
+  // 2. Footer Bar (Bottom)
+  slide.addShape("line", {
+    x: 0.5, y: 5.2, w: 9, h: 0,
+    line: { color: "E0E0E0", width: 1 }
+  });
+
+  // 3. Footer Text (Bottom Left)
+  if (footerText) {
+    slide.addText(footerText, {
+      x: 0.5, y: 5.3, w: 6, h: 0.3,
+      fontSize: 10, color: "888888"
+    });
+  }
+
+  // 4. Page Number (Bottom Right)
+  if (showPageNumber) {
+    // FIX: slideNumber is a property, not a function
+    slide.slideNumber = { 
+      x: 9.0, 
+      y: 5.3, 
+      w: 0.5, 
+      h: 0.3, 
+      fontSize: 10, 
+      color: accentColor 
+    };
+  }
+}
+
+module.exports = { applyMaster };

package/src/system/sectionDivider.js

@@ -0,0 +1,41 @@
+/**
+ * Creates a distinct section divider slide.
+ * Useful for breaking up long presentations.
+ */
+function addSectionDivider(manager, title, subtitle = "") {
+  const pptx = manager.getPptx();
+  const slide = pptx.addSlide();
+
+  // Dark Background for contrast
+  slide.background = { fill: "111111" };
+
+  // Big Title
+  slide.addText(title, {
+    x: 1, y: 2, w: 8, h: 1,
+    fontSize: 44,
+    bold: true,
+    color: "FFFFFF",
+    align: "center"
+  });
+
+  // Horizontal Line
+  slide.addShape("line", {
+    x: 3, y: 3.2, w: 4, h: 0,
+    line: { color: "007AFF", width: 3 }
+  });
+
+  // Subtitle
+  if (subtitle) {
+    slide.addText(subtitle, {
+      x: 1, y: 3.5, w: 8, h: 1,
+      fontSize: 18,
+      color: "BBBBBB",
+      align: "center",
+      italic: true
+    });
+  }
+  
+  return slide;
+}
+
+module.exports = { addSectionDivider };

package/src/system/smartIcon.js

@@ -0,0 +1,33 @@
+// A small set of standard SVG paths (simulated)
+const ICONS = {
+  user: "M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z",
+  home: "M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z",
+  settings: "M19.14 12.94c.04-.3.06-.61.06-.94 0-.32-.02-.64-.07-.94l2.03-1.58c.18-.14.23-.41.12-.61l-1.92-3.32c-.12-.22-.37-.29-.59-.22l-2.39.96c-.5-.38-1.03-.7-1.62-.94l-.36-2.54c-.04-.24-.24-.41-.48-.41h-3.84c-.24 0-.43.17-.47.41l-.36 2.54c-.59.24-1.13.57-1.62.94l-2.39-.96c-.22-.08-.47 0-.59.22L2.68 8.87c-.11.21-.06.47.12.61l2.03 1.58c-.05.3-.09.63-.09.94s.02.64.07.94l-2.03 1.58c-.18.14-.23.41-.12.61l1.92 3.32c.12.22.37.29.59.22l2.39-.96c.5.38 1.03.7 1.62.94l.36 2.54c.04.24.24.41.48.41h3.84c.24 0.43-.17.47-.41l.36-2.54c.59-.24 1.13-.57 1.62-.94l2.39.96c.22.08.47 0 .59-.22l1.92-3.32c.11-.21.06-.47-.12-.61l-2.01-1.58zM12 15.6c-1.98 0-3.6-1.62-3.6-3.6s1.62-3.6 3.6-3.6 3.6 1.62 3.6 3.6-1.62 3.6-3.6 3.6z",
+  star: "M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z"
+};
+
+function addSmartIcon(slide, iconName, options = {}) {
+  const { x = 1, y = 1, size = 0.5, color = "000000" } = options;
+  
+  // Note: pptxgenjs supports SVG paths via 'path' property in addShape (custom geometry) 
+  // or via addImage with dataURI. Custom geometry is cleaner if supported, 
+  // but addImage with SVG XML is more robust across versions.
+  
+  const pathData = ICONS[iconName];
+  if (!pathData) {
+    console.warn(`Icon ${iconName} not found.`);
+    return;
+  }
+
+  // Construct a minimal SVG string
+  const svgData = `data:image/svg+xml;base64,${Buffer.from(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#${color}"><path d="${pathData}"/></svg>`
+  ).toString("base64")}`;
+
+  slide.addImage({
+    data: svgData,
+    x, y, w: size, h: size
+  });
+}
+
+module.exports = { addSmartIcon };