@paprize/core 0.0.11 → 0.1.0

package/dist/paprize-core.d.ts

@@ -1,702 +1,3 @@
-import type * as CSS_2 from 'csstype';
-import { default as default_2 } from 'loglevel';
-
-export declare function adjustPageSize(size: PageSize, orientation?: PageOrientation): PageSize;
-
-export declare const attributePrefix = "data-pz-";
-
-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 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";
-
-export declare const debugPlugin: PaginationPlugin;
-
-export declare const defaultPlugins: PaginationPlugin[];
-
-export declare class DomState {
-    private readonly _transaction;
-    private readonly _treeWalker;
-    private readonly _config;
-    private _completed;
-    private _currentNode;
-    private _previousNode;
-    constructor(root: Element, transaction: Transaction, config: PaginationOptions);
-    get completed(): boolean;
-    get currentNode(): PageNode | null;
-    get previousNode(): PageNode | null;
-    goToNextNode(): void;
-    goToNextSiblingOrParentSibling(): {
-        parentsTraversed: number;
-    };
-    goToFirstChildOrNextNode(): {
-        parentsTraversed: number;
-    };
-    private setState;
-}
-
-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>>): Promise<void>;
-}
-
-declare type EventHandler<TKey extends keyof TEvents, TEvents> = TEvents[TKey] extends (...args: infer TArgs) => infer TReturn ? (...args: TArgs) => TReturn : never;
-
-export declare function getNodeLayoutOptionsFromAttribute(node: Node | null): Partial<LayoutOptions>;
-
-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-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            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";
-
-export declare const isDebugMode: () => boolean;
-
-export declare function isElement(node: Node): node is Element;
-
-export declare function isTextNode(node: Node): node is Text;
-
-export declare const layoutOptionHyphenationDisabledAttribute = "data-pz-hyphenation-disabled";
-
-export declare const layoutOptionHyphenAttribute = "data-pz-hyphen";
-
-export declare const layoutOptionKeepOnSamePageAttribute = "data-pz-keep-on-same-page";
-
-/**
- * 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 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;
-    config: PaginationOptions;
-    readonly type: 'element';
-    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;
-    remove(): void;
-    isEmpty(): boolean;
-    getChildrenCount(): number;
-    getNode(): SafeElement;
-}
-
-declare class PageManager {
-    private _pageState;
-    private readonly _transaction;
-    private readonly _tempContainer;
-    private readonly _config;
-    constructor(tempContainer: Element, pageSize: RealizedPageSize, transaction: Transaction, config: PaginationOptions);
-    nextPage(): void;
-    private cloneParentStackToNewPage;
-    private cleanupEmptyParent;
-    enterElement(): void;
-    leaveElement(): void;
-    private static createPageHtmlElement;
-    private createNewPage;
-    startTransaction(): {
-        rollback: () => void;
-        commit: () => void;
-    };
-    hasEmptySpace(elementHeight?: number): boolean;
-    isOverFlow(): boolean;
-    markPageAsFull(): void;
-    appendChild(node: PageElement, withChildren: boolean): PageElement;
-    addTextNode(text: string): PageText;
-    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 {
-    /** @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;
-    currentElement: PageElement;
-    parentStack: PageElement[];
-    pageIsFull: boolean;
-    pageIndex: number;
-    pageHeight: number;
-    constructor(currentPage: PageElement, activeElement: PageNode | null, currentElement: PageElement, parentStack: PageElement[], pageIsFull: boolean, pageIndex: number, pageHeight: number);
-    static create(currentPage: PageElement, parentStack: PageElement[], pageIndex: number, pageHeight: number): PageState;
-    clone: () => PageState;
-}
-
-declare class PageText {
-    private readonly _node;
-    readonly type: 'text';
-    readonly transaction: Transaction;
-    config: PaginationOptions;
-    constructor(text: Text, transaction: Transaction, config: PaginationOptions);
-    get textContent(): string;
-    set textContent(value: string);
-    remove(): void;
-    getNode(): SafeText;
-}
-
-export declare type PaginateResult = string[];
-
-/**
- * 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;
-    onVisitText?: (id: string, domState: DomState & {
-        currentNode: PageText;
-    }, pageManager: PageManager, context: VisitContext) => void;
-    onVisitElement?: (id: string, domState: DomState & {
-        currentNode: PageElement;
-    }, pageManager: PageManager, context: VisitContext) => 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;
-    afterPagination?: (id: string, domState: DomState, pageManager: PageManager) => void;
-}
-
-export declare class Paginator {
-    private readonly _domState;
-    private readonly _pageManager;
-    private readonly _transaction;
-    private readonly _tempContainer;
-    private readonly _config;
-    private constructor();
-    private static createTempContainer;
-    static paginate(root: Element, pageSize: RealizedPageSize, config?: Partial<PaginationOptions>): PaginateResult;
-    private processAllNodes;
-    private handleNodeSkipped;
-    private handleFullNodePlaced;
-    private handleChildrenSplit;
-    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";
-
-declare type PluginHookNames = NonNullable<PluginKeys>;
-
-declare type PluginKeys = {
-    [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: SectionState['onPaginationCompleted']): Promise<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>;
-    /**
-     * Retrieves JSON data injected by **@paprize/puppeteer** during server-side rendering (SSR).
-     *
-     * If no injected data is available, the function returns the provided `defaultData`, or `null` if none is given.
-     *
-     * ⚠️ **Important Notes:**
-     * - This function is **not type-safe** — it performs **no runtime type validation** on the returned data.
-     * - It is available **only during server-side rendering** when using **@paprize/puppeteer**.
-     * - When used in **client-side rendering** or **development** mode, you should provide a `defaultData` value for testing purposes.
-     *
-     * @template T - The expected type of the injected JSON data.
-     * @param defaultData - Optional fallback value to return if no injected data is found.
-     * @returns A promise resolving to the injected JSON data if available, otherwise the provided default value or `null`.
-     */
-    getJsonData<T>(defaultData?: T): Promise<T | null>;
-    private _lazyJsonDataReader;
-    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[];
-    /**
-     * Options used for paginating this section.
-     *
-     * @remarks
-     * Options may differ from the original {@link SectionOptions}
-     * provided during section creation, as some values may be
-     */
-    options: SectionOptions;
-    /**
-     * Components used in this section.
-     */
-    components: SectionComponents;
-}
-
-/**
- * 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 {
-    context: SectionContext;
-    onPaginationCompleted: (context: SectionContext) => Promise<unknown> | void;
-}
-
-export declare const sectionTocName = "sectionToc";
-
-export declare class SectionTocPlugin implements PaginationPlugin {
-    readonly name = "sectionToc";
-    readonly order = 1;
-    private _state;
-    getContentList: () => SectionTocState[];
-    onVisitElement: (id: string, domState: DomState & {
-        currentNode: PageElement;
-    }, pageManager: PageManager) => void;
-    getHeadingLevel(node: SafeElement): number | null;
-}
-
-export declare type SectionTocState = {
-    sectionId: string;
-    pageIndex: number;
-    title: string;
-    level: number;
-};
-
-export declare const SplitResult: {
-    readonly None: 0;
-    readonly FullNodePlaced: 1;
-    readonly SplitChildren: 2;
-};
-
-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;
-    onVisitElement: (_id: string, domState: DomState & {
-        currentNode: PageElement;
-    }, _pageManager: PageManager, context: VisitContext) => 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 {
-    private _onRollback;
-    private _onCommit;
-    isActive: boolean;
-    constructor();
-    start: () => void;
-    addRollbackCallback: (callback: () => void) => void;
-    addCommitCallback: (callback: () => void) => void;
-    rollback: () => void;
-    commit: () => void;
-}
-
-export declare interface VisitContext {
-    result?: SplitResult;
-}
-
 export { }