@prostgles/prostgles 2.3.6-dev.1786548258

package/client/src/app/CommandPalette/useCommandPaletteState.tsx

@@ -0,0 +1,188 @@
+import { getProperty } from "@common/utils";
+import Btn from "@components/Btn";
+import type { SearchListItem } from "@components/SearchList/SearchList";
+import { getItemSearchRank } from "@components/SearchList/searchMatchUtils/getItemSearchRank";
+import {
+  mdiArrowSplitVertical,
+  mdiButtonPointer,
+  mdiCardTextOutline,
+  mdiChartLine,
+  mdiCheckboxOutline,
+  mdiFileUploadOutline,
+  mdiFormatListBulleted,
+  mdiFormSelect,
+  mdiFormTextbox,
+  mdiKeyboard,
+  mdiLink,
+  mdiListBoxOutline,
+  mdiMenu,
+  mdiNumeric,
+  mdiOpenInApp,
+  mdiTextLong,
+} from "@mdi/js";
+import React, { useEffect, useState } from "react";
+import { isPlaywrightTest } from "src/i18n/i18nUtils";
+import { COMMAND_SEARCH_ATTRIBUTE_NAME } from "src/Testing";
+import { flatUIDocs, type UIDoc, type UIDocInputElement } from "../UIDocs";
+import type { CommandSearchHighlight } from "./CommandPalette";
+import "./CommandPalette.css";
+import type { DynamicComponentRegistry } from "./DynamicComponent";
+import { useGoToUI } from "./useGoToUI";
+
+export const useCommandPaletteState = (prglLoaded: boolean) => {
+  const { showSection, setShowSection } = useOnKeyDown();
+  const [highlights, setHighlights] = useState<CommandSearchHighlight[]>([]);
+  const { message, setMessage, goToUIDocItem } = useGoToUI(setHighlights);
+  const [quickPeekComponent, setQuickPeekComponent] =
+    useState<keyof DynamicComponentRegistry>();
+  const items = flatUIDocs.map((data) => {
+    const iconKey =
+      data.type === "input" ? `${data.type}-${data.inputType}` : data.type;
+    const iconPath = data.iconPath ?? getProperty(UIDocTypeToIcon, iconKey);
+    if (!iconPath) {
+      console.warn("No icon for UIDoc type", iconKey, data);
+    }
+    const componentName =
+      data.componentName ||
+      data.parentDocs.find((d) => d.componentName)?.componentName;
+
+    const goToItem = () => {
+      setShowSection(undefined);
+      return goToUIDocItem(data);
+    };
+    return {
+      key: data.title,
+      parentLabels: data.parentTitles,
+      label: data.title,
+      subLabel: data.description,
+      iconLeft:
+        iconPath ?
+          { type: "Icon", path: iconPath, title: data.type }
+        : undefined,
+      onPress: async () => {
+        // TODO: keep track of which component needs prglLoaded and if it's not loaded:
+        //     - goToItem until it becomes loaded and show component
+        if (componentName && prglLoaded) {
+          setQuickPeekComponent(componentName);
+        } else {
+          await goToItem();
+        }
+
+        window.document.body.setAttribute(
+          COMMAND_SEARCH_ATTRIBUTE_NAME,
+          data.title,
+        );
+      },
+      contentRight: Boolean(componentName) && (
+        <Btn
+          iconPath={mdiOpenInApp}
+          onClick={() => {
+            void goToItem();
+          }}
+        />
+      ),
+      ranking: (searchTerm) =>
+        getItemSearchRank(
+          {
+            title: data.title,
+            subTitle: data.description,
+            level: data.parentTitles.length,
+          },
+          searchTerm,
+        ),
+      data,
+    } satisfies SearchListItem;
+  });
+
+  return {
+    showSection,
+    setShowSection,
+    highlights,
+    message,
+    setMessage,
+    items,
+    quickPeekComponent,
+    setQuickPeekComponent,
+  };
+};
+
+const useOnKeyDown = () => {
+  const [showSection, setShowSection] = useState<"commands" | "docs">();
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "F1") {
+        event.preventDefault();
+        setShowSection("docs");
+      }
+      if (event.ctrlKey && event.key === "k") {
+        event.preventDefault();
+        setShowSection("commands");
+      }
+      if (event.key === "Escape") {
+        setShowSection(undefined);
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [showSection]);
+  return { showSection, setShowSection };
+};
+
+const UIDocTypeToIcon: Partial<
+  Record<
+    `${UIDocInputElement["type"]}-${UIDocInputElement["inputType"]}`,
+    string
+  > &
+    Record<Exclude<UIDoc["type"], "input">, string>
+> = {
+  link: mdiLink,
+  button: mdiButtonPointer,
+  popup: mdiButtonPointer,
+  select: mdiButtonPointer,
+  "input-text": mdiFormTextbox,
+  "input-checkbox": mdiCheckboxOutline,
+  "input-file": mdiFileUploadOutline,
+  "input-number": mdiNumeric,
+  "input-select": mdiFormSelect,
+  smartform: mdiListBoxOutline,
+  "smartform-popup": mdiListBoxOutline,
+  list: mdiFormatListBulleted,
+  section: mdiCardTextOutline,
+  tab: mdiCardTextOutline,
+  "accordion-item": mdiCardTextOutline,
+  "drag-handle": mdiArrowSplitVertical,
+  "hotkey-popup": mdiKeyboard,
+  navbar: mdiMenu,
+  text: mdiTextLong,
+  canvas: mdiChartLine,
+  // page: mdiGrid,
+};
+
+if (isPlaywrightTest) {
+  flatUIDocs.forEach(({ title: searchTerm }) => {
+    let lowestRank = { value: Infinity, title: "" };
+    flatUIDocs.forEach(({ title, description, parentTitles }) => {
+      const rank = getItemSearchRank(
+        {
+          title,
+          subTitle: description,
+          level: parentTitles.length,
+        },
+        searchTerm,
+      );
+
+      if (rank < lowestRank.value) {
+        lowestRank = { value: rank, title };
+      }
+    });
+
+    if (searchTerm !== lowestRank.title) {
+      throw new Error(
+        `Search rank test failed for term "${searchTerm}". Expected "${searchTerm}" to rank highest, but got "${lowestRank.title}"`,
+      );
+    }
+  });
+}

