fix(KNO-14012): inject guide toolbar styles at runtime

.changeset/toolbar-self-injects-styles.md

@@ -0,0 +1,7 @@
+---
+"@knocklabs/react": patch
+---
+
+fix(KNO-14012): guide toolbar no longer requires importing `@knocklabs/react/dist/index.css`
+
+The guide toolbar previously rendered unstyled (or with frankenstein styling) unless the consuming app imported `@knocklabs/react/dist/index.css`. Apps that only render custom guide components have no reason to import that stylesheet, so the toolbar broke for them. The toolbar now injects its compiled styles into the document head at runtime when it becomes visible, making it plug and play without an explicit CSS import. When `dist/index.css` is imported anyway, the injected rules are identical duplicates and have no effect.

packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx

@@ -19,6 +19,7 @@ import React from "react";
 import { KnockButton } from "../KnockButton";
 import { TOOLBAR_Z_INDEX } from "../shared";
 import "../styles.css";
+import { useToolbarStyles } from "../useToolbarStyles";
 
 import { FocusChin } from "./FocusChin";
 import { GuideContextDetails } from "./GuideContextDetails";
@@ -90,6 +91,8 @@ export const V2 = ({ readyToTarget, listenForUpdates }: Props) => {
     string | undefined
   >();
 
+  useToolbarStyles(Boolean(runConfig?.isVisible));
+
   React.useEffect(() => {
     setExpandedGuideRowKey(undefined);
   }, [displayOption]);

packages/react/src/modules/guide/components/Toolbar/useToolbarStyles.ts

@@ -0,0 +1,21 @@
+import React from "react";
+
+import toolbarStyles from "./styles.css?inline";
+
+const STYLE_ELEMENT_ID = "knock-guide-toolbar-styles";
+
+// The toolbar's styles are bundled into dist/index.css, but consumers who only
+// render custom guide components have no reason to import that stylesheet.
+// Inject the toolbar's compiled styles at runtime when it becomes visible, so
+// the toolbar works without an explicit CSS import. When dist/index.css is
+// imported anyway, the injected rules are identical duplicates and harmless.
+export const useToolbarStyles = (enabled: boolean) => {
+  React.useEffect(() => {
+    if (!enabled || document.getElementById(STYLE_ELEMENT_ID)) return;
+
+    const styleElement = document.createElement("style");
+    styleElement.id = STYLE_ELEMENT_ID;
+    styleElement.textContent = toolbarStyles;
+    document.head.appendChild(styleElement);
+  }, [enabled]);
+};

packages/react/test/guide/Toolbar/V2/V2.test.tsx

@@ -0,0 +1,56 @@
+import { render } from "@testing-library/react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { V2 } from "../../../../src/modules/guide/components/Toolbar/V2/V2";
+
+vi.mock("@knocklabs/react-core", async () => {
+  const actual = await vi.importActual("@knocklabs/react-core");
+  return {
+    ...actual,
+    useGuideContext: () => ({
+      client: {
+        store: { state: {} },
+        setDebug: vi.fn(),
+        unsetDebug: vi.fn(),
+      },
+    }),
+  };
+});
+
+vi.mock(
+  "../../../../src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore",
+  async () => {
+    const actual = await vi.importActual(
+      "../../../../src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore",
+    );
+    return {
+      ...actual,
+      useInspectGuideClientStore: () => null,
+    };
+  },
+);
+
+const getStyleElement = () =>
+  document.getElementById("knock-guide-toolbar-styles");
+
+afterEach(() => {
+  getStyleElement()?.remove();
+  window.history.replaceState({}, "", "/");
+});
+
+describe("Toolbar V2", () => {
+  test("injects toolbar styles when launched via the toolbar url param", () => {
+    window.history.replaceState({}, "", "/?knock_guide_toolbar=true");
+
+    render(<V2 readyToTarget={false} listenForUpdates={false} />);
+
+    expect(getStyleElement()).not.toBeNull();
+    expect(getStyleElement()?.parentElement).toBe(document.head);
+  });
+
+  test("does not inject toolbar styles without the toolbar url param", () => {
+    render(<V2 readyToTarget={false} listenForUpdates={false} />);
+
+    expect(getStyleElement()).toBeNull();
+  });
+});

packages/react/test/guide/Toolbar/useToolbarStyles.test.ts

@@ -0,0 +1,44 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, test } from "vitest";
+
+import { useToolbarStyles } from "../../../src/modules/guide/components/Toolbar/useToolbarStyles";
+
+const getStyleElement = () =>
+  document.getElementById("knock-guide-toolbar-styles");
+
+afterEach(() => {
+  getStyleElement()?.remove();
+});
+
+describe("useToolbarStyles", () => {
+  test("does not inject styles when disabled", () => {
+    renderHook(() => useToolbarStyles(false));
+    expect(getStyleElement()).toBeNull();
+  });
+
+  test("injects a style element into the document head when enabled", () => {
+    renderHook(() => useToolbarStyles(true));
+    const styleElement = getStyleElement();
+    expect(styleElement).not.toBeNull();
+    expect(styleElement?.parentElement).toBe(document.head);
+  });
+
+  test("injects styles once it becomes enabled", () => {
+    const { rerender } = renderHook(
+      ({ enabled }) => useToolbarStyles(enabled),
+      { initialProps: { enabled: false } },
+    );
+    expect(getStyleElement()).toBeNull();
+
+    rerender({ enabled: true });
+    expect(getStyleElement()).not.toBeNull();
+  });
+
+  test("injects only one style element across multiple instances", () => {
+    renderHook(() => useToolbarStyles(true));
+    renderHook(() => useToolbarStyles(true));
+    expect(
+      document.querySelectorAll("#knock-guide-toolbar-styles"),
+    ).toHaveLength(1);
+  });
+});

packages/react/vite.config.mts

@@ -71,7 +71,13 @@ export default defineConfig(({ mode }) => {
             }
             return assetInfo.name;
           },
-          entryFileNames: () => {
+          entryFileNames: (chunkInfo) => {
+            // Chunks from `?inline` CSS imports carry the compiled style
+            // string as code, so they must not be named like the empty .css
+            // proxy chunks that get deleted and stripped below.
+            if (chunkInfo.facadeModuleId?.endsWith("?inline")) {
+              return `[name].inline.${CJS ? "js" : "mjs"}`;
+            }
             return `[name].${CJS ? "js" : "mjs"}`;
           },
         },