feat(postcss-custom-properties): new type definition (#43446)

- definition file
- test coverage for standalone and plugin usage

https://github.com/postcss/postcss-custom-properties#usage

Thanks!

types/postcss-custom-properties/index.d.ts

@@ -0,0 +1,80 @@
+// Type definitions for postcss-custom-properties 9.1
+// Project: https://github.com/postcss/postcss-custom-properties#readme
+// Definitions by: Piotr Błażejewicz <https://github.com/peterblazejewicz>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+import { Plugin, Result, LazyResult } from 'postcss';
+
+declare namespace postcssCustomProperties {
+    /**
+     * Sources where Custom Properties can be imported from or export to,
+     * which might be CSS, JS, and JSON files, functions, and directly passed objects
+     */
+    type ImportSources =
+        | string
+        | (() => CustomPropertiesObject)
+        | CustomPropertiesObject
+        | (() => CustomPropertiesObject)
+        | Promise<CustomPropertiesObject>;
+    /**
+     * Sources where Custom Properties can be imported from or export to,
+     * which might be CSS, JS, and JSON files, functions, and directly passed objects
+     */
+    type ExportSources =
+        | string
+        | CustomPropertiesObject
+        | ((customProperties: CustomPropertiesObject) => any)
+        | Promise<CustomPropertiesObject>;
+
+    interface CustomPropertiesObject {
+        customProperties?: {
+            [name: string]: string;
+        };
+        ['custom-properties']?: {
+            [name: string]: string;
+        };
+    }
+
+    interface Options {
+        /**
+         * The preserve option determines whether Custom Properties
+         * and properties using custom properties should be preserved in their original form.
+         * By default, both of these are preserved
+         * @see {@link https://github.com/postcss/postcss-custom-properties#preserve}
+         */
+        preserve?: boolean;
+        /**
+         * The importFrom option specifies sources where Custom Properties can be imported from,
+         * which might be CSS, JS, and JSON files, functions, and directly passed objects.
+         * Multiple sources can be passed into this option, and they will be parsed in the order they are received.
+         * JavaScript files, JSON files, functions, and objects will need to namespace Custom Properties using the customProperties or custom-properties key.
+         * @see {@link https://github.com/postcss/postcss-custom-properties#importfrom}
+         */
+        importFrom?: ImportSources | ImportSources[];
+        /**
+         * The exportTo option specifies destinations where Custom Properties can be exported to,
+         * which might be CSS, JS, and JSON files, functions, and directly passed objects.
+         * Multiple destinations can be passed into this option, and they will be parsed in the order they are received.
+         * JavaScript files, JSON files, and objects will need to namespace Custom Properties using the customProperties or custom-properties key.
+         * @see {@link https://github.com/postcss/postcss-custom-properties#exportto}
+         */
+        exportTo?: ExportSources | ExportSources[];
+    }
+
+    type CustomPropertiesPlugin = Plugin<Options> & {
+        process: (
+            css:
+                | string
+                | {
+                      toString(): string;
+                  }
+                | Result,
+            opts?: any,
+            pluginOptions?: Options,
+        ) => LazyResult;
+    };
+}
+
+declare const postcssCustomProperties: postcssCustomProperties.CustomPropertiesPlugin;
+
+export = postcssCustomProperties;

types/postcss-custom-properties/package.json

@@ -0,0 +1,6 @@
+{
+    "private": true,
+    "dependencies": {
+        "postcss": "^7.0.27"
+    }
+}

types/postcss-custom-properties/postcss-custom-properties-tests.ts

@@ -0,0 +1,80 @@
+import postcss = require('postcss');
+import postcssCustomProperties = require('postcss-custom-properties');
+import { CustomPropertiesObject, Options } from 'postcss-custom-properties';
+
+const css = `:root {
+    --color: red;
+  }
+
+  h1 {
+    color: var(--color);
+  }`;
+
+const pluginOptions: Options = {
+    preserve: true,
+    importFrom: 'path/to/file.css',
+    exportTo: 'path/to/file.css',
+};
+
+const processOptions = {
+    from: 'src/app.css',
+    to: 'dest/app.css',
+};
+
+postcssCustomProperties.process(css, processOptions, pluginOptions);
+
+postcss([postcssCustomProperties(pluginOptions)]).process(css, processOptions);
+
+postcssCustomProperties({
+    importFrom: 'path/to/file.css',
+});
+
+postcssCustomProperties({
+    importFrom: [
+        'path/to/file.css',
+        'and/then/this.js',
+        'and/then/that.json',
+        {
+            customProperties: { '--color': 'red' },
+        },
+        () => {
+            const customProperties = { '--color': 'red' };
+
+            return { customProperties };
+        },
+    ],
+});
+
+postcssCustomProperties({
+    exportTo: 'path/to/file.css', // :root { --color: red; }
+});
+
+const customProperties = {
+    '--ref-color': 'var(--color)',
+    '--color': 'rgb(255, 0, 0)',
+    '--color-h': '0',
+    '--color-s': '100%',
+    '--color-l': '50%',
+    '--color-hsl': 'hsl(var(--color-h), var(--color-s), var(--color-l))',
+    '--circular': 'var(--circular-2)',
+    '--circular-2': 'var(--circular)',
+    '--margin': '0 10px 20px 30px',
+    '--theme-color': '#053',
+};
+
+const cachedObject: CustomPropertiesObject = {
+    customProperties,
+};
+
+postcssCustomProperties({
+    exportTo: [
+        'path/to/file.css',
+        'and/then/this.js',
+        'and/then/this.mjs',
+        'and/then/that.json',
+        cachedObject,
+        (customProperties: CustomPropertiesObject) => {
+            customProperties;
+        },
+    ],
+});

types/postcss-custom-properties/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictFunctionTypes": true,
+        "strictNullChecks": true,
+        "baseUrl": "../",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "postcss-custom-properties-tests.ts"
+    ]
+}

types/postcss-custom-properties/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }