@ciwergrp/nuxid 1.6.2 → 1.6.4

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@ciwergrp/nuxid",
   "configKey": "nuxid",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/route/route-query.d.ts

@@ -1,3 +1,4 @@
+import type { LocationQueryRaw } from 'vue-router';
 export declare function useRouteQuery(): {
-    URLRouteQuery: (query: any, route?: string) => Promise<void | import("vue-router").NavigationFailure | undefined>;
+    URLRouteQuery: (query: LocationQueryRaw, route?: string) => Promise<void | import("vue-router").NavigationFailure | undefined>;
 };

package/dist/runtime/route/route-query.js

@@ -1,14 +1,18 @@
 import { useRoute, useRouter } from "vue-router";
 export function useRouteQuery() {
+  const currentRoute = useRoute();
+  const router = useRouter();
   const URLRouteQuery = (query, route) => {
-    const $route = useRoute();
-    const router = useRouter();
+    const mergedQuery = {
+      ...currentRoute.query,
+      ...query
+    };
+    const nextQuery = Object.fromEntries(
+      Object.entries(mergedQuery).filter(([, value]) => value !== void 0)
+    );
     return router.push({
-      path: route,
-      query: {
-        ...$route.query,
-        ...query
-      }
+      path: route ?? currentRoute.path,
+      query: nextQuery
     });
   };
   return {

package/docs/.docs/built-in-modules/element-plus.md

@@ -0,0 +1,28 @@
+# @element-plus/nuxt
+
+Nuxus can install and configure Element Plus via `elementPlus` options.
+
+## Enable
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    elementPlus: true,
+  },
+})
+```
+
+## Configure
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    elementPlus: {
+      enabled: true,
+      config: {
+        // @element-plus/nuxt options
+      },
+    },
+  },
+})
+```

package/docs/.docs/built-in-modules/index.md

@@ -0,0 +1,15 @@
+---
+title: Built-In Modules
+---
+
+# Built-In Modules
+
+These are Nuxt-only modules that Nuxus can configure or integrate with.
+
+## Modules
+
+- [lodash](/built-in-modules/lodash)
+- [@element-plus/nuxt](/built-in-modules/element-plus)
+- [@nuxt/icon](/built-in-modules/nuxt-icon)
+- [@vueuse/nuxt](/built-in-modules/vueuse)
+- [@sentry/nuxt](/built-in-modules/sentry)

package/docs/.docs/built-in-modules/lodash.md

