# @microsoft/fast-web-utilities

> FAST web utilities

Latest version **6.0.0** (published 2022-06-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @microsoft/fast-web-utilities
pnpm add @microsoft/fast-web-utilities
yarn add @microsoft/fast-web-utilities
bun add @microsoft/fast-web-utilities
```

## Health

**Score 45/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2022-06-01 |
| First published | 2018-07-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 80.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9671 |
| Author | Microsoft |
| Maintainers | microsoft1es, fastsvc, nirice, janechu, chrisdholt, awentzel |

## Links

- npm: https://www.npmjs.com/package/@microsoft/fast-web-utilities
- Repository: https://github.com/Microsoft/fast
- Homepage: https://www.fast.design/
- Issues: https://github.com/Microsoft/fast/issues/new/choose
- npm.io page: https://npm.io/package/@microsoft/fast-web-utilities

## Dependencies (1)

- [exenv-es6](https://npm.io/package/exenv-es6.md) ^1.1.1

## Recent versions

- 6.0.0 (latest) — 2022-06-01
- 5.4.1 — 2022-05-04
- 5.4.0 — 2022-04-27
- 5.3.0 — 2022-04-17
- 5.2.0 — 2022-04-03
- 5.1.0 — 2022-01-25
- 5.0.2 — 2021-10-31
- 5.0.1 — 2021-10-13
- 5.0.0 — 2021-09-19
- 4.8.1 — 2021-09-12
- 4.8.0 — 2021-05-20
- 4.7.3 — 2021-02-08
- 4.7.2 — 2021-02-08
- 4.7.1 — 2021-01-30
- 4.7.0 — 2020-12-16
- … 40 more at https://npm.io/package/@microsoft/fast-web-utilities/versions

## README

# FAST Web utilities

This package is a collection of utilities intended to be used for web projects.

## Installation

`npm i --save @microsoft/fast-web-utilities`

## Usage

### DOM utilities

#### getKeyCode

The `getKeyCode` function gets the numeric key code associated with a keyboard event. This method is for use with DOM level 3 events that still use the deprecated keyCode property.

```js
import { getKeyCode } from "@microsoft/fast-web-utilities";

handleKeyPress = (e) => {
    let keyCode = getKeyCode(e);

    // Do something based on keyCode value
}
```

### HTML utilities

#### getClientRectWithMargin

The `getClientRectWithMargin` function gets the client bounding rectangle including any margins of an element.

```js
import { getClientRectWithMargin } from "@microsoft/fast-web-utilities";

const itemWidth = getClientRectWithMargin(item).width;
const itemHeight = getClientRectWithMargin(item).height;
```

#### convertStylePropertyPixelsToNumber

The `convertStylePropertyPixelsToNumber` function will convert a property value from an elements computed style from pixels to a number value.

```js
import { convertStylePropertyPixelsToNumber } from "@microsoft/fast-web-utilities";

const elementTopMargin = convertStylePropertyPixelsToNumber(style, "margin-top");
```

### Key utilities

#### Key strings

Commonly used `event.key` values are available as individual exports. Additional `key` values will be added as needed.  

```js
import { keyEnter, keySpace } from "@microsoft/fast-web-utilities";

handleKeyPress = (e) => {
    switch (e.key) {
        case keySpace:
        case keyEnter:
            // Do something if key matches
            break;
    }
}
```

#### KeyCodes (enum)

Keycodes are deprecated and their use should be avoided. Use the individual string `key` values instead.

### Localization utilities

#### Typescript enum

The `Direction` enum contains the `ltr` and `rtl` enum for use in a Typescript project.

```typescript
import { Direction } from "@microsoft/fast-web-utilities";

let direction: Direction = Direction.ltr;
```

### Number utilities

#### Limit

The `limit` function ensures that a value is between a min and max value. If the value is lower than min, min will be returned. If the value is greater than max, max will be retured.

```js
import { limit } from "@microsoft/fast-web-utilities";
const incomingNumber; // 11 
const setNumberByLimit = limit(0, 10, incomingNumber); // returns 10
```

#### wrapInBounds

The `wrapInBounds` function keeps a given value within the bounds of a min and max value. If the value is larger than the max, the minimum value will be returned. If the value is smaller than the minimum, the maximum will be returned. Otherwise, the value is returned un-changed.

```js
import { wrapInBounds } from "@microsoft/fast-web-utilities";
const slides; // 5
const index; // 5
const activeIndex = wrapInBounds(0, this.slides.length - 1, index) // returns 0
```

### String utilities

#### Format

The `format` function builds a string from a format specifier and replacement parameters.

```js
import { format } from "@microsoft/fast-web-utilities";

const formatterString = "View {0} {1}";

const newString = format(formatterString, "page", "4")); // "View page 4"
```

#### startsWith

The `startsWith` function checks to see if one string starts with another. The function is case sensitive.

```js
import { startsWith } from "@microsoft/fast-web-utilities";

const matchIsFalse = startsWith("HelloWorld", "World"); // false
const matchIsTrue = startsWith("HelloWorld", "Hello"); // true
```

#### isNullOrWhiteSpace

The `isNullOrWhiteSpace` function determines if the specified string is undefined, null, empty, or whitespace. The function returns true if the value is undefined, null, empty, or whitespace, otherwise false.

```js
import { isNullOrWhiteSpace } from "@microsoft/fast-web-utilities";

const myAnchor = document.querySelector("#id");
const checkWhitespace = isNullOrWhiteSpace(myAnchor.href);
```

#### pascalCase

The `pascalCase` function converts a string to Pascal Case

```js
import { pascalCase } from "@microsoft/fast-web-utilities";

const hyphenatedToPascal = pascalCase("my-string");
const uppercaseToPascal = pascalCase("MY STRING");
const whitespaceToPascal = pascalCase(" my string ");
```

#### classNames
A utility for merging class names into a single string conditionally. Accepts any number of strings, functions that return strings and two index arrays where the first index is a string or function that returns a string, and the second index is a boolean.

```js
import { classNames } from "@microsoft/fast-web-utilities";

// evaluates to "classOne classTwo classThree classFive"
const myJoinedClassNames = classNames(
    "classOne",
    () => "classTwo",
    ["classThree", true],
    ["classFour", false]
    [() => "classFive", true],
    [() => "classSix", false]
)
```

---
_Source: https://npm.io/package/@microsoft/fast-web-utilities · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._