@jimka/typescript-ui

Appearance

@jimka/typescript-ui / core / Binding

Class: Binding ​

Defined in: src/typescript/lib/core/Binding.ts:57

Synchronises a ModelRecord with a set of UI components.

Components are registered with bind, either as Bindable implementors (short form) or via explicit accessor callbacks (long form). Once a record is loaded via setRecord, every bound component is populated from the record's fields. Conversely, whenever a component's value changes, the record is updated automatically.

Examples ​

typescript
const binding = new Binding()
    .bind('name',   nameField)
    .bind('active', activeCheckbox)
    .bind('role',   roleCombo);

binding.setRecord(record);
typescript
const binding = new Binding()
    .bind('name', myWidget, {
        get:    () => myWidget.getValue(),
        set:    (v) => myWidget.setValue(v),
        listen: (fn) => myWidget.addChangeListener(fn),
    });

Extends ​

Constructors ​

new Binding() ​

ts
new Binding(): Binding

Defined in: src/typescript/lib/core/BaseObject.ts:15

Returns ​

Binding

Inherited from ​

BaseObject.constructor

Methods ​

addBeforeRecordListener() ​

ts
addBeforeRecordListener(fn: BeforeRecordListener): void

Defined in: src/typescript/lib/core/Binding.ts:268

Registers a listener that is consulted before a record change takes effect.

The listener receives the next record (or null) and returns false to cancel the change. Iteration stops on the first false; if any listener vetoes, setRecord returns without modifying any state. Returning true — or anything other than false, including undefined — allows the change.

Parameters ​

fn ​

BeforeRecordListener

Called with the next record (or null). Return false to veto.

Returns ​

void

Remarks ​

Async confirmation must be handled at the call site — setRecord stays synchronous. A caller that needs to reconcile its UI after a veto (e.g. reset a record-picker combo) should compare getRecord after the call. A listener that itself calls setRecord re-enters the same veto loop, which is supported but discouraged. null is a valid next value (it represents a clear); a listener that only wants to guard non-clear switches must short-circuit next === null itself.

addChangeListener() ​

ts
addChangeListener(fn: (fieldName: string, value: unknown) => void): void

Defined in: src/typescript/lib/core/Binding.ts:230

Registers a listener that fires whenever any bound component changes a field value.

Parameters ​

fn ​

(fieldName: string, value: unknown) => void

Called with the field name and new value on every change.

Returns ​

void

addCommitListener() ​

ts
addCommitListener(fn: () => void): void

Defined in: src/typescript/lib/core/Binding.ts:237

Registers a listener that fires after commit is called.

Parameters ​

fn ​

() => void

Returns ​

void

addRejectListener() ​

ts
addRejectListener(fn: () => void): void

Defined in: src/typescript/lib/core/Binding.ts:244

Registers a listener that fires after reject is called.

Parameters ​

fn ​

() => void

Returns ​

void

addValidation() ​

ts
addValidation(
   fieldName: string, 
   component: Component, 
   rules: 
  | ValidationRule
  | ValidationRule[]): this

Defined in: src/typescript/lib/core/Binding.ts:283

Attaches one or more validation rules to a bound field.

Parameters ​

fieldName ​

string

The field name registered with bind.

component ​

Component

The Component instance to wrap with a FieldDecorator on error.

rules ​

One or more ValidationRule objects to apply to this field.

ValidationRule | ValidationRule[]

Returns ​

this

this, for chaining.

bind() ​

Call Signature ​

ts
bind<T>(fieldName: string, component: Bindable<T>): this

Defined in: src/typescript/lib/core/Binding.ts:76

Registers a field binding using a component that implements Bindable.

Type Parameters ​

• T

Parameters ​
fieldName ​

string

The record field to bind to.

component ​

Bindable<T>

A component implementing the Bindable interface.

Returns ​

this

Call Signature ​

ts
bind<T>(
   fieldName: string, 
   component: object, 
   accessors: BindingAccessors<T>): this

