liteagents 2.5.2 → 2.6.0

package/packages/ampcode/commands/live-canvas/templates/feedback-react/selector-utils.ts

@@ -0,0 +1,423 @@
+/**
+ * Design Lab Interactive Feedback System - Element Selector Utilities
+ *
+ * Generates reliable CSS selectors and human-readable paths for clicked elements.
+ * Uses multiple fallback strategies to ensure Claude can locate elements in code.
+ */
+
+import type { ElementIdentifier, VariantId, Coordinates } from './types';
+import { OVERLAY_CLASS_PREFIX } from './types';
+
+/**
+ * Regex pattern to detect CSS-in-JS generated class names.
+ * Matches patterns like: css-1a2b3c, sc-abc123, emotion-xyz, etc.
+ */
+const CSS_IN_JS_PATTERN = /^(css|sc|emotion|styled|chakra|mui|ant)-[a-z0-9]+$/i;
+
+/**
+ * Regex pattern to detect hash-like suffixes in class names.
+ * Matches: component_abc123, button__hash, etc.
+ */
+const HASH_SUFFIX_PATTERN = /_[a-z0-9]{5,}$/i;
+
+/**
+ * Check if a class name appears to be generated by CSS-in-JS.
+ */
+function isCssInJsClass(className: string): boolean {
+  return (
+    CSS_IN_JS_PATTERN.test(className) ||
+    HASH_SUFFIX_PATTERN.test(className) ||
+    // Tailwind-like utility classes are fine, but random hashes aren't
+    /^[a-z]{1,3}[0-9]{4,}$/i.test(className)
+  );
+}
+
+/**
+ * Filter class names to remove CSS-in-JS generated ones.
+ * Returns only meaningful, human-authored class names.
+ */
+function filterClasses(classNames: string): string {
+  if (!classNames) return '';
+
+  return classNames
+    .split(/\s+/)
+    .filter((cls) => cls && !isCssInJsClass(cls))
+    .join(' ');
+}
+
+/**
+ * Get relevant attributes from an element.
+ * Focuses on data-*, aria-*, and id attributes.
+ */
+function getRelevantAttributes(element: HTMLElement): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const relevantPrefixes = ['data-', 'aria-'];
+
+  for (const attr of Array.from(element.attributes)) {
+    if (
+      relevantPrefixes.some((prefix) => attr.name.startsWith(prefix)) ||
+      attr.name === 'id' ||
+      attr.name === 'role' ||
+      attr.name === 'type' ||
+      attr.name === 'name'
+    ) {
+      attrs[attr.name] = attr.value;
+    }
+  }
+
+  return attrs;
+}
+
+/**
+ * Generate a CSS selector for an element, prioritizing reliable identifiers.
+ *
+ * Priority order:
+ * 1. data-testid or data-cy (most reliable for code lookup)
+ * 2. Unique ID
+ * 3. Semantic + accessible name (aria-label, role)
+ * 4. Meaningful class path
+ * 5. Tag + text content hint
+ * 6. Structural path (fallback)
+ */
+export function generateSelector(
+  element: HTMLElement,
+  variantRoot: HTMLElement
+): string {
+  // Priority 1: data-testid or data-cy
+  const testId =
+    element.getAttribute('data-testid') || element.getAttribute('data-cy');
+  if (testId) {
+    return `[data-testid="${testId}"]`;
+  }
+
+  // Priority 2: Unique ID (not auto-generated)
+  const id = element.id;
+  if (id && !isCssInJsClass(id) && !id.startsWith(':')) {
+    return `#${id}`;
+  }
+
+  // Priority 3: Semantic + aria-label
+  const ariaLabel = element.getAttribute('aria-label');
+  const role = element.getAttribute('role');
+  if (ariaLabel) {
+    const tag = element.tagName.toLowerCase();
+    return `${tag}[aria-label="${ariaLabel}"]`;
+  }
+  if (role && !['generic', 'presentation', 'none'].includes(role)) {
+    const tag = element.tagName.toLowerCase();
+    // Add context to make more unique
+    const name = element.getAttribute('name');
+    if (name) {
+      return `${tag}[role="${role}"][name="${name}"]`;
+    }
+    return `${tag}[role="${role}"]`;
+  }
+
+  // Priority 4: Meaningful class path
+  const meaningfulClasses = filterClasses(element.className);
+  if (meaningfulClasses) {
+    const classSelector = meaningfulClasses
+      .split(/\s+/)
+      .slice(0, 2) // Use first 2 meaningful classes
+      .map((c) => `.${c}`)
+      .join('');
+
+    // Check if this is unique enough within the variant
+    const matches = variantRoot.querySelectorAll(classSelector);
+    if (matches.length === 1) {
+      return classSelector;
+    }
+
+    // Add parent context
+    const parent = element.parentElement;
+    if (parent && parent !== variantRoot) {
+      const parentClasses = filterClasses(parent.className);
+      if (parentClasses) {
+        const parentSelector = parentClasses
+          .split(/\s+/)
+          .slice(0, 1)
+          .map((c) => `.${c}`)
+          .join('');
+        return `${parentSelector} > ${classSelector}`;
+      }
+    }
+
+    return classSelector;
+  }
+
+  // Priority 5: Tag + type for inputs/buttons
+  const tag = element.tagName.toLowerCase();
+  const type = element.getAttribute('type');
+  const name = element.getAttribute('name');
+
+  if (tag === 'input' || tag === 'button' || tag === 'select') {
+    if (name) {
+      return `${tag}[name="${name}"]`;
+    }
+    if (type) {
+      return `${tag}[type="${type}"]`;
+    }
+  }
+
+  // Priority 6: Structural path (fallback)
+  return generateStructuralPath(element, variantRoot);
+}
+
+/**
+ * Generate a structural path selector (nth-child based).
+ * Used as a fallback when no better identifiers exist.
+ */
+function generateStructuralPath(
+  element: HTMLElement,
+  variantRoot: HTMLElement
+): string {
+  const path: string[] = [];
+  let current: HTMLElement | null = element;
+
+  while (current && current !== variantRoot && current.parentElement) {
+    const parent = current.parentElement;
+    const siblings = Array.from(parent.children).filter(
+      (child) => child.tagName === current!.tagName
+    );
+
+    const tag = current.tagName.toLowerCase();
+
+    if (siblings.length === 1) {
+      path.unshift(tag);
+    } else {
+      const index = siblings.indexOf(current) + 1;
+      path.unshift(`${tag}:nth-child(${index})`);
+    }
+
+    current = parent;
+
+    // Limit depth to avoid overly long selectors
+    if (path.length >= 4) break;
+  }
+
+  return path.join(' > ');
+}
+
+/**
+ * Generate a human-readable path for an element.
+ * Example: "Variant B > Form > Submit Button"
+ */
+export function generateReadablePath(
+  element: HTMLElement,
+  variantRoot: HTMLElement,
+  variantId: VariantId
+): string {
+  const parts: string[] = [`Variant ${variantId}`];
+  const path: HTMLElement[] = [];
+
+  let current: HTMLElement | null = element;
+  while (current && current !== variantRoot) {
+    path.unshift(current);
+    current = current.parentElement;
+  }
+
+  // Take up to 3 ancestors for context
+  const relevantPath = path.slice(-3);
+
+  for (const el of relevantPath) {
+    const label = getElementLabel(el);
+    if (label) {
+      parts.push(label);
+    }
+  }
+
+  return parts.join(' > ');
+}
+
+/**
+ * Get a human-readable label for an element.
+ */
+function getElementLabel(element: HTMLElement): string {
+  const tag = element.tagName.toLowerCase();
+
+  // Use aria-label if available
+  const ariaLabel = element.getAttribute('aria-label');
+  if (ariaLabel) {
+    return ariaLabel;
+  }
+
+  // Use text content for buttons and links
+  if (tag === 'button' || tag === 'a') {
+    const text = element.textContent?.trim().slice(0, 30);
+    if (text) {
+      return `${capitalizeTag(tag)}: "${text}"`;
+    }
+  }
+
+  // Use name or placeholder for inputs
+  if (tag === 'input' || tag === 'select' || tag === 'textarea') {
+    const name =
+      element.getAttribute('name') ||
+      element.getAttribute('placeholder') ||
+      element.getAttribute('aria-label');
+    if (name) {
+      return `${capitalizeTag(tag)}: ${name}`;
+    }
+  }
+
+  // Use heading level
+  if (/^h[1-6]$/.test(tag)) {
+    const text = element.textContent?.trim().slice(0, 30);
+    if (text) {
+      return `Heading: "${text}"`;
+    }
+  }
+
+  // Use meaningful classes
+  const classes = filterClasses(element.className);
+  if (classes) {
+    const primary = classes.split(/\s+/)[0];
+    return formatClassName(primary);
+  }
+
+  // Fallback to tag name
+  return capitalizeTag(tag);
+}
+
+/**
+ * Capitalize a tag name for display.
+ */
+function capitalizeTag(tag: string): string {
+  const tagLabels: Record<string, string> = {
+    div: 'Container',
+    section: 'Section',
+    article: 'Article',
+    nav: 'Navigation',
+    header: 'Header',
+    footer: 'Footer',
+    main: 'Main',
+    aside: 'Sidebar',
+    form: 'Form',
+    ul: 'List',
+    ol: 'Numbered List',
+    li: 'List Item',
+    button: 'Button',
+    a: 'Link',
+    input: 'Input',
+    select: 'Dropdown',
+    textarea: 'Text Area',
+    img: 'Image',
+    span: 'Text',
+    p: 'Paragraph',
+    table: 'Table',
+    tr: 'Row',
+    td: 'Cell',
+    th: 'Header Cell',
+  };
+
+  return tagLabels[tag] || tag.charAt(0).toUpperCase() + tag.slice(1);
+}
+
+/**
+ * Format a class name for display.
+ * Converts kebab-case or camelCase to readable text.
+ */
+function formatClassName(className: string): string {
+  return className
+    .replace(/[-_]/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Get truncated text content from an element.
+ */
+export function getTextContent(element: HTMLElement, maxLength = 50): string {
+  const text = element.textContent?.trim() || '';
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return text.slice(0, maxLength - 3) + '...';
+}
+
+/**
+ * Calculate coordinates as percentages within the variant container.
+ */
+export function calculateCoordinates(
+  element: HTMLElement,
+  variantRoot: HTMLElement,
+  clickX: number,
+  clickY: number
+): Coordinates {
+  const rootRect = variantRoot.getBoundingClientRect();
+
+  const x = ((clickX - rootRect.left) / rootRect.width) * 100;
+  const y = ((clickY - rootRect.top) / rootRect.height) * 100;
+
+  return {
+    x: Math.round(x * 10) / 10,
+    y: Math.round(y * 10) / 10,
+  };
+}
+
+/**
+ * Identify an element completely, returning all identification data.
+ */
+export function identifyElement(
+  element: HTMLElement,
+  variantRoot: HTMLElement,
+  variantId: VariantId,
+  clickX: number,
+  clickY: number
+): { element: ElementIdentifier; coordinates: Coordinates } {
+  return {
+    element: {
+      selector: generateSelector(element, variantRoot),
+      readablePath: generateReadablePath(element, variantRoot, variantId),
+      tagName: element.tagName.toLowerCase(),
+      textContent: getTextContent(element),
+      className: filterClasses(element.className),
+      attributes: getRelevantAttributes(element),
+    },
+    coordinates: calculateCoordinates(element, variantRoot, clickX, clickY),
+  };
+}
+
+/**
+ * Check if an element is part of the feedback overlay itself.
+ * Used to prevent selecting overlay elements.
+ */
+export function isOverlayElement(element: HTMLElement): boolean {
+  let current: HTMLElement | null = element;
+
+  while (current) {
+    if (
+      current.className &&
+      typeof current.className === 'string' &&
+      current.className.includes(OVERLAY_CLASS_PREFIX)
+    ) {
+      return true;
+    }
+    current = current.parentElement;
+  }
+
+  return false;
+}
+
+/**
+ * Find the variant container that an element belongs to.
+ * Looks for elements with data-variant attribute.
+ */
+export function findVariantContainer(
+  element: HTMLElement
+): { root: HTMLElement; variantId: VariantId } | null {
+  let current: HTMLElement | null = element;
+
+  while (current) {
+    const variantId = current.getAttribute('data-variant');
+    if (variantId && /^[A-F]$/.test(variantId)) {
+      return {
+        root: current,
+        variantId: variantId as VariantId,
+      };
+    }
+    current = current.parentElement;
+  }
+
+  return null;
+}

package/packages/ampcode/commands/live-canvas/templates/feedback-react/types.ts

@@ -0,0 +1,118 @@
+/**
+ * Design Lab Interactive Feedback System - Type Definitions
+ *
+ * These types define the structure for capturing, storing, and
+ * formatting user feedback on design variants.
+ */
+
+/** Supported variant identifiers */
+export type VariantId = 'A' | 'B' | 'C' | 'D' | 'E' | 'F';
+
+/**
+ * Element identification with multiple fallback strategies.
+ * Claude uses these identifiers to locate elements in code.
+ */
+export interface ElementIdentifier {
+  /** Primary: CSS selector (data-testid preferred) */
+  selector: string;
+  /** Secondary: Human-readable path for context */
+  readablePath: string;
+  /** HTML tag name */
+  tagName: string;
+  /** First 50 chars of text content (for disambiguation) */
+  textContent: string;
+  /** Original class names (CSS-in-JS hashes filtered out) */
+  className: string;
+  /** Relevant attributes (data-*, aria-*, id) */
+  attributes: Record<string, string>;
+}
+
+/**
+ * Position coordinates as percentages within the variant container.
+ * Used as visual backup when selectors fail.
+ */
+export interface Coordinates {
+  /** Percentage from left edge of variant container */
+  x: number;
+  /** Percentage from top edge of variant container */
+  y: number;
+}
+
+/**
+ * A single feedback comment attached to an element.
+ */
+export interface Comment {
+  /** Unique identifier for this comment */
+  id: string;
+  /** Which variant this comment belongs to */
+  variant: VariantId;
+  /** Element identification data */
+  element: ElementIdentifier;
+  /** Click position within the variant */
+  coordinates: Coordinates;
+  /** User's feedback text */
+  text: string;
+  /** Unix timestamp when created */
+  timestamp: number;
+}
+
+/**
+ * Complete feedback payload ready for clipboard/download.
+ */
+export interface FeedbackPayload {
+  /** Schema version for future compatibility */
+  version: '1.0';
+  /** Target component or page name */
+  target: string;
+  /** ISO timestamp of submission */
+  timestamp: string;
+  /** All comments grouped by creation order */
+  comments: Comment[];
+  /** User's overall direction/synthesis guidance */
+  overall: string;
+}
+
+/**
+ * FeedbackOverlay component props.
+ */
+export interface FeedbackOverlayProps {
+  /** Name of the component/page being designed */
+  targetName: string;
+  /** Optional: variant IDs to display (defaults to A-E) */
+  variants?: VariantId[];
+  /** Optional: callback when feedback is submitted */
+  onSubmit?: (payload: FeedbackPayload) => void;
+}
+
+/**
+ * Internal state for the feedback overlay.
+ */
+export interface FeedbackState {
+  /** Whether feedback mode is active */
+  isActive: boolean;
+  /** Currently selected element (if any) */
+  selectedElement: HTMLElement | null;
+  /** Position for the comment input panel */
+  panelPosition: { x: number; y: number } | null;
+  /** All comments created in this session */
+  comments: Comment[];
+  /** Text in the current comment input */
+  currentCommentText: string;
+  /** Overall direction text */
+  overallDirection: string;
+  /** Whether the submit modal is showing */
+  showSubmitModal: boolean;
+  /** The formatted output (for modal preview) */
+  formattedOutput: string;
+}
+
+/**
+ * Storage key for persisting comments in localStorage.
+ */
+export const STORAGE_KEY = 'design-lab-feedback';
+
+/**
+ * CSS class prefix for feedback overlay elements.
+ * Used to identify and exclude overlay elements from selection.
+ */
+export const OVERLAY_CLASS_PREFIX = 'dl-feedback';