playbook_ui_docs 14.17.0.pre.alpha.PLAY1967bracketlayoutphase27244 → 14.17.0.pre.alpha.PLAY2040removeunnecessarystickytableclasses7300

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4755e7688ed6d715ceef4f5413393c7cc3f8b99223979f6d41be59a34dc80436
-  data.tar.gz: 785faad33b04324c95e4284a4596c9aa72ad32aee30b927584d63e276a3fbcbd
+  metadata.gz: 95b1ffffd04d0f52985d2753d9782ede5d406f3d8c499ed87be1778f4dbec8ae
+  data.tar.gz: 26533980f4d953a0a9b9fd1fa3ff6ab0e533abe8bc1bb714ce221a56f4929c17
 SHA512:
-  metadata.gz: 5245ac0dadd1e49e32c69bf232809d0c6e871e080df498065ccba8daebc26122932a5e68242835aebaa0465cd0b05a4e698fb0c5587336b2341ce67811e70e8a
-  data.tar.gz: f206a8505ffedb3ceddefde37f17b815dda881718aa209de9cb3291ad21d48c6625694e6d867805fa6354ac8f5928f3af131a737157dd63851c6dba085d01738
+  metadata.gz: ecdbb65ee9cc8ba3a9195bf93a43b7960eef0d0266a7c6636f68347c0871eb372435d84f884afea5aa4ef32a8e6521af107803dfd417a2eeb409e6ce0097875e
+  data.tar.gz: 8ad1efd4bf01caf640dbc5ed45bacfe8a67165a51e98faa9758c272fb36ff425ced04a6df681b29d2e8a68839a8531db21076cb97a0228545eb2a2ed3e5ee8bf

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_columns.jsx

@@ -0,0 +1,58 @@
+import React from "react"
+import AdvancedTable from '../../pb_advanced_table/_advanced_table'
+import MOCK_DATA from "./advanced_table_mock_data.json"
+
+const AdvancedTableStickyColumns = (props) => {
+  const columnDefinitions = [
+    {
+      accessor: "year",
+      label: "Year",
+      id: "year",
+      cellAccessors: ["quarter", "month", "day"],
+    },
+    {
+      accessor: "newEnrollments",
+      label: "New Enrollments",
+      id: "newEnrollments",
+    },
+    {
+      accessor: "scheduledMeetings",
+      label: "Scheduled Meetings",
+      id: "scheduledMeetings",
+    },
+    {
+      accessor: "attendanceRate",
+      label: "Attendance Rate",
+      id: "attendanceRate",
+    },
+    {
+      accessor: "completedClasses",
+      label: "Completed Classes",
+      id: "completedClasses",
+    },
+    {
+      accessor: "classCompletionRate",
+      label: "Class Completion Rate",
+      id: "classCompletionRate",
+    },
+    {
+      accessor: "graduatedStudents",
+      label: "Graduated Students",
+      id: "graduatedStudents",
+    },
+  ]
+
+  return (
+    <div>
+      <AdvancedTable
+          columnDefinitions={columnDefinitions}
+          responsive="none"
+          stickyLeftColumn={["year"]}
+          tableData={MOCK_DATA}
+          {...props}
+      />
+    </div>
+  )
+}
+
+export default AdvancedTableStickyColumns

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_columns.md

@@ -0,0 +1,6 @@
+To render sticky columns for the Advanced Table, you can use the `stickyLeftColumn` prop. This prop expects an array of the column ids you want to be sticky.
+
+To achieve this:
+- Make sure to provide an id for each column via columnDefinitions as shown below. Id can be any string. 
+- One or multiple columns can be made sticky, it is recommended to set the ids within `stickyLeftColumn` in the order in which the columns are rendered.
+- It is recommended to set `responsive` to none when using `stickyLeftColumn` since responsive just makes the first column sticky and the slightly different styling for `responsive` and `stickyLeftColumn` may override each other in unexpected ways.

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_columns_and_header.jsx