package/client/src/app/CommandPalette/useGoToUI.tsx

@@ -0,0 +1,147 @@
+import { useAlert } from "@components/AlertProvider";
+import { includes } from "prostgles-types";
+import { useCallback, useMemo } from "react";
+import { useLocation, useNavigate } from "react-router";
+import { click } from "../../demo/demoUtils";
+import { isPlaywrightTest } from "../../i18n/i18nUtils";
+import { tout } from "../../utils/utils";
+import {
+  flatUIDocs,
+  type UIDoc,
+  type UIDocFlat,
+  type UIDocPage,
+} from "../UIDocs";
+import type { CommandSearchHighlight } from "./CommandPalette";
+import { getUIDocShortestPath } from "./getUIDocShortestPath";
+import { useHighlightDocItem } from "./useHighlightDocItem";
+import {
+  getDocPagePath,
+  getUIDocElements,
+  getUIDocElementsAndAlertIfEmpty,
+} from "./utils";
+
+export type DocItemHighlightItemPosition = "mid" | "last";
+
+export const useGoToUI = (
+  setHighlights: (h: CommandSearchHighlight[]) => void,
+) => {
+  const navigate = useNavigate();
+
+  const { addAlert } = useAlert();
+  const { highlight, message, setMessage, showMultiHighlight } =
+    useHighlightDocItem(setHighlights);
+
+  const location = useLocation();
+  const currentPage = useMemo(() => {
+    return flatUIDocs.find((doc) => {
+      if (doc.type === "page") {
+        const matchInfo = getDocPagePath(doc, location.pathname);
+        return matchInfo.isExactMatch;
+      }
+    }) as UIDocPage | undefined;
+  }, [location.pathname]);
+
+  const clickOneOrHighlight = useCallback(
+    async (doc: UIDoc, duration: DocItemHighlightItemPosition) => {
+      if (doc.type === "info") return;
+
+      const { items, fullSelector } = getUIDocElements(doc);
+      if (items.length === 1) {
+        await highlight(doc, duration);
+        await click("", fullSelector);
+      } else if (items.length > 1) {
+        await showMultiHighlight(doc, duration);
+      }
+    },
+    [highlight, showMultiHighlight],
+  );
+
+  const goToUI = useCallback(
+    async (doc: UIDoc): Promise<undefined | boolean> => {
+      const nonInteractableContainers: UIDoc["type"][] = [
+        "info",
+        "list",
+        "page",
+        "navbar",
+        "section",
+      ];
+      if (doc.type === "info") return;
+
+      if (doc.type === "hotkey-popup") {
+        const [maybeCtrl, charKey] = doc.hotkey;
+        const ctrlKEvent = new KeyboardEvent("keydown", {
+          key: charKey.toLowerCase(),
+          code: "Key" + charKey,
+          ctrlKey: maybeCtrl === "Ctrl",
+          altKey: maybeCtrl === "Alt",
+          shiftKey: maybeCtrl === "Shift",
+          bubbles: true,
+        });
+
+        // Dispatch it on the document
+        document.dispatchEvent(ctrlKEvent);
+      } else if (doc.type === "page" || doc.type === "navbar") {
+        const { isExactMatch, paths } = getDocPagePath(doc, location.pathname);
+        if (!isExactMatch) {
+          void navigate(paths[0]!);
+          await tout(400);
+          if (doc.type === "page" && doc.pathItem) {
+            await highlight(doc, "mid");
+          }
+          await tout(400);
+        }
+      } else if (nonInteractableContainers.includes(doc.type)) {
+        // Do not highlight non-interactable container types
+        const { items } = getUIDocElementsAndAlertIfEmpty(doc, addAlert);
+        return !items.length;
+      } else if (
+        doc.type === "popup" ||
+        doc.type === "tab" ||
+        doc.type === "accordion-item" ||
+        doc.type === "link" ||
+        doc.type === "smartform-popup"
+      ) {
+        await clickOneOrHighlight(doc, "mid");
+      } else {
+        await highlight(doc, "mid");
+      }
+    },
+    [location.pathname, navigate, clickOneOrHighlight, highlight, addAlert],
+  );
+
+  const goToUIDocItem = useCallback(
+    async (data: UIDocFlat) => {
+      const prevParents = data.parentDocs;
+      const shortcut =
+        currentPage ?
+          getUIDocShortestPath(currentPage, prevParents)
+        : undefined;
+      const pathItems = shortcut ?? prevParents;
+      const shouldBeOpened = includes(
+        ["link", "page", "tab", "popup", "smartform-popup"],
+        data.type,
+      );
+      const finalPathItems =
+        data.type === "hotkey-popup" ? [data]
+        : shouldBeOpened ? [...pathItems, data]
+        : pathItems;
+      for (const parent of finalPathItems) {
+        const shouldStop = await goToUI(parent);
+        if (!isPlaywrightTest && shouldStop) {
+          return;
+        }
+        await tout(200);
+      }
+      if (!shouldBeOpened) {
+        await highlight(data, "last");
+      }
+    },
+    [currentPage, highlight, goToUI],
+  );
+
+  return {
+    message,
+    setMessage,
+    goToUIDocItem,
+  };
+};

