av6-pdf-engine 3.0.0 → 3.0.1

package/dist/index.d.mts

@@ -612,4 +612,78 @@ declare function watermarkUsesLast(mode?: WatermarkMode): boolean;
  */
 declare function drawWatermarkForPage(doc: PDFDoc, watermark: WatermarkDef, pageNumber: number, isLast: boolean): void;
 
-export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BlockRendererDeps, type BottomLimitForContentFn, type BoxSpacing, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type EnsureSpaceForFn, type FinishPageParams, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type ListBlock, type ListItem, type ListStyle, type MeasureBlockHeightFn, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineError, PdfEngineErrorCode, type PlacedCell, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderBlockArrayFn, type RenderEnv, type ResolvedSpacing, type ShapeBlock, type ShapePoint, type ShapeType, type SignatureBlock, type SpacingInput, type StyleDef, type StyleRef, type TableBlock, type TableBodyIterable, type TableBorderSide, type TableBorderStyle, type TableCell, type TableCellBorder, type TableColumnStyle, type TableRowStyle, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, computeColumnPixelWidths, contentEnv, createBlockRenderer, createBottomLimitForContent, createEnsureSpaceFor, createInitialContext, createMeasureBlockHeight, createProcessSignatureBlock, createStartNewPageLayout, drawFooter, drawHeader, drawPageBackground, drawSignatureBlock, drawStyledText, drawWatermarkForPage, finishPage, generateBarcodeBuffer, generateQrBuffer, getBottomLimitForContent, getFontNameForText, hasPadding, images, isPdfEngineError, mapBarcodeTypeToBcid, materializeImagesInBlocks, materializeQrAndBarcodesInBlocks, mergeStyleDefs, normalizeImageSrc, renderCustomPdf, renderCustomPdfToBuffer, resolveBlockPadding, resolveFooterPadding, resolveHeaderPadding, resolveSpacing, resolveTableCell, resolveTextBlock, toPdfEngineError, watermarkUsesLast };
+interface PieChartOptions {
+    /** X coordinate of the circle center. Default: 55 */
+    cx?: number;
+    /** Y coordinate of the circle center. Default: 55 */
+    cy?: number;
+    /** Circle radius in points. Default: 50 */
+    radius?: number;
+}
+/**
+ * Builds an SVG arc path for a pie-slice segment.
+ * The slice starts at 12 o'clock and sweeps clockwise.
+ *
+ * Use the returned string as the `path` property on a shape block
+ * with `shape: "path"`.
+ *
+ * @param percent - Filled portion, 0–100
+ * @param options - Circle geometry (defaults match the 110×110 pt donut in the assessment template)
+ *
+ * @example
+ * buildPieSlicePath(75)
+ * // "M 55 55 L 55.0 5.0 A 50 50 0 1 1 105.0 55.0 Z"
+ *
+ * buildPieSlicePath(55, { cx: 55, cy: 55, radius: 50 })
+ * // "M 55 55 L 55.0 5.0 A 50 50 0 1 1 39.6 102.6 Z"
+ */
+declare function buildPieSlicePath(percent: number, options?: PieChartOptions): string;
+interface PieDataInput {
+    obtained: number;
+    total: number;
+}
+interface PieDataResult {
+    /** Marks / score obtained */
+    obtained: number;
+    /** Total / full score */
+    total: number;
+    /** Remaining = total − obtained */
+    remaining: number;
+    /** Rounded percentage 0–100 */
+    percentage: number;
+    /** SVG path string for the filled slice */
+    piePath: string;
+}
+/**
+ * Computes all values needed to render a pie/donut score chart.
+ * Works for any obtained-out-of-total scenario — marks, ratings, progress, etc.
+ *
+ * Pass the returned fields to your substitution service so placeholders like
+ * `{{marks.piePath}}`, `{{marks.percentage}}`, `{{marks.remaining}}` resolve correctly.
+ *
+ * @example
+ * calcPieData({ obtained: 55, total: 100 })
+ * // { obtained: 55, total: 100, remaining: 45, percentage: 55, piePath: "M 55 55 ..." }
+ */
+declare function calcPieData(input: PieDataInput, options?: PieChartOptions): PieDataResult;
+interface PercentagePieResult {
+    /** Rounded percentage 0–100 */
+    percentage: number;
+    /** Complement = 100 − percentage */
+    remaining: number;
+    /** SVG path string for the filled slice */
+    piePath: string;
+}
+/**
+ * Builds pie chart fields when you already have a percentage (0–100).
+ * Use for strengths/weaknesses scores, skill ratings, progress, etc.
+ *
+ * @example
+ * calcPercentagePie(72, { cx: 50, cy: 50, radius: 42 })
+ * // { percentage: 72, remaining: 28, piePath: "M 50 50 ..." }
+ */
+declare function calcPercentagePie(percentage: number, options?: PieChartOptions): PercentagePieResult;
+/** Default geometry for the 100×100 pt donut charts in the assessment template. */
+declare const DEFAULT_PIE_OPTIONS: PieChartOptions;
+
+export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BlockRendererDeps, type BottomLimitForContentFn, type BoxSpacing, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, DEFAULT_PIE_OPTIONS, type EnsureSpaceForFn, type FinishPageParams, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type ListBlock, type ListItem, type ListStyle, type MeasureBlockHeightFn, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineError, PdfEngineErrorCode, type PercentagePieResult, type PieChartOptions, type PieDataInput, type PieDataResult, type PlacedCell, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderBlockArrayFn, type RenderEnv, type ResolvedSpacing, type ShapeBlock, type ShapePoint, type ShapeType, type SignatureBlock, type SpacingInput, type StyleDef, type StyleRef, type TableBlock, type TableBodyIterable, type TableBorderSide, type TableBorderStyle, type TableCell, type TableCellBorder, type TableColumnStyle, type TableRowStyle, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, buildPieSlicePath, calcPercentagePie, calcPieData, computeColumnPixelWidths, contentEnv, createBlockRenderer, createBottomLimitForContent, createEnsureSpaceFor, createInitialContext, createMeasureBlockHeight, createProcessSignatureBlock, createStartNewPageLayout, drawFooter, drawHeader, drawPageBackground, drawSignatureBlock, drawStyledText, drawWatermarkForPage, finishPage, generateBarcodeBuffer, generateQrBuffer, getBottomLimitForContent, getFontNameForText, hasPadding, images, isPdfEngineError, mapBarcodeTypeToBcid, materializeImagesInBlocks, materializeQrAndBarcodesInBlocks, mergeStyleDefs, normalizeImageSrc, renderCustomPdf, renderCustomPdfToBuffer, resolveBlockPadding, resolveFooterPadding, resolveHeaderPadding, resolveSpacing, resolveTableCell, resolveTextBlock, toPdfEngineError, watermarkUsesLast };

