nuxt-crud-modals 1.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Tobias Scheibling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+[![MIT License][license-src]][license-href]
+[![NuxtModules][modules-src]][modules-href]
+
+# Nuxt CRUD Modals
+
+Nuxt CRUD Modals is a lightweight module designed to streamline the creation, viewing and editing of (database) records through modal interfaces in Nuxt applications. It provides a simple and consistent way to handle CRUD-related UI patterns without repetitive boilerplate.
+
+Built on top of Nuxt UI’s modal system, it leverages `UModal` and `useOverlay` under the hood to deliver a flexible and extensible modal experience. The module abstracts common interaction patterns, allowing developers to quickly scaffold modals for different record types while maintaining full control over behavior and presentation.
+
+Whether you're building admin panels, dashboards or data-driven applications, Nuxt CRUD Modals module helps you reduce complexity and focus on your business logic by handling the modal lifecycle, state management and integration patterns for you.
+
+## Features
+
+- Open, view or edit modals based on record ID
+- Loading overlay for long running data fetching operations
+- `<UFormModal>` component for creating and editing data records
+- Coming soon: delete modals
+
+## Peer Dependencies
+
+Requires Nuxt UI and Zod 4
+
+## Quick Setup
+
+Install the module to your Nuxt application with one command:
+
+```bash
+npx nuxt module add nuxt-crud-modals
+```
+
+That's it! You can now use CRUD Modals in your Nuxt app
+
+## Options
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', 'nuxt-crud-modals'],
+  
+  //...
+
+  modals: {
+    loadingDelay: 700, // hides the loading overlay for 700 ms
+    prefix: 'U', // prefix for the components, e.g. UFormModal
+  },
+})
+```
+
+## Usage
+
+First, define a modal for your specific record type. You configure which components should be used for creating, editing, and viewing records, and optionally provide a data-fetching function:
+
+```ts
+import JobForm from '~/components/JobForm.vue'
+import JobView from '~/components/Job.vue'
+
+export const useJobModal = defineCrudModals({
+  components: {
+    create: JobForm,
+    edit: JobForm,
+    view: JobView
+  },
+  fetchData: async (id) => {
+    // your data fetching logic
+    return {
+      id,
+      title: 'Sample job',
+      status: 'In progress',
+      comment: 'Additional briefing needed'
+    }
+  }
+})
+```
+
+### Open modal to edit a record
+To open the modal in edit mode, call `openToEdit` with the record ID:
+
+```ts
+const jobModal = useJobModal()
+jobModal.openToEdit(123)
+```
+
+### Open modal with initial state to create a new record
+To create a new record, use `openToCreate`. You can optionally pass an initial state:
+
+```ts
+const jobModal = useJobModal()
+jobModal.openToCreate({ status: 'New' })
+```
+
+This will open the modal providing the initial state in the modal to prefill the form.
+
+## Local development
+
+```bash
+# Install dependencies
+npm install
+  
+# Generate type stubs
+npm run dev:prepare
+  
+# Develop with the playground
+npm run dev
+  
+# Build the playground
+npm run dev:build
+  
+# Run ESLint
+npm run lint
+  
+# Run Vitest
+npm run test
+npm run test:watch
+  
+# Release new version
+npm run release
+```
+
+[license-src]: https://img.shields.io/github/license/tosling/nuxt-crud-modals
+[license-href]: ./LICENSE
+
+[modules-src]: https://img.shields.io/badge/Nuxt%20Module-gray?logo=nuxt
+[modules-href]: https://nuxt.com/modules

package/dist/module.d.mts

@@ -0,0 +1,17 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+declare module '@nuxt/schema' {
+    interface PublicRuntimeConfig {
+        modals: {
+            loadingDelay: number;
+        };
+    }
+}
+interface ModuleOptions {
+    loadingDelay: number;
+    prefix: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-crud-modals",
+  "configKey": "modals",
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "version": "1.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,41 @@
+import { defineNuxtModule, createResolver, addComponentsDir, addImports } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-crud-modals",
+    configKey: "modals",
+    compatibility: {
+      nuxt: ">=4.0.0"
+    }
+  },
+  // default configuration options of the module
+  defaults: {
+    prefix: "U",
+    loadingDelay: 500
+    // ms
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.modals = defu(
+      nuxt.options.runtimeConfig.public.modals,
+      {
+        loadingDelay: options.loadingDelay
+      }
+    );
+    addComponentsDir({
+      path: resolve("runtime/app/components"),
+      prefix: options.prefix
+    });
+    addImports({
+      name: "useLoadingOverlay",
+      from: resolve("runtime/app/composables/useLoadingOverlay")
+    });
+    addImports({
+      name: "defineCrudModals",
+      from: resolve("runtime/app/utils/modalFactory")
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/components/FormModal.d.vue.ts

@@ -0,0 +1,38 @@
+import type { ZodType } from 'zod';
+import type { FormSubmitEvent } from '@nuxt/ui';
+import type { CrudModalResult } from '../utils/modalFactory.js';
+declare const __VLS_export: <T extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<({
+        schema: ZodType<T>;
+        initialState: T;
+        onSubmit: (event: FormSubmitEvent<T>) => void | Promise<void>;
+    } & {
+        open?: boolean;
+    }) & {
+        onClose?: ((value: CrudModalResult) => any) | undefined;
+        "onUpdate:open"?: ((value: boolean | undefined) => any) | undefined;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: import("vue").ShallowUnwrapRef<{
+        setError: (message: string) => void;
+    }>) => void;
+    attrs: any;
+    slots: {
+        fields?: (props: {
+            state: import("@vue/reactivity").DistributeRef<import("vue").Reactive<T>>;
+        }) => any;
+    } & {
+        buttons?: (props: {}) => any;
+    };
+    emit: ((evt: "close", value: CrudModalResult) => void) & ((event: "update:open", value: boolean | undefined) => void);
+}>) => import("vue").VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/app/components/FormModal.vue

@@ -0,0 +1,80 @@
+<template>
+  <UModal v-model:open="open">
+    <template #body>
+      <UForm
+        ref="form"
+        class="space-y-4"
+        :state="state"
+        :schema="schema"
+        @submit="submit"
+      >
+        <slot
+          name="fields"
+          :state="state"
+        />
+
+        <UAlert
+          v-if="error"
+          :description="error"
+          variant="subtle"
+          color="error"
+          icon="i-lucide-triangle-alert"
+        />
+
+        <div class="flex flex-row-reverse gap-2">
+          <slot name="buttons">
+            <UButton
+              type="submit"
+              loading-auto
+            >
+              Submit
+            </UButton>
+          </slot>
+        </div>
+      </UForm>
+    </template>
+  </UModal>
+</template>
+
+<script setup>
+import { reactive, ref, useTemplateRef, watch } from "vue";
+const props = defineProps({
+  schema: { type: Object, required: true },
+  initialState: { type: null, required: true },
+  onSubmit: { type: Function, required: true }
+});
+const emit = defineEmits(["close"]);
+const error = ref();
+const open = defineModel("open", { type: Boolean });
+const form = useTemplateRef("form");
+const state = reactive({ ...props.initialState });
+function setError(message) {
+  error.value = message;
+}
+defineExpose({ setError });
+async function submit(event) {
+  try {
+    await props.onSubmit(event);
+    emit("close", { success: true });
+    open.value = false;
+  } catch (err) {
+    error.value = "Unknown error";
+    if (err instanceof Error)
+      error.value = err.message;
+  }
+}
+watch(open, (newVal) => {
+  if (newVal) {
+    Object.assign(state, props.initialState);
+    error.value = void 0;
+  }
+});
+watch(
+  () => form.value?.dirty,
+  (newVal) => {
+    if (newVal) {
+      error.value = void 0;
+    }
+  }
+);
+</script>

package/dist/runtime/app/components/FormModal.vue.d.ts

@@ -0,0 +1,38 @@
+import type { ZodType } from 'zod';
+import type { FormSubmitEvent } from '@nuxt/ui';
+import type { CrudModalResult } from '../utils/modalFactory.js';
+declare const __VLS_export: <T extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<({
+        schema: ZodType<T>;
+        initialState: T;
+        onSubmit: (event: FormSubmitEvent<T>) => void | Promise<void>;
+    } & {
+        open?: boolean;
+    }) & {
+        onClose?: ((value: CrudModalResult) => any) | undefined;
+        "onUpdate:open"?: ((value: boolean | undefined) => any) | undefined;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: import("vue").ShallowUnwrapRef<{
+        setError: (message: string) => void;
+    }>) => void;
+    attrs: any;
+    slots: {
+        fields?: (props: {
+            state: import("@vue/reactivity").DistributeRef<import("vue").Reactive<T>>;
+        }) => any;
+    } & {
+        buttons?: (props: {}) => any;
+    };
+    emit: ((evt: "close", value: CrudModalResult) => void) & ((event: "update:open", value: boolean | undefined) => void);
+}>) => import("vue").VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/app/components/LoadingOverlay.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/components/LoadingOverlay.vue

@@ -0,0 +1,51 @@
+<template>
+  <Teleport to="body">
+    <Transition
+      appear
+      enter-active-class="transition-opacity duration-150 ease-out"
+      enter-from-class="opacity-0"
+      enter-to-class="opacity-100"
+      leave-active-class="transition-opacity duration-100 ease-in"
+      leave-from-class="opacity-100"
+      leave-to-class="opacity-0"
+    >
+      <div
+        v-if="state.isActive && state.blocking"
+        class="fixed inset-0 z-100 flex items-center justify-center cursor-progress"
+        :class="{
+  'bg-elevated/75': state.backdrop
+}"
+      >
+        <Transition
+          enter-active-class="transition-all duration-300 ease-out"
+          leave-active-class="transition-all duration-200 ease-in"
+          enter-from-class="opacity-0 scale-95"
+          enter-to-class="opacity-100 scale-100"
+          leave-from-class="opacity-100 scale-100"
+          leave-to-class="opacity-0 scale-95"
+        >
+          <div
+            v-if="state.isVisible"
+            class="bg-default rounded-lg shadow-lg ring ring-default p-4 sm:p-6 flex flex-col items-center gap-2 min-w-30"
+          >
+            <UIcon
+              name="i-lucide-loader-circle"
+              class="size-8 text-primary animate-spin"
+            />
+            <span
+              v-if="state.label"
+              class="text-sm text-muted font-medium"
+            >
+              {{ state.label }}
+            </span>
+          </div>
+        </Transition>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
+
+<script setup>
+import { useLoadingOverlay } from "../composables/useLoadingOverlay";
+const { state } = useLoadingOverlay();
+</script>

package/dist/runtime/app/components/LoadingOverlay.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/composables/useLoadingOverlay.d.ts

@@ -0,0 +1,24 @@
+export declare const useLoadingOverlay: () => {
+    state: Readonly<import("vue").Ref<{
+        readonly isActive: boolean;
+        readonly isVisible: boolean;
+        readonly backdrop: boolean;
+        readonly blocking: boolean;
+        readonly delay: number;
+        readonly label: string | null;
+    }, {
+        readonly isActive: boolean;
+        readonly isVisible: boolean;
+        readonly backdrop: boolean;
+        readonly blocking: boolean;
+        readonly delay: number;
+        readonly label: string | null;
+    }>>;
+    show: (options?: {
+        backdrop?: boolean;
+        blocking?: boolean;
+        delay?: number;
+        label?: string | null;
+    }) => void;
+    hide: () => void;
+};

package/dist/runtime/app/composables/useLoadingOverlay.js

@@ -0,0 +1,36 @@
+import { useRuntimeConfig, useState } from "#app";
+import { readonly } from "vue";
+let timer = null;
+export const useLoadingOverlay = () => {
+  const config = useRuntimeConfig();
+  const loadingDelay = config.public.modals.loadingDelay;
+  const state = useState("loading-overlay", () => ({
+    isActive: false,
+    isVisible: false,
+    backdrop: false,
+    blocking: true,
+    delay: loadingDelay,
+    label: "Loading..."
+  }));
+  function show(options) {
+    state.value.backdrop = options?.backdrop === true ? true : false;
+    state.value.blocking = options?.blocking === false ? false : true;
+    state.value.delay = options?.delay ?? loadingDelay;
+    state.value.label = options?.label === null ? null : "Loading...";
+    state.value.isActive = true;
+    timer = setTimeout(() => state.value.isVisible = true, state.value.delay);
+  }
+  function hide() {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    state.value.isActive = false;
+    state.value.isVisible = false;
+  }
+  return {
+    state: readonly(state),
+    show,
+    hide
+  };
+};

package/dist/runtime/app/utils/modalFactory.d.ts

@@ -0,0 +1,26 @@
+import { type Component } from 'vue';
+type RecordId = string | number;
+type CrudModalMode = 'create' | 'read' | 'update';
+export type CrudModalResult = {
+    success: boolean;
+};
+type CrudModalConfig<TRecord extends {
+    id: RecordId;
+}> = {
+    components: Partial<Record<CrudModalMode, Component>>;
+    fetchData?: (id: RecordId) => Promise<TRecord>;
+};
+export declare function defineCrudModals<TRecord extends {
+    id: RecordId;
+}>(config: CrudModalConfig<TRecord>): () => {
+    data: [TRecord | null] extends [import("vue").Ref<any, any>] ? import("@vue/shared").IfAny<import("vue").Ref<any, any> & TRecord, import("vue").Ref<import("vue").Ref<any, any> & TRecord, import("vue").Ref<any, any> & TRecord>, import("vue").Ref<any, any> & TRecord> : import("vue").Ref<import("vue").UnwrapRef<TRecord> | null, TRecord | import("vue").UnwrapRef<TRecord> | null>;
+    error: import("vue").Ref<string | null, string | null>;
+    isLoading: import("vue").Ref<boolean, boolean>;
+    isOpen: import("vue").Ref<boolean, boolean>;
+    openToCreate: (initialState?: Partial<TRecord>) => Promise<CrudModalResult | undefined>;
+    openToRead: (id: RecordId) => Promise<CrudModalResult | undefined>;
+    openToUpdate: (id: RecordId) => Promise<CrudModalResult | undefined>;
+    refresh: () => Promise<void>;
+    reset: () => void;
+};
+export {};

package/dist/runtime/app/utils/modalFactory.js

@@ -0,0 +1,90 @@
+import { createError } from "#app";
+import { useLoadingOverlay } from "#imports";
+import { useOverlay } from "@nuxt/ui/runtime/composables/useOverlay.js";
+import { useToast } from "@nuxt/ui/runtime/composables/useToast.js";
+import { ref } from "vue";
+export function defineCrudModals(config) {
+  const overlay = useOverlay();
+  const data = ref(null);
+  const error = ref(null);
+  const isLoading = ref(false);
+  const isOpen = ref(false);
+  function resolveComponent(mode) {
+    if (!config.components[mode])
+      throw createError({
+        status: 500,
+        statusText: `No component registered for modal mode '${mode}'`
+      });
+    return config.components[mode];
+  }
+  async function fetchData(id) {
+    if (!config.fetchData) return;
+    setLoading(true);
+    try {
+      data.value = await config.fetchData(id);
+    } catch (err) {
+      const toast = useToast();
+      toast.add({
+        title: "Failed to fetch record",
+        description: err instanceof Error ? err.message : "Unknown error",
+        color: "error"
+      });
+    } finally {
+      setLoading(false);
+    }
+  }
+  async function open(mode, payload) {
+    reset();
+    const component = resolveComponent(mode);
+    if (mode !== "create") {
+      const { id } = payload;
+      if (!id) throw new Error(`Mode '${mode}' requires an id`);
+      await fetchData(id);
+      if (!data.value) return;
+    } else if (mode === "create") {
+      const { initialState } = payload;
+      data.value = initialState;
+    }
+    isOpen.value = true;
+    const promise = overlay.create(component).open({ mode, ...payload });
+    promise.finally(() => isOpen.value = false);
+    return promise;
+  }
+  function openToRead(id) {
+    return open("read", { id });
+  }
+  function openToUpdate(id) {
+    return open("update", { id });
+  }
+  function openToCreate(initialState) {
+    return open("create", { initialState });
+  }
+  async function refresh() {
+    if (!data.value?.id) return;
+    return fetchData(data.value.id);
+  }
+  function reset() {
+    data.value = null;
+    error.value = null;
+    isOpen.value = false;
+  }
+  function setLoading(loading) {
+    isLoading.value = loading;
+    if (!isOpen.value) {
+      const loadingOverlay = useLoadingOverlay();
+      if (loading) loadingOverlay.show();
+      else loadingOverlay.hide();
+    }
+  }
+  return () => ({
+    data,
+    error,
+    isLoading,
+    isOpen,
+    openToCreate,
+    openToRead,
+    openToUpdate,
+    refresh,
+    reset
+  });
+}

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "nuxt-crud-modals",
+  "version": "1.1.0",
+  "description": "Nuxt UI compatible module to handle modals for creating, editing and viewing id based records",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tosling/nuxt-crud-modals.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.4.2",
+    "defu": "^6.1.6"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/eslint-config": "^1.15.2",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.4.2",
+    "@nuxt/test-utils": "^4.0.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.1.0",
+    "nuxt": "^4.4.2",
+    "typescript": "~6.0.2",
+    "vitest": "^4.1.2",
+    "vue-tsc": "^3.2.6"
+  },
+  "peerDependencies": {
+    "@nuxt/ui": "^4.6.0",
+    "nuxt": "^4.4.2",
+    "zod": "^4.0.0"
+  }
+}