rux 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2874b5336b991b08b274df04219d2c7b97247580f0587dfc3b6860e913d8af8
-  data.tar.gz: ba582dd96d6c58da357295e60267f4db9a6cdf47ddc99aa2740d590a1cec530d
+  metadata.gz: 2418beae606c99c851a3000546d6fffe20fb30e02049b41a2c2cbd8ecae427dc
+  data.tar.gz: 974fc8d3502737b5737f30b07c818e04918eb55b9693ea8b3d5ef629a71a1dc6
 SHA512:
-  metadata.gz: c6c663d6d237fb6fc044dc2ebfa9c706d54eb5cdd3bc7a50011d82578ac7aab36a8f6c1ca466754f44bfed73ce708fc57bbd0ea3951681febd79f2730e7fd1d7
-  data.tar.gz: fb52a3a10cb3db47817acc7d760210758bc733b3b74b4ebfc9d241039d8d38ce00d4622957fd26effa7593acefe4d9387ebce9bcc6bab7dd20d83e9523b62322
+  metadata.gz: b6ba53663a7d8fb7195962d37586beee45a9ea97f1fcbc73b0366f68c640e54ae8f11a0daafee299500c84c06526d9683ad0bb09a065f929b43096eaaae77c9d
+  data.tar.gz: d25ada54406d57355e85d6824ab2ac2141771e613aa9a7dabfc24f7e2732124a4e369bca0fd61025248b0661c8e80183f0016c04480253870cc3fe2f94afcb9c

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 1.4.1
+* Fix bug preventing use of curly brace-delimited block syntax, eg. `[1, 2].each { ... }`.
+
+# 1.4.0
+* Implement React-style contexts for passing arguments across arbitrary levels of component nesting.
+  - Define a new context via `Rux.create_context`.
+  - Read that context later via `Rux.use_context`.
+
 # 1.3.0
 * Automatically add generated files to an ignore file, eg. .gitignore.
   - Pass the --ignore-path=PATH flag to ruxc to indicate the file to update.

data/README.md

