h17-sspdf 0.1.7 → 0.1.8

package/DOCUMENTATION.md

@@ -169,7 +169,9 @@ Used by `divider` operations. Does not use font properties.
 
 #### Bullet marker label properties
 
-The marker label controls the bullet character's appearance.
+The marker label controls the bullet character's appearance. A marker can be either a text character or a vector shape.
+
+**Text marker** (default):
 
 | Property | Type | Description |
 |---|---|---|
@@ -180,6 +182,17 @@ The marker label controls the bullet character's appearance.
 | `lineHeight` | number | Marker line height multiplier |
 | `marker` | string | The marker character (e.g., `"-"`) |
 
+**Shape marker** (vector, no text encoding needed):
+
+| Property | Type | Description |
+|---|---|---|
+| `shape` | string | Shape name from the built-in shape library (see Vector Shapes below) |
+| `shapeColor` | [R,G,B] | Shape fill/stroke color (falls back to `color` if omitted) |
+| `shapeSize` | number | Scale factor (default: 1) |
+| `textIndentMm` | number | Gap between shape and bullet text in mm (default: 1.5, added to shape width) |
+
+When `shape` is set, the core renders a vector shape instead of a text character. The text indent is calculated as `shapeWidth + textIndentMm`. No `fontFamily`, `fontSize`, or `marker` needed.
+
 #### Table label properties
 
 Used by `table` operations. The `label` controls data cell styling, `headerLabel` controls header cell styling.
