rux 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2874b5336b991b08b274df04219d2c7b97247580f0587dfc3b6860e913d8af8
-  data.tar.gz: ba582dd96d6c58da357295e60267f4db9a6cdf47ddc99aa2740d590a1cec530d
+  metadata.gz: f1e472f55eed0269091c2f5efa3a1d27fb1d16ed1959c32a84633be8b192940d
+  data.tar.gz: 46e848d6871ff5ea01638d6e50e24968ad3aa9867324580417151287ed932b3d
 SHA512:
-  metadata.gz: c6c663d6d237fb6fc044dc2ebfa9c706d54eb5cdd3bc7a50011d82578ac7aab36a8f6c1ca466754f44bfed73ce708fc57bbd0ea3951681febd79f2730e7fd1d7
-  data.tar.gz: fb52a3a10cb3db47817acc7d760210758bc733b3b74b4ebfc9d241039d8d38ce00d4622957fd26effa7593acefe4d9387ebce9bcc6bab7dd20d83e9523b62322
+  metadata.gz: 1681c3f2cedc43ee87559663ada3f92d9061ed004cb4ea100a588d847b7de3cf2e4a490ec23f5d0cd653602d3f0fee1c97045c9c786e38249663a73534ab559c
+  data.tar.gz: 94c7c21726d2b38750162fb36ceb1f8ff9321fe99425efb078b51a042568b5914e5821341bb45fa5b18f1f6df1040f2fa706edd7ce32b834207a0046e8ac0479

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 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

@@ -268,6 +268,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/version.rb

@@ -1,3 +1,3 @@
 module Rux
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 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/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.0
 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,7 @@ files:
 - lib/rux/ast/tag_node.rb
 - lib/rux/ast/text_node.rb
 - lib/rux/buffer.rb
+- lib/rux/context.rb
 - lib/rux/default_tag_builder.rb
 - lib/rux/default_visitor.rb
 - lib/rux/file.rb
@@ -96,6 +111,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