@gallopsystems/agent-skills 1.30.0 → 1.31.1
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.
- package/README.md +13 -1
- package/package.json +1 -1
- package/plugins/copier-template/skills/copier-template/applying-updates.md +2 -2
- package/plugins/frontend-design/skills/frontend-design/SKILL.md +10 -10
- package/plugins/gallop-ui/.claude-plugin/plugin.json +8 -0
- package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +108 -0
- package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +157 -0
- package/plugins/gallop-ui/skills/gallop-ui/changing-the-layer.md +102 -0
- package/plugins/gallop-ui/skills/gallop-ui/checking-other-apps.md +108 -0
- package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +92 -0
- package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +82 -0
- package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +101 -0
- package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +122 -0
- package/plugins/linear/skills/linear/SKILL.md +4 -4
- package/plugins/linear/skills/linear/examples/frontend-feature.md +1 -1
- package/plugins/linear/skills/linear/tech-stack.md +12 -14
- package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +3 -26
- package/plugins/nitro-testing/skills/nitro-testing/ci-setup.md +18 -23
- package/plugins/nitro-testing/skills/nitro-testing/frontend-testing.md +7 -33
- package/plugins/tailwind-v4/skills/tailwind-v4/SKILL.md +12 -14
- package/plugins/tailwind-v4/skills/tailwind-v4/gotchas.md +13 -18
- package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +2 -2
- package/plugins/vue-nuxt/skills/vue-nuxt/auto-imports.md +2 -2
- package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +1 -1
- package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +6 -6
- package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +3 -3
- package/plugins/volt-primevue/.claude-plugin/plugin.json +0 -8
- package/plugins/volt-primevue/skills/volt-primevue/SKILL.md +0 -170
- package/plugins/volt-primevue/skills/volt-primevue/config.md +0 -51
- package/plugins/volt-primevue/skills/volt-primevue/gotchas.md +0 -140
- package/plugins/volt-primevue/skills/volt-primevue/theming.md +0 -137
|
@@ -301,13 +301,7 @@ export default isNuxtEnv
|
|
|
301
301
|
}
|
|
302
302
|
```
|
|
303
303
|
|
|
304
|
-
|
|
305
|
-
```typescript
|
|
306
|
-
export default defineNuxtConfig({
|
|
307
|
-
modules: ["@primevue/nuxt-module"], // Include UI libraries
|
|
308
|
-
ssr: false, // Disable SSR for simpler component testing
|
|
309
|
-
});
|
|
310
|
-
```
|
|
304
|
+
The `nuxt` environment boots the app's real `nuxt.config.ts`, so the gallop-ui layer, `@nuxt/icon` and every auto-import are already there. No separate test config, no module list.
|
|
311
305
|
|
|
312
306
|
### File Organization
|
|
313
307
|
|
|
@@ -428,26 +422,9 @@ describe("Task Detail Page", () => {
|
|
|
428
422
|
});
|
|
429
423
|
```
|
|
430
424
|
|
|
431
|
-
###
|
|
425
|
+
### UI Layer Components
|
|
432
426
|
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
```typescript
|
|
436
|
-
import { mountSuspended } from "@nuxt/test-utils/runtime";
|
|
437
|
-
import ToastService from "primevue/toastservice";
|
|
438
|
-
import ConfirmationService from "primevue/confirmationservice";
|
|
439
|
-
|
|
440
|
-
const wrapper = await mountSuspended(MyComponent, {
|
|
441
|
-
global: {
|
|
442
|
-
plugins: [ToastService, ConfirmationService],
|
|
443
|
-
stubs: {
|
|
444
|
-
DataTable: true,
|
|
445
|
-
Column: true,
|
|
446
|
-
Dialog: true,
|
|
447
|
-
},
|
|
448
|
-
},
|
|
449
|
-
});
|
|
450
|
-
```
|
|
427
|
+
Mount the real gallop-ui components; don't stub them and don't register services. `useToast()` and `useConfirm()` provide their state on the app the first time they run in setup, so a component that calls them mounts as is. To assert a toast or a confirmation, mock the composable (`mockNuxtImport("useToast", ...)`) or render `<Toaster />` / `<ConfirmDialog />` next to the component. Component props and `pt`: see the **gallop-ui** skill.
|
|
451
428
|
|
|
452
429
|
### Testing Utility Functions
|
|
453
430
|
|
|
@@ -179,37 +179,32 @@ Configure branch protection rules in GitHub:
|
|
|
179
179
|
- `test`
|
|
180
180
|
- `typecheck`
|
|
181
181
|
|
|
182
|
-
##
|
|
182
|
+
## Running the CI tests locally
|
|
183
183
|
|
|
184
|
-
|
|
184
|
+
Run the same tests against a disposable **native** Postgres (Postgres.app's binaries), not Docker. Don't start Docker
|
|
185
|
+
(`docker run`, `docker compose`, `open -a Docker`, testcontainers, `act`) unless the user asks for it. Use your own
|
|
186
|
+
port, never 5432, 5433 or 3306, so a test run can never reach a real local database:
|
|
185
187
|
|
|
186
188
|
```bash
|
|
187
|
-
|
|
188
|
-
|
|
189
|
+
PG=/Applications/Postgres.app/Contents/Versions/latest/bin
|
|
190
|
+
$PG/initdb --locale=en_US.UTF-8 -U postgres -D /tmp/myapp-pg
|
|
191
|
+
$PG/pg_ctl -D /tmp/myapp-pg -l /tmp/myapp-pg.log -o "-p 54329 -c fsync=off -c synchronous_commit=off \
|
|
192
|
+
-c full_page_writes=off" start
|
|
193
|
+
$PG/createdb -h 127.0.0.1 -p 54329 -U postgres myapp-test
|
|
189
194
|
|
|
190
|
-
# Run
|
|
191
|
-
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
Or use Docker directly:
|
|
195
|
-
|
|
196
|
-
```bash
|
|
197
|
-
# Start test database
|
|
198
|
-
docker run -d --name test-db \
|
|
199
|
-
-e POSTGRES_USER=postgres \
|
|
200
|
-
-e POSTGRES_PASSWORD=postgres \
|
|
201
|
-
-e POSTGRES_DB=myapp-test \
|
|
202
|
-
-p 5432:5432 \
|
|
203
|
-
postgres:15
|
|
204
|
-
|
|
205
|
-
# Run tests
|
|
206
|
-
TEST_POSTGRESQL_CONNECTION_STRING=postgresql://postgres:postgres@localhost:5432/myapp-test \
|
|
207
|
-
yarn test
|
|
195
|
+
# Run tests (127.0.0.1, not localhost)
|
|
196
|
+
TEST_POSTGRESQL_CONNECTION_STRING=postgresql://postgres@127.0.0.1:54329/myapp-test yarn test
|
|
208
197
|
|
|
209
198
|
# Cleanup
|
|
210
|
-
|
|
199
|
+
$PG/pg_ctl -D /tmp/myapp-pg stop && rm -rf /tmp/myapp-pg
|
|
211
200
|
```
|
|
212
201
|
|
|
202
|
+
Before running, check that the test URL is set and doesn't point at 5432. An unset test URL can fall back to the
|
|
203
|
+
developer's real database.
|
|
204
|
+
|
|
205
|
+
If the user wants the workflow itself replayed, [act](https://github.com/nektos/act) runs it, but act needs Docker,
|
|
206
|
+
so only with their go-ahead.
|
|
207
|
+
|
|
213
208
|
## Secrets and Environment Variables
|
|
214
209
|
|
|
215
210
|
For production-like test databases or external services:
|
|
@@ -61,17 +61,7 @@ export default isNuxtEnv
|
|
|
61
61
|
|
|
62
62
|
## Nuxt Test Configuration
|
|
63
63
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
```typescript
|
|
67
|
-
// nuxt.config.test.ts
|
|
68
|
-
export default defineNuxtConfig({
|
|
69
|
-
modules: [
|
|
70
|
-
"@primevue/nuxt-module", // Include UI libraries your components need
|
|
71
|
-
],
|
|
72
|
-
ssr: false, // Simplifies component testing
|
|
73
|
-
});
|
|
74
|
-
```
|
|
64
|
+
No extra config file. With `VITEST_ENV=nuxt` (`environment: "nuxt"`) vitest boots the app's own `nuxt.config.ts`, so the gallop-ui layer and every auto-import are available, and `hookTimeout` should stay at 30s (each file boots Nuxt; 10s fails under pre-push load).
|
|
75
65
|
|
|
76
66
|
## Package.json Scripts
|
|
77
67
|
|
|
@@ -265,44 +255,28 @@ describe("Task Detail Page", () => {
|
|
|
265
255
|
});
|
|
266
256
|
```
|
|
267
257
|
|
|
268
|
-
### Testing with UI
|
|
258
|
+
### Testing with the UI Layer (gallop-ui)
|
|
269
259
|
|
|
270
|
-
|
|
260
|
+
Mount the real layer components. There is nothing to register or stub, and no service plugins:
|
|
271
261
|
|
|
272
262
|
```typescript
|
|
273
263
|
import { describe, it, expect } from "vitest";
|
|
274
264
|
import { mountSuspended } from "@nuxt/test-utils/runtime";
|
|
275
|
-
import ToastService from "primevue/toastservice";
|
|
276
|
-
import ConfirmationService from "primevue/confirmationservice";
|
|
277
265
|
import ProjectForm from "./ProjectForm.vue";
|
|
278
266
|
|
|
279
267
|
describe("ProjectForm", () => {
|
|
280
268
|
it("renders form fields", async () => {
|
|
281
269
|
const wrapper = await mountSuspended(ProjectForm, {
|
|
282
|
-
props: {
|
|
283
|
-
project: { id: 1, name: "", status: "draft" },
|
|
284
|
-
},
|
|
285
|
-
global: {
|
|
286
|
-
plugins: [ToastService, ConfirmationService],
|
|
287
|
-
stubs: {
|
|
288
|
-
// Stub complex PrimeVue components
|
|
289
|
-
DataTable: true,
|
|
290
|
-
Column: true,
|
|
291
|
-
Dialog: true,
|
|
292
|
-
Calendar: true,
|
|
293
|
-
Dropdown: true,
|
|
294
|
-
// Keep simple components
|
|
295
|
-
InputText: false,
|
|
296
|
-
Button: false,
|
|
297
|
-
},
|
|
298
|
-
},
|
|
270
|
+
props: { project: { id: 1, name: "", status: "draft" } },
|
|
299
271
|
});
|
|
300
272
|
|
|
301
|
-
expect(wrapper.exists()).toBe(true);
|
|
273
|
+
expect(wrapper.find("input").exists()).toBe(true);
|
|
302
274
|
});
|
|
303
275
|
});
|
|
304
276
|
```
|
|
305
277
|
|
|
278
|
+
`useToast()` and `useConfirm()` set up their own state when called in setup. To assert on them, mock the composable with `mockNuxtImport` or render `<Toaster />` / `<ConfirmDialog />` in the test. Prop and `pt` details: the **gallop-ui** skill.
|
|
279
|
+
|
|
306
280
|
### Testing User Interactions
|
|
307
281
|
|
|
308
282
|
```typescript
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: tailwind-v4
|
|
3
|
-
description: Work effectively with Tailwind CSS v4 (the CSS-first model) in a Nuxt/Vite +
|
|
3
|
+
description: Work effectively with Tailwind CSS v4 (the CSS-first model) in a Nuxt/Vite + gallop-ui stack. Use when editing Tailwind CSS, configuring @theme/@source/@import, setting up dark mode, defining design tokens, or debugging classes that silently don't apply. Covers the v3→v4 traps an LLM trained on v3 falls into.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Tailwind CSS v4
|
|
@@ -26,8 +26,7 @@ There is **no `tailwind.config.js`/`.ts`**. The whole config is in your CSS entr
|
|
|
26
26
|
|
|
27
27
|
```css
|
|
28
28
|
@import "tailwindcss"; /* NOT @tailwind base/components/utilities */
|
|
29
|
-
@
|
|
30
|
-
@source "../../../src/volt"; /* scan sources Tailwind won't auto-detect */
|
|
29
|
+
@source "../../../layers"; /* scan sources Tailwind won't auto-detect */
|
|
31
30
|
|
|
32
31
|
@theme {
|
|
33
32
|
--color-surface: #ffffff; /* defines the bg-surface / text-surface utilities */
|
|
@@ -46,7 +45,7 @@ export default defineNuxtConfig({ vite: { plugins: [tailwindcss()] } });
|
|
|
46
45
|
Do **not** add `@nuxtjs/tailwindcss`, a `postcss.config.js` with `tailwindcss: {}`,
|
|
47
46
|
or `@tailwind base/components/utilities` — those are v3 and either no-op or break.
|
|
48
47
|
`tailwindcss` itself must be a direct dependency (alongside `@tailwindcss/vite`),
|
|
49
|
-
or
|
|
48
|
+
or tooling that peers on it raises peer-dependency warnings.
|
|
50
49
|
|
|
51
50
|
## Design tokens: `@theme` vs `:root`
|
|
52
51
|
|
|
@@ -58,16 +57,16 @@ or `tailwindcss-primeui` raises peer-dependency warnings.
|
|
|
58
57
|
`bg-surface-strong` with no matching token) **generates nothing, with no error**
|
|
59
58
|
— the element just renders unstyled. First thing to check when a custom color
|
|
60
59
|
"does nothing": does the token name match exactly?
|
|
61
|
-
- **
|
|
62
|
-
`
|
|
63
|
-
|
|
60
|
+
- **gallop-ui reads a fixed token set** (`canvas`, `surface`, `fg`, `line`, `accent`, `field`…; the contract
|
|
61
|
+
is `layers/gallop-ui/TOKENS.md`). The app defines each in `@theme` with a dark override, so layer components
|
|
62
|
+
and your own markup flip together. Add a token the layer doesn't know and you also own its dark value.
|
|
64
63
|
|
|
65
64
|
## `@source` — v4 only generates classes from scanned files
|
|
66
65
|
|
|
67
66
|
v4 auto-detects content, but skips files outside the project's default roots (and
|
|
68
67
|
anything gitignored). Classes used **only** inside a vendored/library directory
|
|
69
|
-
(e.g.
|
|
70
|
-
Tailwind at them
|
|
68
|
+
(e.g. a Nuxt layer's components) get purged and silently go missing. Point
|
|
69
|
+
Tailwind at them with `@source`. If a vendored component's
|
|
71
70
|
classes aren't generating, check this line first.
|
|
72
71
|
|
|
73
72
|
## Dark mode
|
|
@@ -101,8 +100,8 @@ default. Two consequences:
|
|
|
101
100
|
## More gotchas
|
|
102
101
|
|
|
103
102
|
The full set mined from real debugging sessions — `@apply` in scoped `<style>`,
|
|
104
|
-
JS-driven colors that can't read tokens, `@import url()` ordering,
|
|
105
|
-
|
|
103
|
+
JS-driven colors that can't read tokens, `@import url()` ordering, why raw
|
|
104
|
+
palette classes plus `dark:` don't mix with tokens, and more — is in
|
|
106
105
|
[gotchas.md](gotchas.md). Read it when touching CSS in this stack.
|
|
107
106
|
|
|
108
107
|
## Optional tooling
|
|
@@ -114,9 +113,8 @@ class discovery, but it does not encode the stack-specific gotchas above.
|
|
|
114
113
|
|
|
115
114
|
## Related
|
|
116
115
|
|
|
117
|
-
- **
|
|
118
|
-
|
|
119
|
-
see the **volt-primevue** skill — it owns the component layer; this skill owns
|
|
116
|
+
- **Component styling** (the gallop-ui layer's components, `pt` and `class`, colour
|
|
117
|
+
tokens): see the **gallop-ui** skill. It owns the component layer; this skill owns
|
|
120
118
|
the Tailwind-v4 fundamentals.
|
|
121
119
|
|
|
122
120
|
## Contributing Back
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Tailwind v4 Gotchas
|
|
2
2
|
|
|
3
3
|
Mined from real debugging sessions in this stack (Nuxt/Vite + Tailwind v4 +
|
|
4
|
-
|
|
4
|
+
gallop-ui). Each is a place where a class silently did nothing, a v3 habit
|
|
5
5
|
broke, or the fix was non-obvious.
|
|
6
6
|
|
|
7
7
|
## `@apply` of custom tokens in a `<style>` block needs `@reference` to YOUR css
|
|
@@ -30,8 +30,7 @@ variables directly — `color: var(--color-fg)` always works with no `@reference
|
|
|
30
30
|
|
|
31
31
|
Note: a full `yarn build` validates `@apply` in `<style>`; a bare
|
|
32
32
|
`@tailwindcss/cli` compile does **not** — the CLI can pass while the real build
|
|
33
|
-
fails. Include `build` in your check.
|
|
34
|
-
**volt-primevue** skill's gotchas.)
|
|
33
|
+
fails. Include `build` in your check.
|
|
35
34
|
|
|
36
35
|
## `@import url(...)` must come before `@import "tailwindcss"`
|
|
37
36
|
|
|
@@ -52,20 +51,17 @@ written from script) can't use `bg-surface`/`var(--color-fg)` — the value is b
|
|
|
52
51
|
at render and won't follow `prefers-color-scheme`. A `colors: ["#18181b"]`
|
|
53
52
|
(near-black) chart line is invisible on dark. Compute a palette from a
|
|
54
53
|
`window.matchMedia("(prefers-color-scheme: dark)")` match and recompute on its
|
|
55
|
-
`change` event
|
|
54
|
+
`change` event (VueUse's `usePreferredDark` does this in Vue).
|
|
56
55
|
|
|
57
|
-
##
|
|
56
|
+
## Tokens flip, raw palette classes don't
|
|
58
57
|
|
|
59
|
-
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
- Your `@theme` semantic tokens (`--color-surface`, `--color-fg`) **flip their
|
|
64
|
-
value** in the dark `@media` block, so `bg-surface` needs no `dark:`.
|
|
58
|
+
- Your `@theme` semantic tokens (`--color-surface`, `--color-fg`, `--color-line`) change value in the dark
|
|
59
|
+
block, so `bg-surface` needs no `dark:`. gallop-ui components are written the same way.
|
|
60
|
+
- A raw palette class (`bg-white`, `text-zinc-700`) is fixed. It needs a `dark:` pair, and forgetting it gives
|
|
61
|
+
white stripes on dark.
|
|
65
62
|
|
|
66
|
-
Rule:
|
|
67
|
-
|
|
68
|
-
upstream-compatible. Mixing the two is what produces white-striped tables on dark.
|
|
63
|
+
Rule: use tokens in app markup, so there is no `dark:` half to forget. Keep raw palette classes for meaning-carrying
|
|
64
|
+
hues (red for an error, green for success). Don't restyle layer components with `dark:` pairs: change the token.
|
|
69
65
|
|
|
70
66
|
## Don't port a v3 `tailwind.config.js` into a v4 app
|
|
71
67
|
|
|
@@ -86,7 +82,6 @@ trigger an infinite dev-server regeneration loop. Use `@tailwindcss/vite`.
|
|
|
86
82
|
|
|
87
83
|
## Benign noise
|
|
88
84
|
|
|
89
|
-
Under Yarn (esp. PnP), `@tailwindcss/vite`
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
(Adding `tailwindcss` as a direct dependency silences the `tailwindcss-primeui` one.)
|
|
85
|
+
Under Yarn (esp. PnP), `@tailwindcss/vite` may emit a "doesn't provide vite/tailwindcss"
|
|
86
|
+
unmet-peer-dependency warning even though the deps resolve transitively. It is safe to ignore,
|
|
87
|
+
and not a config bug. (Adding `tailwindcss` as a direct dependency silences the `tailwindcss` one.)
|
|
@@ -8,7 +8,7 @@ description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-impor
|
|
|
8
8
|
Patterns for writing Vue 3 `<script setup>` components inside a Nuxt 4 app. This
|
|
9
9
|
is the **frontend authoring** slice — the data layer (`useFetch`/`$fetch`, SSR
|
|
10
10
|
storage, hydration, `definePageMeta`/auth) lives in the `nuxt-nitro-api` skill;
|
|
11
|
-
|
|
11
|
+
components, styling and dark mode live in `gallop-ui`. This skill
|
|
12
12
|
cross-links to those rather than restating them.
|
|
13
13
|
|
|
14
14
|
## When to Use This Skill
|
|
@@ -51,7 +51,7 @@ instead of testing those pieces as plain Vue functions.
|
|
|
51
51
|
3. **`computed` for derivation, `watch` for escaping the graph.** If a watcher body just assigns one reactive value from others, it's a `computed`. Need to write a value back? A `computed` can have a setter — reach for a writable `computed` or `defineModel` before a sync watcher. Keep computed getters pure (no fetch, no mutation, no DOM).
|
|
52
52
|
4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive). Before hand-rolling that effect-plus-teardown, check whether a **VueUse** composable already wraps it (`vueuse.md`) — they bundle the cleanup.
|
|
53
53
|
5. **Call composables at the top of `<script setup>`** — never inside a callback or a template expression (both lose Nuxt's request scope). Derive display state with `computed`, guarding for possibly-null data.
|
|
54
|
-
6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`.
|
|
54
|
+
6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. UI components, `pt` styling, color tokens, dark mode → `gallop-ui`. Don't duplicate them here.
|
|
55
55
|
|
|
56
56
|
## Contributing Back
|
|
57
57
|
|
|
@@ -22,7 +22,7 @@ PascalCased filename:
|
|
|
22
22
|
- **Guessing the bare filename fails silently.** `<FileUpload>` for `form/FileUpload.vue` resolves to nothing — no error, just an unrendered tag. If a component "isn't showing up," check the prefix first.
|
|
23
23
|
- **Want a clean unprefixed tag?** Either explicitly import it
|
|
24
24
|
(`import EstimateHeader from '~/components/estimates/EstimateHeader.vue'`), or
|
|
25
|
-
register a directory with a prefix in `nuxt.config` (`components: [{ path: '
|
|
25
|
+
register a directory with a prefix in `nuxt.config` (`components: [{ path: '~/components/forms', prefix: 'Form' }]` → `<FormInput>`).
|
|
26
26
|
|
|
27
27
|
## What auto-imports (no `import` line)
|
|
28
28
|
|
|
@@ -36,7 +36,7 @@ naming collision.
|
|
|
36
36
|
|
|
37
37
|
## What does NOT auto-import (import explicitly)
|
|
38
38
|
|
|
39
|
-
- **Third-party composables/components:** `
|
|
39
|
+
- **Third-party composables/components:** `date-fns` helpers, a Mapbox or Tiptap class, a composable from a package that is not a Nuxt module, etc. (gallop-ui's components, `useToast()`, `useConfirm()` and the `format*` helpers are auto-imported from the layer.)
|
|
40
40
|
- **TypeScript types** — interfaces, enums, type aliases are never auto-imported. `import type { Foo } from '...'`.
|
|
41
41
|
- **`server/utils`** — auto-imported on the *server* only, never into client code.
|
|
42
42
|
- **Vitest unit tests** — plain `*.test.ts` files do NOT get Nuxt's auto-import context. Import the composable/util under test explicitly: `import { useFormatters } from './useFormatters'`. (Component tests via `@nuxt/test-utils/runtime` + `mountSuspended` DO have the context — see the `nitro-testing` skill.)
|
|
@@ -109,7 +109,7 @@ a dialog clipped inside a scrolling panel):
|
|
|
109
109
|
<Teleport to="body"><div class="modal">…</div></Teleport>
|
|
110
110
|
```
|
|
111
111
|
|
|
112
|
-
`<Teleport>` is auto-imported. (
|
|
112
|
+
`<Teleport>` is auto-imported. (gallop-ui's `Modal`, `Drawer` and `Popover` already teleport
|
|
113
113
|
internally; this is for your own hand-rolled overlays.)
|
|
114
114
|
|
|
115
115
|
## `<KeepAlive>` caches toggled-component state
|
|
@@ -40,15 +40,15 @@ const [model, modifiers] = defineModel<string>({
|
|
|
40
40
|
|
|
41
41
|
## The computed-proxy — for forwarding an existing model
|
|
42
42
|
|
|
43
|
-
When you wrap a component that already has its own `v-model` (a
|
|
44
|
-
`
|
|
43
|
+
When you wrap a component that already has its own `v-model` (a gallop-ui
|
|
44
|
+
`Modal`'s `open`, say), or you need a named local handle or a value
|
|
45
45
|
transform, use a writable `computed` over `props` + `emit`:
|
|
46
46
|
|
|
47
47
|
```ts
|
|
48
|
-
const props = defineProps<{
|
|
49
|
-
const emit = defineEmits<{ 'update:
|
|
50
|
-
const
|
|
51
|
-
// <
|
|
48
|
+
const props = defineProps<{ open: boolean }>()
|
|
49
|
+
const emit = defineEmits<{ 'update:open': [v: boolean] }>()
|
|
50
|
+
const open = computed({ get: () => props.open, set: (v) => emit('update:open', v) })
|
|
51
|
+
// <Modal v-model:open="open" />
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
A `computed({ get, set })` transforms a *forwarded* value shape (date string ↔
|
|
@@ -63,7 +63,7 @@ Only when the effect crosses **out of** the reactive graph:
|
|
|
63
63
|
auto-refetches; see `nuxt-nitro-api/fetch-patterns.md`). Reach for `watch` only
|
|
64
64
|
for imperative `$fetch` keyed off a single id.
|
|
65
65
|
- **Drive a non-Vue library** — Tiptap, a Leaflet/Google map, a signature canvas,
|
|
66
|
-
a
|
|
66
|
+
a Mapbox popup you `.remove()` imperatively.
|
|
67
67
|
- **DOM / timers** — `document.body.style.overflow`, a debounce `setTimeout`, a
|
|
68
68
|
polling `setInterval` (clear it in `onUnmounted`).
|
|
69
69
|
- **Persist** — a `localStorage`/`useCookie` write, debounced auto-save of a
|
|
@@ -73,8 +73,8 @@ Only when the effect crosses **out of** the reactive graph:
|
|
|
73
73
|
below). A write-back watch is the right tool only when the URL can't model the
|
|
74
74
|
state: a ref with **two distinct "empty" states** (e.g. a filter that defaults to
|
|
75
75
|
`"Open"` on load but clears to `null` — an absent param can map to only one of
|
|
76
|
-
them), or a **composite object fanning out to many params** (a
|
|
77
|
-
object) that a one-ref-per-param `useRouteQuery` can't express.
|
|
76
|
+
them), or a **composite object fanning out to many params** (a filter
|
|
77
|
+
object with six fields) that a one-ref-per-param `useRouteQuery` can't express.
|
|
78
78
|
- **Re-seed local state on dialog open** — `watch(visible, (v) => { if (v) initForm() })`.
|
|
79
79
|
The single most common legit pattern. Its one-liner is `whenever(visible, initForm)`
|
|
80
80
|
(see `vueuse.md`); a compound guard keeps its inner half —
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "volt-primevue",
|
|
3
|
-
"description": "Volt (unstyled PrimeVue + Tailwind) UI: adding components, pt: pass-through styling, the surface-* vs semantic-token color model, and prefers-color-scheme dark mode",
|
|
4
|
-
"version": "1.0.0",
|
|
5
|
-
"author": {
|
|
6
|
-
"name": "yeedle"
|
|
7
|
-
}
|
|
8
|
-
}
|
|
@@ -1,170 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: volt-primevue
|
|
3
|
-
description: Build UIs with Volt (unstyled PrimeVue + Tailwind). Covers adding components, pt: pass-through customization, choosing components, and the two-layer color model for prefers-color-scheme dark mode.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Volt + PrimeVue UI
|
|
7
|
-
|
|
8
|
-
Volt components are **PrimeVue unstyled components styled with Tailwind**. They
|
|
9
|
-
ship as source you vendor into `src/volt/` and register with a `Volt` prefix, so
|
|
10
|
-
you own the markup but track upstream styling conventions.
|
|
11
|
-
|
|
12
|
-
## When to Use This Skill
|
|
13
|
-
|
|
14
|
-
- Building UI in a Nuxt + Tailwind v4 + PrimeVue/Volt project
|
|
15
|
-
- Adding or customizing a Volt component
|
|
16
|
-
- Anything color/theme/dark-mode related in this stack
|
|
17
|
-
- Deciding between a Volt component and a hand-rolled one
|
|
18
|
-
|
|
19
|
-
## What Volt is
|
|
20
|
-
|
|
21
|
-
- PrimeVue **unstyled** components + Tailwind classes, vendored under `src/volt/`.
|
|
22
|
-
- Registered with a `Volt` prefix via `nuxt.config.ts` (`<VoltButton>`, `<VoltCard>`, …).
|
|
23
|
-
- `app/assets/css/main.css` has `@source "../../../src/volt";` so Tailwind scans
|
|
24
|
-
the vendored sources for class names. If a Volt class isn't generating, that
|
|
25
|
-
`@source` line is the first thing to check.
|
|
26
|
-
|
|
27
|
-
## Adding components
|
|
28
|
-
|
|
29
|
-
Use the CLI — **never hand-create a Volt component**:
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
npx volt-vue add MultiSelect # adds src/volt/MultiSelect.vue
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
Hand-writing one means you've guessed the PrimeVue part structure and the
|
|
36
|
-
`surface-*`/`dark:` conventions; the generator gets both right and stays
|
|
37
|
-
consistent with upstream.
|
|
38
|
-
|
|
39
|
-
**`volt-vue add` is a one-time fetch, not a sync channel.** Volt's docs are
|
|
40
|
-
explicit that vendored components [aren't meant to be updated](https://volt.primevue.org/overview/)
|
|
41
|
-
— once added, the file is yours and editing it is the *expected* path, not a
|
|
42
|
-
fallback. There's no `volt-vue update`. Upstream **behavior/structure** fixes
|
|
43
|
-
arrive by bumping the **`primevue`** version (the unstyled logic is imported from
|
|
44
|
-
it); the **styling** is yours to keep. So "edit the vendored source" carries no
|
|
45
|
-
hidden regeneration penalty — that escape hatch was never there to lose.
|
|
46
|
-
|
|
47
|
-
## Customization — `pt:` pass-through
|
|
48
|
-
|
|
49
|
-
Volt uses PrimeVue's pass-through API. Target a component's internal section with
|
|
50
|
-
`pt:<section>:class`:
|
|
51
|
-
|
|
52
|
-
```vue
|
|
53
|
-
<VoltButton pt:root:class="bg-zinc-900 hover:bg-zinc-800" />
|
|
54
|
-
<VoltCard pt:root:class="rounded-2xl" pt:body:class="p-6" />
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
**Use `pt:`, not a plain `class`.** Volt merges classes with
|
|
58
|
-
[tailwind-merge](https://volt.primevue.org/overview/#twmerge), and the two paths
|
|
59
|
-
differ in precedence:
|
|
60
|
-
|
|
61
|
-
- `pt:{section}:class` is **merged with the component's defaults** and reliably
|
|
62
|
-
overrides them — `pt:root:class="bg-primary"` wins.
|
|
63
|
-
- A plain `class="bg-primary"` has **lower precedence and may not apply** — its
|
|
64
|
-
conflicting utilities can lose to the component's own classes.
|
|
65
|
-
|
|
66
|
-
So `<VoltInputText pt:root:class="bg-primary" />` works; `<VoltInputText
|
|
67
|
-
class="bg-primary" />` may silently not.
|
|
68
|
-
|
|
69
|
-
Both paths run through **`ptViewMerge` in `src/volt/utils.ts`**
|
|
70
|
-
(`twMerge(globalClass, selfClass)` + Vue `mergeProps`), wired onto every component
|
|
71
|
-
via `:ptOptions="{ mergeProps: ptViewMerge }"`. That local helper — not a global
|
|
72
|
-
config — is the actual override point; it's *why* `pt:` reliably wins. To change
|
|
73
|
-
merge behavior across components, edit `utils.ts`. See [gotchas.md](./gotchas.md).
|
|
74
|
-
|
|
75
|
-
### Restyle component states with `p-*` variants
|
|
76
|
-
|
|
77
|
-
Per-state styling (active, focus, disabled, invalid) is expressed declaratively in
|
|
78
|
-
the class string via `tailwindcss-primeui` variants — `p-selected:`, `p-focus:`,
|
|
79
|
-
`p-disabled:`, `p-editable:`, `p-invalid:` (you'll see them throughout the
|
|
80
|
-
vendored sources). They're plain Tailwind variants, so you can **override a state's
|
|
81
|
-
look through `pt:`** without touching DOM or source:
|
|
82
|
-
|
|
83
|
-
```vue
|
|
84
|
-
<VoltSelect pt:option:class="p-selected:bg-highlight p-focus:bg-surface-100" />
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
Reach for these before editing vendored source — restyling the *active* or
|
|
88
|
-
*disabled* appearance rarely needs a source edit.
|
|
89
|
-
|
|
90
|
-
What `pt:` **can't** do is change DOM — it only restyles sections the component
|
|
91
|
-
already renders. To add an element the component doesn't have (e.g. an animated
|
|
92
|
-
overlay), you have two honest options, because Volt components are **vendored and
|
|
93
|
-
yours to edit** (see [Choosing a component](#choosing-a-component-volt-vs-custom)):
|
|
94
|
-
edit the component's source in `src/volt/`, or build a standalone component.
|
|
95
|
-
|
|
96
|
-
## Choosing a component: Volt vs custom
|
|
97
|
-
|
|
98
|
-
Volt gives you selection semantics + accessibility for free. The question is only
|
|
99
|
-
whether you need DOM/behavior the component doesn't render — and remember Volt
|
|
100
|
-
components are **vendored and editable**, so "the component doesn't do X" has
|
|
101
|
-
three answers, not two: restyle via `pt:`, **edit the source in `src/volt/`**, or
|
|
102
|
-
build standalone.
|
|
103
|
-
|
|
104
|
-
Worked example — **segmented toggle** (`SelectButton` vs a custom `SlidingTabs`).
|
|
105
|
-
*Illustrative:* `SelectButton` isn't vendored in every project (e.g. not in this
|
|
106
|
-
repo's `src/volt/` by default) — you'd `npx volt-vue add SelectButton` first.
|
|
107
|
-
|
|
108
|
-
- `VoltSelectButton` ships v-model, single/multi-select, label+icon options, and
|
|
109
|
-
proper radiogroup a11y, with a *highlighted-active* look.
|
|
110
|
-
- A custom `SlidingTabs` adds an **animated indicator** (a single shared element
|
|
111
|
-
that measures the active button and slides), responsive label collapse, and
|
|
112
|
-
token-matched styling.
|
|
113
|
-
- The active/focus/disabled *look* **is** `pt:`-reachable (via the `p-selected:`/
|
|
114
|
-
`p-focus:` variants above). What `pt:` can't add is the **shared sliding
|
|
115
|
-
element** — `SelectButton` toggles a per-button background and has no single
|
|
116
|
-
position-measured overlay, and `pt:` changes classes, not DOM. Adding that
|
|
117
|
-
indicator means editing the vendored `SelectButton.vue` (you keep its a11y +
|
|
118
|
-
selection model) or building standalone.
|
|
119
|
-
|
|
120
|
-
So the real decision:
|
|
121
|
-
|
|
122
|
-
- **No animation needed → `SelectButton` as-is** (`pt:` to match your design).
|
|
123
|
-
Free a11y + multi-select; don't reinvent it.
|
|
124
|
-
- **Animated indicator / responsive collapse needed →** either **edit the
|
|
125
|
-
vendored `SelectButton`** (keep its a11y; you own the file — which is true the
|
|
126
|
-
moment you `volt-vue add` it anyway, so there's no regeneration to forfeit) **or
|
|
127
|
-
build a standalone `SlidingTabs`** (clean and decoupled, but you owe the a11y
|
|
128
|
-
yourself — `role="group"` + `aria-pressed` at minimum). Standalone wins when
|
|
129
|
-
it's a *filter* toggle rather than a form field; editing the source wins when
|
|
130
|
-
you want the full input semantics.
|
|
131
|
-
|
|
132
|
-
## Theming & dark mode
|
|
133
|
-
|
|
134
|
-
This is the part people get wrong. Read **[theming.md](./theming.md)** — the
|
|
135
|
-
two-layer color model (`surface-*` for Volt, semantic tokens for your markup),
|
|
136
|
-
why they can't be unified, and the `prefers-color-scheme` mechanics.
|
|
137
|
-
|
|
138
|
-
The one-paragraph version: dark mode follows the OS via
|
|
139
|
-
`@media (prefers-color-scheme: dark)`. **Your app markup** uses semantic `@theme`
|
|
140
|
-
tokens (`bg-surface`, `text-fg`, `border-line`) written **once** — the
|
|
141
|
-
`--color-*` var flips in the dark media block, so there's no `dark:` half to
|
|
142
|
-
forget. **Volt internals** stay on the `surface-*` scale with explicit `dark:`
|
|
143
|
-
pairs — they need the full 0–950 ramp, and leaving them as `volt-vue add`
|
|
144
|
-
generated them keeps regeneration easy. You *could* restyle a vendored component
|
|
145
|
-
to tokens (it's your code), but the small token set can't express the whole ramp,
|
|
146
|
-
so don't — tokens for your opinionated markup, `surface-*` for the component
|
|
147
|
-
library.
|
|
148
|
-
|
|
149
|
-
## Gotchas
|
|
150
|
-
|
|
151
|
-
See **[gotchas.md](./gotchas.md)** — the ones that cost real debugging time:
|
|
152
|
-
|
|
153
|
-
- `@reference "main.css"` (not `"tailwindcss"`) for `@apply` of custom tokens in
|
|
154
|
-
SFC `<style>` blocks.
|
|
155
|
-
- JS-driven colors (ApexCharts, canvas) can't read CSS tokens — pick them from a
|
|
156
|
-
reactive `prefers-color-scheme` palette.
|
|
157
|
-
- A bare `boolean` prop casts to `false` when absent — default it with
|
|
158
|
-
`withDefaults`, never rely on `undefined`.
|
|
159
|
-
- The class merge lives in `ptViewMerge` (`src/volt/utils.ts`) — the lever when a
|
|
160
|
-
`pt:` override won't take.
|
|
161
|
-
- `data-pc-name` / `data-pc-section` to reach internals from CSS; `pc`-prefixed
|
|
162
|
-
section names (`pt:pcBadge:…`) for nested child components.
|
|
163
|
-
- We deliberately **don't** use `@primevue/forms` — zod + manual wiring instead.
|
|
164
|
-
|
|
165
|
-
## Plugin config
|
|
166
|
-
|
|
167
|
-
See **[config.md](./config.md)** for PrimeVue plugin options beyond colors —
|
|
168
|
-
global `pt` defaults, `ptOptions` merge behavior, `zIndex` overlay stacking, and
|
|
169
|
-
`locale`. (Keep `unstyled: true`; styled-mode `definePreset`/`theme.preset` are
|
|
170
|
-
inert — see [theming.md](./theming.md).)
|
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
# PrimeVue plugin config
|
|
2
|
-
|
|
3
|
-
Options passed where PrimeVue is registered (`app.use(PrimeVue, { … })` / the Nuxt
|
|
4
|
-
module config), beyond colors. Volt runs **`unstyled: true`** — keep that; it's
|
|
5
|
-
what makes the components unstyled (and what makes styled-mode theming inert; see
|
|
6
|
-
[theming.md](./theming.md)).
|
|
7
|
-
|
|
8
|
-
## App-wide section styling: global `pt`
|
|
9
|
-
|
|
10
|
-
Instead of repeating the same `pt:` on every call site, set defaults once with a
|
|
11
|
-
global `pt` object keyed by lowercase component name → sections. A component-level
|
|
12
|
-
`pt:` still overrides the global:
|
|
13
|
-
|
|
14
|
-
```ts
|
|
15
|
-
app.use(PrimeVue, {
|
|
16
|
-
unstyled: true,
|
|
17
|
-
pt: {
|
|
18
|
-
dialog: { header: { class: "border-b border-line" } }, // every dialog's header
|
|
19
|
-
select: { dropdown: { class: "text-fg-muted" } },
|
|
20
|
-
},
|
|
21
|
-
ptOptions: { mergeSections: true, mergeProps: true },
|
|
22
|
-
});
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
`ptOptions` governs how global + local combine: `mergeSections` (default `true`)
|
|
26
|
-
merges section objects; `mergeProps` (default `false`) merges class/listener
|
|
27
|
-
props rather than replacing. Set `mergeProps: true` if you want a call-site
|
|
28
|
-
`pt:` to *add to* the global classes instead of replacing them. (Note the vendored
|
|
29
|
-
components already pass their own `mergeProps: ptViewMerge` per-component — see
|
|
30
|
-
[gotchas.md](./gotchas.md).)
|
|
31
|
-
|
|
32
|
-
## Config knobs worth knowing
|
|
33
|
-
|
|
34
|
-
```ts
|
|
35
|
-
app.use(PrimeVue, {
|
|
36
|
-
unstyled: true,
|
|
37
|
-
zIndex: { modal: 1100, overlay: 1000, menu: 1000, tooltip: 1100 }, // overlay stacking
|
|
38
|
-
locale: { /* aria, filter, date strings — overrides built-in en defaults */ },
|
|
39
|
-
});
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
- **`zIndex`** — the dial when a Volt overlay (dialog, menu, tooltip) renders
|
|
43
|
-
under or over app chrome. Defaults: modal/tooltip `1100`, overlay/menu `1000`.
|
|
44
|
-
- **`locale`** — overrides all built-in aria labels, filter/date/pagination
|
|
45
|
-
strings (i18n, or just rewording an aria label).
|
|
46
|
-
- **`inputVariant: 'outlined' | 'filled'`** — default `outlined`; affects input
|
|
47
|
-
styling defaults.
|
|
48
|
-
- **`ripple`** — irrelevant under unstyled (no ripple CSS), harmless if set.
|
|
49
|
-
|
|
50
|
-
Don't set `theme` / `definePreset` — inert under `unstyled: true`
|
|
51
|
-
([theming.md](./theming.md)).
|