vc_shortcut 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 121fe909a048b53b9e19a3add48e31fd050563cfd73aedcc58d4783b3326c8c3
+  data.tar.gz: 9c71c7101640ec293254a719734cf0cf635687827ad819d77a4fa8fbb679b8e9
+SHA512:
+  metadata.gz: 1b58829cf8e0cda1a48130d87c1b35fa5708761afe9d9e6316cc072c22205797480c5a970bd2f1d3c7bf4661bb650e55060c7237613cc47f9688d1e5941ce52e
+  data.tar.gz: 46a9011945220b5e4eec8deab64fd3b2ef7774882b7a4a963e4e0cd2b9300f5555dd87e210a1960c4ec9ff1dd5e6523b73de5c3fe2924ca21abadc17ecbd6c94

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Owais
+
+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,218 @@
+# VcShortcut Gem
+
+VcShortcut simplifies the API for rendering [ViewComponent](https://viewcomponent.org/)s and [Phlex](https://www.phlex.fun/) components in Ruby on Rails applications, reducing verbosity and streamlining component usage.
+
+It also features caching for lookups, ensuring that it operates with minimal overhead and maximal speed.
+
+```erb
+<%# Instead of: %>
+<%= render Admin::Dashboard::TabsComponent.new(style: :compact) do |tabs| %>
+  <% tabs.with_tab('Sales') { ... } %>
+  <% tabs.with_divider %>
+  <% tabs.with_tab('Settings') { ... } %>
+<% end %>
+<%= render ButtonComponent.new('Sign up', '/sign_up') %>
+<%= render Wysiwyg::Toolbar::FontSelectComponent.new %>
+
+<%# You can now also do: %>
+<%= vc.button('Sign up', '/sign_up') %>
+<%= vc.wysiwyg.toolbar.font_select %>
+<%= vc.admin.dashboard.tabs(style: :compact) do |tabs| %>
+  <% tabs.with_tab('Sales') { ... } %>
+  <% tabs.with_divider %>
+  <% tabs.with_tab('Settings') { ... } %>
+<% end %>
+```
+
+It works out of the box with just a `bundle add vc_shortcut`, and is also highly customizable.
+
+By default, two shortcuts are set up: `vc` for rendering and `vci` for instantiating components. You can change the shortcut prefix.
+
+For more advanced use-cases, it also allows you to change the lookup logic as well as setup custom shortcuts.
+
+## Installation
+
+Add `vc_shortcut` to your Gemfile:
+
+```shell
+bundle add vc_shortcut
+```
+
+## Usage
+
+If you're using ViewComponent or Phlex in your Rails app and your component class names end with `Component` or `::Component` (which should be the standard), there's nothing else you need to do.
+
+By default, two shortcuts are set up: `vc` for rendering and `vci` for instantiating components.
+
+You can start using these helpers from any views or from your components.
+
+#### Example:
+
+```ruby
+### Instead of:
+render Wysiwyg::UploadFieldComponent.new(limit: 50.megabytes) do |upload_field|
+  upload_field.with_footer do
+      render IconComponent.new('file')
+  end
+end
+### You can now also do:
+vc.wysiwyg.upload_field(limit: 50.megabytes) do |upload_field|
+  upload_field.with_footer do
+    vc.icon('file')
+  end
+end
+
+### Instead of:
+instance = ProgressBarComponent.new(progress: 75)
+### You can now also do:
+instance = vci.progress_bar(progress: 75)
+```
+
+<br/>
+<br/>
+
+## Interested in a powerful Rails UI library?
+
+I am working on a super-powerful Rails UI library - components as well as templates & patterns.
+
+[Please check this out if you're interested](https://owaiskhan.me/rails-ui-library).
+<br/>
+<br/>
+<br/>
+
+## Advanced
+
+You can customize things by creating an initializer file at `config/initializers/vc_shortcut.rb`.
+
+#### Customize name of default shortcuts
+
+You can rename the default shortcuts or disable them entirely:
+
+```ruby
+# In config/initializers/vc_shortcut.rb:
+VcShortcut.render_shortcut      = :vc  # Or whatever you prefer
+VcShortcut.instantiate_shortcut = :vci # Or whatever you prefer
+```
+
+You can disable a shortcut by setting its value to `false`.
+
+#### Custom Component Lookup
+
+By default, we assume your component class names end with `Component` or `::Component`, which is the standard and should cover the majority of cases.
+
+However, if you're doing something non-standard, you can customize the logic that finds a component:
+
+```ruby
+# In config/initializers/vc_shortcut.rb:
+VcShortcut.find_component = ->(camelized_name) {
+  "#{camelized_name}Component".safe_constantize || "#{camelized_name}::Component".safe_constantize
+}
+```
+
+For example, if all your components are namespaced under `Polaris` and are suffixed with `Primitive` instead of `Component`, you can set:
+```ruby
+# In config/initializers/vc_shortcut.rb:
+VcShortcut.find_component = ->(camelized_name) {
+  "Polaris::#{camelized_name}Primitive".safe_constantize
+}
+## So instead of:
+#   `render Polaris::Admin::NavbarPrimitive.new`
+#  You can now also do:
+#   `vc.admin.navbar`
+```
+
+## Super Advanced
+
+You can take customization one level further if needed:
+
+#### Registering Additional Custom Shortcuts
+
+```ruby
+# In config/initializers/vc_shortcut.rb:
+VcShortcut.register :admin,
+  find_component: ->(camelized_name) {
+    "Ui::Admin::#{camelized_name}::Component".safe_constantize
+  },
+  process: ->(context) {
+    context.view_context.render(
+      context.component.new(*context.call_args, **context.call_kwargs),
+      &context.call_block
+    )
+  }
+## So instead of:
+#   `render Ui::Admin::Navbar::Component.new`
+#  You can now also do:
+#   `admin.navbar`
+```
+
+#### Taking Full Control
+
+You can customize the find process even more by specifying `find` instead of `find_component`:
+
+```ruby
+# In config/initializers/vc_shortcut.rb:
+VcShortcut.register :admin,
+  find: ->(context) {
+    # If you return :has_more, we'll assume there's another component coming up in the chain.
+    # If you return a non-nil value, we'll assume this is the leaf component and move on to call `process`.
+    # If you return nil, we'll assume nothing was found for the given chain and raise an error.
+    chain_camelized = context.chain_camelized
+    component = "Ui::#{chain_camelized}::Component".safe_constantize
+    next component if component
+    :has_more if chain_camelized.safe_constantize
+  },
+  process: ->(context) {
+    context.view_context.render(
+      context.component.new(*context.call_args, **context.call_kwargs),
+      &context.call_block
+    )
+  }
+## So instead of:
+#   `render Ui::Admin::Navbar::Component.new`
+#  You can now also do:
+#   `admin.navbar`
+```
+
+The return value of the `register` call is a module that you can include in places where you wish to make the helper available. It's, however, automatically included for all your views, view components, and phlex components.
+
+#### What is `context` in the above examples?
+
+`context` is provided to the `find` and `process` proc. It's an object that responds to the following methods:
+
+##### 1. `context.chain`:
+Chain until now. E.g., if you call `vc.admin.button`:
+* When processing :admin, chain will be [:admin].
+* Then, when processing :button, chain will be [:admin, :button].
+
+##### 2. `context.chain_camelized`:
+Just does `context.chain.join('/').camelize`. So, if chain was [:admin, :buttton], it'd return `Admin::Button`.
+
+##### 3. `context.component`:
+Only set when called in the `process` proc. It is the component returned by the `find` or `find_component` proc.
+
+##### 4. `context.call_args` `context.call_kwargs`, `context.call_block`:
+Only set when called in the `process` proc. These are the arguments used when calling the shortcut. E.g.:
+```ruby
+vc.admin.navbar('Treact', size: :sm, style: :compact) do |navbar|
+  navbar.with_menu_item(...)
+end
+```
+Here, `context.call_args` will be `['Treact']`, `context.call_kwargs` will be `{ size: :sm, style: :compact }` and `context.call_block` will be the block above.
+
+##### 5. `context.view_context`:
+
+The view context when the shortcut was called. You can use it to render the component. E.g.:
+
+```ruby
+instance = context.component.new(*context.call_args, **context.call_kwargs)
+html = context.view_context.render(instance, &context.call_block)
+```
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## 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/lib/vc_shortcut/chain_context.rb

@@ -0,0 +1,30 @@
+module VcShortcut
+  class ChainContext
+    # The view_context (e.g an ActionView::Base or a ViewComponent instance)
+    attr_reader :view_context
+
+    # Chain until now. E.g if you call vc.admin.button
+    # When processing :admin, chain will be [:admin]
+    # Then, when processing :button, chain will be [:admin, :button]
+    attr_reader :chain
+
+    # The leaf component found by the `find` proc when registering a shortcut
+    attr_accessor :component
+
+    # Arguments for the leaf component
+    attr_accessor :call_args, :call_kwargs, :call_block
+
+    def initialize(view_context)
+      @view_context = view_context
+      @chain = []
+      @component = nil
+      @call_args = []
+      @call_kwargs = {}
+      @call_block = nil
+    end
+
+    def chain_camelized(rindex = -1)
+      @chain[0..rindex].join('/').camelize
+    end
+  end
+end

data/lib/vc_shortcut/chain_manager.rb

@@ -0,0 +1,45 @@
+module VcShortcut
+  class ChainManager
+    TREE = {}
+
+    def initialize(shortcut, process, find, view_context)
+      @tree = TREE[shortcut] ||= {}
+      @process = process
+      @find = find
+      @context = ChainContext.new(view_context)
+    end
+
+    def method_missing(method, *args, **kwargs, &block)
+      @context.chain << method
+
+      # If we haven't seen this path before, let's attempt constantization
+      if @tree[method].nil?
+        result = @find.call(@context)
+
+        if result == :has_more
+          # We matched with a module
+          @tree[method] = {}
+        elsif result
+          # We matched with a leaf
+          @tree[method] = result
+        else
+          raise NameError, "Cannot find a component or module matching. Chain: #{@context.chain.join('.')}"
+        end
+      end
+
+      leaf_or_subtree = @tree[method]
+      # We are at a module. Continue chaining
+      if leaf_or_subtree.is_a?(Hash)
+        @tree = leaf_or_subtree
+        return self
+      end
+
+      # Otherwise, we are at the leaf node (i.e a component)
+      @context.component = leaf_or_subtree
+      @context.call_args = args
+      @context.call_kwargs = kwargs
+      @context.call_block = block
+      @process.call(@context)
+    end
+  end
+end

data/lib/vc_shortcut/railtie.rb

@@ -0,0 +1,32 @@
+module VcShortcut
+  class Railtie < ::Rails::Railtie
+    initializer :vc_shortcut do
+      config.after_initialize do
+        VcShortcut.define_render_shortcut
+        VcShortcut.define_instantiate_shortcut
+      end
+
+      config.to_prepare do
+        VcShortcut::ChainManager::TREE.clear
+      end
+    end
+
+  end
+
+  def self.define_render_shortcut
+    return unless VcShortcut.render_shortcut
+
+    VcShortcut.register(VcShortcut.render_shortcut,
+      process: ->(context) { context.view_context.render(context.component.new(*context.call_args, **context.call_kwargs), &context.call_block) }
+    )
+  end
+
+
+  def self.define_instantiate_shortcut
+    return unless VcShortcut.instantiate_shortcut
+
+    VcShortcut.register(VcShortcut.instantiate_shortcut,
+      process: ->(context) { context.component.new(*context.call_args, **context.call_kwargs) }
+    )
+  end
+end

data/lib/vc_shortcut/register.rb

@@ -0,0 +1,53 @@
+module VcShortcut
+  # @param [Symbol] shortcut          What the shortcut helper is going to be called by
+  #
+  # @param [Proc]   process           Proc to process what to do with the leaf component. E.g instantiating a new class or rendering a component.
+  #                                   It's invoked with a single arguments: An instance of VcHelper::Context. See it's doc for what's available.
+  #
+  # @param [Proc]   find_component    Proc to find the component class given the current camelized name
+  #                                   Lower level than find. If you supply find_component, you shouldn't supply find.
+  #                                   And vice-versa.
+  #
+  # @param [Proc]   find              Proc to find the component class given the current chain
+  #                                   Optional. If you don't pass it, we'll try to camelize the chain, and try finding a component or module.
+  #                                   You might want to define this if you have got some custom lookup logic.
+  #                                   It's invoked with a single argument: An instance of VcHelper::Context. See it's doc for what's available
+  #                                   If you return :has_more, we'll assume there's another component coming up in the chain
+  #                                   If you return a non-nil value, we'll assume this is the leaf component.
+  #                                   If you return nil, we'll assume we couldn't find any component for the given chain and raise an error
+  #
+  def self.register(shortcut, process:, find_component: nil, find: nil)
+    raise "You should only provide either find_component: or find:. Not both" if find_component && find
+    find_component ||= VcShortcut.find_component
+    find ||= ->(context)  {
+      chain_camelized = context.chain_camelized
+      component = find_component.call(chain_camelized)
+      next component if component
+      :has_more if chain_camelized.safe_constantize
+    }
+
+    helper_module = Module.new do
+      define_method(shortcut) do |view_context = nil|
+        ChainManager.new(shortcut, process, find, view_context || self)
+      end
+    end
+
+    ActiveSupport.on_load(:action_view) do
+      include helper_module
+    end
+
+    ViewComponent::Base.class_eval do
+      define_method(shortcut) do
+        helpers.send(shortcut, self)
+      end
+    end if defined?(ViewComponent::Base)
+
+    Phlex::HTML.class_eval do
+      define_method(shortcut) do
+        helpers.send(shortcut, self)
+      end
+    end if defined?(Phlex::HTML)
+
+    helper_module
+  end
+end

data/lib/vc_shortcut/version.rb

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

data/lib/vc_shortcut.rb

@@ -0,0 +1,18 @@
+require "vc_shortcut/version"
+require "vc_shortcut/chain_context"
+require "vc_shortcut/chain_manager"
+require "vc_shortcut/register"
+require "vc_shortcut/railtie"
+
+module VcShortcut
+  # If you've got a custom/non-standard lookup logic for you components, you can define that here.
+  mattr_accessor :find_component, default: ->(camelized_name) {
+    "#{camelized_name}Component".safe_constantize || "#{camelized_name}::Component".safe_constantize  || (defined?(Phlex::HTML) && "#{camelized_name}View".safe_constantize)
+  }
+
+  # Configures the name of the shortcut for rendering a component. You can set it to false if you don't want to define one by default
+  mattr_accessor :render_shortcut, default: :vc
+
+  # Configures the name of the shortcut for instantiating a component. You can set it to false if you don't want to define one by default
+  mattr_accessor :instantiate_shortcut, default: :vci
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: vc_shortcut
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Owais
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: A simpler and less verbose-y way to render view_components
+email:
+- owaiswiz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/vc_shortcut.rb
+- lib/vc_shortcut/chain_context.rb
+- lib/vc_shortcut/chain_manager.rb
+- lib/vc_shortcut/railtie.rb
+- lib/vc_shortcut/register.rb
+- lib/vc_shortcut/version.rb
+homepage: https://github.com/owaiswiz/vc_shortcut
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/owaiswiz/vc_shortcut
+  source_code_uri: https://github.com/owaiswiz/vc_shortcut
+  changelog_uri: https://github.com/owaiswiz/vc_shortcut/releases
+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.4.10
+signing_key:
+specification_version: 4
+summary: A simpler and less verbose-y way to render view_components
+test_files: []