Add format number component

2020-11-09 09:38:30 -05:00 · 2020-11-09 09:38:30 -05:00 · 4e2cf2e9de
commit 4e2cf2e9de
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@ -50,6 +50,7 @@
 - Utility Components
  - [Animation](/components/animation.md)
  - [Format Bytes](/components/format-bytes.md)
+  - [Format Number](/components/format-number.md)
  - [Include](/components/include.md)
  - [Resize Observer](/components/resize-observer.md)
  - [Theme](/components/theme.md)
--- a/docs/components/format-number.md
+++ b/docs/components/format-number.md
@ -0,0 +1,61 @@
+# Format Number
+
+[component-header:sl-format-number]
+
+Formats a number using the specified locale and options.
+
+Localization is handled by the browser's built-in [Intl: NumberFormat API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). As such, there's no need to load language packs or omit those you don't plan on using.
+
+```html preview
+<div class="format-number-overview">
+  <sl-format-number value="1000"></sl-format-number> 
+  <br><br>
+  <sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>  
+</div>
+
+<script>
+  const container = document.querySelector('.format-number-overview');
+  const formatter = container.querySelector('sl-format-number');
+  const input = container.querySelector('sl-input');
+
+  input.addEventListener('sl-input', () => formatter.value = input.value || 0);
+</script>
+```
+
+## Examples
+
+### Percentages
+
+To get the value as a percent, set the `type` attribute to `percent`.
+
+```html preview
+<sl-format-number type="percent" value="0"></sl-format-number><br>
+<sl-format-number type="percent" value=".25"></sl-format-number><br>
+<sl-format-number type="percent" value=".50"></sl-format-number><br>
+<sl-format-number type="percent" value=".75"></sl-format-number><br>
+<sl-format-number type="percent" value="1"></sl-format-number>
+```
+
+### Localization
+
+Use the `locale` attribute to set the number formatting locale.
+
+```html preview
+English: <sl-format-number value="2000" locale="en" minimum-fraction-digits="2"></sl-format-number><br>
+German: <sl-format-number value="2000" locale="de" minimum-fraction-digits="2"></sl-format-number><br>
+Russian: <sl-format-number value="2000" locale="ru" minimum-fraction-digits="2"></sl-format-number><br>
+```
+
+### Currency
+
+To format a number as a monetary value, set the `type` attribute to `currency` and set the `currency` attribute to the desired ISO 4217 currency code. You should also specify `locale` to ensure the the number is formatted correctly for the target locale.
+
+```html preview
+<sl-format-number type="currency" currency="USD" value="2000" locale="en-US"></sl-format-number><br>
+<sl-format-number type="currency" currency="GBP" value="2000" locale="en-GB"></sl-format-number><br>
+<sl-format-number type="currency" currency="EUR" value="2000" locale="de"></sl-format-number><br>
+<sl-format-number type="currency" currency="RUB" value="2000" locale="ru"></sl-format-number><br>
+<sl-format-number type="currency" currency="CNY" value="2000" locale="zh-cn"></sl-format-number>
+```
+
+[component-metadata:sl-format-number]
--- a/docs/getting-started/changelog.md
+++ b/docs/getting-started/changelog.md
@ -8,9 +8,10 @@ _During the beta period, these restrictions may be relaxed in the event of a mis

 ## Next

+- Added `sl-format-number` component
+- Added `closable` prop to `sl-tab`
 - Added experimental `sl-resize-observer` utility
 - Added experimental `sl-theme` utility and updated theming documentation
- Added `closable` prop to `sl-tab`
 - Fixed a bug where `sl-menu-item` wouldn't render properly in the dark theme
 - Fixed a bug where `sl-select` would show an autocomplete menu
 - Improved placeholder contrast in dark theme
--- a/src/components.d.ts
+++ b/src/components.d.ts
@ -468,6 +468,52 @@ export namespace Components {
         */
        "value": number;
    }
