@cfp-studio/plugin-react 17.1.0 → 17.2.1

package/dist/index.mjs

@@ -1,141 +1 @@
-import { createAnalyzer } from '@cfp-studio/analyzer-react';
-import react from '@vitejs/plugin-react';
-import { polyfillNode } from 'esbuild-plugin-polyfill-node';
-import path from 'node:path';
-import url from 'node:url';
-
-const reactImportRegExp = /import (\* as )?React[ ,]/;
-function reactImportsPlugin() {
-  return {
-    /**
-     * 插件名称，用于在 Vite 构建过程中标识此插件。
-     */
-    name: "previewjs:react-js-imports",
-    /**
-     * 转换钩子，在 Vite 处理模块时调用。
-     * 
-     * @param code - 模块的原始代码。
-     * @param id - 模块的唯一标识符，通常是文件路径。
-     * @returns 返回转换后的代码，如果不需要转换则返回原始代码。
-     */
-    async transform(code, id) {
-      if (id.includes("node_modules") || path.extname(id) !== ".js" || reactImportRegExp.test(code)) {
-        return code;
-      }
-      return `import React from 'react';${code}`;
-    }
-  };
-}
-
-const reactFrameworkPlugin = {
-  /**
-   * 插件的基本信息
-   */
-  info: {
-    /**
-     * 插件的 API 版本
-     */
-    apiVersion: 5,
-    /**
-     * 插件的名称
-     */
-    name: "@cfp-studio/plugin-react"
-  },
-  /**
-   * 检查当前项目是否与该插件兼容
-   * @param dependencies - 项目依赖项对象
-   * @returns 如果兼容返回 true，否则返回 false
-   */
-  isCompatible: async (dependencies) => {
-    const version = await dependencies.react?.readInstalledVersion();
-    if (!version) {
-      return false;
-    }
-    const [major, minor] = version.split(".").map((n) => Number.parseInt(n));
-    if (Number.isNaN(major) || Number.isNaN(minor)) {
-      return false;
-    }
-    return major >= 17 || major === 16 && minor >= 14;
-  },
-  /**
-   * 创建插件实例
-   * @param param0 - 包含根目录、读取器、日志记录器和依赖项的对象
-   * @returns 插件实例对象
-   */
-  async create({ rootDir, reader, logger, dependencies }) {
-    const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
-    const analyzerPlugin = createAnalyzer({
-      rootDir,
-      reader,
-      logger
-    });
-    const previewDirPath = path.join(__dirname, "..", "preview");
-    return {
-      // 默认的包装器文件路径
-      defaultWrapperPath: "__previewjs__/Wrapper.tsx",
-      // 预览目录的路径
-      previewDirPath,
-      // 展开分析器插件实例的属性
-      ...analyzerPlugin,
-      /**
-       * 配置 Vite 的配置选项
-       * @param configuredPlugins - 已配置的 Vite 插件数组
-       * @returns Vite 配置对象
-       */
-      viteConfig: (configuredPlugins) => {
-        const hasReactPlugin = configuredPlugins.find(
-          (plugin) => plugin.name.startsWith("vite:react-")
-        );
-        return {
-          // 优化依赖项的配置
-          optimizeDeps: {
-            esbuildOptions: {
-              // 如果项目依赖中包含 next，则添加 polyfillNode 插件
-              plugins: dependencies.next ? [polyfillNode()] : []
-            }
-          },
-          // 路径解析配置
-          resolve: {
-            alias: {
-              // 将 react-native 别名映射到 react-native-web
-              "react-native": "react-native-web"
-            }
-          },
-          // Vite 插件数组
-          plugins: [
-            // 添加 reactImportsPlugin 插件
-            reactImportsPlugin(),
-            // 展开已配置的插件
-            ...configuredPlugins,
-            // 如果已配置的插件中不包含 Vite 的 React 插件，则添加 react 插件
-            ...!hasReactPlugin ? [react()] : [],
-            {
-              // 插件名称
-              name: "previewjs:update-react-import",
-              /**
-               * 转换代码的钩子函数
-               * @param code - 要转换的代码
-               * @param id - 文件的 ID
-               * @returns 转换后的代码，如果不需要转换则返回 undefined
-               */
-              async transform(code, id) {
-                if (!id.endsWith("__previewjs_internal__/renderer/index.tsx")) {
-                  return;
-                }
-                const reactVersion = Number.parseInt(
-                  await dependencies.react?.readInstalledVersion() || "0"
-                );
-                return code.replace(
-                  /__PREVIEWJS_PLUGIN_REACT_IMPORT_PATH__/g,
-                  reactVersion >= 18 ? "./render-18" : "./render-16"
-                );
-              }
-            }
-          ]
-        };
-      }
-    };
-  }
-};
-
-export { reactFrameworkPlugin as default };
+import{factoryWithDefaultOptions as e}from"@cfp-studio/analyzer-api/factory";import{EMPTY_OBJECT_TYPE as t,NODE_TYPE as n,UNKNOWN_TYPE as r,arrayType as i,createTypeAnalyzer as a,dereferenceType as o,functionType as s,helpers as c,maybeOptionalType as l,objectType as u,stripUnusedTypes as d}from"@cfp-studio/type-analyzer";import{createFileSystemReader as f,createStackedReader as p}from"@cfp-studio/vfs";import m from"node:fs";import h from"node:path";import g from"typescript";import _ from"node:url";import{decodePreviewableId as v,generatePreviewableId as y}from"@cfp-studio/analyzer-api";import{parseSerializableValue as b}from"@cfp-studio/serializable-values";import{extractArgs as x,extractCsf3Stories as S,extractStoriesInfo as C,resolvePreviewableId as w}from"@cfp-studio/storybook-helpers";import T from"@vitejs/plugin-react";import{polyfillNode as E}from"esbuild-plugin-polyfill-node";function D(e,t){for(let n of e.statements)if(g.isExpressionStatement(n)&&g.isBinaryExpression(n.expression)&&n.expression.operatorToken.kind===g.SyntaxKind.EqualsToken&&g.isPropertyAccessExpression(n.expression.left)&&g.isIdentifier(n.expression.left.expression)){if(n.expression.left.expression.text!==t)continue;if(n.expression.left.name.text===`propTypes`)return n.expression.right}else if(g.isClassDeclaration(n)&&n.name){if(n.name.text!==t)continue;for(let e of n.members)if(g.isPropertyDeclaration(e)&&e.initializer&&e.name.getText()===`propTypes`)return e.initializer}return null}function O(e,t,n,r,i){let a=t.sourceFile(n),o=null;a&&(o=D(a,r));let s=null;return s=o?A(t,o):k(e,t,i),{props:s.type,types:{...s.collected}}}function k(e,n,i){let a=i.getParameters()[0];if(!a)return{type:t,collected:{}};if(!a.valueDeclaration)return{type:r,collected:{}};let s=n.checker.getTypeOfSymbolAtLocation(a,a.valueDeclaration);try{let{type:e,collected:t}=n.resolveType(s);if([e]=o(e,t,[]),e.kind===`object`&&g.isParameter(a.valueDeclaration)&&g.isObjectBindingPattern(a.valueDeclaration.name)){let t=a.valueDeclaration.name,n=new Set,r=new Set,i=!1;for(let e of t.elements){if(e.dotDotDotToken){i=!0;break}let t=e.propertyName||e.name;if(!g.isIdentifier(t)){i=!0;break}n.add(t.text),e.initializer&&r.add(t.text)}i||(e=u(Object.fromEntries(Object.entries(e.fields).filter(([e])=>n.has(e)).map(([e,t])=>[e,l(t,r.has(e))]))))}return{type:e,collected:t}}catch(t){e.warn(`Unable to resolve props type for ${n.checker.typeToString(s)}`),e.error(t.toString())}return{type:r,collected:{}}}function A(e,t){let n=e.checker.getTypeAtLocation(t),i={},a={};for(let t of n.getProperties())i[t.name]=(()=>{if(!t.valueDeclaration)return r;let n=e.checker.getTypeAtLocation(t.valueDeclaration),i=e.resolveTypeArguments(n),o=i.types[0];return o?(a={...a,...i.collected},l(o,n.symbol.name===`Requireable`)):r})();let o=u(i);return{type:o,collected:d(a,[o])}}async function j(e,t,n,i){let a=t.sourceFile(i);if(!a)return[];let o=[];for(let e of a.statements)if(g.isExportAssignment(e)){if(g.isIdentifier(e.expression))continue;o.push([`default`,e,e.expression])}else if(g.isVariableStatement(e))for(let t of e.declarationList.declarations)!g.isIdentifier(t.name)||!t.initializer||o.push([t.name.text,e,t.initializer]);else if(g.isFunctionDeclaration(e)){let t=!!e.modifiers?.find(e=>e.kind===g.SyntaxKind.ExportKeyword)&&!!e.modifiers?.find(e=>e.kind===g.SyntaxKind.DefaultKeyword),n=e.name?.text;(t||n)&&o.push([n||`default`,e,e])}else g.isClassDeclaration(e)&&e.name&&o.push([e.name.text,e,e]);let s=C(a);e.debug(`**storiresInfo: ${s}`);let l=[],u=x(a),d=c.extractExportedNames(a);async function f(r,a,o){if(o===`default`&&s)return null;let c=u[o],l=o===`default`||!!d[o],f=N(t.checker,a);if(s&&l&&(c||f?.parameters.length===0)){let i=M(e,t,n,s.component);return{...r,analyze:async()=>({args:c?{sourcePosition:{start:c.getStart(),end:c.getEnd()},value:await b(c)}:null}),associatedComponent:i}}return f?{...r,exported:l,analyze:async()=>O(e,t,i,o,f)}:null}for(let[e,t,r]of o){let a=await f({id:y({filePath:h.relative(n,i),name:e}),sourcePosition:{start:t.getStart(),end:t.getEnd()}},r,e);a&&l.push(a)}return[...l,...await S(n,t,a,async i=>{let{filePath:a}=v(i),o=(await j(e,t,n,h.join(n,a))).find(e=>e.id===i);return!o||!(`exported`in o)?{props:r,types:{}}:o.analyze()})]}function M(e,t,n,i){let a=w(n,t.checker,i);return i&&a?{id:a,analyze:async()=>{let o=N(t.checker,i);if(!o)return{props:r,types:{}};let{filePath:s,name:c}=v(a);return O(e,t,h.join(n,s),c,o)}}:null}function N(e,t){let n=e.getTypeAtLocation(t);if(n.flags===g.TypeFlags.Any&&g.isCallExpression(t)&&g.isPropertyAccessExpression(t.expression)&&g.isIdentifier(t.expression.name)&&t.expression.name.text===`bind`){let r=e.getSymbolAtLocation(t.expression.expression);r?.valueDeclaration&&g.isVariableDeclaration(r.valueDeclaration)&&r.valueDeclaration.initializer&&(n=e.getTypeAtLocation(r.valueDeclaration.initializer))}for(let e of n.getCallSignatures())if(P(e.getReturnType()))return e;if(n.symbol){let r=e.getTypeOfSymbolAtLocation(n.symbol,t);for(let e of r.getConstructSignatures())if(e.getReturnType().getProperty(`render`))return e}return null}function P(e){return!!I(e)}const F=new Set([`Element`,`ReactElement`]);function I(e){if(e.isUnion()){for(let t of e.types)if(I(t))return!0}return F.has(e.symbol?.getEscapedName().toString())}const L={Component:n,ComponentClass:s(n),FunctionComponent:s(n),ReactElement:n,ReactNode:n,ReactNodeArray:i(n),ReactPortal:n},R=e(({rootDir:e,reader:t,logger:n})=>{let r=_.fileURLToPath(new URL(`.`,import.meta.url)),i=h.join(r,`..`,`types`),o=h.join(r,`..`,`node_modules`),s=m.existsSync(i)?i:o,c=a({reader:p([t,f({mapping:{from:s,to:h.join(e,`node_modules`)},watch:!1}),...s===i?[f({mapping:{from:i,to:h.join(e,`node_modules`,`@types`)},watch:!1})]:[]]),rootDir:e,specialTypes:L,tsCompilerOptions:{jsx:g.JsxEmit.ReactJSX,jsxImportSource:`react`},warn:n.warn.bind(n)});return{typeAnalyzer:c,crawlFiles:async t=>{let r=t.map(t=>h.isAbsolute(t)?t:h.join(e,t)),i=c.analyze(r),a=[],o=[];for(let t of r)for(let r of await j(n,i,e,t))`exported`in r?a.push(r):o.push(r);return{components:a,stories:o}},dispose:()=>{c.dispose()}}}),z=/import (\* as )?React[ ,]/;function B(){return{name:`previewjs:react-js-imports`,async transform(e,t){return t.includes(`node_modules`)||h.extname(t)!==`.js`||z.test(e)?e:`import React from 'react';${e}`}}}const V={info:{apiVersion:5,name:`@cfp-studio/plugin-react`},isCompatible:async e=>{let t=await e.react?.readInstalledVersion();if(!t)return!1;let[n,r]=t.split(`.`).map(e=>Number.parseInt(e));return Number.isNaN(n)||Number.isNaN(r)?!1:n>=17||n===16&&r>=14},async create({rootDir:e,reader:t,logger:n,dependencies:r}){let i=_.fileURLToPath(new URL(`.`,import.meta.url)),a=R({rootDir:e,reader:t,logger:n});return{defaultWrapperPath:`__previewjs__/Wrapper.tsx`,previewDirPath:h.join(i,`..`,`preview`),...a,viteConfig:e=>{let t=e.find(e=>e.name.startsWith(`vite:react-`));return{optimizeDeps:{esbuildOptions:{plugins:r.next?[E()]:[]}},resolve:{alias:{"react-native":`react-native-web`}},plugins:[B(),...e,...t?[]:[T()],{name:`previewjs:update-react-import`,async transform(e,t){if(!t.endsWith(`__previewjs_internal__/renderer/index.tsx`))return;let n=Number.parseInt(await r.react?.readInstalledVersion()||`0`);return e.replace(/__PREVIEWJS_PLUGIN_REACT_IMPORT_PATH__/g,n>=18?`./render-18`:`./render-16`)}}]}}}}};export{V as default};

