@rickcedwhat/playwright-smart-table 6.21.0 → 6.22.0-next.28cae60

package/dist/useTable.js

@@ -32,6 +32,9 @@ const scanPages_1 = require("./engine/scanPages");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
 const elementTracker_1 = require("./utils/elementTracker");
+const loadingWait_1 = require("./utils/loadingWait");
+const pageIndex_1 = require("./utils/pageIndex");
+const smartRowInternals_1 = require("./utils/smartRowInternals");
 // Helper to safely serialize objects containing functions for logging
 const safeStringify = (obj) => {
     try {
@@ -145,13 +148,14 @@ const useTable = (rootLocator, configOptions = {}) => {
     // Placeholder for the final table object
     let finalTable = null;
     // Helper factory
-    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier, rowSelector, renderWindowPosition = false) => {
-        const effectiveLocator = rowSelector
-            ? rootLocator.locator(rowSelector)
+    // healSelector: the per-row selector returned by resolveRowIndex (not config.rowSelector).
+    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier, healSelector, renderWindowPosition = false) => {
+        const effectiveLocator = healSelector
+            ? rootLocator.locator(healSelector)
             : rowLocator;
         const sr = (0, smartRow_1.default)(effectiveLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier, renderWindowPosition);
-        if (rowSelector)
-            sr._selfHealing = true;
+        if (healSelector)
+            (0, smartRowInternals_1.internals)(sr)._selfHealing = true;
         return sr;
     };
     const tableState = { currentPageIndex: 0, empty: false };
@@ -183,7 +187,7 @@ const useTable = (rootLocator, configOptions = {}) => {
     const _handlePrompt = async (promptName, content) => {
         let finalPrompt = content;
         finalPrompt += `\n\n👇 Useful TypeScript Definitions 👇\n\`\`\`typescript\n${minimalConfigContext_1.MINIMAL_CONFIG_CONTEXT}\n\`\`\`\n`;
-        console.log(`⚠️ Throwing error to display [${promptName}] cleanly...`);
+        (0, debugUtils_1.logDebug)(config, 'info', `Throwing error to display [${promptName}] cleanly...`);
         throw new Error(finalPrompt);
     };
     const _autoInit = async () => {
@@ -229,9 +233,12 @@ const useTable = (rootLocator, configOptions = {}) => {
     };
     const result = {
         get currentPageIndex() { return tableState.currentPageIndex; },
-        set currentPageIndex(v) { tableState.currentPageIndex = v; },
+        set currentPageIndex(v) {
+            console.warn('[SmartTable] Manually assigning table.currentPageIndex can desync pagination path planning. Prefer reset() / library navigation; writable access may become read-only in v7.');
+            tableState.currentPageIndex = v;
+        },
         init: async (options) => {
-            var _a;
+            var _a, _b, _c;
             if (tableMapper.isInitialized() || tableState.empty)
                 return result;
             if (config.strategies.sorting)
@@ -240,6 +247,10 @@ const useTable = (rootLocator, configOptions = {}) => {
                 (0, validation_1.validateFillStrategy)(config.strategies.fill);
             (0, debugUtils_1.warnIfDebugInCI)(config);
             (0, debugUtils_1.logDebug)(config, 'info', 'Initializing table');
+            if (config.maxPages === 1 &&
+                (((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goNext) || ((_b = config.strategies.pagination) === null || _b === void 0 ? void 0 : _b.goNextBulk))) {
+                console.warn('[SmartTable] maxPages is 1 but a pagination strategy is configured — iteration/find will never leave page 1. Pass maxPages: N (or Infinity) to scan further pages.');
+            }
             let map;
             try {
                 map = await tableMapper.getMap(options === null || options === void 0 ? void 0 : options.timeout);
@@ -256,7 +267,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw headerError;
             }
             (0, debugUtils_1.logDebug)(config, 'info', `Table initialized with ${map.size} columns`, Array.from(map.keys()));
-            if ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.detectCurrentPage) {
+            if ((_c = config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.detectCurrentPage) {
                 try {
                     const detected = await config.strategies.pagination.detectCurrentPage(rootLocator);
                     if (Number.isInteger(detected) && detected >= 0) {
@@ -370,10 +381,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             const isTableLoading = (_e = config.strategies.loading) === null || _e === void 0 ? void 0 : _e.isTableLoading;
             if (isTableLoading) {
                 const ctx = createStrategyContext();
-                while (await isTableLoading(ctx)) {
-                    log('countRows: table is loading... waiting');
-                    await rootLocator.page().waitForTimeout(200);
-                }
+                await (0, loadingWait_1.waitWhileTableLoading)(config, ctx, rootLocator.page(), 'countRows');
             }
             if (!hasPagination) {
                 log(`countRows: counting rows in current viewport (no pagination)${hasFilters ? ` filters=${safeStringify(filtersRecord)}` : ''}`);
@@ -396,10 +404,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         if (!isTableLoading)
                             return;
                         const ctx = createStrategyContext();
-                        while (await isTableLoading(ctx)) {
-                            log('countRows: table is loading... waiting');
-                            await rootLocator.page().waitForTimeout(200);
-                        }
+                        await (0, loadingWait_1.waitWhileTableLoading)(config, ctx, rootLocator.page(), 'countRows');
                     },
                 }, async ({ pagesScanned: pageNum }) => {
                     const rowLocators = resolveRows();
@@ -592,7 +597,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         },
         sorting: {
             apply: async (columnName, direction) => {
-                var _a, _b, _c, _d, _e;
+                var _a, _b, _c, _d, _e, _f;
                 await _autoInit();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
@@ -607,15 +612,15 @@ const useTable = (rootLocator, configOptions = {}) => {
                     }
                     await config.strategies.sorting.doSort({ columnName, direction, context });
                     if ((_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isTableLoading) {
-                        const timeout = (_b = config.strategies.loading.sortStabilizationTimeout) !== null && _b !== void 0 ? _b : 10000;
-                        const poll = (_c = config.strategies.loading.sortStabilizationPollInterval) !== null && _c !== void 0 ? _c : 100;
-                        const deadline = Date.now() + timeout;
-                        while (Date.now() < deadline && await config.strategies.loading.isTableLoading(context)) {
-                            await rootLocator.page().waitForTimeout(poll);
-                        }
+                        const timeout = (_c = (_b = config.strategies.loading.sortStabilizationTimeout) !== null && _b !== void 0 ? _b : config.strategies.loading.loadingTimeout) !== null && _c !== void 0 ? _c : 10000;
+                        const poll = (_d = config.strategies.loading.sortStabilizationPollInterval) !== null && _d !== void 0 ? _d : 100;
+                        await (0, loadingWait_1.waitWhileTableLoading)(config, context, rootLocator.page(), 'sorting.apply', {
+                            timeout,
+                            pollInterval: poll,
+                        });
                     }
                     else {
-                        const fallback = (_e = (_d = config.strategies.loading) === null || _d === void 0 ? void 0 : _d.sortStabilizationFallbackDelay) !== null && _e !== void 0 ? _e : 200;
+                        const fallback = (_f = (_e = config.strategies.loading) === null || _e === void 0 ? void 0 : _e.sortStabilizationFallbackDelay) !== null && _f !== void 0 ? _f : 200;
                         await rootLocator.page().waitForTimeout(fallback);
                     }
                     await (0, debugUtils_1.debugDelay)(config, 'default');
@@ -767,10 +772,14 @@ const useTable = (rootLocator, configOptions = {}) => {
             await _handlePrompt('Smart Table Config', content);
         },
         generateConfigPrompt: async () => {
-            console.warn('⚠️ [playwright-smart-table] generateConfigPrompt() is deprecated and will be removed in v7.0.0. Please use generateConfig() instead.');
+            (0, debugUtils_1.logDebug)(config, 'error', 'generateConfigPrompt() is deprecated and will be removed in v7.0.0. Please use generateConfig() instead.');
             return result.generateConfig();
         },
     };
+    Object.defineProperty(result, pageIndex_1.SET_CURRENT_PAGE_INDEX, {
+        value: (v) => { tableState.currentPageIndex = v; },
+        enumerable: false,
+    });
     createStrategyContext = () => ({
         root: rootLocator,
         config,

package/dist/utils/cssSelector.d.ts

@@ -0,0 +1,14 @@
+import type { TableSelector } from '../types';
+type SelectorKey = 'headerSelector' | 'rowSelector' | 'cellSelector';
+/** Viewport range meaning "can't measure": callers treat everything as possibly visible and verify in the DOM. */
+export declare const UNKNOWN_RANGE: {
+    first: number;
+    last: number;
+};
+/**
+ * Returns the configured selector when it is a CSS string. Features that run
+ * `querySelectorAll` in the browser can't use a function selector; for those this warns
+ * once per config + feature and returns `null` so the caller can skip that step.
+ */
+export declare function cssSelectorOrWarn(config: Partial<Record<SelectorKey, TableSelector>>, key: SelectorKey, feature: string): string | null;
+export {};

package/dist/utils/cssSelector.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_RANGE = void 0;
+exports.cssSelectorOrWarn = cssSelectorOrWarn;
+/** Viewport range meaning "can't measure": callers treat everything as possibly visible and verify in the DOM. */
+exports.UNKNOWN_RANGE = { first: 0, last: Number.POSITIVE_INFINITY };
+const warned = new WeakMap();
+/**
+ * Returns the configured selector when it is a CSS string. Features that run
+ * `querySelectorAll` in the browser can't use a function selector; for those this warns
+ * once per config + feature and returns `null` so the caller can skip that step.
+ */
+function cssSelectorOrWarn(config, key, feature) {
+    const selector = config[key];
+    if (typeof selector === 'string')
+        return selector;
+    if (selector === undefined)
+        return null;
+    let seen = warned.get(config);
+    if (!seen)
+        warned.set(config, (seen = new Set()));
+    const id = `${key}:${feature}`;
+    if (!seen.has(id)) {
+        seen.add(id);
+        console.warn(`[SmartTable] ${feature} needs ${key} to be a CSS string, but a function was configured — skipping it. Use a string ${key} to enable ${feature}.`);
+    }
+    return null;
+}

package/dist/utils/loadingWait.d.ts

@@ -0,0 +1,15 @@
+import type { Page } from '@playwright/test';
+import type { FinalTableConfig, TableContext } from '../types';
+/**
+ * Poll `loading.isTableLoading` until false or timeout.
+ * Shared by countRows, findRow(s), and sort stabilization (#434).
+ *
+ * Timeout resolution (first defined wins):
+ * 1. Explicit `options.timeout` — e.g. the sort caller's stabilization timeout
+ * 2. `loadingTimeout` — general gate for any isTableLoading poll
+ * 3. 10_000 ms default
+ */
+export declare function waitWhileTableLoading(config: FinalTableConfig, context: TableContext, page: Page, label: string, options?: {
+    timeout?: number;
+    pollInterval?: number;
+}): Promise<void>;

package/dist/utils/loadingWait.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitWhileTableLoading = waitWhileTableLoading;
+const debugUtils_1 = require("./debugUtils");
+/**
+ * Poll `loading.isTableLoading` until false or timeout.
+ * Shared by countRows, findRow(s), and sort stabilization (#434).
+ *
+ * Timeout resolution (first defined wins):
+ * 1. Explicit `options.timeout` — e.g. the sort caller's stabilization timeout
+ * 2. `loadingTimeout` — general gate for any isTableLoading poll
+ * 3. 10_000 ms default
+ */
+async function waitWhileTableLoading(config, context, page, label, options) {
+    var _a, _b, _c, _d, _e;
+    const isTableLoading = (_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isTableLoading;
+    if (!isTableLoading)
+        return;
+    const loading = config.strategies.loading;
+    const timeout = (_c = (_b = options === null || options === void 0 ? void 0 : options.timeout) !== null && _b !== void 0 ? _b : loading.loadingTimeout) !== null && _c !== void 0 ? _c : 10000;
+    const poll = (_e = (_d = options === null || options === void 0 ? void 0 : options.pollInterval) !== null && _d !== void 0 ? _d : loading.sortStabilizationPollInterval) !== null && _e !== void 0 ? _e : 200;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        let timer;
+        try {
+            // A custom predicate may never settle. Stop waiting when the budget expires;
+            // Promise.race also handles any later rejection from that predicate.
+            const expired = new Promise(resolve => {
+                timer = setTimeout(() => resolve(false), Math.max(0, deadline - Date.now()));
+            });
+            if (!(await Promise.race([isTableLoading(context), expired])))
+                return;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return;
+        (0, debugUtils_1.logDebug)(config, 'verbose', `${label}: table is loading... waiting`);
+        await page.waitForTimeout(Math.min(poll, remaining));
+    }
+}

package/dist/utils/pageIndex.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal setter for `table.currentPageIndex` used by library navigation
+ * (bringIntoView path planner, etc.) so the public setter can warn on
+ * external writes without spamming on every library update (#434).
+ */
+export declare const SET_CURRENT_PAGE_INDEX: unique symbol;
+export type PageIndexWritable = {
+    currentPageIndex: number;
+    [SET_CURRENT_PAGE_INDEX]?: (n: number) => void;
+};
+/** Prefer the internal setter when present; fall back to the public property. */
+export declare function setCurrentPageIndex(table: PageIndexWritable, n: number): void;

package/dist/utils/pageIndex.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SET_CURRENT_PAGE_INDEX = void 0;
+exports.setCurrentPageIndex = setCurrentPageIndex;
+/**
+ * Internal setter for `table.currentPageIndex` used by library navigation
+ * (bringIntoView path planner, etc.) so the public setter can warn on
+ * external writes without spamming on every library update (#434).
+ */
+exports.SET_CURRENT_PAGE_INDEX = Symbol.for('playwright-smart-table.setCurrentPageIndex');
+/** Prefer the internal setter when present; fall back to the public property. */
+function setCurrentPageIndex(table, n) {
+    const internal = table[exports.SET_CURRENT_PAGE_INDEX];
+    if (typeof internal === 'function') {
+        internal(n);
+        return;
+    }
+    table.currentPageIndex = n;
+}

package/dist/utils/resolveCellLocator.d.ts

@@ -22,8 +22,8 @@ export declare function resolveCellLocator(args: {
  * `filter({ has })`. Using the rows collection or a document-rooted parent nests
  * the row selector and matches nothing.
  *
- * Without `getCellLocator`, keeps the historical page-scoped `cellSelector.nth(i)`
- * template that Playwright re-bases into each row.
+ * Without `getCellLocator`, resolves `cellSelector` against the same `:scope` row so a
+ * function `cellSelector` receives a Locator, and Playwright re-bases it into each row.
  */
 export declare function resolveCellLocatorForFilter(args: {
     config: FinalTableConfig;

package/dist/utils/resolveCellLocator.js

@@ -31,14 +31,14 @@ function resolveCellLocator(args) {
  * `filter({ has })`. Using the rows collection or a document-rooted parent nests
  * the row selector and matches nothing.
  *
- * Without `getCellLocator`, keeps the historical page-scoped `cellSelector.nth(i)`
- * template that Playwright re-bases into each row.
+ * Without `getCellLocator`, resolves `cellSelector` against the same `:scope` row so a
+ * function `cellSelector` receives a Locator, and Playwright re-bases it into each row.
  */
 function resolveCellLocatorForFilter(args) {
     var _a;
     const { config, resolve, page, root, columnName, columnIndex } = args;
+    const scopeRow = page.locator(':scope');
     if ((_a = config.strategies) === null || _a === void 0 ? void 0 : _a.getCellLocator) {
-        const scopeRow = page.locator(':scope');
         return config.strategies.getCellLocator({
             row: scopeRow,
             root: root !== null && root !== void 0 ? root : scopeRow,
@@ -48,5 +48,5 @@ function resolveCellLocatorForFilter(args) {
             config,
         });
     }
-    return resolve(config.cellSelector, page).nth(columnIndex);
+    return resolve(config.cellSelector, scopeRow).nth(columnIndex);
 }

package/dist/utils/smartRowInternals.d.ts

@@ -0,0 +1,14 @@
+import type { SmartRow } from '../types';
+import type { NavigationBarrier } from './navigationBarrier';
+/**
+ * Library-private state stored on SmartRow instances. Not part of the public `SmartRow` type.
+ */
+export interface SmartRowInternals {
+    /** Row re-resolves itself from the `resolveRowIndex` selector on every use (DOM recycling). */
+    _selfHealing?: boolean;
+    /** Row is being processed inside a batch (map/forEach/filter or findRows). */
+    _inBatch?: boolean;
+    /** Barrier coordinating column scrolls across rows in `synchronized` iteration. */
+    _barrier?: NavigationBarrier;
+}
+export declare function internals(row: SmartRow<any>): SmartRowInternals;

package/dist/utils/smartRowInternals.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.internals = internals;
+function internals(row) {
+    return row;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.21.0",
+  "version": "6.22.0-next.28cae60",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",