Add trustedHTML via alias/re-export of htmlSafe (#20939)

Author: NullVoxPopuli

packages/@ember/-internals/glimmer/index.ts

@@ -457,7 +457,14 @@ export {
   type FunctionBasedHelper,
   type FunctionBasedHelperInstance,
 } from './lib/helper';
-export { SafeString, htmlSafe, isHTMLSafe } from './lib/utils/string';
+export {
+  TrustedHTML,
+  SafeString,
+  trustHTML,
+  isTrustedHTML,
+  htmlSafe,
+  isHTMLSafe,
+} from './lib/utils/string';
 export { Renderer, _resetRenderers, renderSettled } from './lib/renderer';
 export {
   getTemplate,

packages/@ember/-internals/glimmer/lib/utils/string.ts

@@ -5,39 +5,39 @@
 import type { SafeString as GlimmerSafeString } from '@glimmer/runtime';
 
 /**
-  A wrapper around a string that has been marked as safe ("trusted"). **When
+  A wrapper around a string that has been marked as "trusted". **When
   rendered in HTML, Ember will not perform any escaping.**
 
   Note:
 
   1. This does not *make* the string safe; it means that some code in your
-     application has *marked* it as safe using the `htmlSafe()` function.
+     application has *marked* it as trusted using the `trustHTML()` function.
 
-  2. The only public API for getting a `SafeString` is calling `htmlSafe()`. It
+  2. The only public API for getting a `TrutsedHTML` is calling `trustHTML()`. It
      is *not* user-constructible.
 
   If a string contains user inputs or other untrusted data, you must sanitize
-  the string before using the `htmlSafe` method. Otherwise your code is
+  the string before using the `trustHTML` method. Otherwise your code is
   vulnerable to [Cross-Site Scripting][xss]. There are many open source
   sanitization libraries to choose from, both for front end and server-side
   sanitization.
 
   [xss]: https://owasp.org/www-community/attacks/DOM_Based_XSS
 
   ```javascript
-  import { htmlSafe } from '@ember/template';
+  import { trustHTML } from '@ember/template';
 
   let someTrustedOrSanitizedString = "<div>Hello!</div>"
 
-  htmlSafe(someTrustedorSanitizedString);
+  trustHTML(someTrustedorSanitizedString);
   ```
 
   @for @ember/template
-  @class SafeString
-  @since 4.12.0
+  @class TrustedHTML
+  @since 6.7.0
   @public
  */
-export class SafeString implements GlimmerSafeString {
+export class TrustedHTML implements GlimmerSafeString {
   private readonly __string: string;
 
   constructor(string: string) {
@@ -67,6 +67,42 @@ export class SafeString implements GlimmerSafeString {
   }
 }
 
+/**
+  A wrapper around a string that has been marked as safe ("trusted"). **When
+  rendered in HTML, Ember will not perform any escaping.**
+
+  Note:
+
+  1. This does not *make* the string safe; it means that some code in your
+     application has *marked* it as safe using the `htmlSafe()` function.
+
+  2. The only public API for getting a `SafeString` is calling `htmlSafe()`. It
+     is *not* user-constructible.
+
+  If a string contains user inputs or other untrusted data, you must sanitize
+  the string before using the `htmlSafe` method. Otherwise your code is
+  vulnerable to [Cross-Site Scripting][xss]. There are many open source
+  sanitization libraries to choose from, both for front end and server-side
+  sanitization.
+
+  [xss]: https://owasp.org/www-community/attacks/DOM_Based_XSS
+
+  ```javascript
+  import { htmlSafe } from '@ember/template';
+
+  let someTrustedOrSanitizedString = "<div>Hello!</div>"
+
+  htmlSafe(someTrustedorSanitizedString);
+  ```
+
+  @for @ember/template
+  @class SafeString
+  @since 4.12.0
+  @public
+ */
+export const SafeString = TrustedHTML;
+export type SafeString = TrustedHTML;
+
 /**
   Use this method to indicate that a string should be rendered as HTML
   when the string is used in a template. To say this another way,
@@ -96,13 +132,46 @@ export class SafeString implements GlimmerSafeString {
   @return {SafeString} A string that will not be HTML escaped by Handlebars.
   @public
 */
-export function htmlSafe(str: string): SafeString {
+export const htmlSafe = trustHTML;
+
+/**
+  Use this method to indicate that a string should be rendered as HTML
+  without escaping when the string is used in a template. To say this another way,
+  strings marked with `trustHTML` will not be HTML escaped.
+
+  A word of warning -   The `trustHTML` method does not make the string safe;
+  it only tells the framework to treat the string as if it is safe to render
+  as HTML - that we trust its contents to be safe. If a string contains user inputs or other untrusted
+  data, you must sanitize the string before using the `trustHTML` method.
+  Otherwise your code is vulnerable to
+  [Cross-Site Scripting](https://owasp.org/www-community/attacks/DOM_Based_XSS).
+  There are many open source sanitization libraries to choose from,
+  both for front end and server-side sanitization.
+
+  ```glimmer-js
+  import { trustHTML } from '@ember/template';
+
+  const someTrustedOrSanitizedString = "<div>Hello!</div>"
+
+  <template>
+    {{trustHTML someTrustedOrSanitizedString}}
+  </template>
+  ```
+
+  @method trustHTML
+  @for @ember/template
+  @param str {String} The string to treat as trusted.
+  @static
+  @return {TrustedHTML} A string that will not be HTML escaped by Handlebars.
+  @public
+ */
+export function trustHTML(str: string): TrustedHTML {
   if (str === null || str === undefined) {
     str = '';
   } else if (typeof str !== 'string') {
     str = String(str);
   }
-  return new SafeString(str);
+  return new TrustedHTML(str);
 }
 
 /**
@@ -124,12 +193,33 @@ export function htmlSafe(str: string): SafeString {
   @return {Boolean} `true` if the string was decorated with `htmlSafe`, `false` otherwise.
   @public
 */
-export function isHTMLSafe(str: unknown): str is SafeString {
+export const isHTMLSafe = isTrustedHTML;
+
+/**
+  Detects if a string was decorated using `trustHTML`.
+
+  ```javascript
+  import { trustHTML, isTrustedHTML } from '@ember/template';
+
+  let plainString = 'plain string';
+  let safeString = trustHTML('<div>someValue</div>');
+
+  isTrustedHTML(plainString); // false
+  isTrustedHTML(safeString);  // true
+  ```
+
+  @method isTrustedHTML
+  @for @ember/template
+  @static
+  @return {Boolean} `true` if the string was decorated with `htmlSafe`, `false` otherwise.
+  @public
+*/
+export function isTrustedHTML(str: unknown): str is TrustedHTML {
   return (
     // SAFETY: cast `as SafeString` only present to make this check "legal"; we
     // can further improve this by changing the behavior to do an `in` check
     // instead, but that's worth landing as a separate change for bisecting if
     // it happens to have an impact on e.g. perf.
-    str !== null && typeof str === 'object' && typeof (str as SafeString).toHTML === 'function'
+    str !== null && typeof str === 'object' && typeof (str as TrustedHTML).toHTML === 'function'
   );
 }

packages/@ember/template/index.ts

@@ -1,3 +1,10 @@
 // NOTE: this intentionally *only* exports the *type* `SafeString`, not its
 // value, since it should not be constructed by users.
-export { htmlSafe, isHTMLSafe, type SafeString } from '@ember/-internals/glimmer';
+export {
+  isTrustedHTML,
+  trustHTML,
+  htmlSafe,
+  isHTMLSafe,
+  type SafeString,
+  type TrustedHTML,
+} from '@ember/-internals/glimmer';

tests/docs/expected.js

@@ -253,6 +253,7 @@ module.exports = {
     'helper',
     'helperContainer',
     'htmlSafe',
+    'trustHTML',
     'if',
     'in-element',
     'includes',
@@ -292,6 +293,7 @@ module.exports = {
     'isFactory',
     'isFulfilled',
     'isHTMLSafe',
+    'isTrustedHTML',
     'isInteractive',
     'isNone',
     'isObject',
@@ -599,6 +601,7 @@ module.exports = {
     'Service',
     'TestAdapter',
     'Transition',
+    'TrustedHTML',
     'rsvp',
   ],
   modules: [