# @croud-ui/utilities

> This package contains base configs, libraries and compositions for our FE applications

Latest version **2.1.0** (published 2025-10-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @croud-ui/utilities
pnpm add @croud-ui/utilities
yarn add @croud-ui/utilities
bun add @croud-ui/utilities
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2025-10-23 |
| First published | 2021-04-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 91 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | mitchreece, brockreece |

## Links

- npm: https://www.npmjs.com/package/@croud-ui/utilities
- npm.io page: https://npm.io/package/@croud-ui/utilities

## Dependencies (1)

- [@croud-ui/tokens](https://npm.io/package/@croud-ui/tokens.md) ^2.1.0

## Recent versions

- 2.1.0 (latest) — 2025-10-23
- 0.7.12-alpha.1 (alpha) — 2023-12-19
- 2.0.1 — 2025-10-17
- 2.0.0 — 2025-10-17
- 1.16.2 — 2025-08-06
- 1.16.1 — 2025-07-25
- 1.16.0 — 2025-07-15
- 1.15.0 — 2025-04-16
- 1.14.0 — 2025-03-27
- 1.13.0 — 2025-03-20
- 1.12.0 — 2025-03-06
- 1.11.0 — 2024-10-29
- 1.10.0 — 2024-07-31
- 1.9.0 — 2024-06-19
- 1.8.1 — 2024-05-16
- … 49 more at https://npm.io/package/@croud-ui/utilities/versions

## README

# @croud-ui/utilities

This package contains base configs, libraries and compositions for our FE applications

## Install

To use any of these in your app install via the npm registery:

```bash
yarn add @croud-ui/utilities
```

## Config

### Colors

Collection of color palette configs for use in croud control.

```typescript
import {
  // Color palettes for avatar fallback:
  AVATAR_FALLBACK_COLORS,
} from "@croud-ui/utilities/config/colors";
```

### Navigation

Collection of configs to help build out navigation components in croud control.

```typescript
import {
  // Primary navigation menu config:
  navigationItems,

  // External application menu config:
  externalApps,
} from "@croud-ui/utilities/config/navigation";
```

### Roles

Collection of configs to help handle user roles in croud control.

```typescript
import {
  // Available user roles enum:
  Roles,

  // All possible roles assigned to croudies:
  ALL_CROUDIE_ROLES,

  // Croudie roles that enable raising of invoices:
  INVOICEABLE_STATUSES,
} from "@croud-ui/utilities/config/roles";
```

### tsconfig

We should extend the `tsconfig.json` from this package in our other packages.

```json
// tsconfig.json
{
  "extends": "@croud-ui/utilities/tsconfig.json"
}
```

## Hooks

### localForage

This composition hook can be used for persisting data in the browser using the [localforage](https://localforage.github.io/localForage/) library.

**Usage**

import the `useLocalForage` hook into your component

```typescript
import { useLocalForage } from '@croud-ui/utilities/hooks'

export default defineComponent({
...
```

The `useLocalForage` method accepts a single argument, this is the key that `localforage` will use for getting and setting values

It also accepts an optional generic argument for type defintions, this defaults to a `string` if not set

```typescript
useLocalForage<number>("some-key");
```

The hook returns two properties

`getItem` is a Promise that either returns `null` or the persisted value if it exists

```typescript
  setup() {
    const val = ref(0)
    const { getItem } = useLocalForage<number>('some-key')

    getItem.then((persistedValue) => {
      if (persistedValue) val.value = persistedValue
    })
  ...
```

The `setItem` method expects a single argument and persists this value in local storage

```typescript
const { setItem } = useLocalForage("some-key");
setItem("someValue");
```

### Navigation

This composition hook can be used to build out navigation menus in our SPAs.

**usage**

Import the `useNavigation` composition into your component:

```typescript
import { useNavigation } from '@croud-ui/utilities/hooks'

export default defineComponent({
...
```

The `useNavigation` method expects two arguments:

- `roles` - current user roles.
- `route` - current vue router route.

```typescript
const {
  ...
} = useNavigation(roles, route)
```

The logic returned from the `useNavigation` composition hook is shown in the table below:

| Return                              | Type                                                                   | Description                                                          |
| ----------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `availableNavigationItems`          | `Ref<NavigationMenuItem[]>`                                            | Navigation items available to the current user.                      |
| `activeMenu`                        | `Ref<NavigationMenuItem \| undefined>`                                 | Active top-level navigation menu item.                               |
| `activeRoute`                       | `Ref<NavigationMenuItem \| undefined>`                                 | Active navigation menu item.                                         |
| `navigationItems`                   | `NavigationMenuItem[]`                                                 | Primary navigation menu config.                                      |
| `canViewNavItem`                    | `(item: NavigationMenuItem[], roles: Roles[]): boolean`                | Determine if the current user can view a given navigation menu item. |
| `findFirstRouteItem`                | `(item: NavigationMenuItem[]): NavigationMenuItem \| null`             | Find the first route of a navigation menu item.                      |
| `flattenNavigationItem`             | `(item: NavigationMenuItem[]): NavigationMenuItem[]`                   | Flatten all the children of a navigation item.                       |
| `getActiveRoute`                    | `(item: NavigationMenuItem, route: Route): NavigationMenuItem \| null` | Finds menu item that matches the path of the active route.           |
| `getFirstLinkForNavigationMenuItem` | `(item: NavigationMenuItem): string`                                   | Get first link for given navigation menu item.                       |

### Variant

This composition hook can be used for A/B testing within our application.

**usage**

import the `useVariant` hook into your component

```typescript
import { useVariant } from '@croud-ui/utilities/hooks'

export default defineComponent({
...
```

The `useVariant` hook accepts a single config argument and returns which variant has been generated in this component.

```typescript
const { variant } = useVariant(config);
```

**config**

The config requires 2 properties

- **name** - name of the variance (for persistance and consistency purposes)
- **variances** - an object of possible variances to be returned and their weighting in the following format `{ variant: weighting }`. This must include a `control` variant.

The below config weighting makes the `control` variant twice as likely as the `other` variant

```typescript
const config = {
  name: "some-name",
  variances: {
    control: 2,
    other: 1,
  },
};
```

**Persistance**

This hook, uses the `localForage` composition to persist the `variant` previously generated by this hook.

**Full example**

```vue
<template>
  <div>
    <div v-if="variant === 'control'">2/3 of users will see this</div>
    <div v-if="variant === 'other'">1/3 of users will see this</div>
  </div>
</template>
<script lang="ts">
import { useVariant } from "@croud-ui/utilities/hooks";

const config = {
  name: "some-name",
  variances: {
    control: 2,
    other: 1,
  },
};

export default defineComponent({
  setup() {
    const { variant } = useVariant(config);
    return {
      variant,
    };
  },
});
</script>
```

## Standard Version

This package uses [Standard Version](https://github.com/conventional-changelog/standard-version) to automate versioning and CHANGELOG generation. For convenience, there is an opinionated NPM script for this.

```bash
yarn standard-version
```

You can also append this command with additional CLI args. See the [docs](https://github.com/conventional-changelog/standard-version#cli-usage) for more details.

```bash
yarn standard-version --dry-run
```

## License

Licensed under the [MIT License](../../../LICENSE)

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