Merge branch 'master' into PLAY-1581

playbook-website/app/views/guides/getting_started/dependencies.md

@@ -0,0 +1,52 @@
+---
+title: Dependencies
+icon: code
+description: Some of our kits require additional libraries to run properly.
+---
+
+## Unbundled Dependencies
+
+These kits require you to install additional libraries to get full functionality.
+
+To install them add them to your project using `yarn add`, `npm install`, or manually add them to your `package.json` file.
+
+| Kit                 | Kit Link                                                                    | NPM Link(s)                                                                                              | Dependency(s)                               |
+|---------------------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|---------------------------------------------|
+| **Icon**            | [Icon](https://playbook.powerapp.cloud/kits/icon/react)                     | [fontawesome-free](https://www.npmjs.com/package/fontawesome-free)                                       | fontawesome-free                            |
+| **Icon Circle**     | [Icon Circle](https://playbook.powerapp.cloud/kits/icon_circle/react)       | [fontawesome-free](https://www.npmjs.com/package/fontawesome-free)                                       | fontawesome-free                            |
+| **Icon Stat Value** | [Icon Stat Value](https://playbook.powerapp.cloud/kits/icon_stat_value/react) | [fontawesome-free](https://www.npmjs.com/package/fontawesome-free)                                       | fontawesome-free                            |
+| **Icon Value**      | [Icon Value](https://playbook.powerapp.cloud/kits/icon_value/react)         | [fontawesome-free](https://www.npmjs.com/package/fontawesome-free)                                       | fontawesome-free                            |
+| **Map**             | [Map](https://playbook.powerapp.cloud/kits/map/react)                       | [maplibre-gl](https://www.npmjs.com/package/maplibre-gl)                                                 | maplibre-gl                                 |
+| **Rich Text Editor**<br>(TipTap Editor) | [Rich Text Editor](https://playbook.powerapp.cloud/kits/rich_text_editor/react) | - [@tiptap/core](https://www.npmjs.com/package/@tiptap/core)<br>- [@tiptap/react](https://www.npmjs.com/package/@tiptap/react)<br>- [@tiptap/starter-kit](https://www.npmjs.com/package/@tiptap/starter-kit)<br>- [@tiptap/extension-document](https://www.npmjs.com/package/@tiptap/extension-document)<br>- [@tiptap/extension-highlight](https://www.npmjs.com/package/@tiptap/extension-highlight)<br>- [@tiptap/extension-horizontal-rule](https://www.npmjs.com/package/@tiptap/extension-horizontal-rule)<br>- [@tiptap/extension-link](https://www.npmjs.com/package/@tiptap/extension-link)<br>- [@tiptap/extension-paragraph](https://www.npmjs.com/package/@tiptap/extension-paragraph)<br>- [@tiptap/extension-text](https://www.npmjs.com/package/@tiptap/extension-text)<br>- [@tiptap/pm](https://www.npmjs.com/package/@tiptap/pm) | - @tiptap/core<br>- @tiptap/react<br>- @tiptap/starter-kit<br>- @tiptap/extension-document<br>- @tiptap/extension-highlight<br>- @tiptap/extension-horizontal-rule<br>- @tiptap/extension-link<br>- @tiptap/extension-paragraph<br>- @tiptap/extension-text<br>- @tiptap/pm |
+
+## Bundled Dependencies
+
+These kits use dependencies that are bundled with them; no additional installation is required.
+
+| Kit                    | Kit Link                                                                    | NPM Link(s)                                                                                       | Dependency(s)                           |
+|------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|-----------------------------------------|
+| **Advanced Table**     | [Advanced Table](https://playbook.powerapp.cloud/kits/advanced_table/react) | [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)                      | @tanstack/react-table                   |
+| **Bar Graph**          | [Bar Graph](https://playbook.powerapp.cloud/kits/bar_graph/react)           | [highcharts](https://www.npmjs.com/package/highcharts),<br>[highcharts-react-official](https://www.npmjs.com/package/highcharts-react-official) | highcharts,<br>highcharts-react-official |
+| **Circle Chart**       | [Circle Chart](https://playbook.powerapp.cloud/kits/circle_chart/react)     | [highcharts](https://www.npmjs.com/package/highcharts),<br>[highcharts-react-official](https://www.npmjs.com/package/highcharts-react-official) | highcharts,<br>highcharts-react-official |
+| **Date Picker**        | [Date Picker](https://playbook.powerapp.cloud/kits/date_picker/react)       | [flatpickr](https://www.npmjs.com/package/flatpickr)                                              | flatpickr                               |
+| **Dialog**             | [Dialog](https://playbook.powerapp.cloud/kits/dialog/react)                 | [react-modal](https://www.npmjs.com/package/react-modal)                                          | react-modal                             |
+| **File Upload**        | [File Upload](https://playbook.powerapp.cloud/kits/file_upload/react)       | [react-dropzone](https://www.npmjs.com/package/react-dropzone)                                    | react-dropzone                          |
+| **Filter**             | [Filter](https://playbook.powerapp.cloud/kits/filter/react)                 | [react-popper](https://www.npmjs.com/package/react-popper)                                        | react-popper                            |
+| **Gauge**              | [Gauge](https://playbook.powerapp.cloud/kits/gauge/react)                   | [highcharts](https://www.npmjs.com/package/highcharts),<br>[highcharts-react-official](https://www.npmjs.com/package/highcharts-react-official) | highcharts,<br>highcharts-react-official |
+| **Highlight**          | [Highlight](https://playbook.powerapp.cloud/kits/highlight/react)           | [react-highlight-words](https://www.npmjs.com/package/react-highlight-words)                      | react-highlight-words                   |
+| **LightBox**           | [LightBox](https://playbook.powerapp.cloud/kits/lightbox/react)             | [react-zoom-pan-pinch](https://www.npmjs.com/package/react-zoom-pan-pinch)                        | react-zoom-pan-pinch                    |
+| **Line Graph**         | [Line Graph](https://playbook.powerapp.cloud/kits/line_graph/react)         | [highcharts](https://www.npmjs.com/package/highcharts),<br>[highcharts-react-official](https://www.npmjs.com/package/highcharts-react-official) | highcharts,<br>highcharts-react-official |
+| **Multi Level Select** | [Multi Level Select](https://playbook.powerapp.cloud/kits/multi_level_select/react) | [lodash](https://www.npmjs.com/package/lodash)                                                    | lodash                                  |
+| **Passphrase**         | [Passphrase](https://playbook.powerapp.cloud/kits/passphrase/react)         | [react-popper](https://www.npmjs.com/package/react-popper)                                        | react-popper                            |
+| **Phone Number Input** | [Phone Number Input](https://playbook.powerapp.cloud/kits/phone_number_input/react) | [intl-tel-input](https://www.npmjs.com/package/intl-tel-input)                                    | intl-tel-input                          |
+| **Popover**            | [Popover](https://playbook.powerapp.cloud/kits/popover/react)               | [lodash](https://www.npmjs.com/package/lodash),<br>[react-popper](https://www.npmjs.com/package/react-popper) | lodash,<br>react-popper                 |
+| **Rich Text Editor**<br>(Trix Editor) | [Rich Text Editor](https://playbook.powerapp.cloud/kits/rich_text_editor/react) | [trix](https://www.npmjs.com/package/trix),<br>[react-trix](https://www.npmjs.com/package/react-trix) | trix,<br>react-trix                     |
+| **Tooltip**            | [Tooltip](https://playbook.powerapp.cloud/kits/tooltip/react)               | [@floating-ui/react](https://www.npmjs.com/package/@floating-ui/react)                            | @floating-ui/react                      |
+| **Treemap Chart**      | [Treemap Chart](https://playbook.powerapp.cloud/kits/treemap_chart/react)   | [highcharts](https://www.npmjs.com/package/highcharts),<br>[highcharts-react-official](https://www.npmjs.com/package/highcharts-react-official) | highcharts,<br>highcharts-react-official |
+| **Typeahead**          | [Typeahead](https://playbook.powerapp.cloud/kits/typeahead/react)           | [react-select](https://www.npmjs.com/package/react-select),<br>[lodash](https://www.npmjs.com/package/lodash) | react-select,<br>lodash                 |
+| **Walkthrough**        | [Walkthrough](https://playbook.powerapp.cloud/kits/walkthrough/react)       | [react-joyride](https://www.npmjs.com/package/react-joyride)                                      | react-joyride                           |
+
+## Notes
+**Rich Text Editor**: This kit supports two different editors:
+**TipTap Editor**: Requires manual installation of `tiptap` and various `@tiptap/*` extensions (listed above under Unbundled Dependencies).
+**Trix Editor**: Dependencies (`trix` and `react-trix`) are bundled with the kit; no extra installation is needed.

playbook-website/app/views/guides/getting_started/font_awesome.md

@@ -0,0 +1,73 @@
+---
+title: Font Awesome Setup
+description: Playbook seamlessly integrates with Font Awesome, a leading icon library known for its extensive collection of high-quality, scalable icons. This integration not only enhances the visual appeal of websites and applications but also improves overall usability.
+icon: font-awesome
+---
+
+Playbook seamlessly integrates with [Font Awesome](https://fontawesome.com/), a leading icon library known for its extensive collection of high-quality, scalable icons. This integration not only enhances the visual appeal of websites and applications but also improves overall usability. 
+
+Some Font Awesome benefits:
+
+**1. Wide Range of Icons:** Font Awesome offers a vast selection of icons to suit a variety of needs. You can easily find the perfect icon for your project through their [icon search](https://fontawesome.com/search).
+**2. Ease of Use:** The icons are straightforward to implement. With just a few lines of code, you can quickly and easily add visual elements to your web projects. Note, a Pro subscription is required for access to a wider range of icons beyond the [Free set](https://fontawesome.com/search?o=r&m=free&s=regular).
+**3. Visual Appeal:** Incorporating these icons can improve the aesthetic of your site or application, making it more attractive to users. With Playbook, you have the flexibility to customize color, size, and animations.
+**4. User-Friendliness:** Icons can help users navigate and understand your website or application more efficiently, enhancing their overall experience. Font Awesome icons are web fonts compatible with most browsers and are optimized for performance and accessibility.
+
+Integrating Font Awesome with Playbook ensures that you have access to these benefits, making your projects more polished and professional.
+
+![fontawesome](https://github.com/user-attachments/assets/638b63ad-56d3-4819-8e05-fcbb175bedc7)
+
+## Ruby on Rails Setup (default with asset pipeline)
+
+**Make sure you are on Rails 7 or higher.**
+
+**1.** Follow the [Ruby on Rails Setup getting started page](/guides/getting_started/ruby_on_rails_setup) to setup Playbook with your Rails project.
+
+**2.** Setup Pro or Free Font Awesome to use our Icon Component.
+
+**Pro:**
+
+```rb
+# app/assets/stylesheets/application.scss
+ @import "font-awesome-pro";
+ @import "font-awesome-pro/solid";
+ @import "font-awesome-pro/regular";
+ @import "playbook";
+```
+
+```rb
+# app/Gemfile
+ source "https://token:[email protected]/basic/fontawesome-pro/ruby/" do
+   gem "font-awesome-pro-sass", "6.2.0"
+ end
+```
+
+**Free:**
+
+*Currently only [Free Regular](https://fontawesome.com/search?o=r&m=free&s=regular) icons are supported in our icon component structure.*
+
+```rb
+# app/assets/stylesheets/application.scss
+ @import "font-awesome";
+```
+
+```rb
+# app/Gemfile
+ source "https://token:[email protected]/basic/fontawesome-pro/ruby/" do
+   gem "font-awesome-pro-sass", "6.2.0"
+ end
+```
+
+**3.** Bundle all the things!
+
+```sh
+bundle install
+```
+
+**4.** **Go build awesome stuff!**
+
+Refer to our [Icon kit](/kits/icon) to get started with Font Awesome icons in Playbook. 
+
+```rb
+<%= pb_rails("icon", props: { icon: "font-awesome", fixed_width: true }) %>
+```

playbook-website/config/initializers/global_variables.rb

@@ -69,10 +69,11 @@
   ],
 }
 
-# Move HTML figma to the end
+# Move these pages to the end of the Getting Started page
+page_names = ["HTML&_CSS", "figma_setup", "how_to_theme", "dependencies", "font_awesome"]
 
-move_pages = navigation[:getting_started][:pages].select { |page| ["HTML&_CSS", "figma_setup", "how_to_theme"].include?(page[:page_id]) }
-navigation[:getting_started][:pages].reject! { |page| ["HTML&_CSS", "figma_setup", "how_to_theme"].include?(page[:page_id]) }
+move_pages = navigation[:getting_started][:pages].select { |page| page_names.include?(page[:page_id]) }
+navigation[:getting_started][:pages].reject! { |page| page_names.include?(page[:page_id]) }
 navigation[:getting_started][:pages].concat(move_pages)
 
 DOCS = navigation

playbook/app/pb_kits/playbook/pb_form_pill/_form_pill.scss

@@ -142,7 +142,9 @@ $form_pill_colors: map-merge($status_color_text, map-merge($data_colors, $produc
     height: 12px !important;
     width: 12px !important;
     padding-right: $space_xs;
-    + .pb_form_pill_text, + .pb_form_pill_tag {
+    + .pb_form_pill_text, + .pb_form_pill_tag, 
+    + .pb_tooltip_kit .pb_form_pill_text, + .pb_tooltip_kit .pb_form_pill_tag,
+    + div .pb_form_pill_text, + div .pb_form_pill_tag {
       padding-left: 0;
     }
   }
@@ -169,7 +171,9 @@ $form_pill_colors: map-merge($status_color_text, map-merge($data_colors, $produc
     }
     .pb_form_pill_icon {
       padding-right: $space_xxs;
-      + .pb_form_pill_text, + .pb_form_pill_tag {
+      + .pb_form_pill_text, + .pb_form_pill_tag, 
+      + .pb_tooltip_kit .pb_form_pill_text, + .pb_tooltip_kit .pb_form_pill_tag,
+      + div .pb_form_pill_text, + div .pb_form_pill_tag {
         padding-left: 0;
       }
     }

playbook/app/pb_kits/playbook/pb_form_pill/_form_pill.tsx

@@ -3,6 +3,7 @@ import classnames from 'classnames'
 import Title from '../pb_title/_title'
 import Icon from '../pb_icon/_icon'
 import Avatar from '../pb_avatar/_avatar'
+import Tooltip from '../pb_tooltip/_tooltip'
 import { globalProps, GlobalProps } from '../utilities/globalProps'
 import { buildDataProps, buildHtmlProps } from '../utilities/props'
 
@@ -62,6 +63,30 @@ const FormPill = (props: FormPillProps): React.ReactElement => {
   const dataProps = buildDataProps(data)
   const htmlProps = buildHtmlProps(htmlOptions)
 
+  const renderTitle = (content: string, className: string) => {
+    const titleComponent = (
+      <Title
+          className={className}
+          size={4}
+          text={content}
+          truncate={props.truncate}
+      />
+    )
+    if (props.truncate) {
+      return (
+        <Tooltip
+            interaction
+            placement="top"
+            position="fixed"
+            text={content}
+        >
+          {titleComponent}
+        </Tooltip>
+      )
+    }
+    return titleComponent
+  }
+
   return (
     <div className={css}
         id={id}
@@ -77,12 +102,7 @@ const FormPill = (props: FormPillProps): React.ReactElement => {
               size="xxs"
               status={null}
           />
-          <Title
-              className="pb_form_pill_text"
-              size={4}
-              text={name}
-              truncate={props.truncate}
-          />
+          {renderTitle(name, "pb_form_pill_text")}
         </>
       )}
       {((name && icon && !text) || (name && icon && text)) && (
@@ -93,12 +113,7 @@ const FormPill = (props: FormPillProps): React.ReactElement => {
               size="xxs"
               status={null}
           />
-          <Title
-              className="pb_form_pill_text"
-              size={4}
-              text={name}
-              truncate={props.truncate}
-          />
+          {renderTitle(name, "pb_form_pill_text")}
           <Icon
               className="pb_form_pill_icon"
               color={color}
@@ -113,22 +128,10 @@ const FormPill = (props: FormPillProps): React.ReactElement => {
               color={color}
               icon={icon}
           />
-          <Title
-              className="pb_form_pill_tag"
-              size={4}
-              text={text}
-              truncate={props.truncate}
-          />
+          {renderTitle(text, "pb_form_pill_tag")}
         </>
       )}
-      {(!name && !icon && text) && (
-        <Title
-            className="pb_form_pill_tag"
-            size={4}
-            text={text}
-            truncate={props.truncate}
-        />
-      )}
+      {(!name && !icon && text) && renderTitle(text, "pb_form_pill_tag")}
       <div
           className="pb_form_pill_close"
           onClick={onClick}
@@ -143,4 +146,5 @@ const FormPill = (props: FormPillProps): React.ReactElement => {
     </div>
   )
 }
+
 export default FormPill

playbook/app/pb_kits/playbook/pb_form_pill/docs/_form_pill_truncated_text.html.erb

@@ -13,7 +13,30 @@
     id: "typeahead-form-pill",
     is_multi: true,
     options: names,
-    label: "Names",
+    label: "Truncation Within Typeahead",
     pills: true,
     truncate: 1,
 }) %>
+
+<%= pb_rails("caption", props: { text: "Form Pill Truncation" }) %>
+<%= pb_rails("card", props: { max_width: "xs" })  do %>
+  <%= pb_rails("form_pill", props: {
+      name: "Princess Amelia Mignonette Grimaldi Thermopolis Renaldo",
+      avatar_url: "https://randomuser.me/api/portraits/women/44.jpg",
+      tabindex: 0,
+      truncate: 1,
+      id: "truncation-1"
+  }) %>
+  <%= pb_rails("form_pill", props: {
+      icon: "badge-check",
+      text: "icon and a very long tag to show truncation",
+      tabindex: 0,
+      truncate: 1,
+      id: "truncation-2"
+  }) %>
+  <%= pb_rails("form_pill", props: {
+      text: "form pill long tag no tooltip show truncation",
+      tabindex: 0,
+      truncate: 1,
+  }) %>
+<% end %>

playbook/app/pb_kits/playbook/pb_form_pill/docs/_form_pill_truncated_text.jsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import Typeahead from '../../pb_typeahead/_typeahead'
+import { Card, Caption, FormPill, Typeahead } from 'playbook-ui'
 
 const names = [
   { label: 'Alexander Nathaniel Montgomery', value: 'Alexander Nathaniel Montgomery' },
@@ -15,11 +15,34 @@ const FormPillTruncatedText = (props) => {
       <Typeahead
           htmlOptions={{ style: { maxWidth: "240px" }}}
           isMulti
-          label="Names"
+          label="Truncation Within Typeahead"
           options={names}
           truncate={1}
           {...props}
       />
+      <Caption text="Form Pill Truncation"/>
+      <Card maxWidth="xs">
+        <FormPill
+            avatarUrl="https://randomuser.me/api/portraits/women/44.jpg"
+            name="Princess Amelia Mignonette Grimaldi Thermopolis Renaldo"
+            onClick={() => alert('Click!')}
+            tabIndex={0}
+            truncate={1}
+        />
+        <FormPill
+            icon="badge-check"
+            onClick={() => {alert('Click!')}}
+            tabIndex={0}
+            text="icon and a very long tag to show truncation"
+            truncate={1}
+        />
+        <FormPill
+            onClick={() => {alert('Click!')}}
+            tabIndex={0}
+            text="form pill with a very long tag to show truncation"
+            truncate={1}
+        />
+      </Card>
     </>
   )
 }