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
@@ -1950,6 +1950,7 @@
1950
1950
  }
1951
1951
  },
1952
1952
  "globalProps": true,
1953
+ "globalEventProps": true,
1953
1954
  "usage": {
1954
1955
  "react": {
1955
1956
  "import": "import { Background } from 'playbook-ui'",
@@ -2412,7 +2413,7 @@
2412
2413
  ],
2413
2414
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
2414
2415
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
2415
- "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).",
2416
+ "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).",
2416
2417
  "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.",
2417
2418
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
2418
2419
  "sources": [
@@ -2634,6 +2635,7 @@
2634
2635
  }
2635
2636
  },
2636
2637
  "globalProps": true,
2638
+ "globalEventProps": true,
2637
2639
  "usage": {
2638
2640
  "react": {
2639
2641
  "import": "import { Caption } from 'playbook-ui'",
@@ -3015,7 +3017,7 @@
3015
3017
  ],
3016
3018
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
3017
3019
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
3018
- "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).",
3020
+ "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).",
3019
3021
  "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.",
3020
3022
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
3021
3023
  "sources": [
@@ -3049,13 +3051,14 @@
3049
3051
  "type": "boolean",
3050
3052
  "example": "@user.errors[:terms].any?",
3051
3053
  "description": "Checkbox does not auto-map record.errors. Pass a boolean styling flag; render any error message separately."
3052
- }
3054
+ },
3055
+ "client": "props.validation_message becomes data-message on the checkbox input."
3053
3056
  },
3054
3057
  "block": {
3055
3058
  "supported": false,
3056
3059
  "description": "The builder supplies the Rails checkbox as kit content; caller blocks are not forwarded."
3057
3060
  },
3058
- "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 %>",
3061
+ "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 %>",
3059
3062
  "kit": "checkbox",
3060
3063
  "signature": "check_box(name, props: {}, **options)",
3061
3064
  "sources": [
@@ -3091,9 +3094,10 @@
3091
3094
  "questions": [
3092
3095
  "How do I show ActiveRecord errors?",
3093
3096
  "Does required_indicator validate?",
3094
- "How do I enable client validation?"
3097
+ "How do I enable client validation?",
3098
+ "How do I set a custom required-field message?"
3095
3099
  ],
3096
- "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.",
3100
+ "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.",
3097
3101
  "contractPaths": [
3098
3102
  "form.rails.builder.validation",
3099
3103
  "form.rails.builder.methods"
@@ -3521,6 +3525,7 @@
3521
3525
  }
3522
3526
  },
3523
3527
  "globalProps": true,
3528
+ "globalEventProps": true,
3524
3529
  "usage": {
3525
3530
  "react": {
3526
3531
  "import": "import { Container } from 'playbook-ui'",
@@ -3773,6 +3778,7 @@
3773
3778
  }
3774
3779
  },
3775
3780
  "globalProps": true,
3781
+ "globalEventProps": true,
3776
3782
  "usage": {
3777
3783
  "react": {
3778
3784
  "import": "import { Currency } from 'playbook-ui'",
@@ -3833,6 +3839,7 @@
3833
3839
  }
3834
3840
  },
3835
3841
  "globalProps": true,
