bert.hausmans/crewli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(rfc): correct AD-2/AD-5 and Appendix B to reflect ecosystem state

Browse Source 
Three RFC drift corrections discovered during F3 implementation:

1. AD-5 icon rendering: corrected from "<i :class='i-tabler-X'>"
   utility-class pattern (which would require UnoCSS, not installed)
   to "@iconify/vue's <Icon> component with name='tabler-X' prop"
   (existing Crewli pattern producing real SVG output). The thin wrapper
   shipped in F3 B6 as apps/app/src/components/Icon.vue accordingly.

2. AD-2 theme architecture: corrected package reference from
   @primevue/themes@^4.5 (deprecated by PrimeFaces) to
   @primeuix/themes@^2 (the path now prescribed by PrimeVue 4's
   official install docs at primevue.org/vite/). Same maintainers,
   same API surface (definePreset, Aura preset, semantic tokens).
   F3 commit B1 already uses the corrected package.

3. Appendix B Aura theme token plan: updated import-path examples to
   @primeuix/themes and @primeuix/themes/aura accordingly.

Also updated:
- §6 F3 deliverables list: dependency line now reads @primeuix/themes@^2
  with a footnote linking to the B1 rationale.
- Appendix C Version Pinning Policy: separated @primeuix/themes from
  the primevue/^primevue/forms lockstep pin (independent release cadence).
- dev-docs/PRIMEVUE_COMPONENTS.md §3 (Data display): VIcon row updated
  to <Icon name="tabler-..." />; surrounding migration-spirit paragraph
  rewritten; §10 external-resources link relabeled to @primeuix/themes.

These are RFC drift corrections — the implementation in F3 (commits
B1, B2, B6 of this sprint) already uses the corrected packages and
import paths. This commit aligns the spec with reality so future
contributors don't reach for the deprecated/inaccurate documentation.

.claude-sync/ regenerates automatically post-commit via lefthook.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
bert.hausmans
2026-05-11 01:16:13 +02:00
parent ad82110a69
commit d5c9cf1927
2 changed files with 25 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
dev-docs/PRIMEVUE_COMPONENTS.md
View File

