grsx 0.1.0

data/lib/grsx/phlex_component.rb

@@ -0,0 +1,361 @@
+require "phlex"
+require "phlex-rails"
+require "digest"
+
+module Grsx
+  # Base class for JSX-backed Phlex components.
+  #
+  # Define your props in initialize, write your template in a co-located .rbx
+  # file. Grsx compiles the .rbx into a real view_template method — no eval
+  # at render time.
+  #
+  # ## Basic usage
+  #
+  #   # app/components/card_component.rb
+  #   class CardComponent < Grsx::PhlexComponent
+  #     def initialize(title:)
+  #       @title = title
+  #     end
+  #   end
+  #
+  #   # app/components/card_component.rbx
+  #   <article class="card">
+  #     <h2>{@title}</h2>
+  #     {content}
+  #   </article>
+  #
+  # ## Named slots
+  #
+  #   class CardComponent < Grsx::PhlexComponent
+  #     slots :header, :footer
+  #   end
+  #
+  #   # card_component.rbx
+  #   <article>
+  #     <header>{slot(:header)}</header>
+  #     <main>{content}</main>
+  #     <footer>{slot(:footer)}</footer>
+  #   </article>
+  #
+  #   # Usage
+  #   card = CardComponent.new
+  #   card.with_slot(:header) { render LogoComponent.new }
+  #   render card
+  #
+  class PhlexComponent < Phlex::HTML
+    # Include ALL phlex-rails helper adapters so link_to, form_with,
+    # image_tag, url_for, etc. just work in every .rbx template without
+    # per-component opt-in.
+    #
+    # Some helpers (e.g. Routes) reference `Rails.application` at define
+    # time, which raises NameError outside a Rails boot. We rescue and
+    # skip — those helpers are unavailable in non-Rails contexts anyway.
+    Phlex::Rails::Helpers.constants.each do |helper_name|
+      begin
+        mod = Phlex::Rails::Helpers.const_get(helper_name)
+        include mod if mod.is_a?(Module)
+      rescue NameError
+        # Skip helpers that require Rails to be fully initialized
+      end
+    end
+
+    # --- Named slots ---
+
+    class << self
+      # Declare named content slots on the component.
+      #
+      #   class CardComponent < Grsx::PhlexComponent
+      #     slots :header, :footer
+      #   end
+      def slots(*names)
+        names.each do |name|
+          # Define a setter: component.with_header { ... }
+          define_method(:"with_#{name}") do |&block|
+            @_slots ||= {}
+            @_slots[name] = block
+            self
+          end
+
+          # Define a predicate: has_header?
+          define_method(:"has_#{name}?") do
+            (@_slots ||= {}).key?(name)
+          end
+        end
+      end
+
+      # Declare typed props with optional defaults — auto-generates initialize.
+      #
+      #   class CardComponent < Grsx::PhlexComponent
+      #     props :title, :body, size: :md, disabled: false
+      #   end
+      #
+      # This is exactly equivalent to:
+      #
+      #   def initialize(title:, body:, size: :md, disabled: false)
+      #     @title    = title
+      #     @body     = body
+      #     @size     = size
+      #     @disabled = disabled
+      #   end
+      #
+      # You can still override initialize manually when you need logic
+      # beyond simple ivar assignment.
+      def props(*required_names, **defaults)
+        # Guard against mutable default values ([], {}) — they would be
+        # shared across every instance of the component, causing subtle
+        # cross-request state contamination. Fail loudly at class-definition
+        # time with guidance on the idiomatic fix.
+        defaults.each do |key, val|
+          if val.is_a?(Array) || val.is_a?(Hash)
+            raise ArgumentError,
+              "#{name}.props :#{key} has a mutable default (#{val.inspect}). " \
+              "Use nil as the default and set the value in initialize instead:\n" \
+              "  props :#{key}\n" \
+              "  def initialize(#{key}: nil)\n" \
+              "    @#{key} = #{key} || #{val.inspect}\n" \
+              "  end"
+          end
+        end
+
+        @_declared_props = { required: required_names.map(&:to_sym), defaults: defaults }
+
+        all_names = required_names.map(&:to_sym) + defaults.keys.map(&:to_sym)
+
+        # Generate attr_readers so callers can inspect prop values after render.
+        # Templates use @ivar directly; attr_reader makes the same data available
+        # to parent components or test code.
+        attr_reader(*all_names)
+
+        # Build initialize parameter list
+        params = required_names.map { |n| "#{n}:" }
+        defaults.each { |k, v| params << "#{k}: #{v.inspect}" }
+
+        # Build ivar assignment lines
+        assignments = all_names.map { |n| "  @#{n} = #{n}" }
+
+        class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+          def initialize(#{params.join(", ")})
+          #{assignments.join("\n")}
+          end
+        RUBY
+      end
+
+      # Returns the declared props, or nil if none were declared.
+      attr_reader :_declared_props
+    end
+
+    # Render a named slot. Falls back silently if no slot content was provided.
+    # Used in .rbx templates as {slot(:header)}.
+    def slot(name)
+      block = (@_slots ||= {})[name]
+      instance_exec(&block) if block
+      nil
+    end
+
+    # --- Default children slot ---
+
+    # {content} in a .rbx template compiles to `yield` — Phlex 2.x style.
+    # This method is a no-op; the compiler special-cases the `content` identifier.
+    # Kept for documentation and as a fallback.
+    def content
+      yield
+    end
+
+    # --- Expression output ---
+
+    # Handles all { ruby_expr } in compiled templates:
+    #
+    #   render(<Comp />) already wrote to buffer → returns nil → no-op here
+    #   Array/Enumerable    → each element rendered recursively
+    #   Phlex::SafeObject   → raw()  (trusted HTML, no escaping)
+    #   nil / false / ""   → silent no-op (safe for && and || patterns)
+    #   anything else       → plain(value.to_s)  (CGI auto-escaped, XSS-safe)
+    def __rbx_expr_out(value)
+      case value
+      when nil, false, ""
+        nil  # {condition && <Foo />}: falsy short-circuit
+      when Array, Enumerable
+        # {@items.map { |i| <Item /> }}: map returns [nil,nil,...] after render→nil
+        value.each { |v| __rbx_expr_out(v) }
+      when Phlex::SGML
+        # Safety net: if a user passes a component directly (e.g. {MyComp.new})
+        # render it normally. Our render override returns nil so this branch is
+        # only hit in direct-instance-passing scenarios, not {cond && <Comp />}.
+        render(value)
+      when Phlex::SGML::SafeObject
+        raw(value)
+      else
+        plain(value.to_s)
+      end
+    end
+
+    # Explicit escape hatch for trusted HTML strings.
+    #
+    # By default, every { expression } is CGI-escaped via plain(). Use safe()
+    # when you have a string that is already HTML and must not be escaped:
+    #
+    #   {safe(@html_body)}            # raw inject
+    #   {@items.map { safe(i.html) }} # safe inside map
+    #
+    # WARNING: never pass user-supplied input to safe() — it bypasses all XSS
+    # protection. Only use for strings you have produced or sanitized yourself.
+    def safe(html_string)
+      Phlex::SGML::SafeValue.new(html_string.to_s)
+    end
+
+    # Override Phlex's render to always return nil.
+    #
+    # Phlex::SGML#render returns the component instance, which would cause
+    # __rbx_expr_out to see a Phlex::SGML and call render() a second time
+    # (double-render bug). Returning nil short-circuits that:
+    #
+    #   {true && <Button />}  → true && render(ButtonComponent.new)  → nil
+    #                            __rbx_expr_out(nil) → no-op ✓
+    #
+    #   {@items.map { |i| <Item /> }} → map returns [nil, nil, nil]
+    #                            __rbx_expr_out([nil, nil, nil]) → no-op ✓
+    def render(renderable = nil, &block)
+      super
+      nil
+    end
+
+    # Raised when a .rbx template fails to compile (syntax or parse error).
+    # Provides the source file path and the underlying error message so
+    # developers see their .rbx line rather than a grsx internal backtrace.
+    class TemplateCompileError < StandardError
+      attr_reader :template_path
+
+      def initialize(message, template_path:)
+        @template_path = template_path
+        super(message)
+      end
+    end
+
+    # --- Template loading ---
+
+    class << self
+      # Template cache: { path => { mtime: Time, code: String } }
+      TEMPLATE_CACHE = {}
+      private_constant :TEMPLATE_CACHE
+
+      def inherited(subclass)
+        # Capture the caller's file path BEFORE calling super so the stack
+        # frame is still fresh. This is more reliable than source_location
+        # because it works even when the subclass has no custom initialize.
+        defining_file = caller_locations(1, 10)
+          .find { |loc| loc.path != __FILE__ && !loc.path.end_with?("phlex_component.rb") }
+          &.path
+        subclass.instance_variable_set(:@_rbx_source_rb, defining_file)
+
+        super
+        subclass.load_rbx_template
+      end
+
+      # Locate, compile, and define view_template from the co-located .rbx file.
+      # Called once when the subclass is first defined.
+      def load_rbx_template
+        path = rbx_template_path
+        return unless path && File.exist?(path)
+
+        compiled = compile_template(path)
+        define_view_template(compiled)
+        @_rbx_template_path = path
+      end
+
+      # Recompile and redefine view_template if the .rbx file has changed.
+      # Called by Grsx::Rails::PhlexReloader on each dev request.
+      def reload_rbx_template_if_changed
+        path = @_rbx_template_path
+        return unless path
+
+        mtime = File.mtime(path)
+        cached = TEMPLATE_CACHE[path]
+        return if cached && cached[:mtime] == mtime
+
+        compiled = compile_template(path)
+        define_view_template(compiled)
+      end
+
+      # Return the path to the .rbx file for this component (nil if not found).
+      def rbx_template_path
+        @_rbx_template_path if defined?(@_rbx_template_path)
+
+        source = @_rbx_source_rb
+        return nil unless source
+
+        base = File.basename(source, ".rb")
+        dir  = File.dirname(source)
+        candidate = File.join(dir, "#{base}.rbx")
+        candidate if File.exist?(candidate)
+      end
+
+      # All known PhlexComponent subclasses, for the dev-mode reloader.
+      def all_descendants
+        ObjectSpace.each_object(Class).select { |c| c < self }
+      end
+
+      # Returns the Phlex DSL Ruby code that was compiled from the .rbx template.
+      # Useful for debugging, introspection, and writing specs that verify
+      # what the compiler generates:
+      #
+      #   puts MyCard.compiled_template_code
+      #   # ⇒ div(class: "card") do
+      #   #      plain(@title)
+      #   #    end
+      def compiled_template_code
+        path = @_rbx_template_path || rbx_template_path
+        return nil unless path
+        compile_template(path)
+      end
+
+      private
+
+      def compile_template(path)
+        content = File.read(path)
+
+        # Cache by content hash, not mtime. mtime is fragile in Docker/rsync
+        # deployments where COPY or rsync can reset timestamps to build time
+        # without changing content — or vice versa, touch the file without
+        # changing content, causing pointless recompilation.
+        #
+        # SHA256 is deterministic and correct. We truncate to 16 hex chars
+        # (64 bits of collision resistance) which is more than sufficient for
+        # a per-process in-memory cache keyed by full path.
+        hash = Digest::SHA256.hexdigest(content)[0, 16]
+        cache_key = "#{path}:#{hash}"
+
+        return TEMPLATE_CACHE[cache_key] if TEMPLATE_CACHE.key?(cache_key)
+
+        template = Grsx::Template.new(content, path)
+
+        begin
+          code = Grsx.compile(template)
+        rescue Grsx::Lexer::SyntaxError, Grsx::Parser::ParseError => e
+          raise TemplateCompileError.new(
+            "#{File.basename(path)}: #{e.message}",
+            template_path: path
+          )
+        end
+
+        TEMPLATE_CACHE[cache_key] = code
+        code
+      end
+
+      def define_view_template(compiled_code)
+        # Pass the .rbx file path and line 1 to class_eval so that Ruby's
+        # backtraces point directly to the template file when errors occur.
+        #
+        # Before: view_template defined at phlex_component.rb:233 (useless)
+        # After:  error at card_component.rbx:5:in 'view_template'
+        #
+        # @_rbx_template_path is set by load_rbx_template before we get here.
+        source_file = @_rbx_template_path || __FILE__
+        class_eval(<<~RUBY, source_file, 1)
+          def view_template
+            #{compiled_code}
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/grsx/phlex_runtime.rb

@@ -0,0 +1,70 @@
+require "phlex"
+require "phlex-rails"
+
+module Grsx
+  # A Phlex::HTML subclass that serves as the execution context for compiled
+  # .rbx templates when Grsx.configuration.render_target == :phlex.
+  #
+  # Instead of ActionView's @output_buffer, compiled Phlex-target code calls
+  # Phlex element methods directly (div, span, etc.) and renders component
+  # instances via render().
+  class PhlexRuntime < Phlex::HTML
+    # Include ALL phlex-rails helper adapters (mirrors PhlexComponent).
+    Phlex::Rails::Helpers.constants.each do |helper_name|
+      begin
+        mod = Phlex::Rails::Helpers.const_get(helper_name)
+        include mod if mod.is_a?(Module)
+      rescue NameError
+        # Skip helpers that require Rails to be fully initialized
+      end
+    end
+
+    # Called by PhlexCompiler-generated code for inline expressions: {expr}
+    #
+    #   render(<Comp />) already wrote to buffer → returns nil → no-op here
+    #   Array/Enumerable    → each element rendered recursively
+    #   Phlex::SafeObject   → raw()
+    #   nil / false / ""   → silent no-op (safe for &&, ||, ternary)
+    #   anything else      → plain(value.to_s) CGI-escaped
+    def __rbx_expr_out(value)
+      case value
+      when nil, false, ""
+        nil
+      when Array, Enumerable
+        value.each { |v| __rbx_expr_out(v) }
+      when Phlex::SGML
+        render(value)
+      when Phlex::SGML::SafeObject
+        raw(value)
+      else
+        plain(value.to_s)
+      end
+    end
+
+    # Return nil from render() so that {cond && <Comp />} doesn't double-render.
+    # The actual rendering is a side-effect on the buffer, not the return value.
+    def render(renderable = nil, &block)
+      super
+      nil
+    end
+
+    def initialize(assigns: {})
+      assigns.each { |k, v| instance_variable_set("@#{k}", v) }
+    end
+
+    def view_template(&block)
+      instance_eval(&block)
+    end
+
+    # Explicit escape hatch for trusted HTML strings (mirrors PhlexComponent#safe).
+    # WARNING: never pass user-supplied input to safe() — bypasses XSS protection.
+    def safe(html_string)
+      Phlex::SGML::SafeValue.new(html_string.to_s)
+    end
+
+    # Rails view_context is accessed via phlex-rails' context[:rails_view_context]
+    # which is set automatically during render_in. We no longer carry our own
+    # @view_context ivar or method_missing delegation — phlex-rails' SGML#method_missing
+    # provides better error hints ("Try including Phlex::Rails::Helpers::LinkTo").
+  end
+end

data/lib/grsx/prop_inspector.rb

@@ -0,0 +1,52 @@
+module Grsx
+  # Walks a compiled Phlex code string (or a Grsx AST) and collects every
+  # @ivar name referenced in the template.
+  #
+  # This powers the `props` DSL — it lets us tell the user which props are
+  # actually used in a template without requiring manual declaration.
+  #
+  # Usage:
+  #   code = Grsx.compile(template)
+  #   names = Grsx::PropInspector.scan_code(code)
+  #   # => [:title, :body, :user]
+  #
+  # Or directly from a parse tree:
+  #   root = Grsx::Parser.new(tokens).parse
+  #   names = Grsx::PropInspector.scan_tree(root)
+  #
+  class PropInspector
+    # Regex that matches @ivar names in the already-compiled Phlex code string.
+    # Matches patterns like @title, @user_name, @items123
+    IVAR_PATTERN = /@([a-z_][a-zA-Z0-9_]*)/.freeze
+
+    # Scan compiled Phlex code (a Ruby string) for @ivar references
+    # and return them as an array of symbols.
+    def self.scan_code(code)
+      code.scan(IVAR_PATTERN).map { |m| m.first.to_sym }.uniq.sort
+    end
+
+    # Recursively walk a Grsx AST root node and collect @ivar identifiers
+    # from all expression nodes. Returns a sorted, unique array of symbols.
+    def self.scan_tree(root)
+      names = []
+      walk(root, names)
+      names.sort.uniq
+    end
+
+    private_class_method def self.walk(node, names)
+      case node
+      when Nodes::Root
+        node.children.each { |c| walk(c, names) }
+      when Nodes::HTMLElement, Nodes::ComponentElement
+        node.members.each { |m| walk(m, names) }
+        (node.children || []).each { |c| walk(c, names) }
+      when Nodes::ExpressionGroup
+        node.members.each { |m| walk(m, names) }
+      when Nodes::Expression
+        node.content.scan(IVAR_PATTERN).each { |m| names << m.first.to_sym }
+      when Nodes::HTMLAttr, Nodes::ComponentProp
+        walk(node.value, names) if node.respond_to?(:value)
+      end
+    end
+  end
+end

data/lib/grsx/rails/engine.rb

@@ -0,0 +1,24 @@
+module Grsx
+  module Rails
+    class Engine < ::Rails::Engine
+      # In development, hot-reload .rbx templates for PhlexComponent subclasses
+      # on every request via a lightweight Rack middleware.
+      initializer "grsx.phlex_reloader" do |app|
+        dev_mode = if app.config.respond_to?(:enable_reloading)
+          app.config.enable_reloading
+        else
+          !app.config.cache_classes
+        end
+
+        if dev_mode
+          require "grsx/rails/phlex_reloader"
+          app.middleware.use Grsx::Rails::PhlexReloader
+        end
+
+        Grsx.configure do |config|
+          config.template_paths << ::Rails.root.join("app", "components")
+        end
+      end
+    end
+  end
+end

data/lib/grsx/rails/phlex_reloader.rb

@@ -0,0 +1,25 @@
+module Grsx
+  module Rails
+    # Rack middleware that hot-reloads .rbx templates for all known
+    # PhlexComponent subclasses on every request in development.
+    #
+    # Installed automatically by the Grsx Rails engine when
+    # config.cache_classes / config.enable_reloading indicates dev mode.
+    #
+    # You can also install it manually:
+    #
+    #   # config/application.rb
+    #   config.middleware.use Grsx::Rails::PhlexReloader
+    #
+    class PhlexReloader
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        Grsx::PhlexComponent.all_descendants.each(&:reload_rbx_template_if_changed)
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/grsx/template.rb

@@ -0,0 +1,12 @@
+module Grsx
+  class Template
+    attr_reader :source, :identifier
+
+    Anonymous = Class.new(String).new.freeze
+
+    def initialize(source, identifier = Anonymous)
+      @source = source
+      @identifier = identifier
+    end
+  end
+end

data/lib/grsx/version.rb

@@ -0,0 +1,3 @@
+module Grsx
+  VERSION = "0.1.0"
+end

data/lib/grsx.rb

@@ -0,0 +1,35 @@
+require "grsx/version"
+require "active_support/inflector"
+
+require "grsx/rails/engine" if defined?(::Rails)
+
+module Grsx
+  autoload :Lexer,          "grsx/lexer"
+  autoload :Parser,         "grsx/parser"
+  autoload :Nodes,          "grsx/nodes"
+  autoload :PhlexRuntime,   "grsx/phlex_runtime"
+  autoload :PhlexCompiler,  "grsx/phlex_compiler"
+  autoload :PhlexComponent, "grsx/phlex_component"
+  autoload :PropInspector,  "grsx/prop_inspector"
+  autoload :Configuration,  "grsx/configuration"
+  autoload :ComponentResolver, "grsx/component_resolver"
+  autoload :Template,       "grsx/template"
+
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Compile a .rbx template to Phlex DSL Ruby code.
+    # Returns a string that can be class_eval'd inside a PhlexComponent.
+    def compile(template)
+      tokens = Lexer.new(template, configuration.element_resolver).tokenize
+      root   = Parser.new(tokens).parse
+      PhlexCompiler.new(root).compile
+    end
+  end
+end