package/dist/index.d.ts

@@ -612,4 +612,78 @@ declare function watermarkUsesLast(mode?: WatermarkMode): boolean;
  */
 declare function drawWatermarkForPage(doc: PDFDoc, watermark: WatermarkDef, pageNumber: number, isLast: boolean): void;
 
-export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BlockRendererDeps, type BottomLimitForContentFn, type BoxSpacing, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type EnsureSpaceForFn, type FinishPageParams, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type ListBlock, type ListItem, type ListStyle, type MeasureBlockHeightFn, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineError, PdfEngineErrorCode, type PlacedCell, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderBlockArrayFn, type RenderEnv, type ResolvedSpacing, type ShapeBlock, type ShapePoint, type ShapeType, type SignatureBlock, type SpacingInput, type StyleDef, type StyleRef, type TableBlock, type TableBodyIterable, type TableBorderSide, type TableBorderStyle, type TableCell, type TableCellBorder, type TableColumnStyle, type TableRowStyle, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, computeColumnPixelWidths, contentEnv, createBlockRenderer, createBottomLimitForContent, createEnsureSpaceFor, createInitialContext, createMeasureBlockHeight, createProcessSignatureBlock, createStartNewPageLayout, drawFooter, drawHeader, drawPageBackground, drawSignatureBlock, drawStyledText, drawWatermarkForPage, finishPage, generateBarcodeBuffer, generateQrBuffer, getBottomLimitForContent, getFontNameForText, hasPadding, images, isPdfEngineError, mapBarcodeTypeToBcid, materializeImagesInBlocks, materializeQrAndBarcodesInBlocks, mergeStyleDefs, normalizeImageSrc, renderCustomPdf, renderCustomPdfToBuffer, resolveBlockPadding, resolveFooterPadding, resolveHeaderPadding, resolveSpacing, resolveTableCell, resolveTextBlock, toPdfEngineError, watermarkUsesLast };
+interface PieChartOptions {
+    /** X coordinate of the circle center. Default: 55 */
+    cx?: number;
+    /** Y coordinate of the circle center. Default: 55 */
+    cy?: number;
+    /** Circle radius in points. Default: 50 */
+    radius?: number;
+}
+/**
+ * Builds an SVG arc path for a pie-slice segment.
+ * The slice starts at 12 o'clock and sweeps clockwise.
+ *
+ * Use the returned string as the `path` property on a shape block
+ * with `shape: "path"`.
+ *
+ * @param percent - Filled portion, 0–100
+ * @param options - Circle geometry (defaults match the 110×110 pt donut in the assessment template)
+ *
+ * @example
+ * buildPieSlicePath(75)
+ * // "M 55 55 L 55.0 5.0 A 50 50 0 1 1 105.0 55.0 Z"
+ *
+ * buildPieSlicePath(55, { cx: 55, cy: 55, radius: 50 })
+ * // "M 55 55 L 55.0 5.0 A 50 50 0 1 1 39.6 102.6 Z"
+ */
+declare function buildPieSlicePath(percent: number, options?: PieChartOptions): string;
+interface PieDataInput {
+    obtained: number;
+    total: number;
+}
+interface PieDataResult {
+    /** Marks / score obtained */
+    obtained: number;
+    /** Total / full score */
+    total: number;
+    /** Remaining = total − obtained */
+    remaining: number;
+    /** Rounded percentage 0–100 */
+    percentage: number;
+    /** SVG path string for the filled slice */
+    piePath: string;
+}
+/**
+ * Computes all values needed to render a pie/donut score chart.
+ * Works for any obtained-out-of-total scenario — marks, ratings, progress, etc.
+ *
+ * Pass the returned fields to your substitution service so placeholders like
+ * `{{marks.piePath}}`, `{{marks.percentage}}`, `{{marks.remaining}}` resolve correctly.
+ *
+ * @example
+ * calcPieData({ obtained: 55, total: 100 })
+ * // { obtained: 55, total: 100, remaining: 45, percentage: 55, piePath: "M 55 55 ..." }
+ */
+declare function calcPieData(input: PieDataInput, options?: PieChartOptions): PieDataResult;
+interface PercentagePieResult {
+    /** Rounded percentage 0–100 */
+    percentage: number;
+    /** Complement = 100 − percentage */
+    remaining: number;
+    /** SVG path string for the filled slice */
+    piePath: string;
+}
+/**
+ * Builds pie chart fields when you already have a percentage (0–100).
+ * Use for strengths/weaknesses scores, skill ratings, progress, etc.
+ *
+ * @example
+ * calcPercentagePie(72, { cx: 50, cy: 50, radius: 42 })
+ * // { percentage: 72, remaining: 28, piePath: "M 50 50 ..." }
+ */
+declare function calcPercentagePie(percentage: number, options?: PieChartOptions): PercentagePieResult;
+/** Default geometry for the 100×100 pt donut charts in the assessment template. */
+declare const DEFAULT_PIE_OPTIONS: PieChartOptions;
+
+export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BlockRendererDeps, type BottomLimitForContentFn, type BoxSpacing, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, DEFAULT_PIE_OPTIONS, type EnsureSpaceForFn, type FinishPageParams, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type ListBlock, type ListItem, type ListStyle, type MeasureBlockHeightFn, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineError, PdfEngineErrorCode, type PercentagePieResult, type PieChartOptions, type PieDataInput, type PieDataResult, type PlacedCell, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderBlockArrayFn, type RenderEnv, type ResolvedSpacing, type ShapeBlock, type ShapePoint, type ShapeType, type SignatureBlock, type SpacingInput, type StyleDef, type StyleRef, type TableBlock, type TableBodyIterable, type TableBorderSide, type TableBorderStyle, type TableCell, type TableCellBorder, type TableColumnStyle, type TableRowStyle, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, buildPieSlicePath, calcPercentagePie, calcPieData, computeColumnPixelWidths, contentEnv, createBlockRenderer, createBottomLimitForContent, createEnsureSpaceFor, createInitialContext, createMeasureBlockHeight, createProcessSignatureBlock, createStartNewPageLayout, drawFooter, drawHeader, drawPageBackground, drawSignatureBlock, drawStyledText, drawWatermarkForPage, finishPage, generateBarcodeBuffer, generateQrBuffer, getBottomLimitForContent, getFontNameForText, hasPadding, images, isPdfEngineError, mapBarcodeTypeToBcid, materializeImagesInBlocks, materializeQrAndBarcodesInBlocks, mergeStyleDefs, normalizeImageSrc, renderCustomPdf, renderCustomPdfToBuffer, resolveBlockPadding, resolveFooterPadding, resolveHeaderPadding, resolveSpacing, resolveTableCell, resolveTextBlock, toPdfEngineError, watermarkUsesLast };

