@shbernal/pptxgenjs 5.2.0 → 5.4.0

package/dist/units-BMrBTU0-.js

@@ -0,0 +1,106 @@
+//#region src/units.ts
+/**
+* Public unit conversion helpers and standard PowerPoint slide-layout constants.
+*/
+const EMU_PER_INCH = 914400;
+const EMU_PER_POINT = 12700;
+const POINTS_PER_INCH = 72;
+/** A bare number larger than this (in inches) is almost certainly a mistake — likely a raw EMU
+*  value passed where inches are expected. We interpret it as inches (the documented contract) but
+*  warn, pointing at the explicit `"<n>emu"` form. ~1000in is far beyond any real slide. */
+const IMPLAUSIBLE_INCHES = 1e3;
+function inchesToEmu(inches) {
+	assertFiniteNumber(inches, "inches");
+	return Math.round(inches * EMU_PER_INCH);
+}
+function pointsToEmu(points) {
+	assertFiniteNumber(points, "points");
+	return Math.round(points * EMU_PER_POINT);
+}
+function pixelsToEmu(pixels, dpi) {
+	assertFiniteNumber(pixels, "pixels");
+	assertPositiveFiniteNumber(dpi, "dpi");
+	return inchesToEmu(pixels / dpi);
+}
+/**
+* Resolve a percentage of an axis length to EMU.
+* @param percent - percentage value (e.g. `50` for 50%)
+* @param axisEmu - the axis length in EMU (slide width for x/w, height for y/h)
+*/
+function percentToEmu(percent, axisEmu) {
+	assertFiniteNumber(percent, "percent");
+	assertFiniteNumber(axisEmu, "axisEmu");
+	return Math.round(percent / 100 * axisEmu);
+}
+/**
+* The single user-coordinate → EMU boundary. Convert each user-supplied coordinate exactly once.
+*
+* Accepts (see {@link Coord}):
+* - a bare `number` → **always inches** (the documented unit); no magnitude guessing
+* - `"<n>%"` → percentage of `axisEmu`
+* - `"<n>in"` / `"<n>pt"` / `"<n>emu"` → explicit units (the escape hatch for non-inch values)
+*
+* Throws on non-finite or unparseable input rather than silently emitting a degenerate 0-size.
+* @param value - user coordinate
+* @param axisEmu - axis length in EMU, used only to resolve percentages
+*/
+function coordToEmu(value, axisEmu) {
+	if (typeof value === "number") {
+		assertFiniteNumber(value, "coordinate");
+		if (Math.abs(value) > IMPLAUSIBLE_INCHES) console.warn(`PptxGenJS: coordinate ${value} interpreted as ${value} inches. A bare number is always inches; if you meant EMU, pass it as a string like "${Math.round(value)}emu".`);
+		return inchesToEmu(value);
+	}
+	const match = /^\s*(-?\d*\.?\d+)\s*(%|in|pt|emu)\s*$/.exec(value);
+	if (!match) throw new Error(`PptxGenJS: invalid coordinate "${value}". Expected a number (inches) or a string like "50%", "5in", "72pt", or "914400emu".`);
+	const n = Number(match[1]);
+	switch (match[2]) {
+		case "%": return percentToEmu(n, axisEmu);
+		case "in": return inchesToEmu(n);
+		case "pt": return pointsToEmu(n);
+		default:
+			assertFiniteNumber(n, "coordinate");
+			return Math.round(n);
+	}
+}
+function emuToInches(emu) {
+	assertFiniteNumber(emu, "emu");
+	return emu / EMU_PER_INCH;
+}
+function emuToPoints(emu) {
+	assertFiniteNumber(emu, "emu");
+	return emu / EMU_PER_POINT;
+}
+function emuToPixels(emu, dpi) {
+	assertFiniteNumber(emu, "emu");
+	assertPositiveFiniteNumber(dpi, "dpi");
+	return Math.round(emuToInches(emu) * dpi);
+}
+function standardLayout(layout, name, widthIn, heightIn) {
+	return Object.freeze({
+		layout,
+		name,
+		width: widthIn,
+		height: heightIn,
+		widthIn,
+		heightIn,
+		widthEmu: inchesToEmu(widthIn),
+		heightEmu: inchesToEmu(heightIn)
+	});
+}
+const STANDARD_LAYOUTS = Object.freeze({
+	LAYOUT_4x3: standardLayout("LAYOUT_4x3", "screen4x3", 10, 7.5),
+	LAYOUT_16x9: standardLayout("LAYOUT_16x9", "screen16x9", 10, 5.625),
+	LAYOUT_16x10: standardLayout("LAYOUT_16x10", "screen16x10", 10, 6.25),
+	LAYOUT_WIDE: standardLayout("LAYOUT_WIDE", "custom", 40 / 3, 7.5)
+});
+function assertFiniteNumber(value, name) {
+	if (!Number.isFinite(value)) throw new Error(`${name} must be a finite number`);
+}
+function assertPositiveFiniteNumber(value, name) {
+	assertFiniteNumber(value, name);
+	if (value <= 0) throw new Error(`${name} must be greater than 0`);
+}
+//#endregion
+export { coordToEmu as a, emuToPoints as c, pixelsToEmu as d, pointsToEmu as f, STANDARD_LAYOUTS as i, inchesToEmu as l, EMU_PER_POINT as n, emuToInches as o, POINTS_PER_INCH as r, emuToPixels as s, EMU_PER_INCH as t, percentToEmu as u };
+
+//# sourceMappingURL=units-BMrBTU0-.js.map

