nuxt-unified-ui 0.5.7 → 0.5.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-unified-ui",
   "type": "module",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "main": "./nuxt.config.ts",
   "types": "./index.d.ts",
   "exports": {
@@ -20,7 +20,7 @@
   ],
   "dependencies": {
     "@formkit/tempo": "1.1.0",
-    "@iconify-json/lucide": "1.2.126",
+    "@iconify-json/lucide": "1.2.129",
     "@nuxt/kit": "4.5.2",
     "@nuxt/ui": "4.11.0",
     "@nuxtjs/i18n": "10.6.0",

package/skills/nuxt-unified-ui/SKILL.md

@@ -4,8 +4,8 @@ description: >-
   Single skill for the nuxt-unified-ui Nuxt layer and mandatory Nuxt code style:
   install/extend the layer, required CSS, modules/config, radashi radXxx
   auto-imports, un-form / useForm, launchFormPickerDialog /
-  launchChoicePickerDialog, toast helpers, un-card / un-typography, pages /
-  definePageMeta, ufetch / useUFetch wrapping, unified resources
+  launchChoicePickerDialog, toast helpers,   un-card / un-typography, pages /
+  definePageMeta, page /* params */ and /* seo */ blocks, ufetch / useUFetch wrapping, unified resources
   (server plugins, REST handleResource*, resource-manager dashboard /
   customization), attribute order/defaults, and whitespace/formatting
   conventions for all Nuxt-generated code. Use when working in or consuming
@@ -71,7 +71,7 @@ Absolute highlights:
 - `{{ ... }}` on its own line (static + dynamic text may mix)
 - `/* section */` comments; imports co-located under the section that uses them
 - Light naming: `handleXxx` handlers, `it` in short callbacks, descriptive `for...of`, computeds use block + `return`
-- Pages: explicit `definePageMeta.name`, reactive route params, named `navigateTo` / `nuxt-link` → [pages.md](references/pages.md)
+- Pages: explicit `definePageMeta.name`, `/* params */` for `route.params` / `route.query`, required `/* seo */` (`useHead` + `useSeoMeta`, `useJsonld` when installed) → [pages.md](references/pages.md)
 - Fetching: `ufetch(url, {` one line; `useUFetch` with URL on next line + `data*Data` / `is*Loading` / `refresh*` → [data-fetching.md](references/data-fetching.md)
 
 ---

package/skills/nuxt-unified-ui/references/code-style.md

@@ -361,7 +361,9 @@ Group with `/* name */`:
 | Common section | Contents |
 |----------------|----------|
 | `/* interface */` | props, emits, models |
-| `/* page */` | `definePageMeta`, `useHead` |
+| `/* page */` | `definePageMeta` only |
+| `/* params */` | `useRoute` + reactive computeds for `route.params` and `route.query` |
+| `/* seo */` | `useHead` + `useSeoMeta` (and `useJsonld` when the project has it) |
 | domain names | `/* login */`, `/* resource */`, `/* captcha */`, … |
 | `/* outlets */` | `defineExpose` |
 
@@ -411,11 +413,13 @@ function refreshAll() {
 
 **Pages**
 
-1. `/* page */`
-2. Route/params
-3. Data / forms / domain sections
-4. Watchers / lifecycle
-5. Handlers
+1. `/* page */` — `definePageMeta` only
+2. `/* params */` — only when the page reads `route.params` or `route.query`
+3. Domain sections SEO needs (fetches / derived data)
+4. `/* seo */` — required; under the last block it reads
+5. Remaining domain sections
+6. Watchers / lifecycle
+7. Handlers
 
 ### Import co-location
 
@@ -648,7 +652,7 @@ Refs unwrap automatically — do not write `.value` in template expressions or i
 
 These are part of the same “shape” conventions when generating app code:
 
-- Pages / named routes / reactive params → [pages.md](pages.md)
+- Pages / named routes / `/* params */` / `/* seo */` → [pages.md](pages.md)
 - `ufetch` / `useUFetch` wrapping, naming, options order → [data-fetching.md](data-fetching.md)
 
 ### `useUFetch` wrapping (summary)
@@ -801,5 +805,5 @@ export default defineEventHandler(async event => {
 - [ ] Every section is named; imports are co-located with the section that uses them
 - [ ] `handleXxx` for action handlers; `it` for short callbacks; descriptive loop names
 - [ ] Computeds that return structures use block + `return`
-- [ ] Pages: explicit `definePageMeta.name`, reactive route params, named navigation ([pages.md](pages.md))
+- [ ] Pages: explicit `definePageMeta.name`, `/* params */` + `/* seo */` placement, named navigation ([pages.md](pages.md))
 - [ ] Fetching: `ufetch` / `useUFetch` wrap styles and destructure names ([data-fetching.md](data-fetching.md))

package/skills/nuxt-unified-ui/references/pages.md

@@ -13,13 +13,12 @@ definePageMeta({
   name: 'dashboard.patients.single',
 });
 
-useHead({
-  title: $t('patients.single.pageTitle'),
-});
 
+/* params */
 
 const route = useRoute();
 
+
 const patientUid = computed(() => {
   return route.params.patientUid;
 });
@@ -27,11 +26,22 @@ const patientUid = computed(() => {
 
 /* data */
 
-const { data: patientData, pending: isPatientLoading, refresh: refreshPatient } = useUFetch(
+const { data: patientData, pending: isPatientPending, refresh: refreshPatient } = useUFetch(
   computed(() => `/api/patients/${patientUid.value}`),
 );
 
 
+/* seo */
+
+useHead({
+  title: () => patientData.value?.name,
+});
+
+useSeoMeta({
+  description: () => patientData.value?.description,
+});
+
+
 /* handlers */
 
 async function handleAction() {
@@ -56,40 +66,147 @@ async function handleAction() {
 </template>
 ```
 
+A page with no dynamic params and no fetched SEO fields puts `/* seo */` directly under `/* page */`.
+
 ## Script ordering (pages)
 
-1. `/* page */` — `definePageMeta`, then `useHead` (head may move below data when title depends on fetched data)
-2. Route / params (`useRoute`, reactive param computeds)
-3. Domain sections (`/* data */`, forms, etc.) including `useUFetch`
-4. Watchers / lifecycle
-5. Handlers (`handleXxx`)
+1. `/* page */` — only `definePageMeta`
+2. `/* params */` — only when the page reads `route.params` or `route.query` (see Page params)
+3. Domain sections the SEO block needs (`useUFetch`, derived data, …)
+4. `/* seo */` — required on every page (see Page SEO)
+5. Remaining domain sections (forms, sessions, UI state, …)
+6. Watchers / lifecycle
+7. Handlers (`handleXxx`)
 
-## `definePageMeta`
+Do **not** put `useHead` / `useSeoMeta` / `useJsonld` inside `/* page */`. Those belong in `/* seo */`.
 
-- **Always** set an explicit `name`
-- Dot notation: `dashboard.home`, `flash-cards.single`, `authentication.login`
-- `layout: 'empty'` for login / full-bleed auth-style pages only
-- Never use `layout: false`
+## Page params
+
+If a page reads `route.params` or `route.query`, add a `/* params */` block **immediately under** `/* page */`.
+
+1. Declare `const route = useRoute();`
+2. Two blank lines
+3. One `computed` per value — `route.params` first, then `route.query` — keep each reactive; do not snapshot into a bare `const`
+
+Consecutive computeds: **one** blank line between them.
 
 ```ts
-definePageMeta({
-  name: 'authentication.login',
-  layout: 'empty',
+/* params */
+
+const route = useRoute();
+
+
+const flashCardSlug = computed(() => {
+  return route.params.flashCardSlug;
 });
 ```
 
-## Dynamic routes
+```ts
+/* params */
 
-- Files: `[patientUid].vue`, `[flashCardSlug]/index.vue`
-- Params: **camelCase** in brackets and when reading `route.params`
-- Keep params **reactive** for async workflows — do not snapshot once into a bare `const`:
+const route = useRoute();
+
+
+const returnUrl = computed(() => {
+  return route.query.returnUrl;
+});
+```
 
 ```ts
+/* params */
+
 const route = useRoute();
 
+
 const flashCardSlug = computed(() => {
   return route.params.flashCardSlug;
 });
+
+const journeySlug = computed(() => {
+  return route.query.journey;
+});
+```
+
+- Files: `[patientUid].vue`, `[flashCardSlug]/index.vue`
+- Params: **camelCase** in brackets and when reading `route.params`
+- Query keys stay as they appear on the URL; the computed name is camelCase (`returnUrl` for `returnUrl`)
+- Omit `/* params */` entirely on pages that read neither `route.params` nor `route.query` — do not create an empty block. If something else needs `route` (for example `route.fullPath`), call `useRoute()` in that domain section instead.
+
+## Page SEO
+
+Every page **must** have a `/* seo */` block.
+
+**Placement**
+
+1. Default: directly under `/* page */`
+2. If the page has `/* params */`: under `/* params */`
+3. If `/* seo */` needs data from any other block: under **that** block (after the fetch / derived computeds), not above it
+
+Blocks that SEO does not read (sessions, local UI state, handlers) stay **below** `/* seo */`.
+
+**Contents (in this order, one blank line between calls)**
+
+1. `useHead({ title })` — required
+2. `useSeoMeta({ description })` — required
+3. `useJsonld(() => …)` — only when the project has `nuxt-jsonld` set up (`package.json` / `nuxt.config` modules), and only on public indexable pages. Skip it on `noindex` / dashboard / auth pages.
+
+Static strings when the copy is fixed; getters when the value comes from fetched data (`() => flashCardData.value?.name`). Optional chaining is fine on title/description getters.
+
+```ts
+/* seo */
+
+useHead({
+  title: 'Flash Cards',
+});
+
+useSeoMeta({
+  description: 'Browse free flash card decks for practice and study.',
+});
+```
+
+```ts
+/* seo */
+
+useHead({
+  title: () => flashCardData.value?.name,
+});
+
+useSeoMeta({
+  description: () => flashCardData.value?.description,
+});
+```
+
+**`useJsonld` data guard**
+
+When JSON-LD is included, inline the schema in the page (no shared `makeXxxJsonld` helpers). Guard absent data with a ternary — return `null` so no tag is emitted; do **not** replace this guard with optional chaining inside the object:
+
+```ts
+useJsonld(() => !flashCardData.value ? null : {
+  '@context': 'https://schema.org',
+  '@graph': [
+    {
+      '@type': 'LearningResource',
+      'name': flashCardData.value.name,
+      'url': `https://khoshghadam.com/flash-cards/${flashCardData.value.slug}`,
+    },
+  ],
+});
+```
+
+Keep `useJsonld(() => !data ? null : {` on **one line**. Object properties follow the usual multi-line literal rules. `data` is the fetched document or list the schema reads.
+
+## `definePageMeta`
+
+- **Always** set an explicit `name`
+- Dot notation: `dashboard.home`, `flash-cards.single`, `authentication.login`
+- `layout: 'empty'` for login / full-bleed auth-style pages only
+- Never use `layout: false`
+
+```ts
+definePageMeta({
+  name: 'authentication.login',
+  layout: 'empty',
+});
 ```
 
 ## Navigation