uilint-react 0.1.18 → 0.1.20

package/dist/index.d.ts

@@ -1,28 +1,267 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
-import { Violation, GroupedSnapshot, DOMSnapshot, ExtractedStyles, AnalysisResult } from 'uilint-core';
+import React$1 from 'react';
+import { GroupedSnapshot, Violation, DOMSnapshot, ExtractedStyles, AnalysisResult } from 'uilint-core';
 export { AnalysisResult, ConsistencyResult, DOMSnapshot, ElementRole, ElementSnapshot, ExtractedStyles, GroupedSnapshot, SerializedStyles, StyleGuide, StyleSnapshot, UILintIssue, Violation, ViolationCategory, ViolationSeverity, createEmptyStyleGuide, createStyleSummary, extractStylesFromDOM, generateStyleGuideFromStyles as generateStyleGuide, mergeStyleGuides, parseStyleGuide, serializeStyles } from 'uilint-core';
 
-interface UILintProps {
+/**
+ * Types for UILint Source Visualization
+ */
+/**
+ * Source location from React Fiber _debugSource
+ */
+interface SourceLocation {
+    fileName: string;
+    lineNumber: number;
+    columnNumber?: number;
+}
+/**
+ * Component information extracted from React Fiber
+ */
+interface ComponentInfo {
+    name: string;
+    source: SourceLocation | null;
+}
+/**
+ * A scanned DOM element with its React source information
+ */
+interface ScannedElement {
+    id: string;
+    element: Element;
+    tagName: string;
+    className: string;
+    source: SourceLocation | null;
+    componentStack: ComponentInfo[];
+    rect: DOMRect;
+}
+/**
+ * A source file with all its associated elements
+ */
+interface SourceFile {
+    path: string;
+    displayName: string;
+    color: string;
+    elements: ScannedElement[];
+}
+/**
+ * User-configurable settings for the overlay
+ */
+interface UILintSettings {
+    hideNodeModules: boolean;
+}
+/**
+ * Element detected under the cursor during Alt-key locator mode
+ */
+interface LocatorTarget {
+    element: Element;
+    source: SourceLocation | null;
+    componentStack: ComponentInfo[];
+    rect: DOMRect;
+    /** Index in the component stack (0 = current element, higher = parent) */
+    stackIndex: number;
+}
+/**
+ * Element being inspected in the sidebar
+ */
+interface InspectedElement {
+    element: Element;
+    source: SourceLocation | null;
+    componentStack: ComponentInfo[];
+    rect: DOMRect;
+}
+/**
+ * Context value provided by UILintProvider
+ */
+interface UILintContextValue {
+    settings: UILintSettings;
+    updateSettings: (settings: Partial<UILintSettings>) => void;
+    /** True when Alt/Option key is held down */
+    altKeyHeld: boolean;
+    /** Current element under cursor when Alt is held */
+    locatorTarget: LocatorTarget | null;
+    /** Navigate to parent component in locator mode */
+    locatorGoUp: () => void;
+    /** Navigate to child component in locator mode */
+    locatorGoDown: () => void;
+    /** Element currently being inspected in sidebar */
+    inspectedElement: InspectedElement | null;
+    /** Set the element to inspect (opens sidebar) */
+    setInspectedElement: (element: InspectedElement | null) => void;
+}
+/**
+ * Props for the UILintProvider component
+ */
+interface UILintProviderProps {
     children: React.ReactNode;
     enabled?: boolean;
-    position?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
-    autoScan?: boolean;
-    apiEndpoint?: string;
 }
-interface UILintContextValue {
-    violations: Violation[];
-    isScanning: boolean;
-    elementCount: number;
-    scan: () => Promise<void>;
-    clearViolations: () => void;
-    selectedViolation: Violation | null;
-    setSelectedViolation: (violation: Violation | null) => void;
-    lockedViolation: Violation | null;
-    setLockedViolation: (violation: Violation | null) => void;
+/**
+ * Response from the source API
+ */
+interface SourceApiResponse {
+    content: string;
+    relativePath: string;
+}
+/**
+ * Cached source file content
+ */
+interface CachedSource {
+    content: string;
+    relativePath: string;
+    fetchedAt: number;
 }
-declare function useUILint(): UILintContextValue;
-declare function UILint({ children, enabled, position, autoScan, apiEndpoint, }: UILintProps): react_jsx_runtime.JSX.Element;
+/**
+ * Color palette for source file differentiation
+ */
+declare const FILE_COLORS: readonly ["#3B82F6", "#8B5CF6", "#EC4899", "#10B981", "#F59E0B", "#06B6D4", "#EF4444", "#84CC16", "#6366F1", "#F97316", "#14B8A6", "#A855F7"];
+/**
+ * Default settings
+ */
+declare const DEFAULT_SETTINGS: UILintSettings;
+/**
+ * Data attribute used to mark scanned elements
+ */
+declare const DATA_UILINT_ID = "data-ui-lint-id";
+
+/**
+ * Hook to access UILint context
+ */
+declare function useUILintContext(): UILintContextValue;
+/**
+ * UILint Provider Component
+ */
+declare function UILintProvider({ children, enabled, }: UILintProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * UILint Toolbar - Simple floating button with settings popover
+ */
+
+/**
+ * Main Toolbar Component - Simple floating button with settings popover
+ */
+declare function UILintToolbar(): React$1.ReactPortal | null;
+
+/**
+ * Inspection Panel - Slide-out sidebar showing element details, source preview,
+ * and LLM analysis with clipboard-ready fix prompts
+ */
+
+/**
+ * Main Inspection Panel Component
+ */
+declare function InspectionPanel(): React$1.ReactPortal | null;
+
+/**
+ * Locator Overlay - Shows element info when Alt/Option key is held
+ * Inspired by LocatorJS for a quick "hover to find source" experience
+ */
+
+/**
+ * Main Locator Overlay Component
+ */
+declare function LocatorOverlay(): React$1.ReactPortal | null;
+
+/**
+ * React Fiber inspection utilities for source file visualization
+ *
+ * In development mode, React attaches debug information to Fiber nodes:
+ * - _debugSource: { fileName, lineNumber, columnNumber }
+ * - _debugOwner: The component that rendered this element
+ * - return: Parent fiber in the tree
+ */
+
+/** React Fiber type (simplified) */
+interface Fiber {
+    tag: number;
+    type: string | Function | null;
+    stateNode: Element | null;
+    return: Fiber | null;
+    _debugSource?: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber?: number;
+    } | null;
+    _debugOwner?: Fiber | null;
+}
+/**
+ * Get React Fiber from a DOM element
+ * React attaches fiber via __reactFiber$xxx key
+ */
+declare function getFiberFromElement(element: Element): Fiber | null;
+/**
+ * Extract source location from a fiber's _debugSource
+ */
+declare function getDebugSource(fiber: Fiber): SourceLocation | null;
+/**
+ * Get the debug owner fiber (component that rendered this element)
+ */
+declare function getDebugOwner(fiber: Fiber): Fiber | null;
+/**
+ * Build a component stack by walking up the fiber tree
+ * Returns an array from innermost to outermost component
+ */
+declare function getComponentStack(fiber: Fiber): ComponentInfo[];
+/**
+ * Check if a file path is from node_modules
+ */
+declare function isNodeModulesPath(path: string): boolean;
+/**
+ * Get display name from a file path (just the filename)
+ */
+declare function getDisplayName(path: string): string;
+/**
+ * Scan the DOM tree and extract React source information
+ */
+declare function scanDOMForSources(root?: Element, hideNodeModules?: boolean): ScannedElement[];
+/**
+ * Group scanned elements by their source file
+ */
+declare function groupBySourceFile(elements: ScannedElement[]): SourceFile[];
+/**
+ * Clean up data attributes from previous scans
+ */
+declare function cleanupDataAttributes(): void;
+/**
+ * Get an element by its UILint ID
+ */
+declare function getElementById(id: string): Element | null;
+/**
+ * Update element rects (for scroll/resize handling)
+ */
+declare function updateElementRects(elements: ScannedElement[]): ScannedElement[];
+/**
+ * Build an "Open in Editor" URL
+ */
+declare function buildEditorUrl(source: SourceLocation, editor?: "cursor" | "vscode"): string;
+
+/**
+ * Client for fetching source code from the dev API
+ */
+
+/**
+ * Fetch source code for a file
+ */
+declare function fetchSource(filePath: string): Promise<SourceApiResponse | null>;
+/**
+ * Fetch source and extract lines around a specific location
+ */
+declare function fetchSourceWithContext(source: SourceLocation, contextLines?: number): Promise<{
+    lines: string[];
+    startLine: number;
+    highlightLine: number;
+    relativePath: string;
+} | null>;
+/**
+ * Clear the source cache
+ */
+declare function clearSourceCache(): void;
+/**
+ * Get cached source without fetching
+ */
+declare function getCachedSource(filePath: string): SourceApiResponse | null;
+/**
+ * Prefetch source files for a list of paths
+ */
+declare function prefetchSources(filePaths: string[]): Promise<void>;
 
 /**
  * DOM snapshotting for consistency analysis
@@ -50,7 +289,7 @@ interface ConsistencyHighlighterProps {
  * Main consistency highlighter component
  * Renders highlights via Portal to document.body
  */
-declare function ConsistencyHighlighter({ violations, selectedViolation, lockedViolation, }: ConsistencyHighlighterProps): React.ReactPortal | null;
+declare function ConsistencyHighlighter({ violations, selectedViolation, lockedViolation, }: ConsistencyHighlighterProps): React$1.ReactPortal | null;
 
 /**
  * DOM scanner for browser environment
@@ -104,4 +343,4 @@ declare class LLMClient {
     generateStyleGuide(styles: ExtractedStyles): Promise<string | null>;
 }
 
-export { ConsistencyHighlighter, LLMClient, UILint, type UILintProps, cleanupDataElements, createSnapshot, getElementBySnapshotId, isBrowser, isJSDOM, isNode, scanDOM, useUILint };
+export { type CachedSource, type ComponentInfo, ConsistencyHighlighter, DATA_UILINT_ID, DEFAULT_SETTINGS, FILE_COLORS, type InspectedElement, InspectionPanel, LLMClient, LocatorOverlay, type LocatorTarget, type ScannedElement, type SourceApiResponse, type SourceFile, type SourceLocation, type UILintContextValue, UILintProvider, type UILintProviderProps, type UILintSettings, UILintToolbar, buildEditorUrl, cleanupDataAttributes, cleanupDataElements, clearSourceCache, createSnapshot, fetchSource, fetchSourceWithContext, getCachedSource, getComponentStack, getDebugOwner, getDebugSource, getDisplayName, getElementById, getElementBySnapshotId, getFiberFromElement, groupBySourceFile, isBrowser, isJSDOM, isNode, isNodeModulesPath, prefetchSources, scanDOM, scanDOMForSources, updateElementRects, useUILintContext };