xml-wizard / huetiful

Function oriented library for color manipulation 🧪

huetiful-js is a small (~10kB) & fast library for color manipulation written in JavaScript.

It is function oriented and borrows a lot of its features from color theory but tries to hide away the science from the developer.

The library aims to parse colors from as many types as possible allowing freedom to define our color tokens as we see fit as well as parse colors from other source. For instance, methods such as the HTML Canvas API's getImageData() method. The collection methods try to be as generic as possible by treating ArrayLike and Map-like objects as valid color collections so long as the values are parseable color tokens.

It uses Culori under the hood which provides access to low level functions for color conversions and other necessary bells and whistles that this library depends on. It works both in Node and the browser.

Features

• Filtering collections of colors by using the values of their properties as ranges. For example distance against a comparison color and luminance.
• Sorting collections of colors by their properties. For example using saturation or hue in either descending or ascending order
• Creating custom palettes and color scales
• Manipulating individual color tokens for example setting and querying properties as well as querying their properties i.e chromaticity.
• Calculating values of central tendency and other statistical values from collections of colors
• Wrapping collections of colors/individual color tokens similar to Lodash's _.chain utility allowing method chaining before returning our final output.
• Color maps for Colorbrewer, TailwindCSS and CSS named colors
• Converting colors across different types including numbers, strings (all CSS parseable string represantations of color), plain objects, arrays and even boolean values

Installation

Using a package manager

Note that the library is ESM and UMD only.

Assuming you already have Node already installed, you can add the package using npm/yarn or any other Node based package manager:

npm i huetiful-js

Or:

yarn add huetiful-js

In the browser and via CDNs

You can use also a CDN in this example, jsdelivr to load the library remotely:

import {...} from 'https://cdn.jsdelivr.net/npm/huetiful-js/lib/huetiful.esm.js'

Or load the library as a UMD glabal (huetiful) in your HTML file using a <script> tag:

# With script tag

<script src='https://cdn.jsdelivr.net/npm/huetiful-js/dist/huetiful.umd.js'></script>

Quickstart

See the Quickstart here

Community

See the discussions and just say hi, or share a coding meme (whatever breaks the ice🏔️)

Contributing

This project is fully open source! Contributions of any kind are greatly appreciated! See🔍 the contributing page on the documentation site file for more information on how to get started.

References

This project is a result of open source resources from many places all over the Internet.

See some of the references here

 License ⚖️

 © 2024, Dean Tarisai & xml-wizard contributors
 Released under the  Apache 2.0 license.
 🧪 & 🔬 with 🥃 in Crowhill,ZW

huetiful's Issues

Examples and demonstrating the library functions through codepens

People understand better when they see practical examples showing how to use something.

Adding more comprehensive examples with visual feedback would improve the experience of developers going through our API

Remove dependency on lodash to reduce code bloat.

For the sake of rapid prototyping, I had relied on the lodash library to provide utilities I needed to get the job done. However, as of v1.7, effort is being made to use vanilla JS for all utilities and implement the special ones myself.

So in version 1.8, I'm including a new directory fp/ that will contain all these utilities. The funcs inside will be categorised by the data types they work on. This will, also find the helpers.ts module being refactored and broken down into smaller modules for better readability

Feature: Add a GitHub Actions workflow for documentation site deployment.

This issue came from this pull request which failed to pass build tests. It would be nice to have a workflow that logs the deployment results where everyone can see them (in the Actions tab)

Using the utility functions with generative art.

How can the values generated with these utility functions be plugged in to creative coding libraries such as P5.js. Is the code readily/easily integrated into the sketches?

CSS utilities to implement the values produced by the generator functions.

Maybe we could have hackable utility functions that map the generated values directly to respective CSS properties such as background , linear-gradient etc.

Create a nextjs based documentation site

I want to clone my blog into the docs directory. Since it already has syntax highlighting, I can refactor my docs into simple mdx files with Playground components/codepens that

Map all TailwindCSS colors too etc and the values from the functions

Improving the UX for docs

A lot of effort needs to be put into improving the overall UX of the documentation site.

Over the next month I'll be adding small but noticeable improvements to help make it easier to navigate the site. Contributions are greatly appreciated devs!!

tonalPalette function should be customizable.

The tonalPalette() utility should provide an override to adjust different variables when computing the tonal palettes. It could also output a theme Map that contains contains palette options as per Material Design Guidelines.

Enhancement: make the list view (each post) more engaging

Suggestion

For the list view, there's not much to change except to make a few design changes to the basic unit (each post in this case). The list would look more engaging if it had shadows and had each post in card format. Here's an example of what the card could look like. I have taken it from George Francis's personal blog

Migrating the docs to Docsify

For aesthetic and ease of use we're migrating the docs to Docsify because it relies on simple Markdown and allows the source files to be easily edited.

