@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