🏗️ chore: add basic UI scaffolding

Author: svenvandescheur

frontend/bin/create_page.sh

@@ -39,7 +39,8 @@ function create_css_file() {
 function create_page_file() {
   cat > "$2/$capitalized_page_name.tsx" <<EOF
 import React from "react";
-import { useLoaderData } from "react-router";
+import { Outlet, useLoaderData } from "react-router";
+import { useCurrentMatch } from "~/api/hooks/useCurrentMatch.ts";
 
 import "./$capitalized_page_name.css";
 import { ${capitalized_page_name}LoaderData } from "./${page_name}.loader.tsx";
@@ -52,12 +53,14 @@ export type ${component_name}Props = React.ComponentProps<"main"> & {
  * ${capitalized_page_name} page
  */
 export function ${component_name}({ children, ...props }: ${component_name}Props) {
+  const activeMatch = useCurrentMatch();
   const loaderData = useLoaderData<${capitalized_page_name}LoaderData>();
 
   return (
     <main className="${component_name}" {...props}>
-      <pre>children: {children}</pre>
+      <pre>match: {JSON.stringify(activeMatch)}</pre>
       <pre>data: {JSON.stringify(loaderData)}</pre>
+      <Outlet />
     </main>
   );
 }

frontend/bin/link_conflicting_devdependencies.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# Get the directory of the script
+SCRIPT_DIR=`dirname $0`;
+FRONTEND_DIR=`dirname $SCRIPT_DIR`
+
+cd $FRONTEND_DIR;
+
+CONFLICTS=("@maykin-ui/admin-ui/node_modules/react" "@maykin-ui/admin-ui/node_modules/react-dom")
+
+# Function to check if a directory exists
+function directory_exists() {
+  [ -d $1 ]
+}
+
+count=0;
+for dir in ${CONFLICTS[@]}; do
+  fulldir="node_modules/${dir}"
+  dirname=`basename ${fulldir}`
+  symlink_target="${FRONTEND_DIR}/node_modules/${dirname}"
+
+  if directory_exists $fulldir; then
+    real_source=`realpath ${fulldir}`
+    real_target=`realpath ${symlink_target}`
+    echo "removing conflicting dependency: $real_source"
+    rm -rf $real_source;
+
+    echo "creating symlink: $dirname"
+    ln -s $real_target $real_source
+
+    let count++
+  else
+    echo "conflicting dependency not found: $fulldir"
+  fi
+done
+
+echo ""
+echo "$count conflicting dependencies linked"
+
+if [ $count -gt 0 ]; then
+  echo "you may need to restart your server"
+fi
+

frontend/eslint.config.js

@@ -16,6 +16,7 @@ const config = [
     },
     rules: {
       "tsdoc/syntax": "error",
+      "react-hooks/exhaustive-deps": "off",
     },
   },
 ];

frontend/package-lock.json

@@ -17,7 +17,7 @@
     "build-storybook": "storybook build"
   },
   "dependencies": {
-    "@maykin-ui/admin-ui": "^0.0.53",
+    "@maykin-ui/admin-ui": "alpha",
     "@maykin-ui/client-common": "^0.0.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

frontend/package.json

@@ -1,10 +1,15 @@
 import { render } from "@testing-library/react";
+import { RouterProvider, createBrowserRouter } from "react-router";
 import { describe, it } from "vitest";
 
 import App from "./App";
 
 describe("App", () => {
   it("renders without crashing", () => {
-    render(<App />);
+    render(
+      <RouterProvider
+        router={createBrowserRouter([{ path: "/", element: <App /> }])}
+      ></RouterProvider>,
+    );
   });
 });

frontend/src/App.test.tsx

@@ -1,12 +1,106 @@
-// @ts-expect-error Style is an alias, and ts isn't able to resolve this
+import {
+  BaseTemplate,
+  ButtonProps,
+  ConfigContext,
+  Logo,
+  Outline,
+  ucFirst,
+} from "@maykin-ui/admin-ui";
+// @ts-expect-error - no ts modules
 import "@maykin-ui/admin-ui/style";
-import { Outlet } from "react-router";
+import { useMemo } from "react";
+import { Outlet, RouteObject, useLocation, useNavigate } from "react-router";
+import { useChildRoutes } from "~/hooks/useChildRoutes.ts";
+import { useCurrentMatch } from "~/hooks/useCurrentMatch.ts";
+
+import "./main.css";
 
 /**
  * This component serves as the entry point for the React app and renders the main UI structure.
  */
 function App() {
-  return <Outlet />;
+  const location = useLocation();
+  const navigate = useNavigate();
+  const currentMatch = useCurrentMatch();
+  const childRoutes = useChildRoutes();
+
+  const currentMatchHandle = currentMatch.handle as
+    | Record<string, unknown>
+    | undefined;
+  const hideUi = currentMatchHandle?.hideUi;
+
+  /**
+   * The primary navigation items.
+   */
+  const primaryNavigationItems = useMemo(() => {
+    // Login page should not show primary navigation.
+    if (hideUi) {
+      return [];
+    }
+
+    const buttons = [
+      {
+        children: (
+          <>
+            <Outline.Squares2X2Icon />
+          </>
+        ),
+        title: "Catalogi",
+        onClick: () => navigate("/"),
+      },
+    ].map<ButtonProps>((props) => ({
+      ...props,
+      // eslint-disable-next-line react/prop-types
+      key: props.title,
+      align: "start",
+      pad: true,
+    }));
+    return [
+      <Logo key="logo" abbreviated variant="contrast" />,
+      ...buttons,
+      "spacer",
+    ];
+  }, [location]);
+
+  /**
+   * The sidebar navigation items.
+   */
+  const sidebarItems = useMemo(() => {
+    // Page with no child routes should not show sidebar.
+    if (!childRoutes.length) {
+      return [];
+    }
+
+    return childRoutes
+      .filter((route) => route.path)
+      .map(({ path, id }: RouteObject): ButtonProps => {
+        return {
+          active: currentMatch.id === id,
+          align: "start",
+          children: ucFirst(path?.split("/").pop()?.trim() || ""),
+          onClick: () =>
+            navigate(
+              currentMatch.id === id
+                ? currentMatch.pathname || ""
+                : [currentMatch.pathname, path!].join("/"),
+            ),
+        };
+      });
+  }, [primaryNavigationItems]);
+
+  return (
+    <BaseTemplate
+      primaryNavigationItems={primaryNavigationItems}
+      sidebarItems={sidebarItems}
+      grid={!hideUi}
+    >
+      <ConfigContext.Provider
+        value={{ templatesContentOnly: true, templatesGrid: false }}
+      >
+        <Outlet />
+      </ConfigContext.Provider>
+    </BaseTemplate>
+  );
 }
 
 export default App;

frontend/src/App.tsx

@@ -0,0 +1,53 @@
+import { UIMatch, useMatches } from "react-router";
+import { routes } from "~/routes";
+
+/**
+ * Returns the child routes for a given route ID.
+ *
+ * @param id - The ID of the parent route to look up, must be present in `ROUTE_IDS`.
+ * @returns An array of child route objects, or an empty array if none are found.
+ */
+export function useChildRoutes(id?: string) {
+  const matches = useMatches();
+
+  for (const currentMatch of matches.reverse()) {
+    const childRoutes = _resolveChildRoutes(id, currentMatch);
+    if (childRoutes.length) {
+      return childRoutes;
+    }
+  }
+  return [];
+}
+
+/**
+ * Returns the child routes for a given route ID.
+ *
+ * @param id - The ID of the parent route to look up, must be present in `ROUTE_IDS`.
+ * @param currentMatch - The current React Router match.
+ * @param haystack - Used internally when this hooks recurses to find a nested route.
+ * @returns An array of child route objects, or an empty array if none are found.
+ */
+function _resolveChildRoutes(
+  id: string | undefined,
+  currentMatch: UIMatch | undefined,
+  haystack = routes,
+) {
+  const _id = typeof id === "undefined" ? currentMatch?.id || "" : id;
+
+  // if (Object.values(ROUTE_IDS).includes(_id)) {
+  const currentRoute = haystack.find((route) => route.id === _id);
+  if (currentRoute) {
+    return currentRoute.children || [];
+  }
+
+  // Recurse through child routes.
+  const _haystack = haystack
+    .filter((route) => route.children?.length)
+    .flatMap((route) => route.children || []);
+
+  if (_haystack.length) {
+    return _resolveChildRoutes(_id, currentMatch, _haystack);
+  }
+  // }
+  return [];
+}

frontend/src/hooks/useChildRoutes.ts

@@ -0,0 +1,14 @@
+import { useMatches } from "react-router";
+
+/**
+ * Returns the deepest matched route from the current route hierarchy.
+ *
+ * Useful for accessing metadata such as `id`, `params`, `handle`, or route-specific data
+ * defined on the most specific (child) route in the current match.
+ *
+ * @returns The last matched route object, or `undefined` if no matches exist.
+ */
+export function useCurrentMatch() {
+  const matches = useMatches();
+  return [...matches].pop() as (typeof matches)[number];
+}

frontend/src/hooks/useCurrentMatch.ts

@@ -2,7 +2,7 @@ import { redirect } from "react-router";
 import { vi } from "vitest";
 import { loginRequired } from "~/loaders/loginRequired.loader.ts";
 
-vi.mock("react-router-dom", () => ({
+vi.mock("react-router", () => ({
   redirect: vi.fn(),
 }));