The Library crashes in the browser.

It seems like my build configuration is erroneous and is not bundling dependencies.

Working on it

Gradient generator core function not yet defined

This function should be able to take Map and iterate over the key value pairs returning gradients which can be used as a CSS reference to the background property. Customization of the manipulation could be done through eases, the use of different color spaces and different interpolation methods.

Setting up unit tests for the library.

Currently I'm debugging using console.log 😂 and that's a bit tedious given the amount of code I need to test. Any suggestions on how to setup a testing/assertion library would be nice.

Create a README

Add a README file to highlight the capabilities/functionalities of the library.

Make the keys in palette mappers case insensitive

The utilities depend on the autocomplete feature of code editors to pass in the correct keys for the target hues. This could cause unnecessary nonsensical errors

Working on it...

Feature: Automation of issue management and pull requests using Actions.

Is there a way we can automate some of these tasks as well ? Such as GitHub Actions?

Yeah we can automate assigning issues with github actions, like we do on open-sauced. i.e -> open-sauced/app#1988

Here is the workflow file -> https://github.com/open-sauced/hot/blob/beta/.github/workflows/triage.yml

Originally posted by @takanome-dev in #62 (reply in thread)

API and documentation needs drafting.

At the moment the project has no plausible API. Some attention to the documentation could be useful in reference during development. They could be two documentations. One which is more low level and used by contributors and another one which is more high level and is meant to be as concise as possible for anyone who wants to consume the code.

Add ESLint to the project

Adding ESLint will help maintain sanity in the codebase ensuring that the coding style is consistent. For example, since this is an open source project, there's a keen focus on readable code which means using if...else instead of ternary operators et cetera.

Migrating docs to next13

Currently the project documentation site is down but we're working on a fix

Top level palette functions must return a map with predefined keys (such as background, foreground, accent etc). Each of these keys will in turn have a tints, shades and hueshifted key which points to an array of color objects (preferably hex).

Can this function be hooked up with P5js to creatively compute color schemes for generative artwork?

hueShifted palette generator function.

This utility should be able to take a collection preferably a Map that has keys to the color roles ie primary, secondary and returns a collection of hue shifted palettes. Customizable by default.

Using treeshaken Culori to reduce bundle size.

At the moment, the library is a bit bloated with code which is not used but included in the bundle anyway.

According to the Culori docs, we can use the treeshaken version which allows us to import only what we need.

What does this mean ?

This is going to mean a library wide refactoring in all modules that are importing Culori.

1. First, color spaces won't be initialized by default. The library will be limited to CSS recognized color spaces for now.
2. Importing individual lodash utilities (if it means smaller bundle size)
3. Setting up ESLint to help detect unused code thus keeping our code clean.

pairedScheme sometimes returns colors less than the ones specified

At the moment the pairedScheme function returns an array that is first filtered out duplicate colors resulting from the way the colors are collected in separate arrays and then concatenated before being filtered.

Working on it

CLI for the library to allow more flexibility in use cases.

Create a command line tool that can generate pelette maps and save them as files. Similar to generating a tailwind.config.js file. The interface could support taking in a presaved palettes.json file with the relevant key value pair meta.

Understanding hue linearity in the LCH color space.

The phenomena of hue linearity in LCH can be defined as a mathematical formula. Using a derived approach can a function be made that produces color scales based on this assumption ?

Create interfaces to define structure for different palette/theme objects.

This can help in assigning relevant information for the library's functions without having to deal with parameters to directly. Is this what they call programming to an interface?Lol 😆

Docs: add a link to the source code for each utility

What would you like to share

Add a link to the source code for each utility. Since every H4 element in the doc source files is a heading for a utility we can attach these links by dynamically attaching the heading title to a path pattern to the repository

As you can see above, source and npm package are links that lead to external resources. In this case, we only need to link to the source. Also, notice how the details for each component are laid out in a well-spaced manner making readability a breeze. All the utilities are documented using a uniform schema containing the fields:

• Parameters
• Description
• Returns
• Example

Maybe a React component to template this layout would be efficient.

Add Husky for precommit hooks

Some tasks are starting to get tedious and would benefit from automation

To allow us to work better can we have an ESLint and Prettier precommit hook ?

Will add more specifications later.

Docs: add a table of contents in the reading view

Add a Table of Contents Table that lists all the headings in the document. Since the source files for the docs are plain text files .mdx we could use a remark-plugin or a RegExp that maps through all headings and adds them to the TOC

setTemp crashes when you pass in an argument

So apparently setTemp has a bug that's making it crash even when invoked with the correct parameters 😂. Obviously this is the worst bug ever and a sign of carelessness during testing.

The issue has been resolved in v1.6 and it will be released soon.

What similar tools have accomplished the same motive that we pursue and what sets this project apart.

