Control

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

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:668

Parameters

Parameter	Type
root?	HTMLElement
scope?	Scope

Returns

Control

Overrides

Component.constructor

Properties

Property	Modifier	Type	Default value	Description	Inherited from	Defined in
_root	protected	HTMLElement	undefined	-	-	js-api/src/u2core/component.ts:666
_u2	readonly	ComponentState	undefined	-	Component._u2	js-api/src/u2core/component.ts:119
componentMeta?	public	ComponentMetaBase	undefined	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:114
specProps?	public	Record<string, unknown>	undefined	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:118
isRoot	static	boolean	false	A root has no owner by design (a dialog): built with none, it is not reported as owner-missing.	Component.isRoot	js-api/src/u2core/component.ts:81

Accessors

aiDescription

Get Signature

get aiDescription(): string | null

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

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:341

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:440

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:882

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:886

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:435

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:429

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:675

Returns

HTMLElement

Set Signature

set root(x): void

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

Parameters

Parameter	Type
x	HTMLElement

Returns

void

---

rootId

Get Signature

get rootId(): string

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

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:86

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. Lazy: counted and tracked only once it owns something, so a static control costs nothing.

Returns

Scope

Inherited from

Component.scope

---

visible

Get Signature

get visible(): boolean

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

Hidden ⇔ the root carries the hidden attribute.

Returns

boolean

Set Signature

set visible(x): void

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

Parameters

Parameter	Type
x	boolean

Returns

void

Methods

_scopeMinted()

protected _scopeMinted(_scope): void

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

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:762

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:492

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): Signal<unknown> | BindSource | null

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

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

Signal<unknown> | BindSource | null

Inherited from

Component.bindStep

---

deriveName()

protected deriveName(x): void

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

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:687

Disposes the control; disposed by hand, it also leaves the page — a dead control left on show looks alive. One its owner disposes leaves the DOM to whoever holds it: a region swapping its content, a spec re-rendering.

Returns

void

Overrides

Component.dispose

---

effect()

effect(fn): this

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

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:636

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:388

Returns

FuncLike[]

Inherited from

Component.getFunctions

---

getItems()

getItems(_opts?): IItemsState | undefined

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

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:352

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:713

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:874

The base status plus getState.

Returns

IWidgetStatus

Overrides

Component.getWidgetStatus

---

link()

link(name, source, twoWay): void

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

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:623

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:921

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:267

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:446

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:616

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:746

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:253

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

Deprecated

Use the owner verb build(fn) (OwnerVerbs.build): this.build(fn), dialog.build(fn).

Inherited from

Component.runInScope

---

subscribe()

subscribe<T>(source, handler): () => void

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

Subscribes handler to source until this owner is disposed. See Scope.subscribe.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
source	ObservableLike<T>
handler	(value) => void

Returns

() => void

Inherited from

OwnerVerbs.subscribe

---

task()

task<R>(fn, options?): TaskRun

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

Async work owned here. See Scope.task.

Type Parameters

Type Parameter
R

Parameters

Parameter	Type
fn	(t) => R | PromiseLike<R>
options?	TaskOptions

Returns

TaskRun

Inherited from

OwnerVerbs.task

---

_isPlain()

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

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

Parameters

Parameter	Type
x	unknown

Returns

x is Record<string, unknown>

Inherited from

Component._isPlain

---

build()

Call Signature

static build(builder, options?): Control

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

The function component component makes, under its old name.

Parameters

Parameter	Type
builder	(self) => BuiltRoot
options?	ControlBuildOptions

Returns

Control

Deprecated

Use component: one spelling, apart from an owner's build(fn).

Call Signature

static build<R>(builder, options?): never

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

The function component component makes, under its old name.

Type Parameters

Type Parameter
R extends BuiltHandle

Parameters

Parameter	Type
builder	(self) => R
options?	ControlBuildOptions

Returns

never

Deprecated

Use component: one spelling, apart from an owner's build(fn).

---

forElement()

static forElement(el): Control | undefined

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

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:126

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:915

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:826

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:775

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:232

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:789

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

Parameters

Parameter	Type
el	Element

Returns

string