JNG-4463 pandino integration with initial customizations (#16)

* JNG-4463: migrate l10n abstraction

* JNG-4463: add pandino with customizable routes

* JNG-4463: add customization for pages / l10n provider plus docs

* JNG-4463: fix default customizer

* JNG-4463: fix review items

README.adoc

@@ -179,6 +179,11 @@ This example generates a complete application into the `target/frontend-react` d
 The `judo-ui-generator-maven-plugin` documentation is placed inside
 the plugin documentation itself. https://github.com/BlackBeltTechnology/judo-meta-ui/tree/develop/generator-maven-plugin
 
+## Documentation
+
+Detailed documentation for the generated apps and how to maintain / modify them can be found under
+link:{docdir}/docs/pages[docs/pages] folder.
+
 ## Notes
 
 The `maven-dependency-plugin` copies repackaged dependencies from the module `judo-ui-react-external-packages`.

docs/pages/00_intro.adoc

@@ -0,0 +1,11 @@
+= Introduction
+ifndef::env-site,env-github[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+:icons: font
+:KW: [purple]##**
+:KWE: **##
+
+JUDO React frontend generator templates and utilities / libraries.

docs/pages/01_ui_react.adoc

@@ -0,0 +1,130 @@
+= UI React
+ifndef::env-site,env-github[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+:icons: font
+:KW: [purple]##**
+:KWE: **##
+
+JUDO React frontend generator templates.
+
+== Architecture
+
+WIP
+
+=== Fixed dependency versions and the map.json file
+
+In order for projects to be consistently re-built without changing versions and effective version mismatches, we fixed
+in all dependency versions, and are providing a `pnpm.lock` file as well.
+
+Without fix versions, and a reproducible lock file, the dependency versions in `map.json` could differ, causing runtime
+errors.
+
+== Customization
+
+There are two major ways how JUDO apps can be customized with various pros / cons:
+
+- Template overrides
+- Providing custom implementations for certain interfaces
+
+Customization via template overrides is discussed at the https://github.com/BlackBeltTechnology/judo-meta-ui/tree/develop/generator-maven-plugin[ judo-meta-ui/generator-maven-plugin]
+repository.
+
+In this documentation we will only discuss customization via interface implementation.
+
+=== Context
+
+JUDO frontend applications utilize the https://github.com/BlackBeltTechnology/pandino[Pandino] library. This library can
+be considered as a "dependency injection framework on steroids".
+
+For details about Pandino, please check its corresponding documentation.
+
+Regardless of documentation, the fastest way of figuring out what interfaces can be re-implemented is by searching for:
+
+- `ComponentProxy` components
+- `useTrackService<T>()` hooks
+
+All of these usually consume at least a `filter` parameter and where applicable refer to a `T` generic type.
+
+> All customizable interfaces have a `string` representation (INTERFACE_KEY) since at the end of the day, JavaScript doesn't support
+  interfaces and we need to pair them up.
+
+=== First step
+
+The entry point for registering implementations is `src/custom/application-customizer.tsx`.
+
+[WARNING]
+====
+This file MUST be put into the `.generator-ignore` file and should be added to Git, otherwise whatever we put into it
+will be replaced by the generator.
+====
+
+You may put your implementations anywhere inside the project, the only purpose of the `application-customizer.tsx` file
+is to be the entry point for registration.
+
+=== Implementing pages
+
+Interface keys for pages can be found at `src/routes.tsx` with their actual implementation pairs next to them.
+
+[source,typescriptjsx]
+----
+import type { FC } from 'react';
+import type { BundleContext } from '@pandino/pandino-api';
+import { ApplicationCustomizer } from './interfaces';
+import { ROUTE_GOD_GALAXIES_TABLE_INTERFACE_KEY } from '../routes';
+
+export class DefaultApplicationCustomizer implements ApplicationCustomizer {
+  async customize(context: BundleContext): Promise<void> {
+    context.registerService<FC>(ROUTE_GOD_GALAXIES_TABLE_INTERFACE_KEY, CustomGalaxies);
+  }
+}
+
+export const CustomGalaxies = () => {
+  return (
+    <div className="galaxies">
+      <img src="https://c.tenor.com/rtnshG9YFykAAAAM/rick-astley-rick-roll.gif" />
+    </div>
+  );
+};
+----
+
+=== Implementing the localization loader
+
+The localization loader is responsible for loading the translations for the application.
+
+We need to implement the `L10NTranslationProvider` interface (`L10N_TRANSLATION_PROVIDER_INTERFACE_KEY`).
+
+[source,typescriptjsx]
+----
+import type { BundleContext } from '@pandino/pandino-api';
+import { ApplicationCustomizer } from './interfaces';
+import {
+  L10N_TRANSLATION_PROVIDER_INTERFACE_KEY,
+  L10NTranslationProvider,
+  L10NTranslations,
+} from '../l10n/l10n-context';
+
+export class DefaultApplicationCustomizer implements ApplicationCustomizer {
+  async customize(context: BundleContext): Promise<void> {
+    context.registerService(L10N_TRANSLATION_PROVIDER_INTERFACE_KEY, new CustomL10NProvider());
+  }
+}
+
+class CustomL10NProvider implements L10NTranslationProvider {
+  async provideTranslations(locale: string): Promise<L10NTranslations> {
+    return Promise.resolve({
+      systemTranslations: {
+        'judo.pages.create': 'My Create Label',
+        // ...
+      },
+      applicationTranslations: {
+        'God.galaxies.View.group.group.2.group.2.constellation': 'cOnStElLaTiOn',
+        // ...
+      },
+    });
+  }
+}
+----
+

docs/pages/02_react_external_packages.adoc

@@ -0,0 +1,15 @@
+= React External Packages
+ifndef::env-site,env-github[]
+endif::[]
+// Settings
+:idprefix:
+:idseparator: -
+:icons: font
+:KW: [purple]##**
+:KWE: **##
+
+Repackaged third-party dependencies used by JUDO React frontend apps / generators.
+
+== Process
+
+WIP

docs/pom.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+    <parent>
+    	<artifactId>hu.blackbelt.judo.generator</artifactId>
+		<groupId>judo-ui-react-template</groupId>
+        <version>${revision}</version>
+	</parent>
+
+    <artifactId>judo-ui-react-template-docs</artifactId>
+    <name>JUDO UI React Frontend Generator Documentation</name>
+
+    <packaging>jar</packaging>
+
+    <build>
+        <resources>
+            <resource>
+                <directory>${basedir}</directory>
+                <includes>
+                    <include>pages/</include>
+<!--                    <include>_attributes.adoc</include>-->
+                </includes>
+            </resource>
+        </resources>
+
+        <plugins>
+            <plugin>
+                <groupId>org.apache.felix</groupId>
+                <artifactId>maven-bundle-plugin</artifactId>
+                <version>5.1.8</version>
+                <extensions>true</extensions>
+                <configuration>
+                    <obrRepository>NONE</obrRepository>
+                    <instructions>
+                        <Include-Resource>{maven-resources}</Include-Resource>
+                    </instructions>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

judo-ui-react/src/main/java/hu/blackbelt/judo/ui/generator/react/UiPandinoHelper.java

@@ -0,0 +1,12 @@
+package hu.blackbelt.judo.ui.generator.react;
+
+import hu.blackbelt.judo.generator.commons.annotations.TemplateHelper;
+import lombok.extern.java.Log;
+
+@Log
+@TemplateHelper
+public class UiPandinoHelper {
+    public static String camelCaseNameToInterfaceKey(String name) {
+        return name.replaceAll("([a-z])([A-Z]+)", "$1_$2").toUpperCase();
+    }
+}

judo-ui-react/src/main/resources/actor/package.json.dependencies.fragment.hbs

@@ -5,6 +5,9 @@
 "@mui/material": "5.11.4",
 "@mui/x-data-grid": "5.17.18",
 "@mui/x-date-pickers": "5.0.13",
+"@pandino/loader-configuration-dom": "0.8.26",
+"@pandino/pandino": "0.8.26",
+"@pandino/react-hooks": "0.8.26",
 "@remix-run/router": "1.1.0",
 "axios": "1.2.1",
 "dayjs": "1.11.7",

judo-ui-react/src/main/resources/actor/package.json.dev-dependencies.fragment.hbs

@@ -1,4 +1,5 @@
 "@judo/data-api-common": "0.4.2",
+"@pandino/pandino-api": "0.8.26",
 "@rollup/plugin-commonjs": "24.0.0",
 "@rollup/plugin-node-resolve": "15.0.1",
 "@rollup/plugin-replace": "5.0.2",

judo-ui-react/src/main/resources/actor/public/map.json

@@ -1,5 +1,9 @@
 {
   "imports": {
+    "@pandino/loader-configuration-dom": "./externals/@pandino/[email protected]/dist/system/loader-configuration-dom.min.js",
+    "@pandino/pandino": "./externals/@pandino/[email protected]/dist/system/pandino.min.js",
+    "@pandino/pandino-api": "./externals/@pandino/[email protected]/dist/system/pandino-api.min.js",
+    "@pandino/react-hooks": "./externals/@pandino/[email protected]/dist/system/react-hooks.min.js",
     "dayjs": "./externals/[email protected]/dayjs.min.js",
     "dayjs/locale/hu": "./externals/[email protected]/locale/hu.js",
     "react/jsx-runtime": "./externals/react/[email protected]/umd/react-jsx-runtime.min.js",

judo-ui-react/src/main/resources/actor/rollup.config.mjs.hbs

@@ -47,6 +47,10 @@ export default [
                         ['react', '/umd'],
                         ['react-dom', '/umd'],
                         ['i18next', '/dist/umd'],
+                        ['@pandino/loader-configuration-dom', '/dist/system'],
+                        ['@pandino/pandino', '/dist/system'],
+                        ['@pandino/pandino-api', '/dist/system'],
+                        ['@pandino/react-hooks', '/dist/system'],
                         ['react-i18next', '/dist/umd'],
                         ['@remix-run/router', '/dist'],
                         ['react-router', '/dist/umd'],