npm - uilint-react - Versions diffs - 0.1.19 → 0.1.20 - Mend

uilint-react 0.1.19 → 0.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.md +49 -92
package/dist/{InspectionPanel-6DBGEWWD.js → InspectionPanel-3ML64TAP.js} +2 -2
package/dist/LocatorOverlay-GTTWBRKH.js +11 -0
package/dist/{UILintToolbar-7ZYCQC4M.js → UILintToolbar-GAOYF7GY.js} +2 -2
package/dist/{chunk-7WYVWDRU.js → chunk-DAFFOBEU.js} +53 -218
package/dist/{chunk-3TA6OKS6.js → chunk-NOISZ3XP.js} +417 -90
package/dist/chunk-PBC3J267.js +276 -0
package/dist/{chunk-KUFV22FO.js → chunk-VYCIUDU7.js} +72 -2
package/dist/index.d.ts +26 -65
package/dist/index.js +32 -1096
package/package.json +2 -2
package/dist/LocatorOverlay-FQEYAMT6.js +0 -9
package/dist/SourceOverlays-2SEINA2B.js +0 -9
package/dist/chunk-MEP7WO7U.js +0 -210
package/dist/chunk-OWX36QE3.js +0 -595

package/README.md CHANGED Viewed

@@ -4,7 +4,7 @@ React component for AI-powered UI consistency checking in running applications.
 ## Overview
-`uilint-react` provides React components and utilities for analyzing UI consistency at runtime and in tests. It includes a visual overlay for development and a JSDOM adapter for testing.
+`uilint-react` provides the `UILintProvider` component that enables element inspection and LLM-powered code analysis in your React/Next.js application.
 ## Installation
@@ -12,127 +12,70 @@ React component for AI-powered UI consistency checking in running applications.
 npm install uilint-react uilint-core
 ```
+Or use the CLI to install everything automatically:
+```bash
+npx uilint-cli install
+```
 ## Usage in a Running App
-Wrap your app with the `<UILint>` component to get a visual overlay:
+Wrap your app with the `UILintProvider` component:
 ### Next.js Setup
 ```tsx
 // app/layout.tsx
-import { UILint } from "uilint-react";
+import { UILintProvider } from "uilint-react";
 export default function RootLayout({ children }) {
   return (
     <html>
       <body>
-        <UILint
-          enabled={process.env.NODE_ENV !== "production"}
-          position="bottom-left"
-          autoScan={false}
-        >
+        <UILintProvider enabled={process.env.NODE_ENV !== "production"}>
           {children}
-        </UILint>
+        </UILintProvider>
       </body>
     </html>
   );
 }
 ```
+### Features
+- **Alt+Click** on any element to open the inspector sidebar
+- View component source location and file path
+- Navigate through the component stack (scroll while holding Alt)
+- **Open in Cursor** - jump directly to the source file
+- **Scan with LLM** - analyze the component for style issues
+- **Copy fix prompt** - paste into Cursor agent for automatic fixes
 ### Props
-| Prop          | Type                                                           | Default                 | Description                     |
-| ------------- | -------------------------------------------------------------- | ----------------------- | ------------------------------- |
-| `enabled`     | `boolean`                                                      | `true`                  | Enable/disable UILint           |
-| `position`    | `'bottom-left' \| 'bottom-right' \| 'top-left' \| 'top-right'` | `'bottom-left'`         | Overlay position                |
-| `autoScan`    | `boolean`                                                      | `false`                 | Automatically scan on page load |
-| `apiEndpoint` | `string`                                                       | `'/api/uilint/analyze'` | Custom API endpoint             |
+| Prop      | Type      | Default | Description           |
+| --------- | --------- | ------- | --------------------- |
+| `enabled` | `boolean` | `true`  | Enable/disable UILint |
 ### API Routes
-You'll need to add API routes for the React component:
+The CLI installs these routes automatically, or you can add them manually:
 ```ts
 // app/api/uilint/analyze/route.ts
