playbook-ui 18.2.0-rc.1 → 18.2.0-rc.2

package/dist/ai/all-schemas.json

@@ -2412,7 +2412,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -3015,7 +3015,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -3049,13 +3049,14 @@
                     "type": "boolean",
                     "example": "@user.errors[:terms].any?",
                     "description": "Checkbox does not auto-map record.errors. Pass a boolean styling flag; render any error message separately."
-                  }
+                  },
+                  "client": "props.validation_message becomes data-message on the checkbox input."
                 },
                 "block": {
                   "supported": false,
                   "description": "The builder supplies the Rails checkbox as kit content; caller blocks are not forwarded."
                 },
-                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.check_box :terms, checked_value: \"1\", unchecked_value: \"0\", props: { label: true, required: true, error: @user.errors[:terms].any? } %>\n<% end %>",
+                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.check_box :terms, checked_value: \"1\", unchecked_value: \"0\", props: { label: true, required: true, validation_message: \"Please accept the terms\", error: @user.errors[:terms].any? } %>\n<% end %>",
                 "kit": "checkbox",
                 "signature": "check_box(name, props: {}, **options)",
                 "sources": [
@@ -3091,9 +3092,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -4384,7 +4386,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -4460,9 +4462,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -5677,6 +5680,13 @@
           "type": "boolean",
           "default": false
         },
+        "validationMessage": {
+          "platforms": [
+            "rails"
+          ],
+          "type": "string",
+          "default": ""
+        },
         "searchTermMinimumLength": {
           "platforms": [
             "rails"
@@ -5784,7 +5794,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -5825,9 +5835,9 @@
                     "example": "Omit props.error, or pass an explicit message / nil to override",
                     "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
                   },
-                  "client": "No validation or input_options prop is exposed by this Rails kit."
+                  "client": "props.validation_message becomes data-message on the CSS-hidden input (single and multi-select)."
                 },
-                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.dropdown_field :country, props: { label: \"Country\", options: [{ id: \"ca\", value: \"canada\", label: \"Canada\" }], required: true } %>\n<% end %>",
+                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.dropdown_field :country, props: { label: \"Country\", options: [{ id: \"ca\", value: \"canada\", label: \"Canada\" }], required: true, validation_message: \"Please select a country\" } %>\n<% end %>",
                 "kit": "dropdown",
                 "signature": "dropdown_field(name, props: {})",
                 "sources": [
@@ -5863,9 +5873,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -8968,6 +8979,13 @@
             "accessories"
           ],
           "default": "primary"
+        },
+        "validationMessage": {
+          "platforms": [
+            "rails"
+          ],
+          "type": "string",
+          "default": ""
         }
       },
       "globalProps": true,
@@ -8995,7 +9013,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -9026,7 +9044,7 @@
                   "multi": "Pass user[regions], without [], to submit user[regions][] entries."
                 },
                 "validation": {
-                  "required": "props.required is used by the kit; hidden selected-value inputs also receive required. Do not infer native validation from hidden inputs.",
+                  "required": "props.required is used by the kit. The search input is required when empty; kit JS removes required from the search input once currentSelected() is non-empty. Hidden selected-value inputs also receive required, but type=hidden is not constraint-validated.",
                   "indicator": "props.required_indicator is visual only.",
                   "error": {
                     "automatic": true,
@@ -9034,9 +9052,10 @@
                     "type": "string",
                     "example": "Omit props.error, or pass an explicit message / nil to override",
                     "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
-                  }
+                  },
+                  "client": "props.validation_message becomes data-message on the search input. Kit JS clears custom validity when the selection changes."
                 },
