@captn/utils

The @captn/utils package is a crucial component of the Captain suite of utilities, providing essential helper functions and constants designed to facilitate application development within the Captain ecosystem. This includes handling downloads, string manipulation, color processing, and interacting with HTML elements.

Features

Constants Module: Defines various constants used throughout the Captain applications, ensuring consistency across different modules.
String Utilities: Includes functions for parsing action strings, constructing URIs with custom protocols, and more.
Color Utilities: Provides functions for determining optimal contrast colors, calculating luminance, converting color formats, and mixing colors.
Action Utilities: Facilitates performing actions on HTML elements based on unique identifiers.
Type Definitions: Utilizes TypeScript for enhanced code quality and developer experience with clear interfaces and utility types.

Installation

Install @captn/utils using npm:

npm install @captn/utils

Usage

Constants

import { ERROR_KEY, ACTION_KEY } from '@captn/utils/constants';
 
console.log(ERROR_KEY);  // Outputs: 'ERROR'
console.log(ACTION_KEY); // Outputs: 'ACTION'

String Utilities

Get Action Arguments

import { getActionArguments } from '@captn/utils/string';
 
const action = getActionArguments("click:item-id");
console.log(action); // Outputs: { command: 'click', captainId: 'item-id', value: undefined, options: undefined }

Local File URI Construction

import { localFile } from '@captn/utils/string';
 
const fileURI = localFile('/path/to/file', { localProtocol: 'file' });
console.log(fileURI); // Outputs: 'file:///path/to/file'

Color Utilities

Get Contrast Color

import { getContrastColor } from '@captn/utils/color';
 
const contrastColor = getContrastColor("#ffffff");
console.log(contrastColor); // Outputs: 'black'

Hex to RGB Conversion

import { hexToRGB } from '@captn/utils/color';
 
const rgb = hexToRGB("#ff0000");
console.log(rgb); // Outputs: [255, 0, 0]

Mix Colors

import { mixColors } from '@captn/utils/color';
 
const mixedColor = mixColors("#ffffff", "#000000", 0.5);
console.log(mixedColor); // Outputs: '#808080' (a shade of gray)

Action Utilities

import { performElementAction } from '@captn/utils/actions';
 
// Assuming an element with `data-captainid="submit-button"` exists
performElementAction("submit-button", element => element.click());

Versioning

We use SemVer (opens in a new tab) for versioning. For the versions available, see the tags on this repository.

Template Modules