rsx-rb 0.1.0

data/lib/rsx/component.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module RSX
+  # Base class for every `component` defined in a .rsx file.
+  #
+  #   component Greeting do |name:|
+  #     return <p>Hello {name}</p>
+  #   end
+  #
+  # compiles to a subclass whose `rsx_render` is the block body. Components are
+  # plain Ruby objects: one instance per render, no inheritance requirements on
+  # the caller, and no framework needed to use them.
+  class Component
+    EMPTY_PROPS = {}.freeze
+
+    class << self
+      attr_accessor :rsx_source_path, :rsx_source_digest
+      attr_writer :rsx_cache_options
+
+      def rsx_cache_options
+        @rsx_cache_options
+      end
+
+      # Marks a component whose output never varies. The compiler sets this
+      # automatically when a component body is nothing but static markup.
+      def rsx_static!
+        @rsx_static = true
+      end
+
+      def rsx_static?
+        @rsx_static ? true : false
+      end
+
+      # Enables whole-component caching.
+      #
+      #   cache expires_in: 300
+      #   cache key: ->(props) { [props[:user], props[:locale]] }
+      def cache(options = true)
+        @rsx_cache_options = RSX.normalize_cache_options(options)
+      end
+
+      # Renders the component. This is the entry point used by compiled markup.
+      def rsx_call(props = nil, parent = nil)
+        return (@rsx_static_output ||= new(props, parent).rsx_perform) if rsx_static?
+
+        options = rsx_cache_options
+        return new(props, parent).rsx_perform unless options
+
+        key = rsx_cache_key(props, options)
+        cached = RSX.cache.fetch(key, expires_in: options[:expires_in]) do
+          new(props, parent).rsx_perform.to_s
+        end
+        cached.is_a?(SafeString) ? cached : SafeString.new(cached)
+      end
+
+      # Public API: Button.call(label: "Save") => SafeString
+      def call(**props)
+        rsx_call(props)
+      end
+
+      def render(**props)
+        rsx_call(props)
+      end
+
+      def rsx_cache_key(props, options)
+        custom = options[:key]
+        payload =
+          if custom.nil?
+            (props || EMPTY_PROPS).reject { |key, _| key == :children }
+          elsif custom.respond_to?(:arity) && custom.arity.zero?
+            custom.call
+          else
+            custom.call(props || EMPTY_PROPS)
+          end
+
+        "rsx/#{name || "component"}/#{rsx_source_digest || "0"}/#{RSX.stable_key(payload)}"
+      end
+
+      def rsx_render_style
+        return @rsx_render_style if defined?(@rsx_render_style)
+
+        parameters = rsx_render_parameters
+        keyword = parameters.any? { |kind, _| %i[key keyreq keyrest].include?(kind) }
+        @rsx_render_style = keyword ? :keyword : :positional
+      end
+
+      def rsx_render_parameters
+        instance_method(:rsx_render).parameters
+      rescue NameError
+        []
+      end
+
+      # The keyword props this component declares.
+      def rsx_accepted_props
+        @rsx_accepted_props ||= rsx_render_parameters.filter_map do |kind, name|
+          name if %i[key keyreq].include?(kind)
+        end
+      end
+
+      def rsx_accepts_extra_props?
+        return @rsx_accepts_extra_props if defined?(@rsx_accepts_extra_props)
+
+        @rsx_accepts_extra_props = rsx_render_parameters.any? { |kind, _| kind == :keyrest }
+      end
+
+      def rsx_filter_props(props)
+        return EMPTY_PROPS if props.nil? || props.empty?
+        return props if rsx_accepts_extra_props?
+
+        accepted = rsx_accepted_props
+        unknown = props.keys - accepted - [:children]
+        unless unknown.empty?
+          raise PropsError, "#{name} does not accept #{unknown.map(&:inspect).join(", ")}. " \
+                            "Declared props: #{accepted.map(&:inspect).join(", ")}. " \
+                            "Add `**rest` to the component parameters to accept anything else."
+        end
+
+        accepted.include?(:children) ? props : props.except(:children)
+      end
+
+      def inspect
+        name || super
+      end
+    end
+
+    attr_reader :props
+
+    def initialize(props = nil, parent = nil)
+      @props = props || EMPTY_PROPS
+      @rsx_parent = parent
+    end
+
+    def rsx_perform
+      result =
+        if self.class.rsx_render_style == :keyword
+          rsx_render(**self.class.rsx_filter_props(@props))
+        else
+          rsx_render(@props)
+        end
+      RSX.child(result)
+    rescue ArgumentError => e
+      raise unless e.message.start_with?("missing keyword", "unknown keyword", "wrong number of arguments")
+
+      raise PropsError, "#{self.class.name}: #{e.message}. " \
+                        "Declared props: #{self.class.rsx_accepted_props.map(&:inspect).join(", ")}"
+    end
+
+    # The markup nested inside this component's tag, rendered on demand.
+    def children
+      @props[:children]
+    end
+
+    def children?
+      child = children
+      !child.nil? && !(child.respond_to?(:empty?) && child.empty?)
+    end
+
+    # The object that rendered this component: a view context in Rails, the
+    # parent component when nested, or nil when rendered directly.
+    def rsx_parent
+      @rsx_parent
+    end
+
+    # The nearest non-component render context, i.e. the Rails view. Gives access
+    # to url helpers, form builders, `t`, asset helpers and anything else the
+    # application exposes to templates.
+    def helpers
+      node = @rsx_parent
+      node = node.rsx_parent while node.is_a?(Component)
+      return node unless node.nil?
+
+      raise Error, "#{self.class.name} has no view context. Render it from a Rails view, " \
+                   "or pass one with RSX.render(#{self.class.name}, context: view)."
+    end
+    alias view_context helpers
+
+    def helpers?
+      node = @rsx_parent
+      node = node.rsx_parent while node.is_a?(Component)
+      !node.nil?
+    end
+
+    # Reads a value provided by an enclosing <Ctx.Provider>.
+    def use_context(context)
+      context.value
+    end
+
+    # Caches a fragment of markup.
+    #
+    #   {cache(["sidebar", user.id], expires_in: 300) do
+    #     <nav>...</nav>
+    #   end}
+    def cache(key, expires_in: nil)
+      full_key = "rsx/#{self.class.name}/#{self.class.rsx_source_digest || "0"}/#{RSX.stable_key(key)}"
+      cached = RSX.cache.fetch(full_key, expires_in: expires_in) { RSX.child(yield).to_s }
+      cached.is_a?(SafeString) ? cached : SafeString.new(cached)
+    end
+
+    # Escape hatch for trusted HTML built elsewhere.
+    def raw(value)
+      RSX.raw(value)
+    end
+
+    def to_s
+      rsx_perform
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@props.inspect}>"
+    end
+  end
+end

