Merge pull request #206 from temisan0x/feature/191-frontend-feature-flags-rollout-control

feat(frontend): introduce feature flags for incremental UI rollout control

Author: Junirezz

frontend/.env.example

@@ -1,3 +1,4 @@
 VITE_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
 VITE_STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
 VITE_VAULT_CONTRACT_ID=
+VITE_FF_ANALYTICS_PAGE=true

frontend/FEATURE_FLAGS.md

@@ -0,0 +1,37 @@
+# Feature Flags (Vite)
+
+This app uses environment-based flags to toggle frontend features safely. We use a **fail-closed** approach: if a variable is not exactly `"true"`, the feature is treated as disabled.
+
+> [!IMPORTANT]
+> Vite injects `import.meta.env` values at build/dev-server startup time.
+> Restart the dev server after changing `.env` values so flag updates take effect.
+
+## Registered Flags
+
+| Key | Env Var | Notes |
+| :--- | :--- | :--- |
+| `ANALYTICS_PAGE` | `VITE_FF_ANALYTICS_PAGE` | Gates the analytics route until rollout is approved. |
+
+## How to Add a Flag
+
+1. Register the key in `FLAG_KEYS` in `src/context/FeatureFlagContext.tsx`.
+2. Add the env variable to `.env.example` (`VITE_FF_<FLAG_KEY>`).
+3. Use `useFeatureFlag` (evaluation utility) or `<FeatureGate>` where needed.
+
+## Usage Patterns
+
+### 1) Component wrapper (preferred for full sections/routes)
+
+```tsx
+<FeatureGate flag="ANALYTICS_PAGE" fallback={<Skeleton />}>
+  <AnalyticsDashboard />
+</FeatureGate>
+```
+
+### 2) Evaluation utility hook (preferred for inline conditions)
+
+```tsx
+const analyticsEnabled = useFeatureFlag("ANALYTICS_PAGE");
+
+return analyticsEnabled ? <AnalyticsDashboard /> : <EmptyState />;
+```

frontend/src/App.tsx

@@ -15,6 +15,8 @@ import "./index.css";
 import { KeyboardShortcutProvider } from "./context/KeyboardShortcutContext";
 import Navbar from "./components/Navbar";
 import ShortcutHelpModal from "./components/ShortcutHelpModal";
+import { FeatureGate } from "./components/FeatureGate";
+import { FeatureFlagProvider } from "./context/FeatureFlagContext";
 import "./index.css";
 
 import * as Sentry from "@sentry/react";
@@ -174,6 +176,14 @@ function AppContent() {
                   />
                 }
               />
+              <Route
+                path="/analytics"
+                element={
+                  <FeatureGate flag="ANALYTICS_PAGE">
+                    <Analytics />
+                  </FeatureGate>
+                }
+              />
               <Route path="/analytics" element={<Analytics />} />
               <Route path="/settings" element={<div>Settings Page</div>} />
               <Route path="/ui-kit" element={<UIPreview />} />