3842
+ "globalEventProps": true,
3836
3843
  "usage": {
3837
3844
  "react": {
3838
3845
  "import": "import { DashboardValue } from 'playbook-ui'",
@@ -4384,7 +4391,7 @@
4384
4391
  ],
4385
4392
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
4386
4393
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
4387
- "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).",
4394
+ "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).",
4388
4395
  "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.",
4389
4396
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
4390
4397
  "sources": [
@@ -4460,9 +4467,10 @@
4460
4467
  "questions": [
4461
4468
  "How do I show ActiveRecord errors?",
4462
4469
  "Does required_indicator validate?",
4463
- "How do I enable client validation?"
4470
+ "How do I enable client validation?",
4471
+ "How do I set a custom required-field message?"
4464
4472
  ],
4465
- "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.",
4473
+ "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.",
4466
4474
  "contractPaths": [
4467
4475
  "form.rails.builder.validation",
4468
4476
  "form.rails.builder.methods"
@@ -5072,6 +5080,7 @@
5072
5080
  }
5073
5081
  },
5074
5082
  "globalProps": true,
5083
+ "globalEventProps": true,
5075
5084
  "usage": {
5076
5085
  "react": {
5077
5086
  "import": "import { Detail } from 'playbook-ui'",
@@ -5406,6 +5415,56 @@
5406
5415
  "rails"
5407
5416
  ],
5408
5417
  "props": {
5418
+ "async": {
5419
+ "type": "boolean",
5420
+ "platforms": [
5421
+ "react",
5422
+ "rails"
5423
+ ],
5424
+ "default": false
5425
+ },
5426
+ "loadOptions": {
5427
+ "type": "LoadOptions",
5428
+ "platforms": [
5429
+ "react"
5430
+ ]
5431
+ },
5432
+ "defaultOptions": {
5433
+ "type": "boolean | GenericObject[]",
5434
+ "platforms": [
5435
+ "react"
5436
+ ]
5437
+ },
5438
+ "cacheOptions": {
5439
+ "type": "boolean",
5440
+ "platforms": [
5441
+ "react"
5442
+ ]
5443
+ },
5444
+ "loading": {
5445
+ "type": "boolean",
5446
+ "platforms": [
5447
+ "react"
5448
+ ]
5449
+ },
5450
+ "onInputChange": {
5451
+ "type": "function",
5452
+ "platforms": [
5453
+ "react"
5454
+ ]
5455
+ },
5456
+ "value": {
5457
+ "type": "GenericObject | GenericObject[] | null",
5458
+ "platforms": [
5459
+ "react"
5460
+ ]
5461
+ },
5462
+ "renderOption": {
5463
+ "type": "function",
5464
+ "platforms": [
5465
+ "react"
5466
+ ]
5467
+ },
5409
5468
  "autocomplete": {
5410
5469
  "type": "boolean",
5411
5470
  "platforms": [
@@ -5524,6 +5583,13 @@
5524
5583
  "rails"
5525
5584
  ]
5526
5585
  },
5586
+ "noOptionsText": {
5587
+ "type": "string",
5588
+ "platforms": [
5589
+ "react",
5590
+ "rails"
5591
+ ]
5592
+ },
5527
5593
  "onChange": {
5528
5594
  "type": "function",
5529
5595
  "platforms": [
@@ -5601,7 +5667,8 @@
5601
5667
  "activeStyle": {
5602
5668
  "type": "GenericObject",
5603
5669
  "platforms": [
5604
- "react"
5670
+ "react",
5671
+ "rails"
5605
5672
  ]
5606
5673
  },
5607
5674
  "requiredIndicator": {
@@ -5619,6 +5686,25 @@
5619
5686
  "type": "boolean",
5620
5687
  "default": false
5621
5688
  },
5689
+ "validationMessage": {
5690
+ "platforms": [
5691
+ "rails"
5692
+ ],
5693
+ "type": "string",
5694
+ "default": ""
5695
+ },
5696
+ "searchTermMinimumLength": {
5697
+ "platforms": [
5698
+ "rails"
5699
+ ],
5700
+ "default": 3
5701
+ },
5702
+ "searchDebounceTimeout": {
5703
+ "platforms": [
5704
+ "rails"
5705
+ ],
5706
+ "default": 250
5707
+ },
5622
5708
  "searchbar": {
5623
5709
  "platforms": [
5624
5710
  "rails"
@@ -5693,13 +5779,13 @@
5693
5779
  "usage": {
5694
5780
  "react": {
5695
5781
  "import": "import { Dropdown } from 'playbook-ui'",
5696
- "example": "<Dropdown variant=\"default\" placeholder=\"Select a country\" />",
5697
- "preset": "Default trigger"
5782
+ "example": "<Dropdown />",
5783
+ "preset": "Async search"
5698
5784
  },
5699
5785
  "rails": {
5700
5786
  "import": null,
5701
- "example": "<%= pb_rails(\"dropdown\", props: { variant: \"default\", placeholder: \"Select a country\" }) %>",
5702
- "preset": "Default trigger"
5787
+ "example": "<%= pb_rails(\"dropdown\") %>",
5788
+ "preset": "Async search"
5703
5789
  }
5704
5790
  },
5705
5791
  "category": "form_selection",
@@ -5714,7 +5800,7 @@
5714
5800
  ],
5715
5801
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
5716
5802
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
5717
- "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).",
5803
+ "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).",
5718
5804
  "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.",
5719
5805
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
5720
5806
  "sources": [
@@ -5755,9 +5841,9 @@
5755
5841
  "example": "Omit props.error, or pass an explicit message / nil to override",
5756
5842
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
5757
5843
  },
5758
- "client": "No validation or input_options prop is exposed by this Rails kit."
5844
+ "client": "props.validation_message becomes data-message on the CSS-hidden input (single and multi-select)."
5759
5845
  },
5760
- "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 %>",
5846
+ "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 %>",
5761
5847
  "kit": "dropdown",
5762
5848
  "signature": "dropdown_field(name, props: {})",
5763
5849
  "sources": [
@@ -5793,9 +5879,10 @@
5793
5879
  "questions": [
5794
5880
  "How do I show ActiveRecord errors?",
5795
5881
  "Does required_indicator validate?",
5796
- "How do I enable client validation?"
5882
+ "How do I enable client validation?",
5883
+ "How do I set a custom required-field message?"
5797
5884
  ],
5798
- "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.",
5885
+ "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.",
5799
5886
  "contractPaths": [
5800
5887
  "form.rails.builder.validation",
5801
5888
  "form.rails.builder.methods"
@@ -5928,6 +6015,78 @@
5928
6015
  "optionsEventType"
5929
6016
  ]
5930
6017
  },
6018
+ {
6019
+ "id": "dropdown.async-search",
6020
+ "platforms": [
6021
+ "rails"
6022
+ ],
6023
+ "questions": [
6024
+ "How do I load Rails Dropdown options as the user types?"
6025
+ ],
6026
+ "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.",
6027
+ "props": [
6028
+ "async",
6029
+ "autocomplete",
6030
+ "searchbar",
6031
+ "searchTermMinimumLength",
6032
+ "searchDebounceTimeout"
6033
+ ]
6034
+ },
6035
+ {
6036
+ "id": "dropdown.async-selection-data",
6037
+ "platforms": [
6038
+ "rails"
6039
+ ],
6040
+ "questions": [
6041
+ "Does async Dropdown preserve custom selection fields?",
6042
+ "Can an async Dropdown have a default before options load?"
6043
+ ],
6044
+ "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.",
6045
+ "props": [
6046
+ "async",
6047
+ "defaultValue",
6048
+ "multiSelect"
6049
+ ]
6050
+ },
6051
+ {
6052
+ "id": "dropdown.async-input-reset",
6053
+ "platforms": [
6054
+ "rails"
6055
+ ],
6056
+ "questions": [
6057
+ "How do I submit free text from an async Dropdown?",
6058
+ "What happens when an async Dropdown is cleared or reset?"
6059
+ ],
6060
+ "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.",
6061
+ "props": [
6062
+ "async",
6063
+ "clearable"
6064
+ ]
6065
+ },
6066
+ {
6067
+ "id": "dropdown.react-input-reset",
6068
+ "platforms": [
6069
+ "react"
6070
+ ],
6071
+ "questions": [
6072
+ "How do I observe React Dropdown input changes?",
6073
+ "How do I reset React Dropdown?",
6074
+ "Does cacheOptions remember an empty search?"
6075
+ ],
6076
+ "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.",
6077
+ "props": [
6078
+ "onInputChange",
6079
+ "async",
6080
+ "options",
6081
+ "loading",
6082
+ "loadOptions",
6083
+ "value",
6084
+ "defaultOptions",
6085
+ "cacheOptions",
6086
+ "noOptionsText",
6087
+ "blankSelection"
6088
+ ]
6089
+ },
5931
6090
  {
5932
6091
  "id": "dropdown.react-form-libraries",
5933
6092
  "platforms": [
@@ -7114,6 +7273,7 @@
7114
7273
  }
7115
7274
  },
7116
7275
  "globalProps": true,
7276
+ "globalEventProps": true,
7117
7277
  "usage": {
7118
7278
  "react": {
7119
7279
  "import": "import { Highlight } from 'playbook-ui'",
@@ -7640,6 +7800,7 @@
7640
7800
  }
7641
7801
  },
7642
7802
  "globalProps": true,
7803
+ "globalEventProps": true,
7643
7804
  "usage": {
7644
7805
  "react": {
7645
7806
  "import": "import { IconStatValue } from 'playbook-ui'",
@@ -7699,6 +7860,7 @@
7699
7860
  }
7700
7861
  },
7701
7862
  "globalProps": true,
7863
+ "globalEventProps": true,
7702
7864
  "usage": {
7703
7865
  "react": {
7704
7866
  "import": "import { IconValue } from 'playbook-ui'",
@@ -7927,6 +8089,7 @@
7927
8089
  }
7928
8090
  },
7929
8091
  "globalProps": true,
8092
+ "globalEventProps": true,
7930
8093
  "usage": {
7931
8094
  "react": {
7932
8095
  "import": "import { LabelValue } from 'playbook-ui'",
@@ -8110,6 +8273,7 @@
8110
8273
  }
8111
8274
  },
8112
8275
  "globalProps": true,
8276
+ "globalEventProps": true,
8113
8277
  "usage": {
8114
8278
  "react": {
8115
8279
  "import": "import { Legend } from 'playbook-ui'",
@@ -8622,6 +8786,7 @@
8622
8786
  }
8623
8787
  },
8624
8788
  "globalProps": true,
8789
+ "globalEventProps": true,
8625
8790
  "usage": {
8626
8791
  "react": {
8627
8792
  "import": "import { Message } from 'playbook-ui'",
@@ -8826,6 +8991,13 @@
8826
8991
  "accessories"
8827
8992
  ],
8828
8993
  "default": "primary"
8994
+ },
8995
+ "validationMessage": {
8996
+ "platforms": [
8997
+ "rails"
8998
+ ],
8999
+ "type": "string",
9000
+ "default": ""
8829
9001
  }
8830
9002
  },
8831
9003
  "globalProps": true,
@@ -8853,7 +9025,7 @@
8853
9025
  ],
8854
9026
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
8855
9027
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
8856
- "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).",
9028
+ "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).",
8857
9029
  "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.",
8858
9030
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
8859
9031
  "sources": [
@@ -8884,7 +9056,7 @@
8884
9056
  "multi": "Pass user[regions], without [], to submit user[regions][] entries."
8885
9057
  },
8886
9058
  "validation": {
8887
- "required": "props.required is used by the kit; hidden selected-value inputs also receive required. Do not infer native validation from hidden inputs.",
9059
+ "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.",
8888
9060
  "indicator": "props.required_indicator is visual only.",
8889
9061
  "error": {
8890
9062
  "automatic": true,
@@ -8892,9 +9064,10 @@
8892
9064
  "type": "string",
8893
9065
  "example": "Omit props.error, or pass an explicit message / nil to override",
8894
9066
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
8895
- }
9067
+ },
9068
+ "client": "props.validation_message becomes data-message on the search input. Kit JS clears custom validity when the selection changes."
8896
9069
  },
8897
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.multi_level_select :regions, props: { label: \"Regions\", tree_data: @regions, required: true } %>\n<% end %>",
9070
+ "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 %>",
8898
9071
  "kit": "multi_level_select",
8899
9072
  "signature": "multi_level_select(name, props: {})",
8900
9073
  "sources": [
@@ -8930,9 +9103,10 @@
8930
9103
  "questions": [
8931
9104
  "How do I show ActiveRecord errors?",
8932
9105
  "Does required_indicator validate?",
8933
- "How do I enable client validation?"
9106
+ "How do I enable client validation?",
9107
+ "How do I set a custom required-field message?"
8934
9108
  ],
8935
- "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.",
9109
+ "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.",
8936
9110
  "contractPaths": [
8937
9111
  "form.rails.builder.validation",
8938
9112
  "form.rails.builder.methods"
@@ -9076,6 +9250,7 @@
9076
9250
  }
9077
9251
  },
9078
9252
  "globalProps": true,
9253
+ "globalEventProps": true,
9079
9254
  "usage": {
9080
9255
  "react": {
9081
9256
  "import": "import { MultipleUsers } from 'playbook-ui'",
@@ -9141,6 +9316,7 @@
9141
9316
  }
9142
9317
  },
9143
9318
  "globalProps": true,
9319
+ "globalEventProps": true,
9144
9320
  "usage": {
9145
9321
  "react": {
9146
9322
  "import": "import { MultipleUsersStacked } from 'playbook-ui'",
@@ -10001,6 +10177,14 @@
10001
10177
  ],
10002
10178
  "default": false
10003
10179
  },
10180
+ "validationMessage": {
10181
+ "type": "string",
10182
+ "platforms": [
10183
+ "react",
10184
+ "rails"
10185
+ ],
10186
+ "default": ""
10187
+ },
10004
10188
  "value": {
10005
10189
  "type": "string",
10006
10190
  "platforms": [
@@ -10067,7 +10251,7 @@
10067
10251
  ],
10068
10252
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
10069
10253
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
10070
- "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).",
10254
+ "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).",
10071
10255
  "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.",
10072
10256
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
10073
10257
  "sources": [
@@ -10106,9 +10290,10 @@
10106
10290
  "type": "string",
10107
10291
  "example": "Omit props.error, or pass an explicit message / nil to override",
10108
10292
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
10109
- }
10293
+ },
10294
+ "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."
10110
10295
  },
10111
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.intl_telephone :phone, props: { label: \"Phone\", required: true } %>\n<% end %>",
10296
+ "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 %>",
10112
10297
  "kit": "phone_number_input",
10113
10298
  "signature": "intl_telephone(name, props: {})",
10114
10299
  "sources": [
@@ -10146,9 +10331,10 @@
10146
10331
  "type": "string",
10147
10332
  "example": "Omit props.error, or pass an explicit message / nil to override",
10148
10333
  "description": "Unless props.error is set (including explicit nil), the builder sets it from record.errors.full_messages_for(attribute).first when present."
10149
- }
10334
+ },
10335
+ "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."
10150
10336
  },
10151
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.phone_number_field :phone, props: { label: \"Phone\", required: true } %>\n<% end %>",
10337
+ "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 %>",
10152
10338
  "kit": "phone_number_input",
10153
10339
  "signature": "phone_number_field(name, props: {})",
10154
10340
  "sources": [
@@ -10184,9 +10370,10 @@
10184
10370
  "questions": [
10185
10371
  "How do I show ActiveRecord errors?",
10186
10372
  "Does required_indicator validate?",
10187
- "How do I enable client validation?"
10373
+ "How do I enable client validation?",
10374
+ "How do I set a custom required-field message?"
10188
10375
  ],
10189
- "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.",
10376
+ "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.",
10190
10377
  "contractPaths": [
10191
10378
  "form.rails.builder.validation",
10192
10379
  "form.rails.builder.methods"
@@ -11325,7 +11512,7 @@
11325
11512
  ],
11326
11513
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
11327
11514
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
11328
- "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).",
11515
+ "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).",
11329
11516
  "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.",
11330
11517
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
11331
11518
  "sources": [
@@ -11348,7 +11535,7 @@
11348
11535
  },
11349
11536
  "htmlOptions": {
11350
11537
  "argument": "html_options",
11351
- "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)."
11538
+ "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."
11352
11539
  },
11353
11540
  "validation": {
11354
11541
  "required": "props.required sets html_options.required.",
@@ -11388,7 +11575,7 @@
11388
11575
  },
11389
11576
  "htmlOptions": {
11390
11577
  "argument": "html_options",
11391
- "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)."
11578
+ "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."
11392
11579
  },
11393
11580
  "validation": {
11394
11581
  "required": "props.required sets html_options.required.",
@@ -11428,7 +11615,7 @@
11428
11615
  },
11429
11616
  "htmlOptions": {
11430
11617
  "argument": "html_options",
11431
- "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)."
11618
+ "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."
11432
11619
  },
11433
11620
  "validation": {
11434
11621
  "required": "props.required sets html_options.required.",
@@ -11482,9 +11669,10 @@
11482
11669
  "questions": [
11483
11670
  "How do I show ActiveRecord errors?",
11484
11671
  "Does required_indicator validate?",
11485
- "How do I enable client validation?"
11672
+ "How do I enable client validation?",
11673
+ "How do I set a custom required-field message?"
11486
11674
  ],
11487
- "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.",
11675
+ "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.",
11488
11676
  "contractPaths": [
11489
11677
  "form.rails.builder.validation",
11490
11678
  "form.rails.builder.methods"
@@ -11563,6 +11751,24 @@
11563
11751
  "contractPaths": [
11564
11752
  "form.rails.builder.simpleForm"
11565
11753
  ]
11754
+ },
11755
+ {
11756
+ "id": "select.builder-prompt",
11757
+ "platforms": [
11758
+ "rails"
11759
+ ],
11760
+ "questions": [
11761
+ "How do I omit the prompt in a select builder field?",
11762
+ "Does blank_selection override options.prompt?"
11763
+ ],
11764
+ "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.",
11765
+ "example": "<%= f.select :country, [[\"Canada\", \"ca\"]], { prompt: false }, {}, props: { label: true } %>",
11766
+ "contractPaths": [
11767
+ "form.rails.builder.methods"
11768
+ ],
11769
+ "props": [
11770
+ "blankSelection"
11771
+ ]
11566
11772
  }
11567
11773
  ]
11568
11774
  },
@@ -12308,6 +12514,13 @@
12308
12514
  "type": "boolean",
12309
12515
  "default": false
12310
12516
  },
12517
+ "validationMessage": {
12518
+ "platforms": [
12519
+ "rails"
12520
+ ],
12521
+ "type": "string",
12522
+ "default": ""
12523
+ },
12311
12524
  "inputOptions": {
12312
12525
  "platforms": [
12313
12526
  "rails"
@@ -12345,7 +12558,7 @@
12345
12558
  ],
12346
12559
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
12347
12560
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
12348
- "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).",
12561
+ "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).",
12349
12562
  "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.",
12350
12563
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
12351
12564
  "sources": [
@@ -12381,9 +12594,10 @@
12381
12594
  "supported": false,
12382
12595
  "automatic": false,
12383
12596
  "description": "This kit has no error prop. Render model errors separately."
12384
- }
12597
+ },
12598
+ "client": "props.validation_message becomes data-message on the CSS-hidden rating input."
12385
12599
  },
