rhales 0.3.0

data/lib/rhales/view_composition.rb

@@ -0,0 +1,165 @@
+# lib/rhales/view_composition.rb
+
+require_relative 'rue_document'
+require_relative 'refinements/require_refinements'
+
+using Rhales::Ruequire
+
+module Rhales
+  # ViewComposition builds and represents the complete template dependency graph
+  # for a view render. It provides a data-agnostic, immutable representation
+  # of all templates (layout, view, partials) required for rendering.
+  #
+  # This class is a key component in the two-pass rendering architecture,
+  # enabling server-side data aggregation before HTML generation.
+  #
+  # Responsibilities:
+  # - Dependency Resolution: Recursively discovers and loads all partials
+  # - Structural Representation: Organizes templates into a traversable tree
+  # - Traversal Interface: Provides methods to iterate templates in render order
+  #
+  # Key Characteristics:
+  # - Data-Agnostic: Knows nothing about runtime context or request data
+  # - Immutable: Once created, the composition is read-only
+  # - Cacheable: Can be cached in production for performance
+  class ViewComposition
+    class TemplateNotFoundError < StandardError; end
+    class CircularDependencyError < StandardError; end
+
+    attr_reader :root_template_name, :templates, :dependencies
+
+    def initialize(root_template_name, loader:)
+      @root_template_name = root_template_name
+      @loader             = loader
+      @templates          = {}
+      @dependencies       = {}
+      @loading            = Set.new
+    end
+
+    # Resolve all template dependencies
+    def resolve!
+      load_template_recursive(@root_template_name)
+      freeze_composition
+      self
+    end
+
+    # Iterate through all documents in render order
+    # Layout -> View -> Partials (depth-first)
+    def each_document_in_render_order(&)
+      return enum_for(:each_document_in_render_order) unless block_given?
+
+      visited = Set.new
+
+      # Process layout first if specified
+      root_doc = @templates[@root_template_name]
+      if root_doc && root_doc.layout
+        layout_name = root_doc.layout
+        if @templates[layout_name]
+          yield_template_recursive(layout_name, visited, &)
+        end
+      end
+
+      # Then process the root template and its dependencies
+      yield_template_recursive(@root_template_name, visited, &)
+    end
+
+    # Get a specific template by name
+    def template(name)
+      @templates[name]
+    end
+
+    # Check if a template exists in the composition
+    def has_template?(name)
+      @templates.key?(name)
+    end
+
+    # Get all template names
+    def template_names
+      @templates.keys
+    end
+
+    # Get direct dependencies of a template
+    def dependencies_of(template_name)
+      @dependencies[template_name] || []
+    end
+
+    private
+
+    def load_template_recursive(template_name, parent_path = nil)
+      # Check for circular dependencies
+      if @loading.include?(template_name)
+        raise CircularDependencyError, "Circular dependency detected: #{template_name} -> #{@loading.to_a.join(' -> ')}"
+      end
+
+      # Skip if already loaded
+      return if @templates.key?(template_name)
+
+      @loading.add(template_name)
+
+      begin
+        # Load template using the provided loader
+        parser = @loader.call(template_name)
+
+        unless parser
+          raise TemplateNotFoundError, "Template not found: #{template_name}"
+        end
+
+        # Store the template
+        @templates[template_name]    = parser
+        @dependencies[template_name] = []
+
+        # Extract and load partials
+        extract_partials(parser).each do |partial_name|
+          @dependencies[template_name] << partial_name
+          load_template_recursive(partial_name, template_name)
+        end
+
+        # Load layout if specified and not already loaded
+        if parser.layout && !@templates.key?(parser.layout)
+          load_template_recursive(parser.layout, template_name)
+        end
+      ensure
+        @loading.delete(template_name)
+      end
+    end
+
+    def extract_partials(parser)
+      partials         = Set.new
+      template_content = parser.section('template')
+
+      return partials unless template_content
+
+      # Extract partial references from template
+      # Looking for {{> partial_name}} patterns
+      template_content.scan(/\{\{>\s*([^\s}]+)\s*\}\}/) do |match|
+        partials.add(match[0])
+      end
+
+      partials
+    end
+
+    def yield_template_recursive(template_name, visited, &)
+      return if visited.include?(template_name)
+
+      visited.add(template_name)
+
+      # First yield dependencies (partials)
+      (@dependencies[template_name] || []).each do |dep_name|
+        yield_template_recursive(dep_name, visited, &)
+      end
+
+      # Then yield the template itself
+      if @templates[template_name]
+        yield template_name, @templates[template_name]
+      end
+    end
+
+    def freeze_composition
+      @templates.freeze
+      @dependencies.freeze
+      @templates.each_value(&:freeze)
+      @dependencies.each_value(&:freeze)
+      freeze
+    end
+  end
+end

data/lib/rhales.rb

