Add show options to debugger api (#84)

* Refactor devtools settings to use nested show properties for better organization

* fix format

Author: spaansba

packages/devpage-react/src/components/ui/ControlSection.tsx

@@ -57,7 +57,7 @@ const ControlSection = ({ title, subtitle }: ControlSectionProps) => {
       description: "Toggle Debug Mode",
       onClick: () => {
         ForesightDevtools.instance.alterDevtoolsSettings({
-          showDebugger: !ForesightDevtools.instance.devtoolsSettings.showDebugger,
+          show: { controlPanel: !ForesightDevtools.instance.devtoolsSettings.show.controlPanel },
         })
       },
       isActive: true,

packages/devpage-react/src/contexts/DebugContext.tsx

@@ -11,21 +11,21 @@ const DebugContext = createContext<DebugContextType | undefined>(undefined)
 
 export function DebugProvider({ children }: { children: ReactNode }) {
   const [isDebugActive, setIsDebugActive] = useState(
-    () => ForesightDevtools.instance.devtoolsSettings.showDebugger
+    () => ForesightDevtools.instance.devtoolsSettings.show.controlPanel
   )
 
   const toggleDebug = useCallback(() => {
     const newState = !isDebugActive
     setIsDebugActive(newState)
     ForesightDevtools.instance.alterDevtoolsSettings({
-      showDebugger: newState,
+      show: { controlPanel: newState },
     })
   }, [isDebugActive])
 
   const setDebugMode = useCallback((enabled: boolean) => {
     setIsDebugActive(enabled)
     ForesightDevtools.instance.alterDevtoolsSettings({
-      showDebugger: enabled,
+      show: { controlPanel: enabled },
     })
   }, [])
 

packages/docs/src/components/Hero/Hero.tsx

@@ -43,17 +43,19 @@ export function Hero() {
   })
 
   ForesightDevtools.initialize({
-    showDebugger:
-      typeof window !== "undefined" &&
-      !(window.matchMedia("(pointer: coarse)").matches && navigator.maxTouchPoints > 0),
-    showNameTags: false,
+    show: {
+      controlPanel:
+        typeof window !== "undefined" &&
+        !(window.matchMedia("(pointer: coarse)").matches && navigator.maxTouchPoints > 0),
+      nameTags: false,
+    },
     isControlPanelDefaultMinimized: true,
     logging: { callbackCompleted: true, callbackInvoked: true, managerSettingsChanged: true },
   })
 
   const turnOffDebugMode = () => {
     ForesightDevtools.instance.alterDevtoolsSettings({
-      showDebugger: false,
+      show: { controlPanel: false },
     })
   }
 

packages/docs/src/hooks/useDebugMode.ts

@@ -4,7 +4,7 @@ import { useState, useEffect } from "react"
 function useDebugMode() {
   const [debugMode, setDebugMode] = useState(true)
   useEffect(() => {
-    ForesightDevtools.instance.alterDevtoolsSettings({ showDebugger: debugMode })
+    ForesightDevtools.instance.alterDevtoolsSettings({ show: { controlPanel: debugMode } })
   }, [debugMode])
 
   const toggleDebugMode = () => {

packages/js.foresight-devtools/README.md

@@ -31,9 +31,14 @@ ForesightManager.initialize({})
 
 // Initialize the development tools (all options are optional)
 ForesightDevtools.initialize({
-  showDebugger: true,
+  show: {
+    controlPanel: true, // show the floating control panel
+    nameTags: true, // show the element name above each registered element
+    elementOverlays: true, // show the hit-slop boundary around each registered element
+    mouseTrajectory: true, // show the predicted mouse trajectory line
+    scrollTrajectory: true, // show the predicted scroll trajectory line
+  },
   isControlPanelDefaultMinimized: false, // optional setting which allows you to minimize the control panel on default
-  showNameTags: true, // optional setting which shows the name of the element
   sortElementList: "visibility", // optional setting for how the elements in the control panel are sorted
   logging: {
     logLocation: "controlPanel", // Where to log the Foresight Events

packages/js.foresight-devtools/src/lit-entry/control-panel/settings-tab/setting-item/setting-item-checkbox.ts

@@ -3,7 +3,9 @@ import { customElement, property } from "lit/decorators.js"
 
 import "./setting-item"
 import { ForesightManager, type ForesightManagerSettings } from "js.foresight"
-import type { DevtoolsSettings } from "../../../../types/types"
+import type { DevtoolsSettings, ShowKey } from "../../../../types/types"
+
+type ShowSettingKey = `show.${ShowKey}`
 @customElement("setting-item-checkbox")
 export class SettingItemCheckbox extends LitElement {
   static styles = [
@@ -56,15 +58,17 @@ export class SettingItemCheckbox extends LitElement {
   @property({ type: Boolean }) isChecked: boolean = false
   @property({ type: String }) header: string = ""
   @property({ type: String }) description: string = ""
-  @property({ type: String }) setting: keyof ForesightManagerSettings | keyof DevtoolsSettings =
-    "enableMousePrediction"
+  @property({ type: String }) setting:
+    | keyof ForesightManagerSettings
+    | keyof DevtoolsSettings
+    | ShowSettingKey = "enableMousePrediction"
 
   private handleCheckboxChange(event: Event): void {
     const target = event.target
     if (target instanceof HTMLInputElement) {
       const targetIsChecked = target.checked
 
-      if (this.setting === "showNameTags") {
+      if (String(this.setting).startsWith("show.")) {
         this.dispatchEvent(
           new CustomEvent("setting-changed", {
             detail: { setting: this.setting, value: targetIsChecked },

packages/js.foresight-devtools/src/lit-entry/control-panel/settings-tab/settings-tab.ts

@@ -8,7 +8,13 @@ import { ForesightManager } from "js.foresight"
 import { css, html, LitElement } from "lit"
 import { customElement, state } from "lit/decorators.js"
 
-import type { Corner, DevtoolsSettings } from "../../../types/types"
+import {
+  SHOW_KEYS,
+  type Corner,
+  type DevtoolsSettings,
+  type ShowKey,
+  type ShowSettings,
+} from "../../../types/types"
 import {
   MAX_POSITION_HISTORY_SIZE,
   MAX_SCROLL_MARGIN,
@@ -36,12 +42,12 @@ import { ForesightDevtools } from "../../foresight-devtools"
 
 // A helper type to represent a change in a Devtools setting
 type UpdatedDevtoolsSetting = {
-  [K in keyof DevtoolsSettings]: {
-    setting: K
-    newValue: DevtoolsSettings[K]
-    oldValue: DevtoolsSettings[K]
+  [K in ShowKey]: {
+    setting: `show.${K}`
+    newValue: ShowSettings[K]
+    oldValue: ShowSettings[K]
   }
-}[keyof DevtoolsSettings]
+}[ShowKey]
 
 @customElement("settings-tab")
 export class SettingsTab extends LitElement {
@@ -168,13 +174,20 @@ export class SettingsTab extends LitElement {
     const currentDevtoolsSettings = ForesightDevtools.instance.devtoolsSettings
     const currentManagerSettings = ForesightManager.instance.getManagerData.globalSettings
 
-    // Shallow copy is sufficient for settings objects
-    this.devtoolsSettings = Object.assign({}, currentDevtoolsSettings)
+    // Shallow copy is sufficient except for `show`, which we deep-copy so
+    // the live and initial snapshots can diverge as the user toggles flags.
+    this.devtoolsSettings = {
+      ...currentDevtoolsSettings,
+      show: { ...currentDevtoolsSettings.show },
+    }
     this.managerSettings = Object.assign({}, currentManagerSettings)
     this.currentCorner = this.getCurrentCorner()
 
     this.initialSettings = {
-      devtools: Object.assign({}, currentDevtoolsSettings),
+      devtools: {
+        ...currentDevtoolsSettings,
+        show: { ...currentDevtoolsSettings.show },
+      },
       manager: Object.assign({}, currentManagerSettings),
     }
   }
@@ -239,14 +252,12 @@ export class SettingsTab extends LitElement {
   private _checkDevtoolsSettingsChanges(
     changes: (UpdatedManagerSetting | UpdatedDevtoolsSetting)[]
   ): void {
-    const devtoolsKeys: (keyof DevtoolsSettings)[] = ["showNameTags"]
-
-    for (const key of devtoolsKeys) {
-      const oldValue = this.initialSettings.devtools[key]
-      const newValue = this.devtoolsSettings[key]
+    for (const key of SHOW_KEYS) {
+      const oldValue = this.initialSettings.devtools.show[key]
+      const newValue = this.devtoolsSettings.show[key]
       if (oldValue !== newValue) {
         changes.push({
-          setting: key,
+          setting: `show.${key}`,
           oldValue,
           newValue,
         } as UpdatedDevtoolsSetting)
@@ -257,14 +268,16 @@ export class SettingsTab extends LitElement {
   private _handleDevtoolsSettingChange(e: CustomEvent<{ setting: string; value: boolean }>): void {
     const { setting, value } = e.detail
 
-    if (setting === "showNameTags") {
-      this.devtoolsSettings = {
-        ...this.devtoolsSettings,
-        showNameTags: value,
-      }
-      ForesightDevtools.instance.alterDevtoolsSettings({ showNameTags: value })
-      this._updateChangedSettings()
+    if (!setting.startsWith("show.")) return
+    const key = setting.slice("show.".length) as ShowKey
+    if (!SHOW_KEYS.includes(key)) return
+
+    this.devtoolsSettings = {
+      ...this.devtoolsSettings,
+      show: { ...this.devtoolsSettings.show, [key]: value },
     }
+    ForesightDevtools.instance.alterDevtoolsSettings({ show: { [key]: value } })
+    this._updateChangedSettings()
   }
 
   private _handleTouchDeviceStrategyChange = (value: string): void => {
@@ -475,10 +488,31 @@ export class SettingsTab extends LitElement {
             <div class="settings-group">
               <h4>Developer Tools</h4>
               <setting-item-checkbox
-                .isChecked=${this.devtoolsSettings.showNameTags}
+                .isChecked=${this.devtoolsSettings.show.nameTags}
                 header="Show Name Tags"
                 description="Display name tags over each registered element in the debugger"
-                setting="showNameTags"
+                setting="show.nameTags"
+                @setting-changed=${this._handleDevtoolsSettingChange}
+              ></setting-item-checkbox>
+              <setting-item-checkbox
+                .isChecked=${this.devtoolsSettings.show.elementOverlays}
+                header="Show Element Overlays"
+                description="Render hit-slop boundary overlays around registered elements. Note: turning this off also hides name tags."
+                setting="show.elementOverlays"
+                @setting-changed=${this._handleDevtoolsSettingChange}
+              ></setting-item-checkbox>
+              <setting-item-checkbox
+                .isChecked=${this.devtoolsSettings.show.mouseTrajectory}
+                header="Show Mouse Trajectory"
+                description="Render the predicted mouse trajectory line"
+                setting="show.mouseTrajectory"
+                @setting-changed=${this._handleDevtoolsSettingChange}
+              ></setting-item-checkbox>
+              <setting-item-checkbox
+                .isChecked=${this.devtoolsSettings.show.scrollTrajectory}
+                header="Show Scroll Trajectory"
+                description="Render the predicted scroll trajectory line"
+                setting="show.scrollTrajectory"
                 @setting-changed=${this._handleDevtoolsSettingChange}
               ></setting-item-checkbox>
               <setting-item

packages/js.foresight-devtools/src/lit-entry/debug-overlay/debug-overlay.ts

@@ -1,5 +1,5 @@
 import { LitElement, css, html } from "lit"
-import { customElement, state } from "lit/decorators.js"
+import { customElement, property, state } from "lit/decorators.js"
 import "./element-overlays"
 import "./mouse-trajectory"
 import "./scroll-trajectory"
@@ -28,6 +28,11 @@ export class DebugOverlay extends LitElement {
   private _strategy: "mouse" | "touch" | "pen" =
     ForesightManager.instance.getManagerData.currentDeviceStrategy
 
+  @property({ type: Boolean }) showElementOverlays = true
+  @property({ type: Boolean }) showMouseTrajectory = true
+  @property({ type: Boolean }) showScrollTrajectory = true
+  @property({ type: Boolean }) showNameTags = true
+
   connectedCallback(): void {
     super.connectedCallback()
     this._abortController = new AbortController()
@@ -53,9 +58,12 @@ export class DebugOverlay extends LitElement {
       <div id="overlay-container">
         ${this._strategy === "mouse"
           ? html`
-              <mouse-trajectory></mouse-trajectory>
-              <scroll-trajectory></scroll-trajectory>
-              <element-overlays></element-overlays>
+              <mouse-trajectory ?hidden=${!this.showMouseTrajectory}></mouse-trajectory>
+              <scroll-trajectory ?hidden=${!this.showScrollTrajectory}></scroll-trajectory>
+              <element-overlays
+                ?hidden=${!this.showElementOverlays}
+                .showNameTags=${this.showNameTags}
+              ></element-overlays>
             `
           : ""}
       </div>

packages/js.foresight-devtools/src/lit-entry/debug-overlay/element-overlays.ts

@@ -1,5 +1,5 @@
-import { LitElement, html, css } from "lit"
-import { customElement, state, query } from "lit/decorators.js"
+import { LitElement, html, css, type PropertyValues } from "lit"
+import { customElement, state, query, property } from "lit/decorators.js"
 import {
   type ForesightElementData,
   type ForesightElement,
@@ -14,7 +14,6 @@ import type {
   ElementRegisteredEvent,
   ElementUnregisteredEvent,
 } from "js.foresight"
-import { ForesightDevtools } from "../foresight-devtools"
 interface ElementOverlay {
   expandedOverlay: HTMLElement
   nameLabel: HTMLElement
@@ -31,6 +30,8 @@ export class ElementOverlays extends LitElement {
   @state() private callbackAnimations: Map<ForesightElement, CallbackAnimation> = new Map()
   @query("#overlays-container") private containerElement!: HTMLElement
 
+  @property({ type: Boolean }) showNameTags = true
+
   static styles = [
     css`
       :host {
@@ -43,6 +44,10 @@ export class ElementOverlays extends LitElement {
         z-index: 9999;
       }
 
+      :host([hidden]) {
+        display: none;
+      }
+
       .expanded-overlay {
         position: absolute;
         will-change: transform, box-shadow;
@@ -165,15 +170,12 @@ export class ElementOverlays extends LitElement {
       },
       { signal }
     )
+  }
 
-    document.addEventListener(
-      "showNameTagsChanged",
-      (e: Event) => {
-        const customEvent = e as CustomEvent<{ showNameTags: boolean }>
-        this.updateNameTagVisibility(customEvent.detail.showNameTags)
-      },
-      { signal }
-    )
+  protected willUpdate(changed: PropertyValues<this>): void {
+    if (changed.has("showNameTags")) {
+      this.updateNameTagVisibility(this.showNameTags)
+    }
   }
 
   private createElementOverlays(elementData: ForesightElementData): ElementOverlay {
@@ -198,7 +200,7 @@ export class ElementOverlays extends LitElement {
     expandedOverlay.style.height = `${expandedHeight}px`
     expandedOverlay.style.transform = `translate3d(${expandedRect.left}px, ${expandedRect.top}px, 0)`
 
-    if (!ForesightDevtools.instance.devtoolsSettings.showNameTags) {
+    if (!this.showNameTags) {
       nameLabel.style.display = "none"
     } else {
       nameLabel.textContent = elementData.name

packages/js.foresight-devtools/src/lit-entry/debug-overlay/mouse-trajectory.ts

@@ -20,6 +20,10 @@ export class MouseTrajectory extends LitElement {
         display: block;
       }
 
+      :host([hidden]) {
+        display: none;
+      }
+
       .trajectory-line {
         display: none;
         position: absolute;