package/package.json

@@ -1,35 +1,58 @@
 {
   "name": "@cfp-studio/plugin-react",
-  "version": "17.1.0",
+  "version": "17.2.1",
   "license": "MIT",
-  "sideEffects": false,
-  "type": "module",
-  "main": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "preview"
+    "preview",
+    "types"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "dependencies": {
-    "@cfp-studio/analyzer-react": "^0.1.11",
     "@vitejs/plugin-react": "4.3.4",
-    "esbuild-plugin-polyfill-node": "0.3.0"
+    "esbuild-plugin-polyfill-node": "0.3.0",
+    "typescript": "5.9.3",
+    "@cfp-studio/analyzer-api": "0.1.12",
+    "@cfp-studio/type-analyzer": "10.1.8",
+    "@cfp-studio/vfs": "2.1.6",
+    "@cfp-studio/storybook-helpers": "6.0.2",
+    "@cfp-studio/serializable-values": "9.0.8"
   },
   "devDependencies": {
-    "@playwright/test": "1.50.1",
+    "@playwright/test": "1.64.1",
+    "@types/prop-types": "15.7.15",
     "@types/react": "18.3.18",
     "@types/react-dom": "18.3.5",
-    "pino": "9.5.0",
-    "pino-pretty": "11.2.1",
-    "unbuild": "2.0.0",
-    "vite": "6.2.0",
+    "csstype": "3.1.3",
+    "pino": "9.11.0",
+    "pino-pretty": "11.3.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "vite": "6.4.5",
+    "vitest": "5.0.5",
+    "@cfp-studio/iframe": "18.2.0",
     "@cfp-studio/testing": "14.0.1",
-    "@cfp-studio/iframe": "18.0.0",
-    "@cfp-studio/core": "1.0.0",
-    "@cfp-studio/api": "16.1.0"
+    "@cfp-studio/core": "1.0.6"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "cfp": {
+    "domain": "web-preview",
+    "layer": "analysis"
   },
   "scripts": {
-    "build": "tsc && tsc -p preview/tsconfig.json && unbuild",
-    "e2e-test": "playwright test"
+    "build": "node scripts/prepare-types.mjs && tsdown",
+    "release": "node scripts/prepare-types.mjs && tsdown --minify",
+    "prepare:types": "node scripts/prepare-types.mjs",
+    "typecheck": "tsc --noEmit && tsc -p preview/tsconfig.json",
+    "test": "node scripts/prepare-types.mjs && vitest run",
+    "test:watch": "vitest watch",
+    "e2e-test": "pnpm --dir tests/apps/react16 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react17 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react18 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react-sass install --ignore-workspace --ignore-scripts && playwright test",
+    "lint": "oxlint",
+    "format": "oxfmt --write ."
   }
 }

package/preview/index.tsx

@@ -47,7 +47,6 @@ export const loadRenderer: RendererLoader = async ({
         previewableModule.default?.component ||
         Previewable
     : Previewable;
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   const Renderer = (props: any) => {
     return (
       <ErrorBoundary renderId={renderId}>

package/preview/root.ts

@@ -1,2 +1 @@
-// biome-ignore lint/style/noNonNullAssertion: <explanation>
 export const rootContainer = document.getElementById("root")!;

package/preview/tsconfig.json

@@ -1,9 +1,9 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "module": "ES2022",
-    "moduleResolution": "Bundler",
-    "jsx": "preserve"
-  },
-  "exclude": ["types"]
-}
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve"
+  },
+  "exclude": ["types"]
+}

package/types/csstype/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2017-2018 Fredrik Nicol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/types/csstype/README.md

@@ -0,0 +1,277 @@
+# CSSType
+
+[![npm](https://img.shields.io/npm/v/csstype.svg)](https://www.npmjs.com/package/csstype)
+
+TypeScript 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.
+
+**TypeScript**
+
+```ts
+import type * as CSS from 'csstype';
+
+const style: CSS.Properties = {
+  colour: 'white', // Type error on property
+  textAlign: 'middle', // Type error on value
+};
+```
+
+**Flow**
+
+```js
+// @flow strict
+import * as CSS from 'csstype';
+
+const style: CSS.Properties<> = {
+  colour: 'white', // Type error on property
+  textAlign: 'middle', // Type error on value
+};
+```
+
+_Further examples below will be in TypeScript!_
+
+## Getting started
+
+```sh
+$ npm install csstype
+```
+
+## Table of content
+
+- [Style types](#style-types)
+- [At-rule types](#at-rule-types)
+- [Pseudo types](#pseudo-types)
+- [Generics](#generics)
+- [Usage](#usage)
+- [What should I do when I get type errors?](#what-should-i-do-when-i-get-type-errors)
+- [Version 3.0](#version-30)
+- [Contributing](#contributing)
+
+## Style types
+
+Properties are categorized in different uses and in several technical variations to provide typings that suits as many as possible.
+
+|                | Default              | `Hyphen`                   | `Fallback`                   | `HyphenFallback`                   |
+| -------------- | -------------------- | -------------------------- | ---------------------------- | ---------------------------------- |
+| **All**        | `Properties`         | `PropertiesHyphen`         | `PropertiesFallback`         | `PropertiesHyphenFallback`         |
+| **`Standard`** | `StandardProperties` | `StandardPropertiesHyphen` | `StandardPropertiesFallback` | `StandardPropertiesHyphenFallback` |
+| **`Vendor`**   | `VendorProperties`   | `VendorPropertiesHyphen`   | `VendorPropertiesFallback`   | `VendorPropertiesHyphenFallback`   |
+| **`Obsolete`** | `ObsoleteProperties` | `ObsoletePropertiesHyphen` | `ObsoletePropertiesFallback` | `ObsoletePropertiesHyphenFallback` |
+| **`Svg`**      | `SvgProperties`      | `SvgPropertiesHyphen`      | `SvgPropertiesFallback`      | `SvgPropertiesHyphenFallback`      |
+
+Categories:
+
+- **All** - Includes `Standard`, `Vendor`, `Obsolete` and `Svg`
+- **`Standard`** - Current properties and extends subcategories `StandardLonghand` and `StandardShorthand` _(e.g. `StandardShorthandProperties`)_
+- **`Vendor`** - Vendor prefixed properties and extends subcategories `VendorLonghand` and `VendorShorthand` _(e.g. `VendorShorthandProperties`)_
+- **`Obsolete`** - Removed or deprecated properties
+- **`Svg`** - SVG-specific properties
+
+Variations:
+
+- **Default** - JavaScript (camel) cased property names
+- **`Hyphen`** - CSS (kebab) cased property names
+- **`Fallback`** - Also accepts array of values e.g. `string | string[]`
+
+## At-rule types
+
+At-rule interfaces with descriptors.
+
+**TypeScript**: These will be found in the `AtRule` namespace, e.g. `AtRule.Viewport`.  
+**Flow**: These will be prefixed with `AtRule$`, e.g. `AtRule$Viewport`.
+
+|                      | Default        | `Hyphen`             | `Fallback`             | `HyphenFallback`             |
+| -------------------- | -------------- | -------------------- | ---------------------- | ---------------------------- |
+| **`@counter-style`** | `CounterStyle` | `CounterStyleHyphen` | `CounterStyleFallback` | `CounterStyleHyphenFallback` |
+| **`@font-face`**     | `FontFace`     | `FontFaceHyphen`     | `FontFaceFallback`     | `FontFaceHyphenFallback`     |
+| **`@viewport`**      | `Viewport`     | `ViewportHyphen`     | `ViewportFallback`     | `ViewportHyphenFallback`     |
+
+## Pseudo types
+
+String literals of pseudo classes and pseudo elements
+
+- `Pseudos`
+
+  Extends:
+
+  - `AdvancedPseudos`
+
+    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.
+
+  - `SimplePseudos`
+
+    Plain pseudos e.g. `:hover` that can only be **one** variation.
+
+## Generics
+
+All interfaces has two optional generic argument to define length and time: `CSS.Properties<TLength = string | 0, TTime = string>`
+
+- **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.
+  ```tsx
+  const style: CSS.Properties<string | number> = {
+    width: 100,
+  };
+  ```
+- **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.
+  ```tsx
+  const style: CSS.Properties<string | number, number> = {
+    transitionDuration: 1000,
+  };
+  ```
+
+## Usage
+
+```ts
+import type * as CSS from 'csstype';
+
+const style: CSS.Properties = {
+  width: '10px',
+  margin: '1em',
+};
+```
+
+In 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.
+
+```ts
+import type * as CSS from 'csstype';
+
+const style: CSS.PropertiesFallback = {
+  display: ['-webkit-flex', 'flex'],
+  color: 'white',
+};
+```
+
+There's even string literals for pseudo selectors and elements.
+
+```ts
+import type * as CSS from 'csstype';
+
+const pseudos: { [P in CSS.SimplePseudos]?: CSS.Properties } = {
+  ':hover': {
+    display: 'flex',
+  },
+};
+```
+
+Hyphen 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`.
+
+```ts
+import type * as CSS from 'csstype';
+
+interface Style extends CSS.Properties, CSS.PropertiesHyphen {}
+
+const style: Style = {
+  'flex-grow': 1,
+  'flex-shrink': 0,
+  'font-weight': 'normal',
+  backgroundColor: 'white',
+};
+```
+
+Adding type checked CSS properties to a `HTMLElement`.
+
+```ts
+import type * as CSS from 'csstype';
+
+const style: CSS.Properties = {
+  color: 'red',
+  margin: '1em',
+};
+
+let button = document.createElement('button');
+
+Object.assign(button.style, style);
+```
+
+## What should I do when I get type errors?
+
+The 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:
+
+_If you're using CSS Custom Properties you can step directly to step 3._
+
+1.  **First of all, make sure you're doing it right.** A type error could also indicate that you're not :wink:
+
+    - 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 included
+    - 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...` errors
+
+2.  **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.
+3.  Fix the issue locally with **TypeScript** (Flow further down):
+
+    - The recommended way is to use **module augmentation**. Here's a few examples:
+
+      ```ts
+      // My css.d.ts file
+      import type * as CSS from 'csstype';
+
+      declare module 'csstype' {
+        interface Properties {
+          // Add a missing property
+          WebkitRocketLauncher?: string;
+
+          // Add a CSS Custom Property
+          '--theme-color'?: 'black' | 'white';
+
+          // Allow namespaced CSS Custom Properties
+          [index: `--theme-${string}`]: any;
+          
+          // Allow any CSS Custom Properties
+          [index: `--${string}`]: any;
+
+          // ...or allow any other property
+          [index: string]: any;
+        }
+      }
+      ```
+
+    - The alternative way is to use **type assertion**. Here's a few examples:
+
+      ```ts
+      const style: CSS.Properties = {
+        // Add a missing property
+        ['WebkitRocketLauncher' as any]: 'launching',
+
+        // Add a CSS Custom Property
+        ['--theme-color' as any]: 'black',
+      };
+      ```
+
+    Fix the issue locally with **Flow**:
+
+    - Use **type assertion**. Here's a few examples:
+
+      ```js
+      const style: $Exact<CSS.Properties<*>> = {
+        // Add a missing property
+        [('WebkitRocketLauncher': any)]: 'launching',
+
+        // Add a CSS Custom Property
+        [('--theme-color': any)]: 'black',
+      };
+      ```
+
+## Version 3.0
+
+- **All property types are exposed with namespace**  
+  TypeScript: `Property.AlignContent` (was `AlignContentProperty` before)  
+  Flow: `Property$AlignContent`
+- **All at-rules are exposed with namespace**  
+  TypeScript: `AtRule.FontFace` (was `FontFace` before)  
+  Flow: `AtRule$FontFace`
+- **Data types are NOT exposed**  
+  E.g. `Color` and `Box`. Because the generation of data types may suddenly be removed or renamed.
+- **TypeScript hack for autocompletion**  
+  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`.
+- **New generic for time**  
+  Read more on the ["Generics"](#generics) section.
+- **Flow types improvements**  
+  Flow Strict enabled and exact types are used.
+
+## Contributing
+
+**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.
+
+### Commands
+
+- `npm run build` Generates typings and type checks them
+- `npm run watch` Runs build on each save
+- `npm run test` Runs the tests
+- `npm run lazy` Type checks, lints and formats everything