@prostgles/prostgles 2.3.6-dev.1786548258

package/client/src/app/UIDocs/editConnectionUIDoc.ts

@@ -0,0 +1,131 @@
+import { ROUTES } from "@common/utils";
+import type { UIDocContainers } from "../UIDocs";
+
+export const editConnectionUIDoc = {
+  type: "page",
+  // path: ROUTES.EDIT_CONNECTION,
+  title: "Add or Edit Connection",
+  description:
+    "Create a new connection or modify the details of an existing database connection. Update connection settings, credentials, and more.",
+  docs: `
+    Connection settings, credentials, and other parameters to ensure your connection is configured correctly.
+    `,
+  children: [
+    {
+      type: "popup",
+      selectorCommand: "PostgresInstallationInstructions",
+      title: "PostgreSQL Installation Instructions",
+      description: "Instructions for installing PostgreSQL on your system.",
+      children: [],
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.connectionName",
+      title: "Connection Name",
+      description: "The name of the connection.",
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.connectionType",
+      title: "Connection Type",
+      description:
+        "Allows you change the connection details format: standard or connection string.",
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.db_conn",
+      title: "Connection String",
+      description: "The connection string for the database. ",
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.db_host",
+      title: "Database Host",
+      description: "The hostname or IP address of the database server.",
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.db_port",
+      title: "Database Port",
+      description: "The port number on which the database server is listening.",
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.db_user",
+      title: "Database User",
+      description: "The username used to connect to the database.",
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.db_pass",
+      title: "Database Password",
+      description: "The password for the database user.",
+    },
+    {
+      type: "input",
+      inputType: "text",
+      selectorCommand: "NewConnectionForm.db_name",
+      title: "Database Name",
+      description: "The name of the database to connect to.",
+    },
+    {
+      type: "section",
+      selectorCommand: "NewConnectionForm.MoreOptionsToggle",
+      title: "More Options",
+      description: "Additional connection options.",
+      children: [
+        {
+          type: "select",
+          selectorCommand: "NewConnectionForm.schemaFilter",
+          title: "Schema Filter",
+          description:
+            "Controls which schemas are visible in the dashboard (public by default).",
+        },
+        {
+          type: "input",
+          inputType: "text",
+          selectorCommand: "NewConnectionForm.connectionTimeout",
+          title: "Connection Timeout",
+          description:
+            "The maximum time to wait for a connection to the database before timing out.",
+        },
+        {
+          type: "section",
+          selectorCommand: "NewConnectionForm.sslMode",
+          title: "SSL Mode",
+          description: "Configure SSL settings for the connection.",
+          children: [],
+        },
+        {
+          type: "input",
+          inputType: "checkbox",
+          selectorCommand: "NewConnectionForm.watchSchema",
+          title: "Watch Schema",
+          description:
+            "Enabled by default. Enables schema change tracking. Any changes made to the database schema are reflected in the API and UI.",
+        },
+        {
+          type: "input",
+          inputType: "checkbox",
+          selectorCommand: "NewConnectionForm.realtime",
+          title: "Enable Realtime",
+          description:
+            "Enabled by default. Enables realtime data change tracking for tables and views. Requires trigger permissions to the underlying tables.",
+        },
+      ],
+    },
+    {
+      type: "button",
+      selectorCommand: "Connection.edit.updateOrCreateConfirm",
+      title: "Update Connection",
+      description: "Save the changes made to the connection.",
+    },
+  ],
+} satisfies Omit<UIDocContainers, "path">;

package/client/src/app/UIDocs/navbarUIDoc.ts

