nuxt-unified-ui 0.5.0 → 0.5.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-unified-ui",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "main": "./nuxt.config.ts",
   "types": "./index.d.ts",
   "exports": {

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

@@ -4,10 +4,11 @@ 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, and the
-  whitespace/formatting/code-shape conventions for all Nuxt-generated code. Use
-  when working in or consuming nuxt-unified-ui, or whenever generating Vue/Nuxt
-  code that must match unified code style.
+  launchChoicePickerDialog, toast helpers, un-card / un-typography, pages /
+  definePageMeta, ufetch / useUFetch wrapping, attribute order/defaults, and
+  whitespace/formatting conventions for all Nuxt-generated code. Use when
+  working in or consuming nuxt-unified-ui, or whenever generating Vue/Nuxt code
+  that must match unified code style.
 ---
 
 # nuxt-unified-ui
@@ -29,6 +30,8 @@ This is the **only** installable skill in this repo. Deep topics live under `ref
 | Topic | File |
 |-------|------|
 | **Code style (mandatory)** | [references/code-style.md](references/code-style.md) |
+| Pages / routing | [references/pages.md](references/pages.md) |
+| Data fetching (`ufetch` / `useUFetch`) | [references/data-fetching.md](references/data-fetching.md) |
 | Layer install + required CSS | [references/layer-setup.md](references/layer-setup.md) |
 | Public surface inventory | [references/public-surface.md](references/public-surface.md) |
 | Forms (`useForm` / `un-form`) | [references/forms.md](references/forms.md) |
@@ -55,10 +58,12 @@ Absolute highlights:
 - Script object literals always multi-line (even one property)
 - Kebab-case tags (`u-button`, `un-card`)
 - `v-if` / `v-for` on `<template>` wrappers — not on rendered nodes
-- **2+ attributes → one per line**; non-self-closing `>` on same line as last attr; multi-line self-closing `/>` on its own line
+- **2+ attributes → one per line**; attribute order + default omissions (`variant="subtle"`, omit neutral `color`, `loading-auto`); non-self-closing `>` on same line as last attr; multi-line self-closing `/>` on its own line
 - `{{ ... }}` on its own line
 - `/* 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)
+- Fetching: `ufetch(url, {` one line; `useUFetch` with URL on next line + `data*Data` / `is*Loading` / `refresh*` → [data-fetching.md](references/data-fetching.md)
 
 ---
 
@@ -132,6 +137,8 @@ From `nuxt.config.ts`: `@vueuse/nuxt`, `@nuxt/ui`, `@nuxtjs/i18n`; `ui.colorMode
 | Page chrome | `un-typography` + `un-card` |
 | Custom field | `registerFormExtraElement` in a plugin |
 | Utilities | `radXxx` → [radashi.md](references/radashi.md) |
+| New page / route | [pages.md](references/pages.md) |
+| List/detail fetch or mutation | [data-fetching.md](references/data-fetching.md) |
 | Formatting any of the above | [code-style.md](references/code-style.md) |
 
 ## Do / don’t

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

@@ -330,18 +330,64 @@ Keep tight `v-if` / `v-else` chains adjacent (no blank line between matching bra
 When wrapping, order attributes as:
 
 1. Refs / identity: `ref`, `id`, `name`
-2. Visual props: `variant`, `color`, `size`, `icon`, static `label`
+2. Component visual props: `variant`, `color`, `size`, `icon`, static `label`
 3. Static presentation: `class`, `style`
 4. Data bindings: `:items`, `:data`, `:placeholder`, `:value`, dynamic `:label`, …
 5. `v-model` / `:model-value` / `v-model:*`
-6. Navigation / state: `to`, `href`, `block`, `disabled`, `loading`, `loading-auto`, `fluid-body`, …
+6. Navigation / state: `to`, `href`, `block`, `disabled`, `loading`, `loading-auto`, `fluid-body`, `scrollable`, …
 7. Events last: `@click`, `@update:*`, …
 
 Practical shortcuts:
 
 - `u-button`: `variant` → `color` → `size` → `icon` → label/value → `block` → `disabled` → `loading-auto` → events
-- `u-input` / `u-select*`: user-facing props → `:loading`/`:disabled` → `:items` → `class` → `v-model` → events
+- `u-input` / `u-select*`: user-facing props (`:placeholder`, `:label`) → transient state (`:loading`, `:disabled`) → data source (`:items`) → `class` → `v-model` → events
+- Action objects (`:actions`, `:append-actions`, table row actions): `vIf` → `color` → `icon` → `label` → `tooltip` → `disabled` → `to` → `onClick`
+- Tab / select item objects: `value` → `icon` → `label`
 
+### Default attribute values (omit noise)
+
+Prefer defaults by **omitting** props rather than restating them:
+
+| Component / context | Default convention |
+|---------------------|--------------------|
+| `u-button` | Prefer `variant="subtle"` over `ghost` for new buttons |
+| Async `u-button` clicks | Prefer `loading-auto` over hand-rolled `isLoading` when nothing else depends on that flag |
+| `u-badge` | Always `variant="subtle"`; use `icon` + `:label` (no default slot text); **do not** set `size`; **omit** `color` for neutral (use `undefined` in ternaries, never `color="neutral"`) |
+| `u-tooltip` | Do not set `:delay-duration` — use the default delay |
+| Action objects where subtle is the local default | Omit `variant: 'subtle'` unless overriding |
+| Icons | Always `lucide:*` prefix |
+
+```vue
+<!-- ✅ omit neutral color; subtle badge -->
+<u-badge
+  variant="subtle"
+  :label="item.name"
+/>
+
+<!-- ✅ ternary falls back with undefined -->
+<u-badge
+  variant="subtle"
+  :color="item.digital ? 'info' : undefined"
+  :label="item.digital ? 'Digital' : 'Physical'"
+/>
+
+<!-- ❌ restating neutral / wrong variant -->
+<u-badge
+  variant="outline"
+  color="neutral"
+  :label="item.name"
+/>
+```
+
+```vue
+<!-- ✅ async button -->
+<u-button
+  variant="subtle"
+  icon="lucide:trash"
+  loading-auto
+  @click="handleDelete()"
+/>
+```
 ### `>` and `/>` placement
 
 **Non-self-closing**, multi-attribute: `>` on the **same line** as the last attribute:
@@ -408,6 +454,38 @@ Refs unwrap automatically — do not write `.value` in template expressions or i
 
 ---
 
+## Pages, routing, and data fetching
+
+These are part of the same “shape” conventions when generating app code:
+
+- Pages / named routes / reactive params → [pages.md](pages.md)
+- `ufetch` / `useUFetch` wrapping, naming, options order → [data-fetching.md](data-fetching.md)
+
+### `useUFetch` wrapping (summary)
+
+```ts
+const { data: ordersData, pending: isOrdersLoading, refresh: refreshOrders } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}/orders`),
+  {
+    query: {
+      limit: itemsPerPage,
+    },
+  },
+);
+```
+
+- First line: destructure + `= useUFetch(`
+- Next line: URL (string or `computed`)
+- Optional multi-line options object
+- Closing `);` alone on the last line
+- Consecutive `useUFetch` calls: **one** blank line between them
+
+### `ufetch` wrapping (summary)
+
+Keep `ufetch(url, {` on one line — do not break the URL above `{`.
+
+---
+
 ## Light naming (reading shape)
 
 | Context | Convention |
@@ -498,6 +576,9 @@ Leading blank line at top of file is fine when the local tree uses it. Prefer `a
 | `{{ x }}` glued to tags | interpolation on its own line |
 | Hoisted import block | imports co-located under section |
 | `computed(() => [ ... ])` | `computed(() => { return [ ... ]; })` |
+| `color="neutral"` on badge | omit `color` / use `undefined` |
+| `ufetch(\n  url,\n  {` | `ufetch(url, {` on one line |
+| One-line `useUFetch(...)` | URL on next line; options multi-line |
 
 ---
 
@@ -513,8 +594,10 @@ Leading blank line at top of file is fine when the local tree uses it. Prefer `a
 - [ ] Kebab-case component tags
 - [ ] `v-if` / `v-for` on `<template>` wrappers
 - [ ] 2+ attributes → one per line; `>` same line as last attr; multi-line self-closing `/>` on own line
-- [ ] Attribute order respected
+- [ ] Attribute order + default-value omissions respected (`subtle`, no neutral color noise, `loading-auto`)
 - [ ] `{{ }}` on own line
 - [ ] Section comments + import co-location where the file has sections
 - [ ] `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))
+- [ ] Fetching: `ufetch` / `useUFetch` wrap styles and destructure names ([data-fetching.md](data-fetching.md))

package/skills/nuxt-unified-ui/references/data-fetching.md

@@ -0,0 +1,196 @@
+# Data fetching (`ufetch` / `useUFetch`)
+
+Prefer host-app unified API helpers (`ufetch`, `useUFetch`) over raw `useFetch` / `useAsyncData` / `$fetch` for app API calls. Formatting rules below are mandatory; wire paths to whatever your app’s API plugin expects (relative paths — do not manually prepend `baseApiUrl`).
+
+Combine with [code-style.md](code-style.md).
+
+## `ufetch` (imperative)
+
+One-off requests (submit, delete, button click):
+
+```ts
+const response = await ufetch(`/api/resources/${id}`, {
+  silent: true,
+  method: 'post',
+  body: {
+    field: value,
+  },
+});
+```
+
+Rules:
+
+- Name the result `response` (not `result`), unless a more specific name is clearer (`loginResponse`)
+- Inline `body` / `query` objects in the options — extract only when large/reused
+- `silent: true` — suppress automatic error toast when handling errors locally
+- `responseType: 'blob'` — file downloads
+
+### Options order
+
+- Mutations: behavior flags (`silent`, `responseType`) → `method` → `body` → `query` / other
+- Reads without `method`/`body`: behavior flags before `query`
+
+### Call wrapping (critical)
+
+Keep `ufetch(url, {` on **one line**. Do not break the URL onto its own line above `{`:
+
+```ts
+// ✅
+const response = await ufetch(`/api/items/${item.uid}/documents`, {
+  silent: true,
+});
+
+// ❌
+const response = await ufetch(
+  `/api/items/${item.uid}/documents`,
+  {
+    silent: true,
+  },
+);
+```
+
+### After mutation
+
+```ts
+const response = await ufetch(url, {
+  method: 'post',
+  body: {
+    field: value,
+  },
+});
+
+
+await refresh();
+
+toastSuccess({
+  title: 'Created successfully.',
+});
+
+formValue.value = '';
+```
+
+Call `refresh()` **before** resetting local form UI state. Put side effects in dialog button `onClick` when the mutation is launched from a picker (see [dialogs.md](dialogs.md)).
+
+### Response guards
+
+Fail-fast after `ufetch`:
+
+1. Special non-success statuses first when relevant
+2. Invalid success → early `return toastError({ ... })`
+3. Success path without deep `else` nesting
+
+Prefer direct access on `response` (`response.status`) over optional chaining when the call is expected to return a body.
+
+---
+
+## `useUFetch` (reactive)
+
+For route/param/reactive-driven lists and detail loads:
+
+```ts
+const { data: ordersData, pending: isOrdersPending, refresh: refreshOrders } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}/orders`),
+  {
+    query: {
+      page: computed(() => currentPage.value - 1),
+      limit: itemsPerPage,
+      search: searchTerm,
+    },
+  },
+);
+```
+
+### Wrapping style (critical)
+
+Always format as:
+
+1. `const { ... } = useUFetch(` on the first line
+2. URL argument on the next line (string **or** `computed(() => ...)`)
+3. Optional options object as a multi-line second argument
+4. Closing `);` on its own line
+
+```ts
+// ✅ string URL + options
+const { data: mediaData, pending: isMediaPending, refresh: refreshMedia } = useUFetch(
+  '/api/media',
+  {
+    query: {
+      'sort': '_id:-1',
+      'limit': itemsPerPage,
+    },
+  },
+);
+
+// ✅ computed URL only
+const { data: patientData, pending: isPatientPending, refresh: refreshPatient } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}`),
+);
+
+// ❌ crammed one-liner or URL broken like ufetch's wrong form without the useUFetch indent pattern
+```
+
+### Destructuring names
+
+| Key | Convention | Example |
+|-----|------------|---------|
+| `data` | suffix `Data` | `ordersData`, `flashCardsData` |
+| `pending` | `is` + name + `Pending` | `isOrdersPending` |
+| `refresh` | prefix `refresh` | `refreshOrders` |
+
+### Spacing between consecutive calls
+
+When several `useUFetch` calls sit in the same section, use **one** blank line between them (not two):
+
+```ts
+const { data: mediaData, pending: isMediaPending, refresh: refreshMedia } = useUFetch(
+  '/api/media',
+  {
+    query: {
+      'limit': itemsPerPage,
+    },
+  },
+);
+
+const { data: mediaCountData, refresh: refreshMediaCount } = useUFetch(
+  '/api/media/count',
+);
+```
+
+Major section boundaries elsewhere still use double blanks.
+
+### Conditional fetching
+
+When the request must wait on a prop/id, prefer a reactive gate (e.g. reactive `method` or `enabled`) over one-shot `immediate: !!prop` evaluated only at mount:
+
+```ts
+const { data: itemsData, pending: isItemsPending, refresh: refreshItems } = useUFetch(
+  computed(() => `/api/groups/${props.groupUid}/items`),
+  {
+    method: computed(() => props.groupUid ? 'get' : ''),
+  },
+);
+```
+
+Do **not** use `{ immediate: !!props.groupUid }` when the dependency can appear later.
+
+### Query values
+
+- Refs and computeds are fine inside `query`
+- Keep query object multi-line with trailing commas
+- Quoted keys are fine when matching API conventions (`'filter'`, `'sort'`)
+
+---
+
+## Do / don’t
+
+**Do**
+
+- Use `ufetch` / `useUFetch` for app API traffic
+- Keep `ufetch(url, {` on one line; wrap `useUFetch` with URL on the next line
+- Refresh lists before clearing local form state after mutations
+
+**Don’t**
+
+- Reach for raw `$fetch` / `useFetch` for the same app API
+- Manually prepend `baseApiUrl`
+- Break `useUFetch` destructuring into ad-hoc formatting that hides the URL argument

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

@@ -0,0 +1,151 @@
+# Pages and routing
+
+Page shape conventions for Nuxt apps using this stack. Always combine with [code-style.md](code-style.md).
+
+## Page script skeleton
+
+```vue
+<script setup>
+
+/* page */
+
+definePageMeta({
+  name: 'dashboard.patients.single',
+});
+
+useHead({
+  title: $t('patients.single.pageTitle'),
+});
+
+
+const route = useRoute();
+
+const patientUid = computed(() => {
+  return route.params.patientUid;
+});
+
+
+/* data */
+
+const { data: patientData, pending: isPatientLoading, refresh: refreshPatient } = useUFetch(
+  computed(() => `/api/patients/${patientUid.value}`),
+);
+
+
+/* handlers */
+
+async function handleAction() {
+
+  ...
+
+}
+
+</script>
+
+
+<template>
+  <div>
+
+    <h1 class="text-2xl font-semibold">
+      {{ $t('patients.single.title') }}
+    </h1>
+
+    <!-- content -->
+
+  </div>
+</template>
+```
+
+## 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`)
+
+## `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',
+});
+```
+
+## Dynamic routes
+
+- 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`:
+
+```ts
+const route = useRoute();
+
+const flashCardSlug = computed(() => {
+  return route.params.flashCardSlug;
+});
+```
+
+## Navigation
+
+Always prefer **named routes**:
+
+```ts
+await navigateTo({
+  name: 'authentication.account',
+});
+```
+
+```vue
+<nuxt-link
+  :to="{
+    name: 'flash-cards.single',
+    params: {
+      flashCardSlug,
+    },
+  }">
+  ...
+</nuxt-link>
+```
+
+### Navigation in action objects
+
+When an action only navigates, use `to` — not `onClick: () => navigateTo(...)`:
+
+```ts
+{
+  icon: 'lucide:arrow-left',
+  label: 'Back',
+  to: {
+    name: 'orders.single',
+    params: {
+      orderUid,
+    },
+  },
+}
+```
+
+## Page headings
+
+- Primary title: `h1` with `class="text-2xl font-semibold"` (match local siblings if they consistently differ)
+- Subtitle / secondary line: size-based hierarchy (`text-sm` / `text-xs`) — see text-hierarchy rules in [code-style.md](code-style.md)
+
+## Item / tab object property order
+
+For objects in `:items` arrays (tabs, selects, menus):
+
+`value` → `icon` → `label` → other props
+
+```ts
+{
+  value: 'preview',
+  icon: 'lucide:eye',
+  label: $t('section.preview'),
+}
+```