Support transforming and serving JS files (#27)

* wip: support transforming and serving JS files

* adjustments

Author: zth

README.md

@@ -59,7 +59,11 @@ import { defineConfig } from "vite";
 import { resXVitePlugin } from "rescript-x";
 
 export default defineConfig({
-  plugins: [resXVitePlugin()],
+  plugins: [
+    resXVitePlugin({
+      clientDirs: ["client"],
+    }),
+  ],
   server: {
     port: 9000,
   },
@@ -326,7 +330,7 @@ GET /assets/logo.svg
 
 ### `assets` for assets that do need transformation
 
-If you have assets you'd like transformed by Vite before using, put them in the top level `assets` folder. This could be CSS, images, additional JavaScript, and so on. Anything you might want Vite to transform.
+If you have assets you'd like transformed by Vite before using, put them in the top level `assets` folder. This could be CSS, images, or browser entry JavaScript. Anything you might want Vite to transform.
 
 Here's an example of how you wire up Tailwind:
 
@@ -347,6 +351,81 @@ Then, include it in your ReScript:
 
 There! It's now available to you, and Vite will both transform and hot module reload the asset if it's possible.
 
+#### Thinking about client side JavaScript
+
+ResX is server-first. The default is:
+
+- Render HTML on the server.
+- Reach for normal links, forms and handlers first.
+- Use HTMX or `ResX.Client` when declarative browser behavior is enough.
+- Add your own browser JavaScript only when you actually need code running in the browser.
+
+When you do need browser JavaScript, think in terms of browser entry modules, not loose script files. An entry module is the file you include from HTML. That file can then import whatever else it needs, and Vite will handle transformation, minification, hashing, CSS extraction, and shared chunks in production.
+
+There are two intended places for those entry modules:
+
+- Put small app-local entry files in top level `assets/` when they sit naturally next to your other transformed assets.
+- Configure `clientDirs` when you want a dedicated folder for browser code, for example `client/`.
+
+Top level JS and TS files in `assets/` become browser entries automatically. They are exposed through `ResXAssets.assets` and should be loaded as module scripts:
+
+```rescript
+<script type_="module" src={ResXAssets.assets.analytics_js} />
+```
+
+If you want browser entry files outside `assets/`, configure `clientDirs` in `resXVitePlugin`. Files found there are also exposed through `ResXAssets.assets`, prefixed by directory name:
+
+```js
+// vite.config.js
+import { defineConfig } from "vite";
+import resXVitePlugin from "rescript-x/res-x-vite-plugin.mjs";
+
+export default defineConfig({
+  plugins: [
+    resXVitePlugin({
+      clientDirs: ["client"],
+    }),
+  ],
+});
+```
+
+```rescript
+<script type_="module" src={ResXAssets.assets.client__admin_ts} />
+```
+
+The recommended structure is:
+
+- Keep entry files at the top level of `assets/` or each configured `clientDirs` folder.
+- Put shared support modules in subdirectories and import them from those entries.
+- Import CSS from the entry module when that CSS belongs to that client behavior.
+
+For example:
+
+```text
+assets/
+  analytics.js
+client/
+  admin.ts
+  admin.css
+  shared/
+    markLoaded.ts
+```
+
+```ts
+// client/admin.ts
+import "./admin.css";
+import {markLoaded} from "./shared/markLoaded";
+
+document.body.classList.add("client-admin-loaded");
+markLoaded(document.body, "admin-loaded");
+```
+
+Any CSS imported from those browser entries is emitted and loaded automatically in both development and production.
+
+By default, only top level JS and TS files in `assets/` and each configured `clientDirs` folder become entries. Put shared support modules in subdirectories and import them from those entries so Vite can emit shared chunks for them. If you want a different discovery rule, set `assetEntryGlobs` and `clientEntryGlobs`.
+
+Current limitation: this pipeline expects browser entries to be JavaScript or TypeScript by the time Vite sees them. Direct `.res` entry files are not part of this flow. If you want to write client code in ReScript, compile it to JS first and then point `clientDirs` or `extraClientEntries` at that generated JS.
+
 #### Referring to transformed `assets`
 
 Notice how we're not using a `"/assets/styles.css"` string to refer to `styles.css`, but rather `ResXAssets.assets.styles_css`? This is because ResX comes with a "type safe" asset layer - anything you put in `assets/` will be available via `ResXAssets.assets`.
@@ -684,10 +763,12 @@ These functions should only be used in exceptional cases where you need to:
 
 ResX also ships with a tiny client side library that will help you do basic client side tasks fully declaratively. It's quite basic at the moment, but will be extended (tastefully) as we discover more places where it can help you avoid having to use a full blown client side framework to accomplish fairly basic tasks.
 
+The browser bundle for this is shipped with `rescript-x`, so you can reference `ResXAssets.assets.resXClient_js` directly without adding your own `extraClientEntries` config.
+
 To use ResX client, make sure you include its script:
 
 ```rescript
-<script src={ResXAssets.assets.resXClient_js} async=true />
+<script type_="module" src={ResXAssets.assets.resXClient_js} async=true />
 ```
 
 #### Handling CSS classes on events

client/ResXClient.js

@@ -0,0 +1,106 @@
+// Built browser entry for ResX.Client.
+// Source of truth: src/ResXClient.res
+// Regenerate with: npm run build:resx-client
+
+function init() {
+  let getTarget = (target, $$this) => {
+    if (typeof target !== "object") {
+      return $$this;
+    } else {
+      return document.querySelector(target.selector);
+    }
+  };
+  let handleAction = (action, $$this) => {
+    let target;
+    target = action.kind === "CopyToClipboard" ? null : getTarget(action.target, $$this);
+    if (target === null) {
+      if (action.kind !== "CopyToClipboard") {
+        return;
+      }
+      let onAfterFailure = action.onAfterFailure;
+      let onAfterSuccess = action.onAfterSuccess;
+      navigator.clipboard.writeText(action.text).catch(param => {
+        if (onAfterFailure !== undefined) {
+          return Promise.resolve((onAfterFailure.forEach(action => handleAction(action, $$this)), undefined));
+        } else {
+          return Promise.resolve();
+        }
+      }).then(() => {
+        if (onAfterSuccess !== undefined) {
+          onAfterSuccess.forEach(action => handleAction(action, $$this));
+          return;
+        }
+      });
+      return;
+    }
+    switch (action.kind) {
+      case "ToggleClass" :
+        action.className.split(" ").forEach(className => target.classList.toggle(className));
+        return;
+      case "RemoveClass" :
+        action.className.split(" ").forEach(className => target.classList.remove(className));
+        return;
+      case "AddClass" :
+        action.className.split(" ").forEach(className => target.classList.add(className));
+        return;
+      case "SwapClass" :
+        action.fromClassName.split(" ").forEach(className => target.classList.remove(className));
+        action.toClassName.split(" ").forEach(className => target.classList.add(className));
+        return;
+      case "RemoveElement" :
+        return target.remove();
+      case "CopyToClipboard" :
+        return;
+    }
+  };
+  document.addEventListener("click", event => {
+    let $$this = event.target;
+    let match = $$this.attributes["resx-onclick"];
+    let actions = match !== undefined ? JSON.parse(match.value) : [];
+    actions.forEach(action => handleAction(action, $$this));
+  });
+  document.addEventListener("invalid", event => {
+    let $$this = event.target;
+    let match = $$this.validity;
+    let match$1 = $$this.attributes["resx-validity-message"];
+    if (match === undefined) {
+      return;
+    }
+    if (match.valid) {
+      return;
+    }
+    if (match$1 === undefined) {
+      return;
+    }
+    let validityMessages = JSON.parse(match$1.value);
+    let messageToSet = match.badInput ? validityMessages.badInput : (
+        match.patternMismatch ? validityMessages.patternMismatch : (
+            match.rangeOverflow ? validityMessages.rangeOverflow : (
+                match.rangeUnderflow ? validityMessages.rangeUnderflow : (
+                    match.stepMismatch ? validityMessages.stepMismatch : (
+                        match.tooLong ? validityMessages.tooLong : (
+                            match.tooShort ? validityMessages.tooShort : (
+                                match.typeMismatch ? validityMessages.typeMismatch : (
+                                    match.valueMissing ? validityMessages.valueMissing : undefined
+                                  )
+                              )
+                          )
+                      )
+                  )
+              )
+          )
+      );
+    if (messageToSet !== undefined) {
+      return $$this.setCustomValidity(messageToSet);
+    }
+  }, true);
+  document.addEventListener("change", event => {
+    let $$this = event.target;
+    let match = $$this.attributes["resx-validity-message"];
+    if (match !== undefined) {
+      return $$this.setCustomValidity("");
+    }
+  });
+}
+
+init();

demo/assets/analytics.js

@@ -0,0 +1,3 @@
+import {markLoaded} from "../client/shared/markLoaded";
+
+markLoaded(document.documentElement, "analytics-loaded");

demo/client/admin.css

@@ -0,0 +1,3 @@
+.client-admin-loaded {
+  box-shadow: inset 0 0 0 4px #0f766e;
+}

demo/client/admin.ts

@@ -0,0 +1,5 @@
+import "./admin.css";
+import {markLoaded} from "./shared/markLoaded";
+
+document.body.classList.add("client-admin-loaded");
+markLoaded(document.body, "admin-loaded");

demo/client/shared/markLoaded.ts

@@ -0,0 +1,10 @@
+const sharedState = window as typeof window & {
+  __resxMarkLoadedModuleCount?: number;
+};
+
+sharedState.__resxMarkLoadedModuleCount =
+  (sharedState.__resxMarkLoadedModuleCount || 0) + 1;
+
+export function markLoaded(node: HTMLElement, value: string) {
+  node.dataset.sharedLoaded = value;
+}

demo/src/Html.js

@@ -8,7 +8,9 @@ let make = (~children) => {
       {children}
       <ResX.Dev />
       <script src="https://unpkg.com/htmx.org@1.9.5" />
-      <script src={ResXAssets.assets.resXClient_js} async=true />
+      <script type_="module" src={ResXAssets.assets.analytics_js} />
+      <script type_="module" src={ResXAssets.assets.client__admin_ts} />
+      <script type_="module" src={ResXAssets.assets.resXClient_js} async=true />
     </body>
   </html>
 }

demo/src/Html.res

@@ -2,7 +2,11 @@ import { defineConfig } from "vite";
 import resXVitePlugin from "../res-x-vite-plugin.mjs";
 
 export default defineConfig({
-  plugins: [resXVitePlugin()],
+  plugins: [
+    resXVitePlugin({
+      clientDirs: ["client"],
+    }),
+  ],
   server: {
     port: 9000,
   },