Posthog webview experiments

src/app/helpers/posthog.ts

@@ -0,0 +1,60 @@
+import React from 'react';
+
+export type FlagValue = string | boolean | undefined;
+
+type PostHogClient = {
+    getFeatureFlag: (key: string) => FlagValue;
+    onFeatureFlags: (cb: () => void) => void;
+    capture: (event: string, properties?: Record<string, unknown>) => void;
+};
+
+/** PostHog is loaded by GTM; it may not be present yet (pre-consent). */
+function getPostHog(): PostHogClient | undefined {
+    return (window as unknown as {posthog?: PostHogClient}).posthog;
+}
+
+/** Read an experiment/feature-flag variant. Reading it auto-fires the
+ *  `$feature_flag_called` exposure event in PostHog. */
+export function getExperimentVariant(flagKey: string): FlagValue {
+    return getPostHog()?.getFeatureFlag(flagKey);
+}
+
+/** Fire a goal/auxiliary event. Safe no-op when PostHog is absent. */
+export function captureEvent(event: string, properties?: Record<string, unknown>) {
+    getPostHog()?.capture(event, properties);
+}
+
+/** Hook form: returns the variant, re-rendering once PostHog's flags resolve. */
+export function useExperiment(flagKey: string): FlagValue {
+    const [variant, setVariant] = React.useState<FlagValue>(() =>
+        getExperimentVariant(flagKey)
+    );
+
+    React.useEffect(() => {
+        const ph = getPostHog();
+
+        if (!ph) {
+            return;
+        }
+        ph.onFeatureFlags(() => setVariant(ph.getFeatureFlag(flagKey)));
+    }, [flagKey]);
+
+    return variant;
+}
+
+/** Subscribe to PostHog flag resolution and return a synchronous variant
+ *  reader. Re-renders the caller once flags load, so callers can read any
+ *  number of flags (e.g. while filtering a list) without breaking hooks rules. */
+export function useExperimentReader(): (flag: string) => FlagValue {
+    const [, forceRender] = React.useReducer((n: number) => n + 1, 0);
+
+    React.useEffect(() => {
+        const ph = getPostHog();
+
+        if (!ph) {
+            return;
+        }
+        ph.onFeatureFlags(() => forceRender());
+    }, []);
+    return getExperimentVariant;
+}

src/app/layouts/default/header/menus/main-menu/main-menu.tsx