package/client/src/app/CommandPalette/useHighlightDocItem.ts

@@ -0,0 +1,89 @@
+import { useCallback, useState } from "react";
+import { useAlert } from "@components/AlertProvider";
+import { isDefined } from "prostgles-types";
+import { getUIDocElementsAndAlertIfEmpty } from "./utils";
+import type { UIDocNonInfo } from "../UIDocs";
+import { scrollIntoViewIfNeeded, tout } from "../../utils/utils";
+import type { CommandSearchHighlight } from "./CommandPalette";
+import { isInParentViewport } from "../domToSVG/utils/isElementVisible";
+import { isPlaywrightTest } from "../../i18n/i18nUtils";
+import type { DocItemHighlightItemPosition } from "./useGoToUI";
+
+export const useHighlightDocItem = (
+  setHighlights: (h: CommandSearchHighlight[]) => void,
+) => {
+  const { addAlert } = useAlert();
+  const [message, setMessage] = useState<{
+    text: string;
+    left: number;
+    top: number;
+  }>();
+  const highlight = useCallback(
+    async (doc: UIDocNonInfo, itemPosition: DocItemHighlightItemPosition) => {
+      const { items } = getUIDocElementsAndAlertIfEmpty(doc, addAlert);
+      const firstElem = items[0];
+      firstElem && scrollIntoViewIfNeeded(firstElem);
+      await tout(500);
+      const mustChooseOne = items.length > 1 && itemPosition !== "last";
+      const highlights = Array.from(items)
+        .map((el) => {
+          const rect = el.getBoundingClientRect();
+          const isVisible = isInParentViewport(el, rect);
+          if (!isVisible) {
+            return;
+          }
+          return {
+            left: rect.left,
+            top: rect.top,
+            width: rect.width,
+            height: rect.height,
+            borderRadius: getComputedStyle(el).borderRadius,
+            flickerSlow: itemPosition === "last" || mustChooseOne,
+          };
+        })
+        .filter(isDefined);
+
+      const firstItem = highlights[0];
+      setHighlights(highlights);
+      let waitedForClick = false;
+      if (firstItem && mustChooseOne) {
+        const { left, top } = firstItem;
+        setMessage({ text: "Chose one", left, top: top - 70 });
+        if (isPlaywrightTest) {
+          items[0]?.scrollIntoView();
+          items[0]?.click();
+        } else {
+          await new Promise((resolve) => {
+            window.addEventListener("click", resolve, { once: true });
+            window.addEventListener("keydown", resolve, { once: true });
+          });
+        }
+        waitedForClick = true;
+      }
+      if (!waitedForClick) {
+        await tout(
+          isPlaywrightTest ? 0
+          : itemPosition === "mid" ? 500
+          : 1200,
+        );
+      }
+      setHighlights([]);
+      setMessage(undefined);
+      return Array.from(items);
+    },
+    [addAlert, setHighlights],
+  );
+  const showMultiHighlight = useCallback(
+    async (doc: UIDocNonInfo, duration: DocItemHighlightItemPosition) => {
+      const [firstItem] = await highlight(doc, duration);
+      if (!firstItem) {
+        addAlert({
+          children: `No items found in the ${JSON.stringify(doc.title)} list.`,
+        });
+        return;
+      }
+    },
+    [highlight, addAlert],
+  );
+  return { highlight, message, setMessage, showMultiHighlight };
+};

