@effindomv2/fui-as 0.1.6 → 0.1.7

package/browser/src/common-harness/ui-imports.ts

@@ -128,12 +128,15 @@ export function createUiImportModule(deps: UiImportDeps) {
     ui_set_height(handle: AppHandleLike, value: number, unit: number): void {
       deps.getRuntime().ui._ui_set_height(toBigIntHandle(handle), value, unit);
     },
+    ui_set_fill_width(handle: AppHandleLike, fill: number): void {
+      deps.getRuntime().ui._ui_set_fill_width(toBigIntHandle(handle), fill);
+    },
+    ui_set_fill_height(handle: AppHandleLike, fill: number): void {
+      deps.getRuntime().ui._ui_set_fill_height(toBigIntHandle(handle), fill);
+    },
     ui_set_flex_direction(handle: AppHandleLike, direction: number): void {
       deps.getRuntime().ui._ui_set_flex_direction(toBigIntHandle(handle), direction);
     },
-    ui_set_flex_grow(handle: AppHandleLike, grow: number): void {
-      deps.getRuntime().ui._ui_set_flex_grow(toBigIntHandle(handle), grow);
-    },
     ui_set_flex_basis(handle: AppHandleLike, basis: number): void {
       deps.getRuntime().ui._ui_set_flex_basis(toBigIntHandle(handle), basis);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effindomv2/fui-as",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "license": "AGPL-3.0-only OR LicenseRef-EffinDom-Commercial",
   "description": "EffinDom v2 AssemblyScript frontend framework SDK and browser harness",
@@ -78,7 +78,7 @@
   },
   "dependencies": {
     "@assemblyscript/loader": "^0.28.17",
-    "@effindomv2/runtime": "0.1.1"
+    "@effindomv2/runtime": "0.1.2"
   },
   "devDependencies": {
     "@as-pect/assembly": "8.1.0",

package/scripts/build.sh

@@ -124,10 +124,10 @@ resolve_runtime_dist_dir() {
   fi
 
   candidates+=(
+    "${REPO_ROOT}/public/v2/browser-bridge"
+    "${REPO_ROOT}/v2/browser-bridge/dist"
     "${PACKAGE_DIR}/node_modules/@effindomv2/runtime/dist"
     "${REPO_ROOT}/node_modules/@effindomv2/runtime/dist"
-    "${REPO_ROOT}/v2/browser-bridge/dist"
-    "${REPO_ROOT}/public/v2/browser-bridge"
   )
 
   for candidate in "${candidates[@]}"; do
@@ -177,9 +177,11 @@ copy_runtime_assets() {
     cp "${RUNTIME_DIST_DIR}/icu-asset.json" "${destination}/runtime/dist/icu-asset.json"
   fi
   cp -R "${RUNTIME_DIST_DIR}/runtime" "${destination}/runtime/dist/runtime"
-  if [ -d "${RUNTIME_DIST_DIR}/fonts" ]; then
-    mkdir -p "${destination}/runtime"
-    cp -R "${RUNTIME_DIST_DIR}/fonts" "${destination}/runtime/fonts"
+  mkdir -p "${destination}/runtime/fonts"
+  if [ -d "${REPO_ROOT}/public/v2/fonts" ]; then
+    cp -R "${REPO_ROOT}/public/v2/fonts/." "${destination}/runtime/fonts/"
+  elif [ -d "${RUNTIME_DIST_DIR}/fonts" ]; then
+    cp -R "${RUNTIME_DIST_DIR}/fonts/." "${destination}/runtime/fonts/"
   fi
 }
 

package/src/bindings/ui.ts

@@ -100,12 +100,16 @@ export function setHeight(handle: u64, value: f32, unit: u32): void {
   ffi.ui_set_height(handle, value, unit);
 }
 
-export function setFlexDirection(handle: u64, direction: u32): void {
-  ffi.ui_set_flex_direction(handle, direction);
+export function setFillWidth(handle: u64, fill: bool): void {
+  ffi.ui_set_fill_width(handle, fill);
+}
+
+export function setFillHeight(handle: u64, fill: bool): void {
+  ffi.ui_set_fill_height(handle, fill);
 }
 
-export function setFlexGrow(handle: u64, grow: f32): void {
-  ffi.ui_set_flex_grow(handle, grow);
+export function setFlexDirection(handle: u64, direction: u32): void {
+  ffi.ui_set_flex_direction(handle, direction);
 }
 
 export function setFlexBasis(handle: u64, basis: f32): void {

package/src/controls/Dropdown.ts

@@ -251,7 +251,7 @@ export class Dropdown extends FlexBox implements GlobalKeyHandler {
     this.cursor(CursorStyle.Pointer);
     this.flexDirection(FlexDirection.Row);
     this.alignItems(AlignItems.Center);
-    fieldPresenter.root.flexGrow(1.0);
+    fieldPresenter.root.fillWidth();
     fieldPresenter.chevronHost.child(chevronPresenter.root);
     this.child(fieldPresenter.root);
     this.child(this.popupRoot);
@@ -780,7 +780,7 @@ export class Dropdown extends FlexBox implements GlobalKeyHandler {
     this.padding(0.0, 0.0, 0.0, 0.0);
     this.bgColor(0x00000000);
     this.opacity(this.isEnabled ? 1.0 : 0.6);
-    this.fieldPresenter.root.flexGrow(1.0);
+    this.fieldPresenter.root.fillWidth();
     this.fieldPresenter.apply(
       theme,
       new DropdownFieldVisualState(
@@ -845,7 +845,7 @@ export class Dropdown extends FlexBox implements GlobalKeyHandler {
     const previousFieldRoot = this.fieldPresenter.root;
     this.fieldPresenter = nextFieldPresenter;
     this.chevronPresenter = nextChevronPresenter;
-    nextFieldPresenter.root.flexGrow(1.0);
+    nextFieldPresenter.root.fillWidth();
     nextFieldPresenter.chevronHost.addChildNode(nextChevronPresenter.root);
     const children = new Array<Node>();
     children.push(nextFieldPresenter.root);

package/src/controls/internal/DropdownFieldPresenter.ts

@@ -63,8 +63,7 @@ class DefaultDropdownFieldPresenter extends DropdownFieldPresenter {
       .overflowFade(true, false)
       .verticalAlign(TextVerticalAlign.Center);
     const valueHost = new FlexBox()
-      .width(0.0, Unit.Pixel)
-      .flexGrow(1.0)
+      .fillWidth()
       .child(valueNode) as FlexBox;
     const chevronHost = new FlexBox()
       .width(DEFAULT_CHEVRON_BOX_SIZE, Unit.Pixel)
@@ -88,8 +87,7 @@ class DefaultDropdownFieldPresenter extends DropdownFieldPresenter {
       .padding(theme.spacing.md, theme.spacing.sm, theme.spacing.md, theme.spacing.sm)
       .bgColor(state.pressed && state.enabled ? theme.colors.background : theme.colors.surface);
     this.valueHost
-      .width(0.0, Unit.Pixel)
-      .flexGrow(1.0);
+      .fillWidth();
     this.valueNode
       .font(theme.fonts.body, theme.fonts.sizeBody)
       .textColor(state.enabled ? theme.colors.textPrimary : theme.colors.textMuted);

package/src/controls/internal/PressableLabeledControl.ts

@@ -44,8 +44,7 @@ export class PressableLabeledControl extends FlexBox {
       .width(activeTheme.value.spacing.sm, Unit.Pixel)
       .height(1.0, Unit.Pixel);
     this.labelHost = new FlexBox()
-      .flexBasis(0.0)
-      .flexGrow(1.0);
+      .fillWidth();
     this.labelNode.width(100.0, Unit.Percent);
     this.labelHost.child(this.labelNode);
 

package/src/controls/internal/TextInputCore.ts

@@ -190,6 +190,7 @@ export class TextInputCore extends FlexBox {
     this.placeholderHost = new TextInputPlaceholderHost(this, this.placeholderText);
     if (profile.multiline) {
       const scrollBox = new ScrollBox(new ScrollState(), new TextInputEditorViewport(this))
+        .fillSize()
         .child(this.editorText) as ScrollBox;
       this.editorScrollBox = scrollBox;
       this.child(scrollBox);
@@ -488,9 +489,7 @@ export class TextInputCore extends FlexBox {
     if (scrollBox !== null) {
       scrollBox.cursor(CursorStyle.Default);
       scrollBox.viewport.cursor(editableCursor);
-      scrollBox.width(100.0, Unit.Percent);
-      scrollBox.height(100.0, Unit.Percent);
-      scrollBox.flexGrow(1.0);
+      scrollBox.fillSize();
       this.syncScrollChromeState();
     }
     this.syncFocusChrome(theme);

package/src/core/Errors.ts

@@ -8,6 +8,14 @@ export class ObjectDisposedError extends Error {
   }
 }
 
+export class VirtualListItemBindingError extends Error {
+  constructor() {
+    const message = "VirtualList: item renderer not configured. Call .onBindItem() or .onBindItemWith() after construction.";
+    super(message);
+    this.name = "VirtualListItemBindingError";
+  }
+}
+
 export function throwNullArgument(functionName: string, argumentName: string): void {
   error("Validation", functionName + ": " + argumentName + " must not be null");
   throw new TypeError(functionName + ": " + argumentName + " must not be null");

package/src/core/ffi.ts

@@ -228,12 +228,15 @@ export declare function ui_set_width(handle: u64, value: f32, unit: u32): void;
 @external("effindom_v2_ui", "ui_set_height")
 export declare function ui_set_height(handle: u64, value: f32, unit: u32): void;
 
+@external("effindom_v2_ui", "ui_set_fill_width")
+export declare function ui_set_fill_width(handle: u64, fill: bool): void;
+
+@external("effindom_v2_ui", "ui_set_fill_height")
+export declare function ui_set_fill_height(handle: u64, fill: bool): void;
+
 @external("effindom_v2_ui", "ui_set_flex_direction")
 export declare function ui_set_flex_direction(handle: u64, direction: u32): void;
 
-@external("effindom_v2_ui", "ui_set_flex_grow")
-export declare function ui_set_flex_grow(handle: u64, grow: f32): void;
-
 @external("effindom_v2_ui", "ui_set_flex_basis")
 export declare function ui_set_flex_basis(handle: u64, basis: f32): void;
 

package/src/nodes/FlexBox.ts

@@ -38,17 +38,17 @@ export class FlexBoxProps {
   widthValue: f32 = 0.0;
   widthUnit: Unit = Unit.Pixel;
   hasWidth: bool = false;
+  hasFillWidth: bool = false;
   heightValue: f32 = 0.0;
   heightUnit: Unit = Unit.Pixel;
   hasHeight: bool = false;
+  hasFillHeight: bool = false;
   flexBasisValue: f32 = 0.0;
   hasFlexBasis: bool = false;
   backgroundColor: u32 = 0;
   hasBackgroundColor: bool = false;
   flexDirectionValue: FlexDirection = FlexDirection.Column;
   hasFlexDirection: bool = false;
-  flexGrowValue: f32 = 0.0;
-  hasFlexGrow: bool = false;
   justifyContentValue: JustifyContent = JustifyContent.Start;
   hasJustifyContent: bool = false;
   alignItemsValue: AlignItems = AlignItems.Start;
@@ -72,9 +72,11 @@ export class FlexBox extends Node {
   private widthValue: f32 = 0.0;
   private widthUnit: Unit = Unit.Pixel;
   private hasWidth: bool = false;
+  private hasFillWidth: bool = false;
   private heightValue: f32 = 0.0;
   private heightUnit: Unit = Unit.Pixel;
   private hasHeight: bool = false;
+  private hasFillHeight: bool = false;
   private flexBasisValue: f32 = 0.0;
   private hasFlexBasis: bool = false;
   private backgroundColor: u32 = 0;
@@ -91,8 +93,6 @@ export class FlexBox extends Node {
   private borderDashOff: f32 = 0.0;
   private flexDirectionValue: FlexDirection = FlexDirection.Column;
   private hasFlexDirection: bool = false;
-  private flexGrowValue: f32 = 0.0;
-  private hasFlexGrow: bool = false;
   private justifyContentValue: JustifyContent = JustifyContent.Start;
   private hasJustifyContent: bool = false;
   private alignItemsValue: AlignItems = AlignItems.Start;
@@ -149,6 +149,7 @@ export class FlexBox extends Node {
     this.widthValue = value;
     this.widthUnit = unit;
     this.hasWidth = true;
+    this.hasFillWidth = false;
     if (this.hasBuiltHandle()) {
       ui.setWidth(this.handle, value, <u32>unit);
       this.notifyRetainedLayoutMutation();
@@ -160,6 +161,7 @@ export class FlexBox extends Node {
     this.heightValue = value;
     this.heightUnit = unit;
     this.hasHeight = true;
+    this.hasFillHeight = false;
     if (this.hasBuiltHandle()) {
       ui.setHeight(this.handle, value, <u32>unit);
       this.notifyRetainedLayoutMutation();
@@ -168,12 +170,20 @@ export class FlexBox extends Node {
   }
 
   fillWidth(): this {
-    this.width(100.0, Unit.Percent);
+    this.hasFillWidth = true;
+    if (this.hasBuiltHandle()) {
+      ui.setFillWidth(this.handle, true);
+      this.notifyRetainedLayoutMutation();
+    }
     return this;
   }
 
   fillHeight(): this {
-    this.height(100.0, Unit.Percent);
+    this.hasFillHeight = true;
+    if (this.hasBuiltHandle()) {
+      ui.setFillHeight(this.handle, true);
+      this.notifyRetainedLayoutMutation();
+    }
     return this;
   }
 
@@ -274,21 +284,6 @@ export class FlexBox extends Node {
     return this;
   }
 
-  flexGrow(grow: f32): this {
-    this.flexGrowValue = grow;
-    this.hasFlexGrow = true;
-    if (this.hasBuiltHandle()) {
-      ui.setFlexGrow(this.handle, grow);
-      this.notifyRetainedLayoutMutation();
-    }
-    return this;
-  }
-
-  grow(grow: f32 = 1.0): this {
-    this.flexGrow(grow);
-    return this;
-  }
-
   justifyContent(justify: JustifyContent): this {
     this.justifyContentValue = justify;
     this.hasJustifyContent = true;
@@ -530,15 +525,18 @@ export class FlexBox extends Node {
     if (this.hasWidth) {
       ui.setWidth(this.handle, this.widthValue, <u32>this.widthUnit);
     }
+    if (this.hasFillWidth) {
+      ui.setFillWidth(this.handle, true);
+    }
     if (this.hasHeight) {
       ui.setHeight(this.handle, this.heightValue, <u32>this.heightUnit);
     }
+    if (this.hasFillHeight) {
+      ui.setFillHeight(this.handle, true);
+    }
     if (this.hasFlexDirection) {
       ui.setFlexDirection(this.handle, <u32>this.flexDirectionValue);
     }
-    if (this.hasFlexGrow) {
-      ui.setFlexGrow(this.handle, this.flexGrowValue);
-    }
     if (this.hasFlexBasis) {
       ui.setFlexBasis(this.handle, this.flexBasisValue);
     }
@@ -569,9 +567,15 @@ export class FlexBox extends Node {
     if (props.hasWidth) {
       this.width(props.widthValue, props.widthUnit);
     }
+    if (props.hasFillWidth) {
+      this.fillWidth();
+    }
     if (props.hasHeight) {
       this.height(props.heightValue, props.heightUnit);
     }
+    if (props.hasFillHeight) {
+      this.fillHeight();
+    }
     if (props.hasFlexBasis) {
       this.flexBasis(props.flexBasisValue);
     }
@@ -581,9 +585,6 @@ export class FlexBox extends Node {
     if (props.hasFlexDirection) {
       this.flexDirection(props.flexDirectionValue);
     }
-    if (props.hasFlexGrow) {
-      this.flexGrow(props.flexGrowValue);
-    }
     if (props.hasJustifyContent) {
       this.justifyContent(props.justifyContentValue);
     }
@@ -722,16 +723,16 @@ export class FlexBox extends Node {
 
   private buildFullMainAxisPercentWarning(isRow: bool): string {
     if (isRow) {
-      return "A row container has an in-flow child using width(100.0, Unit.Percent) or fillWidth() alongside siblings. Unit.Percent is literal parent-relative sizing, not flex sharing. Use grow() when siblings should share the row.";
+      return "A row container has an in-flow child using width(100.0, Unit.Percent) alongside siblings. Unit.Percent is literal parent-relative sizing, not flex sharing. Use fillWidth() when the child should take remaining row space.";
     }
-    return "A column container has an in-flow child using height(100.0, Unit.Percent) or fillHeight() alongside siblings. Unit.Percent is literal parent-relative sizing, not flex sharing. Use grow() when siblings should share the column.";
+    return "A column container has an in-flow child using height(100.0, Unit.Percent) alongside siblings. Unit.Percent is literal parent-relative sizing, not flex sharing. Use fillHeight() when the child should take remaining column space.";
   }
 
   private buildMainAxisPercentOverflowWarning(isRow: bool): string {
     if (isRow) {
-      return "A row container has in-flow children whose explicit width percentages exceed 100% in total. Unit.Percent is literal parent-relative sizing, not flex sharing. Use grow() when siblings should share the row, or reduce the percentages so they fit.";
+      return "A row container has in-flow children whose explicit width percentages exceed 100% in total. Unit.Percent is literal parent-relative sizing, not flex sharing. Use fillWidth() for the child that should expand, or reduce the percentages so they fit.";
     }
-    return "A column container has in-flow children whose explicit height percentages exceed 100% in total. Unit.Percent is literal parent-relative sizing, not flex sharing. Use grow() when siblings should share the column, or reduce the percentages so they fit.";
+    return "A column container has in-flow children whose explicit height percentages exceed 100% in total. Unit.Percent is literal parent-relative sizing, not flex sharing. Use fillHeight() for the child that should expand, or reduce the percentages so they fit.";
   }
 
   protected applyVisualStyle(): void {

package/src/nodes/ScrollBox.ts

@@ -49,12 +49,10 @@ export class ScrollBox extends FlexBox {
     const viewportValue = (viewportOverride === null ? new ScrollView() : viewportOverride)
       .bindScrollState(scrollState)
       .showScrollbars(false)
-      .width(0.0, Unit.Pixel)
-      .height(100.0, Unit.Percent)
-      .flexGrow(1.0);
+      .fillSize();
     const verticalGutterValue = new FlexBox()
       .width(DEFAULT_SCROLLBAR_GUTTER, Unit.Pixel)
-      .height(100.0, Unit.Percent)
+      .fillHeight()
       .onPointerDown(noopPointerCallback) as FlexBox;
     const verticalScrollBarValue = new ScrollBar(scrollState, Orientation.Vertical);
     const cornerValue = new FlexBox()
@@ -68,13 +66,13 @@ export class ScrollBox extends FlexBox {
       verticalScrollBarValue.render(),
     );
     topRowValue.onPointerDown(noopPointerCallback);
-    topRowValue.width(100.0, Unit.Percent).height(0.0, Unit.Pixel).flexGrow(1.0);
+    topRowValue.fillSize();
     const bottomRowValue = Row(
       horizontalScrollBarValue.render(),
       cornerValue,
     );
     bottomRowValue.onPointerDown(noopPointerCallback);
-    bottomRowValue.width(100.0, Unit.Percent).height(0.0, Unit.Pixel);
+    bottomRowValue.fillWidth();
 
     this.viewportValue = viewportValue;
     this.topRowValue = topRowValue;

package/src/nodes/ScrollView.ts

@@ -38,13 +38,13 @@ export class ScrollView extends Node {
   private widthValue: f32 = 0.0;
   private widthUnit: Unit = Unit.Pixel;
   private hasWidth: bool = false;
+  private hasFillWidth: bool = false;
   private heightValue: f32 = 0.0;
   private heightUnit: Unit = Unit.Pixel;
   private hasHeight: bool = false;
+  private hasFillHeight: bool = false;
   private flexBasisValue: f32 = 0.0;
   private hasFlexBasis: bool = false;
-  private flexGrowValue: f32 = 0.0;
-  private hasFlexGrow: bool = false;
   private enableScrollX: bool = true;
   private enableScrollY: bool = true;
   private showScrollbarsValue: bool = true;
@@ -99,6 +99,7 @@ export class ScrollView extends Node {
     this.widthValue = value;
     this.widthUnit = unit;
     this.hasWidth = true;
+    this.hasFillWidth = false;
     if (unit == Unit.Pixel) {
       this._scrollState.viewportWidth.value = value;
     }
@@ -113,6 +114,7 @@ export class ScrollView extends Node {
     this.heightValue = value;
     this.heightUnit = unit;
     this.hasHeight = true;
+    this.hasFillHeight = false;
     if (unit == Unit.Pixel) {
       this._scrollState.viewportHeight.value = value;
     }
@@ -124,12 +126,20 @@ export class ScrollView extends Node {
   }
 
   fillWidth(): this {
-    this.width(100.0, Unit.Percent);
+    this.hasFillWidth = true;
+    if (this.hasBuiltHandle()) {
+      ui.setFillWidth(this.handle, true);
+      this.notifyRetainedLayoutMutation();
+    }
     return this;
   }
 
   fillHeight(): this {
-    this.height(100.0, Unit.Percent);
+    this.hasFillHeight = true;
+    if (this.hasBuiltHandle()) {
+      ui.setFillHeight(this.handle, true);
+      this.notifyRetainedLayoutMutation();
+    }
     return this;
   }
 
@@ -149,21 +159,6 @@ export class ScrollView extends Node {
     return this;
   }
 
-  flexGrow(value: f32): this {
-    this.flexGrowValue = value;
-    this.hasFlexGrow = true;
-    if (this.hasBuiltHandle()) {
-      ui.setFlexGrow(this.handle, value);
-      this.notifyRetainedLayoutMutation();
-    }
-    return this;
-  }
-
-  grow(value: f32 = 1.0): this {
-    this.flexGrow(value);
-    return this;
-  }
-
   scrollEnabledX(flag: bool): this {
     this.enableScrollX = flag;
     if (this.hasBuiltHandle()) {
@@ -319,11 +314,14 @@ export class ScrollView extends Node {
     if (this.hasWidth) {
       ui.setWidth(this.handle, this.widthValue, <u32>this.widthUnit);
     }
+    if (this.hasFillWidth) {
+      ui.setFillWidth(this.handle, true);
+    }
     if (this.hasHeight) {
       ui.setHeight(this.handle, this.heightValue, <u32>this.heightUnit);
     }
-    if (this.hasFlexGrow) {
-      ui.setFlexGrow(this.handle, this.flexGrowValue);
+    if (this.hasFillHeight) {
+      ui.setFillHeight(this.handle, true);
     }
     if (this.hasFlexBasis) {
       ui.setFlexBasis(this.handle, this.flexBasisValue);

package/src/nodes/VirtualList.ts

@@ -2,6 +2,7 @@ import { HandlerAction } from "../core/Action";
 import { Disposable, disposeAll } from "../core/Disposable";
 import { markNeedsCommit } from "../core/FrameScheduler";
 import { FlexDirection, HandleValue, Unit } from "../core/ffi";
+import { VirtualListItemBindingError } from "../core/Errors";
 import { Node } from "../core/Node";
 import { FlexBox } from "./FlexBox";
 import { ScrollBar } from "./ScrollBar";
@@ -20,7 +21,7 @@ export type VirtualListBinder = (container: FlexBox, index: i32) => void;
 export class VirtualList extends FlexBox {
   private totalItemsValue: i32;
   private readonly itemHeightValue: f32;
-  private readonly bindItemValue: VirtualListBinder;
+  private bindItemValue: VirtualListBinder;
   private readonly scrollStateValue: ScrollState;
   private readonly scrollBoxValue: ScrollBox;
   private readonly contentValue: FlexBox;
@@ -33,7 +34,7 @@ export class VirtualList extends FlexBox {
   private currentFirstVisibleIndex: i32 = -1;
   private currentLastVisibleIndex: i32 = -1;
 
-  constructor(totalItems: i32, itemHeight: f32, bindItem: VirtualListBinder, maxVisible: i32 = DEFAULT_MAX_VISIBLE_ITEMS) {
+  constructor(totalItems: i32, itemHeight: f32, maxVisible: i32 = DEFAULT_MAX_VISIBLE_ITEMS) {
     super();
     const scrollStateValue = new ScrollState();
     const poolValue = new Array<SelectionArea>();
@@ -44,7 +45,9 @@ export class VirtualList extends FlexBox {
     const poolSizeValue = maxVisible > 0 ? maxVisible + POOL_OVERSCAN_ITEMS : POOL_OVERSCAN_ITEMS;
     this.totalItemsValue = totalItemsValue;
     this.itemHeightValue = itemHeightValue;
-    this.bindItemValue = bindItem;
+    this.bindItemValue = (): void => {
+      throw new VirtualListItemBindingError();
+    };
     this.scrollStateValue = scrollStateValue;
     this.poolSizeValue = poolSizeValue;
 
@@ -95,9 +98,7 @@ export class VirtualList extends FlexBox {
       .child(this.scrollBoxValue)
       .width(FULL_SIZE, Unit.Percent)
       .height(FULL_SIZE, Unit.Percent);
-
     this.attachListeners();
-    this.rebuildVisibleRange(false);
   }
 
   get scrollState(): ScrollState {
@@ -150,6 +151,9 @@ export class VirtualList extends FlexBox {
       return this.builtHandle;
     }
     const handle = super.build();
+    if (this.currentFirstVisibleIndex < 0 && this.totalItemsValue > 0) {
+      this.rebuildVisibleRange(false);
+    }
     ui.setSelectionAreaBarrier(handle, true);
     return handle;
   }
@@ -174,6 +178,24 @@ export class VirtualList extends FlexBox {
     return this;
   }
 
+  onBindItem(renderer: VirtualListBinder): this {
+    this.bindItemValue = renderer;
+    this.currentFirstVisibleIndex = -1;
+    this.currentLastVisibleIndex = -1;
+    this.rebuildVisibleRange(true);
+    return this;
+  }
+
+  onBindItemWith<Owner>(owner: Owner, renderer: (owner: Owner, container: FlexBox, index: i32) => void): this {
+    this.bindItemValue = (container: FlexBox, index: i32): void => {
+      renderer(owner, container, index);
+    };
+    this.currentFirstVisibleIndex = -1;
+    this.currentLastVisibleIndex = -1;
+    this.rebuildVisibleRange(true);
+    return this;
+  }
+
   updateItemCount(next: i32): void {
     this.totalItemsValue = next > 0 ? next : 0;
     this.scrollStateValue.contentHeight.value = this.totalContentHeight;
@@ -301,7 +323,7 @@ export class VirtualList extends FlexBox {
         const nextItemIndex = firstVisibleIndex + poolIndex;
         rowArea.height(this.itemHeightValue, Unit.Pixel);
         const container = changetype<FlexBox>(rowArea.getChildAt(0));
-        this.bindItemValue(container, nextItemIndex);
+        this.renderItem(container, nextItemIndex);
         unchecked(this.poolItemIndexByRow[poolIndex] = nextItemIndex);
       } else {
         this.hidePoolItem(rowArea, poolIndex);
@@ -421,6 +443,10 @@ export class VirtualList extends FlexBox {
     markNeedsCommit();
   }
 
+  private renderItem(container: FlexBox, index: i32): void {
+    this.bindItemValue(container, index);
+  }
+
   private maxOffsetForCurrentViewport(): f32 {
     const viewportHeight = this.scrollStateValue.viewportHeight.value > 0.0
       ? this.scrollStateValue.viewportHeight.value