arrmatura 6.2.1 → 6.3.1

package/README.md

@@ -0,0 +1,45 @@
+# Arrmatura
+
+## Definitive
+
+`Arrmatura` is a programming framework strongly relied on declarative style and functional programming paradigm.
+It comprises of
+
+- declarative notation to define orbitrary components, its composition and data flow.
+- set of public and private types, which outlines an implementation approach.
+- a runtime engine, that enables launching applications of any kind.
+- `IPlatform` implementation for web to build/launch client applications.
+- Web UI kits with various components, services, forms, rich UI etc.
+
+## Key features and benefits of the platform
+
+The framework is designed to facilitate the creation of web applications
+by allowing developers to define components and specify how they are composed and connected.
+
+This component composition is achieved through a declarative syntax,
+which describes how data flows between components and how it is propagated across the composition.
+
+This streamlines the development process and makes it easier for developers
+to create complex and dynamic applications that can respond to changes in data in real-time.
+
+Overall, the framework aims to provide a flexible and intuitive way
+to build web applications that are scalable, maintainable, and responsive.
+
+## Documentation
+
+- [Manual](docs/manual.md)
+- [Glossary](docs/glossary.md)
+
+## Getting started for Web
+
+See [Hello, world](docs/HELLO.md) for starting example.
+
+## Examples
+
+- [Emoji List](https://emojis-list.web.app/)
+- [Countries List](https://countries-list.web.app/)
+- [Game Solver](https://dlitskevich.github.io/solver/) ([source](https://github.com/dlitskevich/solver/tree/master/app))
+
+## Limitations and considerations
+
+TBD

package/docs/glossary.md

@@ -0,0 +1,19 @@
+# Glossary
+
+|                        _Term_ | _Description_                                                                                                                                                                                                  |
+| ----------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+|                     `Program` | A formal prescription given to a runtime to process (to apply trasformation rules in some order) incoming data.                                                                                                |
+|                        `Type` | A specification that defines the possible values that can be reffered by a variable.                                                                                                                           |
+|                    `Variable` | A program entity, which may reffer some data value.                                                                                                                                                            |
+| `Object-oriented programming` | A programming style that evolves around composing components, which interact with each others by handling streams of events.                                                                                   |
+|                   `Component` | An individual runtime entity that has a lifecycle, state, and behavior. Components can interact with others and are treated as black boxes.                                                                    |
+|                       `Class` | A design-time specification for the state and behavior of a component. It provides guidance for the runtime to create and manage instances of the component.                                                   |
+|                       `State` | A private data structure that is managed by a component.                                                                                                                                                       |
+|                    `Property` | A public getter/setter pair that allows access to a state value by a specified key.                                                                                                                            |
+|                    `Behavior` | A specification that defines how a component should change its state in response to external impacts.                                                                                                          |
+|                   `Interface` | A design-time specification of the methods and signatures that can be used to interact with a component.                                                                                                       |
+|                 `Composition` | The                                                                                                                                                                                                            | parent-child and context-content relationships between components. It defines the scope and lifecycle of the components that they can interact with. |
+|                    `Template` | A text written in a formal language that allows for the description of component composition and property binding in a declarative way, focused on the desired outcome rather than the implementation details. |
+|            `Property binding` | A formal sentence that expresses a dependency between the value of a target component's property and other properties. It ensures that the target property is updated whenever the dependency changes.         |
+|        `Property propagation` | A one-way binding that passes property values from a container component to its contents.                                                                                                                      |
+|                        `Hook` | A component-bound method that is called by the runtime at specific points in the component's lifecycle.                                                                                                        |

package/docs/hello.md

@@ -0,0 +1,46 @@
+# Hello, world
+
+The code you have provided is a combination of XML and JavaScript that utilizes the arrmatura framework to create a web application.
+
+## templates.xml
+
+The templates.xml file defines two components: "Application" and "Main". The "Application" component is the root component of the application and contains a single instance of the "Main" component. The "Main" component is defined as a div element that displays a greeting, which consists of a static string ("Hello") and a dynamic value (name).
+
+```xml
+<component id="Application">
+    <Main name="world"/>
+</component>
+
+<component id="Main">
+    <div title="{#greeting}, {@name | upper}!"></div>
+</component>
+```
+
+## index.ts
+
+In the index.ts file, the arrmatura framework is imported and used to render the application.
+
+```javascript
+import { arrmatura } from 'arrmatura';
+import templates from './templates.xml';
+
+arrmatura({
+  template: '<Application />'
+  types: [templates],
+  resources: {
+    greeting: 'Hello',
+  },
+  functions: {
+    upper: (x) => x.toUpperCase(),
+  },
+});
+```
+
+The arrmatura function is passed several arguments:
+
+- template: Specifies the root component of the application, which is <Application />.
+- types: An array of component templates, in this case, the contents of the templates.xml file.
+- resources: An object that contains the static data used in the application. In this case, a single resource greeting with the value "Hello" is provided.
+- functions: An object that contains functions that can be used in component templates. In this case, a single function upper is provided, which takes a string as an argument and returns the uppercase version of the string.
+
+When the arrmatura function is executed, it creates an instance of the "Application" component and renders it to the page. The "Main" component is then rendered as a child of the "Application" component, and its title is set to the result of evaluating the expression "{#greeting}, {@name | upper}!". This expression uses a combination of static data (greeting), dynamic data (name), and a function (upper) to create the greeting that is displayed in the div element.

package/docs/manual.md

@@ -0,0 +1,294 @@
+#Templates
+
+**Template** is a xml-based notation defining a components composition, events and data flow.
+
+## Insight
+
+```html
+
+<component id="NavTreeItem">
+  <a href="@id">
+    <span>{@name | slice:0:50 | capitalize}</span>
+    <span if="@label" class="label label-{@type}">{@label}</span>
+  </a>
+</component>
+
+<component id="NavTree">
+  <ul class="nav">
+    <li class="nav-item {@item.class}" each="item of @data">
+      <NavTreeItem {...@item}>
+      <NavTree if="@item.subs" data="@item.subs" />
+    </li>
+  </ul>
+</component>
+```
+
+## Composition Control flow.
+
+### Conditionals.
+
+With `if` attribute, an element(and its inner context) presents only if value of expression is truthy.
+
+```html
+<div ... if="@enabled">...</div>
+```
+
+#### full `then-else` syntax
+
+```html
+<Fragment if="@enabled">
+  <Then><Case1 /></Then>
+  <Else><Case2 /></Else>
+</Fragment>
+```
+
+### Iterations.
+
+`each` attribute multiplies component instances along items from given array.
+
+```html
+<ul>
+  <li each="item of @data">
+    <a href="/item/{@item.id}">{@item.position}. {@item.name}</span>
+  </li>
+</ul>
+```
+
+> - items MUST HAVE unique `id` field
+
+### Fragment.
+
+`<Fragment>` is a transparent container and works just like a parens for multiple components.
+
+```html
+<Fragment if="@enabled"> <innerContent1 />...<innerContentN /> </Fragment>
+```
+
+## Dynamic tags.
+
+Used to calculate tag dunamically at runtime.
+
+```html
+<Dynamic as="{@type}Field" ...></Dynamic>
+```
+
+> use dot in type name to fallback to a basic implementation if a specific one not found `tag="Button.{@type}"`
+
+### References.
+
+Add `ref` attribute to any component to get refer it in `arrows` expressions.
+
+```html
+<UserService ref="user" />
+...
+<UserAvatar data="<- user.profile" onSave="->user.update" />
+```
+
+## Properties.
+
+Component properties can be assigned
+
+### with scalar literals
+
+`prop1="magicNumber"` puts a `magicNumber` literal into `prop1` property.
+
+> - 'true', 'false' values are narrowed to boolean,
+> - numbers has been narrowed to number type.
+
+### with resources values
+
+use `@@` prefix to refer any entity in the resource bundle.
+
+`prop="@@resId"` puts result of `platform.getResource(resId)` into `prop`.
+
+### with result of expression
+
+`prop="@prop2"` puts value of `prop2` owner property
+
+`prop="@data.key"` puts value of `prop2.key` owner property in depth.
+
+`prop="@prop2#not"` the `#not` postfix narrow to boolean and inverts the value of `prop2`
+
+`...="@data"` special `...` prop name spreads keys/values of `data` into properties of an entity.
+
+### with result of chain of pipes
+
+`prop="@some | pipeFn1 : 'strLiteral1' : 1 : true | pipeFn2 : @property2 | pipeFn2 : @@resourceId"` applies chain of pipes in left-to-right order.
+
+> - Pipe functions can be chained. Result of the previous one passed as a first argument to the next one.
+> - Optional colon-separated arguments can be passed to a pipe function as second, third arguments.
+> - Use shortcuts like `==, && , ??, ?, >, <, []` for `equals, and, or, then, less, greater, dot` functions respectively. Priority is still left-to-right here.
+
+### `data-*` attributes
+
+All `data-[key]` attributes will be collected into single `data` object property under its keys.
+
+## Left arrow expression
+
+`data="<-ref.prop"` makes a hot subscription to any property of orbitrary component in upper scopes.
+
+> may use pipes to adapt received value `data="<-ref.prop | adjustFn"`.
+
+## Right arrow expression
+
+```html
+<button ... action="-> ref.key1" data-key="val" data="@data" />
+
+<button ... action="-> ref.key1 = @value|pipe" />
+```
+
+Right arrow creates a function, that
+
+- `action="-> ref.key1"` invokes `upperScopes[ref].onKey1(data)` action handler with an `data` object as parameter.
+
+- `action="-> ref.!prop1"` updates container state for given key `upperScopes[ref].up({ prop1: data })`.
+
+> `action="-> ref.key1 = * | prepare"` pipes will be applied on `data`-object before it passed to the action handler .
+
+> `click="-> @opened"` if `ref` is omitted, then a target will be a scope component `scope.up({opened:data})`
+
+> `click="-> ..."` will spread data to state of a scope component `scope.up(data)`
+
+#### Right arrows with inline payload
+
+Often, it is shorter to pass payload inline instead of using `data` property.
+
+- `click="->" data="@data | assignKeyValue:key:@value"` updates a scope properties with `data` object.
+- `click="-> prop" data="@data"` updates a given scope property of owner with `data` object.
+- `click="-> prop=literalValue"` updates a given scope property of owner with literal.
+
+## Slots
+
+Slots are placeholders to inject an inner content of component usage tag.
+
+```html
+<Comp>
+  <!-- inner content of component usage -->
+  <InnerContent />
+</Comp>
+```
+
+```html
+<component id="Comp">
+<div class="container">
+    <!-- Inner content will replace <Slot/> -->
+    <Slot>
+</div>
+</component>
+```
+
+### Multi-part extra content.
+
+Inner content could be multiple-part and thus, distributed separately inside component template.
+
+```html
+<Comp>
+  <Comp:key1><Extra1 /></Comp:key1>
+  <Comp:key2><Extra2 /></Comp:key2>
+  <DefaultSlotContent />
+</Comp>
+```
+
+```html
+<div class="component template">
+
+    <!-- <Extra1/> will be placed here-->
+    <Slot key="key1">
+
+    <!-- special `slot(key)` conditional expression may be used to check if non-empty slot content passed. -->
+    <div class="comp" if="slot(key2)">
+        <!-- <Extra2/> will be placed here -->
+        <Slot key="key2">
+    </div>
+
+    <!-- <DefaultContent/> will be placed here -->
+    <Slot>
+</div>
+```
+
+### DOM support.
+
+You can provide life-cycle hooks for DOM element:
+
+```html
+<div attached="initBehavior" detached="finalizeBehavior"></div>
+```
+
+# Custom components
+
+There is a [Component] class that could be used an base ancestor for custom components.
+
+It allows
+
+- to define life-cycle hooks;
+- to add getters/setter for its properties;
+- to define action handlers;
+- to use context methods like `up()`, `emit()`, `defer()`.
+
+```typescript
+class MyService extends Component {
+
+    constructor(initials: Hash, ctx: ICtx) {
+        Object.asign(this, initials);
+        this.ctx = ctx;
+    }
+
+    // life-cycle hook called once on component is inited
+    init() {
+        this.cancel = api.listen(this)
+        // ...or using $.defer()
+        this.ctx.defer(api.listen2(this));
+
+        // will update component state with returned result
+        return {
+            prop1:'value',
+            // can be promise as well
+            prop2: Promise.resolve(2)
+        }
+    }
+
+    // life-cycle hook called once on component is done
+    done (){
+      this.cancel();
+    }
+
+    // property getter
+    getSrc(){
+        return this.url.toString()
+    }
+
+    // property setter
+    setSrc(value){
+      this.url = URL.parse(value)
+    }
+
+    // getter can return promise
+    async getData() {
+      return this.fetchData()
+    }
+
+    // action handler. To be invoked with '-> ref.someAction' notation
+    onSomeAction(data, T:This) {
+        if (asyncMode) {
+            return promise.then(() => delta)
+        }
+        // delta object to update component state
+        return {
+            // instant value for 'prop'
+            prop: data.value,
+            // async evaluation for 'prop'. 'Promise' postfix is optional.
+            propPromise: T.fetchProp(),
+            // async spread
+            '*': Promise.resolve({
+                prop1: 'val1'
+                prop2: 'val2'
+            })
+        }
+    }
+
+    toast (message) {
+      // emit action event
+      this.emit('toasters.send', { message });
+    };
+}
+```

package/index.ts

@@ -1,18 +1,19 @@
-import { ICtx, IPlatform } from "arrmatura-api/types";
-import { CRootNode } from "./src/core/root";
+import { IEntitron, IPlatform } from "arrmatura/types";
+import { CRootNode } from "./src/registry/root";
 
-export { Registry } from "./src/core";
-export { CRootNode } from "./src/core/root";
+export * from "./src/registry";
+export { CRootNode } from "./src/registry/root";
+export * from "./src/core/Component";
 
 /**
  * Launches the runtime with given top-level template on the specified platform.
  *
  * @param {IPlatform} platform - The platform on which to launch the template.
  * @param {string} template - The template to launch with.
- * @return {ICtx} The root context object.
+ * @return {IEntitron} The root context object.
  */
-export const launch = (platform: IPlatform, template: string): ICtx => {
-  const root = new CRootNode(template).createContext(platform);
+export const launch = (platform: IPlatform, template: string): IEntitron => {
+  const root = new CRootNode(template).createEntitron(platform);
 
   root.up({}, true);
 

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "arrmatura",
-  "version": "6.2.1",
+  "version": "6.3.1",
   "description": "Arrmatura runtime engine",
   "author": "alitskevich@gmail.com",
   "license": "ISC",
   "type": "module",
-  "main": "index.ts",
+  "main": "./index.ts",
   "files": [
-    "src/**/*"
+    "src",
+    "types.ts",
+    "docs/**/*"
   ],
   "dependencies": {
-    "arrmatura-api": "1.0.2",
-    "ultimus": "2.1.4"
+    "arrmatura": "6.3.1",
+    "ultimus": "2.1.8"
   },
   "scripts": {
     "pnpm:publish": "pnpm publish --no-git-checks"

package/src/core/Component.ts

@@ -0,0 +1,67 @@
+import type { Data, Delta, Hash, LogEntry } from "ultimus/types";
+import type { IComponent, IEntitron } from "../../types";
+
+/**
+ * Base Ancestor for custom components.
+ */
+export abstract class Component implements IComponent {
+  [key: string]: unknown;
+
+  constructor(_: Hash, readonly ctx: IEntitron) {
+    //no-op
+  }
+
+  get platform() {
+    return this.ctx.platform;
+  }
+
+  get isDone() {
+    return this.ctx.isDone;
+  }
+
+  // hook on done
+  done(_: IEntitron): void {
+    //no-op
+  }
+
+  // hook on init
+  // returned value will be used to update state
+  init(_: IEntitron): Delta | null | undefined | unknown {
+    return undefined;
+  }
+
+  // update its state
+  up(d: Delta) {
+    return this.ctx.up(d);
+  }
+  touch() {
+    return this.ctx.touch();
+  }
+  // emit action event to another component by key
+  emit(key: string, data: Delta) {
+    return this.ctx.emit(key, data);
+  }
+
+  // access to resource entity by key
+  res(key: string): Data | Data[] {
+    return this.ctx.res(key);
+  }
+
+  // register callback to be called on done
+  defer(fn: () => void) {
+    this.ctx.defer(fn);
+  }
+
+  log(val: unknown, ...args: unknown[]) {
+    this.ctx.log(val, ...args);
+  }
+
+  logError(val: unknown, ...args: unknown[]) {
+    this.ctx.logError(val, ...args);
+  }
+
+  toast(message: string | Partial<LogEntry> = "ok") {
+    // may  overriden from props
+    void this.emit("toasters.send", typeof message === "string" ? { message } : message);
+  }
+}