playbook_ui 17.2.0.pre.rc.1 → 17.2.0.pre.rc.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0cfdd29dff7aa690ffa80f529b880a467df847de2897b20978f15aee42493f9
-  data.tar.gz: efe2a6be9fa5b594a9ec8cf3dba4085b7bbc3b6e0ce181a60710b0e760165640
+  metadata.gz: 672b9baf425e982f8d59fe03e71b4211cd715c2975de0f0c3a30895201d6b780
+  data.tar.gz: ed5012fd921338fdcc088c046e07e0a44f54b11f61e9921309958307b324fdfa
 SHA512:
-  metadata.gz: d1000f4e35e8953cbeff95dba2a55f2373c594320e00fc58ac8436eded89a5eb9f5383c85600bf3d747d71148182841ab2a1c5f4124581b5b03596813ea0b353
-  data.tar.gz: '068ba2587e7d290077532454b72d6b6cddefa2d919834bc41329259a010b70535ab6ab0636a846973f3c436d6f6cc259a1fb455edade7989f352b15e76c3543d'
+  metadata.gz: 8291cbace8ba3b7abebdf73b25d577d4a464fc49b1c8de677c1e990b42409a90e3b59a1b76f11312a7443c45ddb18bae51e481e501e602bfc3c735aa8ff98422
+  data.tar.gz: e1277c1934e5ecd79e9740070ca25dee5966f39916501d5cd257055bb96aaade4fa9d5ed924badab1a53666e725caaaef2644a6ec55393d1f06032cf5b250b6f

data/app/pb_kits/playbook/pb_form/docs/_description.md

