playbook-ui 18.1.0 → 18.2.0-alpha.PLAY3330requiredtypeaheadvalidationbug20501

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/dist/.vite/manifest.json +61 -53
  2. package/dist/advanced-table.js +2 -2
  3. package/dist/ai/all-schemas.json +277 -55
  4. package/dist/ai/forms.json +26 -20
  5. package/dist/ai/index.json +2 -2
  6. package/dist/ai/kits/background.schema.json +1 -0
  7. package/dist/ai/kits/button.schema.json +1 -1
  8. package/dist/ai/kits/caption.schema.json +1 -0
  9. package/dist/ai/kits/checkbox.schema.json +7 -5
  10. package/dist/ai/kits/container.schema.json +1 -0
  11. package/dist/ai/kits/currency.schema.json +1 -0
  12. package/dist/ai/kits/dashboard_value.schema.json +1 -0
  13. package/dist/ai/kits/date_picker.schema.json +4 -3
  14. package/dist/ai/kits/detail.schema.json +1 -0
  15. package/dist/ai/kits/dropdown.schema.json +160 -10
  16. package/dist/ai/kits/highlight.schema.json +1 -0
  17. package/dist/ai/kits/icon_stat_value.schema.json +1 -0
  18. package/dist/ai/kits/icon_value.schema.json +1 -0
  19. package/dist/ai/kits/label_value.schema.json +1 -0
  20. package/dist/ai/kits/legend.schema.json +1 -0
  21. package/dist/ai/kits/message.schema.json +1 -0
  22. package/dist/ai/kits/multi_level_select.schema.json +15 -6
  23. package/dist/ai/kits/multiple_users.schema.json +1 -0
  24. package/dist/ai/kits/multiple_users_stacked.schema.json +1 -0
  25. package/dist/ai/kits/phone_number_input.schema.json +18 -7
  26. package/dist/ai/kits/select.schema.json +25 -6
  27. package/dist/ai/kits/star_rating.schema.json +14 -5
  28. package/dist/ai/kits/stat_value.schema.json +1 -0
  29. package/dist/ai/kits/text_input.schema.json +4 -3
  30. package/dist/ai/kits/textarea.schema.json +4 -3
  31. package/dist/ai/kits/time_picker.schema.json +4 -3
  32. package/dist/ai/kits/title_count.schema.json +1 -0
  33. package/dist/ai/kits/title_detail.schema.json +1 -0
  34. package/dist/ai/kits/typeahead.schema.json +4 -3
  35. package/dist/ai/playgrounds/dropdown.json +1 -1
  36. package/dist/ai/playgrounds/index.json +1 -1
  37. package/dist/ai/playgrounds/map.json +1 -1
  38. package/dist/ai/playgrounds/rich_text_editor.json +1 -1
  39. package/dist/charts.js +1 -1
  40. package/dist/chunks/_pagination-BStnaG2D.js +1 -0
  41. package/dist/chunks/{_pb_line_graph-CUJ7NJIr.js → _pb_line_graph-DAoYQIoh.js} +1 -1
  42. package/dist/chunks/_tooltip-WptzLsCF.js +5 -0
  43. package/dist/chunks/_typeahead-DNfFwTns.js +1 -0
  44. package/dist/chunks/{globalProps-DDcpyjvz.js → globalProps-wXibGgWr.js} +1 -1
  45. package/dist/chunks/lib-BDUQ3wt0.js +29 -0
  46. package/dist/chunks/quickpickDateSync-DLDx4zce.js +1 -0
  47. package/dist/chunks/{time_picker_helper-B_FN8E9Y.js → time_picker_helper-Dc38LjqW.js} +1 -1
  48. package/dist/chunks/vendor.js +2 -2
  49. package/dist/playbook-advanced-table.js +1 -1
  50. package/dist/playbook-charts.js +1 -1
  51. package/dist/playbook-rails-charts-bindings.js +1 -1
  52. package/dist/playbook-rails-react-bindings.js +1 -1
  53. package/dist/playbook-rails.js +1 -1
  54. package/dist/playbook.css +1 -1
  55. package/dist/playbook.js +1 -1
  56. package/package.json +3 -3
  57. package/dist/chunks/_detail-CDUjsRrc.js +0 -5
  58. package/dist/chunks/_table-C9KHGQhb.js +0 -1
  59. package/dist/chunks/_typeahead-CfxZLhd3.js +0 -1
  60. package/dist/chunks/lib-D57mygNT.js +0 -29
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "metadataVersion": 1,
3
- "version": "18.1.0",
3
+ "version": "18.2.0-alpha.PLAY3330requiredtypeaheadvalidationbug20501",
4
4
  "builder": {
5
5
  "class": "Playbook::Forms::Builder",
6
6
  "helper": "pb_form_with",
@@ -9,7 +9,7 @@
9
9
  ],
