Whitespace handling for `<template>` tag

[chancancode]

#779 does not specify the whitespace handling semantics for <template> tag, as a result the current implementation leaves all the whitespace intact as they appear in the source code. This causes several refactoring hazards:

1. when migrating from .hbs the indentation level likely will change, since <template> is typically nested inside a class, and even for template-only component, the content is customarily indented after the opening <template> tag
2. when refactoring code, say, nesting things inside an if statement, it changes the indentation level thus the amount of whitespace inside the template tag

It appears that there are broad consensus that this is a problem, and at a minimum, we need to strip the leading indentation.

However, I would like to go a step further, and consider taking the opportunity and collapsing whitespaces by default.

The reason we care about preserving whitespace is for HTML compatibility. The guiding principle for Ember template is that "things that look like HTML should behave like HTML", however, I am not sure if in this particular case it is worth it. Generally, the browser collapses whitespace so it rarely matters, but in the cases where it does, I think the extra leading indentation from the <template> tag will make things too finicky/confusing to rely on whether we strip leading indention or not.

Since the <template> tag makes it easy to access the JavaScript scope, a more reliable and more readable thing to do, IMO, would be to do this in JavaScript:

import { action } from "@ember/object";
import Component from "@glimmer/component";
import { stripIndent } from "common-tags"

const STATIC_EXAMPLE = stripIndent`
  function greeting() {
    console.log(
      "hello, world!"
    );
  }
`;

class ExampleCodeComponent {
  @action dynamicExample(defaultName = "human") {
    return stripIndent`
      function personalizedGreeting(name = ${JSON.stringify(defaultName)}) {
        console.log(
          "hello, \${name}!"
        );
      }
    `;
  }

  <template>
    <p>
      Static example:
      <pre><code>{{STATIC_EXAMPLE}}</code></pre>
    </p>
    <p>
      Dynamic example:
      <pre><code>{{this.dynamicExample @user.name}}</code></pre>
    </p>
  </template>
}

Since you can always extract any whitespace sensitive text into JavaScript, I think that is sufficient for the white-space: pre kind of use cases.

So I think we can specify that whitespace <template> has white-space: normal semantics by default – or more precisely template("...", { ... }) apply the equivalent of white-space: normal collapsing to its content by default.

In addition to the regular HTML/browser white space collapsing semantics, we have to specify:

1. what happens to the leading and trailing whitespace

   <template>
     [👈 these 👉]
   </templaet>
   

   becomes
   template("\n\x20\x20[👈 these 👉]\n\x20\x20")
