doc(overlay): Add JSDoc to Overlay options (#180)

packages/overlay/src/index.tsx

@@ -3,14 +3,13 @@ import ReactDOM from 'react-dom/client';
 import fontStyles from '@fontsource/raleway/index.css?inline';
 
 import App from './App.tsx';
-import { DEFAULT_ANCHOR, type Anchor } from './components/Trigger.tsx';
+import { DEFAULT_ANCHOR } from './components/Trigger.tsx';
 import globalStyles from './index.css?inline';
-import type { Integration } from './integrations/integration.ts';
 import { initIntegrations } from './integrations/integration.ts';
 import { default as sentry } from './integrations/sentry/index.ts';
 import { getSpotlightEventTarget } from './lib/eventTarget.ts';
 import { activateLogger, log } from './lib/logger.ts';
-import { WindowWithSpotlight } from './types.ts';
+import { SpotlightOverlayOptions, WindowWithSpotlight } from './types.ts';
 
 export { default as console } from './integrations/console/index.ts';
 export { default as sentry } from './integrations/sentry/index.ts';
@@ -72,17 +71,7 @@ export async function init({
   anchor = DEFAULT_ANCHOR,
   debug = false,
   integrations,
-}: {
-  integrations?: Integration[];
-  fullScreen?: boolean;
-  defaultEventId?: string;
-  sidecarUrl?: string;
-  showTriggerButton?: boolean;
-  injectImmediately?: boolean;
-  sidecar?: string;
-  anchor?: Anchor;
-  debug?: boolean;
-} = {}) {
+}: SpotlightOverlayOptions = {}) {
   if (typeof document === 'undefined') return;
 
   // We only want to intialize and inject spotlight once. If it's already

packages/overlay/src/types.ts

@@ -1,3 +1,86 @@
+import { Anchor } from './components/Trigger';
+import { Integration } from './integrations/integration';
+
+export type SpotlightOverlayOptions = {
+  /**
+   * Array of Spotlight integrations to enable when the Overlay initializes.
+   *
+   * Usage:
+   * ```js
+   * integrations: [sentry(), myIntegration()]
+   * ```
+   *
+   * @default [sentry()]
+   */
+  integrations?: Integration[];
+
+  /**
+   * TODO: Rename
+   *
+   * If set to `true`, the Spotlight overlay Window will be opened immediately
+   * after calling the init.
+   *
+   * @default false - only the Spotlight button is visible.
+   */
+  fullScreen?: boolean;
+
+  /**
+   * Set a URL to a custom Spotlight Sidecar instance. The Spotlight overlay
+   * will use this URL instead of the default URL to connect to the sidecar
+   * and to listen to incoming events.
+   *
+   * @default "http://localhost:8969/stream"
+   */
+  sidecarUrl?: string;
+
+  /**
+   * If set to `false`, the Spotlight button will not be visible.
+   * This is useful if Spotlight is integrated into an existing UI,
+   * such as the Astro Dev Overlay.
+   *
+   * @default true
+   */
+  showTriggerButton?: boolean;
+
+  /**
+   * By default, Spotlight waits until the host page is loaded before injecting the
+   * Spotlight Overlay. Depending on how and when the init call is made, the load
+   * event might have already happened.
+   *
+   * Setting injectImmediately to `true`, will inject the UI synchronously with the
+   * `init` call, regardless of the host page's load state.
+   *
+   * Use this option, if you called `init()` but the Spotlight Overlay UI is not visible.
+   *
+   * @default false
+   */
+  injectImmediately?: boolean;
+
+  /**
+   * Set this option to define where the spotlight button should be anchored.
+   *
+   * @default "bottomRight"
+   */
+  anchor?: Anchor;
+
+  /**
+   * If set to `true`, the Spotlight overlay will log additional debug messages to the console.
+   *
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * TODO: Remove? No longer needed with new approach
+   */
+  defaultEventId?: string;
+
+  /**
+   * TODO: Remove! duplicate of `sidecarUrl`
+   */
+  sidecar?: string;
+};
+
 export type TriggerButtonCount = {
   general: number;
   severe: number;