chordsheetjs 14.6.1 → 15.0.0

package/lib/pdf/rendering/html/positioned_html_renderer.d.ts

@@ -0,0 +1,85 @@
+import Dimensions from '../../layout/engine/dimensions';
+import HtmlDocWrapper from './html_doc_wrapper';
+import Song from '../../chord_sheet/song';
+import { LineLayout, MeasuredItem } from '../../layout/engine';
+import Renderer, { ParagraphLayout } from '../renderer';
+import { FontConfiguration, MeasuredHtmlFormatterConfiguration } from '../../formatter/configuration';
+/**
+ * HtmlRenderer renders a song as HTML with absolute positioning
+ */
+declare class PositionedHtmlRenderer extends Renderer {
+    private configuration;
+    private currentLayoutFontStyle;
+    private currentLayoutSection;
+    private currentLayoutTextItem;
+    private currentLineStyle;
+    private _dimensions;
+    private _dimensionCacheKey;
+    private styler;
+    container: HTMLElement;
+    doc: HtmlDocWrapper;
+    /**
+     * Creates a new HtmlRenderer
+     */
+    constructor(song: Song, container: HTMLElement, configuration: MeasuredHtmlFormatterConfiguration);
+    getFontConfiguration(objectType: string): FontConfiguration;
+    getDocumentMetadata(): Record<string, any>;
+    getDoc(): HtmlDocWrapper;
+    getHTML(): HTMLElement;
+    dispose(): void;
+    protected initializeBackend(): void;
+    protected createNewPage(): void;
+    protected renderChordDiagrams(): void;
+    protected renderHeadersAndFooters(): void;
+    private renderLayoutForEachPage;
+    private resetLayoutRenderingState;
+    private createLayoutRenderer;
+    private createLayoutBackend;
+    private renderHtmlText;
+    private applyLayoutTextClasses;
+    private applyLayoutTextStyles;
+    private renderHtmlImage;
+    private renderHtmlLine;
+    protected renderParagraphs(paragraphLayouts: ParagraphLayout[]): void;
+    private renderParagraph;
+    private groupElementsByPageAndColumn;
+    protected renderLineItems(lines: LineLayout[]): void;
+    private renderSingleLine;
+    private getCurrentContext;
+    private handleColumnOverflow;
+    private renderLineContent;
+    private renderMeasuredItem;
+    private renderChordLyricsPairItem;
+    private renderTagItem;
+    private updatePosition;
+    protected addSectionLabel(label: string, x: number, y: number, options?: {
+        noUnderline?: boolean;
+    }): void;
+    protected addComment(comment: string, x: number, y: number, options?: {
+        noUnderline?: boolean;
+    }): void;
+    private addTextElementWithOptions;
+    protected measureText(text: string, font: FontConfiguration): {
+        width: number;
+        height: number;
+    };
+    protected calculateChordBaseline(yOffset: number, items: MeasuredItem[], chordText: string): number;
+    protected finalizeRendering(): void;
+    protected getConfiguration(): MeasuredHtmlFormatterConfiguration;
+    get dimensions(): Dimensions;
+    protected getDocPageSize(): {
+        width: number;
+        height: number;
+    };
+    private calculateBounds;
+    private createParagraphDiv;
+    private createElementGroupDiv;
+    private renderElementGroup;
+    private renderElement;
+    private drawElement;
+    private drawTextElement;
+    private buildDimensions;
+    private generateDimensionCacheKey;
+    protected getExtraMetadata(page: number, totalPages: number): Record<string, string | string[]>;
+}
+export default PositionedHtmlRenderer;

package/lib/pdf/rendering/pdf/js_pdf_renderer.d.ts