@@ -0,0 +1,145 @@
+import { mdiThemeLightDark, mdiTranslate } from "@mdi/js";
+import { ROUTES } from "@common/utils";
+import type { UIDocNavbar } from "../UIDocs";
+
+export const navbarUIDoc = {
+  type: "navbar",
+  selectorCommand: "NavBar",
+  title: "Navigation bar",
+  description:
+    "The top navigation bar provides quick access to all major sections of Prostgles UI.",
+  docs: `
+    The top navigation bar provides quick access to all major sections of Prostgles UI. 
+    Located at the top of the interface, it allows you to switch between database connections, manage users and server settings, and access your account preferences. 
+    The navigation adapts to your user role, showing admin-only sections like Users and Server Settings only to authorized users.
+
+    ## Key sections of the app
+
+    ### Connections
+
+    A connection represents a unique postgres database instance (unique host, port, user and database name).
+    The connection list page shows all available connections you can access based on your user permissions.
+    
+    ### Connection dashboard
+
+    Clicking a connection from the connection list will take you to the dashboard page where you can explore and interact with the database.
+    Available views and tools include SQL Editor, Table, Map, Schema Diagram, AI Assistant, and more.
+
+    ### Dashboard workspaces
+    
+    The views you open in the dashboard are saved automatically to the current workspace.
+    This allows you to return to the same views later, even after closing the application.
+    You can create multiple workspaces to organize your views by project, team, task, or any other criteria.
+
+
+    <img src="./screenshots/navbar.svgif.svg" alt="Navigation" />
+`,
+  children: [
+    // {
+    //   type: "link",
+    //   path: ROUTES.CONNECTIONS,
+    //   selector: ".prgl-brand-icon",
+    //   title: "Go to Homepage",
+    //   description: "Navigate to the home page (connection list). ",
+    // },
+    {
+      type: "link",
+      path: ROUTES.CONNECTIONS,
+      selector: '[href="/connections"]',
+      title: "Connections",
+      description: "Manage database connections",
+    },
+    {
+      type: "link",
+      path: ROUTES.USERS,
+      selector: '[href="/users"]',
+      title: "Users",
+      description: "Manage user accounts (admin only)",
+      docOptions: "hideChildren",
+      pageContent: [
+        {
+          type: "input",
+          inputType: "text",
+          selectorCommand: "SearchList",
+          title: "Search Users",
+          description: "Search for users by name or email.",
+        },
+        {
+          type: "smartform-popup",
+          selectorCommand: "dashboard.window.rowInsertTop",
+          title: "Create User",
+          description: "Create a new user account.",
+          tableName: "users",
+        },
+        {
+          type: "list",
+          selector: ".table-component",
+          title: "User List",
+          description: "List of all users in the system.",
+          itemSelector: ".TableBody div[role='row']",
+          itemContent: [
+            {
+              type: "smartform-popup",
+              selectorCommand: "dashboard.window.viewEditRow",
+              title: "Edit User",
+              description: "Edit user details.",
+              tableName: "users",
+            },
+          ],
+        },
+        {
+          type: "button",
+          selectorCommand: "Pagination.lastPage",
+          title: "Go to Last Page",
+          description: "Navigate to the last page of the user list.",
+        },
+      ],
+    },
+    {
+      type: "link",
+      path: ROUTES.SERVER_SETTINGS,
+      selector: '[href="/server-settings"]',
+      title: "Server Settings",
+      description: "Configure server settings (admin only)",
+    },
+    {
+      type: "link",
+      path: ROUTES.ACCOUNT,
+      title: "Account",
+      selector: '[href="/account"]',
+      description: "Manage your account",
+    },
+    {
+      type: "button",
+      title: "Logout",
+      selectorCommand: "NavBar.logout",
+      description: "Logout of your account",
+    },
+    {
+      type: "select",
+      selectorCommand: "App.colorScheme",
+      title: "Theme Selector",
+      description: "Switch between light and dark themes",
+      iconPath: mdiThemeLightDark,
+    },
+    {
+      type: "select",
+      selectorCommand: "App.LanguageSelector",
+      title: "Language Selector",
+      description: "Change the interface language",
+      iconPath: mdiTranslate,
+    },
+    {
+      type: "button",
+      selector: ".hamburger",
+      title: "Toggle Menu (visible on small screens)",
+      description: "Toggle the mobile navigation menu on smaller screens",
+    },
+  ],
+  paths: [
+    { route: ROUTES.CONNECTIONS, exact: true },
+    ROUTES.USERS,
+    ROUTES.SERVER_SETTINGS,
+    ROUTES.ACCOUNT,
+  ],
+} satisfies UIDocNavbar;

package/client/src/app/UIDocs/overviewUIDoc.ts

@@ -0,0 +1,31 @@
+import type { UIDoc } from "../UIDocs";
+
+export const overviewUIDoc = {
+  type: "info",
+  title: "Overview",
+  description: "Overview",
+  docs: `
+    Prostgles UI is a user-friendly way for interacting with PostgreSQL, creating dashboards and internal tools.
+
+    <img src="./screenshots/overview.svgif.svg" alt="Prostgles UI Overview" width="100%" />
+
+    ## Features
+    - SQL editor with syntax highlighting and auto-completion
+    - Real-time dashboards and charts
+    - AI assistant with MCP support and agentic workflows
+    - User authentication (email, third-party OAuth and two-factor authentication)
+    - Role-based access control
+    - Database management
+    - File storage and backups (locally or to AWS S3 compatible storage)
+    - TypeScript API with database schema types and end to end type safety
+    - LISTEN NOTIFY support
+    - Mobile friendly
+
+    It comes in two versions: 
+    - **Prostgles UI** - Web-based app with the full feature set, accessible from modern browsers.
+    - **Prostgles Desktop** - Electron-based app for Linux, macOS, and Windows, focused on data exploration and database management.
+  
+    Note: Multi-user features such as User Management are not available in the desktop version.
+  `,
+  docOptions: "asSeparateFile",
+} as const satisfies UIDoc;