@@ -190,13 +200,15 @@ function AppContent() {
 function App() {
   return (
     <Sentry.ErrorBoundary fallback={<AppErrorFallback />} showDialog>
-      <ThemeProvider>
-        <VaultProvider>
-          <Router>
-            <AppContent />
-          </Router>
-        </VaultProvider>
-      </ThemeProvider>
+      <FeatureFlagProvider>
+        <ThemeProvider>
+          <VaultProvider>
+            <Router>
+              <AppContent />
+            </Router>
+          </VaultProvider>
+        </ThemeProvider>
+      </FeatureFlagProvider>
     </Sentry.ErrorBoundary>
   );
 }

frontend/src/components/FeatureGate.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+import { ShieldOff } from "lucide-react";
+import { useFeatureFlag } from "../context/FeatureFlagContext";
+import type { FeatureFlagKey } from "../context/FeatureFlagContext";
+
+interface FeatureGateProps {
+  flag: FeatureFlagKey;
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+}
+const DefaultFallback: React.FC = () => (
+  <div className="glass-panel feature-gate-fallback" role="status" aria-live="polite">
+    <div className="feature-gate-icon" aria-hidden="true">
+      <ShieldOff size={18} />
+    </div>
+    <span className="tag cyan feature-gate-tag">Controlled Rollout</span>
+    <div className="text-gradient feature-gate-title">
+      Feature Unavailable
+    </div>
+    <div className="feature-gate-description">
+      This section is currently disabled for this environment. It will be
+      enabled as rollout progresses.
+    </div>
+  </div>
+);
+
+export const FeatureGate: React.FC<FeatureGateProps> = ({ flag, children, fallback }) => {
+  const enabled = useFeatureFlag(flag);
+  if (!enabled) return <>{fallback ?? <DefaultFallback />}</>;
+  return <>{children}</>;
+};

frontend/src/context/FeatureFlagContext.tsx

@@ -0,0 +1,32 @@
+import React, { createContext, useContext } from "react";
+const FLAG_KEYS = ["ANALYTICS_PAGE"] as const;
+export type FeatureFlagKey = (typeof FLAG_KEYS)[number];
+
+type FeatureFlagMap = Record<FeatureFlagKey, boolean>;
+
+const resolveFlags = (): FeatureFlagMap => {
+  return FLAG_KEYS.reduce((acc, key) => {
+    acc[key] = import.meta.env[`VITE_FF_${key}`] === "true";
+    return acc;
+  }, {} as FeatureFlagMap);
+}
+
+const FeatureFlagContext = createContext<FeatureFlagMap | null>(null);
+
+export const FeatureFlagProvider: React.FC<{ children: React.ReactNode }> = ({
+  children,
+}) => {
+  const flags = resolveFlags();
+  return (
+    <FeatureFlagContext.Provider value={flags}>
+      {children}
+    </FeatureFlagContext.Provider>
+  );
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export const useFeatureFlag = (flag: FeatureFlagKey): boolean => {
+  const ctx = useContext(FeatureFlagContext);
+  if (!ctx) throw new Error("useFeatureFlag must be used within FeatureFlagProvider");
+  return ctx[flag];
+}

frontend/src/index.css

@@ -508,6 +508,49 @@ button {
   border: 1px solid rgba(0, 240, 255, 0.3);
 }
 
+/* Feature Gate */
+.feature-gate-fallback {
+  max-width: 720px;
+  margin: 0 auto;
+  padding: 40px 44px;
+  text-align: center;
+  background:
+    radial-gradient(circle at 85% 10%, var(--bg-gradient-2), transparent 45%),
+    radial-gradient(circle at 10% 100%, var(--bg-gradient-1), transparent 45%),
+    var(--bg-surface);
+}
+
+.feature-gate-icon {
+  width: 40px;
+  height: 40px;
+  margin: 0 auto 12px;
+  border-radius: 9999px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--accent-cyan);
+  background: var(--accent-cyan-dim);
+  border: 1px solid rgba(0, 240, 255, 0.28);
+}
+
+.feature-gate-tag {
+  margin-bottom: 12px;
+}
+
+.feature-gate-title {
+  font-size: clamp(var(--text-2xl), 4vw, var(--text-3xl));
+  margin-bottom: 10px;
+  line-height: var(--leading-tight);
+}
+
+.feature-gate-description {
+  color: var(--text-secondary);
+  font-size: var(--text-base);
+  line-height: var(--leading-relaxed);
+  max-width: 56ch;
+  margin: 0 auto;
+}
+
 /* Base button styles */
 .btn {
   display: inline-flex;
@@ -1187,6 +1230,18 @@ button {
 
 /* Mobile responsiveness for PageHeader */
 @media (max-width: 768px) {
+  .feature-gate-fallback {
+    padding: 28px 20px;
+  }
+
+  .feature-gate-title {
+    font-size: var(--text-2xl);
+  }
+
+  .feature-gate-description {
+    font-size: var(--text-sm);
+  }
+
   .page-header {
     text-align: left !important;
   }
@@ -1260,4 +1315,3 @@ button {
   background: var(--border-glass);
   margin: 16px 0;
 }
-

frontend/src/tests/feature-flags.test.tsx

@@ -0,0 +1,63 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { FeatureGate } from "../components/FeatureGate";
+import {
+  FeatureFlagProvider,
+  useFeatureFlag,
+} from "../context/FeatureFlagContext";
+
+function FlagProbe() {
+  const enabled = useFeatureFlag("ANALYTICS_PAGE");
+  return <div data-testid="flag-value">{String(enabled)}</div>;
+}
+
+describe("feature flags", () => {
+  beforeEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("fails closed for non-true values", () => {
+    vi.stubEnv("VITE_FF_ANALYTICS_PAGE", "false");
+
+    render(
+      <FeatureFlagProvider>
+        <FlagProbe />
+      </FeatureFlagProvider>,
+    );
+
+    expect(screen.getByTestId("flag-value")).toHaveTextContent("false");
+  });
+
+  it("renders fallback when a feature is disabled", () => {
+    vi.stubEnv("VITE_FF_ANALYTICS_PAGE", "false");
+
+    render(
+      <FeatureFlagProvider>
+        <FeatureGate
+          flag="ANALYTICS_PAGE"
+          fallback={<div>analytics fallback</div>}
+        >
+          <div>analytics enabled</div>
+        </FeatureGate>
+      </FeatureFlagProvider>,
+    );
+
+    expect(screen.queryByText("analytics enabled")).not.toBeInTheDocument();
+    expect(screen.getByText("analytics fallback")).toBeInTheDocument();
+  });
+
+  it("renders gated content when the feature is enabled", () => {
+    vi.stubEnv("VITE_FF_ANALYTICS_PAGE", "true");
+
+    render(
+      <FeatureFlagProvider>
+        <FeatureGate flag="ANALYTICS_PAGE">
+          <div>analytics enabled</div>
+        </FeatureGate>
+      </FeatureFlagProvider>,
+    );
+
+    expect(screen.getByText("analytics enabled")).toBeInTheDocument();
+    expect(screen.queryByText("Feature Unavailable")).not.toBeInTheDocument();
+  });
+});