-                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.multi_level_select :regions, props: { label: \"Regions\", tree_data: @regions, required: true } %>\n<% end %>",
+                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.multi_level_select :regions, props: { label: \"Regions\", tree_data: @regions, required: true, validation_message: \"Please select a region\" } %>\n<% end %>",
                 "kit": "multi_level_select",
                 "signature": "multi_level_select(name, props: {})",
                 "sources": [
@@ -9072,9 +9091,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -10143,6 +10163,14 @@
           ],
           "default": false
         },
+        "validationMessage": {
+          "type": "string",
+          "platforms": [
+            "react",
+            "rails"
+          ],
+          "default": ""
+        },
         "value": {
           "type": "string",
           "platforms": [
@@ -10209,7 +10237,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -10248,9 +10276,10 @@
                     "type": "string",
                     "example": "Omit props.error, or pass an explicit message / nil to override",
                     "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
-                  }
+                  },
+                  "client": "props.validation_message replaces the kit-owned required empty-field copy (default \"Missing phone number\"). Format errors remain kit-owned. PbFormValidation skips phone fields."
                 },
-                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.intl_telephone :phone, props: { label: \"Phone\", required: true } %>\n<% end %>",
+                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.intl_telephone :phone, props: { label: \"Phone\", required: true, validation_message: \"Phone number is required\" } %>\n<% end %>",
                 "kit": "phone_number_input",
                 "signature": "intl_telephone(name, props: {})",
                 "sources": [
@@ -10288,9 +10317,10 @@
                     "type": "string",
                     "example": "Omit props.error, or pass an explicit message / nil to override",
                     "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
-                  }
+                  },
+                  "client": "props.validation_message replaces the kit-owned required empty-field copy (default \"Missing phone number\"). Format errors remain kit-owned. PbFormValidation skips phone fields."
                 },
-                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.phone_number_field :phone, props: { label: \"Phone\", required: true } %>\n<% end %>",
+                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.phone_number_field :phone, props: { label: \"Phone\", required: true, validation_message: \"Phone number is required\" } %>\n<% end %>",
                 "kit": "phone_number_input",
                 "signature": "phone_number_field(name, props: {})",
                 "sources": [
@@ -10326,9 +10356,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -11467,7 +11498,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -11490,7 +11521,7 @@
                 },
                 "htmlOptions": {
                   "argument": "html_options",
-                  "description": "Pass input attributes in the positional html_options hash. props.input_options forwards only id, class and data. props.blank_selection sets options.prompt (default empty)."
+                  "description": "Pass input attributes in the positional html_options hash. props.input_options forwards only id, class and data. An explicitly supplied props.blank_selection sets options.prompt (nil becomes empty), overriding any explicit prompt. Otherwise options.prompt is preserved, including false or nil to omit the prompt; when neither is supplied, the prompt defaults to empty."
                 },
                 "validation": {
                   "required": "props.required sets html_options.required.",
@@ -11530,7 +11561,7 @@
                 },
                 "htmlOptions": {
                   "argument": "html_options",
-                  "description": "Pass input attributes in the positional html_options hash. props.input_options forwards only id, class and data. props.blank_selection sets options.prompt (default empty)."
+                  "description": "Pass input attributes in the positional html_options hash. props.input_options forwards only id, class and data. An explicitly supplied props.blank_selection sets options.prompt (nil becomes empty), overriding any explicit prompt. Otherwise options.prompt is preserved, including false or nil to omit the prompt; when neither is supplied, the prompt defaults to empty."
                 },
                 "validation": {
                   "required": "props.required sets html_options.required.",
@@ -11570,7 +11601,7 @@
                 },
                 "htmlOptions": {
                   "argument": "html_options",
-                  "description": "Pass input attributes in the positional html_options hash. props.input_options forwards only id, class and data. props.blank_selection sets options.prompt (default empty)."
+                  "description": "Pass input attributes in the positional html_options hash. props.input_options forwards only id, class and data. props.blank_selection sets options.prompt (default empty), overriding any explicit prompt."
                 },
                 "validation": {
                   "required": "props.required sets html_options.required.",
@@ -11624,9 +11655,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -11705,6 +11737,24 @@
           "contractPaths": [
             "form.rails.builder.simpleForm"
           ]
+        },
+        {
+          "id": "select.builder-prompt",
+          "platforms": [
+            "rails"
+          ],
+          "questions": [
+            "How do I omit the prompt in a select builder field?",
+            "Does blank_selection override options.prompt?"
+          ],
+          "answer": "For f.select and f.collection_select, pass prompt: false in the positional options hash and omit props.blank_selection to omit the prompt. An explicitly supplied props.blank_selection overrides options.prompt, including false or nil; a nil blank_selection becomes an empty prompt. Otherwise an explicit prompt is preserved, and when neither is supplied the prompt defaults to empty. time_zone_select_field still sets the prompt from props.blank_selection (default empty), overriding an explicit prompt.",
+          "example": "<%= f.select :country, [[\"Canada\", \"ca\"]], { prompt: false }, {}, props: { label: true } %>",
+          "contractPaths": [
+            "form.rails.builder.methods"
+          ],
+          "props": [
+            "blankSelection"
+          ]
         }
       ]
     },
