Ooidget Component Format 0.1Editor's Draft

Layers

A widget’s layers are drawn in array order, the first at the back. Each layer is a JSON object. Its kind is given by the first of these members it has, in this order: use, slot, primitive, paint, image, svg / svgExpr, shape / style / pathExpr, text / runs. A layer with none of them is unknown and is skipped (fallbacks).

Common properties

Property	Type	Required	Description
`when`	Expression<boolean>	no	The layer is drawn only while this is true. Absent: always.
`frame`	Frame	no	The layer’s box, anchored to the instance’s edges.
`box`	[number, number, number, number]	no	The layer’s box, fixed. Ignored when `frame` is present.
`boxExpr`	Expression<box>	no	The layer’s box, computed. Takes precedence over `frame` and `box` when it yields a box.
`opacity`	number	no	0 to 1. Absent: 1.
`opacityExpr`	Expression<number>	no	Computed opacity, clamped to 0..1. Takes precedence over `opacity`.
`clip`	boolean	no	Clip the layer to its box.
`region`	string	no	Name the layer’s box as a region.

A layer with none of frame, box or boxExpr covers the instance: its box is [0, 0, ui.w, ui.h].

Frames

A frame places a box relative to the instance’s edges, with the meaning of CSS absolute positioning [CSS2 §9.3]: l, t, r, b are the CSS left, top, right and bottom offsets and w, h the width and height. Each is a number or an Expression<number>.

To compute a frame’s box inside an area of width W and height H, run these steps:

Let w be the value of w if present, else W. Let h be the value of h if present, else H.
If l and r are both present, let x be l and set w to W − l − r. Otherwise, if l is present, let x be l; if r is present, let x be W − r − w; otherwise let x be (W − w) / 2.
Compute y and h from t, b and H in the same way.
Return [x, y, w, h].

Shape

A shape is a primitive outline painted by its effects.

Property	Type	Required	Description
`shape`	string	yes	`"rect"`, `"ellipse"` or `"path"`.
`radius`	number or [number, number, number, number]	no	Corner radii of a rect (top-left, top-right, bottom-right, bottom-left), clamped to half the shorter side.
`d`	string	for `path`	SVG path data [SVG2 §9.3], in the layer’s box coordinates.
`pathExpr`	Expression<string>	no	Computed path data; implies `shape: "path"`.
`effects`	array of Effect	no	Painted in order. Absent: nothing is painted.
`style`	string	no	A style whose `radius` and `effects` come before the layer’s own. Implies `shape: "rect"`.

Text

Property	Type	Required	Description
`text`	Expression<string>	yes	The text. To give a literal, quote it inside the expression: `"'Play'"`.
`size`	number	no	Font size in design units. Absent: 12.
`color`	Color	no	A CSS colour. Absent: `#000000`.
`font`	string	no	A CSS `font-family` list [CSS-FONTS].
`weight`	number	no	CSS `font-weight`, 1 to 1000. Absent: 400.
`align`	string	no	`"left"`, `"center"` or `"right"` within the box. Absent: `"left"`.
`valign`	string	no	`"top"`, `"middle"` or `"bottom"`. Absent: `"middle"`.
`wrap`	boolean	no	Wrap to the box width. Absent: a single line.
`runs`	array	no	Instead of `text`: styled spans, each `{ "text": Expression<string>, ...text properties }`.

Text is shaped and laid out as CSS would lay out the same string in the same font, size and weight [CSS-TEXT]. A runtime MUST use the first available family of font, then the host’s default sans-serif face.

Image

Property	Type	Required	Description
`image`	string	yes	An asset name, or `"$key"`: the name held by the view’s member `key`.
`frames`	integer	no	The image is a filmstrip of this many frames of equal height, stacked top to bottom. Absent: 1.
`frameBy`	string	no	The view member, a number in 0..1, that picks the frame: frame `round(v × (frames − 1))`.
`fit`	string	no	CSS `object-fit`: `"fill"` (default), `"contain"`, `"cover"`.

Assets are PNG, JPEG, WebP or SVG. A missing asset draws nothing.

SVG

Property	Type	Required	Description
`svg`	string	yes	An SVG fragment: the content of an `<svg>` element whose viewport is the layer’s box.
`svgExpr`	Expression<string>	no	A computed fragment. Takes precedence over `svg`.

The fragment MUST use only the SVG subset. It is drawn in a coordinate system whose origin is the box’s top-left corner and whose unit is the design unit; the widget’s defs are in scope.

Use

A use layer draws another component inside the layer’s box.

Property	Type	Required	Description
`use`	string	yes	A component name, or `"$key"` for the name held by the view’s member `key`.
`props`	object	no	Values placed over the used component’s initial state. A string value `"$key"` is the view’s member `key`.

The used component is drawn at its design size, scaled uniformly to fit the box and centred in it (CSS object-fit: contain). It is drawn as it starts: its behaviour does not run and it takes no input. A component that must respond to input is a child, not a layer.

If the name does not resolve to a component, the layer is passed to the host as a host draw.

Host-drawn layers

Kind	Property	Description
Slot	`slot`: string	A box whose contents and input the host owns: an editor’s canvas, a video, a native view.
Primitive	`primitive`: string	A drawing the host performs from the layer and the view, for what layers cannot express.
Painter	`paint`: string	A named painter program; see Painters.

The runtime passes the layer, its box and the view to the host. A host that does not know the name draws nothing.