Embeddable UI Kit

The Amberflo UI Kit is a React component library for our customers to be able to consume and make use of principal Amberflo views, for one of their customers, on their own site.

UI Kit uses Customer Portal API. Each component is responsible of making the API calls. To use them you just first need to import the components into your app.

If you are trying to use this widgets on a non React.js environment, you can use the vanilla.js library as well.

Installation

Run yarn add @amberflo/uikit or npm install @amberflo/uikit to install Amberflo UI Kit in your React project.

📘
Technologies
React >= v17.0.2
Node v16.13.1
Typescript v4.5.5

Available Versions

All versions can be found on npm repository: @amberflo/uikit

Getting Started

Amberflo Provider

The AmberfloProvider is a Provider component that needs to wrap your app, so the components can hit our API. It requires a customer-specific session and a theme. You can check here how to:

<AmberfloProvider
  session="<YOUR_SESSION_ID>"
  theme={{
    brandColor: "<YOUR_BRAND_COLOR>",
    fontSize: <DEFAULT_FONT_SIZE>,
    fontFamily: "<DEFAULT_FONT_FAMILY>"
  }}
>
  ...
</AmberfloProvider>

Imports

To import a single Amberflo UI Kit component into your application (Recommended):

import { CostExplorerBarGraph } from "@amberflo/uikit/components/organisms/CostExplorerBarGraph";
import { InvoicesList } from '@amberflo/uikit/components/organisms/InvoiceList'

This will allow to perform tree-shaking so unused components will be dropped from the final bundle that will weight less and load faster.

📘
To make this possible the bundler needs to allow tree shaking.

To import multiple components from the root:

import { CostExplorerBarGraph, InvoicesList } from "@amberflo/ui-kit/components";

📘
Notice tree shaking won’t be effective if you use this approach. Also some unexpected behavior may occur, for example, importing all this components will prepare for rendering, meaning for instance stripe component will call some endpoints, even if this is not rendered.

Theming

In order to customize components with a theme add a theme prop to the AmberfloProvider with the following object:

{
  brandColor: string // it can be hex, or color name
  fontSize: number // Basic font size, all rest of font sizes will scale dynamically to this value
  fontFamily: string // name of the font to use. The font must be available on your site. Or you can use a custom font as showed below.
  customFontUrl: string // google font url to import to your site
}

We have added some class names to most of our components, you will be able to identify them, once they are placed on your app, by the starting name of aflo-. You can use this classes along with the material UI classes in your own css file.

So for instance, if you want to set a dark mode, to make it look something like this:

You can add some styles like:

.aflo-button .aflo-text {
    color: black;
}

.aflo-text {
    color: white;
}

This way you can change the text color for the whole components to white. And in the buttons that have a light background, we can set a dark color as black.

Types

Amberflo UI Kit is heavily typed, which will allow, if you use typescript on your project, to easily see which kind of properties a component receives, or what would return a specific function or hook.

Available hooks are:

Invoice-related Options

There are a few UI Kit components that display invoice-related data (i.e. Invoice List, Invoice Details, Invoice PDF). There are invoice-related settings a user can update at Amberflo | Settings | Invoice which affect how invoices are displayed through UI Kit components (as well as the customer portal and in the main-app).

The current available option/settings are:

Displaying cached invoices
- Invoice data displayed will either be cached data or real-time data.
- Cached data is used to speed up how quickly invoice data can be retrieved.
Group product items on invoices
- We list all product items and allow user to create categories to group on the invoices.

How to

Read how to use the widgets, views and components in here.

Read how to use hooks in here

Appendix 1: Full Code Example

import { useEffect, useState } from "react";
import {
  AmberfloProvider,
  UsageByMeterLineGraph,
  UsageByMeterTable,
} from "@amberflo/uikit";

function App() {
  const [sessionToken, setSessionToken] = useState(null);

  const getSession = async () => {
    const response = await fetch("https://app.amberflo.io/session", {
      method: "POST",
      body: JSON.stringify({
        // replace customer123 with an actual customer id
        customerId: "customer123",
      }),
      headers: {
        // YOU SHOULD NOT HAVE YOUR API KEY IN YOUR CLIENT SIDE CODE.
        // THIS IS ONLY FOR DEMONSTRATION PURPOSES TO TRY OUT A QUICK WORKING EXAMPLE.
        // Replace your_api_key with your account's API key.
        // Please see this section for more info.
        // (https://docs.amberflo.io/docs/get-session-token)
        "x-api-key": "your_api_key",
      },
    });

    const data = await response.json();

    setSessionToken(data.sessionToken);
  };

  useEffect(() => {
    getSession();
  }, []);

  if (!sessionToken) {
    // You can handle this many different ways (e.g. loaders, etc.), but we will just
    // return null until you have a token for simplicity.
    return null;
  }

  return (
    // When using UI Kit components, they must be a child of the AmberfloProvider.
    // Find out more about the AmberfloProvider here: https://docs.amberflo.io/docs/amberflo-components#getting-started
    // You will give need to provide it the sessionToken we receive from the
    // https://app.amberflo.io/session API.
    <AmberfloProvider session={sessionToken}>
      {/*
          A Usage Graph and Usage Table will be displayed 
          populated with the usage of the customer you selected a session for above.
          Your account must have meters and the selected customer must have usage
          to be able to display any data within the table and graph.
      */}
      <div style={{ display: "flex", flexDirection: "column", gap: "2rem" }}>
        <UsageByMeterLineGraph withTitle withMeterSelector withContainer />
        <UsageByMeterTable withTitle withContainer />
      </div>
    </AmberfloProvider>
  );
}

export default App;