package/dist/index.js

@@ -31,9 +31,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BARCODE_TYPES: () => BARCODE_TYPES,
+  DEFAULT_PIE_OPTIONS: () => DEFAULT_PIE_OPTIONS,
   PdfEngineError: () => PdfEngineError,
   PdfEngineErrorCode: () => PdfEngineErrorCode,
   QR_ERROR_LEVEL: () => QR_ERROR_LEVEL,
+  buildPieSlicePath: () => buildPieSlicePath,
+  calcPercentagePie: () => calcPercentagePie,
+  calcPieData: () => calcPieData,
   computeColumnPixelWidths: () => computeColumnPixelWidths,
   contentEnv: () => contentEnv,
   createBlockRenderer: () => createBlockRenderer,
@@ -2906,12 +2910,58 @@ async function renderCustomPdfToBuffer(def) {
     runRender(doc, def, fallbackImage);
   });
 }
+
+// src/utils/pie-chart.ts
+function buildPieSlicePath(percent, options = {}) {
+  const { cx = 55, cy = 55, radius: r = 50 } = options;
+  const p = Math.max(0, Math.min(100, Number(percent) || 0));
+  if (p <= 0) return "";
+  if (p >= 100) {
+    return `M ${cx} ${cy} L ${cx} ${cy - r} A ${r} ${r} 0 1 1 ${(cx - 0.01).toFixed(2)} ${cy - r} Z`;
+  }
+  const startAngle = -Math.PI / 2;
+  const endAngle = startAngle + p / 100 * 2 * Math.PI;
+  const x1 = cx;
+  const y1 = cy - r;
+  const x2 = cx + r * Math.cos(endAngle);
+  const y2 = cy + r * Math.sin(endAngle);
+  const largeArc = p > 50 ? 1 : 0;
+  return `M ${cx} ${cy} L ${x1.toFixed(1)} ${y1.toFixed(1)} A ${r} ${r} 0 ${largeArc} 1 ${x2.toFixed(1)} ${y2.toFixed(1)} Z`;
+}
+function calcPieData(input, options = {}) {
+  const { obtained, total } = input;
+  if (!Number.isFinite(total) || !Number.isFinite(obtained) || total <= 0) {
+    throw new Error(`calcPieData: "total" must be a positive finite number, got ${total}`);
+  }
+  const percentage = Math.round(obtained / total * 100);
+  const remaining = Math.max(0, total - obtained);
+  return {
+    obtained,
+    total,
+    remaining,
+    percentage,
+    piePath: buildPieSlicePath(percentage, options)
+  };
+}
+function calcPercentagePie(percentage, options = {}) {
+  const p = Math.max(0, Math.min(100, Math.round(Number(percentage) || 0)));
+  return {
+    percentage: p,
+    remaining: 100 - p,
+    piePath: buildPieSlicePath(p, options)
+  };
+}
+var DEFAULT_PIE_OPTIONS = { cx: 50, cy: 50, radius: 42 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BARCODE_TYPES,
+  DEFAULT_PIE_OPTIONS,
   PdfEngineError,
   PdfEngineErrorCode,
   QR_ERROR_LEVEL,
+  buildPieSlicePath,
+  calcPercentagePie,
+  calcPieData,
   computeColumnPixelWidths,
   contentEnv,
   createBlockRenderer,

package/dist/index.mjs

@@ -2829,11 +2829,57 @@ async function renderCustomPdfToBuffer(def) {
     runRender(doc, def, fallbackImage);
   });
 }
