Add options contexts to set conventions for more involved definitions

README.md

@@ -29,6 +29,31 @@ Which will then render the following:
 
 ![](/readme/example.png?raw=true "Showcase showing a button component")
 
+## Using options contexts
+
+Showcase also supports custom options contexts. They're useful for cases where the options have a very specific format and it would be nice to keep them standardized.
+
+By default, Showcase ships Nice Partials and Stimulus contexts out of the box. Here's a sample of the Stimulus one:
+
+```erb
+<% showcase.options.stimulus controller: :welcome do |o| %>
+  <% o.optional.targets :greeter, "If the id of the target element must be printed" %>
+<% end %>
+```
+
+In case Showcase didn't ship with a Stimulus context, here's how you could add it:
+
+```ruby
+# config/initializers/showcase.rb
+if defined?(Showcase)
+  Showcase.options.define :stimulus do
+    def targets(name, ...)
+      option(%(data-#{@controller}-target="#{name}"), ...)
+    end
+  end
+end
+```
+
 ## Automatic integration testing
 
 Showcase automatically runs integration tests for all your Showcases by rendering them and asserting they respond with `200 OK`. As long as `gem "showcase-rails"` is in the `:test` group you're set.

app/assets/builds/showcase.css

@@ -1,5 +1,5 @@
 /*
-! tailwindcss v3.2.6 | MIT License | https://tailwindcss.com
+! tailwindcss v3.2.7 | MIT License | https://tailwindcss.com
 */
 
 /*

lib/showcase.rb

@@ -3,6 +3,7 @@
 module Showcase
   autoload :IntegrationTest, "showcase/integration_test"
   autoload :RouteHelper,     "showcase/route_helper"
+  autoload :Options,         "showcase/options"
 
   singleton_class.attr_accessor :sample_renderer
   @sample_renderer = ->(lines) { tag.pre lines.join.strip_heredoc }
@@ -15,6 +16,38 @@ def self.previews
       Dir.glob("**/*.*", base: File.join(root, previews_path))
     end.uniq
   end
