arrmatura 6.3.1 → 6.3.2

package/README.md

@@ -2,14 +2,14 @@
 
 ## Definitive
 
-`Arrmatura` is a programming framework strongly relied on declarative style and functional programming paradigm.
+`Arrmatura` is a framework which inherits declarative approach and functional programming.
+
 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.
+- extended HTML notation to define components, its composition, behaviour and data flow.
+- type system and runtime enabling development of applications of any kind.
+- `IPlatform` implementation for web client applications.
+- Web UI kits with plenty of components, services, forms, editors etc.
 
 ## Key features and benefits of the platform
 
@@ -39,7 +39,3 @@ See [Hello, world](docs/HELLO.md) for starting example.
 - [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/dist/index.js

@@ -0,0 +1,2 @@
+import{CRootNode as m}from"./src/registry/root";export*from"./src/registry";import{CRootNode as c}from"./src/registry/root";export*from"./src/core/Component";var n=(o,t)=>{let r=new m(t).createArrmatron(o);return r.up({},!0),r};export{c as CRootNode,n as launch};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../index.ts"],
+  "sourcesContent": ["import { IArrmatron, IPlatform } from \"arrmatura/types\";\n\nimport { CRootNode } from \"./src/registry/root\";\n\nexport * from \"./src/registry\";\nexport { CRootNode } from \"./src/registry/root\";\nexport * from \"./src/core/Component\";\n\n/**\n * Launches the runtime with given top-level template on the specified platform.\n *\n * @param {IPlatform} platform - The platform on which to launch the template.\n * @param {string} template - The template to launch with.\n * @return {IArrmatron} The root context object.\n */\nexport const launch = (platform: IPlatform, template: string): IArrmatron => {\n  const root = new CRootNode(template).createArrmatron(platform);\n\n  root.up({}, true);\n\n  return root;\n};\n"],
+  "mappings": "AAEA,OAAS,aAAAA,MAAiB,sBAE1B,WAAc,iBACd,OAAS,aAAAA,MAAiB,sBAC1B,WAAc,uBASP,IAAMC,EAAS,CAACC,EAAqBC,IAAiC,CAC3E,IAAMC,EAAO,IAAIJ,EAAUG,CAAQ,EAAE,gBAAgBD,CAAQ,EAE7D,OAAAE,EAAK,GAAG,CAAC,EAAG,EAAI,EAETA,CACT",
+  "names": ["CRootNode", "launch", "platform", "template", "root"]
+}

package/docs/manual.md

@@ -7,17 +7,17 @@
 ```html
 
 <component id="NavTreeItem">
-  <a href="@id">
-    <span>{@name | slice:0:50 | capitalize}</span>
-    <span if="@label" class="label label-{@type}">{@label}</span>
+  <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 class="nav-item {item.class}" Each="item of data">
+      <NavTreeItem (...)="{item}">
+      <NavTree If="item.subs" data="{item.subs}" />
     </li>
   </ul>
 </component>
@@ -30,13 +30,13 @@
 With `if` attribute, an element(and its inner context) presents only if value of expression is truthy.
 
 ```html
-<div ... if="@enabled">...</div>
+<div ... If="enabled">...</div>
 ```
 
 #### full `then-else` syntax
 
 ```html
-<Fragment if="@enabled">
+<Fragment If="enabled">
   <Then><Case1 /></Then>
   <Else><Case2 /></Else>
 </Fragment>
@@ -48,8 +48,8 @@ With `if` attribute, an element(and its inner context) presents only if value of
 
 ```html
 <ul>
-  <li each="item of @data">
-    <a href="/item/{@item.id}">{@item.position}. {@item.name}</span>
+  <li Each="item of data">
+    <a href="/item/{item.id}">{item.position}. {item.name}</span>
   </li>
 </ul>
 ```
@@ -61,7 +61,7 @@ With `if` attribute, an element(and its inner context) presents only if value of
 `<Fragment>` is a transparent container and works just like a parens for multiple components.
 
 ```html
-<Fragment if="@enabled"> <innerContent1 />...<innerContentN /> </Fragment>
+<Fragment If="enabled"> <innerContent1 />...<innerContentN /> </Fragment>
 ```
 
 ## Dynamic tags.
