@spark-ui/theme-utils 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.1.1](https://github.com/adevinta/spark/compare/@spark-ui/theme-utils@1.1.0...@spark-ui/theme-utils@1.1.1) (2023-02-13)
+
+**Note:** Version bump only for package @spark-ui/theme-utils
+
 # [1.1.0](https://github.com/adevinta/spark/compare/@spark-ui/theme-utils@0.0.1...@spark-ui/theme-utils@1.1.0) (2023-02-10)
 
 ### Features

package/createCSSTokensFile.mts

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, mkdirSync } from 'fs'
 import hexRgb from 'hex-rgb'
 import parentModule from 'parent-module'
 import { join } from 'path'
+import type { RequireAtLeastOne } from 'type-fest'
 
 import type { Theme } from './types.mjs'
 import {
@@ -67,7 +68,32 @@ const getStringifiedThemes = (themeRecord: Record<string, Theme>) =>
       : `.${className}{${toStringifiedTheme(rest)}}`
   })
 
-export function createCSSTokensFile(path: string, themeRecord: Record<string, Theme>) {
+/**
+ * Creates a CSS file containing theme tokens represented as CSS custom properties
+ *
+ * @param {string} path - The file path where the CSS file will be created.
+ * @param {Record<string, Theme>} themeRecord - A record (with a required key of "default") of themes that will be included in the CSS Tokens file.
+ *
+ * @returns {void}
+ *
+ * @example
+ *
+ * const defaultTheme: Theme = { ... }
+ * const darkTheme: Theme = { ... }
+ * const otherTheme: Theme = { ... }
+ *
+ * const themes = {
+ *   default: defaultTheme,
+ *   dark: darkTheme
+ *   other: otherTheme
+ * }
+ *
+ * createCSSTokensFile('somePath.css', themes)
+ */
+export function createCSSTokensFile(
+  path: string,
+  themeRecord: RequireAtLeastOne<Record<string, Theme>, 'default'>
+) {
   const { filepath, rootPath } = buildFilePath(join(parentModule() || '', path))
 
   const folders = filepath.split('/').slice(0, -1)

package/{createTailwindConfigFile.mts → createTailwindThemeConfigFile.mts}

@@ -47,7 +47,18 @@ function toTailwindConfig(theme: Theme): TailwindConfig {
   return toKebabCaseKeys(themeCpy)
 }
 
-export function createTailwindConfigFile(path: string) {
+/**
+ * Creates a Tailwind config file that links the [theme options](https://tailwindcss.com/docs/theme#configuration-reference) provided by Tailwind with the CSS custom property values generated using the "createCSSTokensFile" function
+ *
+ * @param {string} path - The file path where the Tailwind config file will be created.
+ *
+ * @returns {void}
+ *
+ * @example
+ *
+ * createTailwindThemeConfigFile('tailwind.theme.js')
+ */
+export function createTailwindThemeConfigFile(path: string) {
   const { filepath, rootPath } = buildFilePath(join(parentModule() || '', path))
 
   const folders = filepath.split('/').slice(0, -1)

package/createTheme.mts

@@ -4,6 +4,18 @@ import { PartialDeep } from 'type-fest'
 import { defaultTheme } from './defaultTheme.mjs'
 import type { Theme } from './types.mjs'
 
+/**
+ * Create a custom theme by merging the default theme with a partial custom theme passed as an argument.
+ *
+ * @param {PartialDeep<Theme>} theme - A partial theme object of type PartialDeep<Theme> which holds the theme values that need to be customized or overridden
+ *
+ * @returns {Theme}
+ *
+ * @example
+ *
+ * const alternativeTheme: PartialDeep<Theme> = { ... }
+ * const newTheme = createTheme(alternativeTheme)
+ */
 export function createTheme(theme: PartialDeep<Theme> = {}): Theme {
   return deepMerge<Theme, PartialDeep<Theme>>(defaultTheme, theme)
 }

package/index.mts

@@ -1,5 +1,5 @@
 export { createTheme } from './createTheme.mjs'
-export { createTailwindConfigFile } from './createTailwindConfigFile.mjs'
+export { createTailwindThemeConfigFile } from './createTailwindThemeConfigFile.mjs'
 export { createCSSTokensFile } from './createCSSTokensFile.mjs'
 export { defaultTheme } from './defaultTheme.mjs'
 

package/index.stories.mdx

@@ -0,0 +1,219 @@
+import { Meta } from '@storybook/blocks'
+import { StoryHeading } from '../../../documentation/helpers/StoryHeading/'
+
+<Meta title="utils/Theme" />
+
+# Theme
+
+- [Theme](#theme-interface)
+- [defaultTheme](#default-theme)
+- [createTheme](#createtheme)
+- [createCSSTokensFile](#createcsstokensfile)
+- [createTailwindThemeConfigFile](#createtailwindthemeconfigfile)
+- [Practical example](#practical-example)
+
+> **Note**
+>
+> Spark Design System is built using the **Tailwind CSS** framework
+
+---
+
+The **`packages/utils/theme`** exposes the following:
+
+```tsx
+import {
+  Theme,
+  defaultTheme,
+  createTheme,
+  createCSSTokensFile,
+  createTailwindThemeConfigFile,
+} from '@spark-ui/theme-utils'
+```
+
+<StoryHeading label="theme interface" as="h4" />
+
+- `Theme`, the TypeScript interface for our theme
+
+<StoryHeading label="default theme" as="h4" />
+
+- `defaultTheme`, our default theme, represented as an `Object`
+
+<StoryHeading label="createTheme" as="h4" />
+
+- A function, that enables one to create a new theme by modifying specific values from the default theme without having to define a completely new theme from scratch.
+
+This function expects one argument:
+
+- A partial theme object which holds the theme values that need to be customized or overridden
+
+**Usage:**
+
+```tsx
+const someTheme: PartialDeep<Theme> = { ... }
+const newTheme = createTheme(someTheme) // Theme
+
+```
+
+<StoryHeading label="createCSSTokensFile" as="h4" />
+
+- A function, that will generate a `css` file containing all of the theme tokens, represented as CSS custom properties.
+
+This function expects two arguments:
+
+- The file path where the `css` file will be created
+- A `Record` (with a required key of "default") of themes that will be included in the `css` file
+
+**Usage:**
+
+- Let's create a file (named `createTokens.ts` in our example) that will call this function
+
+```tsx
+// createTokens.ts
+const defaultTheme: Theme = { ... }
+const darkTheme: Theme = { ... }
+const someOtherTheme: Theme = { ... }
+
+const themes = {
+  default: defaultTheme,
+  dark: darkTheme,
+  other: someOtherTheme
+}
+
+createCSSTokensFile('./somePath.css', themes)
+
+```
+
+- Executing `createTokens.ts` will generate a `somePath.css` file with the following structure:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    /* :root, derived from the "default" key ↔️ themes.default */
+    --some-token: someValue;
+    --some-other-token: otherValue;
+    ...;
+  }
+
+  .dark {
+    /* .dark, derived from the "dark" key ↔️ themes.dark */
+    --some-token: foo;
+    --some-other-token: bar;
+    ...;
+  }
+
+  .other {
+    /* .other, derived from the "other" key ↔️ themes.other */
+    --some-token: lorem;
+    --some-other-token: ipsum;
+    ...;
+  }
+}
+```
+
+<StoryHeading label="createTailwindThemeConfigFile" as="h4" />
+
+A function that will generate a config file that links the [theme options](https://tailwindcss.com/docs/theme#configuration-reference) provided by Tailwind with the CSS custom property values generated using the `createCSSTokensFile` function.
+
+This function expects one argument:
+
+- The file path where the `css` file will be created
+
+**Usage:**
+
+- Let's create a file (named `overrideTailwindConfig.ts` in our example) that will call this function
+
+```tsx
+// overrideTailwindConfig.ts
+createTailwindThemeConfigFile('./tailwind.theme.js)
+
+```
+
+- Executing `overrideTailwindConfig.ts` will generate a `tailwind.theme.js` file with the following structure:
+
+```js
+// tailwind.theme.js
+module.exports = {
+  ...,
+  screens: {
+    sm: 'var(--some-value)',
+    md: 'var(--some-other-value)',
+  },
+  spacing: {
+    sm: 'var(--some-foo)',
+    md: 'var(--some-bar)'
+  }
+  ...
+}
+```
+
+- Then, inside your Tailwind config file, include a reference to the file that will be generated upon executing `overrideTailwindConfig.ts`
+
+```js
+// tailwind.config.js
+const themeConf = require('./tailwind.theme.js') // ⬅️ generated by executing `overrideTailwindConfig.ts`
+
+module.exports = {
+  theme: {
+    ...themeConf, // ⬅️ replacing default Tailwind theme with our own
+  },
+  content: ['...'],
+}
+```
+
+<StoryHeading label="Practical Example" as="h3" />
+
+- For a more detailed understanding of how to employ these two functions together (**createCSSTokensFile** & **createTailwindThemeConfigFile**), here's a practical example of integrating them into your project:
+
+1️⃣. Create a file (named `createThemeConfig.ts` in this example) that will call both of these functions
+
+```tsx
+// createThemeConfig.ts
+import { createCSSTokensFile, createTailwindThemeConfigFile } from '@spark-ui/theme-utils'
+import { themes } from '/myThemes'
+
+createTailwindThemeConfigFile('./tailwind.theme.js') // ⬅️ will generate the Tailwind theme config file
+createCSSTokensFile('./tailwind.css', themes) // ⬅️ will generate the CSS tokens file
+```
+
+2️⃣ a. Inside the Tailwind config file, include a reference to the file that will be generated upon executing the file from step 1
+
+```js
+// tailwind.config.js
+const themeConf = require('./tailwind.theme.js') // ⬅️ generated by executing `createThemeConfig.ts`
+
+module.exports = {
+  theme: {
+    ...themeConf, // ⬅️ replacing default Tailwind theme with our own
+  },
+  content: ['...'],
+}
+```
+
+2️⃣ b. Inside a file in your application where you import your global styles, include a reference to the file that will be generated upon executing the file from step 1
+
+If you are using **Next.js**, that would be `_app.tsx`
+
+```tsx
+// some file in your application where you can import global styles
+
+import '../tailwind.css' // ⬅️ generated by executing `createThemeConfig.ts`
+```
+
+3️⃣. Inside your `package.json`, add a script that will execute the file from step 1, and make sure to run that script before you start your application
+
+```json
+// package.json
+{
+  ...
+  "scripts": {
+    ...,
+    "start": "npm run create:theme-config && start your-app",
+    "create:theme-config": "ts-node-esm createThemeConfig.ts", // ⬅️ executing `createThemeConfig.ts`
+    ...
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spark-ui/theme-utils",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Theme configuration",
   "publishConfig": {
     "access": "public"
@@ -17,5 +17,5 @@
     "parent-module": "3.0.0",
     "type-fest": "3.5.6"
   },
-  "gitHead": "807a2fbdf384a277d4110cff7dbb549bb9ab4563"
+  "gitHead": "88ef74d7ffbf238395c021350fb6e54fe50bba43"
 }