+    interface SlFormatNumber {
+        /**
+          * The currency to use when formatting. Must be an ISO 4217 currency code such as `USD` or `EUR`.
+         */
+        "currency": string;
+        /**
+          * How to display the currency.
+         */
+        "currencyDisplay": 'symbol' | 'narrowSymbol' | 'code' | 'name';
+        /**
+          * The locale to use when formatting the number.
+         */
+        "locale": string;
+        /**
+          * The maximum number of fraction digits to use. Possible values are 0 - 20.
+         */
+        "maximumFractionDigits": number;
+        /**
+          * The maximum number of significant digits to use,. Possible values are 1 - 21.
+         */
+        "maximumSignificantDigits": number;
+        /**
+          * The minimum number of fraction digits to use. Possible values are 0 - 20.
+         */
+        "minimumFractionDigits": number;
+        /**
+          * The minimum number of integer digits to use. Possible values are 1 - 21.
+         */
+        "minimumIntegerDigits": number;
+        /**
+          * The minimum number of significant digits to use. Possible values are 1 - 21.
+         */
+        "minimumSignificantDigits": number;
+        /**
+          * Turns off grouping separators.
+         */
+        "noGrouping": boolean;
+        /**
+          * The formatting style to use.
+         */
+        "type": 'currency' | 'decimal' | 'percent';
+        /**
+          * The number to format in bytes.
+         */
+        "value": number;
+    }
    interface SlIcon {
        /**
          * An alternative description to use for accessibility. If omitted, the name or src will be used to generate it.
@ -1292,6 +1338,12 @@ declare global {
        prototype: HTMLSlFormatBytesElement;
        new (): HTMLSlFormatBytesElement;
    };
+    interface HTMLSlFormatNumberElement extends Components.SlFormatNumber, HTMLStencilElement {
+    }
+    var HTMLSlFormatNumberElement: {
+        prototype: HTMLSlFormatNumberElement;
+        new (): HTMLSlFormatNumberElement;
+    };
    interface HTMLSlIconElement extends Components.SlIcon, HTMLStencilElement {
    }
    var HTMLSlIconElement: {
@ -1476,6 +1528,7 @@ declare global {
        "sl-dropdown": HTMLSlDropdownElement;
        "sl-form": HTMLSlFormElement;
        "sl-format-bytes": HTMLSlFormatBytesElement;
+        "sl-format-number": HTMLSlFormatNumberElement;
        "sl-icon": HTMLSlIconElement;
        "sl-icon-button": HTMLSlIconButtonElement;
        "sl-icon-library": HTMLSlIconLibraryElement;
@ -2000,6 +2053,52 @@ declare namespace LocalJSX {
         */
        "value"?: number;
    }
