Control

Defined in: js-api/src/u2core/component.ts:565

A component that renders: everything visual in u2 is one.

Extends

• Component

Extended by

• Widget

Constructors

Constructor

new Control(root?, scope?): Control

Defined in: js-api/src/u2core/component.ts:568

Parameters

Parameter	Type
root?	HTMLElement
scope?	Scope

Returns

Control

Overrides

Component.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
_root	protected	HTMLElement	-	-	js-api/src/u2core/component.ts:566
_u2	readonly	ComponentState	-	Component._u2	js-api/src/u2core/component.ts:98
componentMeta?	public	ComponentMetaBase	The registry metadata of the tag that built this component, stamped by the spec renderer — the single source the introspection surface below is generated from.	Component.componentMeta	js-api/src/u2core/component.ts:93
specProps?	public	Record<string, unknown>	The props the registry's create was handed, stamped alongside componentMeta: the last resort of the property read below, for a component that keeps a prop under another name or not at all (a create wrapping a bare element). Construction-time values — a live one always wins.	Component.specProps	js-api/src/u2core/component.ts:97

Accessors

aiDescription

Get Signature

get aiDescription(): string | null

Defined in: js-api/src/u2core/component.ts:237

A short AI-facing briefing, seeded from the registry's usage or description.

Returns

string | null

Set Signature

set aiDescription(x): void

Defined in: js-api/src/u2core/component.ts:241

Parameters

Parameter	Type
x	string | null

Returns

void

Inherited from

ColumnGrid.aiDescription

---

ambientAdoption

Get Signature

get protected ambientAdoption(): boolean

Defined in: js-api/src/u2core/component.ts:340

Whether a component constructed inside an ambient scope is disposed with it.

Returns

boolean

Inherited from

Component.ambientAdoption

---

name

Get Signature

get name(): string | undefined

Defined in: js-api/src/u2core/component.ts:772