Its undeniable that we stand on the shoulder of giants. Therefore its wise to consider the current solutions out there and make a case study of each noting its pros and cons as well as drawing inspiration from previous successful projects. This is not to be a competition but rather give developers a different experience when dealing with color in frontend development.

Color maps containing different color schemes for palette types and grafmdients.

These should be Map data structures that store precompiled key value pairs for different color schemes or themes. The Maps can be used with WCAG utilities from Culori to create themes that are compliant to Material Design Guidelines.

Create a dynamic landing page

So far the documentation site is a bit flat on the aesthetics side but I have few ideas in mind

• Full sized hero background with SVG and animation
• A detailed description of what the library can do
• A getting started section
• GitHub/NPM statistics
  Will update the issue it I think of anything else

Research about color theory and related information.

Wide knowledge of combining color creatively is indespensible in deriving palette generation algorithms. Would this be a job of ML ? Is there a work around to this reasoning?

Extract color from images and a return a map of the types of palettes

Color palettes can be extracted from images using the the getImage API. How can this be achieved.... Time for inspiration LOL

Docs: add wrapping on the code blocks on small screens

Current Behaviour

The code blocks scroll horizontally on small screens.

Suggestions

It would be nice to add some wrapping and use a lighter monospace font for the code blocks (I think the font for code is a bit too heavy)

Applying mathematics in manipulating the color computations.

What mathematical concepts can be applied to make the output of these functions more optimized or balanced. Actually mathematics should play a vital role throughout the development of the functionalities.

A webapp that demonstrates the library's capabilities.

In order to improve the code we inevitably have to consume our own APi so that it acts as proof of concept and help keeps the development morale upbeat. Functionality suggestions are greatly appreciated.

Animated gradients in CSS using interpolations and JavaScript Animation.

Create custom animated gradients that can have color values generated on-the-fly or different timing functions,eases as well different color spaces. Should probably take a Map that has all the customizable options.

Adding licenses to borrowed code

Properly add open source licenses for code that has been derived from another source.

Project guidelines and conventions to follow throughout the development lifecycle.

Obviously conventions have to be set in place so that the codebase is easy to understand since it will follow set standards which further eliminates confusion during development. This can also include refactoring code to suit the paradigm(s) being used . Code readability increases contribution confidence and is a priority.

Enhancement: make homepage UX better

People like what they see so a pretty landing page is a necessary aesthetic. I think they're plenty of landing page examples out there for libraries but here's what I had in mind:

• A flowfield coverpage that has shifting colors (kinda makes the project goal obvious that its about color). This could be preferably full viewport.
• A description of the library capabilities, a getting started section and at the footer we can put some statistics about the project e.g stargazers, forks and contributors.

I've attached an example landing page above. Feel free to make suggestions

Improving the UX for docs

Discussed in #62

^{Originally posted by prjctimg October 24, 2023}
A lot of effort needs to be put into improving the overall UX of the documentation site.

Over the next month we'll be adding small but noticeable improvements to help make it easier to navigate the site. Contributions are greatly appreciated devs!!

Improvements

Homepage

• #70

Reading View

• #71
• #72
• #73
• #74
• #75

List View

• #76

Start a knowledge base on color

Colour is a broad subject and I've noticed that for most people they can't use the library because of lack of background information on the terminologies used in colour science.

By v1.8 the docs will have a knowledge base section that has short and concise introductions to terminologies used when we are working with color.

Use of TypeScript for a streamlined development experience.

UpThis could help eliminate ambiguity and potential bugs by programming to agreed upon interfaces which will also make it easy to extend the functions. Please feel free to offer criticism if JavaScript would be your preference since I am not proficient in the superset myself. If possible recommendations for setting up the TypeScript development environment with minimal maintenance and a more focus on designing functionality, would be greatly appreciated.

Using machine learning in generating palettes.

Is it possible to implement ML to improve the overall functionality of the utilities so that they produce a near infinite range of palettes.

Docs: add edit in Github button on each page

What would you like to share

Add an edit in GitHub button on every page so that it's easy to fix typos and adjust the docs. A 'was this doc' useful statistic would also help us better our documentation, but of course, it's a 'nice to have' feature.

Demonstrations and examples for using the library.

Concise yet fully explanatory demos or examples of using the library's utilities are necessary to ensure a lower learning curve for our potential code users. This can involve following guidelines that cover all relevant meta about the code being demonstrated its use cases.

The functions must be chainable to compose more customizable behavior

Using utilities from Lodash we can make our code look more functional and easier to reason about. This means that computations must be performed in order of data relevancy till the desired output is attained.

Enhancement: Improve the README description.

The project's README is undeniably boring and too vague.

Let's make it comprehensive and give it lots of example use cases to give our users a starting point #77