12386
- "example": "<%= pb_form_with model: @user do |f| %>\n <%= f.star_rating_field :rating, props: { label: \"Rating\", variant: \"interactive\", required: true } %>\n<% end %>",
12600
+ "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 %>",
12387
12601
  "kit": "star_rating",
12388
12602
  "signature": "star_rating_field(name, props: {})",
12389
12603
  "sources": [
@@ -12419,9 +12633,10 @@
12419
12633
  "questions": [
12420
12634
  "How do I show ActiveRecord errors?",
12421
12635
  "Does required_indicator validate?",
12422
- "How do I enable client validation?"
12636
+ "How do I enable client validation?",
12637
+ "How do I set a custom required-field message?"
12423
12638
  ],
12424
- "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.",
12639
+ "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.",
12425
12640
  "contractPaths": [
12426
12641
  "form.rails.builder.validation",
12427
12642
  "form.rails.builder.methods"
@@ -12599,6 +12814,7 @@
12599
12814
  }
12600
12815
  },
12601
12816
  "globalProps": true,
12817
+ "globalEventProps": true,
12602
12818
  "usage": {
12603
12819
  "react": {
12604
12820
  "import": "import { StatValue } from 'playbook-ui'",
@@ -13046,7 +13262,7 @@
13046
13262
  ],
13047
13263
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
13048
13264
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
13049
- "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).",
13265
+ "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).",
13050
13266
  "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.",
13051
13267
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
13052
13268
  "sources": [
@@ -13433,9 +13649,10 @@
13433
13649
  "questions": [
13434
13650
  "How do I show ActiveRecord errors?",
13435
13651
  "Does required_indicator validate?",
13436
- "How do I enable client validation?"
13652
+ "How do I enable client validation?",
13653
+ "How do I set a custom required-field message?"
13437
13654
  ],
13438
- "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.",
13655
+ "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.",
13439
13656
  "contractPaths": [
13440
13657
  "form.rails.builder.validation",
13441
13658
  "form.rails.builder.methods"
@@ -13711,7 +13928,7 @@
13711
13928
  ],
13712
13929
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
13713
13930
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
13714
- "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).",
13931
+ "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).",
13715
13932
  "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.",
13716
13933
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
13717
13934
  "sources": [
@@ -13798,9 +14015,10 @@
13798
14015
  "questions": [
13799
14016
  "How do I show ActiveRecord errors?",
13800
14017
  "Does required_indicator validate?",
13801
- "How do I enable client validation?"
14018
+ "How do I enable client validation?",
14019
+ "How do I set a custom required-field message?"
13802
14020
  ],
13803
- "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.",
14021
+ "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.",
13804
14022
  "contractPaths": [
13805
14023
  "form.rails.builder.validation",
13806
14024
  "form.rails.builder.methods"
@@ -14167,7 +14385,7 @@
14167
14385
  ],
14168
14386
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
14169
14387
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
14170
- "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).",
14388
+ "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).",
14171
14389
  "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.",
14172
14390
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
14173
14391
  "sources": [
@@ -14244,9 +14462,10 @@
14244
14462
  "questions": [
14245
14463
  "How do I show ActiveRecord errors?",
14246
14464
  "Does required_indicator validate?",
14247
- "How do I enable client validation?"
14465
+ "How do I enable client validation?",
14466
+ "How do I set a custom required-field message?"
14248
14467
  ],
14249
- "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.",
14468
+ "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.",
14250
14469
  "contractPaths": [
14251
14470
  "form.rails.builder.validation",
14252
14471
  "form.rails.builder.methods"
@@ -14856,6 +15075,7 @@
14856
15075
  }
14857
15076
  },
14858
15077
  "globalProps": true,
15078
+ "globalEventProps": true,
14859
15079
  "usage": {
14860
15080
  "react": {
14861
15081
  "import": "import { TitleCount } from 'playbook-ui'",
@@ -14909,6 +15129,7 @@
14909
15129
  }
14910
15130
  },
14911
15131
  "globalProps": true,
15132
+ "globalEventProps": true,
14912
15133
  "usage": {
14913
15134
  "react": {
14914
15135
  "import": "import { TitleDetail } from 'playbook-ui'",
@@ -15526,7 +15747,7 @@
15526
15747
  ],
15527
15748
  "setup": "<%= pb_form_with model: @user do |f| %>\n <%= f.text_field :email, props: { label: \"Email\", required: true } %>\n<% end %>",
15528
15749
  "formWith": "<%= form_with model: @user, builder: Playbook::Forms::Builder do |f| %>\n <%= f.text_field :email, props: { label: \"Email\" } %>\n<% end %>",
15529
- "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).",
15750
+ "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).",
15530
15751
  "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.",
15531
15752
  "simpleForm": "No Simple Form adapter is declared by this contract. These methods belong to Playbook::Forms::Builder.",
15532
15753
  "sources": [
@@ -15607,9 +15828,10 @@
15607
15828
  "questions": [
15608
15829
  "How do I show ActiveRecord errors?",
15609
15830
  "Does required_indicator validate?",
15610
- "How do I enable client validation?"
15831
+ "How do I enable client validation?",
15832
+ "How do I set a custom required-field message?"
15611
15833
  ],
15612
- "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.",
15834
+ "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.",
15613
15835
  "contractPaths": [
15614
15836
  "form.rails.builder.validation",
15615
15837
  "form.rails.builder.methods"