@spark-ui/tailwind-plugins 2.1.0 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/animations/index.stories.mdx +3 -3
  3. package/index.stories.mdx +1 -0
  4. package/package.json +4 -4
  5. package/sizings/index.stories.mdx +4 -4
  6. package/spark-theme/index.stories.mdx +98 -0
package/CHANGELOG.md CHANGED
@@ -3,6 +3,16 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
5
 
6
+ ## [2.1.2](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.1.1...@spark-ui/tailwind-plugins@2.1.2) (2023-03-20)
7
+
8
+ ### Bug Fixes
9
+
10
+ - **tailwind-plugins:** fix invalid tailwind package version ([b79c5a6](https://github.com/adevinta/spark/commit/b79c5a6e92c955246a57728dfb466d0d23d82e3d))
11
+
12
+ ## [2.1.1](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.1.0...@spark-ui/tailwind-plugins@2.1.1) (2023-03-19)
13
+
14
+ **Note:** Version bump only for package @spark-ui/tailwind-plugins
15
+
6
16
  # [2.1.0](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.0.0...@spark-ui/tailwind-plugins@2.1.0) (2023-03-17)
7
17
 
8
18
  ### Bug Fixes
package/animations/index.stories.mdx CHANGED
@@ -6,7 +6,7 @@ import { Alert } from '@docs/helpers/Alert'
6
6
 
7
7
  # Tailwind animation plugin
8
8
 
9
- ## Installation
9
+ <StoryHeading label="Installation" as="h2" />
10
10
 
11
11
  To use our Tailwind animation plugin, simply install the `@spark-ui/tailwind-plugins` package and add the animation plugin to your `tailwind.config.js` file
12
12
 
@@ -26,7 +26,7 @@ module.exports = {
26
26
 
27
27
  ```
28
28
 
29
- ## Usage
29
+ <StoryHeading label="Usage" as="h2" />
30
30
 
31
31
  This plugin provides the following **animation-related** declaration properties that are missing by default in **Tailwind**:
32
32
 
@@ -47,7 +47,7 @@ This plugin also includes four animation keyframes:
47
47
  - **animate-slide-bottom**: `animate-slide-bottom`
48
48
  - **animate-slide-left**: `animate-slide-left`
49
49
 
50
- <StoryHeading label="Configuration" as="h3" />
50
+ <StoryHeading label="Configuration" as="h2" />
51
51
 
52
52
  You can customize the **CSS class prefix** using the `prefixVariant` option.
53
53
 
package/index.stories.mdx CHANGED
@@ -8,5 +8,6 @@ import { Alert } from '@docs/helpers/Alert'
8
8
 
9
9
  Below is a list of our Tailwind plugins:
10
10
 
11
+ - [spark theme](?path=/docs/utils-tailwind-plugins-spark-theme--docs)
11
12
  - [animations](?path=/docs/utils-tailwind-plugins-animations--docs)
12
13
  - [sizings](?path=/docs/utils-tailwind-plugins-sizings--docs)
package/package.json CHANGED
@@ -1,21 +1,21 @@
1
1
  {
2
2
  "name": "@spark-ui/tailwind-plugins",
3
- "version": "2.1.0",
3
+ "version": "2.1.2",
4
4
  "description": "Spark Tailwind plugins",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
8
8
  "main": "index.js",
9
9
  "dependencies": {
10
- "@spark-ui/theme-utils": "^2.9.0"
10
+ "@spark-ui/theme-utils": "^2.9.1"
11
11
  },
12
12
  "peerDependencies": {
13
- "tailwindcss": "4.0.0"
13
+ "tailwindcss": "^3.2.7"
14
14
  },
15
15
  "repository": {
16
16
  "type": "git",
17
17
  "url": "git@github.com:adevinta/spark.git",
18
18
  "directory": "packages/utils/tailwind-plugins"
19
19
  },
20
- "gitHead": "b02d8de6793827cb8783dcf1029c7345c7629974"
20
+ "gitHead": "6efd4ae4a8f830e228ba06081f8fd2a242e0f86a"
21
21
  }
package/sizings/index.stories.mdx CHANGED
@@ -6,7 +6,7 @@ import { Alert } from '@docs/helpers/Alert'
6
6
 
7
7
  # Tailwind sizing plugin
8
8
 
9
- ## Installation
9
+ <StoryHeading label="Installation" as="h2" />
10
10
 
11
11
  To use our Tailwind sizing plugin, simply install the `@spark-ui/tailwind-plugins` package and add the animation plugin to your `tailwind.config.js` file
12
12
 
@@ -27,7 +27,7 @@ module.exports = {
27
27
 
28
28
  ```
29
29
 
30
- ## Usage
30
+ <StoryHeading label="Usage" as="h2" />
31
31
 
32
32
  This plugin predefines a sizing range with the following pixel values:
33
33
 
@@ -43,7 +43,7 @@ These values are converted into rem units based on the specified **HTML font siz
43
43
 
44
44
  The plugin generates CSS variables for each size value, which can then be used for `width`, `height`, `max-width`, `max-height`, and `translate` properties.
45
45
 
46
- <StoryHeading label="Example" as="h3" />
46
+ <StoryHeading label="Example" as="h2" />
47
47
 
48
48
  To set the `width` of an element using the sizing plugin, use the `w-sz-{size}` class, where`{size}` is the desired pixel value from the predefined range:
49
49
 
@@ -53,7 +53,7 @@ To set the `width` of an element using the sizing plugin, use the `w-sz-{size}`
53
53
 
54
54
  This will set the width of the element to **10px** (0.625rem, if `htmlFontSize` is 16) using the custom sizing scale provided by the plugin.
55
55
 
56
- <StoryHeading label="Configuration" as="h3" />
56
+ <StoryHeading label="Configuration" as="h2" />
57
57
 
58
58
  You can customize the **base html font size** using the `htmlFontSize` option.
59
59
 
package/spark-theme/index.stories.mdx ADDED
@@ -0,0 +1,98 @@
1
+ import { Meta } from '@storybook/blocks'
2
+ import { StoryHeading } from '@docs/helpers/StoryHeading'
3
+ import { Alert } from '@docs/helpers/Alert'
4
+
5
+ <Meta title="utils/Tailwind plugins/spark theme" />
6
+
7
+ # Tailwind spark theme plugin
8
+
9
+ ## Installation
10
+
11
+ To use our Tailwind spark theme plugin, simply install the `@spark-ui/tailwind-plugins` package and add the spark theme plugin to your `tailwind.config.js` file
12
+
13
+ ```bash
14
+ $ npm i @spark-ui/tailwind-plugins
15
+ ```
16
+
17
+ ```js
18
+ // tailwind.config.js
19
+
20
+ const sparkPlugins = require('@spark-ui/tailwind-plugins')
21
+
22
+ module.exports = {
23
+ ...,
24
+ plugins: [sparkPlugins.sparkTheme({
25
+ htmlFontSize: 16 // The base font size for your application (default: 16),
26
+ themes: {
27
+ default: yourDefaultTheme,
28
+ dark: yourDarkTheme,
29
+ foo: someOtherTheme,
30
+ ...rest
31
+ } //
32
+ })],
33
+ }
34
+
35
+ ```
36
+
37
+ <StoryHeading label="Usage" as="h2" />
38
+
39
+ The plugin performs two main tasks:
40
+
41
+ - first, it converts every value within the objects inside the themes object into **CSS variables**, which is helpful for managing **multiple themes**.
42
+
43
+ - Second, it provides Tailwind with an internal mapping to retrieve these CSS variables This is necessary because, by default, Tailwind does not use CSS variables, but rather direct values.
44
+
45
+ Once the plugin is configured, all Spark custom classes become available for use.
46
+
47
+ ```tsx
48
+ <div className="bg-primary text-primary...">...</div>
49
+ ```
50
+
51
+ <StoryHeading label="Configuration" as="h2" />
52
+
53
+ This plugin can be customized by providing a configuration object with two fields, `themes` and `htmlFontSize`.
54
+
55
+ **themes**:
56
+
57
+ An object containing your themes. Each key in the object will be extracted to a `[data-theme]` attribute, and the values will be converted to CSS custom properties inside the `css` file generated by Tailwing. **Note that this object requires a key with a value of default**, which specifies the default theme for your project.
58
+
59
+ For example, if your `themes` object looks like this:
60
+
61
+ ```js
62
+
63
+ sparkPlugins.sparkTheme({
64
+ themes: {
65
+ default: yourDefaultTheme,
66
+ alternative: someAlternativeTheme,
67
+ },
68
+ }),
69
+ ```
70
+
71
+ Tailwind will generate the following CSS:
72
+
73
+ ```css
74
+ :root {
75
+ /* ...tokens from yourDefaultTheme */
76
+ }
77
+
78
+ [data-theme='alternative'] {
79
+ /* ...tokens from someAlternativeTheme */
80
+ }
81
+ ```
82
+
83
+ You can populate the `themes` object with as many themes as desired, with the only requirement being that they conform to our `Theme` interface. The Theme interface can be accessed through the [**@spark-ui/theme-utils**](?path=/docs/utils-theme--docs#theme) package.
84
+
85
+ **htmlFontSize (optional)**:
86
+
87
+ Spark uses a base font size of **16 pixels** as a standard value for calculating the sizes of all other font-related properties defined in the theme. For example, our `spacing.lg` value is defined as **1rem**, which is equal to 16 pixels (based on the default base font size of 16 pixels).
88
+
89
+ However, if your application uses a different base font size, such as **10 pixels** for example, this can cause issues with the sizing of elements in the application. To account for this, you can set the `htmlFontSize` to the appropriate value for your application's base font size. This will adjust the `rem` based values in Spark to be relative to the new base font size.
90
+
91
+ This will ensure that the `rem`-based values are accurately calculated according to your application's HTML font size.
92
+
93
+ <Alert>
94
+ To better understand what happens when you adjust `htmlFontSize`, it's useful to know that we use CSS custom properties to define the values of our design tokens, such as `spacing.lg`.
95
+
96
+ By default, the value for this token is expressed as `--spacing-lg: 1rem;`. However, when you define a `htmlFontSize` of 10, for example, this value will be updated to `--spacing-lg: 1.6rem;`
97
+
98
+ </Alert>