10
10
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
11
11
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
12
- "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).",
12
+ "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).",
13
13
  "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.",
14
14
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
15
15
  "sources": [
@@ -444,13 +444,14 @@
444
444
  "type": "boolean",
445
445
  "example": "@user.errors[:terms].any?",
446
446
  "description": "Checkbox does not auto-map record.errors. Pass a boolean styling flag; render any error message separately."
447
- }
447
+ },
448
+ "client": "props.validation_message becomes data-message on the checkbox input."
448
449
  },
449
450
  "block": {
450
451
  "supported": false,
451
452
  "description": "The builder supplies the Rails checkbox as kit content; caller blocks are not forwarded."
452
453
  },
453
- "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 %>",
454
+ "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 %>",
454
455
  "kit": "checkbox",
455
456
  "signature": "check_box(name, props: {}, **options)",
456
457
  "sources": [
@@ -472,7 +473,7 @@
472
473
  },
473
474
  "htmlOptions": {
474
475
  "argument": "html_options",
475
- "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)."
476
+ "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."
476
477
  },
477
478
  "validation": {
478
479
  "required": "props.required sets html_options.required.",
@@ -569,9 +570,9 @@
569
570
  "example": "Omit props.error, or pass an explicit message / nil to override",
570
571
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
571
572
  },
572
- "client": "No validation or input_options prop is exposed by this Rails kit."
573
+ "client": "props.validation_message becomes data-message on the CSS-hidden input (single and multi-select)."
573
574
  },
574
- "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 %>",
575
+ "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 %>",
575
576
  "kit": "dropdown",
576
577
  "signature": "dropdown_field(name, props: {})",
577
578
  "sources": [
@@ -593,7 +594,7 @@
593
594
  },
594
595
  "htmlOptions": {
595
596
  "argument": "html_options",
596
- "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)."
597
+ "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."
597
598
  },
598
599
  "validation": {
599
600
  "required": "props.required sets html_options.required.",
@@ -649,9 +650,10 @@
649
650
  "type": "string",
650
651
  "example": "Omit props.error, or pass an explicit message / nil to override",
651
652
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
652
- }
653
+ },
654
+ "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."
653
655
  },
654
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.intl_telephone :phone, props: { label: \"Phone\", required: true } %>\n<% end %>",
656
+ "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 %>",
655
657
  "kit": "phone_number_input",
656
658
  "signature": "intl_telephone(name, props: {})",
657
659
  "sources": [
@@ -681,7 +683,7 @@
681
683
  "multi": "Pass user[regions], without [], to submit user[regions][] entries."
682
684
  },
683
685
  "validation": {
684
- "required": "props.required is used by the kit; hidden selected-value inputs also receive required. Do not infer native validation from hidden inputs.",
686
+ "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.",
685
687
  "indicator": "props.required_indicator is visual only.",
686
688
  "error": {
687
689
  "automatic": true,
@@ -689,9 +691,10 @@
689
691
  "type": "string",
690
692
  "example": "Omit props.error, or pass an explicit message / nil to override",
691
693
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
692
- }
694
+ },
695
+ "client": "props.validation_message becomes data-message on the search input. Kit JS clears custom validity when the selection changes."
693
696
  },