@@ -8,6 +8,13 @@ import {
 import {FormattedMessage} from 'react-intl';
 import {useLocation} from 'react-router-dom';
 import {useDataFromSlug} from '~/helpers/page-data-utils';
+import {useExperimentReader, useExperiment, type FlagValue} from '~/helpers/posthog';
+import {
+    NAV_PRODUCTS_LABEL_FLAG,
+    NAV_K12_ITEM_FLAG,
+    isNodeVisible,
+    dropdownLabel
+} from './nav-experiments';
 import Dropdown, {MenuItem} from './dropdown/dropdown';
 import LoginMenu from './login-menu/login-menu';
 import GiveButton from '../give-button/give-button';
@@ -18,52 +25,74 @@ type MenuItemData =
     | {
           name: string;
           menu: MenuItemData[];
+          key?: string;
+          feature_flag?: string;
+          flag_value?: string;
       }
     | {
           label: string;
           partial_url: string;
+          key?: string;
+          feature_flag?: string;
+          flag_value?: string;
       }
     | object;
 
-function DropdownOrMenuItem({item}: {item: MenuItemData}) {
+function DropdownOrMenuItem({
+    item,
+    getVariant
+}: {
+    item: MenuItemData;
+    getVariant: (flag: string) => FlagValue;
+}) {
     if (!('name' in item) && !('label' in item)) {
         return null;
     }
+    if (!isNodeVisible(item, getVariant)) {
+        return null;
+    }
     if ('menu' in item) {
+        const label = dropdownLabel(item, getVariant(NAV_PRODUCTS_LABEL_FLAG));
+
         return (
-            <Dropdown
-                label={item.name!}
-                navAnalytics={`Main Menu (${item.name})`}
-            >
-                <MenusFromStructure structure={item.menu} />
+            <Dropdown label={label} navAnalytics={`Main Menu (${item.name})`}>
+                <MenusFromStructure structure={item.menu} getVariant={getVariant} />
             </Dropdown>
         );
     }
 
     return <MenuItem label={item.label} url={item.partial_url} />;
 }
 
-function MenusFromStructure({structure}: {structure: MenuItemData[]}) {
+function MenusFromStructure({
+    structure,
+    getVariant
+}: {
+    structure: MenuItemData[];
+    getVariant: (flag: string) => FlagValue;
+}) {
     return (
         <React.Fragment>
             {structure.map((item, index) => (
                 <DropdownOrMenuItem
                     key={'label' in item ? item.label : index}
                     item={item}
+                    getVariant={getVariant}
                 />
             ))}
         </React.Fragment>
     );
 }
 
 function MenusFromCMS() {
+    const getVariant = useExperimentReader();
     const structure = useDataFromSlug('oxmenus') as MenuItemData[] | undefined;
 
     if (!structure) {
         return null;
     }
 
-    return <MenusFromStructure structure={structure} />;
+    return <MenusFromStructure structure={structure} getVariant={getVariant} />;
 }
 
 function K12MenuItem() {
@@ -73,6 +102,7 @@ function K12MenuItem() {
 function SubjectsMenu() {
     const categories = useSubjectCategoryContext();
     const {language} = useLanguageContext();
+    const k12TopLevel = Boolean(useExperiment(NAV_K12_ITEM_FLAG));
     // This will have to be revisited if/when we implement more languages
     const otherLocale = ['en', 'es'].filter((la) => la !== language)[0];
     const {pathname} = useLocation();
@@ -110,7 +140,7 @@ function SubjectsMenu() {
                     </LanguageSelectorWrapper>
                 </React.Fragment>
             )}
-            {language === 'en' ? (
+            {language === 'en' && !k12TopLevel ? (
                 <React.Fragment>
                     <hr />
                     <K12MenuItem />

src/app/layouts/default/header/menus/main-menu/nav-experiments.ts

@@ -0,0 +1,53 @@
+import type {FlagValue} from '~/helpers/posthog';
+
+export const NAV_PRODUCTS_LABEL_FLAG = 'nav-products-label';
+export const NAV_K12_ITEM_FLAG = 'nav-k12-item';
+
+/** Stable CMS `key` of the dropdown under the Products/Tools A/B.
+ *  CONFIRM this matches the `key` set on that dropdown in Wagtail. */
+export const PRODUCTS_DROPDOWN_KEY = 'products-dropdown';
+const TOOLS_LABEL = 'Tools';
+
+/** Flag metadata any CMS menu node may carry (snake_case, matching the
+ *  oxmenus API — same casing as `partial_url`). */
+export type FlagAwareNode = {
+    key?: string;
+    feature_flag?: string;
+    flag_value?: string;
+};
+
+/** Generic visibility gate from a node's optional flag metadata.
+ *  - no feature_flag     → always visible
+ *  - flag_value provided → visible iff String(variant) === flag_value
+ *  - flag_value blank    → visible iff the flag is truthy
+ *  Nodes gated ON by a flag appear once PostHog's flags resolve (fine for
+ *  additive items); author controls/defaults WITHOUT a feature_flag so they
+ *  render immediately. */
+export function isNodeVisible(
+    node: FlagAwareNode,
+    getVariant: (flag: string) => FlagValue
+): boolean {
+    const flag = node.feature_flag;
+
+    if (!flag) {
+        return true;
+    }
+    const variant = getVariant(flag);
+
+    if (node.flag_value) {
+        return String(variant) === node.flag_value;
+    }
+    return Boolean(variant);
+}
+
+/** A/B label swap for the Products dropdown, keyed by stable `key`
+ *  (not the display label, so editors can rename freely). */
+export function dropdownLabel(
+    node: {key?: string; name?: string},
+    productsVariant: FlagValue
+): string {
+    if (node.key === PRODUCTS_DROPDOWN_KEY && productsVariant === 'tools') {
+        return TOOLS_LABEL;
+    }
+    return node.name ?? '';
+}

test/src/helpers/posthog.test.tsx

@@ -0,0 +1,93 @@
+import React from 'react';
+import {render, screen, act} from '@testing-library/preact';
+import {
+    getExperimentVariant,
+    captureEvent,
+    useExperiment,
+    useExperimentReader
+} from '~/helpers/posthog';
+
+type FakePostHog = {
+    getFeatureFlag: jest.Mock;
+    onFeatureFlags: jest.Mock;
+    capture: jest.Mock;
+};
+
+function installPostHog(overrides: Partial<FakePostHog> = {}) {
+    const ph: FakePostHog = {
+        getFeatureFlag: jest.fn(),
+        onFeatureFlags: jest.fn(),
+        capture: jest.fn(),
+        ...overrides
+    };
+    (window as unknown as {posthog?: FakePostHog}).posthog = ph;
+    return ph;
+}
+
+afterEach(() => {
+    delete (window as unknown as {posthog?: unknown}).posthog;
+});
+
+describe('posthog helper', () => {
+    it('getExperimentVariant returns undefined when posthog is absent', () => {
+        expect(getExperimentVariant('nav-products-label')).toBeUndefined();
+    });
+
+    it('getExperimentVariant reads the flag', () => {
+        installPostHog({getFeatureFlag: jest.fn().mockReturnValue('tools')});
+        expect(getExperimentVariant('nav-products-label')).toBe('tools');
+    });
+
+    it('captureEvent no-ops without posthog', () => {
+        expect(() => captureEvent('thing_clicked')).not.toThrow();
+    });
+
+    it('captureEvent forwards to posthog', () => {
+        const ph = installPostHog();
+        captureEvent('thing_clicked', {a: 1});
+        expect(ph.capture).toHaveBeenCalledWith('thing_clicked', {a: 1});
+    });
+
+    it('useExperiment returns control then updates when flags resolve', async () => {
+        const ph = installPostHog({
+            getFeatureFlag: jest
+                .fn()
+                .mockReturnValueOnce(undefined)
+                .mockReturnValue('tools')
+        });
+
+        function Probe() {
+            const variant = useExperiment('nav-products-label');
+            return <span>{String(variant)}</span>;
+        }
+
+        render(<Probe />);
+        screen.getByText('undefined');
+
+        const cb = ph.onFeatureFlags.mock.calls[0][0] as () => void;
+        act(() => cb());
+        await screen.findByText('tools');
+    });
+});
+
+describe('useExperimentReader', () => {
+    it('returns a reader and re-renders when flags resolve', async () => {
+        const ph = {
+            getFeatureFlag: jest.fn().mockReturnValueOnce(undefined).mockReturnValue('on'),
+            onFeatureFlags: jest.fn(),
+            capture: jest.fn()
+        };
+        (window as unknown as {posthog?: typeof ph}).posthog = ph;
+
+        function Probe() {
+            const getVariant = useExperimentReader();
+            return <span>{String(getVariant('f'))}</span>;
+        }
+        const {findByText, getByText} = render(<Probe />);
+        getByText('undefined');
+        const cb = ph.onFeatureFlags.mock.calls[0][0] as () => void;
+        act(() => cb());
+        await findByText('on');
+        delete (window as unknown as {posthog?: unknown}).posthog;
+    });
+});