+    interface SlFormatNumber {
+        /**
+          * The currency to use when formatting. Must be an ISO 4217 currency code such as `USD` or `EUR`.
+         */
+        "currency"?: string;
+        /**
+          * How to display the currency.
+         */
+        "currencyDisplay"?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+        /**
+          * The locale to use when formatting the number.
+         */
+        "locale"?: string;
+        /**
+          * The maximum number of fraction digits to use. Possible values are 0 - 20.
+         */
+        "maximumFractionDigits"?: number;
+        /**
+          * The maximum number of significant digits to use,. Possible values are 1 - 21.
+         */
+        "maximumSignificantDigits"?: number;
+        /**
+          * The minimum number of fraction digits to use. Possible values are 0 - 20.
+         */
+        "minimumFractionDigits"?: number;
+        /**
+          * The minimum number of integer digits to use. Possible values are 1 - 21.
+         */
+        "minimumIntegerDigits"?: number;
+        /**
+          * The minimum number of significant digits to use. Possible values are 1 - 21.
+         */
+        "minimumSignificantDigits"?: number;
+        /**
+          * Turns off grouping separators.
+         */
+        "noGrouping"?: boolean;
+        /**
+          * The formatting style to use.
+         */
+        "type"?: 'currency' | 'decimal' | 'percent';
+        /**
+          * The number to format in bytes.
+         */
+        "value"?: number;
+    }
    interface SlIcon {
        /**
          * An alternative description to use for accessibility. If omitted, the name or src will be used to generate it.
@ -2747,6 +2846,7 @@ declare namespace LocalJSX {
        "sl-dropdown": SlDropdown;
        "sl-form": SlForm;
        "sl-format-bytes": SlFormatBytes;
+        "sl-format-number": SlFormatNumber;
        "sl-icon": SlIcon;
        "sl-icon-button": SlIconButton;
        "sl-icon-library": SlIconLibrary;
@ -2796,6 +2896,7 @@ declare module "@stencil/core" {
            "sl-dropdown": LocalJSX.SlDropdown & JSXBase.HTMLAttributes<HTMLSlDropdownElement>;
            "sl-form": LocalJSX.SlForm & JSXBase.HTMLAttributes<HTMLSlFormElement>;
            "sl-format-bytes": LocalJSX.SlFormatBytes & JSXBase.HTMLAttributes<HTMLSlFormatBytesElement>;
+            "sl-format-number": LocalJSX.SlFormatNumber & JSXBase.HTMLAttributes<HTMLSlFormatNumberElement>;
            "sl-icon": LocalJSX.SlIcon & JSXBase.HTMLAttributes<HTMLSlIconElement>;
            "sl-icon-button": LocalJSX.SlIconButton & JSXBase.HTMLAttributes<HTMLSlIconButtonElement>;
            "sl-icon-library": LocalJSX.SlIconLibrary & JSXBase.HTMLAttributes<HTMLSlIconLibraryElement>;
--- a/src/components/format-number/format-number.tsx
+++ b/src/components/format-number/format-number.tsx
@ -0,0 +1,65 @@
+import { Component, Prop } from '@stencil/core';
+
+/**
+ * @since 2.0
+ * @status stable
+ */
+
+@Component({
+  tag: 'sl-format-number',
+  shadow: true
+})
+export class FormatBytes {
+  /** The number to format in bytes. */
+  @Prop() value = 0;
+
+  /** The locale to use when formatting the number. */
+  @Prop() locale: string;
+
+  /** The formatting style to use. */
+  @Prop() type: 'currency' | 'decimal' | 'percent' = 'decimal';
+
+  /** Turns off grouping separators. */
+  @Prop() noGrouping = false;
+
+  /** The currency to use when formatting. Must be an ISO 4217 currency code such as `USD` or `EUR`. */
+  @Prop() currency = 'USD';
+
+  /** How to display the currency. */
+  @Prop() currencyDisplay: 'symbol' | 'narrowSymbol' | 'code' | 'name' = 'symbol';
+
+  /** The minimum number of integer digits to use. Possible values are 1 - 21. */
+  @Prop() minimumIntegerDigits: number;
+
+  /** The minimum number of fraction digits to use. Possible values are 0 - 20. */
+  @Prop() minimumFractionDigits: number;
+
+  /** The maximum number of fraction digits to use. Possible values are 0 - 20. */
+  @Prop() maximumFractionDigits: number;
+
+  /** The minimum number of significant digits to use. Possible values are 1 - 21. */
+  @Prop() minimumSignificantDigits: number;
+
+  /** The maximum number of significant digits to use,. Possible values are 1 - 21. */
+  @Prop() maximumSignificantDigits: number;
+
+  render() {
+    const number = Number(this.value);
+
+    if (isNaN(number)) {
+      return '';
+    }
+
+    return new Intl.NumberFormat(this.locale, {
+      style: this.type,
+      currency: this.currency,
+      currencyDisplay: this.currencyDisplay,
+      useGrouping: !this.noGrouping,
+      minimumIntegerDigits: this.minimumIntegerDigits,
+      minimumFractionDigits: this.minimumFractionDigits,
+      maximumFractionDigits: this.maximumFractionDigits,
+      minimumSignificantDigits: this.minimumSignificantDigits,
+      maximumSignificantDigits: this.maximumSignificantDigits
+    }).format(number);
+  }
+}