@@ -0,0 +1,46 @@
+import { Blob } from 'buffer';
+import Dimensions from '../../layout/engine/dimensions';
+import DocWrapper from '../../formatter/pdf_formatter/doc_wrapper';
+import Song from '../../chord_sheet/song';
+import { MeasuredItem } from '../../layout/engine';
+import { PdfConstructor } from '../../formatter/pdf_formatter/types';
+import Renderer from '../renderer';
+import { FontConfiguration, PDFFormatterConfiguration } from '../../formatter/configuration';
+declare class JsPdfRenderer extends Renderer {
+    private configuration;
+    private _dimensions;
+    private _dimensionCacheKey;
+    doc: DocWrapper;
+    constructor(song: Song, docConstructor: PdfConstructor, configuration: PDFFormatterConfiguration);
+    getFontConfiguration(objectType: string): FontConfiguration;
+    getDocumentMetadata(): Record<string, any>;
+    save(filename: string): void;
+    generatePDF(): Promise<Blob>;
+    getDoc(): DocWrapper;
+    protected initializeBackend(): void;
+    protected createNewPage(): void;
+    protected renderChordDiagrams(): void;
+    private createDiagramContext;
+    private createDiagramConfig;
+    protected renderHeadersAndFooters(): void;
+    private createLayoutRenderer;
+    private createLayoutBackend;
+    protected measureText(text: string, font: FontConfiguration): {
+        width: number;
+        height: number;
+    };
+    protected calculateChordBaseline(yOffset: number, items: MeasuredItem[], chordText: string): number;
+    protected finalizeRendering(): void;
+    protected getConfiguration(): PDFFormatterConfiguration;
+    protected get dimensions(): Dimensions;
+    protected getDocPageSize(): {
+        width: number;
+        height: number;
+    };
+    private drawElement;
+    private drawUnderlineIfNeeded;
+    private buildDimensions;
+    private generateDimensionCacheKey;
+    protected getExtraMetadata(page: number, totalPages: number): Record<string, string | string[]>;
+}
+export default JsPdfRenderer;

package/lib/pdf/rendering/pdf/pdf_chord_diagram_renderer.d.ts

@@ -0,0 +1,118 @@
+import DocWrapper from '../../formatter/pdf_formatter/doc_wrapper';
+import Song from '../../chord_sheet/song';
+import { ChordDiagramRenderingConfig } from '../../chord_diagram/chord_diagram';
+import { ChordDiagramFontConfigurations } from '../../formatter/configuration';
+/**
+ * Context for chord diagram rendering
+ */
+export interface ChordDiagramRenderingContext {
+    song: Song;
+    doc: DocWrapper;
+    getMinY: () => number;
+    getColumnStartX: () => number;
+    getColumnBottomY: () => number;
+    moveToNextColumn: () => void;
+    dimensions: {
+        columnWidth: number;
+    };
+    getX: () => number;
+    getY: () => number;
+    getCurrentColumn: () => number;
+    getCurrentPage: () => number;
+    setPosition: (x: number, y: number, column: number, page: number) => void;
+}
+/**
+ * Configuration for chord diagram rendering
+ */
+export interface ChordDiagramConfig {
+    enabled: boolean;
+    renderingConfig?: ChordDiagramRenderingConfig;
+    fonts: ChordDiagramFontConfigurations;
+    overrides?: {
+        global?: Record<string, {
+            hide?: boolean;
+            definition?: string;
+        }>;
+        byKey?: Record<string, Record<string, {
+            hide?: boolean;
+            definition?: string;
+        }>>;
+    };
+}
+/**
+ * Handles chord diagram rendering for PDF output.
+ * Extracted from JsPdfRenderer to improve modularity.
+ */
+export declare class ChordDiagramRenderer {
+    private context;
+    private config;
+    constructor(context: ChordDiagramRenderingContext, config: ChordDiagramConfig);
+    /**
+     * Renders all chord diagrams for the song
+     */
+    render(): void;
+    /**
+     * Calculates layout dimensions for chord diagrams
+     */
+    private calculateDiagramLayout;
+    /**
+     * Initializes position for diagram rendering
+     */
+    private initializeDiagramPosition;
+    /**
+     * Renders a single chord diagram
+     */
+    private renderSingleChordDiagram;
+    /**
+     * Positions for the next diagram, handling row and column breaks
+     */
+    private positionForNextDiagram;
+    private getInitialPosition;
+    private handleRowBreak;
+    private handleColumnBreak;
+    /**
+     * Draws a single chord diagram
+     */
+    private drawChordDiagram;
+    /**
+     * Processes chord overrides from configuration
+     */
+    private processChordOverrides;
+    /**
+     * Extracts override values from configuration
+     */
+    private extractOverrideValues;
+    /**
+     * Gets chord definitions from the song
+     */
+    private getChordDefinitions;
+    /**
+     * Builds a chord diagram from a chord definition
+     */
+    private buildChordDiagram;
+    /**
+     * Processes fingering information and identifies barres
+     */
+    private processFingeringAndBarres;
+    /**
+     * Adds markers without fingering information
+     */
+    private addMarkersWithoutFingering;
+    /**
+     * Groups frets by finger for barre detection
+     */
+    private groupFretsByFinger;
+    /**
+     * Processes grouped frets/fingers into markers and barres
+     */
+    private processFretFingerGroups;
+    /**
+     * Processes a single finger group into either a marker or barre
+     */
+    private processFingerGroup;
+    /**
+     * Adds a barre if string positions are valid
+     */
+    private addBarreIfValid;
+}
+export default ChordDiagramRenderer;

