@rickcedwhat/playwright-smart-table 5.3.0 → 6.0.0

package/dist/src/typeContext.js

@@ -0,0 +1,465 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TYPE_CONTEXT = void 0;
+/**
+ * 🤖 AUTO-GENERATED FILE. DO NOT EDIT.
+ * This file is generated by scripts/embed-types.js
+ * It contains the raw text of types.ts to provide context for LLM prompts.
+ */
+exports.TYPE_CONTEXT = `
+/**
+ * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.
+ * @example
+ * // String selector
+ * rowSelector: 'tbody tr'
+ * 
+ * // Function selector
+ * rowSelector: (root) => root.locator('[role="row"]')
+ */
+export type Selector = string | ((root: Locator | Page) => Locator);
+
+/**
+ * Function to get a cell locator given row, column info.
+ * Replaces the old cellResolver.
+ */
+export type GetCellLocatorFn = (args: {
+  row: Locator;
+  columnName: string;
+  columnIndex: number;
+  rowIndex?: number;
+  page: Page;
+}) => Locator;
+
+/**
+ * Function to get the currently active/focused cell.
+ * Returns null if no cell is active.
+ */
+export type GetActiveCellFn = (args: TableContext) => Promise<{
+  rowIndex: number;
+  columnIndex: number;
+  columnName?: string;
+  locator: Locator;
+} | null>;
+
+
+/**
+ * SmartRow - A Playwright Locator with table-aware methods.
+ * 
+ * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.
+ * 
+ * @example
+ * const row = table.getRow({ Name: 'John Doe' });
+ * await row.click(); // Standard Locator method
+ * const email = row.getCell('Email'); // Table-aware method
+ * const data = await row.toJSON(); // Extract all row data
+ * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields
+ */
+export type SmartRow<T = any> = Locator & {
+  /** Optional row index (0-based) if known */
+  rowIndex?: number;
+
+  /**
+   * Get a cell locator by column name.
+   * @param column - Column name (case-sensitive)
+   * @returns Locator for the cell
+   * @example
+   * const emailCell = row.getCell('Email');
+   * await expect(emailCell).toHaveText('john@example.com');
+   */
+  getCell(column: string): Locator;
+
+  /**
+   * Extract all cell data as a key-value object.
+   * @param options - Optional configuration
+   * @param options.columns - Specific columns to extract (extracts all if not specified)
+   * @returns Promise resolving to row data
+   * @example
+   * const data = await row.toJSON();
+   * // { Name: 'John', Email: 'john@example.com', ... }
+   * 
+   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
+   * // { Name: 'John', Email: 'john@example.com' }
+   */
+  toJSON(options?: { columns?: string[] }): Promise<T>;
+
+  /**
+   * Scrolls/paginates to bring this row into view.
+   * Only works if rowIndex is known (e.g., from getRowByIndex).
+   * @throws Error if rowIndex is unknown
+   */
+  bringIntoView(): Promise<void>;
+
+  /**
+   * Intelligently fills form fields in the row.
+   * Automatically detects input types (text, select, checkbox, contenteditable).
+   * 
+   * @param data - Column-value pairs to fill
+   * @param options - Optional configuration
+   * @param options.inputMappers - Custom input selectors per column
+   * @example
+   * // Auto-detection
+   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });
+   * 
+   * // Custom input mappers
+   * await row.smartFill(
+   *   { Name: 'John' },
+   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }
+   * );
+   */
+  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
+};
+
+export type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };
+
+/**
+ * Defines the contract for a sorting strategy.
+ */
+export interface SortingStrategy {
+  /**
+   * Performs the sort action on a column.
+   */
+  doSort(options: {
+    columnName: string;
+    direction: 'asc' | 'desc';
+    context: StrategyContext;
+  }): Promise<void>;
+
+  /**
+   * Retrieves the current sort state of a column.
+   */
+  getSortState(options: {
+    columnName: string;
+    context: StrategyContext;
+  }): Promise<'asc' | 'desc' | 'none'>;
+}
+
+/**
+ * Debug configuration for development and troubleshooting
+ */
+export type DebugConfig = {
+  /**
+   * Slow down operations for debugging
+   * - number: Apply same delay to all operations (ms)
+   * - object: Granular delays per operation type
+   */
+  slow?: number | {
+    pagination?: number;
+    getCell?: number;
+    findRow?: number;
+    default?: number;
+  };
+  /**
+   * Log level for debug output
+   * - 'verbose': All logs (verbose, info, error)
+   * - 'info': Info and error logs only
+   * - 'error': Error logs only
+   * - 'none': No logs
+   */
+  logLevel?: 'verbose' | 'info' | 'error' | 'none';
+};
+
+export interface TableContext {
+  root: Locator;
+  config: FinalTableConfig;
+  page: Page;
+  resolve: (selector: Selector, parent: Locator | Page) => Locator;
+}
+
+export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+
+export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
+
+export interface PromptOptions {
+  /**
+   * Output Strategy:
+   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
+   * - 'console': Standard console logs (Default).
+   */
+  output?: 'console' | 'error';
+  includeTypes?: boolean;
+}
+
+export type FillStrategy = (options: {
+  row: SmartRow;
+  columnName: string;
+  value: any;
+  index: number;
+  page: Page;
+  rootLocator: Locator;
+  table: TableResult; // The parent table instance
+  fillOptions?: FillOptions;
+}) => Promise<void>;
+
+export type { HeaderStrategy } from './strategies/headers';
+export type { CellNavigationStrategy } from './strategies/columns';
+
+/**
+ * Strategy to resolve column names (string or regex) to their index.
+ */
+export type { ColumnResolutionStrategy } from './strategies/resolution';
+
+/**
+ * Strategy to filter rows based on criteria.
+ */
+export interface FilterStrategy {
+  apply(options: {
+    rows: Locator;
+    filter: { column: string, value: string | RegExp | number };
+    colIndex: number;
+    tableContext: TableContext;
+  }): Locator;
+}
+
+/**
+ * Strategy to check if the table or rows are loading.
+ */
+export interface LoadingStrategy {
+  isTableLoading?: (context: TableContext) => Promise<boolean>;
+  isRowLoading?: (row: SmartRow) => Promise<boolean>;
+}
+
+/**
+ * Organized container for all table interaction strategies.
+ */
+export interface TableStrategies {
+  /** Strategy for discovering/scanning headers */
+  header?: HeaderStrategy;
+  /** Strategy for navigating to specific cells (row + column) */
+  cellNavigation?: CellNavigationStrategy;
+  /** Strategy for filling form inputs */
+  fill?: FillStrategy;
+  /** Strategy for paginating through data */
+  pagination?: PaginationStrategy;
+  /** Strategy for sorting columns */
+  sorting?: SortingStrategy;
+  /** Strategy for deduplicating rows during iteration/scrolling */
+  dedupe?: DedupeStrategy;
+  /** Function to get a cell locator */
+  getCellLocator?: GetCellLocatorFn;
+  /** Function to get the currently active/focused cell */
+  getActiveCell?: GetActiveCellFn;
+  /** Custom helper to check if a table is fully loaded/ready */
+  isTableLoaded?: (args: TableContext) => Promise<boolean>;
+  /** Custom helper to check if a row is fully loaded/ready */
+  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;
+  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */
+  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;
+  /** Strategy for detecting loading states */
+  loading?: LoadingStrategy;
+}
+
+/**
+ * Configuration options for useTable.
+ */
+export interface TableConfig {
+  /** Selector for the table headers */
+  headerSelector?: string;
+  /** Selector for the table rows */
+  rowSelector?: string;
+  /** Selector for the cells within a row */
+  cellSelector?: string;
+  /** Number of pages to scan for verification */
+  maxPages?: number;
+  /** Hook to rename columns dynamically */
+  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;
+  /** Automatically scroll to table on init */
+  autoScroll?: boolean;
+  /** Debug options for development and troubleshooting */
+  debug?: DebugConfig;
+  /** Reset hook */
+  onReset?: (context: TableContext) => Promise<void>;
+  /** All interaction strategies */
+  strategies?: TableStrategies;
+}
+
+export interface FinalTableConfig extends TableConfig {
+  headerSelector: string;
+  rowSelector: string;
+  cellSelector: string;
+  maxPages: number;
+  autoScroll: boolean;
+  debug?: TableConfig['debug'];
+  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;
+  onReset: (context: TableContext) => Promise<void>;
+  strategies: TableStrategies;
+}
+
+
+export interface FillOptions {
+  /**
+   * Custom input mappers for specific columns.
+   * Maps column names to functions that return the input locator for that cell.
+   */
+  inputMappers?: Record<string, (cell: Locator) => Locator>;
+}
+
+/**
+ * Options for generateConfigPrompt
+ */
+export interface PromptOptions {
+  /**
+   * Output Strategy:
+   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
+   * - 'console': Standard console logs (Default).
+   */
+  output?: 'console' | 'error';
+  /**
+   * Include TypeScript type definitions in the prompt
+   * @default true
+   */
+  includeTypes?: boolean;
+}
+
+export interface TableResult<T = any> {
+  /**
+   * Initializes the table by resolving headers. Must be called before using sync methods.
+   * @param options Optional timeout for header resolution (default: 3000ms)
+   */
+  init(options?: { timeout?: number }): Promise<TableResult>;
+
+  /**
+   * SYNC: Checks if the table has been initialized.
+   * @returns true if init() has been called and completed, false otherwise
+   */
+  isInitialized(): boolean;
+
+  getHeaders: () => Promise<string[]>;
+  getHeaderCell: (columnName: string) => Promise<Locator>;
+
+  /**
+   * Finds a row by filters on the current page only. Returns immediately (sync).
+   * Throws error if table is not initialized.
+   */
+  getRow: (
+    filters: Record<string, string | RegExp | number>,
+    options?: { exact?: boolean }
+  ) => SmartRow;
+
+  /**
+   * Gets a row by 1-based index on the current page.
+   * Throws error if table is not initialized.
+   * @param index 1-based row index
+   * @param options Optional settings including bringIntoView
+   */
+  getRowByIndex: (
+    index: number,
+    options?: { bringIntoView?: boolean }
+  ) => SmartRow;
+
+  /**
+   * ASYNC: Searches for a single row across pages using pagination.
+   * Auto-initializes the table if not already initialized.
+   * @param filters - The filter criteria to match
+   * @param options - Search options including exact match and max pages
+   */
+  findRow: (
+    filters: Record<string, string | RegExp | number>,
+    options?: { exact?: boolean, maxPages?: number }
+  ) => Promise<SmartRow>;
+
+  /**
+   * ASYNC: Searches for all matching rows across pages using pagination.
+   * Auto-initializes the table if not already initialized.
+   * @param filters - The filter criteria to match
+   * @param options - Search options including exact match, max pages, and asJSON
+   */
+  findRows: <R extends { asJSON?: boolean }>(
+    filters: Record<string, string | RegExp | number>,
+    options?: { exact?: boolean, maxPages?: number } & R
+  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+
+  /**
+   * Navigates to a specific column using the configured CellNavigationStrategy.
+   */
+  scrollToColumn: (columnName: string) => Promise<void>;
+
+  /**
+   * Gets all rows on the current page only (does not paginate).
+   * Auto-initializes the table if not already initialized.
+   * Returns a SmartRowArray which extends Array with a toJSON() helper method.
+   * @param options - Filter options
+   */
+  getRows: (options?: { filter?: Record<string, any>, exact?: boolean }) => Promise<SmartRowArray>;
+
+  /**
+   * Resets the table state (clears cache, flags) and invokes the onReset strategy.
+   */
+  reset: () => Promise<void>;
+
+  /**
+   * Revalidates the table's structure (headers, columns) without resetting pagination or state.
+   * Useful when columns change visibility or order dynamically.
+   */
+  revalidate: () => Promise<void>;
+
+  /**
+   * Scans a specific column across all pages and returns the values.
+   */
+  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;
+
+  /**
+   * Provides access to sorting actions and assertions.
+   */
+  sorting: {
+    /**
+     * Applies the configured sorting strategy to the specified column.
+     * @param columnName The name of the column to sort.
+     * @param direction The direction to sort ('asc' or 'desc').
+     */
+    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;
+    /**
+     * Gets the current sort state of a column using the configured sorting strategy.
+     * @param columnName The name of the column to check.
+     * @returns A promise that resolves to 'asc', 'desc', or 'none'.
+     */
+    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
+  };
+
+  /**
+   * Iterates through paginated table data, calling the callback for each iteration.
+   * Callback return values are automatically appended to allData, which is returned.
+   */
+  iterateThroughTable: <T = any>(
+    callback: (context: {
+      index: number;
+      isFirst: boolean;
+      isLast: boolean;
+      rows: SmartRowArray;
+      allData: T[];
+      table: RestrictedTableResult;
+      batchInfo?: {
+        startIndex: number;
+        endIndex: number;
+        size: number;
+      };
+
+    }) => T | T[] | Promise<T | T[]>,
+    options?: {
+      pagination?: PaginationStrategy;
+      dedupeStrategy?: DedupeStrategy;
+      maxIterations?: number;
+      batchSize?: number;
+      getIsFirst?: (context: { index: number }) => boolean;
+      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;
+      beforeFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
+      afterLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
+      /**
+       * If true, flattens array results from callback into the main data array.
+       * If false (default), pushes the return value as-is (preserves batching/arrays).
+       */
+      autoFlatten?: boolean;
+    }
+  ) => Promise<T[]>;
+
+  /**
+   * Generate an AI-friendly configuration prompt for debugging.
+   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
+   */
+  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
+}
+
+/**
+ * Restricted table result that excludes methods that shouldn't be called during iteration.
+ */
+export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;
+`;