playbook_ui_docs 16.5.0 → 16.6.0.pre.alpha.RTEPOC15805

data/app/pb_kits/playbook/pb_dropdown/docs/_playground.overrides.json

@@ -0,0 +1,137 @@
+{
+  "groups": [
+    {
+      "name": "Content",
+      "props": [
+        "label",
+        "placeholder",
+        "options",
+        "blankSelection",
+        "error"
+      ]
+    },
+    {
+      "name": "Appearance",
+      "props": [
+        "variant",
+        "separators",
+        "constrainHeight",
+        "clearable",
+        "requiredIndicator"
+      ]
+    },
+    {
+      "name": "State & behavior",
+      "props": [
+        "isClosed",
+        "multiSelect",
+        "autocomplete",
+        "closeOnClick",
+        "onSelect"
+      ]
+    },
+    {
+      "name": "Quick pick",
+      "props": [
+        "customQuickPickDates",
+        "rangeEndsToday",
+        "controlsStartId",
+        "controlsEndId"
+      ]
+    },
+    {
+      "name": "Values & forms",
+      "props": ["defaultValue", "formPillProps"]
+    }
+  ],
+  "presets": [
+    {
+      "name": "Default trigger",
+      "props": {
+        "variant": "default",
+        "placeholder": "Select a country",
+        "options": [
+          { "label": "United States", "value": "unitedStates", "id": "us" },
+          { "label": "Canada", "value": "canada", "id": "ca" },
+          { "label": "Mexico", "value": "mexico", "id": "mx" }
+        ]
+      }
+    },
+    {
+      "name": "Subtle trigger",
+      "props": {
+        "variant": "subtle",
+        "placeholder": "Choose an option",
+        "options": [
+          { "label": "Alpha", "value": "alpha", "id": "a" },
+          { "label": "Beta", "value": "beta", "id": "b" },
+          { "label": "Gamma", "value": "gamma", "id": "g" }
+        ]
+      }
+    },
+    {
+      "name": "Quick pick",
+      "props": {
+        "variant": "quickpick",
+        "label": "Date range"
+      }
+    },
+    {
+      "name": "Multi-select",
+      "props": {
+        "variant": "default",
+        "multiSelect": true,
+        "placeholder": "Select regions",
+        "options": [
+          { "label": "North", "value": "north", "id": "n" },
+          { "label": "South", "value": "south", "id": "s" },
+          { "label": "East", "value": "east", "id": "e" },
+          { "label": "West", "value": "west", "id": "w" }
+        ]
+      }
+    },
+    {
+      "name": "With error",
+      "props": {
+        "variant": "default",
+        "placeholder": "Required field",
+        "error": "Please make a selection.",
+        "options": [
+          { "label": "Option A", "value": "a", "id": "a" },
+          { "label": "Option B", "value": "b", "id": "b" }
+        ]
+      }
+    },
+    {
+      "name": "Search (autocomplete)",
+      "props": {
+        "variant": "default",
+        "autocomplete": true,
+        "placeholder": "Search…",
+        "options": [
+          { "label": "Apple", "value": "apple", "id": "1" },
+          { "label": "Apricot", "value": "apricot", "id": "2" },
+          { "label": "Banana", "value": "banana", "id": "3" }
+        ]
+      }
+    }
+  ],
+  "conditionals": {
+    "rangeEndsToday": { "requires": { "variant": "quickpick" } },
+    "controlsStartId": { "requires": { "variant": "quickpick" } },
+    "controlsEndId": { "requires": { "variant": "quickpick" } },
+    "customQuickPickDates": { "requires": { "variant": "quickpick" } }
+  },
+  "hints": {
+    "quickpick_scope": {
+      "when": { "variant": "quickpick" },
+      "message": "Quick pick uses preset date-range options. Use custom quick pick dates or range controls to tailor the menu.",
+      "type": "info"
+    },
+    "multi_options": {
+      "when": { "multiSelect": true },
+      "message": "Multi-select shows selected values as pills when applicable; use clearable to allow resetting.",
+      "type": "info"
+    }
+  }
+}

data/app/pb_kits/playbook/pb_empty_state/docs/_playground.json

@@ -0,0 +1,34 @@
+{
+  "template": "<EmptyState{{props}} />",
+  "propTargets": {},
+  "defaults": {
+    "alignment": "center",
+    "orientation": "vertical",
+    "size": "md"
+  },
+  "groups": [
+    {
+      "name": "Props",
+      "props": [
+        "alignment",
+        "description",
+        "header",
+        "image",
+        "linkButton",
+        "onLinkButtonClick",
+        "onPrimaryButtonClick",
+        "orientation",
+        "primaryButton",
+        "size"
+      ]
+    }
+  ],
+  "presets": [
+    {
+      "name": "Default",
+      "props": {}
+    }
+  ],
+  "conditionals": {},
+  "hints": {}
+}

