noeldelgado / parse-css-color Goto Github PK

View Code? Open in Web Editor NEW

14.0 2.0 6.0 506 KB

:herb: Parse a CSS color string

License: MIT License

JavaScript 100.00%

parse css color string rgb rgba hsl hsla hex alpha

parse-css-color's Introduction

parse-css-color

Parse a CSS color string.

Supports

<color value>
- Hexadecimal RGB value: #RGB #RRGGBB
- #RGBA #RRGGBBAA (4 and 8-digit hexadecimal RGBA notation)
- RGB/A color module level 3 and 4 (number, percentage)
- HSL/A color module level 3 and 4 (number, deg, rad, turn)
<color keyword>
- One of the pre-defined color keywords.
transparent
- Shorthand for transparent black, rgba(0,0,0,0).

Does not support

currentColor
inherit

Installation

NPM

npm i parse-css-color

Or as a <script> tag from a CDN as parseCssColor:

Unpkg CDN

<script src="https://unpkg.com/parse-css-color"></script>

jsDelivr CDN

<script src="https://cdn.jsdelivr.net/npm/parse-css-color"></script>

Usage

import parse from 'parse-css-color'

// HEX/A
parse('#00f')
//> { type: 'rgb', values: [0, 0, 255], alpha: 1 }
parse('#00f8')
//> { type: 'rgb', values: [0, 0, 255], alpha: 0.5333333333333333 }
parse('#0000FF80')
//> { type: 'rgb', values: [0, 0, 255], alpha: 0.5019607843137255 }
parse('#00g')
//> null

// HSL/A
parse('hsl(270deg 60% 70% / 25%)')
//> { type: 'hsl', values: [270, 60, 70], alpha: 0.25 }
parse('hsl(4.71239rad 260% -70% / 0.5)') // clipped to
//> { type: 'hsl', values: [270, 100, 0], alpha: 0.5 }
parse('hsla(.75turn, 60%, 70%, 50%)')
//> { type: 'hsl', values: [270, 60, 70], alpha: 0.5 }
parse('hsla(100deg 0 0 / 0)') // error: missing percetanges
//> null

// RGB/A
parse('rgb(255 0 0 / 0.5)')
//> { type: 'rgb', values: [255, 0, 0], alpha: 0.5 }
parse('rgb(500 -100 0 / 200%)') // clipped to
//> { type: 'rgb', values: [255, 0, 0], alpha: 1 }
parse('rgba(255, 0, 255, 20%)')
//> { type: 'rgb', values: [255, 0, 255], alpha: 0.2 }
parse('rgba(100% 255 100% / 0)') // error: mixed percetange with integer
//> null

See tests for more cases.

Dev

npm install   # install dependencies
npm test      # run the tests (append `-- -w`) to watch
npm run dev   # watch for changes and rebuild

mix-css-color - Mix two CSS colors together in variable proportion. Opacity is included in the calculations.
values.js - Get the tints and shades of a CSS color.

License

MIT © Noel Delgado

parse-css-color's People

Contributors

Stargazers

Watchers

Forkers

bierdav simplylinn pythondev5 lgtm-migrator alexkuz

parse-css-color's Issues

HSL colors don't get parsed correctly, when the degree is a unitless value

When passing in a hsl color definition of the form:

hsl(1100, 100%, 50%)

the output is:

[1100, 100, 50]

even though the css standard permits the use of a unitless value (in which case it is interpreted as degrees)

TypeScript Typedefs

Would be kind to have TypeScript Typedefinitions ;)

Alpha should not be set if it is not defined

Hello. 👋 For a project, I'm reviewing over a dozen color parsing libraries, all of which have various problems. Yours is one of the closest to correctness, only having this one issue. Nice!

The alpha is incorrectly being set to a default value when it is actually undefined. For example:

parse('#00f')
//> { type: 'rgb', values: [0, 0, 255], alpha: 1 }

While this alpha can be inferred as 1, for tokenization and parsing, alpha is not set, and should not be included in the parsed results. By forcing a default alpha, it removes the ability to know what the actual input was and precisely convert it.

For example, should converting #00f to rgb color mode be rgb(0 0 255) or rgb(0 0 255 / 1)? It's indeterminate from the result of parse. While it is true that they are equivalent in an rgb color model, at a parsing level they are not equivalent. To be a perfect 1:1 conversion in a parsing scenario, the output result must be rgb(0 0 255), but there's no way to infer that from the parsing result.

Expectation:

parse('#00f')
//> { type: 'rgb', values: [0, 0, 255], alpha: undefined }

parse('#00ff')
//> { type: 'rgb', values: [0, 0, 255], alpha: 1 }

Typescript compiler issue

node_modules/parse-css-color/dist/index.d.ts:2:3 - error TS2309: An export assignment cannot be used in a module with other exported elements.

2   export = parseCSSColor
    ~~~~~~~~~~~~~~~~~~~~~~


Found 1 error in node_modules/parse-css-color/dist/index.d.ts:2

Happens at compiling, likely an issue in the index.d.ts file.