package/client/src/app/UIDocs/serverSettingsUIDoc.ts

@@ -0,0 +1,64 @@
+import { ROUTES } from "@common/utils";
+import { mdiServerSecurity, mdiTools } from "@mdi/js";
+import { getDataKey } from "../../Testing";
+import type { UIDocContainers } from "../UIDocs";
+import { authenticationUIDoc } from "./connection/config/authentication.UIDoc";
+
+export const serverSettingsUIDoc = {
+  type: "page",
+  path: ROUTES.SERVER_SETTINGS,
+  iconPath: mdiServerSecurity,
+  title: "Server Settings",
+  description:
+    "Server Settings. Configure security, authentication, and LLM settings.",
+  docs: `
+    Manage server settings to enhance security, configure authentication methods, and set up LLM providers.
+    <img src="./screenshots/server_settings.svg" alt="Server Settings" />
+  `,
+  children: [
+    {
+      type: "tab",
+      selector: getDataKey("security"),
+      title: "Security",
+      description:
+        "Security. Configure domain access, IP restrictions, session duration, and login rate limits to enhance security.",
+      children: [
+        {
+          type: "smartform",
+          title: "Settings form",
+          description: "Configure server settings.",
+          selectorCommand: "SmartForm",
+          tableName: "server_settings",
+        },
+      ],
+    },
+    authenticationUIDoc,
+    {
+      type: "tab",
+      iconPath: mdiTools,
+      title: "MCP Servers",
+      selector: getDataKey("mcpServers"),
+      description:
+        "Manage MCP servers and tools that can then be used in the Ask AI chat",
+      componentName: "MCPServers",
+      children: [],
+    },
+    {
+      type: "tab",
+      title: "LLM Providers",
+      selector: getDataKey("llmProviders"),
+      description:
+        "Manage LLM providers, credentials and models to be used in the Ask AI chat",
+      componentName: "LLMProviderSetup",
+      children: [],
+    },
+    {
+      type: "tab",
+      title: "Services",
+      selector: getDataKey("services"),
+      description: "Manage services",
+      componentName: "Services",
+      children: [],
+    },
+  ],
+} satisfies UIDocContainers;

package/client/src/app/UIDocs.ts