@@ -0,0 +1,64 @@
+import React from "react"
+import AdvancedTable from '../../pb_advanced_table/_advanced_table'
+import MOCK_DATA from "./advanced_table_mock_data.json"
+
+const AdvancedTableStickyColumnsAndHeader = (props) => {
+  const columnDefinitions = [
+    {
+      accessor: "year",
+      label: "Year",
+      id: "year",
+      cellAccessors: ["quarter", "month", "day"],
+    },
+    {
+      accessor: "newEnrollments",
+      label: "New Enrollments",
+      id: "newEnrollments",
+    },
+    {
+      accessor: "scheduledMeetings",
+      label: "Scheduled Meetings",
+      id: "scheduledMeetings",
+    },
+    {
+      accessor: "attendanceRate",
+      label: "Attendance Rate",
+      id: "attendanceRate",
+    },
+    {
+      accessor: "completedClasses",
+      label: "Completed Classes",
+      id: "completedClasses",
+    },
+    {
+      accessor: "classCompletionRate",
+      label: "Class Completion Rate",
+      id: "classCompletionRate",
+    },
+    {
+      accessor: "graduatedStudents",
+      label: "Graduated Students",
+      id: "graduatedStudents",
+    },
+  ]
+
+  const tableProps = {
+    sticky: true
+  }
+
+  return (
+    <div>
+      <AdvancedTable
+          columnDefinitions={columnDefinitions}
+          maxHeight="xs"
+          responsive="none"
+          stickyLeftColumn={["year"]}
+          tableData={MOCK_DATA}
+          tableProps={tableProps}
+          {...props}
+      />
+    </div>
+  )
+}
+
+export default AdvancedTableStickyColumnsAndHeader

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_columns_and_header.md

@@ -0,0 +1,8 @@
+To achieve a sticky header AND sticky columns together, in addition to the `stickyLeftColumn` logic outlined above, you can:
+
+- Set `sticky: true` via `tableProps`
+- Give the AdvancedTable a `maxHeight` using our [Max Height](https://playbook.powerapp.cloud/visual_guidelines/max_height) global prop. 
+
+**NOTE**: This behavior requires a `maxHeight` to work. The header is sticky within the table container, allowing for it to work along with the column stickiness.
+
+Expand the table above to see this in action.

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_header.jsx

@@ -0,0 +1,55 @@
+import React from "react"
+import AdvancedTable from '../../pb_advanced_table/_advanced_table'
+import MOCK_DATA from "./advanced_table_mock_data.json"
+
+const AdvancedTableStickyHeader = (props) => {
+  const columnDefinitions = [
+    {
+      accessor: "year",
+      label: "Year",
+      cellAccessors: ["quarter", "month", "day"],
+    },
+    {
+      accessor: "newEnrollments",
+      label: "New Enrollments",
+    },
+    {
+      accessor: "scheduledMeetings",
+      label: "Scheduled Meetings",
+    },
+    {
+      accessor: "attendanceRate",
+      label: "Attendance Rate",
+    },
+    {
+      accessor: "completedClasses",
+      label: "Completed Classes",
+    },
+    {
+      accessor: "classCompletionRate",
+      label: "Class Completion Rate",
+    },
+    {
+      accessor: "graduatedStudents",
+      label: "Graduated Students",
+    },
+  ]
+
+  const tableProps = {
+    sticky: true
+  }
+
+  return (
+    <div>
+      <AdvancedTable
+          columnDefinitions={columnDefinitions}
+          responsive="none"
+          tableData={MOCK_DATA}
+          tableProps={tableProps}
+          {...props}
+      />
+    </div>
+  )
+}
+
+export default AdvancedTableStickyHeader

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_header.md

@@ -0,0 +1,3 @@
+The `TableProps` prop can also be used to render a sticky header for the Advanced Table.
+
+This doc example showcases how to set a sticky header for a nonresponsive table (see the `responsive` prop set to "none"). To achieve sticky header AND responsive functionality, see the "Sticky Header for Responsive Table" doc example below.

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_header_rails.html.erb

@@ -0,0 +1,33 @@
+<% column_definitions = [
+    {
+      accessor: "year",
+      label: "Year",
+      cellAccessors: ["quarter", "month", "day"],
+    },
+    {
+      accessor: "newEnrollments",
+      label: "New Enrollments",
+    },
+    {
+      accessor: "scheduledMeetings",
+      label: "Scheduled Meetings",
+    },
+    {
+      accessor: "attendanceRate",
+      label: "Attendance Rate",
+    },
+    {
+      accessor: "completedClasses",
+      label: "Completed Classes",
+    },
+    {
+      accessor: "classCompletionRate",
+      label: "Class Completion Rate",
+    },
+    {
+      accessor: "graduatedStudents",
+      label: "Graduated Students",
+    }
+] %>
+
+<%= pb_rails("advanced_table", props: { id: "sticky_header_table", table_data: @table_data, column_definitions: column_definitions, responsive: "none", table_props: { sticky: true }}) %>

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_header_rails.md

@@ -0,0 +1,3 @@
+The `table_props` prop can also be used to render a sticky header for the Advanced Table.
+
+This doc example showcases how to set a sticky header for a nonresponsive table (see the `responsive` prop set to "none"). To achieve sticky header AND responsive functionality, see the "[Sticky Header for Responsive Table](https://playbook.powerapp.cloud/kits/advanced_table/react#sticky-header-for-responsive-table)" doc example below.

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_table_props.html.erb

@@ -30,4 +30,4 @@
     }
 ] %>
 
