@paprize/core 0.0.4 → 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,37 +1,20 @@
+import type * as CSS_2 from 'csstype';
 import { default as default_2 } from 'loglevel';
 
-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 type ConfigAttribute = {
-    [K in AttributeKey]?: AttributeValue<K>;
-};
-
-export declare function configToAttributeMap(config: ConfigAttribute): Record<string, string>;
+export declare function cloneComponents(components: SectionComponents): SectionComponents;
 
 export declare function createLoremIpsumParagraph(wordCount: number, seed: number): string;
 
+export declare type CSSProperties = CSS_2.Properties<string | number>;
+
 export declare const currentElementClassName = "pz-current-element";
 
 export declare const currentTextClassName = "pz-current-text";
@@ -47,15 +30,15 @@ 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;
-    nextNode(): void;
-    nextSiblingOrParentSibling(): {
+    goToNextNode(): void;
+    goToNextSiblingOrParentSibling(): {
         parentsTraversed: number;
     };
-    firstChildOrNextNode(): {
+    goToFirstChildOrNextNode(): {
         parentsTraversed: number;
     };
     private setState;
@@ -63,8 +46,21 @@ export declare class DomState {
 
 export declare const enableDebugMode: () => void;
 
+export declare class EventDispatcher<TEvents> {
+    private registry;
+    addEventListener<T extends keyof TEvents>(name: T, handler: EventHandler<T, TEvents>): () => void;
+    removeEventListener<T extends keyof TEvents>(name: T, handler: EventHandler<T, TEvents>): void;
+    dispatch<T extends keyof TEvents>(name: T, ...args: Parameters<EventHandler<T, TEvents>>): void;
+}
+
+declare type EventHandler<TKey extends keyof TEvents, TEvents> = TEvents[TKey] extends (...args: infer TArgs) => infer TReturn ? (...args: TArgs) => TReturn : never;
+
 export declare function getVisibleHeight(element: Element): number;
 
+export declare const globalStyle = "\n    html {\n        box-sizing: border-box;\n    }\n\n    *,\n    *:before,\n    *:after {\n        box-sizing: inherit;\n    }\n\n    :root {\n        --paprize-page-background-color: #ffffff;\n        --paprize-page-margin-bottom: 10px;\n        --paprize-page-box-shadow: rgb(142 138 138) -1px 3px 5px 2px;\n        --paprize-section-margin-bottom: 10px;\n        --paprize-preview-background-color: rgb(218 220 224);\n        --paprize-preview-padding: 30px 10px;\n    }\n\n    body {\n        margin: 0;\n    }\n    \n    @media screen {\n        .pz-preview {\n            min-height: 100vh;\n            display: flex;\n            flex-direction: column;\n            align-items: center;\n            background-color: var(--paprize-preview-background-color);\n            padding: var(--paprize-preview-padding);\n        }\n\n        .pz-page {\n            box-shadow: var(--paprize-page-box-shadow);\n            margin-bottom: var(--paprize-page-margin-bottom);\n            background-color: var(--paprize-page-background-color);\n        }\n\n        .pz-section {\n            margin-bottom: var(--paprize-section-margin-bottom);\n        }\n    }\n\n    @media print {\n        html:has(.pz-preview) *:not(.pz-preview):not(.pz-preview *):not(:has(.pz-preview)) {\n            display: none !important;\n        }\n    }   \n ";
+
+export declare const globalStyleId = "paprize-global-style";
+
 export declare const ignoredElementClassName = "pz-ignored-element";
 
 export declare const ignoredTextClassName = "pz-ignored-text";
@@ -75,26 +71,86 @@ 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";
 
+export declare type Monitor<TEvents> = Omit<EventDispatcher<TEvents>, 'dispatch'>;
+
 export declare function moveOffscreen(element: HTMLDivElement): void;
 
 export declare const pageBreakAttributeName = "data-pz-page-break";
 
-export declare const pageBreakPlugin: PaginationPlugin;
-
-export declare const pageBreakPluginName = "pageBreak";
+export declare class PageBreakPlugin implements PaginationPlugin {
+    name: string;
+    order: number;
+    onVisitElement: (_id: string, domState: DomState & {
+        currentNode: PageElement;
+    }, pageManager: PageManager, context: VisitContext) => void;
+}
 
 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 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;
+}
+
 declare class PageElement {
     private readonly _node;
-    private readonly _transaction;
+    config: PaginationOptions;
     readonly type: 'element';
-    readonly config: PaginationConfig;
-    constructor(element: Element, transaction: Transaction, config: PaginationConfig);
+    readonly transaction: Transaction;
+    readonly clonedFrom?: PageElement;
+    readonly cloneCount: number;
+    constructor(element: Element, transaction: Transaction, config: PaginationOptions, clonedFrom?: PageElement);
+    getOriginalNode(): Node | undefined;
     appendChild(node: PageNode): void;
     clone(withChildren?: boolean): PageElement;
     getHeight(): number;
@@ -109,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;
@@ -129,13 +185,96 @@ 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;
+}
+
+/**
+ * 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;
 }
 
+/**
+ * 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 {
     currentPage: PageElement;
     activeElement: PageNode | null;
@@ -151,10 +290,10 @@ declare class PageState {
 
 declare class PageText {
     private readonly _node;
-    private readonly _transaction;
     readonly type: 'text';
-    readonly config: PaginationConfig;
-    constructor(text: Text, transaction: Transaction, config: PaginationConfig);
+    readonly transaction: Transaction;
+    config: PaginationOptions;
+    constructor(text: Text, transaction: Transaction, config: PaginationOptions);
     get textContent(): string;
     set textContent(value: string);
     remove(): void;
@@ -163,8 +302,29 @@ declare class PageText {
 
 export declare type PaginateResult = string[];
 
-export declare type PaginationConfig = Required<ConfigAttribute> & {
+/**
+ * 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[];
 };
 
@@ -177,7 +337,7 @@ export declare interface PaginationPlugin {
     onVisitElement?: (id: string, domState: DomState & {
         currentNode: PageElement;
     }, pageManager: PageManager, context: VisitContext) => void;
-    afterVisitNode?: (id: string, domState: DomState, pageManager: PageManager) => void;
+    afterVisitNode?: (id: string, result: SplitResult, domState: DomState, pageManager: PageManager) => void;
     onNewPage?: (id: string, pageManager: PageManager) => void;
     onClone?: (id: string, source: Element, cloned: PageElement) => void;
 }
@@ -190,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;
@@ -198,6 +358,8 @@ export declare class Paginator {
     private processCurrentNode;
 }
 
+export declare const paprize_isInitialized = "__PAPRIZE_IS_INITIALIZED";
+
 export declare const paprize_isReady = "__PAPRIZE_IS_READY";
 
 export declare const paprize_readJsonDataFile = "__PAPRIZE_READ_JSON_DATA_FILE";
@@ -205,19 +367,230 @@ export declare const paprize_readJsonDataFile = "__PAPRIZE_READ_JSON_DATA_FILE";
 declare type PluginHookNames = NonNullable<PluginKeys>;
 
 declare type PluginKeys = {
-    [K in keyof PaginationPlugin]: PaginationPlugin[K] extends ((...args: any[]) => any) | undefined ? K : never;
+    [K in keyof PaginationPlugin]: PaginationPlugin[K] extends ((...args: never[]) => unknown) | undefined ? K : never;
 }[keyof PaginationPlugin];
 
+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;
+    private _paginationInProgress;
+    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;
+    /**
+     * 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;
+}
+
+export declare const reportStyles: {
+    globalStyle: string;
+    component: CSSProperties;
+    outOfScreen: CSSProperties;
+    page: (pageSize: PageSize, pageMargin: PageMargin) => CSSProperties;
+    overlay: CSSProperties;
+    pageContent: CSSProperties;
+    sectionPageMedia: typeof sectionPageMedia;
+    section: (sectionId: string) => CSSProperties;
+};
+
 declare type SafeElement = Omit<Element, 'removeChild' | 'appendChild' | 'replaceChild' | 'remove'>;
 
 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 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[];
+}
+
+/**
+ * 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;
+    /**
+     * 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, size: PageSize): string;
+
+export declare interface SectionState {
+    options: SectionOptions;
+    context: SectionContext;
+    components: SectionComponents;
+    onPaginationCompleted: (pages: PageContext[]) => void;
+}
+
 export declare const sectionTocName = "sectionToc";
 
 export declare class SectionTocPlugin implements PaginationPlugin {
-    readonly state: SectionTocState[];
     readonly name = "sectionToc";
     readonly order = 1;
+    private _state;
+    getContentList: () => SectionTocState[];
     onVisitElement: (id: string, domState: DomState & {
         currentNode: PageElement;
     }, pageManager: PageManager) => void;
@@ -226,7 +599,7 @@ export declare class SectionTocPlugin implements PaginationPlugin {
 
 export declare type SectionTocState = {
     sectionId: string;
-    pageNumber: number;
+    pageIndex: number;
     title: string;
     level: number;
 };
@@ -239,6 +612,35 @@ export declare const SplitResult: {
 
 export declare type SplitResult = (typeof SplitResult)[keyof typeof SplitResult];
 
+export declare class TablePlugin implements PaginationPlugin {
+    private readonly _options;
+    name: string;
+    order: number;
+    constructor(options?: TablePluginOptions);
+    onNewPage: (_id: string, pageManager: PageManager) => void;
+    onClone: (_id: string, source: Element, cloned: PageElement) => void;
+    private _isTable;
+    private _isTableBodyEmpty;
+}
+
+/**
+ * Table plugin options
+ */
+export declare interface TablePluginOptions {
+    /**
+     * If true, the table header (thead) will be cloned on each page.
+     */
+    cloneHeader?: boolean;
+    /**
+     * If true, the table footer (tfoot) will be cloned on each page.
+     */
+    cloneFooter?: boolean;
+    /**
+     * When true, tables containing only a header (no body rows) will not be removed.
+     */
+    includeHeaderOnlyTables?: boolean;
+}
+
 export declare const tempContainerClassName = "pz-temp-container";
 
 declare class Transaction {
@@ -262,6 +664,7 @@ export { }
 
 declare global {
     interface Window {
+        [paprize_isInitialized]?: boolean;
         [paprize_isReady]?: boolean;
         [paprize_readJsonDataFile]?: () => Promise<string>;
     }