@dcoder-x/plugin-shared 0.1.4 → 0.1.6

package/dist/extractors/InteractionGraphExtractor.js

@@ -2,9 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InteractionGraphExtractor = void 0;
 const ComponentContextResolver_1 = require("./ComponentContextResolver");
+const MODAL_STATE_PATTERN = /^(is|show|open|visible)/i;
 /**
  * Extracts interaction graphs from React component ASTs.
- * Maps event handlers -> state mutations -> conditional renders and effects.
+ * Maps event handlers -> state mutations -> conditional renders, navigation, and async effects.
  */
 class InteractionGraphExtractor {
     constructor() {
@@ -16,21 +17,54 @@ class InteractionGraphExtractor {
     extractInteractions(componentPath, componentName) {
         const context = this.contextResolver.extractContext(componentPath, componentName);
         const interactions = [];
-        // Walk all JSX elements looking for event handlers
         componentPath.traverse({
             JSXOpeningElement: (jsxPath) => {
                 const attributes = jsxPath.node.attributes || [];
                 for (const attr of attributes) {
-                    if (attr.type === 'JSXAttribute' &&
-                        attr.name?.name &&
-                        attr.name.name.startsWith('on')) {
-                        const eventName = attr.name.name;
-                        const settersCalledByEvent = this.resolveStateSettersForAttribute(attr, context);
-                        if (settersCalledByEvent.length === 0)
-                            continue;
-                        const interaction = this.extractTriggerAndEffect(jsxPath, componentPath, eventName, context, settersCalledByEvent);
+                    if (attr.type !== 'JSXAttribute' ||
+                        !attr.name?.name?.startsWith('on'))
+                        continue;
+                    const eventName = attr.name.name;
+                    // Path A: handler calls a known state setter → find conditional effect
+                    const settersCalledByEvent = this.resolveStateSettersForAttribute(attr, context);
+                    if (settersCalledByEvent.length > 0) {
+                        const interaction = this.buildInteractionFromSetters(jsxPath, componentPath, eventName, context, settersCalledByEvent);
                         if (interaction) {
                             interactions.push(interaction);
+                            continue;
+                        }
+                    }
+                    // Path B: handler contains router.push / router.replace → navigation effect
+                    const navTarget = this.resolveRouterNavigation(attr, context);
+                    if (navTarget) {
+                        const tagName = jsxPath.node.name?.name || 'unknown';
+                        interactions.push({
+                            trigger: { event: eventName, element: tagName },
+                            effect: {
+                                type: 'asyncEffect',
+                                waitStrategy: 'domSettle',
+                                settleMs: 0,
+                            },
+                        });
+                        continue;
+                    }
+                    // Path C: handler calls a setter with a modal/open-like name → domSettle fallback
+                    if (settersCalledByEvent.length > 0) {
+                        const hasModalSetter = settersCalledByEvent.some((s) => MODAL_STATE_PATTERN.test(s));
+                        if (hasModalSetter) {
+                            const tagName = jsxPath.node.name?.name || 'unknown';
+                            interactions.push({
+                                trigger: {
+                                    event: eventName,
+                                    element: tagName,
+                                    setsState: settersCalledByEvent[0],
+                                },
+                                effect: {
+                                    type: 'conditionalRender',
+                                    waitStrategy: 'domSettle',
+                                    settleMs: 150,
+                                },
+                            });
                         }
                     }
                 }
@@ -38,23 +72,96 @@ class InteractionGraphExtractor {
         });
         return interactions;
     }
-    /**
-     * Extract trigger/effect pair from a JSX element with an event handler.
-     */
-    extractTriggerAndEffect(jsxPath, componentPath, eventName, context, settersCalledByEvent) {
+    buildInteractionFromSetters(jsxPath, componentPath, eventName, context, settersCalledByEvent) {
         const tagName = jsxPath.node.name?.name || 'unknown';
-        const stateVar = settersCalledByEvent[0]; // Take first setter as primary
+        const stateVar = settersCalledByEvent[0];
         const trigger = {
             event: eventName,
             element: tagName,
             setsState: stateVar,
         };
-        // Look for conditional effects that depend on the modified state
+        // Try to find a conditional render driven by this state variable
         const effect = this.findConditionalEffect(jsxPath, componentPath, stateVar);
-        if (!effect) {
+        if (effect) {
+            return { trigger, effect };
+        }
+        // Fallback: if setter name looks modal-like, emit a domSettle effect
+        if (MODAL_STATE_PATTERN.test(stateVar)) {
+            return {
+                trigger,
+                effect: {
+                    type: 'conditionalRender',
+                    waitStrategy: 'domSettle',
+                    settleMs: 150,
+                },
+            };
+        }
+        // Generic async/loading pattern: setter name contains loading, pending, fetching
+        if (/loading|pending|fetching|submitting/i.test(stateVar)) {
+            return {
+                trigger,
+                effect: {
+                    type: 'asyncEffect',
+                    waitStrategy: 'domSettle',
+                    settleMs: 300,
+                },
+            };
+        }
+        return null;
+    }
+    /**
+     * Detect router.push() / router.replace() / navigate() calls inside a handler.
+     * Returns the destination route string if found, otherwise null.
+     */
+    resolveRouterNavigation(attr, context) {
+        if (attr.type !== 'JSXAttribute' || !attr.value || attr.value.type !== 'JSXExpressionContainer') {
             return null;
         }
-        return { trigger, effect };
+        const expression = attr.value.expression;
+        if (!expression)
+            return null;
+        const body = expression.type === 'ArrowFunctionExpression' || expression.type === 'FunctionExpression'
+            ? expression.body
+            : expression.type === 'Identifier'
+                ? this.findHandlerBody(expression.name, context)
+                : null;
+        if (!body)
+            return null;
+        return this.extractRouterCallFromNode(body);
+    }
+    findHandlerBody(handlerName, context) {
+        const handler = context.eventHandlers.find((h) => h.name === handlerName);
+        return handler?._body ?? null;
+    }
+    extractRouterCallFromNode(node) {
+        if (!node || typeof node !== 'object')
+            return null;
+        if (node.type === 'CallExpression') {
+            const callee = node.callee;
+            const isRouterCall = (callee?.type === 'MemberExpression' &&
+                (callee.object?.name === 'router' || callee.object?.name === 'navigate') &&
+                (callee.property?.name === 'push' || callee.property?.name === 'replace')) ||
+                (callee?.type === 'Identifier' && callee.name === 'navigate');
+            if (isRouterCall && node.arguments?.[0]?.type === 'StringLiteral') {
+                return node.arguments[0].value;
+            }
+        }
+        for (const key of Object.keys(node)) {
+            const value = node[key];
+            if (Array.isArray(value)) {
+                for (const child of value) {
+                    const found = this.extractRouterCallFromNode(child);
+                    if (found)
+                        return found;
+                }
+            }
+            else if (value && typeof value === 'object') {
+                const found = this.extractRouterCallFromNode(value);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
     }
     resolveStateSettersForAttribute(attr, context) {
         if (attr.type !== 'JSXAttribute' || !attr.value || attr.value.type !== 'JSXExpressionContainer') {
@@ -99,32 +206,23 @@ class InteractionGraphExtractor {
         for (const key of Object.keys(node)) {
             const value = node[key];
             if (Array.isArray(value)) {
-                for (const child of value) {
+                for (const child of value)
                     this.collectSettersFromNode(child, setterMap, result);
-                }
             }
             else if (value && typeof value === 'object') {
                 this.collectSettersFromNode(value, setterMap, result);
             }
         }
     }
-    /**
-     * Find conditional renders/effects that depend on a state variable.
-     * Looks for logical expressions and ternaries using the state var.
-     */
     findConditionalEffect(jsxPath, componentPath, stateVar) {
-        const directEffect = this.findConditionalEffectInAncestors(jsxPath, stateVar);
-        if (directEffect) {
-            return directEffect;
-        }
-        return this.findConditionalEffectInComponent(componentPath, stateVar);
+        return (this.findConditionalEffectInAncestors(jsxPath, stateVar) ||
+            this.findConditionalEffectInComponent(componentPath, stateVar));
     }
     findConditionalEffectInAncestors(jsxPath, stateVar) {
         let effectFound = null;
         let current = jsxPath.parentPath;
         while (current && !effectFound) {
             const node = current.node;
-            // Check for logical AND/OR: condition && <Component />
             if (node.type === 'LogicalExpression') {
                 if (this.nodeReferencesState(node.left, stateVar)) {
                     const rendersWhenTrue = this.extractComponentNameFromNode(node.right);
@@ -138,7 +236,6 @@ class InteractionGraphExtractor {
                     }
                 }
             }
-            // Check for ternary: condition ? <Component /> : null
             if (node.type === 'ConditionalExpression') {
                 if (this.nodeReferencesState(node.test, stateVar)) {
                     const rendersWhenTrue = this.extractComponentNameFromNode(node.consequent);
@@ -149,7 +246,9 @@ class InteractionGraphExtractor {
                             rendersWhenTrue: rendersWhenTrue ?? undefined,
                             rendersWhenFalse: rendersWhenFalse ?? undefined,
                             waitStrategy: 'elementAppears',
-                            selector: rendersWhenTrue ? `[data-clippy-component='${rendersWhenTrue}']` : undefined,
+                            selector: rendersWhenTrue
+                                ? `[data-clippy-component='${rendersWhenTrue}']`
+                                : undefined,
                         };
                     }
                 }
@@ -190,7 +289,9 @@ class InteractionGraphExtractor {
                             rendersWhenTrue: rendersWhenTrue ?? undefined,
                             rendersWhenFalse: rendersWhenFalse ?? undefined,
                             waitStrategy: 'elementAppears',
-                            selector: rendersWhenTrue ? `[data-clippy-component='${rendersWhenTrue}']` : undefined,
+                            selector: rendersWhenTrue
+                                ? `[data-clippy-component='${rendersWhenTrue}']`
+                                : undefined,
                         };
                     }
                 }
@@ -198,47 +299,34 @@ class InteractionGraphExtractor {
         });
         return effectFound;
     }
-    /**
-     * Check if a node references a specific state variable by name.
-     */
     nodeReferencesState(node, stateVar) {
-        if (node.type === 'Identifier' && node.name === stateVar) {
+        if (node.type === 'Identifier' && node.name === stateVar)
             return true;
-        }
-        if (node.type === 'MemberExpression') {
+        if (node.type === 'MemberExpression')
             return this.nodeReferencesState(node.object, stateVar);
-        }
-        if (node.type === 'CallExpression') {
+        if (node.type === 'CallExpression')
             return this.nodeReferencesState(node.callee, stateVar);
-        }
         if (node.type === 'BinaryExpression' || node.type === 'LogicalExpression') {
-            return this.nodeReferencesState(node.left, stateVar) || this.nodeReferencesState(node.right, stateVar);
+            return (this.nodeReferencesState(node.left, stateVar) ||
+                this.nodeReferencesState(node.right, stateVar));
         }
-        if (node.type === 'UnaryExpression') {
+        if (node.type === 'UnaryExpression')
             return this.nodeReferencesState(node.argument, stateVar);
-        }
         return false;
     }
-    /**
-     * Extract component name from a JSX element or identifier.
-     */
     extractComponentNameFromNode(node) {
         if (!node)
             return null;
         if (node.type === 'JSXElement' && node.openingElement?.name?.name) {
             const name = node.openingElement.name.name;
-            // Only return if it looks like a component (PascalCase)
             return /^[A-Z]/.test(name) ? name : null;
         }
-        if (node.type === 'JSXFragment') {
+        if (node.type === 'JSXFragment')
             return null;
-        }
-        if (node.type === 'Identifier' && /^[A-Z]/.test(node.name)) {
+        if (node.type === 'Identifier' && /^[A-Z]/.test(node.name))
             return node.name;
-        }
-        if (node.type === 'MemberExpression' && node.property?.name) {
+        if (node.type === 'MemberExpression' && node.property?.name)
             return node.property.name;
-        }
         return null;
     }
 }

package/dist/extractors/SelectorGenerator.d.ts

@@ -1,10 +1,6 @@
 import type { DiscoveredElement, ElementWithSelectors } from '../types';
+import type { InjectedEntry } from '../injection/ClippyIdInjector';
 export declare class SelectorGenerator {
-    generate(elements: DiscoveredElement[], injectedMap?: Record<string, Array<{
-        clippyId: string;
-        component: string;
-        tag: string;
-        line: number;
-    }>>): ElementWithSelectors[];
+    generate(elements: DiscoveredElement[], injectedMap?: Record<string, InjectedEntry[]>): ElementWithSelectors[];
     private generateForElement;
 }

package/dist/extractors/SelectorGenerator.js

@@ -16,14 +16,19 @@ class SelectorGenerator {
             if (injectedMap && el.filePath) {
                 const entries = injectedMap[el.filePath];
                 if (entries && entries.length) {
-                    // Prefer exact line match when available
-                    let match = null;
-                    if (el.loc && el.loc.line) {
-                        match = entries.find((e) => e.line === el.loc.line);
+                    const elLine = el.loc?.line;
+                    const elLabel = el.label;
+                    // 1. Exact line match — most reliable
+                    let match = elLine ? entries.find((e) => e.line === elLine) : null;
+                    // 2. Label + tag match — handles multiple same-tag elements in one file
+                    // (e.g. two <button> tags where line lookup fails due to AST offset)
+                    if (!match && elLabel) {
+                        match = entries.find((e) => e.tag === el.tag && e.label === elLabel) ?? null;
                     }
-                    // Fallback to tag/component match
+                    // 3. Tag-only fallback — last resort, may pick the wrong element when
+                    // multiple same-tag elements exist but is better than no clippy_id at all
                     if (!match) {
-                        match = entries.find((e) => e.tag === el.tag);
+                        match = entries.find((e) => e.tag === el.tag) ?? null;
                     }
                     if (match) {
                         candidates.push({

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './injection/ClippyIdInjector';
+export * from './injection/IdStrategy';
 export * from './buildId';
 export * from './upload/Adapter';
 export * from './upload/BackendAdapter';

package/dist/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./injection/ClippyIdInjector"), exports);
+__exportStar(require("./injection/IdStrategy"), exports);
 __exportStar(require("./buildId"), exports);
 __exportStar(require("./upload/Adapter"), exports);
 __exportStar(require("./upload/BackendAdapter"), exports);

package/dist/injection/ClippyIdInjector.d.ts

@@ -3,10 +3,15 @@ export interface InjectedEntry {
     component: string;
     tag: string;
     line: number;
+    label?: string;
 }
 export interface InjectResult {
     source: string;
     injectedCount: number;
     injected: InjectedEntry[];
 }
-export declare function injectClippyIds(source: string, filePath: string): InjectResult;
+/**
+ * Inject data-clippy-id and data-clippy-component attributes into intrinsic HTML elements.
+ * IDs incorporate the route-derived component name and visible label text for readability.
+ */
+export declare function injectClippyIds(source: string, filePath: string, routePath?: string): InjectResult;

package/dist/injection/ClippyIdInjector.js

@@ -8,7 +8,11 @@ const parser_1 = require("@babel/parser");
 const traverse_1 = __importDefault(require("@babel/traverse"));
 const HtmlTagGuards_1 = require("./HtmlTagGuards");
 const IdStrategy_1 = require("./IdStrategy");
-function injectClippyIds(source, filePath) {
+/**
+ * Inject data-clippy-id and data-clippy-component attributes into intrinsic HTML elements.
+ * IDs incorporate the route-derived component name and visible label text for readability.
+ */
+function injectClippyIds(source, filePath, routePath) {
     let ast;
     try {
         ast = (0, parser_1.parse)(source, {
@@ -31,9 +35,22 @@ function injectClippyIds(source, filePath) {
             const attrs = opening.attributes;
             if ((0, HtmlTagGuards_1.hasAttribute)(attrs, 'data-clippy-id'))
                 return;
-            const componentName = findEnclosingComponentName(path) || (0, IdStrategy_1.deriveComponentName)(filePath);
+            // Resolve component name: prefer enclosing name, fall back to route-derived or filename
+            const enclosing = (0, IdStrategy_1.findEnclosingComponentName)(path);
+            let componentName;
+            if (enclosing && !IdStrategy_1.GENERIC_COMPONENT_NAMES.has(enclosing)) {
+                componentName = enclosing;
+            }
+            else if (routePath) {
+                componentName = (0, IdStrategy_1.deriveRouteComponentName)(routePath);
+            }
+            else {
+                componentName = (0, IdStrategy_1.deriveComponentName)(filePath);
+            }
             const line = opening.loc?.start.line ?? 0;
-            const clippyId = (0, IdStrategy_1.deriveClippyId)(componentName, tagName, line);
+            // Extract visible label text from element children for ID enrichment
+            const labelText = extractLabelFromOpeningElement(path, attrs, tagName);
+            const clippyId = (0, IdStrategy_1.deriveClippyId)(componentName, tagName, line, routePath, labelText ?? undefined);
             const componentAttr = (0, HtmlTagGuards_1.hasAttribute)(attrs, 'data-clippy-component')
                 ? ''
                 : ` data-clippy-component="${componentName}"`;
@@ -42,7 +59,13 @@ function injectClippyIds(source, filePath) {
             if (insertIndex === null)
                 return;
             edits.push({ index: insertIndex, text: insertText });
-            injected.push({ clippyId, component: componentName, tag: tagName, line });
+            injected.push({
+                clippyId,
+                component: componentName,
+                tag: tagName,
+                line,
+                label: labelText ?? undefined,
+            });
         },
     });
     if (edits.length === 0) {
@@ -51,26 +74,84 @@ function injectClippyIds(source, filePath) {
     const transformed = applyEdits(source, edits);
     return { source: transformed, injectedCount: edits.length, injected };
 }
-function findEnclosingComponentName(path) {
-    let current = path;
-    while (current) {
-        if (current.isFunctionDeclaration() && current.node.id?.name) {
-            return current.node.id.name;
+/**
+ * Extract a usable label from the element's attributes and children.
+ * Priority: aria-label > title > visible text content > placeholder > name.
+ * For form elements: only aria-label or the last short text (submit button),
+ * never the full concatenation of all child field labels.
+ */
+function extractLabelFromOpeningElement(path, attrs, tagName) {
+    // Check attributes first — fastest path
+    for (const attr of attrs) {
+        if (attr.type !== 'JSXAttribute')
+            continue;
+        const name = attr.name?.name;
+        if (name !== 'aria-label' && name !== 'title')
+            continue;
+        if (attr.value?.type === 'StringLiteral')
+            return attr.value.value;
+        if (attr.value?.type === 'JSXExpressionContainer' &&
+            attr.value.expression?.type === 'StringLiteral')
+            return attr.value.expression.value;
+    }
+    // Extract visible text from children
+    const parent = path.parentPath?.node;
+    if (parent?.children) {
+        const text = extractTextFromChildren(parent.children, 0);
+        if (tagName === 'form') {
+            // Forms: only use the last short text node (submit button label), not the full
+            // concatenation of every field label inside the form.
+            const lastShort = [...text].reverse().find((t) => t.length >= 2 && t.length <= 30);
+            return lastShort || null;
         }
-        if (current.isClassDeclaration() && current.node.id?.name) {
-            return current.node.id.name;
+        const joined = text.join(' ').trim();
+        if (joined && joined.length <= 60) {
+            const sanitized = (0, IdStrategy_1.sanitizeLabelForId)(joined);
+            if (sanitized)
+                return joined;
         }
-        if (current.isVariableDeclarator() && current.node.id?.type === 'Identifier') {
-            return current.node.id.name;
+    }
+    // Fallback to placeholder / name for inputs
+    for (const attr of attrs) {
+        if (attr.type !== 'JSXAttribute')
+            continue;
+        const name = attr.name?.name;
+        if (name !== 'placeholder' && name !== 'name')
+            continue;
+        if (attr.value?.type === 'StringLiteral')
+            return attr.value.value;
+    }
+    return null;
+}
+function extractTextFromChildren(children, depth) {
+    if (depth > 3)
+        return [];
+    const texts = [];
+    for (const child of children) {
+        if (child.type === 'JSXText') {
+            const t = child.value.trim();
+            if (t)
+                texts.push(t);
+        }
+        else if (child.type === 'JSXExpressionContainer') {
+            if (child.expression?.type === 'StringLiteral') {
+                texts.push(child.expression.value);
+            }
+            else if (child.expression?.type === 'TemplateLiteral' &&
+                child.expression.quasis?.length === 1) {
+                const raw = child.expression.quasis[0].value.raw.trim();
+                if (raw)
+                    texts.push(raw);
+            }
         }
-        if ((current.isArrowFunctionExpression() || current.isFunctionExpression()) &&
-            current.parentPath?.isVariableDeclarator() &&
-            current.parentPath.node.id?.type === 'Identifier') {
-            return current.parentPath.node.id.name;
+        else if (child.type === 'JSXElement') {
+            const childTag = child.openingElement?.name?.name || '';
+            if (!/^(Icon|Svg|Loader|Spinner|Arrow|Check|Plus|Minus|Close|X)[A-Z]?/i.test(childTag)) {
+                texts.push(...extractTextFromChildren(child.children || [], depth + 1));
+            }
         }
-        current = current.parentPath;
     }
-    return null;
+    return texts.filter(Boolean);
 }
 function findAttributeInsertIndex(source, range) {
     if (!range)

package/dist/injection/IdStrategy.d.ts

@@ -1,2 +1,36 @@
+import type { NodePath } from '@babel/traverse';
 export declare function deriveComponentName(filePath: string, fallback?: string): string;
-export declare function deriveClippyId(componentName: string, tagName: string, lineNumber: number): string;
+/**
+ * Generic Next.js component names that should be replaced by a route-derived name.
+ */
+export declare const GENERIC_COMPONENT_NAMES: Set<string>;
+/**
+ * Infer the route path from an absolute file path.
+ * Handles both App Router (app/…/page.tsx) and Pages Router (pages/….tsx).
+ * Returns null if the file is not a route file.
+ */
+export declare function inferRouteFromFilePath(filePath: string): string | null;
+/**
+ * Convert a route path to a PascalCase component name.
+ * /admin/transactions      → AdminTransactions
+ * /dashboard/forms/[id]   → DashboardForms
+ * /auth/forgot-password   → AuthForgotPassword
+ */
+export declare function deriveRouteComponentName(routePath: string): string;
+/**
+ * Compute a short route hash for use in stable IDs.
+ * Takes a route path (e.g., "/admin/transactions") and produces a 4-char hash.
+ */
+export declare function hashRoutePath(routePath: string): string;
+/**
+ * Sanitize a label string for embedding in a CSS/HTML attribute ID.
+ * TitleCase, max 2 words, alphanumeric only, minimum 2 chars.
+ * Returns null if no usable text can be extracted.
+ */
+export declare function sanitizeLabelForId(label: string): string | null;
+export declare function deriveClippyId(componentName: string, tagName: string, lineNumber: number, routePath?: string, labelText?: string): string;
+/**
+ * Walk the AST upward to find the enclosing React component name.
+ * Exported here so both the injector and the extractor use the same logic.
+ */
+export declare function findEnclosingComponentName(path: NodePath<any>): string | null;