@angular-wave/angular.ts 0.7.0-beta.0 → 0.7.1

package/src/interface.ts

@@ -0,0 +1,329 @@
+import { Attributes } from "./core/compile/attributes.js";
+import { Scope } from "./core/scope/scope.js";
+
+/**
+ * A JavaScript expression represented as a string.
+ *
+ * Often used in interpolation bindings such as:
+ * `<span title="{{ attrBinding }}">{{ textBinding }}</span>`.
+ * Evaluated in the context of a {@link import('./core/scope/scope.js').Scope `scope`} object.
+ */
+export type Expression = string;
+
+/**
+ * A dependency-annotated factory array used by AngularTS DI system.
+ *
+ * It consists of zero or more dependency names (as strings), followed by
+ * a factory function that takes those dependencies as arguments.
+ *
+ * Example:
+ * ```ts
+ * ['dep1', 'dep2', function(dep1, dep2) { ... }]
+ * ```
+ */
+export type AnnotatedFactory = [...string[], (...args: any[]) => any];
+
+/**
+ * A factory that can be either a standalone function or a dependency-annotated array.
+ *
+ * The array form is used to support minification-safe dependency injection.
+ * See {@link AnnotatedFactory}.
+ */
+export type InjectableFactory = (...args: any[]) => any;
+
+export type Injectable = AnnotatedFactory | InjectableFactory;
+
+/**
+ * An object that defines how a service is constructed.
+ *
+ * It must define a `$get` property that provides the instance of the service,
+ * either as a plain factory function or as an {@link AnnotatedFactory}.
+ */
+export interface ServiceProvider {
+  $get: Injectable;
+}
+
+/**
+ * The API for registering different types of providers with the injector.
+ *
+ * This interface is used within AngularTS's `$provide` service to define
+ * services, factories, constants, values, decorators, etc.
+ */
+export interface Provider {
+  /**
+   * Register a service provider.
+   * @param name - The name of the service.
+   * @param provider - An object with a `$get` property that defines how the service is created.
+   */
+  provider(name: string, provider: ServiceProvider): ServiceProvider;
+
+  /**
+   * Register a factory function to create a service.
+   * @param name - The name of the service.
+   * @param factoryFn - A function (or annotated array) that returns the service instance.
+   */
+  factory(name: string, factoryFn: Injectable): ServiceProvider;
+
+  /**
+   * Register a constructor function to create a service.
+   * @param name - The name of the service.
+   * @param constructor - A class or function to instantiate.
+   */
+  service(name: string, constructor: Injectable): ServiceProvider;
+
+  /**
+   * Register a fixed value as a service.
+   * @param name - The name of the service.
+   * @param val - The value to use.
+   */
+  value(name: string, val: any): ServiceProvider;
+
+  /**
+   * Register a constant value (available during config).
+   * @param name - The name of the constant.
+   * @param val - The constant value.
+   */
+  constant(name: string, val: any): void;
+
+  /**
+   * Register a decorator function to modify or replace an existing service.
+   * @param name - The name of the service to decorate.
+   * @param fn - A function that takes `$delegate` and returns a decorated service.
+   */
+  decorator(name: string, fn: Injectable): void;
+}
+
+/**
+ * A filter function takes an input and optional arguments, and returns a transformed value.
+ */
+export type FilterFn = (input: any, ...args: any[]) => any;
+
+/**
+ * A filter factory function that returns a FilterFn.
+ */
+export type FilterFactory = (...args: any[]) => FilterFn;
+
+/**
+ * A controller constructor function used in AngularTS.
+ */
+export type ControllerConstructor = (...args: any[]) => void | Controller;
+
+/**
+ * Describes the changes in component bindings during `$onChanges`.
+ */
+export interface ChangesObject<T = any> {
+  /** New value of the binding */
+  currentValue: T;
+  /** Whether this is the first change */
+  isFirstChange: () => boolean;
+}
+
+/**
+ * Mapping of binding property names to their change metadata.
+ */
+export type OnChangesObject = Record<string, ChangesObject>;
+
+/**
+ * AngularTS component lifecycle interface.
+ */
+export interface Controller {
+  /** Optional controller name (used in debugging) */
+  name?: string;
+  /** Called when the controller is initialized */
+  $onInit?: () => void;
+  /** Called when one-way bindings are updated */
+  $onChanges?: (changes: OnChangesObject) => void;
+  /** Called before the controller is destroyed */
+  $onDestroy?: () => void;
+  /** Called after the component is linked */
+  $postLink?: () => void;
+}
+
+/**
+ * Defines a component's configuration object.
+ */
+export interface ComponentOptions {
+  /** Controller function or injectable string reference */
+  controller?: string | Injectable;
+  /** Alias name for the controller in templates */
+  controllerAs?: string;
+  /** Inline HTML template */
+  template?: string | Injectable;
+  /** URL of the HTML template */
+  templateUrl?: string | Injectable;
+  /** Binding definitions (e.g., `@`, `=`, `<`) */
+  bindings?: Record<string, string>;
+  /** Enable transclusion or specify named slots */
+  transclude?: boolean | Record<string, string>;
+  /** Required controllers from other directives */
+  require?: Record<string, string>;
+}
+
+/**
+ * A controller instance or object map used in directives.
+ */
+export type DirectiveController =
+  | Controller
+  | Controller[]
+  | { [key: string]: Controller };
+
+/**
+ * Represents a controller used within directive link functions.
+ */
+export type TController = DirectiveController | NgModelController;
+
+/**
+ * Defines optional pre/post link functions in directive compile phase.
+ */
+export interface DirectivePrePost {
+  pre?: DirectiveLinkFn;
+  post?: DirectiveLinkFn;
+}
+
+/**
+ * A link function executed during directive linking.
+ */
+export type DirectiveLinkFn = (
+  scope: Scope,
+  element: HTMLElement,
+  attrs: Attributes,
+  controller?: TController,
+  transclude?: (...args: any[]) => any,
+) => void;
+
+/**
+ * A compile function used to prepare directives before linking.
+ */
+export type DirectiveCompileFn = (
+  templateElement: HTMLElement,
+  templateAttributes: Attributes,
+  transclude: (...args: any[]) => any,
+) => void | DirectiveLinkFn | DirectivePrePost;
+
+/**
+ * Defines the structure of an AngularTS directive.
+ */
+export interface Directive {
+  /** Optional name (usually inferred) */
+  name?: string;
+  /** Restrict option: 'A' and/or 'E'. Defaults to 'EA' */
+  restrict?: string;
+  /** Compile function for the directive */
+  compile?: DirectiveCompileFn;
+  /** Controller constructor or injectable string name */
+  controller?: string | Injectable | any;
+  /** Alias name for the controller in templates */
+  controllerAs?: string;
+  /** Whether to bind scope to controller */
+  bindToController?: boolean | Record<string, string>;
+  /** Link function(s) executed during linking */
+  link?: DirectiveLinkFn | DirectivePrePost;
+  /** Priority of the directive */
+  priority?: number;
+  /** Stops further directive processing if true */
+  terminal?: boolean;
+  /** Replaces the element with the template if true */
+  replace?: boolean;
+  /** Required controllers for the directive */
+  require?: string | string[] | Record<string, string>;
+  /** Scope configuration (`true`, `false`, or object for isolate scope) */
+  scope?: boolean | Record<string, string>;
+  /** Inline template */
+  template?: string | ((element: Element, attrs: Attributes) => string);
+  /** Template namespace (e.g., SVG, HTML) */
+  templateNamespace?: string;
+  /** Template URL for loading from server */
+  templateUrl?: string | ((element: Element, attrs: Attributes) => string);
+  /** Enables transclusion or configures named slots */
+  transclude?: boolean | "element" | Record<string, string>;
+  /** Internal hook for directive compilation state */
+  $$addStateInfo?: (...args: any[]) => any;
+}
+
+/**
+ * A factory function returning a directive definition.
+ */
+export type DirectiveFactory = (...args: any[]) => Directive | DirectiveLinkFn;
+
+/**
+ * Represents advanced transclusion functions used in directives.
+ */
+export interface TranscludeFunctionObject {
+  /** Transcludes content with a new scope */
+  transcludeWithScope(
+    scope: Scope,
+    cloneAttachFn: CloneAttachFunction,
+    element?: Element,
+    slotName?: string,
+  ): Element;
+  /** Transcludes content without creating a new scope */
+  transcludeWithoutScope(
+    cloneAttachFn?: CloneAttachFunction,
+    element?: Element,
+    slotName?: string,
+  ): Element;
+  /** Checks if a named slot is filled */
+  isSlotFilled(slotName: string): boolean;
+}
+
+/**
+ * Callback used when transcluded content is cloned.
+ */
+export type CloneAttachFunction = (
+  clonedElement?: Element,
+  scope?: Scope,
+) => any;
+
+/**
+ * Configuration for ngModel behavior.
+ */
+export interface NgModelOptions {
+  /** Space-separated event names that trigger updates */
+  updateOn?: string;
+  /** Delay in milliseconds or event-specific debounce times */
+  debounce?: number | Record<string, number>;
+  /** Whether to allow invalid values */
+  allowInvalid?: boolean;
+  /** Enables getter/setter style ngModel */
+  getterSetter?: boolean;
+  /** Timezone used for Date objects */
+  timezone?: string;
+  /** Time display format including seconds */
+  timeSecondsFormat?: string;
+  /** Whether to remove trailing :00 seconds */
+  timeStripZeroSeconds?: boolean;
+}
+
+/**
+ * Controller API for ngModel directive.
+ */
+export interface NgModelController {
+  /** Updates the view when the model changes */
+  $render(): void;
+  /** Sets the validity state of the control */
+  $setValidity(validationErrorKey: string, isValid: boolean): void;
+  /** Updates the model value */
+  $setViewValue(value: any, trigger?: string): void;
+  /** Marks the control as pristine */
+  $setPristine(): void;
+  /** Marks the control as dirty */
+  $setDirty(): void;
+  /** Re-validates the model */
+  $validate(): void;
+  /** Marks the control as touched */
+  $setTouched(): void;
+  /** Marks the control as untouched */
+  $setUntouched(): void;
+  /** Rolls back to previous view value */
+  $rollbackViewValue(): void;
+  /** Commits the current view value to the model */
+  $commitViewValue(): void;
+  /** Processes view-to-model transformations */
+  $processModelValue(): void;
+  /** Determines if value is considered empty */
+  $isEmpty(value: any): boolean;
+  /** Overrides the model options dynamically */
+  $overrideModelOptions(options: NgModelOptions): void;
+  /** Current value shown in the view */
+  $viewValue: any;
+}

