@pagedjs/paged-layout

Extracted from Paged.js, this library can be used independently to lay out content across pages, or any bounded container.

NPM Module

$ npm install @pagedjs/paged-layout

How It Works

Source content is laid out into pages one at a time. When content exceeds the remaining page extent, the engine selects a break point and produces a break token. The break token captures the position in the content and carries any extracted overflow. The next page receives this break token and resumes layout where the previous one left off.

• Layout is per-page -- a new Layout instance is created for each page. It reads the page element's getBoundingClientRect() as bounds.
• Break tokens carry overflow -- BreakToken.overflow[] holds Overflow objects containing DOM content extracted from the previous page.
• Overflow transfer is built-in -- renderTo() automatically transfers overflow from the incoming break token before continuing the content walk.
• Dynamic page creation -- the consumer creates new pages as needed when a break token is returned.

import{Layout,ContentParser}from'@pagedjs/paged-layout';constsource=newContentParser(document.getElementById('content'));constcontainer=document.getElementById('container');letbreakToken;letprevWrapper;// Pages are created dynamically as content overflowswhile(true){// Create a new page with defined boundsconstpage=document.createElement('div');page.style.width='600px';page.style.height='400px';page.style.overflow='hidden';container.appendChild(page);constwrapper=document.createElement('div');page.appendChild(wrapper);// Layout is instantiated per-page (not reused)constlayout=newLayout(page);constresult=awaitlayout.renderTo(wrapper,source,breakToken,prevWrapper);breakToken=result.breakToken;prevWrapper=wrapper;// No more content -- layout is completeif(!breakToken)break;}

API

Layout

The core layout engine. Takes a page element and lays out content into it.

import{Layout}from'@pagedjs/paged-layout';constlayout=newLayout(element,hooks,options);constresult=awaitlayout.renderTo(wrapper,source,breakToken,prevWrapper);

Constructor:

• element -- the page DOM element (bounds are read from its getBoundingClientRect())
• hooks -- optional Hook objects for plugin integration
• options -- optional settings (hyphenGlyph, maxChars)

renderTo(wrapper, source, breakToken, prevWrapper) -- renders content into the wrapper, returns a RenderResult containing the next BreakToken (or undefined if complete).

BreakToken

Carries state between pages: the current node position and overflow content.

import{BreakToken}from'@pagedjs/paged-layout';

ContentParser

Prepares source content by adding data-ref UUIDs for element tracking across pages.

import{ContentParser}from'@pagedjs/paged-layout';constsource=newContentParser(document.getElementById('content'));

Hook

The plugin registration and callback system. Allows consumers to hook into layout events.

import{Hook}from'@pagedjs/paged-layout';constonOverflow=newHook();onOverflow.register((overflow,rendered,bounds)=>{console.log('Overflow detected:',overflow);});

Layout Hooks

When Layout is constructed without hooks, it creates its own set:

onPageLayout// Fired at the start of renderTolayoutNode// Fired for each node during the layout walkrenderNode// Fired when rendering a cloned nodelayout// Fired after completing a top-level elementbeforeOverflow// Fired before overflow detectiononOverflow// Fired when overflow is detectedonBreakToken// Fired when a break token is createdonNamedPage// Fired when a named page node is encounteredafterOverflowRemoved// Fired after overflow content is extractedafterOverflowAdded// Fired after overflow content is added to a new pagebeforeRenderResult// Fired before returning the final result

Consumers can pass shared hooks to coordinate behavior across pages.

Events

constlayout=newLayout(element);layout.addEventListener('overflow',(e)=>{console.log('Overflow detected:',e.detail);});layout.addEventListener('breaktoken',(e)=>{console.log('Break token created:',e.detail);});

DOM Utilities

Helper functions for DOM traversal, node classification, and tree rebuilding:

import{walk,rebuildTree,needsBreakBefore,isContainer,words,letters}from'@pagedjs/paged-layout';

Setup

Install dependencies

$ npm install

Development

Build the dist output

$ npm run build

Testing

$ npm test

License

MIT License (MIT)