structured-fw 0.8.1 → 0.8.21

package/README.md

@@ -8,15 +8,20 @@ It works with Node.js and Deno runtimes. Other runtimes are not tested.
 - [Why Structured](#why-structured)
 - [Audience](#audience)
 - [Getting started](#getting-started)
+- [Key concepts](#key-concepts)
+- [Good to know](#good-to-know)
+
 
 ### Key concepts:
 * [Application](#application)
 * [Route](#route)
 * [Document](#document)
-* [ClientComponent](#component) (component)
+* [Component](#component)
 
 ## Getting started
 
+_Following getting started instructions are relevant for Node.js runtime, if you are using Deno skip to [runtimes](#runtimes) section._
+
 ### Initialize a Node.js project
 ```
 cd /path/to/project
@@ -605,6 +610,117 @@ Methods:
 - `arrayRef<T>(refName: string): Array<T>` - get an array of HTMLElement or ClientComponent that have attribute `array:ref="[refName]"`
 - `add(appendTo: HTMLElement, componentName: string, data?: LooseObject)` - add `componentName` component to `appendTo` element, optionally passing `data` to the component when it's being rendered
 
+## Good to know
+- [Uing CSS frameworks](#css-frameworks)
+- [Using JS runtimes other than Node.js](#runtimes)
+- [Why not JSR](#jsr)
+
+### CSS frameworks
+We rarely write all CSS from scratch, usually we use a CSS framework to speed us up. Structured allows you to work with any CSS frameworks such as Tailwind, PostCSS or Bootstrap.
+
+Your Tailwind configuration may look something like:
+```
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ["./app/views/**/*.html", "./app/views/**/*.hbs"],
+  ...
+}
+```
+
+Above we just defined where all our HTML resides, which is within /app/views. That is all there is to it. From there, you can generate the CSS, for example:\
+`npx tailwindcss -i ./assets/css/src/style.css -o ./assets/css/dist.css`
+
+**Including the output CSS**\
+To include the output CSS in all pages, you can add the following to `index.ts`:
+```
+const app = new Application(config);
+
+app.on('documentCreated', (doc) => {
+    doc.head.addCSS('/assets/css/dist.css');
+});
+```
+
+### Runtimes
+Structured is tested with Node.js and Deno. Other runtimes would likely work as well.
+
+To use Structured with Deno, you can:
+```
+cd /path/to/project
+deno init
+deno add npm:structured-fw
+```
+
+With Deno, we can't use the cli to create the boilerplate, so you will need to create it yourself.
+```
+mkdir app
+mkdir app/views
+mkdir app/routes
+```
+
+Create `Config.ts`:
+```
+import { StructuredConfig } from "structured-fw/Types";
+
+export const config: StructuredConfig = {
+    // Application.importEnv will load all env variables starting with [envPrefix]_
+    envPrefix: 'STRUCTURED',
+
+    // whether to call Application.init when an instance of Application is created
+    autoInit: true,
+
+    url: {
+        removeTrailingSlash: true,
+
+        // if you want to enable individual component rendering set this to URI (string)
+        // to disable component rendering set it to false
+        // setting this to false disallows the use of ClientComponent.redraw and ClientComponent.add
+        componentRender: '/componentRender',
+
+        // function that receives the requested URL and returns boolean, if true, treat as static asset
+        // if there is a registered request handler that matches this same URL, it takes precedence over this
+        isAsset: function(uri: string) {
+            return uri.indexOf('/assets/') === 0;
+        }
+    },
+    routes: {
+        path: '/app/routes'
+    },
+    components : {
+        // relative to index.ts
+        path: '/app/views',
+
+        componentNameAttribute: 'structured-component'
+    },
+    session: {
+        cookieName: 'session',
+        keyLength: 24,
+        durationSeconds: 60 * 60,
+        garbageCollectIntervalSeconds: 60
+    },
+    http: {
+        port: 9191,
+        host: '0.0.0.0',
+        // used by Document.push, can be preload or preconnect
+        linkHeaderRel : 'preload'
+    },
+    runtime: 'Deno'
+}
+```
+
+Import `Config.ts` in `main.ts` and create the Application instance:
+```
+import { Application } from 'structured-fw/Application';
+import { config } from './Config.ts';
+
+new Application(config);
+```
+
+Run application using `deno main.ts`
+
+### JSR
+It would make a lot of sense to have Structured hosted on JSR (JavaScript Registry) given Structured is a TypeScript framework, and JSR is a TypeScript-first registry, however, the issue is that Deno imposes [limitations with dynamic imports](https://docs.deno.com/deploy/api/dynamic-import/) with JSR-imported dependencies, which are required for the framework (to dynamically import your routes and components).\
+This does not stop the framework from working with Deno, but for the time being, we have to stick with good old npm.
+
 ## Why Structured
 Framework was developed by someone who has been a web developer for almost 20 years (me), and did not like the path web development has taken.
 \

package/build/system/client/ClientComponent.d.ts

@@ -1,14 +1,8 @@
-import { InitializerFunction, LooseObject, StructuredClientConfig } from '../Types.js';
+import { LooseObject } from '../Types.js';
 import { DataStoreView } from './DataStoreView.js';
 import { DataStore } from './DataStore.js';
 import { Net } from './Net.js';
 import { EventEmitter } from './EventEmitter.js';
-declare global {
-    interface Window {
-        initializers: Record<string, InitializerFunction | string>;
-        structuredClientConfig: StructuredClientConfig;
-    }
-}
 export declare class ClientComponent extends EventEmitter {
     readonly name: string;
     children: Array<ClientComponent>;

package/jsr.json

@@ -0,0 +1,35 @@
+{
+    "name": "@structured/structured-fw",
+    "version": "0.8.21",
+    "license": "MIT",
+    "exports" : {
+        "./Types": "./system/Types.ts",
+        "./Symbols": "./system/Symbols.ts",
+        "./Util": "./system/Util.ts",
+        "./Application": "./system/server/Application.ts",
+        "./Document": "./system/server/Document.ts",
+        "./FormValidation": "./system/server/FormValidation.ts",
+        "./ClientComponent": "./system/client/ClientComponent.ts"
+    },
+    "dependencies": {
+        "handlebars": "^4.7.8",
+        "mime-types": "^3.0.0",
+        "ts-md5": "^1.3.1",
+        "@types/node": "^22.9.3",
+        "@types/mime-types": "^2.1.4"
+    },
+    "exclude": [
+        "build",
+        "assets",
+        "node_modules",
+        "tsconfig.json",
+        "package.json",
+        "package.lock.json",
+        "tailwind.config.cjs",
+        ".vscode",
+        "app/Types.ts",
+        "app/views/*",
+        "app/routes/*",
+        "app/models/*"
+    ]
+}

package/package.json

@@ -14,7 +14,7 @@
   "license": "MIT",
   "type": "module",
   "main": "build/index",
-  "version": "0.8.1",
+  "version": "0.8.21",
   "scripts": {
     "develop": "tsc --watch",
     "startDev": "cd build && nodemon --watch '../app/**/*' --watch '../build/**/*' -e js,html,css index.js",

package/system/client/ClientComponent.ts

@@ -1,4 +1,4 @@
-import { ClientComponentTransition, ClientComponentTransitions, InitializerFunction, LooseObject, StoreChangeCallback, StructuredClientConfig } from '../Types.js';
+import { ClientComponentTransition, ClientComponentTransitions, InitializerFunction, LooseObject, StoreChangeCallback } from '../Types.js';
 import { attributeValueFromString, attributeValueToString, mergeDeep, objectEach, queryStringDecodedSetValue, toCamelCase } from '../Util.js';
 import { DataStoreView } from './DataStoreView.js';
 import { DataStore } from './DataStore.js';
@@ -6,16 +6,6 @@ import { Net } from './Net.js';
 import { NetRequest } from './NetRequest.js';
 import { EventEmitter } from './EventEmitter.js';
 
-// window.initializers will always be present
-// each Document has a list of initializers used in components within it
-// and they will be output as initializers = { componentName : initializer }
-declare global {
-    interface Window {
-        initializers: Record<string, InitializerFunction | string>;
-        structuredClientConfig: StructuredClientConfig;
-    }
-}
-
 export class ClientComponent extends EventEmitter {
     readonly name: string;
     children: Array<ClientComponent> = [];

package/system/global.d.ts

@@ -0,0 +1,12 @@
+import { InitializerFunction, StructuredClientConfig } from "./Types.js";
+
+export {}
+// window.initializers will always be present
+// each Document has a list of initializers used in components within it
+// and they will be output as initializers = { componentName : initializer }
+declare global {
+    interface Window {
+        initializers: Record<string, InitializerFunction | string>;
+        structuredClientConfig: StructuredClientConfig;
+    }
+}