subcomponent 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e45581419c661089fedb66b9c803a42f9edc3554585c24ddc0b8fa97e26a448
+  data.tar.gz: e5863ed447bf64a00b37c50afb8d22ae68020ef3c6887f0872edcf1d42c0d463
+SHA512:
+  metadata.gz: ca8c18a231cfc387a1545e5c894903890396365d1776d6432c2d7aa702ec0e07b4e7979934476fc1b77099837349b407a5fac4888dcba4fdcd65b30c3e598d24
+  data.tar.gz: d8644df39b061f70c0213449f6b34e9b0f94f7cd69f8ecaa5b61388ca6cd9888e3e09e038b6b35c2631c5472b9f5dcaa66ffb8a399a356685623199b37fc83e1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2023 candland
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# Subcomponent
+
+When you want to create HTML simple components, using partials.
+
+## Usage
+
+Components are stored in `app/views/components` and are named `_component.html.erb`.
+They can also be stored in a subdirectory of `app/views/components` and are named using the component name for the directory and the partial `component/_component.html.erb`.
+
+Additional subcomponent partials can be included in the component directory allowing
+to break up the component into smaller pieces.
+
+### Example Simple Component
+
+Create a button component in `app/views/components/_button.html.erb`:
+```erb
+<button>
+  <%= this.text %>
+</button>
+```
+
+Use `this` to access the component instance containing locals and subcomponents.
+
+To use the component in a view:
+```erb
+<%= component :button, text: 'Click Me' %>
+```
+
+Using with the method_missing shorthand:
+```erb
+<%= button text: 'Click Me' %>
+```
+
+Locals can also be set within the component block:
+```erb
+<%= component :button do |c| %>
+  <% c.text = 'Click Me' %>
+<% end %>
+```
+
+### Example Component with Subcomponents
+
+Create a card component in `app/views/components/card/_card.html.erb`:
+```erb
+<div>
+  <%= this.render :title %>
+  <%= this.text || this.yield %>
+</div>
+```
+
+Create the title subcomponent in `app/views/components/card/_title.html.erb`:
+```erb
+<h1>
+  <%= this.text %>
+</h1>
+```
+
+You can use `this.render` to render a subcomponent. The subcomponent will have access
+to the locals and subcomponents passed in the view.
+
+You can use `this.yield` to render the block passed in the view.
+
+To use the component in a view:
+```erb
+<%= component :card do |c| %>
+  <%= c.title text: 'Card Title' %>
+  <p>Card Text</p>
+<% end %>
+```
+
+This will render:
+```html
+<div>
+  <h1>Card Title</h1>
+  <p>Card Text</p>
+</div>
+```
+
+### Example Using Locals without method_missing.
+
+In some cases you may want to use a local variable that
+clashes with existing methods on `Object`. In these cases you can access
+the locals hash directly.
+```erb
+<h1>
+  <%= this.local(:method) %>
+</h1>
+```
+
+### Example Using Subcomponents without method_missing.
+
+In some cases you may want to use a subcomponent that
+clashes with existing methods on `Object`. In these cases you can access
+the subcomponents hash directly.
+```erb
+<%= this.components(:method) %>
+```
+
+This returns and Array of subcomponents. You can render the first subcomponent with
+a given key using, `this.render(:header)`.
+```erb
+<%= this.render(:header) %>
+```
+
+If you have multiple subcomponents with the same key, you can render them all using
+`this.render_all(:header)`.
+```erb
+<%= this.render_all(:header) %>
+```
+
+If you want to render all subcomponents, but with HTML between them,
+you can use `this.components(:actions)`.
+```erb
+<ul>
+<% this.components(:actions).each do |sub| %>
+  <li><%= sub.render %></li>
+<% end %>
+</ul>
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+```bash
+$ bundle add subcomponent
+```
+
+Or install it yourself as:
+```bash
+$ gem install subcomponent
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/candland/subcomponent](https://github.com/candland/subcomponent).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/helpers/component_helper.rb

@@ -0,0 +1,59 @@
+module ComponentHelper
+  # Create a component in a view.
+  #
+  # @param [Symbol] name The name of the component.
+  # @param [Hash] kwargs The locals to pass to the component.
+  # @param [Proc] block The block to pass to the component. You can use
+  # other components inside this block. You can set locals inside this
+  # block.
+  #
+  # @example
+  #
+  #  = component :header do |c|
+  #    - c.title = "Hello"
+  #    p My Extra Content
+  #
+  def component name, **kwargs, &block
+    component = Component.new(name, kwargs, lookup_context, nil, block)
+
+    component._renderer = proc do |partial, locals, captured|
+      render partial, locals do
+        captured
+      end
+    end
+
+    component._capture = proc do |component, block|
+      if block
+        capture do
+          block.call(component)
+        end
+      end
+    end
+
+    component._capture_self
+    component._yield_renderer
+  end
+
+  # Alias for component.
+  alias_method :comp, :component
+
+  # Create a component in a view with shorthand syntax.
+  # This is the same as calling component with the same arguments.
+  #
+  # @example
+  #
+  #   = header do |c|
+  #     - c.title = "Hello"
+  #
+  def method_missing symbol, *args, **kwargs, &block
+    super unless respond_to?(symbol)
+
+    component symbol, *args, **kwargs, &block
+  end
+
+  # :nodoc:
+  def respond_to_missing? symbol, *args
+    lookup_context.exists?("components/#{symbol}/#{symbol}", [], true) ||
+      lookup_context.exists?("components/#{symbol}", [], true)
+  end
+end

data/lib/subcomponent/component.rb

@@ -0,0 +1,209 @@
+class Component
+  attr_accessor :_renderer
+  attr_accessor :_capture
+
+  # Use Component::ComponentHelper to create components.
+  def initialize name, locals, lookup_context, parent, block
+    @_name = name
+    @_parent = parent
+    @_locals = locals
+    @_lookup_context = lookup_context
+    @_block = block
+
+    @_components = {}
+    @_building = false
+  end
+
+  # Specify and use local values or sub-components using method calls.
+  #
+  # == Locals
+  #
+  # @example
+  #
+  #   = component :header do |c|
+  #     c.title = "Hello"
+  #
+  # In the component:
+  #
+  # @example
+  #
+  #   = this.title
+  #
+  # @return "Hello"
+  #
+  # == Sub-components
+  #
+  # @example
+  #
+  #   = component :card do |c|
+  #     - c.header do |c|
+  #       - c.title = "Hello"
+  #
+  # In the component:
+  #
+  # @example
+  #
+  #   = this.render :header
+  #
+  #   = this.header.render
+  #
+  # @return The rendered component
+  #
+  # == Checking for locals or sub-components
+  #
+  # @example
+  #
+  #   = this.title?
+  #   = this.header?
+  #
+  # @return true or false
+  #
+  def method_missing symbol, *args, **kwargs, &block
+    # This is used when building a component
+    if _building && symbol != :to_ary
+      if symbol.ends_with?("=") && args.length == 1
+        _locals[symbol[0..-2].to_sym] = args.first
+      else
+        _components[symbol] ||= []
+
+        child = Component.new(symbol, args.first || kwargs, _lookup_context, self, block)
+        child._renderer = _renderer
+        child._capture = _capture
+        child._capture_self
+
+        _components[symbol] << child
+      end
+      nil
+
+    # This is used when rendering a component
+    elsif symbol.ends_with?("?")
+      _locals.key?(symbol[0..-2].to_sym) || _components.key?(symbol[0..-2].to_sym)
+    else
+      _locals[symbol] || _components[symbol]
+    end
+  end
+
+  # :nodoc:
+  def respond_to_missing? symbol, *args
+    if symbol != :to_ary
+      true
+    else
+      super
+    end
+  end
+
+  # This is used to require local keys or sub-components.
+  #
+  # @param [Array<Symbol>] loacl_keys
+  #
+  #   require :title, :body
+  #
+  def require *local_keys
+    missing = local_keys.reject { |k| _locals.key?(k) || _components.key?(k) }
+    if missing.count > 0
+      raise "The #{_name} component requires #{missing.join(", ")} local(s) or component(s)."
+    end
+    nil
+  end
+
+  # This is used to access sub-components passed to the component.
+  #
+  # @param [Symbol] key The name of the sub-component
+  #
+  # @example
+  #
+  #   components :header
+  #
+  #   returns: [<Component>, <Component>, ...]
+  #
+  def components key
+    _components[key] || []
+  end
+
+  # This is used to access locals passed to the component.
+  def local key
+    _locals[key]
+  end
+
+  # This is used to render a sub-component.
+  #
+  # From within a component:
+  #
+  #   this.render :header
+  #
+  # Or calling directly on a sub-component:
+  #
+  #   this.header.render
+  #
+  def render symbol = nil
+    if symbol.nil?
+      if _parent.nil?
+        raise "Cannot render a component without a symbol when it has a parent."
+      else
+        return _yield_renderer
+      end
+    end
+    _components[symbol]&.first&._yield_renderer
+  end
+
+  # Render all sub-components of a given name.
+  #
+  #   this.render_all :header
+  #
+  # Returns a string of all rednered sub-components.
+  #
+  def render_all symbol
+    _components[symbol]&.map(&:_yield_renderer)&.join&.html_safe
+  end
+
+  # Yield the block passed to the component.
+  #
+  #   this.yield
+  #
+  def yield
+    _captured
+  end
+
+  # :nodoc:
+  def _yield_renderer
+    locals = _locals.merge(this: self)
+    _renderer.call(_partial, locals, _captured)
+  end
+
+  # :nodoc:
+  def _capture_self
+    self._building = true
+    self._captured = _capture.call(self, _block)
+  ensure
+    self._building = false
+  end
+
+  protected
+
+  attr_reader :_name
+  attr_reader :_locals
+  attr_reader :_components
+  attr_reader :_block
+  attr_reader :_parent
+  attr_accessor :_captured
+  attr_reader :_lookup_context
+  attr_accessor :_building
+
+  # :nodoc:
+  def _base_name
+    on = self
+    until on._parent.nil?
+      on = on._parent
+    end
+    on._name
+  end
+
+  # :nodoc:
+  def _partial
+    @partial ||= if _lookup_context.exists?("components/#{_base_name}/#{_name}", [], true)
+      "components/#{_base_name}/#{_name}"
+    else
+      "components/#{_name}"
+    end
+  end
+end

data/lib/subcomponent/railtie.rb

@@ -0,0 +1,9 @@
+module Subcomponent
+  class Railtie < ::Rails::Railtie
+    initializer "subcomponent.helper" do
+      ActiveSupport.on_load(:action_view) do
+        include ComponentHelper
+      end
+    end
+  end
+end

data/lib/subcomponent/version.rb

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

data/lib/subcomponent.rb

@@ -0,0 +1,7 @@
+require "subcomponent/version"
+require "subcomponent/railtie"
+require "subcomponent/component"
+require_relative "../app/helpers/component_helper"
+
+module Subcomponent
+end

data/lib/tasks/subcomponent_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :subcomponent do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: subcomponent
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- candland
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Very simple parial based components.
+email:
+- candland@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/helpers/component_helper.rb
+- lib/subcomponent.rb
+- lib/subcomponent/component.rb
+- lib/subcomponent/railtie.rb
+- lib/subcomponent/version.rb
+- lib/tasks/subcomponent_tasks.rake
+homepage: https://candland.net/subcomponent
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://candland.net/subcomponent
+  source_code_uri: https://github.com/candland/subcomponent
+  changelog_uri: https://github.com/candland/subcomponent/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Very simple parial based components
+test_files: []