data/app/pb_kits/playbook/pb_file_upload/docs/_playground.json

@@ -0,0 +1,34 @@
+{
+  "template": "<FileUpload{{props}} />",
+  "propTargets": {},
+  "defaults": {
+    "accept": ""
+  },
+  "groups": [
+    {
+      "name": "Props",
+      "props": [
+        "accept",
+        "customMessage",
+        "dark",
+        "acceptedFilesDescription",
+        "maxSize",
+        "onFilesAccepted",
+        "onFilesRejected",
+        "error",
+        "getRootProps",
+        "getInputProps",
+        "isDragActive",
+        "fileRejections"
+      ]
+    }
+  ],
+  "presets": [
+    {
+      "name": "Default",
+      "props": {}
+    }
+  ],
+  "conditionals": {},
+  "hints": {}
+}

data/app/pb_kits/playbook/pb_filter/docs/_playground.json

@@ -0,0 +1,13 @@
+{
+  "template": "<Filter{{props}} />",
+  "propTargets": {},
+  "defaults": {},
+  "presets": [
+    {
+      "name": "Default",
+      "props": {}
+    }
+  ],
+  "conditionals": {},
+  "hints": {}
+}

data/app/pb_kits/playbook/pb_fixed_confirmation_toast/docs/_playground.json

@@ -0,0 +1,37 @@
+{
+  "template": "<FixedConfirmationToast{{props}} />",
+  "propTargets": {},
+  "defaults": {
+    "closeable": false,
+    "multiLine": false,
+    "navMarginTop": false,
+    "status": "neutral"
+  },
+  "groups": [
+    {
+      "name": "Props",
+      "props": [
+        "autoClose",
+        "closeable",
+        "horizontal",
+        "icon",
+        "multiLine",
+        "navMarginTop",
+        "onClose",
+        "open",
+        "status",
+        "text",
+        "vertical",
+        "zIndex"
+      ]
+    }
+  ],
+  "presets": [
+    {
+      "name": "Default",
+      "props": {}
+    }
+  ],
+  "conditionals": {},
+  "hints": {}
+}

data/app/pb_kits/playbook/pb_flex/docs/_playground.json