data/lib/rsx/context.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RSX
+  # React's Context API: a value provided high in the tree and read anywhere
+  # below it without threading props through every component in between.
+  #
+  #   Theme = RSX.create_context("light")
+  #
+  #   <Theme.Provider value={"dark"}>
+  #     <Toolbar />
+  #   </Theme.Provider>
+  #
+  #   # inside any descendant
+  #   {use_context(Theme)}
+  #
+  # Provided values live on a per-thread stack, so concurrent requests never see
+  # each other's context.
+  class Context
+    attr_reader :name, :default
+
+    def initialize(default = nil, name: nil)
+      @default = default
+      @name = name
+      @key = :"rsx_context_#{object_id}"
+    end
+
+    def value
+      stack = Thread.current[@key]
+      stack && !stack.empty? ? stack.last : @default
+    end
+    alias current value
+
+    def with(value)
+      stack = (Thread.current[@key] ||= [])
+      stack.push(value)
+      yield
+    ensure
+      stack.pop
+    end
+
+    # Allows <Theme.Provider value={...}>
+    def Provider # rubocop:disable Naming/MethodName
+      @provider ||= ProviderComponent.new(self)
+    end
+    alias provider Provider
+
+    def inspect
+      "#<RSX::Context #{name || object_id} default=#{@default.inspect}>"
+    end
+
+    # A component-like object: anything answering to rsx_call can be rendered.
+    class ProviderComponent
+      def initialize(context)
+        @context = context
+      end
+
+      def name
+        "#{@context.name || "Context"}.Provider"
+      end
+
+      def rsx_call(props = nil, _parent = nil)
+        props ||= {}
+        @context.with(props[:value]) { RSX.child(props[:children]) }
+      end
+    end
+  end
+end