@@ -0,0 +1,14 @@
+# lodash
+
+Nuxus can auto-import lodash helpers when `lodash` is enabled.
+
+## Enable
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    lodash: true,
+  },
+})
+```
+

package/docs/.docs/built-in-modules/nuxt-icon.md

@@ -0,0 +1,31 @@
+# @nuxt/icon
+
+Nuxus can install and configure @nuxt/icon via the `icon` options.
+
+## Enable
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    icon: true,
+  },
+})
+```
+
+## Configure
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    icon: {
+      enabled: true,
+      config: {
+        componentName: 'KIcon',
+        size: '1.25em',
+        class: 'align-middle inline-block text-current',
+        mode: 'svg',
+      },
+    },
+  },
+})
+```

package/docs/.docs/built-in-modules/sentry.md

@@ -0,0 +1,13 @@
+# @sentry/nuxt
+
+Nuxus declares @sentry/nuxt as a module dependency. Configure it in your Nuxt config as needed.
+
+## Configure
+
+```ts
+export default defineNuxtConfig({
+  sentry: {
+    // @sentry/nuxt options
+  },
+})
+```

package/docs/.docs/built-in-modules/vueuse.md

@@ -0,0 +1,28 @@
+# @vueuse/nuxt
+
+Nuxus integrates with VueUse and can manage auto-import exclusions.
+
+## Enable
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    vueuse: true,
+  },
+})
+```
+
+## Configure
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    vueuse: {
+      enabled: true,
+      autoImports: true,
+      ssrHandlers: false,
+      exclude: [],
+    },
+  },
+})
+```

package/docs/.docs/composables/use-breadcrumbs.md

@@ -0,0 +1,53 @@
+# useBreadcrumbs
+
+`useBreadcrumbs` stores and exposes breadcrumb state in Nuxt app state.
+
+## Signature
+
+```ts
+const {
+  breadcrumbs,
+  activeBreadcrumb,
+  setBreadcrumbs,
+} = useBreadcrumbs()
+```
+
+## Params
+
+- None.
+
+## Types
+
+```ts
+type BreadcrumbItem = {
+  name: string
+  path: string
+}
+
+type UseBreadcrumbsReturn = {
+  breadcrumbs: Readonly<Ref<BreadcrumbItem[]>>
+  activeBreadcrumb: ComputedRef<BreadcrumbItem | null>
+  setBreadcrumbs: (value: BreadcrumbItem[]) => void
+}
+```
+
+## Returns
+
+- `breadcrumbs`: readonly breadcrumb list.
+- `activeBreadcrumb`: computed last breadcrumb item or `null`.
+- `setBreadcrumbs(value)`: replaces breadcrumb list.
+
+## Example
+
+```ts
+const { breadcrumbs, activeBreadcrumb, setBreadcrumbs } = useBreadcrumbs()
+
+setBreadcrumbs([
+  { name: 'Home', path: '/' },
+  { name: 'Products', path: '/products' },
+])
+
+console.log(breadcrumbs.value.length) // 2
+console.log(activeBreadcrumb.value?.name) // Products
+```
+

package/docs/.docs/composables/use-cursor-http.md

@@ -0,0 +1,56 @@
+# useCursorHttp
+
+`useCursorHttp` wraps cursor-based APIs for infinite lists. It merges new pages, exposes `loadMore` and `refresh`, and can poll for new items.
+
+## Signature
+
+```ts
+const result = await useCursorHttp(url, options?)
+```
+
+## Options
+
+- `lazy` (boolean): skip the first fetch until `init()` is called.
+- `immediate` (boolean): run the first fetch on creation. Default: `true`.
+- `pollInterval` (number): poll interval in ms for new items.
+- `fetcher` (function): custom fetcher. Defaults to Nuxt `$fetch`.
+- `fetchOptions` (object): passed to `$fetch`, supports refs for reactive params.
+- `meta` (object): response meta keys.
+- `meta.cursorKey` (string): key for the next cursor. Default: `afterCursor`.
+- `meta.hasMoreKey` (string): key for more data. Default: `hasMore`.
+- `itemKey` (string): unique item id to dedupe polls. Default: `id`.
+- `cursorParam` (string): query param for cursor. Default: `cursor`.
+
+## Returns
+
+- `data` (ref): response data with merged pages.
+- `loading` (readonly ref)
+- `error` (readonly ref)
+- `hasNextPage` (readonly ref)
+- `isLoadMoreTriggered` (readonly ref)
+- `loadMore()` (function)
+- `refresh()` (function)
+- `init()` (function)
+
+## Examples
+
+Basic usage:
+
+```ts
+const {
+  data,
+  loading,
+  hasNextPage,
+  loadMore,
+} = await useCursorHttp('/api/articles')
+```
+
+Custom cursor keys and polling:
+
+```ts
+const result = await useCursorHttp('/api/articles', {
+  meta: { cursorKey: 'nextCursor', hasMoreKey: 'hasMore' },
+  cursorParam: 'after',
+  pollInterval: 10000,
+})
+```

package/docs/.docs/composables/use-http.md

@@ -0,0 +1,57 @@
+# useHttp
+
+`useHttp` builds a reactive form object with submit helpers that use Nuxt `$fetch`. It normalizes strings and nested values, supports `FormData` when files are present, and tracks `processing`, `errors`, and `response`.
+
+## Signature
+
+```ts
+const form = useHttp(initialData, formOptions)
+```
+
+## Options
+
+- `alwaysFormData` (boolean): force `FormData` even when there are no files.
+- `fetcher` (function): custom fetcher. Defaults to Nuxt `$fetch`.
+- `fetchOptions` (object): shared options passed to `$fetch` (headers, onResponse, etc).
+
+## Returns
+
+The returned object includes your initial fields plus:
+
+- `submit(method, url, options?)`
+- `post(url, options?)`
+- `patch(url, options?)`
+- `put(url, options?)`
+- `delete(url, options?)`
+- `processing` (boolean)
+- `errors` (any)
+- `response` (object | null)
+
+## Examples
+
+Basic submit:
+
+```ts
+const form = useHttp({ name: '', avatar: null })
+
+await form.post('/api/users')
+```
+
+Send multipart data and attach hooks:
+
+```ts
+const form = useHttp(
+  { name: '', avatar: null, tags: [] },
+  {
+    alwaysFormData: true,
+    fetchOptions: {
+      onResponse({ response }) {
+        console.log('ok', response.ok)
+      },
+    },
+  },
+)
+
+await form.post('/api/users')
+```
+

package/docs/.docs/composables/use-pinia.md

@@ -0,0 +1,65 @@
+# usePinia
+
+`usePinia` returns the active Pinia instance from Nuxt. Use it when you need to pass the instance explicitly to a store or to work outside the standard auto-import context.
+
+This composable is available when the `pinia` feature is enabled in `nuxid`.
+
+## Enable
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    pinia: true,
+  },
+})
+```
+
+## Configure
+
+```ts
+export default defineNuxtConfig({
+  nuxid: {
+    pinia: {
+      enabled: true,
+      storesDirs: ['stores'],
+    },
+  },
+})
+```
+
+## Signature
+
+```ts
+const pinia = usePinia()
+```
+
+## Returns
+
+- The Pinia instance injected by Nuxt.
+
+## Auto-imports
+
+When enabled, Nuxus auto-imports common Pinia helpers:
+
+- `defineStore`
+- `definePiniaStore` (alias of `defineStore`)
+- `acceptHMRUpdate`
+- `storeToRefs`
+- `usePinia`
+
+## Examples
+
+Use with a store:
+
+```ts
+const pinia = usePinia()
+const userStore = useUserStore(pinia)
+```
+
+Create a store with auto-imported helpers:
+
+```ts
+const useUserStore = defineStore('user', {
+  state: () => ({ name: '' }),
+})
+```

