Add viewer pagination metadata

Author: Recoveredd

CHANGELOG.md

@@ -2,9 +2,12 @@
 
 All notable changes to this package are documented here.
 
+## 0.4.2 - 2026-05-12
+
+- Added `getPageCount()` and `getPageInfo()` to the DOM viewer so custom pagination controls can read the current page state.
+
 ## 0.4.1 - 2026-05-12
 
 - Added ecosystem recipes showing how to combine `json-html-kit` with small parsing and table utilities.
 - Added GitHub Actions CI for typechecking, building and testing on Node.js 20 and 22.
 - Documented package quality signals in the README.
-

README.md

@@ -167,11 +167,13 @@ const viewer = createJsonHtmlViewer(container, hugeRows, {
 });
 
 viewer.nextPage();
+viewer.getPageInfo();
 viewer.setPage(10);
 viewer.destroy();
 ```
 
 The viewer is intentionally separate from `renderJsonToHtml`. The renderer stays static and string-based; the viewer owns DOM state for pagination.
+Use `getPageInfo()` or `getPageCount()` when your UI needs to render its own pagination controls.
 
 ## Custom themes
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "json-html-kit",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Render arbitrary JSON as safe, themed, human-friendly HTML tables.",
   "type": "module",
   "sideEffects": false,

package.json

@@ -7,6 +7,7 @@ export {
 export { createTheme, getThemeCss, getThemePreset, getThemeStyleTag, injectThemeCss, themes } from './lib/themes.js';
 export type {
   JsonHtmlRenderer,
+  JsonHtmlViewerPageInfo,
   JsonHtmlRenderOptions,
   JsonHtmlStyleOptions,
   JsonHtmlTableMode,

src/index.ts

@@ -157,6 +157,25 @@ export function createJsonHtmlViewer(element: Element, value: unknown, options:
     getPage() {
       return page;
     },
+    getPageCount() {
+      return getViewerPageCount(data, pageSize);
+    },
+    getPageInfo() {
+      const totalItems = Array.isArray(data) ? data.length : 1;
+      const pageCount = getViewerPageCount(data, pageSize);
+      const clampedPage = clamp(page, 0, pageCount - 1);
+      const startIndex = Array.isArray(data) && totalItems > 0 ? clampedPage * pageSize : 0;
+      const endIndex = Array.isArray(data) ? Math.min(startIndex + pageSize, totalItems) : totalItems;
+
+      return {
+        page: clampedPage,
+        pageCount,
+        pageSize,
+        totalItems,
+        startIndex,
+        endIndex
+      };
+    },
     nextPage() {
       viewer.setPage(page + 1);
     },
@@ -182,6 +201,10 @@ export function createJsonHtmlViewer(element: Element, value: unknown, options:
   return viewer;
 }
 
+function getViewerPageCount(data: unknown, pageSize: number): number {
+  return Array.isArray(data) ? Math.max(1, Math.ceil(data.length / pageSize)) : 1;
+}
+
 function resolveRenderOptions(options: JsonHtmlRenderOptions): ResolvedRenderOptions {
   return {
     ...DEFAULT_OPTIONS,

src/lib/render.ts

@@ -60,9 +60,20 @@ export interface JsonHtmlViewerOptions extends JsonHtmlRenderOptions {
   initialPage?: number;
 }
 
+export interface JsonHtmlViewerPageInfo {
+  page: number;
+  pageCount: number;
+  pageSize: number;
+  totalItems: number;
+  startIndex: number;
+  endIndex: number;
+}
+
 export interface JsonHtmlViewer {
   destroy(): void;
   getPage(): number;
+  getPageCount(): number;
+  getPageInfo(): JsonHtmlViewerPageInfo;
   nextPage(): void;
   previousPage(): void;
   render(): void;

src/lib/types.ts

@@ -131,6 +131,15 @@ describe('createJsonHtmlViewer', () => {
     viewer.nextPage();
 
     expect(viewer.getPage()).toBe(1);
+    expect(viewer.getPageCount()).toBe(2);
+    expect(viewer.getPageInfo()).toEqual({
+      page: 1,
+      pageCount: 2,
+      pageSize: 2,
+      totalItems: 3,
+      startIndex: 2,
+      endIndex: 3
+    });
     expect(element.textContent).toContain('Showing 3-3 of 3 items');
     expect(element.textContent).toContain('Katherine');