packages/forms/signals/src/api/rules/hidden.ts - main - githubmirror/angular

packages/forms/signals/src/api/rules/hidden.ts
66 строк2 KB
brysonbw
feat(forms): allow permanent hidden fields in signal forms
29 июл 2026, 18:39
29 июл 2026, 18:39d5e8b1e
/**
 * @license
 * Copyright Google LLC All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.dev/license
 */

import {FieldPathNode} from '../../schema/path_node';
import {assertPathIsCurrent} from '../../schema/schema';
import type {LogicFn, PathKind, SchemaPath, SchemaPathRules} from '../types';

/**
 * Adds logic to a field to conditionally hide it. A hidden field does not contribute to the
 * validation, touched/dirty, or other state of its parent field.
 *
 * If a field may be hidden it is recommended to guard it with an `@if` in the template:
 * ```
 * @if (!email().hidden()) {
 *   <label for="email">Email</label>
 *   <input id="email" type="email" [control]="email" />
 * }
 * ```
 *
 * @param path The target path to add the hidden logic to.
 * @param config Options object containing the `when` condition.
 *  - `when`: A reactive function that returns `true` when the field is hidden.
 * @template TValue The type of value stored in the field the logic is bound to.
 * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
 *
 * @see [Hidden fields](guide/forms/signals/form-logic#configuring-hidden-state-on-fields)
 * @see [Availability state](guide/forms/signals/field-state-management#availability-state)
 *
 * @category logic
 * @publicApi 22.0
 */
export function hidden<TValue, TPathKind extends PathKind = PathKind.Root>(
  path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>,
  config?: {when?: NoInfer<LogicFn<TValue, boolean, TPathKind>>},
): void;

/**
 * Adds logic to a field to conditionally hide it.
 *
 * @deprecated Passing a function directly to `hidden` is deprecated. Use `{ when: ... }` instead.
 */
export function hidden<TValue, TPathKind extends PathKind = PathKind.Root>(
  path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>,
  logic?: NoInfer<LogicFn<TValue, boolean, TPathKind>>,
): void;

export function hidden<TValue, TPathKind extends PathKind = PathKind.Root>(
  path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>,
  configOrLogic?:
    | {when?: NoInfer<LogicFn<TValue, boolean, TPathKind>>}
    | NoInfer<LogicFn<TValue, boolean, TPathKind>>,
): void {
  assertPathIsCurrent(path);

  const pathNode = FieldPathNode.unwrapFieldPath(path);

  const logic =
    typeof configOrLogic === 'function' ? configOrLogic : (configOrLogic?.when ?? (() => true));

  pathNode.builder.addHiddenRule(logic);
}