@ni/nimble-angular 17.9.10 → 18.0.0

package/thirdparty/directives/router_link.d.ts

@@ -0,0 +1,235 @@
+/**
+ * [Nimble]
+ * Copied from https://github.com/angular/angular/blob/15.2.10/packages/router/src/directives/router_link.ts
+ * with the following modifications:
+ * - Hardcode `isAnchorElement` to `true` so that the directive will correctly set the `href` on elements within nimble that represent anchors
+ * - Make `href` a `@HostBindinding` to avoid using Angular's private sanitization APIs because `href` bindings automatically are sanitized by
+ *   Angular (see https://angular.io/guide/security#sanitization-and-security-contexts). Implementations leveraging RouterLink should have a test
+ *   ensuring sanitization is called.
+ * - Comment out uneccessary export of the deprecated `RouterLinkWithHref`
+ */
+/**
+ * @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.io/license
+ */
+import { LocationStrategy } from '@angular/common';
+import { ElementRef, OnChanges, OnDestroy, Renderer2, SimpleChanges } from '@angular/core';
+import { Subject } from 'rxjs';
+import { Params, QueryParamsHandling, ActivatedRoute, Router, UrlTree } from '@angular/router';
+import * as i0 from "@angular/core";
+/**
+ * @description
+ *
+ * When applied to an element in a template, makes that element a link
+ * that initiates navigation to a route. Navigation opens one or more routed components
+ * in one or more `<router-outlet>` locations on the page.
+ *
+ * Given a route configuration `[{ path: 'user/:name', component: UserCmp }]`,
+ * the following creates a static link to the route:
+ * `<a routerLink="/user/bob">link to user component</a>`
+ *
+ * You can use dynamic values to generate the link.
+ * For a dynamic link, pass an array of path segments,
+ * followed by the params for each segment.
+ * For example, `['/team', teamId, 'user', userName, {details: true}]`
+ * generates a link to `/team/11/user/bob;details=true`.
+ *
+ * Multiple static segments can be merged into one term and combined with dynamic segments.
+ * For example, `['/team/11/user', userName, {details: true}]`
+ *
+ * The input that you provide to the link is treated as a delta to the current URL.
+ * For instance, suppose the current URL is `/user/(box//aux:team)`.
+ * The link `<a [routerLink]="['/user/jim']">Jim</a>` creates the URL
+ * `/user/(jim//aux:team)`.
+ * See {@link Router#createUrlTree createUrlTree} for more information.
+ *
+ * @usageNotes
+ *
+ * You can use absolute or relative paths in a link, set query parameters,
+ * control how parameters are handled, and keep a history of navigation states.
+ *
+ * ### Relative link paths
+ *
+ * The first segment name can be prepended with `/`, `./`, or `../`.
+ * * If the first segment begins with `/`, the router looks up the route from the root of the
+ *   app.
+ * * If the first segment begins with `./`, or doesn't begin with a slash, the router
+ *   looks in the children of the current activated route.
+ * * If the first segment begins with `../`, the router goes up one level in the route tree.
+ *
+ * ### Setting and handling query params and fragments
+ *
+ * The following link adds a query parameter and a fragment to the generated URL:
+ *
+ * ```
+ * <a [routerLink]="['/user/bob']" [queryParams]="{debug: true}" fragment="education">
+ *   link to user component
+ * </a>
+ * ```
+ * By default, the directive constructs the new URL using the given query parameters.
+ * The example generates the link: `/user/bob?debug=true#education`.
+ *
+ * You can instruct the directive to handle query parameters differently
+ * by specifying the `queryParamsHandling` option in the link.
+ * Allowed values are:
+ *
+ *  - `'merge'`: Merge the given `queryParams` into the current query params.
+ *  - `'preserve'`: Preserve the current query params.
+ *
+ * For example:
+ *
+ * ```
+ * <a [routerLink]="['/user/bob']" [queryParams]="{debug: true}" queryParamsHandling="merge">
+ *   link to user component
+ * </a>
+ * ```
+ *
+ * See {@link UrlCreationOptions.queryParamsHandling UrlCreationOptions#queryParamsHandling}.
+ *
+ * ### Preserving navigation history
+ *
+ * You can provide a `state` value to be persisted to the browser's
+ * [`History.state` property](https://developer.mozilla.org/en-US/docs/Web/API/History#Properties).
+ * For example:
+ *
+ * ```
+ * <a [routerLink]="['/user/bob']" [state]="{tracingId: 123}">
+ *   link to user component
+ * </a>
+ * ```
+ *
+ * Use {@link Router.getCurrentNavigation() Router#getCurrentNavigation} to retrieve a saved
+ * navigation-state value. For example, to capture the `tracingId` during the `NavigationStart`
+ * event:
+ *
+ * ```
+ * // Get NavigationStart events
+ * router.events.pipe(filter(e => e instanceof NavigationStart)).subscribe(e => {
+ *   const navigation = router.getCurrentNavigation();
+ *   tracingService.trace({id: navigation.extras.state.tracingId});
+ * });
+ * ```
+ *
+ * @ngModule RouterModule
+ *
+ * @publicApi
+ */
+export declare class RouterLink implements OnChanges, OnDestroy {
+    private router;
+    private route;
+    private readonly tabIndexAttribute;
+    private readonly renderer;
+    private readonly el;
+    private locationStrategy?;
+    private _preserveFragment;
+    private _skipLocationChange;
+    private _replaceUrl;
+    /**
+     * Represents an `href` attribute value applied to a host element,
+     * when a host element is `<a>`. For other tags, the value is `null`.
+     */
+    href: string | null;
+    /**
+     * Represents the `target` attribute on a host element.
+     * This is only used when the host element is an `<a>` tag.
+     */
+    target?: string;
+    /**
+     * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the
+     * `UrlCreationOptions`.
+     * @see {@link UrlCreationOptions#queryParams UrlCreationOptions#queryParams}
+     * @see {@link Router#createUrlTree Router#createUrlTree}
+     */
+    queryParams?: Params | null;
+    /**
+     * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the
+     * `UrlCreationOptions`.
+     * @see {@link UrlCreationOptions#fragment UrlCreationOptions#fragment}
+     * @see {@link Router#createUrlTree Router#createUrlTree}
+     */
+    fragment?: string;
+    /**
+     * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the
+     * `UrlCreationOptions`.
+     * @see {@link UrlCreationOptions#queryParamsHandling UrlCreationOptions#queryParamsHandling}
+     * @see {@link Router#createUrlTree Router#createUrlTree}
+     */
+    queryParamsHandling?: QueryParamsHandling | null;
+    /**
+     * Passed to {@link Router#navigateByUrl Router#navigateByUrl} as part of the
+     * `NavigationBehaviorOptions`.
+     * @see {@link NavigationBehaviorOptions#state NavigationBehaviorOptions#state}
+     * @see {@link Router#navigateByUrl Router#navigateByUrl}
+     */
+    state?: {
+        [k: string]: any;
+    };
+    /**
+     * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the
+     * `UrlCreationOptions`.
+     * Specify a value here when you do not want to use the default value
+     * for `routerLink`, which is the current activated route.
+     * Note that a value of `undefined` here will use the `routerLink` default.
+     * @see {@link UrlCreationOptions#relativeTo UrlCreationOptions#relativeTo}
+     * @see {@link Router#createUrlTree Router#createUrlTree}
+     */
+    relativeTo?: ActivatedRoute | null;
+    private commands;
+    /** Whether a host element is an `<a>` tag. */
+    private isAnchorElement;
+    private subscription?;
+    /** @internal */
+    onChanges: Subject<RouterLink>;
+    constructor(router: Router, route: ActivatedRoute, tabIndexAttribute: string | null | undefined, renderer: Renderer2, el: ElementRef, locationStrategy?: LocationStrategy | undefined);
+    /**
+     * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the
+     * `UrlCreationOptions`.
+     * @see {@link UrlCreationOptions#preserveFragment UrlCreationOptions#preserveFragment}
+     * @see {@link Router#createUrlTree Router#createUrlTree}
+     */
+    set preserveFragment(preserveFragment: boolean | string | null | undefined);
+    get preserveFragment(): boolean;
+    /**
+     * Passed to {@link Router#navigateByUrl Router#navigateByUrl} as part of the
+     * `NavigationBehaviorOptions`.
+     * @see {@link NavigationBehaviorOptions#skipLocationChange NavigationBehaviorOptions#skipLocationChange}
+     * @see {@link Router#navigateByUrl Router#navigateByUrl}
+     */
+    set skipLocationChange(skipLocationChange: boolean | string | null | undefined);
+    get skipLocationChange(): boolean;
+    /**
+     * Passed to {@link Router#navigateByUrl Router#navigateByUrl} as part of the
+     * `NavigationBehaviorOptions`.
+     * @see {@link NavigationBehaviorOptions#replaceUrl NavigationBehaviorOptions#replaceUrl}
+     * @see {@link Router#navigateByUrl Router#navigateByUrl}
+     */
+    set replaceUrl(replaceUrl: boolean | string | null | undefined);
+    get replaceUrl(): boolean;
+    /**
+     * Modifies the tab index if there was not a tabindex attribute on the element during
+     * instantiation.
+     */
+    private setTabIndexIfNotOnNativeEl;
+    /** @nodoc */
+    ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * Commands to pass to {@link Router#createUrlTree Router#createUrlTree}.
+     *   - **array**: commands to pass to {@link Router#createUrlTree Router#createUrlTree}.
+     *   - **string**: shorthand for array of commands with just the string, i.e. `['/route']`
+     *   - **null|undefined**: effectively disables the `routerLink`
+     * @see {@link Router#createUrlTree Router#createUrlTree}
+     */
+    set routerLink(commands: any[] | string | null | undefined);
+    /** @nodoc */
+    onClick(button: number, ctrlKey: boolean, shiftKey: boolean, altKey: boolean, metaKey: boolean): boolean;
+    /** @nodoc */
+    ngOnDestroy(): any;
+    private updateHref;
+    private applyAttributeValue;
+    get urlTree(): UrlTree | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RouterLink, [null, null, { attribute: "tabindex"; }, null, null, null]>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RouterLink, never, never, { "target": "target"; "queryParams": "queryParams"; "fragment": "fragment"; "queryParamsHandling": "queryParamsHandling"; "state": "state"; "relativeTo": "relativeTo"; "preserveFragment": "preserveFragment"; "skipLocationChange": "skipLocationChange"; "replaceUrl": "replaceUrl"; "routerLink": "routerLink"; }, {}, never, never, false, never>;
+}

package/thirdparty/directives/select_control_value_accessor.d.ts

@@ -0,0 +1,148 @@
+/**
+ * [Nimble]
+ * Copied from https://github.com/angular/angular/blob/15.2.10/packages/forms/src/directives/select_control_value_accessor.ts
+ * with the following modifications:
+ * - Update imports
+ * - Remove all configuration from SelectControlValueAccessor's `@Directive` decorator
+ * - Remove all configuration from NgSelectOption's `@Directive` decorator
+ * - Update validation within `compareWith` to use public APIs
+ */
+/**
+ * @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.io/license
+ */
+import { ElementRef, OnDestroy, Renderer2 } from '@angular/core';
+import type { ControlValueAccessor } from '@angular/forms';
+import { BuiltInControlValueAccessor } from './control_value_accessor';
+import * as i0 from "@angular/core";
+/**
+ * @description
+ * The `ControlValueAccessor` for writing select control values and listening to select control
+ * changes. The value accessor is used by the `FormControlDirective`, `FormControlName`, and
+ * `NgModel` directives.
+ *
+ * @usageNotes
+ *
+ * ### Using select controls in a reactive form
+ *
+ * The following examples show how to use a select control in a reactive form.
+ *
+ * {@example forms/ts/reactiveSelectControl/reactive_select_control_example.ts region='Component'}
+ *
+ * ### Using select controls in a template-driven form
+ *
+ * To use a select in a template-driven form, simply add an `ngModel` and a `name`
+ * attribute to the main `<select>` tag.
+ *
+ * {@example forms/ts/selectControl/select_control_example.ts region='Component'}
+ *
+ * ### Customizing option selection
+ *
+ * Angular uses object identity to select option. It's possible for the identities of items
+ * to change while the data does not. This can happen, for example, if the items are produced
+ * from an RPC to the server, and that RPC is re-run. Even if the data hasn't changed, the
+ * second response will produce objects with different identities.
+ *
+ * To customize the default option comparison algorithm, `<select>` supports `compareWith` input.
+ * `compareWith` takes a **function** which has two arguments: `option1` and `option2`.
+ * If `compareWith` is given, Angular selects option by the return value of the function.
+ *
+ * ```ts
+ * const selectedCountriesControl = new FormControl();
+ * ```
+ *
+ * ```
+ * <select [compareWith]="compareFn"  [formControl]="selectedCountriesControl">
+ *     <option *ngFor="let country of countries" [ngValue]="country">
+ *         {{country.name}}
+ *     </option>
+ * </select>
+ *
+ * compareFn(c1: Country, c2: Country): boolean {
+ *     return c1 && c2 ? c1.id === c2.id : c1 === c2;
+ * }
+ * ```
+ *
+ * **Note:** We listen to the 'change' event because 'input' events aren't fired
+ * for selects in IE, see:
+ * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event#browser_compatibility
+ *
+ * @ngModule ReactiveFormsModule
+ * @ngModule FormsModule
+ * @publicApi
+ */
+export declare class SelectControlValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor {
+    /** @nodoc */
+    value: any;
+    /** @internal */
+    _optionMap: Map<string, any>;
+    /** @internal */
+    _idCounter: number;
+    /**
+     * @description
+     * Tracks the option comparison algorithm for tracking identities when
+     * checking for changes.
+     */
+    set compareWith(fn: (o1: any, o2: any) => boolean);
+    private _compareWith;
+    /**
+     * Sets the "value" property on the select element.
+     * @nodoc
+     */
+    writeValue(value: any): void;
+    /**
+     * Registers a function called when the control value changes.
+     * @nodoc
+     */
+    registerOnChange(fn: (value: any) => any): void;
+    /** @internal */
+    _registerOption(): string;
+    /** @internal */
+    _getOptionId(value: any): string | null;
+    /** @internal */
+    _getOptionValue(valueString: string): any;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SelectControlValueAccessor, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SelectControlValueAccessor, never, never, { "compareWith": "compareWith"; }, {}, never, never, false, never>;
+}
+/**
+ * @description
+ * Marks `<option>` as dynamic, so Angular can be notified when options change.
+ *
+ * @see `SelectControlValueAccessor`
+ *
+ * @ngModule ReactiveFormsModule
+ * @ngModule FormsModule
+ * @publicApi
+ */
+export declare class NgSelectOption implements OnDestroy {
+    private _element;
+    private _renderer;
+    private _select;
+    /**
+     * @description
+     * ID of the option element
+     */
+    id: string;
+    constructor(_element: ElementRef, _renderer: Renderer2, _select: SelectControlValueAccessor);
+    /**
+     * @description
+     * Tracks the value bound to the option element. Unlike the value binding,
+     * ngValue supports binding to objects.
+     */
+    set ngValue(value: any);
+    /**
+     * @description
+     * Tracks simple string values bound to the option element.
+     * For objects, use the `ngValue` input binding.
+     */
+    set value(value: any);
+    /** @internal */
+    _setElementValue(value: string): void;
+    /** @nodoc */
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgSelectOption, [null, null, { optional: true; host: true; }]>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgSelectOption, never, never, { "ngValue": "ngValue"; "value": "value"; }, {}, never, never, false, never>;
+}

package/thirdparty/utils/coercion.d.ts

@@ -0,0 +1,15 @@
+/**
+ * [Nimble]
+ * Copied from https://github.com/angular/angular/blob/15.2.10/packages/core/src/util/coercion.ts
+ * with no modifications so that the `coerceToBoolean` function can be used by the forked directive
+ * in `router_link.ts` without depending on private Angular APIs.
+ */
+/**
+ * @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.io/license
+ */
+/** Coerces a value (typically a string) to a boolean. */
+export declare function coerceToBoolean(value: unknown): boolean;

package/build/generate-icons/README.md

@@ -1,15 +0,0 @@
-# Generate Icons
-
-## Behavior
-
-- Depends on the build output of `nimble-tokens` to generate icon Angular integrations.
-- Generates an icon directive file and module file for each icon, and a barrel file.
-
-## How to run
-
-This script runs as part of the Nimble Angular build.
-
-To run manually:
-
-1. Run a Nimble Angular build.
-2. Edit `index.js` for this script and run `npm run generate-icons` (can re-run when modifying `index.js` behavior).

package/src/thirdparty/README.md

@@ -1,10 +0,0 @@
-This folder contains forked third-party source.
-
-- Each file in this folder should begin with a comment explaining where the file comes from and listing any modifications from the original.
-- All comments made by Nimble developers should be prefixed with the tag "`[Nimble]`".
-
-The `directives` folder corresponds to the [`packages/forms/src/directives` folder](https://github.com/angular/angular/tree/14.2.6/packages/forms/src/directives) of the Angular repo. **When updating the version of Angular** used by the `nimble-angular` package:
-1. Examine the versions of the files in the `directives` folder. The first comment in each file should contain a link with the release version in it. If the file's version is less than the version of Angular being upgraded to, continue with the following steps to update the files.
-2. Copy the upgrade version of the files on top of the existing ones, and migrate diffs as necessary.
-3. Update the link in the comment at the top of the file.
-4. Update the list of diffs in the comment at the top of the file. (I.e. if you made additional changes.)