playbook_ui_docs 16.3.0 → 16.4.0.pre.alpha.PLAY2718containerfalseborderradiusresponsiveonly15164

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_custom_event_type.html.erb

@@ -0,0 +1,224 @@
+<%
+  default_options = [
+    { label: 'United States', value: 'unitedStates', id: 'us' },
+    { label: 'Canada', value: 'canada', id: 'ca' },
+    { label: 'Pakistan', value: 'pakistan', id: 'pk' },
+    { label: 'India', value: 'India', id: 'in' },
+    { label: 'Mexico', value: 'Mexico', id: 'mx' },
+  ]
+
+  multi_options = [
+    { label: 'United States', value: 'unitedStates', id: 'us' },
+    { label: 'Canada', value: 'canada', id: 'ca' },
+    { label: 'Pakistan', value: 'pakistan', id: 'pk' },
+    { label: 'India', value: 'india', id: 'in' },
+    { label: 'United Kingdom', value: 'unitedKingdom', id: 'uk' },
+  ]
+
+  autocomplete_options = [
+    { label: "United States", value: "unitedStates", areaCode: "+1", icon: "🇺🇸", id: "us" },
+    { label: "United Kingdom", value: "unitedKingdom", areaCode: "+44", icon: "🇬🇧", id: "gb" },
+    { label: "Pakistan", value: "pakistan", areaCode: "+92", icon: "🇵🇰", id: "pk" },
+  ]
+
+  custom_display_options = [
+    { label: "Strong Bad", value: "strongBad", id: "strong-bad", status: "Offline" },
+    { label: "Strong Mad", value: "strongMad", id: "strong-mad", status: "Online" },
+    { label: "Strong Sad", value: "strongSad", id: "strong-sad", status: "Away" },
+  ]
+
+  custom_display_content = capture do
+    pb_rails("flex", props: { align: "center" }) do
+      concat(pb_rails("avatar", props: { name: "", size: "xs", id: "cet-dropdown-avatar" }))
+      concat(pb_rails("body", props: { text: "", size: "xs", margin_x: "xs", id: "cet-dropdown-avatar-name" }))
+      concat(pb_rails("badge", props: { text: "", id: "cet-dropdown-avatar-status" }))
+    end
+  end
+%>
+
+<!-- Example 1: Default dropdown -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-default-cet",
+  label: "Default dropdown",
+  margin_bottom: "sm",
+  options: default_options,
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-default-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-default-cet", text: "Select Canada", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-default-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-default-cet";
+    document.getElementById("clear-default-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-default-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "ca" } }));
+    });
+    document.getElementById("simulate-default-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 2: Multi select -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-multi-cet",
+  label: "Multi select dropdown",
+  margin_bottom: "sm",
+  multi_select: true,
+  options: multi_options,
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-multi-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-multi-cet", text: "Select US + UK", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-multi-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-multi-cet";
+    document.getElementById("clear-multi-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-multi-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionIds: ["us", "uk"] } }));
+    });
+    document.getElementById("simulate-multi-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 3: Autocomplete -->
+<%= pb_rails("dropdown", props: {
+  autocomplete: true,
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-autocomplete-cet",
+  label: "Autocomplete dropdown",
+  margin_bottom: "sm",
+  options: autocomplete_options,
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-autocomplete-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-autocomplete-cet", text: "Select Pakistan", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-autocomplete-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-autocomplete-cet";
+    document.getElementById("clear-autocomplete-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-autocomplete-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "pk" } }));
+    });
+    document.getElementById("simulate-autocomplete-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 4: Quick pick (Date Range) -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-quickpick-cet",
+  label: "Quickpick dropdown",
+  margin_bottom: "sm",
+  variant: "quickpick",
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-quickpick-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-quickpick-cet", text: "Select This Week", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-quickpick-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-quickpick-cet";
+    document.getElementById("clear-quickpick-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-quickpick-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "quickpick-this-week" } }));
+    });
+    document.getElementById("simulate-quickpick-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 5: Custom display -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-custom-display-cet",
+  label: "Custom display (Subcomponent) dropdown",
+  margin_bottom: "sm",
+  options: custom_display_options,
+}) do %>
+  <%= pb_rails("dropdown/dropdown_trigger", props: { placeholder: "Select a User", custom_display: custom_display_content }) %>
+  <%= pb_rails("dropdown/dropdown_container") do %>
+    <% custom_display_options.each do |option| %>
+      <%= pb_rails("dropdown/dropdown_option", props: { option: option }) do %>
+        <%= pb_rails("flex", props: { align: "center", justify: "between" }) do %>
+          <%= pb_rails("flex/flex_item") do %>
+            <%= pb_rails("user", props: { name: option[:label], align: "left", avatar: true, orientation: "horizontal" }) %>
+          <% end %>
+          <%= pb_rails("flex/flex_item") do %>
+            <%= pb_rails("badge", props: { rounded: true, dark: true, text: option[:status], variant: option[:status] == "Offline" ? "neutral" : option[:status] == "Online" ? "success" : "warning" }) %>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-custom-display-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-custom-display-cet", text: "Select Strong Sad", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-custom-display-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-custom-display-cet";
+    document.getElementById("clear-custom-display-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-custom-display-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "strong-sad" } }));
+    });
+    document.getElementById("simulate-custom-display-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+
+    document.addEventListener("pb:dropdown:selected", function(e) {
+      if (e.target && e.target.id === id && e.detail) {
+        var display = e.target.querySelector("[data-dropdown-trigger-custom-display]");
+        if (!display) return;
+        var nameEl = display.querySelector("#cet-dropdown-avatar-name");
+        if (nameEl) nameEl.textContent = e.detail.label;
+        var avatarEl = display.querySelector("#cet-dropdown-avatar");
+        if (avatarEl) {
+          var wrapper = avatarEl.querySelector(".avatar_wrapper");
+          if (wrapper) {
+            var initials = (e.detail.label[0] + (e.detail.label.split(" ").pop() || "")[0]).toUpperCase();
+            wrapper.dataset.name = e.detail.label;
+            wrapper.setAttribute("data-initials", initials);
+          }
+        }
+        var badgeEl = display.querySelector("#cet-dropdown-avatar-status");
+        if (badgeEl && e.detail.status) {
+          var variant = e.detail.status === "Online" ? "success" : e.detail.status === "Offline" ? "neutral" : "warning";
+          badgeEl.querySelector("span").textContent = e.detail.status;
+          badgeEl.className = "pb_badge_kit_" + variant;
+        }
+      }
+    });
+  })();
+</script>

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_custom_event_type.md

