npm - @agentskillkit/agent-skills - Versions diffs - 1.0.1 → 3.2.1 - Mend

@agentskillkit/agent-skills 1.0.1 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (801) hide show

package/.agent/skills/document-skills/pptx/html2pptx.md DELETED Viewed

@@ -1,625 +0,0 @@
-# HTML to PowerPoint Guide
-Convert HTML slides to PowerPoint presentations with accurate positioning using the `html2pptx.js` library.
-## Table of Contents
-1. [Creating HTML Slides](#creating-html-slides)
-2. [Using the html2pptx Library](#using-the-html2pptx-library)
-3. [Using PptxGenJS](#using-pptxgenjs)
----
-## Creating HTML Slides
-Every HTML slide must include proper body dimensions:
-### Layout Dimensions
-- **16:9** (default): `width: 720pt; height: 405pt`
-- **4:3**: `width: 720pt; height: 540pt`
-- **16:10**: `width: 720pt; height: 450pt`
-### Supported Elements
-- `<p>`, `<h1>`-`<h6>` - Text with styling
-- `<ul>`, `<ol>` - Lists (never use manual bullets •, -, *)
-- `<b>`, `<strong>` - Bold text (inline formatting)
-- `<i>`, `<em>` - Italic text (inline formatting)
-- `<u>` - Underlined text (inline formatting)
-- `<span>` - Inline formatting with CSS styles (bold, italic, underline, color)
-- `<br>` - Line breaks
-- `<div>` with bg/border - Becomes shape
-- `<img>` - Images
-- `class="placeholder"` - Reserved space for charts (returns `{ id, x, y, w, h }`)
-### Critical Text Rules
-**ALL text MUST be inside `<p>`, `<h1>`-`<h6>`, `<ul>`, or `<ol>` tags:**
-- ✅ Correct: `<div><p>Text here</p></div>`
-- ❌ Wrong: `<div>Text here</div>` - **Text will NOT appear in PowerPoint**
-- ❌ Wrong: `<span>Text</span>` - **Text will NOT appear in PowerPoint**
-- Text in `<div>` or `<span>` without a text tag will be silently ignored
-**NEVER use manual bullet symbols (•, -, *, etc.)** - Use `<ul>` or `<ol>` lists instead
-**ONLY use web-safe fonts that are universally available:**
-- ✅ Web-safe fonts: `Arial`, `Helvetica`, `Times New Roman`, `Georgia`, `Courier New`, `Verdana`, `Tahoma`, `Trebuchet MS`, `Impact`, `Comic Sans MS`
-- ❌ Wrong: `'Segoe UI'`, `'SF Pro'`, `'Roboto'`, custom fonts - **Might cause rendering issues**
-### Styling
-- Use `display: flex` on body to prevent margin collapse from breaking overflow validation
-- Use `margin` for spacing (padding included in size)
-- Inline formatting: Use `<b>`, `<i>`, `<u>` tags OR `<span>` with CSS styles
-  - `<span>` supports: `font-weight: bold`, `font-style: italic`, `text-decoration: underline`, `color: #rrggbb`
-  - `<span>` does NOT support: `margin`, `padding` (not supported in PowerPoint text runs)
-  - Example: `<span style="font-weight: bold; color: #667eea;">Bold blue text</span>`
-- Flexbox works - positions calculated from rendered layout
-- Use hex colors with `#` prefix in CSS
-- **Text alignment**: Use CSS `text-align` (`center`, `right`, etc.) when needed as a hint to PptxGenJS for text formatting if text lengths are slightly off
-### Shape Styling (DIV elements only)
-**IMPORTANT: Backgrounds, borders, and shadows only work on `<div>` elements, NOT on text elements (`<p>`, `<h1>`-`<h6>`, `<ul>`, `<ol>`)**
-- **Backgrounds**: CSS `background` or `background-color` on `<div>` elements only
-  - Example: `<div style="background: #f0f0f0;">` - Creates a shape with background
-- **Borders**: CSS `border` on `<div>` elements converts to PowerPoint shape borders
-  - Supports uniform borders: `border: 2px solid #333333`
-  - Supports partial borders: `border-left`, `border-right`, `border-top`, `border-bottom` (rendered as line shapes)
-  - Example: `<div style="border-left: 8pt solid #E76F51;">`
-- **Border radius**: CSS `border-radius` on `<div>` elements for rounded corners
-  - `border-radius: 50%` or higher creates circular shape
-  - Percentages <50% calculated relative to shape's smaller dimension
-  - Supports px and pt units (e.g., `border-radius: 8pt;`, `border-radius: 12px;`)
-  - Example: `<div style="border-radius: 25%;">` on 100x200px box = 25% of 100px = 25px radius
-- **Box shadows**: CSS `box-shadow` on `<div>` elements converts to PowerPoint shadows
-  - Supports outer shadows only (inset shadows are ignored to prevent corruption)
-  - Example: `<div style="box-shadow: 2px 2px 8px rgba(0, 0, 0, 0.3);">`
-  - Note: Inset/inner shadows are not supported by PowerPoint and will be skipped
-### Icons & Gradients
-- **CRITICAL: Never use CSS gradients (`linear-gradient`, `radial-gradient`)** - They don't convert to PowerPoint
-- **ALWAYS create gradient/icon PNGs FIRST using Sharp, then reference in HTML**
-- For gradients: Rasterize SVG to PNG background images
-- For icons: Rasterize react-icons SVG to PNG images
-- All visual effects must be pre-rendered as raster images before HTML rendering
-**Rasterizing Icons with Sharp:**
-```javascript
-const React = require('react');
-const ReactDOMServer = require('react-dom/server');
-const sharp = require('sharp');
-const { FaHome } = require('react-icons/fa');
-async function rasterizeIconPng(IconComponent, color, size = "256", filename) {
-  const svgString = ReactDOMServer.renderToStaticMarkup(
-    React.createElement(IconComponent, { color: `#${color}`, size: size })
-  );
-  // Convert SVG to PNG using Sharp
-  await sharp(Buffer.from(svgString))
-    .png()
-    .toFile(filename);
-  return filename;
-}
-// Usage: Rasterize icon before using in HTML
-const iconPath = await rasterizeIconPng(FaHome, "4472c4", "256", "home-icon.png");
-// Then reference in HTML: <img src="home-icon.png" style="width: 40pt; height: 40pt;">
-```
-**Rasterizing Gradients with Sharp:**
-```javascript
-const sharp = require('sharp');
-async function createGradientBackground(filename) {
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="562.5">
-    <defs>
-      <linearGradient id="g" x1="0%" y1="0%" x2="100%" y2="100%">
-        <stop offset="0%" style="stop-color:#COLOR1"/>
-        <stop offset="100%" style="stop-color:#COLOR2"/>
-      </linearGradient>
-    </defs>
-    <rect width="100%" height="100%" fill="url(#g)"/>
-  </svg>`;
-  await sharp(Buffer.from(svg))
-    .png()
-    .toFile(filename);
-  return filename;
-}
-// Usage: Create gradient background before HTML
-const bgPath = await createGradientBackground("gradient-bg.png");
-// Then in HTML: <body style="background-image: url('gradient-bg.png');">
-```
-### Example
-```html
-<!DOCTYPE html>
-<html>
-<head>
-<style>
-html { background: #ffffff; }
-body {
-  width: 720pt; height: 405pt; margin: 0; padding: 0;
-  background: #f5f5f5; font-family: Arial, sans-serif;
-  display: flex;
-}
-.content { margin: 30pt; padding: 40pt; background: #ffffff; border-radius: 8pt; }
-h1 { color: #2d3748; font-size: 32pt; }
-.box {
-  background: #70ad47; padding: 20pt; border: 3px solid #5a8f37;
-  border-radius: 12pt; box-shadow: 3px 3px 10px rgba(0, 0, 0, 0.25);
-}
-</style>
-</head>
-<body>
-<div class="content">
-  <h1>Recipe Title</h1>
-  <ul>
-    <li><b>Item:</b> Description</li>
-  </ul>
-  <p>Text with <b>bold</b>, <i>italic</i>, <u>underline</u>.</p>
-  <div id="chart" class="placeholder" style="width: 350pt; height: 200pt;"></div>
-  <!-- Text MUST be in <p> tags -->
-  <div class="box">
-    <p>5</p>
-  </div>
-</div>
-</body>
-</html>
-```
-## Using the html2pptx Library
-### Dependencies
-These libraries have been globally installed and are available to use:
-- `pptxgenjs`
-- `playwright`
-- `sharp`
-### Basic Usage
-```javascript
-const pptxgen = require('pptxgenjs');
-const html2pptx = require('./html2pptx');
-const pptx = new pptxgen();
-pptx.layout = 'LAYOUT_16x9';  // Must match HTML body dimensions
-const { slide, placeholders } = await html2pptx('slide1.html', pptx);
-// Add chart to placeholder area
-if (placeholders.length > 0) {
-    slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
-}
-await pptx.writeFile('output.pptx');
-```
-### API Reference
-#### Function Signature
-```javascript
-await html2pptx(htmlFile, pres, options)
-```
-#### Parameters
-- `htmlFile` (string): Path to HTML file (absolute or relative)
-- `pres` (pptxgen): PptxGenJS presentation instance with layout already set
-- `options` (object, optional):
-  - `tmpDir` (string): Temporary directory for generated files (default: `process.env.TMPDIR || '/tmp'`)
-  - `slide` (object): Existing slide to reuse (default: creates new slide)
-#### Returns
-```javascript
-{
-    slide: pptxgenSlide,           // The created/updated slide
-    placeholders: [                 // Array of placeholder positions
-        { id: string, x: number, y: number, w: number, h: number },
-        ...
-    ]
-}
-```
-### Validation
-The library automatically validates and collects all errors before throwing:
-1. **HTML dimensions must match presentation layout** - Reports dimension mismatches
-2. **Content must not overflow body** - Reports overflow with exact measurements
-3. **CSS gradients** - Reports unsupported gradient usage
-4. **Text element styling** - Reports backgrounds/borders/shadows on text elements (only allowed on divs)
-**All validation errors are collected and reported together** in a single error message, allowing you to fix all issues at once instead of one at a time.
-### Working with Placeholders
-```javascript
-const { slide, placeholders } = await html2pptx('slide.html', pptx);
-// Use first placeholder
-slide.addChart(pptx.charts.BAR, data, placeholders[0]);
-// Find by ID
-const chartArea = placeholders.find(p => p.id === 'chart-area');
-slide.addChart(pptx.charts.LINE, data, chartArea);
-```
-### Complete Example
-```javascript
-const pptxgen = require('pptxgenjs');
-const html2pptx = require('./html2pptx');
-async function createPresentation() {
-    const pptx = new pptxgen();
-    pptx.layout = 'LAYOUT_16x9';
-    pptx.author = 'Your Name';
-    pptx.title = 'My Presentation';
-    // Slide 1: Title
-    const { slide: slide1 } = await html2pptx('slides/title.html', pptx);
-    // Slide 2: Content with chart
-    const { slide: slide2, placeholders } = await html2pptx('slides/data.html', pptx);
-    const chartData = [{
-        name: 'Sales',
-        labels: ['Q1', 'Q2', 'Q3', 'Q4'],
-        values: [4500, 5500, 6200, 7100]
-    }];
-    slide2.addChart(pptx.charts.BAR, chartData, {
-        ...placeholders[0],
-        showTitle: true,
-        title: 'Quarterly Sales',
-        showCatAxisTitle: true,
-        catAxisTitle: 'Quarter',
-        showValAxisTitle: true,
-        valAxisTitle: 'Sales ($000s)'
-    });
-    // Save
-    await pptx.writeFile({ fileName: 'presentation.pptx' });
-    console.log('Presentation created successfully!');
-}
-createPresentation().catch(console.error);
-```
-## Using PptxGenJS
-After converting HTML to slides with `html2pptx`, you'll use PptxGenJS to add dynamic content like charts, images, and additional elements.
-### ⚠️ Critical Rules
-#### Colors
-- **NEVER use `#` prefix** with hex colors in PptxGenJS - causes file corruption
-- ✅ Correct: `color: "FF0000"`, `fill: { color: "0066CC" }`
-- ❌ Wrong: `color: "#FF0000"` (breaks document)
-### Adding Images
-Always calculate aspect ratios from actual image dimensions:
-```javascript
-// Get image dimensions: identify image.png | grep -o '[0-9]* x [0-9]*'
-const imgWidth = 1860, imgHeight = 1519;  // From actual file
-const aspectRatio = imgWidth / imgHeight;
-const h = 3;  // Max height
-const w = h * aspectRatio;
-const x = (10 - w) / 2;  // Center on 16:9 slide
-slide.addImage({ path: "chart.png", x, y: 1.5, w, h });
-```
-### Adding Text
-```javascript
-// Rich text with formatting
-slide.addText([
-    { text: "Bold ", options: { bold: true } },
-    { text: "Italic ", options: { italic: true } },
-    { text: "Normal" }
-], {
-    x: 1, y: 2, w: 8, h: 1
-});
-```
-### Adding Shapes
-```javascript
-// Rectangle
-slide.addShape(pptx.shapes.RECTANGLE, {
-    x: 1, y: 1, w: 3, h: 2,
-    fill: { color: "4472C4" },
-    line: { color: "000000", width: 2 }
-});
-// Circle
-slide.addShape(pptx.shapes.OVAL, {
-    x: 5, y: 1, w: 2, h: 2,
-    fill: { color: "ED7D31" }
-});
-// Rounded rectangle
-slide.addShape(pptx.shapes.ROUNDED_RECTANGLE, {
-    x: 1, y: 4, w: 3, h: 1.5,
-    fill: { color: "70AD47" },
-    rectRadius: 0.2
-});
-```
-### Adding Charts
-**Required for most charts:** Axis labels using `catAxisTitle` (category) and `valAxisTitle` (value).
-**Chart Data Format:**
-- Use **single series with all labels** for simple bar/line charts
-- Each series creates a separate legend entry
-- Labels array defines X-axis values
-**Time Series Data - Choose Correct Granularity:**
-- **< 30 days**: Use daily grouping (e.g., "10-01", "10-02") - avoid monthly aggregation that creates single-point charts
-- **30-365 days**: Use monthly grouping (e.g., "2024-01", "2024-02")
-- **> 365 days**: Use yearly grouping (e.g., "2023", "2024")
-- **Validate**: Charts with only 1 data point likely indicate incorrect aggregation for the time period
-```javascript
-const { slide, placeholders } = await html2pptx('slide.html', pptx);
-// CORRECT: Single series with all labels
-slide.addChart(pptx.charts.BAR, [{
-    name: "Sales 2024",
-    labels: ["Q1", "Q2", "Q3", "Q4"],
-    values: [4500, 5500, 6200, 7100]
-}], {
-    ...placeholders[0],  // Use placeholder position
-    barDir: 'col',       // 'col' = vertical bars, 'bar' = horizontal
-    showTitle: true,
-    title: 'Quarterly Sales',
-    showLegend: false,   // No legend needed for single series
-    // Required axis labels
-    showCatAxisTitle: true,
-    catAxisTitle: 'Quarter',
-    showValAxisTitle: true,
-    valAxisTitle: 'Sales ($000s)',
-    // Optional: Control scaling (adjust min based on data range for better visualization)
-    valAxisMaxVal: 8000,
-    valAxisMinVal: 0,  // Use 0 for counts/amounts; for clustered data (e.g., 4500-7100), consider starting closer to min value
-    valAxisMajorUnit: 2000,  // Control y-axis label spacing to prevent crowding
-    catAxisLabelRotate: 45,  // Rotate labels if crowded
-    dataLabelPosition: 'outEnd',
-    dataLabelColor: '000000',
-    // Use single color for single-series charts
-    chartColors: ["4472C4"]  // All bars same color
-});
-```
-#### Scatter Chart
-**IMPORTANT**: Scatter chart data format is unusual - first series contains X-axis values, subsequent series contain Y-values:
-```javascript
-// Prepare data
-const data1 = [{ x: 10, y: 20 }, { x: 15, y: 25 }, { x: 20, y: 30 }];
-const data2 = [{ x: 12, y: 18 }, { x: 18, y: 22 }];
-const allXValues = [...data1.map(d => d.x), ...data2.map(d => d.x)];
-slide.addChart(pptx.charts.SCATTER, [
-    { name: 'X-Axis', values: allXValues },  // First series = X values
-    { name: 'Series 1', values: data1.map(d => d.y) },  // Y values only
-    { name: 'Series 2', values: data2.map(d => d.y) }   // Y values only
-], {
-    x: 1, y: 1, w: 8, h: 4,
-    lineSize: 0,  // 0 = no connecting lines
-    lineDataSymbol: 'circle',
-    lineDataSymbolSize: 6,
-    showCatAxisTitle: true,
-    catAxisTitle: 'X Axis',
-    showValAxisTitle: true,
-    valAxisTitle: 'Y Axis',
-    chartColors: ["4472C4", "ED7D31"]
-});
-```
-#### Line Chart
-```javascript
-slide.addChart(pptx.charts.LINE, [{
-    name: "Temperature",
-    labels: ["Jan", "Feb", "Mar", "Apr"],
-    values: [32, 35, 42, 55]
-}], {
-    x: 1, y: 1, w: 8, h: 4,
-    lineSize: 4,
-    lineSmooth: true,
-    // Required axis labels
-    showCatAxisTitle: true,
-    catAxisTitle: 'Month',
-    showValAxisTitle: true,
-    valAxisTitle: 'Temperature (°F)',
-    // Optional: Y-axis range (set min based on data range for better visualization)
-    valAxisMinVal: 0,     // For ranges starting at 0 (counts, percentages, etc.)
-    valAxisMaxVal: 60,
-    valAxisMajorUnit: 20,  // Control y-axis label spacing to prevent crowding (e.g., 10, 20, 25)
-    // valAxisMinVal: 30,  // PREFERRED: For data clustered in a range (e.g., 32-55 or ratings 3-5), start axis closer to min value to show variation
-    // Optional: Chart colors
-    chartColors: ["4472C4", "ED7D31", "A5A5A5"]
-});
-```
-#### Pie Chart (No Axis Labels Required)
-**CRITICAL**: Pie charts require a **single data series** with all categories in the `labels` array and corresponding values in the `values` array.
-```javascript
-slide.addChart(pptx.charts.PIE, [{
-    name: "Market Share",
-    labels: ["Product A", "Product B", "Other"],  // All categories in one array
-    values: [35, 45, 20]  // All values in one array
-}], {
-    x: 2, y: 1, w: 6, h: 4,
-    showPercent: true,
-    showLegend: true,
-    legendPos: 'r',  // right
-    chartColors: ["4472C4", "ED7D31", "A5A5A5"]
-});
-```
-#### Multiple Data Series
-```javascript
-slide.addChart(pptx.charts.LINE, [
-    {
-        name: "Product A",
-        labels: ["Q1", "Q2", "Q3", "Q4"],
-        values: [10, 20, 30, 40]
-    },
-    {
-        name: "Product B",
-        labels: ["Q1", "Q2", "Q3", "Q4"],
-        values: [15, 25, 20, 35]
-    }
-], {
-    x: 1, y: 1, w: 8, h: 4,
-    showCatAxisTitle: true,
-    catAxisTitle: 'Quarter',
-    showValAxisTitle: true,
-    valAxisTitle: 'Revenue ($M)'
-});
-```
-### Chart Colors
-**CRITICAL**: Use hex colors **without** the `#` prefix - including `#` causes file corruption.
-**Align chart colors with your chosen design palette**, ensuring sufficient contrast and distinctiveness for data visualization. Adjust colors for:
-- Strong contrast between adjacent series
-- Readability against slide backgrounds
-- Accessibility (avoid red-green only combinations)
-```javascript
-// Example: Ocean palette-inspired chart colors (adjusted for contrast)
-const chartColors = ["16A085", "FF6B9D", "2C3E50", "F39C12", "9B59B6"];
-// Single-series chart: Use one color for all bars/points
-slide.addChart(pptx.charts.BAR, [{
-    name: "Sales",
-    labels: ["Q1", "Q2", "Q3", "Q4"],
-    values: [4500, 5500, 6200, 7100]
-}], {
-    ...placeholders[0],
-    chartColors: ["16A085"],  // All bars same color
-    showLegend: false
-});
-// Multi-series chart: Each series gets a different color
-slide.addChart(pptx.charts.LINE, [
-    { name: "Product A", labels: ["Q1", "Q2", "Q3"], values: [10, 20, 30] },
-    { name: "Product B", labels: ["Q1", "Q2", "Q3"], values: [15, 25, 20] }
-], {
-    ...placeholders[0],
-    chartColors: ["16A085", "FF6B9D"]  // One color per series
-});
-```
-### Adding Tables
-Tables can be added with basic or advanced formatting:
-#### Basic Table
-```javascript
-slide.addTable([
-    ["Header 1", "Header 2", "Header 3"],
-    ["Row 1, Col 1", "Row 1, Col 2", "Row 1, Col 3"],
-    ["Row 2, Col 1", "Row 2, Col 2", "Row 2, Col 3"]
-], {
-    x: 0.5,
-    y: 1,
-    w: 9,
-    h: 3,
-    border: { pt: 1, color: "999999" },
-    fill: { color: "F1F1F1" }
-});
-```
-#### Table with Custom Formatting
-```javascript
-const tableData = [
-    // Header row with custom styling
-    [
-        { text: "Product", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } },
-        { text: "Revenue", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } },
-        { text: "Growth", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } }
-    ],
-    // Data rows
-    ["Product A", "$50M", "+15%"],
-    ["Product B", "$35M", "+22%"],
-    ["Product C", "$28M", "+8%"]
-];
-slide.addTable(tableData, {
-    x: 1,
-    y: 1.5,
-    w: 8,
-    h: 3,
-    colW: [3, 2.5, 2.5],  // Column widths
-    rowH: [0.5, 0.6, 0.6, 0.6],  // Row heights
-    border: { pt: 1, color: "CCCCCC" },
-    align: "center",
-    valign: "middle",
-    fontSize: 14
-});
-```
-#### Table with Merged Cells
-```javascript
-const mergedTableData = [
-    [
-        { text: "Q1 Results", options: { colspan: 3, fill: { color: "4472C4" }, color: "FFFFFF", bold: true } }
-    ],
-    ["Product", "Sales", "Market Share"],
-    ["Product A", "$25M", "35%"],
-    ["Product B", "$18M", "25%"]
-];
-slide.addTable(mergedTableData, {
-    x: 1,
-    y: 1,
-    w: 8,
-    h: 2.5,
-    colW: [3, 2.5, 2.5],
-    border: { pt: 1, color: "DDDDDD" }
-});
-```
-### Table Options
-Common table options:
-- `x, y, w, h` - Position and size
-- `colW` - Array of column widths (in inches)
-- `rowH` - Array of row heights (in inches)
-- `border` - Border style: `{ pt: 1, color: "999999" }`
-- `fill` - Background color (no # prefix)
-- `align` - Text alignment: "left", "center", "right"
-- `valign` - Vertical alignment: "top", "middle", "bottom"
-- `fontSize` - Text size
-- `autoPage` - Auto-create new slides if content overflows