@@ -0,0 +1,133 @@
+{
+  "template": "<Flex{{props}}>{{children}}</Flex>",
+  "propTargets": {},
+  "defaults": {
+    "horizontal": "left",
+    "justify": "none",
+    "inline": false,
+    "orientation": "row",
+    "spacing": "none",
+    "reverse": false,
+    "vertical": "top",
+    "align": "none",
+    "wrap": false,
+    "alignSelf": "none"
+  },
+  "children": {
+    "editable": true,
+    "default": "<Caption text=\"A\" /><Caption text=\"B\" /><Caption text=\"C\" />"
+  },
+  "groups": [
+    {
+      "name": "Direction & flow",
+      "props": [
+        "orientation",
+        "reverse",
+        "wrap",
+        "inline"
+      ]
+    },
+    {
+      "name": "Primary axis",
+      "props": [
+        "horizontal",
+        "justify",
+        "spacing"
+      ]
+    },
+    {
+      "name": "Cross axis",
+      "props": [
+        "vertical",
+        "align",
+        "alignSelf"
+      ]
+    }
+  ],
+  "presets": [
+    {
+      "name": "Row (start)",
+      "props": {
+        "orientation": "row",
+        "justify": "none",
+        "horizontal": "left",
+        "vertical": "top"
+      },
+      "children": "<Caption text=\"A\" /><Caption text=\"B\" /><Caption text=\"C\" />"
+    },
+    {
+      "name": "Column",
+      "props": {
+        "orientation": "column",
+        "justify": "none",
+        "horizontal": "left",
+        "vertical": "top"
+      },
+      "children": "<Caption text=\"One\" /><Caption text=\"Two\" /><Caption text=\"Three\" />"
+    },
+    {
+      "name": "Centered",
+      "props": {
+        "orientation": "row",
+        "justify": "center",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Centered\" />"
+    },
+    {
+      "name": "Space between",
+      "props": {
+        "orientation": "row",
+        "justify": "between",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Left\" /><Caption text=\"Right\" />"
+    },
+    {
+      "name": "Space around",
+      "props": {
+        "orientation": "row",
+        "justify": "around",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"A\" /><Caption text=\"B\" /><Caption text=\"C\" />"
+    },
+    {
+      "name": "End aligned",
+      "props": {
+        "orientation": "row",
+        "justify": "end",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Trailing\" />"
+    },
+    {
+      "name": "Wrap",
+      "props": {
+        "orientation": "row",
+        "wrap": true,
+        "justify": "start"
+      },
+      "children": "<Caption text=\"Item 1\" /><Caption text=\"Item 2\" /><Caption text=\"Item 3\" /><Caption text=\"Item 4\" />"
+    },
+    {
+      "name": "Inline flex",
+      "props": {
+        "inline": true,
+        "orientation": "row",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Inline\" /> <Caption text=\"chips\" />"
+    },
+    {
+      "name": "Column (center items)",
+      "props": {
+        "orientation": "column",
+        "align": "center"
+      },
+      "children": "<Caption text=\"Stacked\" /><Caption text=\"centered\" />"
+    }
+  ],
+  "conditionals": {},
+  "hints": {}
+}

data/app/pb_kits/playbook/pb_flex/docs/_playground.overrides.json

@@ -0,0 +1,105 @@
+{
+  "children": {
+    "default": "<Caption text=\"A\" /><Caption text=\"B\" /><Caption text=\"C\" />"
+  },
+  "groups": [
+    {
+      "name": "Direction & flow",
+      "props": ["orientation", "reverse", "wrap", "inline"]
+    },
+    {
+      "name": "Primary axis",
+      "props": ["horizontal", "justify", "spacing"]
+    },
+    {
+      "name": "Cross axis",
+      "props": ["vertical", "align", "alignSelf"]
+    }
+  ],
+  "presets": [
+    {
+      "name": "Row (start)",
+      "props": {
+        "orientation": "row",
+        "justify": "none",
+        "horizontal": "left",
+        "vertical": "top"
+      },
+      "children": "<Caption text=\"A\" /><Caption text=\"B\" /><Caption text=\"C\" />"
+    },
+    {
+      "name": "Column",
+      "props": {
+        "orientation": "column",
+        "justify": "none",
+        "horizontal": "left",
+        "vertical": "top"
+      },
+      "children": "<Caption text=\"One\" /><Caption text=\"Two\" /><Caption text=\"Three\" />"
+    },
+    {
+      "name": "Centered",
+      "props": {
+        "orientation": "row",
+        "justify": "center",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Centered\" />"
+    },
+    {
+      "name": "Space between",
+      "props": {
+        "orientation": "row",
+        "justify": "between",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Left\" /><Caption text=\"Right\" />"
+    },
+    {
+      "name": "Space around",
+      "props": {
+        "orientation": "row",
+        "justify": "around",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"A\" /><Caption text=\"B\" /><Caption text=\"C\" />"
+    },
+    {
+      "name": "End aligned",
+      "props": {
+        "orientation": "row",
+        "justify": "end",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Trailing\" />"
+    },
+    {
+      "name": "Wrap",
+      "props": {
+        "orientation": "row",
+        "wrap": true,
+        "justify": "start"
+      },
+      "children": "<Caption text=\"Item 1\" /><Caption text=\"Item 2\" /><Caption text=\"Item 3\" /><Caption text=\"Item 4\" />"
+    },
+    {
+      "name": "Inline flex",
+      "props": {
+        "inline": true,
+        "orientation": "row",
+        "vertical": "center"
+      },
+      "children": "<Caption text=\"Inline\" /> <Caption text=\"chips\" />"
+    },
+    {
+      "name": "Column (center items)",
+      "props": {
+        "orientation": "column",
+        "align": "center"
+      },
+      "children": "<Caption text=\"Stacked\" /><Caption text=\"centered\" />"
+    }
+  ],
+  "conditionals": {},
+  "hints": {}
+}

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

@@ -97,8 +97,8 @@
 }] %>
 
 <%= pb_form_with(scope: :example, method: :get, url: "", validate: true) do |form| %>
-  <%= form.typeahead :example_typeahead_validation, props: { data: { typeahead_example2: true, user: {} }, label: true, placeholder: "Search for a user", required: true, validation: { message: "Please select a user." } } %>
-  <%= form.typeahead :example_typeahead_validation_react, props: { options: example_typeahead_options, pills: true, label: "Example Typeahead (React Rendered)", placeholder: "Search for a user", required: true, validation: { message: "Please select a color." } } %>
+  <%= form.typeahead :example_typeahead_validation, props: { data: { typeahead_example2: true, user: {} }, label: true, placeholder: "Search for a user", required: true } %>
+  <%= form.typeahead :example_typeahead_validation_react, props: { options: example_typeahead_options, pills: true, label: "Example Typeahead (React Rendered)", placeholder: "Search for a user", required: true } %>
   <%= form.typeahead :example_typeahead_validation_react_2, props: { options: example_typeahead_options, pills: true, label: "Example Typeahead 2 (React Rendered)", placeholder: "Search for a user", required: true } %>
   <%= form.text_field :example_text_field_validation, props: { label: true, required: true } %>
   <%= form.phone_number_field :example_phone_number_field_validation, props: { label: "Example phone field", hidden_inputs: true, required: true } %>
@@ -110,14 +110,14 @@
   <%= form.text_area :example_text_area_validation, props: { label: true, required: true } %>
   <%= form.dropdown_field :example_dropdown_validation, props: { label: true, options: example_dropdown_options, required: true } %>
   <%= form.dropdown_field :example_dropdown_validation_multi, props: { label: true, options: example_dropdown_options, multi_select: true, required: true } %>
-  <%= form.select :example_select_validation, [ ["Yes", 1], ["No", 2] ], props: { label: true, blank_selection: "Select One...", required: true, validation_message: "Please, select an option." } %>
+  <%= form.select :example_select_validation, [ ["Yes", 1], ["No", 2] ], props: { label: true, blank_selection: "Select One...", required: true } %>
   <%= form.collection_select :example_collection_select_validation, example_collection, :value, :name, props: { label: true, blank_selection: "Select One...", required: true } %>
   <%= form.check_box :example_checkbox_validation, props: { text: "Example Checkbox Validation", label: true, required: true }, checked_value: "1", unchecked_value: "0" %>
-  <%= form.date_picker :example_date_picker_2, props: { label: true, required: true, validation_message: "Please, select a date.", allow_input: true } %>
+  <%= form.date_picker :example_date_picker_2, props: { label: true, required: true, allow_input: true } %>
   <%= form.star_rating_field :example_star_rating_validation, props: { variant: "interactive", label: true, required: true } %>
   <%= form.time_zone_select_field :example_time_zone_select, ActiveSupport::TimeZone.us_zones, { default: "Eastern Time (US & Canada)" }, props: { label: true, blank_selection: "Select a Time Zone...", required: true } %>
   <%= form.multi_level_select :example_multi_level_select, props: { id: "multi-level-select-form", tree_data: treeData, margin_bottom: "sm", required: true, label: "Example Multi Level Select field" } %>
-  <%= form.time_picker :example_time_picker_validation, props: { label: true, required: true, validation_message: "Please select a time." } %>
+  <%= form.time_picker :example_time_picker_validation, props: { label: true, required: true } %>
  
   <%= form.actions do |action| %>
     <%= action.submit %>

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

@@ -0,0 +1,90 @@
+<%
+  example_collection = [
+    OpenStruct.new(name: "Alabama", value: 1),
+    OpenStruct.new(name: "Alaska", value: 2),
+    OpenStruct.new(name: "Arizona", value: 3),
+    OpenStruct.new(name: "Arkansas", value: 4),
+    OpenStruct.new(name: "California", value: 5),
+    OpenStruct.new(name: "Colorado", value: 6),
+    OpenStruct.new(name: "Connecticut", value: 7),
+    OpenStruct.new(name: "Delaware", value: 8),
+    OpenStruct.new(name: "Florida", value: 9),
+    OpenStruct.new(name: "Georgia", value: 10),
+  ]
+%>
+
+
+<%
+  example_typeahead_options = [
+    { label: 'Orange', value: '#FFA500' },
+    { label: 'Red', value: '#FF0000' },
+    { label: 'Green', value: '#00FF00' },
+    { label: 'Blue', value: '#0000FF' },
+  ]
+%>
+
+
+<%= pb_form_with(scope: :example, method: :get, url: "", validate: true) do |form| %>
+  <%= form.text_field :example_text_field_validation_msg, props: { label: "Text Field With Validation Message", required: true, validation: { message: "I am a custom validation message for text field." } } %>
+  <%= form.typeahead :example_typeahead_validation_msg, props: { data: { typeahead_example_msg: true, user: {} }, label: "Typeahead With Validation Message", placeholder: "Search for a user", required: true, validation: { message: "I am a custom validation message for typeahead." } } %>
+  <%= form.typeahead :example_typeahead_validation_react_msg, props: { options: example_typeahead_options, pills: true, label: "Typeahead With Validation Message (React Rendered)", placeholder: "Search for a color", required: true, validation: { message: "I am a custom validation message for React typeahead." } } %>
+  <%= form.select :example_select_validation_msg, [ ["Yes", 1], ["No", 2] ], props: { label: true, blank_selection: "Select One...", required: true, validation_message: "I am a custom validation message for select." } %>
+  <%= form.collection_select :example_collection_select_validation_msg, example_collection, :value, :name, props: { label: "Collection Select With Validation Message", blank_selection: "Select a State...", required: true, validation_message: "I am a custom validation message for collection select." } %>
+  <%= form.date_picker :example_date_picker_validation_msg, props: { label: "Date Picker With Validation Message", required: true, validation_message: "I am a custom validation message for date picker.", allow_input: true } %>
+  <%= form.time_picker :example_time_picker_validation_msg, props: { label: "Time Picker With Validation Message", required: true, validation_message: "I am a custom validation message for time picker." } %>
+
+  <%= form.actions do |action| %>
+    <%= action.submit %>
+    <%= action.button props: { type: "reset", text: "Cancel", variant: "secondary" } %>
+  <% end %>
+<% end %>
+
+<!-- form.typeahead user results example template -->
+<template data-typeahead-example-result-option>
+  <%= pb_rails("user", props: {
+    name: tag(:slot, name: "name"),
+    orientation: "horizontal",
+    align: "left",
+    avatar_url: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR4nGP6zwAAAgcBApocMXEAAAAASUVORK5CYII=",
+    avatar: true
+    }) %>
+</template>
+
+<!-- form.typeahead JS example implementation -->
+<%= javascript_tag defer: "defer" do %>
+  document.addEventListener("pb-typeahead-kit-search", function(event) {
+    if (!event.target.dataset || !event.target.dataset.typeaheadExampleMsg) return
+
+    fetch(`https://api.github.com/search/users?q=${encodeURIComponent(event.detail.searchingFor)}`)
+      .then(response => response.json())
+      .then((result) => {
+        const resultOptionTemplate = document.querySelector("[data-typeahead-example-result-option]")
+
+        event.detail.setResults((result.items || []).map((user) => {
+          const wrapper = resultOptionTemplate.content.cloneNode(true)
+          wrapper.children[0].dataset.user = JSON.stringify(user)
+          wrapper.querySelector('slot[name="name"]').replaceWith(user.login)
+          wrapper.querySelector('img').dataset.src = user.avatar_url
+          return wrapper
+        }))
+      })
+  })
+
+
+  document.addEventListener("pb-typeahead-kit-result-option-selected", function(event) {
+    if (!event.target.dataset.typeaheadExampleMsg) return
+
+    const selectedUserJSON = event.detail.selected.firstElementChild.dataset.user
+    const selectedUserData = JSON.parse(selectedUserJSON)
+
+    // set the input field's value
+    event.target.querySelector('input[name=example_typeahead_validation_msg]').value = selectedUserData.login
+
+    // log the selected option's dataset
+    console.log('The selected user data:')
+    console.dir(selectedUserData)
+
+    // do even more with the data later - TBD
+    event.target.dataset.user = selectedUserJSON
+  })
+<% end %>

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

@@ -0,0 +1,13 @@
+Custom validation messages allow you to override the browser's default validation text with your own messaging. This provides a better user experience by giving specific, actionable feedback.
+
+**Text-based inputs** (TextInput, Typeahead) use the `validation` prop with a `message` key:
+```ruby
+validation: { message: "Please enter a valid email address." }
+```
+
+**Selection-based inputs** (Select, DatePicker, TimePicker) use the `validation_message` prop:
+```ruby
+validation_message: "Please select an option."
+```
+
+When a required field is left empty or fails validation, your custom message will display instead of the generic browser default.

data/app/pb_kits/playbook/pb_form/docs/_playground.json

@@ -0,0 +1,13 @@
+{
+  "template": "<Form{{props}} />",
+  "propTargets": {},
+  "defaults": {},
+  "presets": [
+    {
+      "name": "Default",
+      "props": {}
+    }
+  ],
+  "conditionals": {},
+  "hints": {}
+}

data/app/pb_kits/playbook/pb_form/docs/example.yml

@@ -3,5 +3,6 @@ examples:
   rails:
   - form_form_with: Default
   - form_form_with_validate: Default + Validation
+  - form_form_with_validation_msg: Validation + Custom Validation Message
   - form_form_with_loading: Default + Loading
   - form_with_required_indicator: With Optional Required Indicator