pagyra-js 0.0.1

package/src/css/custom-properties.ts

@@ -0,0 +1,215 @@
+// src/css/custom-properties.ts
+
+/**
+ * CSS Custom Properties (CSS Variables) support
+ * Implements variable definition and resolution per CSS Custom Properties spec
+ */
+
+/**
+ * Storage for custom properties (CSS variables)
+ * Maps variable names (e.g., "--primary-color") to their raw string values
+ */
+export class CustomPropertiesMap {
+    private properties: Map<string, string> = new Map();
+
+    /**
+     * Set a custom property value
+     */
+    set(name: string, value: string): void {
+        // Ensure the property name starts with --
+        if (!name.startsWith('--')) {
+            return;
+        }
+        this.properties.set(name, value.trim());
+    }
+
+    /**
+     * Get a custom property value
+     */
+    get(name: string): string | undefined {
+        return this.properties.get(name);
+    }
+
+    /**
+     * Check if a custom property exists
+     */
+    has(name: string): boolean {
+        return this.properties.has(name);
+    }
+
+    /**
+     * Clone the custom properties map
+     */
+    clone(): CustomPropertiesMap {
+        const cloned = new CustomPropertiesMap();
+        this.properties.forEach((value, key) => {
+            cloned.set(key, value);
+        });
+        return cloned;
+    }
+
+    /**
+     * Inherit properties from a parent map
+     * Child properties override parent properties
+     */
+    inherit(parent: CustomPropertiesMap | undefined): CustomPropertiesMap {
+        if (!parent) {
+            return this.clone();
+        }
+
+        const inherited = parent.clone();
+        this.properties.forEach((value, key) => {
+            inherited.set(key, value);
+        });
+        return inherited;
+    }
+
+    /**
+     * Get all property names
+     */
+    keys(): string[] {
+        return Array.from(this.properties.keys());
+    }
+
+    /**
+     * Get the number of properties
+     */
+    get size(): number {
+        return this.properties.size;
+    }
+}
+
+/**
+ * Regular expression to match var() function calls
+ * Matches: var(--name) or var(--name, fallback)
+ */
+const VAR_FUNCTION_REGEX = /var\s*\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\s*\)/g;
+
+/**
+ * Check if a CSS value contains var() references
+ */
+export function containsVariableReference(value: string): boolean {
+    return value.includes('var(');
+}
+
+/**
+ * Extract variable name from var() function
+ * Example: "var(--primary-color)" -> "--primary-color"
+ */
+export function extractVariableName(varFunctionCall: string): string | null {
+    const match = varFunctionCall.match(/var\s*\(\s*(--[a-zA-Z0-9_-]+)/);
+    return match ? match[1] : null;
+}
+
+/**
+ * Parse var() function to extract variable name and fallback
+ * Returns: { name: string, fallback?: string }
+ */
+export function parseVarFunction(varFunctionCall: string): { name: string; fallback?: string } | null {
+    const trimmed = varFunctionCall.trim();
+
+    // Match var(--name) or var(--name, fallback)
+    const match = trimmed.match(/^var\s*\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*(.+))?\s*\)$/);
+
+    if (!match) {
+        return null;
+    }
+
+    return {
+        name: match[1],
+        fallback: match[2]?.trim(),
+    };
+}
+
+/**
+ * Resolve CSS value by replacing var() references with actual values
+ * Supports nested var() calls and fallback values
+ */
+export function resolveVariableReferences(
+    value: string,
+    customProperties: CustomPropertiesMap,
+    maxDepth = 10
+): string {
+    if (!containsVariableReference(value)) {
+        return value;
+    }
+
+    if (maxDepth <= 0) {
+        // Prevent infinite recursion
+        console.warn('CSS variable resolution depth limit reached');
+        return value;
+    }
+
+    let resolved = value;
+    const matches = value.matchAll(VAR_FUNCTION_REGEX);
+
+    for (const match of matches) {
+        const fullMatch = match[0];
+        const varName = match[1];
+        const fallback = match[2]?.trim();
+
+        // Try to get the variable value
+        let replacement = customProperties.get(varName);
+
+        // If variable not found, use fallback
+        if (replacement === undefined) {
+            if (fallback !== undefined) {
+                replacement = fallback;
+            } else {
+                // If no fallback, leave the var() call as-is (invalid)
+                console.warn(`CSS variable ${varName} not found and no fallback provided`);
+                continue;
+            }
+        }
+
+        // Replace this var() call
+        resolved = resolved.replace(fullMatch, replacement);
+    }
+
+    // Recursively resolve any nested var() calls
+    if (containsVariableReference(resolved)) {
+        resolved = resolveVariableReferences(resolved, customProperties, maxDepth - 1);
+    }
+
+    return resolved.trim();
+}
+
+/**
+ * Apply custom properties from declarations to the custom properties map
+ * Extracts all properties that start with "--"
+ */
+export function extractCustomProperties(
+    declarations: Record<string, string>
+): CustomPropertiesMap {
+    const customProps = new CustomPropertiesMap();
+
+    for (const [property, value] of Object.entries(declarations)) {
+        if (property.startsWith('--')) {
+            customProps.set(property, value);
+        }
+    }
+
+    return customProps;
+}
+
+/**
+ * Resolve all property values in declarations by replacing var() references
+ */
+export function resolveDeclarationsWithVariables(
+    declarations: Record<string, string>,
+    customProperties: CustomPropertiesMap
+): Record<string, string> {
+    const resolved: Record<string, string> = {};
+
+    for (const [property, value] of Object.entries(declarations)) {
+        // Don't resolve custom properties themselves (they can contain var())
+        if (property.startsWith('--')) {
+            resolved[property] = value;
+        } else {
+            // Resolve var() references in regular properties
+            resolved[property] = resolveVariableReferences(value, customProperties);
+        }
+    }
+
+    return resolved;
+}

