Add MacroComponent directives and Root Tag Attribute

Supersedes #4116.

Co-Authored-By: David Green <134172184+green-david@users.noreply.github.com>

Author: SteffenDE

lib/phoenix_component/macro_component.ex

@@ -120,6 +120,29 @@ defmodule Phoenix.Component.MacroComponent do
   #   LiveView's end to end tests: a macro component that performs
   #   [syntax highlighting at compile time](https://github.com/phoenixframework/phoenix_live_view/blob/38851d943f3280c5982d75679291dccb8c442534/test/e2e/support/colocated_live.ex#L4-L35)
   #   using the [Makeup](https://hexdocs.pm/makeup/Makeup.html) library.
+  #
+  #   ## Directives
+  #
+  #   Macro components may return directives from `transform/2` which can be used to influence
+  #   other elements in the template outside of the macro component at compile-time. For example:
+  #
+  #   ```elixir
+  #   defmodule MyAppWeb.TagRootSampleComponent do
+  #     @behaviour Phoenix.Component.MacroComponent
+  #
+  #     @impl true
+  #     def transform(_ast, _meta) do
+  #       {:ok, "", %{}, [root_tag_annotation: "test1", root_tag_annotation: "test2"]}
+  #     end
+  #   end
+  #   ```
+  #
+  #   The following directives are currently supported:
+  #
+  #   * `:root_tag_annotation` - A value to apply as an annotation to all root tags during template compilation.
+  #     Requires that a `:root_tag_annotation` is configured for the application. The value must be a string.
+  #     May be provided multiple times to apply multiple annotations.
+  #
 
   @type tag :: binary()
   @type attribute :: {binary(), Macro.t()}
@@ -128,9 +151,13 @@ defmodule Phoenix.Component.MacroComponent do
   @type tag_meta :: %{closing: :self | :void}
   @type heex_ast :: {tag(), attributes(), children(), tag_meta()} | binary()
   @type transform_meta :: %{env: Macro.Env.t()}
+  @type directive :: {:root_tag_annotation, String.t()}
+  @type directives :: [directive]
 
   @callback transform(heex_ast :: heex_ast(), meta :: transform_meta()) ::
-              {:ok, heex_ast()} | {:ok, heex_ast(), data :: term()}
+              {:ok, heex_ast()}
+              | {:ok, heex_ast(), data :: term()}
+              | {:ok, heex_ast(), data :: term(), directives :: directives()}
 
   @doc """
   Returns the stored data from macro components that returned `{:ok, ast, data}`.

lib/phoenix_live_view/html_formatter.ex

@@ -312,8 +312,8 @@ defmodule Phoenix.LiveView.HTMLFormatter do
           process_buffer: &process_buffer/1
         )
         |> case do
-          {:ok, nodes} ->
-            nodes
+          {:ok, result} ->
+            result.nodes
             |> transform_tree(source, newlines)
             |> HTMLAlgebra.build(opts)
             |> Inspect.Algebra.format(line_length)

lib/phoenix_live_view/tag_engine/compiler.ex

@@ -1,6 +1,7 @@
 defmodule Phoenix.LiveView.TagEngine.Compiler do
   @moduledoc false
 
+  alias Phoenix.LiveView.TagEngine.ParseResult
   alias Phoenix.LiveView.TagEngine.Tokenizer.ParseError
 
   @doc """
