rework plugins (#187)

Author: mattallty

.changeset/cool-students-look.md

@@ -0,0 +1,7 @@
+---
+"@enpage/template-example": patch
+"@enpage/editor": patch
+"@enpage/sdk": patch
+---
+
+Rework plugins

packages/editor/README.md

@@ -1,30 +1 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
-
-- Configure the top-level `parserOptions` property like this:
-
-```js
-export default {
-  // other rules...
-  parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.node.json'],
-    tsconfigRootDir: __dirname,
-  },
-}
-```
-
-- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
-- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
+# Enpage Editor Component

packages/sdk/INTERNALS.md

@@ -26,6 +26,41 @@ Table of differences between the 3 environments:
 The HTML document itself is the source of truth for the editor state.
 Liquid tags are used to define loops, conditions, and other logic in the HTML document.
 
+## Server-side rendering
+
+### Flow
+
+The SSR flow is composed of 3 main steps:
+
+1. Incoming Request
+2. Page Config handler: retrieves the page configuration including context (attributes and data sources)
+  - In dev mode, the page configuration is loaded from the virtual file `virtual:enpage-page-config.json`
+  - In local-preview mode, the page configuration is loaded from cache or from enpage.config.js (the local-preview is a node environment)
+  - In production mode, the page configuration is fetched from the API
+3. Render handler: renders the HTML document using the page configuration
+  - In dev mode, renderer is loaded from the virtual `virtual:vite-entry-server` file
+  - In production/local-preview mode, the renderer is loaded from the real vite-entry-server file
+  - The render function returns the HTML document and the state. Those are then merged and returned to the client.
+
+## Vite
+
+### Flow
+
+The `vite-config.ts` is the equivalent of the `vite.config.js` file in a Vite project. It only load the enpage plugin.
+
+### Vite plugins:
+
+- enpage meta: loads all enpage plugins
+- enpage: main plugin defining the vite config
+- enpage:virtual-files: plugin to handle virtual files. Hooks used: `resolveId`, `load`. It returns the content of the virtual files:
+  - `virtual:enpage-template:index.html`: the main index.html template file
+  - `virtual:vite-entry-server`: the entry server file
+  - `virtual:enpage-page-config.json`: returns  a virtual json file containing the GenericPageConfig.
+- enpage:context: plugin to handle the PageContext. In dev mode, it generates a fake context. In non-ssr build mode, it fetches the context from the server. Hooks used: `config`. It adds the
+`enpageContext` property (of type `PageContext`) to the vite config.
+- enpage:render: plugin to handle the rendering of the main index.html file. It uses the transformIndexHtml hook to render the HTML document using the page context. Hooks used: `transformIndexHtml`, `configureServer`.
+- enpage:base-url (dev only): plugin to handle the base URL of the website. It uses the transformIndexHtml hook to inject the base URL in the HTML document. Hooks used: `transformIndexHtml`, `configureServer`.
+- enpage:manifest: plugin to handle the manifest file. It uses the `generateBundle` hook to generate the enpage.manifest.json file.
 
 ## Rendering flow
 

packages/sdk/env.d.ts

@@ -5,7 +5,8 @@ import type { CloudflareWorkersPlatformInfo } from "@hattip/adapter-cloudflare-w
 declare global {
   interface Window {
     enpage: import("./src/browser/js-api").EnpageJavascriptAPI;
-    __ENPAGE_STATE__: ConstructorParameters<typeof import("./src/browser/js-api").EnpageJavascriptAPI>;
+    __ENPAGE_STATE__: import("./src/browser/js-api").State;
+    __ENPAGE_ROUTING__: import("./src/browser/js-api").Routing;
   }
 }
 

packages/sdk/package.json

@@ -75,6 +75,7 @@
     "postcss-preset-env": "10.0.2",
     "rimraf": "6.0.1",
     "rollup-plugin-strip-banner": "3.1.0",
+    "serve-favicon": "2.5.0",
     "sharp": "0.33.5",
     "svgo": "3.3.2",
     "tailwindcss": "3.4.10",
@@ -98,6 +99,7 @@
     "@types/jsdom": "21.1.7",
     "@types/lodash-es": "4.17.12",
     "@types/node": "^20.14.10",
+    "@types/serve-favicon": "2.5.7",
     "concurrently": "8.2.2",
     "tsup": "8.2.4"
   },

