@pdfme/common 2.1.0 → 2.2.0

package/src/font.ts

@@ -1,6 +1,6 @@
 import * as fontkit from 'fontkit';
 import type { Font as FontKitFont } from 'fontkit';
-import { Template, Schema, Font, isTextSchema, TextSchema } from './type';
+import { FontWidthCalcValues, Template, Schema, Font, isTextSchema, TextSchema } from './type';
 import { Buffer } from 'buffer';
 import {
   DEFAULT_FONT_VALUE,
@@ -9,12 +9,12 @@ import {
   DEFAULT_CHARACTER_SPACING,
   DEFAULT_LINE_HEIGHT,
   FONT_SIZE_ADJUSTMENT,
-  PT_TO_PX_RATIO,
   DEFAULT_DYNAMIC_FIT,
   DYNAMIC_FIT_HORIZONTAL,
   DYNAMIC_FIT_VERTICAL,
+  VERTICAL_ALIGN_TOP,
 } from './constants';
-import { mm2pt, pt2mm } from './helper';
+import { mm2pt, pt2mm, pt2px } from './helper';
 import { b64toUint8Array } from "."
 
 export const getFallbackFontName = (font: Font) => {
@@ -77,20 +77,50 @@ export const checkFont = (arg: { font: Font; template: Template }) => {
   }
 };
 
-export const getFontAlignmentValue = (fontKitFont: FontKitFont, fontSize: number) => {
+export const getBrowserVerticalFontAdjustments = (
+  fontKitFont: FontKitFont,
+  fontSize: number,
+  lineHeight: number,
+  verticalAlignment: string
+) => {
   const { ascent, descent, unitsPerEm } = fontKitFont;
 
-  const fontSizeInPx = fontSize * PT_TO_PX_RATIO;
+  // Fonts have a designed line height that the browser renders when using `line-height: normal`
+  const fontBaseLineHeight = (ascent - descent) / unitsPerEm;
 
-  // Convert ascent and descent to px values
-  const ascentInPixels = (ascent / unitsPerEm) * fontSizeInPx;
-  const descentInPixels = (descent / unitsPerEm) * fontSizeInPx;
+  // For vertical alignment top
+  // To achieve consistent positioning between browser and PDF, we apply the difference between
+  // the font's actual height and the font size in pixels.
+  // Browsers middle the font within this height, so we only need half of it to apply to the top.
+  // This means the font renders a bit lower in the browser, but achieves PDF alignment
+  const topAdjustment = (fontBaseLineHeight * fontSize - fontSize) / 2;
 
-  // Calculate the single line height in px
-  const singleLineHeight = ((ascentInPixels + Math.abs(descentInPixels)) / fontSizeInPx);
+  if (verticalAlignment === VERTICAL_ALIGN_TOP) {
+    return { topAdj: pt2px(topAdjustment), bottomAdj: 0 };
+  }
+
+  // For vertical alignment bottom and middle
+  // When browsers render text in a non-form element (such as a <div>), some of the text may be
+  // lowered below and outside the containing element if the line height used is less than
+  // the base line-height of the font.
+  // This behaviour does not happen in a <textarea> though, so we need to adjust the positioning
+  // for consistency between editing and viewing to stop text jumping up and down.
+  // This portion of text is half of the difference between the base line height and the used
+  // line height. If using the same or higher line-height than the base font, then line-height
+  // takes over in the browser and this adjustment is not needed.
+  // Unlike the top adjustment - this is only driven by browser behaviour, not PDF alignment.
+  let bottomAdjustment = 0;
+  if (lineHeight < fontBaseLineHeight) {
+    bottomAdjustment = ((fontBaseLineHeight - lineHeight) * fontSize) / 2;
+  }
 
-  // Calculate the top margin/padding in px
-  return ((singleLineHeight * fontSizeInPx) - fontSizeInPx) / 2
+  return { topAdj: 0, bottomAdj: pt2px(bottomAdjustment) };
+};
+
+export const getFontDescentInPt = (fontKitFont: FontKitFont, fontSize: number) => {
+  const { descent, unitsPerEm } = fontKitFont;
+
+  return (descent / unitsPerEm) * fontSize;
 };
 
 export const heightOfFontAtSize = (fontKitFont: FontKitFont, fontSize: number) => {
@@ -138,12 +168,6 @@ export const getFontKitFont = async (textSchema: TextSchema, font: Font) => {
   return fontKitFont;
 };
 
-export type FontWidthCalcValues = {
-  font: FontKitFont;
-  fontSize: number;
-  characterSpacing: number;
-  boxWidthInPt: number;
-};
 
 const isTextExceedingBoxWidth = (text: string, calcValues: FontWidthCalcValues) => {
   const { font, fontSize, characterSpacing, boxWidthInPt } = calcValues;

package/src/helper.ts

@@ -10,7 +10,7 @@ import {
   GenerateProps as GeneratePropsSchema,
   UIProps as UIPropsSchema,
 } from './schema';
-import { MM_TO_PT_RATIO, PT_TO_MM_RATIO } from './constants';
+import { MM_TO_PT_RATIO, PT_TO_MM_RATIO, PT_TO_PX_RATIO } from './constants';
 import { checkFont } from './font';
 
 export const mm2pt = (mm: number): number => {
@@ -21,6 +21,10 @@ export const pt2mm = (pt: number): number => {
   return pt * PT_TO_MM_RATIO;
 };
 
+export const pt2px = (pt: number): number => {
+  return pt * PT_TO_PX_RATIO;
+};
+
 const blob2Base64Pdf = (blob: Blob) => {
   return new Promise<string>((resolve, reject) => {
     const reader = new FileReader();

package/src/index.ts

@@ -2,6 +2,10 @@ import {
   DEFAULT_FONT_NAME,
   DEFAULT_FONT_SIZE,
   DEFAULT_ALIGNMENT,
+  VERTICAL_ALIGN_TOP,
+  VERTICAL_ALIGN_MIDDLE,
+  VERTICAL_ALIGN_BOTTOM,
+  DEFAULT_VERTICAL_ALIGNMENT,
   DEFAULT_LINE_HEIGHT,
   DEFAULT_CHARACTER_SPACING,
   DEFAULT_FONT_COLOR,
@@ -17,6 +21,7 @@ import {
 } from './constants.js';
 import { schemaTypes, isImageSchema, isBarcodeSchema, isTextSchema } from './type.js';
 import type {
+  FontWidthCalcValues,
   Lang,
   Size,
   Alignment,
@@ -52,6 +57,7 @@ import {
   checkDesignerProps,
   checkGenerateProps,
   mm2pt,
+  pt2px,
   validateBarcodeInput,
 } from './helper.js';
 import {
@@ -62,15 +68,19 @@ import {
   widthOfTextAtSize,
   checkFont,
   getFontKitFont,
-  getFontAlignmentValue,
+  getBrowserVerticalFontAdjustments,
+  getFontDescentInPt,
   getSplittedLines,
-  FontWidthCalcValues,
 } from './font.js';
 
 export {
   DEFAULT_FONT_NAME,
   DEFAULT_FONT_SIZE,
   DEFAULT_ALIGNMENT,
+  VERTICAL_ALIGN_TOP,
+  VERTICAL_ALIGN_MIDDLE,
+  VERTICAL_ALIGN_BOTTOM,
+  DEFAULT_VERTICAL_ALIGNMENT,
   DEFAULT_LINE_HEIGHT,
   DEFAULT_CHARACTER_SPACING,
   DEFAULT_FONT_COLOR,
@@ -95,9 +105,11 @@ export {
   heightOfFontAtSize,
   widthOfTextAtSize,
   mm2pt,
+  pt2px,
   checkFont,
+  getBrowserVerticalFontAdjustments,
+  getFontDescentInPt,
   getFontKitFont,
-  getFontAlignmentValue,
   checkInputs,
   checkUIOptions,
   checkTemplate,

package/src/schema.ts

@@ -1,5 +1,6 @@
 /* eslint dot-notation: "off"*/
 import { z } from 'zod';
+import { VERTICAL_ALIGN_TOP, VERTICAL_ALIGN_MIDDLE, VERTICAL_ALIGN_BOTTOM } from "./constants";
 
 const langs = ['en', 'ja', 'ar', 'th', 'pl'] as const;
 export const Lang = z.enum(langs);
@@ -9,6 +10,13 @@ export const Size = z.object({ height: z.number(), width: z.number() });
 const alignments = ['left', 'center', 'right'] as const;
 export const Alignment = z.enum(alignments);
 
+const verticalAlignments = [
+  VERTICAL_ALIGN_TOP,
+  VERTICAL_ALIGN_MIDDLE,
+  VERTICAL_ALIGN_BOTTOM,
+] as const;
+export const VerticalAlignment = z.enum(verticalAlignments);
+
 // prettier-ignore
 export const barcodeSchemaTypes = ['qrcode', 'japanpost', 'ean13', 'ean8', 'code39', 'code128', 'nw7', 'itf14', 'upca', 'upce', 'gs1datamatrix'] as const;
 const notBarcodeSchemaTypes = ['text', 'image'] as const;
@@ -28,6 +36,7 @@ export const CommonSchema = z.object({
 export const TextSchema = CommonSchema.extend({
   type: z.literal(SchemaType.Enum.text),
   alignment: Alignment.optional(),
+  verticalAlignment: VerticalAlignment.optional(),
   fontSize: z.number().optional(),
   fontName: z.string().optional(),
   fontColor: z.string().optional(),

package/src/type.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import type { Font as FontKitFont } from 'fontkit';
+
 import {
   Lang,
   Size,
@@ -28,6 +30,13 @@ import {
   DesignerReactProps,
 } from './schema.js';
 
+export type FontWidthCalcValues = {
+  font: FontKitFont;
+  fontSize: number;
+  characterSpacing: number;
+  boxWidthInPt: number;
+};
+
 type CommonSchema = z.infer<typeof _CommonSchema>;
 export const schemaTypes = _schemaTypes;
 export const isTextSchema = (arg: CommonSchema): arg is TextSchema => arg.type === 'text';