+
+  def self.options
+    Options
+  end
+
+  options.define :stimulus do
+    def targets(name, ...)
+      option(%(data-#{@controller}-target="#{name}"), ...)
+    end
+
+    def values(name, ...)
+      option("data-#{@controller}-#{name}-value", ...)
+    end
+
+    def classes(name, ...)
+      option("data-#{@controller}-#{name}-class", ...)
+    end
+
+    def outlet(name, ...)
+      option("data-#{@controller}-#{name}-outlet", ...)
+    end
+
+    def action(name, ...)
+      option(%(data-action="#{name}"), ...)
+    end
+  end
+
+  options.define :nice_partials do
+    def content_block(*arguments, **options, &block)
+      option(*arguments, **options, type: "Content Block", &block)
+    end
+  end
 end
 
 require "showcase/engine" if defined?(Rails::Engine)

lib/showcase/options.rb

@@ -0,0 +1,89 @@
+require "active_support/option_merger"
+
+class Showcase::Options
+  include Enumerable
+
+  def initialize(view_context)
+    @view_context = view_context
+    @options = []
+    @order = [:name, :required, :type, :default, :description]
+  end
+  delegate :empty?, to: :@options
+
+  #   Showcase.options.define :stimulus do
+  #     def value(name, ...)
+  #       option("data-#{@controller}-#{name}-value", ...)
+  #     end
+  #   end
+  singleton_class.attr_reader :contexts
+  @contexts = Hash.new { |h,k| h[k] = Class.new Context }
+
+  def self.define(key, &block)
+    contexts[key].class_eval(&block) # Lets users reopen an already defined context class.
+  end
+
+  #   showcase.options.stimulus controller: :welcome do |o|
+  #     o.value :greeting, default: "Hello"
+  #   end
+  def context(key, **options, &block)
+    context = self.class.contexts.fetch(key)
+    context.new(@view_context, @options, **options).tap { yield _1 if block_given? }
+  end
+
+  def required(*arguments, **keywords, &block)
+    if arguments.none?
+      ActiveSupport::OptionMerger.new(self, required: true)
+    else
+      option(*arguments, **keywords, required: true, &block)
+    end
+  end
+
+  def optional(*arguments, **keywords, &block)
+    if arguments.none?
+      ActiveSupport::OptionMerger.new(self, required: false)
+    else
+      option(*arguments, **keywords, required: false, &block)
+    end
+  end
+
+  DEFAULT_OMITTED = Object.new
+
+  def option(name, description = nil, required: false, type: nil, default: DEFAULT_OMITTED, **options, &block)
+    description ||= @view_context.capture(&block).remove(/^\s+/).html_safe if block
+
+    type ||= type_from_default(default)
+    default = default == DEFAULT_OMITTED ? nil : default.inspect
+
+    @options << options.with_defaults(name: name, default: default, type: type, description: description, required: required)
+  end
+
+  def headers
+    @headers ||= @order | @options.flat_map(&:keys).uniq.sort
+  end
+
+  def each(&block)
+    @options.each do |option|
+      yield headers.index_with { option[_1] }
+    end
+  end
+
+  private
+
+  class Context < Showcase::Options
+    def initialize(view_context, options, **kwargs)
+      super(view_context)
+      @options = options
+      kwargs.each { instance_variable_set(:"@#{_1}", _2) }
+    end
+  end
+
+  def type_from_default(default)
+    case default
+    when DEFAULT_OMITTED then String
+    when true, false then "Boolean"
+    when nil then "nil"
+    else
+      default.class
+    end
+  end
+end

test/controllers/showcase/previews_controller_test.rb

@@ -102,9 +102,15 @@ class Showcase::PreviewsControllerTest < Showcase::InternalIntegrationTest
 
     within :section, "Options" do
       assert_table with_rows: [
-        {"Name" => "data-welcome-target", "Required" => "", "Type" => "String", "Default" => "", "Description" => "If the id of the target element must be printed"},
-        {"Name" => "data-welcome-yell-value", "Required" => "", "Type" => "Boolean", "Default" => "false", "Description" => "Whether the hello is to be YELLED"}
+        {"Name" => %(data-welcome-target="greeter"), "Required" => "", "Type" => "String", "Default" => "", "Description" => "If the id of the target element must be printed"},
+        {"Name" => "data-welcome-yell-value", "Required" => "", "Type" => "Boolean", "Default" => "false", "Description" => "Whether the hello is to be YELLED"},
+        {"Name" => "data-welcome-success-class", "Required" => "", "Type" => "String", "Default" => "", "Description" => "The success class to append after greeting"},
+        {"Name" => "data-welcome-list-outlet", "Required" => "", "Type" => "String", "Default" => "", "Description" => "An outlet to append each yelled greeter to"},
+        {"Name" => %(data-action="greet"), "Required" => "", "Type" => "String", "Default" => "", "Description" => "An action to repeat the greeting, if need be"},
+        {"Name" => "body", "Required" => "", "Type" => "Content Block", "Default" => "", "Description" => "An optional content block to set the body" }
       ]
+
+      assert_checked_field type: "checkbox", disabled: true, count: 3
     end
   end
 end

test/dummy/app/views/showcase/previews/stimulus_controllers/_welcome.html.erb

@@ -14,7 +14,14 @@
   <div data-controller="welcome" data-welcome-yell-value="true">
 <% end %>
 
-<% showcase.options do |o| %>
-  <% o.optional "data-welcome-target", "If the id of the target element must be printed" %>
-  <% o.optional "data-welcome-yell-value", "Whether the hello is to be YELLED", default: false %>
+<% showcase.options.context :stimulus, controller: :welcome do |o| %>
+  <% o.optional.targets :greeter, "If the id of the target element must be printed" %>
+  <% o.required.values :yell, "Whether the hello is to be YELLED", default: false %>
+  <% o.required.classes :success, "The success class to append after greeting" %>
+  <% o.required.outlet :list, "An outlet to append each yelled greeter to" %>
+  <% o.optional.action :greet, "An action to repeat the greeting, if need be" %>
+<% end %>
+
+<% showcase.options.context :nice_partials do |o| %>
+  <% o.content_block :body, "An optional content block to set the body" %>
 <% end %>