U2
Classes
| Class | Description |
|---|---|
| Component | Base of every u2 component, visual or not: a name, an effect/cleanup scope, and the widget introspection surface (DD7) generated from componentMeta — what the shell, the context panel, automation and the copilot ask of a widget, implemented by DG.Widget through inheritance. A component constructed inside another's scope is disposed with it. Platform-free; in Datagrok, DG.Widget extends Control, so the kill channel and the introspection surface are this class's own — nothing wires or delegates. Standalone hosts (gallery, tests) call dispose directly. |
| Control | A component that renders: everything visual in u2 is one. |
| Scope | Owner of effects, cleanups, listeners, timers and child scopes. Everything registered on a scope is released by a single dispose() call. Errors raised in what it owns are reported to onError, then up the parent chain, then to Scope.onUnhandledError — never thrown at whoever happened to write a signal. |
| Signal | The base class for plain and computed signals. |
| U2UsageError | A misuse of u2 the engine detected. code names the rule (owner-missing, owner-disposed, …); the message names the fix. |
| Usage | What the engine does about a misuse of u2 — the one place every usage rule reports through. The mode is report unless __U2_STRICT__, localStorage['u2.strict'] or U2_STRICT says off, report or throw (1); with u2 debug on in the browser (localStorage['u2.debug'] = '1', dev) it is throw. The test runners set throw: u2's node runner, bdd and grok test. A report is a console warning; in Node a line on stderr, and U2_USAGE_REPORT=<file> appends each new one to that file as a JSON line. |
Interfaces
| Interface | Description |
|---|---|
| BindProp | One enumerated binding step: a property (typed, semType included) plus what the picker needs — no probing, no signal creation during enumeration. |
| BindSource | The DD5 binding protocol: a source resolves one path step at a time and enumerates what a picker may offer without allocating a single signal — laziness is the contract, not an optimization. Every Component answers it off its registry meta. |
| ColumnLike | Deliberately structural, not DG.Column/DG.DataFrame: every real frame satisfies these, while the headless suite feeds plain fakes — a Dart-handle class could never type them. |
| ComponentMetaBase | The registry metadata a component introspects itself through; the spec layer's ComponentMeta extends it (structural, so the core never imports the spec layer). |
| ComponentState | The per-instance u2 state, kept under one own field so that Component.init can be applied to a platform DG.Widget (a Component by inheritance) without clobbering its own fields. |
| ControlBuildOptions | Options of component. |
| DataFrameLike | - |
| DebugSnapshot | What was live at one moment — the baseline U2Debug.diff compares against. |
| FuncLike | A callable a component exposes, params as properties. The invocation is named after DG.Func.apply so that a real platform function IS a FuncLike — the host hands out either. Deliberately NOT DG.Func: components mint plain callables no registry knows. |
| IItemsState | The items of a collection-like control. |
| IItemState | One addressable item of a collection-like control: a list/tree/table row, a chip, an option, a radio/checkbox item, a tab, a wizard step, a menu item, a breadcrumb. |
| LeakReport | What a U2Debug.diff found live that was not live at the snapshot. |
| ListenerRecord | A listener on window, document or body added through a scope helper or while a u2 scope was current. |
| NamedProperty | A property whose name is guaranteed — what descriptors and bind steps carry. |
| ObservableLike | The subscription surface of an event stream; an rxjs Observable satisfies it structurally. Deliberately NOT rxjs Observable: the notification seams return hand-rolled literals, and the dependency-free core never types against rxjs (a webpack external). What Component.onEvent emits is a union: a component event's own payload, or a DOM Event where the control's root raises one of the same name. Nothing wraps or tags them — a subscriber that cares tests for instanceof Event. |
| OperabilityFinding | A control the page offers that a user cannot operate as offered, as operability finds it. |
| OperabilityOptions | Options of operability. |
| OwnerVerbs | The owner verbs every component has, its Component.scope's: build(fn) runs fn with it ambient, task runs async work for it, subscribe owns a stream. The engine puts them on every component; their types come with u2 (@datagrok-libraries/u2 declares them on Component), so a platform class that has a member of one of these names of its own (a function view's build()) keeps it and still compiles. |
| PropState | One declared property of a control, as props reports it. |
| ReadonlySignal | An interface for read-only signals. |
| ScopeRecord | A live scope, as U2Debug.liveScopes reports it. |
| TaskContext | What the function Scope.task runs gets: the run's abort signal, and the way back into its owner after an await. |
| TaskOptions | How Scope.task runs. |
| TaskRun | A run Scope.task started. |
| TimerRecord | A pending timeout, interval or animation frame created through a scope helper or while a u2 scope was current. |
| U2Debug | The in-page leak and ownership inspector, DG.U2.debug. |
| UsageReport | One misuse as Usage.reports lists it. |
Type Aliases
| Type Alias | Description |
|---|---|
| BuiltHandle | A handle a component builder answers: the content under root, beside the API the control carries; no other key may be a Control member. |
| BuiltRoot | The content a component builder answers: an element, a control, a text, or several (in a div). |
| ErrorHandler | Receives an error a scope caught: from an effect, a bound handler, a listener or a cleanup. |
| JsonValue | JSON-safe projection of a value — what crosses page.evaluate. Dates become ISO strings, entities/objects with a name become that name, arrays map element-wise, plain objects key-wise, functions/elements become undefined, everything else String(x). Produced by Control.jsonValue. |
| OperabilityRule | A rule operability checks: covered — at its centre the page answers another element; no-pointer — pointer-events: none on it or above it in its control that no :hover of an ancestor taking the pointer lifts; inert — inside an inert region that says no reason; disabled-without-reason — off with no reason on it, its control or a control around it that is off too; name-mismatch — an icon-only button whose accessible name is not its tooltip; oversized-option — an option taller than the one-row rail it sits on. |
| PropertyChange | What a widget announces when one of its properties changed: the property's name, or null when several changed at once (or the widget cannot say which). Structural — nothing platform-typed. |
| U2Gesture | What the user does to a control or an item — the bdd library's gesture verbs. |
| UsageMode | How u2 answers a misuse it detects: off says nothing, report logs it once per code and call site and keeps it in Usage.reports, throw throws a U2UsageError. |
Variables
| Variable | Description |
|---|---|
| debug | DG.U2.debug — live scopes with creation stacks, owned timers and global listeners, the snapshot/diff the BDD leak check runs, and the orphan sweep. |
| DF_STEPS | The seven steps every DataFrame answers — static, so a source that IS a frame enumerates them without building the frame's bindings first. |
| ITEMS_CAP | Item cap of IItemsState.list. |
| version | The u2 engine's version, DG.U2.version. u2 refuses to build its controls on an engine older than the one it needs, so a plugin built with a newer u2 than the platform carries says so instead of failing later on a missing member, and still loads. |
Functions
| Function | Description |
|---|---|
| afterFlush | Runs fn once the outermost batch has ended and the effects it set off have run — what an effect builds in answer to a write (a new row) exists then; outside a batch, now. u2 runs every handler in a batch. A throw is thrown at whoever ended the batch: hand it a Scope.bind handler to have it reported instead. |
| batch | Runs fn with every signal write inside it as one change: the effects it sets off run once, when the outermost batch ends — and then what afterFlush queued. |
| component | Builds a control — the function component: builder runs now with the new control's scope ambient and gets it as self, so what it builds is owned by the result; after an await it gets back in with self.task(async (t) => … t.build(…)). It answers the content (an element, a control, a text, or several, which go into a div), or a handle {root, ...api}: the result is then Control & api, the api's properties copied onto it as they are (getters stay live). A handle key that is a Control member is a type error, and reported (reserved-key) and skipped at run time. name is the automation id (data-u2-name). A built control is a root: built with no owner, it is not reported. |
| computed | Create a new signal that is computed based on the values of other signals. |
| control | The u2 control owning el: the nearest control root at or above it, or the owner of the popup it sits in. Platform widget wrappers are passed over — whether one exists depends on who asked the platform for it. Undefined for an element outside any u2 control. |
| dfBindings | The BindSource over a DataFrame signal. Subscriptions and signals live on scope. Lazy: a currentRow.<col> signal is created on first bindStep and cached; a repoint (the frame signal changing identity) resubscribes events and refreshes every cached signal. A column step always answers a signal — an absent frame or column reads undefined and refuses writes, so bound inputs show empty instead of breaking (the containment posture). |
| isWritableSignal | Whether s is a signal whose value can be written — the two-way gate. A prototype-descriptor check: the vendored Computed defines a getter-only value, so computeds classify read-only without any engine knowledge. |
| items | Items of the control owning el (the state's items), uncapped with all: true; null when it lists none. |
| lens | A writable signal over a part of source: reading it reads get(source.value) (tracked), writing it writes source.value = set(source.peek(), x). Writing the value it already reads changes nothing, so two of them wired both ways settle at once. It is a Signal: it binds wherever a signal does. |
| operability | What under root a user is offered and cannot operate as offered: every visible interactive element (native controls, [tabindex], interactive roles, interactive, the children of an options rail) is checked against the OperabilityRules. An aria-hidden element is not offered; what a platform widget below root holds is the platform's to judge; what a control holds inside another that is off and says why (a disabled filter builder, a designer canvas in Design mode) is off with that reason; an element under a sticky part of its own scroller is scrolled out of view, not covered; one the page's style rules reveal on hover (a row's actions: .row:hover .actions {pointer-events: auto}) takes the pointer once it is over the row, so it is no finding and its hit test at rest is skipped. Platform-free; without layout (Node) covered is skipped and rectangles are whatever the test set. |
| propertyFields | A plain copy of the named fields — a spread of a DG.Property copies nothing but its dart handle, since every field is a prototype getter. |
| props | The declared properties of the control owning el, values JSON-projected. |
| rawEffect | Create an effect to run arbitrary code in response to signal changes. |
| revealItem | Brings an item of the control owning el into view by key or label (see Control.revealItem); rejects naming the candidates when a label matches several. |
| setProp | Writes a declared property of the control owning el through its setter — for putting a control in a state from a test. Throws when the control has no such property or it is read-only. |
| signal | Create a new plain signal. |
| state | JSON-safe state of the control owning el — what page.evaluate hands to a test runner; null outside a u2 control. Synchronous and side-effect free. |
| status | Full status of the control owning el; its parts are elements, so use it inside the page only. |
| untracked | Run a callback function that can access signal values without subscribing to the signal updates. |
| uuid4 | A random v4 UUID. Unlike crypto.randomUUID() this also works outside a secure context — a stand served over plain HTTP on a hostname has no randomUUID. |
References
BitArray
Re-exports BitArray
BitPredicate
Re-exports BitPredicate
COLUMN_TYPE
Re-exports COLUMN_TYPE
IControlState
Re-exports IControlState
IEventType
Re-exports IEventType
IInputStatus
Re-exports IInputStatus
IProperty
Re-exports IProperty
IPropertyMeta
Re-exports IPropertyMeta
IRectBounds
Re-exports IRectBounds
IWidgetStatus
Re-exports IWidgetStatus
SEMTYPE
Re-exports SEMTYPE
TYPE
Re-exports TYPE
TYPES_SCALAR
Re-exports TYPES_SCALAR