package/dist/units-BMrBTU0-.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"units-BMrBTU0-.js","names":[],"sources":["../src/units.ts"],"sourcesContent":["/**\n * Public unit conversion helpers and standard PowerPoint slide-layout constants.\n */\n\nexport const EMU_PER_INCH = 914400\nexport const EMU_PER_POINT = 12700\nexport const POINTS_PER_INCH = 72\n\n/**\n * English Metric Units — the integer unit OOXML serializes geometry in (914400 per inch).\n *\n * Branded so a value that has already been resolved to EMU cannot be silently fed back into a\n * unit converter: {@link coordToEmu} only accepts a user `Coord`, so passing an `Emu` into it is\n * a compile-time error. This replaces the old runtime \"a number ≥ 100 must already be EMU\"\n * magnitude guess, which silently mis-rendered values near the threshold.\n */\nexport type Emu = number & { readonly __unit: 'emu' }\n\n/** A bare number larger than this (in inches) is almost certainly a mistake — likely a raw EMU\n *  value passed where inches are expected. We interpret it as inches (the documented contract) but\n *  warn, pointing at the explicit `\"<n>emu\"` form. ~1000in is far beyond any real slide. */\nconst IMPLAUSIBLE_INCHES = 1000\n\nexport type StandardLayoutName = 'LAYOUT_4x3' | 'LAYOUT_16x9' | 'LAYOUT_16x10' | 'LAYOUT_WIDE'\n\nexport interface StandardLayout {\n\t/** PptxGenJS layout key used with `pptx.layout`. */\n\treadonly layout: StandardLayoutName\n\t/** PresentationML slide-size preset name, or `custom` for PowerPoint widescreen. */\n\treadonly name: string\n\t/** Slide width in inches. Alias of {@link StandardLayout.widthIn} — inches is PptxGenJS's default coordinate unit, so this is the value to use for `addText`/`addShape` math. */\n\treadonly width: number\n\t/** Slide height in inches. Alias of {@link StandardLayout.heightIn}. */\n\treadonly height: number\n\t/** Slide width in inches. */\n\treadonly widthIn: number\n\t/** Slide height in inches. */\n\treadonly heightIn: number\n\t/** Slide width in English Metric Units. */\n\treadonly widthEmu: number\n\t/** Slide height in English Metric Units. */\n\treadonly heightEmu: number\n}\n\nexport function inchesToEmu(inches: number): Emu {\n\tassertFiniteNumber(inches, 'inches')\n\treturn Math.round(inches * EMU_PER_INCH) as Emu\n}\n\nexport function pointsToEmu(points: number): Emu {\n\tassertFiniteNumber(points, 'points')\n\treturn Math.round(points * EMU_PER_POINT) as Emu\n}\n\nexport function pixelsToEmu(pixels: number, dpi: number): Emu {\n\tassertFiniteNumber(pixels, 'pixels')\n\tassertPositiveFiniteNumber(dpi, 'dpi')\n\treturn inchesToEmu(pixels / dpi)\n}\n\n/**\n * Resolve a percentage of an axis length to EMU.\n * @param percent - percentage value (e.g. `50` for 50%)\n * @param axisEmu - the axis length in EMU (slide width for x/w, height for y/h)\n */\nexport function percentToEmu(percent: number, axisEmu: number): Emu {\n\tassertFiniteNumber(percent, 'percent')\n\tassertFiniteNumber(axisEmu, 'axisEmu')\n\treturn Math.round((percent / 100) * axisEmu) as Emu\n}\n\n/**\n * The single user-coordinate → EMU boundary. Convert each user-supplied coordinate exactly once.\n *\n * Accepts (see {@link Coord}):\n * - a bare `number` → **always inches** (the documented unit); no magnitude guessing\n * - `\"<n>%\"` → percentage of `axisEmu`\n * - `\"<n>in\"` / `\"<n>pt\"` / `\"<n>emu\"` → explicit units (the escape hatch for non-inch values)\n *\n * Throws on non-finite or unparseable input rather than silently emitting a degenerate 0-size.\n * @param value - user coordinate\n * @param axisEmu - axis length in EMU, used only to resolve percentages\n */\nexport function coordToEmu(value: number | string, axisEmu: number): Emu {\n\tif (typeof value === 'number') {\n\t\tassertFiniteNumber(value, 'coordinate')\n\t\tif (Math.abs(value) > IMPLAUSIBLE_INCHES) {\n\t\t\tconsole.warn(\n\t\t\t\t`PptxGenJS: coordinate ${value} interpreted as ${value} inches. A bare number is always inches; ` +\n\t\t\t\t\t`if you meant EMU, pass it as a string like \"${Math.round(value)}emu\".`\n\t\t\t)\n\t\t}\n\t\treturn inchesToEmu(value)\n\t}\n\n\tconst match = /^\\s*(-?\\d*\\.?\\d+)\\s*(%|in|pt|emu)\\s*$/.exec(value)\n\tif (!match) {\n\t\tthrow new Error(\n\t\t\t`PptxGenJS: invalid coordinate \"${value}\". Expected a number (inches) or a string like \"50%\", \"5in\", \"72pt\", or \"914400emu\".`\n\t\t)\n\t}\n\tconst n = Number(match[1])\n\tswitch (match[2]) {\n\t\tcase '%':\n\t\t\treturn percentToEmu(n, axisEmu)\n\t\tcase 'in':\n\t\t\treturn inchesToEmu(n)\n\t\tcase 'pt':\n\t\t\treturn pointsToEmu(n)\n\t\tdefault: // 'emu'\n\t\t\tassertFiniteNumber(n, 'coordinate')\n\t\t\treturn Math.round(n) as Emu\n\t}\n}\n\nexport function emuToInches(emu: number): number {\n\tassertFiniteNumber(emu, 'emu')\n\treturn emu / EMU_PER_INCH\n}\n\nexport function emuToPoints(emu: number): number {\n\tassertFiniteNumber(emu, 'emu')\n\treturn emu / EMU_PER_POINT\n}\n\nexport function emuToPixels(emu: number, dpi: number): number {\n\tassertFiniteNumber(emu, 'emu')\n\tassertPositiveFiniteNumber(dpi, 'dpi')\n\treturn Math.round(emuToInches(emu) * dpi)\n}\n\nfunction standardLayout(layout: StandardLayoutName, name: string, widthIn: number, heightIn: number): StandardLayout {\n\treturn Object.freeze({\n\t\tlayout,\n\t\tname,\n\t\twidth: widthIn,\n\t\theight: heightIn,\n\t\twidthIn,\n\t\theightIn,\n\t\twidthEmu: inchesToEmu(widthIn),\n\t\theightEmu: inchesToEmu(heightIn),\n\t})\n}\n\nexport const STANDARD_LAYOUTS: Readonly<Record<StandardLayoutName, StandardLayout>> = Object.freeze({\n\tLAYOUT_4x3: standardLayout('LAYOUT_4x3', 'screen4x3', 10, 7.5),\n\tLAYOUT_16x9: standardLayout('LAYOUT_16x9', 'screen16x9', 10, 5.625),\n\tLAYOUT_16x10: standardLayout('LAYOUT_16x10', 'screen16x10', 10, 6.25),\n\tLAYOUT_WIDE: standardLayout('LAYOUT_WIDE', 'custom', 40 / 3, 7.5),\n})\n\nfunction assertFiniteNumber(value: number, name: string): void {\n\tif (!Number.isFinite(value)) throw new Error(`${name} must be a finite number`)\n}\n\nfunction assertPositiveFiniteNumber(value: number, name: string): void {\n\tassertFiniteNumber(value, name)\n\tif (value <= 0) throw new Error(`${name} must be greater than 0`)\n}\n"],"mappings":";;;;AAIA,MAAa,eAAe;AAC5B,MAAa,gBAAgB;AAC7B,MAAa,kBAAkB;;;;AAe/B,MAAM,qBAAqB;AAuB3B,SAAgB,YAAY,QAAqB;CAChD,mBAAmB,QAAQ,QAAQ;CACnC,OAAO,KAAK,MAAM,SAAS,YAAY;AACxC;AAEA,SAAgB,YAAY,QAAqB;CAChD,mBAAmB,QAAQ,QAAQ;CACnC,OAAO,KAAK,MAAM,SAAS,aAAa;AACzC;AAEA,SAAgB,YAAY,QAAgB,KAAkB;CAC7D,mBAAmB,QAAQ,QAAQ;CACnC,2BAA2B,KAAK,KAAK;CACrC,OAAO,YAAY,SAAS,GAAG;AAChC;;;;;;AAOA,SAAgB,aAAa,SAAiB,SAAsB;CACnE,mBAAmB,SAAS,SAAS;CACrC,mBAAmB,SAAS,SAAS;CACrC,OAAO,KAAK,MAAO,UAAU,MAAO,OAAO;AAC5C;;;;;;;;;;;;;AAcA,SAAgB,WAAW,OAAwB,SAAsB;CACxE,IAAI,OAAO,UAAU,UAAU;EAC9B,mBAAmB,OAAO,YAAY;EACtC,IAAI,KAAK,IAAI,KAAK,IAAI,oBACrB,QAAQ,KACP,yBAAyB,MAAM,kBAAkB,MAAM,uFACP,KAAK,MAAM,KAAK,EAAE,MACnE;EAED,OAAO,YAAY,KAAK;CACzB;CAEA,MAAM,QAAQ,wCAAwC,KAAK,KAAK;CAChE,IAAI,CAAC,OACJ,MAAM,IAAI,MACT,kCAAkC,MAAM,qFACzC;CAED,MAAM,IAAI,OAAO,MAAM,EAAE;CACzB,QAAQ,MAAM,IAAd;EACC,KAAK,KACJ,OAAO,aAAa,GAAG,OAAO;EAC/B,KAAK,MACJ,OAAO,YAAY,CAAC;EACrB,KAAK,MACJ,OAAO,YAAY,CAAC;EACrB;GACC,mBAAmB,GAAG,YAAY;GAClC,OAAO,KAAK,MAAM,CAAC;CACrB;AACD;AAEA,SAAgB,YAAY,KAAqB;CAChD,mBAAmB,KAAK,KAAK;CAC7B,OAAO,MAAM;AACd;AAEA,SAAgB,YAAY,KAAqB;CAChD,mBAAmB,KAAK,KAAK;CAC7B,OAAO,MAAM;AACd;AAEA,SAAgB,YAAY,KAAa,KAAqB;CAC7D,mBAAmB,KAAK,KAAK;CAC7B,2BAA2B,KAAK,KAAK;CACrC,OAAO,KAAK,MAAM,YAAY,GAAG,IAAI,GAAG;AACzC;AAEA,SAAS,eAAe,QAA4B,MAAc,SAAiB,UAAkC;CACpH,OAAO,OAAO,OAAO;EACpB;EACA;EACA,OAAO;EACP,QAAQ;EACR;EACA;EACA,UAAU,YAAY,OAAO;EAC7B,WAAW,YAAY,QAAQ;CAChC,CAAC;AACF;AAEA,MAAa,mBAAyE,OAAO,OAAO;CACnG,YAAY,eAAe,cAAc,aAAa,IAAI,GAAG;CAC7D,aAAa,eAAe,eAAe,cAAc,IAAI,KAAK;CAClE,cAAc,eAAe,gBAAgB,eAAe,IAAI,IAAI;CACpE,aAAa,eAAe,eAAe,UAAU,KAAK,GAAG,GAAG;AACjE,CAAC;AAED,SAAS,mBAAmB,OAAe,MAAoB;CAC9D,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,MAAM,IAAI,MAAM,GAAG,KAAK,yBAAyB;AAC/E;AAEA,SAAS,2BAA2B,OAAe,MAAoB;CACtE,mBAAmB,OAAO,IAAI;CAC9B,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,GAAG,KAAK,wBAAwB;AACjE"}