[PLAY-1327] Add Variants Specification to Kit Collection View (#3516)

**What does this PR do?**

- ✅ Lets a user specify variants on the kit_collection page by URL. 
- ✅ Add optional parameter, (/*variants), to routes.rb. Pass variable in
pages controller.
- ✅ Add variants argument to `pb_kit` function and filter examples if
variants are specified.
- ✅ Add variants to `pb_rails` nav links and `pb_kit` in Kit Collection
view

kit_collection/*names/(/:name)**(/*variants)**(/:type)

E.g.,
/kit_collection/title&card&avatar/card/**title_default&card_background&avatar_monogram**
would only show "title_default", "card_background", and
"avatar_monogram" variants.

This should help out with handoffs. We'll be able to specify only the
relevant variants.

Later, we'll look into making a UI to build out these links. 

**Screenshots:** 
![Zight 2024-07-22 at 2 50 13
PM](https://github.com/user-attachments/assets/e8e02797-ba1f-4657-85fa-ba7491bb8a94)

**How to test?**
1. Go to
https://pr3516.playbook.beta.px.powerapp.cloud/kit_collection/title&card&avatar/title/title_default&title_responsive&card_background&avatar_monogram/react
2. You should only see two Title variants: "Default UI" and "Responsive"
3. Click "Card" in the top nav bar
4. You should see one Card variant: "Card Backgrounds"
5. Go to
https://pr3516.playbook.beta.px.powerapp.cloud/kit_collection/title&card&avatar/
6. You should see all the variants for Title on this page. 
7. Click "Avatar" in the top nav bar
8. You should see all the variants for Avatar on this page. 

#### Checklist:
- [x] **LABELS** Add a label: `enhancement`, `bug`, `improvement`, `new
kit`, `deprecated`, or `breaking`. See [Changelog &
Labels](https://github.com/powerhome/playbook/wiki/Changelog-&-Labels)
for details.
- [x] **DEPLOY** I have added the `milano` label to show I'm ready for a
review.

playbook-website/app/controllers/pages_controller.rb

@@ -349,6 +349,7 @@ def handle_kit_collection(type)
     @kits_array = @kits.first.split("&")
     params[:name] ||= @kits_array[0]
     @selected_kit = params[:name]
+    @variants = params[:variants].present? ? params[:variants].split("&") : []
     @type = type
 
     render template: "pages/kit_collection", layout: "layouts/fullscreen"

playbook-website/app/views/pages/kit_collection.html.erb

@@ -2,16 +2,16 @@
   <%= pb_rails("nav", props: { margin_bottom: "md", orientation: "horizontal" }) do %>
     <%= pb_rails("flex", props: {wrap: true}) do %>
       <% @kits_array.each do |kit| %>
-        <%= pb_rails("nav/item", props: { id: "nav-item-#{kit}", text: kit.titleize, link: kit_collection_show_path(names: params[:names], name: kit, type: @type), active: kit == @selected_kit}) %>
+        <%= pb_rails("nav/item", props: { id: "nav-item-#{kit}", text: kit.titleize, link: kit_collection_show_path(names: params[:names], name: kit, variants: params[:variants], type: @type), active: kit == @selected_kit}) %>
       <% end %>
     <% end %>
   <% end %>
   <div class="multi-kits-container">
     <% if @type == "rails" %>
-      <%= pb_kit(kit: @selected_kit, dark_mode: dark_mode?) %>
+      <%= pb_kit(kit: @selected_kit, dark_mode: dark_mode?, variants: @variants) %>
       <%= pb_rails("docs/kit_api", props: { kit: @selected_kit, dark: dark_mode? }) %>
     <% elsif @type == "react" %>
-      <%= pb_kit(kit: @selected_kit, type: "react", dark_mode: dark_mode?) %>
+      <%= pb_kit(kit: @selected_kit, type: "react", dark_mode: dark_mode?, variants: @variants) %>
     <% end %>
   </div>
 <% end %>

playbook-website/config/routes.rb

@@ -26,10 +26,10 @@
   get "kit_category/:category/rails",   to: "pages#kit_category_show_rails",  as: "kit_category_show_rails"
   get "kit_category/:category/react",   to: "pages#kit_category_show_react",  as: "kit_category_show_reacts"
   get "kit_category/:category/swift",   to: "pages#kit_category_show_swift",  as: "kit_category_show_swift"
-  get "kit_collection/*names/:name/rails",    to: "pages#kit_collection_show_rails",                        as: "kit_collection_show_rails"
-  get "kit_collection/*names/:name/react",    to: "pages#kit_collection_show_react",                        as: "kit_collection_show_react"
-  get "kit_collection/*names/:name/swift",    to: "pages#kit_collection_show_swift",                        as: "kit_collection_show_swift"
-  get "kit_collection/*names/(/:name)(/:type)", to: "pages#kit_collection_show_rails", defaults: { type: "rails" }, as: "kit_collection_show"
+  get "kit_collection/*names/:name(/*variants)/rails",    to: "pages#kit_collection_show_rails", as: "kit_collection_show_rails"
+  get "kit_collection/*names/:name(/*variants)/react",    to: "pages#kit_collection_show_react", as: "kit_collection_show_react"
+  get "kit_collection/*names/:name(/*variants)/swift",    to: "pages#kit_collection_show_swift", as: "kit_collection_show_swift"
+  get "kit_collection/*names/(/:name)(/*variants)(/:type)", to: "pages#kit_collection_show_rails", defaults: { type: "rails" }, as: "kit_collection_show"
 
   # Experiments
   #

playbook-website/lib/pb_doc_helper.rb

@@ -6,8 +6,9 @@ def pb_kit_title(title)
       title.remove("pb_").titleize.tr("_", " ")
     end
 
-    def pb_kit(kit: "", type: "rails", show_code: true, limit_examples: false, dark_mode: false)
+    def pb_kit(kit: "", type: "rails", show_code: true, limit_examples: false, dark_mode: false, variants: [])
       examples = pb_doc_kit_examples(kit, type)
+      examples.select! { |elem| variants.any? { |variant| elem.key?(variant) } } unless variants.empty?
       examples = examples.first(1) if limit_examples
       examples.map do |example|
         pb_rails "docs/kit_example", props: {
@@ -61,7 +62,7 @@ def render_pb_doc_kit(kit, type, limit_examples, code = true, dark_mode = false)
           #{pb_kit(kit: kit, type: type, show_code: code, limit_examples: limit_examples, dark_mode: dark_mode)}</div>")
       title + ui
     end
-  # rubocop:enable Style/OptionalBooleanParameter
+    # rubocop:enable Style/OptionalBooleanParameter
 
   private