@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:

yarn add @croud-ui/utilities

Config

Colors

Collection of color palette configs for use in croud control.

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.

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.

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.

// 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 library.

Usage

import the useLocalForage hook into your component

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

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

The hook returns two properties

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

  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

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:

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.

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

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.

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

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

<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 to automate versioning and CHANGELOG generation. For convenience, there is an opinionated NPM script for this.

yarn standard-version

You can also append this command with additional CLI args. See the docs for more details.

yarn standard-version --dry-run

License

Licensed under the MIT License