playbook_ui_docs 16.7.0 → 16.8.0.pre.alpha.PLAY2945selectformblankselection16424

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

@@ -0,0 +1,99 @@
+{
+  "defaults": {
+    "accept": {},
+    "dark": false
+  },
+  "hiddenProps": [
+    "fileRejections",
+    "getInputProps",
+    "getRootProps",
+    "isDragActive",
+    "onFilesAccepted",
+    "onFilesRejected"
+  ],
+  "groups": [
+    {
+      "name": "Guidance",
+      "props": ["customMessage", "accept", "acceptedFilesDescription", "maxSize"]
+    },
+    {
+      "name": "State",
+      "props": ["error", "dark"]
+    }
+  ],
+  "presets": [
+    {
+      "name": "Default",
+      "props": {}
+    },
+    {
+      "name": "Accepted Types",
+      "props": {
+        "accept": {
+          "image/svg+xml": [".svg", ".xml"]
+        }
+      }
+    },
+    {
+      "name": "Custom Description",
+      "props": {
+        "accept": {
+          "application/pdf": [".pdf"],
+          "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": [".xlsx"]
+        },
+        "acceptedFilesDescription": "Adobe (.pdf) and Microsoft (.xlsx)"
+      }
+    },
+    {
+      "name": "Custom Message",
+      "props": {
+        "customMessage": "Playbook is awesome!"
+      }
+    },
+    {
+      "name": "Max File Size",
+      "props": {
+        "accept": {
+          "application/pdf": [".pdf"]
+        },
+        "maxSize": 1000000
+      }
+    },
+    {
+      "name": "Error State",
+      "props": {
+        "error": "Please upload a valid file"
+      }
+    }
+  ],
+  "conditionals": {
+    "acceptedFilesDescription": { "requires": "accept" }
+  },
+  "hints": {
+    "accepted_types_info": {
+      "presetName": "Accepted Types",
+      "message": "Use MIME-type keys with extension arrays for accept, for example { image/svg+xml: ['.svg', '.xml'] }.",
+      "type": "info"
+    },
+    "custom_description_info": {
+      "presetName": "Custom Description",
+      "message": "acceptedFilesDescription only changes the helper copy. File validation still comes from the accept object.",
+      "type": "info"
+    },
+    "custom_message_info": {
+      "presetName": "Custom Message",
+      "message": "customMessage replaces the built-in guidance, including accepted types and max file size text.",
+      "type": "info"
+    },
+    "max_size_info": {
+      "presetName": "Max File Size",
+      "message": "maxSize is measured in bytes. In app code, pair it with onFilesRejected to surface rejection details.",
+      "type": "warning"
+    },
+    "error_state_info": {
+      "presetName": "Error State",
+      "message": "Use the error prop for validation or server feedback below the dropzone.",
+      "type": "info"
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+<%
+  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),
+  ]
+%>
+
+<%= pb_form_with(scope: :example, url: "", method: :get) do |form| %>
+  <%= form.select :example_select, [ ["Yes", 1], ["No", 2], ["Maybe", 3] ], props: { label: "Select Default" } %>
+  <%= form.select :example_select_2, [ ["Yes", 1], ["No", 2], ["Maybe", 3] ], props: { label: "Select with Blank Selection", blank_selection: "Blank selection..." } %>
+  <%= form.select :example_select_3, [ ["Yes", 1], ["No", 2], ["Maybe", 3] ], { include_blank: "Include blank..." }, {}, props: { label: "Select with Include Blank" } %>
+  <%= form.collection_select :example_collection_select, example_collection, :value, :name, props: { label: "Collection Select Default" } %>
+  <%= form.collection_select :example_collection_select_2, example_collection, :value, :name, props: { label: "Collection Select with Blank Selection", blank_selection: "Blank selection..." } %>
+  <%= form.collection_select :example_collection_select_3, example_collection, :value, :name, { include_blank: "Include blank..." }, {}, props: { label: "Collection Select with Include Blank" } %>
+  <%= form.time_zone_select_field :example_time_zone_select, ActiveSupport::TimeZone.us_zones, props: { label: "Time Zone Select Default" } %>
+  <%= form.time_zone_select_field :example_time_zone_select_2, ActiveSupport::TimeZone.us_zones, { default: "Eastern Time (US & Canada)" }, props: { label: "Time Zone Select with a Default Selection" } %>
+  <%= form.time_zone_select_field :example_time_zone_select_3, ActiveSupport::TimeZone.us_zones, props: { label: "Time Zone Select with Blank Selection", blank_selection: "Blank selection..." }  %>
+  <%= form.time_zone_select_field :example_time_zone_select_4, ActiveSupport::TimeZone.us_zones, { include_blank: "Include blank..." }, {}, props: { label: "Time Zone Select with Include Blank" } %>
+  <%= form.actions do |action| %>
+    <%= action.submit %>
+    <%= action.button props: { type: "reset", text: "Cancel", variant: "secondary" } %>
+  <% end %>
+<% end %>

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

@@ -1,6 +1,7 @@
 examples:
 
   rails:
+  - form_form_with_select_examples: Select Examples
   - form_form_with: Default
   - form_form_with_validate: Default + Validation
   - form_form_with_validation_msg: Validation + Custom Validation Message

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

@@ -5,7 +5,9 @@
     "color": "default",
     "disabled": false,
     "tag": "a",
-    "underline": false
+    "underline": false,
+    "href": "#link-example",
+    "text": "Link text"
   },
   "children": {
     "editable": true,
@@ -28,6 +30,7 @@
       "props": [
         "href",
         "target",
+        "disabled",
         "tabIndex"
       ]
     },
