From 2ed3dac5e5a6f0e0abcbd19839d44e49d86b7085 Mon Sep 17 00:00:00 2001 From: Thomas Date: Mon, 20 Jul 2026 15:28:27 -0400 Subject: [PATCH 1/2] fix(KNO-14012): inject guide toolbar styles at runtime The guide toolbar rendered unstyled unless the consuming app imported @knocklabs/react/dist/index.css, which apps rendering only custom guide components have no reason to do. The toolbar now injects its compiled styles (telegraph tokens + components + toolbar keyframes, via a ?inline css import) into the document head when it becomes visible, so it works without an explicit CSS import. dist/index.css is unchanged. Co-Authored-By: Claude Fable 5 --- .changeset/toolbar-self-injects-styles.md | 7 +++ .../guide/components/Toolbar/V2/V2.tsx | 3 + .../components/Toolbar/useToolbarStyles.ts | 21 +++++++ .../react/test/guide/Toolbar/V2/V2.test.tsx | 56 +++++++++++++++++++ .../guide/Toolbar/useToolbarStyles.test.ts | 44 +++++++++++++++ 5 files changed, 131 insertions(+) create mode 100644 .changeset/toolbar-self-injects-styles.md create mode 100644 packages/react/src/modules/guide/components/Toolbar/useToolbarStyles.ts create mode 100644 packages/react/test/guide/Toolbar/V2/V2.test.tsx create mode 100644 packages/react/test/guide/Toolbar/useToolbarStyles.test.ts diff --git a/.changeset/toolbar-self-injects-styles.md b/.changeset/toolbar-self-injects-styles.md new file mode 100644 index 000000000..383511c6c --- /dev/null +++ b/.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. diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx index 9065f76c3..43c5ec47a 100644 --- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx +++ b/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]); diff --git a/packages/react/src/modules/guide/components/Toolbar/useToolbarStyles.ts b/packages/react/src/modules/guide/components/Toolbar/useToolbarStyles.ts new file mode 100644 index 000000000..15dcfe618 --- /dev/null +++ b/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]); +}; diff --git a/packages/react/test/guide/Toolbar/V2/V2.test.tsx b/packages/react/test/guide/Toolbar/V2/V2.test.tsx new file mode 100644 index 000000000..2ea3e017e --- /dev/null +++ b/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(); + + expect(getStyleElement()).not.toBeNull(); + expect(getStyleElement()?.parentElement).toBe(document.head); + }); + + test("does not inject toolbar styles without the toolbar url param", () => { + render(); + + expect(getStyleElement()).toBeNull(); + }); +}); diff --git a/packages/react/test/guide/Toolbar/useToolbarStyles.test.ts b/packages/react/test/guide/Toolbar/useToolbarStyles.test.ts new file mode 100644 index 000000000..b654ed1e8 --- /dev/null +++ b/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); + }); +}); From 58615257eb89d9084e4d39c3ca7d93e35eb4bc36 Mon Sep 17 00:00:00 2001 From: Thomas Date: Wed, 22 Jul 2026 16:21:02 -0400 Subject: [PATCH 2/2] bot review feedback, name inline css differently --- packages/react/vite.config.mts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/react/vite.config.mts b/packages/react/vite.config.mts index 866958eb4..625e8a938 100644 --- a/packages/react/vite.config.mts +++ b/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"}`; }, },