hale-commenting-system 3.5.2 → 3.6.0

package/src/app/commenting-system/contexts/CommentContext.tsx

@@ -1,16 +1,18 @@
 import * as React from 'react';
-import { Comment, Thread } from '../types';
+import { Comment, Thread, ComponentMetadata } from '../types';
 import { getStoredUser, githubAdapter, isGitHubConfigured } from '../services/githubAdapter';
 
 interface CommentContextType {
   threads: Thread[];
   commentsEnabled: boolean;
   setCommentsEnabled: (enabled: boolean) => void;
+  showPinsEnabled: boolean;
+  setShowPinsEnabled: (enabled: boolean) => void;
   drawerPinnedOpen: boolean;
   setDrawerPinnedOpen: (open: boolean) => void;
   floatingWidgetMode: boolean;
   setFloatingWidgetMode: (mode: boolean) => void;
-  addThread: (xPercent: number, yPercent: number, route: string, version?: string) => string;
+  addThread: (cssSelector: string, elementDescription: string, componentMetadata: ComponentMetadata | null, xPercent: number, yPercent: number, route: string, version?: string) => string;
   addReply: (threadId: string, text: string, parentCommentId?: string) => void;
   syncFromGitHub: (route: string, version?: string) => Promise<void>;
   retrySync: () => Promise<void>;
@@ -103,6 +105,7 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
   };
   const STORAGE_KEY = 'hale_comment_threads_v1';
   const COMMENTS_ENABLED_KEY = 'hale_comments_enabled_v1';
+  const SHOW_PINS_ENABLED_KEY = 'hale_show_pins_enabled_v1';
   const DRAWER_PINNED_OPEN_KEY = 'hale_drawer_pinned_open_v1';
   const FLOATING_WIDGET_MODE_KEY = 'hale_floating_widget_mode_v1';
   const HIDDEN_ISSUES_KEY = 'hale_hidden_issue_numbers_v1';
@@ -191,6 +194,14 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
       return false;
     }
   });
+  const [showPinsEnabled, setShowPinsEnabled] = React.useState<boolean>(() => {
+    try {
+      const raw = window.localStorage.getItem(SHOW_PINS_ENABLED_KEY);
+      return raw === 'true';
+    } catch {
+      return false;
+    }
+  });
   const [syncInFlightCount, setSyncInFlightCount] = React.useState(0);
   const isSyncing = syncInFlightCount > 0;
   const syncInFlightByKey = React.useRef<Map<string, Promise<void>>>(new Map());
@@ -236,7 +247,15 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
     }
   }, [floatingWidgetMode]);
 
