arrmatura 6.2.1 → 6.3.2

package/README.md

@@ -0,0 +1,41 @@
+# Arrmatura
+
+## Definitive
+
+`Arrmatura` is a framework which inherits declarative approach and functional programming.
+
+It comprises of
+
+- 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
+
+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))

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/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,312 @@
+#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="Field.{type}" ...></Dynamic>
+```
+
+> it will fallback to a `Field` if a specific type not found.
+
+## Properties.
+
+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="'somestring'"` puts a literal into `prop1` property.
+
+> - 'true', 'false' values are narrowed to boolean,
+> - numbers has been narrowed to number type.
+
+### with resources values
+
+`R`-prefix used to refer any value in the resource bundle.
+
+`prop="R.resId"` assigns `resId` resource value to `prop`.
+
+### with result of expression
+
+`prop="{prop2}"` assigns value of `prop2` property of the current scope.
+
+`prop="{data.key}"` assigns value of `data.key`.
+
+`prop="{!prop2}"` assigns inverted value of `prop2`
+
+`(...)="{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 : 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.
+> - 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.
+
+### 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" />
+```
+
+## Left arrow expression
+
+`data="<- ref.prop"` makes a hot subscription to any property of orbitrary component in the current or upper scopes.
+
+> use pipes to adapt received value `data="<- ref.prop | adjustFn"`.
+
+## Right arrow expression
+
+Right arrow creates a function, that
+
+- `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 `scope.refs[ref].up({ prop1: data })`.
+
+> `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="-> *"` 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.
+
+## 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
+
+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>
+```
+
+# Custom components
+
+There is a [Component] class that could be used an base ancestor for custom components.
+
+While designing custom components you can
+
+- to define life-cycle hooks;
+- to add getters/setter for its properties;
+- 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 {
+
+    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();
+    }
+
+    // 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()
+    }
+
+    // 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: any) {
+        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.onSend(data)', { message });
+    };
+}
+```

package/index.ts

@@ -1,18 +1,20 @@
-import { ICtx, IPlatform } from "arrmatura-api/types";
-import { CRootNode } from "./src/core/root";
+import { IArrmatron, IPlatform } from "arrmatura/types";
 
-export { Registry } from "./src/core";
-export { CRootNode } from "./src/core/root";
+import { CRootNode } from "./src/registry/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 {IArrmatron} 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): IArrmatron => {
+  const root = new CRootNode(template).createArrmatron(platform);
 
   root.up({}, true);
 

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "arrmatura",
-  "version": "6.2.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/**/*"
+    "src",
+    "dist",
+    "index.ts",
+    "types.ts",
+    "docs/**/*"
   ],
   "dependencies": {
-    "arrmatura-api": "1.0.2",
-    "ultimus": "2.1.4"
+    "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"
   }
 }