Foundation for Web Interfaces

Types

ifc Identifiable

Entity that can be uniquely identified.

• id: string

ifc Stringifiable

Entity that can be stringified using JavaScript convention.

• toString: () -> string

type StateItemConverter<T>

Function that converts T to an HTMLElement: (T)->HTMLElement.

Utility Functions

fn UUID: () -> string

Generates a unique UUID.

Reactivity & States

class<T> State

States are the foundation for reactive interfaces in FWI. They are used instead of standard variables when the user interface must respond to changes in data, or when the interface changes data.

• Implements
  • stringifiable
• Type Parameters
  • T: the data type of the State's value
• Methods
  • constructor: (T) -> void sets the initial value
  • callSubscriptions: () -> void: calls every subscribing function
  • subscribe: (T->void) -> void: adds a subscribing function. The function added will be called immediately and every time the state's value changes, or every time callSubscriptions is used.
  • subscribeSilent: (T->void) -> void: adds a subscribing function. Analog to subscribe but the function will not be called immediately.
• Properties, Getters, and Setters
  • T value: the current value of the state

class<T> ListState

A State designed to hold a Set of multiple items and add or remove UI elements efficiently when data changes.

• Extends State<Set<T>>
• Methods
  • constructor: (T[]) -> void sets the initial items
  • add: (...T[]) -> void: adds items, calls additionHandlers for each new item, calls subscriptions once
  • remove: (...T[]) -> void: removes items, calls removalHandlers for each removed item, calls subscriptions once
  • clear: () -> void: removes all values
  • handleAddition: (T->void) -> void: adds function to be called when items get added (additionHandler), calls the handler for every current item.
  • handleRemoval: (item: T, handler: T->void) -> void: adds function to be called when the specific item gets removed (removalHandler)

class<T> MapState

Analog to ListState<T> but using a Map instead of Set

• Extends State<Map<string, T>>
• Methods
  • constructor: ([string, T][]) -> void sets the initial items
  • set: (string, T) -> void: removes the previous value, sets the new value, calls additionHandlers and subscriptions
  • remove: (string) -> void: removes the item if it exists, calls removalHandlers and subscriptions
  • clear: () -> void: removes all entries
  • handleAddition: (T->void) -> void: adds function to be called when items get added (additionHandler), calls the handler for every current item.
  • handleRemoval: (item: T, handler: T->void) -> void: adds function to be called when the specific item gets removed (removalHandler)

fn createProxyState<T>: (states: State<any>[], generateNewValue: ()->T) -> State<T>

Creates a new state and subscribes to every state provided in the first argument. Whenever either of these states changes, the value of the proxy state is updated using generateNewValue.

fn bulkSubscribe: (states: State<any>[], handler: ()->void) -> void

Subscribes to every state provided in the first parameter using subscribeSilent.

fn persistState: (state: State<any>, handler: string->void) -> void

Subscribes to the state. Whenever the state changes, the handler gets called with the stringified state. Can be used with handlers like localStorage.setItem.

fn restoreState<T>: (stateString: string, initialStateValue: T) -> State<T>

Counterpart to persistState: reads the stringified state and re-creates the state.

fn restoreListState<T>: (stateString: string) -> ListState<T>

Analog to restoreState but for ListState.

fn restoreMapState<T>: (stateString: string) -> MapState<T>

Analog to restoreState but for MapState.

User Interface

Fundamentals

• Both stylesheets/base.css and stylesheets/theme.css must be imported.
• FWI expects use of .tsx. The FWI library must be imported as * as FWI for this to work.

Elements

• Elements are added like standard jsx/tsx elements. However, event handlers and bindings have custom implementation.
• Custom attributes (directives) have special prefixes that are separated by a colon, e.g. <input on:enter={myFunction} />.
• The library ships pre-built components for certain actions. Components with more complex parameters are called views and extend the GenericView class. Implement them as {new SomeView().view}.
• Directives
  • on: Adds an event listener. All standard events and enter (Enter key pressed) are supported.
    • Example: <button on:click={()=>myFunction()}>Click me</button>
  • subscribe: Updates the given property of the element when the state changes. Immediately assignes the current value.
    • Example: <input subscribe:placeholder={inputPlaceholderText} />
  • bind: Two-way-equivalent to subscribe, triggered by the input event. Uses the specified property to read the value.
    • Example: <input bind:value={inputValue} />
  • toggle: Subscribes to a state to toggle an attribute.
    • Example: <button toggle:disabled={isButtonDisabled}>Click me, or not?</button>
  • set: Subscribes to a state to set an attribute's value.
    • Example: <div set:class={divClassName}>...</div>
  • style: Subscribes to a state to change a CSS property.
    • Example: <div style:order={itemSortIndex}>...</div>
  • children: Sets, appends, or prepends elements from a State<Node|Node[]>. This directive supports the following values: children:set={state}: whenever the state changes, all previous child elements get removed, and the elements of the state are added. The state provided must be a State<Node[]>. children:append={[state, converter]}: uses addition handlers to dynamically append elements added to the state. Elements removed from the state are also removed from the component. The state may be of any type ListState<T>, and the converter must convert to an HTMLElement (T)->HTMLElement. children:prepend={[state, converter]}: analog to append but new elements get added from to the start.