Template literal types for strongly typed string values

I’m working on a library that’s essentially typescript functions that generate valid CSS. Having just discovered template literal types, I figured out that you can essentially have strongly typed CSS strings. I think this could help tighten up csstype’s property types even further for things like CSS units, colors, functions, etc.

Some examples:

export type PCT = `${ number }%`

export function pct(amount: number): PCT {
    return `${ amount }%`
}

export type NumberOrPercent = number | PCT

export type HEX = `#${ string }`
export type RGB = `rgb(${ NumberOrPercent } ${ NumberOrPercent } ${ NumberOrPercent } / ${ NumberOrPercent })`

export type Color = HEX | RGB

export function rgb(r: NumberOrPercent, g: NumberOrPercent, b: NumberOrPercent, alpha: NumberOrPercent): RGB {
    return `rgb(${ r } ${ g } ${ b } / ${ alpha })`
}

export type ColorContrastFn = `color-contrast(${ Color } vs ${ Color })`

export function colorContrast(base: Color, compare: Color): ColorContrastFn {
    return `color-contrast(${ base } vs ${ compare })`
}

With the above types, you restrict the types of strings that are allowed to be passed into other interpolated string types to form strongly typed CSS.

// These are all valid:
colorContrast('#FFF', '#000')
colorContrast('rgb(255 255 255 / 1)', '#000')
colorContrast(rgb(255, 0, 0), 'rgb(255 0 0 / 1)')

// These are type errors:
colorContrast('asdf', '12345')
colorContrast('flex-start', 'flex-end')

This means that the Properties interface could become more strict to be something like:

interface Properties {
    backgroundColor: Color
    color: Color
}

Is this something that sounds useful for these type definitions? Is it something that’s doable based on how the type definitions are even being generated?

[buschtoens]

While I agree that strongly-typing <color> is not really feasible yet, strongly-typing any <dimension> and <percentage> value should be realistically possible, as the syntax is fairly strict for them.

Dimensions

A <dimension> is a <number> with a unit attached to it, for example 45deg, 100ms, or 10px. The attached unit identifier is case insensitive. There is never a space or any other characters between a the number and the unit identifier: i.e. 1 cm is not valid.

CSS uses dimensions to specify:

• <length> (Distance units)
• <angle>
• <time>
• <frequency>
• <resolution>

Percentages

The <percentage> data type consists of a <number> followed by the percentage sign (%). Optionally, it may be preceded by a single + or - sign, although negative values are not valid for all properties. As with all CSS dimensions, there is no space between the symbol and the number.

Would you accept a pull request? Do you have any further thoughts?

[buschtoens]

Also, what’s the rationale for not exporting the DataType namespace?