-  const addThread = (xPercent: number, yPercent: number, route: string, version?: string): string => {
+  React.useEffect(() => {
+    try {
+      window.localStorage.setItem(SHOW_PINS_ENABLED_KEY, String(showPinsEnabled));
+    } catch {
+      // ignore
+    }
+  }, [showPinsEnabled]);
+
+  const addThread = (cssSelector: string, elementDescription: string, componentMetadata: ComponentMetadata | null, xPercent: number, yPercent: number, route: string, version?: string): string => {
     const threadId = `thread-${Date.now()}`;
     const isConfigured = isGitHubConfigured();
 
@@ -244,6 +263,8 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
       threadId,
       route,
       version,
+      cssSelector,
+      elementDescription,
       xPercent: xPercent.toFixed(1),
       yPercent: yPercent.toFixed(1),
       isGitHubConfigured: isConfigured,
@@ -251,6 +272,9 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
 
     const newThread: Thread = {
       id: threadId,
+      cssSelector,
+      elementDescription,
+      componentMetadata: componentMetadata || undefined,
       xPercent,
       yPercent,
       route,
@@ -329,29 +353,44 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
     return threadId;
   };
 
-  const parseCoordsFromIssueBody = (body: string): { xPercent: number; yPercent: number } | null => {
-    const match = body.match(/Coordinates:\s*`?\(([\d.]+)%?,\s*([\d.]+)%?\)`?/i);
-    if (!match) return null;
-    const x = Number(match[1]);
-    const y = Number(match[2]);
-    if (Number.isNaN(x) || Number.isNaN(y)) return null;
-    return { xPercent: x, yPercent: y };
-  };
+  const parseMetadataFromIssueBody = (body: string): {
+    cssSelector?: string;
+    elementDescription?: string;
+    xPercent: number;
+    yPercent: number;
+  } => {
+    let cssSelector: string | undefined;
+    let elementDescription: string | undefined;
+    let xPercent = 0;
+    let yPercent = 0;
+
+    // Parse CSS Selector
+    const selectorMatch = body.match(/CSS Selector:\s*`([^`]+)`/i);
+    if (selectorMatch) {
+      cssSelector = selectorMatch[1];
+    }
+
+    // Parse Target Component
+    const componentMatch = body.match(/Target Component:\s*`([^`]+)`/i);
+    if (componentMatch) {
+      elementDescription = componentMatch[1];
+    }
+
+    // Parse Fallback Position (new format) or Coordinates (old format)
+    const fallbackMatch = body.match(/Fallback Position:\s*`?\(([\d.]+)%?,\s*([\d.]+)%?\)`?/i);
+    const coordMatch = body.match(/Coordinates:\s*`?\(([\d.]+)%?,\s*([\d.]+)%?\)`?/i);
+
+    const match = fallbackMatch || coordMatch;
+    if (match) {
+      const x = Number(match[1]);
+      const y = Number(match[2]);
+      if (!Number.isNaN(x) && !Number.isNaN(y)) {
+        xPercent = x;
+        yPercent = y;
+      }
+    }
 
-  const parseCoordsFromIssueLabels = (issue: any): { xPercent: number; yPercent: number } | null => {
-    const labels = issue?.labels;
-    if (!Array.isArray(labels)) return null;
-    const names = labels
-      .map((l: any) => (typeof l === 'string' ? l : l?.name))
-      .filter((n: any) => typeof n === 'string') as string[];
-    const coord = names.find((n) => n.startsWith('coords:'));
-    if (!coord) return null;
-    const raw = coord.replace('coords:', '');
-    const parts = raw.split(',').map((p) => Number(p.trim()));
-    if (parts.length !== 2) return null;
-    const [x, y] = parts;
-    if (Number.isNaN(x) || Number.isNaN(y)) return null;
-    return { xPercent: x, yPercent: y };
+    return { cssSelector, elementDescription, xPercent, yPercent };
   };
 
   const syncFromGitHub = async (route: string, version?: string) => {
@@ -395,10 +434,7 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
           const issueUrl = issue?.html_url as string | undefined;
           if (!issueNumber) continue;
 
-          const coords =
-            parseCoordsFromIssueBody(issue?.body || '') ||
-            parseCoordsFromIssueLabels(issue) ||
-            { xPercent: 0, yPercent: 0 };
+          const metadata = parseMetadataFromIssueBody(issue?.body || '');
 
           const commentsResult = await githubAdapter.fetchIssueComments(issueNumber);
           const ghComments = commentsResult.success && commentsResult.data ? commentsResult.data : [];
@@ -429,8 +465,10 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
             id: `gh-${issueNumber}`,
             route,
             version,
-            xPercent: coords.xPercent,
-            yPercent: coords.yPercent,
+            cssSelector: metadata.cssSelector,
+            elementDescription: metadata.elementDescription,
+            xPercent: metadata.xPercent,
+            yPercent: metadata.yPercent,
             comments: mappedComments,
             issueNumber,
             issueUrl,
@@ -555,8 +593,10 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
         if (!ensuredIssueNumber) {
           const created = await githubAdapter.createIssue({
             title: `Feedback: ${thread.route}`,
-            body: `Thread created from pin at (${thread.xPercent.toFixed(1)}%, ${thread.yPercent.toFixed(1)}%).`,
+            body: `Thread created from pin${thread.elementDescription ? ` on ${thread.elementDescription}` : ''}.`,
             route: thread.route,
+            cssSelector: thread.cssSelector,
+            elementDescription: thread.elementDescription,
             xPercent: thread.xPercent,
             yPercent: thread.yPercent,
             version: thread.version,
@@ -947,8 +987,10 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
         setThreads((prev) => prev.map((x) => (x.id === t.id ? { ...x, syncStatus: 'syncing', syncError: undefined } : x)));
         const created = await githubAdapter.createIssue({
           title: `Feedback: ${t.route}`,
-          body: `Thread created from pin at (${t.xPercent.toFixed(1)}%, ${t.yPercent.toFixed(1)}%).`,
+          body: `Thread created from pin${t.elementDescription ? ` on ${t.elementDescription}` : ''}.`,
           route: t.route,
+          cssSelector: t.cssSelector,
+          elementDescription: t.elementDescription,
           xPercent: t.xPercent,
           yPercent: t.yPercent,
           version: t.version,
@@ -1012,6 +1054,8 @@ export const CommentProvider: React.FunctionComponent<{ children: React.ReactNod
     threads,
     commentsEnabled,
     setCommentsEnabled,
+    showPinsEnabled,
+    setShowPinsEnabled,
     drawerPinnedOpen,
     setDrawerPinnedOpen,
     floatingWidgetMode,

package/src/app/commenting-system/index.ts

@@ -14,4 +14,7 @@ export { FloatingWidget } from './components/FloatingWidget';
 export { githubAdapter, isGitHubConfigured } from './services/githubAdapter';
 
 // Types
-export type { Comment, Thread, SyncStatus, ThreadStatus } from './types';
+export type { Comment, Thread, SyncStatus, ThreadStatus, ComponentMetadata } from './types';
+
+// Utils
+export { getComponentMetadata, getComponentPath, findNearestComponentElement } from './utils/componentUtils';

package/src/app/commenting-system/services/githubAdapter.ts

@@ -151,6 +151,8 @@ export const githubAdapter = {
     title: string;
     body: string;
     route: string;
+    cssSelector?: string;
+    elementDescription?: string;
     xPercent: number;
     yPercent: number;
     version?: string;
@@ -164,7 +166,9 @@ export const githubAdapter = {
       const metadata = [
         `- Route: \`${params.route}\``,
         params.version ? `- Version: \`${params.version}\`` : null,
-        `- Coordinates: \`(${params.xPercent.toFixed(1)}%, ${params.yPercent.toFixed(1)}%)\``,
+        params.cssSelector ? `- Target Component: \`${params.elementDescription || 'unknown'}\`` : null,
+        params.cssSelector ? `- CSS Selector: \`${params.cssSelector}\`` : null,
+        `- Fallback Position: \`(${params.xPercent.toFixed(1)}%, ${params.yPercent.toFixed(1)}%)\``,
       ]
         .filter(Boolean)
         .join('\n');
@@ -181,8 +185,11 @@ export const githubAdapter = {
         const labels: string[] = [
           'hale-comment',
           `route:${params.route}`,
-          `coords:${Math.round(params.xPercent)},${Math.round(params.yPercent)}`,
         ];
+        if (params.cssSelector && params.elementDescription) {
+          labels.push(`component:${params.elementDescription}`);
+        }
+        labels.push(`coords:${Math.round(params.xPercent)},${Math.round(params.yPercent)}`);
         if (params.version) labels.push(`version:${params.version}`);
         await githubProxyRequest('POST', `/repos/${owner}/${repo}/issues/${data.number}/labels`, { labels });
       } catch {

package/src/app/commenting-system/types/index.ts

@@ -11,10 +11,22 @@ export interface Comment {
 export type SyncStatus = 'synced' | 'local' | 'pending' | 'syncing' | 'error';
 export type ThreadStatus = 'open' | 'closed';
 
+export interface ComponentMetadata {
+  componentName?: string;
+  componentType?: string; // 'function' | 'class' | 'forwardRef' | 'memo' | 'lazy' | 'native' | 'unknown'
+  props?: Record<string, unknown>;
+  displayName?: string;
+  key?: string | number | null;
+  componentPath?: string[]; // Component tree path (e.g., ["App", "Dashboard", "Button"])
+}
+
 export interface Thread {
   id: string;
-  xPercent: number; // Percentage from left (0-100)
-  yPercent: number; // Percentage from top (0-100)
+  cssSelector?: string; // CSS selector for target element
+  elementDescription?: string; // Simplified element name for display (e.g., "button.pf-c-button")
+  componentMetadata?: ComponentMetadata; // React component information (component-based)
+  xPercent: number; // Percentage from left (0-100) - used as fallback when element is deleted
+  yPercent: number; // Percentage from top (0-100) - used as fallback when element is deleted
   route: string;
   version?: string;
   comments: Comment[];

package/src/app/commenting-system/utils/componentUtils.ts

@@ -0,0 +1,242 @@
+/**
+ * Utilities for React component detection and metadata extraction
+ * Similar to Chrome DevTools component inspection
+ */
+
+import { ComponentMetadata } from '../types';
+
+/**
+ * Get React fiber node from a DOM element
+ * Uses React DevTools internal API if available, otherwise traverses up the DOM tree
+ */
+export function getFiberFromElement(element: Element | null): any {
+  if (!element) return null;
+
+  // Try React DevTools internal API first (if DevTools is installed)
+  const key = Object.keys(element).find((k) => k.startsWith('__reactFiber') || k.startsWith('__reactInternalInstance'));
+  if (key) {
+    return (element as any)[key];
+  }
+
+  // Fallback: traverse up the DOM tree to find a React fiber
+  let current: Node | null = element;
+  while (current) {
+    const keys = Object.keys(current);
+    const fiberKey = keys.find((k) => k.startsWith('__reactFiber') || k.startsWith('__reactInternalInstance'));
+    if (fiberKey) {
+      return (current as any)[fiberKey];
+    }
+    current = current.parentNode;
+  }
+
+  return null;
+}
+
+/**
+ * Get component name from a React fiber node
+ */
+export function getComponentName(fiber: any): string | undefined {
+  if (!fiber) return undefined;
+
+  // Try different fiber types
+  const type = fiber.type;
+  if (!type) return undefined;
+
+  // Function component
+  if (typeof type === 'function') {
+    return type.displayName || type.name || 'Anonymous';
+  }
+
+  // Forward ref
+  if (type.$$typeof === Symbol.for('react.forward_ref')) {
+    return type.render?.displayName || type.render?.name || 'ForwardRef';
+  }
+
+  // Memo
+  if (type.$$typeof === Symbol.for('react.memo')) {
+    const innerType = type.type;
+    if (typeof innerType === 'function') {
+      return innerType.displayName || innerType.name || 'Memo';
+    }
+    return 'Memo';
+  }
+
+  // String (native element)
+  if (typeof type === 'string') {
+    return type;
+  }
+
+  return undefined;
+}
+
+/**
+ * Get component type (function, class, etc.)
+ */
+function getComponentType(fiber: any): ComponentMetadata['componentType'] {
+  if (!fiber) return 'unknown';
+
+  const type = fiber.type;
+  if (!type) return 'unknown';
+
+  if (typeof type === 'function') {
+    // Check if it's a class component
+    if (type.prototype && type.prototype.isReactComponent) {
+      return 'class';
+    }
+    return 'function';
+  }
+
+  if (type.$$typeof === Symbol.for('react.forward_ref')) {
+    return 'forwardRef';
+  }
+
+  if (type.$$typeof === Symbol.for('react.memo')) {
+    return 'memo';
+  }
+
+  if (type.$$typeof === Symbol.for('react.lazy')) {
+    return 'lazy';
+  }
+
+  if (typeof type === 'string') {
+    return 'native';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Extract component metadata from a DOM element
+ * Returns React component information if available
+ */
+export function getComponentMetadata(element: Element | null): ComponentMetadata | null {
+  if (!element) return null;
+
+  const fiber = getFiberFromElement(element);
+  if (!fiber) return null;
+
+  const componentName = getComponentName(fiber);
+  const componentType = getComponentType(fiber);
+
+  // Get props (may be null for native elements)
+  const props = fiber.memoizedProps || fiber.pendingProps || undefined;
+
+  // Get key
+  const key = fiber.key !== null && fiber.key !== undefined ? fiber.key : undefined;
+
+  // Get display name
+  const type = fiber.type;
+  const displayName =
+    (typeof type === 'function' && (type.displayName || type.name)) ||
+    (type?.$$typeof === Symbol.for('react.forward_ref') && (type.render?.displayName || type.render?.name)) ||
+    undefined;
+
+  return {
+    componentName,
+    componentType,
+    props: props ? sanitizeProps(props) : undefined,
+    displayName,
+    key,
+  };
+}
+
+/**
+ * Sanitize props for display (remove functions, circular refs, etc.)
+ */
+function sanitizeProps(props: Record<string, unknown>): Record<string, unknown> {
+  const sanitized: Record<string, unknown> = {};
+  const seen = new WeakSet();
+
+  const sanitize = (value: unknown, depth = 0): unknown => {
+    if (depth > 3) return '[Max Depth]'; // Prevent infinite recursion
+    if (value === null || value === undefined) return value;
+    if (typeof value === 'function') return '[Function]';
+    if (typeof value === 'symbol') return '[Symbol]';
+    if (typeof value === 'bigint') return `[BigInt: ${value}]`;
+
+    if (typeof value === 'object') {
+      if (seen.has(value)) return '[Circular]';
+      if (value instanceof Date) return value.toISOString();
+      if (value instanceof RegExp) return value.toString();
+      if (Array.isArray(value)) {
+        seen.add(value);
+        return value.map((item) => sanitize(item, depth + 1));
+      }
+      if (value instanceof Set) return `[Set(${value.size})]`;
+      if (value instanceof Map) return `[Map(${value.size})]`;
+
+      // React elements
+      if ((value as any).$$typeof) {
+        const type = (value as any).type;
+        if (typeof type === 'string') return `<${type} />`;
+        if (typeof type === 'function') return `<${type.displayName || type.name || 'Component'} />`;
+        return '[React Element]';
+      }
+
+      seen.add(value);
+      const obj: Record<string, unknown> = {};
+      for (const [key, val] of Object.entries(value)) {
+        // Skip internal React props
+        if (key.startsWith('__') || key === 'ref' || key === 'key') continue;
+        obj[key] = sanitize(val, depth + 1);
+      }
+      return obj;
+    }
+
+    return value;
+  };
+
+  for (const [key, value] of Object.entries(props)) {
+    // Skip internal React props
+    if (key.startsWith('__') || key === 'ref' || key === 'key') continue;
+    sanitized[key] = sanitize(value);
+  }
+
+  return sanitized;
+}
+
+/**
+ * Get component hierarchy path (component tree path)
+ */
+export function getComponentPath(element: Element | null): string[] {
+  if (!element) return [];
+
+  const path: string[] = [];
+  let current: Element | null = element;
+
+  while (current) {
+    const fiber = getFiberFromElement(current);
+    if (fiber) {
+      const name = getComponentName(fiber);
+      if (name && name !== 'Anonymous') {
+        path.unshift(name);
+      }
+    }
+    current = current.parentElement;
+  }
+
+  return path;
+}
+
+/**
+ * Find the nearest React component element (not a native DOM element)
+ */
+export function findNearestComponentElement(element: Element | null): Element | null {
+  if (!element) return null;
+
+  let current: Element | null = element;
+
+  while (current) {
+    const fiber = getFiberFromElement(current);
+    if (fiber) {
+      const type = fiber.type;
+      // If it's a React component (not a native element), return it
+      if (type && typeof type !== 'string') {
+        return current;
+      }
+    }
+    current = current.parentElement;
+  }
+
+  return element; // Fallback to original element
+}

package/src/app/commenting-system/utils/selectorUtils.ts

@@ -0,0 +1,155 @@
+/**
+ * Utilities for generating and working with CSS selectors for element-based commenting
+ * Now includes React component detection for component-based commenting
+ */
+
+import { getComponentMetadata, getComponentPath, findNearestComponentElement } from './componentUtils';
+import { ComponentMetadata } from '../types';
+
+/**
+ * Generate a stable, unique CSS selector for a DOM element.
+ * Priority order:
+ * 1. data-testid or data-id attributes (most stable)
+ * 2. id attribute
+ * 3. Combination of tag + class + aria attributes
+ * 4. Fall back to nth-child path from body
+ */
+export function generateSelectorForElement(element: Element): string {
+  // Strategy 1: Use data-testid or data-id (testing attributes are most stable)
+  const testId = element.getAttribute('data-testid') || element.getAttribute('data-id');
+  if (testId) {
+    return `[data-testid="${testId}"]`;
+  }
+
+  // Strategy 2: Use id attribute
+  const id = element.getAttribute('id');
+  if (id) {
+    return `#${CSS.escape(id)}`;
+  }
+
+  // Strategy 3: Build selector from tag + class + aria attributes
+  const tagName = element.tagName.toLowerCase();
+  const classList = Array.from(element.classList);
+  const ariaLabel = element.getAttribute('aria-label');
+  const role = element.getAttribute('role');
+  const type = element.getAttribute('type');
+
+  // Build a selector with tag and primary class
+  let selector = tagName;
+
+  // Add first class if available (usually the main component class)
+  if (classList.length > 0) {
+    selector += `.${CSS.escape(classList[0])}`;
+  }
+
+  // Add aria-label for uniqueness if available
+  if (ariaLabel) {
+    selector += `[aria-label="${CSS.escape(ariaLabel)}"]`;
+  } else if (role) {
+    // Fall back to role
+    selector += `[role="${CSS.escape(role)}"]`;
+  } else if (type) {
+    // For inputs, include type
+    selector += `[type="${CSS.escape(type)}"]`;
+  }
+
+  // Test if this selector is unique enough
+  const matches = document.querySelectorAll(selector);
+  if (matches.length === 1 && matches[0] === element) {
+    return selector;
+  }
+
+  // Strategy 4: Fall back to nth-child path (less stable but guaranteed unique)
+  return getNthChildPath(element);
+}
+
+/**
+ * Generate nth-child based path from body to element
+ * This is a fallback when other strategies don't provide uniqueness
+ */
+function getNthChildPath(element: Element): string {
+  const path: string[] = [];
+  let current: Element | null = element;
+
+  while (current && current !== document.body && current.parentElement) {
+    const parent = current.parentElement;
+    const siblings = Array.from(parent.children);
+    const index = siblings.indexOf(current) + 1;
+
+    const tagName = current.tagName.toLowerCase();
+    const classList = Array.from(current.classList);
+
+    if (classList.length > 0) {
+      path.unshift(`${tagName}.${CSS.escape(classList[0])}:nth-child(${index})`);
+    } else {
+      path.unshift(`${tagName}:nth-child(${index})`);
+    }
+
+    current = parent;
+  }
+
+  return path.join(' > ');
+}
+
+/**
+ * Get a simplified, human-readable description of an element for display.
+ * Prioritizes React component name if available, otherwise falls back to DOM element description.
+ * Format: "ComponentName" (React) or "tagName.primaryClass" (DOM)
+ * Examples: "Button", "Card", "button.pf-c-button", "div.pf-c-card", "input"
+ */
+export function getElementDescription(element: Element): string {
+  // Try to get React component name first
+  const componentMeta = getComponentMetadata(element);
+  if (componentMeta?.componentName && componentMeta.componentType !== 'native') {
+    return componentMeta.componentName;
+  }
+
+  // Fall back to DOM element description
+  const tagName = element.tagName.toLowerCase();
+  const classList = Array.from(element.classList);
+
+  // If element has classes, use the first one (usually the main component class)
+  if (classList.length > 0) {
+    return `${tagName}.${classList[0]}`;
+  }
+
+  // Fall back to just tag name
+  return tagName;
+}
+
+/**
+ * Get component metadata for an element (React component information)
+ */
+export function getElementComponentMetadata(element: Element): ComponentMetadata | null {
+  // Try to find the nearest React component element
+  const componentElement = findNearestComponentElement(element);
+  if (!componentElement) return null;
+
+  const metadata = getComponentMetadata(componentElement);
+  if (!metadata) return null;
+
+  // Add component path
+  const path = getComponentPath(componentElement);
+  return {
+    ...metadata,
+    componentPath: path.length > 0 ? path : undefined,
+  };
+}
+
+/**
+ * Query the DOM for an element matching the given CSS selector.
+ * Returns the element if found, null otherwise.
+ */
+export function findElementBySelector(selector: string | undefined): Element | null {
+  if (!selector) {
+    return null;
+  }
+
+  try {
+    return document.querySelector(selector);
+  } catch (error) {
+    // Invalid selector
+    console.warn('Invalid CSS selector:', selector, error);
+    return null;
+  }
+}