structured-fw 0.8.41 → 0.8.42

package/README.md

@@ -347,13 +347,25 @@ app.request.on('GET', '/home', async (ctx) => {
 });
 ```
 
+> [!TIP]
+> Since version 0.8.4 Document extends EventEmitter, and "componentCreated" event is emitted whenever a component instance is created within the Document.\
+> This makes the following possible:
+> ```
+> app.on('documentCreated', (doc) => {
+>   doc.on('componentCreated', (component) => {
+>       // do something with the document or the component
+>   })    
+> })
+> ```
+
 ## Component
-A component is comprised of 1-3 files. It always must include one HTML file, while server side and client side files are optional.
+A component is comprised of [1-3 files](#component-parts). It always must include one HTML file, while server side and client side files are optional.
 * HTML file probably requires no explanation
 * server side file, code that runs on the server and makes data available to HTML and client side code
 * client side file, code that runs on the client (in the browser)
 
-You should never need to instantiate a Component on your own. You will always load a Component representing your page into a document (using `Document.loadComponent(componentName: string)`), which will know what to do from there.
+> [!TIP]
+> You should never need to instantiate a Component on your own. You will always load a Component representing your page into a document (using `Document.loadComponent(componentName: string)`), which will know what to do from there.
 
 Example component files:
 - `/app/views/`
@@ -373,6 +385,12 @@ It is recommended, but not necessary, that you contain each component in it's ow
 - Components HTML file can have a `.hbs` extension (which allows for better Handlebars syntax highlighting)
 - Components can reside at any depth in the file structure
 
+### Component parts
+- [Component HTML](#component-html) (_ComponentName.html_)
+- [Component server-side code](#component-server-side-code) (_ComponentName.ts_)
+- [Component client-side code](#component-client-side-code) (_ComponentName.client.ts_)
+
+### Component HTML
 Let's create a HelloWorld Component `/app/views/HelloWorld/HelloWorld.html`:\
 `Hello, World!`
 
@@ -392,7 +410,12 @@ export default function(app: Application) {
 You can now run the app and if you open /hello/world in the browser you will see:\
 `Hello, World!` - which came from your HelloWorld component.
 
-That was the simplest possible example, let's make it more interesting.
+> [!TIP]
+> It is recommended to use .hbs (Handlebars) extension as you will get better syntax highlighting in most IDEs. Other than syntax highlighting there is no difference between using html or hbs extension.
+
+That was the simplest possible example, let's make it more interesting by adding some server-side code.
+
+### Component server-side code
 Create a new file `/app/views/HelloWorld/HelloWorld.ts` (server side component code):
 ```
 import { ComponentScaffold } from 'system/Types.js';
@@ -426,7 +449,15 @@ Your lucky number is [a number from 0-100]
 This demonstrates the use of a *server side component code* to make data available to HTML.
 We just generated a random number, but the data could be anything and will more often come from a database, session, or be provided by the parent component.
 
+> [!IMPORTANT]
+> Server side `getData` will receive the following arguments:
+> - `data: LooseObject` any data passed in (either by attributes, ClientComponent.add or ClientComponent.redraw)
+> - `ctx: RequestContext` - current `RequestContext`, you will often use this to access for example ctx.data (`RequestContextData`) or ctx.sessionId to interact with session
+> - `app: Application` - your Application instance. You can use it to, for example, access the session in combination with ctx.sessionId
+
 Let's make it even more interesting by adding some client side code to it.
+
+### Component client-side code
 Create `/app/views/HelloWorld/HelloWorld.client.ts`:
 ```
 import { InitializerFunction } from 'system/Types.js';
@@ -509,12 +540,6 @@ What about client side? **By default, data returned by server side code is not a
 > [!NOTE]
 > Whenever a component with server-side code is rendered, `getData` is automatically called and anything it returns is available in HTML. You can export all returned data to client-side code by setting `exportData = true` or you can export some of the fields by setting `exportFields = ["field1", "field2", ...]` as a direct property of the class. To access the exported data from client-side use `ClientComponent`.`getData(key: string)` which will be `this.getData(key:string)` within client side code.
 
-> [!IMPORTANT]
-> Server side `getData` will receive the following arguments:
-> - `data: LooseObject` any data passed in (either by attributes, ClientComponent.add or ClientComponent.redraw)
-> - `ctx: RequestContext` - current `RequestContext`, you will often use this to access for example ctx.data (`RequestContextData`) or ctx.sessionId to interact with session
-> - `app: Application` - your Application instance. You can use it to, for example, access the session in combination with ctx.sessionId
-
 Let's create a client side code for `AnotherComponent` and export the `betterNumber` to it, create `/app/views/AnotherComponent/AnotherComponent.client.ts`:
 ```
 import { InitializerFunction } from 'system/Types.js';
