Ooidget Component Format 0.1Editor's Draft

Documents and components

The component file

A component file is a JSON text [RFC8259] encoded in UTF-8 whose top-level value is an object. Its media type is application/ooidget+json; its file name extension SHOULD be .json, and a bundle of several components SHOULD use .ooidget.json.

A file MUST contain widget or behaviour, and MUST NOT contain both.

Names and namespaces

Components, shared behaviours and code are referred to by name, never copied. A name is a path of segments separated by /, each segment ASCII letters, digits, _ and -, beginning with a letter; names are case-sensitive. The last segment names the thing; the segments before it are its namespace, which is the folder it lives in, relative to the project’s root:

A function is referred to as { "fn": "module#export" }: the export export of the code module module.js, named as above. Without #, { "fn": "export" } is an export of the referring component’s own code module.

Names resolve within the project first, then in its packages; a project MUST NOT define a name twice. Where a document refers to a component (a use layer, a child, a shared behaviour), the runtime resolves its name through the host’s component resolver. A name that does not resolve is not an error: the referring layer or child is skipped, and a runtime SHOULD report it to the host as a diagnostic.

Both forms are valid everywhere code is accepted: JavaScript inline in a string, for quick expressions and small behaviours (s.on && !ui.down, `${s.tempo} bpm`, ({ click(s) { return { on: !s.on } } })), or a reference to a function in a code module. Authoring tools SHOULD move code longer than a line or two into a code module, where it is written, read and checked as JavaScript.

Project folders

A component’s source is kept as a project folder, one file per reusable thing, each referred to by name and never copied into the files that use it:

Authoring tools SHOULD write projects this way. A name MUST NOT be defined by more than one file of a project. A bundle is the packed form of a project folder, for distribution: tools pack and unpack between the two without loss.

Code modules

Quick code may be written inline, as JavaScript in a string (expressions, a short behaviour). Longer code (a behaviour with several handlers, a computed drawing, a painter) belongs in the component’s code module: an ECMAScript module name.js beside name.json.

Wherever this specification accepts an Expression<T>, a document MAY instead give { "fn": "name" }: the code module’s export of that name, called with the expression’s parameters (s, ui, m, env) and returning the value. For example, a road drawn from state:

{ "svgExpr": { "fn": "road" } }

/** The road ahead, its dashes moving with the distance driven. */
export function road(s, ui) {
  let o = "";
  for (let i = 0; i < 12; i++) o += dash(i, s.trip);
  return o;
}

A code module MUST NOT have side effects when imported, and its exports MUST behave as expressions and behaviours do: no I/O, no time, no randomness. Runtimes load it in the same sandbox. Because a code module is already code, a runtime needs no eval for it.

A code module MAY import other code modules of the project, and only those, by relative path with the .js extension (import { detents } from "./detents.js"), resolved as names are: relative to the importing module’s folder. Imports of anything else (packages, URLs, the host’s modules) are not allowed.

In a bundle a component’s code module travels as the member module of its component file: the module’s source text.

Bundles

A bundle is a single JSON object that carries several components and the resources they share, for distribution and for the web:

A runtime given a bundle MUST resolve component names against its components before asking the host.

The widget object

Members not defined here or by an extension MUST be ignored by runtimes and SHOULD be reported by validators.