Support adding descriptions to controls.

Controls are now able to be given a custom description to provide better
context when viewing Storybook.js documentation.

Adding a description works in the same way as adding a custom name for
the control — it can be set when initializing the control or by calling
the `description` method on the instance.

docs/guide/controls.md

@@ -207,7 +207,7 @@ For example this story results in two controls with names "First Name" and "Last
 class PersonComponentStories < ViewComponent::Storybook::Stories
   story :person do
     constructor(
-      first_name: text("Nelson"), 
+      first_name: text("Nelson"),
       last_name:  text("Mandela")
     )
   end
@@ -221,9 +221,35 @@ The control name is configured using `name`:
 class PersonComponentStories < ViewComponent::Storybook::Stories
   story :person do
     constructor(
-      first_name: text("Nelson").name("First"), 
+      first_name: text("Nelson").name("First"),
       last_name:  text("Mandela").name("Last")
     )
   end
 end
 ```
+
+## Adding a description to the control
+
+You can provide additional information about the control by passing a string
+into the `description` method.
+
+```ruby
+# test/components/stories/person_component_stories.rb
+class PersonComponentStories < ViewComponent::Storybook::Stories
+  story :person do
+    constructor(
+      first_name: text("Nelson").description("The person's first name"),
+      last_name:  text("Mandela").description("The person's last name")
+    )
+  end
+end
+```
+
+To have Storybook.js display your description you will need to add the following
+to `.storybook/preview.js`:
+
+```js
+export const parameters = {
+  controls: { expanded: true }
+}
+```

lib/view_component/storybook/controls/base_options_config.rb

@@ -8,8 +8,8 @@ class BaseOptionsConfig < SimpleControlConfig
 
         validates :type, :options, presence: true
 
-        def initialize(type, options, default_value, labels: nil, param: nil, name: nil)
-          super(default_value, param: param, name: name)
+        def initialize(type, options, default_value, labels: nil, param: nil, name: nil, description: nil)
+          super(default_value, param: param, name: name, description: description)
           @type = type
           @options = options
           @labels = labels

lib/view_component/storybook/controls/color_config.rb

@@ -6,8 +6,8 @@ module Controls
       class ColorConfig < SimpleControlConfig
         attr_reader :preset_colors
 
-        def initialize(default_value, preset_colors: nil, param: nil, name: nil)
-          super(default_value, param: param, name: name)
+        def initialize(default_value, preset_colors: nil, param: nil, name: nil, description: nil)
+          super(default_value, param: param, name: name, description: description)
           @preset_colors = preset_colors
         end
 

lib/view_component/storybook/controls/control_config.rb

@@ -8,9 +8,10 @@ class ControlConfig
 
         validates :param, presence: true
 
-        def initialize(param: nil, name: nil)
+        def initialize(param: nil, name: nil, description: nil)
           @param = param
           @name = name
+          @description = description
         end
 
         def name(new_name = nil)
@@ -22,6 +23,13 @@ def name(new_name = nil)
           end
         end
 
+        def description(new_description = nil)
+          return @description if new_description.nil?
+
+          @description = new_description
+          self
+        end
+
         def param(new_param = nil)
           return @param if new_param.nil?
 

lib/view_component/storybook/controls/date_config.rb

@@ -4,8 +4,8 @@ module ViewComponent
   module Storybook
     module Controls
       class DateConfig < SimpleControlConfig
-        def initialize(default_value, param: nil, name: nil)
-          super(default_value, param: param, name: name)
+        def initialize(default_value, param: nil, name: nil, description: nil)
+          super(default_value, param: param, name: name, description: description)
         end
 
         def type

lib/view_component/storybook/controls/multi_options_config.rb

@@ -9,8 +9,8 @@ class MultiOptionsConfig < BaseOptionsConfig
         validates :type, inclusion: { in: TYPES }, unless: -> { type.nil? }
         validate :validate_default_value, unless: -> { options.nil? || default_value.nil? }
 
-        def initialize(type, options, default_value, labels: nil, param: nil, name: nil)
-          super(type, options, Array.wrap(default_value), labels: labels, param: param, name: name)
+        def initialize(type, options, default_value, labels: nil, param: nil, name: nil, description: nil)
+          super(type, options, Array.wrap(default_value), labels: labels, param: param, name: name, description: description)
         end
 
         def value_from_params(params)

lib/view_component/storybook/controls/number_config.rb

@@ -11,8 +11,8 @@ class NumberConfig < SimpleControlConfig
         validates :type, presence: true
         validates :type, inclusion: { in: TYPES }, unless: -> { type.nil? }
 
-        def initialize(type, default_value, min: nil, max: nil, step: nil, param: nil, name: nil)
-          super(default_value, param: param, name: name)
+        def initialize(type, default_value, min: nil, max: nil, step: nil, param: nil, name: nil, description: nil)
+          super(default_value, param: param, name: name, description: description)
           @type = type
           @min = min
           @max = max

lib/view_component/storybook/controls/simple_control_config.rb

@@ -9,16 +9,18 @@ module Controls
       class SimpleControlConfig < ControlConfig
         attr_reader :default_value
 
-        def initialize(default_value, param: nil, name: nil)
-          super(param: param, name: name)
+        def initialize(default_value, param: nil, name: nil, description: nil)
+          super(param: param, name: name, description: description)
           @default_value = default_value
         end
 
         def to_csf_params
           validate!
           {
             args: { param => csf_value },
-            argTypes: { param => { control: csf_control_params, name: name } }
+            argTypes: {
+              param => { control: csf_control_params, name: name, description: description }.compact
+            }
           }
         end
 

spec/dummy/test/components/stories/content_component_stories.rb

@@ -9,6 +9,10 @@ class ContentComponentStories < ViewComponent::Storybook::Stories
     content text("Hello World!")
   end
 
+  story :with_described_control do
+    content text("Hello World!").description('My first computer program.')
+  end
+
   story :with_block_content do
     content do
       "Hello World!"

spec/dummy/test/components/stories/custom_control_stories.rb

@@ -34,4 +34,10 @@ class CustomControlStories < ViewComponent::Storybook::Stories
       button_text: custom_control
     )
   end
+
+  story :described_control, Demo::ButtonComponent do
+    constructor(
+      button_text: text('DO NOT PUSH!').description('Make this irresistible.')
+    )
+  end
 end

spec/support/controls_examples.rb

@@ -3,6 +3,7 @@
 shared_examples "a controls config" do
   let(:param) { :button_text }
   let(:name) { nil }
+  let(:description) { nil }
 
   describe "#param" do
     it "can be set" do
@@ -40,6 +41,30 @@
     end
   end
 
+  describe '#description' do
+    it "by default is nil" do
+      expect(subject.description).to be_nil
+    end
+
+    context "with description" do
+      let(:description) { "Text for the button" }
+
+      it "can be passed in the constructor" do
+        expect(subject.description).to eq("Text for the button")
+      end
+    end
+
+    it "can be set" do
+      subject.description("Text for the button")
+
+      expect(subject.description).to eq("Text for the button")
+    end
+
+    it "set returns the control" do
+      expect(subject.description("Text for the button")).to eq(subject)
+    end
+  end
+
   describe "#prefix_param" do
     it "prefixes the param" do
       subject.param(:name).prefix_param(:author)
@@ -112,6 +137,15 @@
       end
     end
 
+    context "with description" do
+      let(:description) { "Descriptive Text" }
+
+      it "creates params" do
+        description_params = { argTypes: { button_text: { description: "Descriptive Text" } } }
+        expect(subject.to_csf_params).to eq(expected_csf_params.deep_merge(description_params))
+      end
+    end
+
     it "calls validate!" do
       allow(subject).to receive(:validate!).and_raise ActiveModel::ValidationError.new(subject)
 

spec/view_component/storybook/controls/boolean_config_spec.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 RSpec.describe ViewComponent::Storybook::Controls::BooleanConfig do
-  subject { described_class.new(default_value, param: param, name: name) }
+  subject { described_class.new(default_value, param: param, name: name, description: description) }
 
   let(:type) { :boolean }
 

spec/view_component/storybook/controls/color_config_spec.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 RSpec.describe ViewComponent::Storybook::Controls::ColorConfig do
-  subject { described_class.new(default_value, param: param, name: name) }
+  subject { described_class.new(default_value, param: param, name: name, description: description) }
 
   let(:type) { :color }
 
   it_behaves_like "a simple controls config"
 
   context "with :preset_color array" do
-    subject { described_class.new(default_value, param: param, name: name, preset_colors: preset_colors) }
+    subject { described_class.new(default_value, param: param, name: name, description: description, preset_colors: preset_colors) }
 
     let(:preset_colors) { %w[red green blue] }
 

spec/view_component/storybook/controls/custom_config_spec.rb

@@ -2,7 +2,7 @@
 
 RSpec.describe ViewComponent::Storybook::Controls::CustomConfig do
   subject do
-    described_class.new(param: param, name: name).with_value(
+    described_class.new(param: param, name: name, description: description).with_value(
       message: ViewComponent::Storybook::Controls::TextConfig.new("Hello")
     ) do |message:|
       message.upcase
@@ -11,6 +11,7 @@
 
   let(:param) { :greeting }
   let(:name) { nil }
+  let(:description) { nil }
 
   it_behaves_like "a controls config"
 
@@ -19,7 +20,7 @@
 
     context "with args missmatch" do
       subject do
-        described_class.new(param: param, name: name).with_value(
+        described_class.new(param: param, name: name, description: description).with_value(
           message: ViewComponent::Storybook::Controls::TextConfig.new("Hello")
         ) do |msg:|
           msg.upcase

spec/view_component/storybook/controls/date_config_spec.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 RSpec.describe ViewComponent::Storybook::Controls::DateConfig do
-  subject { described_class.new(default_value, param: param, name: name) }
+  subject { described_class.new(default_value, param: param, name: name, description: description) }
 
   shared_examples "valid with object value" do
     it "has a value" do

spec/view_component/storybook/controls/multi_options_config_spec.rb

@@ -3,7 +3,7 @@
 RSpec.describe ViewComponent::Storybook::Controls::MultiOptionsConfig do
   described_class::TYPES.each do |type|
     context "type: #{type}" do
-      subject { described_class.new(type, options, default_value, labels: labels, param: param, name: name) }
+      subject { described_class.new(type, options, default_value, labels: labels, param: param, name: name, description: description) }
 
       let(:type) { type }
       let(:labels) { {} }

spec/view_component/storybook/controls/number_config_spec.rb

@@ -3,7 +3,7 @@
 RSpec.describe ViewComponent::Storybook::Controls::NumberConfig do
   described_class::TYPES.each do |number_type|
     context "with '#{number_type}' type" do
-      subject { described_class.new(number_type, default_value, param: param, name: name) }
+      subject { described_class.new(number_type, default_value, param: param, name: name, description: description) }
 
       it_behaves_like "a simple controls config" do
         let(:type) { number_type }
@@ -20,7 +20,7 @@
       end
 
       context "with options" do
-        subject { described_class.new(number_type, default_value, **number_options, param: param, name: name) }
+        subject { described_class.new(number_type, default_value, **number_options, param: param, name: name, description: description) }
 
         let(:number_options) { { min: 60, max: 90, step: 1 } }
 

spec/view_component/storybook/controls/object_config_spec.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 RSpec.describe ViewComponent::Storybook::Controls::ObjectConfig do
-  subject { described_class.new(default_value, param: param, name: name) }
+  subject { described_class.new(default_value, param: param, name: name, description: description) }
 
   let(:separator) { "," }
   let(:type) { :object }

spec/view_component/storybook/controls/options_config_spec.rb

@@ -3,7 +3,7 @@
 RSpec.describe ViewComponent::Storybook::Controls::OptionsConfig do
   described_class::TYPES.each do |type|
     context "type: #{type}" do
-      subject { described_class.new(type, options, default_value, labels: labels, param: param, name: name) }
+      subject { described_class.new(type, options, default_value, labels: labels, param: param, name: name, description: description) }
 
       let(:type) { type }
       let(:labels) { {} }

spec/view_component/storybook/controls/text_config_spec.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 RSpec.describe ViewComponent::Storybook::Controls::TextConfig do
-  subject { described_class.new(default_value, param: param, name: name) }
+  subject { described_class.new(default_value, param: param, name: name, description: description) }
 
   let(:type) { :text }