@@ -0,0 +1,57 @@
+# lib/rhales.rb
+
+require_relative 'rhales/version'
+require_relative 'rhales/errors'
+require_relative 'rhales/configuration'
+require_relative 'rhales/adapters/base_auth'
+require_relative 'rhales/adapters/base_session'
+require_relative 'rhales/context'
+require_relative 'rhales/rue_document'
+require_relative 'rhales/parsers/handlebars_parser'
+require_relative 'rhales/parsers/rue_format_parser'
+require_relative 'rhales/template_engine'
+require_relative 'rhales/hydrator'
+require_relative 'rhales/view_composition'
+require_relative 'rhales/hydration_data_aggregator'
+require_relative 'rhales/refinements/require_refinements'
+require_relative 'rhales/view'
+
+# Ruby Single File Components (RSFC)
+#
+# A framework for building server-rendered components with client-side hydration
+# using .rue files (Ruby Single File Components). Similar to .vue files but for Ruby.
+#
+# Features:
+# - Server-side template rendering with Handlebars-style syntax
+# - Client-side data hydration with JSON injection
+# - Partial support for component composition
+# - Pluggable authentication and session adapters
+# - Security-first design with XSS protection and CSP support
+#
+# Usage:
+#   Rhales.configure do |config|
+#     config.default_localhas_role?e = 'en'
+#     config.template_paths = ['app/templates']
+#     config.features = { dark_mode: true }
+#   end
+#
+#   view = Rhales::View.new(request, session, user)
+#   html = view.render('my_component')
+module Rhales
+  # Convenience method to create a view with props
+  def self.render(template_name, request: nil, session: nil, user: nil, locale: nil, **props)
+    view = View.new(request, session, user, locale, props: props)
+    view.render(template_name)
+  end
+
+  # Quick template rendering for testing/simple use cases
+  def self.render_template(template_content, context_data = {})
+    context = Context.minimal(props: context_data)
+    TemplateEngine.render(template_content, context)
+  end
+
+  # Create context with props (for advanced usage)
+  def self.create_context(request: nil, session: nil, user: nil, locale: nil, **props)
+    Context.for_view(request, session, user, locale, **props)
+  end
+end

data/rhales.gemspec

@@ -0,0 +1,46 @@
+# rhales.gemspec
+
+require_relative 'lib/rhales/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'rhales'
+  spec.version       = Rhales::VERSION
+  spec.authors       = ['delano']
+  spec.email         = ['gems@onetimesecret.com']
+
+  spec.summary       = 'Rhales - Server-rendered components with client-side hydration (RSFCs)'
+  spec.description   = <<~DESC
+    Rhales is a framework for building server-rendered components with
+    client-side data hydration using .rue files called RSFCs (Ruby
+    Single File Components). Similar to Vue.js single file components
+    but for server-side Ruby applications.
+
+    Features include Handlebars-style templating, JSON data injection, partial support,
+    pluggable authentication adapters, and security-first design.
+  DESC
+
+  spec.homepage              = 'https://github.com/onetimesecret/rhales'
+  spec.license               = 'MIT'
+  spec.required_ruby_version = '>= 3.4.0'
+
+
+  spec.metadata['source_code_uri']       = 'https://github.com/onetimesecret/rhales'
+  spec.metadata['changelog_uri']         = 'https://github.com/onetimesecret/rhales/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri']     = 'https://github.com/onetimesecret/rhales/blob/main/README.md'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem
+  spec.files = Dir.chdir(__dir__) do
+    Dir['{lib}/**/*', '*.md', '*.txt', '*.gemspec'].select { |f| File.file?(f) }
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  # (none currently - all parsing is done with manual recursive descent parsers)
+
+  # Development dependencies should be specified in Gemfile instead of gemspec
+  # See: https://bundler.io/guides/creating_gem.html#testing-our-gem
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: rhales
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- delano
+bindir: exe
+cert_chain: []
+date: 2025-07-09 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Rhales is a framework for building server-rendered components with
+  client-side data hydration using .rue files called RSFCs (Ruby
+  Single File Components). Similar to Vue.js single file components
+  but for server-side Ruby applications.
+
+  Features include Handlebars-style templating, JSON data injection, partial support,
+  pluggable authentication adapters, and security-first design.
+email:
+- gems@onetimesecret.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CLAUDE.locale.txt
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- lib/rhales.rb
+- lib/rhales/adapters/base_auth.rb
+- lib/rhales/adapters/base_request.rb
+- lib/rhales/adapters/base_session.rb
+- lib/rhales/configuration.rb
+- lib/rhales/context.rb
+- lib/rhales/csp.rb
+- lib/rhales/errors.rb
+- lib/rhales/errors/hydration_collision_error.rb
+- lib/rhales/hydration_data_aggregator.rb
+- lib/rhales/hydration_registry.rb
+- lib/rhales/hydrator.rb
+- lib/rhales/parsers/handlebars-grammar-review.txt
+- lib/rhales/parsers/handlebars_parser.rb
+- lib/rhales/parsers/rue_format_parser.rb
+- lib/rhales/refinements/require_refinements.rb
+- lib/rhales/rue_document.rb
+- lib/rhales/template_engine.rb
+- lib/rhales/tilt.rb
+- lib/rhales/version.rb
+- lib/rhales/view.rb
+- lib/rhales/view_composition.rb
+- rhales.gemspec
+homepage: https://github.com/onetimesecret/rhales
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/onetimesecret/rhales
+  changelog_uri: https://github.com/onetimesecret/rhales/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/onetimesecret/rhales/blob/main/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Rhales - Server-rendered components with client-side hydration (RSFCs)
+test_files: []