@@ -1,6 +1,3 @@
-The `form` kit provides consumers with a convenient, consistently styled `<form>` wrapper.
-
-### Form Helpers
-
-This kit uses rails `form_with` with our custom builder to render forms using other kits such as text_input, select, and typeahead to name a few. Doing so provides UI consistency within forms and makes adding a form to your page easier.
+Use `pb_form_with` to build Rails forms with Playbook kits. It wraps Rails [`form_with`](https://guides.rubyonrails.org/form_helpers.html) and supplies a custom form builder so fields like text inputs, selects, and typeaheads render with consistent Playbook styling and behavior.
 
+Pick an input below to see Defaults, Validation, Default Values, and Multi-Column layout patterns one field at a time.

data/app/pb_kits/playbook/pb_form/docs/_footer.md

@@ -1,2 +1,3 @@
 ### Things to Avoid
-Avoid using a form without validation if fields are required and using  with  validation if not required.
+
+Avoid using a form without validation when fields are required, and avoid enabling validation on fields that are not required.

data/app/pb_kits/playbook/pb_form/docs/_form_default_values.html.erb

@@ -0,0 +1,183 @@
+<%
+  load Playbook.kit_path("form", "docs", "_sample_data.ruby").to_s
+  demo_id = "default_values"
+  input_types = PlaybookFormDocsSampleData.input_types
+  default_key = PlaybookFormDocsSampleData.default_input_key
+  select_choices = PlaybookFormDocsSampleData.select_choices
+  dropdown_options = PlaybookFormDocsSampleData.dropdown_options("-dv")
+  typeahead_options = PlaybookFormDocsSampleData.typeahead_options
+  collection = PlaybookFormDocsSampleData.collection
+  tree_data = PlaybookFormDocsSampleData.tree_data("default-values")
+  form_open_source = PlaybookFormDocsSampleData.form_open(scope: demo_id)
+  form_close_source = PlaybookFormDocsSampleData.form_close
+%>
+
+<div data-form-docs-demo="<%= demo_id %>">
+  <div hidden data-form-docs-open><%= raw render_code(form_open_source, "erb") %></div>
+  <div hidden data-form-docs-close><%= raw render_code(form_close_source, "erb") %></div>
+  <%= pb_rails("body", props: {
+        text: "Select one or more inputs to add them to the form.",
+        color: "light",
+        margin_bottom: "xs",
+      }) %>
+  <%= pb_rails("flex", props: { gap: "xs", wrap: true, margin_bottom: "md" }) do %>
+    <% input_types.each do |input_type| %>
+      <div data-form-docs-pill="<%= input_type[:key] %>"
+           role="button"
+           tabindex="0"
+           style="cursor: pointer">
+        <%= pb_rails("pill", props: {
+              text: input_type[:label],
+              text_transform: "none",
+              variant: input_type[:key] == default_key ? "primary" : "neutral",
+            }) %>
+      </div>
+    <% end %>
+  <% end %>
+
+  <%= pb_rails("flex", props: PlaybookFormDocsSampleData.demo_panel_flex_props) do %>
+    <div style="<%= PlaybookFormDocsSampleData.demo_form_column_style %>">
+      <%= pb_rails("card", props: PlaybookFormDocsSampleData.demo_form_card_props) do %>
+      <%= pb_form_with(scope: :default_values, url: "", method: :get, html: { onsubmit: "return false;" }) do |form| %>
+        <% input_types.each do |input_type| %>
+          <div data-form-docs-panel="<%= input_type[:key] %>"
+               style="<%= input_type[:key] == default_key ? "" : "display: none;" %>">
+            <div data-form-docs-snippet hidden><%= raw render_code(
+              PlaybookFormDocsSampleData.form_body_snippet(
+                File.read(Playbook.kit_path("form", "docs", "snippets", "default_values_#{input_type[:key]}.txt"))
+              ),
+              "erb"
+            ) %></div>
+            <% case input_type[:key]
+               when "text_field" %>
+              <%= form.text_field :full_name, props: { label: "Full Name", value: "John Doe" } %>
+            <% when "email_field" %>
+              <%= form.email_field :email, props: { label: "Email", value: "jane@example.com" } %>
+            <% when "number_field" %>
+              <%= form.number_field :quantity, props: { label: "Quantity", value: 3 } %>
+            <% when "search_field" %>
+              <%= form.search_field :project_number, props: { label: "Project Number", value: "33-12345" } %>
+            <% when "password_field" %>
+              <%= form.password_field :password, props: { label: "Password", value: "secret" } %>
+            <% when "url_field" %>
+              <%= form.url_field :website, props: { label: "Website", value: "https://example.com" } %>
+            <% when "textarea" %>
+              <%= form.text_area :bio, props: { label: "Bio", value: "Loves building with Playbook." } %>
+            <% when "select" %>
+              <%= form.select :favorite_color, select_choices,
+                    { selected: "blue" },
+                    props: { label: "Favorite Color", blank_selection: "Select one..." } %>
+            <% when "collection_select" %>
+              <%= form.collection_select :state, collection, :value, :name,
+                    { selected: 2 },
+                    props: { label: "State", blank_selection: "Select one..." } %>
+            <% when "dropdown" %>
+              <%= form.dropdown_field "default_values[country]",
+                    props: {
+                      label: "Country",
+                      options: dropdown_options,
+                      default_value: { label: "Canada", value: "Canada", id: "ca-dv" },
+                    } %>
+            <% when "multi_select" %>
+              <%= form.dropdown_field "default_values[countries]",
+                    props: {
+                      label: "Countries",
+                      options: dropdown_options,
+                      multi_select: true,
+                      default_value: [{ label: "Canada", value: "Canada", id: "ca-dv" }],
+                    } %>
+            <% when "checkbox" %>
+              <%= form.check_box :newsletter,
+                    props: { text: "Subscribe to newsletter", label: "Checkbox" },
+                    checked: true,
+                    checked_value: "yes",
+                    unchecked_value: "no" %>
+            <% when "date_picker" %>
+              <%= form.date_picker :start_date, props: {
+                    label: "Start Date",
+                    allow_input: true,
+                    default_date: "06/15/2026",
+                  } %>
+            <% when "time_picker" %>
+              <%= form.time_picker :start_time, props: { label: "Start Time", default_time: "09:30" } %>
+            <% when "time_zone_select" %>
+              <%= form.time_zone_select_field :time_zone, ActiveSupport::TimeZone.us_zones,
+                    { default: "Pacific Time (US & Canada)" },
+                    props: { label: "Time Zone" } %>
+            <% when "typeahead_default" %>
+              <%= form.typeahead "default_values[color_search_single]",
+                    props: {
+                      options: typeahead_options,
+                      is_multi: false,
+                      label: "Favorite Color",
+                      placeholder: "Search for a color",
+                      default_options: [{ label: "Blue", value: "#0000FF" }],
+                    } %>
+            <% when "typeahead" %>
+              <%= form.typeahead "default_values[color_search]",
+                    props: {
+                      options: typeahead_options,
+                      pills: true,
+                      label: "Favorite Color",
+                      placeholder: "Search for a color",
+                      default_options: [{ label: "Blue", value: "#0000FF" }],
+                    } %>
+            <% when "phone_number" %>
+              <%= form.phone_number_field "default_values[phone]", props: {
+                    label: "Phone Number",
+                    value: "5551234567",
+                  } %>
+            <% when "star_rating" %>
+              <%= form.star_rating_field "default_values[rating]",
+                    props: { variant: "interactive", label: "Rating", rating: 4 } %>
+            <% when "multi_level_select" %>
+              <%= form.multi_level_select "default_values[department]",
+                    props: {
+                      id: "mls-default-values",
+                      tree_data: tree_data,
+                      margin_bottom: "sm",
+                      label: "Department",
+                      selected_ids: ["default-values-102"],
+                    } %>
+            <% end %>
+          </div>
+        <% end %>
+
+        <%= form.actions do |action| %>
+          <%= action.submit %>
+          <%= action.button props: { type: "reset", text: "Cancel", variant: "secondary" } %>
+        <% end %>
+      <% end %>
+      <% end %>
+    </div>
+
+    <div style="<%= PlaybookFormDocsSampleData.demo_data_column_style %>">
+      <%= pb_rails("caption", props: { text: "Submitted Form Data", margin_bottom: "xs" }) %>
+      <%= pb_rails("card", props: { background: "light", padding: "md" }) do %>
+        <div data-form-docs-empty>
+          <%= pb_rails("body", props: { text: "No data submitted yet.", color: "light" }) %>
+        </div>
+        <pre data-form-docs-output
+             style="display: none; margin: 0; overflow: auto; font-size: 12px; line-height: 1.5; white-space: pre-wrap;"></pre>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%= pb_rails("body", props: {
+        text: "Submit the form to see the data on the right.",
+        color: "light",
+        margin_top: "sm",
+        margin_bottom: "sm",
+      }) %>
+
+  <%= pb_rails("card", props: { background: "dark", dark: true, padding: "none" }) do %>
+    <div class="pb--codeCopy pb--codeCopy_compact">
+      <pre class="highlight" data-form-docs-code style="margin: 0; overflow: auto; font-size: 12px; line-height: 1.5; white-space: pre;"></pre>
+    </div>
+  <% end %>
+</div>
+
+<script>
+<%= raw File.read(Playbook.kit_path("form", "docs", "_form_docs_demo.js")) %>
+PbFormDocsDemo("<%= demo_id %>")
+</script>

data/app/pb_kits/playbook/pb_form/docs/_form_default_values.md

@@ -0,0 +1,3 @@
+Toggle pills to add pre-filled inputs. Initial values come from builder props (for example `value` on text inputs). Submit to see the selected fields' data on the right.
+
+For `typeahead`, `phone_number_field`, and `dropdown_field`, pass a scoped string name that matches the form scope (for example `"default_values[phone]"` when `scope: :default_values`) — see Defaults for details.

data/app/pb_kits/playbook/pb_form/docs/_form_defaults.html.erb

@@ -0,0 +1,180 @@
+<%
+  load Playbook.kit_path("form", "docs", "_sample_data.ruby").to_s
+  demo_id = "defaults"
+  input_types = PlaybookFormDocsSampleData.input_types
+  default_key = PlaybookFormDocsSampleData.default_input_key
+  select_choices = PlaybookFormDocsSampleData.select_choices
+  dropdown_options = PlaybookFormDocsSampleData.dropdown_options
+  typeahead_options = PlaybookFormDocsSampleData.typeahead_options
+  collection = PlaybookFormDocsSampleData.collection
+  tree_data = PlaybookFormDocsSampleData.tree_data("defaults")
+  form_open_source = PlaybookFormDocsSampleData.form_open(scope: demo_id)
+  form_close_source = PlaybookFormDocsSampleData.form_close
+%>
+
+<div data-form-docs-demo="<%= demo_id %>">
+  <div hidden data-form-docs-open><%= raw render_code(form_open_source, "erb") %></div>
+  <div hidden data-form-docs-close><%= raw render_code(form_close_source, "erb") %></div>
+  <%= pb_rails("body", props: {
+        text: "Select one or more inputs to add them to the form.",
+        color: "light",
+        margin_bottom: "xs",
+      }) %>
+  <%= pb_rails("flex", props: { gap: "xs", wrap: true, margin_bottom: "md" }) do %>
+    <% input_types.each do |input_type| %>
+      <div data-form-docs-pill="<%= input_type[:key] %>"
+           role="button"
+           tabindex="0"
+           style="cursor: pointer">
+        <%= pb_rails("pill", props: {
+              text: input_type[:label],
+              text_transform: "none",
+              variant: input_type[:key] == default_key ? "primary" : "neutral",
+            }) %>
+      </div>
+    <% end %>
+  <% end %>
+
+  <%= pb_rails("flex", props: PlaybookFormDocsSampleData.demo_panel_flex_props) do %>
+    <div style="<%= PlaybookFormDocsSampleData.demo_form_column_style %>">
+      <%= pb_rails("card", props: PlaybookFormDocsSampleData.demo_form_card_props) do %>
+      <%= pb_form_with(scope: :defaults, url: "", method: :get, html: { onsubmit: "return false;" }) do |form| %>
+        <% input_types.each do |input_type| %>
+          <div data-form-docs-panel="<%= input_type[:key] %>"
+               style="<%= input_type[:key] == default_key ? "" : "display: none;" %>">
+            <div data-form-docs-snippet hidden><%= raw render_code(
+              PlaybookFormDocsSampleData.form_body_snippet(
+                File.read(Playbook.kit_path("form", "docs", "snippets", "defaults_#{input_type[:key]}.txt"))
+              ),
+              "erb"
+            ) %></div>
+            <% case input_type[:key]
+               when "text_field" %>
+              <%= form.text_field :full_name, props: { label: "Full Name" } %>
+            <% when "email_field" %>
+              <%= form.email_field :email, props: { label: "Email" } %>
+            <% when "number_field" %>
+              <%= form.number_field :quantity, props: { label: "Quantity" } %>
+            <% when "search_field" %>
+              <%= form.search_field :project_number, props: { label: "Project Number" } %>
+            <% when "password_field" %>
+              <%= form.password_field :password, props: { label: "Password" } %>
+            <% when "url_field" %>
+              <%= form.url_field :website, props: { label: "Website" } %>
+            <% when "textarea" %>
+              <%= form.text_area :bio, props: { label: "Bio" } %>
+            <% when "select" %>
+              <%= form.select :favorite_color, select_choices,
+                    props: { label: "Favorite Color", blank_selection: "Select one..." } %>
+            <% when "collection_select" %>
+              <%= form.collection_select :state, collection, :value, :name,
+                    props: { label: "State", blank_selection: "Select one..." } %>
+            <% when "dropdown" %>
+              <%= form.dropdown_field "defaults[country]",
+                    props: { label: "Country", options: dropdown_options } %>
+            <% when "multi_select" %>
+              <%= form.dropdown_field "defaults[countries]",
+                    props: {
+                      label: "Countries",
+                      options: dropdown_options,
+                      multi_select: true,
+                    } %>
+            <% when "checkbox" %>
+              <%= form.check_box :newsletter,
+                    props: { text: "Subscribe to newsletter", label: "Checkbox" },
+                    checked_value: "yes",
+                    unchecked_value: "no" %>
+            <% when "date_picker" %>
+              <%= form.date_picker :start_date, props: { label: "Start Date", allow_input: true } %>
+            <% when "time_picker" %>
+              <%= form.time_picker :start_time, props: { label: "Start Time" } %>
+            <% when "time_zone_select" %>
+              <%= form.time_zone_select_field :time_zone, ActiveSupport::TimeZone.us_zones,
+                    { default: "Eastern Time (US & Canada)" },
+                    props: { label: "Time Zone" } %>
+            <% when "typeahead_default" %>
+              <%= form.typeahead "defaults[color_search_single]",
+                    props: {
+                      options: typeahead_options,
+                      is_multi: false,
+                      label: "Favorite Color",
+                      placeholder: "Search for a color",
+                    } %>
+            <% when "typeahead" %>
+              <%= form.typeahead "defaults[color_search]",
+                    props: {
+                      options: typeahead_options,
+                      pills: true,
+                      label: "Favorite Color",
+                      placeholder: "Search for a color",
+                    } %>
+            <% when "phone_number" %>
+              <%= form.phone_number_field "defaults[phone]", props: { label: "Phone Number" } %>
+            <% when "star_rating" %>
+              <%= form.star_rating_field "defaults[rating]",
+                    props: { variant: "interactive", label: "Rating" } %>
+            <% when "multi_level_select" %>
+              <%= form.multi_level_select "defaults[department]",
+                    props: {
+                      id: "mls-defaults",
+                      tree_data: tree_data,
+                      margin_bottom: "sm",
+                      label: "Department",
+                    } %>
+            <% end %>
+          </div>
+        <% end %>
+
+        <%= form.actions do |action| %>
+          <%= action.submit %>
+          <%= action.button props: { type: "reset", text: "Cancel", variant: "secondary" } %>
+        <% end %>
+      <% end %>
+      <% end %>
+    </div>
+
+    <div style="<%= PlaybookFormDocsSampleData.demo_data_column_style %>">
+      <%= pb_rails("caption", props: { text: "Submitted Form Data", margin_bottom: "xs" }) %>
+      <%= pb_rails("card", props: { background: "light", padding: "md" }) do %>
+        <div data-form-docs-empty>
+          <%= pb_rails("body", props: { text: "No data submitted yet.", color: "light" }) %>
+        </div>
+        <pre data-form-docs-output
+             style="display: none; margin: 0; overflow: auto; font-size: 12px; line-height: 1.5; white-space: pre-wrap;"></pre>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%= pb_rails("body", props: {
+        text: "Submit the form to see the data on the right.",
+        color: "light",
+        margin_top: "sm",
+        margin_bottom: "sm",
+      }) %>
+
+  <%= pb_rails("card", props: { background: "dark", dark: true, padding: "none" }) do %>
+    <div class="pb--codeCopy pb--codeCopy_compact">
+      <pre class="highlight" data-form-docs-code style="margin: 0; overflow: auto; font-size: 12px; line-height: 1.5; white-space: pre;"></pre>
+    </div>
+  <% end %>
+</div>
+
+<%= pb_rails("title", props: { size: 4, text: "Naming kit fields under a scope", margin_top: "md", margin_bottom: "sm" }) %>
+<%= pb_rails("body", props: { tag: "div", margin_bottom: "sm" }) do %>
+  <p><code>text_field</code>, <code>select</code>, <code>check_box</code>, and similar Rails-backed helpers nest under the form <code>scope</code> automatically (<code>defaults[full_name]</code> when <code>scope: :defaults</code>).</p>
+  <p>Playbook-only helpers — <code>typeahead</code>, <code>phone_number_field</code>, and <code>dropdown_field</code> — do not. Pass an explicit string that matches the form scope so params stay nested:</p>
+<% end %>
+<%= pb_rails("card", props: { background: "dark", dark: true, padding: "none", margin_bottom: "sm" }) do %>
+  <div class="pb--codeCopy pb--codeCopy_compact">
+    <pre class="highlight" style="margin: 0; overflow: auto; font-size: 12px; line-height: 1.5; white-space: pre;"><%= raw render_code(
+      File.read(Playbook.kit_path("form", "docs", "snippets", "defaults_scoped_fields.txt")),
+      "erb"
+    ) %></pre>
+  </div>
+<% end %>
+<%= pb_rails("body", props: { text: "Submitted params then land under params[:defaults], matching the code you copy.", color: "light" }) %>
+
+<script>
+<%= raw File.read(Playbook.kit_path("form", "docs", "_form_docs_demo.js")) %>
+PbFormDocsDemo("<%= demo_id %>")
+</script>

data/app/pb_kits/playbook/pb_form/docs/_form_defaults.md

@@ -0,0 +1 @@
+Toggle pills to add or remove inputs from the form. Submit to see values for the selected fields on the right. The code snippet updates to match the current selection.

data/app/pb_kits/playbook/pb_form/docs/_form_docs_demo.js

@@ -0,0 +1,226 @@
+window.PbFormDocsDemo = window.PbFormDocsDemo || function (demoId) {
+  var root = document.querySelector('[data-form-docs-demo="' + demoId + '"]')
+  if (!root || root.dataset.pbFormDocsReady === "true") return
+  root.dataset.pbFormDocsReady = "true"
+
+  var dataOutput = root.querySelector("[data-form-docs-output]")
+  var emptyState = root.querySelector("[data-form-docs-empty]")
+  var codeOutput = root.querySelector("[data-form-docs-code]")
+  var formOpenEl = root.querySelector("[data-form-docs-open]")
+  var formCloseEl = root.querySelector("[data-form-docs-close]")
+  var formOpenHtml = formOpenEl ? formOpenEl.innerHTML.trim() : ""
+  var formCloseHtml = formCloseEl ? trimHighlightHtml(formCloseEl.innerHTML) : ""
+
+  function trimHighlightHtml(html) {
+    // Rouge keeps leading indent as literal spaces before the first span.
+    // String trim() would strip those; only drop trailing newlines.
+    return html.replace(/\n+$/g, "")
+  }
+
+  function clearSubmittedData() {
+    if (dataOutput) {
+      dataOutput.textContent = ""
+      dataOutput.style.display = "none"
+    }
+    if (emptyState) emptyState.style.display = ""
+    clearQueryParams()
+  }
+
+  function clearQueryParams() {
+    var url = window.location.pathname + window.location.hash
+    if (window.location.search) history.replaceState(null, "", url)
+  }
+
+  function formDataToQueryString(form) {
+    var params = new URLSearchParams()
+    var formData = new FormData(form)
+
+    formData.forEach(function (value, key) {
+      if (key === "authenticity_token" || key === "utf8" || key === "_method") return
+      params.append(key, value)
+    })
+
+    return params.toString()
+  }
+
+  function updateQueryParams(form) {
+    var query = formDataToQueryString(form)
+    var url = window.location.pathname + window.location.hash
+    if (query) url += "?" + query
+    history.replaceState(null, "", url)
+  }
+
+  function setPillActive(pillEl, active) {
+    var kit = pillEl.querySelector("[class*='pb_pill_kit_']")
+    if (!kit) return
+    kit.className = kit.className
+      .replace(/pb_pill_kit_primary_/g, "pb_pill_kit_TEMP_")
+      .replace(/pb_pill_kit_neutral_/g, active ? "pb_pill_kit_primary_" : "pb_pill_kit_neutral_")
+      .replace(/pb_pill_kit_TEMP_/g, active ? "pb_pill_kit_primary_" : "pb_pill_kit_neutral_")
+  }
+
+  function setPanelEnabled(panel, enabled) {
+    panel.style.display = enabled ? "" : "none"
+    panel.querySelectorAll("input, select, textarea").forEach(function (el) {
+      el.disabled = !enabled
+    })
+  }
+
+  function selectedKeys() {
+    var keys = []
+    root.querySelectorAll("[data-form-docs-pill]").forEach(function (pillEl) {
+      var kit = pillEl.querySelector("[class*='pb_pill_kit_primary_']")
+      if (kit) keys.push(pillEl.getAttribute("data-form-docs-pill"))
+    })
+    return keys
+  }
+
+  function updateCodeSnippet(keys) {
+    if (!codeOutput) return
+
+    // Match visible panel order (fixed kit order), not click/selection order.
+    var selected = {}
+    keys.forEach(function (key) { selected[key] = true })
+
+    var fieldSnippets = []
+    root.querySelectorAll("[data-form-docs-panel]").forEach(function (panel) {
+      var key = panel.getAttribute("data-form-docs-panel")
+      if (!selected[key]) return
+      var snippetEl = panel.querySelector("[data-form-docs-snippet]")
+      if (snippetEl) fieldSnippets.push(trimHighlightHtml(snippetEl.innerHTML))
+    })
+
+    codeOutput.innerHTML = [formOpenHtml].concat(fieldSnippets).concat([formCloseHtml]).join("\n")
+  }
+
+  function syncSelection(keys) {
+    root.querySelectorAll("[data-form-docs-pill]").forEach(function (pillEl) {
+      var key = pillEl.getAttribute("data-form-docs-pill")
+      setPillActive(pillEl, keys.indexOf(key) !== -1)
+    })
+    root.querySelectorAll("[data-form-docs-panel]").forEach(function (panel) {
+      var key = panel.getAttribute("data-form-docs-panel")
+      setPanelEnabled(panel, keys.indexOf(key) !== -1)
+    })
+    updateCodeSnippet(keys)
+    clearSubmittedData()
+  }
+
+  function toggleKey(key) {
+    var keys = selectedKeys()
+    var index = keys.indexOf(key)
+    if (index === -1) {
+      keys.push(key)
+    } else if (keys.length > 1) {
+      keys.splice(index, 1)
+    }
+    syncSelection(keys)
+  }
+
+  function assignFormValue(result, key, value) {
+    var path = []
+    var asArray = false
+    var rest = key
+    var bareMatch = rest.match(/^([^[\]]+)/)
+
+    if (!bareMatch) {
+      result[key] = value
+      return
+    }
+
+    path.push(bareMatch[1])
+    rest = rest.slice(bareMatch[1].length)
+
+    while (rest.length > 0) {
+      if (rest.indexOf("[]") === 0) {
+        asArray = true
+        rest = rest.slice(2)
+        break
+      }
+
+      var bracketMatch = rest.match(/^\[([^\]]+)\]/)
+      if (!bracketMatch) {
+        result[key] = value
+        return
+      }
+
+      path.push(bracketMatch[1])
+      rest = rest.slice(bracketMatch[0].length)
+    }
+
+    if (rest.length > 0) {
+      result[key] = value
+      return
+    }
+
+    var cursor = result
+    for (var i = 0; i < path.length - 1; i++) {
+      var segment = path[i]
+      if (!cursor[segment] || typeof cursor[segment] !== "object" || Array.isArray(cursor[segment])) {
+        cursor[segment] = {}
+      }
+      cursor = cursor[segment]
+    }
+
+    var last = path[path.length - 1]
+    if (asArray) {
+      if (!Array.isArray(cursor[last])) cursor[last] = []
+      cursor[last].push(value)
+    } else if (Object.prototype.hasOwnProperty.call(cursor, last)) {
+      if (!Array.isArray(cursor[last])) cursor[last] = [cursor[last]]
+      cursor[last].push(value)
+    } else {
+      cursor[last] = value
+    }
+  }
+
+  function formDataToObject(form) {
+    var result = {}
+    var formData = new FormData(form)
+
+    formData.forEach(function (value, key) {
+      if (key === "authenticity_token" || key === "utf8" || key === "_method") return
+      assignFormValue(result, key, value)
+    })
+
+    return result
+  }
+
+  function showSubmittedData(data) {
+    if (emptyState) emptyState.style.display = "none"
+    if (dataOutput) {
+      dataOutput.style.display = ""
+      dataOutput.textContent = JSON.stringify(data, null, 2)
+    }
+  }
+
+  root.querySelectorAll("[data-form-docs-pill]").forEach(function (pillEl) {
+    pillEl.addEventListener("click", function () {
+      toggleKey(pillEl.getAttribute("data-form-docs-pill"))
+    })
+    pillEl.addEventListener("keydown", function (event) {
+      if (event.key !== "Enter" && event.key !== " ") return
+      event.preventDefault()
+      toggleKey(pillEl.getAttribute("data-form-docs-pill"))
+    })
+  })
+
+  root.querySelectorAll("form").forEach(function (form) {
+    // Docs demos never navigate. Capture + return false cover the window before
+    // this script runs (live examples delay inline scripts ~100ms) and Turbo.
+    form.setAttribute("onsubmit", "return false;")
+    form.addEventListener("submit", function (event) {
+      event.preventDefault()
+      event.stopPropagation()
+      if (typeof form.reportValidity === "function" && !form.reportValidity()) return
+      showSubmittedData(formDataToObject(form))
+      updateQueryParams(form)
+    }, true)
+
+    form.addEventListener("reset", function () {
+      setTimeout(clearSubmittedData, 0)
+    })
+  })
+
+  syncSelection(selectedKeys())
+}