-<%= pb_rails("advanced_table", props: { id: "table_props_table", table_data: @table_data, column_definitions: column_definitions, responsive: "none", table_props: { container: false, sticky: true }}) %>
+<%= pb_rails("advanced_table", props: { id: "table_props_table", table_data: @table_data, column_definitions: column_definitions, table_props: { vertical_border: true, container: false }}) %>

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_table_props.jsx

@@ -37,14 +37,13 @@ const AdvancedTableTableProps = (props) => {
 
   const tableProps = {
     container: false,
-    sticky: true
+    verticalBorder: true
   }
 
   return (
     <div>
       <AdvancedTable
           columnDefinitions={columnDefinitions}
-          responsive="none"
           tableData={MOCK_DATA}
           tableProps={tableProps}
           {...props}

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_table_props_rails.md

@@ -1,3 +1,3 @@
-This kit uses the [Table kit](https://playbook.powerapp.cloud/kits/table) under the hood which comes with its own set of props. If you want to apply certain Table props to that underlying kit, you can do so by using the optional `table_props` prop. This prop must be an object that contains valid Table props. For a full list of Table props, see [here](https://playbook.powerapp.cloud/kits/table).
+This kit uses the [Table kit](https://playbook.powerapp.cloud/kits/table/react) under the hood which comes with its own set of props. If you want to apply certain Table props to that underlying kit, you can do so by using the optional `table_props` prop. This prop must be an object that contains valid Table props. For a full list of Table props, see [here](https://playbook.powerapp.cloud/kits/table/react).
 
-This doc example showcases how to set a sticky header for a nonresponsive table. To achieve sticky header AND responsive functionality, see the ["Table Props Sticky Header"](https://playbook.powerapp.cloud/kits/advanced_table#table-props-sticky-header) doc example below.
+This doc example showcases the use of two table props, including how to render the vertical borders between columns. 

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_table_props_react.md

@@ -1,3 +1,3 @@
 This kit uses the [Table kit](https://playbook.powerapp.cloud/kits/table/react) under the hood which comes with its own set of props. If you want to apply certain Table props to that underlying kit, you can do so by using the optional `tableProps` prop. This prop must be an object that contains valid Table props. For a full list of Table props, see [here](https://playbook.powerapp.cloud/kits/table/react).
 
-This doc example showcases how to set a sticky header for a nonresponsive table. To achieve sticky header AND responsive functionality, see the ["Table Props Sticky Header"](https://playbook.powerapp.cloud/kits/advanced_table/react#table-props-sticky-header) doc example below.
+This doc example showcases the use of two table props, including how to render the vertical borders between columns. 

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_table_props_sticky_header_rails.md

@@ -1,3 +1,7 @@
-Create a sticky header that works for responsive Advanced Tables by setting `sticky: true` via `table_props` and giving the AdvancedTable a `max_height` using our [Max Height](https://playbook.powerapp.cloud/visual_guidelines/max_height) global prop. This behavior requires a `max_height` to work. The header is sticky within the table container, allowing for it to work along with the first column stickiness of a responsive table on smaller screen sizes.
+Create a sticky header that works for responsive Advanced Tables by setting `sticky: true` via `table_props` and giving the AdvancedTable a `max_height` using our [Max Height](https://playbook.powerapp.cloud/visual_guidelines/max_height) global prop. 
 
-A sticky header on a nonresponsive table is demonstrated in the ["Table Props"](https://playbook.powerapp.cloud/kits/advanced_table#table-props) doc example above.
+**NOTE**: This behavior requires a `max_height` to work. The header is sticky within the table container, allowing for it to work along with the first column stickiness of a responsive table on smaller screen sizes.
+
+Expand the table above to see this in action.
+
+A sticky header on a nonresponsive table is demonstrated in the ["Sticky Header"](https://playbook.powerapp.cloud/kits/advanced_table#sticky-header) doc example above.

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_table_props_sticky_header_react.md

@@ -1,3 +1,7 @@
-Create a sticky header that works for responsive Advanced Tables by setting `sticky: true` via `tableProps` and giving the AdvancedTable a `maxHeight` using our [Max Height](https://playbook.powerapp.cloud/visual_guidelines/max_height) global prop. This behavior requires a `maxHeight` to work. The header is sticky within the table container, allowing for it to work along with the first column stickiness of a responsive table on smaller screen sizes.
+Create a sticky header that works for responsive Advanced Tables by setting `sticky: true` via `tableProps` and giving the AdvancedTable a `maxHeight` using our [Max Height](https://playbook.powerapp.cloud/visual_guidelines/max_height) global prop. 
 
-A sticky header on a nonresponsive table is demonstrated in the ["Table Props"](https://playbook.powerapp.cloud/kits/advanced_table/react#table-props) doc example above.
+**NOTE**: This behavior requires a `maxHeight` to work. The header is sticky within the table container, allowing for it to work along with the first column stickiness of a responsive table on smaller screen sizes.
+
+Expand the table above to see this in action.
+
+A sticky header on a nonresponsive table is demonstrated in the ["Sticky Header"](https://playbook.powerapp.cloud/kits/advanced_table/react#sticky-header) doc example above.

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

@@ -5,7 +5,8 @@ examples:
   - advanced_table_beta_subrow_headers: SubRow Headers
   - advanced_table_collapsible_trail_rails: Collapsible Trail
   - advanced_table_table_props: Table Props
-  - advanced_table_table_props_sticky_header: Table Props Sticky Header
+  - advanced_table_sticky_header_rails: Sticky Header
+  - advanced_table_table_props_sticky_header: Sticky Header for Responsive Table
   - advanced_table_beta_sort: Enable Sorting
   - advanced_table_responsive: Responsive Tables
   - advanced_table_custom_cell_rails: Custom Components for Cells
@@ -25,7 +26,10 @@ examples:
   - advanced_table_collapsible_trail: Collapsible Trail
   - advanced_table_table_options: Table Options
   - advanced_table_table_props: Table Props
-  - advanced_table_table_props_sticky_header: Table Props Sticky Header
+  - advanced_table_sticky_header: Sticky Header
+  - advanced_table_table_props_sticky_header: Sticky Header for Responsive Table
+  - advanced_table_sticky_columns: Sticky Columns
+  - advanced_table_sticky_columns_and_header: Sticky Columns with Sticky Header
   - advanced_table_inline_row_loading: Inline Row Loading
   - advanced_table_responsive: Responsive Tables
   - advanced_table_custom_cell: Custom Components for Cells

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

@@ -22,4 +22,7 @@ export { default as AdvancedTableSelectableRowsActions } from './_advanced_table
 export { default as AdvancedTableTablePropsStickyHeader } from './_advanced_table_table_props_sticky_header.jsx'
 export { default as AdvancedTableColumnHeadersCustomCell } from './_advanced_table_column_headers_custom_cell.jsx'
 export { default as AdvancedTableInlineEditing } from './_advanced_table_inline_editing.jsx'
-export { default as AdvancedTableFullscreen } from './_advanced_table_fullscreen.jsx'
+export { default as AdvancedTableFullscreen } from './_advanced_table_fullscreen.jsx'
+export { default as AdvancedTableStickyColumns } from './_advanced_table_sticky_columns.jsx'
+export { default as AdvancedTableStickyHeader } from './_advanced_table_sticky_header.jsx'
+export { default as AdvancedTableStickyColumnsAndHeader } from './_advanced_table_sticky_columns_and_header.jsx'

data/app/pb_kits/playbook/pb_copy_button/docs/_copy_button_hook.jsx

@@ -0,0 +1,54 @@
+import React, { useEffect, useState } from 'react'
+import usePBCopy from '../../pb_copy_button/usePBCopy'
+import Body from '../../pb_body/_body'
+import Textarea from '../../pb_textarea/_textarea'
+import Tooltip from '../../pb_tooltip/_tooltip'
+
+const CopyButtonHook = ({...props}) => {
+  // This is how you can use the copy button hook to copy text to the clipboard
+  // eslint-disable-next-line no-unused-vars
+  const [copied, copyToClipboard] = usePBCopy({ from: 'hookbody' })
+  // I added a tooltip so it looks better in the ui
+  const [showTooltip, setShowTooltip] = useState(false)
+
+  const handleCopy = () => {
+    copyToClipboard()
+    setShowTooltip(true)
+    setTimeout(() => setShowTooltip(false), 1500)
+  }
+
+  useEffect(() => {
+    const el = document.getElementById('hookbody')
+    if (!el) return
+
+    el.addEventListener('click', handleCopy)
+    return () => {
+      el.removeEventListener('click', handleCopy)
+    }
+  }, [copyToClipboard])
+
+  return (
+    <div>
+      <Tooltip
+          delay={{ close: 1000 }}
+          forceOpenTooltip={showTooltip}
+          placement="top"
+          showTooltip={false}
+          text="Copied!"
+      >
+        <Body
+            cursor="pointer"
+            id="hookbody"
+            text="I'm a custom copy hook! Click this body to copy this text!"
+        />
+      </Tooltip>
+
+      <Textarea
+          {...props}
+          placeholder="Paste here"
+      />
+    </div>
+  )
+}
+
+export default CopyButtonHook

data/app/pb_kits/playbook/pb_copy_button/docs/_copy_button_hook.md

@@ -0,0 +1,3 @@
+We provide a `usePBCopy` hook that you can import to your project. This hook will return a function that you can call to copy the text to the clipboard.
+
+`usePBCopy({ from: 'your_id' })` will grab the `innerText` from `your_id` element, or `value` if it is an input element.

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

@@ -6,3 +6,4 @@ examples:
   react:
   - copy_button_default: Default
   - copy_button_from: Copy From
+  - copy_button_hook: Copy Hook

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

@@ -1,2 +1,3 @@
 export { default as CopyButtonDefault } from './_copy_button_default.jsx'
-export { default as CopyButtonFrom } from './_copy_button_from.jsx'
+export { default as CopyButtonFrom } from './_copy_button_from.jsx' 
+export { default as CopyButtonHook } from './_copy_button_hook.jsx'

data/app/pb_kits/playbook/pb_form_group/docs/_form_group_select.html.erb

@@ -1,5 +1,4 @@
-<div>
-
+<%= pb_rails("flex", props: {orientation: "column", row_gap:"md"}) do %>
   <%= pb_rails("form_group") do %>
     <%= pb_rails("text_input", props: { placeholder: "Enter Artist Name" }) %>
     <%= pb_rails("select", props: {
@@ -17,8 +16,6 @@
       ]
     }) %>
   <% end %>
-  <br>
-  <br>
   <%= pb_rails("form_group") do %>
     <%= pb_rails("select", props: {
         blank_selection: "Phone",
@@ -32,4 +29,17 @@
         id: "phone"
     }) %>
   <% end %>
-</div>
+  <%= pb_rails("form_group") do %>
+      <%= pb_rails("phone_number_input", props: {
+        id: "phone2"
+      }) %>
+      <%= pb_rails("select", props: {
+        blank_selection: "Phone",
+        options: [
+          { value: "Cell" },
+          { value: "Work" },
+          { value: "Home" },
+        ]
+      }) %>
+  <% end %>
+<% end %>

data/app/pb_kits/playbook/pb_form_group/docs/_form_group_select.jsx

@@ -4,6 +4,7 @@ import FormGroup from '../_form_group'
 import PhoneNumberInput from '../../pb_phone_number_input/_phone_number_input'
 import Select from '../../pb_select/_select'
 import TextInput from '../../pb_text_input/_text_input'
+import Flex from '../../pb_flex/_flex'
 
 const FormGroupSelect = (props) => {
   const options = [
@@ -25,7 +26,10 @@ const FormGroupSelect = (props) => {
   ]
 
   return (
-    <div>
+    <Flex 
+        orientation="column" 
+        rowGap="md"
+    >
       <FormGroup>
         <TextInput
             placeholder="Enter Artist Name"
@@ -37,18 +41,29 @@ const FormGroupSelect = (props) => {
             {...props}
         />
       </FormGroup>
-      <br />
-      <br />
       <FormGroup>
         <Select
             blankSelection="Phone"
             options={phoneOptions}
-            />
+            {...props}
+        />
         <PhoneNumberInput
             id='default'
+            {...props}
         />
     </FormGroup>
-    </div>
+    <FormGroup>
+      <PhoneNumberInput
+          id='default-2'
+          {...props}
+      />
+      <Select
+          blankSelection="Phone"
+          options={phoneOptions}
+          {...props}
+      />
+    </FormGroup>
+    </Flex>
   )
 }
 

data/app/pb_kits/playbook/pb_overlay/docs/_overlay_color.jsx

@@ -0,0 +1,63 @@
+import React from 'react'
+
+import Overlay from '../../pb_overlay/_overlay'
+import Image from '../../pb_image/_image'
+import Flex from '../../pb_flex/_flex'
+
+const OverlayColor = () => (
+    <Flex
+        justify="around"
+        wrap
+    >
+        <Overlay
+            color="black"
+            marginBottom="xxs"
+        >
+          <Image
+              alt="picture of a misty forest"
+              display="block"
+              size="xl"
+              url="https://unsplash.it/500/400/?image=634"
+          />
+        </Overlay>
+        <Overlay
+            color="black"
+            gradient={false}
+            marginBottom="xxs"
+            opacity="opacity_4"
+        >
+          <Image
+              alt="picture of a misty forest"
+              display="block"
+              size="xl"
+              url="https://unsplash.it/500/400/?image=634"
+          />
+        </Overlay>
+        <Overlay
+            color="error"
+            marginBottom="xxs"
+        >
+          <Image
+              alt="picture of a misty forest"
+              display="block"
+              size="xl"
+              url="https://unsplash.it/500/400/?image=634"
+          />
+        </Overlay>
+        <Overlay
+            color="error"
+            gradient={false}
+            marginBottom="xxs"
+            opacity="opacity_4"
+        >
+          <Image
+              alt="picture of a misty forest"
+              display="block"
+              size="xl"
+              url="https://unsplash.it/500/400/?image=634"
+          />
+        </Overlay>
+    </Flex>
+)
+
+export default OverlayColor

data/app/pb_kits/playbook/pb_overlay/docs/_overlay_color.md

@@ -0,0 +1,3 @@
+The `color` prop is used to change the color of the solid or gradient mask. Gradient overlays always start opaque and fade to transparent.
+
+NOTE: Images are set to `display: block` to remove the default inline spacing caused by line height. This ensures the image fully fills the container without unexpected gaps.

data/app/pb_kits/playbook/pb_overlay/docs/_overlay_default.md

@@ -1,7 +1 @@
-Overlays optionally accept a `color`, which sets the "start" (opaque) color of a gradient mask. Because this overlay is intended to reveal underlying content, the "end" color is fixed to transparent. 
-
-The optional `layout` prop accepts the `position` and `size` of the overlay as a key:value pair.
-
-The `position` key accepts `bottom` (default), `top`, `y` (for both top and bottom) `right`, `left`, or `x` (for both left and right), which sets the side(s) where the `color` overlay starts. The direction of the overlay is always toward the opposite side of the position. For example, the default position of `bottom` starts the overlay on the bottom edge of your container and extends it toward the opposite side: the top.
-
-The `size` value is `full` (100%) by default, but accepts our [spacing tokens](https://playbook.powerapp.cloud/visual_guidelines/spacing) or a percentage value as a string, and literally translates to how much of the container is covered by the overlay(s). 
+Overlays help shift focus by dimming or masking background content. This kit supports gradient and solid color modes, with adjustable opacity to suit the context.

data/app/pb_kits/playbook/pb_overlay/docs/_overlay_gradient_opacity.jsx

@@ -0,0 +1,39 @@
+import React from 'react'
+
+import Overlay from '../../pb_overlay/_overlay'
+import Image from '../../pb_image/_image'
+import Flex from '../../pb_flex/_flex'
+
+const OverlayGradientOpacity = () => (
+    <Flex
+        justify="around"
+        wrap
+    >
+        <Overlay
+            gradient={false}
+            marginBottom="xxs"
+            opacity="opacity_2"
+        >
+          <Image
+              alt="picture of a misty forest"
+              display="block"
+              maxWidth="100%"
+              url="https://unsplash.it/500/400/?image=634"
+          />
+        </Overlay>
+        <Overlay
+            gradient={false}
+            marginBottom="xxs"
+            opacity="opacity_8"
+        >
+          <Image
+              alt="picture of a misty forest"
+              display="block"
+              maxWidth="100%"
+              url="https://unsplash.it/500/400/?image=634"
+          />
+        </Overlay>
+    </Flex>
+)
+
+export default OverlayGradientOpacity

data/app/pb_kits/playbook/pb_overlay/docs/_overlay_gradient_opacity.md

@@ -0,0 +1 @@
+By default, the overlay is rendered as a gradient. Setting the `gradient` prop to `false` renders the overlay as a solid color. You can adjust the transparency of the solid overlay by using the `opacity` prop.