Closes #18006: Dispatch event when toggling color mode & document for plugin use (#20031)

docs/plugins/development/user-interface.md

@@ -0,0 +1,14 @@
+# User Interface
+
+## Light & Dark Mode
+
+The NetBox user interface supports toggling between light and dark versions of the theme. If needed, a plugin can determine the currently active color theme by inspecting `window.localStorage['netbox-color-mode']`, which will indicate either `light` or `dark`.
+
+Additionally, when the color scheme is toggled by the user, a custom event `netbox.colorModeChanged` indicating the new scheme is dispatched. A plugin can listen for this event if needed to react to the change:
+
+```typescript
+window.addEventListener('netbox.colorModeChanged', e => {
+  const customEvent = e as CustomEvent<ColorModeData>;
+  console.log('New color mode:', customEvent.detail.netboxColorMode);
+});
+```

mkdocs.yml

@@ -144,6 +144,7 @@ nav:
             - Search: 'plugins/development/search.md'
             - Event Types: 'plugins/development/event-types.md'
             - Data Backends: 'plugins/development/data-backends.md'
+            - User Interface: 'plugins/development/user-interface.md'
             - REST API: 'plugins/development/rest-api.md'
             - GraphQL API: 'plugins/development/graphql-api.md'
             - Background Jobs: 'plugins/development/background-jobs.md'

netbox/project-static/src/colorMode.ts

@@ -43,6 +43,11 @@ function updateElements(targetMode: ColorMode): void {
 export function setColorMode(mode: ColorMode): void {
   storeColorMode(mode);
   updateElements(mode);
+  window.dispatchEvent(
+    new CustomEvent<ColorModeData>('netbox.colorModeChanged', {
+      detail: { netboxColorMode: mode },
+    }),
+  );
 }
 
 /**

netbox/project-static/src/global.d.ts

@@ -79,3 +79,6 @@ type FormControls = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
 
 type ColorMode = 'light' | 'dark';
 type ColorModePreference = ColorMode | 'none';
+type ColorModeData = {
+  netboxColorMode: ColorMode;
+};