-import { NextRequest, NextResponse } from "next/server";
-import { OllamaClient, UILINT_DEFAULT_OLLAMA_MODEL } from "uilint-core";
-export async function POST(request: NextRequest) {
-  const { styleSummary, styleGuide, generateGuide, model } =
-    await request.json();
-  const client = new OllamaClient({
-    model: model || UILINT_DEFAULT_OLLAMA_MODEL,
-  });
-  if (generateGuide) {
-    const styleGuideContent = await client.generateStyleGuide(styleSummary);
-    return NextResponse.json({ styleGuide: styleGuideContent });
-  } else {
-    const result = await client.analyzeStyles(styleSummary, styleGuide);
-    return NextResponse.json({ issues: result.issues });
-  }
-}
-```
-```ts
-// app/api/uilint/styleguide/route.ts
-import { NextRequest, NextResponse } from "next/server";
-import {
-  readStyleGuideFromProject,
-  writeStyleGuide,
-  styleGuideExists,
-  getDefaultStyleGuidePath,
-} from "uilint-core/node";
-export async function GET() {
-  const projectPath = process.cwd();
-  if (!styleGuideExists(projectPath)) {
-    return NextResponse.json({ exists: false, content: null });
-  }
-  const content = await readStyleGuideFromProject(projectPath);
-  return NextResponse.json({ exists: true, content });
-}
+// Handles LLM analysis of source code
-export async function POST(request: NextRequest) {
-  const { content } = await request.json();
-  const projectPath = process.cwd();
-  const stylePath = getDefaultStyleGuidePath(projectPath);
-  await writeStyleGuide(stylePath, content);
-  return NextResponse.json({ success: true });
-}
+// app/api/dev/source/route.ts
+// Dev-only route for fetching source files
 ```
 ## Usage in Tests
 UILint can run in Vitest/Jest tests with JSDOM:
-### Basic Test
-```tsx
-import { render, screen } from "@testing-library/react";
-import { UILint } from "uilint-react";
-import { MyComponent } from "./MyComponent";
-test("MyComponent has consistent styles", async () => {
-  render(
-    <UILint enabled={true}>
-      <MyComponent />
-    </UILint>
-  );
-  expect(screen.getByRole("button")).toBeInTheDocument();
-  // UILint automatically outputs warnings to console:
-  // ⚠️ [UILint] Button uses #3B82F6 but style guide specifies #2563EB
-});
-```
 ### Direct JSDOM Adapter
-For more control, use the `JSDOMAdapter`:
 ```tsx