@@ -0,0 +1,7 @@
+The `custom_event_type` prop lets the dropdown clear when specific events are dispatched. Set it to a comma-separated list of event names (e.g. Turbo or app-specific); when any of those events fire with optional `detail: { dropdownId }`, the matching dropdown clears. You can also listen for selection changes (`pb:dropdown:selected`), clear by dispatching `pb:dropdown:clear`, or set the selection by dispatching `pb:dropdown:select` with `detail: { dropdownId, optionId }` (or `optionIds` for multi-select).
+
+The examples show five distinct variants (default, multi select, autocomplete, quick pick, custom display). In each example, the first button clears the dropdown by dispatching a custom event that the dropdown listens for via `custom_event_type`. The second button sets the selection by dispatching `pb:dropdown:select`. The third button simulates a form submit by dispatching another custom event in `custom_event_type`, so the dropdown clears as it would after a real form submission.
+
+Turbo events (e.g. `turbo:frame-load`, `turbo:frame-render`, `turbo:submit-end`) often fire for many actions or across the page, so using them as `custom_event_type` can clear the dropdown more often than intended. Use them when that scope is what you want; otherwise use app-specific event names and dispatch with `detail: { dropdownId }` when the action happens, or dispatch `pb:dropdown:clear` from your own handler.
+
+Dropdowns with subcomponent structures that show custom displays (e.g. custom trigger or custom display) require a `pb:dropdown:selected` listener to update the visible UI from `event.detail` when a selection is made; clear is handled by the kit.

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

@@ -25,6 +25,7 @@ examples:
   - dropdown_separators_hidden: Separators Hidden
   - dropdown_with_clearable: Clearable
   - dropdown_with_constrain_height_rails: Constrain Height
+  - dropdown_closing_options_rails: Closing Options
   - dropdown_quickpick_rails: Quick Pick Variant
   - dropdown_quickpick_range_end_rails: Quick Pick Variant (Range Ends Today)
   - dropdown_quickpick_default_dates: Quick Pick Variant (Default Dates)
@@ -32,6 +33,7 @@ examples:
   - dropdown_quickpick_with_date_pickers_rails: Quick Pick with Date Pickers
   - dropdown_quickpick_with_date_pickers_default_rails: Quick Pick with Date Pickers (Default Value)
   - dropdown_required_indicator: Required Indicator
+  - dropdown_custom_event_type: Custom Event Type
 
   react:
   - dropdown_default: Default

data/app/pb_kits/playbook/pb_fixed_confirmation_toast/docs/_fixed_confirmation_toast_nav_margin.html.erb