package/docs/.docs/composables/use-query-filters.md

@@ -0,0 +1,88 @@
+# useQueryFilters
+
+`useQueryFilters` builds active filter chips from route query and provides helpers to apply, reset, and remove filters.
+
+## Signature
+
+```ts
+const {
+  activeFilters,
+  applyFilters,
+  resetFilters,
+  handleFilterChange,
+  normalizeQueryValue,
+} = useQueryFilters(definitions)
+```
+
+## Params
+
+- `definitions: QueryFilterDefinition[]`
+
+## Types
+
+```ts
+import type { LocationQuery, LocationQueryValue } from 'vue-router'
+
+type ActiveQueryFilter = {
+  key: string
+  label: string
+  value: string
+  displayValue: string
+}
+
+type QueryFilterDefinition = {
+  key: string
+  label: string
+  clearQueryKeys: string[]
+  resolve: (query: LocationQuery) => { value: string; displayValue: string } | null
+}
+```
+
+```ts
+type FilterChangePayload = {
+  key: string
+  active: boolean
+}
+
+type UseQueryFiltersReturn = {
+  activeFilters: ComputedRef<ActiveQueryFilter[]>
+  applyFilters: (query: Record<string, any>, callback?: () => void | Promise<void>) => Promise<void>
+  resetFilters: (queryKeys: string[], callback?: () => void | Promise<void>) => Promise<void>
+  handleFilterChange: (payload: FilterChangePayload, callback?: () => void | Promise<void>) => Promise<void>
+  normalizeQueryValue: (value: LocationQueryValue | LocationQueryValue[] | undefined) => LocationQueryValue | undefined
+}
+```
+
+## API
+
+- `activeFilters`: computed active filters resolved from route query.
+- `applyFilters(query, callback?)`: merges query and pushes route.
+- `resetFilters(queryKeys, callback?)`: removes specified query keys.
+- `handleFilterChange(payload, callback?)`: removes query keys defined in matching filter when `payload.active` is `false`.
+- `normalizeQueryValue(value)`: returns first value for array query params.
+
+## Example
+
+```ts
+const definitions = [
+  {
+    key: 'status',
+    label: 'Status',
+    clearQueryKeys: ['status'],
+    resolve: (query) => {
+      const value = query.status
+      if (!value || Array.isArray(value)) {
+        return null
+      }
+
+      return { value, displayValue: value }
+    },
+  },
+]
+
+const { activeFilters, applyFilters, resetFilters } = useQueryFilters(definitions)
+
+await applyFilters({ status: 'active' })
+await resetFilters(['status'])
+```
+