package/src/loader.js

@@ -4,6 +4,7 @@ import {
   ngAttrPrefixes,
   assertNotHasOwnProperty,
   errorHandlingConfig,
+  hasOwn,
 } from "./shared/utils.js";
 import {
   getController,
@@ -18,6 +19,7 @@ import { publishExternalAPI } from "./public.js";
 import { VERSION } from "./public.js";
 import { unnestR } from "./shared/common.js";
 import { EventBus } from "./core/pubsub/pubsub.js";
+import { $injectTokens } from "./injection-tokens.js";
 
 const ngMinErr = minErr("ng");
 const $injectorMinErr = minErr("$injector");
@@ -42,7 +44,9 @@ export class Angular {
     /** @type {import('./core/pubsub/pubsub.js').PubSub} */
     this.EventBus = EventBus;
 
-    /** @type {string} */
+    /**
+     * @type {string} `version` from `package.json`
+     */
     this.version = VERSION;
 
     /** @type {!Array<string|any>} */
@@ -54,16 +58,17 @@ export class Angular {
     this.errorHandlingConfig = errorHandlingConfig;
 
     window["angular"] = this;
+    this.$injectTokens = $injectTokens;
     publishExternalAPI(this);
   }
 
   /**
-   * Use this function to manually start up AngularJS application.
+   * Use this function to manually start up AngularTS application.
    *
    * AngularTS will detect if it has been loaded into the browser more than once and only allow the
    * first loaded script to be bootstrapped and will report a warning to the browser console for
    * each of the subsequent scripts. This prevents strange results in applications, where otherwise
-   * multiple instances of AngularJS try to work on the DOM.
+   * multiple instances of AngularTS try to work on the DOM.
    *   *
    * <div class="alert alert-warning">
    * **Note:** Do not bootstrap the app on an element with a directive that uses {@link ng.$compile#transclusion transclusion},
@@ -92,18 +97,13 @@ export class Angular {
    * </html>
    * ```
    *
-   * @param {string | Element | Document} element DOM element which is the root of AngularJS application.
+   * @param {string | Element | Document} element DOM element which is the root of AngularTS application.
    * @param {Array<String|any>} [modules] an array of modules to load into the application.
    *     Each item in the array should be the name of a predefined module or a (DI annotated)
    *     function that will be invoked by the injector as a `config` block.
    *     See: {@link angular.module modules}
-   * @param {AngularBootstrapConfig} [config] an object for defining configuration options for the application. The
-   *     following keys are supported:
-   *
-   * * `strictDi` - disable automatic function annotation for the application. This is meant to
-   *   assist in finding bugs which break minified code. Defaults to `false`.
-   *
-   * @returns {any} InjectorService - Returns the newly created injector for this app.
+   * @param {AngularBootstrapConfig} [config]
+   * @returns {import('./core/di/internal-injector.js').InjectorService} The created injector instance for this application.
    */
   bootstrap(element, modules, config) {
     config = config || {
@@ -123,6 +123,9 @@ export class Angular {
 
     this.bootsrappedModules.unshift([
       "$provide",
+      /**
+       * @param {import('./interface.ts').Provider} $provide
+       */
       ($provide) => {
         $provide.value("$rootElement", element);
       },
@@ -151,7 +154,7 @@ export class Angular {
         compileFn(scope);
 
         // https://github.com/angular-ui/ui-router/issues/3678
-        if (!Object.prototype.hasOwnProperty.call($injector, "strictDi")) {
+        if (!hasOwn($injector, "strictDi")) {
           try {
             $injector.invoke(() => {});
           } catch (error) {
@@ -226,13 +229,13 @@ export class Angular {
 
   /**
    *
-   * The `angular.module` is a global place for creating, registering and retrieving AngularJS
+   * The `angular.module` is a global place for creating, registering and retrieving AngularTS
    * modules.
-   * All modules (AngularJS core or 3rd party) that should be available to an application must be
+   * All modules (AngularTS core or 3rd party) that should be available to an application must be
    * registered using this mechanism.
    *
-   * Passing one argument retrieves an existing {@link import('./types.js').Module},
-   * whereas passing more than one argument creates a new {@link import('./types.js').Module}
+   * Passing one argument retrieves an existing {@link import('./interface.ts').Module},
+   * whereas passing more than one argument creates a new {@link import('./interface.ts').Module}
    *
    *
    * # Module
@@ -267,13 +270,13 @@ export class Angular {
    * @param {string} name The name of the module to create or retrieve.
    * @param {Array.<string>} [requires] If specified then new module is being created. If
    *        unspecified then the module is being retrieved for further configuration.
-   * @param {Array<any>|Function} [configFn] Optional configuration function for the module. Same as
-   *        {@link import('./types.js').Module#config Module#config()}.
+   * @param {Array<any>|Function} [configFn] Optional configuration function for the module that gets
+   *        passed to {@link NgModule.config NgModule.config()}.
    * @returns {NgModule} A newly registered module.
    */
   module(name, requires, configFn) {
     assertNotHasOwnProperty(name, "module");
-    if (requires && Object.prototype.hasOwnProperty.call(modules, name)) {
+    if (requires && hasOwn(modules, name)) {
       modules[name] = null;
     }
     return ensure(modules, name, () => {

package/src/loader.md

@@ -6,8 +6,8 @@
 - @installation
 - @description
 -
-- The ng module is loaded by default when an AngularJS application is started. The module itself
-- contains the essential components for an AngularJS application to function. The table below
+- The ng module is loaded by default when an AngularTS application is started. The module itself
+- contains the essential components for an AngularTS application to function. The table below
 - lists a high level breakdown of each of the services/factories, filters, directives and testing
 - components available within this core module.
 - \*/
@@ -18,7 +18,7 @@
 - @name ngApp
 -
 - @element ANY
-- @param {import('./types.js').Module} ngApp an optional application
+- @param {import('./interface.ts').Module} ngApp an optional application
 - {@link angular.module module} name to load.
 - @param {boolean=} ngStrictDi if this attribute is present on the app element, the injector will be
 - created in "strict-di" mode. This means that the application will fail to invoke functions which
@@ -28,23 +28,23 @@
 -
 - @description
 -
-- Use this directive to **auto-bootstrap** an AngularJS application. The `ngApp` directive
+- Use this directive to **auto-bootstrap** an AngularTS application. The `ngApp` directive
 - designates the **root element** of the application and is typically placed near the root element
 - of the page - e.g. on the `<body>` or `<html>` tags.
 -
 - There are a few things to keep in mind when using `ngApp`:
-- - only one AngularJS application can be auto-bootstrapped per HTML document. The first `ngApp`
+- - only one AngularTS application can be auto-bootstrapped per HTML document. The first `ngApp`
 - found in the document will be used to define the root element to auto-bootstrap as an
 - application. To run multiple applications in an HTML document you must manually bootstrap them using
 - {@link angular.bootstrap} instead.
-- - AngularJS applications cannot be nested within each other.
+- - AngularTS applications cannot be nested within each other.
 - - Do not use a directive that uses {@link ng.$compile#transclusion transclusion} on the same element as `ngApp`.
 - This includes directives such as {@link ng.ngIf `ngIf`}, {@link ng.ngInclude `ngInclude`} and
 - {@link ngRoute.ngView `ngView`}.
 - Doing this misplaces the app {@link ng.$rootElement `$rootElement`} and the app's {@link auto.$injector injector},
 - causing animations to stop working and making the injector inaccessible from outside the app.
 -
-- You can specify an **AngularJS module** to be used as the root module for the application. This
+- You can specify an **AngularTS module** to be used as the root module for the application. This
 - module will be loaded into the {@link auto.$injector} when the application is bootstrapped. It
 - should contain the application code needed or have dependencies on other modules that will
 - contain the code. See {@link angular.module} for more information.

package/src/public.js

@@ -1,3 +1,4 @@
+// @private
 import { CompileProvider } from "./core/compile/compile.js";
 import {
   inputDirective,
@@ -107,7 +108,7 @@ import { AnimateJsDriverProvider } from "./animations/animate-js-driver.js";
 import { ngAnimateSwapDirective } from "./animations/animate-swap.js";
 import { $$AnimateChildrenDirective } from "./animations/animate-children-directive.js";
 import { UrlConfigProvider } from "./router/url/url-config.js";
-import { UIRouterGlobals } from "./router/globals.js";
+import { RouterGlobals } from "./router/globals.js";
 import { ViewService } from "./router/view/view.js";
 import { TransitionProvider } from "./router/transition/transition-service.js";
 import { StateProvider } from "./router/state/state-service.js";
@@ -127,16 +128,14 @@ import {
 } from "./router/directives/view-directive.js";
 import { ngChannelDirective } from "./directive/channel/channel.js";
 import { ngSetterDirective } from "./directive/setter/setter.js";
+import { PubSubProvider } from "./core/pubsub/pubsub.js";
 
-/**
- * @type {string} `version` from `package.json`, injected by Rollup plugin
- */
 export const VERSION = "[VI]{version}[/VI]";
 
 /**
- * Initializes `ng`, `animate`, `message`, `aria` and `router` modules.
- * @param {import('./loader').Angular} angular
- * @returns {import('./types.js').Module} `ng`module
+ * Initializes core `ng` module.
+ * @param {import('./loader.js').Angular} angular
+ * @returns {import('./core/di/ng-module.js').NgModule} `ng` module
  */
 export function publishExternalAPI(angular) {
   const ng = angular
@@ -145,6 +144,7 @@ export function publishExternalAPI(angular) {
       [],
       [
         "$provide",
+        /** @type {import('./interface.js').Provider} */
         ($provide) => {
           // $$sanitizeUriProvider needs to be before $compileProvider as it is used by it.
           $provide.provider({
@@ -254,7 +254,7 @@ export function publishExternalAPI(angular) {
             $parse: ParseProvider,
             $$rAFScheduler: RafSchedulerProvider,
             $rootScope: RootScopeProvider,
-            $routerGlobals: UIRouterGlobals,
+            $routerGlobals: RouterGlobals,
             $sce: SceProvider,
             $sceDelegate: SceDelegateProvider,
             $$taskTrackerFactory: TaskTrackerFactoryProvider,
@@ -268,12 +268,17 @@ export function publishExternalAPI(angular) {
             $templateFactory: TemplateFactoryProvider,
             $urlService: UrlService,
             $stateRegistry: StateRegistryProvider,
+            $eventBus: PubSubProvider,
           });
         },
       ],
     )
     .factory("$stateParams", [
       "$routerGlobals",
+      /**
+       * @param {import('./router/globals.js').RouterGlobals} globals
+       * @returns {import('./router/params/state-params.js').StateParams }
+       */
       function (globals) {
         return globals.params;
       },

package/src/public.spec.js

@@ -9,6 +9,7 @@ describe("public", () => {
   it("sets up the angular object and the module loader", () => {
     expect(window.angular).toBeDefined();
     expect(window.angular.module).toBeDefined();
+    expect(window.angular.$injectTokens).toBeDefined();
   });
 
   it("sets up the ng module", () => {

package/src/router/common/{glob.html → common.html}

@@ -12,6 +12,7 @@
     <script src="/jasmine/boot0.js"></script>
     <script src="/jasmine/boot1.js"></script>
     <script type="module" src="/src/router/common/glob.spec.js"></script>
+    <script type="module" src="/src/router/common/queue.spec.js"></script>
   </head>
   <body>
     <div id="app"></div>

package/src/router/common/{glob.test.js → common.test.js}

@@ -1,6 +1,6 @@
 import { test, expect } from "@playwright/test";
 
-const TEST_URL = "src/router/common/glob.html";
+const TEST_URL = "src/router/common/common.html";
 
 test("unit tests contain no errors", async ({ page }) => {
   await page.goto(TEST_URL);

package/src/router/common/glob.js

@@ -45,20 +45,30 @@
  * | `'**.X'`    | `'X'` , `'A.X'` , `'Z.Y.X'`                   | `'A'` , `'A.login.Z'`             |
  * | `'A.**.X'`  | `'A.X'` , `'A.B.X'` , `'A.B.C.X'`             | `'A'` , `'A.B.C'`                 |
  *
- * @packageDocumentation
  */
 export class Glob {
-  /** Returns true if the string has glob-like characters in it */
-  static is(text) {
-    return !!/[!,*]+/.exec(text);
-  }
-  /** Returns a glob from the string, or null if the string isn't Glob-like */
+  /** Returns a glob from the string, or null if the string isn't Glob-like
+   * @param {string} text
+   * @returns {?Glob}
+   */
   static fromString(text) {
-    return Glob.is(text) ? new Glob(text) : null;
+    return hasGlobs(text) ? new Glob(text) : null;
   }
+
+  /**
+   * @param {string} text
+   */
   constructor(text) {
+    /**
+     * @type {string}
+     */
     this.text = text;
+
+    /**
+     * @type {string[]}
+     */
     this.glob = text.split(".");
+
     const regexpString = this.text
       .split(".")
       .map((seg) => {
@@ -67,9 +77,21 @@ export class Glob {
         return "\\." + seg;
       })
       .join("");
+
+    /**
+     * @type {RegExp}
+     */
     this.regexp = new RegExp("^" + regexpString + "$");
   }
   matches(name) {
     return this.regexp.test("." + name);
   }
 }
+
+/** Returns true if the string has glob-like characters in it
+ *  @param {string} text
+ *  @returns {boolean}
+ */
+export function hasGlobs(text) {
+  return !!/[!,*]+/.exec(text);
+}