@@ -12450,6 +12500,13 @@
           "type": "boolean",
           "default": false
         },
+        "validationMessage": {
+          "platforms": [
+            "rails"
+          ],
+          "type": "string",
+          "default": ""
+        },
         "inputOptions": {
           "platforms": [
             "rails"
@@ -12487,7 +12544,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -12523,9 +12580,10 @@
                     "supported": false,
                     "automatic": false,
                     "description": "This kit has no error prop. Render model errors separately."
-                  }
+                  },
+                  "client": "props.validation_message becomes data-message on the CSS-hidden rating input."
                 },
-                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.star_rating_field :rating, props: { label: \"Rating\", variant: \"interactive\", required: true } %>\n<% end %>",
+                "example": "<%= pb_form_with model: @user do |f| %>\n  <%= f.star_rating_field :rating, props: { label: \"Rating\", variant: \"interactive\", required: true, validation_message: \"Please provide a rating\" } %>\n<% end %>",
                 "kit": "star_rating",
                 "signature": "star_rating_field(name, props: {})",
                 "sources": [
@@ -12561,9 +12619,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -13188,7 +13247,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -13575,9 +13634,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -13853,7 +13913,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -13940,9 +14000,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -14309,7 +14370,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -14386,9 +14447,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"
@@ -15668,7 +15730,7 @@
             ],
             "setup": "<%= pb_form_with model: @user do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
             "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n  <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
-            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
+            "validation": "pb_form_with defaults validate to false. validate: true sets data-pb-form-validation for Playbook client validation. PbFormValidation finds the field kit via a *_kit classname, or via data-pb-dropdown / data-pb-multi-level-select for those kits. It binds invalid in capture on the form (not a one-time [required] snapshot) so controls that toggle required after mount still get data-message. Server/model validation remains the host application responsibility. Most builder fields also map record.errors into props.error unless the caller sets error explicitly (including nil).",
             "lifecycle": "pb_form_with invokes formHelper when available. PbFormValidation is registered with PbKitRegistry; its MutationObserver handles dynamically added forms, including Turbo navigation. Load the Playbook Rails bundle in the host.",
             "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
             "sources": [
@@ -15749,9 +15811,10 @@
           "questions": [
             "How do I show ActiveRecord errors?",
             "Does required_indicator validate?",
-            "How do I enable client validation?"
+            "How do I enable client validation?",
+            "How do I set a custom required-field message?"
           ],
-          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations.",
+          "answer": "Most builder fields auto-map record.errors.full_messages_for(attribute) into props.error unless error is set explicitly (including nil to opt out). Checkbox still needs an explicit boolean error flag, and StarRating has no error prop. A required indicator is visual only. pb_form_with validate: true enables Playbook client validation; it does not run model validations. Custom required messages use props.validation.message on text-style fields (including text_area and telephone_field) and props.validation_message on selection-style fields (select, dropdown_field, check_box, phone_number_field, star_rating_field, multi_level_select, and similar). Phone kits own their UI and use validation_message for the empty required copy only.",
           "contractPaths": [
             "form.rails.builder.validation",
             "form.rails.builder.methods"