@@ -36,78 +39,95 @@
       "props": [
         "color",
         "underline",
-        "disabled",
-        "tag"
+        "tag",
+        "dark"
       ]
     }
   ],
   "presets": [
     {
       "name": "Default",
-      "props": {},
-      "children": "Link text"
+      "props": {
+        "href": "#link-example",
+        "text": "Link text"
+      }
     },
     {
-      "name": "Muted underline",
+      "name": "Body color",
       "props": {
-        "color": "muted",
-        "underline": true
-      },
-      "children": "Secondary link"
+        "color": "body",
+        "href": "#body-link",
+        "text": "Inline body link"
+      }
     },
     {
-      "name": "Body color",
+      "name": "Muted underline",
       "props": {
-        "color": "body"
-      },
-      "children": "Inline body link"
+        "color": "muted",
+        "href": "#secondary-link",
+        "underline": true,
+        "text": "Secondary link"
+      }
     },
     {
       "name": "Destructive",
       "props": {
-        "color": "destructive"
-      },
-      "children": "Delete account"
+        "color": "destructive",
+        "href": "#delete-account",
+        "text": "Delete account"
+      }
     },
     {
-      "name": "With icon",
+      "name": "Leading icon",
       "props": {
         "color": "default",
-        "icon": "arrow-up-right-from-square"
-      },
-      "children": "Continue"
+        "href": "#continue",
+        "icon": "arrow-up-right-from-square",
+        "text": "Continue"
+      }
     },
     {
-      "name": "Icon both sides",
+      "name": "Trailing icon",
       "props": {
+        "href": "#details",
         "icon": "plus",
-        "iconRight": "chevron-right"
-      },
-      "children": "Open document"
+        "iconRight": "chevron-right",
+        "text": "Open document"
+      }
     },
     {
-      "name": "As heading tag",
+      "name": "Disabled",
       "props": {
-        "tag": "span"
-      },
-      "children": "Styled as link"
+        "disabled": true,
+        "href": "#disabled",
+        "text": "Disabled link"
+      }
     },
     {
-      "name": "With href",
+      "name": "Heading tag",
       "props": {
-        "href": "/dashboard",
-        "color": "default"
-      },
-      "children": "Go to dashboard"
+        "href": "#heading-link",
+        "icon": "arrow-up-right-from-square",
+        "tag": "h3",
+        "text": "Heading link"
+      }
     },
     {
       "name": "External new tab",
       "props": {
         "href": "https://example.com",
         "target": "_blank",
-        "icon": "arrow-up-right-from-square"
-      },
-      "children": "Example.com"
+        "icon": "arrow-up-right-from-square",
+        "text": "Example.com"
+      }
+    },
+    {
+      "name": "Span tag",
+      "props": {
+        "href": "#span-link",
+        "tag": "span",
+        "text": "Span link example"
+      }
     }
   ],
   "conditionals": {
@@ -119,11 +139,32 @@
     }
   },
   "hints": {
-    "target_needs_href": {
+    "external_target_info": {
+      "when": {
+        "target": "_blank"
+      },
+      "message": "Use target=\"_blank\" for external destinations that should open in a new tab.",
+      "type": "info"
+    },
+    "icon_pairing_info": {
+      "when": {
+        "iconRight": "chevron-right"
+      },
+      "message": "iconRight is available only when icon is also set, so the link can render a balanced icon treatment.",
+      "type": "info"
+    },
+    "disabled_info": {
+      "when": {
+        "disabled": true
+      },
+      "message": "Disabled links keep their visual treatment but should not be the only way to reach important actions.",
+      "type": "info"
+    },
+    "tag_semantics_info": {
       "when": {
-        "target": true
+        "tag": "h3"
       },
-      "message": "The target attribute only applies when href is set.",
+      "message": "Use tag to borrow link styling on semantic headings or inline text, but keep href when the element should still navigate.",
       "type": "info"
     }
   }

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

@@ -2,6 +2,14 @@
   "children": {
     "default": "Link text"
   },
+  "defaults": {
+    "color": "default",
+    "disabled": false,
+    "href": "#link-example",
+    "tag": "a",
+    "text": "Link text",
+    "underline": false
+  },
   "groups": [
     {
       "name": "Content",
@@ -9,62 +17,97 @@
     },
     {
       "name": "Behavior",
-      "props": ["href", "target", "tabIndex"]
+      "props": ["href", "target", "disabled", "tabIndex"]
     },
     {
       "name": "Appearance",
-      "props": ["color", "underline", "disabled", "tag"]
+      "props": ["color", "underline", "tag", "dark"]
     }
   ],
   "presets": [
     {
       "name": "Default",
-      "props": {},
-      "children": "Link text"
+      "props": {
+        "href": "#link-example",
+        "text": "Link text"
+      }
     },
     {
-      "name": "Muted underline",
-      "props": { "color": "muted", "underline": true },
-      "children": "Secondary link"
+      "name": "Body color",
+      "props": {
+        "color": "body",
+        "href": "#body-link",
+        "text": "Inline body link"
+      }
     },
     {
-      "name": "Body color",
-      "props": { "color": "body" },
-      "children": "Inline body link"
+      "name": "Muted underline",
+      "props": {
+        "color": "muted",
+        "href": "#secondary-link",
+        "underline": true,
+        "text": "Secondary link"
+      }
     },
     {
       "name": "Destructive",
-      "props": { "color": "destructive" },
-      "children": "Delete account"
+      "props": {
+        "color": "destructive",
+        "href": "#delete-account",
+        "text": "Delete account"
+      }
     },
     {
-      "name": "With icon",
-      "props": { "color": "default", "icon": "arrow-up-right-from-square" },
-      "children": "Continue"
+      "name": "Leading icon",
+      "props": {
+        "color": "default",
+        "href": "#continue",
+        "icon": "arrow-up-right-from-square",
+        "text": "Continue"
+      }
     },
     {
-      "name": "Icon both sides",
-      "props": { "icon": "plus", "iconRight": "chevron-right" },
-      "children": "Open document"
+      "name": "Trailing icon",
+      "props": {
+        "href": "#details",
+        "icon": "plus",
+        "iconRight": "chevron-right",
+        "text": "Open document"
+      }
     },
     {
-      "name": "As heading tag",
-      "props": { "tag": "span" },
-      "children": "Styled as link"
+      "name": "Disabled",
+      "props": {
+        "disabled": true,
+        "href": "#disabled",
+        "text": "Disabled link"
+      }
     },
     {
-      "name": "With href",
-      "props": { "href": "/dashboard", "color": "default" },
-      "children": "Go to dashboard"
+      "name": "Heading tag",
+      "props": {
+        "href": "#heading-link",
+        "icon": "arrow-up-right-from-square",
+        "tag": "h3",
+        "text": "Heading link"
+      }
     },
     {
       "name": "External new tab",
       "props": {
         "href": "https://example.com",
         "target": "_blank",
-        "icon": "arrow-up-right-from-square"
-      },
-      "children": "Example.com"
+        "icon": "arrow-up-right-from-square",
+        "text": "Example.com"
+      }
+    },
+    {
+      "name": "Span tag",
+      "props": {
+        "href": "#span-link",
+        "tag": "span",
+        "text": "Span link example"
+      }
     }
   ],
   "conditionals": {
@@ -72,9 +115,24 @@
     "iconRight": { "requires": "icon" }
   },
   "hints": {
-    "target_needs_href": {
-      "when": { "target": true },
-      "message": "The target attribute only applies when href is set.",
+    "external_target_info": {
+      "when": { "target": "_blank" },
+      "message": "Use target=\"_blank\" for external destinations that should open in a new tab.",
+      "type": "info"
+    },
+    "icon_pairing_info": {
+      "when": { "iconRight": "chevron-right" },
+      "message": "iconRight is available only when icon is also set, so the link can render a balanced icon treatment.",
+      "type": "info"
+    },
+    "disabled_info": {
+      "when": { "disabled": true },
+      "message": "Disabled links keep their visual treatment but should not be the only way to reach important actions.",
+      "type": "info"
+    },
+    "tag_semantics_info": {
+      "when": { "tag": "h3" },
+      "message": "Use tag to borrow link styling on semantic headings or inline text, but keep href when the element should still navigate.",
       "type": "info"
     }
   }

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

@@ -13,7 +13,8 @@
     "value": "",
     "formatAsYouType": false,
     "strictMode": false,
-    "countrySearch": false
+    "countrySearch": false,
+    "showPlaceholder": false
   },
   "groups": [
     {
@@ -37,7 +38,8 @@
         "value",
         "formatAsYouType",
         "strictMode",
-        "countrySearch"
+        "countrySearch",
+        "showPlaceholder"
       ]
     }
   ],

