diff --git a/src/data/types.d.ts b/src/data/types.d.ts new file mode 100644 index 0000000..3fa8af5 --- /dev/null +++ b/src/data/types.d.ts @@ -0,0 +1,261 @@ +/** + * An integer is one or more decimal digits, `0` through `9`, such as `1024` or + * `-55`. An integer may be preceded by a `+` or `-` symbol, with no space + * between the symbol and the integer. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#integers} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/integer} + * + * @note + * This type actually permits any number, including decimals like `0.123`. Once + * TypeScript template literal types support more sophisticated constraints, + * this can be tightened. + * + * {@link https://github.com/microsoft/TypeScript/issues/41160} + * {@link https://github.com/microsoft/TypeScript/issues/43505} + */ +export type Integer = `${number}`; + +export type Zero = '0' | '-0' | '+0'; + +/** + * A `` represents a real number, which may or may not have a decimal + * point with a fractional component, for example `0.255`, `128` or `-1.2`. + * Numbers may also be preceded by a `+` or `-` symbol. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#numbers} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/number} + */ +export type Number = `${number}`; + +/** + * A `` is a type that represents a fraction of some other value. + * + * Percentage values are always relative to another quantity, for example a + * ``. Each property that allows percentages also defines the quantity + * to which the percentage refers. This quantity can be a value of another + * property of the same element, the value of a property of an ancestor element, + * a measurement of a containing block, or something else. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#percentages} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/percentage} + */ +export type Percentage = `${TNumber}%`; + +/** + * A `` is a `` with a {@link 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 the + * number and the unit identifier: i.e. `1 cm` is not valid. + * + * {@link https://develraoper.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#dimensions} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/dimension} + */ +export type Dimension = `${TNumber}${TUnit}`; + +/** + * @see Dimension + */ +export type Unit = LengthUnit | AngleUnit | TimeUnit | FrequencyUnit | ResolutionUnit; + +/** + * Where a distance unit, also known as a length, is allowed as a value for a + * property, this is described as the `` type. There are two types of + * lengths in CSS: relative and absolute. + * + * @remarks + * When including a length value, if the length is `0`, the unit identifier is + * not required. Otherwise, the unit identifier is required, is case + * insensitive, and must come immediately after the numeric part of the value, + * with no space in-between. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#distance_units} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/length} + */ +export type Length = + | Dimension + | (`${TNumber}` & Zero); + +/** + * {@inheritDoc Length} + * @see RelativeLengthUnit + * @see AbsoluteLengthUnit + */ +export type LengthUnit = RelativeLengthUnit | AbsoluteLengthUnit; + +/** + * Relative length units specify a length in relation to something else. For + * example, `em` is relative to the font size on the element and `vh` is + * relative to the viewport height. + * + * @see Length + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#distance_units} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/length} + */ +export type RelativeLengthUnit = FontRelativeLengthUnit | ViewportPercentageLengthUnit; + +/** + * Font-relative lengths define the `` value in terms of the size of a + * particular character or font attribute in the font currently in effect in an + * element or its parent. + * + * @see RelativeLengthUnit + * @see Length + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/length#font-relative_lengths} + */ +export type FontRelativeLengthUnit = 'cap' | 'ch' | 'em' | 'ex' | 'ic' | 'lh' | 'rem' | 'rlh'; + +/** + * Viewport-percentage lengths define the `` value relative to the size + * of the viewport, i.e., the visible portion of the document. Viewport lengths + * are invalid in `@page` declaration blocks. + * + * @see RelativeLengthUnit + * @see Length + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/length#viewport-percentage_lengths} + */ +export type ViewportPercentageLengthUnit = 'vh' | 'vw' | 'vi' | 'vb' | 'vmin' | 'vmax'; + +/** + * Absolute length units represent a physical measurement when the physical + * properties of the output medium are known, such as for print layout. This is + * done by anchoring one of the units to a physical unit, and then defining the + * others relative to it. The anchor is done differently for low-resolution + * devices, such as screens, versus high-resolution devices, such as printers. + * + * @remarks + * For low-dpi devices, the unit `px` represents the physical _reference pixel_; + * other units are defined relative to it. Thus, `1in` is defined as `96px`, + * which equals `72pt`. The consequence of this definition is that on such + * devices, dimensions described in inches (`in`), centimeters (`cm`), or + * millimeters (`mm`) don't necessarily match the size of the physical unit with + * the same name. + * + * For high-dpi devices, inches (`in`), centimeters (`cm`), and millimeters + * (`mm`) are the same as their physical counterparts. Therefore, the `px` unit + * is defined relative to them (1/96 of 1 inch). + * + * @see Length + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#distance_units} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/length} + */ +export type AbsoluteLengthUnit = 'cm' | 'mm' | 'Q' | 'in' | 'pc' | 'pt' | 'px'; + +/** + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#angle_units} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/angle} + */ +export type Angle = Dimension; + +/** + * {@inheritDoc Angle} + */ +export type AngleUnit = 'deg' | 'grad' | 'rad' | 'turn'; + +/** + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#time_units} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/time} + */ +export type Time = Dimension; + +/** + * {@inheritDoc Time} + */ +export type TimeUnit = 's' | 'ms'; + +/** + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#frequency_units} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/frequency} + */ +export type Frequency = Dimension< + TUnit, + TNumber +>; + +/** + * {@inheritDoc Frequency} + */ +export type FrequencyUnit = 'Hz' | 'kHz'; + +/** + * Resolution units are represented by the type ``. They represent + * the size of a single dot in a graphical representation, such as a screen, by + * indicating how many of these dots fit in a CSS inch, centimeter, or pixel. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#resolution_units} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/resolution} + */ +export type Resolution = Dimension< + TUnit, + TNumber +>; + +/** + * {@inheritDoc Resolution} + */ +export type ResolutionUnit = 'dpi' | 'dpcm' | 'dppx' | 'x'; + +/** + * The `` CSS data type represents a value that can be either + * a {@link Length | ``} or a {@link Percentage | ``}. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/length-percentage} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#mixing_percentages_and_dimensions} + */ +export type LengthPercentage, TPercentage extends Percentage> = TLength | TPercentage; + +/** + * The `` CSS data type represents a value that can be + * either a {@link Frequency | ``} or a + * {@link Percentage | ``}. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/frequency-percentage} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#mixing_percentages_and_dimensions} + */ +export type FrequencyPercentage, TPercentage extends Percentage> = + | TFrequency + | TPercentage; + +/** + * The `` CSS data type represents a value that can be either + * an {@link Angle | ``} or a {@link Percentage | ``}. + * + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/angle-percentage} + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#mixing_percentages_and_dimensions} + */ +export type AnglePercentage, TPercentage extends Percentage> = TAngle | TPercentage; + +/** + * The `` CSS data type represents a value that can be either a + * {@link Time | `