@@ -69,93 +69,108 @@ With `if` attribute, an element(and its inner context) presents only if value of
 Used to calculate tag dunamically at runtime.
 
 ```html
-<Dynamic as="{@type}Field" ...></Dynamic>
+<Dynamic As="Field.{type}" ...></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" />
-```
+> it will fallback to a `Field` if a specific type not found.
 
 ## Properties.
 
-Component properties can be assigned
+Component state can be mutated different ways listed below.
+State updates lead to redraw UI and notify subscribers(left arrows)
+Updating data is compared with existing state values for 'sameness' (same set of same values).
 
 ### with scalar literals
 
-`prop1="magicNumber"` puts a `magicNumber` literal into `prop1` property.
+`prop1="'somestring'"` puts a 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.
+`R`-prefix used to refer any value in the resource bundle.
 
-`prop="@@resId"` puts result of `platform.getResource(resId)` into `prop`.
+`prop="R.resId"` assigns `resId` resource value to `prop`.
 
 ### with result of expression
 
-`prop="@prop2"` puts value of `prop2` owner property
+`prop="{prop2}"` assigns value of `prop2` property of the current scope.
 
-`prop="@data.key"` puts value of `prop2.key` owner property in depth.
+`prop="{data.key}"` assigns value of `data.key`.
 
-`prop="@prop2#not"` the `#not` postfix narrow to boolean and inverts the value of `prop2`
+`prop="{!prop2}"` assigns inverted value of `prop2`
 
-`...="@data"` special `...` prop name spreads keys/values of `data` into properties of an entity.
+`(...)="{data}"` special `(...)` notation used to spread keys/values of `data` into properties of a target 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.
+`prop="{some | pipeFn1 : 'strLiteral1' : 1 : true | pipeFn2 : property2 | pipeFn2 : R.resourceId}` applies chain of pipes.
 
 > - 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.
+> - Use shortcuts like `==, && , ??, ?, >, <, []` for `equals, and, or, then, less, greater, dot` functions respectively.
+> - There is no operation priority, they applied in left-to-right order.
 
 ### `data-*` attributes
 
 All `data-[key]` attributes will be collected into single `data` object property under its keys.
 
-## Left arrow expression
+### References.
 
-`data="<-ref.prop"` makes a hot subscription to any property of orbitrary component in upper scopes.
+Add `Ref` attribute to any component to get refer it in `arrows` expressions.
 
-> may use pipes to adapt received value `data="<-ref.prop | adjustFn"`.
+```html
+<UserService Ref="user" /> <UserAvatar data="<- user.profile" onSave="-> user.update" />
+```
 
-## Right arrow expression
+## Left arrow expression
 
-```html
-<button ... action="-> ref.key1" data-key="val" data="@data" />
+`data="<- ref.prop"` makes a hot subscription to any property of orbitrary component in the current or upper scopes.
 
-<button ... action="-> ref.key1 = @value|pipe" />
-```
+> use pipes to adapt received value `data="<- ref.prop | adjustFn"`.
+
+## Right arrow expression
 
 Right arrow creates a function, that
 
-- `action="-> ref.key1"` invokes `upperScopes[ref].onKey1(data)` action handler with an `data` object as parameter.
+- `action="data-> ref.submit(data)"` invokes `scope.refs[ref].submit(data)` action with an `data` object as parameter.
+
+- `action="-> ref.submit(prop1)"` invokes `scope.refs[ref].submit(data)` action with a value of property `prop1` as parameter.
 
-- `action="-> ref.!prop1"` updates container state for given key `upperScopes[ref].up({ prop1: data })`.
+- `action="-> ref.prop1"` updates container state for given key `scope.refs[ref].up({ prop1: data })`.
 
-> `action="-> ref.key1 = * | prepare"` pipes will be applied on `data`-object before it passed to the action handler .
+> `action="data-> ref.action(data | prepare)` pipes will be applied on `data`-object before it passed to the action.
 
-> `click="-> @opened"` if `ref` is omitted, then a target will be a scope component `scope.up({opened:data})`
+> `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)`
+> `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.
+- `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.
+
+## Connector
+
+Special build-in `Connector` component serves for async data binding
+It acts with timeout(0 by default) and debounces if any:
+
+```html
+<!-- `data` works as a `trigger`, if none specified. -->
+<Connector data="<- todo.shownItems|adjust" change="-> someData" />
+
+<!-- `change` is invokes with `data` on `trigger` changed.  -->
+<Connector
+  data="someData"
+  trigger="<- todo.shownItemsCount"
+  timeout="100"
+  change="data-> discriminant=data|calculate"
+/>
+```
 
 ## Slots
 
