upd

Author: mattqual

src/SUMMARY.md

@@ -12,6 +12,7 @@
   - [Whack DS](./overview/whack_ds.md)
     - [MXML like constructs](./overview/whack_ds/mxml_like.md)
     - [The good, the bad](./overview/whack_ds/good_bad.md)
+    - [Technical](./overview/whack_ds/technical.md)
   - [Tooling](./overview/tooling.md)
   - [Namespaces](./overview/namespaces.md)
   - [Event model](./overview/event-model.md)

src/overview/whack_ds.md

@@ -1,52 +1,44 @@
 # Whack DS
 
-Whack DS is a feature of the Whack engine used for extending the closed set of Whack element classes with reactive UI components. It is functionally similar to ReactJS, but its syntax is more similar to Adobe MXML.
+Whack DS takes inspiration from both ReactJS and Adobe MXML for GUI dev.
 
 ## Memoization
 
-Whack DS automatically memoizes components, allowing for user customizable Prop/State equality comparison and clones through overriding the `equals` method and implementing a `clone` method.
+Whack DS memoizes components.
 
-Memoization allows to skip re-rendering a component when its Props do not change.
-
-Just like with ReactJS, memoizing components has drawbacks such as possibly volatile code regions (such as when internationalizing a product with locale-specific translation strings). In such cases, relying on a Whack DS context will re-render the component when the context changes regardless of whether props did or not change.
-
-Whack DS skips re-rendering component if the parent re-renders and the props are equals to the previous render; the Whack DS component's own states updating with a different value will always re-render it.
-
-Whack DS implementation stores previous state or previous properties by performing a `generic::clone`. For using custom classes inside states or Properties — like when a tuple, record, `Array` or `Map` is not enough — you may need a `clone` method that returns an object of the same kind and perhaps an `equals` method.
-
-- Custom classes do not need a `clone` method if they are, say, purely data with an optional constructor.
-- Custom classes whose instances should be references (that is, cloned by reference and equal by reference) should implement a `clone` method that returns the this receiver as is and an `equals` method that does simply `===`.
+- It invokes `generic::clone` to clone an object and keep it as a previous state.
+- It invokes `equals` to compare two objects.
 
 ## Style sheets
 
