base

plane-src/apps/web/core/lib/app-rail/context.tsx

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import { createContext, useContext } from "react";
+import type { IAppRailVisibilityContext } from "./types";
+
+/**
+ * Context for app-rail visibility control
+ * Provides access to app rail enabled state, collapse state, and toggle function
+ */
+export const AppRailVisibilityContext = createContext<IAppRailVisibilityContext | undefined>(undefined);
+
+/**
+ * Hook to consume the AppRailVisibilityContext
+ * Must be used within an AppRailVisibilityProvider
+ *
+ * @returns The app rail visibility context
+ * @throws Error if used outside of AppRailVisibilityProvider
+ */
+export const useAppRailVisibility = (): IAppRailVisibilityContext => {
+  const context = useContext(AppRailVisibilityContext);
+  if (context === undefined) {
+    throw new Error("useAppRailVisibility must be used within AppRailVisibilityProvider");
+  }
+  return context;
+};

plane-src/apps/web/core/lib/app-rail/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+export * from "./context";
+export * from "./provider";
+export * from "./types";

plane-src/apps/web/core/lib/app-rail/provider.tsx

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import React, { useCallback, useMemo } from "react";
+import { observer } from "mobx-react";
+import { useParams } from "next/navigation";
+import useLocalStorage from "@/hooks/use-local-storage";
+import { AppRailVisibilityContext } from "./context";
+import type { IAppRailVisibilityContext } from "./types";
+
+interface AppRailVisibilityProviderProps {
+  children: React.ReactNode;
+  isEnabled?: boolean; // Allow override, default false
+}
+
+/**
+ * AppRailVisibilityProvider - manages app rail visibility state
+ * Base provider that accepts isEnabled as a prop
+ */
+export const AppRailVisibilityProvider = observer(function AppRailVisibilityProvider({
+  children,
+  isEnabled = false,
+}: AppRailVisibilityProviderProps) {
+  const { workspaceSlug } = useParams();
+
+  // User preference from localStorage
+  const { storedValue: isCollapsed, setValue: setIsCollapsed } = useLocalStorage<boolean>(
+    `APP_RAIL_${workspaceSlug}`,
+    false // Default: not collapsed (app rail visible)
+  );
+
+  const toggleAppRail = useCallback(() => {
+    setIsCollapsed(!isCollapsed);
+  }, [isCollapsed, setIsCollapsed]);
+
+  // Compute final visibility: enabled and not collapsed
+  const shouldRenderAppRail = isEnabled && !isCollapsed;
+
+  const value: IAppRailVisibilityContext = useMemo(
+    () => ({
+      isEnabled,
+      isCollapsed: isCollapsed ?? false,
+      shouldRenderAppRail,
+      toggleAppRail,
+    }),
+    [isEnabled, isCollapsed, shouldRenderAppRail, toggleAppRail]
+  );
+
+  return <AppRailVisibilityContext.Provider value={value}>{children}</AppRailVisibilityContext.Provider>;
+});

plane-src/apps/web/core/lib/app-rail/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+/**
+ * Type definitions for app-rail visibility context
+ */
+
+export interface IAppRailVisibilityContext {
+  /**
+   * Whether the app rail is enabled
+   */
+  isEnabled: boolean;
+
+  /**
+   * Whether the app rail is collapsed (user preference from localStorage)
+   */
+  isCollapsed: boolean;
+
+  /**
+   * Computed property: whether the app rail should actually render
+   * True only if isEnabled && !isCollapsed
+   */
+  shouldRenderAppRail: boolean;
+
+  /**
+   * Toggle the collapse state of the app rail
+   */
+  toggleAppRail: () => void;
+}