@@ -129,17 +129,21 @@ replaces `VSheet`, `VSpacer`, and most uses of `VContainer`.
| `VChip` | `Tag` (preferred) or `Chip` | https://primevue.org/tag/ | `Tag` for status badges; `Chip` for removable filters |
| `VAvatar` | `Avatar` | https://primevue.org/avatar/ | `variant='tonal'` → `:style="{ background, color }"` (no built-in tonal) |
| `VImg` | `<img>` (native) | — | No wrapper needed; use `loading="lazy"` |
| `VIcon` | `<i class="i-tabler-..." />` | — | **Iconify-Tabler retained** per [RFC AD-5](./RFC-WS-FRONTEND-PRIMEVUE.md#ad-5-icons--iconify-tabler-retained-primeicons-not-installed); PrimeIcons is **not installed** |
| `VIcon` | `<Icon name="tabler-..." />` | — | **Iconify-Tabler retained** per [RFC AD-5](./RFC-WS-FRONTEND-PRIMEVUE.md#ad-5-icons--iconify-tabler-retained-primeicons-not-installed); thin wrapper at `apps/app/src/components/Icon.vue` over `@iconify/vue`'s `<Icon>`. PrimeIcons is **not installed** |
| `VLabel` | `<label>` (native) or `<FormField label="...">` | — | |
| `VTimeline` / `VTimelineItem` | `Timeline` | https://primevue.org/timeline/ | |
| `VBadge` (1 use) | `Badge` or `OverlayBadge` | https://primevue.org/badge/ | |
**Migration spirit.** `VIcon` is the most widespread component (267 uses)
and it does **not** become a PrimeVue component. The Iconify-Tabler
class-based pattern (`<i class="i-tabler-arrow-right" />`) is
stack-agnostic and survives the migration intact. PrimeIcons is not
installed; do not introduce `pi pi-*` icon classes during F4 — they will
not render. Lists are the most context-dependent area: a selection list
naming convention survives intact: call-sites use the existing
`tabler-*` string identifiers (e.g. `tabler-arrow-right`) and the new
`apps/app/src/components/Icon.vue` wrapper renders them through
`@iconify/vue` as real `<svg>` markup. UnoCSS-style `i-tabler-*` utility
classes were considered but not adopted (UnoCSS is not in the stack);
the wrapper preserves Crewli continuity. PrimeIcons is not installed;
do not introduce `pi pi-*` icon classes during F4 — they will not
render. Lists are the most context-dependent area: a selection list
uses `Listbox`, a card grid uses `DataView`, a navigation list uses
`MenuItem`/`PanelMenu`, and a generic display list is just `<ul><li>`.
@@ -369,7 +373,7 @@ External (PrimeVue ecosystem):
- PrimeVue components: https://primevue.org/
- `@primevue/forms` (form layer): https://primevue.org/forms/
- `@primevue/themes` (Aura preset): https://primevue.org/theming/styled/
- `@primeuix/themes` (Aura preset, the maintained successor to `@primevue/themes`): https://primevue.org/theming/styled/
- `tailwindcss-primeui` (token bridge): https://github.com/primefaces/tailwindcss-primeui
Internal (Crewli docs):

21
dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md
View File

@@ -105,7 +105,9 @@ The current `<VForm>` ref + per-field `:rules` array pattern is replaced by `<Fo
### AD-2: Theme = Aura preset, Crewli teal primary, dark mode preserved
The Aura preset is configured via `@primevue/themes` `definePreset(Aura, { semantic: { primary: { ... } } })`. The Crewli teal (`#0D9394` light, `#0B7F80` dark) maps to `primary.500` and `primary.600` semantic tokens. Surface, success, info, warning, error tokens use Aura defaults unless explicit Crewli equivalents exist. Dark mode is wired via PrimeVue's `darkModeSelector: '.dark'` config, integrated with the existing `@core/composable/useSkins.ts` until F6 cleanup.
The Aura preset is configured via `@primeuix/themes` `definePreset(Aura, { semantic: { primary: { ... } } })`. The Crewli teal (`#0D9394` light, `#0B7F80` dark) maps to `primary.500` and `primary.600` semantic tokens. Surface, success, info, warning, error tokens use Aura defaults unless explicit Crewli equivalents exist. Dark mode is wired via PrimeVue's `darkModeSelector: '.dark'` config, integrated with the existing `@core/composable/useSkins.ts` until F6 cleanup.
> **Drift correction (F3 B9):** RFC v1.0 referenced `@primevue/themes@^4.5`. That package was deprecated by its maintainers (PrimeFaces) during the F3 sprint with explicit guidance to migrate to `@primeuix/themes`. PrimeVue 4's official install documentation at primevue.org/vite/ now specifies `@primeuix/themes` as the theme package. Same maintainers, same API surface (Aura preset, `definePreset`, semantic tokens). F3 commit B1 installed `@primeuix/themes@^2` directly; this paragraph and Appendix B are aligned with that ecosystem state.
**Per-tenant overrides:** primary color and logo only (per project-level decision). Implementation: a Pinia computed reads `useOrganisationStore().branding.primaryColor` and patches the active preset via `usePrimeVue().config.theme.preset` at organisation-switch time. Full white-labeling is explicitly out of scope.
@@ -125,7 +127,9 @@ The Aura preset is configured via `@primevue/themes` `definePreset(Aura, { seman
### AD-5: Icons = Iconify-Tabler retained, PrimeIcons not installed
The 593 `tabler-*` icon references in templates remain unchanged. PrimeVue's components accept any element in icon slots and `:icon` props can render arbitrary class names. The custom Vuetify icon component in `apps/app/src/plugins/vuetify/icons.ts` is replaced by a tiny generic `<Icon>` component that renders `<i :class="...">` for Iconify class strings — or, where call-sites already use `<VIcon icon="tabler-X">`, the migration substitutes `<i class="iconify tabler-X">` directly. The 5 SVG checkbox/radio overrides in `@images/svg/` become unused (PrimeVue's Checkbox/RadioButton ship their own styling) and are deleted in F6.
The 593 `tabler-*` icon references in templates remain unchanged. PrimeVue's components accept any element in icon slots and `:icon` props can render arbitrary content. The custom Vuetify icon adapter in `apps/app/src/plugins/vuetify/icons.ts` is replaced by a tiny generic `<Icon>` component (at `apps/app/src/components/Icon.vue`) that wraps `@iconify/vue`'s `<Icon>` component and emits real `<svg>` markup. Call-site migration substitutes `<VIcon icon="tabler-X" />` with `<Icon name="tabler-X" />`. The 5 SVG checkbox/radio overrides in `@images/svg/` become unused (PrimeVue's Checkbox/RadioButton ship their own styling) and are deleted in F6.
> **Drift correction (F3 B9):** RFC v1.0 described the new `<Icon>` component as rendering `<i :class="i-tabler-X">` utility classes. That approach would require UnoCSS to resolve `i-tabler-*` into real icon output, and UnoCSS is not in the Crewli stack — the project already uses `@iconify/vue` (installed at 4.1.2) for SVG icon rendering through Vuetify's icon adapter. F3 commit B6 implements `Icon.vue` as a thin wrapper around `@iconify/vue` accordingly. The substitution preserves existing icon naming (`tabler-eye`, `tabler-user`, etc.) and produces equivalent SVG output to the current Vuetify path. UnoCSS-style utility-class icon rendering was considered but not adopted; the wrapper retains Crewli's continuity.
**Rationale:** Throwing away 593 icon references is needless cost; PrimeVue does not require its own icon set; the project's Tabler aesthetic is preserved.
@@ -195,7 +199,9 @@ Six work packages, executed strictly serially. Each package ends with: (a) all t
### F3 — Foundation (2 days)
**Output:**
- Dependencies installed: `primevue@^4.5`, `@primevue/themes@^4.5`, `@primevue/forms@^4.5`, `primelocale@^1`, `tailwindcss@^4`, `@tailwindcss/vite@^4`.
- Dependencies installed: `primevue@^4.5`, `@primeuix/themes@^2` [^themes-pkg], `@primevue/forms@^4.5`, `primelocale@^1`, `tailwindcss@^4`, `@tailwindcss/vite@^4`.
[^themes-pkg]: RFC v1.0 specified `@primevue/themes@^4.5`. That package was deprecated during F3 with explicit guidance to migrate to `@primeuix/themes` (same maintainers, same API surface). PrimeVue 4's official install documentation now prescribes `@primeuix/themes`. See F3 commit B1 for the substitution rationale and B9 for the AD-2 + Appendix B alignment.
- Dependencies retained: `flatpickr`, `vue-flatpickr-component`, `@iconify-json/tabler`, `@iconify-json/mdi`, `@iconify-json/fa`, all Pinia/TanStack/Vue Query/Zod packages.
- New: `apps/app/src/plugins/primevue/index.ts` — registers PrimeVue plugin with Aura preset, theme tokens, nl-NL locale.
- New: `apps/app/src/plugins/primevue/theme.ts` — Aura `definePreset` with Crewli teal semantic tokens.
@@ -510,8 +516,10 @@ const onSubmit = async ({ valid, values }: any) => {
```ts
// apps/app/src/plugins/primevue/theme.ts
import Aura from '@primevue/themes/aura'
import { definePreset } from '@primevue/themes'
// Drift correction (F3 B9): imports use @primeuix/themes (the
// maintained successor that PrimeVue 4's install docs now prescribe).
import { definePreset } from '@primeuix/themes'
import Aura from '@primeuix/themes/aura'
export const CrewliPreset = definePreset(Aura, {
semantic: {
@@ -549,7 +557,8 @@ Component-level overrides use the `pt` (PassThrough) prop globally configured in
PrimeVue moves fast (4.5.0 → 4.5.5 in Oct–Dec 2025). Sprint pins:
- `primevue` and `@primevue/themes` and `@primevue/forms`: pin to **same exact patch version** (e.g., `4.5.5`) in F3. They must always upgrade together to avoid token-mismatch bugs.
- `primevue` and `@primevue/forms`: pin to **same exact patch version** (e.g., `4.5.5`) in F3. They must always upgrade together to avoid token-mismatch bugs.
- `@primeuix/themes`: pin to `^2` (own release cadence, decoupled from PrimeVue's 4.x patch line — same maintainers, separate package per the F3 B9 drift correction).
- `tailwindcss` and `@tailwindcss/vite`: pin to same exact version.
- `primelocale`: caret range fine (`^1`).