A named control carries its name in the DOM: data-u2-name is the stable automation id selectors, tutorials and agents address the control by — the same attribute the spec renderer stamps on named nodes, so hand-built and spec-built UI share one selector vocabulary. Derived names (an input's label fallback) never stamp — see Component.deriveName.

Returns

string | undefined

Set Signature

set name(x): void

Defined in: js-api/src/u2core/component.ts:776

Unique within a spec: the anchor for selection, patches and automation. An accessor pair (not a field), so a platform descendant's own name accessors override it legally (TS2611).

Parameters

Parameter	Type
x	string | undefined

Returns

void

Overrides

Component.name

---

propertyTarget

Get Signature

get propertyTarget(): unknown

Defined in: js-api/src/u2core/component.ts:335

What this component's properties are read from and written to — prop.get(target) / prop.set(target, v): the component itself, unless an adoption says otherwise.

Returns

unknown

Inherited from

Component.propertyTarget

---

propertyTier

Get Signature

get propertyTier(): boolean

Defined in: js-api/src/u2core/component.ts:329

The second binding tier is on: every property getProperties declares is a bind step, read and written on propertyTarget. Off for a plain u2 component, whose signal-less meta props are construction-time options.

Returns

boolean

Inherited from

Component.propertyTier

---

root

Get Signature

get root(): HTMLElement

Defined in: js-api/src/u2core/component.ts:575

Returns

HTMLElement

Set Signature

set root(x): void

Defined in: js-api/src/u2core/component.ts:579

Parameters

Parameter	Type
x	HTMLElement

Returns

void

---

rootId

Get Signature

get rootId(): string

Defined in: js-api/src/u2core/component.ts:596

Stable element id, minted (u2-<n>) on first ask unless the root has one: the anchor of for, aria-* and data-u2-owner-id references.

Returns

string

---

scope

Get Signature

get scope(): Scope

Defined in: js-api/src/u2core/component.ts:67

Minted on first use; assigned before _scopeMinted fires, so the hook's own this.scope.own(...) reads the stored scope instead of re-entering the mint.

Returns

Scope

Inherited from

Component.scope

---

visible

Get Signature

get visible(): boolean

Defined in: js-api/src/u2core/component.ts:586

Hidden ⇔ the root carries the hidden attribute.

Returns

boolean

Set Signature

set visible(x): void

Defined in: js-api/src/u2core/component.ts:590

Parameters

Parameter	Type
x	boolean

Returns

void

Methods

_scopeMinted()

protected _scopeMinted(_scope): void

Defined in: js-api/src/u2core/component.ts:80

First-mint hook: a platform descendant wires its lifecycle here. Never fired for a scope provided to init — that path runs inside the constructor chain.

Parameters

Parameter	Type
_scope	Scope

Returns

void

Inherited from

Component._scopeMinted

---

accessibleLabel()

protected accessibleLabel(): string | undefined

Defined in: js-api/src/u2core/component.ts:652

The accessible name: aria-label, then the aria-labelledby texts, then this control's own data-u2-part="label" element, then — for a root that is a button — its own text.

Returns

string | undefined

---

bindProps()

bindProps(): BindProp[]

Defined in: js-api/src/u2core/component.ts:392

The signal-backed subset of the meta props — what a binding picker offers on a named node — plus, under propertyTier, every declared property. Allocates no signal.

Returns

BindProp[]

Inherited from

Component.bindProps

---

bindStep()

bindStep(name): BindSource | Signal<unknown> | null

Defined in: js-api/src/u2core/component.ts:381

One binding step (DD5): a meta-declared prop's same-named Signal member — a named node is a bind source, generated off componentMeta the way getProperties is — then, under propertyTier, a cached signal over the declared property. '' answers the default binding: the component's own value signal, where one exists.

Parameters

Parameter	Type
name	string

Returns

BindSource | Signal<unknown> | null

Inherited from

Component.bindStep

---

deriveName()

protected deriveName(x): void

Defined in: js-api/src/u2core/component.ts:88

Sets the introspection/form key without claiming an automation id — the label-fallback path: a caption is not a stable identity, so it never reaches data-u2-name.

Parameters

Parameter	Type
x	string | undefined

Returns

void

Inherited from

Component.deriveName

---

dispose()

dispose(): void

Defined in: js-api/src/u2core/component.ts:227

On a never-engaged wrapper the getter mints here and _scopeMinted wires the lifecycle (own(kill) + the platform cleanup for Dart-owned), so dispose still kills it; re-entry from the kill cleanup is a no-op via the scope's disposed flag.

Returns

void

Inherited from

Component.dispose

---

effect()

effect(fn): this

Defined in: js-api/src/u2core/component.ts:160

Runs fn now and on every change of the signals it reads, until this component is disposed. Called while a row of each() or an effect run is being built, it belongs on a control built there (input.effect(...)) — on a longer-lived one it piles up with every rebuild, and u2 warns.

Parameters

Parameter	Type
fn	() => void

Returns

this

Inherited from

Component.effect

---

fireEvent()

protected fireEvent(eventId, args?): void

Defined in: js-api/src/u2core/component.ts:536

Every matching listener runs inside one batch; a throwing one is reported to this component's scope and does not stop the rest.

Parameters

Parameter	Type
eventId	string
args?	unknown

Returns

void

Inherited from

Component.fireEvent

---

getFunctions()

getFunctions(): FuncLike[]

Defined in: js-api/src/u2core/component.ts:288

Returns

FuncLike[]

Inherited from

Component.getFunctions

---

getItems()

getItems(_opts?): IItemsState | undefined

Defined in: js-api/src/u2core/component.ts:627

Items of a collection-like control; undefined for other kinds. list holds the first ITEMS_CAP unless all.

Parameters

Parameter	Type
_opts?	{ all?: boolean; }
_opts.all?	boolean

Returns

IItemsState | undefined

---

getProperties()

getProperties(): NamedProperty[]

Defined in: js-api/src/u2core/component.ts:252

The props componentMeta declares, each closed over the component's own state: a same-named signal reads and writes live, a same-named plain member, an options entry or — last — a specProps entry reads read-only. name — the component's spec identity — is never a property; an input's declared name prop is its form key, a different thing that IS a property like any other. A component never hand-writes its property list. The list is generated once per componentMeta: the accessors read live state, so only a re-stamp invalidates it.

Returns

NamedProperty[]

Inherited from

Component.getProperties

---

getState()

getState(): IControlState

Defined in: js-api/src/u2core/component.ts:605

The state block generic tests read (DG.U2.state). This base reads the DOM — kind, name, accessible name, aria-disabled, hidden, focus, aria-busy — plus getItems; a subclass adds what the DOM cannot say and spreads super.getState(). Synchronous, side-effect free, never cached.

Returns

IControlState

---

getWidgetStatus()

getWidgetStatus(): IWidgetStatus

Defined in: js-api/src/u2core/component.ts:764

The base status plus getState.

Returns

IWidgetStatus

Overrides

Component.getWidgetStatus

---

link()

link(name, source, twoWay): void

Defined in: js-api/src/u2core/component.ts:353

Keeps this component's name step and source equal, echo-suppressed by value; the reverse direction only where twoWay. A component that took source as its own signal needs no link and gets none; a read-only step cannot follow anything and gets none either.

Parameters

Parameter	Type
name	string
source	Signal<unknown>
twoWay	boolean

Returns

void

Inherited from

Component.link

---

on()

on(eventId, handler): () => void

Defined in: js-api/src/u2core/component.ts:523

Subscribes handler to onEvent(eventId); it gets the payload and this component. Owned by the ambient scope when there is one (the subscriber's), else by this component; runs as Scope.bind runs a handler. Answers the unsubscribe.

Parameters

Parameter	Type
eventId	string
handler	(arg, source) => void

Returns

() => void

Inherited from

Component.on

---

onEvent()

onEvent(eventId?): ObservableLike<unknown>

Defined in: js-api/src/u2core/component.ts:811

Component events plus the DOM events of that name raised on root — the listener is wired per subscription and dropped with it, or with the scope if the subscriber never does.

Parameters

Parameter	Type	Default value
eventId	string | null	null

Returns

ObservableLike<unknown>

Overrides

Component.onEvent

---

own()

own(dispose): this

Defined in: js-api/src/u2core/component.ts:167

Registers a cleanup that runs when this component is disposed.

Parameters

Parameter	Type
dispose	() => void

Returns

this

Inherited from

Component.own

---

propertyChanges()

protected propertyChanges(): ObservableLike<PropertyChange> | null

Defined in: js-api/src/u2core/component.ts:346

What refreshes the property tier's cached signals from outside: null where nothing announces a change (one-way).

Returns

ObservableLike<PropertyChange> | null

Inherited from

Component.propertyChanges

---

registerFunction()

protected registerFunction(f): void

Defined in: js-api/src/u2core/component.ts:516

Parameters

Parameter	Type
f	FuncLike

Returns

void

Inherited from

Component.registerFunction

---

revealItem()

revealItem(keyOrLabel): Promise<HTMLElement | null>

Defined in: js-api/src/u2core/component.ts:636

Brings the item into view and resolves to its element, or null when none matches: the exact key (data-u2-item) first, then the label, trimmed and case-insensitive. Several label matches reject, naming the candidates. This base searches the rendered [data-u2-item] elements under the root and in the popups it owns; a virtual or collapsible control overrides it to scroll or expand first.

Parameters

Parameter	Type
keyOrLabel	string

Returns

Promise<HTMLElement | null>

---

runInScope()

runInScope<T>(fn): T

Defined in: js-api/src/u2core/component.ts:153

Runs fn with this component's scope ambient: what it builds is owned by this component.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
fn	() => T

Returns

T

Inherited from

Component.runInScope

---

_isPlain()

protected static _isPlain(x): x is Record<string, unknown>

Defined in: js-api/src/u2core/component.ts:145

Parameters

Parameter	Type
x	unknown

Returns

x is Record<string, unknown>

Inherited from

Component._isPlain

---

build()

static build(builder): Control

Defined in: js-api/src/u2core/component.ts:836

Builds a control out of plain elements: builder runs with the new control's scope ambient, so signal bindings and nested components inside it are owned by the result. The ambient scope only spans the synchronous part of builder — components constructed after an await inside it are adopted by nobody and must be disposed by hand, or constructed before the first await.

Parameters

Parameter	Type
builder	() => HTMLElement | (string | HTMLElement | Control)[]

Returns

Control

---

forElement()

static forElement(el): Control | undefined

Defined in: js-api/src/u2core/component.ts:794

The nearest control owning el — the DOM → component door for tooling, automation and inspectors (the u2 counterpart of the platform's Widget.find): the nearest root at or above el, else, inside a popup portaled to the body, the popup's owner (data-u2-owner-id). Best-effort: the last control constructed on (or assigned) a root wins it. The root carries the control under Symbol.for('u2.control'), so every engine copy on the page answers alike.

Parameters

Parameter	Type
el	Element | null

Returns

Control | undefined

---

init()

static init(self, scope?): void

Defined in: js-api/src/u2core/component.ts:105

Per-instance state, for a constructed component and for an adopted platform object alike.

Parameters

Parameter	Type
self	Component
scope?	Scope

Returns

void

Inherited from

Component.init

---

is()

static is(x): x is Control

Defined in: js-api/src/u2core/component.ts:805

Structural probe by methods only — never .scope: the accessor mints.

Parameters

Parameter	Type
x	unknown

Returns

x is Control

Overrides

Component.is

---

jsonValue()

static jsonValue(x, depth?): JsonValue | undefined

Defined in: js-api/src/u2core/component.ts:716

The JSON-safe projection behind IControlState.value: a Date → its ISO string, an object with a string name (an entity, a column) → the name, arrays and sets element-wise, plain objects key-wise (depth 4), a signal → its current value; functions and elements → undefined; anything else → String(x).

Parameters

Parameter	Type	Default value
x	unknown	undefined
depth	number	0

Returns

JsonValue | undefined

---

labelOf()

protected static labelOf(el): string | undefined

Defined in: js-api/src/u2core/component.ts:665

aria-label, else the joined texts of the aria-labelledby elements; undefined when neither names el.

Parameters

Parameter	Type
el	Element

Returns

string | undefined

---

sameValue()

static sameValue(a, b): boolean

Defined in: js-api/src/u2core/component.ts:133

The equality the property tier and link suppress echoes by: Object.is, arrays element-wise, plain objects key-wise (recursive), everything else by identity.

Parameters

Parameter	Type
a	unknown
b	unknown

Returns

boolean

Inherited from

Component.sameValue

---

text()

protected static text(el): string

Defined in: js-api/src/u2core/component.ts:679

The text the user reads: trimmed, single-spaced.

Parameters

Parameter	Type
el	Element

Returns

string