@@ -15,7 +16,7 @@ defmodule Phoenix.LiveView.TagEngine.Compiler do
   text and expression parts and properly invoking the engine
   with the correct code for features like components and slots.
   """
-  def compile(nodes, opts) do
+  def compile(%ParseResult{nodes: nodes, directives: directives}, opts) do
     {engine, opts} = Keyword.pop(opts, :engine, Phoenix.LiveView.Engine)
     tag_handler = Keyword.fetch!(opts, :tag_handler)
 
@@ -26,8 +27,11 @@ defmodule Phoenix.LiveView.TagEngine.Compiler do
       caller: Keyword.fetch!(opts, :caller),
       source: Keyword.fetch!(opts, :source),
       tag_handler: tag_handler,
-      # slots is the only key that is updated when traversing nodes
-      slots: []
+      root_tag_attribute: Application.get_env(:phoenix_live_view, :root_tag_attribute, false),
+      root_tag_attributes: Keyword.get_values(directives, :root_tag_attribute),
+      # The following keys are updated when traversing nodes
+      slots: [],
+      local_root?: true
     }
 
     # Live components require a single, static root tag.
@@ -328,7 +332,7 @@ defmodule Phoenix.LiveView.TagEngine.Compiler do
 
     with_special_attrs(attrs, meta, substate, state, fn attrs, meta, substate, state ->
       substate = handle_tag_and_attrs(name, attrs, ">", to_location(meta), substate, state)
-      {_child_state, substate} = handle_node(children, substate, state)
+      {_child_state, substate} = handle_node(children, substate, %{state | local_root?: false})
       substate = state.engine.handle_text(substate, [to_location(close_meta)], "</#{name}>")
       {state, substate}
     end)
@@ -353,7 +357,7 @@ defmodule Phoenix.LiveView.TagEngine.Compiler do
         meta,
         close_meta,
         substate,
-        state
+        %{state | local_root?: true}
       )
 
     ast =
@@ -383,7 +387,10 @@ defmodule Phoenix.LiveView.TagEngine.Compiler do
 
     with_special_attrs(attrs, meta, substate, state, fn attrs, meta, substate, state ->
       {assigns, attr_info, slot_info} =
-        build_component_assigns(ref, attrs, children, meta, close_meta, substate, state)
+        build_component_assigns(ref, attrs, children, meta, close_meta, substate, %{
+          state
+          | local_root?: true
+        })
 
       store_component_call({mod, fun}, attr_info, slot_info, line, state)
       call_meta = [line: line, column: column]
@@ -420,7 +427,10 @@ defmodule Phoenix.LiveView.TagEngine.Compiler do
     with_special_attrs(attrs, meta, substate, state, fn attrs, meta, substate, state ->
       # Process children in a new nesting
       {assigns, attr_info, slot_info} =
-        build_component_assigns(ref, attrs, children, meta, close_meta, substate, state)
+        build_component_assigns(ref, attrs, children, meta, close_meta, substate, %{
+          state
+          | local_root?: true
+        })
 
       store_component_call({mod, fun}, attr_info, slot_info, line, state)
       call_meta = [line: line, column: column + mod_size]
@@ -479,17 +489,41 @@ defmodule Phoenix.LiveView.TagEngine.Compiler do
 
   defp handle_tag_and_attrs(name, attrs, suffix, meta, substate, state) do
     text =
-      if debug_attributes?(state.caller) do
-        "<#{name} data-phx-loc=\"#{meta[:line]}\""
-      else
-        "<#{name}"
-      end
+      "<#{name}"
+      |> maybe_add_phx_loc(state, meta)
+      |> maybe_add_root_tag_attributes(state, meta)
 
     substate = state.engine.handle_text(substate, meta, text)
     substate = handle_tag_attrs(meta, attrs, substate, state)
     state.engine.handle_text(substate, meta, suffix)
   end
 
+  defp maybe_add_phx_loc(text, %{caller: caller}, meta) do
+    if debug_attributes?(caller) do
+      "#{text} data-phx-loc=\"#{meta[:line]}\""
+    else
+      text
+    end
+  end
+
+  defp maybe_add_root_tag_attributes(text, %{local_root?: true} = state, _meta) do
+    case state do
+      %{root_tag_attribute: root_tag_attribute} when is_binary(root_tag_attribute) ->
+        attrs =
+          [{root_tag_attribute, true} | state.root_tag_attributes]
+          |> Phoenix.HTML.attributes_escape()
+          |> Phoenix.HTML.safe_to_string()
+
+        # Phoenix.HTML.attributes_escape/1 adds a leading space automatically
+        "#{text}#{attrs}"
+
+      %{root_tag_attribute: _} ->
+        text
+    end
+  end
+
+  defp maybe_add_root_tag_attributes(text, _state, _meta), do: text
+
   defp handle_tag_attrs(meta, attrs, substate, state) do
     Enum.reduce(attrs, substate, fn
       {:root, {:expr, _, _} = expr, _attr_meta}, substate ->

lib/phoenix_live_view/tag_engine/parser.ex

@@ -2,6 +2,7 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
   @moduledoc false
 
   alias Phoenix.LiveView.TagEngine.Tokenizer
+  alias Phoenix.LiveView.TagEngine.ParseResult
   alias Phoenix.Component.MacroComponent
 
   defguardp is_tag_open(tag_type) when tag_type not in [:close, :eex]
@@ -30,7 +31,8 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
       caller: caller,
       skip_macro_components: skip_macro_components,
       prune_text_after_slots: prune_text_after_slots,
-      process_buffer: process_buffer
+      process_buffer: process_buffer,
+      directives: []
     })
   catch
     {:syntax_error, line, column, message} ->
@@ -233,8 +235,8 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
   #    ], %{line: 0, column: 0, opt: '='}}
   # ]
   # ```
-  defp to_tree([], buffer, [], _state) do
-    {:ok, Enum.reverse(buffer)}
+  defp to_tree([], buffer, [], state) do
+    {:ok, %ParseResult{nodes: Enum.reverse(buffer), directives: state.directives}}
   end
 
   defp to_tree(
@@ -269,7 +271,7 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
        when parent_type in [:local_component, :remote_component] do
     meta = meta |> Map.put(:special, extract_special_attrs(attrs)) |> maybe_macro_component(attrs)
 
-    {tokens, buffer} =
+    {tokens, buffer, state} =
       maybe_process_macro_component(
         {:self_close, :slot, name, attrs, meta},
         tokens,
@@ -331,7 +333,7 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
        when is_tag_open(type) do
     meta = meta |> Map.put(:special, extract_special_attrs(attrs)) |> maybe_macro_component(attrs)
 
-    {tokens, buffer} =
+    {tokens, buffer, state} =
       maybe_process_macro_component({:self_close, type, name, attrs, meta}, tokens, buffer, state)
 
     to_tree(tokens, buffer, stack, state)
@@ -353,7 +355,7 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
        ) do
     block = Enum.reverse(reversed_buffer)
 
-    {tokens, buffer} =
+    {tokens, buffer, state} =
       maybe_process_macro_component(
         {:block, type, name, attrs, block, open_meta, close_meta},
         tokens,
@@ -522,9 +524,19 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
 
   defp maybe_process_macro_component(tree_node, tokens, buffer, state)
        when is_macro_component(tree_node) and not skip_macro_components(state) do
-    # Remove :type from attrs for the macro component AST
+    caller = state.caller
+
+    if is_nil(caller) do
+      raise ArgumentError, "macro components require a caller environment"
+    end
+
+    Macro.Env.required?(caller, Phoenix.Component) ||
+      raise ArgumentError,
+            "macro components are only supported in modules that `use Phoenix.Component`"
+
     tree_node =
       case tree_node do
+        # Remove :type from attrs for the macro component AST
         {:self_close, :tag, name, attrs, meta} ->
           {:self_close, :tag, name, List.keydelete(attrs, ":type", 0), meta}
 
@@ -545,54 +557,57 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
           )
       end
 
-    case process_macro_component(tree_node, state) do
-      {:text, "", _} ->
-        {strip_text(tokens), buffer}
+    meta = get_meta(tree_node)
+    module_string = meta.macro_component
+    module = validate_module!(module_string, meta, state)
+
+    case process_macro_component(tree_node, module, state) do
+      {_new_node, directives} when directives != [] and buffer != [] ->
+        throw_syntax_error!(
+          "macro component #{inspect(module)} specified directives and therefore must appear at the very beginning of the template",
+          get_meta(tree_node)
+        )
+
+      {{:text, "", _}, directives} ->
+        {strip_text(tokens), buffer, %{state | directives: directives}}
 
-      new_node ->
-        {strip_text(tokens), [new_node | buffer]}
+      {new_node, directives} ->
+        {strip_text(tokens), [new_node | buffer], %{state | directives: directives}}
     end
   end
 
-  defp maybe_process_macro_component(tree_node, tokens, buffer, _state) do
-    {tokens, [tree_node | buffer]}
+  defp maybe_process_macro_component(tree_node, tokens, buffer, state) do
+    {tokens, [tree_node | buffer], state}
   end
 
   # Process a macro component: call transform and convert result back to tree nodes
-  defp process_macro_component(tree_node, state) do
+  defp process_macro_component(tree_node, module, state) do
     # Macro components work by converting the tree nodes into a macro AST
     # (see Phoenix.Component.MacroComponent) and then calling the transform
     # function on the macro component module, which can return a transformed
     # AST.
     #
     # The AST is limited in functionality and we convert it back to the regular
     # node format afterwards.
-    caller = state.caller
-
-    if is_nil(caller) do
-      raise ArgumentError, "macro components require a caller environment"
-    end
-
-    Macro.Env.required?(caller, Phoenix.Component) ||
-      raise ArgumentError,
-            "macro components are only supported in modules that `use Phoenix.Component`"
-
     meta = get_meta(tree_node)
-    module_string = meta.macro_component
-    module = validate_module!(module_string, meta, state)
 
-    # Build the macro component AST
-    case MacroComponent.build_ast(tree_node, caller) do
+    case MacroComponent.build_ast(tree_node, state.caller) do
       {:ok, macro_ast} ->
         try do
           # Call the transform function
-          case module.transform(macro_ast, %{env: caller}) do
+          case module.transform(macro_ast, %{env: state.caller}) do
             {:ok, new_ast} ->
-              MacroComponent.ast_to_tree(new_ast, meta)
+              {MacroComponent.ast_to_tree(new_ast, meta), []}
 
             {:ok, new_ast, data} ->
-              Module.put_attribute(caller.module, :__macro_components__, {module, data})
-              MacroComponent.ast_to_tree(new_ast, meta)
+              Module.put_attribute(state.caller.module, :__macro_components__, {module, data})
+              {MacroComponent.ast_to_tree(new_ast, meta), []}
+
+            {:ok, new_ast, data, directives} ->
+              Module.put_attribute(state.caller.module, :__macro_components__, {module, data})
+
+              {MacroComponent.ast_to_tree(new_ast, meta),
+               validate_directives!(module, directives, meta)}
 
             other ->
               throw_syntax_error!(
@@ -641,6 +656,60 @@ defmodule Phoenix.LiveView.TagEngine.Parser do
     module
   end
 
+  defp validate_directives!(module, directives, meta) do
+    Enum.each(directives, fn {key, value} ->
+      validate_directive!(module, key, value, meta)
+    end)
+
+    directives
+  end
+
+  defp validate_directive!(_module, :root_tag_attribute, nil, _), do: :ok
+
+  defp validate_directive!(module, :root_tag_attribute, {name, value}, meta)
+       when is_binary(name) and (is_binary(value) or value == true) do
+    configured_attribute = Application.get_env(:phoenix_live_view, :root_tag_attribute)
+
+    if !configured_attribute do
+      message = """
+      a global :root_tag_attribute must be configured for macro components to use the :root_tag_attribute directive
+
+      Macro Component: #{inspect(module)}
+
+      Expected global :root_tag_attribute to be a string, got: #{inspect(configured_attribute)}
+
+      The global :root_tag_attribute is typically used for `Phoenix.LiveView.ColocatedCSS` and
+      is usually configured to `"phx-r"`, but it needs to be explicitly enabled in your configuration:
+
+          config :phoenix_live_view, root_tag_attribute: "phx-r"
+
+      You can also use a different value than `"phx-r"`.
+      """
+
+      throw_syntax_error!(message, meta)
+    else
+      :ok
+    end
+  end
+
+  defp validate_directive!(module, :root_tag_attribute, other, meta) do
+    throw_syntax_error!(
+      """
+      expected {name, value} for :root_tag_attribute directive from macro component #{inspect(module)}, got: #{inspect(other)}
+
+      name must be a compile-time string, and value must be a compile-time string or true
+      """,
+      meta
+    )
+  end
+
+  defp validate_directive!(module, directive, value, meta) do
+    throw_syntax_error!(
+      "unknown directive #{inspect({directive, value})} provided by macro component #{inspect(module)}",
+      meta
+    )
+  end
+
   defp throw_syntax_error!(message, meta) do
     throw({:syntax_error, meta.line, meta.column, message})
   end