@sungen/driver-ui 3.2.8 → 3.2.10-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-ui",
-  "version": "3.2.8",
+  "version": "3.2.10-beta.1",
   "description": "Sungen UI capability (Playwright) — step patterns, viewpoint gate, and phase hooks. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.8"
+    "@sun-asterisk/sungen": "3.2.10-beta.1"
   },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"

package/src/app-profile-presets.ts

@@ -0,0 +1,74 @@
+/**
+ * App-profile presets shipped with the UI driver (spec: sungen_app_profile_spec.md §3).
+ * A preset is itself an AppProfile-shaped object that a project's `qa/app.yaml` pulls in
+ * via `extends: <name>` (or `extends: "@sungen/app-<name>"`). The project file always
+ * wins over the preset; per-element `variant:`/`scope:` in selectors.yaml wins over both.
+ *
+ * Keep presets truthful and minimal — every key must be consumed by a compiler slice
+ * (portal_roles → dialog-scope exemption; feedback.toast → name policy; widgets → the
+ * P3 recipe engine reads these when it lands).
+ */
+export const APP_PROFILE_PRESETS: Record<string, unknown> = {
+  // Reserved base layer — ALWAYS merged first by the loader (not listed in extends).
+  // Ships the built-in widget recipes so a per-element `variant: radix-select` works
+  // even in a project with no qa/app.yaml at all.
+  builtin: {
+    recipes: {
+      // Radix UI Select (incl. shadcn/ui): options portal to body with proper ARIA roles.
+      'radix-select': {
+        select: [
+          { click: '$trigger' },
+          { clickText: { role: 'option', text: '$value', exact: true } },
+        ],
+      },
+      // Ant Design Select: closed panels stay in the DOM hidden — scope every lookup
+      // to the VISIBLE dropdown panel. `waitFor: attached` first because a select that
+      // already holds a value collapses its input to ~0px (the chip covers the click
+      // target). `clickText` scrolls the target option into view before clicking, which
+      // nudges a lazily-rendered / below-the-fold option list.
+      'antd-select': {
+        select: [
+          { waitFor: { target: '$trigger', state: 'attached' } },
+          { click: '$trigger' },
+          { waitFor: '.ant-select-dropdown:not(.ant-select-dropdown-hidden)' },
+          { clickText: { within: '.ant-select-dropdown:not(.ant-select-dropdown-hidden)', text: '$value' } },
+        ],
+      },
+      // Ant Design DatePicker (typed input + panel): after typing, the panel keeps
+      // blocking pointer events; a single blur dismisses it (Escape/force-click are
+      // unreliable). Enter commits the typed value first.
+      'antd-datepicker': {
+        fill: [
+          { click: '$trigger' },
+          { type: '$value' },
+          { press: 'Enter' },
+          { blur: '$trigger' },
+        ],
+      },
+    },
+  },
+
+  // Classic server-rendered / native-widget apps: no portals anywhere, native <select>.
+  native: {
+    app: { ui_library: 'native' },
+    layers: { portal_roles: [] },
+    widgets: { select: 'native' },
+  },
+
+  // Radix UI (incl. shadcn/ui): Select/Menu/Tooltip render through portals onto
+  // document.body; Toast has no accessible label by default (name derives from content).
+  radix: {
+    app: { ui_library: 'radix' },
+    layers: { portal_roles: ['option', 'listbox', 'menu', 'menuitem', 'tooltip'] },
+    feedback: { toast: { role: 'status', named_by: 'content' } },
+    widgets: { select: 'radix-select' },
+  },
+
+  // Ant Design: dropdown/picker panels portal to document.body (and closed panels stay
+  // in the DOM hidden — recipes must scope to the VISIBLE panel, handled in P3).
+  antd: {
+    app: { ui_library: 'antd' },
+    layers: { portal_roles: ['option', 'listbox', 'menu', 'menuitem', 'tooltip'] },
+    widgets: { select: 'antd-select' },
+  },
+};

package/src/index.ts

@@ -26,6 +26,7 @@ import type {
 } from '@sun-asterisk/sungen';
 import { loadCatalog, viewpointGate, assertionDepth, dataThemesFor } from '@sun-asterisk/sungen';
 
+import { APP_PROFILE_PRESETS } from './app-profile-presets';
 import { setupPatterns } from './patterns/setup-patterns';
 import { navigationPatterns } from './patterns/navigation-patterns';
 import { formPatterns } from './patterns/form-patterns';
