@plone/volto 19.1.6 → 19.3.0

package/src/components/manage/Widgets/QuerystringWidget.test.jsx

@@ -38,10 +38,21 @@ describe('objectSchema', () => {
       'sort_on',
       'sort_order_boolean',
       'limit',
+      'offset',
       'b_size',
     ]);
   });
 
+  it('offers offset as a number field defaulting to no items skipped', () => {
+    const schema = objectSchema({ intl: mockIntl });
+
+    expect(schema.properties.offset).toMatchObject({
+      title: 'Offset',
+      type: 'number',
+      default: 0,
+    });
+  });
+
   it('does not include depth in the schema properties', () => {
     const schema = objectSchema({ intl: mockIntl });
 

package/src/config/index.js

@@ -102,6 +102,8 @@ let config = {
     internalApiPath: process.env.RAZZLE_INTERNAL_API_PATH || undefined,
     subpathPrefix: process.env.RAZZLE_SUBPATH_PREFIX || '',
     websockets: process.env.RAZZLE_WEBSOCKETS || false,
+    // Overrides the API traversal suffix. An empty string disables it.
+    apiSuffix: process.env.RAZZLE_API_SUFFIX,
     // TODO: legacyTraverse to be removed when the use of the legacy traverse is deprecated.
     legacyTraverse: process.env.RAZZLE_LEGACY_TRAVERSE || false,
     cookieExpires: 15552000, //in seconds. Default is 6 month (15552000)

package/src/config/server.js

@@ -1,5 +1,6 @@
 import imagesMiddleware from '@plone/volto/express-middleware/images';
 import filesMiddleware from '@plone/volto/express-middleware/files';
+import portraitsMiddleware from '@plone/volto/express-middleware/portraits';
 import robotstxtMiddleware from '@plone/volto/express-middleware/robotstxt';
 import sitemapMiddleware from '@plone/volto/express-middleware/sitemap';
 import staticsMiddleware from '@plone/volto/express-middleware/static';
@@ -10,6 +11,7 @@ const settings = {
     devProxyMiddleware(),
     filesMiddleware(),
     imagesMiddleware(),
+    portraitsMiddleware(),
     robotstxtMiddleware(),
     sitemapMiddleware(),
     staticsMiddleware(),

package/src/express-middleware/devproxy.js

@@ -7,7 +7,6 @@ import {
   responseInterceptor,
 } from 'http-proxy-middleware';
 import querystring from 'querystring';
-import { parse as parseUrl } from 'url';
 
 const filter = function (pathname, req) {
   // Check if pathname is defined, there are some corner cases that pathname is null
@@ -31,8 +30,9 @@ function getEnv() {
     return _env;
   }
 
-  const apiPathURL = parseUrl(config.settings.apiPath);
-  const proxyURL = parseUrl(config.settings.devProxyToApiPath);
+  // Use the WHATWG URL API instead of the deprecated `url.parse()` (DEP0169).
+  const apiPathURL = new URL(config.settings.apiPath);
+  const proxyURL = new URL(config.settings.devProxyToApiPath);
   const serverURL = `${proxyURL.protocol}//${proxyURL.host}`;
   const instancePath = proxyURL.pathname;
 

package/src/express-middleware/images.js

@@ -29,7 +29,6 @@ export default function imagesMiddleware() {
   const middleware = express.Router();
 
   middleware.all(['**/@@images/*'], imageMiddlewareFn);
-  middleware.all(['/@portrait/*'], imageMiddlewareFn);
   middleware.all(['/@@site-logo/*'], imageMiddlewareFn);
   middleware.id = 'imageResourcesProcessor';
   return middleware;

package/src/express-middleware/portraits.js

@@ -0,0 +1,34 @@
+import express from 'express';
+import { getPloneBackendAPIResourceWithAuth } from '@plone/volto/helpers/Api/PloneBackendAPIResourceWithAuth';
+
+const HEADERS = [
+  'content-type',
+  'content-disposition',
+  'cache-status',
+  'cache-control',
+  'x-sendfile',
+  'x-accel-redirect',
+  'x-robots-tag',
+];
+
+function portraitMiddlewareFn(req, res, next) {
+  getPloneBackendAPIResourceWithAuth(req)
+    .then((resource) => {
+      // Just forward the headers that we need
+      HEADERS.forEach((header) => {
+        if (resource.headers[header]) {
+          res.set(header, resource.headers[header]);
+        }
+      });
+      res.send(resource.body);
+    })
+    .catch(next);
+}
+
+export default function portraitsMiddleware() {
+  const middleware = express.Router();
+
+  middleware.all(['/@portrait/*'], portraitMiddlewareFn);
+  middleware.id = 'portraitResourcesProcessor';
+  return middleware;
+}

package/src/helpers/Api/APIResourceWithAuth.js

@@ -6,7 +6,7 @@
 import superagent from 'superagent';
 import config from '@plone/volto/registry';
 import { addHeadersFactory } from '@plone/volto/helpers/Proxy/Proxy';
-import { stripSubpathPrefix } from '@plone/volto/helpers/Url/Url';
+import { getApiSuffix, stripSubpathPrefix } from '@plone/volto/helpers/Url/Url';
 
 /**
  * Get a resource image/file with authenticated (if token exist) API headers
@@ -17,7 +17,7 @@ import { stripSubpathPrefix } from '@plone/volto/helpers/Url/Url';
 export const getAPIResourceWithAuth = (req) =>
   new Promise((resolve, reject) => {
     const { settings } = config;
-    const apiSuffix = settings.legacyTraverse ? '' : '/++api++';
+    const apiSuffix = getApiSuffix();
     let apiPath = '';
 
     if (settings.internalApiPath && __SERVER__) {

package/src/helpers/Api/Api.js

@@ -8,6 +8,7 @@ import Cookies from 'universal-cookie';
 import config from '@plone/volto/registry';
 import { addHeadersFactory } from '@plone/volto/helpers/Proxy/Proxy';
 import {
+  getApiSuffix,
   stripQuerystring,
   stripSubpathPrefix,
 } from '@plone/volto/helpers/Url/Url';
@@ -22,7 +23,7 @@ const methods = ['get', 'post', 'put', 'patch', 'del'];
  */
 export function formatUrl(path) {
   const { settings } = config;
-  const apiSuffix = settings.legacyTraverse ? '' : '/++api++';
+  const apiSuffix = getApiSuffix();
 
   if (path.startsWith('http://') || path.startsWith('https://')) return path;
 

package/src/helpers/Api/Api.plone.rest.test.js

@@ -15,6 +15,7 @@ vi.mock('superagent', () => ({
 }));
 
 beforeAll(() => {
+  config.settings.apiSuffix = undefined;
   config.settings.legacyTraverse = false;
 });
 
@@ -41,4 +42,10 @@ describe('Api', () => {
     const promise = api.get('https://example.com');
     expect(promise.request.url).toBe('https://example.com');
   });
+  it('uses the configured API suffix', () => {
+    config.settings.apiSuffix = '/custom-api';
+    const promise = api.get('/test');
+    expect(promise.request.url).toBe(`${settings.apiPath}/custom-api/test`);
+    config.settings.apiSuffix = undefined;
+  });
 });

package/src/helpers/Api/PloneBackendAPIResourceWithAuth.js

@@ -0,0 +1,39 @@
+import superagent from 'superagent';
+import config from '@plone/volto/registry';
+import { addHeadersFactory } from '@plone/volto/helpers/Proxy/Proxy';
+import { getApiSuffix, stripSubpathPrefix } from '@plone/volto/helpers/Url/Url';
+
+/**
+ * Get a resource from Plone Backend (/++api++) with authenticated (if token exist) API headers
+ * @function getPloneBackendAPIResourceWithAuth
+ * @param {Object} req Request object
+ * @return {string} The response with the image
+ */
+export const getPloneBackendAPIResourceWithAuth = (req) =>
+  new Promise((resolve, reject) => {
+    const { settings } = config;
+    const apiSuffix = getApiSuffix();
+    let apiPath = '';
+
+    if (settings.internalApiPath && __SERVER__) {
+      apiPath = settings.internalApiPath;
+    } else if (__DEVELOPMENT__ && settings.devProxyToApiPath) {
+      apiPath = settings.devProxyToApiPath;
+    } else {
+      apiPath = settings.apiPath;
+    }
+
+    //strip subpath if any
+    const contentPath = stripSubpathPrefix(req.path);
+
+    const request = superagent
+      .get(`${apiPath}${apiSuffix}${contentPath}`)
+      .maxResponseSize(settings.maxResponseSize)
+      .responseType('blob');
+    const authToken = req.universalCookies.get('auth_token');
+    if (authToken) {
+      request.set('Authorization', `Bearer ${authToken}`);
+    }
+    request.use(addHeadersFactory(req));
+    request.then(resolve).catch(reject);
+  });

package/src/helpers/Api/PloneBackendAPIResourceWithAuth.test.js

@@ -0,0 +1,72 @@
+import superagent from 'superagent';
+import config from '@plone/volto/registry';
+import { getPloneBackendAPIResourceWithAuth } from './PloneBackendAPIResourceWithAuth';
+
+vi.mock('superagent', () => ({
+  default: {
+    get: vi.fn(() => ({
+      maxResponseSize: vi.fn().mockReturnThis(),
+      responseType: vi.fn().mockReturnThis(),
+      set: vi.fn(),
+      use: vi.fn(),
+      then: vi.fn((resolve) => resolve()),
+    })),
+  },
+}));
+
+const request = {
+  path: '/@portrait/admin',
+  universalCookies: { get: vi.fn() },
+  headers: {},
+};
+
+describe('getPloneBackendAPIResourceWithAuth', () => {
+  const originalSettings = { ...config.settings };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubGlobal('__DEVELOPMENT__', true);
+    Object.assign(config.settings, originalSettings, {
+      apiPath: 'http://localhost:3000',
+      devProxyToApiPath: 'http://localhost:8080/Plone',
+      internalApiPath: undefined,
+      apiSuffix: undefined,
+    });
+  });
+
+  afterAll(() => {
+    vi.unstubAllGlobals();
+    Object.assign(config.settings, originalSettings);
+  });
+
+  it('uses the API traversal path for Plone in development', async () => {
+    config.settings.legacyTraverse = false;
+
+    await getPloneBackendAPIResourceWithAuth(request);
+
+    expect(superagent.get).toHaveBeenCalledWith(
+      'http://localhost:8080/Plone/++api++/@portrait/admin',
+    );
+  });
+
+  it('omits the API traversal path for legacy backends in development', async () => {
+    config.settings.legacyTraverse = true;
+
+    await getPloneBackendAPIResourceWithAuth(request);
+
+    expect(superagent.get).toHaveBeenCalledWith(
+      'http://localhost:8080/Plone/@portrait/admin',
+    );
+  });
+
+  it('uses apiSuffix in preference to legacyTraverse in development', async () => {
+    config.settings.legacyTraverse = true;
+    config.settings.apiSuffix = '/custom-api';
+
+    await getPloneBackendAPIResourceWithAuth(request);
+
+    expect(superagent.get).toHaveBeenCalledWith(
+      'http://localhost:8080/Plone/custom-api/@portrait/admin',
+    );
+  });
+});

package/src/helpers/Pagination/Pagination.test.ts

@@ -0,0 +1,259 @@
+import {
+  computeBStart,
+  computeLimit,
+  computeTotalPages,
+  computeVisibleTotal,
+  type IntegerLike,
+} from './Pagination';
+
+describe('computeBStart', () => {
+  describe('paging without an offset', () => {
+    it('starts the first page at the beginning', () => {
+      expect(computeBStart(1, 0, 10, 25)).toBe(0);
+    });
+
+    it('advances by the batch size on each page', () => {
+      expect(computeBStart(2, 0, 10, 25)).toBe(10);
+      expect(computeBStart(3, 0, 10, 25)).toBe(20);
+    });
+
+    it('falls back to the default page size when b_size is unset', () => {
+      expect(computeBStart(2, 0, undefined, 25)).toBe(25);
+      expect(computeBStart(3, 0, null, 25)).toBe(50);
+    });
+
+    it('treats a zero b_size as unset', () => {
+      expect(computeBStart(2, 0, 0, 25)).toBe(25);
+    });
+  });
+
+  describe('paging with an offset', () => {
+    it('skips the leading items on the first page', () => {
+      expect(computeBStart(1, 3, 10, 25)).toBe(3);
+    });
+
+    it('keeps the offset applied on later pages', () => {
+      expect(computeBStart(2, 3, 10, 25)).toBe(13);
+      expect(computeBStart(3, 3, 10, 25)).toBe(23);
+    });
+
+    it('applies the offset to the default page size too', () => {
+      expect(computeBStart(2, 5, undefined, 25)).toBe(30);
+    });
+  });
+
+  describe('missing page', () => {
+    // getQueryStringResults is also called without a page, e.g. by the query
+    // widget's own preview. `undefined - 1` would produce NaN, which
+    // serialises to a null b_start.
+    it('defaults an undefined page to the first page', () => {
+      expect(computeBStart(undefined, 0, 1, 25)).toBe(0);
+    });
+
+    it('still honours the offset when the page is missing', () => {
+      expect(computeBStart(undefined, 4, 10, 25)).toBe(4);
+    });
+  });
+
+  describe('integer coercion', () => {
+    it('accepts numeric strings from the querystring widget', () => {
+      expect(computeBStart('2', '3', '10', 25)).toBe(13);
+    });
+
+    it('truncates floats towards zero', () => {
+      expect(computeBStart(1, 3.7, 10, 25)).toBe(3);
+      expect(computeBStart(2.9, 0, 10, 25)).toBe(10);
+    });
+
+    it('falls back on values that are not numbers', () => {
+      expect(computeBStart('abc', 'xyz', 10, 25)).toBe(0);
+      expect(computeBStart(NaN, NaN, 10, 25)).toBe(0);
+      expect(computeBStart(Infinity, 0, 10, 25)).toBe(0);
+    });
+
+    it('treats empty strings as unset', () => {
+      expect(computeBStart('', '', '', 25)).toBe(0);
+      expect(computeBStart(2, '', '', 25)).toBe(25);
+    });
+  });
+
+  describe('result is always a non-negative integer', () => {
+    it('clamps a page below one to the first page', () => {
+      expect(computeBStart(0, 0, 10, 25)).toBe(0);
+      expect(computeBStart(-5, 0, 10, 25)).toBe(0);
+    });
+
+    it('ignores a negative offset', () => {
+      expect(computeBStart(1, -3, 10, 25)).toBe(0);
+      expect(computeBStart(2, -3, 10, 25)).toBe(10);
+    });
+
+    it('returns the offset alone when no batch size can be resolved', () => {
+      expect(computeBStart(3, 7, undefined, undefined)).toBe(7);
+    });
+
+    const cases: Array<[IntegerLike, IntegerLike, IntegerLike, IntegerLike]> = [
+      [1, 0, 10, 25],
+      [undefined, undefined, undefined, undefined],
+      ['2', '3.9', '10.1', '25'],
+      [-1, -1, -1, -1],
+      [2.5, 1.5, 10.5, 25.5],
+    ];
+
+    it.each(cases)(
+      'returns an integer for (%o, %o, %o, %o)',
+      (page, offset, bSize, defaultPageSize) => {
+        const result = computeBStart(page, offset, bSize, defaultPageSize);
+        expect(Number.isInteger(result)).toBe(true);
+        expect(result).toBeGreaterThanOrEqual(0);
+      },
+    );
+  });
+});
+
+describe('computeLimit', () => {
+  describe('with a limit set', () => {
+    it('adds the offset to the limit', () => {
+      expect(computeLimit(3, 10)).toBe(13);
+    });
+
+    it('returns the limit unchanged when nothing is skipped', () => {
+      expect(computeLimit(0, 10)).toBe(10);
+    });
+
+    it('accepts values stored as strings by the widget', () => {
+      expect(computeLimit('3', '10')).toBe(13);
+    });
+
+    it('truncates floats towards zero', () => {
+      expect(computeLimit(3.9, 10.9)).toBe(13);
+    });
+
+    it('ignores a negative offset', () => {
+      expect(computeLimit(-3, 10)).toBe(10);
+    });
+  });
+
+  describe('without a usable limit', () => {
+    it('returns null when the limit is unset', () => {
+      expect(computeLimit(3, undefined)).toBeNull();
+      expect(computeLimit(3, null)).toBeNull();
+      expect(computeLimit(3, '')).toBeNull();
+    });
+
+    it('returns null when the limit is not a number', () => {
+      expect(computeLimit(3, 'abc')).toBeNull();
+      expect(computeLimit(3, NaN)).toBeNull();
+      expect(computeLimit(3, Infinity)).toBeNull();
+    });
+
+    // plone.app.querystring's querybuilder defaults limit to 0 and only
+    // applies it when truthy, so 0 means "no limit". Summing it with the
+    // offset would cap the batch at the items the listing then skips.
+    it('treats a zero limit as no limit', () => {
+      expect(computeLimit(3, 0)).toBeNull();
+      expect(computeLimit(3, '0')).toBeNull();
+    });
+
+    it('treats a negative limit as no limit', () => {
+      expect(computeLimit(3, -10)).toBeNull();
+    });
+  });
+
+  it('returns an integer or null', () => {
+    const cases: Array<[IntegerLike, IntegerLike]> = [
+      [3, 10],
+      [undefined, undefined],
+      ['3.9', '10.1'],
+      [-1, -1],
+      [0, 0],
+    ];
+
+    for (const [offset, limit] of cases) {
+      const result = computeLimit(offset, limit);
+      expect(result === null || Number.isInteger(result)).toBe(true);
+    }
+  });
+});
+
+describe('computeVisibleTotal', () => {
+  it('subtracts the skipped items from the backend total', () => {
+    expect(computeVisibleTotal(23, 3)).toBe(20);
+  });
+
+  it('returns the total untouched when nothing is skipped', () => {
+    expect(computeVisibleTotal(23, 0)).toBe(23);
+  });
+
+  it('never goes negative when the offset exceeds the total', () => {
+    expect(computeVisibleTotal(2, 5)).toBe(0);
+  });
+
+  it('accepts values stored as strings by the widget', () => {
+    expect(computeVisibleTotal('23', '3')).toBe(20);
+  });
+
+  it('falls back to zero when the total is not yet loaded', () => {
+    expect(computeVisibleTotal(undefined, 3)).toBe(0);
+    expect(computeVisibleTotal(null, 3)).toBe(0);
+  });
+
+  it('ignores a negative offset', () => {
+    expect(computeVisibleTotal(23, -3)).toBe(23);
+  });
+});
+
+describe('computeTotalPages', () => {
+  it('splits the total across whole pages', () => {
+    expect(computeTotalPages(20, 10)).toBe(2);
+    expect(computeTotalPages(23, 10)).toBe(3);
+  });
+
+  it('counts a partial page', () => {
+    expect(computeTotalPages(21, 10)).toBe(3);
+  });
+
+  it('returns zero when there is nothing to show', () => {
+    expect(computeTotalPages(0, 10)).toBe(0);
+  });
+
+  it('returns zero when no batch size can be resolved', () => {
+    expect(computeTotalPages(20, 0)).toBe(0);
+    expect(computeTotalPages(20, undefined)).toBe(0);
+  });
+
+  it('accepts values stored as strings by the widget', () => {
+    expect(computeTotalPages('20', '10')).toBe(2);
+  });
+
+  // The regression this pair exists for: 23 results, skip 3, 10 per page.
+  // Dividing the raw total gives 3 pages, but page 3 asks for b_start 23 and
+  // comes back empty. Only 20 items are reachable, so there are 2 pages.
+  it('does not advertise a page the offset makes unreachable', () => {
+    const total = 23;
+    const offset = 3;
+    const bSize = 10;
+
+    expect(computeTotalPages(total, bSize)).toBe(3);
+    expect(computeTotalPages(computeVisibleTotal(total, offset), bSize)).toBe(
+      2,
+    );
+    expect(computeBStart(3, offset, bSize, 25)).toBe(23);
+  });
+
+  it('keeps the last page reachable across the offset range', () => {
+    const total = 25;
+    const bSize = 10;
+
+    for (const offset of [0, 1, 5, 10, 15, 24, 25, 30]) {
+      const pages = computeTotalPages(
+        computeVisibleTotal(total, offset),
+        bSize,
+      );
+      if (pages > 0) {
+        const lastPageStart = computeBStart(pages, offset, bSize, 25);
+        expect(lastPageStart).toBeLessThan(total);
+      }
+    }
+  });
+});

package/src/helpers/Pagination/Pagination.ts

@@ -0,0 +1,151 @@
+/**
+ * Pagination helpers.
+ * @module helpers/Pagination/Pagination
+ */
+
+/**
+ * A value that is meant to represent an integer, but which reaches us from
+ * user-editable block settings. The querystring widget stores `offset`,
+ * `limit` and `b_size` as JSON schema `number` fields, so a value may arrive
+ * as a string (`'3'`), as a float (`3.7`), or not at all.
+ */
+export type IntegerLike = number | string | null | undefined;
+
+/**
+ * Coerce a value to an integer, or to null when it holds no usable number.
+ * Floats are truncated towards zero, since these values index into a batch.
+ * @function toIntegerOrNull
+ * @param {IntegerLike} value Value to coerce.
+ * @returns {number | null} An integer, or null when value is unset or not a
+ * finite number.
+ */
+function toIntegerOrNull(value: IntegerLike): number | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  if (typeof value === 'string' && value.trim() === '') {
+    return null;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : null;
+}
+
+/**
+ * Coerce a value to an integer, falling back when it cannot be represented.
+ * @function toInteger
+ * @param {IntegerLike} value Value to coerce.
+ * @param {number} fallback Integer returned when value is not a finite number.
+ * @returns {number} An integer.
+ */
+function toInteger(value: IntegerLike, fallback: number): number {
+  return toIntegerOrNull(value) ?? fallback;
+}
+
+/**
+ * Compute the `b_start` index for a `@querystring-search` request: the index
+ * of the first item the backend should return for the requested page.
+ *
+ * `offset` shifts the whole result set, letting a listing skip the first N
+ * items of its query while paginating over the remainder.
+ *
+ * Every parameter is coerced to an integer and the result is always a
+ * non-negative integer, so a malformed block setting degrades to a sane batch
+ * rather than sending `NaN` to the backend. When neither `bSize` nor
+ * `defaultPageSize` yields a positive batch size, paging cannot be applied and
+ * the result is `offset` alone.
+ * @function computeBStart
+ * @param {IntegerLike} page 1-based page number. Defaults to the first page.
+ * @param {IntegerLike} offset Number of leading items to skip. Defaults to 0.
+ * @param {IntegerLike} bSize Batch size configured on the block, if any.
+ * @param {IntegerLike} defaultPageSize Batch size to use when bSize is unset.
+ * @returns {number} A non-negative integer `b_start` index.
+ */
+export function computeBStart(
+  page: IntegerLike,
+  offset: IntegerLike,
+  bSize: IntegerLike,
+  defaultPageSize: IntegerLike,
+): number {
+  const pageNumber = Math.max(1, toInteger(page, 1));
+  const offsetValue = Math.max(0, toInteger(offset, 0));
+  const batchSize =
+    Math.max(0, toInteger(bSize, 0)) ||
+    Math.max(0, toInteger(defaultPageSize, 0));
+
+  return Math.max(0, (pageNumber - 1) * batchSize + offsetValue);
+}
+
+/**
+ * Compute the effective `limit` for a `@querystring-search` request.
+ *
+ * A listing that skips the first `offset` items still wants `limit` items
+ * afterwards, so the backend has to return the skipped items on top of the
+ * wanted ones: `offset + limit`.
+ *
+ * A limit of zero, or one that resolves to no usable number, means "no limit"
+ * — matching `plone.app.querystring`'s querybuilder, whose `limit` defaults to
+ * 0 and is only applied when truthy. Returning `offset` in that case would cap
+ * the batch at the very items the listing is about to skip, leaving it empty.
+ * @function computeLimit
+ * @param {IntegerLike} offset Number of leading items to skip. Defaults to 0.
+ * @param {IntegerLike} limit Number of items the listing wants, if capped.
+ * @returns {number | null} A positive integer limit, or null for no limit.
+ */
+export function computeLimit(
+  offset: IntegerLike,
+  limit: IntegerLike,
+): number | null {
+  const limitValue = toIntegerOrNull(limit);
+  if (limitValue === null || limitValue <= 0) {
+    return null;
+  }
+
+  return Math.max(0, toInteger(offset, 0)) + limitValue;
+}
+
+/**
+ * Compute how many items a listing can actually show.
+ *
+ * The `items_total` reported by `@querystring-search` is the length of the
+ * whole result set: `plone.restapi`'s HypermediaBatch derives it from the
+ * sequence length, so `b_start` never reduces it. The items an offset skips
+ * are counted in there even though the listing never renders them.
+ * @function computeVisibleTotal
+ * @param {IntegerLike} total The `items_total` reported by the backend.
+ * @param {IntegerLike} offset Number of leading items skipped. Defaults to 0.
+ * @returns {number} A non-negative integer count of reachable items.
+ */
+export function computeVisibleTotal(
+  total: IntegerLike,
+  offset: IntegerLike,
+): number {
+  const totalValue = Math.max(0, toInteger(total, 0));
+  const offsetValue = Math.max(0, toInteger(offset, 0));
+
+  return Math.max(0, totalValue - offsetValue);
+}
+
+/**
+ * Compute how many pages a listing spans.
+ *
+ * `total` is expected to be the reachable item count, so pass the result of
+ * `computeVisibleTotal` for an offset listing rather than the raw backend
+ * total. Otherwise the listing advertises pages that resolve to an empty batch.
+ * @function computeTotalPages
+ * @param {IntegerLike} total Number of items the listing can show.
+ * @param {IntegerLike} bSize Batch size, i.e. items per page.
+ * @returns {number} A non-negative integer page count, 0 when there is no
+ * usable batch size.
+ */
+export function computeTotalPages(
+  total: IntegerLike,
+  bSize: IntegerLike,
+): number {
+  const totalValue = Math.max(0, toInteger(total, 0));
+  const batchSize = Math.max(0, toInteger(bSize, 0));
+  if (batchSize <= 0) {
+    return 0;
+  }
+
+  return Math.ceil(totalValue / batchSize);
+}