@@ -0,0 +1,46 @@
+<%= pb_rails("button", props: { text: "Top Nav Toast", variant: "secondary", data: { toast: "#top-nav" } }) %>
+
+<%= pb_rails("fixed_confirmation_toast", props: {
+  classname: "top-nav-margin",
+  closeable: true,
+  id: "top-nav",
+  multi_line: true,
+  text: "Top nav Margin.",
+  status: "tip",
+  vertical: "top",
+  horizontal: "center",
+  nav_margin_top: true
+}) %>
+
+
+
+<script type="text/javascript">
+  const navtoast = document.querySelectorAll(".top-nav-margin")
+  const navbutton = document.querySelectorAll("button[data-toast]")
+
+  const hideNavToast = () => {
+    navtoast.forEach((toast) => {
+      toast.style.display = "none"
+    })
+  }
+
+  // Hide toasts immediately
+  hideNavToast()
+
+  // Handle various page load/restore events
+  window.addEventListener('pageshow', hideNavToast)
+  document.addEventListener('DOMContentLoaded', hideNavToast)
+  document.addEventListener('turbolinks:load', hideNavToast)
+  document.addEventListener('turbo:load', hideNavToast)
+
+  navbutton.forEach((button) => {
+    button.onclick = () => {
+      hideNavToast()
+      let toast = document.querySelector(button.getAttribute("data-toast"))
+
+      if (toast) {
+        toast.style.display = "flex"
+      }
+    }
+  })
+</script>

data/app/pb_kits/playbook/pb_fixed_confirmation_toast/docs/_fixed_confirmation_toast_nav_margin.jsx

@@ -0,0 +1,42 @@
+import React, { useState } from 'react'
+
+import Button from '../../pb_button/_button'
+import FixedConfirmationToast from '../_fixed_confirmation_toast'
+
+const FixedConfirmationToastNavMargin = (props) => {
+  const [openToast, setOpenToast] = useState(false)
+
+
+  const handleClickShort = () => {
+    setOpenToast(true)
+  }
+
+  const handleCloseShort = () => {
+    setOpenToast(false)
+  }
+
+  return (
+    <div>
+      <Button
+          onClick={handleClickShort}
+          text="Top Nav Margin"
+          variant="secondary"
+          {...props}
+      />
+
+      <FixedConfirmationToast
+          closeable
+          horizontal='center'
+          navMarginTop
+          onClose={handleCloseShort}
+          open={openToast}
+          status="tip"
+          text="Top nav Margin."
+          vertical='top'
+          {...props}
+      />
+    </div>
+  )
+}
+
+export default FixedConfirmationToastNavMargin

data/app/pb_kits/playbook/pb_fixed_confirmation_toast/docs/_fixed_confirmation_toast_nav_margin_rails.md

@@ -0,0 +1 @@
+Use the `nav_margin_top` prop to position the toast lower on the page. This is useful for cases where we want to position the toast below a header or nav.

data/app/pb_kits/playbook/pb_fixed_confirmation_toast/docs/_fixed_confirmation_toast_nav_margin_react.md

@@ -0,0 +1 @@
+Use the `navMarginTop` prop to position the toast lower on the page. This is useful for cases where we want to position the toast below a header or nav.

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

@@ -2,6 +2,7 @@ examples:
   
   rails:
   - fixed_confirmation_toast_default: Default
+  - fixed_confirmation_toast_nav_margin: Nav Margin Top
   - fixed_confirmation_toast_multi_line: Multi Line
   - fixed_confirmation_toast_close: Click to Close
   - fixed_confirmation_toast_positions: Click to Show Positions
@@ -12,6 +13,7 @@ examples:
   
   react:
   - fixed_confirmation_toast_default: Default
+  - fixed_confirmation_toast_nav_margin: Nav Margin Top
   - fixed_confirmation_toast_multi_line: Multi Line
   - fixed_confirmation_toast_close: Click to Close
   - fixed_confirmation_toast_positions: Click to Show Positions

data/app/pb_kits/playbook/pb_fixed_confirmation_toast/docs/index.js

@@ -5,4 +5,5 @@ export { default as FixedConfirmationToastPositions } from './_fixed_confirmatio
 export { default as FixedConfirmationToastAutoClose } from './_fixed_confirmation_toast_auto_close.jsx'
 export { default as FixedConfirmationToastChildren } from './_fixed_confirmation_toast_children.jsx'
 export { default as FixedConfirmationToastCustomIcon } from './_fixed_confirmation_toast_custom_icon.jsx'
