feat(countRows): support optional filters and maxPages override

docs/.vitepress/tableresult-signatures.json

@@ -61,8 +61,8 @@
   },
   {
     "name": "countRows",
-    "signature": "countRows: () => Promise<number>",
-    "comment": "/**\n* Counts the number of rows currently on the page.\n* Does not paginate.\n*/"
+    "signature": "countRows: (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }) => Promise<number>",
+    "comment": "/**\n* Counts the number of rows, optionally filtered.\n* Without arguments, counts all rows. With filters, counts only matching rows.\n* Paginates when pagination is configured.\n*/"
   },
   {
     "name": "mapColumn",

docs/api/table-methods.md

@@ -405,7 +405,7 @@ await table.scrollToColumn('Notes');
 ### Signature
 
 ```typescript
-countRows: () => Promise<number>
+countRows: (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }) => Promise<number>
 ```
 
 <!-- /api-signature: countRows -->

src/typeContext.ts

@@ -866,10 +866,11 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   scrollToColumn: (columnName: string) => Promise<void>;
 
   /**
-   * Counts the number of rows currently on the page.
-   * Does not paginate.
+   * Counts the number of rows, optionally filtered.
+   * Without arguments, counts all rows. With filters, counts only matching rows.
+   * Paginates when pagination is configured.
    */
-  countRows: () => Promise<number>;
+  countRows: (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }) => Promise<number>;
 
   /**
    * Iterates over rows and extracts the value of a single column.

src/types.ts

@@ -866,10 +866,11 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   scrollToColumn: (columnName: string) => Promise<void>;
 
   /**
-   * Counts the number of rows currently on the page.
-   * Does not paginate.
+   * Counts the number of rows, optionally filtered.
+   * Without arguments, counts all rows. With filters, counts only matching rows.
+   * Paginates when pagination is configured.
    */
-  countRows: () => Promise<number>;
+  countRows: (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }) => Promise<number>;
 
   /**
    * Iterates over rows and extracts the value of a single column.

src/useTable.ts

@@ -322,27 +322,41 @@ export const useTable = <T = any>(rootLocator: Locator, configOptions: TableConf
       return resolve(config.headerSelector as Selector, rootLocator).nth(idx);
     },
 
-    countRows: async (): Promise<number> => {
+    countRows: async (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }): Promise<number> => {
       if (tableState.empty) return 0;
       await _autoInit();
+      const filtersRecord = (filters ?? {}) as Record<string, FilterValue>;
+      const hasFilters = Object.keys(filtersRecord).length > 0;
+      const effectiveMaxPages = options?.maxPages ?? config.maxPages;
       const pag = config.strategies.pagination;
-      const hasPagination = config.maxPages > 1 && !!(pag?.goNext || pag?.goNextBulk);
+      const hasPagination = effectiveMaxPages > 1 && !!(pag?.goNext || pag?.goNextBulk);
+
+      const resolveRows = () => {
+        let rows = resolve(config.rowSelector, rootLocator);
+        if (hasFilters) {
+          const map = tableMapper.getMapSync();
+          if (!map) throw new Error('Initialization Error: Table map not available. Call "await table.init()" first.');
+          rows = filterEngine.applyFilters(rows, filtersRecord, map, options?.exact ?? false, rootLocator.page(), rootLocator);
+        }
+        return rows;
+      };
+
       if (!hasPagination) {
-        log("countRows: counting rows in current viewport (no pagination)");
-        return resolve(config.rowSelector, rootLocator).count();
+        log(`countRows: counting rows in current viewport (no pagination)${hasFilters ? ` filters=${safeStringify(filtersRecord)}` : ''}`);
+        return resolveRows().count();
       }
 
-      log(`countRows: paginating up to ${config.maxPages} page(s)`);
+      log(`countRows: paginating up to ${effectiveMaxPages} page(s)${hasFilters ? ` filters=${safeStringify(filtersRecord)}` : ''}`);
       const tracker = new ElementTracker('countRows');
       let total = 0;
       let pagesScanned = 1;
       let paginationError: unknown;
       try {
         while (true) {
-          const newIndices = await tracker.getUnseenIndices(resolve(config.rowSelector, rootLocator));
+          const newIndices = await tracker.getUnseenIndices(resolveRows());
           total += newIndices.length;
           log(`countRows: page ${pagesScanned} — ${newIndices.length} row(s) (running total: ${total})`);
-          if (pagesScanned >= config.maxPages) break;
+          if (pagesScanned >= effectiveMaxPages) break;
           if (!await _advancePage(false)) break;
           pagesScanned++;
         }

tests/functional-methods.spec.ts

@@ -562,6 +562,61 @@ test.describe('new API additions', () => {
         expect(await page.locator('#current-page').innerText()).toBe('1');
     });
 
+    test('countRows with filters counts only matching rows across pages', async ({ page }) => {
+        await page.setContent(TABLE_HTML);
+        const table = useTable(page.locator('#tbl'), {
+            maxPages: 3,
+            strategies: {
+                pagination: Strategies.Pagination.click({
+                    next: () => page.locator('#next'),
+                    first: () => page.locator('#first'),
+                }),
+            },
+        });
+
+        expect(await table.countRows({ Status: 'Inactive' }, { exact: true })).toBe(3);
+        expect(await page.locator('#current-page').innerText()).toBe('1');
+    });
+
+    test('countRows with filters on single page (no pagination)', async ({ page }) => {
+        await page.setContent(TABLE_HTML);
+        const table = useTable(page.locator('#tbl'), {});
+
+        expect(await table.countRows({ Status: 'Inactive' }, { exact: true })).toBe(1);
+    });
+
+    test('countRows with maxPages option limits pagination depth', async ({ page }) => {
+        await page.setContent(TABLE_HTML);
+        const table = useTable(page.locator('#tbl'), {
+            maxPages: 3,
+            strategies: {
+                pagination: Strategies.Pagination.click({
+                    next: () => page.locator('#next'),
+                    first: () => page.locator('#first'),
+                }),
+            },
+        });
+
+        expect(await table.countRows({ Status: 'Inactive' }, { exact: true, maxPages: 2 })).toBe(2);
+        expect(await page.locator('#current-page').innerText()).toBe('1');
+    });
+
+    test('countRows with no matching filter returns 0', async ({ page }) => {
+        await page.setContent(TABLE_HTML);
+        const table = useTable(page.locator('#tbl'), {
+            maxPages: 3,
+            strategies: {
+                pagination: Strategies.Pagination.click({
+                    next: () => page.locator('#next'),
+                    first: () => page.locator('#first'),
+                }),
+            },
+        });
+
+        expect(await table.countRows({ Status: 'Deleted' })).toBe(0);
+        expect(await page.locator('#current-page').innerText()).toBe('1');
+    });
+
     test('mapColumn collects values for a single column', async ({ page }) => {
         await page.setContent(TABLE_HTML);
         const table = makeTable(page);