@muraldevkit/ds-utilities

Mural Design System Utilities package

This package contains utility files used across many of Mural's design system packages.

Table of contents

1. Usage
2. Exports
3. Available utilities
   1. isObject
   2. getKebabCase
   3. setAttributes
   4. logger
   5. handleError
   6. Configuration files
4. Tests

Usage

To install the package as a dev dependency within your component package please refer to our global FAQs for our guide on adding a new dependency.

Exports

ds-utilities is a hybrid package which outputs both CommonJs and ECMAScript modules, which are both supported by Node.js. If you need to import a file directly from the dist folder of the package, be sure to use the path of appropriate subfolder for your module, i.e. dist/cjs for CommonJs and dist/esm for ESM. If your package uses CommonJs and runs in a Node.js environment you can require('@muraldevkit/ds-utilities') or import { isObject } from '@muraldevkit/ds-utilities' (in a TypeScript project) without the need to specify the full path.

Available utilities

isObject

The isObject utility is a function that tests that a variable is actually an object and not an array or null (which can mistakenly be flagged as an object).

getKebabCase

The getKebabCase utility is a function that converts a string to kebab case. It lowercases any capital letters, removes special characters, and converts spaces to hyphens so that it can be used by computer-friendly use cases.

setAttributes

The setAttributes utility is a function that sets an object of attributes to be used in a given Stencil component. The custom attributes can be passed in via an object or string and can also take in an object of default attributes.

logger

The logger utility is a function that adds format and colors to the terminal log output. It exposes methods to support different log levels: logger.info(), logger.error(), logger.title() and logger.success()

handleError

The handleError utility is a function that helps with error handling by adding an organized and colorful output to an error and its stacktrace. It also allows finishing the node js process if the error is critical.

import { handleError } from '@muraldevkit/ds-utilities'

handleError({
	label: 'User input',
	error: new Error('custom error message'),
	// The process will finish after logging the error.
	exit: true
})

Configuration files

This package contains base configuration files used across multiple of Mural's design system package. They are located at ./lib/configs. It currently includes configurations for:

• Jest
• Cypress Webpack Config
• Stencil - Contains a static object and a more robust function for generating a configuration object which is used by the design system components.
• Storybook
• Style Dictionary
• TypeScript configurations for:
  • Web Components
  • React components
  • Utility packages

Tests

Each function has a suite of Jest unit tests to ensure that they function as expected. The tests can be run within the package directory using:

npm test

Test files are located in the tests directory and new files should follow the naming convention <scriptToTest>.test.ts.

Notes for contributors

The module entry and export paths for import (ESM) and require (CommonJs) usage are set in the package.json file, e.g.:

"main": "./dist/cjs/index.js",
"module": "dist/esm/index.js",
"exports": {
	".": {
		"import": "./dist/esm/index.js",
		"require": "./dist/cjs/index.js"
	},
	"./lib/configs/stencil": "./lib/configs/stencil.ts",
	"./lib/configs/jest": "./lib/configs/jest.js",
	...
	}

If you need to add a configuration file to the lib/configs folder, please be sure to update the exports property with the path to your file. Otherwise, you may encounter compilation errors such as:

ERR! Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/configs/storybook' is not defined by "exports" in
/home/runner/work/design-system/design-system/packages/library-react/node_modules/@muraldevkit/ds-utilities/package.json