@@ -2,6 +2,8 @@
 
 ![Unit Tests](https://github.com/camertron/rux/actions/workflows/unit_tests.yml/badge.svg?branch=master)
 
+/rʌks/, rhymes with "ducks" and "trucks"
+
 Rux is a JSX-inspired way to write HTML tags in your Ruby code. It can be used to render view components in Rails via the [rux-rails gem](https://github.com/camertron/rux-rails). This repo however contains only the rux parser itself.
 
 ## Introduction
@@ -268,6 +270,51 @@ Notice that the rux attribute "first-name" is passed to `MyComponent#initialize`
 
 Attributes on regular tags, i.e. non-component tags like `<div>` and `<span>`, are not modified. In other words, `<div data-foo="foo">` does _not_ become `<div data_foo="foo">` because that would be very annoying.
 
+## Context
+
+Occasionally you might find it necessary to pass values across multiple component boundaries. A grandparent component might want to pass values to its grandchildren but not the parent components (i.e. the grandparent's direct children).
+
+For example, imagine you'd like to support multiple themes on your website, like dark and light mode. While it would be possible to add a `theme:` argument to all your components, doing so could be quite invasive - you'd have to modify every single one.
+
+Contexts are modeled after the React concept by the same name. They allow you to set values at one level of the component hierarchy and consume them at a deeper one, without having to pass the values through every intermediate level.
+
+First, create a new context, passing an optional default value or default block. Note that the value stored in a context can be anything, i.e. any Ruby object.
+
+```ruby
+# with a default value
+ThemeContext = Rux.create_context("dark")
+
+# with a default block
+ThemeContext = Rux.create_context { "dark" }
+```
+
+NOTE: passing a default block takes precedence over default values. In other words, if you pass both an argument _and_ a block to `create_context`, only the block will be used to produce default values.
+
+The `create_context` method returns a component class. Rux requires that all components start with an uppercase letter, i.e. be a Ruby constant, which is why we assigned it to the `ThemeContext` constant in the example above. You can now render the context component like you would any other component:
+
+```ruby
+<ThemeContext value="light">
+  <Heading>Welcome!</Heading>
+  <WelcomePage />
+</ThemeContext>
+```
+
+Now that we've defined a context and rendered it, any component rendered inside `ThemeContext` (i.e. any of its children) can access the context like this:
+
+```ruby
+class WelcomePage < ViewComponent::Base
+  def call
+    theme = Rux.use_context(ThemeContext)
+
+    <div>
+      <h2 style={theme == "dark" ? "color: #FFF" : "color: #000"}>
+        Welcome to my site!
+      </h2>
+    </div>
+  end
+end
+```
+
 ## How it Works
 
 Translating rux code (Ruby + HTML tags) into Ruby code happens in three phases: lexing, parsing, and emitting. The lexer phase is implemented as a wrapper around the lexer from the [Parser gem](https://github.com/whitequark/parser) that looks for specific patterns in the token stream. When it finds an opening HTML tag, it hands off lexing to the rux lexer. When the tag ends, the lexer continues emitting Ruby tokens, and so on.

data/lib/rux/context.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "use_context"
+require "securerandom"
+
+module Rux
+  class ContextBase
+    include UseContext::ContextMethods
+
+    class << self
+      attr_accessor :default_value, :default_value_block
+
+      def context_key
+        @context_key ||= "#{context_name}_context"
+      end
+
+      def context_name
+        @context_name ||= self.name || SecureRandom.hex
+      end
+    end
+
+    attr_reader :value
+
+    def initialize(**kwargs)
+      if kwargs.include?(:value)
+        @value = kwargs[:value]
+      else
+        @value = if self.class.default_value_block
+          self.class.default_value_block.call
+        else
+          self.class.default_value
+        end
+      end
+    end
+
+    def render_in(_view_context, &block)
+      provide_context(self.class.context_key, { value: value }) do
+        block.call if block
+      end
+    end
+  end
+
+  module Context
+    class << self
+      include UseContext::ContextMethods
+
+      def create(default_value = nil, &default_value_block)
+        Class.new(ContextBase).tap do |klass|
+          klass.default_value = default_value
+          klass.default_value_block = default_value_block
+        end
+      end
+
+      def use(context_class)
+        use_context(context_class.context_key, :value)
+      end
+    end
+  end
+end

data/lib/rux/debug_lexer.rb

@@ -0,0 +1,23 @@
+module Rux
+  class DebugLexer
+    def initialize(...)
+      @lexer = Lexer.new(...)
+      @tokens = @lexer.to_a
+      @counter = -1
+    end
+
+    def source_buffer
+      @lexer.source_buffer
+    end
+
+    def advance
+      @counter += 1
+
+      if @counter >= @tokens.size
+        [nil, ['$eof']]
+      else
+        @tokens[@counter]
+      end
+    end
+  end
+end

data/lib/rux/parser.rb

@@ -19,7 +19,12 @@ module Rux
       private
 
       def make_lexer(buffer)
-        ::Rux::Lexer.new(buffer)
+        if ENV["RUX_DEBUG"]
+          require "rux/debug_lexer"
+          ::Rux::DebugLexer.new(buffer)
+        else
+          ::Rux::Lexer.new(buffer)
+        end
       end
     end
 
@@ -50,19 +55,21 @@ module Rux
             curlies -= 1
         end
 
-        break if curlies == 0
-
         if rb = ruby
           children << rb
         elsif type_of(current) == :tRUX_TAG_OPEN_START
           children << tag
         elsif type_of(current) == :tRUX_FRAGMENT_OPEN
           children << fragment
+        elsif type_of(current) == :tRUX_LITERAL_RUBY_CODE_END
+          # do nothing - let #literal_ruby_code consume the end token
         else
           raise UnexpectedTokenError,
             'expected ruby code or the start of a rux tag but found '\
               "#{type_of(current)} instead"
         end
+
+        break if curlies == 0
       end
 
       AST::ListNode.new(children)
@@ -306,7 +313,7 @@ module Rux
     def consume(*types)
       if !types.include?(type_of(current))
         raise UnexpectedTokenError,
-          "expected [#{types.map(&:to_s).join(', ')}], got '#{type_of(current)}'"
+          "expected [#{types.map(&:to_s).join(', ')}], got '#{type_of(current)}' at #{pos_of(current)}"
       end
 
       @current = get_next

data/lib/rux/version.rb

@@ -1,3 +1,3 @@
 module Rux
-  VERSION = '1.3.0'
+  VERSION = '1.4.1'
 end

data/lib/rux.rb

@@ -20,6 +20,7 @@ module Rux
   autoload :AST,               'rux/ast'
   autoload :Buffer,            'rux/buffer'
   autoload :Component,         'rux/component'
+  autoload :Context,           'rux/context'
   autoload :DefaultTagBuilder, 'rux/default_tag_builder'
   autoload :DefaultVisitor,    'rux/default_visitor'
   autoload :File,              'rux/file'
@@ -65,6 +66,14 @@ module Rux
     def library_paths
       @library_paths ||= []
     end
+
+    def create_context(...)
+      Rux::Context.create(...)
+    end
+
+    def use_context(...)
+      Rux::Context.use(...)
+    end
   end
 
   self.tag_builder = self.default_tag_builder

data/rux.gemspec

@@ -13,6 +13,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'onload', '~> 1.1'
   s.add_dependency 'parser', '~> 3.0'
   s.add_dependency 'unparser', '~> 0.8'
+  s.add_dependency 'use_context', '~> 1.2'
 
   s.require_path = 'lib'
   s.executables << 'ruxc'

data/spec/context_spec.rb

@@ -0,0 +1,84 @@
+require 'spec_helper'
+
+describe 'context', type: :render do
+  FooContext = Rux.create_context("foo")
+  FooContextWithBlock = Rux.create_context { "foo from block" }
+
+  class FooComponent < ViewComponent::Base
+    def call
+      context = Rux.use_context(FooContext)
+      Rux::SafeString.new("<p>#{context}</p>")
+    end
+  end
+
+  class FooComponentWithBlock < ViewComponent::Base
+    def call
+      context = Rux.use_context(FooContextWithBlock)
+      Rux::SafeString.new("<p>#{context}</p>")
+    end
+  end
+
+  describe '#context_key' do
+    it 'uses the class name in the key' do
+      expect(FooContext.context_key).to eq("FooContext_context")
+      expect(FooContextWithBlock.context_key).to eq("FooContextWithBlock_context")
+    end
+
+    it "uses a random ID if the class doesn't have a name" do
+      no_name = Rux.create_context
+      expect(no_name.context_key).to match(/[a-f0-9-]{32}_context/)
+    end
+
+    it 'returns the same value when called multiple times' do
+      no_name = Rux.create_context
+      key = no_name.context_key
+      expect(no_name.context_key).to eq(key)
+    end
+  end
+
+  describe 'rendering' do
+    it 'uses the given context value' do
+      result = render(<<~RUX)
+        <FooContext value="bar">
+          <FooComponent />
+        </FooContext>
+      RUX
+
+      expect(result).to eq("<p>bar</p>")
+    end
+
+    it 'uses the default value when no value is provided' do
+      result = render(<<~RUX)
+        <FooContext>
+          <FooComponent />
+        </FooContext>
+      RUX
+
+      expect(result).to eq("<p>foo</p>")
+    end
+
+    it 'calls the default block when provided' do
+      result = render(<<~RUX)
+        <FooContextWithBlock>
+          <FooComponentWithBlock />
+        </FooContextWithBlock>
+      RUX
+
+      expect(result).to eq("<p>foo from block</p>")
+    end
+
+    it 'allows context to be temporarily overridden' do
+      result = render(<<~RUX)
+        <FooContext value="bar">
+          <FooComponent />
+          <FooContext value="baz">
+            <FooComponent />
+          </FooContext>
+          <FooComponent />
+        </FooContext>
+      RUX
+
+      expect(result).to eq("<p>bar</p><p>baz</p><p>bar</p>")
+    end
+  end
+end

data/spec/render_spec.rb

@@ -25,6 +25,24 @@ describe 'rendering', type: :render do
     expect(result).to eq("<div><p>Welcome!</p><p>Welcome!</p><p>Welcome!</p></div>")
   end
 
+  it 'handles curly brace block syntax' do
+    result = render(<<~RUBY)
+      [1, 2, 3].map { |i| <div>{i}</div> }
+    RUBY
+
+    expect(result).to eq(["<div>1</div>", "<div>2</div>", "<div>3</div>"])
+  end
+
+  it 'handles curly brace block syntax with wrapping tag' do
+    result = render(<<~RUBY)
+      <span>
+        {[1, 2, 3].map { |i| <div>{i}</div> }}
+      </span>
+    RUBY
+
+    expect(result).to eq("<span><div>1</div><div>2</div><div>3</div></span>")
+  end
+
   it 'correctly handles keyword arguments (ruby 3)' do
     result = render(<<~RUBY)
       <ArgsComponent a="a" b="b" />

data/spec/support/view_component/base.rb

@@ -7,8 +7,7 @@ module ViewComponent
     end
 
     def to_s
-      @component_instance.content = @content_block.call(@component_instance) if @content_block
-      @component_instance.call
+      @component_instance.render_in(nil, &@content_block)
     end
   end
 
@@ -40,14 +39,18 @@ module ViewComponent
       end
     end
 
-    attr_accessor :content
-
     def render(component, &block)
-      if block
-        component.content = block.call(component)
-      end
+      component.render_in(nil, &block)
+    end
+
+    def render_in(_view_context, &block)
+      @content_block = block
+      content  # fill in slots
+      call
+    end
 
-      component.call
+    def content
+      @content ||= @content_block&.call(self)
     end
 
     private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rux
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Cameron Dutro
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: use_context
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 description: A jsx-inspired way to write view components.
 email:
 - camertron@gmail.com
@@ -80,6 +94,8 @@ files:
 - lib/rux/ast/tag_node.rb
 - lib/rux/ast/text_node.rb
 - lib/rux/buffer.rb
+- lib/rux/context.rb
+- lib/rux/debug_lexer.rb
 - lib/rux/default_tag_builder.rb
 - lib/rux/default_visitor.rb
 - lib/rux/file.rb
@@ -96,6 +112,7 @@ files:
 - lib/rux/version.rb
 - lib/rux/visitor.rb
 - rux.gemspec
+- spec/context_spec.rb
 - spec/parser/attributes_spec.rb
 - spec/parser/fragment_spec.rb
 - spec/parser/html_safety_spec.rb