feat: add persistent options with localStorage (#145)

* feat: add persistent options with localStorage

Author: pivanov

README.md

@@ -225,6 +225,7 @@ export interface Options {
    * Maximum number of renders for red indicator
    *
    * @default 20
+   * @deprecated
    */
   maxRenders?: number;
 

packages/scan/src/core/index.ts

@@ -25,6 +25,7 @@ import {
 import { playGeigerClickSound } from '@web-utils/geiger';
 import { ICONS } from '@web-assets/svgs/svgs';
 import { updateFiberRenderData, type RenderData } from 'src/core/utils';
+import { readLocalStorage, saveLocalStorage } from '@web-utils/helpers';
 import { initReactScanOverlay } from './web/overlay';
 import { createInstrumentation, type Render } from './instrumentation';
 import { createToolbar } from './web/toolbar';
@@ -33,6 +34,7 @@ import { type getSession } from './monitor/utils';
 import styles from './web/assets/css/styles.css';
 
 let toolbarContainer: HTMLElement | null = null;
+let shadowRoot: ShadowRoot | null = null;
 
 export interface Options {
   /**
@@ -213,6 +215,74 @@ export const ReactScanInternals: Internals = {
   Store,
 };
 
+type LocalStorageOptions = Omit<Options,
+  | 'onCommitStart'
+  | 'onRender'
+  | 'onCommitFinish'
+  | 'onPaintStart'
+  | 'onPaintFinish'
+>;
+
+const validateOptions = (options: Partial<Options>): Partial<Options> => {
+  const errors: Array<string> = [];
+  const validOptions: Partial<Options> = {};
+
+  Object.entries(options).forEach(([key, value]) => {
+    switch (key) {
+      case 'enabled':
+      case 'includeChildren':
+      case 'playSound':
+      case 'log':
+      case 'showToolbar':
+      case 'report':
+      case 'alwaysShowLabels':
+      case 'dangerouslyForceRunInProduction':
+        if (typeof value !== 'boolean') {
+          errors.push(`- ${key} must be a boolean. Got "${value}"`);
+        } else {
+          (validOptions as any)[key] = value;
+        }
+        break;
+      case 'renderCountThreshold':
+      case 'resetCountTimeout':
+        if (typeof value !== 'number' || value < 0) {
+          errors.push(`- ${key} must be a non-negative number. Got "${value}"`);
+        } else {
+          (validOptions as any)[key] = value;
+        }
+        break;
+      case 'animationSpeed':
+        if (!['slow', 'fast', 'off'].includes(value as string)) {
+          errors.push(`- Invalid animation speed "${value}". Using default "fast"`);
+        } else {
+          (validOptions as any)[key] = value;
+        }
+        break;
+      case 'onCommitStart':
+      case 'onCommitFinish':
+      case 'onRender':
+      case 'onPaintStart':
+      case 'onPaintFinish':
+        if (typeof value !== 'function') {
+          errors.push(`- ${key} must be a function. Got "${value}"`);
+        } else {
+          (validOptions as any)[key] = value;
+        }
+        break;
+      default:
+        errors.push(`- Unknown option "${key}"`);
+    }
+  });
+
+  if (errors.length > 0) {
+    // eslint-disable-next-line no-console
+    console.warn(`[React Scan] Invalid options:\n${errors.join('\n')}`);
+    return {};
+  }
+
+  return validOptions;
+};
+
 export const getReport = (type?: React.ComponentType<any>) => {
   if (type) {
     for (const reportData of Array.from(Store.legacyReportData.values())) {
@@ -225,32 +295,57 @@ export const getReport = (type?: React.ComponentType<any>) => {
   return Store.legacyReportData;
 };
 
-export const setOptions = (options: Options) => {
+const initializeScanOptions = (userOptions?: Partial<Options>) => {
+  const options = ReactScanInternals.options.value;
+
+  const localStorageOptions = readLocalStorage<LocalStorageOptions>('react-scan-options');
+  if (localStorageOptions) {
+    (Object.keys(localStorageOptions) as Array<keyof LocalStorageOptions>).forEach(key => {
+      const value = localStorageOptions[key];
+      if (key in options && value !== null) {
+        (options as any)[key] = value;
+      }
+    });
+  }
+
+  ReactScanInternals.options.value = validateOptions({
+    ...options,
+    ...userOptions,
+  });
+
+  saveLocalStorage('react-scan-options', ReactScanInternals.options.value);
+
+  return ReactScanInternals.options.value;
+};
+
+export const setOptions = (userOptions: Partial<Options>) => {
+  const validOptions = validateOptions(userOptions);
+
+  if (Object.keys(validOptions).length === 0) {
+    return;
+  }
+
   const { instrumentation } = ReactScanInternals;
   if (instrumentation) {
-    instrumentation.isPaused.value = options.enabled === false;
+    instrumentation.isPaused.value = validOptions.enabled === false;
   }
 
-  const previousOptions = ReactScanInternals.options.value;
+  const newOptions = initializeScanOptions(validOptions);
 
-  ReactScanInternals.options.value = {
-    ...ReactScanInternals.options.value,
-    ...options,
-  };
+  if (toolbarContainer && !newOptions.showToolbar) {
+    toolbarContainer.remove();
+  }
 
-  if (previousOptions.showToolbar && !options.showToolbar) {
-    if (toolbarContainer) {
-      toolbarContainer.remove();
-      toolbarContainer = null;
-    }
+  if (newOptions.showToolbar && toolbarContainer && shadowRoot) {
+    toolbarContainer = createToolbar(shadowRoot);
   }
 };
 
 export const getOptions = () => ReactScanInternals.options;
 
 export const reportRender = (fiber: Fiber, renders: Array<Render>) => {
   const reportFiber = fiber;
-  const { selfTime } = getTimings(fiber);
+  const { selfTime } = getTimings(fiber.type);
   const displayName = getDisplayName(fiber.type);
 
   Store.lastReportTime.value = performance.now();
@@ -354,6 +449,11 @@ export const start = () => {
           !ReactScanInternals.options.value.dangerouslyForceRunInProduction
         ) {
           setOptions({ enabled: false, showToolbar: false });
+          // eslint-disable-next-line no-console
+          console.warn(
+            '[React Scan] Running in production mode is not recommended.\n' +
+            'If you really need this, set dangerouslyForceRunInProduction: true in options.'
+          );
           return;
         }
 
@@ -365,7 +465,7 @@ export const start = () => {
         const container = document.createElement('div');
         container.id = 'react-scan-root';
 
-        const shadow = container.attachShadow({ mode: 'open' });
+        shadowRoot = container.attachShadow({ mode: 'open' });
 
         const fragment = document.createDocumentFragment();
 
@@ -376,7 +476,7 @@ export const start = () => {
           ICONS,
           'image/svg+xml',
         ).documentElement;
-        shadow.appendChild(iconSprite);
+        shadowRoot.appendChild(iconSprite);
 
         const root = document.createElement('div');
         root.id = 'react-scan-toolbar-root';
@@ -385,22 +485,22 @@ export const start = () => {
         fragment.appendChild(cssStyles);
         fragment.appendChild(root);
 
-        shadow.appendChild(fragment);
+        shadowRoot.appendChild(fragment);
 
         document.documentElement.appendChild(container);
 
         ctx = initReactScanOverlay();
         if (!ctx) return;
         startFlushOutlineInterval(ctx);
 
-        createInspectElementStateMachine(shadow);
+        createInspectElementStateMachine(shadowRoot);
 
         globalThis.__REACT_SCAN__ = {
           ReactScanInternals,
         };
 
         if (ReactScanInternals.options.value.showToolbar) {
-          toolbarContainer = createToolbar(shadow);
+          toolbarContainer = createToolbar(shadowRoot);
         }
 
         container.setAttribute('part', 'scan-root');

packages/scan/src/core/web/assets/css/styles.tailwind.css

@@ -149,9 +149,6 @@ button {
   }
 }
 
-/* pivanov */
-
-
 .react-scan-inspector {
   font-size: 13px;
   color: #fff;

packages/scan/src/core/web/components/widget/toolbar.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo } from 'preact/hooks';
-import { cn, readLocalStorage, saveLocalStorage } from '@web-utils/helpers';
+import { cn } from '@web-utils/helpers';
 import { ReactScanInternals, Store, setOptions } from '../../../..';
 import { getNearestFiberFromElement } from '../../inspect-element/utils';
 import { Icon } from '../icon';
@@ -12,7 +12,6 @@ interface ToolbarProps {
 export const Toolbar = ({ refPropContainer }: ToolbarProps) => {
   const inspectState = Store.inspectState;
 
-  const instrumentation = ReactScanInternals.instrumentation;
   const isInspectFocused = inspectState.value.kind === 'focused';
   const isInspectActive = inspectState.value.kind === 'inspecting';
 
@@ -62,85 +61,68 @@ export const Toolbar = ({ refPropContainer }: ToolbarProps) => {
     }
   }, [Store.inspectState.value]);
 
-  const onPreviousFocus = useCallback(() => {
-    const currentState = Store.inspectState.value;
-    if (currentState.kind !== 'focused' || !currentState.focusedDomElement)
-      return;
-
-    const focusedDomElement = currentState.focusedDomElement;
+  const findNextElement = useCallback((
+    currentElement: HTMLElement,
+    direction: 'next' | 'previous'
+  ) => {
     const allElements = Array.from(document.querySelectorAll('*')).filter(
       (el): el is HTMLElement => el instanceof HTMLElement,
     );
-    const currentIndex = allElements.indexOf(focusedDomElement);
-    if (currentIndex === -1) return;
+    const currentIndex = allElements.indexOf(currentElement);
+    if (currentIndex === -1) return null;
 
-    let prevElement: HTMLElement | null = null;
-    let prevIndex = currentIndex - 1;
-    const currentFiber = getNearestFiberFromElement(focusedDomElement);
+    const currentFiber = getNearestFiberFromElement(currentElement);
+    const increment = direction === 'next' ? 1 : -1;
+    let index = currentIndex + increment;
 
-    while (prevIndex >= 0) {
-      const fiber = getNearestFiberFromElement(allElements[prevIndex]);
+    while (index >= 0 && index < allElements.length) {
+      const fiber = getNearestFiberFromElement(allElements[index]);
       if (fiber && fiber !== currentFiber) {
-        prevElement = allElements[prevIndex];
-        break;
+        return allElements[index];
       }
-      prevIndex--;
+      index += increment;
     }
+    return null;
+  }, []);
+
+  const onPreviousFocus = useCallback(() => {
+    const currentState = Store.inspectState.value;
+    if (currentState.kind !== 'focused' || !currentState.focusedDomElement) return;
 
+    const prevElement = findNextElement(currentState.focusedDomElement, 'previous');
     if (prevElement) {
       Store.inspectState.value = {
         kind: 'focused',
         focusedDomElement: prevElement,
         propContainer: currentState.propContainer,
       };
     }
-  }, [Store.inspectState.value]);
+  }, [findNextElement]);
 
   const onNextFocus = useCallback(() => {
     const currentState = Store.inspectState.value;
-    if (currentState.kind !== 'focused' || !currentState.focusedDomElement)
-      return;
-
-    const focusedDomElement = currentState.focusedDomElement;
-    const allElements = Array.from(document.querySelectorAll('*')).filter(
-      (el): el is HTMLElement => el instanceof HTMLElement,
-    );
-    const currentIndex = allElements.indexOf(focusedDomElement);
-    if (currentIndex === -1) return;
-
-    let nextElement: HTMLElement | null = null;
-    let nextIndex = currentIndex + 1;
-    const prevFiber = getNearestFiberFromElement(focusedDomElement);
-
-    while (nextIndex < allElements.length) {
-      const fiber = getNearestFiberFromElement(allElements[nextIndex]);
-      if (fiber && fiber !== prevFiber) {
-        nextElement = allElements[nextIndex];
-        break;
-      }
-      nextIndex++;
-    }
+    if (currentState.kind !== 'focused' || !currentState.focusedDomElement) return;
 
+    const nextElement = findNextElement(currentState.focusedDomElement, 'next');
     if (nextElement) {
       Store.inspectState.value = {
         kind: 'focused',
         focusedDomElement: nextElement,
         propContainer: currentState.propContainer,
       };
     }
-  }, [Store.inspectState.value]);
+  }, [findNextElement]);
 
   const onToggleActive = useCallback(() => {
-    if (instrumentation) {
-      instrumentation.isPaused.value = !instrumentation.isPaused.value;
-      saveLocalStorage('react-scan-paused', instrumentation.isPaused.value);
+    if (ReactScanInternals.instrumentation) {
+      ReactScanInternals.instrumentation.isPaused.value = !ReactScanInternals.instrumentation.isPaused.value;
     }
-  }, []);
+  }, [ReactScanInternals.instrumentation]);
+
 
   const onSoundToggle = useCallback(() => {
     const newSoundState = !ReactScanInternals.options.value.playSound;
-    setOptions({ playSound: newSoundState, showToolbar: true });
-    saveLocalStorage('react-scan-sound', newSoundState);
+    setOptions({ playSound: newSoundState });
   }, []);
 
   useEffect(() => {
@@ -154,20 +136,6 @@ export const Toolbar = ({ refPropContainer }: ToolbarProps) => {
     }
   }, []);
 
-  useEffect(() => {
-    if (instrumentation) {
-      const savedStatePaused = readLocalStorage<boolean>('react-scan-paused');
-      if (savedStatePaused !== null) {
-        instrumentation.isPaused.value = savedStatePaused;
-      }
-
-      const savedStateSound = readLocalStorage<boolean>('react-scan-sound');
-      if (savedStateSound !== null) {
-        setOptions({ playSound: savedStateSound, showToolbar: true });
-      }
-    }
-  }, []);
-
   return (
     <div className="flex max-h-9 min-h-9 flex-1 items-stretch overflow-hidden">
       <button