plane-src/apps/web/core/lib/b-progress/AppProgressBar.tsx

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import { useEffect, useRef } from "react";
+import { BProgress } from "@bprogress/core";
+import { useNavigation } from "react-router";
+import "@bprogress/core/css";
+
+/**
+ * Progress bar configuration options
+ */
+interface ProgressConfig {
+  /** Whether to show the loading spinner */
+  showSpinner: boolean;
+  /** Minimum progress percentage (0-1) */
+  minimum: number;
+  /** Animation speed in milliseconds */
+  speed: number;
+  /** Auto-increment speed in milliseconds */
+  trickleSpeed: number;
+  /** CSS easing function */
+  easing: string;
+  /** Enable auto-increment */
+  trickle: boolean;
+  /** Delay before showing progress bar in milliseconds */
+  delay: number;
+  /** Whether to disable the progress bar */
+  isDisabled?: boolean;
+}
+
+/**
+ * Configuration for the progress bar
+ */
+const PROGRESS_CONFIG: Readonly<ProgressConfig> = {
+  showSpinner: false,
+  minimum: 0.1,
+  speed: 400,
+  trickleSpeed: 800,
+  easing: "ease",
+  trickle: true,
+  delay: 0,
+} as const;
+
+/**
+ * Navigation Progress Bar Component
+ *
+ * Automatically displays a progress bar at the top of the page during React Router navigation.
+ * Integrates with React Router's useNavigation hook to monitor route changes.
+ *
+ * Note: Progress bar is disabled in production builds.
+ *
+ * @returns null - This component doesn't render any visible elements
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <>
+ *       <AppProgressBar />
+ *       <Outlet />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export default function AppProgressBar(): null {
+  const navigation = useNavigation();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const startedRef = useRef<boolean>(false);
+
+  // Initialize BProgress once on mount
+  useEffect(() => {
+    // Skip initialization in production builds
+    if (PROGRESS_CONFIG.isDisabled) {
+      return;
+    }
+
+    // Configure BProgress with our settings
+    BProgress.configure({
+      showSpinner: PROGRESS_CONFIG.showSpinner,
+      minimum: PROGRESS_CONFIG.minimum,
+      speed: PROGRESS_CONFIG.speed,
+      trickleSpeed: PROGRESS_CONFIG.trickleSpeed,
+      easing: PROGRESS_CONFIG.easing,
+      trickle: PROGRESS_CONFIG.trickle,
+    });
+
+    // Render the progress bar element in the DOM
+    BProgress.render(true);
+
+    // Cleanup on unmount
+    return () => {
+      if (BProgress.isStarted()) {
+        BProgress.done();
+      }
+    };
+  }, []);
+
+  // Handle navigation state changes
+  useEffect(() => {
+    // Skip navigation tracking in production builds
+    if (PROGRESS_CONFIG.isDisabled) {
+      return;
+    }
+
+    if (navigation.state === "idle") {
+      // Navigation complete - clear any pending timer
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+
+      // Complete progress if it was started
+      if (startedRef.current) {
+        BProgress.done();
+        startedRef.current = false;
+      }
+    } else {
+      // Navigation in progress (loading or submitting)
+      // Only start if not already started and no timer pending
+      if (timerRef.current === null && !startedRef.current) {
+        timerRef.current = setTimeout((): void => {
+          if (!BProgress.isStarted()) {
+            BProgress.start();
+            startedRef.current = true;
+          }
+          timerRef.current = null;
+        }, PROGRESS_CONFIG.delay);
+      }
+    }
+
+    return () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, [navigation.state]);
+
+  return null;
+}

plane-src/apps/web/core/lib/local-storage.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import { isEmpty } from "lodash-es";
+
+export const storage = {
+  set: (key: string, value: object | string | boolean): void => {
+    if (typeof window === undefined || typeof window === "undefined" || !key || !value) return undefined;
+    const tempValue: string | undefined = value
+      ? ["string", "boolean"].includes(typeof value)
+        ? value.toString()
+        : isEmpty(value)
+          ? undefined
+          : JSON.stringify(value)
+      : undefined;
+    if (!tempValue) return undefined;
+    window.localStorage.setItem(key, tempValue);
+  },
+
+  get: (key: string): string | undefined => {
+    if (typeof window === undefined || typeof window === "undefined") return undefined;
+    const item = window.localStorage.getItem(key);
+    return item ? item : undefined;
+  },
+
+  remove: (key: string): void => {
+    if (typeof window === undefined || typeof window === "undefined" || !key) return undefined;
+    window.localStorage.removeItem(key);
+  },
+};

plane-src/apps/web/core/lib/polyfills/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+if (typeof window !== "undefined" && window) {
+  // Add request callback polyfill to browser in case it does not exist
+  window.requestIdleCallback =
+    window.requestIdleCallback ??
+    function (cb) {
+      const start = Date.now();
+      return setTimeout(function () {
+        cb({
+          didTimeout: false,
+          timeRemaining: function () {
+            return Math.max(0, 50 - (Date.now() - start));
+          },
+        });
+      }, 1);
+    };
+
+  window.cancelIdleCallback =
+    window.cancelIdleCallback ??
+    function (id) {
+      clearTimeout(id);
+    };
+}
+
+export {};

plane-src/apps/web/core/lib/store-context.tsx

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import type { ReactElement } from "react";
+import { createContext } from "react";
+// plane web store
+import { RootStore } from "@/plane-web/store/root.store";
+
+export let rootStore = new RootStore();
+
+export const StoreContext = createContext<RootStore>(rootStore);
+
+const initializeStore = () => {
+  const newRootStore = rootStore ?? new RootStore();
+  if (typeof window === "undefined") return newRootStore;
+  if (!rootStore) rootStore = newRootStore;
+  return newRootStore;
+};
+
+export const store = initializeStore();
+
+export function StoreProvider({ children }: { children: ReactElement }) {
+  return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
+}

plane-src/apps/web/core/lib/wrappers/authentication-wrapper.tsx

@@ -0,0 +1,148 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import type { ReactNode } from "react";
+import { observer } from "mobx-react";
+import { useSearchParams, usePathname } from "next/navigation";
+import useSWR from "swr";
+// components
+import { LogoSpinner } from "@/components/common/logo-spinner";
+// helpers
+import { EPageTypes } from "@/helpers/authentication.helper";
+// hooks
+import { useWorkspace } from "@/hooks/store/use-workspace";
+import { useUser, useUserProfile, useUserSettings } from "@/hooks/store/user";
+import { useAppRouter } from "@/hooks/use-app-router";
+
+type TPageType = EPageTypes;
+
+type TAuthenticationWrapper = {
+  children: ReactNode;
+  pageType?: TPageType;
+};
+
+const isValidURL = (url: string): boolean => {
+  const disallowedSchemes = /^(https?|ftp):\/\//i;
+  return !disallowedSchemes.test(url);
+};
+
+export const AuthenticationWrapper = observer(function AuthenticationWrapper(props: TAuthenticationWrapper) {
+  const pathname = usePathname();
+  const router = useAppRouter();
+  const searchParams = useSearchParams();
+  const nextPath = searchParams.get("next_path");
+  // props
+  const { children, pageType = EPageTypes.AUTHENTICATED } = props;
+  // hooks
+  const { isLoading: isUserLoading, data: currentUser, fetchCurrentUser } = useUser();
+  const { data: currentUserProfile } = useUserProfile();
+  const { data: currentUserSettings } = useUserSettings();
+  const { loader: workspacesLoader, workspaces } = useWorkspace();
+
+  const { isLoading: isUserSWRLoading } = useSWR("USER_INFORMATION", async () => await fetchCurrentUser(), {
+    revalidateOnFocus: false,
+    shouldRetryOnError: false,
+  });
+
+  const isUserOnboard =
+    currentUserProfile?.is_onboarded ||
+    (currentUserProfile?.onboarding_step?.profile_complete &&
+      currentUserProfile?.onboarding_step?.workspace_create &&
+      currentUserProfile?.onboarding_step?.workspace_invite &&
+      currentUserProfile?.onboarding_step?.workspace_join) ||
+    false;
+
+  const getWorkspaceRedirectionUrl = (): string => {
+    let redirectionRoute = "/create-workspace";
+
+    // validating the nextPath from the router query
+    if (nextPath && isValidURL(nextPath.toString())) {
+      redirectionRoute = nextPath.toString();
+      return redirectionRoute;
+    }
+
+    // validate the last and fallback workspace_slug
+    const currentWorkspaceSlug =
+      currentUserSettings?.workspace?.last_workspace_slug || currentUserSettings?.workspace?.fallback_workspace_slug;
+
+    // validate the current workspace_slug is available in the user's workspace list
+    const isCurrentWorkspaceValid = Object.values(workspaces || {}).findIndex(
+      (workspace) => workspace.slug === currentWorkspaceSlug
+    );
+
+    if (isCurrentWorkspaceValid >= 0) redirectionRoute = `/${currentWorkspaceSlug}`;
+    else {
+      const firstWorkspaceSlug = Object.values(workspaces || {})?.[0]?.slug;
+      if (firstWorkspaceSlug) redirectionRoute = `/${firstWorkspaceSlug}`;
+    }
+
+    return redirectionRoute;
+  };
+
+  if ((isUserSWRLoading || isUserLoading || workspacesLoader) && !currentUser?.id)
+    return (
+      <div className="relative flex h-screen w-full items-center justify-center">
+        <LogoSpinner />
+      </div>
+    );
+
+  if (pageType === EPageTypes.PUBLIC) return <>{children}</>;
+
+  if (pageType === EPageTypes.NON_AUTHENTICATED) {
+    if (!currentUser?.id) return <>{children}</>;
+    else {
+      if (currentUserProfile?.id && isUserOnboard) {
+        const currentRedirectRoute = getWorkspaceRedirectionUrl();
+        router.push(currentRedirectRoute);
+        return <></>;
+      } else {
+        router.push("/onboarding");
+        return <></>;
+      }
+    }
+  }
+
+  if (pageType === EPageTypes.ONBOARDING) {
+    if (!currentUser?.id) {
+      router.push(`/${pathname ? `?next_path=${pathname}` : ``}`);
+      return <></>;
+    } else {
+      if (currentUser && currentUserProfile?.id && isUserOnboard) {
+        const currentRedirectRoute = getWorkspaceRedirectionUrl();
+        router.replace(currentRedirectRoute);
+        return <></>;
+      } else return <>{children}</>;
+    }
+  }
+
+  if (pageType === EPageTypes.SET_PASSWORD) {
+    if (!currentUser?.id) {
+      router.push(`/${pathname ? `?next_path=${pathname}` : ``}`);
+      return <></>;
+    } else {
+      if (currentUser && !currentUser?.is_password_autoset && currentUserProfile?.id && isUserOnboard) {
+        const currentRedirectRoute = getWorkspaceRedirectionUrl();
+        router.push(currentRedirectRoute);
+        return <></>;
+      } else return <>{children}</>;
+    }
+  }
+
+  if (pageType === EPageTypes.AUTHENTICATED) {
+    if (currentUser?.id) {
+      if (currentUserProfile && currentUserProfile?.id && isUserOnboard) return <>{children}</>;
+      else {
+        router.push(`/onboarding`);
+        return <></>;
+      }
+    } else {
+      router.push(`/${pathname ? `?next_path=${pathname}` : ``}`);
+      return <></>;
+    }
+  }
+
+  return <>{children}</>;
+});

plane-src/apps/web/core/lib/wrappers/instance-wrapper.tsx

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import type { ReactNode } from "react";
+import { observer } from "mobx-react";
+import useSWR from "swr";
+// components
+import { LogoSpinner } from "@/components/common/logo-spinner";
+import { InstanceNotReady, MaintenanceView } from "@/components/instance";
+// hooks
+import { useInstance } from "@/hooks/store/use-instance";
+
+type TInstanceWrapper = {
+  children: ReactNode;
+};
+
+const InstanceWrapper = observer(function InstanceWrapper(props: TInstanceWrapper) {
+  const { children } = props;
+  // store
+  const { isLoading, instance, error, fetchInstanceInfo } = useInstance();
+
+  const { isLoading: isInstanceSWRLoading, error: instanceSWRError } = useSWR(
+    "INSTANCE_INFORMATION",
+    async () => await fetchInstanceInfo(),
+    { revalidateOnFocus: false }
+  );
+
+  // loading state
+  if ((isLoading || isInstanceSWRLoading) && !instance)
+    return (
+      <div className="relative flex h-screen w-full items-center justify-center">
+        <LogoSpinner />
+      </div>
+    );
+
+  if (instanceSWRError) return <MaintenanceView />;
+
+  // something went wrong while in the request
+  if (error && error?.status === "error") return <>{children}</>;
+
+  // instance is not ready and setup is not done
+  if (instance?.is_setup_done === false) return <InstanceNotReady />;
+
+  return <>{children}</>;
+});
+
+export default InstanceWrapper;

plane-src/apps/web/core/lib/wrappers/store-wrapper.tsx

@@ -0,0 +1,123 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import type { ReactNode } from "react";
+import { useEffect, useRef } from "react";
+import { observer } from "mobx-react";
+import { useParams } from "next/navigation";
+import { useTheme } from "next-themes";
+import type { TLanguage } from "@plane/i18n";
+import { DEFAULT_LANGUAGE, useTranslation } from "@plane/i18n";
+// helpers
+import { applyCustomTheme, clearCustomTheme } from "@plane/utils";
+// hooks
+import { useAppTheme } from "@/hooks/store/use-app-theme";
+import { useRouterParams } from "@/hooks/store/use-router-params";
+import { useUserProfile } from "@/hooks/store/user";
+
+type TStoreWrapper = {
+  children: ReactNode;
+};
+
+function StoreWrapper(props: TStoreWrapper) {
+  const { children } = props;
+  // theme
+  const { setTheme } = useTheme();
+  // router
+  const params = useParams();
+  // store hooks
+  const { setQuery } = useRouterParams();
+  const { sidebarCollapsed, toggleSidebar } = useAppTheme();
+  const { data: userProfile } = useUserProfile();
+  const { changeLanguage } = useTranslation();
+
+  // Track if we've initialized theme from server (one-time only)
+  const hasInitializedThemeRef = useRef(false);
+  // Track current user to reset on logout/login
+  const currentUserIdRef = useRef<string | undefined>(undefined);
+  // Track previous theme to detect transitions from custom theme
+  const previousThemeRef = useRef<string | undefined>(undefined);
+
+  /**
+   * Sidebar collapsed fetching from local storage
+   */
+  useEffect(() => {
+    const localValue = localStorage && localStorage.getItem("app_sidebar_collapsed");
+    const localBoolValue = localValue ? (localValue === "true" ? true : false) : false;
+    if (localValue && sidebarCollapsed === undefined) toggleSidebar(localBoolValue);
+  }, [sidebarCollapsed, setTheme, toggleSidebar]);
+
+  /**
+   * Effect 1: Initial theme sync from server (one-time only)
+   *
+   * This effect runs ONCE per user session to load theme from server.
+   * After initial load, all theme changes are localStorage-driven (next-themes).
+   * This prevents a feedback loop where server updates trigger UI updates in a cycle.
+   */
+  useEffect(() => {
+    const userId = userProfile?.id;
+
+    // Reset initialization flag when user changes (logout/login)
+    // This handles both logout (userId becomes undefined) and login (userId changes)
+    if (userId !== currentUserIdRef.current) {
+      hasInitializedThemeRef.current = false;
+      previousThemeRef.current = undefined;
+      currentUserIdRef.current = userId;
+    }
+
+    // Only initialize theme from server on FIRST load for this user
+    if (!userProfile?.theme?.theme || hasInitializedThemeRef.current) {
+      return; // Skip if already initialized or no profile data
+    }
+
+    // Apply theme from server profile (one-time only)
+    setTheme(userProfile?.theme?.theme || "system");
+
+    // Mark as initialized - prevents future syncs from server
+    hasInitializedThemeRef.current = true;
+  }, [userProfile?.theme?.theme, setTheme]);
+
+  /**
+   * Effect 2: Custom theme CSS application (runs on every change)
+   *
+   * This effect applies or clears custom theme CSS variables whenever
+   * the theme changes. It runs independently of the initial sync effect.
+   */
+  useEffect(() => {
+    if (!userProfile?.theme?.theme) return;
+
+    const currentTheme = userProfile?.theme?.theme;
+    const previousTheme = previousThemeRef.current;
+    const themeData = userProfile?.theme;
+
+    // Apply custom theme if current theme is custom
+    if (currentTheme === "custom" && themeData.primary && themeData.background && themeData.darkPalette !== undefined) {
+      applyCustomTheme(themeData.primary, themeData.background, themeData.darkPalette ? "dark" : "light");
+    }
+    // Clear custom theme CSS when switching away from custom
+    else if (previousTheme === "custom" && currentTheme !== "custom") {
+      clearCustomTheme();
+      // No reload needed - let CSS cascade handle it naturally
+    }
+
+    // Update previous theme for next comparison
+    previousThemeRef.current = currentTheme;
+  }, [userProfile?.theme]);
+
+  useEffect(() => {
+    if (!userProfile?.id) return;
+    changeLanguage((userProfile?.language as TLanguage) || DEFAULT_LANGUAGE);
+  }, [userProfile?.language, changeLanguage]);
+
+  useEffect(() => {
+    if (!params) return;
+    setQuery(params);
+  }, [params, setQuery]);
+
+  return <>{children}</>;
+}
+
+export default observer(StoreWrapper);