@equinor/amplify-utils NPM

Amplify Utilities

This package contains utility functions and components that are used in front end projects across the Amplify Team applications.

Documentation

Utilities

Contains helper code for miscellaneous operations used across Amplify applications.

date

The date object contains functions for handling date display.

formatDate (date?: string | null | undefined)

formatDate takes in a js date string and returns it as a {dd.mm.yyyy} formatted string.

import { date } from "@equinor/amplify-utils";

const myDateObject = new Date(2017, 5, 14);
const str = date.formatDate(myDateObject.toString());

// str = "14.06.2017"

formatDateTime (date?: string | null)

formatDateTime takes in a js date string and returns it as a {dd. MMMM YYYY, mm:ss} formatted string.

import { date } from "@equinor/amplify-utils";

const myDateObject = new Date(2017, 5, 14);
const str = date.formatDateTime(myDateObject.toString());

// str = "14. June 2017, 00:00"

size

When formating bytes there is multiple ways of converting based on how you calculate byte size, we use decimal since this gives us a more realistic value for our use case with file blob storage.

formatBytes (bytes: number, decimals=2)

formatBytes takes in bytes type number and returns formatted byte size string.

import { size } from "@equinor/amplify-utils";

const str = size.formatBytes(123456);

// str = "123.46 KB"

string

When formating bytes there is multiple ways of converting based on how you calculate byte size, we use decimal since this gives us a more realistic value for our use case with file blob storage.

Empty

An empty string object for readability when defining and checking strings.

import { string } from "@equinor/amplify-utils";

if (aStringThatShouldBeEmpty === string.Empty) {
  doSomething();
}

capitalize (str: string)

capitalize every word in a string.

import { string } from "@equinor/amplify-utils";

let body = "i am a string in need of help";

body = string.capitalize(body);

// body = "I Am A String In Need Of Help"

Image

CreateImageFromInitials

Takes a string and returns an image that you can use as an avatar for users that does not have a profile picure.

import { image } from "@equinor/amplify-utils";

const image = image.CreateImageFromInitials("Ola Nordmann");

Return an image as a string, with the first and last initial if it has one. It will be the same color every time, the Name is used as a seed for a random color.

ApplicationIcon

React component that returns an svg icon representing an amplify application depending on props input.

interface IApplicationIconProps {
  name: "data acquisition" | "data experience" | "data tracker" | "data sharing" | "portal" | "default" | string;
  size?: 16 | 24 | 32 | 40 | 48;
}

<ApplicationIcon name="data tracker" size={32} />;

ApplicationIcon Example

FeedbackIcon

React component that returns an svg icon with smiling or frowning face depending on props input. Comes as filled or outlined variants.

interface IFeedBackIconProps {
  name: "positive" | "negative" | "default";
  variant?: "filled" | "outline";
  size?: 16 | 24 | 32 | 40 | 48;
}

<FeedbackIcon name="positive" variant="outline" size={32} />;

FeedbackIcon Example

Favicon

setupIcons (lightFaviconId: string, darkFaviconId: string)

setupIcons takes in the id string (without '#') of the dark/light theme favicons placed in the public.html folder and removes one of them, depending on if the user has dark or light theme enabled.

import { favicon } from "@equinor/amplify-utils";

favicon.setupIcons("light-icon", "dark-icon");

// Removed dark theme icon if the user has light theme enabled

Providers

SnackbarContextProvider

Provider for usage of snackbars. Required for useSnackbar Hook. Uses EDS SnackbarProps as default snackbar setup, but certain properties can be overridden.

Properties that can be overridden

placement: "left" | "right" | "top" | "bottom" | "top-left" | "bottom-left" | "top-right" | "bottom-right";
autoHideDuration: number;
onClose: () => void; // Called after the snackbar closes.

Example usage:

<SnackbarContextProvider
	placement="bottom-left"
	autoHideDuration={3000}>
// Other providers/App
</SnackbarContextProvider>

// Default settings
<SnackbarContextProvider
// Other providers/App
</SnackbarContextProvider>

Hooks

useSnackbar

A hook that allows usage of application snackbar. Requires SnackbarContextProvider.

Returns 2 functions: setSnackbarText and showSnackbar;

Example usage:

const { showSnackbar, setSnackbarText } = useSnackbar();

setSnackbarText("I am new snackbartext");
showSnackbar(); // Show the snackbar

// Show snackbar and override settings
showSnackbar({
  placement: "right",
  autoHideDuration: 5000,
  onClose: () => console.log("This happens after snackbar closes"),
});

useDebounce

A hook that allows for debouncing of any React State object. Takes in the state object and the delay of the debounce trigger in milliseconds.

For more detailed documentation see: https://usehooks.com/useDebounce/

Example usage:

const [textInput, setTextInput] = useState("");
const debouncedInput = useDebounce(textInput, 500);

useEffect(() => {
  // Do something when debounced input changes (aka user has stopped typing).
  console.log(debouncedInput);
}, [debouncedInput]);

<TextField onChange={(event) => setTextInput(event.target.value)} />;

useOnScreen

A hook for detecting when a ref element enters the users viewport. Uses the Intersection Observer API.

Threshold explanation:

A threshold of 1.0 means that when 100% of the target is visible within the
element specified by the `ref` option, the callback is invoked.

Example usage:

const paragraphRef = useRef<HTMLParagraphElement>(null);
const isVisible = useOnScreen(paragraphRef, 1);

useEffect(() => {
  console.log("Element is visible on screen!");
}, [isVisible]);

<p ref={paragraphRef}>This is some text</p>;