package/docs/.docs/composables/use-route-query.md

@@ -0,0 +1,39 @@
+# useRouteQuery
+
+`useRouteQuery` is a small helper to push merged query params to the router.
+
+## Signature
+
+```ts
+const { URLRouteQuery } = useRouteQuery()
+```
+
+## Params
+
+- None.
+
+## Types
+
+```ts
+type URLRouteQuery = (query: any, route?: string) => Promise<void>
+
+type UseRouteQueryReturn = {
+  URLRouteQuery: URLRouteQuery
+}
+```
+
+## API
+
+- `URLRouteQuery(query, route?)`
+- `query`: query values to merge with current route query.
+- `route` (optional): target path. If omitted, current path is used.
+
+## Example
+
+```ts
+const { URLRouteQuery } = useRouteQuery()
+
+await URLRouteQuery({ page: 2, sort: 'desc' })
+await URLRouteQuery({ category: 'books' }, '/products')
+```
+

package/docs/.docs/composables/use-title.md

@@ -0,0 +1,48 @@
+# useTitle
+
+`useTitle` manages the current document title and provides helpers to read, set, and reset it using `runtimeConfig.public.appTitle`.
+
+## Signature
+
+```ts
+const {
+  title,
+  getTitle,
+  setTitle,
+  resetTitle,
+} = useTitle()
+```
+
+## Params
+
+- None.
+
+## Types
+
+```ts
+type UseTitleReturn = {
+  title: Readonly<Ref<string>>
+  getTitle: () => string
+  setTitle: (value: string) => void
+  resetTitle: () => void
+}
+```
+
+## Returns
+
+- `title`: readonly reactive title value.
+- `getTitle()`: returns the current title string.
+- `setTitle(value)`: sets the title and updates `<head><title>`.
+- `resetTitle()`: resets title to `runtimeConfig.public.appTitle` and updates `<head><title>`.
+
+## Example
+
+```ts
+const { title, setTitle, resetTitle } = useTitle()
+
+setTitle('Dashboard')
+console.log(title.value) // Dashboard
+
+resetTitle()
+```
+

package/docs/.docs/composables/use-version-updater.md

@@ -0,0 +1,38 @@
+# useVersionUpdater
+
+`useVersionUpdater` exposes a reactive flag that turns `true` after Nuxt emits `app:manifest:update`.
+
+## Signature
+
+```ts
+const { isNewVersionAvailable } = useVersionUpdater()
+```
+
+## Params
+
+- None.
+
+## Types
+
+```ts
+type UseVersionUpdaterReturn = {
+  isNewVersionAvailable: Readonly<Ref<boolean>>
+}
+```
+
+## Returns
+
+- `isNewVersionAvailable`: readonly ref, default `false`, becomes `true` once a new app manifest version is detected.
+
+## Example
+
+```ts
+const { isNewVersionAvailable } = useVersionUpdater()
+
+watch(isNewVersionAvailable, (available) => {
+  if (available) {
+    console.log('A new version is available')
+  }
+})
+```
+