Defined in: src/typescript/lib/core/Binding.ts:86

Registers a field binding using explicit accessor callbacks. Use this overload for components that do not implement Bindable.

Type Parameters ​

• T

Parameters ​
fieldName ​

string

The record field to bind to.

component ​

object

Any object (used only as a placeholder for the overload).

accessors ​

BindingAccessors<T>

Getter, setter, and change-listener callbacks.

Returns ​

this

clearValidation() ​

ts
clearValidation(): this

Defined in: src/typescript/lib/core/Binding.ts:359

Clears all error decorations without re-running rules. Called automatically by reject.

Returns ​

this

commit() ​

ts
commit(): this

Defined in: src/typescript/lib/core/Binding.ts:192

Commits the current record, clearing its dirty and new flags. Fires all registered commit listeners.

Returns ​

this

getClassName() ​

ts
getClassName(): string

Defined in: src/typescript/lib/core/BaseObject.ts:44

Returns the runtime class name of this object.

Returns ​

string

The name of the constructor function as a string.

Inherited from ​

BaseObject.getClassName

getId() ​

ts
getId(): string

Defined in: src/typescript/lib/core/BaseObject.ts:24

Returns the unique identifier for this object.

Returns ​

string

The UUID string assigned at construction time.

Inherited from ​

BaseObject.getId

getRecord() ​

ts
getRecord(): null | ModelRecord

Defined in: src/typescript/lib/core/Binding.ts:182

Returns the currently bound record, or null if none is loaded.

Returns ​

null | ModelRecord

getValidateOnChange() ​

ts
getValidateOnChange(): boolean

Defined in: src/typescript/lib/core/Binding.ts:351

Returns whether live validation is globally enabled.

Returns ​

boolean

true if live validation is active.

reject() ​

ts
reject(): void

Defined in: src/typescript/lib/core/Binding.ts:207

Rejects all changes on the current record and re-syncs every component from the reverted field values. Fires all registered reject listeners. Also clears any active validation error decorations.

Returns ​

void

removeValidation() ​

ts
removeValidation(fieldName: string): this

Defined in: src/typescript/lib/core/Binding.ts:303

Removes all validation rules for a field and clears any existing error decoration.

Parameters ​

fieldName ​

string

The field whose validation should be removed.

Returns ​

this

this, for chaining.

setId() ​

ts
setId(id: string): this

Defined in: src/typescript/lib/core/BaseObject.ts:33

Sets the unique identifier for this object.

Parameters ​

id ​

string

The new identifier string to assign.

Returns ​

this

Inherited from ​

BaseObject.setId

setRecord() ​

ts
setRecord(record: null | ModelRecord): this

Defined in: src/typescript/lib/core/Binding.ts:153

Loads a record into the binding. All registered components are immediately populated with the corresponding field values. Pass null to clear the binding.

Before any state mutation, every listener registered via addBeforeRecordListener is consulted; if any returns false the call is a complete no-op (no validation reset, no field population) and this is returned unchanged.

Parameters ​

record ​

The record to bind, or null to detach.

null | ModelRecord

Returns ​

this

setValidateOnChange() ​

ts
setValidateOnChange(enabled: boolean): this

Defined in: src/typescript/lib/core/Binding.ts:340

Enables or disables live validation (validation on every field change).

Parameters ​

enabled ​

boolean

true to validate on every change event; false for explicit-only.

Returns ​

this

unbind() ​

ts
unbind(fieldName: string): this

Defined in: src/typescript/lib/core/Binding.ts:129

Removes the binding for the given field. The change listener previously attached to the component becomes a no-op.

Parameters ​

fieldName ​

string

The field whose binding should be removed.

Returns ​

this

validate() ​

ts
validate(): boolean

Defined in: src/typescript/lib/core/Binding.ts:321

Runs all registered validation rules against the current field values. Applies or clears FieldDecorator error state for each validated field.

Returns ​

boolean

true if all fields pass; false if any field fails.