@@ -611,13 +636,67 @@ Methods:
 - `query(componentName: string, recursive: boolean = true): Array<ClientComponent>` - return all components with given name found within this component, if `recursive = false`, only direct children are considered
 - `ref<T>(refName: string): T` - get a HTMLElement or ClientComponent that has attribute `ref="[refName]"`
 - `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
+- `add(appendTo: HTMLElement, componentName: string, data?: LooseObject): Promise<ClientComponent | null>` - add `componentName` component to `appendTo` element, optionally passing `data` to the component when it's being rendered. Returns a promise that resolves with added ClientComponent or null if something went wrong
+- `redraw(data?: LooseObject): Promise<void>` - redraw the component, optionally provide data which will be available server side
+
+### Conditionals
+You can make any DOM node within your components conditionally shown/hidden using `data-if` attribute.\
+For example:
+```
+<div data-if="showDiv"></div>
+```
+Above div will only be shown if store.showDiv = true
+
+You can also use `!` to invert the value, `!showDiv` in which case div would be shown if showDiv is false.
+
+You can also use comparison:
+```
+<div data-if="val === 1"></div>
+<div data-if="val == 1"></div>
+<div data-if="val !== 1"></div>
+<div data-if="val != 1"></div>
+<div data-if="val > 1"></div>
+<div data-if="val < 1"></div>
+<div data-if="val <= 1"></div>
+<div data-if="val >= 1"></div>
+```
+
+The right hand side of the comparison does not have to be boolean or number. It can be a string or any primitive value, but the numeric comparisons don't make sense in such case.
+
+You can also define callbacks and use them as the condition, in you ComponentName.client.ts:
+```
+import { InitializerFunction } from 'structured-fw/Types';
+export const init: InitializerFunction = async function() {
+    this.conditionalCallback('showDiv', () => {
+        // return a boolean here
+    });
+}
+```
+
+then in ComponentName.html:
+```
+<div data-if="showDiv()"></div>
+```
+
+**Basic animation/transitions**\
+If you use conditionals on any DOM node, you may also enable basic animations/transitions using following attributes:
+- Enable transition:
+    - `data-transition-show-slide="durationMilliseconds"` - when DOM node is shown, slide it in
+    - `data-transition-hide-slide="durationMilliseconds"` - when DOM node is hidden, slide it out
+    - `data-transition-show-fade="durationMilliseconds"` - fade DOM node in
+    - `data-transition-hide-fade="durationMilliseconds"` - fade DOM node out
+- Modify transition (slide only)
+    - `data-transform-origin-show="CSS transform origin"` - from where does the component slide in for example `0% 50%` to slide it in from mid-left
+    - `data-transform-origin-hide="CSS transform origin"` - where does the component slide out to for example `100% 100%` to slide it out to bottom-right
+    - `data-transition-axis-show="X | Y"` - slide animation axis
+    - `data-transition-axis-hide="X | Y"` - slide animation axis
 
 ## Good to know
 - [Using CSS frameworks](#css-frameworks)
 - [Using JS runtimes other than Node.js](#runtimes)
 - [Why not JSR](#jsr)
 - [Best practices](#best-practices)
+- [Having an issue?](#issues-and-feedback)
 
 ### 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.
@@ -762,6 +841,9 @@ If you ran `npx structured init`, it has created /app/models for you. Structured
 
 You can create additional code separation, for example, it would make sense to have /app/lib for code that interfaces an API, or have /app/Util.ts where you export utility functions. Structured boilerplate does not include these as not all applications will need them.
 
+### Issues and feedback
+If you have any issues with the framework or the npm package, please don't hesitate to open an issue on [github](https://github.com/julijan/structured). Feedback is also welcome!
+
 ## 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/package.json

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