@paprize/core 0.0.5 → 0.0.6

package/README.md

@@ -2,4 +2,4 @@
 
 Design your report using the full power of JavaScript and CSS, mark the report section by paprize components and then paprize pagination engine will transforming it into a beautiful, professional, print-ready pages.
 
-![Components](https://raw.githubusercontent.com/PejmanNik/paprize/refs/heads/bootstrap/packages/website/static/img/components.svg)
+![Components](https://raw.githubusercontent.com/PejmanNik/paprize/refs/heads/main/packages/website/static/img/components.svg)

package/dist/paprize-core.d.ts

@@ -1,42 +1,16 @@
 import type * as CSS_2 from 'csstype';
 import { default as default_2 } from 'loglevel';
 
-export declare function adjustDimension(dimension: PageDimension, orientation: PageOrientation): PageDimension;
-
-declare const AttributeDef: {
-    hyphen: AttributeValueDef<string>;
-    keepOnSamePage: AttributeValueDef<boolean>;
-    hyphenationEnabled: AttributeValueDef<boolean>;
-};
-
-declare type AttributeKey = keyof typeof AttributeDef;
+export declare function adjustPageSize(size: PageSize, orientation?: PageOrientation): PageSize;
 
 export declare const attributePrefix = "data-pz-";
 
-declare type AttributeValue<K extends AttributeKey> = (typeof AttributeDef)[K] extends AttributeValueDef<infer R> ? R : never;
-
-declare class AttributeValueDef<T> {
-    name: string;
-    defaultValue: T;
-    private _reader;
-    constructor(name: string, reader: (value: string) => T, defaultValue: T);
-    read(value: string): T;
-    static createStr(name: string, defaultValue: string): AttributeValueDef<string>;
-    static createBool(name: string, defaultValue: boolean): AttributeValueDef<boolean>;
-}
-
 export declare function buildPageId(sectionId: string, pageIndex: number): string;
 
 export declare function callPluginHook<T extends PluginHookNames>(plugins: PaginationPlugin[], hookName: T, ...args: Parameters<NonNullable<PaginationPlugin[T]>>): void;
 
 export declare function cloneComponents(components: SectionComponents): SectionComponents;
 
-export declare type ConfigAttribute = {
-    [K in AttributeKey]?: AttributeValue<K>;
-};
-
-export declare function configToAttributeMap(config: ConfigAttribute): Record<string, string>;
-
 export declare function createLoremIpsumParagraph(wordCount: number, seed: number): string;
 
 export declare type CSSProperties = CSS_2.Properties<string | number>;
@@ -56,7 +30,7 @@ export declare class DomState {
     private _completed;
     private _currentNode;
     private _previousNode;
-    constructor(root: Element, transaction: Transaction, config: PaginationConfig);
+    constructor(root: Element, transaction: Transaction, config: PaginationOptions);
     get completed(): boolean;
     get currentNode(): PageNode | null;
     get previousNode(): PageNode | null;
@@ -97,6 +71,35 @@ export declare function isElement(node: Node): node is Element;
 
 export declare function isTextNode(node: Node): node is Text;
 
+/**
+ * Layout options for the pagination engine
+ */
+export declare interface LayoutOptions {
+    /**
+     * Specifies the character used for hyphenation when a word is broken across lines.
+     * @defaultValue "-"
+     */
+    hyphen?: string;
+    /**
+     * Prevents an element from being split across pages.
+     * If an element does not fit in the available space on the current page,
+     * it will be moved entirely to the next page. If it still does not fit on an empty page,
+     * it will be skipped and not rendered.
+     * @defaultValue false
+     */
+    keepOnSamePage?: boolean;
+    /**
+     * Disables automatic word hyphenation.
+     * When disabled, if a word (a sequence of text without whitespace) does not fit
+     * on the current page, it will move to the next page instead of being split
+     * with a hyphen character.
+     * @defaultValue false
+     */
+    hyphenationDisabled?: boolean;
+}
+
+export declare function layoutOptionsToAttributes(config: LayoutOptions): Record<string, string>;
+
 export declare const logger: default_2.Logger;
 
 export declare const loggerName = "paprize";
@@ -117,26 +120,36 @@ export declare class PageBreakPlugin implements PaginationPlugin {
 
 export declare const pageClassName = "pz-page";
 
+/**
+ * Context information for a paginated page.
+ */
 export declare interface PageContext {
+    /**
+     * Index of the section to which this page belongs
+     */
     sectionId: string;
-    index: number;
+    /**
+     * Index of this page within its section.
+     */
+    pageIndex: number;
+    /**
+     * Total number of pages in the section that contains this page.
+     */
     totalPages: number;
+    /**
+     * HTML string representing the paginated content of this page.
+     */
     pageContentHtml: string;
 }
 
-export declare interface PageDimension {
-    height: string;
-    width: string;
-}
-
 declare class PageElement {
     private readonly _node;
-    config: PaginationConfig;
+    config: PaginationOptions;
     readonly type: 'element';
     readonly transaction: Transaction;
     readonly clonedFrom?: PageElement;
     readonly cloneCount: number;
-    constructor(element: Element, transaction: Transaction, config: PaginationConfig, clonedFrom?: PageElement);
+    constructor(element: Element, transaction: Transaction, config: PaginationOptions, clonedFrom?: PageElement);
     getOriginalNode(): Node | undefined;
     appendChild(node: PageNode): void;
     clone(withChildren?: boolean): PageElement;
@@ -152,7 +165,7 @@ declare class PageManager {
     private readonly _transaction;
     private readonly _tempContainer;
     private readonly _config;
-    constructor(tempContainer: Element, pageSize: PageSize, transaction: Transaction, config: PaginationConfig);
+    constructor(tempContainer: Element, pageSize: RealizedPageSize, transaction: Transaction, config: PaginationOptions);
     nextPage(): void;
     private cloneParentStackToNewPage;
     private cleanupEmptyParent;
@@ -172,102 +185,94 @@ declare class PageManager {
     getPageState(): PageState;
 }
 
+/**
+ * Represents the margin sizes for a page.
+ * All values should be valid CSS size strings (e.g., '10mm', '1in').
+ *
+ * Common presets are available in {@link pageMargin}
+ */
 export declare interface PageMargin {
+    /** @public */
     top: string;
+    /** @public */
     right: string;
+    /** @public */
     bottom: string;
+    /** @public */
     left: string;
 }
 
-export declare const pageMargin: Record<keyof typeof _pageMargin, PageMargin>;
-
-declare const _pageMargin: {
-    Normal: {
-        top: string;
-        right: string;
-        bottom: string;
-        left: string;
-    };
-    Narrow: {
-        top: string;
-        right: string;
-        bottom: string;
-        left: string;
-    };
-    Wide: {
-        top: string;
-        right: string;
-        bottom: string;
-        left: string;
-    };
-    None: {
-        top: string;
-        right: string;
-        bottom: string;
-        left: string;
-    };
+/**
+ * Predefined values for commonly used {@link PageMargin}
+ * @privateRemarks
+ * Type casting is only for cleaner TypeDoc output
+ */
+export declare const pageMargin: {
+    /** Top, Right, Bottom, Left: 1in */
+    readonly Normal: PageMargin;
+    /** Top: 0.4in, Right, Bottom, Left: 0.6in */
+    readonly Narrow: PageMargin;
+    /** Top, Bottom: 0.5in, Right, Left: 2in */
+    readonly Wide: PageMargin;
+    /** Top, Right, Bottom, Left: 0 */
+    readonly None: PageMargin;
 };
 
 declare type PageNode = PageElement | PageText;
 
+/**
+ * Describes the page orientation.
+ *
+ * - 'portrait' (default): the page is taller than it is wide. Use the provided
+ *   width and height as-is.
+ * - 'landscape': the page is wider than it is tall. When applying landscape,
+ *   swap the width and height.
+ */
 export declare type PageOrientation = 'portrait' | 'landscape';
 
+/**
+ * Represents the dimensions of a page.
+ * All values should be valid CSS size strings (e.g., '210mm', '8.5in').
+ *
+ * Common presets are available in  {@link pageSize}
+ */
 export declare interface PageSize {
-    width: number;
-    height: number;
+    /** @public */
+    height: string;
+    /** @public */
+    width: string;
 }
 
-export declare const pageSize: Record<keyof typeof _pageSize, PageDimension>;
-
-declare const _pageSize: {
-    A1: {
-        height: string;
-        width: string;
-    };
-    A2: {
-        height: string;
-        width: string;
-    };
-    A3: {
-        height: string;
-        width: string;
-    };
-    A4: {
-        height: string;
-        width: string;
-    };
-    A5: {
-        height: string;
-        width: string;
-    };
-    A6: {
-        height: string;
-        width: string;
-    };
-    B3: {
-        height: string;
-        width: string;
-    };
-    B4: {
-        height: string;
-        width: string;
-    };
-    B5: {
-        height: string;
-        width: string;
-    };
-    Letter: {
-        height: string;
-        width: string;
-    };
-    Legal: {
-        height: string;
-        width: string;
-    };
-    Tabloid: {
-        height: string;
-        width: string;
-    };
+/**
+ * Predefined values for commonly used {@link PageSize}
+ * @privateRemarks
+ * Type casting is only for cleaner TypeDoc output
+ */
+export declare const pageSize: {
+    /** 841mm x 594mm */
+    readonly A1: PageSize;
+    /** 594mm x 420mm */
+    readonly A2: PageSize;
+    /** 420mm x 297mm */
+    readonly A3: PageSize;
+    /** 297mm x 210mm */
+    readonly A4: PageSize;
+    /** 210mm x 148mm */
+    readonly A5: PageSize;
+    /** 148mm x 105mm */
+    readonly A6: PageSize;
+    /** 500mm x 353mm */
+    readonly B3: PageSize;
+    /** 353mm x 250mm */
+    readonly B4: PageSize;
+    /** 250mm x 176mm */
+    readonly B5: PageSize;
+    /** 8.5in x 11in */
+    readonly Letter: PageSize;
+    /** 11in x 8.5in */
+    readonly Legal: PageSize;
+    /** 11in x 17in */
+    readonly Tabloid: PageSize;
 };
 
 declare class PageState {
@@ -287,8 +292,8 @@ declare class PageText {
     private readonly _node;
     readonly type: 'text';
     readonly transaction: Transaction;
-    config: PaginationConfig;
-    constructor(text: Text, transaction: Transaction, config: PaginationConfig);
+    config: PaginationOptions;
+    constructor(text: Text, transaction: Transaction, config: PaginationOptions);
     get textContent(): string;
     set textContent(value: string);
     remove(): void;
@@ -297,15 +302,32 @@ declare class PageText {
 
 export declare type PaginateResult = string[];
 
-export declare type PaginationConfig = Required<ConfigAttribute> & {
-    id: string;
-    plugins: PaginationPlugin[];
-};
-
+/**
+ * Context information for pagination cycle.
+ */
 export declare interface PaginationCycleCompleted {
+    /**
+     * All paginated section within the report.
+     */
     sections: SectionContext[];
 }
 
+/**
+ * Pagination options
+ * @interface
+ * @inlineType LayoutOptions
+ */
+export declare type PaginationOptions = Required<LayoutOptions> & {
+    /**
+     * Unique id of the pagination.
+     */
+    id: string;
+    /**
+     * List of plugins to use during pagination.
+     */
+    plugins: PaginationPlugin[];
+};
+
 export declare interface PaginationPlugin {
     readonly name: string;
     readonly order: number;
@@ -328,7 +350,7 @@ export declare class Paginator {
     private readonly _config;
     private constructor();
     private static createTempContainer;
-    static paginate(root: Element, pageSize: PageSize, config?: Partial<PaginationConfig>): PaginateResult;
+    static paginate(root: Element, pageSize: RealizedPageSize, config?: Partial<PaginationOptions>): PaginateResult;
     private processAllNodes;
     private handleNodeSkipped;
     private handleFullNodePlaced;
@@ -350,6 +372,15 @@ declare type PluginKeys = {
 
 export declare const previewClassName = "pz-preview";
 
+export declare interface RealizedPageSize {
+    width: number;
+    height: number;
+}
+
+/**
+ * The report builder class that contains the logic for handling pagination
+ * and managing the report layout.
+ */
 export declare class ReportBuilder {
     private readonly _sections;
     private readonly _monitor;
@@ -357,20 +388,69 @@ export declare class ReportBuilder {
     private _pendingPaginateResolvers;
     private _currentAbortController;
     constructor();
+    /**
+     * Monitor instance used to subscribe to pagination events.
+     * See {@link ReportBuilderEvents} for available event types.
+     */
     get monitor(): Monitor<ReportBuilderEvents>;
+    /**
+     * Removes a section from the registered sections, if it has already been registered in the report.
+     */
     removeSection(sectionId: string): void;
+    /**
+     * Registers a section by its ID, specifying the page size, margins, and other options.
+     *
+     * @param options - Configuration options for the section.
+     * @param components - The DOM components associated with the section.
+     * @param onPaginationCompleted - Callback invoked when pagination for the section is completed.
+     * @returns `true` if the section was added to the report’s section list, or `false` if it already exists.
+     */
     tryAddSection(options: SectionOptions, components: SectionComponents, onPaginationCompleted: (pages: PageContext[]) => void): boolean;
-    schedulePaginate(): Promise<ScheduleResult>;
+    /**
+     * Schedules a pagination operation.
+     *
+     * It is not possible to schedule multiple pagination operations in parallel,
+     * as the process involves DOM manipulation, and concurrent modifications
+     * could cause conflicts and unexpected results.
+     * Each newly scheduled operation is queued and executed sequentially.
+     * When a new pagination is scheduled, any ongoing or pending operations
+     * will be aborted, and the new pagination will start immediately afterward.
+     *
+     * @returns A promise that resolves when the first pagination cycle is completed.
+     * It does not wait for suspended sections to resolve and be paginated.
+     * To wait for all sections to complete pagination, use the
+     * `suspension` property of the returned result object.
+     */
+    schedulePagination(): Promise<ScheduleResult>;
     private _executePagination;
     private _processPendingPagination;
     private _injectStyle;
     private _paginateSection;
 }
 
+/**
+ * Available events that can be subscribed to, during the pagination process.
+ */
 export declare interface ReportBuilderEvents {
+    /**
+     * Triggered when a page has been fully paginated.
+     * event: {@link PageContext}
+     */
     pageCompleted: (event: PageContext) => void;
+    /**
+     * Triggered when a section has been fully paginated.
+     * event: {@link SectionContext}
+     */
     sectionCompleted: (event: SectionContext) => void;
+    /**
+     * Triggered when a new section is created.
+     * event: {@link SectionContext}
+     */
     sectionCreated: (event: SectionContext) => void;
+    /**
+     * Triggered when an entire pagination cycle is completed.
+     * event: {@link PaginationCycleCompleted}
+     */
     paginationCycleCompleted: (event: PaginationCycleCompleted) => void;
 }
 
@@ -378,7 +458,7 @@ export declare const reportStyles: {
     globalStyle: string;
     component: CSSProperties;
     outOfScreen: CSSProperties;
-    page: (pageDimension: PageDimension, pageMargin: PageMargin) => CSSProperties;
+    page: (pageSize: PageSize, pageMargin: PageMargin) => CSSProperties;
     overlay: CSSProperties;
     pageContent: CSSProperties;
     sectionPageMedia: typeof sectionPageMedia;
@@ -389,37 +469,113 @@ declare type SafeElement = Omit<Element, 'removeChild' | 'appendChild' | 'replac
 
 declare type SafeText = Omit<Text, 'remove'>;
 
+/**
+ * Represents the result of a scheduled pagination process.
+ */
 export declare interface ScheduleResult {
+    /**
+     * List of all registered sections.
+     */
     sections: SectionContext[];
+    /**
+     * If there are any suspended sections, this Promise tracks their state
+     * and resolves only after all suspended sections have been resumed
+     * and paginated.
+     */
     suspension: Promise<void>;
 }
 
 export declare const sectionClassName = "pz-section";
 
+/**
+ * Represents the collection of DOM elements generated by
+ * the pagination engine from the report components on the current page.
+ */
 export declare interface SectionComponents {
+    /**
+     * The HTML element that serves as the header for the entire section.
+     * `null` if the section has no section header.
+     */
     sectionHeader: HTMLElement | null;
+    /**
+     * The HTML element that serves as the footer for the entire section.
+     * `null` if the section has no section footer.
+     */
     sectionFooter: HTMLElement | null;
+    /**
+     * The HTML element that serves as the header for this page.
+     * `null` if the page has no header.
+     */
     pageHeader: HTMLElement | null;
+    /**
+     * The HTML element that serves as the footer for this page.
+     * `null` if the page has no footer.
+     */
     pageFooter: HTMLElement | null;
+    /**
+     * The main HTML element for the this page content
+     * This property is always defined.
+     */
     pageContent: HTMLElement;
 }
 
+/**
+ * Context information for a paginated section.
+ */
 export declare interface SectionContext {
-    index: number;
+    /**
+     * Index of the section within the report.
+     */
+    sectionIndex: number;
+    /**
+     * Unique identifier of the section.
+     */
     sectionId: string;
+    /**
+     * Indicates whether pagination for this section is suspended
+     * and waiting for the suspension to be resolved.
+     */
     isSuspended: boolean;
+    /**
+     * Indicates whether pagination for this section has completed.
+     */
     isPaginated: boolean;
+    /**
+     * All paginated pages that belong to this section.
+     */
     pages: PageContext[];
 }
 
-export declare interface SectionOptions extends Partial<PaginationConfig> {
+/**
+ * Configuration options for a section.
+ * @inlineType PaginationConfig
+ */
+export declare interface SectionOptions extends Partial<Omit<PaginationOptions, 'id'>> {
+    /**
+     * Unique id of the section within the report.
+     */
     readonly id: string;
-    readonly dimension: PageDimension;
+    /**
+     * Page size used for this section.
+     */
+    readonly size: PageSize;
+    /**
+     * Page orientation used for this section.
+     * @inlineType PageOrientation
+     * @default portrait
+     */
+    readonly orientation?: PageOrientation;
+    /**
+     * Page margins for this section.
+     */
     readonly margin?: PageMargin;
+    /**
+     * A list of promises that must be resolved before the section can be paginated.
+     */
     readonly suspense?: Promise<unknown>[];
 }
 
-declare function sectionPageMedia(sectionId: string, dimension: PageDimension): string;
+declare function sectionPageMedia(sectionId: string, size: PageSize): string;
 
 export declare interface SectionState {
     options: SectionOptions;
@@ -467,6 +623,9 @@ export declare class TablePlugin implements PaginationPlugin {
     private _isTableBodyEmpty;
 }
 
+/**
+ * Table plugin options
+ */
 export declare interface TablePluginOptions {
     /**
      * If true, the table header (thead) will be cloned on each page.