-Whack DS supports style sheets out of the box. Here is a simple example:
+Linking style sheets is easy:
 
 ```sx
-<w:VGroup>
+<div>
     <fx:Style>
     <![CDATA[
         root {
             background: red
         }
     ]]>
     </fx:Style>
-</w:VGroup>
+</div>
 ```
 
 [See: Style sheets](./whack_ds/mxml_like.md#style-sheets)
 
-## Very basic components
+## A basic component
 
 Here is a little code snippet:
 
 ```sx
-package spark.components {
+package zero {
     import whack.ds.UIComponent;
 
-    public class TabBar extends UIComponent {
+    public class Box extends UIComponent {
         var props : Props
 
-        public function TabBar(props : Props) {
+        public function Box(props : Props) {
             super()
             this.props = props
             final = (
@@ -57,11 +49,15 @@ package spark.components {
         public type Props = tap {}
     }
 }
-```
 
-Notet that instances of a component class are throwaway. It's not recommended to explicitly construct such classes or share instances with other code locations.
+import z = zero.*;
+
+var xn:whack.ds.Node;
+
+xn = <z:Box/>
+```
 
-Here's a slightly bigger code snippet for a linear second accumulator:
+## Monotonic counter
 
 ```sx
 package {
@@ -98,58 +94,20 @@ package {
 }
 ```
 
-Even though the constructor is frequently re-evaluated, objects originating from the initial rendering phase are reused for the instance fields.
-
 ## Immutability
 
 Ensure you follow immutability principles with States, Contexts and Props.
 
-> **Note**: ReactJS and Adobe Flex also present the same limitation.
->
-> For a language compiler to implement any actual transitive immutability,
-> significant effort is required, and it may end up increasing the language
-> complexity.
-
-## Callback caching
-
-Whack DS caches callbacks (either lambdas, inline event handlers, instance methods of the same component or Functions declared inside the constructor) within applicable E4X attributes, since they are naturally ever changing `Function` objects regardless of whether they are lambdas or fixtures ─ for example, since they capture locals, `this` or ShockScript lexical contexts, they tend to return different `Function` objects ─ and this is crucial for memoization.
-
-> **Note**: Whack currently **does not cache** callbacks nested in objects. It is not recommended to use lambdas or ever changing Functions inside Prop objects within an E4X literal, as Whack will not give an error or warning for now.
->
-> For the tag-form of setting a Prop in an E4X literal (as in `<s:f>{function(){}}</s:f>`), we have not considered caching either, since this is not very common; although that is easy to support in the future as well.
-
-If a callback appears within a nested block, Whack tries contributing it as a `whack.ds.useCallback` to the component main evaluation's body.
-
-Whack DS doesn't attempt to cache such a callback if it it does not belong to a component's constructor or instance method. If it does belong to a constructor, the callback is cached; but after IR generation, if there is a chance of the constructor exiting execution before the generated `whack.ds.useCallback` callback, the compiler generates an error at the respective tag's attribute.
-
-## Auto dependency tracking
-
-- Whack DS presents extra overhead for State/Context/Prop accessors, so that, say, the surrounding effect or callback is said to be dependent on an used State/Context/Prop.
-  - Subsequent renders may still accumulate more dependencies, like conditional ones.
-- Whack DS E4X attributes assigned to functions or methods from the same component are cached based on dependency tracking; same for E4X event handlers **&amp;=**.
-
-### Props tracking
-
-Whack DS automatically tracks not only states and context dependencies in an effect or callback, but also props.
-
-What Whack DS does internally:
-
-- The Props object is reused across renders. For every render, its internal hash map is cleared and then overwritten.
-- **tap \{\}** types, which are used for representing props, desugar into classes which use a hash map internally for storing only props that are specified. Each prop gets its own getter, which detects surrounding effect or callback and returns the current value of the prop at the internal hash map.
-  - Track prop name for comparison + previous value for the surrounding effect/callback if any
+> **Note**: ReactJS, Adobe Flex and many other technologies also present the same limitation. Since Whack DS uses always imposes references for States, Contexts and Props, not following these principles may lead to internal bugs.
 
 ## Deriveds
 
-Variables derived from States, Contexts, Bindables or Props are often expressed as virtual accessors, as in:
-
 ```sx
-private function get combination() : decimal {
-    use decimal ctx
-    return x + y
-}
-```
+[State]     var x : decimal = 0;
+[Bindable]  var y : decimal = 0;
 
-Using methods is also an option.
+private function get z() : decimal (x + y)
+```
 
 ## Understanding Bindables
 
@@ -217,27 +175,6 @@ State annotatated variables are represented as `State.<T>` instances.
 
 A `State` annotatated variable may be assigned, in addition to its expected value type, a compatible `whack.ds.State.<T>`.
 
-## Component validation
-
-The following apply when using E4X literals to construct `whack.ds.Node`.
-
-- A tag name must resolve to either
-  - A component class that extends `whack.ds.UIComponent`
-    - May be an Alias itself
-  - A Prop (clarified in the subsections)
-  - A context provider
-  - An intrinsic element
-
-Class definitions that extend `whack.ds.UIComponent` are validated in a flat way to avoid programmer bugs:
-
-- The `Alias` meta-data
-- Every instance variable is either
-  - **tap \{\}** typed (at most one variable of this kind, which is usually the Props object)
-  - A `Bindable` annotatated variable
-  - A `Context` annotatated variable
-  - A `State` annotatated variable
-- The class either omits the constructor, or defines a constructor whose signature is either `function():void` or `function(Props):void`, where `Props` must be a **tap \{\}** type.
-
 ## Aliases
 
 A component may be an alias by using the Alias meta-data, which specifies a ShockScript qualified identifier which is treated like a tag name.
@@ -280,15 +217,6 @@ package {
 
 Monochrome icons are filled with the current CSS `color`.
 
-## Recommendations
-
-- *Props*
-  - Don't destructure the props object in large method bodies.
-  - Don't mutate props (although their fields are read-only, unfortunately they are not transitively read-only).
-    - Say you want to reuse a `style` prop from the component inside a `final` tag but also set specific fields: You better create a new `style` object spreading that prop, then pass it to that tag.
-- A best order for a component's constructor may be 1. `super` statement followed by 2. any initial values for instance variables (e.g. Props, States and/or Bindables) followed by 3. effects followed by 4. any custom hooks followed by 5. the `final` construction.
-- If, say, a loop or `switch` creating Whack DS nodes contains its own event handlers, it might be better to define a separate component (perhaps nested) for that purpose, thus getting advantage of callback caching.
-
 ## Tips
 
 - Remember that user-defined hooks do not take *props* as actual components do. If an user-defined hook returns any result, it should typically be either a `State` or `BindableReference` which can be assigned to a State or Bindable annotatated variable.

src/overview/whack_ds/good_bad.md

@@ -79,4 +79,79 @@ final = (
     <cset:Evaluator
         finish={function(e){doIt()}} />
 )       // GOOD
+```
+
+## :&#x28; ⸻ Props
+
+```sx
+class Box extends UIComponent {
+    function Box({ x } : Props) {
+        super()
+        whack.ds.useEffect(function() {
+            if (x == 0) {
+                trace("zero!")
+            }
+        });
+        final = (
+            <></>
+        )
+    }
+
+    type Props = tap {
+        x : uint,
+    }
+}
+```
+
+## :&#x29; ⸻ Props
+
+```sx
+class Box extends UIComponent {
+    function Box(props : Props) {
+        super()
+        whack.ds.useEffect(function() {
+            if (props.x == 0) {
+                trace("zero!")
+            }
+        });
+        final = (
+            <></>
+        )
+    }
+
+    type Props = tap {
+        x : uint,
+    }
+}
+```
+
+## :&#x29; ⸻ Evaluation order
+
+```sx
+class Box extends UIComponent {
+    [Bindable]
+    var outside : uint;
+
+    function Box(props : Props) {
+        // 1 - super
+        super()
+
+        // 2 - variable initials & custom hooks
+        outside = props.outside;
+        ...
+
+        // 3 - effects & custom hooks
+        ...
+
+        // 5 - final
+        ...
+        final = (
+            <></>
+        )
+    }
+
+    type Props = tap {
+        outside : whack.ds.BindableReference.<uint>,
+    }
+}
 ```

src/overview/whack_ds/technical.md

@@ -0,0 +1,65 @@
+# Technical
+
+## Memoization
+
+Whack DS automatically memoizes components, allowing for user customizable Prop/State equality comparison and clones through overriding the `equals` method and implementing a `clone` method.
+
+Memoization allows to skip re-rendering a component when its Props do not change.
+
+Just like with ReactJS, memoizing components has drawbacks such as possibly volatile code regions (such as when internationalizing a product with locale-specific translation strings). In such cases, relying on a Whack DS context will re-render the component when the context changes regardless of whether props did or not change.
+
+Whack DS skips re-rendering component if the parent re-renders and the props are equals to the previous render; the Whack DS component's own states updating with a different value will always re-render it.
+
+Whack DS implementation stores previous state or previous properties by performing a `generic::clone`. For using custom classes inside states or Properties — like when a tuple, record, `Array` or `Map` is not enough — you may need a `clone` method that returns an object of the same kind and perhaps an `equals` method.
+
+- Custom classes do not need a `clone` method if they are, say, purely data with an optional constructor.
+- Custom classes whose instances should be references (that is, cloned by reference and equal by reference) should implement a `clone` method that returns the this receiver as is and an `equals` method that does simply `===`.
+
+## Callback caching
+
+Whack DS caches callbacks (either lambdas, inline event handlers, instance methods of the same component or Functions declared inside the constructor) within applicable E4X attributes, since they are naturally ever changing `Function` objects regardless of whether they are lambdas or fixtures ─ for example, since they capture locals, `this` or ShockScript lexical contexts, they tend to return different `Function` objects ─ and this is crucial for memoization.
+
+> **Note**: Whack currently **does not cache** callbacks nested in objects. It is not recommended to use lambdas or ever changing Functions inside Prop objects within an E4X literal, as Whack will not give an error or warning for now.
+>
+> For the tag-form of setting a Prop in an E4X literal (as in `<s:f>{function(){}}</s:f>`), we have not considered caching either, since this is not very common; although that is easy to support in the future as well.
+
+If a callback appears within a nested block, Whack tries contributing it as a `whack.ds.useCallback` to the component main evaluation's body.
+
+Whack DS doesn't attempt to cache such a callback if it it does not belong to a component's constructor or instance method. If it does belong to a constructor, the callback is cached; but after IR generation, if there is a chance of the constructor exiting execution before the generated `whack.ds.useCallback` callback, the compiler generates an error at the respective tag's attribute.
+
+## Auto dependency tracking
+
+- Whack DS presents extra overhead for State/Context/Prop accessors, so that, say, the surrounding effect or callback is said to be dependent on an used State/Context/Prop.
+  - Subsequent renders may still accumulate more dependencies, like conditional ones.
+- Whack DS E4X attributes assigned to functions or methods from the same component are cached based on dependency tracking; same for E4X event handlers **&amp;=**.
+
+### Props tracking
+
+Whack DS automatically tracks not only states and context dependencies in an effect or callback, but also props.
+
+What Whack DS does internally:
+
+- The Props object is reused across renders. For every render, its internal hash map is cleared and then overwritten.
+- **tap \{\}** types, which are used for representing props, desugar into classes which use a hash map internally for storing only props that are specified. Each prop gets its own getter, which detects surrounding effect or callback and returns the current value of the prop at the internal hash map.
+  - Track prop name for comparison + previous value for the surrounding effect/callback if any
+
+## Component validation
+
+The following apply when using E4X literals to construct `whack.ds.Node`.
+
+- A tag name must resolve to either
+  - A component class that extends `whack.ds.UIComponent`
+    - May be an Alias itself
+  - A Prop (clarified in the subsections)
+  - A context provider
+  - An intrinsic element
+
+Class definitions that extend `whack.ds.UIComponent` are validated in a flat way to avoid programmer bugs:
+
+- The `Alias` meta-data
+- Every instance variable is either
+  - **tap \{\}** typed (at most one variable of this kind, which is usually the Props object)
+  - A `Bindable` annotatated variable
+  - A `Context` annotatated variable
+  - A `State` annotatated variable
+- The class either omits the constructor, or defines a constructor whose signature is either `function():void` or `function(Props):void`, where `Props` must be a **tap \{\}** type.