-export { default as FixedConfirmationToastNoIcon } from './_fixed_confirmation_toast_no_icon.jsx'
+export { default as FixedConfirmationToastNoIcon } from './_fixed_confirmation_toast_no_icon.jsx'
+export { default as FixedConfirmationToastNavMargin } from './_fixed_confirmation_toast_nav_margin.jsx'

data/app/pb_kits/playbook/pb_popover/docs/_popover_placement.jsx

@@ -0,0 +1,81 @@
+import React, { useState } from 'react'
+
+import Button from '../../pb_button/_button'
+import Flex from '../../pb_flex/_flex'
+import PbReactPopover from '../../pb_popover/_popover'
+
+const ROWS = [
+  [
+    { placement: 'top', label: 'Top' },
+    { placement: 'top-start', label: 'Top start' },
+    { placement: 'top-end', label: 'Top end' },
+  ],
+  [
+    { placement: 'bottom', label: 'Bottom' },
+    { placement: 'bottom-start', label: 'Bottom start' },
+    { placement: 'bottom-end', label: 'Bottom end' },
+  ],
+  [
+    { placement: 'left', label: 'Left' },
+    { placement: 'left-start', label: 'Left start' },
+    { placement: 'left-end', label: 'Left end' },
+  ],
+  [
+    { placement: 'right', label: 'Right' },
+    { placement: 'right-start', label: 'Right start' },
+    { placement: 'right-end', label: 'Right end' },
+  ],
+]
+
+const PopoverPlacement = (props) => {
+  const [open, setOpen] = useState({})
+
+  const isOpen = (placement) => open[placement] === true
+  const setOpenFor = (placement) => (value) => setOpen((prev) => ({ ...prev, [placement]: value }))
+  const toggle = (placement) => setOpenFor(placement)(!isOpen(placement))
+  const handleShouldClose = (placement) => (shouldClose) => {
+    if (shouldClose) setOpenFor(placement)(false)
+  }
+
+  return (
+    <>
+      {ROWS.map((placements, rowIndex) => (
+        <Flex
+            justify="around"
+            key={placements[0].placement}
+            marginBottom={rowIndex < ROWS.length - 1 ? 'sm' : undefined}
+            orientation="row"
+            wrap
+            {...props}
+        >
+          {placements.map(({ placement, label }) => {
+            const trigger = (
+              <Button
+                  key={placement}
+                  onClick={() => toggle(placement)}
+                  text={label}
+                  variant="secondary"
+              />
+            )
+            return (
+              <PbReactPopover
+                  closeOnClick="outside"
+                  key={placement}
+                  offset
+                  placement={placement}
+                  reference={trigger}
+                  shouldClosePopover={handleShouldClose(placement)}
+                  show={isOpen(placement)}
+                  {...props}
+              >
+                {`Popover: ${label.toLowerCase()}`}
+              </PbReactPopover>
+            )
+          })}
+        </Flex>
+      ))}
+    </>
+  )
+}
+
+export default PopoverPlacement

data/app/pb_kits/playbook/pb_popover/docs/_popover_placement_react.md

@@ -0,0 +1 @@
+Use the `placement` prop to control where the popover appears relative to its trigger. Valid values include `top`, `bottom`, `left`, `right`, and aligned variants such as `top-start`, `top-end`, `bottom-start`, `bottom-end`, `left-start`, `left-end`, `right-start`, and `right-end`.

data/app/pb_kits/playbook/pb_popover/docs/_popover_position.html.erb