package/lib/pdf/rendering/renderer.d.ts

@@ -0,0 +1,273 @@
+import Dimensions from '../layout/engine/dimensions';
+import Line from '../chord_sheet/line';
+import Song from '../chord_sheet/song';
+import { LineLayout, MeasuredItem } from '../layout/engine';
+import { FontConfiguration, LayoutItem, MeasurementBasedFormatterConfiguration } from '../formatter/configuration';
+/**
+ * Interface representing paragraph layouts from the layout engine
+ */
+export interface ParagraphLayout {
+    units: LineLayout[][];
+    addSpacing: boolean;
+    sectionType: string;
+}
+/**
+ * PositionedElement represents an element with absolute positioning
+ */
+export interface PositionedElement {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    content: any;
+    type: string;
+    style?: any;
+    page: number;
+    column: number;
+}
+/**
+ * Abstract renderer class for absolute-positioned rendering
+ */
+declare abstract class Renderer {
+    protected song: Song;
+    protected startTime: number;
+    protected renderTime: number;
+    protected x: number;
+    protected y: number;
+    protected currentColumn: number;
+    protected elements: PositionedElement[];
+    protected currentPage: number;
+    constructor(song: Song);
+    /**
+     * Initialize the renderer with the song
+     */
+    initialize(): void;
+    /**
+     * Main render method - the only method that formatters should call
+     * @param paragraphLayouts The layouts to render
+     * @param config Additional configuration options
+     */
+    render(paragraphLayouts: ParagraphLayout[], _config?: any): void;
+    /**
+     * Get the bottom Y position available for content
+     */
+    getContentBottomY(): number;
+    /**
+     * Get metadata about the rendered document
+     */
+    abstract getDocumentMetadata(): Record<string, any>;
+    /**
+     * Get the font configuration for a specific object type
+     */
+    abstract getFontConfiguration(objectType: string): FontConfiguration;
+    /**
+     * Get the current rendering time in seconds
+     */
+    getRenderTime(): number;
+    /**
+     * Renders all paragraph layouts
+     */
+    protected renderParagraphs(paragraphLayouts: ParagraphLayout[]): void;
+    /**
+     * Render lines of content with chords, lyrics, and other elements
+     */
+    protected renderLines(lines: LineLayout[]): void;
+    private renderLineLayout;
+    protected hasColumnBreak(lineLayout: LineLayout): boolean;
+    private renderItem;
+    private renderChordLyricsPair;
+    /**
+     * Move to the next column or page
+     */
+    protected moveToNextColumn(): void;
+    /**
+     * Start a new page
+     */
+    protected startNewPage(): void;
+    /**
+     * Calculate chord and lyrics Y offsets based on the line content
+     */
+    protected calculateChordLyricYOffsets(items: MeasuredItem[], yOffset: number): {
+        chordsYOffset: number;
+        lyricsYOffset: number;
+    };
+    /**
+     * Get the maximum chord height for a line
+     */
+    protected getMaxChordHeight(items: MeasuredItem[]): number;
+    /**
+     * Process chords for display (handle modifiers, normalization)
+     */
+    protected processChords(chords: string, line: Line): string;
+    /**
+     * Add a text element to the elements array
+     */
+    protected addTextElement(text: string, x: number, y: number, type: string): void;
+    /**
+     * Add a section label element
+     */
+    protected addSectionLabel(label: string, x: number, y: number): void;
+    /**
+     * Add a comment element
+     */
+    protected addComment(comment: string, x: number, y: number): void;
+    /**
+     * Get the font configuration for a specific element type
+     */
+    protected getFontForType(type: string): FontConfiguration;
+    /**
+     * Get the total number of pages in the document
+     */
+    protected getTotalPages(): number;
+    /**
+     * Get the starting X position for the current column
+     */
+    protected getColumnStartX(): number;
+    /**
+     * Get the bottom Y position for the current column
+     */
+    protected getColumnBottomY(): number;
+    /**
+     * Get the width of a column
+     */
+    protected getColumnWidth(): number;
+    /**
+     * Get the minimum X coordinate (left margin)
+     */
+    protected getMinX(): number;
+    /**
+     * Get the minimum Y coordinate (top margin + header)
+     */
+    protected getMinY(): number;
+    /**
+     * Record the rendering time
+     */
+    protected recordRenderingTime(): void;
+    /**
+     * Get the elements for a specific page
+     */
+    protected getElementsForPage(page: number): PositionedElement[];
+    /**
+     * Initialize the backend rendering system
+     */
+    protected abstract initializeBackend(): void;
+    /**
+     * Create a new page in the backend
+     */
+    protected abstract createNewPage(): void;
+    /**
+     * Render chord diagrams
+     */
+    protected abstract renderChordDiagrams(): void;
+    /**
+     * Render headers and footers
+     */
+    protected abstract renderHeadersAndFooters(): void;
+    /**
+     * Measure text with the given font
+     */
+    protected abstract measureText(text: string, font: FontConfiguration): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Calculate chord baseline position
+     */
+    protected abstract calculateChordBaseline(yOffset: number, items: MeasuredItem[], chordText: string): number;
+    /**
+     * Finalize the rendering process
+     */
+    protected abstract finalizeRendering(): void;
+    /**
+     * Get the renderer configuration
+     */
+    protected abstract getConfiguration(): MeasurementBasedFormatterConfiguration | any;
+    /**
+     * Get the dimensions object for layout calculations
+     */
+    protected abstract get dimensions(): Dimensions;
+    /**
+     * Get the page size from the document wrapper
+     */
+    protected abstract getDocPageSize(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Get the layout configuration
+     */
+    protected getLayout(): MeasurementBasedFormatterConfiguration['layout'];
+    /**
+     * Get the header configuration
+     */
+    protected getHeaderConfig(): LayoutItem | undefined;
+    /**
+     * Get the footer configuration
+     */
+    protected getFooterConfig(): LayoutItem | undefined;
+    /**
+     * Get the page width
+     */
+    protected getPageWidth(): number;
+    /**
+     * Get the page height
+     */
+    protected getPageHeight(): number;
+    /**
+     * Get the left margin
+     */
+    protected getLeftMargin(): number;
+    /**
+     * Get the right margin
+     */
+    protected getRightMargin(): number;
+    /**
+     * Get the top margin
+     */
+    protected getTopMargin(): number;
+    /**
+     * Get the bottom margin
+     */
+    protected getBottomMargin(): number;
+    /**
+     * Get the header height
+     */
+    protected getHeaderHeight(): number;
+    /**
+     * Get the footer height
+     */
+    protected getFooterHeight(): number;
+    /**
+     * Get the column count
+     */
+    protected getColumnCount(): number;
+    /**
+     * Get the sections configuration with defaults
+     */
+    protected getSectionsConfig(): import("../formatter/configuration").SectionsConfig;
+    /**
+     * Get the column spacing
+     */
+    protected getColumnSpacing(): number;
+    /**
+     * Get the chord-to-lyrics spacing
+     */
+    protected getChordLyricSpacing(): number;
+    /**
+     * Get the paragraph spacing
+     */
+    protected getParagraphSpacing(): number;
+    /**
+     * Whether to use Unicode modifiers for chord rendering
+     */
+    protected useUnicodeModifiers(): boolean;
+    /**
+     * Whether to normalize chords
+     */
+    protected normalizeChords(): boolean;
+    /**
+     * Whether to render lyrics only (no chords)
+     */
+    protected isLyricsOnly(): boolean;
+}
+export default Renderer;

package/lib/pdf/rendering/shared/layout_section_renderer.d.ts

@@ -0,0 +1,93 @@
+import type { ImageCompression } from 'jspdf';
+import Metadata from '../../chord_sheet/metadata';
+import { Alignment, FontConfiguration, LayoutContentItemWithText, LayoutItem, LayoutSection, Margins } from '../../formatter/configuration';
+/**
+ * Backend abstraction for layout rendering operations.
+ * Both PDF and HTML renderers implement this interface.
+ */
+export interface LayoutRenderingBackend {
+    pageSize: {
+        width: number;
+        height: number;
+    };
+    currentPage: number;
+    totalPages: number;
+    text(content: string, x: number, y: number): void;
+    getTextWidth(text: string, font?: FontConfiguration): number;
+    splitTextToSize(text: string, maxWidth: number, font?: FontConfiguration): string[];
+    setFontStyle(style: FontConfiguration): void;
+    setTextItem?(item: LayoutContentItemWithText): void;
+    addElement?(element: any, x: number, y: number): void;
+    addImage(src: string, format: string, x: number, y: number, width: number, height: number, alias?: string, compression?: ImageCompression, rotation?: number): void;
+    line(x1: number, y1: number, x2: number, y2: number): void;
+    setLineStyle(style: any): void;
+    resetDash(): void;
+    setDrawColor?(color: number): void;
+    setLineWidth?(width: number): void;
+}
+/**
+ * Context for rendering layout sections (headers/footers)
+ */
+export interface LayoutRenderingContext {
+    metadata: Metadata;
+    margins: Margins;
+    extraMetadata: Record<string, string | string[]>;
+}
+/**
+ * Renders layout sections (headers and footers) for both PDF and HTML backends.
+ * This extracts the common layout rendering logic that was duplicated across renderers.
+ */
+export declare class LayoutSectionRenderer {
+    private backend;
+    private context;
+    constructor(backend: LayoutRenderingBackend, context: LayoutRenderingContext);
+    /**
+     * Renders a layout section (header or footer)
+     */
+    renderLayout(layoutConfig: LayoutItem, section: LayoutSection): void;
+    /**
+     * Determines if a content item should be rendered based on conditions
+     */
+    private shouldRenderContent;
+    /**
+     * Renders a text item
+     */
+    private renderTextItem;
+    /**
+     * Renders clipped text with optional ellipsis
+     */
+    private renderClippedText;
+    /**
+     * Clips text with ellipsis if it exceeds the maximum width
+     */
+    private clipTextWithEllipsis;
+    /**
+     * Clips text to fit within the maximum width
+     */
+    clipText(text: string, maxWidth: number, style?: FontConfiguration): string;
+    /**
+     * Renders multiline text
+     */
+    private renderMultilineText;
+    /**
+     * Renders an image
+     */
+    private renderImage;
+    /**
+     * Renders a line
+     */
+    private renderLine;
+    /**
+     * Evaluates a template with metadata
+     */
+    private evaluateTemplate;
+    /**
+     * Calculates the X position based on alignment
+     */
+    calculateX(alignment: Alignment | number, width?: number, offsetX?: number): number;
+    /**
+     * Gets the available width for content
+     */
+    private getAvailableWidth;
+}
+export default LayoutSectionRenderer;

package/lib/pdf/scales.d.ts

@@ -0,0 +1,3 @@
+import { ChordType, Mode, ModifierMaybe } from './constants';
+export declare const KEY_TO_GRADE: Record<ChordType, Record<Mode, Record<ModifierMaybe, Record<string, number>>>>;
+export declare const GRADE_TO_KEY: Record<ChordType, Record<Mode, Record<ModifierMaybe, Record<number, string>>>>;

package/lib/pdf/serialized_types.d.ts

@@ -0,0 +1,76 @@
+import { Accidental, ChordType, Fret } from './constants';
+export interface SerializedTraceInfo {
+    location?: {
+        offset: number | null;
+        line: number | null;
+        column: number | null;
+    };
+}
+export interface SerializedChord {
+    type: 'chord';
+    base: string;
+    accidental: Accidental | null;
+    suffix: string | null;
+    bassBase: string | null;
+    bassAccidental: Accidental | null;
+    chordType: ChordType;
+    optional?: boolean;
+}
+export interface SerializedChordLyricsPair {
+    type: 'chordLyricsPair';
+    chord?: SerializedChord | null;
+    chords: string;
+    lyrics: string | null;
+    annotation?: string | null;
+    isRhythmSymbol?: boolean;
+}
+export interface SerializedChordDefinition {
+    name: string;
+    baseFret: number;
+    frets: Fret[];
+    fingers?: number[];
+}
+export type SerializedTag = SerializedTraceInfo & {
+    type: 'tag';
+    name: string;
+    value: string;
+    chordDefinition?: SerializedChordDefinition;
+    attributes?: Record<string, string>;
+    selector?: string | null;
+    isNegated?: boolean;
+};
+export interface SerializedComment {
+    type: 'comment';
+    comment: string;
+}
+export type ContentType = 'tab' | 'abc' | 'ly' | 'svg' | 'grid' | 'textblock';
+export type PartTypes = 'part' | 'intro' | 'instrumental' | 'tag' | 'end';
+export interface SerializedSection {
+    type: 'section';
+    sectionType: ContentType;
+    content: string[];
+    startTag: SerializedTag;
+    endTag: SerializedTag;
+}
+export type SerializedLiteral = string;
+export interface SerializedTernary extends SerializedTraceInfo {
+    type: 'ternary';
+    variable: string | null;
+    valueTest: string | null;
+    trueExpression: (SerializedLiteral | SerializedTernary)[];
+    falseExpression: (SerializedLiteral | SerializedTernary)[];
+}
+export type SerializedComposite = (SerializedLiteral | SerializedTernary)[];
+export interface SerializedSoftLineBreak {
+    type: 'softLineBreak';
+}
+export type SerializedItem = SerializedChordLyricsPair | SerializedComment | SerializedLiteral | SerializedSoftLineBreak | SerializedTag | SerializedTernary;
+export interface SerializedLine {
+    type: 'line';
+    items: SerializedItem[];
+}
+export interface SerializedSong {
+    type: 'chordSheet';
+    lines: SerializedLine[];
+}
+export type SerializedComponent = SerializedLine | SerializedSong | SerializedChordLyricsPair | SerializedTag | SerializedComment | SerializedTernary | SerializedLiteral | SerializedSection | SerializedSoftLineBreak;