@@ -0,0 +1,274 @@
+import { filterArrInverse } from "@common/llmUtils";
+import type { DBSSchema } from "@common/publishUtils";
+import type { ROUTES } from "@common/utils";
+import type { Route } from "react-router";
+import { isPlaywrightTest } from "../i18n/i18nUtils";
+import type { Command } from "../Testing";
+import { isDefined } from "../utils/utils";
+import { domToThemeAwareSVG } from "./domToSVG/domToThemeAwareSVG";
+import { accountUIDoc } from "./UIDocs/accountUIDoc";
+import { commandPaletteUIDoc } from "./UIDocs/commandPaletteUIDoc";
+import { connectionConfigUIDoc } from "./UIDocs/connection/connectionConfigUIDoc";
+import { dashboardUIDoc } from "./UIDocs/connection/dashboardUIDoc";
+import { connectionsUIDoc } from "./UIDocs/connectionsUIDoc";
+import { desktopInstallationUIDoc } from "./UIDocs/desktopInstallation";
+import { navbarUIDoc } from "./UIDocs/navbarUIDoc";
+import { overviewUIDoc } from "./UIDocs/overviewUIDoc";
+import { serverSettingsUIDoc } from "./UIDocs/serverSettingsUIDoc";
+import { UIInstallation } from "./UIDocs/UIInstallationUIDoc";
+import { getSVGif } from "./domToSVG/SVGif/getSVGif";
+import type { DynamicComponentRegistry } from "./CommandPalette/DynamicComponent";
+import { setThemeForSVGScreenshot } from "./domToSVG/setThemeForSVGScreenshot";
+
+/**
+ * The purpose of UIDocs is to provide structured metadata about the UI elements.
+ * This metadata is used for:
+ * 1. Command Palette. It requires a list of all UI elements and their relationships to enable quick navigation.
+ * 2. Documentation. Generating user guides and documentation with screenshots and descriptions.
+ * 3. Automated testing to ensure UI elements are present and functional.
+ *
+ * Each UIDoc describes a UI element or a group of elements, including their type, selector, description, and hierarchical relationships.
+ * This structured approach allows for easy maintenance and scalability of the documentation system.
+ */
+
+type UIDocCommon = {
+  title: string;
+
+  /**
+   * Optional mdi icon path representing the element, enhancing visual identification in the Command Palette.
+   */
+  iconPath?: string;
+
+  /**
+   * Short description of the element's purpose or functionality used in Command Palette.
+   */
+  description: string;
+
+  /**
+   * If defined, this will be used to generate a separate section in the documentation.
+   */
+  docs?: string;
+
+  /**
+   * If defined, this will be used as the title for the children list in the documentation.
+   */
+  childrenTitle?: string;
+
+  docOptions?:
+    /**
+     * If docs is defined, then it will be rendered as a separate header in the documentation with this title.
+     */
+    | { title: string }
+    /**
+     * If "asSeparateFile" AND docs is defined, this will be saved as a separate file in the documentation.
+     * By default, a single file is generated for each root UIDoc with child items with docs appended to the bottom.
+     */
+    | "asSeparateFile"
+    /**
+     * Hides children from documentation. Meant to be used when the children content is obvious/documented on the parent.
+     */
+    | "hideChildren";
+
+  /** If true then this is not available for Prostgles Desktop */
+  uiVersionOnly?: true;
+
+  /**
+   * If defined, this will be used to render a dynamic component in the Command Palette and documentation.
+   */
+  componentName?: keyof DynamicComponentRegistry;
+};
+
+/**
+ * UI Documentation system for generating interactive element guides and documentation.
+ * Defines structured metadata for UI elements including selectors, types, and hierarchical relationships.
+ * Used for automated testing, user guidance, and generating SVG documentation from DOM elements.
+ */
+type UIDocBase<T> = (
+  | {
+      selector: string;
+      selectorCommand?: undefined;
+    }
+  | {
+      selector?: undefined;
+      /**
+       * data-command attribute of the element to be selected.
+       */
+      selectorCommand: Command;
+    }
+) &
+  UIDocCommon &
+  T;
+
+type Route = (typeof ROUTES)[keyof typeof ROUTES];
+
+export type UIDocInputElement = UIDocBase<{
+  type: "input";
+  inputType: "text" | "number" | "checkbox" | "select" | "file";
+}>;
+
+export type UIDocElement =
+  | UIDocBase<{
+      type: "button";
+    }>
+  | UIDocBase<{
+      type: "drag-handle";
+      direction: "x" | "y";
+    }>
+  | UIDocBase<{
+      type: "canvas";
+    }>
+  | UIDocInputElement
+  | UIDocBase<{
+      type: "text";
+    }>
+  | UIDocBase<{
+      type: "list";
+      itemSelector: string;
+      itemContent: UIDocElement[];
+    }>
+  | UIDocBase<{
+      type: "select";
+    }>
+  | UIDocBase<{
+      type: "link";
+      path: Route;
+      /**
+       * If defined this means that the final url is `${pagePath}/pathItemRow.id`
+       */
+      pathItem?: {
+        tableName: keyof DBSSchema;
+      };
+      pageContent?: UIDocElement[];
+    }>
+  | UIDocBase<{
+      type: "popup";
+      triggerMode?: "click" | "contextmenu";
+      /**
+       * Used in detecting if popup is shown
+       */
+      contentSelectorCommand?: Command;
+      children: UIDocElement[];
+    }>
+  | UIDocBase<{
+      type: "tab" | "accordion-item";
+      children: UIDocElement[];
+    }>
+  | UIDocBase<{
+      type: "section";
+      children: UIDocElement[];
+    }>
+  | UIDocBase<{
+      type: "smartform" | "smartform-popup";
+      tableName: string;
+      fieldNames?: string[];
+    }>
+  | (UIDocCommon & {
+      /**
+       * Documentation-only. Does not appear in Command Palette.
+       */
+      type: "info";
+    });
+
+export type UIDocPage = UIDocCommon & {
+  type: "page";
+  path: Route;
+  pathItem?: {
+    tableName: keyof DBSSchema;
+    selectorCommand?: Command;
+    selector?: string;
+    selectorPath?: Route;
+  };
+  children: UIDocElement[];
+};
+export type UIDocContainers =
+  | UIDocPage
+  | UIDocBase<{
+      type: "hotkey-popup";
+      hotkey: ["Ctrl" | "Alt" | "Shift", "A" | "K"];
+      children: UIDocElement[];
+    }>;
+
+export type UIDocNavbar = UIDocBase<{
+  type: "navbar";
+  docs?: string;
+  children: UIDocElement[];
+  /**
+   * List of paths the navbar appears on.
+   */
+  paths: (Route | { route: Route; exact: true })[];
+}>;
+
+export type UIDoc = UIDocContainers | UIDocElement | UIDocNavbar;
+
+export const UIDocs = [
+  overviewUIDoc,
+  UIInstallation,
+  desktopInstallationUIDoc,
+  navbarUIDoc,
+  connectionsUIDoc,
+  dashboardUIDoc,
+  connectionConfigUIDoc,
+  serverSettingsUIDoc,
+  accountUIDoc,
+  commandPaletteUIDoc,
+] satisfies UIDoc[];
+
+const getFlatDocs = (
+  doc: UIDoc | undefined,
+  parentDocs: UIDoc[] = [],
+):
+  | ({
+      parentTitles: string[];
+      parentDocs: UIDoc[];
+    } & UIDoc)[]
+  | undefined => {
+  if (!doc) return [];
+  const parentTitles = parentDocs.map((d) => d.title);
+  const children =
+    "children" in doc ? doc.children
+    : "itemContent" in doc ? doc.itemContent
+    : "pageContent" in doc ? doc.pageContent
+    : undefined;
+
+  if (!children?.length) {
+    return [
+      {
+        parentTitles,
+        ...doc,
+        parentDocs,
+      },
+    ];
+  }
+
+  const nextParentDocs = [...parentDocs, doc];
+  const flatChildren = children.flatMap(
+    (childDoc: UIDocContainers | UIDocElement) => {
+      const flatChildren = getFlatDocs(childDoc, nextParentDocs) ?? [];
+      return flatChildren;
+    },
+  );
+  return [
+    {
+      parentTitles,
+      ...doc,
+      parentDocs,
+    },
+    ...flatChildren,
+  ];
+};
+export type UIDocNonInfo = Exclude<UIDoc, { type: "info" }>;
+export type UIDocFlat = UIDocNonInfo & {
+  parentTitles: string[];
+  parentDocs: UIDoc[];
+};
+export const flatUIDocs = filterArrInverse(UIDocs, { type: "info" } as const)
+  .map((doc) => getFlatDocs(doc))
+  .filter(isDefined)
+  .flat() as UIDocFlat[];
+window.flatUIDocs = flatUIDocs;
+
+if (isPlaywrightTest) {
+  window.toSVG = domToThemeAwareSVG;
+  window.setTheme = setThemeForSVGScreenshot;
+  window.getSVGif = getSVGif;
+}