@@ -0,0 +1,128 @@
+<%= pb_rails("flex", props: { justify: "around", margin_bottom: "sm", orientation: "row", wrap: true }) do %>
+    <%= pb_rails("button", props: { text: "Top", variant: "secondary", id: "placement-popover-top" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-top",
+      tooltip_id: "placement-tooltip-top",
+      position: "top",
+      offset: true
+    }) do %>
+      Popover: top
+    <% end %>
+    <%= pb_rails("button", props: { text: "Top start", variant: "secondary", id: "placement-popover-top-start" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-top-start",
+      tooltip_id: "placement-tooltip-top-start",
+      position: "top-start",
+      offset: true
+    }) do %>
+      Popover: top start
+    <% end %>
+    <%= pb_rails("button", props: { text: "Top end", variant: "secondary", id: "placement-popover-top-end" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-top-end",
+      tooltip_id: "placement-tooltip-top-end",
+      position: "top-end",
+      offset: true
+    }) do %>
+      Popover: top end
+    <% end %>
+<% end %>
+<%= pb_rails("flex", props: { justify: "around", margin_bottom: "sm", orientation: "row", wrap: true }) do %>
+    <%= pb_rails("button", props: { text: "Bottom", variant: "secondary", id: "placement-popover-bottom" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-bottom",
+      tooltip_id: "placement-tooltip-bottom",
+      position: "bottom",
+      offset: true
+    }) do %>
+      Popover: bottom
+    <% end %>
+    <%= pb_rails("button", props: { text: "Bottom start", variant: "secondary", id: "placement-popover-bottom-start" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-bottom-start",
+      tooltip_id: "placement-tooltip-bottom-start",
+      position: "bottom-start",
+      offset: true
+    }) do %>
+      Popover: bottom start
+    <% end %>
+    <%= pb_rails("button", props: { text: "Bottom end", variant: "secondary", id: "placement-popover-bottom-end" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-bottom-end",
+      tooltip_id: "placement-tooltip-bottom-end",
+      position: "bottom-end",
+      offset: true
+    }) do %>
+      Popover: bottom end
+    <% end %>
+<% end %>
+<%= pb_rails("flex", props: { justify: "around", margin_bottom: "sm", orientation: "row", wrap: true }) do %>
+    <%= pb_rails("button", props: { text: "Left", variant: "secondary", id: "placement-popover-left" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-left",
+      tooltip_id: "placement-tooltip-left",
+      position: "left",
+      offset: true
+    }) do %>
+      Popover: left
+    <% end %>
+    <%= pb_rails("button", props: { text: "Left start", variant: "secondary", id: "placement-popover-left-start" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-left-start",
+      tooltip_id: "placement-tooltip-left-start",
+      position: "left-start",
+      offset: true
+    }) do %>
+      Popover: left start
+    <% end %>
+    <%= pb_rails("button", props: { text: "Left end", variant: "secondary", id: "placement-popover-left-end" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-left-end",
+      tooltip_id: "placement-tooltip-left-end",
+      position: "left-end",
+      offset: true
+    }) do %>
+      Popover: left end
+    <% end %>
+<% end %>
+<%= pb_rails("flex", props: { justify: "around", orientation: "row", wrap: true }) do %>
+    <%= pb_rails("button", props: { text: "Right", variant: "secondary", id: "placement-popover-right" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-right",
+      tooltip_id: "placement-tooltip-right",
+      position: "right",
+      offset: true
+    }) do %>
+      Popover: right
+    <% end %>
+    <%= pb_rails("button", props: { text: "Right start", variant: "secondary", id: "placement-popover-right-start" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-right-start",
+      tooltip_id: "placement-tooltip-right-start",
+      position: "right-start",
+      offset: true
+    }) do %>
+      Popover: right start
+    <% end %>
+    <%= pb_rails("button", props: { text: "Right end", variant: "secondary", id: "placement-popover-right-end" }) %>
+    <%= pb_rails("popover", props: {
+      close_on_click: "outside",
+      trigger_element_id: "placement-popover-right-end",
+      tooltip_id: "placement-tooltip-right-end",
+      position: "right-end",
+      offset: true
+    }) do %>
+      Popover: right end
+    <% end %>
+<% end %>

data/app/pb_kits/playbook/pb_popover/docs/_popover_position_rails.md

@@ -0,0 +1 @@
+Use the `position` prop to control where the popover appears relative to its trigger. Valid values include `top`, `bottom`, `left`, `right`, and aligned variants such as `top-start`, `top-end`, `bottom-start`, `bottom-end`, `left-start`, `left-end`, `right-start`, and `right-end`.

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

@@ -7,6 +7,7 @@ examples:
     - popover_scroll_height: Scroll and Height Settings
     - popover_actionable_content: With Actionable Content
     - popover_append_to: Append To
+    - popover_position: Position
 
   react:
     - popover_default: Default
@@ -16,3 +17,4 @@ examples:
     - popover_scroll_height: Scroll and Height Settings
     - popover_actionable_content: With Actionable Content
     - popover_append_to: Append To
+    - popover_placement: Placement

data/app/pb_kits/playbook/pb_popover/docs/index.js

@@ -4,4 +4,5 @@ export { default as PopoverClose } from './_popover_close.jsx'
 export { default as PopoverZIndex } from './_popover_z_index.jsx'
 export { default as PopoverScrollHeight } from './_popover_scroll_height.jsx'
 export { default as PopoverActionableContent } from './_popover_actionable_content.jsx'
-export { default as PopoverAppendTo } from './_popover_append_to.jsx'
+export { default as PopoverAppendTo } from './_popover_append_to.jsx'
+export { default as PopoverPlacement } from './_popover_placement.jsx'