694
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.multi_level_select :regions, props: { label: \"Regions\", tree_data: @regions, required: true } %>\n<% end %>",
697
+ "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 %>",
695
698
  "kit": "multi_level_select",
696
699
  "signature": "multi_level_select(name, props: {})",
697
700
  "sources": [
@@ -729,9 +732,10 @@
729
732
  "type": "string",
730
733
  "example": "Omit props.error, or pass an explicit message / nil to override",
731
734
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
732
- }
735
+ },
736
+ "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."
733
737
  },
734
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.phone_number_field :phone, props: { label: \"Phone\", required: true } %>\n<% end %>",
738
+ "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 %>",
735
739
  "kit": "phone_number_input",
736
740
  "signature": "phone_number_field(name, props: {})",
737
741
  "sources": [
@@ -766,9 +770,10 @@
766
770
  "supported": false,
767
771
  "automatic": false,
768
772
  "description": "This kit has no error prop. Render model errors separately."
769
- }
773
+ },
774
+ "client": "props.validation_message becomes data-message on the CSS-hidden rating input."
770
775
  },
771
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.star_rating_field :rating, props: { label: \"Rating\", variant: \"interactive\", required: true } %>\n<% end %>",
776
+ "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 %>",
772
777
  "kit": "star_rating",
773
778
  "signature": "star_rating_field(name, props: {})",
774
779
  "sources": [
@@ -790,7 +795,7 @@
790
795
  },
791
796
  "htmlOptions": {
792
797
  "argument": "html_options",
793
- "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)."
798
+ "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."
794
799
  },
795
800
  "validation": {
796
801
  "required": "props.required sets html_options.required.",
@@ -940,9 +945,10 @@
940
945
  "questions": [
941
946
  "How do I show ActiveRecord errors?",
942
947
  "Does required_indicator validate?",
943
- "How do I enable client validation?"
948
+ "How do I enable client validation?",
949
+ "How do I set a custom required-field message?"
944
950
  ],
945
- "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.",
951
+ "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.",
946
952
  "contractPaths": [
947
953
  "form.rails.builder.validation",
948
954
  "form.rails.builder.methods"
@@ -1,8 +1,8 @@
1
1
  {
2
- "version": "18.1.0",
2
+ "version": "18.2.0-alpha.PLAY3330requiredtypeaheadvalidationbug20501",
3
3
  "metadataVersion": 1,
4
4
  "forms": "forms.json",
5
- "generated": "2026-10-07T14:53:55.746Z",
5
+ "generated": "2026-10-26T17:28:46.243Z",
6
6
  "schemas": {
7
7
  "globalProps": "global-props.schema.json",
8
8
  "globalEventProps": "global-event-props.schema.json",
@@ -221,6 +221,7 @@
221
221
  }
222
222
  },
223
223
  "globalProps": true,
224
+ "globalEventProps": true,
224
225
  "usage": {
225
226
  "react": {
226
227
  "import": "import { Background } from 'playbook-ui'",
@@ -218,7 +218,7 @@
218
218
  ],
219
219
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
220
220
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
221
- "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).",
221
+ "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).",
222
222
  "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.",
223
223
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
224
224
  "sources": [
@@ -78,6 +78,7 @@
78
78
  }
79
79
  },
80
80
  "globalProps": true,
81
+ "globalEventProps": true,
81
82
  "usage": {
82
83
  "react": {
83
84
  "import": "import { Caption } from 'playbook-ui'",
@@ -160,7 +160,7 @@
160
160
  ],
161
161
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
162
162
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
163
- "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).",
163
+ "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).",
164
164
  "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.",
165
165
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
166
166
  "sources": [
@@ -194,13 +194,14 @@
194
194
  "type": "boolean",
195
195
  "example": "@user.errors[:terms].any?",
196
196
  "description": "Checkbox does not auto-map record.errors. Pass a boolean styling flag; render any error message separately."
197
- }
197
+ },
198
+ "client": "props.validation_message becomes data-message on the checkbox input."
198
199
  },
199
200
  "block": {
200
201
  "supported": false,
201
202
  "description": "The builder supplies the Rails checkbox as kit content; caller blocks are not forwarded."
202
203
  },
203
- "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 %>",
204
+ "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 %>",
204
205
  "kit": "checkbox",
205
206
  "signature": "check_box(name, props: {}, **options)",
206
207
  "sources": [
@@ -236,9 +237,10 @@
236
237
  "questions": [
237
238
  "How do I show ActiveRecord errors?",
238
239
  "Does required_indicator validate?",
239
- "How do I enable client validation?"
240
+ "How do I enable client validation?",
241
+ "How do I set a custom required-field message?"
240
242
  ],
241
- "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.",
243
+ "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.",
242
244
  "contractPaths": [
243
245
  "form.rails.builder.validation",
244
246
  "form.rails.builder.methods"
@@ -39,6 +39,7 @@
39
39
  }
40
40
  },
41
41
  "globalProps": true,
42
+ "globalEventProps": true,
42
43
  "usage": {
43
44
  "react": {
44
45
  "import": "import { Container } from 'playbook-ui'",
@@ -137,6 +137,7 @@
137
137
  }
138
138
  },
139
139
  "globalProps": true,
140
+ "globalEventProps": true,
140
141
  "usage": {
141
142
  "react": {
142
143
  "import": "import { Currency } from 'playbook-ui'",
@@ -43,6 +43,7 @@
43
43
  }
44
44
  },
45
45
  "globalProps": true,
46
+ "globalEventProps": true,
46
47
  "usage": {
47
48
  "react": {
48
49
  "import": "import { DashboardValue } from 'playbook-ui'",
@@ -427,7 +427,7 @@
427
427
  ],
428
428
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
429
429
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
430
- "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).",
430
+ "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).",
431
431
  "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.",
432
432
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
433
433
  "sources": [
@@ -503,9 +503,10 @@
503
503
  "questions": [
504
504
  "How do I show ActiveRecord errors?",
505
505
  "Does required_indicator validate?",
506
- "How do I enable client validation?"
506
+ "How do I enable client validation?",
507
+ "How do I set a custom required-field message?"
507
508
  ],
508
- "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.",
509
+ "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.",
509
510
  "contractPaths": [
510
511
  "form.rails.builder.validation",
511
512
  "form.rails.builder.methods"
@@ -65,6 +65,7 @@
65
65
  }
66
66
  },
67
67
  "globalProps": true,
68
+ "globalEventProps": true,
68
69
  "usage": {
69
70
  "react": {
70
71
  "import": "import { Detail } from 'playbook-ui'",
@@ -7,6 +7,56 @@
7
7
  "rails"
8
8
  ],
9
9
  "props": {
10
+ "async": {
11
+ "type": "boolean",
12
+ "platforms": [
13
+ "react",
14
+ "rails"
15
+ ],
16
+ "default": false
17
+ },
18
+ "loadOptions": {
19
+ "type": "LoadOptions",
20
+ "platforms": [
21
+ "react"
22
+ ]
23
+ },
24
+ "defaultOptions": {
25
+ "type": "boolean | GenericObject[]",
26
+ "platforms": [
27
+ "react"
28
+ ]
29
+ },
30
+ "cacheOptions": {
31
+ "type": "boolean",
32
+ "platforms": [
33
+ "react"
34
+ ]
35
+ },
36
+ "loading": {
37
+ "type": "boolean",
38
+ "platforms": [
39
+ "react"
40
+ ]
41
+ },
42
+ "onInputChange": {
43
+ "type": "function",
44
+ "platforms": [
45
+ "react"
46
+ ]
47
+ },
48
+ "value": {
49
+ "type": "GenericObject | GenericObject[] | null",
50
+ "platforms": [
51
+ "react"
52
+ ]
53
+ },
54
+ "renderOption": {
55
+ "type": "function",
56
+ "platforms": [
57
+ "react"
58
+ ]
59
+ },
10
60
  "autocomplete": {
11
61
  "type": "boolean",
12
62
  "platforms": [
@@ -125,6 +175,13 @@
125
175
  "rails"
126
176
  ]
127
177
  },
178
+ "noOptionsText": {
179
+ "type": "string",
180
+ "platforms": [
181
+ "react",
182
+ "rails"
183
+ ]
184
+ },
128
185
  "onChange": {
129
186
  "type": "function",
130
187
  "platforms": [
@@ -202,7 +259,8 @@
202
259
  "activeStyle": {
203
260
  "type": "GenericObject",
204
261
  "platforms": [
205
- "react"
262
+ "react",
263
+ "rails"
206
264
  ]
207
265
  },
208
266
  "requiredIndicator": {
@@ -220,6 +278,25 @@
220
278
  "type": "boolean",
221
279
  "default": false
222
280
  },
281
+ "validationMessage": {
282
+ "platforms": [
283
+ "rails"
284
+ ],
285
+ "type": "string",
286
+ "default": ""
287
+ },
288
+ "searchTermMinimumLength": {
289
+ "platforms": [
290
+ "rails"
291
+ ],
292
+ "default": 3
293
+ },
294
+ "searchDebounceTimeout": {
295
+ "platforms": [
296
+ "rails"
297
+ ],
298
+ "default": 250
299
+ },
223
300
  "searchbar": {
224
301
  "platforms": [
225
302
  "rails"
@@ -294,13 +371,13 @@
294
371
  "usage": {
295
372
  "react": {
296
373
  "import": "import { Dropdown } from 'playbook-ui'",
297
- "example": "<Dropdown variant=\"default\" placeholder=\"Select a country\" />",
298
- "preset": "Default trigger"
374
+ "example": "<Dropdown />",
375
+ "preset": "Async search"
299
376
  },
300
377
  "rails": {
301
378
  "import": null,
302
- "example": "<%= pb_rails(\"dropdown\", props: { variant: \"default\", placeholder: \"Select a country\" }) %>",
303
- "preset": "Default trigger"
379
+ "example": "<%= pb_rails(\"dropdown\") %>",
380
+ "preset": "Async search"
304
381
  }
305
382
  },
306
383
  "category": "form_selection",
@@ -315,7 +392,7 @@
315
392
  ],
316
393
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
317
394
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
318
- "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).",
395
+ "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).",
319
396
  "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.",
320
397
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
321
398
  "sources": [
@@ -356,9 +433,9 @@
356
433
  "example": "Omit props.error, or pass an explicit message / nil to override",
357
434
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
358
435
  },
359
- "client": "No validation or input_options prop is exposed by this Rails kit."
436
+ "client": "props.validation_message becomes data-message on the CSS-hidden input (single and multi-select)."
360
437
  },
361
- "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 %>",
438
+ "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 %>",
362
439
  "kit": "dropdown",
363
440
  "signature": "dropdown_field(name, props: {})",
364
441
  "sources": [
@@ -394,9 +471,10 @@
394
471
  "questions": [
395
472
  "How do I show ActiveRecord errors?",
396
473
  "Does required_indicator validate?",
397
- "How do I enable client validation?"
474
+ "How do I enable client validation?",
475
+ "How do I set a custom required-field message?"
398
476
  ],
399
- "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.",
477
+ "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.",
400
478
  "contractPaths": [
401
479
  "form.rails.builder.validation",
402
480
  "form.rails.builder.methods"
@@ -529,6 +607,78 @@
529
607
  "optionsEventType"
530
608
  ]
531
609
  },
610
+ {
611
+ "id": "dropdown.async-search",
612
+ "platforms": [
613
+ "rails"
614
+ ],
615
+ "questions": [
616
+ "How do I load Rails Dropdown options as the user types?"
617
+ ],
618
+ "answer": "Enable async with autocomplete or searchbar. Clicking inside an async Dropdown opens the menu. With no results yet, it shows the empty message (no_options_text, default \"No results found\") until the debounced search starts and replaces it with loading, results, or an error. The bubbling pb:dropdown:search event exposes searchingFor, setResults(options), and setError(). The kit debounces searches (search_debounce_timeout defaults to 250ms), requires search_term_minimum_length characters (default 3), and manages loading, empty results, errors and stale callbacks. Loaded results stay in place until that debounced search starts. Escape, Tab, or an outside click during the debounce keeps those results; dismissing an in-flight request restores them and ignores the late response. Opening the menu again searches for the query still in the input. Consumers fetch and map standard option objects or rich { option, content } entries, where content is an Element or DocumentFragment cloned into the option wrapper and option retains serializable selection data. Results bypass local label filtering while a search is in progress. When a search returns nothing, earlier results whose labels contain the query stay visible, including text typed after a space. After a single-select autocomplete selection, the input shows the selected label, and opening the menu again shows only retained results whose labels contain that text. A default_value is marked on a later result row with the same id, so opening the menu again narrows to labels that contain that default label. A multi-select selection clears the query and the loaded results, so opening the menu again shows the empty message until the next search. The typed query is not submitted by the Dropdown selected-id input. Keep a separate application field when free text must be submitted.",
619
+ "props": [
620
+ "async",
621
+ "autocomplete",
622
+ "searchbar",
623
+ "searchTermMinimumLength",
624
+ "searchDebounceTimeout"
625
+ ]
626
+ },
627
+ {
628
+ "id": "dropdown.async-selection-data",
629
+ "platforms": [
630
+ "rails"
631
+ ],
632
+ "questions": [
633
+ "Does async Dropdown preserve custom selection fields?",
634
+ "Can an async Dropdown have a default before options load?"
635
+ ],
636
+ "answer": "pb:dropdown:selected emits the complete serializable option object (an array for multi_select, null or [] when cleared), preserving custom fields and numeric IDs. Form input values are strings. Selected data is retained when remote results change; matching multi-select options remain hidden even if new result metadata differs. Options match on id, then value. Options with neither match the full payload, so two choices that only have a label stay distinct. Pass an explicit default_value option object or array with id and label to initialize async selection with options: []. The builder cannot infer that payload from an unmatched model ID.",
637
+ "props": [
638
+ "async",
639
+ "defaultValue",
640
+ "multiSelect"
641
+ ]
642
+ },
643
+ {
644
+ "id": "dropdown.async-input-reset",
645
+ "platforms": [
646
+ "rails"
647
+ ],
648
+ "questions": [
649
+ "How do I submit free text from an async Dropdown?",
650
+ "What happens when an async Dropdown is cleared or reset?"
651
+ ],
652
+ "answer": "Async Dropdown emits pb:dropdown:input immediately with { value, reason }, where reason is input, clear, or reset. Use input plus pb:dropdown:selected to synchronize application-owned text and ID fields. Emptying single-select autocomplete clears its selection; emptying a search bar or multi-select query preserves selection. Nonempty edits retain the selected value. Public clear and native form reset clear query, selection, remote results and pending callbacks, close the menu, and notify consumers. Native reset runs after browser controls reset and honors preventDefault; it clears rather than restores default_value. Synchronous Dropdowns retain their existing filtering, selection notifications and reset timing.",
653
+ "props": [
654
+ "async",
655
+ "clearable"
656
+ ]
657
+ },
658
+ {
659
+ "id": "dropdown.react-input-reset",
660
+ "platforms": [
661
+ "react"
662
+ ],
663
+ "questions": [
664
+ "How do I observe React Dropdown input changes?",
665
+ "How do I reset React Dropdown?",
666
+ "Does cacheOptions remember an empty search?"
667
+ ],
668
+ "answer": "Use onInputChange(text, { reason }) for input and clear notifications. Selection itself does not emit an input notification; use onSelect. In async mode, emptying single-select autocomplete proposes an empty selection even without onInputChange; emptying a multi-select or search-bar query preserves selection. With loadOptions, an empty query and a multi-select selection restore the defaultOptions results. A single-select autocomplete selection keeps that search result list and shows the selected label in the input; opening the menu again shows only results whose labels contain that text. Typing a character replaces the query only while the input still shows that label, including when a controlled value later arrives as null. Once the text has changed, further characters edit the query in place. Backspace and Delete remove one character and keep the selection until the query is empty. Escape, an outside click, or disabling the kit cancels an in-flight loadOptions request and ignores its late response. If that search had cleared the list, the last settled options return, or defaultOptions when nothing has settled yet. Opening the menu again searches for the query still in the input; ref.clearSelected() drops that retry. A search that already settled as an error or with no results keeps that message when the menu closes, and opening it again does not search again. Opening an async Dropdown with no source options, or a search that settles empty and has no earlier label matches, shows the empty message (noOptionsText, default \"No results found\"). When a search returns nothing, earlier results whose labels contain the query stay visible, including text typed after a space. cacheOptions stores the server response for that exact query, including an empty array. Each Dropdown keeps at most 100 queries. Errors are not cached. Repeating the query after a clear shows that cached response, so an empty search stays empty. Already-selected rows are hidden and do not count as an empty search, so a successful result list or an idle list that still contains options does not show that message when every remaining row is selected. blankSelection is not a search result: an empty async list shows the empty message instead of the blank row, and the blank row is included when results are present. Async options are identified by value, then id, then label. Reset controlled value through the application or form library, or call ref.clearSelected() for an uncontrolled selection. React Dropdown does not add native form-reset handling. For application-managed fetching, use async with options and loading without loadOptions; the application owns debounce, query thresholds, errors and stale-response protection. When the menu is open, a new result list focuses the first match so Enter selects it, for both loadOptions and application-managed options. ArrowDown and ArrowUp still move through that list.",
669
+ "props": [
670
+ "onInputChange",
671
+ "async",
672
+ "options",
673
+ "loading",
674
+ "loadOptions",
675
+ "value",
676
+ "defaultOptions",
677
+ "cacheOptions",
678
+ "noOptionsText",
679
+ "blankSelection"
680
+ ]
681
+ },
532
682
  {
533
683
  "id": "dropdown.react-form-libraries",
534
684
  "platforms": [
@@ -22,6 +22,7 @@
22
22
  }
23
23
  },
24
24
  "globalProps": true,
25
+ "globalEventProps": true,
25
26
  "usage": {
26
27
  "react": {
27
28
  "import": "import { Highlight } from 'playbook-ui'",
@@ -89,6 +89,7 @@
89
89
  }
90
90
  },
91
91
  "globalProps": true,
92
+ "globalEventProps": true,
92
93
  "usage": {
93
94
  "react": {
94
95
  "import": "import { IconStatValue } from 'playbook-ui'",
@@ -42,6 +42,7 @@
42
42
  }
43
43
  },
44
44
  "globalProps": true,
45
+ "globalEventProps": true,
45
46
  "usage": {
46
47
  "react": {
47
48
  "import": "import { IconValue } from 'playbook-ui'",
@@ -77,6 +77,7 @@
77
77
  }
78
78
  },
79
79
  "globalProps": true,
80
+ "globalEventProps": true,
80
81
  "usage": {
81
82
  "react": {
82
83
  "import": "import { LabelValue } from 'playbook-ui'",
@@ -37,6 +37,7 @@
37
37
  }
38
38
  },
39
39
  "globalProps": true,
40
+ "globalEventProps": true,
40
41
  "usage": {
41
42
  "react": {
42
43
  "import": "import { Legend } from 'playbook-ui'",
@@ -94,6 +94,7 @@
94
94
  }
95
95
  },
96
96
  "globalProps": true,
97
+ "globalEventProps": true,
97
98
  "usage": {
98
99
  "react": {
99
100
  "import": "import { Message } from 'playbook-ui'",