package/client/src/app/CommandPalette/utils.ts

@@ -0,0 +1,111 @@
+import { isObject } from "@common/publishUtils";
+import type { AlertContext } from "@components/AlertProvider";
+import { includes } from "../../dashboard/W_SQL/W_SQLBottomBar/W_SQLBottomBar";
+import { waitForElement } from "../../demo/demoUtils";
+import { isPlaywrightTest } from "../../i18n/i18nUtils";
+import { getCommandElemSelector, type Command } from "../../Testing";
+import { isDefined } from "../../utils/utils";
+import type { UIDoc, UIDocNonInfo } from "../UIDocs";
+
+export const focusElement = async (
+  testId: Command | "",
+  endSelector?: string,
+) => {
+  const elem = await waitForElement<HTMLDivElement>(testId, endSelector);
+  elem.scrollIntoView({ behavior: "smooth", block: "center" });
+  elem.focus();
+  return elem;
+};
+
+export const getUIDocElements = (doc: Exclude<UIDoc, { type: "info" }>) => {
+  const selectors = doc.type === "page" ? doc.pathItem : doc;
+  const { selectorCommand, selector = "" } = selectors ?? {};
+
+  const childSelector = doc.type === "list" ? doc.itemSelector : "";
+  let fullSelector =
+    (selectorCommand ? getCommandElemSelector(selectorCommand) : "") +
+    " " +
+    selector +
+    " " +
+    childSelector;
+  if (!fullSelector.trim() && doc.type === "page") {
+    fullSelector = "body";
+  }
+  const items = document.querySelectorAll<HTMLDivElement>(fullSelector);
+  return {
+    items,
+    fullSelector,
+  };
+};
+
+export const highlightItems = (doc: Exclude<UIDoc, { type: "info" }>) => {
+  const listItems = getUIDocElements(doc).items;
+  listItems.forEach((el) => {
+    el.style.border = "2px solid var(--text-warning)";
+  });
+  return Array.from(listItems);
+};
+
+const PATH_JOIN_CHARS = ["/", "#", "?"] as const;
+export const getDocPagePath = (
+  doc: Extract<UIDoc, { type: "page" | "navbar" }>,
+  pathname: string,
+) => {
+  const paths =
+    doc.type === "page" ?
+      [doc.pathItem?.selectorPath, doc.path].filter(isDefined)
+    : doc.paths;
+  const matchedPage = paths.find((pathWopts) => {
+    const path = isObject(pathWopts) ? pathWopts.route : pathWopts;
+    const exact = isObject(pathWopts) && pathWopts.exact;
+    if (exact) {
+      return pathname === path;
+    }
+    const endChar = pathname[path.length];
+    return (
+      pathname.startsWith(path) &&
+      (!endChar || includes(endChar, PATH_JOIN_CHARS))
+    );
+  });
+  let isOnPage = !!matchedPage;
+  let currentPathItem: string | undefined;
+  if (matchedPage && doc.type === "page" && doc.pathItem) {
+    const matchedPagePath =
+      isObject(matchedPage) ? matchedPage.route : matchedPage;
+    currentPathItem = pathname
+      .slice(matchedPagePath.length + 1)
+      .split(`/[${PATH_JOIN_CHARS.join("")}]/`)
+      .pop();
+    isOnPage = isOnPage && !!currentPathItem;
+  }
+
+  const isExactMatch =
+    !isOnPage ? false
+    : doc.type === "navbar" ? true
+    : doc.pathItem ? Boolean(currentPathItem)
+    : doc.path === pathname;
+  return {
+    isOnPage,
+    isExactMatch,
+    matchedPage,
+    paths: paths.map((pathWopts) =>
+      isObject(pathWopts) ? pathWopts.route : pathWopts,
+    ),
+  };
+};
+
+export const getUIDocElementsAndAlertIfEmpty = (
+  doc: UIDocNonInfo,
+  addAlert: AlertContext["addAlert"],
+) => {
+  const result = getUIDocElements(doc);
+  if (!result.items.length && !isPlaywrightTest) {
+    addAlert({
+      children: [
+        `Could not find a ${JSON.stringify(doc.title)} item.`,
+        `Selector used: ${JSON.stringify(result.fullSelector)}`,
+      ].join("\n"),
+    });
+  }
+  return result;
+};

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

