verstak 0.23.107 → 0.23.109

package/README.md

@@ -5,23 +5,44 @@
 
 # **Verstak** - Experimental Front-End Library
 
-Verstak is an experimental JavaScript library that provides
-chain-based an table-based layouts with
-[transactional reactive](https://blog.nezaboodka.com/post/2019/593-modern-database-should-natively-support-transactionally-reactive-programming)
-facilities for building front-end applications.
-
-Transactional reactivity means that state changes are being made in an
-isolated data snapshot and then, once atomically applied, are
-**consistently propagated** to corresponding visual components for
-(re)rendering. All that is done in automatic, seamless, and fine-grained
-way, because reactronic **takes full care of tracking dependencies**
-between visual components (observers) and state objects (observables).
-
-Based on Reactronic: https://github.com/nezaboodka/reactronic/blob/master/README.md#readme
-
-Example of the application built with Verstak: https://nevod.io
-
-Source code of the example: https://gitlab.com/nezaboodka/nevod.web.public/-/blob/master/README.md
+Verstak is a experimental library for rapid development of user
+interfaces. It provides **automatic refresh** of visual elements
+upon change of underlying data in a program.
+
+Refresh on the screen is **fine-grained**, meaning that only
+those visual elements are refreshed, which really depend on
+actual data changed. It is achieved by automatic tracking of
+all dependencies between visual elements and data they use
+during run time. Such an approach is usually called reactive
+programming. It frees a programmer from writing boilerplate
+code for "pushing" changed data to visual elements.
+
+Changing of compound data and refreshing of visual elements
+on the screen is performed consistently, in other words in
+"all-or-nothing" way. It means that in case of changing
+multiple variables in a program actual visual refresh
+happens only in case of successful change of all the variables.
+Partial changes are "not visible" to visual elements even
+in case of exception or cancellation of changes. Such a
+change of compound data in "all-or-nothing" way is called
+a transaction.
+
+Verstak supports asynchronous programming out of the box
+at all the layers, including transactions and visual elements
+rendering.
+
+Altogether it is called reactive transactional programming.
+Transactional reactivity means that state changes are being
+made in an isolated data snapshot and then, once atomically
+applied, are **consistently propagated** to corresponding
+visual components for (re)rendering. All that is done in
+automatic, seamless, and fine-grained way, because Verstak
+**takes full care of tracking dependencies** between visual
+components (observers) and state objects (observables).
+
+Example application: https://nevod.io ([source code](https://gitlab.com/nezaboodka/nevod.web.public/-/blob/master/README.md)).
+
+Verstak is based on [Reactronic](https://github.com/nezaboodka/reactronic/blob/master/README.md#readme).
 
 # Contribution
 

package/build/dist/source/core/Interfaces.d.ts

@@ -0,0 +1,134 @@
+import { CollectionReader, Item, MemberOptions } from "reactronic";
+export type Callback<T = unknown> = (native: T) => void;
+export type Delegate<T = unknown, M = unknown, C = unknown, R = void> = (block: Block<T, M, C, R>, base: () => R) => R;
+export type AsyncDelegate<T = unknown, M = unknown> = (block: Block<T, M, Promise<void>>) => Promise<void>;
+export type SimpleDelegate<T = unknown> = (block: Block<T, any, any, any>) => void;
+export declare enum BlockKind {
+    Band = 0,
+    Table = 1,
+    Note = 2,
+    Group = 3,
+    Row = 4,
+    Cursor = 5,
+    Native = 6
+}
+export interface Block<T = unknown, M = unknown, C = unknown, R = void> {
+    readonly descriptor: BlockDescriptor<T, M, C, R>;
+    readonly native: T;
+    readonly isBand: boolean;
+    readonly isTable: boolean;
+    model: M;
+    controller: C;
+    kind: BlockKind;
+    area: BlockArea;
+    widthGrowth: number;
+    minWidth: string;
+    maxWidth: string;
+    heightGrowth: number;
+    minHeight: string;
+    maxHeight: string;
+    contentAlignment: Align;
+    blockAlignment: Align;
+    contentWrapping: boolean;
+    overlayVisible: boolean | undefined;
+    childrenShuffling: boolean;
+    renderingPriority?: Priority;
+    isSequential: boolean;
+    readonly isInitialRendering: boolean;
+    useStyle(styleName: string, enabled?: boolean): void;
+    configureReactronic(options: Partial<MemberOptions>): MemberOptions;
+}
+export interface BlockDescriptor<T = unknown, M = unknown, C = unknown, R = void> {
+    readonly key: string;
+    readonly driver: Driver<T>;
+    readonly builder: Readonly<BlockBuilder<T, M, C, R>>;
+    readonly level: number;
+    readonly owner: Block;
+    readonly host: Block;
+    readonly children: CollectionReader<Block>;
+    readonly item: Item<Block> | undefined;
+    readonly stamp: number;
+    readonly outer: Block;
+    readonly context: BlockCtx | undefined;
+}
+export interface BlockBuilder<T = unknown, M = unknown, C = unknown, R = void> {
+    base?: BlockBuilder<T, M, C, R>;
+    key?: string;
+    mode?: Mode;
+    triggers?: unknown;
+    claim?: Delegate<T, M, C, R>;
+    create?: Delegate<T, M, C, R>;
+    initialize?: Delegate<T, M, C, R>;
+    render?: Delegate<T, M, C, R>;
+    finalize?: Delegate<T, M, C, R>;
+}
+export interface BlockCtx<T extends Object = Object> {
+    value: T;
+}
+export interface Driver<T, C = unknown> {
+    readonly name: string;
+    readonly isRow: boolean;
+    readonly preset?: SimpleDelegate<T>;
+    claim(block: Block<T, unknown, C>): void;
+    create(block: Block<T, unknown, C>, b: {
+        native?: T;
+        controller?: C;
+    }): void;
+    initialize(block: Block<T, unknown, C>): void;
+    mount(block: Block<T, unknown, C>): void;
+    render(block: Block<T, unknown, C>): void | Promise<void>;
+    finalize(block: Block<T, unknown, C>, isLeader: boolean): boolean;
+    applyKind(block: Block<T, any, C, any>, value: BlockKind): void;
+    applyCoords(block: Block<T, any, C, any>, value: BlockCoords | undefined): void;
+    applyWidthGrowth(block: Block<T, any, C, any>, value: number): void;
+    applyMinWidth(block: Block<T, any, C, any>, value: string): void;
+    applyMaxWidth(block: Block<T, any, C, any>, value: string): void;
+    applyHeightGrowth(block: Block<T, any, C, any>, value: number): void;
+    applyMinHeight(block: Block<T, any, C, any>, value: string): void;
+    applyMaxHeight(block: Block<T, any, C, any>, value: string): void;
+    applyContentAlignment(block: Block<T, any, C, any>, value: Align): void;
+    applyBlockAlignment(block: Block<T, any, C, any>, value: Align): void;
+    applyContentWrapping(block: Block<T, any, C, any>, value: boolean): void;
+    applyOverlayVisible(block: Block<T, any, C, any>, value: boolean | undefined): void;
+    applyStyle(block: Block<T, any, C, any>, secondary: boolean, styleName: string, enabled?: boolean): void;
+}
+export interface BlockCoords {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+export declare const enum Priority {
+    Realtime = 0,
+    Normal = 1,
+    Background = 2
+}
+export declare enum Mode {
+    Default = 0,
+    PinpointRefresh = 1,
+    ManualMounting = 2
+}
+export declare enum Align {
+    Stretch = 0,
+    Left = 1,
+    CenterX = 2,
+    Right = 3,
+    Top = 4,
+    CenterY = 8,
+    Bottom = 12,
+    Default = 16,
+    Center = 10
+}
+export interface ElasticSize {
+    cells?: number;
+    min?: string;
+    max?: string;
+    growth?: number;
+}
+export interface TrackSize extends ElasticSize {
+    track?: string | number;
+}
+export type BlockArea = undefined | string | {
+    cellsOverWidth?: number;
+    cellsOverHeight?: number;
+};

package/build/dist/source/core/Interfaces.js

@@ -0,0 +1,34 @@
+export var BlockKind;
+(function (BlockKind) {
+    BlockKind[BlockKind["Band"] = 0] = "Band";
+    BlockKind[BlockKind["Table"] = 1] = "Table";
+    BlockKind[BlockKind["Note"] = 2] = "Note";
+    BlockKind[BlockKind["Group"] = 3] = "Group";
+    BlockKind[BlockKind["Row"] = 4] = "Row";
+    BlockKind[BlockKind["Cursor"] = 5] = "Cursor";
+    BlockKind[BlockKind["Native"] = 6] = "Native";
+})(BlockKind || (BlockKind = {}));
+export var Priority;
+(function (Priority) {
+    Priority[Priority["Realtime"] = 0] = "Realtime";
+    Priority[Priority["Normal"] = 1] = "Normal";
+    Priority[Priority["Background"] = 2] = "Background";
+})(Priority || (Priority = {}));
+export var Mode;
+(function (Mode) {
+    Mode[Mode["Default"] = 0] = "Default";
+    Mode[Mode["PinpointRefresh"] = 1] = "PinpointRefresh";
+    Mode[Mode["ManualMounting"] = 2] = "ManualMounting";
+})(Mode || (Mode = {}));
+export var Align;
+(function (Align) {
+    Align[Align["Stretch"] = 0] = "Stretch";
+    Align[Align["Left"] = 1] = "Left";
+    Align[Align["CenterX"] = 2] = "CenterX";
+    Align[Align["Right"] = 3] = "Right";
+    Align[Align["Top"] = 4] = "Top";
+    Align[Align["CenterY"] = 8] = "CenterY";
+    Align[Align["Bottom"] = 12] = "Bottom";
+    Align[Align["Default"] = 16] = "Default";
+    Align[Align["Center"] = 10] = "Center";
+})(Align || (Align = {}));

package/build/dist/source/core/Utils.d.ts

@@ -1,2 +1,8 @@
+import { BlockCoords } from "./Interfaces";
+export declare function parseBlockCoords(text: string, result: BlockCoords): BlockCoords;
+export declare function emitBlockCoords(value: BlockCoords): string;
+export declare function emitLetters(n: number): string;
+export declare function emitCellPosition(x: number, y: number): string;
+export declare function equalBlockCoords(a: BlockCoords, b: BlockCoords): boolean;
 export declare function objectHasMember<T>(obj: any, member: string): obj is T;
 export declare function getCallerInfo(prefix: string): string;

package/build/dist/source/core/Utils.js

@@ -1,3 +1,179 @@
+export function parseBlockCoords(text, result) {
+    let i = 0;
+    let value = 0;
+    let sign = 1;
+    let component = 0;
+    while (i < text.length) {
+        const charCode = text.charCodeAt(i);
+        if (isCapitalLetter(charCode)) {
+            if (component % 2 === 0)
+                value = value * 26 + charCode - 64;
+            else
+                console.error(`Digit is expected, but letter ('${text[i]}') was read`);
+        }
+        else if (isLowercaseLetter(charCode)) {
+            if (component % 2 === 0) {
+                value = value * 26 + charCode - 96;
+            }
+            else {
+                console.error(`Digit is expected, but letter ('${text[i]}') was read`);
+            }
+        }
+        else if (isDigit(charCode)) {
+            if (component % 2 === 0) {
+                if (value !== 0) {
+                    if (component === 0)
+                        result.x1 = value * sign;
+                    else
+                        result.x2 = value * sign;
+                    value = 0;
+                }
+                component++;
+            }
+            value = value * 10 + charCode - 48;
+        }
+        else if (charCode === 40) {
+            if (component === 0)
+                result.x1 = value * sign;
+            else if (component === 2)
+                result.x2 = value * sign;
+            if (sign > 0) {
+                sign = -1;
+                component &= ~1;
+                value = 0;
+            }
+            else {
+                console.error("Sign must not be negative");
+            }
+        }
+        else if (charCode === 41) {
+            if (sign > 0) {
+                console.error("Sign must be negative");
+            }
+            switch (component) {
+                case 0:
+                    result.x1 = value * sign;
+                    break;
+                case 1:
+                    result.y1 = value * sign;
+                    break;
+                case 2:
+                    result.x2 = value * sign;
+                    break;
+                case 3:
+                    result.y2 = value * sign;
+                    break;
+            }
+            sign = 1;
+            value = 0;
+            component++;
+        }
+        else if (charCode === 58) {
+            if (sign < 0)
+                console.error(`area '${text}': e1`);
+            if (component === 1)
+                result.y1 = value * sign;
+            else if (component !== 2)
+                console.error(`area '${text}': [e2] component = ${component}`);
+            component = 2;
+            value = 0;
+        }
+        else if (isWhitespace(charCode)) {
+        }
+        else {
+            console.error(`Unknown symbol '${text[i]}' in '${text}'`);
+        }
+        i++;
+    }
+    if (value !== 0) {
+        switch (component) {
+            case 0: {
+                result.x1 = value * sign;
+                if (sign < 0 && result.y1 === 0)
+                    result.y1 = sign;
+                break;
+            }
+            case 1: {
+                if (sign < 0 && result.x1 === 0)
+                    result.x1 = sign;
+                result.y1 = value * sign;
+                break;
+            }
+            case 2: {
+                result.x2 = value * sign;
+                if (sign < 0 && result.y2 === 0)
+                    result.y2 = sign;
+                break;
+            }
+            case 3: {
+                if (sign < 0 && result.x2 === 0)
+                    result.x2 = sign;
+                result.y2 = value * sign;
+                break;
+            }
+        }
+    }
+    else if (sign < 0) {
+        if (component === 0) {
+            if (result.x1 === 0)
+                result.x1 = sign;
+            if (result.y1 === 0)
+                result.y1 = sign;
+        }
+        else {
+            if (result.x2 === 0)
+                result.x2 = sign;
+            if (result.y2 === 0)
+                result.y2 = sign;
+        }
+    }
+    return result;
+}
+export function emitBlockCoords(value) {
+    const p1 = emitCellPosition(value.x1, value.y1);
+    const p2 = emitCellPosition(value.x2, value.y2);
+    return `${p1}${p2 !== "" ? `:${p2}` : ""}`;
+}
+export function emitLetters(n) {
+    if (n < 0)
+        throw new Error(`emitLetters: argument (${n}) should not be negative or zero`);
+    let result = "";
+    while (n >= 0) {
+        const r = n % 26;
+        n = Math.floor(n / 26) - 1;
+        result = String.fromCharCode(65 + r) + result;
+    }
+    return result;
+}
+export function emitCellPosition(x, y) {
+    let result = "";
+    if (x > 0 && y > 0)
+        result = `${emitLetters(x - 1)}${y}`;
+    else if (x > 0 && y < 0)
+        result = `${emitLetters(x - 1)}(${-y})`;
+    else if (x < 0 && y > 0)
+        result = `(${emitLetters(-x - 1)})${y}`;
+    else if (x < 0 && y < 0)
+        result = `(${emitLetters(-x - 1)}${-y})`;
+    else
+        result = "";
+    return result;
+}
+export function equalBlockCoords(a, b) {
+    return a.x1 === b.x1 && a.y1 === b.y1 && a.x2 === b.x2 && a.y1 === b.y2;
+}
+function isWhitespace(char) {
+    return char === 32 || (char >= 9 && char <= 13) || char === 133 || char === 160;
+}
+function isDigit(input, index) {
+    return 48 <= input && input <= 57;
+}
+function isCapitalLetter(ch) {
+    return 65 <= ch && ch <= 90;
+}
+function isLowercaseLetter(ch) {
+    return 97 <= ch && ch <= 122;
+}
 export function objectHasMember(obj, member) {
     return obj === Object(obj) && !Array.isArray(obj) && member in obj;
 }

package/build/dist/source/core/Verstak.d.ts

@@ -0,0 +1,69 @@
+import { LoggingOptions } from "reactronic";
+import { BlockCoords, BlockKind, Priority, Align, BlockBuilder, Block, Driver, SimpleDelegate } from "./Interfaces";
+export declare class Verstak {
+    static readonly shortFrameDuration = 16;
+    static readonly longFrameDuration = 300;
+    static currentRenderingPriority: Priority;
+    static frameDuration: number;
+    static claim<T = undefined, M = unknown, C = unknown, R = void>(driver: Driver<T>, builder?: BlockBuilder<T, M, C, R>, base?: BlockBuilder<T, M, C, R>): Block<T, M, C, R>;
+    static get block(): Block;
+    static renderNestedTreesThenDo(action: (error: unknown) => void): void;
+    static getDefaultLoggingOptions(): LoggingOptions | undefined;
+    static setDefaultLoggingOptions(logging?: LoggingOptions): void;
+}
+export declare class BaseDriver<T, C = unknown> implements Driver<T, C> {
+    readonly name: string;
+    readonly isRow: boolean;
+    readonly preset?: SimpleDelegate<T> | undefined;
+    static readonly fragment: BaseDriver<any, unknown>;
+    constructor(name: string, isRow: boolean, preset?: SimpleDelegate<T> | undefined);
+    claim(block: Block<T, unknown, C>): void;
+    create(block: Block<T, unknown, C>, b: {
+        native?: T;
+        controller?: C;
+    }): void;
+    initialize(block: Block<T, unknown, C>): void;
+    mount(block: Block<T, unknown, C>): void;
+    render(block: Block<T, unknown, C>): void | Promise<void>;
+    finalize(block: Block<T, unknown, C>, isLeader: boolean): boolean;
+    applyKind(block: Block<T, any, C, any>, value: BlockKind): void;
+    applyCoords(block: Block<T, any, C, any>, value: BlockCoords | undefined): void;
+    applyWidthGrowth(block: Block<T, any, C, any>, value: number): void;
+    applyMinWidth(block: Block<T, any, C, any>, value: string): void;
+    applyMaxWidth(block: Block<T, any, C, any>, value: string): void;
+    applyHeightGrowth(block: Block<T, any, C, any>, value: number): void;
+    applyMinHeight(block: Block<T, any, C, any>, value: string): void;
+    applyMaxHeight(block: Block<T, any, C, any>, value: string): void;
+    applyContentAlignment(block: Block<T, any, C, any>, value: Align): void;
+    applyBlockAlignment(block: Block<T, any, C, any>, value: Align): void;
+    applyContentWrapping(block: Block<T, any, C, any>, value: boolean): void;
+    applyOverlayVisible(block: Block<T, any, C, any>, value: boolean | undefined): void;
+    applyStyle(block: Block<T, any, C, any>, secondary: boolean, styleName: string, enabled?: boolean): void;
+}
+export declare class StaticDriver<T> extends BaseDriver<T> {
+    readonly element: T;
+    constructor(element: T, name: string, isRow: boolean, preset?: SimpleDelegate<T>);
+    create(block: Block<T, unknown, unknown, void>, b: {
+        native?: T;
+        controller?: unknown;
+    }): void;
+}
+export declare class CursorCommand {
+    absolute?: string;
+    columnShift?: number;
+    rowShift?: number;
+}
+export declare class CursorCommandDriver extends BaseDriver<CursorCommand, void> {
+    constructor();
+    create(block: Block<CursorCommand, unknown, void, void>, b: {
+        native?: CursorCommand;
+        controller?: void;
+    }): void;
+}
+export declare class ContextVariable<T extends Object = Object> {
+    readonly defaultValue: T | undefined;
+    constructor(defaultValue?: T);
+    set value(value: T);
+    get value(): T;
+    get valueOrUndefined(): T | undefined;
+}