data/app/pb_kits/playbook/pb_rich_text_editor/docs/_rich_text_editor_rails_default.html.erb

@@ -0,0 +1 @@
+<%= pb_rails("rich_text_editor", props: { input_options: { id: 'hidden_input_id', name: "hidden_input_name" }, value: "Add your text here. You can format your text, add links, quotes, and bullets." }) %>

data/app/pb_kits/playbook/pb_rich_text_editor/docs/_rich_text_editor_rails_default.md

@@ -0,0 +1,12 @@
+The Rails rich text editor is a TipTap surface with no React. The UI (toolbar, block-style menu, formatting actions) is rendered with Playbook Rails kits (`pb_rails`). The editor document is a vanilla TipTap `Editor` instance; HTML is synced to a hidden `<input>` so standard Rails forms can submit the value.
+
+### How TipTap is loaded (Rails)
+
+- The kit’s module script (`rich_text_editor_rails.js`) uses `import()` with **full URLs** on [esm.sh](https://esm.sh) (e.g. `@tiptap/core@2.8.0`). esm.sh resolves dependencies server-side, so **no `<script type="importmap">`** is required—this avoids conflicts when the host page already has an import map (e.g. Vite in dev, or another app map) because Firefox only applies one native map.
+- You do not need TipTap in your app’s npm dependencies or Gemfile for this kit; the browser loads modules from esm.sh when the page runs.
+- Ensure **CSP** allows loading scripts from `https://esm.sh` (and esm.sh’s redirected module URLs) if you use a strict `script-src` / `connect-src`.
+
+### Relation to the React implementation
+
+- Same core: both use TipTap v2 on top of ProseMirror; styling lives in Playbook SCSS (`_tiptap_styles.scss`) so the editor chrome lines up between platforms.
+- Different shell: Rails uses ERB + Playbook Rails components + inline module script. React uses `RichTextEditor` / `_tiptap_editor.tsx` and TipTap wired through the bundled Playbook React package—see Advanced Default for that stack and when you need TipTap installed in your JavaScript bundle.

data/app/pb_kits/playbook/pb_rich_text_editor/docs/_rich_text_editor_rails_simple.html.erb

@@ -0,0 +1,9 @@
+<%= pb_rails("rich_text_editor", props: {
+  simple: true,
+  label: "Notes",
+  input_options: {
+    id: "rails_rte_simple_demo",
+    name: "content",
+  },
+  value: "<p>Use <strong>Bold</strong> and <em>Italic</em> from the toolbar.</p>",
+}) %>

data/app/pb_kits/playbook/pb_rich_text_editor/docs/_rich_text_editor_rails_simple.md

@@ -0,0 +1,8 @@
+### Simple toolbar (`simple: true`)
+
+Pass **`simple: true`** for a compact toolbar: **Bold**, **Italic**, **Undo**, and **Redo** (same history controls as the full toolbar—plain buttons, not popovers).
+
+- No block-style dropdown (no “Paragraph” / headings / lists in the menu).
+- No **`pb_popover`** on the toolbar—useful in **native `<dialog>`** modals, turbo-loaded panels, or other tight layouts where the full block menu is awkward to position.
+
+The underlying TipTap document still accepts the same HTML as the default Rails editor; `simple` only changes which **toolbar controls** are shown.

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

@@ -1,6 +1,8 @@
 examples:
 
   rails:
+  - rich_text_editor_rails_default: "Rails (TipTap)"
+  - rich_text_editor_rails_simple: "Rails (TipTap — Simple toolbar)"
 
   react:
   - rich_text_editor_advanced_default: Advanced Default