@@ -0,0 +1,43 @@
+import type { UIDoc } from "../UIDocs";
+
+export const UIInstallation = {
+  title: "Installation (Docker)",
+  type: "info",
+  description: "A guide to help you get started with the application.",
+  docs: `
+    The quickest way to start is with Docker. 
+    If you don't have Docker installed, please follow the official 
+    <a href="https://docs.docker.com/engine/install/" target="_blank">Docker installation guide</a>
+ 
+    Download the source code:
+
+    \`\`\`bash
+    git clone https://github.com/prostgles/ui.git
+    cd ui
+    \`\`\`
+
+    Start the application:
+
+    \`\`\`docker-compose.sh
+    docker compose up -d --build
+    \`\`\` 
+    
+    Once running, Prostgles UI will be available at [localhost:3004](http://localhost:3004)
+
+    ### Initial Setup & Authentication
+
+    When first launching Prostgles UI, an admin user will be created automatically:
+    - If \`PRGL_USERNAME\` and \`PRGL_PASSWORD\` environment variables are provided, an admin user is created with these credentials. 
+    - Otherwise, a passwordless admin user is created. 
+    It gets assigned to the first client that accesses the app. 
+    Subsequent clients accessing the app will be rejected with an appropriate error message detailing that the passwordless admin user has already been assigned.
+
+    To setup multiple users, the passwordless admin user must be converted to a normal admin account by setting up a password.
+    This will allow accessing /users page where you can manage users.
+
+    Users login using their username and password. Two-factor authentication is provided through TOTP (Time-based One-Time Password) and can be enabled in the account section.
+
+    Email and third-party (OAuth) authentication can be configured in Server Settings section. It allows users to register and log in using their email address or third-party accounts like Google, GitHub, etc.
+   
+    `,
+} satisfies UIDoc;