+
+// src/utils/pie-chart.ts
+function buildPieSlicePath(percent, options = {}) {
+  const { cx = 55, cy = 55, radius: r = 50 } = options;
+  const p = Math.max(0, Math.min(100, Number(percent) || 0));
+  if (p <= 0) return "";
+  if (p >= 100) {
+    return `M ${cx} ${cy} L ${cx} ${cy - r} A ${r} ${r} 0 1 1 ${(cx - 0.01).toFixed(2)} ${cy - r} Z`;
+  }
+  const startAngle = -Math.PI / 2;
+  const endAngle = startAngle + p / 100 * 2 * Math.PI;
+  const x1 = cx;
+  const y1 = cy - r;
+  const x2 = cx + r * Math.cos(endAngle);
+  const y2 = cy + r * Math.sin(endAngle);
+  const largeArc = p > 50 ? 1 : 0;
+  return `M ${cx} ${cy} L ${x1.toFixed(1)} ${y1.toFixed(1)} A ${r} ${r} 0 ${largeArc} 1 ${x2.toFixed(1)} ${y2.toFixed(1)} Z`;
+}
+function calcPieData(input, options = {}) {
+  const { obtained, total } = input;
+  if (!Number.isFinite(total) || !Number.isFinite(obtained) || total <= 0) {
+    throw new Error(`calcPieData: "total" must be a positive finite number, got ${total}`);
+  }
+  const percentage = Math.round(obtained / total * 100);
+  const remaining = Math.max(0, total - obtained);
+  return {
+    obtained,
+    total,
+    remaining,
+    percentage,
+    piePath: buildPieSlicePath(percentage, options)
+  };
+}
+function calcPercentagePie(percentage, options = {}) {
+  const p = Math.max(0, Math.min(100, Math.round(Number(percentage) || 0)));
+  return {
+    percentage: p,
+    remaining: 100 - p,
+    piePath: buildPieSlicePath(p, options)
+  };
+}
+var DEFAULT_PIE_OPTIONS = { cx: 50, cy: 50, radius: 42 };
 export {
   BARCODE_TYPES,
+  DEFAULT_PIE_OPTIONS,
   PdfEngineError,
   PdfEngineErrorCode,
   QR_ERROR_LEVEL,
+  buildPieSlicePath,
+  calcPercentagePie,
+  calcPieData,
   computeColumnPixelWidths,
   contentEnv,
   createBlockRenderer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "av6-pdf-engine",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.mjs",