@@ -1087,6 +1100,224 @@ module.exports = {
 - Each face needs its own file - there's no automatic bold/italic synthesis
 - If you reference a font style that wasn't registered, jsPDF will throw
 
+### Font style limitations
+
+The built-in fonts ship with `Regular` and `Bold` faces only. There are no italic or bolditalic TTF files included. If you set `fontStyle: "italic"` with a built-in font, you will get:
+
+```
+Unable to look up font label for font 'Inter', 'italic'
+```
+
+To use italic text, you need a font that includes an italic TTF file, registered as a separate face in `customFonts`.
+
+---
+
+## Built-in fonts
+
+The package ships with 20 pre-embedded Google Fonts as base64-encoded TTF files. No need to convert fonts yourself.
+
+**Sans-serif:** Inter, Roboto, Open Sans, Montserrat, Lato, Raleway, Nunito, Work Sans, IBM Plex Sans, PT Sans, Oswald
+
+**Serif:** Merriweather, Lora, Playfair Display, Crimson Text, Libre Baskerville, Source Serif 4
+
+**Monospace:** Fira Code, JetBrains Mono, Source Code Pro
+
+### Usage
+
+```js
+const INTER = require("h17-sspdf/fonts/inter.js");
+
+module.exports = {
+  name: "My Theme",
+
+  customFonts: [
+    {
+      family: "Inter",
+      faces: [
+        { style: "normal", fileName: "Inter-Regular.ttf", data: INTER.Regular },
+        { style: "bold", fileName: "Inter-Bold.ttf", data: INTER.Bold },
+      ],
+    },
+  ],
+
+  // now use fontFamily: "Inter" in any label
+  labels: {
+    "doc.body": {
+      fontFamily: "Inter",
+      fontStyle: "normal",
+      fontSize: 10,
+      color: [40, 40, 40],
+      lineHeight: 1.4,
+    },
+  },
+};
+```
+
+The exported properties are `Regular` and `Bold` (capitalized). Every built-in font file exports these two keys.
+
+### Available font files
+
+| Font | Require path |
+|---|---|
+| Inter | `h17-sspdf/fonts/inter.js` |
+| Roboto | `h17-sspdf/fonts/roboto.js` |
+| Open Sans | `h17-sspdf/fonts/open-sans.js` |
+| Montserrat | `h17-sspdf/fonts/montserrat.js` |
+| Lato | `h17-sspdf/fonts/lato.js` |
+| Raleway | `h17-sspdf/fonts/raleway.js` |
+| Nunito | `h17-sspdf/fonts/nunito.js` |
+| Work Sans | `h17-sspdf/fonts/work-sans.js` |
+| IBM Plex Sans | `h17-sspdf/fonts/ibm-plex-sans.js` |
+| PT Sans | `h17-sspdf/fonts/pt-sans.js` |
+| Oswald | `h17-sspdf/fonts/oswald.js` |
+| Merriweather | `h17-sspdf/fonts/merriweather.js` |
+| Lora | `h17-sspdf/fonts/lora.js` |
+| Playfair Display | `h17-sspdf/fonts/playfair-display.js` |
+| Crimson Text | `h17-sspdf/fonts/crimson-text.js` |
+| Libre Baskerville | `h17-sspdf/fonts/libre-baskerville.js` |
+| Source Serif 4 | `h17-sspdf/fonts/source-serif-4.js` |
+| Fira Code | `h17-sspdf/fonts/fira-code.js` |
+| JetBrains Mono | `h17-sspdf/fonts/jetbrains-mono.js` |
+| Source Code Pro | `h17-sspdf/fonts/source-code-pro.js` |
+
+You can also list available fonts from the CLI:
+
+```bash
+npx h17-sspdf --fonts
+```
+
+---
+
+## Vector shapes
+
+The engine includes 20 vector shapes rendered directly via jsPDF drawing primitives. These bypass text encoding entirely, so they work regardless of font or character support.
+
+### Available shapes
+
+**Bullets:** `arrow`, `circle`, `square`, `diamond`, `triangle`, `dash`, `chevron`
+
+**Decorators:** `doubleColon`, `commentSlash`, `hashComment`, `bracketChevron`, `treeBranch`, `terminalPrompt`
+
+**Symbols:** `checkmark`, `cross`, `star`, `plus`, `minus`, `warning`, `infoCircle`
+
+### Using shapes as bullet markers
+
+Shapes work through the existing `bullet` operation. The theme label decides whether the marker is text or a vector shape. The source JSON does not change.
+
+**Theme:**
+
+```js
+labels: {
+  "doc.marker.arrow": {
+    shape: "arrow",
+    shapeColor: [0, 128, 255],
+    shapeSize: 0.8,
+    textIndentMm: 2,
+  },
+  "doc.body": {
+    fontFamily: "helvetica",
+    fontStyle: "normal",
+    fontSize: 10,
+    color: [40, 40, 40],
+    lineHeight: 1.4,
+  },
+}
+```
+
+**Source:**
+
+```json
+{
+  "type": "bullet",
+  "label": "doc.body",
+  "markerLabel": "doc.marker.arrow",
+  "bullets": ["First point", "Second point"]
+}
+```
+
+The core calculates the text indent from the shape's known width (defined in `core/shapes.js`) plus the label's `textIndentMm`. All positioning is exact, derived from the shape width constants.
+
+### Programmatic usage
+
+For custom plugins or advanced rendering, shapes can be called directly:
+
+```js
+const { renderShape, getShapeWidth } = require("h17-sspdf/core/shapes");
+
+// Draw a shape at position (x, y) aligned to text baseline
+renderShape("arrow", doc, x, baseline, [0, 128, 255], 0.8, fontSize);
+
+// Get the shape's width in mm for spacing calculations
+const widthMm = getShapeWidth("arrow", 0.8);
+```
+
+Parameters: `renderShape(name, doc, x, y, color, size, fontSizePt)`
+
+The shape centers vertically at half the font height above the baseline, so it aligns with adjacent text.
+
+---
+
+## Colors
+
+All colors in the engine are RGB arrays with values 0-255:
+
+```js
+color: [255, 0, 128],              // pink
+backgroundColor: [18, 18, 26],     // dark background
+borderColor: [200, 200, 200],      // light gray border
+```
+
+Common values:
+- White: `[255, 255, 255]`
+- Black: `[0, 0, 0]`
+- Gray: `[128, 128, 128]`
+
+This applies to all color properties: `color`, `backgroundColor`, `borderColor`, `altRowColor`, `shapeColor`, and all per-edge border color overrides.
+
+---
+
+## Operation quick reference
+
+| Type | Required fields | Optional fields |
+|---|---|---|
+| `text` | `label`, `text` | `align`, `keepWithNext`, `wrap`, `advance` |
+| `row` | `leftLabel`, `rightLabel`, `leftText`, `rightText` | `xLeftMm`, `xRightMm` |
+| `bullet` | `label`, `text`/`items`/`bullets` | `markerLabel`, `marker`, `textIndentMm` |
+| `divider` | `label` | `x1Mm`, `x2Mm` |
+| `table` | `label`, `columns`, `rows` | `headerLabel`, `xMm`, `maxWidthMm`, border/padding overrides |
+| `spacer` | `mm` or `px` or `label` | - |
+| `block` | `children`/`content`/`items` | `label`, `keepTogether`, `spaceAfterMm`/`Px`/`Label` |
+| `section` | `content` | `label`, `keepTogether` |
+| `quote` | `label`, `text` | `attribution`, `attributionLabel` |
+| `hiddenText` | `label`, `text` | - |
+
+Every operation also accepts `xMm` and `maxWidthMm` to override the theme margins for that operation only.
+
+---
+
+## Table labels pattern
+
+For tables, define two labels: one for data cells, one for headers. The shared constants file `examples/themes/table.js` provides base styles you can spread and override:
+
+```js
+const table = require("h17-sspdf/examples/themes/table");
+
+labels: {
+  "report.table.cell": {
+    ...table.cell,
+    color: [51, 65, 85],
+    altRowColor: [248, 249, 252],
+  },
+  "report.table.header": {
+    ...table.header,
+    backgroundColor: [55, 65, 81],
+    color: [255, 255, 255],
+  },
+}
+```
+
+The spread gives you sensible defaults for `cellPaddingMm`, `borderColor`, border widths, `altRowColor`, and font settings. Override the properties you want to customize.
+
 ---
 
 ## Common patterns

package/README.md

@@ -320,23 +320,69 @@ Any operation accepts `xMm` and `maxWidthMm` to override the theme margins for t
 
 ---
 
+## Built-in fonts
+
+20 Google Fonts ship with the package as base64 TTF. Each exports `{ Regular, Bold }`.
+
+**Sans-serif:** Inter, Roboto, Open Sans, Montserrat, Lato, Raleway, Nunito, Work Sans, IBM Plex Sans, PT Sans, Oswald
+
+**Serif:** Merriweather, Lora, Playfair Display, Crimson Text, Libre Baskerville, Source Serif 4
+
+**Monospace:** Fira Code, JetBrains Mono, Source Code Pro
+
+```js
+const INTER = require('h17-sspdf/fonts/inter.js');
+
+customFonts: [{
+  family: 'Inter',
+  faces: [
+    { style: 'normal', fileName: 'Inter-Regular.ttf', data: INTER.Regular },
+    { style: 'bold',   fileName: 'Inter-Bold.ttf',    data: INTER.Bold },
+  ],
+}],
+```
+
+List all fonts: `npx h17-sspdf --fonts`
+
+---
+
+## Vector shapes
+
+20 built-in vector shapes rendered via jsPDF drawing primitives. No text encoding, no font dependencies.
+
+Use as bullet markers by setting `shape` on a marker label:
+
+```js
+// Theme
+'bullet.arrow': { shape: 'arrow', shapeColor: [0, 128, 255], shapeSize: 0.8 }
+
+// Source JSON (same bullet operation as always)
+{ "type": "bullet", "label": "doc.body", "markerLabel": "bullet.arrow", "bullets": ["Point one"] }
+```
+
+Available: `arrow`, `circle`, `square`, `diamond`, `triangle`, `dash`, `chevron`, `doubleColon`, `commentSlash`, `hashComment`, `bracketChevron`, `treeBranch`, `terminalPrompt`, `checkmark`, `cross`, `star`, `plus`, `minus`, `warning`, `infoCircle`
+
+List all shapes: `npx h17-sspdf --shapes`
+
+---
+
 ## Custom fonts
 
-Embed TTF as base64 and register in the theme:
+Embed your own TTF as base64 and register in the theme:
 
 ```js
 customFonts: [
   {
-    family: 'Inter',
+    family: 'MyFont',
     faces: [
-      { style: 'normal', fileName: 'Inter-Regular.ttf', data: '<base64>' },
-      { style: 'bold',   fileName: 'Inter-Bold.ttf',    data: '<base64>' },
+      { style: 'normal', fileName: 'MyFont-Regular.ttf', data: '<base64>' },
+      { style: 'bold',   fileName: 'MyFont-Bold.ttf',    data: '<base64>' },
     ],
   },
 ],
 ```
 
-Then use `fontFamily: 'Inter'` in any label.
+Then use `fontFamily: 'MyFont'` in any label.
 
 ---
 
@@ -394,14 +440,26 @@ registerPlugin('chart', plugins.chart);
 ## CLI
 
 ```bash
-npx sspdf -s source.json -t theme.js -o output.pdf
+npx h17-sspdf -s source.json -t theme.js -o output.pdf
 ```
 
 | Flag | Short | Description |
 |------|-------|-------------|
 | `--source` | `-s` | Path to source JSON (or pipe via stdin) |
-| `--theme` | `-t` | Path to theme `.js` file |
+| `--theme` | `-t` | Path to theme `.js` file or built-in name |
 | `--output` | `-o` | Output PDF path |
+| `--fonts` | | List built-in fonts |
+| `--shapes` | | List built-in vector shapes |
+| `--help` | `-h` | Show help |
+
+---
+
+## AI skills
+
+Claude Code skills for generating PDFs and themes are available in the `skills/` directory of the [GitHub repository](https://github.com/hugopalma17/sspdf):
+
+- `skills/sspdf/` - Generate PDF documents from a task description
+- `skills/sspdf-theme-generator/` - Generate theme files from brand specs
 
 ---
 

package/cli.js

@@ -7,7 +7,7 @@ const { renderDocument, registerPlugin, plugins } = require("./index");
 const EXAMPLES_THEMES_DIR = path.join(__dirname, "examples", "themes");
 
 function parseArgs(argv) {
-  const out = { source: null, theme: null, output: null, help: false };
+  const out = { source: null, theme: null, output: null, help: false, fonts: false, shapes: false };
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -19,6 +19,10 @@ function parseArgs(argv) {
       out.output = argv[++i];
     } else if (arg === "--help" || arg === "-h") {
       out.help = true;
+    } else if (arg === "--fonts") {
+      out.fonts = true;
+    } else if (arg === "--shapes") {
+      out.shapes = true;
     } else {
       throw new Error(`Unknown argument: ${arg}`);
     }
@@ -81,6 +85,43 @@ function readSource(sourcePath) {
   return JSON.parse(raw);
 }
 
+function listBuiltInFonts() {
+  const fontsDir = path.join(__dirname, "fonts");
+  try {
+    return fs.readdirSync(fontsDir)
+      .filter((f) => f.endsWith(".js"))
+      .map((f) => f.replace(".js", ""))
+      .sort();
+  } catch (e) {
+    return [];
+  }
+}
+
+function printFonts() {
+  const fonts = listBuiltInFonts();
+  if (fonts.length === 0) {
+    console.log("No built-in fonts found.");
+    return;
+  }
+  console.log(`Built-in fonts (${fonts.length}):\n`);
+  for (const font of fonts) {
+    console.log(`  ${font.padEnd(22)} require("h17-sspdf/fonts/${font}.js")`);
+  }
+  console.log(`\nEach font exports { Regular, Bold } as base64 strings.`);
+  console.log(`See DOCUMENTATION.md "Built-in fonts" for usage.`);
+}
+
+function printShapes() {
+  const { shapeWidths } = require("./core/shapes");
+  const names = Object.keys(shapeWidths);
+  console.log(`Built-in shapes (${names.length}):\n`);
+  console.log("  Bullets:    arrow, circle, square, diamond, triangle, dash, chevron");
+  console.log("  Decorators: doubleColon, commentSlash, hashComment, bracketChevron, treeBranch, terminalPrompt");
+  console.log("  Symbols:    checkmark, cross, star, plus, minus, warning, infoCircle");
+  console.log(`\nUse as marker labels: { shape: "arrow", shapeColor: [0,0,0], shapeSize: 1 }`);
+  console.log(`See DOCUMENTATION.md "Vector shapes" for usage.`);
+}
+
 function printHelp() {
   const themes = listBuiltInThemes();
   console.log(`
@@ -95,6 +136,8 @@ Options:
   -t, --theme <name|path>  Built-in theme name or path to a .js theme file
   -o, --output <path>   Output PDF path (default: output/cli-output.pdf)
   -h, --help            Show this help
+  --fonts               List built-in fonts
+  --shapes              List built-in vector shapes
 
 Built-in themes: ${themes.join(", ")}
 
@@ -129,6 +172,14 @@ async function main() {
     printHelp();
     return;
   }
+  if (args.fonts) {
+    printFonts();
+    return;
+  }
+  if (args.shapes) {
+    printShapes();
+    return;
+  }
 
   const source = readSource(args.source);
   const theme = resolveTheme(args.theme);

package/core/pdf-core.js

@@ -493,8 +493,18 @@ class PDFCore {
     );
     const baseline = y + baselineOffsetMm;
 
-    this.applyTextStyle(markerStyle);
-    this.doc.text(String(marker), x, baseline);
+    if (markerStyle.shape) {
+      // Vector shape marker: renders via core/shapes.js, no text encoding needed
+      const { renderShape, getShapeWidth } = require("./shapes");
+      const shapeColor = markerStyle.shapeColor || markerStyle.color || [0, 0, 0];
+      const shapeSize = markerStyle.shapeSize || 1;
+      renderShape(markerStyle.shape, this.doc, x, baseline, shapeColor, shapeSize, textFontSize);
+      this.applyDefaultRenderState();
+    } else {
+      // Text-based marker (existing behavior)
+      this.applyTextStyle(markerStyle);
+      this.doc.text(String(marker), x, baseline);
+    }
 
     this.applyTextStyle(textStyle);
     this.doc.setLineHeightFactor(Number(textStyle.lineHeight));

package/core/render-document.js

@@ -603,9 +603,18 @@ function executeOperation(ctx) {
     const defaultX = bounds.left;
     const x = operation.xMm !== undefined ? operation.xMm : defaultX;
     validatePointInsideBounds("xMm", x, bounds, index, templateBypassMargins);
-    const textIndentMm = operation.textIndentMm !== undefined
-      ? operation.textIndentMm
-      : (theme.layout && Number(theme.layout.bulletIndentMm)) || 4;
+    let textIndentMm;
+    if (operation.textIndentMm !== undefined) {
+      textIndentMm = operation.textIndentMm;
+    } else if (markerStyle && markerStyle.shape) {
+      const { getShapeWidth } = require("./shapes");
+      const shapeW = getShapeWidth(markerStyle.shape, markerStyle.shapeSize || 1);
+      textIndentMm = shapeW + (markerStyle.textIndentMm !== undefined ? markerStyle.textIndentMm : 1.5);
+    } else if (markerStyle && markerStyle.textIndentMm !== undefined) {
+      textIndentMm = markerStyle.textIndentMm;
+    } else {
+      textIndentMm = (theme.layout && Number(theme.layout.bulletIndentMm)) || 4;
+    }
     const rightBoundary = bounds.right;
     const maxWidth = operation.maxWidthMm !== undefined
       ? operation.maxWidthMm
@@ -833,10 +842,20 @@ function estimateOperationHeight(ctx) {
 
   if (operation.type === "bullet") {
     const style = resolveLabelStyle(theme, operation.label, operation, index);
+    const markerEstStyle = resolveLabelStyle(theme, operation.markerLabel || "bullet.marker", operation, index, "markerLabel", true);
     const x = operation.xMm !== undefined ? operation.xMm : core.marginLeftMm;
-    const textIndentMm = operation.textIndentMm !== undefined
-      ? operation.textIndentMm
-      : (theme.layout && Number(theme.layout.bulletIndentMm)) || 4;
+    let textIndentMm;
+    if (operation.textIndentMm !== undefined) {
+      textIndentMm = operation.textIndentMm;
+    } else if (markerEstStyle && markerEstStyle.shape) {
+      const { getShapeWidth } = require("./shapes");
+      const shapeW = getShapeWidth(markerEstStyle.shape, markerEstStyle.shapeSize || 1);
+      textIndentMm = shapeW + (markerEstStyle.textIndentMm !== undefined ? markerEstStyle.textIndentMm : 1.5);
+    } else if (markerEstStyle && markerEstStyle.textIndentMm !== undefined) {
+      textIndentMm = markerEstStyle.textIndentMm;
+    } else {
+      textIndentMm = (theme.layout && Number(theme.layout.bulletIndentMm)) || 4;
+    }
     const maxWidth = operation.maxWidthMm !== undefined
       ? operation.maxWidthMm
       : core.pageWidth - core.marginRightMm - (x + textIndentMm);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h17-sspdf",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Declarative PDF engine - define layout once, feed it JSON, get consistent PDFs",
   "main": "index.js",
   "author": "Hugo Palma",