-import { JSDOMAdapter, runUILintInTest } from "uilint-react";
+import { JSDOMAdapter, runUILintInTest } from "uilint-react/node";
 import { render } from "@testing-library/react";
 test("detect style inconsistencies", async () => {
@@ -160,23 +103,37 @@ test("custom adapter usage", async () => {
 ## API
-### UILint Component
+### UILintProvider
 ```tsx
-interface UILintProps {
+interface UILintProviderProps {
   enabled?: boolean;
-  position?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
-  autoScan?: boolean;
-  apiEndpoint?: string;
   children: React.ReactNode;
 }
-function UILint(props: UILintProps): JSX.Element;
+function UILintProvider(props: UILintProviderProps): JSX.Element;
+```
+### useUILintContext
+```tsx
+function useUILintContext(): UILintContextValue;
+interface UILintContextValue {
+  settings: UILintSettings;
+  updateSettings: (settings: Partial<UILintSettings>) => void;
+  altKeyHeld: boolean;
+  locatorTarget: LocatorTarget | null;
+  inspectedElement: InspectedElement | null;
+  setInspectedElement: (element: InspectedElement | null) => void;
+  // ... additional context values
+}
 ```
-### JSDOM Adapter
+### JSDOM Adapter (Node.js)
 ```typescript
+// Import from "uilint-react/node" for test environments
 class JSDOMAdapter {
   constructor(styleGuidePath?: string);

package/dist/{InspectionPanel-6DBGEWWD.js → InspectionPanel-3ML64TAP.js} RENAMED Viewed

@@ -2,8 +2,8 @@
 "use client";
 import {
   InspectionPanel
-} from "./chunk-3TA6OKS6.js";
-import "./chunk-7WYVWDRU.js";
+} from "./chunk-NOISZ3XP.js";
+import "./chunk-DAFFOBEU.js";
 export {
   InspectionPanel
 };

package/dist/LocatorOverlay-GTTWBRKH.js ADDED Viewed

@@ -0,0 +1,11 @@
+"use client";
+"use client";
+import {
+  InspectedElementHighlight,
+  LocatorOverlay
+} from "./chunk-VYCIUDU7.js";
+import "./chunk-DAFFOBEU.js";
+export {
+  InspectedElementHighlight,
+  LocatorOverlay
+};

package/dist/{UILintToolbar-7ZYCQC4M.js → UILintToolbar-GAOYF7GY.js} RENAMED Viewed

@@ -2,8 +2,8 @@
 "use client";
 import {
   UILintToolbar
-} from "./chunk-OWX36QE3.js";
-import "./chunk-7WYVWDRU.js";
+} from "./chunk-PBC3J267.js";
+import "./chunk-DAFFOBEU.js";
 export {
   UILintToolbar
 };

package/dist/{chunk-7WYVWDRU.js → chunk-DAFFOBEU.js} RENAMED Viewed

@@ -28,10 +28,7 @@ var FILE_COLORS = [
   // purple
 ];
 var DEFAULT_SETTINGS = {
-  showLabels: true,
-  hideNodeModules: true,
-  overlayOpacity: 0.2,
-  labelPosition: "top-left"
+  hideNodeModules: true
 };
 var DATA_UILINT_ID = "data-ui-lint-id";
@@ -250,127 +247,13 @@ function buildEditorUrl(source, editor = "cursor") {
   )}:${lineNumber}:${column}`;
 }
-// src/components/ui-lint/use-element-scan.ts
-import { useState, useEffect, useCallback, useRef } from "react";
-function debounce(fn, delay) {
-  let timeoutId;
-  return (...args) => {
-    clearTimeout(timeoutId);
-    timeoutId = setTimeout(() => fn(...args), delay);
-  };
-}
-function useElementScan({
-  enabled,
-  settings
-}) {
-  const [elements, setElements] = useState([]);
-  const [sourceFiles, setSourceFiles] = useState([]);
-  const [isScanning, setIsScanning] = useState(false);
-  const mutationObserverRef = useRef(null);
-  const resizeObserverRef = useRef(null);
-  const performScan = useCallback(() => {
-    if (!enabled || typeof window === "undefined") return;
-    setIsScanning(true);
-    const scan = () => {
-      try {
-        const scannedElements = scanDOMForSources(
-          document.body,
-          settings.hideNodeModules
-        );
-        const files = groupBySourceFile(scannedElements);
-        setElements(scannedElements);
-        setSourceFiles(files);
-      } catch (error) {
-        console.error("[UILint] Scan error:", error);
-      } finally {
-        setIsScanning(false);
-      }
-    };
-    if ("requestIdleCallback" in window) {
-      window.requestIdleCallback(scan, { timeout: 1e3 });
-    } else {
-      setTimeout(scan, 0);
-    }
-  }, [enabled, settings.hideNodeModules]);
-  const updatePositions = useCallback(() => {
-    if (elements.length === 0) return;
-    setElements((prev) => updateElementRects(prev));
-  }, [elements.length]);
-  const debouncedRescan = useCallback(
-    debounce(() => {
-      performScan();
-    }, 500),
-    [performScan]
-  );
-  const handleScroll = useCallback(
-    debounce(() => {
-      updatePositions();
-    }, 16),
-    // ~60fps
-    [updatePositions]
-  );
-  const handleResize = useCallback(
-    debounce(() => {
-      updatePositions();
-    }, 100),
-    [updatePositions]
-  );
-  useEffect(() => {
-    if (!enabled) {
-      cleanupDataAttributes();
-      setElements([]);
-      setSourceFiles([]);
-      return;
-    }
-    const initialScanTimer = setTimeout(performScan, 100);
-    mutationObserverRef.current = new MutationObserver((mutations) => {
-      const hasRelevantMutation = mutations.some((mutation) => {
-        if (mutation.type === "attributes") {
-          return !mutation.attributeName?.startsWith("data-ui-lint");
-        }
-        return true;
-      });
-      if (hasRelevantMutation) {
-        debouncedRescan();
-      }
-    });
-    mutationObserverRef.current.observe(document.body, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: ["class", "style"]
-    });
-    window.addEventListener("scroll", handleScroll, true);
-    window.addEventListener("resize", handleResize);
-    return () => {
-      clearTimeout(initialScanTimer);
-      mutationObserverRef.current?.disconnect();
-      resizeObserverRef.current?.disconnect();
-      window.removeEventListener("scroll", handleScroll, true);
-      window.removeEventListener("resize", handleResize);
-      cleanupDataAttributes();
-    };
-  }, [enabled, performScan, debouncedRescan, handleScroll, handleResize]);
-  useEffect(() => {
-    if (enabled && elements.length > 0) {
-      performScan();
-    }
-  }, [settings.hideNodeModules]);
-  return {
-    elements,
-    sourceFiles,
-    isScanning,
-    rescan: performScan
-  };
-}
 // src/components/ui-lint/UILintProvider.tsx
 import {
   createContext,
   useContext,
-  useState as useState2,
-  useEffect as useEffect2,
-  useCallback as useCallback2,
+  useState,
+  useEffect,
+  useCallback,
   useMemo
 } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -387,54 +270,28 @@ function isBrowser() {
 }
 function UILintProvider({
   children,
-  enabled = true,
-  defaultMode = "off"
+  enabled = true
 }) {
-  const [mode, setMode] = useState2(defaultMode);
-  const [settings, setSettings] = useState2(DEFAULT_SETTINGS);
-  const [selectedElement, setSelectedElement] = useState2(
+  const [settings, setSettings] = useState(DEFAULT_SETTINGS);
+  const [isMounted, setIsMounted] = useState(false);
+  const [altKeyHeld, setAltKeyHeld] = useState(false);
+  const [locatorTarget, setLocatorTarget] = useState(
     null
   );
-  const [hoveredElement, setHoveredElement] = useState2(
-    null
-  );
-  const [isMounted, setIsMounted] = useState2(false);
-  const [altKeyHeld, setAltKeyHeld] = useState2(false);
-  const [locatorTarget, setLocatorTarget] = useState2(
-    null
-  );
-  const [locatorStackIndex, setLocatorStackIndex] = useState2(0);
-  const isActive = enabled && mode !== "off";
-  const { elements, sourceFiles, isScanning, rescan } = useElementScan({
-    enabled: isActive,
-    settings
-  });
-  const updateSettings = useCallback2((partial) => {
+  const [locatorStackIndex, setLocatorStackIndex] = useState(0);
+  const [inspectedElement, setInspectedElement] = useState(null);
+  const updateSettings = useCallback((partial) => {
     setSettings((prev) => ({ ...prev, ...partial }));
   }, []);
-  const toggleMode = useCallback2(() => {
-    setMode((prev) => {
-      if (prev === "off") return "sources";
-      if (prev === "sources") return "inspect";
-      return "off";
-    });
-  }, []);
-  const handleEscape = useCallback2(() => {
-    if (selectedElement) {
-      setSelectedElement(null);
-    } else if (mode !== "off") {
-      setMode("off");
-    }
-  }, [selectedElement, mode]);
-  const locatorGoUp = useCallback2(() => {
+  const locatorGoUp = useCallback(() => {
     if (!locatorTarget) return;
     const maxIndex = locatorTarget.componentStack.length;
     setLocatorStackIndex((prev) => Math.min(prev + 1, maxIndex));
   }, [locatorTarget]);
-  const locatorGoDown = useCallback2(() => {
+  const locatorGoDown = useCallback(() => {
     setLocatorStackIndex((prev) => Math.max(prev - 1, 0));
   }, []);
-  const getLocatorTargetFromElement = useCallback2(
+  const getLocatorTargetFromElement = useCallback(
     (element) => {
       if (element.closest("[data-ui-lint]")) return null;
       let source = getSourceFromDataLoc(element);
@@ -470,7 +327,7 @@ function UILintProvider({
     },
     [settings.hideNodeModules]
   );
-  const handleMouseMove = useCallback2(
+  const handleMouseMove = useCallback(
     (e) => {
       if (!altKeyHeld) return;
       const elementAtPoint = document.elementFromPoint(e.clientX, e.clientY);
@@ -491,7 +348,7 @@ function UILintProvider({
     },
     [altKeyHeld, getLocatorTargetFromElement]
   );
-  const handleLocatorClick = useCallback2(
+  const handleLocatorClick = useCallback(
     (e) => {
       if (!altKeyHeld || !locatorTarget) return;
       e.preventDefault();
@@ -503,14 +360,19 @@ function UILintProvider({
           source = stackItem.source;
         }
       }
-      if (source) {
-        const url = buildEditorUrl(source, "cursor");
-        window.open(url, "_blank");
-      }
+      setInspectedElement({
+        element: locatorTarget.element,
+        source,
+        componentStack: locatorTarget.componentStack,
+        rect: locatorTarget.rect
+      });
+      setAltKeyHeld(false);
+      setLocatorTarget(null);
+      setLocatorStackIndex(0);
     },
     [altKeyHeld, locatorTarget, locatorStackIndex]
   );
-  useEffect2(() => {
+  useEffect(() => {
     if (!isBrowser() || !enabled) return;
     const handleKeyDown = (e) => {
       if (e.key === "Alt") {
@@ -539,7 +401,7 @@ function UILintProvider({
       window.removeEventListener("blur", handleBlur);
     };
   }, [enabled]);
-  useEffect2(() => {
+  useEffect(() => {
     if (!isBrowser() || !enabled || !altKeyHeld) return;
     window.addEventListener("mousemove", handleMouseMove);
     window.addEventListener("click", handleLocatorClick, true);
@@ -548,7 +410,7 @@ function UILintProvider({
       window.removeEventListener("click", handleLocatorClick, true);
     };
   }, [enabled, altKeyHeld, handleMouseMove, handleLocatorClick]);
-  useEffect2(() => {
+  useEffect(() => {
     if (!isBrowser() || !enabled || !altKeyHeld) return;
     const handleWheel = (e) => {
       if (!locatorTarget) return;
@@ -562,29 +424,19 @@ function UILintProvider({
     window.addEventListener("wheel", handleWheel, { passive: false });
     return () => window.removeEventListener("wheel", handleWheel);
   }, [enabled, altKeyHeld, locatorTarget, locatorGoUp, locatorGoDown]);
-  useEffect2(() => {
+  useEffect(() => {
     if (!isBrowser() || !enabled) return;
     const handleKeyDown = (e) => {
-      if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key === "d") {
-        e.preventDefault();
-        toggleMode();
-        return;
-      }
-      if (e.key === "Escape") {
-        handleEscape();
-        return;
+      if (e.key === "Escape" && inspectedElement) {
+        setInspectedElement(null);
       }
     };
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [enabled, toggleMode, handleEscape]);
-  useEffect2(() => {
+  }, [enabled, inspectedElement]);
+  useEffect(() => {
     setIsMounted(true);
   }, []);
-  useEffect2(() => {
-    setSelectedElement(null);
-    setHoveredElement(null);
-  }, [mode]);
   const effectiveLocatorTarget = useMemo(() => {
     if (!locatorTarget) return null;
     return {
@@ -594,37 +446,23 @@ function UILintProvider({
   }, [locatorTarget, locatorStackIndex]);
   const contextValue = useMemo(
     () => ({
-      mode,
-      setMode,
-      scannedElements: elements,
-      sourceFiles,
-      selectedElement,
-      setSelectedElement,
-      hoveredElement,
-      setHoveredElement,
       settings,
       updateSettings,
-      rescan,
-      isScanning,
       altKeyHeld,
       locatorTarget: effectiveLocatorTarget,
       locatorGoUp,
-      locatorGoDown
+      locatorGoDown,
+      inspectedElement,
+      setInspectedElement
     }),
     [
-      mode,
-      elements,
-      sourceFiles,
-      selectedElement,
-      hoveredElement,
       settings,
       updateSettings,
-      rescan,
-      isScanning,
       altKeyHeld,
       effectiveLocatorTarget,
       locatorGoUp,
-      locatorGoDown
+      locatorGoDown,
+      inspectedElement
     ]
   );
   const shouldRenderUI = enabled && isMounted;
@@ -634,33 +472,31 @@ function UILintProvider({
   ] });
 }
 function UILintUI() {
-  const { mode, altKeyHeld } = useUILintContext();
-  const [components, setComponents] = useState2(null);
-  useEffect2(() => {
+  const { altKeyHeld, inspectedElement } = useUILintContext();
+  const [components, setComponents] = useState(null);
+  useEffect(() => {
     Promise.all([
-      import("./UILintToolbar-7ZYCQC4M.js"),
-      import("./SourceOverlays-2SEINA2B.js"),
-      import("./InspectionPanel-6DBGEWWD.js"),
-      import("./LocatorOverlay-FQEYAMT6.js")
-    ]).then(([toolbar, overlays, panel, locator]) => {
+      import("./UILintToolbar-GAOYF7GY.js"),
+      import("./InspectionPanel-3ML64TAP.js"),
+      import("./LocatorOverlay-GTTWBRKH.js")
+    ]).then(([toolbar, panel, locator]) => {
       setComponents({
         Toolbar: toolbar.UILintToolbar,
-        Overlays: overlays.SourceOverlays,
         Panel: panel.InspectionPanel,
-        LocatorOverlay: locator.LocatorOverlay
+        LocatorOverlay: locator.LocatorOverlay,
+        InspectedHighlight: locator.InspectedElementHighlight
       });
     });
   }, []);
   if (!components) return null;
-  const { Toolbar, Overlays, Panel, LocatorOverlay } = components;
+  const { Toolbar, Panel, LocatorOverlay, InspectedHighlight } = components;
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx(Toolbar, {}),
-    mode === "sources" && /* @__PURE__ */ jsx(Overlays, {}),
-    mode === "inspect" && /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(Overlays, {}),
+    altKeyHeld && /* @__PURE__ */ jsx(LocatorOverlay, {}),
+    inspectedElement && /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(InspectedHighlight, {}),
       /* @__PURE__ */ jsx(Panel, {})
-    ] }),
-    altKeyHeld && /* @__PURE__ */ jsx(LocatorOverlay, {})
+    ] })
   ] });
 }
@@ -680,7 +516,6 @@ export {
   getElementById,
   updateElementRects,
   buildEditorUrl,
-  useElementScan,
   useUILintContext,
   UILintProvider
 };