@@ -113,6 +114,7 @@ export function register(registry: CapabilityRegistry): void {
     viewpoints: loadCatalog, // UI owns the 17-pattern universal viewpoint catalog
     gateProvider: uiGateProvider as (i: unknown) => unknown, // viewpoint coverage + depth
     sensors: [uiViewpointGateSensor],
+    appProfilePresets: APP_PROFILE_PRESETS, // qa/app.yaml `extends: native|radix|antd`
   });
 }
 

package/src/patterns/capture-patterns.ts

@@ -1,5 +1,6 @@
 import { ParsedStep } from '@sun-asterisk/sungen';
 import { StepPattern, StepTemplateData } from '@sun-asterisk/sungen';
+import { rowIndexExpr, TABLE_ROW_NTH } from '../utils/row-index';
 
 /**
  * Capture & collection patterns (P5) — enable cross-screen data consistency and
@@ -20,6 +21,44 @@ import { StepPattern, StepTemplateData } from '@sun-asterisk/sungen';
  *               Roadmap Q2 — the fix for "each card exposes X" claims.
  */
 export const capturePatterns: StepPattern[] = [
+  {
+    // FR2 (issue #468): `User remember [Col] column in [Table] table row {{n}} as {{var}}`
+    // — read a cell by POSITION so a later `… in [Table] table row {{n}}` action targets
+    // the same `getByRole('row').nth(...)` chain (no read-then-act two-query race).
+    // The cell comes from the table entry's `columns:` config (index); without one, the
+    // whole row's text is captured.
+    // NOTE: the `table-` name prefix opts out of generateStep's parentRef auto-scoping
+    // (the table locator is resolved internally from the step text, like all table-* patterns).
+    name: 'table-capture-row-nth',
+    matcher: (step: ParsedStep) =>
+      /\bremember\b/i.test(step.text) && /\bas\s+\{\{[^}]+\}\}/i.test(step.text) && TABLE_ROW_NTH.test(step.text),
+    resolver: (step, context): StepTemplateData => {
+      const brackets = step.text.match(/\[([^\]]+)\]/g) || [];
+      const columnName = brackets[0]?.replace(/[\[\]]/g, '') || '';
+      const tableName = brackets.length >= 2 ? brackets[1].replace(/[\[\]]/g, '') : '';
+      const rowToken = step.text.match(TABLE_ROW_NTH)![1];
+      const varName = step.text.match(/\bas\s+\{\{([^}]+)\}\}/i)![1].trim();
+
+      const tableResolved = context.selectorResolver.resolveSelector(
+        tableName, context.featureName, 'table', 0
+      );
+
+      // Cell by column index from the table entry's `columns:` config.
+      const columnKey = columnName.normalize('NFC').toLowerCase().trim().replace(/\s+/g, ' ');
+      const column = tableResolved.columns?.[columnKey];
+      const cellExpr = column !== undefined
+        ? `tableRow.getByRole('cell').nth(${column.index})`
+        : 'tableRow';
+
+      context.dataResolver.registerCaptured(varName);
+      return {
+        templateName: 'capture-row-column',
+        data: { ...tableResolved, varName, cellExpr, rowIndexExpr: rowIndexExpr(rowToken, context) },
+        comment: `Remember ${columnName} column in ${tableName} table row ${rowToken} as ${varName}`,
+      };
+    },
+    priority: 36,
+  },
   {
     name: 'capture-variable',
     matcher: (step: ParsedStep) =>

package/src/patterns/form-patterns.ts

@@ -1,5 +1,5 @@
 import { ParsedStep } from '@sun-asterisk/sungen';
-import { StepPattern, StepTemplateData } from '@sun-asterisk/sungen';
+import { StepPattern, StepTemplateData, expandRecipe } from '@sun-asterisk/sungen';
 
 /**
  * Form action patterns: fill, type, select, check, uncheck
@@ -52,6 +52,28 @@ export const formPatterns: StepPattern[] = [
         value = step.value!;
       }
 
+      // Widget recipe hook: per-element `variant:` wins; else, for a date-picker element,
+      // the profile's `widgets.datepicker` (custom datepickers — readonly inputs that need
+      // open-panel choreography). Resolves to a recipe with a `fill` intent.
+      const isDatePicker = /date-?picker|calendar/.test(String(step.elementType || ''));
+      const fillVariant = resolved.variant || (isDatePicker ? context.appProfile?.widgetVariants?.['datepicker'] : undefined);
+      const fillRecipe = fillVariant ? context.appProfile?.recipes?.[fillVariant]?.['fill'] : undefined;
+      if (fillRecipe) {
+        try {
+          const steps = expandRecipe(fillRecipe as unknown[], {
+            triggerCode: context.renderLocator(resolved),
+            value,
+          });
+          return {
+            templateName: 'recipe-sequence',
+            data: { steps },
+            comment: `Fill ${step.selectorRef} with ${step.dataRef || step.value} (${fillVariant} recipe)`,
+          };
+        } catch {
+          // malformed recipe → generic fill below
+        }
+      }
+
       // Use pressSequentially template for contenteditable/rich-text editors (auto-detected by live-scan)
       // or when Gherkin explicitly uses 'editor' element type
       const isEditor = resolved.inputMethod === 'pressSequentially' || step.elementType === 'editor';
@@ -132,6 +154,29 @@ export const formPatterns: StepPattern[] = [
         // A native <select> is detected by its ARIA role, or by an explicit `variant: native`
         // on the selector entry (lets a CSS/#id-located select opt into .selectOption()).
         const isNativeSelect = nativeSelectRoles.includes(resolved.role) || resolved.variant === 'native';
+        // Widget variant resolution (spec §3): per-element `variant:` wins over the app
+        // profile's `widgets.select`. A matching recipe's `select` intent expands to
+        // Playwright lines at compile time; native/unknown variants keep the legacy fork.
+        const variantName = resolved.variant || context.appProfile?.widgetVariants?.['select'];
+        const recipeSteps = variantName && variantName !== 'native'
+          ? context.appProfile?.recipes?.[variantName]?.['select']
+          : undefined;
+
+        if (recipeSteps) {
+          try {
+            const steps = expandRecipe(recipeSteps as unknown[], {
+              triggerCode: context.renderLocator(resolved),
+              value,
+            });
+            return {
+              templateName: 'recipe-sequence',
+              data: { steps },
+              comment: `Select ${step.dataRef || step.value} in ${step.selectorRef} (${variantName} recipe)`,
+            };
+          } catch {
+            // malformed recipe → generic fallback below
+          }
+        }
 
         if (isNativeSelect) {
           templateName = 'select-action';

package/src/patterns/interaction-patterns.ts

@@ -9,6 +9,8 @@ import { escapeRegex, pathToRegexSource } from '../utils/url-path-regex';
 function extractWaitState(text: string): string {
   if (/\bhidden\b/.test(text)) return 'hidden';
   if (/\bdetached\b/.test(text)) return 'detached';
+  if (/\bdisabled\b/.test(text)) return 'disabled';
+  if (/\benabled\b/.test(text)) return 'enabled';
   if (/\bvisible\b/.test(text)) return 'visible';
   return 'visible';
 }
@@ -32,7 +34,42 @@ function elementKeywordToRole(text: string): string | null {
  */
 export const interactionPatterns: StepPattern[] = [
   // === Browser Alert (system dialog) patterns ===
-  // These must appear BEFORE the click that triggers the alert in Gherkin:
+  // Compound form (preferred since v3.3): trigger + dialog response in ONE step, in the
+  // user's natural order — the compiler emits the listener FIRST (Playwright requires
+  // registration before the triggering action; a late handler lets the dialog
+  // auto-dismiss with no error):
+  //   When User click [Đăng xuất] button and accept [OK] alert
+  //   When User click [Xoá] button and dismiss [Cancel] alert
+  {
+    name: 'click-with-alert',
+    matcher: (step: ParsedStep) =>
+      /\b(click|clicks)\b/.test(step.text) &&
+      /\band\s+(accept|accepts|dismiss|dismisses)\s+\[[^\]]*\]\s+alert\b/i.test(step.text) &&
+      (step.text.match(/\[[^\]]+\]/g) || []).length >= 2,
+    resolver: (step, context) => {
+      // brackets[0] = trigger element, brackets[1] = alert button (verb decides the action)
+      const brackets = step.text.match(/\[([^\]]+)\]/g) || [];
+      const triggerName = brackets[0].replace(/[\[\]]/g, '');
+      const dialogAction = /\band\s+dismiss(?:es)?\b/i.test(step.text) ? 'dismiss' : 'accept';
+
+      // Element type = the word right after the trigger bracket (button/link/…)
+      const typeMatch = step.text.match(/\]\s+([\w-]+)\s+and\b/i);
+      const triggerType = typeMatch ? typeMatch[1].toLowerCase() : 'button';
+
+      const resolved = context.selectorResolver.resolveSelector(
+        triggerName, context.featureName, triggerType, step.nth
+      );
+
+      return {
+        templateName: 'click-with-alert-action',
+        data: { ...resolved, dialogAction },
+        comment: `Click ${triggerName} and ${dialogAction} the browser dialog`,
+      };
+    },
+    priority: 21,
+  },
+  // Two-step form (still valid): the alert step must appear BEFORE the click that
+  // triggers the alert in Gherkin — SG-W007 warns when it is written after:
   //   When User click [OK] alert       ← registers page.once('dialog', ...)
   //   And User click [Delete] button   ← triggers the alert
   {
@@ -98,12 +135,14 @@ export const interactionPatterns: StepPattern[] = [
     resolver: (step, context) => {
       let selectorValue = '';
       let nth: number | undefined;
+      let exact = false;
       try {
         const resolved = context.selectorResolver.resolveSelector(
           step.selectorRef!, context.featureName, step.elementType, step.nth
         );
         selectorValue = resolved.value || '';
         nth = resolved.nth;
+        exact = resolved.exact === true;
       } catch (error) {
         selectorValue = '';
         nth = undefined;
@@ -122,7 +161,7 @@ export const interactionPatterns: StepPattern[] = [
 
       return {
         templateName: 'unknown-element-action',
-        data: { selectorValue, dataValue, action: actionMethod, nth },
+        data: { selectorValue, dataValue, action: actionMethod, nth, exact },
         comment: `${actionMethod.charAt(0).toUpperCase() + actionMethod.slice(1)} ${step.selectorRef} with ${step.dataRef}`,
       };
     },
@@ -336,6 +375,21 @@ export const interactionPatterns: StepPattern[] = [
     },
     priority: 9,
   },
+  {
+    // FR3 (issue #468): `User wait for [T] table to refresh` — the dedicated wait for
+    // filter/search/pagination round-trips. Signal = the app profile's loading indicator
+    // (qa/app.yaml feedback.loading.indicator, default [aria-busy="true"]): soft-wait for
+    // it to appear (the spinner may already be gone), hard-wait for it to disappear.
+    name: 'wait-table-refresh',
+    matcher: (step: ParsedStep) =>
+      /\bwait(?:s)?\s+for\b/i.test(step.text) && /\btable\s+to\s+refresh\b/i.test(step.text),
+    resolver: (step, context) => ({
+      templateName: 'wait-table-refresh',
+      data: { indicator: context.appProfile?.loadingIndicator ?? '[aria-busy="true"]' },
+      comment: `Wait for ${step.selectorRef || 'table'} to refresh`,
+    }),
+    priority: 12,
+  },
   {
     name: 'wait-for-element-with-text',
     matcher: (step: ParsedStep) =>

package/src/patterns/navigation-patterns.ts

@@ -35,19 +35,35 @@ export const navigationPatterns: StepPattern[] = [
       const finalPath = resolvePathVariables(path, context.scenarioSteps || []);
       const isAbsoluteUrl = /^https?:\/\//.test(finalPath);
 
-      // Then User is on [X] page — assert URL, don't navigate.
+      // `[X] page with {{v}}` — the query/fragment value parsed into dataRef (issue #464).
+      // Raw concat, no "smart" URL merging: the primary use case is injecting malformed
+      // query input, so the compiler must not sanitize what the test wants broken.
+      // Runtime mode resolves to a __SUNGEN_TD__ marker → `path + testData.get(...)`.
+      let query = '';
+      if (step.dataRef) {
+        try {
+          query = context.dataResolver.resolveData(step.dataRef, context.featureName);
+        } catch {
+          query = `\${${step.dataRef}}`;
+        }
+      }
+      const withSuffix = step.dataRef ? ` with ${step.dataRef}` : '';
+
+      // Then User is on [X] page — assert URL, don't navigate. The query is asserted
+      // separately (toHaveURL's regex stays compile-time escapable; the query value is
+      // runtime data with regex-special characters).
       if (isThen) {
         return {
           templateName: 'route-assertion',
-          data: { path: finalPath },
-          comment: step.selectorRef ? `Assert on ${step.selectorRef} page` : `Assert page route`,
+          data: { path: finalPath, query },
+          comment: step.selectorRef ? `Assert on ${step.selectorRef} page${withSuffix}` : `Assert page route`,
         };
       }
 
       return {
         templateName: 'navigation',
-        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: finalPath },
-        comment: step.selectorRef ? `Open ${step.selectorRef} page` : `Navigate to page`,
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: finalPath + query },
+        comment: step.selectorRef ? `Open ${step.selectorRef} page${withSuffix}` : `Navigate to page`,
       };
     },
     priority: 16,

package/src/patterns/table-patterns.ts

@@ -16,6 +16,7 @@
  */
 
 import { StepPattern, PatternContext } from '@sun-asterisk/sungen';
+import { rowIndexExpr, TABLE_ROW_NTH } from '../utils/row-index';
 
 /** Helper: check if current step is in a Given context */
 function isGivenContext(context: PatternContext): boolean {
@@ -179,6 +180,57 @@ export const tablePatterns: StepPattern[] = [
   },
 
   // "User click [Act] button in [Table] table with {{filter}}" — action in row
+  {
+    // FR2 (issue #468): positional row — `User click [Act] button in [Table] table row {{n}}`.
+    // Selecting by POSITION (not content) compiles remember+act steps onto the same
+    // `getByRole('row').nth(...)` chain, eliminating the read-then-act two-query race
+    // where a re-render between queries hits two different rows. Row numbering follows
+    // qa/app.yaml conventions.table (row_base, header_is_row).
+    name: 'table-action-in-row-nth',
+    matcher: (step) => {
+      return TABLE_ROW_NTH.test(step.text) &&
+             /\b(click|clicks|check|checks|uncheck|unchecks)\b/i.test(step.text) &&
+             !/\bremember\b/i.test(step.text) &&
+             /\bin\b.*\btable\b/i.test(step.text);
+    },
+    resolver: (step, context) => {
+      const brackets = step.text.match(/\[([^\]]+)\]/g) || [];
+      const elementName = brackets[0]?.replace(/[\[\]]/g, '') || '';
+      const tableName = brackets.length >= 2 ? brackets[1].replace(/[\[\]]/g, '') : '';
+      const rowToken = step.text.match(TABLE_ROW_NTH)![1];
+
+      const tableResolved = context.selectorResolver.resolveSelector(
+        tableName, context.featureName, 'table', 0
+      );
+
+      const actionMatch = step.text.match(/\b(click|check|uncheck)\b/i);
+      const action = actionMatch ? actionMatch[1].toLowerCase() : 'click';
+
+      const elementTypeMatch = step.text.match(/\]\s+([\w-]+)\s+in\b/i);
+      const elementType = elementTypeMatch ? elementTypeMatch[1].toLowerCase() : 'button';
+      const elementRole = typeToRole[elementType] || elementType;
+
+      let actionLocator: string;
+      try {
+        const elementResolved = context.selectorResolver.resolveSelector(
+          elementName, context.featureName, elementType, step.nth
+        );
+        actionLocator = context.renderLocator({ ...elementResolved, parentLocator: 'tableRow' });
+      } catch {
+        const escapedName = String(elementName)
+          .replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+          .replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
+        actionLocator = `tableRow.getByRole('${elementRole}', { name: '${escapedName}' })`;
+      }
+
+      return {
+        templateName: 'table-action-in-row-nth',
+        data: { ...tableResolved, elementName, action, actionLocator, rowIndexExpr: rowIndexExpr(rowToken, context) },
+        comment: `${action} ${elementName} in ${tableName} table row ${rowToken}`,
+      };
+    },
+    priority: 18,
+  },
   {
     name: 'table-action-in-row',
     matcher: (step) => {

package/src/utils/row-index.ts

@@ -0,0 +1,33 @@
+import { PatternContext } from '@sun-asterisk/sungen';
+
+/**
+ * Positional-row index expression for `… table row {{n}}` steps (FR2, issue #468).
+ *
+ * QA counts rows from `conventions.table.row_base` (default 1) and the header <tr>
+ * usually carries role=row at getByRole('row') index 0 (`header_is_row: false`), so:
+ *   nth index = n + (header_is_row ? 0 : 1) - row_base
+ *
+ * `rowToken` is the literal number or `{{var}}` from the step text. A runtime marker
+ * becomes `Number(testData.get('var'))` via the runtime-data transform, so the offset
+ * is emitted as ` + k` / ` - k` around it.
+ */
+export function rowIndexExpr(rowToken: string, context: PatternContext): string {
+  const rowBase = context.appProfile?.tableRowBase ?? 1;
+  const offset = (context.appProfile?.tableHeaderIsRow ? 0 : 1) - rowBase;
+
+  const varMatch = rowToken.match(/^\{\{([^}]+)\}\}$/);
+  if (!varMatch) return String(Number(rowToken) + offset);
+
+  let expr: string;
+  try {
+    expr = context.dataResolver.resolveData(varMatch[1].trim(), context.featureName);
+  } catch {
+    expr = `\${${varMatch[1].trim()}}`;
+  }
+  if (/^\d+$/.test(expr)) return String(Number(expr) + offset); // inline-data mode
+  if (offset === 0) return expr;
+  return offset > 0 ? `${expr} + ${offset}` : `${expr} - ${-offset}`;
+}
+
+/** Matches `table row 2` / `table row {{n}}` and captures the row token. */
+export const TABLE_ROW_NTH = /\btable\s+row\s+(\d+|\{\{[^}]+\}\})/i;