@rickosborne/css 2025.2.16

package/README.md

@@ -0,0 +1,736 @@
+# @rickosborne/css
+
+Basic CSS utilities built on:
+
+- [@rickosborne/typical](https://www.npmjs.com/package/@rickosborne/typical) for types
+- [@rickosborne/guard](https://www.npmjs.com/package/@rickosborne/guard) for guards
+- [@rickosborne/foundation](https://www.npmjs.com/package/@rickosborne/foundation) for basic utilities
+
+This is not, in any way, a general-purpose CSS handling library.
+It includes some very happy-path-oriented utilities, primarily intended for when you have control over the input.
+
+> ⚠️⚠️⚠️ ***This library does not attempt to cover the various edge cases of the real world or the CSS spec.*** ⚠️⚠️⚠️
+## Usage
+
+Install via your favorite package manager.
+
+Each package supports CommonJS `require`, ESM `import`, and TypeScript usage.
+
+You also have a choice: barrel imports or direct imports.
+
+Barrel imports mean you're going to require/import everything from the same package-level namespace:
+
+```typescript
+// CommonJS
+const { isPlainObject, isListOf } = require("@rickosborne/guard");
+// ESM / TypeScript
+import { isPlainObject, isListOf } from "@rickosborne/guard";
+```
+
+Implications:
+
+- Nice and simple.
+- Your build system needs to do tree-shaking well ... or you'll end up adding the entire package even if you only import two functions.
+
+The other option is to use direct imports:
+
+```typescript
+// CommonJS
+const { isPlainObject } = require("@rickosborne/guard/is-object");
+const { isListOf } = require("@rickosborne/guard/is-list-of");
+// ESM / TypeScript
+import { isPlainObject } from "@rickosborne/guard/is-object.js";
+import { isListOf } from "@rickosborne/guard/is-list-of.js";
+```
+
+Implications:
+
+- You (probably) don't have to worry about tree-shaking as your build (likely) ends up with only the functions you need.
+
+If you're using a modern build system, there aren't any strong reasons to prefer one way over the other.
+It's really just down to your personal preference.
+
+### A quick note about file extensions
+
+Do you need to use file extensions?
+And if so, which extensions?
+
+Honestly ... this is a dumpster fire question.
+It really comes down to your own setup and configuration.
+
+Within each package itself:
+
+- The CommonJS files all have `.cjs` extensions.
+- The ESM files all have `.mjs` extensions.
+- Node subpath exports have been set up to send `.js` imports to the `.cjs` (via `require`) or `.mjs` (via `import`) files, depending on your setup.
+
+So, in theory, the only extension which _won't_ work would be `.ts` because the source isn't included.
+
+If you run into a problem with a particular configuration, file a GitHub issue with:
+
+- Your `tsconfig.json`'s `module`, `moduleResolution`, and `target` settings.
+- Your `package.json`'s `type` and `imports` settings.
+- An example of another package which imports correctly for you.
+
+## License
+
+This package is licensed as [CC-BY-NC-SA-4.0] unless otherwise noted.
+That is, Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.
+
+[CC-BY-NC-SA-4.0]: https://creativecommons.org/licenses/by-nc-sa/4.0/
+
+
+***
+
+## API
+
+### Classes
+
+#### CSSError
+
+<a id="api-csserror"></a>
+
+```typescript
+ class CSSError extends Error 
+```
+
+### Functions
+
+#### angle01FromCSS
+
+<a id="api-angle01fromcss"></a>
+
+```typescript
+angle01FromCSS: (text: string | undefined, defaultUnit?: CSSAngleUnit) => number | undefined
+```
+
+#### colorTokensFromCSS
+
+<a id="api-colortokensfromcss"></a>
+
+```typescript
+colorTokensFromCSS: (text: string) => CSSColorTokens | undefined
+```
+
+#### convertBetweenUnits
+
+<a id="api-convertbetweenunits"></a>
+
+```typescript
+convertBetweenUnits: <Unit extends string, NumberFormat extends number>(original: number | undefined, fromUnit: Unit, toUnit: Unit, conversions: Readonly<Record<Unit, number>>, format?: (num: number) => NumberFormat) => NumberFormat | undefined
+```
+
+Given a number and a lookup table of units, convert the number from the source units to the destination units.
+
+
+#### cssFormatAlpha01
+
+<a id="api-cssformatalpha01"></a>
+
+```typescript
+cssFormatAlpha01: (alpha: number | undefined, resolution?: number | undefined) => string
+```
+
+Format a CSS alpha in the range [0,1] value to an optional resolution.
+
+
+#### cssFormatDimension
+
+<a id="api-cssformatdimension"></a>
+
+```typescript
+cssFormatDimension: (value: number, units?: string | undefined, resolution?: number | undefined) => string
+```
+
+Format a number and its optional units as a CSS dimension.
+
+
+
+#### cssFormatHex
+
+<a id="api-cssformathex"></a>
+
+```typescript
+cssFormatHex: (hex: string, format?: "short" | "long") => string
+```
+
+Format a CSS color hex, with optional short or long transformation.
+
+
+#### cssFormatPercent
+
+<a id="api-cssformatpercent"></a>
+
+```typescript
+cssFormatPercent: (value: number | undefined, resolution?: number | undefined) => string
+```
+
+Format a number as a CSS percentage.
+
+
+#### cssNameFromHex
+
+<a id="api-cssnamefromhex"></a>
+
+```typescript
+cssNameFromHex: (hex: string | undefined) => CSSColorName | undefined
+```
+
+Look up a CSS color name from its hex value.
+
+
+#### dimensionFromCSS
+
+<a id="api-dimensionfromcss"></a>
+
+```typescript
+dimensionFromCSS: (text: string | undefined) => OptionalDimensionPair
+```
+
+#### hexFromCSSName
+
+<a id="api-hexfromcssname"></a>
+
+```typescript
+hexFromCSSName: (name: string | undefined) => string | undefined
+```
+
+Get the hex value for a CSS color name, if possible.
+
+
+#### isAbsoluteLengthUnit
+
+<a id="api-isabsolutelengthunit"></a>
+
+```typescript
+isAbsoluteLengthUnit: (obj: unknown) => obj is CSSAbsoluteLengthUnit
+```
+
+Type guard for [CSSAbsoluteLengthUnit](#api-cssabsolutelengthunit).
+
+
+#### isAngleUnit
+
+<a id="api-isangleunit"></a>
+
+```typescript
+isAngleUnit: (obj: unknown) => obj is CSSAngleUnit
+```
+
+Type guard for [CSSAngleUnit](#api-cssangleunit).
+
+
+#### isColorName
+
+<a id="api-iscolorname"></a>
+
+```typescript
+isColorName: (obj: unknown) => obj is string
+```
+
+Loose type guard for CSS colors. See [isCSSColorName](#api-iscsscolorname) for the more strict version.
+
+
+#### isCSSColorName
+
+<a id="api-iscsscolorname"></a>
+
+```typescript
+isCSSColorName: (obj: unknown) => obj is CSSColorName
+```
+
+Strict type guard for [CSSColorName](#api-csscolorname). See [isColorName](#api-iscolorname) for the more loose version.
+
+
+#### isLengthUnit
+
+<a id="api-islengthunit"></a>
+
+```typescript
+isLengthUnit: (obj: unknown) => obj is CSSLengthUnit
+```
+
+Type guard for [CSSLengthUnit](#api-csslengthunit).
+
+
+#### isRelativeLengthUnit
+
+<a id="api-isrelativelengthunit"></a>
+
+```typescript
+isRelativeLengthUnit: (obj: unknown) => obj is CSSRelativeLengthUnit
+```
+
+Type guard for [CSSRelativeLengthUnit](#api-cssrelativelengthunit).
+
+
+#### isTransparentHex
+
+<a id="api-istransparenthex"></a>
+
+```typescript
+isTransparentHex: (hex: string) => boolean
+```
+
+Whether the given hex would produce a fully transparent (alpha 0) color.
+
+
+#### readFromCSS
+
+<a id="api-readfromcss"></a>
+
+```typescript
+readFromCSS: (text: string) => CSSTokenReader
+```
+
+Minimal CSS pull parser, which only supports the happy-path tokens expected in a CSS color expression. Does not support anywhere near the full CSS Colors spec, but it'll do in a pinch.
+
+
+
+#### toCSSColorName
+
+<a id="api-tocsscolorname"></a>
+
+```typescript
+toCSSColorName: (name: unknown) => CSSColorName | undefined
+```
+
+### Interfaces
+
+#### CSSColorToken
+
+<a id="api-csscolortoken"></a>
+
+```typescript
+export interface CSSColorToken<Type extends string = string> 
+```
+
+#### CSSErrorOptions
+
+<a id="api-csserroroptions"></a>
+
+```typescript
+export interface CSSErrorOptions extends ErrorOptions 
+```
+
+#### CSSFunctionToken
+
+<a id="api-cssfunctiontoken"></a>
+
+```typescript
+export interface CSSFunctionToken extends CSSColorToken<"function"> 
+```
+
+#### CSSHexHashToken
+
+<a id="api-csshexhashtoken"></a>
+
+```typescript
+export interface CSSHexHashToken extends CSSColorToken<"hex"> 
+```
+
+#### CSSKeywordToken
+
+<a id="api-csskeywordtoken"></a>
+
+```typescript
+export interface CSSKeywordToken extends CSSColorToken<"keyword"> 
+```
+
+#### CSSLiteralToken
+
+<a id="api-cssliteraltoken"></a>
+
+```typescript
+export interface CSSLiteralToken extends CSSColorToken<"literal"> 
+```
+
+#### CSSNumberToken
+
+<a id="api-cssnumbertoken"></a>
+
+```typescript
+export interface CSSNumberToken extends CSSColorToken<"number"> 
+```
+
+#### CSSTokenReader
+
+<a id="api-csstokenreader"></a>
+
+```typescript
+export interface CSSTokenReader 
+```
+
+#### CSSTokenReaderMatcher
+
+<a id="api-csstokenreadermatcher"></a>
+
+```typescript
+export interface CSSTokenReaderMatcher<Type extends CSSToken["type"] = CSSToken["type"]> 
+```
+
+#### FunctionColorToken
+
+<a id="api-functioncolortoken"></a>
+
+```typescript
+export interface FunctionColorToken 
+```
+
+#### HexColorToken
+
+<a id="api-hexcolortoken"></a>
+
+```typescript
+export interface HexColorToken 
+```
+
+#### NameColorToken
+
+<a id="api-namecolortoken"></a>
+
+```typescript
+export interface NameColorToken 
+```
+
+### TypeAliases
+
+#### CSSAbsoluteLengthUnit
+
+<a id="api-cssabsolutelengthunit"></a>
+
+```typescript
+type CSSAbsoluteLengthUnit = "cm" | "mm" | "Q" | "in" | "pt" | "pc" | "px";
+```
+
+#### CSSAngleUnit
+
+<a id="api-cssangleunit"></a>
+
+```typescript
+type CSSAngleUnit = "%" | "deg" | "grad" | "rad" | "turn";
+```
+
+Unit for a CSS angle.
+
+
+
+#### CSSColorFunction
+
+<a id="api-csscolorfunction"></a>
+
+```typescript
+type CSSColorFunction = "color" | "rgb" | "rgba" | "hsl" | "hsla" | "hwb";
+```
+
+#### CSSColorName
+
+<a id="api-csscolorname"></a>
+
+```typescript
+type CSSColorName = keyof typeof HEX_FROM_NAME;
+```
+
+CSS Level 4 color name.
+
+
+#### CSSColorTokens
+
+<a id="api-csscolortokens"></a>
+
+```typescript
+type CSSColorTokens = NameColorToken | HexColorToken | FunctionColorToken;
+```
+
+#### CSSLengthUnit
+
+<a id="api-csslengthunit"></a>
+
+```typescript
+type CSSLengthUnit = CSSRelativeLengthUnit | CSSAbsoluteLengthUnit;
+```
+
+#### CSSRelativeLengthUnit
+
+<a id="api-cssrelativelengthunit"></a>
+
+```typescript
+type CSSRelativeLengthUnit = "em" | "ex" | "cap" | "ch" | "ic" | "rem" | "lh" | "rlh" | "vw" | "vh" | "vi" | "vb" | "vmin" | "vmax" | "svw" | "lvw" | "dvw" | "svh" | "lvh" | "dvh" | "svi" | "lvi" | "dvi" | "svb" | "lvb" | "dvb" | "svmin" | "lvmin" | "dvmin" | "svmax" | "lvmax" | "dvmax";
+```
+
+#### CSSToken
+
+<a id="api-csstoken"></a>
+
+```typescript
+type CSSToken = CSSKeywordToken | CSSFunctionToken | CSSHexHashToken | CSSLiteralToken | CSSNumberToken;
+```
+
+#### DimensionPair
+
+<a id="api-dimensionpair"></a>
+
+```typescript
+type DimensionPair = [value: number, units: string | undefined];
+```
+
+A CSS dimension, a number and an optional unit, as a tuple.
+
+
+#### OptionalDimensionPair
+
+<a id="api-optionaldimensionpair"></a>
+
+```typescript
+type OptionalDimensionPair = [value: number | undefined, units: string | undefined];
+```
+
+Variation of a [DimensionPair](#api-dimensionpair) where the value may not be present.
+
+
+### Variables
+
+#### ABSOLUTE_LENGTH_UNITS
+
+<a id="api-absolute-length-units"></a>
+
+```typescript
+ABSOLUTE_LENGTH_UNITS: Readonly<CSSAbsoluteLengthUnit[]>
+```
+
+List of [CSSAbsoluteLengthUnit](#api-cssabsolutelengthunit).
+
+
+#### ANGLE_CONVERSIONS
+
+<a id="api-angle-conversions"></a>
+
+```typescript
+ANGLE_CONVERSIONS: Readonly<Record<CSSAngleUnit, number>>
+```
+
+#### ANGLE_UNITS
+
+<a id="api-angle-units"></a>
+
+```typescript
+ANGLE_UNITS: Readonly<CSSAngleUnit[]>
+```
+
+List of [CSSAngleUnit](#api-cssangleunit).
+
+
+#### COLOR_FUNCTIONS
+
+<a id="api-color-functions"></a>
+
+```typescript
+COLOR_FUNCTIONS: Readonly<CSSColorFunction[]>
+```
+
+#### HEX_FROM_NAME
+
+<a id="api-hex-from-name"></a>
+
+```typescript
+HEX_FROM_NAME: Readonly<{
+    readonly AliceBlue: "#F0F8FF";
+    readonly AntiqueWhite: "#FAEBD7";
+    readonly Aqua: "#00FFFF";
+    readonly Aquamarine: "#7FFFD4";
+    readonly Azure: "#F0FFFF";
+    readonly Beige: "#F5F5DC";
+    readonly Bisque: "#FFE4C4";
+    readonly Black: "#000000";
+    readonly BlanchedAlmond: "#FFEBCD";
+    readonly Blue: "#0000FF";
+    readonly BlueViolet: "#8A2BE2";
+    readonly Brown: "#A52A2A";
+    readonly Burlywood: "#DEB887";
+    readonly CadetBlue: "#5F9EA0";
+    readonly Chartreuse: "#7FFF00";
+    readonly Chocolate: "#D2691E";
+    readonly Coral: "#FF7F50";
+    readonly CornflowerBlue: "#6495ED";
+    readonly Cornsilk: "#FFF8DC";
+    readonly Crimson: "#DC143C";
+    readonly Cyan: "#00FFFF";
+    readonly DarkBlue: "#00008B";
+    readonly DarkCyan: "#008B8B";
+    readonly DarkGoldenrod: "#B8860B";
+    readonly DarkGray: "#A9A9A9";
+    readonly DarkGreen: "#006400";
+    readonly DarkGrey: "#A9A9A9";
+    readonly DarkKhaki: "#BDB76B";
+    readonly DarkMagenta: "#8B008B";
+    readonly DarkOliveGreen: "#556B2F";
+    readonly DarkOrange: "#FF8C00";
+    readonly DarkOrchid: "#9932CC";
+    readonly DarkRed: "#8B0000";
+    readonly DarkSalmon: "#E9967A";
+    readonly DarkSeaGreen: "#8FBC8F";
+    readonly DarkSlateBlue: "#483D8B";
+    readonly DarkSlateGray: "#2F4F4F";
+    readonly DarkSlateGrey: "#2F4F4F";
+    readonly DarkTurquoise: "#00CED1";
+    readonly DarkViolet: "#9400D3";
+    readonly DeepPink: "#FF1493";
+    readonly DeepSkyBlue: "#00BFFF";
+    readonly DimGray: "#696969";
+    readonly DimGrey: "#696969";
+    readonly DodgerBlue: "#1E90FF";
+    readonly FireBrick: "#B22222";
+    readonly FloralWhite: "#FFFAF0";
+    readonly ForestGreen: "#228B22";
+    readonly Fuchsia: "#FF00FF";
+    readonly Gainsboro: "#DCDCDC";
+    readonly GhostWhite: "#F8F8FF";
+    readonly Gold: "#FFD700";
+    readonly Goldenrod: "#DAA520";
+    readonly Gray: "#808080";
+    readonly Green: "#008000";
+    readonly GreenYellow: "#ADFF2F";
+    readonly Grey: "#808080";
+    readonly Honeydew: "#F0FFF0";
+    readonly HotPink: "#FF69B4";
+    readonly IndianRed: "#CD5C5C";
+    readonly Indigo: "#4B0082";
+    readonly Ivory: "#FFFFF0";
+    readonly Khaki: "#F0E68C";
+    readonly Lavender: "#E6E6FA";
+    readonly LavenderBlush: "#FFF0F5";
+    readonly LawnGreen: "#7CFC00";
+    readonly LemonChiffon: "#FFFACD";
+    readonly Lightblue: "#ADD8E6";
+    readonly LightCoral: "#F08080";
+    readonly LightCyan: "#E0FFFF";
+    readonly LightGoldenrodYellow: "#FAFAD2";
+    readonly LightGray: "#D3D3D3";
+    readonly LightGreen: "#90EE90";
+    readonly LightGrey: "#D3D3D3";
+    readonly LightPink: "#FFB6C1";
+    readonly LightSalmon: "#FFA07A";
+    readonly LightSeaGreen: "#20B2AA";
+    readonly LightSkyBlue: "#87CEFA";
+    readonly LightSlateGray: "#778899";
+    readonly LightSlateGrey: "#778899";
+    readonly LightSteelblue: "#B0C4DE";
+    readonly LightYellow: "#FFFFE0";
+    readonly Lime: "#00FF00";
+    readonly LimeGreen: "#32CD32";
+    readonly Linen: "#FAF0E6";
+    readonly Magenta: "#FF00FF";
+    readonly Maroon: "#800000";
+    readonly MediumAquamarine: "#66CDAA";
+    readonly MediumBlue: "#0000CD";
+    readonly MediumOrchid: "#BA55D3";
+    readonly MediumPurple: "#9370DB";
+    readonly MediumSeaGreen: "#3CB371";
+    readonly MediumSlateBlue: "#7B68EE";
+    readonly MediumSpringGreen: "#00FA9A";
+    readonly MediumTurquoise: "#48D1CC";
+    readonly MediumVioletRed: "#C71585";
+    readonly MidnightBlue: "#191970";
+    readonly MintCream: "#F5FFFA";
+    readonly MistyRose: "#FFE4E1";
+    readonly Moccasin: "#FFE4B5";
+    readonly NavajoWhite: "#FFDEAD";
+    readonly Navy: "#000080";
+    readonly NavyBlue: "#9FAFDF";
+    readonly OldLace: "#FDF5E6";
+    readonly Olive: "#808000";
+    readonly OliveDrab: "#6B8E23";
+    readonly Orange: "#FFA500";
+    readonly OrangeRed: "#FF4500";
+    readonly Orchid: "#DA70D6";
+    readonly PaleGoldenrod: "#EEE8AA";
+    readonly PaleGreen: "#98FB98";
+    readonly PaleTurquoise: "#AFEEEE";
+    readonly PaleVioletRed: "#DB7093";
+    readonly PapayaWhip: "#FFEFD5";
+    readonly PeachPuff: "#FFDAB9";
+    readonly Peru: "#CD853F";
+    readonly Pink: "#FFC0CB";
+    readonly Plum: "#DDA0DD";
+    readonly PowderBlue: "#B0E0E6";
+    readonly Purple: "#800080";
+    readonly RebeccaPurple: "#663399";
+    readonly Red: "#FF0000";
+    readonly RosyBrown: "#BC8F8F";
+    readonly RoyalBlue: "#4169E1";
+    readonly SaddleBrown: "#8B4513";
+    readonly Salmon: "#FA8072";
+    readonly SandyBrown: "#F4A460";
+    readonly SeaGreen: "#2E8B57";
+    readonly Seashell: "#FFF5EE";
+    readonly Sienna: "#A0522D";
+    readonly Silver: "#C0C0C0";
+    readonly SkyBlue: "#87CEEB";
+    readonly SlateBlue: "#6A5ACD";
+    readonly SlateGray: "#708090";
+    readonly SlateGrey: "#708090";
+    readonly Snow: "#FFFAFA";
+    readonly SpringGreen: "#00FF7F";
+    readonly SteelBlue: "#4682B4";
+    readonly Tan: "#D2B48C";
+    readonly Teal: "#008080";
+    readonly Thistle: "#D8BFD8";
+    readonly Tomato: "#FF6347";
+    readonly transparent: "#00000000";
+    readonly Turquoise: "#40E0D0";
+    readonly Violet: "#EE82EE";
+    readonly Wheat: "#F5DEB3";
+    readonly White: "#FFFFFF";
+    readonly WhiteSmoke: "#F5F5F5";
+    readonly Yellow: "#FFFF00";
+    readonly YellowGreen: "#9ACD32";
+}>
+```
+
+CSS Level 4 color names mapped to their hex values.
+
+
+#### RELATIVE_LENGTH_UNITS
+
+<a id="api-relative-length-units"></a>
+
+```typescript
+RELATIVE_LENGTH_UNITS: Readonly<CSSRelativeLengthUnit[]>
+```
+
+List of [CSSRelativeLengthUnit](#api-cssrelativelengthunit).
+
+
+#### RENAMED_COLORS
+
+<a id="api-renamed-colors"></a>
+
+```typescript
+RENAMED_COLORS: Partial<Record<CSSColorName, CSSColorName>>
+```
+
+Some color names share hex values. This maps to the value which would be returned by [cssNameFromHex](#api-cssnamefromhex).
+
+
+#### RESOLUTION_BY_UNIT
+
+<a id="api-resolution-by-unit"></a>
+
+```typescript
+RESOLUTION_BY_UNIT: Record<string, number | undefined>
+```
+
+Approximations of useful resolutions for various CSS units.
+
+
+#### TRANSPARENT
+
+<a id="api-transparent"></a>
+
+```typescript
+TRANSPARENT = "transparent"
+```
+
+CSS color keyword for a color with full transparency (0 alpha).
+
+