Merge branch 'master' into play/1571_dependencies_document

playbook-website/config/menu.yml

@@ -542,6 +542,9 @@ kits:
       be followed by Title 2s followed by Title 3s and so on, without skipping any
       levels.
     status: stable
+  - name: link
+    platforms: *1
+    status: beta
 - category: user
   description:
   components:

playbook/README.md

@@ -0,0 +1,94 @@
+[![npm version](https://badge.fury.io/js/playbook-ui.svg)](https://badge.fury.io/js/playbook-ui)
+[![Gem Version](https://badge.fury.io/rb/playbook_ui.svg)](https://badge.fury.io/rb/playbook_ui)
+
+# Playbook Design System
+
+Playbook is the first design system built for both Rails & React interfaces. Inspired by [Velocity](https://www.invisionapp.com/inside-design/design-resources/design-system-dashboard-ui-kit/), Playbook takes a modern design approach and applies it in a way that makes it easy to support bleeding edge or legacy systems. Playbook is built & maintained by the User Experience & Development teams at [Power Home Remodeling](https://www.techatpower.com/), the largest home remodeler in the US.
+
+## Development
+
+### Requirements
+
+- [asdf](https://github.com/asdf-vm/asdf)
+
+### Getting Started and Running Playbook for Development
+
+1. After cloning the repo, you should have the following nested folders among other files. It will be important to pay attention to which folder we are in as we get playbook running:
+    ```
+    playbook
+    │   playbook
+    │   playbook-website
+    ```
+1. Ensure your installed version of `bundler` is the same as the `BUNDLED WITH` section found in [Gemfile.lock](./Gemfile.lock). You can check the version you have by running `bundle -v`.
+
+1. From the root directory, run `./setup.sh`
+
+1. From the top-level playbook folder run `yarn start-dev` This may take a little while.
+1. Once you see the "compiled successfully" message in your terminal, navigate to [http://localhost:3000](http://localhost:3000) and you should see the playbook website.
+
+### Post Installation Startup
+
+Use `./run.sh` to run the application in one step. This will handle dependency updates then start the server. Helpful for fast start-up without bootstrapping especially when switching branches. 🚀
+
+### Running Library Tests
+
+1. `cd playbook && ./test.sh`
+
+---
+
+## Additional Resources
+
+### Adding NPM Dependencies
+
+1. You need to be working in `playbook/playbook` or `playbook/playbook-website` subdirectory
+1. run `yarn workspace playbook-website add <lib name>` to add to the website
+1. run `yarn workspace playbook-ui add <lib name>` to add to the kit source
+1. run `yarn workspace playbook-project add <lib name>` to add to the main project
+
+### Upgrading between versions
+
+See [docs/upgrade-guide](./upgrade-guide)
+
+### Releases
+
+* [Playbook Releases](https://github.com/powerhome/playbook/wiki/Playbook-Releases)
+
+### Development Environment
+
+* [Common Errors & Solutions](https://github.com/powerhome/playbook/wiki/Common-Errors-&-Solutions)
+
+### Building Playbook Kits
+
+* [Generating a Kit](https://github.com/powerhome/playbook/wiki/Generating-a-Kit)
+* [Rails Kit](https://github.com/powerhome/playbook/wiki/Rails-Kit)
+* [Rails Kit Helpers](https://github.com/powerhome/playbook/wiki/Rails-Kit-Helpers)
+* [Using a Kit within a Kit](https://github.com/powerhome/playbook/wiki/Using-a-Kit-within-a-Kit)
+* [Understanding Rails Kit HTML Wrapper](https://github.com/powerhome/playbook/wiki/Understanding-Rails-Kit-HTML-Wrapper)
+* [Kit Stylesheet](https://github.com/powerhome/playbook/wiki/Kit-Stylesheet)
+
+### Testing Playbook Kits Locally
+
+#### Testing React Kits locally
+
+1.  From inside the `playbook-ui` directory, run `yarn link`;
+1.  From Inside the project you want to test with `playbook-ui`, run `yarn link playbook-ui`;
+1.  Rebuild the project now using this version of `playbook-ui`;
+1.  Test all the things!
+1.  When finished, from inside the project you were testing with `playbook-ui`, run `yarn unlink playbook-ui`;
+1.  From Inside the `playbook-ui` directory, run `yarn unlink`;
+
+#### Jest & React-Testing-Library for Writing Tests
+
+We are currently backfilling test cases for React kit test coverage using Jest and React Testing Library. More additions and enhancements
+to the testing libraries are currently in the works. In the meantime, please take a look at these resources:
+
+- https://github.com/testing-library/jest-dom#usage for usage and examples
+- https://jestjs.io/docs/en/using-matchers
+
+When a new kit is generated, a placeholder React kit test will also be created. You can run all the tests with `yarn test`.
+
+### Important Note
+
+Keep in mind: Styles are brought in from playbook through the rails gem, so you will not be able to test scss updates with yarn linking.
+
+The gem & npm package is available as open source under the terms of the [ISC License](https://opensource.org/licenses/ISC).

playbook/app/entrypoints/playbook-doc.js

@@ -59,6 +59,7 @@ import * as Layout from 'kits/pb_layout/docs'
 import * as LegendDocs from 'kits/pb_legend/docs'
 import * as Lightbox from 'kits/pb_lightbox/docs'
 import * as LineGraphDocs from 'kits/pb_line_graph/docs'
+import * as Link from 'kits/pb_link/docs'
 import * as List from 'kits/pb_list/docs'
 import * as LoadingInline from 'kits/pb_loading_inline/docs'
 import * as Map from 'kits/pb_map/docs'
@@ -167,6 +168,7 @@ WebpackerReact.registerComponents({
   ...LegendDocs,
   ...Lightbox,
   ...LineGraphDocs,
+  ...Link,
   ...List,
   ...LoadingInline,
   ...Map,

playbook/app/entrypoints/playbook.scss

@@ -30,6 +30,7 @@
 @import 'kits/pb_dialog/dialog';
 @import 'kits/pb_distribution_bar/distribution_bar';
 @import 'kits/pb_draggable/draggable';
+@import 'kits/pb_drawer/drawer';
 @import 'kits/pb_dropdown/dropdown';
 @import 'kits/pb_file_upload/file_upload';
 @import 'kits/pb_filter/filter';
@@ -54,6 +55,7 @@
 @import 'kits/pb_legend/legend';
 @import 'kits/pb_lightbox/lightbox';
 @import 'kits/pb_line_graph/line_graph';
+@import 'kits/pb_link/link';
 @import 'kits/pb_list/list';
 @import 'kits/pb_loading_inline/loading_inline';
 @import 'kits/pb_map/map';
@@ -106,7 +108,6 @@
 @import 'kits/pb_user_badge/user_badge';
 @import 'kits/pb_walkthrough/walkthrough';
 @import 'kits/pb_weekday_stacked/weekday_stacked';
-@import 'kits/pb_drawer/drawer';
 @import 'utilities/mixins';
 @import 'utilities/spacing';
 @import 'utilities/cursor';

playbook/app/javascript/kits.js

@@ -59,6 +59,7 @@ export { default as Layout } from '../pb_kits/playbook/pb_layout/_layout'
 export { default as Legend } from '../pb_kits/playbook/pb_legend/_legend'
 export { default as Lightbox } from '../pb_kits/playbook/pb_lightbox/_lightbox'
 export { default as LineGraph } from '../pb_kits/playbook/pb_line_graph/_line_graph'
+export { default as Link} from '../pb_kits/playbook/pb_link/_link'
 export { default as List } from '../pb_kits/playbook/pb_list/_list'
 export { default as ListItem } from '../pb_kits/playbook/pb_list/_list_item'
 export { default as LoadingInline } from '../pb_kits/playbook/pb_loading_inline/_loading_inline'

playbook/app/pb_kits/playbook/pb_currency/_currency.tsx

@@ -26,6 +26,7 @@ type CurrencyProps = {
   variant?: 'default' | 'light' | 'bold',
   unit?: string,
   unstyled?: boolean,
+  commaSeparator?: boolean,
 }
 
 const sizes: {lg: 1, md: 3, sm: 4} = {
@@ -53,6 +54,7 @@ const Currency = (props: CurrencyProps): React.ReactElement => {
     variant = 'default',
     dark = false,
     unstyled = false,
+    commaSeparator = false,
   } = props
 
   const emphasizedClass = emphasized ? '' : '_deemphasized'
@@ -74,7 +76,7 @@ const Currency = (props: CurrencyProps): React.ReactElement => {
     className
   )
 
-  const getFormattedNumber = (input: number | any ) => new Intl.NumberFormat('en-US', {
+  const getFormattedNumber = (input: number | any) => new Intl.NumberFormat('en-US', {
     notation: 'compact',
     maximumFractionDigits: 1,
   }).format(input)
@@ -88,12 +90,20 @@ const Currency = (props: CurrencyProps): React.ReactElement => {
     return isAmount ? num.slice(0, -1) : isUnit ? num.slice(-1) : ''
   }
 
-  const getMatchingDecimalAmount = decimals === "matching" ? amount : whole,
-    getMatchingDecimalValue = decimals === "matching" ? '' : `.${decimal}`
+  const getMatchingDecimalAmount = decimals === "matching" ? amount : whole
+  const getMatchingDecimalValue = decimals === "matching" ? '' : `.${decimal}`
 
-  const getAmount = abbreviate ? getAbbreviatedValue('amount') : getMatchingDecimalAmount,
-    getAbbreviation = abbreviate ? getAbbreviatedValue('unit') : null,
-    getDecimalValue = abbreviate ? '' : getMatchingDecimalValue
+  const formatAmount = (amount: string) => {
+    if (!commaSeparator) return amount;
+
+    const [wholePart, decimalPart] = amount.split('.');
+    const formattedWhole = new Intl.NumberFormat('en-US').format(parseInt(wholePart));
+    return decimalPart ? `${formattedWhole}.${decimalPart}` : formattedWhole;
+  }
+
+  const getAmount = abbreviate ? getAbbreviatedValue('amount') : formatAmount(getMatchingDecimalAmount)
+  const getAbbreviation = abbreviate ? getAbbreviatedValue('unit') : null
+  const getDecimalValue = abbreviate ? '' : getMatchingDecimalValue
 
   return (
     <div

playbook/app/pb_kits/playbook/pb_currency/currency.rb

@@ -43,6 +43,9 @@ class Currency < Playbook::KitBase
       prop :unstyled, type: Playbook::Props::Boolean,
                       default: false
 
+      prop :comma_separator, type: Playbook::Props::Boolean,
+                             default: false
+
       def classname
         generate_classname("pb_currency_kit", align, size, dark_class)
       end
@@ -65,7 +68,7 @@ def caption_props
       def title_props
         {
           size: size_value,
-          text: abbreviate ? abbreviated_value : whole_value,
+          text: abbreviate ? abbreviated_value : formatted_amount,
           classname: "pb_currency_value",
           dark: dark,
         }
@@ -96,28 +99,38 @@ def variant_class
     private
 
       def whole_value
-        return amount if decimals == "matching"
-
-        amount.split(".").first.to_s
+        value = amount.split(".").first
+        if comma_separator
+          number_with_delimiter(value.gsub(",", ""))
+        else
+          value
+        end
       end
 
-      def abbreviated_value(index = 0..-2)
-        value = amount.split(".").first.split(",").join("")
-        abbreviated_num = number_to_human(value, units: { thousand: "K", million: "M", billion: "B", trillion: "T" }).gsub(/\s+/, "").to_s
-        abbreviated_num[index]
+      def decimal_value
+        amount.split(".")[1] || "00"
       end
 
       def units_element
         return "" if decimals == "matching" && !abbreviate && !unit
 
-        _, decimal_part = amount.split(".")
-        if unit.nil? && abbreviate == false
-          decimal_part.nil? ? ".00" : ".#{decimal_part}"
+        if unit.nil? && !abbreviate
+          if decimals == "matching"
+            ""
+          else
+            ".#{decimal_value}"
+          end
         else
           abbreviate ? "#{abbreviated_value(-1)}#{unit}" : unit
         end
       end
 
+      def abbreviated_value(index = 0..-2)
+        value = amount.split(".").first.gsub(",", "").to_i
+        abbreviated_num = number_to_human(value, units: { thousand: "K", million: "M", billion: "B", trillion: "T" }).gsub(/\s+/, "")
+        abbreviated_num[index]
+      end
+
       def size_value
         case size
         when "lg"
@@ -132,6 +145,20 @@ def size_value
       def dark_class
         dark ? "dark" : nil
       end
+
+      def formatted_amount
+        return abbreviated_value if abbreviate
+
+        if decimals == "matching"
+          if comma_separator
+            number_with_delimiter(amount.gsub(",", ""))
+          else
+            amount
+          end
+        else
+          whole_value
+        end
+      end
     end
   end
 end

playbook/app/pb_kits/playbook/pb_currency/currency.test.js

@@ -61,3 +61,38 @@ test('decimals default prop returns decimals as body text', () => {
   expect(currencyKit.querySelector('.pb_currency_value')).toHaveTextContent('320')
   expect(currencyKit.querySelector('.unit')).toHaveTextContent('.20')
 })
+
+
+test('commaSeparator prop returns comma separated amount', () => {
+  render(
+    <Currency 
+        amount="1234567890"
+        commaSeparator
+        data={{ testid: 'comma-test' }}
+    />
+  )
+  expect(screen.getByTestId('comma-test')).toHaveTextContent('1,234,567,890')
+})
+
+test('commaSeparator prop returns comma separated amount with decimals', () => {
+  render(
+    <Currency 
+        amount="1234567890.12"
+        commaSeparator
+        data={{ testid: 'comma-test-decimals' }}
+    />
+  )
+  expect(screen.getByTestId('comma-test-decimals')).toHaveTextContent('1,234,567,890.12')
+})
+
+test('commaSeparator prop returns comma separated amount with decimals="matching"', () => {
+  render(
+    <Currency 
+        amount="1234567890.12"
+        commaSeparator
+        data={{ testid: 'comma-test-decimals-matching' }}
+        decimals="matching"
+    />
+  )
+  expect(screen.getByTestId('comma-test-decimals-matching')).toHaveTextContent('1,234,567,890.12')
+})

playbook/app/pb_kits/playbook/pb_currency/docs/_currency_comma_separator.html.erb

@@ -0,0 +1,7 @@
+<%= pb_rails("currency", props: {
+  amount: '1234567.89',
+  comma_separator: true,
+  size: 'lg',
+  emphasized: false,
+  decimals: 'matching',
+}) %>

playbook/app/pb_kits/playbook/pb_currency/docs/_currency_comma_separator.jsx

@@ -0,0 +1,18 @@
+import React from "react"
+
+import Currency from "../_currency"
+
+const CurrencyCommaSeparator = (props) => {
+  return (
+    <Currency
+        amount='1234567.89'
+        commaSeparator
+        decimals="matching"
+        emphasized={false}
+        size="lg"
+        {...props}
+    />
+  )
+}
+
+export default CurrencyCommaSeparator

playbook/app/pb_kits/playbook/pb_currency/docs/_currency_comma_separator.md

@@ -0,0 +1,3 @@
+The optional `commaSeparator` can be used to auto-format the use of commas as a thousands separator. 
+
+**NOTE:** If the value passed into the `amount` prop is already comma-dilineated, it will not add additional commas.

playbook/app/pb_kits/playbook/pb_currency/docs/example.yml

@@ -8,7 +8,8 @@ examples:
   - currency_abbreviated: Abbreviate Larger Amounts
   - currency_matching_decimals: Matching Decimals
   - currency_unstyled: Unstyled
-
+  - currency_comma_separator: Comma Separator
+
   react:
   - currency_variants: Variants
   - currency_size: Size
@@ -17,6 +18,7 @@ examples:
   - currency_abbreviated: Abbreviate Larger Amounts
   - currency_matching_decimals: Matching Decimals
   - currency_unstyled: Unstyled
+  - currency_comma_separator: Comma Separator
 
   swift:
   - currency_size_swift: Size

playbook/app/pb_kits/playbook/pb_currency/docs/index.js

@@ -5,3 +5,4 @@ export { default as CurrencyNoSymbol } from './_currency_no_symbol.jsx'
 export { default as CurrencyAbbreviated } from './_currency_abbreviated.jsx'
 export { default as CurrencyMatchingDecimals } from './_currency_matching_decimals.jsx'
 export { default as CurrencyUnstyled } from './_currency_unstyled.jsx'
+export { default as CurrencyCommaSeparator } from './_currency_comma_separator.jsx'