AK-21/Graphite-Industrial-Intelligence
0
1# CSSType2 3[](https://www.npmjs.com/package/csstype)4 5TypeScript and Flow definitions for CSS, generated by [data from MDN](https://github.com/mdn/data). It provides autocompletion and type checking for CSS properties and values.6 7**TypeScript**8 9```ts10import type * as CSS from 'csstype';11 12const style: CSS.Properties = {13 colour: 'white', // Type error on property14 textAlign: 'middle', // Type error on value15};16```17 18**Flow**19 20```js21// @flow strict22import * as CSS from 'csstype';23 24const style: CSS.Properties<> = {25 colour: 'white', // Type error on property26 textAlign: 'middle', // Type error on value27};28```29 30_Further examples below will be in TypeScript!_31 32## Getting started33 34```sh35$ npm install csstype36```37 38## Table of content39 40- [Style types](#style-types)41- [At-rule types](#at-rule-types)42- [Pseudo types](#pseudo-types)43- [Generics](#generics)44- [Usage](#usage)45- [What should I do when I get type errors?](#what-should-i-do-when-i-get-type-errors)46- [Version 3.0](#version-30)47- [Contributing](#contributing)48 49## Style types50 51Properties are categorized in different uses and in several technical variations to provide typings that suits as many as possible.52 53| | Default | `Hyphen` | `Fallback` | `HyphenFallback` |54| -------------- | -------------------- | -------------------------- | ---------------------------- | ---------------------------------- |55| **All** | `Properties` | `PropertiesHyphen` | `PropertiesFallback` | `PropertiesHyphenFallback` |56| **`Standard`** | `StandardProperties` | `StandardPropertiesHyphen` | `StandardPropertiesFallback` | `StandardPropertiesHyphenFallback` |57| **`Vendor`** | `VendorProperties` | `VendorPropertiesHyphen` | `VendorPropertiesFallback` | `VendorPropertiesHyphenFallback` |58| **`Obsolete`** | `ObsoleteProperties` | `ObsoletePropertiesHyphen` | `ObsoletePropertiesFallback` | `ObsoletePropertiesHyphenFallback` |59| **`Svg`** | `SvgProperties` | `SvgPropertiesHyphen` | `SvgPropertiesFallback` | `SvgPropertiesHyphenFallback` |60 61Categories:62 63- **All** - Includes `Standard`, `Vendor`, `Obsolete` and `Svg`64- **`Standard`** - Current properties and extends subcategories `StandardLonghand` and `StandardShorthand` _(e.g. `StandardShorthandProperties`)_65- **`Vendor`** - Vendor prefixed properties and extends subcategories `VendorLonghand` and `VendorShorthand` _(e.g. `VendorShorthandProperties`)_66- **`Obsolete`** - Removed or deprecated properties67- **`Svg`** - SVG-specific properties68 69Variations:70 71- **Default** - JavaScript (camel) cased property names72- **`Hyphen`** - CSS (kebab) cased property names73- **`Fallback`** - Also accepts array of values e.g. `string | string[]`74 75## At-rule types76 77At-rule interfaces with descriptors.78 79**TypeScript**: These will be found in the `AtRule` namespace, e.g. `AtRule.Viewport`. 80**Flow**: These will be prefixed with `AtRule$`, e.g. `AtRule$Viewport`.81 82| | Default | `Hyphen` | `Fallback` | `HyphenFallback` |83| -------------------- | -------------- | -------------------- | ---------------------- | ---------------------------- |84| **`@counter-style`** | `CounterStyle` | `CounterStyleHyphen` | `CounterStyleFallback` | `CounterStyleHyphenFallback` |85| **`@font-face`** | `FontFace` | `FontFaceHyphen` | `FontFaceFallback` | `FontFaceHyphenFallback` |86| **`@viewport`** | `Viewport` | `ViewportHyphen` | `ViewportFallback` | `ViewportHyphenFallback` |87 88## Pseudo types89 90String literals of pseudo classes and pseudo elements91 92- `Pseudos`93 94 Extends:95 - `AdvancedPseudos`96 97 Function-like pseudos e.g. `:not(:first-child)`. The string literal contains the value excluding the parenthesis: `:not`. These are separated because they require an argument that results in infinite number of variations.98 99 - `SimplePseudos`100 101 Plain pseudos e.g. `:hover` that can only be **one** variation.102 103## Generics104 105All interfaces has two optional generic argument to define length and time: `CSS.Properties<TLength = string | 0, TTime = string>`106 107- **Length** is the first generic parameter and defaults to `string | 0` because `0` is the only [length where the unit identifier is optional](https://drafts.csswg.org/css-values-3/#lengths). You can specify this, e.g. `string | number`, for platforms and libraries that accepts any numeric value as length with a specific unit.108 ```tsx109 const style: CSS.Properties<string | number> = {110 width: 100,111 };112 ```113- **Time** is the second generic argument and defaults to `string`. You can specify this, e.g. `string | number`, for platforms and libraries that accepts any numeric value as length with a specific unit.114 ```tsx115 const style: CSS.Properties<string | number, number> = {116 transitionDuration: 1000,117 };118 ```119 120## Usage121 122```ts123import type * as CSS from 'csstype';124 125const style: CSS.Properties = {126 width: '10px',127 margin: '1em',128};129```130 131In some cases, like for CSS-in-JS libraries, an array of values is a way to provide fallback values in CSS. Using `CSS.PropertiesFallback` instead of `CSS.Properties` will add the possibility to use any property value as an array of values.132 133```ts134import type * as CSS from 'csstype';135 136const style: CSS.PropertiesFallback = {137 display: ['-webkit-flex', 'flex'],138 color: 'white',139};140```141 142There's even string literals for pseudo selectors and elements.143 144```ts145import type * as CSS from 'csstype';146 147const pseudos: { [P in CSS.SimplePseudos]?: CSS.Properties } = {148 ':hover': {149 display: 'flex',150 },151};152```153 154Hyphen cased (kebab cased) properties are provided in `CSS.PropertiesHyphen` and `CSS.PropertiesHyphenFallback`. It's not **not** added by default in `CSS.Properties`. To allow both of them, you can simply extend with `CSS.PropertiesHyphen` or/and `CSS.PropertiesHyphenFallback`.155 156```ts157import type * as CSS from 'csstype';158 159interface Style extends CSS.Properties, CSS.PropertiesHyphen {}160 161const style: Style = {162 'flex-grow': 1,163 'flex-shrink': 0,164 'font-weight': 'normal',165 backgroundColor: 'white',166};167```168 169Adding type checked CSS properties to a `HTMLElement`.170 171```ts172import type * as CSS from 'csstype';173 174const style: CSS.Properties = {175 color: 'red',176 margin: '1em',177};178 179let button = document.createElement('button');180 181Object.assign(button.style, style);182```183 184## What should I do when I get type errors?185 186The goal is to have as perfect types as possible and we're trying to do our best. But with CSS Custom Properties, the CSS specification changing frequently and vendors implementing their own specifications with new releases sometimes causes type errors even if it should work. Here's some steps you could take to get it fixed:187 188_If you're using CSS Custom Properties you can step directly to step 3._189 1901. **First of all, make sure you're doing it right.** A type error could also indicate that you're not :wink:191 - Some CSS specs that some vendors has implemented could have been officially rejected or haven't yet received any official acceptance and are therefor not included192 - If you're using TypeScript, [type widening](https://blog.mariusschulz.com/2017/02/04/TypeScript-2-1-literal-type-widening) could be the reason you get `Type 'string' is not assignable to...` errors193 1942. **Have a look in [issues](https://github.com/frenic/csstype/issues) to see if an issue already has been filed. If not, create a new one.** To help us out, please refer to any information you have found.1953. Fix the issue locally with **TypeScript** (Flow further down):196 - The recommended way is to use **module augmentation**. Here's a few examples:197 198 ```ts199 // My css.d.ts file200 import type * as CSS from 'csstype';201 202 declare module 'csstype' {203 interface Properties {204 // Add a missing property205 WebkitRocketLauncher?: string;206 207 // Add a CSS Custom Property208 '--theme-color'?: 'black' | 'white';209 210 // Allow namespaced CSS Custom Properties211 [index: `--theme-${string}`]: any;212 213 // Allow any CSS Custom Properties214 [index: `--${string}`]: any;215 216 // ...or allow any other property217 [index: string]: any;218 }219 }220 ```221 222 - The alternative way is to use **type assertion**. Here's a few examples:223 224 ```ts225 const style: CSS.Properties = {226 // Add a missing property227 ['WebkitRocketLauncher' as any]: 'launching',228 229 // Add a CSS Custom Property230 ['--theme-color' as any]: 'black',231 };232 ```233 234 Fix the issue locally with **Flow**:235 - Use **type assertion**. Here's a few examples:236 237 ```js238 const style: $Exact<CSS.Properties<*>> = {239 // Add a missing property240 [('WebkitRocketLauncher': any)]: 'launching',241 242 // Add a CSS Custom Property243 [('--theme-color': any)]: 'black',244 };245 ```246 247## Version 3.2248 249- **No longer compatible with version 2** 250 Conflicts may occur when both version ^3.2.0 and ^2.0.0 are installed. Potential fix for Npm would be to force resolution in `package.json`:251 ```json252 {253 "overrides": {254 "csstype": "^3.2.0"255 }256 }257 ```258 259## Version 3.1260 261- **Data types are exposed** 262 TypeScript: `DataType.Color`263 Flow: `DataType$Color`264 265## Version 3.0266 267- **All property types are exposed with namespace** 268 TypeScript: `Property.AlignContent` (was `AlignContentProperty` before) 269 Flow: `Property$AlignContent`270- **All at-rules are exposed with namespace** 271 TypeScript: `AtRule.FontFace` (was `FontFace` before) 272 Flow: `AtRule$FontFace`273- **Data types are NOT exposed** 274 E.g. `Color` and `Box`. Because the generation of data types may suddenly be removed or renamed.275- **TypeScript hack for autocompletion** 276 Uses `(string & {})` for literal string unions and `(number & {})` for literal number unions ([related issue](https://github.com/microsoft/TypeScript/issues/29729)). Utilize `PropertyValue<T>` to unpack types from e.g. `(string & {})` to `string`.277- **New generic for time** 278 Read more on the ["Generics"](#generics) section.279- **Flow types improvements** 280 Flow Strict enabled and exact types are used.281 282## Contributing283 284**Never modify `index.d.ts` and `index.js.flow` directly. They are generated automatically and committed so that we can easily follow any change it results in.** Therefor it's important that you run `$ git config merge.ours.driver true` after you've forked and cloned. That setting prevents merge conflicts when doing rebase.285 286### Commands287 288- `npm run build` Generates typings and type checks them289- `npm run watch` Runs build on each save290- `npm run test` Runs the tests291- `npm run lazy` Type checks, lints and formats everything292