2. what happens around handlebars constructs

   <template>
     [these 👉]
       {{#if this.isAdmin}}
         [👈 and these 👉]
       {{/if}}
     [👈 and these]
   </templaet>
   

   becomes
   template("\n\x20\x20[these 👉]\n\x20\x20\x20\x20{{#if this.isAdmin}}\n\x20\x20\x20\x20\x20\x20[👈 and these 👉]\n\x20\x20\x20\x20{{/if}}\n\x20\x20[👈 and these]\n")
3. the browser algorithm is supposed to be language dependent
   In languages that separate words with spaces, such as English:

   <p>
     Here is an English paragraph
     that is broken into multiple lines
     in the source code so that it can
     be more easily read and edited
     in a text editor.
   </p>
   

   ...is intended to read as (with applicable soft wrap)
   "Here is an English paragraph that is broken into multiple lines in the source code so that it can be more easily read and edited in a text editor."
   Where the chunks joined by spaces.
   On the other hand, in languages that do not separate words, such as Chinese:

   <p>
     這個段落是那麼長，
     在一行寫不行。最好
     用三行寫。
   </p>
   

   ...is intended to read as
   "這個段落是那麼長，在一行寫不行。最好用三行寫。"
   ...which is what the CSS spec recommends. However, "historically" browsers unconditionally treated \n the same as spaces, which results in this well-known broken behavior:
   "這個段落是那麼長，\x20在一行寫不行。最好\x20用三行寫。"
   This behavior is ultimately left in the spec as browser defined. In my testing today, at least on Safari and Chrome they still have the "historical" broken behavior.

So, my proposal is:

1. We .trim() the template text for maximal composability, i.e. the template content begins with and end at the first/last none-whitespace character. Invoking a component should not introduce extra whitespace by default, the caller can easily add whitespace (and typically do) on the outside as needed.
2. We don't do anything special for handlebars but continue to respect handlebars whitespace control: {{~, {{~# etc.
3. We normalize and collapse whitespaces within a line:
   1. \t is replaced by \x20,
   2. leading and trailing \x20 on the line are trimmed,
   3. multiple successive whitespace characters are replace with a single \x20.
4. We normalize line breaks:
   1. \r\n becomes \n
   2. lone \r becomes \n
   3. multiple successive \n are replaced with a single \n
5. We leave the \n alone for the browser to decide what to do

We should make it possible to overridable locally:

1. template("...", { whitespace: "collapse" | "preserve" = "collapse")
2. Something like:

   <template whitespace="collapse">...</template>
   <template whitespace="preserve">...</template>

   ..or if we are not ready to use the "attributes" space...

   // whitespace: collapse
   <template>...</template>
   
   // whitespace: preserve
   <template>...</template>

We could also consider having a way to change the global default, but it gets complicated:

1. where do you put this config?
2. is it global global, or is it scoped to the app/addon?
3. does it get propagated to the runtime compiler if present?

[NullVoxPopuli]

cp issues/982 pulls/

[simonihmig]

This makes a lot of sense!

Sorry if I'm kinda hijacking this for another use case, but it is very much related: when doing DOM-less rendering, it would be super useful to also have something like <template whitespace="none">.

A simple imaginary example of 3D rendering:

<template whitespace="none">
  <ThreeJsCanvas>
    <Mesh/>
    <PerspectiveCamera/>
    <PointLight/>
  </ThreeJsCanvas>
</template>

<ThreeJsCanvas> would render a <canvas> element and do other setup work, everything else is not rendering any DOM but causing other rendering side effects like creating objects and adding them to the scene graph (which is currently difficult due to #597, which could be solved by #975, however I'm digressing...). In this scenario, all the white space would cause empty text nodes to be created as children of <canvas>, which is completely useless.

This gets even worse when doing more dynamic and complex things with e.g. {{#if}} and {{#each}}, where Glimmer would mindlessly create and remove whitespace text nodes dynamically, all within the hot path, where you just have 16ms for all the work to get to 60fps.

Note that this is equally true for classic hbs files as well as <template> currently, but the proposal here opens up a good opportunity to get that use case nicely supported I think!

[chancancode]

I was also thinking if we should at least support something like this for the Chinese (etc) use case:

<p>
  這個段落是那麼長，\
  在一行寫不行。最好\
  用三行寫。
</p>

But it further eats into the "is it still HTML" budget... plus I am not sure what would be the rationalization for this to have no spaces at all. Perhaps whitespace="none" works good enough here also, but I'm not sure.

[chancancode]

Also pointing out that if we were to do this, it would have to be a feature in the wire-format compiler, not a feature of content-tag, since you can only do it when you have parsed (knowing what's html text content, etc). Just stripping leading indentation, on the other hand, can be done in content-tag.

[a13o]

It should be possible, knowing only the contents of a template tag, to factor out unnecessary leading whitespace. For example a template tag starting at col 8 will have content with further indented lines at, say 10, 12 for a two-space-tab. 10 spaces can be removed from all leading whitespace to normalize the indentation.

These normalized indentations can be composed when the template is compiled. E.g. you invoke a component in another template at indentation 4 (normalized) you can add 4 to that component template’s lines to respect the author’s intent.

TLDR the mental model is that template tags behave like a nested module in the source code. Similar to backtick code blocks in a markdown file, the indentation within the template tag or code block is treated separately from the indentation of the template tag or code block itself

[BoussonKarel]

+1

Stripping leading/trailing whitespace and controlling the whitespace in other places is something we definitely need.

In Firefox, when you double click a word, the span and some stuff around it gets copied to your clipboard, resulting in excess spaces in your clipboard's text/html.

Chrome copies this text differently, they don't copy this excess whitespace and put all styling of the element inline.

The result of the whitespace in <template> is also very unpredictable and not always what you'd expect. Take a look at the following examples:

Example

import RouteTemplate from 'ember-route-template';

const TextWithExcessWhitespace = <template>
  <span>
    COPYME
  </span>
</template>;

export default RouteTemplate(
  <template>
    Copy this piece here:
    <TextWithExcessWhitespace />
  </template>,
);

Output HTML:

<body class="ember-application">
    

    <script src="/assets/vendor.js"></script>
<script src="/assets/chunk.vendors-node_modules_pnpm_ember-data_adapter_5_5_0_67fcdd47b402c636eea35a6f15a33748_node_modu-856164.17b4e0940a02be846f5d.js"></script>
<script src="/assets/chunk.tmp_broccoli-35337aVFwTyFdFzNy_cache-169-webpack_bundler_ember_auto_import_webpack_app_cjs-tm-6c5c21.602cf6b671ff6e44cc5a.js"></script>
<script src="/assets/chunk.app.1ff0c2acb3a7a3d8467d.js"></script>
    <script src="/assets/test-app.js"></script>

    
  


    Copy this piece here:
    
  <span>
    COPYME
  </span>

  </body>

Results in the following clipboard (inspected using xclip in Ubuntu):

• text/html from Firefox

<meta http-equiv="content-type" content="text/html; charset=utf-8"><span>    COPYME
  </span>%

• text/plain from Firefox

 COPYME %

• text/html from Chrome

<span style="color: rgb(33, 37, 41); font-family: system-ui, -apple-system, &quot;Segoe UI&quot;, Roboto, &quot;Helvetica Neue&quot;, &quot;Noto Sans&quot;, &quot;Liberation Sans&quot;, Arial, sans-serif, &quot;Apple Color Emoji&quot;, &quot;Segoe UI Emoji&quot;, &quot;Segoe UI Symbol&quot;, &quot;Noto Color Emoji&quot;; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;">COPYME</span>% 

• text/plain from Chrome

COPYME%

(% marks the end of the clipboard entry)

As you can see this has leading and trailing whitespace around the text in Firefox.

Removing whitespace in the <span>

Changing the example component to this:

const TextWithExcessWhitespace = <template>
  <span>COPYME</span>
</template>;

Output HTML:

<body class="ember-application">
    

    <script src="/assets/vendor.js"></script>
<script src="/assets/chunk.vendors-node_modules_pnpm_ember-data_adapter_5_5_0_67fcdd47b402c636eea35a6f15a33748_node_modu-856164.17b4e0940a02be846f5d.js"></script>
<script src="/assets/chunk.tmp_broccoli-35337aVFwTyFdFzNy_cache-169-webpack_bundler_ember_auto_import_webpack_app_cjs-tm-6c5c21.602cf6b671ff6e44cc5a.js"></script>
<script src="/assets/chunk.app.1ff0c2acb3a7a3d8467d.js"></script>
    <script src="/assets/test-app.js"></script>

    
  


    Copy this piece here:
    
  <span>COPYME</span>

  </body>

• text/html in Firefox

<meta http-equiv="content-type" content="text/html; charset=utf-8">  <span>COPYME</span>%  

• text/plain in Firefox

 COPYME%  

The trailing space is gone, but there is still leading whitespace in the Firefox output, but from outside the <span> element

(% marks the end of the clipboard entry)

Removing all whitespace in this route

import RouteTemplate from 'ember-route-template';

/* prettier-ignore */
const TextWithExcessWhitespace = <template><span>COPYME</span></template>;

export default RouteTemplate(<template><TextWithExcessWhitespace /></template>);

Output HTML:

<body class="ember-application">
    

    <script src="/assets/vendor.js"></script>
<script src="/assets/chunk.vendors-node_modules_pnpm_ember-data_adapter_5_5_0_67fcdd47b402c636eea35a6f15a33748_node_modu-856164.17b4e0940a02be846f5d.js"></script>
<script src="/assets/chunk.tmp_broccoli-35337aVFwTyFdFzNy_cache-169-webpack_bundler_ember_auto_import_webpack_app_cjs-tm-6c5c21.602cf6b671ff6e44cc5a.js"></script>
<script src="/assets/chunk.app.1ff0c2acb3a7a3d8467d.js"></script>
    <script src="/assets/test-app.js"></script>

    
  

<span>COPYME</span></body>

Now you would think this has removed all whitespace from the clipboard, but it hasn't, their is still a leading space:

• text/html in Firefox

<meta http-equiv="content-type" content="text/html; charset=utf-8">


    

    
  

<span>COPYME</span>% 

• text/plain in Firefox

 COPYME%  

Leading space before the text.

[NullVoxPopuli]

made an RFC: #1121

I need to prove browser behaviors though -- if anyone has a doc off hand of how browsers handle invisible character collapsing, that'd be good.

One thing we can't do by default is to do something that would differ from browser behavior with invisible character handling.

If you need to diverge from defaults, you can implement your own template transform plugin ✨ 🎉