@@ -193,12 +208,12 @@ Inner content could be multiple-part and thus, distributed separately inside com
 <div class="component template">
 
     <!-- <Extra1/> will be placed here-->
-    <Slot key="key1">
+    <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)">
+    <div class="comp" If="slot(key2)">
         <!-- <Extra2/> will be placed here -->
-        <Slot key="key2">
+        <Slot Key="key2">
     </div>
 
     <!-- <DefaultContent/> will be placed here -->
@@ -206,24 +221,18 @@ Inner content could be multiple-part and thus, distributed separately inside com
 </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
+While designing custom components you can
 
 - to define life-cycle hooks;
 - to add getters/setter for its properties;
-- to define action handlers;
-- to use context methods like `up()`, `emit()`, `defer()`.
+- to define `__getProperty(propName)` to return value of any property by its name
+- to define `__stateChanged(changes)` to intercept appluing state changes
+- to define action handlers like `doSomethig(data: any): object`, which may return a delta object for updating a component state;
+- to use context methods like `up(delta)`, `emit('ref-target', data)`, `defer(fn)`.
 
 ```typescript
 class MyService extends Component {
@@ -252,6 +261,15 @@ class MyService extends Component {
       this.cancel();
     }
 
+    // to intercept getting of any property
+    __getProperty(key: string) {
+      this.log('getProperty', key)
+      return this[key]
+
+    // to intercept state changes
+    __stateChanged(changes: Map) {
+    }
+
     // property getter
     getSrc(){
         return this.url.toString()
@@ -268,7 +286,7 @@ class MyService extends Component {
     }
 
     // action handler. To be invoked with '-> ref.someAction' notation
-    onSomeAction(data, T:This) {
+    onSomeAction(data: any) {
         if (asyncMode) {
             return promise.then(() => delta)
         }
@@ -279,7 +297,7 @@ class MyService extends Component {
             // async evaluation for 'prop'. 'Promise' postfix is optional.
             propPromise: T.fetchProp(),
             // async spread
-            '*': Promise.resolve({
+            '...': Promise.resolve({
                 prop1: 'val1'
                 prop2: 'val2'
             })
@@ -288,7 +306,7 @@ class MyService extends Component {
 
     toast (message) {
       // emit action event
-      this.emit('toasters.send', { message });
+      this.emit('toasters.onSend(data)', { message });
     };
 }
 ```

package/index.ts

@@ -1,4 +1,5 @@
-import { IEntitron, IPlatform } from "arrmatura/types";
+import { IArrmatron, IPlatform } from "arrmatura/types";
+
 import { CRootNode } from "./src/registry/root";
 
 export * from "./src/registry";
@@ -10,10 +11,10 @@ export * from "./src/core/Component";
  *
  * @param {IPlatform} platform - The platform on which to launch the template.
  * @param {string} template - The template to launch with.
- * @return {IEntitron} The root context object.
+ * @return {IArrmatron} The root context object.
  */
-export const launch = (platform: IPlatform, template: string): IEntitron => {
-  const root = new CRootNode(template).createEntitron(platform);
+export const launch = (platform: IPlatform, template: string): IArrmatron => {
+  const root = new CRootNode(template).createArrmatron(platform);
 
   root.up({}, true);
 

package/package.json

@@ -1,21 +1,27 @@
 {
   "name": "arrmatura",
-  "version": "6.3.1",
+  "version": "6.3.2",
   "description": "Arrmatura runtime engine",
   "author": "alitskevich@gmail.com",
   "license": "ISC",
   "type": "module",
-  "main": "./index.ts",
+  "exports": {
+    "import": "./index.ts",
+    "require": "./dist/index.js"
+  },
   "files": [
     "src",
+    "dist",
+    "index.ts",
     "types.ts",
     "docs/**/*"
   ],
   "dependencies": {
-    "arrmatura": "6.3.1",
-    "ultimus": "2.1.8"
+    "arrmatura": "6.3.2",
+    "ultimus": "2.1.10"
   },
   "scripts": {
+    "esbuild": "esbuild index.ts --bundle --outdir=./dist --platform=browser --format=esm --sourcemap --target=esnext --external:* --minify",
     "pnpm:publish": "pnpm publish --no-git-checks"
   }
 }