elegance-js 1.13.0 → 1.14.1

package/dist/global.d.ts

@@ -27,10 +27,7 @@ declare global {
         children: null;
         options: Record<string, any> | Child;
     };
-    type PageOptions = {
-        build: "once" | "interval" | "request";
-    };
-    type Page = (AnyBuiltElement) | (() => AnyBuiltElement);
+    type Page = (AnyBuiltElement) | (() => AnyBuiltElement) | (() => Promise<AnyBuiltElement>);
     type ObjectAttribute<T> = T extends ObjectAttributeType.STATE ? {
         type: ObjectAttributeType;
         id: string | number;

package/dist/page_compiler.mjs

@@ -646,6 +646,12 @@ var generateClientPageData = async (pageLocation, state, objectAttributes, pageL
     console.error("Failed to transform client page js!", error);
   });
   if (!transformedResult) return { sendHardReloadInstruction };
+  if (fs.existsSync(pageDataPath)) {
+    const content = fs.readFileSync(pageDataPath).toString();
+    if (content !== transformedResult.code) {
+      sendHardReloadInstruction = true;
+    }
+  }
   fs.writeFileSync(pageDataPath, transformedResult.code, "utf-8");
   return { sendHardReloadInstruction };
 };
@@ -730,7 +736,7 @@ return __exports
     console.warn(`WARNING: ${filePath} should export a const page, which is of type () => BuiltElement<"body">.`);
   }
   if (typeof pageElements === "function") {
-    if (pageElements.constructor.name === "AsyncFunctino") {
+    if (pageElements.constructor.name === "AsyncFunction") {
       pageElements = await pageElements();
     } else {
       pageElements = pageElements();

package/dist/server/state.d.ts

@@ -19,7 +19,7 @@ type ReactiveMap<T extends any[], D extends Dependencies> = (this: {
     bind: string | undefined;
 }, template: (item: T[number], index: number, ...deps: {
     [K in keyof D]: ClientSubjectGeneric<D[K]>["value"];
-}) => Child, deps: [...D]) => Child;
+}) => Child, deps?: [...D]) => Child;
 type Dependencies = {
     type: ObjectAttributeType;
     value: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elegance-js",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "description": "Web-Framework",
   "type": "module",
   "bin": {

package/scripts/bootstrap.js

@@ -7,7 +7,7 @@ import { execSync } from "node:child_process";
 
 execSync("npm install tailwindcss @tailwindcss/cli");
 
-const dirs = ["pages", "public"];
+const dirs = ["pages", "public", "pages/components"];
 dirs.forEach((dir) => {
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 });
@@ -18,12 +18,34 @@ const envDtsPath = "env.d.ts";
 const tsconfigPath = "tsconfig.json";
 
 const pageTsContent = `
-import { eventListener, state } from "elegance-js/server/state";
-import { loadHook } from "elegance-js/server/loadHook";
-import { observe } from "elegance-js/server/observe";
+import { observe, loadHook, eventListener, state } from "elegance-js";
 
+/*
+    This is state.
+    It uses a simple observer model in the browser (see the observer function)
+    
+    You can update it's value using state.value, and when you want the observers
+    of said state to refresh, call state.signal().
+    
+    You can update the state to whatever value you want it to be,
+    before the page is finished building.
+    
+    Once the page is built, all state values are shipped to the browser as-is.
+*/
 const counter = state(0);
 
+/*
+    The server keeps track of every call to the loadHook() function,
+    does some preprocessing, and ships the loadhook to the browser.
+    The browser, after the page loads, runs the content of the function (the second paramater)
+    passed into the loadHook call.
+    
+    Loadhook takes in as it's first parameter, a dependency list of state()'s that
+    the loadHook can then reference in the browser.
+    
+    For newbies, note that the content of loadHook is *browser code*, and thus
+    cannot be trusted!
+*/
 loadHook(
     [counter],
     (_, counter) => {
@@ -36,57 +58,160 @@ loadHook(
     },
 )
 
-export const page = body ({
-    class: "text-white flex min-h-screen items-start sm:justify-center p-4 bg-black flex-col gap-4 max-w-[500px] w-full mx-auto",
-},
-    h1 ({
-        class: "text-4xl font-inter font-semibold bg-clip-text text-transparent bg-gradient-to-tl from-[#EEB844] to-[#FF4FED] oveflow-clip",
-    },
-        "Welcome to Elegance.JS!",
-    ),
+/*
+    This variable lets you determine whether your page is:
+    1. Built at compile time (non dynamic page).
+        Meaning, the page is turned into HTML, CSS and JS *once*, and then served statically.
+        
+    2. Built per-request (dynamic page).
+        Meaning the page is *transpiled into JS*, and then every time someone requests the page,
+        it is built and then served.
+*/
+export const isDynamicPage = true;
+
+/*
+    State can also be an array!
+    In which case, the reactiveMap() method is added onto the state.
+    This allows you to run client-side code, which dynamically changes
+    the page's HTML content based on the state of the array in the browser.
+*/
+const ReactiveMap = () => {
+    const arrayState = state([
+        "John","Mary","William","Kimberly",
+    ]);
     
-    p ({
-    }, 
-        "Edit page.ts to get started.",
-    ),
+    return arrayState.reactiveMap((item, index) => {
+        index += 1;
+        
+        return div({
+        },
+            index + ". ", item,
+        )
+    })
+};
+
+/*
+    This is the actual content of the page.
     
-    div({
-        class: "flex items-start gap-4 mt-2",
+    It does not *have* to be an async function.
+    Page can be any value, as long as it resolves into a Child (a built element, eg. string, a return value of an element creation call, etc)
+*/
+export const page: Page = async () => {
+    const pageName = state("Elegance.JS");
+    
+    /*
+        The below is an element creation function.
+        The syntax is roughly similar to how HTML works.
+        
+        A call like: h1("Hello World!")
+        
+        Would generate the HTML: <h1>Hello World!</h1>
+        
+        The first parameter to an element may be another element (child), or an options object.
+        
+        Options objects are used to set things like classNames, style, ids. etc.
+        
+        For example this call: h1({ 
+            id: "my-id", 
+        },
+            "Hello World!"
+        )
+        
+        Turns into this HTML: <h1 id="my-id">Hello World!</h1>
+    */
+    return body ({
+        class: "text-white flex min-h-screen items-start sm:justify-center p-4 bg-black flex-col gap-4 max-w-[500px] w-full mx-auto",
     },
-        a ({
-            class: "px-4 py-2 rounded-md bg-red-400 text-black font-semibold relative group hover:scale-[1.05] duration-200",
-            href: "https://elegance.js.org/",
-            target: "_blank",
+        h1 ({
+            class: "text-4xl font-inter font-semibold bg-clip-text text-transparent bg-gradient-to-tl from-[#EEB844] to-[#FF4FED] oveflow-clip",
         },
-            "Documentation",
-            
-            div ({
-                class: "blur-[50px] absolute group-hover:bg-red-400 inset-0 bg-transparent duration-200 pointer-events-none -z-10",
-                "aria-hidden": "true",
-            }),
+            \`Welcome to \${pageName.value}!\`,
         ),
-            
-        button ({
-            class: "hover:cursor-pointer px-4 py-2 rounded-md bg-zinc-200 text-black font-semibold relative group hover:scale-[1.05] duration-200",
-            onClick: eventListener(
-                [counter],
-                (_, counter) => {
-                    counter.value++;
+        
+        ReactiveMap(),
+        
+        p ({
+        }, 
+            "Edit page.ts to get started.",
+        ),
+        
+        div({
+            class: "flex items-start gap-4 mt-2",
+        },
+            a ({
+                class: "px-4 py-2 rounded-md bg-red-400 text-black font-semibold relative group hover:scale-[1.05] duration-200",
+                href: "https://elegance.js.org/",
+                target: "_blank",
+            },
+                "Documentation",
+                
+                div ({
+                    class: "blur-[50px] absolute group-hover:bg-red-400 inset-0 bg-transparent duration-200 pointer-events-none -z-10",
+                    "aria-hidden": "true",
+                }),
+            ),
+                
+            button ({
+                class: "hover:cursor-pointer px-4 py-2 rounded-md bg-zinc-200 text-black font-semibold relative group hover:scale-[1.05] duration-200",
+                /*
+                    Normally, element attributes can only be a string, number or boolean.
+                    
+                    However, exceptions are made for *object attributes*.
+                    These are special values that usually perform client-side actions.
+                    
+                    Take the below for example.
+                    The eventListener() takes in a dependency array, and a callback function.
+                    
+                    It then returns an ObjectAttribute of type EVENT_LISTENER.
                     
-                    counter.signal();
-                },
+                    The elegance-compiler, when it sees this, packs up the callback function and state references,
+                    and ships it to the page.
+                    
+                    The page, when it loads, then binds the eventListener callback to the corresponding event (in this case, "onclick").
+                    
+                    ObjectAttributes do not show up in HTML!
+                */
+                onClick: eventListener(
+                    [counter],
+                    (_, counter) => {
+                        counter.value++;
+                        
+                        counter.signal();
+                    },
+                ),
+                
+                /*
+                    This is another ObjectAttribute, just like eventListener
+                    It takes in an array of state it should watch,
+                    and when that state calls its state.signal() method,
+                    
+                    The observer calls it's callback function with the new values,
+                    and whatever is returned, is the new value of the property.
+                    
+                    So in this instance, whenever counter.signal() is called
+                    this observer displays Counter: VALUE, and makes it the
+                    innerText of this button.
+                */
+                innerText: observe([counter], (counter) => \`Counter: \${counter}\`),
+            },
+                div ({
+                    class: "blur-[50px] absolute group-hover:bg-zinc-200 inset-0 bg-transparent duration-200 pointer-events-none -z-10",
+                    "aria-hidden": "true",
+                }),
             ),
-            
-            innerText: observe([counter], (counter) => \`Counter: \${counter}\`),
-        },
-            div ({
-                class: "blur-[50px] absolute group-hover:bg-zinc-200 inset-0 bg-transparent duration-200 pointer-events-none -z-10",
-                "aria-hidden": "true",
-            }),
-        ),
-    )
-);
-
+        )
+    );
+}
+ 
+/*
+    This is the metadata of the page.
+    Aka the <head> element which gets served alongside the page content.
+    
+    It *must* be a function that resolves into a head() result.
+    
+    In it, you should do things like link your stylesheets,
+    set page titles, all that goodness.
+*/   
 export const metadata = () => head ({},
     link ({
         rel: "stylesheet",
@@ -94,7 +219,7 @@ export const metadata = () => head ({},
     }),
     
     title ({},
-        "Elegance.JS"
+        "Elegance.JS Demo"
     ),
 )
 
@@ -114,6 +239,9 @@ const tsconfigContent = JSON.stringify({
   },
   include: ["pages/**/*", "env.d.ts"],
   exclude: ["node_modules"],
+  paths: {
+    "@/": ["./"],
+  }
 }, null, 2);
 
 const indexCssContent = `