Scope operators

Scope operators sit between the chain root and the leaf method. They narrow the broader leaf so it only fires for widgets that meet the scope condition.

Method	Restricts the match to widgets that…
tag(name)	…have name in their tags array.
state(name)	…are inside a form where the named state is currently active.

tag(name)

tag(name) narrows a leaf to only widgets that carry name in their tags array. Widgets without the tag pass through untouched, even if the leaf would otherwise match by type.

const formDef = [
  gui.inputs.textInput('street', { label: 'Street' }, ['priority']),
  gui.inputs.textInput('city', { label: 'City' }),
  gui.inputs.textInput('zip', { label: 'ZIP' }),
];

const formSelectors = [
  gui.selectors.tag('priority').textInputs({
    override: { hint: 'Required to ship.' },
  }),
];

Only Street carries the 'priority' tag, so only it picks up the hint. City and ZIP are still text inputs but the scope narrows them out of the match. Without the tag('priority') scope, the leaf would have decorated all three.

state(name)

state(name) narrows a leaf to fire only while the named state is active. The state is resolved against the form’s state map (the same one you declare via formConfig.states or via the gui.* states arg).

const formDef = [
  gui.inputs.booleanInput('submitting', { label: 'Mark as submitting' }),
  gui.actions.button({ label: 'Submit' }),
];

const formConfig = {
  states: {
    submitting: '$form.submitting === true',
  },
};

const formSelectors = [
  gui.selectors.state('submitting').actions({
    override: { disabled: true, label: 'Submitting…' },
  }),
];

Toggle the Mark as submitting switch to flip the state. While submitting is active, the selector fires and the button gets disabled: true plus a new label. Toggle off and the scope no longer matches — the button reverts to its declared shape.

Combining both

tag() and state() can be chained on the same selector — the engine collects every condition and matches when all of them hold. See Chaining for a worked example combining a tag and a state scope.

See also

• Multi-value scopes — tagsAnd, tagsOr for matching multiple tags at once.
• Chaining — composition order and partial-chain reuse.
• States — declaring named conditions in formConfig.states.