herb 0.10.4 → 0.11.0

data/lib/herb/engine/scoped_style/visitor.rb

@@ -0,0 +1,533 @@
+# frozen_string_literal: true
+# typed: false
+
+require "digest"
+
+require_relative "../../visitor"
+require_relative "../../visitor/experimental"
+require_relative "../../visitor/context_aware"
+require_relative "../../visitor/diagnostics"
+require_relative "channel"
+require_relative "../../visitor/context"
+
+module Herb
+  class Engine
+    module ScopedStyle
+      # Scopes a `<style scoped>` block to the markup written in the same file.
+      #
+      #     require "herb/engine/scoped_style/visitor"
+      #
+      #     Herb::Engine.new(source, filename: path, visitors: [
+      #       Herb::Engine::ScopedStyle::Visitor.new(transform: transform)
+      #     ])
+      #
+      # A file holding a scoped block is given a scope attribute, and the block's selectors are
+      # rewritten to require it. There is no single root element to write, because a file is scoped
+      # as a whole. A file with five sibling roots and a file with none behave the same way.
+      #
+      # Every element the file wrote carries the attribute, and every rule is narrowed by it. Markup the
+      # file rendered carries a scope of its own or none, so a block reaches what the file wrote and
+      # nothing else, whatever is nested inside it.
+      #
+      # Narrowing by ancestor would cost fewer attributes, and cannot be had. An element inside a nested
+      # scope is still a descendant of the one outside it, and CSS has no way to say otherwise, so only
+      # an attribute on the element itself tells them apart.
+      #
+      # A file is scoped as a whole, so markup an inlined partial brought with it belongs to the
+      # partial and not to the template it landed in. `Herb::Visitor::Context::Origin` is what says so, which
+      # is why this has to run after `InlineRenderVisitor` and before `Slots::Visitor`, whose parked
+      # markup a client rebuilds from and which therefore has to already carry the attribute.
+      #
+      # Rewriting the selectors is somebody else's job. `transform` is anything answering `call` with
+      # the block's CSS and the selector to narrow it by:
+      #
+      #     transform.call(".title { color: red }", scope: "[data-herb-scope-1a2b3c4d]")
+      #     #=> ".title[data-herb-scope-1a2b3c4d] { color: red }"
+      #
+      # Anything the return value answers to `warnings` is reported, because CSS a transform kept
+      # without acting on it is CSS that does nothing once the page is rendered.
+      #
+      # `LightningCSS::Transformer` answers that, so it can be handed over as it is:
+      #
+      #     Herb::Engine::ScopedStyle::Visitor.new(transform: LightningCSS::Transformer.new(minify: true))
+      #
+      # `scope` is the selector each rule has to be narrowed by, appended to what the rule already
+      # matches.
+      #
+      # Lightning CSS is what narrows a block unless something else is given, so `transform` is for
+      # narrowing it some other way. Without one at all, which is a machine with no `lightningcss` on
+      # it, a block is left exactly as it was written and reported. Scoping the markup while
+      # leaving the CSS alone would turn a scoped block into a global one. A `transform` that raises
+      # is treated the same way, so CSS nobody can read costs the block it was written in and not the
+      # whole template.
+      #
+      # `deliver` says where the narrowed CSS goes. `:inline` leaves the block where it was written,
+      # which needs nothing else installed and writes the block again on every render of the file it
+      # was written in. `:hoist` takes the block out and registers the CSS with the session the page
+      # is collecting into, which writes it once however many times the file renders, and needs
+      # `Herb::Engine::Runtime::Middleware` to put it on the page.
+      #
+      class Visitor < Herb::Visitor
+        extend Herb::Visitor::Experimental
+        include Herb::Visitor::ContextAware
+        include Herb::Visitor::Diagnostics
+
+        ARRAY_PROPERTIES = [:children, :body, :statements].freeze #: Array[Symbol]
+        NODE_PROPERTIES = [:subsequent, :else_clause, :rescue_clause, :ensure_clause].freeze #: Array[Symbol]
+
+        ATTRIBUTE_PREFIX = "data-herb-scope-" #: String
+        SCOPED_ATTRIBUTE = "scoped" #: String
+        ANCHOR_ATTRIBUTE = "data-herb-style-scoped" #: String
+        UNSCOPABLE_ELEMENTS = ["style", "script"].freeze #: Array[String]
+        OPEN_TAGS = [Herb::AST::HTMLOpenTagNode, Herb::AST::ERBOpenTagNode].freeze #: Array[untyped]
+        DELIVERIES = [:inline, :hoist, :none].freeze #: Array[Symbol]
+
+        DIGEST_LENGTH = 8 #: Integer
+
+        required_parser_option track_locations: true
+        required_parser_option render_nodes: true
+        experimental "Scoped styles are experimental. Their output and API may change."
+
+        Pending = Data.define(:node, :open_tag, :attribute, :css, :file, :container)
+
+        #: () -> bool
+        def self.rewrites_style_blocks?
+          true
+        end
+
+        #: (?transform: untyped, ?deliver: Symbol) -> void
+        def initialize(transform: nil, deliver: :inline)
+          super()
+
+          raise ArgumentError, "`deliver: #{deliver.inspect}` is not a delivery. Pass one of #{DELIVERIES.map(&:inspect).join(", ")}." unless DELIVERIES.include?(deliver)
+
+          @deliver = deliver
+          @transform = transform || default_transform
+          @scopes = {} #: Hash[String, String]
+          @styles = {} #: Hash[String, String]
+          @elements = {} #: Hash[String, Integer]
+          @pending = [] #: Array[Array[untyped]]
+          @stack = [] #: Array[String]
+        end
+
+        #: () -> Hash[String, String]
+        def styles
+          @styles.dup
+        end
+
+        #: (Herb::AST::DocumentNode) -> void
+        def visit_document_node(node)
+          @stack = [context.relative_file_path]
+          @scopes = {} #: Hash[String, String]
+          @styles = {} #: Hash[String, String]
+          @elements = Hash.new(0) #: Hash[String, Integer]
+          @pending = [] #: Array[Array[untyped]]
+
+          collect(node)
+          narrow
+
+          super
+
+          report_empty_scopes
+        end
+
+        #: (Herb::AST::ERBBlockNode) -> void
+        def visit_erb_block_node(node)
+          entered = enter(node)
+
+          super
+        ensure
+          leave if entered
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> void
+        def visit_html_element_node(node)
+          file = current_file
+          scope = @scopes[file]
+          open_tag = node.open_tag
+
+          attributes = scope && scopable?(node) ? attribute_children(open_tag) : nil
+
+          if attributes && scope
+            @elements[file] += 1
+
+            attributes << attribute_node(scope)
+          end
+
+          super
+        end
+
+        #: () -> String
+        def inspect
+          parts = [] #: Array[String]
+          parts << "transform=#{@transform.class}" if @transform
+          parts << "deliver=#{@deliver}" unless @deliver == :inline
+
+          return "#<#{self.class.name}>" if parts.empty?
+
+          "#<#{self.class.name} #{parts.join(" ")}>"
+        end
+
+        private
+
+        #: () -> String
+        def current_file
+          @stack.last #: as String
+        end
+
+        #: (Herb::AST::Node) -> Herb::Visitor::Context::Origin::Entry?
+        def enter(node)
+          entry = origin.of(node)
+
+          @stack.push(entry.file) if entry
+
+          entry
+        end
+
+        #: () -> void
+        def leave
+          @stack.pop
+
+          nil
+        end
+
+        #: (Herb::AST::Node, ?Array[untyped]?) -> void
+        def collect(node, container = nil)
+          entered = enter(node)
+
+          scope_style(node, container) if node.is_a?(Herb::AST::HTMLElementNode)
+
+          ARRAY_PROPERTIES.each do |property|
+            children = property_of(node, property)
+
+            next unless children.is_a?(Array)
+
+            children.each { |child| collect(child, children) if child.is_a?(Herb::AST::Node) }
+          end
+
+          NODE_PROPERTIES.each do |property|
+            child = property_of(node, property)
+
+            collect(child) if child.is_a?(Herb::AST::Node)
+          end
+
+          leave if entered
+
+          nil
+        end
+
+        #: (Herb::AST::Node, Symbol) -> untyped
+        def property_of(node, property)
+          node.send(property) if node.respond_to?(property)
+        end
+
+        #: (Herb::AST::HTMLElementNode, Array[untyped]?) -> void
+        def scope_style(node, container)
+          return unless node.tag_name&.value&.downcase == "style"
+
+          open_tag = node.open_tag
+
+          return unless open_tag.is_a?(Herb::AST::HTMLOpenTagNode)
+
+          attribute = scoped_attribute(open_tag)
+
+          return unless attribute
+          return unless scopable_file?(node)
+
+          css = static_css(node)
+
+          return dynamic_style(node) unless css
+          return untransformed_style(node) unless @transform
+
+          @pending << Pending.new(
+            node: node,
+            open_tag: open_tag,
+            attribute: attribute,
+            css: css,
+            file: current_file,
+            container: container
+          )
+
+          scope_for(current_file)
+
+          nil
+        end
+
+        #: () -> void
+        def narrow
+          @pending.each do |pending|
+            scope = @scopes[pending.file] #: as String
+            narrowed = narrowed_css(pending, scope)
+
+            next unless narrowed
+
+            place(pending, scope, narrowed)
+
+            @styles[scope] = narrowed
+          end
+
+          @scopes.delete_if { |_file, scope| !@styles.key?(scope) }
+
+          nil
+        end
+
+        #: (Pending, String) -> String?
+        def narrowed_css(pending, scope)
+          result = @transform.call(pending.css, scope: scope_selector(scope))
+
+          warned_style(pending.node, result, pending.file)
+
+          result.to_s
+        rescue StandardError => e
+          untransformable_style(pending.node, e, pending.file)
+        end
+
+        #: (Pending, String, String) -> void
+        def place(pending, scope, narrowed)
+          index = @deliver == :inline ? nil : position_of(pending)
+
+          if index.nil?
+            pending.node.body.replace([literal_node(narrowed)])
+            replace_attribute(pending.open_tag, pending.attribute, anchor_node(scope))
+          elsif @deliver == :hoist
+            pending.container[index] = register_node(scope, narrowed)
+          else
+            pending.container.delete_at(index)
+          end
+
+          nil
+        end
+
+        #: (Pending) -> Integer?
+        def position_of(pending)
+          container = pending.container
+
+          return nil unless container
+
+          container.index { |child| child.equal?(pending.node) }
+        end
+
+        #: (String, String) -> Herb::AST::ERBContentNode
+        def register_node(scope, narrowed)
+          Herb::AST::ERBContentNode.build(
+            tag_opening: Herb::Token.from("TOKEN_ERB_START", "<%"),
+            content: Herb::Token.from(
+              "TOKEN_ERB_CONTENT",
+              " ::Herb::Engine::ScopedStyle::Channel.record(#{scope.dump}, #{narrowed.dump}) "
+            ),
+            tag_closing: Herb::Token.from("TOKEN_ERB_END", "%>"),
+            valid: true
+          )
+        end
+
+        #: (String) -> Herb::AST::HTMLAttributeNode
+        def anchor_node(scope)
+          name_node = Herb::AST::HTMLAttributeNameNode.build(children: [literal_node(ANCHOR_ATTRIBUTE)])
+
+          value_node = Herb::AST::HTMLAttributeValueNode.build(
+            open_quote: Herb::Token.from("TOKEN_QUOTE", '"'),
+            children: [literal_node(scope)],
+            close_quote: Herb::Token.from("TOKEN_QUOTE", '"'),
+            quoted: true
+          )
+
+          Herb::AST::HTMLAttributeNode.build(
+            name: name_node,
+            equals: Herb::Token.from("TOKEN_EQUALS", "="),
+            value: value_node
+          )
+        end
+
+        #: (Herb::AST::HTMLOpenTagNode, Herb::AST::HTMLAttributeNode, Herb::AST::HTMLAttributeNode) -> void
+        def replace_attribute(open_tag, attribute, replacement)
+          children = open_tag.children
+          index = children.index(attribute)
+
+          return unless index
+
+          children[index] = replacement
+
+          nil
+        end
+
+        #: (Herb::AST::HTMLOpenTagNode, Herb::AST::HTMLAttributeNode) -> void
+        def remove_attribute(open_tag, attribute)
+          children = open_tag.children
+          index = children.index(attribute)
+
+          return unless index
+
+          children.delete_at(index)
+
+          preceding = index.positive? ? children[index - 1] : nil
+
+          children.delete_at(index - 1) if preceding.is_a?(Herb::AST::WhitespaceNode)
+
+          nil
+        end
+
+        #: (Herb::AST::HTMLOpenTagNode) -> Herb::AST::HTMLAttributeNode?
+        def scoped_attribute(open_tag)
+          (open_tag.children || []).each do |child|
+            next unless child.is_a?(Herb::AST::HTMLAttributeNode)
+
+            return child if attribute_name(child) == SCOPED_ATTRIBUTE
+          end
+
+          nil
+        end
+
+        #: (Herb::AST::HTMLAttributeNode) -> String?
+        def attribute_name(node)
+          children = node.name&.children
+
+          return nil unless children
+
+          name = children.filter_map { |child| child.content if child.is_a?(Herb::AST::LiteralNode) }.join
+
+          name.empty? ? nil : name.downcase
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> String?
+        def static_css(node)
+          children = node.body || []
+
+          return nil unless children.all?(Herb::AST::LiteralNode)
+
+          children.filter_map { |child| child.content if child.is_a?(Herb::AST::LiteralNode) }.join
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> bool
+        def scopable_file?(node)
+          return true unless current_file == Herb::Visitor::Context::UNKNOWN_FILE_PATH
+
+          warning(
+            "A `<style scoped>` block needs the path of the file it was written in, and this template was compiled without one. Compile it with `filename:` to scope it.",
+            node.location,
+            code: "scoped-style-without-a-file",
+            template: current_file
+          )
+
+          false
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> void
+        def dynamic_style(node)
+          warning(
+            "A `<style scoped>` block built with ERB has no CSS to read at compile time, so it was left as it was written and still applies to the whole page.",
+            node.location,
+            code: "scoped-style-built-with-erb",
+            template: current_file
+          )
+
+          nil
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> void
+        def untransformed_style(node)
+          reason = @unavailable ? " Loading `lightningcss` failed with `#{@unavailable}`." : ""
+
+          warning(
+            "A `<style scoped>` block was found, and there is no `transform` to narrow its selectors with, so it was left as it was written and still applies to the whole page.#{reason} Install `lightningcss`, or give #{self.class.name} a `transform` of its own.",
+            node.location,
+            code: "scoped-style-without-a-transform",
+            template: current_file
+          )
+
+          nil
+        end
+
+        #: () -> untyped
+        def default_transform
+          require "lightningcss"
+
+          ::LightningCSS::Transformer.new
+        rescue LoadError => e
+          @unavailable = e.message
+
+          nil
+        end
+
+        #: (Herb::AST::HTMLElementNode, StandardError, String) -> nil
+        def untransformable_style(node, error, file)
+          warning(
+            "A `<style scoped>` block could not be narrowed by the `transform` #{self.class.name} was given, so it was left as it was written and still applies to the whole page. It failed with `#{error.message}`.",
+            node.location,
+            code: "scoped-style-that-could-not-be-narrowed",
+            template: file
+          )
+
+          nil
+        end
+
+        #: (Herb::AST::HTMLElementNode, untyped, String) -> void
+        def warned_style(node, result, file)
+          return unless result.respond_to?(:warnings)
+
+          result.warnings.each do |message|
+            warning(
+              "The `transform` could not act on something in this `<style scoped>` block, so that part of the CSS was kept as it was written and does nothing. It reported `#{message}`.",
+              node.location,
+              code: "scoped-style-with-a-warning",
+              template: file
+            )
+          end
+
+          nil
+        end
+
+        #: (String) -> String
+        def scope_selector(scope)
+          "[#{scope}]"
+        end
+
+        #: (String) -> String
+        def scope_for(file)
+          @scopes[file] ||= "#{ATTRIBUTE_PREFIX}#{Digest::SHA256.hexdigest(file)[0, DIGEST_LENGTH]}"
+        end
+
+        #: (untyped) -> Array[untyped]?
+        def attribute_children(open_tag)
+          return nil unless OPEN_TAGS.any? { |type| open_tag.is_a?(type) }
+
+          open_tag.children
+        end
+
+        #: (Herb::AST::HTMLElementNode) -> bool
+        def scopable?(node)
+          !UNSCOPABLE_ELEMENTS.include?(node.tag_name&.value&.downcase)
+        end
+
+        #: (String) -> Herb::AST::HTMLAttributeNode
+        def attribute_node(name)
+          Herb::AST::HTMLAttributeNode.build(
+            name: Herb::AST::HTMLAttributeNameNode.build(children: [literal_node(name)]),
+            equals: nil,
+            value: nil
+          )
+        end
+
+        #: (String) -> Herb::AST::LiteralNode
+        def literal_node(content)
+          Herb::AST::LiteralNode.build(content: content.dup)
+        end
+
+        #: () -> void
+        def report_empty_scopes
+          @scopes.each_key do |file|
+            next unless @elements[file].zero?
+
+            warning(
+              "The `<style scoped>` block in #{file} has no markup to apply to, because nothing in the file it was written in is an element.",
+              nil,
+              code: "scoped-style-without-markup",
+              template: file
+            )
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/annotation.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "types"
+
+module Herb
+  class Engine
+    module Slots
+      # What the visitor knows about one slot while it is still reading the template.
+      #
+      # A slot's index is its address, and an address cannot be handed out until it is known which
+      # slots survive: collapsing an invariant conditional drops one and merges the branches behind
+      # it. So the walk records annotations, which carry no index and can be marked as it learns
+      # more, and only the final pass turns the survivors into numbered slots.
+      #
+      class Annotation
+        attr_reader :node #: untyped
+        attr_accessor :type #: Symbol
+        attr_reader :node_path #: Array[Integer]
+        attr_accessor :expression #: String?
+        attr_accessor :attribute #: String?
+        attr_reader :key_source #: Symbol?
+        attr_reader :key_expression #: String?
+        attr_reader :tag #: String?
+        attr_reader :scope #: untyped
+        attr_reader :depth #: Integer
+
+        attr_accessor :index #: Integer?
+        attr_accessor :name #: String?
+        attr_accessor :dropped #: bool
+        attr_accessor :merged_into #: Annotation?
+        attr_reader :covered #: Array[Annotation]
+
+        #: (node: untyped, type: Symbol, node_path: Array[Integer], expression: String?, attribute: String?, key_source: Symbol?, key_expression: String?, tag: String?, scope: untyped, depth: Integer) -> void
+        def initialize(node:, type:, node_path:, expression:, attribute:, key_source:, key_expression:, tag:, scope:, depth:) # rubocop:disable Metrics/ParameterLists
+          @node = node
+          @type = type
+          @node_path = node_path
+          @expression = expression
+          @attribute = attribute
+          @key_source = key_source
+          @key_expression = key_expression
+          @tag = tag
+          @scope = scope
+          @depth = depth
+
+          @index = nil
+          @name = nil
+          @dropped = false
+          @merged_into = nil
+          @covered = [] #: Array[Annotation]
+        end
+
+        #: () -> bool
+        def gone? = @dropped || !@merged_into.nil?
+
+        #: () -> Annotation
+        def survivor
+          found = self #: Annotation
+
+          found = found.merged_into while found.merged_into
+
+          found
+        end
+
+        #: () -> bool
+        def structural? = Types.structural?(type)
+
+        #: () -> bool
+        def attribute? = Types.attribute?(type)
+
+        #: () -> bool
+        def anchored? = Types.element_anchored?(type)
+
+        #: () -> bool
+        def nameable? = Types.nameable?(type)
+
+        #: () -> bool
+        def valued? = Types.valued?(type)
+
+        #: (Integer) -> untyped
+        def to_slot(index)
+          Visitor::Slot.new(
+            index: index,
+            type: type,
+            node_path: node_path,
+            expression: expression,
+            attribute: attribute,
+            key_source: key_source,
+            key_expression: key_expression,
+            name: name,
+            tag: tag,
+            merged_paths: covered.map(&:node_path)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/bindings.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      # The state values a render call hands the partial it renders.
+      #
+      # A caller's compile rewrites `render "card", state: { open: modal_open }` into a call
+      # wrapped by `with`, so the values travel on a stack the partial's own state assignments
+      # read through `StateOverrides.resolve`. Two tables ride on every frame. A bound value
+      # aliases the partial's state to the caller's and wins over anything a client sent, since
+      # the client cannot tell two render sites of one partial apart. A seeded value only sets
+      # the partial's starting point, so a client that has since written the state wins over it.
+      #
+      # The stack lives in fiber storage, which a child fiber or thread inherits, so a render
+      # that streams or captures still sees the frames its caller pushed.
+      #
+      module Bindings
+        KEY = :herb_slots_bindings #: Symbol
+
+        class UncoercibleSeedError < StandardError
+        end
+
+        #: (String, ?bound: Hash[String, untyped], ?seeded: Hash[String, untyped]) { () -> untyped } -> untyped
+        def self.with(identifier, bound: {}, seeded: {})
+          seeded.each { |name, value| check_seed(identifier, name, value) }
+
+          stack = (Fiber[KEY] ||= []) #: Array[Hash[String, Hash[Symbol, Hash[String, untyped]]]]
+          stack.push({ identifier => { bound: bound, seeded: seeded } })
+
+          begin
+            yield
+          ensure
+            stack.pop
+          end
+        end
+
+        #: (String) -> Hash[Symbol, Hash[String, untyped]]?
+        def self.current(identifier)
+          stack = Fiber[KEY]
+
+          return nil unless stack.is_a?(Array)
+
+          stack.reverse_each do |frame|
+            return frame[identifier] if frame.key?(identifier)
+          end
+
+          nil
+        end
+
+        #: (String, String, untyped) -> void
+        def self.check_seed(identifier, name, value)
+          return unless StateOverrides.coerce(value, :seeded) == :__herb_uncoercible
+
+          raise UncoercibleSeedError, "`#{name}` on `#{identifier}` was seeded with #{value.class}, and a state holds a scalar. Pass the value as a local instead."
+        end
+      end
+    end
+  end
+end