@md5crypt/layout v2.0.2

Unnamed layout engine

README OUTDATED!

This package aims at providing a base for a layout engine regardless of what graphic framework will be used. It implements the following:

• a json based layout description system for creating entire structures from static json templates
• a render-loop single-pass flexbox positioning system with margin and padding support
• a runtime api for finding and manipulating instantiated layout elements

Layout description syntax

LayoutElementJson

Top-level structure used to describe the layout. This structure is passed to the layout factory to create element instances.

LayoutConfig

The element's layout configuration.

Width and height values

• When a dimension is set to a number that value is used directly.
• When a dimension is a string it is expected to to match /\d+%/ and is evaluated as a percentage of parent's size
• When a dimension is a function it should be a (element: LayoutElement) => number | null callback that returns the element's size. null should be returned only if the size could not be computed.
• When a dimension is undefined the element's content size is used.

Setting a dimension controlled by the current layout (so width for horizontal and height for vertical) will set the element's base dimension (using a css analogy, basically flex-basis).

PositioningBox

An object or number used for providing padding and margin values.

If an number is given instead of an object then all dimensions are set that the given value.

Instancing elements

A LayoutFactory instance is used to create element instances.

interface LayoutFactory {
    create(layout: LayoutElementJson, parent?: LayoutElement) => LayoutElement
}

If parent is provided the created element will be inserted as it's last child.

Alternatively elements can be created by passing LayoutElementJson to the insertElement / replaceElement functions of a LayoutElement instance.

LayoutElement

The base class for all instantiated layout elements.

Properties reference

Function reference

Resolving elements by name

The name resolution system allows to find elements by name. Each element that was defined with a name will be stored inside a name table of the first named parent in it's parent chain.

Element which names start with @ will not be stored in a name table but will still create a name table themselves.

Names passed to getElement / hasElement can be dot delimited paths. For example calling e.getElement("foo.bar") will query e for foo and then the result for bar.

Consider the example below:

   root
(1)  foo
(2)  /unnamed/
(3)    bar
(4)      rab
(5)  @off
(6)    foo

Now consider the following function calls:

root.getElement("foo")     // 1
root.getElement("bar")     // 3
root.getElement("bar.rab") // 4
root.getElement("@off")    // error, @off not stored in a name table
root.children[1]           // 2
root.children[2]           // 5
root.children[2].getElement("foo") // 6
root.children[1].getElement("bar") // error, unnamed element does not have a name table

Implementing element types

1. extend LayoutElement
2. register the resulting class by calling register on a LayoutFactory instance
3. fudge around with typescript's types
4. profit

(I think this section would use some improvements)