packages/sdk/src/browser/js-api.ts

@@ -1,15 +1,23 @@
-import type { PageContext } from "../shared/page-context";
+import type { PageContext } from "../shared/page-config";
 import type { NavigateEvent } from "./events";
 
+export type State = {
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  ctx: PageContext<any, any>;
+  pageIndex: number;
+};
+
 export class EnpageJavascriptAPI extends EventTarget {
+  private _totalPages: number;
+
   constructor(
-    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-    private ctx: PageContext<any, any>,
-    private pageIndex = 0,
-    private pagesCount = 1,
-    private pagesSlugs: string[] = [],
+    private state: State,
+    private _slugs: string[] = [],
   ) {
     super();
+    this._totalPages = this.slugs.length
+      ? this.slugs.length + 1
+      : Array.from(document.querySelectorAll("body > section")).length;
     this.setupListeners();
   }
 
@@ -18,10 +26,14 @@ export class EnpageJavascriptAPI extends EventTarget {
       const evt = e as NavigateEvent;
       const oldIndex = evt.detail.from;
       const newIndex = evt.detail.to;
-      const slug = this.pagesSlugs.at(newIndex - 1);
+      const slug = this.slugs.at(newIndex - 1);
 
-      this.pageIndex = newIndex;
-      history.pushState({ page: newIndex }, "", newIndex === 0 ? "/" : slug ? `/${slug}` : undefined);
+      this.state.pageIndex = newIndex;
+      history.pushState(
+        { page: newIndex },
+        "",
+        newIndex === 0 ? "/" : slug ? `/${slug}` : `/page-${newIndex}`,
+      );
 
       this.dispatchEvent(
         new CustomEvent("afternavigate", {
@@ -33,15 +45,15 @@ export class EnpageJavascriptAPI extends EventTarget {
   }
 
   get currentPage() {
-    return this.pageIndex;
+    return this.state.pageIndex;
   }
 
   get totalPages() {
-    return this.pagesCount;
+    return this._totalPages;
   }
 
   get context() {
-    return this.ctx;
+    return this.state.ctx;
   }
 
   nextPage() {
@@ -69,7 +81,7 @@ export class EnpageJavascriptAPI extends EventTarget {
   }
 
   goToPage(index: number) {
-    if (index < 0 || index >= this.pagesCount) {
+    if (index < 0 || index >= this.totalPages) {
       throw new RangeError(`Invalid page index: ${index}`);
     }
     this.dispatchEvent(
@@ -94,23 +106,23 @@ export class EnpageJavascriptAPI extends EventTarget {
   lastPage() {
     this.dispatchEvent(
       new CustomEvent("beforenavigate", {
-        detail: { from: this.currentPage, to: this.pagesCount - 1 },
+        detail: { from: this.currentPage, to: this.totalPages - 1 },
         bubbles: true,
         cancelable: true,
       }),
     );
   }
 
   get canGoBack() {
-    return this.pageIndex > 0;
+    return this.state.pageIndex > 0;
   }
 
   get canGoForward() {
-    return this.pageIndex < this.pagesCount - 1;
+    return this.state.pageIndex < this.totalPages - 1;
   }
 
   get slugs() {
-    return this.pagesSlugs;
+    return this._slugs;
   }
 
   async saveDataRecord(dataRecordId: string, record: Record<string, unknown>) {

packages/sdk/src/browser/page-sections.ts

@@ -0,0 +1,51 @@
+/**
+ * Retrieves all page sections from the document.
+ * @param {Document} doc - The document to search for sections.
+ */
+export function getPageSections(doc: Document) {
+  const sections = doc.querySelectorAll("body > section[ep-type='page']");
+  return sections;
+}
+/**
+ * Processes page sections, setting attributes and generating slugs.
+ * @param {NodeListOf<Element>} sections - The list of section elements to process.
+ */
+export function processPageSections(sections: NodeListOf<Element>) {
+  const slugs: string[] = [];
+  sections.forEach((section, index) => {
+    section.setAttribute("ep-label", `Page ${index + 1}`);
+    if (!section.getAttribute("id")) {
+      section.setAttribute("id", `page-${index + 1}`);
+    }
+    if (!section.getAttribute("ep-animate-appear")) {
+      section.setAttribute("ep-animate-appear", "fadeIn");
+    }
+    if (!section.getAttribute("ep-animate-disappear")) {
+      section.setAttribute("ep-animate-disappear", "fadeOut");
+    }
+    // add [ep-editable] if not present
+    if (!section.getAttribute("ep-editable")) {
+      section.setAttribute("ep-editable", "");
+    }
+    // hide all sections except the first one
+    if (index > 0) {
+      section.setAttribute("hidden", "");
+      let slug = section.getAttribute("ep-slug");
+      if (!slug) {
+        slug = `page-${index + 1}`;
+        section.setAttribute("ep-slug", slug);
+      }
+      slugs.push(slug);
+    } else {
+      // make sure the first section has role="main"
+      section.setAttribute("role", "main");
+      // make sure the first section has no slug
+      section.removeAttribute("ep-slug");
+      // hide it by default if it as an animation
+      if (section.hasAttribute("ep-animate-appear")) {
+        section.setAttribute("hidden", "");
+      }
+    }
+  });
+  return { slugs, pageCount: sections.length };
+}

packages/sdk/src/browser/vite-entry-client.ts

@@ -1,5 +1,6 @@
 import { EnpageJavascriptAPI } from "./js-api";
-if (window.__ENPAGE_STATE__) {
-  console.debug("Loading Enpage Javascript API...");
-  window.enpage = new EnpageJavascriptAPI(...window.__ENPAGE_STATE__);
-}
+import { getPageSections, processPageSections } from "./page-sections";
+const sections = getPageSections(document);
+const { slugs } = processPageSections(sections);
+console.debug("Loading Enpage Javascript API...");
+window.enpage = new EnpageJavascriptAPI(window.__ENPAGE_STATE__, slugs);

packages/sdk/src/node/builder/context.ts renamed to packages/sdk/src/node/builder/page-context.ts

@@ -1,5 +1,5 @@
 import type { EnpageTemplateConfig } from "~/shared/template-config";
-import type { PageContext } from "~/shared/page-context";
+import type { PageContext } from "~/shared/page-config";
 import { samples } from "~/shared/datasources/samples";
 import type { AttributesResolved } from "~/shared/attributes";
 import invariant from "~/shared/utils/invariant";
@@ -22,8 +22,9 @@ export function createFakeContext<Config extends EnpageTemplateConfig>(cfg: Conf
 
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   const attributes: AttributesResolved<any> = {};
-  for (const key in cfg.attributes) {
-    attributes[key] = cfg.attributes[key].defaultValue;
+
+  for (const key in cfg.attributes.properties) {
+    attributes[key] = cfg.attributes.properties[key].default;
   }
 
   return { data, attr: attributes } as PageContext<typeof cfg.datasources, typeof cfg.attributes>;

packages/sdk/src/node/builder/plugin-context.ts

@@ -1,9 +1,8 @@
 import type { EnpageTemplateConfig } from "~/shared/template-config";
 import type { ConfigEnv, Plugin } from "vite";
-import type { PageContext } from "~/shared/page-context";
-import { createFakeContext, fetchContext } from "./context";
+import type { PageContext } from "~/shared/page-config";
+import { createFakeContext, fetchContext } from "./page-context";
 import type { EnpageEnv } from "~/shared/env";
-import type { Logger } from "../shared/logger";
 
 export const contextPlugin = (cfg: EnpageTemplateConfig, viteEnv: ConfigEnv, env: EnpageEnv): Plugin => {
   const isBuildMode = viteEnv.command === "build";
@@ -23,7 +22,7 @@ export const contextPlugin = (cfg: EnpageTemplateConfig, viteEnv: ConfigEnv, env
 
       // If in dev mode, use fake context
       if (!isBuildMode) {
-        // console.warn("Using fake context.");
+        console.warn("Using fake context.");
         context = createFakeContext(cfg);
         // If in build mode, fetch context from API if not SSR build
       } else if (!isSsrBuild) {