Type improvements on SCE. Typedoc fixes

Author: tolyo

src/angular.ts

@@ -48,7 +48,9 @@ const moduleRegistry: ModuleRegistry = {};
  */
 export class Angular extends EventTarget {
   public subapps: Angular[] = [];
+  /** @internal */
   public _subapp: boolean;
+  /** @internal */
   public _bootsrappedModules: Array<string | any> = [];
 
   public $eventBus!: ng.PubSubService;

src/animations/interface.ts

@@ -40,13 +40,13 @@ export interface AnimationOptions {
   /** Optional completion callback (driver/queue dependent). */
   onDone?: () => void;
 
-  /** Internal flag: whether domOperation has fired. */
+  /** @internal Internal flag: whether domOperation has fired. */
   _domOperationFired?: boolean;
 
-  /** Internal flag: whether preparation has been performed. */
+  /** @internal Internal flag: whether preparation has been performed. */
   _prepared?: boolean;
 
-  /** Internal flag: skip preparation classes. */
+  /** @internal Internal flag: skip preparation classes. */
   _skipPreparationClasses?: boolean;
 
   /** Whether to clean up styles after animation completes. */
@@ -117,7 +117,7 @@ export interface AnimationOptions {
  * `end()` forces completion (may be synchronous depending on driver).
  */
 export interface Animator {
-  /** Whether this handle is expected to perform a real animation. */
+  /** @internal Whether this handle is expected to perform a real animation. */
   _willAnimate: boolean;
 
   /** Start the animation and return a runner you can control/cancel. */

src/animations/runner/animate-runner.ts

@@ -85,10 +85,15 @@ function schedule(fn: VoidFunction): void {
 }
 
 export class AnimateRunner {
+  /** @internal */
   _host: AnimationHost;
+  /** @internal */
   _doneCallbacks: Array<(ok: boolean) => void>;
+  /** @internal */
   _state: number;
+  /** @internal */
   _promise: Promise<void> | null;
+  /** @internal */
   _tick: (fn: VoidFunction) => void;
 
   /**
@@ -256,6 +261,7 @@ export class AnimateRunner {
   // ---------------------------------------------------------------------------
 
   /**
+   * @internal
    * Executes a list of runners sequentially.
    * Each must complete before the next starts.
    */
@@ -278,6 +284,7 @@ export class AnimateRunner {
   }
 
   /**
+   * @internal
    * Waits until all runners complete.
    */
   static _all(runners: AnimateRunner[], callback: (ok: boolean) => void): void {

src/core/compile/compile.ts

@@ -41,7 +41,7 @@ import {
   simpleCompare,
   trim,
 } from "../../shared/utils.ts";
-import { SCE_CONTEXTS } from "../../services/sce/sce.ts";
+import { SCE_CONTEXTS, type SceContext } from "../../services/sce/sce.ts";
 import { PREFIX_REGEXP } from "../../shared/constants.ts";
 import {
   createEventDirective,
@@ -344,7 +344,7 @@ export interface TextInterpolateLinkState {
 export interface AttrInterpolateLinkState {
   _name: string;
   _value: string;
-  _trustedContext?: string;
+  _trustedContext?: SceContext;
   _allOrNothing: boolean;
   _interpolateFn?: InterpolationFunction;
 }
@@ -910,7 +910,14 @@ export class CompileProvider {
     /**
      * The security context of DOM Properties.
      */
-    const PROP_CONTEXTS = nullObject() as Record<string, string>;
+    const PROP_CONTEXTS = nullObject() as Record<string, SceContext>;
+
+    const LEGACY_SCE_CONTEXTS: Record<string, SceContext> = {
+      html: SCE_CONTEXTS._HTML,
+      mediaUrl: SCE_CONTEXTS._MEDIA_URL,
+      resourceUrl: SCE_CONTEXTS._RESOURCE_URL,
+      url: SCE_CONTEXTS._URL,
+    };
 
     /**
      * Defines the security context for DOM properties bound by ng-prop-*.
@@ -925,20 +932,22 @@ export class CompileProvider {
       propertyName: string,
       ctx: string,
     ) {
+      const normalizedCtx = LEGACY_SCE_CONTEXTS[ctx] || ctx;
+
       const key = `${elementName.toLowerCase()}|${propertyName.toLowerCase()}`;
 
-      if (key in PROP_CONTEXTS && PROP_CONTEXTS[key] !== ctx) {
+      if (key in PROP_CONTEXTS && PROP_CONTEXTS[key] !== normalizedCtx) {
         throw $compileMinErr(
           "ctxoverride",
           "Property context '{0}.{1}' already set to '{2}', cannot override to '{3}'.",
           elementName,
           propertyName,
           PROP_CONTEXTS[key],
-          ctx,
+          normalizedCtx,
         );
       }
 
-      PROP_CONTEXTS[key] = ctx;
+      PROP_CONTEXTS[key] = normalizedCtx as SceContext;
 
       return this;
     };
@@ -953,18 +962,18 @@ export class CompileProvider {
      */
     (function registerNativePropertyContexts() {
       /** Registers the same security context for a list of `element|property` keys. */
-      function registerContext(ctx: string, items: string[]) {
+      function registerContext(ctx: SceContext, items: string[]) {
         items.forEach((v) => {
           PROP_CONTEXTS[v.toLowerCase()] = ctx;
         });
       }
 
-      registerContext(SCE_CONTEXTS.HTML, [
+      registerContext(SCE_CONTEXTS._HTML, [
         "iframe|srcdoc",
         "*|innerHTML",
         "*|outerHTML",
       ]);
-      registerContext(SCE_CONTEXTS.URL, [
+      registerContext(SCE_CONTEXTS._URL, [
         "area|href",
         "area|ping",
         "a|href",
@@ -976,7 +985,7 @@ export class CompileProvider {
         "ins|cite",
         "q|cite",
       ]);
-      registerContext(SCE_CONTEXTS.MEDIA_URL, [
+      registerContext(SCE_CONTEXTS._MEDIA_URL, [
         "audio|src",
         "img|src",
         "img|srcset",
@@ -986,7 +995,7 @@ export class CompileProvider {
         "video|src",
         "video|poster",
       ]);
-      registerContext(SCE_CONTEXTS.RESOURCE_URL, [
+      registerContext(SCE_CONTEXTS._RESOURCE_URL, [
         "*|formAction",
         "applet|code",
         "applet|codebase",
@@ -3490,9 +3499,9 @@ export class CompileProvider {
         function getTrustedAttrContext(
           nodeName: string,
           attrNormalizedName: string,
-        ) {
+        ): SceContext | undefined {
           if (attrNormalizedName === "srcdoc") {
-            return $sce.HTML;
+            return SCE_CONTEXTS._HTML;
           }
 
           // All nodes with src attributes require a RESOURCE_URL value, except for
@@ -3502,30 +3511,30 @@ export class CompileProvider {
               ["img", "video", "audio", "source", "track"].indexOf(nodeName) ===
               -1
             ) {
-              return $sce.RESOURCE_URL;
+              return SCE_CONTEXTS._RESOURCE_URL;
             }
 
-            return $sce.MEDIA_URL;
+            return SCE_CONTEXTS._MEDIA_URL;
           }
 
           if (attrNormalizedName === "xlinkHref") {
             // Some xlink:href are okay, most aren't
             if (nodeName === "image") {
-              return $sce.MEDIA_URL;
+              return SCE_CONTEXTS._MEDIA_URL;
             }
 
             if (nodeName === "a") {
-              return $sce.URL;
+              return SCE_CONTEXTS._URL;
             }
 
-            return $sce.RESOURCE_URL;
+            return SCE_CONTEXTS._RESOURCE_URL;
           }
 
           if (
             nodeName === "image" &&
             (attrNormalizedName === "href" || attrNormalizedName === "ngHref")
           ) {
-            return $sce.MEDIA_URL;
+            return SCE_CONTEXTS._MEDIA_URL;
           }
 
           if (
@@ -3537,14 +3546,14 @@ export class CompileProvider {
             // links can be stylesheets or imports, which can run script in the current origin
             (nodeName === "link" && attrNormalizedName === "href")
           ) {
-            return $sce.RESOURCE_URL;
+            return SCE_CONTEXTS._RESOURCE_URL;
           }
 
           if (
             nodeName === "a" &&
             (attrNormalizedName === "href" || attrNormalizedName === "ngHref")
           ) {
-            return $sce.URL;
+            return SCE_CONTEXTS._URL;
           }
 
           return undefined;
@@ -3554,7 +3563,7 @@ export class CompileProvider {
         function getTrustedPropContext(
           nodeName: string,
           propNormalizedName: string,
-        ) {
+        ): SceContext | undefined {
           const prop = propNormalizedName.toLowerCase();
 
           return (

src/core/di/internal-injector.ts

@@ -19,9 +19,12 @@ const INSTANTIATING = true;
 type InjectableFn = Function | AnnotatedFactory<(...args: any[]) => any>;
 
 class AbstractInjector {
+  /** @internal */
   _cache: Record<string, any>;
   strictDi: boolean;
+  /** @internal */
   _path: string[];
+  /** @internal */
   _modules: Record<string, NgModule>;
 
   /**
@@ -68,6 +71,7 @@ class AbstractInjector {
   }
 
   /**
+   * @internal
    * Get the injection arguments for a function.
    *
    * @param {Function|ng.AnnotatedFactory<any>} fn
@@ -179,6 +183,7 @@ class AbstractInjector {
    * @returns {any}
    */
 
+  /** @internal */
   _factory(serviceName: string): any {
     void serviceName;
 
@@ -200,6 +205,7 @@ export class ProviderInjector extends AbstractInjector {
   }
 
   /**
+   * @internal
    * Factory method for creating services.
    * @param {string} caller - The name of the caller requesting the service.
    * @throws {Error} If the provider is unknown.
@@ -225,6 +231,7 @@ export class InjectorService extends AbstractInjector {
     /* empty */
   };
 
+  /** @internal */
   _providerInjector: ProviderInjector;
 
   /**
@@ -244,6 +251,7 @@ export class InjectorService extends AbstractInjector {
    * @param {string} serviceName
    * @returns {*}
    */
+  /** @internal */
   _factory(serviceName: string): any {
     const provider = this._providerInjector.get(serviceName + providerSuffix);
 

src/core/filter/filter.ts

@@ -16,6 +16,7 @@ const SUFFIX = "Filter";
 export class FilterProvider {
   static $inject = [$t._provide];
 
+  /** @internal */
   _$provide: Provider;
   $get: [string, ($injector: ng.InjectorService) => FilterService];
 

src/core/interpolate/interpolate.spec.js

@@ -1,6 +1,7 @@
 import { createInjector } from "../di/injector.ts";
 import { Angular } from "../../angular.ts";
 import { wait } from "../../shared/test-utils.ts";
+import { SCE_CONTEXTS } from "../../services/sce/sce.ts";
 
 describe("$interpolate", () => {
   let $interpolate, $injector, $rootScope, $sce;
@@ -384,7 +385,7 @@ describe("$interpolate", () => {
       const scope = $rootScope.$new();
       scope.foo = "foo";
       await wait();
-      $interpolate("{{foo}}", true, sce.HTML)(scope);
+      $interpolate("{{foo}}", true, SCE_CONTEXTS._HTML)(scope);
       expect(errors[0]).toMatch("unsafe value");
     });
 
@@ -395,7 +396,9 @@ describe("$interpolate", () => {
 
     it("should interpolate trusted expressions in a specific trustedContext", () => {
       const foo = sce.trustAsHtml("foo");
-      expect($interpolate("{{foo}}", true, sce.HTML)({ foo })).toBe("foo");
+      expect($interpolate("{{foo}}", true, SCE_CONTEXTS._HTML)({ foo })).toBe(
+        "foo",
+      );
     });
 
     // The concatenation of trusted values does not necessarily result in a trusted value.  (For
@@ -405,7 +408,7 @@ describe("$interpolate", () => {
       const foo = sce.trustAsHtml("foo");
       const bar = sce.trustAsHtml("bar");
       expect(() =>
-        $interpolate("{{foo}}{{bar}}", true, sce.HTML)({ foo, bar }),
+        $interpolate("{{foo}}{{bar}}", true, SCE_CONTEXTS._HTML)({ foo, bar }),
       ).toThrowError(/Error while interpolating/);
     });
   });
@@ -491,7 +494,7 @@ describe("$interpolate", () => {
 
   describe("isTrustedContext", () => {
     it("should NOT interpolate a multi-part expression when isTrustedContext is RESOURCE_URL", () => {
-      const isTrustedContext = $sce.RESOURCE_URL;
+      const isTrustedContext = SCE_CONTEXTS._RESOURCE_URL;
       expect(() => {
         $interpolate("constant/{{var}}", true, isTrustedContext)("val");
       }).toThrowError(/Can't interpolate:/);
@@ -510,25 +513,42 @@ describe("$interpolate", () => {
     });
 
     it("should interpolate a multi-part expression when isTrustedContext is URL", () => {
-      expect($interpolate("some/{{id}}", true, $sce.URL)({})).toEqual("some/");
-      expect($interpolate("some/{{id}}", true, $sce.URL)({ id: 1 })).toEqual(
-        "some/1",
+      expect($interpolate("some/{{id}}", true, SCE_CONTEXTS._URL)({})).toEqual(
+        "some/",
       );
       expect(
-        $interpolate("{{foo}}{{bar}}", true, $sce.URL)({ foo: 1, bar: 2 }),
+        $interpolate("some/{{id}}", true, SCE_CONTEXTS._URL)({ id: 1 }),
+      ).toEqual("some/1");
+      expect(
+        $interpolate(
+          "{{foo}}{{bar}}",
+          true,
+          SCE_CONTEXTS._URL,
+        )({
+          foo: 1,
+          bar: 2,
+        }),
       ).toEqual("12");
     });
 
     it("should interpolate and sanitize a multi-part expression when isTrustedContext is URL", () => {
-      expect($interpolate("some/{{id}}", true, $sce.URL)({})).toEqual("some/");
+      expect($interpolate("some/{{id}}", true, SCE_CONTEXTS._URL)({})).toEqual(
+        "some/",
+      );
       expect(
-        $interpolate("some/{{id}}", true, $sce.URL)({ id: "javascript:" }),
+        $interpolate(
+          "some/{{id}}",
+          true,
+          SCE_CONTEXTS._URL,
+        )({
+          id: "javascript:",
+        }),
       ).toEqual("some/javascript:");
       expect(
         $interpolate(
           "{{foo}}{{bar}}",
           true,
-          $sce.URL,
+          SCE_CONTEXTS._URL,
         )({ foo: "javascript:", bar: "javascript:" }),
       ).toEqual("unsafe:javascript:javascript:");
     });