package/src/css/enums.ts

@@ -0,0 +1,127 @@
+export enum Display {
+  Block = "block",
+  Inline = "inline",
+  InlineBlock = "inline-block",
+  Flex = "flex",
+  InlineFlex = "inline-flex",
+  Grid = "grid",
+  InlineGrid = "inline-grid",
+  Table = "table",
+  InlineTable = "inline-table",
+  TableRowGroup = "table-row-group",
+  TableHeaderGroup = "table-header-group",
+  TableFooterGroup = "table-footer-group",
+  TableRow = "table-row",
+  TableCell = "table-cell",
+  TableCaption = "table-caption",
+  ListItem = "list-item",
+  None = "none",
+  FlowRoot = "flow-root",
+}
+
+export enum Position {
+  Static = "static",
+  Relative = "relative",
+  Absolute = "absolute",
+  Fixed = "fixed",
+  Sticky = "sticky",
+}
+
+export enum FloatMode {
+  None = "none",
+  Left = "left",
+  Right = "right",
+}
+
+export enum ClearMode {
+  None = "none",
+  Left = "left",
+  Right = "right",
+  Both = "both",
+  InlineStart = "inline-start",
+  InlineEnd = "inline-end",
+}
+
+export enum OverflowMode {
+  Visible = "visible",
+  Hidden = "hidden",
+  Scroll = "scroll",
+  Auto = "auto",
+  Clip = "clip",
+}
+
+export enum WhiteSpace {
+  Normal = "normal",
+  NoWrap = "nowrap",
+  Pre = "pre",
+  PreWrap = "pre-wrap",
+  PreLine = "pre-line",
+}
+
+export enum TextWrap {
+  Wrap = "wrap",
+  NoWrap = "nowrap",
+  Balance = "balance",
+}
+
+export enum AlignItems {
+  Stretch = "stretch",
+  FlexStart = "flex-start",
+  FlexEnd = "flex-end",
+  Center = "center",
+  Baseline = "baseline",
+}
+
+export enum JustifyContent {
+  FlexStart = "flex-start",
+  FlexEnd = "flex-end",
+  Center = "center",
+  SpaceBetween = "space-between",
+  SpaceAround = "space-around",
+  SpaceEvenly = "space-evenly",
+  Start = "start",
+  End = "end",
+  Left = "left",
+  Right = "right",
+}
+
+export enum AlignContent {
+  Stretch = "stretch",
+  FlexStart = "flex-start",
+  FlexEnd = "flex-end",
+  Center = "center",
+  SpaceBetween = "space-between",
+  SpaceAround = "space-around",
+  SpaceEvenly = "space-evenly",
+}
+
+export enum VerticalAlign {
+  Baseline = "baseline",
+  Top = "top",
+  Middle = "middle",
+  Bottom = "bottom",
+  TextTop = "text-top",
+  TextBottom = "text-bottom",
+  Sub = "sub",
+  Super = "super",
+}
+
+export enum WritingMode {
+  HorizontalTb = "horizontal-tb",
+  VerticalRl = "vertical-rl",
+  VerticalLr = "vertical-lr",
+}
+
+export enum TableLayoutMode {
+  Auto = "auto",
+  Fixed = "fixed",
+}
+
+export enum BorderModel {
+  Separate = "separate",
+  Collapse = "collapse",
+}
+
+export type FlexDirection = "row" | "row-reverse" | "column" | "column-reverse";
+
+export type AlignSelfValue = "auto" | AlignItems;

