Skip to main content

GroupApi

State and operations for a structural group, including its typed children.

Import​

import type { GroupApi } from '@ngblocks/form-nodes';

When to use it​

Use for structural-group API operations. A group's $api combines this contract with a callable signal; child nodes are available through children.

Declaration​

type GroupApi<TNodes extends Nodes, TParent extends AnyNode = AnyNode> = Omit<FormApi<TNodes, TParent>, 'onValueChange' | 'setValidators' | 'children' | 'forEachChild' | 'errors' | 'allErrors' | 'form' | 'root' | 'getError' | 'add' | 'remove' | 'nodeType' | 'submit' | 'submitted' | 'submitting' | 'validationStatus'> & {
    nodeType(): 'group';
    onValueChange(callback: (value: FormValue<TNodes>, node: GroupNode<TNodes, TParent>) => void, options?: {
        injector?: Injector;
        debounce?: number;
    }): () => void;
    setValidators(validators: ValidatorSource<GroupValue<TNodes>, GroupNode<TNodes, TParent>>): void;
    readonly children: GroupChildren<TNodes, TParent> & Readonly<Record<string, DynamicNode>>;
    forEachChild(callback: (child: keyof TNodes extends never ? DynamicNode : GroupChildren<TNodes, TParent>[keyof TNodes], key: string) => void, options?: {
        includeDynamic?: false;
    }): void;
    forEachChild(callback: (child: DynamicNode, key: string) => void, options: {
        includeDynamic?: boolean;
    }): void;
    add<TKey extends string, TDefinition>(key: TKey extends keyof TNodes | '$api' ? never : TKey, definition: ObjectNodeDefinitionInput<TDefinition>): AddedNode<TDefinition, GroupNode<TNodes, TParent>>;
    add<TDefinitions extends ObjectNodeDefinitions>(definitions: TDefinitions & ObjectNodeDefinitionInputs<TDefinitions> & Partial<Record<keyof TNodes | '$api', never>>): {
        readonly [TKey in keyof TDefinitions]: AddedNode<TDefinitions[TKey], GroupNode<TNodes, TParent>>;
    };
    remove(key: string): DynamicNode | undefined;
    form: Signal<NearestForm<TParent> | null>;
    root: Signal<GroupRoot<TNodes, TParent>>;
    errors: NodeErrorsSignal<GroupNode<TNodes, TParent>>;
    allErrors: Signal<readonly ValidationErrorWithTargetNode<AnyNode>[]>;
    getError<TKind extends keyof ValidationErrorMap>(kind: TKind): (ValidationErrorWithTargetNode<GroupNode<TNodes, TParent>> & ValidationErrorMap[TKind]) | undefined;
    getError<TKind extends keyof ValidationErrorMap | (string & {})>(kind: TKind): (ValidationErrorWithTargetNode<GroupNode<TNodes, TParent>> & CustomValidationError<TKind>) | undefined;
    validationStatus: Signal<ValidationStatus>;
    submitting: Signal<boolean>;
};

Type parameters​

ParameterConstraintDefault
TNodesNodesRequired
TParentAnyNodeAnyNode

Declared members​

The declaration above also includes inherited contracts and overloads where applicable.

MemberMeaning
nodeTypeReturns the concrete primitive represented by this node.
onValueChangeSubscribes to future exposed value changes and returns an idempotent cancellation function. Runs untracked, respects equality and control debounce, and skips initial values. Multiple listeners coexist with the construction callback; subscriptions are not cloned. The explicit injector, otherwise the registration context, owns the listener. The node's current injector also ends the subscription on destruction and acts as the fallback owner. Binding and ancestor ownership follow the node when it is rebound or detached. Without an injector, observation still works and can be canceled manually. A positive debounce delays only this callback until that many milliseconds without another change. Omitted or zero stays synchronous. Cancellation drops pending delivery. Node values, validation, and interaction state are unaffected by the subscription delay.
setValidatorsReplaces this group's validators while preserving its node type in inline callbacks.
childrenReadonly runtime child map. Declared properties retain exact node types; arbitrary keys use DynamicNode.
forEachChildDynamically added nodes are excluded by default. Pass { includeDynamic: true } to visit them.
addAdds one child at runtime and returns the attached node with its exact inferred type.
removeDetaches a dynamically added child. Initially declared children cannot be removed.
formNearest explicit form() containing this group, or null when no form workflow owns it. A nested explicit form is the workflow owner instead of the complete structural root.
rootComplete structural root containing this group. A root or detached group returns itself. Use this signal when traversal must cross nested form workflow boundaries.
errorsValidation errors belonging directly to this group, excluding descendant-owned errors.
allErrorsValidation errors from this group and its complete subtree in structural order.
getErrorReturns the first validation error belonging directly to this group and matching kind. Suggests registered error kinds while accepting any custom string.
validationStatusAggregated validation phase for this group subtree: 'valid', 'invalid', or 'unknown'.
submittingWhether an ancestor form is currently running its submission action. Groups cannot initiate submission.
Last updated on