Skip to content

Commit b002ad3

Browse files
mitkinsmitkins
authored
Merge pull request #416 from petalframework/tailwind4_docs
Tailwind instructions for upgrade guide and README
2 parents dea2016 + 360275a commit b002ad3

File tree

3 files changed

+256
-21
lines changed

3 files changed

+256
-21
lines changed

‎README.md

+16-20
Original file line numberDiff line numberDiff line change
@@ -134,41 +134,37 @@ alias PetalComponents.Button
134134
```
135135

136136
**Q: Does this increase my CSS filesize?**
137-
A: Tailwind will scan any folders you specify and hoover up CSS classes from files to include in your final CSS file. You specify the folders in `tailwind.config.js`. By default, we instruct you to just scan the whole Petal Components library:
137+
A: Tailwind will scan any folders you specify and hoover up CSS classes from files to include in your final CSS file. You specify the folders in `assets/app.css`. By default, we instruct you to just scan the whole Petal Components library:
138138

139-
```js
140-
const colors = require("tailwindcss/colors");
141-
142-
module.exports = {
143-
purge: [
144-
"../lib/*_web/**/*.*ex",
145-
"./js/**/*.js",
139+
```css
140+
@import "tailwindcss";
146141

147-
// We need to include the Petal dependency so the classes get picked up by JIT.
148-
"../deps/petal_components/**/*.*ex"
149-
],
142+
@source "../deps/petal_components/**/*.*ex";
143+
@import "../deps/petal_components/assets/default.css";
150144

151-
... rest of file omitted
145+
... rest of file omitted
152146
```
153147

154148
You might be worried that if you don't use every component you'll have unused CSS classes. But we believe it's so small it won't matter. Our petal.build site's CSS file totals just 25kb.
155149

156150
If you really want to you can instruct Tailwind to just scan the components you use:
157151

158-
```
159-
"../deps/petal_components/lib/button.ex",
160-
"../deps/petal_components/lib/alert.ex",
152+
```css
153+
@source "../deps/petal_components/lib/button.ex",
154+
@source "../deps/petal_components/lib/alert.ex",
161155
```
162156

163157
**Q: Can I customize the components?**
164158
A: Yes! You can customize the components by overriding the CSS classes. For example, if you want to change the color of the button you can do this:
165159

166160
```css
167-
.pc-button {
168-
@apply inline-flex items-center justify-center font-semibold tracking-wider uppercase transition duration-150 ease-in-out border-2 rounded-none focus:outline-hidden;
169-
}
170-
.pc-button--primary {
171-
@apply text-black border-black bg-primary-400 hover:bg-primary-700 focus:bg-primary-700 active:bg-primary-800 focus:shadow-primary-500/50;
161+
@layer components {
162+
.pc-button {
163+
@apply inline-flex items-center justify-center font-semibold tracking-wider uppercase transition duration-150 ease-in-out border-2 rounded-none focus:outline-hidden;
164+
}
165+
.pc-button--primary {
166+
@apply text-black border-black bg-primary-400 hover:bg-primary-700 focus:bg-primary-700 active:bg-primary-800 focus:shadow-primary-500/50;
167+
}
172168
}
173169
```
174170

‎UPGRADE_GUIDE.md

+239
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,244 @@
11
# Upgrade Guide
22

3+
## v2.8.4 to v2.9.0
4+
5+
Petal Components has been upgraded to Tailwind 4. Some utilities have been removed or renamed. See the [Tailwind upgrade guide](https://tailwindcss.com/docs/upgrade-guide) for more information.
6+
7+
To upgrade to Tailwind 4 in your project, make sure you update `mix.exs`:
8+
9+
```diff
10+
- {:tailwind, "~> 0.2", runtime: Mix.env() == :dev}
11+
+ {:tailwind, "~> 0.3", runtime: Mix.env() == :dev}
12+
```
13+
14+
And `config.exs` (note that the paths have changed and that you need 4.0.9 or above):
15+
16+
```diff
17+
config :tailwind,
18+
- version: "3.3.3",
19+
+ version: "4.0.9",
20+
default: [
21+
args: ~w(
22+
- --config=tailwind.config.js
23+
- --input=css/app.css
24+
- --output=../priv/static/assets/app.css
25+
+ --input=assets/css/app.css
26+
+ --output=priv/static/assets/app.css
27+
),
28+
- cd: Path.expand("../assets", __DIR__)
29+
+ cd: Path.expand("..", __DIR__)
30+
]
31+
```
32+
33+
Don't forget to run:
34+
35+
```bash
36+
mix tailwind.install
37+
```
38+
39+
`tailwind.config.js` is now considered legacy and is no longer automatically loaded. However, it is still supported and you can manually load it by adding the following to your `app.css`:
40+
41+
```css
42+
@config "../tailwind.config.js";
43+
```
44+
45+
Now you should be able to follow the [Tailwind upgrade guide](https://tailwindcss.com/docs/upgrade-guide) to update your project.
46+
47+
### Petal Components CSS configuration
48+
49+
Here are some tips on how to integrate Petal Components if you are no longer using the `tailwind.config.js` file.
50+
51+
To reference Petal Components CSS and include it as a source for Tailwind utility classes, use the `@source` and `@import` directives:
52+
53+
```css
54+
@import "tailwindcss";
55+
56+
@source "../../deps/petal_components/**/*.*ex";
57+
@import "../../deps/petal_components/assets/default.css";
58+
```
59+
60+
The CSS file equivalent of `darkMode: 'class'` is:
61+
62+
```css
63+
@custom-variant dark (&:where(.dark, .dark *));
64+
```
65+
66+
In Tailwind 4 buttons now use `cursor: default` instead of `cursor: pointer`. If you would like the old behaviour:
67+
68+
```css
69+
@layer base {
70+
/* Use the pointer for buttons */
71+
button:not(:disabled),
72+
[role="button"]:not(:disabled) {
73+
cursor: pointer;
74+
}
75+
}
76+
```
77+
78+
To configure Petal Component colours add an `@import`:
79+
80+
```css
81+
@import "./colors.css";
82+
```
83+
84+
Then create the `colors.css` file:
85+
86+
```css
87+
@theme inline {
88+
--color-primary-50: var(--color-blue-50);
89+
--color-primary-100: var(--color-blue-100);
90+
--color-primary-200: var(--color-blue-200);
91+
--color-primary-300: var(--color-blue-300);
92+
--color-primary-400: var(--color-blue-400);
93+
--color-primary-500: var(--color-blue-500);
94+
--color-primary-600: var(--color-blue-600);
95+
--color-primary-700: var(--color-blue-700);
96+
--color-primary-800: var(--color-blue-800);
97+
--color-primary-900: var(--color-blue-900);
98+
--color-primary-950: var(--color-blue-950);
99+
100+
--color-secondary-50: var(--color-pink-50);
101+
--color-secondary-100: var(--color-pink-100);
102+
--color-secondary-200: var(--color-pink-200);
103+
--color-secondary-300: var(--color-pink-300);
104+
--color-secondary-400: var(--color-pink-400);
105+
--color-secondary-500: var(--color-pink-500);
106+
--color-secondary-600: var(--color-pink-600);
107+
--color-secondary-700: var(--color-pink-700);
108+
--color-secondary-800: var(--color-pink-800);
109+
--color-secondary-900: var(--color-pink-900);
110+
--color-secondary-950: var(--color-pink-950);
111+
112+
--color-success-50: var(--color-green-50);
113+
--color-success-100: var(--color-green-100);
114+
--color-success-200: var(--color-green-200);
115+
--color-success-300: var(--color-green-300);
116+
--color-success-400: var(--color-green-400);
117+
--color-success-500: var(--color-green-500);
118+
--color-success-600: var(--color-green-600);
119+
--color-success-700: var(--color-green-700);
120+
--color-success-800: var(--color-green-800);
121+
--color-success-900: var(--color-green-900);
122+
--color-success-950: var(--color-green-950);
123+
124+
--color-danger-50: var(--color-red-50);
125+
--color-danger-100: var(--color-red-100);
126+
--color-danger-200: var(--color-red-200);
127+
--color-danger-300: var(--color-red-300);
128+
--color-danger-400: var(--color-red-400);
129+
--color-danger-500: var(--color-red-500);
130+
--color-danger-600: var(--color-red-600);
131+
--color-danger-700: var(--color-red-700);
132+
--color-danger-800: var(--color-red-800);
133+
--color-danger-900: var(--color-red-900);
134+
--color-danger-950: var(--color-red-950);
135+
136+
--color-warning-50: var(--color-yellow-50);
137+
--color-warning-100: var(--color-yellow-100);
138+
--color-warning-200: var(--color-yellow-200);
139+
--color-warning-300: var(--color-yellow-300);
140+
--color-warning-400: var(--color-yellow-400);
141+
--color-warning-500: var(--color-yellow-500);
142+
--color-warning-600: var(--color-yellow-600);
143+
--color-warning-700: var(--color-yellow-700);
144+
--color-warning-800: var(--color-yellow-800);
145+
--color-warning-900: var(--color-yellow-900);
146+
--color-warning-950: var(--color-yellow-950);
147+
148+
--color-info-50: var(--color-sky-50);
149+
--color-info-100: var(--color-sky-100);
150+
--color-info-200: var(--color-sky-200);
151+
--color-info-300: var(--color-sky-300);
152+
--color-info-400: var(--color-sky-400);
153+
--color-info-500: var(--color-sky-500);
154+
--color-info-600: var(--color-sky-600);
155+
--color-info-700: var(--color-sky-700);
156+
--color-info-800: var(--color-sky-800);
157+
--color-info-900: var(--color-sky-900);
158+
--color-info-950: var(--color-sky-950);
159+
160+
--color-gray-50: var(--color-slate-50);
161+
--color-gray-100: var(--color-slate-100);
162+
--color-gray-200: var(--color-slate-200);
163+
--color-gray-300: var(--color-slate-300);
164+
--color-gray-400: var(--color-slate-400);
165+
--color-gray-500: var(--color-slate-500);
166+
--color-gray-600: var(--color-slate-600);
167+
--color-gray-700: var(--color-slate-700);
168+
--color-gray-800: var(--color-slate-800);
169+
--color-gray-900: var(--color-slate-900);
170+
--color-gray-950: var(--color-slate-950);
171+
}
172+
```
173+
174+
To add the "typography" and "form" plug-ins:
175+
176+
```css
177+
@plugin "@tailwindcss/typography";
178+
@plugin "@tailwindcss/forms";
179+
```
180+
181+
To re-create the heroicons JavaScript:
182+
183+
```css
184+
@plugin "./tailwind_heroicons.js";
185+
```
186+
187+
Then create the `tailwind_heroicons.js` file:
188+
189+
```JavaScript
190+
const plugin = require("tailwindcss/plugin");
191+
const fs = require("fs");
192+
const path = require("path");
193+
194+
// Embeds Heroicons (https://heroicons.com) into your app.css bundle
195+
// See your `CoreComponents.icon/1` for more information.
196+
module.exports = plugin(function ({ matchComponents, theme }) {
197+
let iconsDir = path.join(__dirname, "../../deps/heroicons/optimized");
198+
let values = {};
199+
let icons = [
200+
["", "/24/outline"],
201+
["-solid", "/24/solid"],
202+
["-mini", "/20/solid"],
203+
["-micro", "/16/solid"],
204+
];
205+
icons.forEach(([suffix, dir]) => {
206+
fs.readdirSync(path.join(iconsDir, dir)).forEach((file) => {
207+
let name = path.basename(file, ".svg") + suffix;
208+
values[name] = { name, fullPath: path.join(iconsDir, dir, file) };
209+
});
210+
});
211+
matchComponents(
212+
{
213+
hero: ({ name, fullPath }) => {
214+
let content = fs
215+
.readFileSync(fullPath)
216+
.toString()
217+
.replace(/\r?\n|\r/g, "");
218+
let size = theme("spacing.6");
219+
if (name.endsWith("-mini")) {
220+
size = theme("spacing.5");
221+
} else if (name.endsWith("-micro")) {
222+
size = theme("spacing.4");
223+
}
224+
return {
225+
[`--hero-${name}`]: `url('data:image/svg+xml;utf8,${content}')`,
226+
"-webkit-mask": `var(--hero-${name})`,
227+
mask: `var(--hero-${name})`,
228+
"mask-repeat": "no-repeat",
229+
"background-color": "currentColor",
230+
"vertical-align": "middle",
231+
display: "inline-block",
232+
width: size,
233+
height: "1lh",
234+
};
235+
},
236+
},
237+
{ values },
238+
);
239+
});
240+
```
241+
3242
## v1.4 to v1.5
4243

5244
v1.5 requires Tailwind v3.3.3. Update the version in `config.exs`:

‎assets/default.css

+1-1
Original file line numberDiff line numberDiff line change
@@ -2543,7 +2543,7 @@
25432543
@apply border-danger-500! rounded-md! focus:border-danger-500! text-danger-900! placeholder-danger-700! bg-danger-50! file:border-none! dark:border-none! dark:bg-gray-950! dark:text-danger-400;
25442544
}
25452545

2546-
/* If in tailwind.config.json, darkMode: 'class', use this: */
2546+
/* If in tailwind config, darkMode: 'class', use this: */
25472547
.dark ::-webkit-calendar-picker-indicator {
25482548
filter: invert(1);
25492549
}

0 commit comments

Comments
 (0)