feat: Implement @pigment-css/theme package

At this point, it is just a helper library for extending TS types of the user theme.

packages/pigment-css-theme/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Material-UI SAS
+
+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.

packages/pigment-css-theme/README.md

@@ -0,0 +1,3 @@
+# @pigment-css/theme
+
+Theme related JavaScript and Typescript utilities to be shared across other Pigment CSS libraries.

packages/pigment-css-theme/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@pigment-css/theme",
+  "version": "0.0.27",
+  "main": "build/index.js",
+  "module": "build/index.mjs",
+  "types": "build/index.d.ts",
+  "author": "MUI Team",
+  "description": "Theme related JS and TS utilities to be shared across other Pigment CSS libraries.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mui/pigment-css.git",
+    "directory": "packages/pigment-css-theme"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mui/pigment-css/issues"
+  },
+  "homepage": "https://github.com/mui/pigment-css/tree/master/README.md",
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/mui-org"
+  },
+  "scripts": {
+    "clean": "rimraf build types processors utils",
+    "watch": "tsup --watch --clean false",
+    "copy-license": "node ../../scripts/pigment-license.mjs",
+    "build": "tsup",
+    "test": "cd ../../ && cross-env NODE_ENV=test BABEL_ENV=coverage nyc --reporter=text mocha 'packages/pigment-css-theme/**/*.test.{js,ts,tsx}'",
+    "test:update": "cd ../../ && cross-env NODE_ENV=test UPDATE_FIXTURES=true mocha 'packages/pigment-css-theme/**/*.test.{js,ts,tsx}'",
+    "test:ci": "cd ../../ && cross-env NODE_ENV=test BABEL_ENV=coverage nyc --reporter=lcov --report-dir=./coverage/pigment-css-theme mocha 'packages/pigment-css-theme/**/*.test.{js,ts,tsx}'",
+    "typescript": "tsc --noEmit -p ."
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/chai": "^4.3.14",
+    "chai": "^4.4.1"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "build",
+    "src",
+    "package.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": {
+        "types": "./build/index.d.mts",
+        "default": "./build/index.mjs"
+      },
+      "require": "./build/index.js",
+      "default": "./theme/index.js"
+    },
+    "./package.json": "./package.json",
+    "./styles.css": {
+      "require": "./build/index.js",
+      "default": "./styles.css"
+    },
+    "./exports/*": {
+      "default": "./exports/*.js"
+    }
+  },
+  "nx": {
+    "targets": {
+      "test": {
+        "cache": false,
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "test:update": {
+        "cache": false,
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "test:ci": {
+        "cache": false,
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "build": {
+        "outputs": [
+          "{projectRoot}/build"
+        ]
+      }
+    }
+  }
+}

packages/pigment-css-theme/src/index.ts

@@ -0,0 +1 @@
+export * from './theme';

packages/pigment-css-theme/src/theme.ts

@@ -0,0 +1,37 @@
+export interface Theme {}
+
+type Join<K extends string | number, P extends string> = K extends string | number
+  ? P extends ''
+    ? `${K}`
+    : `${P}.${K}`
+  : never;
+
+type PathsToLeaves<T extends object, P extends string = ''> = {
+  [K in keyof T]: T[K] extends object
+    ? PathsToLeaves<T[K], Join<K & string, P>>
+    : Join<K & string, P>;
+}[keyof T];
+
+export type ThemeKey = `$${PathsToLeaves<Theme>}`;
+
+/**
+ * It just returns what it receives at this point. Actual transformation happens during the build time
+ * separately.
+ * It is there to strictly type first argument as per the overridden `Theme`.
+ *
+ * @example Usage in application
+ *
+ * ```js
+ * import { t } from '@pigment-css/theme';
+ * import { css } from '@pigment-css/core';
+ *
+ * // override Theme type as per docs
+ *
+ * const cls1 = css({
+ *   border: `1px solid t('$palette.main')`,
+ * })
+ * ```
+ */
+export function t(themeKey: ThemeKey): ThemeKey {
+  return themeKey;
+}

packages/pigment-css-theme/tests/theme.spec.ts

@@ -0,0 +1,14 @@
+import { t } from '../src';
+
+declare module '../src' {
+  interface Theme {
+    palette: {
+      main: string;
+    };
+  }
+}
+
+t('$palette.main');
+
+// @ts-expect-error
+t('$palette.secondary');

packages/pigment-css-theme/tests/theme.test.ts

@@ -0,0 +1,9 @@
+import { expect } from 'chai';
+import { t } from '../src/theme';
+
+describe('t', () => {
+  it('should return the passed value', () => {
+    // @ts-ignore Ignoring for tests
+    expect(t('$palette.primary.main')).to.equal('$palette.primary.main');
+  });
+});

packages/pigment-css-theme/tsconfig.build.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": false
+  },
+  "exclude": ["./tsup.config.ts", "src/**/*.d.ts"]
+}

packages/pigment-css-theme/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2015",
+    "allowJs": true,
+    "lib": ["ES2017", "ES2021.String", "DOM"],
+    "composite": true,
+    "noEmit": false,
+    "resolveJsonModule": true,
+    "types": ["node", "mocha"],
+    "jsx": "react-jsx"
+  },
+  "include": [
+    "src/**/*.tsx",
+    "src/**/*.js",
+    "src/**/*.ts",
+    "tests/**/*.spec.ts",
+    "tests/**/*.spec.tsx"
+  ],
+  "exclude": ["./tsup.config.ts"]
+}

packages/pigment-css-theme/tsup.config.ts

@@ -0,0 +1,16 @@
+import { Options, defineConfig } from 'tsup';
+import config from '../../tsup.config';
+
+const baseConfig: Options = {
+  ...(config as Options),
+  tsconfig: './tsconfig.build.json',
+};
+
+const BASE_FILES = ['index.ts'];
+
+export default defineConfig([
+  {
+    ...baseConfig,
+    entry: BASE_FILES.map((file) => `./src/${file}`),
+  },
+]);