data/lib/rsx/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RSX
+  class Error < StandardError; end
+
+  # Raised when a .rsx file cannot be transformed into Ruby.
+  class SyntaxError < Error
+    attr_reader :path, :line, :column
+
+    def initialize(message, path: nil, line: nil, column: nil)
+      @path = path
+      @line = line
+      @column = column
+      location = [path || "(rsx)", line, column].compact.join(":")
+      super("#{location}: #{message}")
+    end
+  end
+
+  # Raised when a <Tag /> cannot be resolved to a component.
+  class UnknownComponentError < Error; end
+
+  # Raised when a component is rendered with props it does not accept.
+  class PropsError < Error; end
+
+  # Raised when RSX cannot locate a .rsx file for a path or import.
+  class FileNotFoundError < Error; end
+end

data/lib/rsx/escape.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module RSX
+  # HTML escaping. Runtime escaping goes through CGI.escapeHTML (a C extension
+  # in stdlib) so no third-party gem is needed.
+  module Escape
+    # Matches a character reference such as & © or —
+    ENTITY = /&(?:[a-zA-Z][a-zA-Z0-9]{1,30}|#[0-9]{1,7}|#[xX][0-9a-fA-F]{1,6});/
+
+    module_function
+
+    # Escapes text for element content or an attribute value.
+    def html(string)
+      CGI.escapeHTML(string)
+    end
+
+    # True for values that must not be escaped again.
+    #
+    # ActiveSupport::SafeBuffer (what Rails helpers return) is a String
+    # subclass, so the exact-class check below is what keeps `link_to` output
+    # from being escaped while still taking the fast path for plain strings.
+    def safe?(value)
+      return true if value.is_a?(SafeString)
+      return false if value.instance_of?(String)
+
+      value.respond_to?(:html_safe?) && value.html_safe?
+    end
+
+    # Escaping for *static* text baked in at compile time.
+    #
+    # JSX passes character references such as   through to the browser, so
+    # RSX keeps well-formed entities intact while still escaping stray markup.
+    def static_text(string)
+      return CGI.escapeHTML(string) unless string.include?("&")
+
+      out = +""
+      last = 0
+      string.scan(ENTITY) do
+        match = Regexp.last_match
+        out << CGI.escapeHTML(string[last...match.begin(0)])
+        out << match[0]
+        last = match.end(0)
+      end
+      out << CGI.escapeHTML(string[last..]) if last < string.length
+      out
+    end
+
+    # Escapes a value destined for a double-quoted attribute.
+    def attribute(value)
+      return value if value.is_a?(SafeString)
+      return CGI.escapeHTML(value) if value.instance_of?(String)
+      return value.to_s if safe?(value)
+
+      CGI.escapeHTML(value.to_s)
+    end
+  end
+end

data/lib/rsx/helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RSX
+  # Mixed into ActionView so components can be rendered from ERB, Haml, Slim or
+  # anywhere else a view helper is available.
+  #
+  #   <%= rsx UserProfile, user: @user %>
+  #   <%= rsx "Card", title: "Hello" do %>
+  #     <p>Body rendered by ERB, passed to the component as children.</p>
+  #   <% end %>
+  module Helpers
+    def rsx(target, **props, &block)
+      children =
+        if block
+          captured = capture(&block)
+          RSX::Children.new { RSX.raw(captured) }
+        end
+
+      component = target.is_a?(String) || target.is_a?(Symbol) ? RSX.lookup_component(target) : target
+      RSX.safe(RSX.render_component(component, props.empty? ? nil : props, children, self))
+    end
+    alias render_rsx rsx
+
+    # Renders a .rsx file directly by path, relative to the configured paths.
+    def rsx_file(path, **props)
+      RSX.render_file(path, context: self, **props)
+    end
+  end
+end

data/lib/rsx/loader.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module RSX
+  # Finds, compiles, evaluates and reloads .rsx files.
+  class Loader
+    EXTENSIONS = [".rsx", ".html.rsx"].freeze
+
+    Entry = Struct.new(:path, :digest, :mtime, :components, :default, :template, keyword_init: true) do
+      # Markup files render through a template; component files render their
+      # default export.
+      def renderable
+        default || components.first
+      end
+    end
+
+    def initialize(config)
+      @config = config
+      @entries = {}
+      @stack = []
+      @monitor = Monitor.new
+    end
+
+    def entries
+      @entries.values
+    end
+
+    def loaded?(path)
+      @entries.key?(File.expand_path(path))
+    end
+
+    # The file currently being evaluated, used to attribute components to it.
+    def current_entry
+      @stack.last
+    end
+
+    def compile_cache
+      @config.compile_cache
+    end
+
+    # Compiles and evaluates a .rsx file exactly once per digest.
+    def load(path, force: false)
+      absolute = File.expand_path(path)
+      raise FileNotFoundError, "no such RSX file: #{absolute}" unless File.file?(absolute)
+
+      @monitor.synchronize do
+        source = File.read(absolute)
+        digest = compile_cache.digest(source)
+        existing = @entries[absolute]
+        return existing if existing && existing.digest == digest && !force
+
+        unload(existing) if existing
+
+        entry = Entry.new(path: absolute, digest: digest, mtime: mtime(absolute), components: [], default: nil)
+        @entries[absolute] = entry
+        @stack.push(entry)
+
+        begin
+          ruby = compile_cache.fetch(absolute, source) do
+            Transformer.transform(source, path: absolute)
+          end
+
+          if Transformer.defines_components?(ruby)
+            # Component files are evaluated at the top level so that `class`,
+            # `def` and constants behave exactly as they do in a .rb file.
+            eval(ruby, TOPLEVEL_BINDING, absolute, 1) # rubocop:disable Security/Eval
+          else
+            entry.template = Template.from_ruby(ruby, path: absolute, digest: digest)
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          @entries.delete(absolute)
+          raise
+        ensure
+          @stack.pop
+        end
+
+        entry
+      end
+    end
+
+    # Loads every .rsx file under the configured paths. Called at boot in
+    # production so no request pays for compilation.
+    def load_all(paths = @config.paths)
+      files(paths).each { |file| load(file) }
+    end
+
+    def files(paths = @config.paths)
+      Array(paths).flat_map do |root|
+        next [] unless File.directory?(root)
+
+        Dir.glob(File.join(root, "**", "*.rsx")).sort
+      end
+    end
+
+    # Reloads only the files whose contents changed. Used by the Rails reloader.
+    def reload!
+      @monitor.synchronize do
+        @entries.values.each do |entry|
+          if !File.file?(entry.path)
+            unload(entry)
+            @entries.delete(entry.path)
+          elsif mtime(entry.path) != entry.mtime
+            load(entry.path, force: true)
+          end
+        end
+      end
+    end
+
+    def clear
+      @monitor.synchronize do
+        @entries.each_value { |entry| unload(entry) }
+        @entries.clear
+      end
+    end
+
+    # Resolves an import specifier or template path to a file on disk.
+    def resolve(spec, from: nil)
+      spec = spec.to_s
+      candidates = []
+
+      if spec.start_with?("/")
+        candidates << spec
+      else
+        candidates << File.expand_path(spec, File.dirname(from)) if from && !from.empty?
+        Array(@config.paths).each { |root| candidates << File.join(root, spec) }
+        candidates << File.expand_path(spec, Dir.pwd)
+      end
+
+      candidates.each do |candidate|
+        return candidate if File.file?(candidate)
+
+        EXTENSIONS.each do |extension|
+          with_extension = "#{candidate}#{extension}"
+          return with_extension if File.file?(with_extension)
+        end
+      end
+
+      nil
+    end
+
+    def resolve!(spec, from: nil)
+      resolve(spec, from: from) ||
+        raise(FileNotFoundError, "could not find `#{spec}`#{" imported from #{from}" if from}. " \
+                                 "Looked in: #{Array(@config.paths).join(", ")}")
+    end
+
+    def import(spec, as: nil, from: nil)
+      entry = load(resolve!(spec, from: from))
+      Array(as).each { |name| alias_constant(name, entry) }
+      entry.default || entry.components.first
+    end
+
+    # Records a component defined by the file currently being loaded.
+    def track(component)
+      entry = current_entry
+      return component unless entry
+
+      entry.components << component
+      entry.default ||= component
+      component.rsx_source_path = entry.path
+      component.rsx_source_digest = entry.digest
+      component
+    end
+
+    def default_export(path)
+      entry = load(path)
+      entry.default || entry.components.first
+    end
+
+    private
+
+    def mtime(path)
+      File.mtime(path)
+    rescue SystemCallError
+      nil
+    end
+
+    def alias_constant(name, entry)
+      name = name.to_s
+      target = entry.default || entry.components.first
+      return if target.nil?
+      return if RSX.const_defined_at?(name)
+
+      RSX.assign_constant(name, target)
+    end
+
+    def unload(entry)
+      entry.components.each { |component| RSX.remove_constant(component) }
+      entry.components.clear
+      entry.default = nil
+    end
+  end
+end

data/lib/rsx/nodes.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSX
+  # The RSX syntax tree. Every node records the source line it started on so the
+  # generated Ruby can be padded to keep backtraces aligned with the .rsx file.
+  module Nodes
+    # Literal markup text, already whitespace-normalized JSX style.
+    Text = Struct.new(:value, :line)
+
+    # {ruby} in child position.
+    Expression = Struct.new(:source, :line)
+
+    # <div>, <img />, <my-element>
+    Element = Struct.new(:tag, :attributes, :children, :self_closing, :line)
+
+    # <Button>, <Admin::Card>, <Theme.Provider>
+    Component = Struct.new(:name, :attributes, :children, :line)
+
+    # <>...</>
+    Fragment = Struct.new(:children, :line)
+
+    # kind is :static (name="text"), :expression (name={ruby}),
+    # :boolean (bare name) or :spread ({**ruby} / {...ruby}).
+    Attribute = Struct.new(:name, :value, :kind, :line)
+  end
+end

data/lib/rsx/railtie.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "template_handler"
+require_relative "helpers"
+
+module RSX
+  # Wires RSX into a Rails application. Nothing here runs unless Rails is
+  # already loaded, which keeps the gem usable outside Rails.
+  #
+  # Configure it from config/application.rb:
+  #
+  #   config.rsx.paths = [Rails.root.join("app/components")]
+  #   config.rsx.cache_store = :rails
+  #
+  class Railtie < ::Rails::Railtie
+    config.rsx = ActiveSupport::OrderedOptions.new
+
+    initializer "rsx.configure" do |app|
+      options = app.config.rsx
+
+      RSX.configure do |config|
+        config.paths = Array(options.paths.presence || default_paths(app))
+        config.cache_dir = options.key?(:cache_dir) ? options.cache_dir : app.root.join("tmp/cache/rsx").to_s
+        config.component_namespace = options.component_namespace || Object
+        config.reload = options.key?(:reload) ? options.reload : reloading?(app)
+        config.cache_store = build_cache_store(options.cache_store) if options.cache_store
+      end
+    end
+
+    initializer "rsx.action_view" do
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Template.register_template_handler(:rsx, RSX::TemplateHandler)
+        include RSX::Helpers
+      end
+    end
+
+    initializer "rsx.load_components" do |app|
+      # Eager load in production so no request ever pays for compilation, and
+      # reload changed files between requests in development.
+      if app.config.eager_load
+        app.config.after_initialize { RSX.load_all }
+      else
+        app.reloader.to_prepare { RSX.reload! if RSX.config.reload }
+      end
+
+      app.config.watchable_dirs ||= {}
+      Array(RSX.config.paths).each do |path|
+        app.config.watchable_dirs[path.to_s] = [:rsx] if File.directory?(path.to_s)
+      end
+    end
+
+    rake_tasks do
+      load File.expand_path("tasks.rake", __dir__)
+    end
+
+    # Initializer blocks are instance_exec'd on the railtie instance, so these
+    # helpers have to be instance methods.
+    private
+
+    def default_paths(app)
+      %w[app/components app/rsx].map { |path| app.root.join(path).to_s }
+    end
+
+    def reloading?(app)
+      if app.config.respond_to?(:enable_reloading)
+        app.config.enable_reloading
+      else
+        !app.config.cache_classes
+      end
+    end
+
+    def build_cache_store(setting)
+      case setting
+      when :rails, "rails" then Cache::Rails.new
+      when :memory, "memory" then Cache::Memory.new
+      when :null, "null", false then Cache::Null.new
+      else setting
+      end
+    end
+  end
+end