package/src/css/font-face-parser.ts

@@ -0,0 +1,233 @@
+/**
+ * CSS @font-face parsing utilities.
+ * 
+ * This module handles parsing of CSS @font-face rules from stylesheets,
+ * including font family list parsing, weight matching, and source extraction.
+ */
+
+import type { CSSFontFace, StyleSheets } from "../pdf/types.js";
+import { normalizeFontWeight, parseFontWeightValue } from "./font-weight.js";
+
+/**
+ * Result of parsing font faces from stylesheets.
+ */
+export interface ParsedFontFaceMap {
+    /**
+     * Map of normalized font family names to their @font-face definitions.
+     */
+    facesByFamily: Map<string, CSSFontFace[]>;
+}
+
+/**
+ * Parse all @font-face definitions from stylesheets into a family-keyed map.
+ * 
+ * @param stylesheets - StyleSheets containing font face definitions
+ * @returns Map of font families to their face definitions
+ * 
+ * @example
+ * ```typescript
+ * const { facesByFamily } = parseFontFaces(stylesheets);
+ * const tinosFaces = facesByFamily.get("tinos");
+ * ```
+ */
+export function parseFontFaces(stylesheets: StyleSheets): ParsedFontFaceMap {
+    const facesByFamily = new Map<string, CSSFontFace[]>();
+
+    for (const face of stylesheets.fontFaces ?? []) {
+        const family = normalizeToken(face.family);
+        if (!family) {
+            continue;
+        }
+        const list = facesByFamily.get(family) ?? [];
+        list.push(face);
+        facesByFamily.set(family, list);
+    }
+
+    return { facesByFamily };
+}
+
+/**
+ * Select the best @font-face from a list based on requested weight.
+ * 
+ * Chooses the face with the smallest weight difference from the requested weight.
+ * Falls back to the first face if no weight information is available.
+ * 
+ * @param faces - Array of font faces to select from
+ * @param requestedWeight - Desired font weight (100-900)
+ * @returns Best matching font face, or undefined if faces array is empty
+ */
+export function selectFaceForWeight(faces: CSSFontFace[], requestedWeight: number): CSSFontFace | undefined {
+    let bestFace: CSSFontFace | undefined;
+    let smallestDiff = Number.POSITIVE_INFINITY;
+
+    for (const face of faces) {
+        const faceWeight = parseFaceWeight(face.weight, requestedWeight);
+        if (faceWeight === null) {
+            if (!bestFace) {
+                bestFace = face;
+            }
+            continue;
+        }
+        const diff = Math.abs(faceWeight - requestedWeight);
+        if (diff < smallestDiff) {
+            smallestDiff = diff;
+            bestFace = face;
+        }
+    }
+
+    return bestFace ?? faces[0];
+}
+
+/**
+ * Parse a font family list (comma-separated) into individual family names.
+ * 
+ * Handles quoted family names and filters out empty tokens.
+ * 
+ * @param value - Comma-separated font family string
+ * @returns Array of normalized family names
+ * 
+ * @example
+ * ```typescript
+ * parseFamilyList("'Times New Roman', Times, serif")
+ * // => ["Times New Roman", "Times", "serif"]
+ * ```
+ */
+export function parseFamilyList(value: string | undefined): string[] {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((token) => stripQuotes(token.trim()))
+        .filter((token) => token.length > 0);
+}
+
+/**
+ * Check if a font style is italic or oblique.
+ * 
+ * @param style - Font style value
+ * @returns True if style is "italic" or "oblique" (case-insensitive)
+ */
+export function isItalicStyle(style: string | undefined): boolean {
+    if (!style) {
+        return false;
+    }
+    const normalized = style.toLowerCase();
+    return normalized === "italic" || normalized === "oblique";
+}
+
+/**
+ * Normalize a font family or token to lowercase and remove quotes.
+ * 
+ * @param value - Token to normalize
+ * @returns Normalized lowercase string, or empty string if value is undefined
+ */
+export function normalizeToken(value: string | undefined): string {
+    if (!value) {
+        return "";
+    }
+    return stripQuotes(value).trim().toLowerCase();
+}
+
+/**
+ * Remove surrounding quotes from a string.
+ * 
+ * Handles both single and double quotes.
+ * 
+ * @param value - String potentially wrapped in quotes
+ * @returns String with quotes removed, or original value if not quoted
+ */
+export function stripQuotes(value: string): string {
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+
+/**
+ * Extract base font name from a @font-face definition using aliases.
+ * 
+ * Checks both local() sources and the family name against the provided alias map.
+ * 
+ * @param face - @font-face definition
+ * @param aliases - Map of font names to their aliases
+ * @returns Base font name if found, null otherwise
+ */
+export function baseFontFromFace(face: CSSFontFace, aliases: ReadonlyMap<string, string>): string | null {
+    const localName = extractLocalSource(face.src);
+    if (localName) {
+        const normalized = normalizeToken(localName);
+        const alias = aliases.get(normalized);
+        if (alias) {
+            return alias;
+        }
+    }
+    const familyAlias = aliases.get(normalizeToken(face.family));
+    if (familyAlias) {
+        return familyAlias;
+    }
+    return null;
+}
+
+/**
+ * Extract the first local() font source from a src list.
+ * 
+ * @param srcList - Array of font source strings (e.g., ["local('Arial')", "url(...))"])
+ * @returns Local font name if found, null otherwise
+ * 
+ * @example
+ * ```typescript
+ * extractLocalSource(["local('Arial')", "url(arial.woff2)"])
+ * // => "Arial"
+ * ```
+ */
+export function extractLocalSource(srcList: string[]): string | null {
+    for (const src of srcList) {
+        const match = src.match(/local\(([^)]+)\)/i);
+        if (match) {
+            return stripQuotes(match[1].trim());
+        }
+    }
+    return null;
+}
+
+/**
+ * Parse a @font-face weight value into a numeric weight.
+ * 
+ * Handles:
+ * - Numeric weights (already normalized)
+ * - String values ("normal", "bold", "400", etc.)
+ * - Multiple weights (chooses closest to fallback)
+ * 
+ * @param value - Weight value from @font-face
+ * @param fallback - Fallback weight to use for choosing from multiple values
+ * @returns Normalized numeric weight (100-900), or null if unparseable
+ */
+function parseFaceWeight(value: string | number | undefined, fallback: number): number | null {
+    if (typeof value === "number") {
+        return normalizeFontWeight(value);
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    const parts = value.split(/\s+/).filter(Boolean);
+    if (parts.length > 1) {
+        const parsedWeights = parts
+            .map((part) => parseFontWeightValue(part, fallback))
+            .filter((weight): weight is number => weight !== undefined)
+            .map((weight) => normalizeFontWeight(weight));
+        if (parsedWeights.length === 0) {
+            return null;
+        }
+        return parsedWeights.reduce((closest, candidate) => {
+            const candidateDiff = Math.abs(candidate - fallback);
+            const closestDiff = Math.abs(closest - fallback);
+            return candidateDiff < closestDiff ? candidate : closest;
+        }, parsedWeights[0]);
+    }
+    const parsed = parseFontWeightValue(value, fallback);
+    if (parsed === undefined) {
+        return null;
+    }
+    return normalizeFontWeight(parsed);
+}

package/src/css/font-weight.ts

@@ -0,0 +1,65 @@
+const FONT_WEIGHT_STEPS = [100, 200, 300, 400, 500, 600, 700, 800, 900] as const;
+
+type FontWeightDirection = "bolder" | "lighter";
+
+export function normalizeFontWeight(weight: number | undefined): number {
+  if (!Number.isFinite(weight ?? NaN)) {
+    return 400;
+  }
+  const clamped = Math.min(900, Math.max(100, weight as number));
+  let nearest = 400;
+  let smallestDiff = Math.abs(nearest - clamped);
+  for (const step of FONT_WEIGHT_STEPS) {
+    const diff = Math.abs(step - clamped);
+    if (diff < smallestDiff) {
+      smallestDiff = diff;
+      nearest = step;
+    }
+  }
+  return nearest;
+}
+
+export function stepFontWeight(weight: number | undefined, direction: FontWeightDirection): number {
+  const normalized = normalizeFontWeight(weight);
+  const index = FONT_WEIGHT_STEPS.indexOf(normalized as (typeof FONT_WEIGHT_STEPS)[number]);
+  if (index === -1) {
+    return normalized;
+  }
+  if (direction === "bolder") {
+    return FONT_WEIGHT_STEPS[Math.min(FONT_WEIGHT_STEPS.length - 1, index + 1)];
+  }
+  return FONT_WEIGHT_STEPS[Math.max(0, index - 1)];
+}
+
+export function parseFontWeightValue(value: string, inherited?: number): number | undefined {
+  const token = value.trim().toLowerCase();
+  switch (token) {
+    case "normal":
+      return 400;
+    case "bold":
+      return 700;
+    case "bolder":
+      return stepFontWeight(inherited, "bolder");
+    case "lighter":
+      return stepFontWeight(inherited, "lighter");
+    case "inherit":
+      return inherited !== undefined ? normalizeFontWeight(inherited) : undefined;
+    case "initial":
+      return 400;
+    default: {
+      const numeric = Number.parseFloat(token);
+      if (Number.isFinite(numeric)) {
+        return normalizeFontWeight(numeric);
+      }
+      return undefined;
+    }
+  }
+}
+
+export function fontWeightCacheKey(weight: number | undefined): string {
+  return normalizeFontWeight(weight).toString();
+}
+
+export function isBoldFontWeight(weight: number | undefined): boolean {
+  return normalizeFontWeight(weight) >= 600;
+}

package/src/css/inline-style-parser.ts

@@ -0,0 +1,27 @@
+/**
+ * Parse inline style attribute
+ * Responsibility: Convert style string to property map
+ */
+export function parseInlineStyle(style: string): Record<string, string> {
+    const properties: Record<string, string> = {};
+
+    if (!style || typeof style !== 'string') {
+        return properties;
+    }
+
+    const declarations = style.split(';');
+
+    for (const decl of declarations) {
+        const colonIndex = decl.indexOf(':');
+        if (colonIndex === -1) continue;
+
+        const property = decl.substring(0, colonIndex).trim();
+        const value = decl.substring(colonIndex + 1).trim();
+
+        if (property && value) {
+            properties[property] = value;
+        }
+    }
+
+    return properties;
+}