data/app/pb_kits/playbook/pb_form/docs/_form_form_with_vs.html.erb

@@ -0,0 +1,36 @@
+<%= pb_rails("flex", props: { align: "stretch", gap: "md", margin_bottom: "md", orientation: "column" }) do %>
+  <%= pb_rails("flex/flex_item") do %>
+    <%= pb_rails("caption", props: { text: "Rails form_with", margin_bottom: "xs" }) %>
+    <%= pb_rails("card", props: { background: "dark", dark: true, padding: "none" }) do %>
+      <div class="pb--codeCopy pb--codeCopy_compact">
+        <pre class="highlight" style="margin: 0; overflow: auto; font-size: 12px; line-height: 1.5; white-space: pre;"><%= raw render_code(
+          File.read(Playbook.kit_path("form", "docs", "snippets", "comparison_rails.txt")),
+          "erb"
+        ) %></pre>
+      </div>
+    <% end %>
+  <% end %>
+
+  <%= pb_rails("flex/flex_item") do %>
+    <%= pb_rails("caption", props: { text: "Playbook pb_form_with", margin_bottom: "xs" }) %>
+    <%= pb_rails("card", props: { background: "dark", dark: true, padding: "none" }) do %>
+      <div class="pb--codeCopy pb--codeCopy_compact">
+        <pre class="highlight" style="margin: 0; overflow: auto; font-size: 12px; line-height: 1.5; white-space: pre;"><%= raw render_code(
+          File.read(Playbook.kit_path("form", "docs", "snippets", "comparison_playbook.txt")),
+          "erb"
+        ) %></pre>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>
+
+<%= pb_rails("title", props: { size: 4, text: "What pb_form_with adds", margin_bottom: "sm" }) %>
+<%= pb_rails("body", props: { tag: "div" }) do %>
+  <ul style="margin: 0; padding-left: 1.25rem;">
+    <li>Automatic Playbook styling via the <code>pb-form</code> class and kit-backed fields</li>
+    <li>A custom form builder for inputs such as <code>text_field</code>, <code>select</code>, <code>typeahead</code>, and more</li>
+    <li>Consistent spacing and action buttons through <code>form.actions</code></li>
+    <li>Optional client-side validation with <code>validate: true</code> and field-level messages</li>
+    <li>For <code>typeahead</code>, <code>phone_number_field</code>, and <code>dropdown_field</code>, pass a scoped string name that matches the form scope (e.g. <code>"user[phone]"</code> when <code>scope: :user</code>) so params nest together</li>
+  </ul>
+<% end %>

data/app/pb_kits/playbook/pb_form/docs/_form_form_with_vs.md

@@ -0,0 +1 @@
+Standard Rails `form_with` still works, but it does not apply Playbook kit styling or the form builder helpers. Prefer `pb_form_with` when building forms in Playbook apps.