package/client/src/app/XRealIpSpoofableAlert.tsx

@@ -0,0 +1,39 @@
+import { ROUTES } from "@common/utils";
+import Btn from "@components/Btn";
+import { InfoRow } from "@components/InfoRow";
+import PopupMenu from "@components/PopupMenu";
+import { mdiAlertOutline } from "@mdi/js";
+import React from "react";
+import { NavLink } from "react-router";
+import { t } from "../i18n/i18nUtils";
+import type { useAppState } from "../useAppState/useAppState";
+
+type P = Pick<ReturnType<typeof useAppState>, "serverState" | "prglState">;
+export const XRealIpSpoofableAlert = ({ serverState, prglState }: P) => {
+  const user = prglState?.user;
+  return (
+    <>
+      {serverState?.xRealIpSpoofable && user?.type === "admin" && (
+        <PopupMenu
+          button={
+            <Btn color="danger" iconPath={mdiAlertOutline} variant="filled">
+              {t["App"]["Security issue"]}
+            </Btn>
+          }
+          style={{ position: "fixed", right: 0, top: 0, zIndex: 999999 }}
+          positioning="beneath-left-minfill"
+          clickCatchStyle={{ opacity: 0.5 }}
+          content={
+            <InfoRow>
+              Failed login rate limiting is based on x-real-ip header which can
+              be spoofed based on your current connection.{" "}
+              <NavLink to={ROUTES.SERVER_SETTINGS}>
+                {t["App"]["Settings"]}
+              </NavLink>
+            </InfoRow>
+          }
+        />
+      )}
+    </>
+  );
+};