🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(web): banner users who opted out of the v4 UI (#19608)
marliessophiea0f5dd522b37
diff --git a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsxindex 4c420d1172..be4260f214 100644--- a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx+++ b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx@@ -67,6 +67,10 @@ import {usePaymentBanner,} from "@/src/features/payment-banner";import { useTopBannerHeight } from "@/src/features/top-banner";+import {+ LegacyUiBanner,+ useLegacyUiBannerVisible,+} from "@/src/features/v4-migration/LegacyUiBanner";const DISMISSED_SIDEBAR_NOTIFICATIONS_KEY = "dismissed-sidebar-notifications";@@ -144,14 +148,16 @@ export function AuthenticatedLayout({const showV4Migration = useV4UpgradeUiFlag();const { organization: currentOrganization, project: currentProject } =useQueryProjectOrOrganization();+ const routerProjectId =+ typeof router.query.projectId === "string"+ ? router.query.projectId+ : undefined;+ const showLegacyUiBanner = useLegacyUiBannerVisible(routerProjectId);const customerDataWarning = getCustomerDataWarning({email: user.email,isAdmin: user.admin === true,isLangfuseCloud,- projectId:- typeof router.query.projectId === "string"- ? router.query.projectId- : null,+ projectId: routerProjectId ?? null,organizationId:typeof router.query.organizationId === "string"? router.query.organizationId@@ -316,6 +322,7 @@ export function AuthenticatedLayout({{customerDataWarning && (<CustomerDataWarningBannerView {...customerDataWarning} />)}+ {showLegacyUiBanner && <LegacyUiBanner />}{paymentBanner && (<PaymentBannerVieworganizationName={paymentBanner.organizationName}@@ -342,11 +349,7 @@ export function AuthenticatedLayout({user={sidebarUser}userMenuItems={userMenuItems}isLangfuseCloud={isLangfuseCloud}- routerProjectId={- typeof router.query.projectId === "string"- ? router.query.projectId- : undefined- }+ routerProjectId={routerProjectId}/>{/* `min-w-0`, not a `100vw`-derived width: viewport units ignorescrollbars, and a definite width also floors `min-width:diff --git a/web/src/features/events/components/V4SidebarToggle.tsx b/web/src/features/events/components/V4SidebarToggle.tsxindex c3d0e98cf3..ea89598b46 100644--- a/web/src/features/events/components/V4SidebarToggle.tsx+++ b/web/src/features/events/components/V4SidebarToggle.tsx@@ -8,161 +8,17 @@ import {TooltipTrigger,} from "@/src/components/ui/tooltip";import { useReadPath } from "@/src/features/events/hooks/useReadPath";-import { setReadPath } from "@/src/features/events/actions/setReadPath";-import { usePendingReadPath } from "@/src/features/events/stores/readPathToggleStore";+import { useV4PreviewToggle } from "@/src/features/events/hooks/useV4PreviewToggle";import { V4IntroDialog } from "@/src/features/events/components/V4IntroDialog";-import { usePostHogClientCapture } from "@/src/features/posthog-analytics";-import {- getV4PreviewDisabledRedirect,- getV4PreviewEnabledRedirect,-} from "@/src/features/events/lib/v4PreviewRedirect";-import { api } from "@/src/utils/api";import { ZapIcon } from "@langfuse/icons";-import { useId, useState } from "react";+import { useId } from "react";import { useRouter } from "next/router";-import { useSession } from "next-auth/react";-import {- singleRunToExperimentsUrl,- toExperimentsResultsUrl,-} from "@/src/features/experiments/utils/experimentUrlTranslation";import {V4_PREVIEW_LABEL,V4_PREVIEW_DESCRIPTION,} from "@/src/features/events/lib/v4PreviewLabel";-function asSingleValue(value: string | string[] | undefined) {- return Array.isArray(value) ? value[0] : value;-}--function asArrayValue(value: string | string[] | undefined) {- if (!value) return [];- return Array.isArray(value) ? value : [value];-}--const INTRO_DIALOG_SEEN_KEY = "v4-beta-intro-dialog-seen";--// Shared behavior for every V4 Preview toggle surface: session-backed state,-// intro dialog on first enable, and the datasets/experiments URL translation-// that keeps the current page valid after switching. `source` distinguishes-// the surfaces in the shared v4_beta_toggled event. The commit itself is the-// shared `setReadPath` workflow; only the intro dialog lives here.-function useV4PreviewToggle(source: "sidebar" | "migration_panel") {- const router = useRouter();- const { isV4 } = useReadPath();- const pendingReadPath = usePendingReadPath();- const { update: updateSession } = useSession();- const mutation = api.userAccount.setV4BetaEnabled.useMutation();- const capture = usePostHogClientCapture();-- const [showIntroDialog, setShowIntroDialog] = useState(false);- const [pendingAfterToggle, setPendingAfterToggle] = useState<- (() => Promise<unknown> | void) | undefined- >();-- // The pending intent wins while a toggle is committing, so the switch shows- // the value the user just chose — and snaps back if the commit fails.- const isChecked = pendingReadPath ? pendingReadPath === "v4" : isV4;- const isLoading = pendingReadPath !== null;-- // Returns the navigation promise so the pending intent (disabled switch)- // holds until the redirect lands.- const redirectAfterToggle = (enabled: boolean): Promise<unknown> | void => {- const projectId = asSingleValue(router.query.projectId);- if (!projectId) return;-- if (!enabled) {- const redirect = getV4PreviewDisabledRedirect(router.pathname, projectId);- if (redirect) return router.push(redirect);- return;- }-- const evaluatorRedirect = getV4PreviewEnabledRedirect(- router.pathname,- projectId,- );- if (evaluatorRedirect) {- return router.push(evaluatorRedirect);- }-- if (- router.pathname ===- "/project/[projectId]/datasets/[datasetId]/runs/[runId]"- ) {- const runId = asSingleValue(router.query.runId);- if (runId) {- return router.push(singleRunToExperimentsUrl(projectId, runId));- }- return;- }-- if (- router.pathname === "/project/[projectId]/datasets/[datasetId]/compare" ||- router.pathname ===- "/project/[projectId]/datasets/[datasetId]/compare/charts"- ) {- const runIds = asArrayValue(router.query.runs);- if (runIds.length > 0) {- return router.push(toExperimentsResultsUrl(projectId, runIds));- }- }- };-- const commitToggle = (- enabled: boolean,- afterToggle?: () => Promise<unknown> | void,- ) => {- setReadPath(enabled ? "v4" : "v3", {- setV4BetaEnabled: (input) => mutation.mutateAsync(input),- updateSession,- onSuccess: () => {- capture("sidebar:v4_beta_toggled", { enabled, source });- return afterToggle ? afterToggle() : redirectAfterToggle(enabled);- },- });- };-- // afterToggle, when given, replaces the default same-page URL translation- // and runs only after the toggle actually committed (mutation + session- // update done, intro dialog confirmed rather than dismissed).- const handleToggle = (- enabled: boolean,- afterToggle?: () => Promise<unknown> | void,- ) => {- if (- enabled &&- typeof window !== "undefined" &&- !localStorage.getItem(INTRO_DIALOG_SEEN_KEY)- ) {- setPendingAfterToggle(() => afterToggle);- setShowIntroDialog(true);- return;- }- commitToggle(enabled, afterToggle);- };-- const confirmIntroDialog = () => {- localStorage.setItem(INTRO_DIALOG_SEEN_KEY, "true");- setShowIntroDialog(false);- commitToggle(true, pendingAfterToggle);- setPendingAfterToggle(undefined);- };-- const dismissIntroDialog = () => {- setShowIntroDialog(false);- setPendingAfterToggle(undefined);- };-- return {- isChecked,- isLoading,- handleToggle,- showIntroDialog,- confirmIntroDialog,- dismissIntroDialog,- };-}-export function V4SidebarToggle() {const { canToggleV4 } = useReadPath();// A locked toggle is only shown in the sidebar for one-way recovery.diff --git a/web/src/features/events/hooks/useV4PreviewToggle.ts b/web/src/features/events/hooks/useV4PreviewToggle.tsnew file mode 100644index 0000000000..df73dfada5--- /dev/null+++ b/web/src/features/events/hooks/useV4PreviewToggle.ts@@ -0,0 +1,157 @@+import { useState } from "react";+import { useRouter } from "next/router";+import { useSession } from "next-auth/react";++import { setReadPath } from "@/src/features/events/actions/setReadPath";+import { useReadPath } from "@/src/features/events/hooks/useReadPath";+import {+ getV4PreviewDisabledRedirect,+ getV4PreviewEnabledRedirect,+} from "@/src/features/events/lib/v4PreviewRedirect";+import { usePendingReadPath } from "@/src/features/events/stores/readPathToggleStore";+import {+ singleRunToExperimentsUrl,+ toExperimentsResultsUrl,+} from "@/src/features/experiments/utils/experimentUrlTranslation";+import { usePostHogClientCapture } from "@/src/features/posthog-analytics";+import { api } from "@/src/utils/api";++function asSingleValue(value: string | string[] | undefined) {+ return Array.isArray(value) ? value[0] : value;+}++function asArrayValue(value: string | string[] | undefined) {+ if (!value) return [];+ return Array.isArray(value) ? value : [value];+}++const INTRO_DIALOG_SEEN_KEY = "v4-beta-intro-dialog-seen";++export type V4PreviewToggleSource =+ | "sidebar"+ | "migration_panel"+ | "legacy_ui_banner";++/**+ * Shared behavior for every V4 Preview toggle surface: session-backed state,+ * intro dialog on first enable, and the datasets/experiments URL translation+ * that keeps the current page valid after switching. `source` distinguishes+ * the surfaces in the shared v4_beta_toggled event. The commit itself is the+ * shared `setReadPath` workflow; only the intro dialog lives with each+ * surface.+ */+export function useV4PreviewToggle(source: V4PreviewToggleSource) {+ const router = useRouter();+ const { isV4 } = useReadPath();+ const pendingReadPath = usePendingReadPath();+ const { update: updateSession } = useSession();+ const mutation = api.userAccount.setV4BetaEnabled.useMutation();+ const capture = usePostHogClientCapture();++ const [showIntroDialog, setShowIntroDialog] = useState(false);+ const [pendingAfterToggle, setPendingAfterToggle] = useState<+ (() => Promise<unknown> | void) | undefined+ >();++ // The pending intent wins while a toggle is committing, so the switch shows+ // the value the user just chose — and snaps back if the commit fails.+ const isChecked = pendingReadPath ? pendingReadPath === "v4" : isV4;+ const isLoading = pendingReadPath !== null;++ // Returns the navigation promise so the pending intent (disabled switch)+ // holds until the redirect lands.+ const redirectAfterToggle = (enabled: boolean): Promise<unknown> | void => {+ const projectId = asSingleValue(router.query.projectId);+ if (!projectId) return;++ if (!enabled) {+ const redirect = getV4PreviewDisabledRedirect(router.pathname, projectId);+ if (redirect) return router.push(redirect);+ return;+ }++ const evaluatorRedirect = getV4PreviewEnabledRedirect(+ router.pathname,+ projectId,+ );+ if (evaluatorRedirect) {+ return router.push(evaluatorRedirect);+ }++ if (+ router.pathname ===+ "/project/[projectId]/datasets/[datasetId]/runs/[runId]"+ ) {+ const runId = asSingleValue(router.query.runId);+ if (runId) {+ return router.push(singleRunToExperimentsUrl(projectId, runId));+ }+ return;+ }++ if (+ router.pathname === "/project/[projectId]/datasets/[datasetId]/compare" ||+ router.pathname ===+ "/project/[projectId]/datasets/[datasetId]/compare/charts"+ ) {+ const runIds = asArrayValue(router.query.runs);+ if (runIds.length > 0) {+ return router.push(toExperimentsResultsUrl(projectId, runIds));+ }+ }+ };++ const commitToggle = (+ enabled: boolean,+ afterToggle?: () => Promise<unknown> | void,+ ) => {+ setReadPath(enabled ? "v4" : "v3", {+ setV4BetaEnabled: (input) => mutation.mutateAsync(input),+ updateSession,+ onSuccess: () => {+ capture("sidebar:v4_beta_toggled", { enabled, source });+ return afterToggle ? afterToggle() : redirectAfterToggle(enabled);+ },+ });+ };++ // afterToggle, when given, replaces the default same-page URL translation+ // and runs only after the toggle actually committed (mutation + session+ // update done, intro dialog confirmed rather than dismissed).+ const handleToggle = (+ enabled: boolean,+ afterToggle?: () => Promise<unknown> | void,+ ) => {+ if (+ enabled &&+ typeof window !== "undefined" &&+ !localStorage.getItem(INTRO_DIALOG_SEEN_KEY)+ ) {+ setPendingAfterToggle(() => afterToggle);+ setShowIntroDialog(true);+ return;+ }+ commitToggle(enabled, afterToggle);+ };++ const confirmIntroDialog = () => {+ localStorage.setItem(INTRO_DIALOG_SEEN_KEY, "true");+ setShowIntroDialog(false);+ commitToggle(true, pendingAfterToggle);+ setPendingAfterToggle(undefined);+ };++ const dismissIntroDialog = () => {+ setShowIntroDialog(false);+ setPendingAfterToggle(undefined);+ };++ return {+ isChecked,+ isLoading,+ handleToggle,+ showIntroDialog,+ confirmIntroDialog,+ dismissIntroDialog,+ };+}diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.tsindex d8543548d7..f15118a030 100644--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts@@ -518,6 +518,8 @@ const events = {"migrate_evals_with_agent_clicked","overview_banner_status_clicked","overview_banner_docs_clicked",+ // Opt-out users on the legacy-UI top strip → migration status page.+ "legacy_ui_banner_status_clicked","panel_docs_link_clicked","create_project_keys_clicked","panel_opened",diff --git a/web/src/features/v4-migration/LegacyUiBanner.tsx b/web/src/features/v4-migration/LegacyUiBanner.tsxnew file mode 100644index 0000000000..f4450e6857--- /dev/null+++ b/web/src/features/v4-migration/LegacyUiBanner.tsx@@ -0,0 +1,58 @@+import { V4IntroDialog } from "@/src/features/events/components/V4IntroDialog";+import { useReadPath } from "@/src/features/events/hooks/useReadPath";+import { useV4PreviewToggle } from "@/src/features/events/hooks/useV4PreviewToggle";+import { usePostHogClientCapture } from "@/src/features/posthog-analytics";+import { LegacyUiBannerView } from "@/src/features/v4-migration/LegacyUiBannerView";+import { useIsForceV3ExperienceSettled } from "@/src/features/v4-migration/useForceV3Experience";+import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";+import { useHasV4MigrationDeadline } from "@/src/features/v4-migration/V4MigrationContent";++/**+ * Whether the legacy-UI migration strip should render. Only for users who+ * are on the legacy read path *and* whose deployment/project still exposes+ * the v4 migration UI (so enable + `/v4-migration` are real actions). That+ * gate also excludes force-v3 projects, and waits until the force-v3 query+ * has settled so those tenants do not flash the strip on first paint.+ */+export function useLegacyUiBannerVisible(projectId?: string): boolean {+ const { isV3Legacy, isResolved } = useReadPath();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(projectId);+ const forceV3Settled = useIsForceV3ExperienceSettled(projectId);+ return isResolved && isV3Legacy && forceV3Settled && v4UpgradeUiEnabled;+}++/**+ * Top-of-app strip for users who disabled the v4 UI. Parent gates with+ * `useLegacyUiBannerVisible`. Primary CTA runs the same enable path as the+ * sidebar / migration-page toggle so the banner disappears as soon as the+ * session flips to v4.+ */+export function LegacyUiBanner() {+ const hasDeadline = useHasV4MigrationDeadline();+ const capture = usePostHogClientCapture();+ const {+ isLoading,+ handleToggle,+ showIntroDialog,+ confirmIntroDialog,+ dismissIntroDialog,+ } = useV4PreviewToggle("legacy_ui_banner");++ return (+ <>+ <LegacyUiBannerView+ hasDeadline={hasDeadline}+ isSwitching={isLoading}+ onSwitchToLatestUi={() => handleToggle(true)}+ onMigrationStatusClick={() =>+ capture("v4_migration:legacy_ui_banner_status_clicked")+ }+ />+ <V4IntroDialog+ open={showIntroDialog}+ onConfirm={confirmIntroDialog}+ onDismiss={dismissIntroDialog}+ />+ </>+ );+}diff --git a/web/src/features/v4-migration/LegacyUiBannerView.stories.tsx b/web/src/features/v4-migration/LegacyUiBannerView.stories.tsxnew file mode 100644index 0000000000..9309fed5fe--- /dev/null+++ b/web/src/features/v4-migration/LegacyUiBannerView.stories.tsx@@ -0,0 +1,48 @@+import { fn } from "storybook/test";++import preview from "../../../.storybook/preview";+import { LegacyUiBannerView } from "./LegacyUiBannerView";++const meta = preview.meta({+ component: LegacyUiBannerView,+ args: {+ hasDeadline: true,+ isSwitching: false,+ onSwitchToLatestUi: fn(),+ onMigrationStatusClick: fn(),+ },+});++/**+ * Cloud: retirement date included. Blue preview-banner tokens; primary+ * enables v4; secondary is an underlined link to the migration guide.+ */+export const WithDeadline = meta.story({});++/** Self-hosted / no Cloud deadline — date clause omitted. */+export const WithoutDeadline = meta.story({+ args: { hasDeadline: false },+});++/** Primary CTA while the enable mutation / session refresh is in flight. */+export const Switching = meta.story({+ args: { isSwitching: true },+});++/**+ * Phone width: actions drop under the message (PaymentBanner pattern) so the+ * copy keeps the full row instead of squeezing beside non-wrapping buttons.+ */+export const Narrow = meta.story({+ globals: { viewport: { value: "legacy-ui-banner-phone", isRotated: false } },+ parameters: {+ viewport: {+ options: {+ "legacy-ui-banner-phone": {+ name: "Phone",+ styles: { width: "390px", height: "844px" },+ },+ },+ },+ },+});diff --git a/web/src/features/v4-migration/LegacyUiBannerView.tsx b/web/src/features/v4-migration/LegacyUiBannerView.tsxnew file mode 100644index 0000000000..ac61a8133d--- /dev/null+++ b/web/src/features/v4-migration/LegacyUiBannerView.tsx@@ -0,0 +1,58 @@+import Link from "next/link";++import { Button } from "@/src/components/design-system/Button/Button";+import { V4_MIGRATION_DEADLINE } from "@/src/features/v4-migration/V4MigrationContent";++export type LegacyUiBannerViewProps = {+ /** When true, include the Cloud retirement date in the message. */+ hasDeadline: boolean;+ /** True while the enable-v4 mutation / session refresh is in flight. */+ isSwitching: boolean;+ onSwitchToLatestUi: () => void;+ /** Fires on the secondary link click (analytics). */+ onMigrationStatusClick?: () => void;+};++/**+ * Full-width top strip for users who opted back to the legacy (v3) UI.+ * Uses the blue preview-banner tokens. Enable CTA is DS Button outline/sm+ * (bordered gray, quietest box variant). Below `sm` the actions drop to their+ * own row (PaymentBanner pattern). Not dismissible.+ */+export function LegacyUiBannerView({+ hasDeadline,+ isSwitching,+ onSwitchToLatestUi,+ onMigrationStatusClick,+}: LegacyUiBannerViewProps) {+ return (+ <div+ className="border-preview-banner-border bg-preview-banner text-preview-banner-foreground flex w-full flex-col gap-1 border-b px-4 py-1.5 sm:flex-row sm:items-center sm:justify-between sm:gap-3 sm:py-1"+ role="status"+ >+ <p className="min-w-0 flex-1 text-sm wrap-break-word">+ <span className="font-bold">You are viewing legacy UI.</span>{" "}+ {hasDeadline+ ? `It will be retired on ${V4_MIGRATION_DEADLINE}.`+ : "It will be retired."}+ </p>+ <div className="flex shrink-0 items-center gap-3 self-end sm:self-auto">+ <Button+ size="sm"+ variant="outline"+ text="Switch to latest UI"+ loading={isSwitching}+ disabled={isSwitching}+ onClick={onSwitchToLatestUi}+ />+ <Link+ href="/v4-migration"+ onClick={onMigrationStatusClick}+ className="text-preview-banner-link hover:text-preview-banner-link-hover text-sm underline underline-offset-2"+ >+ View migration guide+ </Link>+ </div>+ </div>+ );+}diff --git a/web/src/features/v4-migration/useForceV3Experience.ts b/web/src/features/v4-migration/useForceV3Experience.tsindex 6dc11d5e66..3f4a6794a3 100644--- a/web/src/features/v4-migration/useForceV3Experience.ts+++ b/web/src/features/v4-migration/useForceV3Experience.ts@@ -1,13 +1,7 @@import { api } from "@/src/utils/api";-/**- * Whether the given project is forced onto the v3 experience via- * LANGFUSE_FORCE_V3_EXPERIENCE. The value is static per deployment, so it is- * cached for the session. Returns false while loading or when no project id is- * available (safe default: not forced).- */-export function useForceV3Experience(projectId?: string): boolean {- const forceV3 = api.v4Transition.forceV3Experience.useQuery(+function useForceV3ExperienceQuery(projectId?: string) {+ return api.v4Transition.forceV3Experience.useQuery({ projectId: projectId ?? "" },{// Callers that only need the value behind another gate (e.g. the v4@@ -17,5 +11,29 @@ export function useForceV3Experience(projectId?: string): boolean {staleTime: Infinity,},);+}++/**+ * Whether the given project is forced onto the v3 experience via+ * LANGFUSE_FORCE_V3_EXPERIENCE. The value is static per deployment, so it is+ * cached for the session. Returns false while loading or when no project id is+ * available (safe default: not forced).+ */+export function useForceV3Experience(projectId?: string): boolean {+ const forceV3 = useForceV3ExperienceQuery(projectId);return forceV3.data ?? false;}++/**+ * True once the force-v3 query has a definitive answer for this project, or+ * when there is no project id (nothing to wait for). Use before showing+ * surfaces that would flash for force-v3 tenants while the default is+ * "not forced".+ */+export function useIsForceV3ExperienceSettled(projectId?: string): boolean {+ const forceV3 = useForceV3ExperienceQuery(projectId);+ if (!projectId) {+ return true;+ }+ return forceV3.isFetched;+}