@mapomodule/form 2.0.0-beta.0

package/src/__tests__/useMapoForm.test.ts

@@ -0,0 +1,319 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ref } from "vue";
+import { useMapoForm } from "../runtime/composables/useMapoForm.js";
+import { defaultRegistry } from "../runtime/registry/defaults.js";
+import type { FieldDescriptor } from "../runtime/types/descriptor.js";
+
+vi.mock("@mapomodule/store/runtime/stores/auth", () => ({
+  useAuthStore: () => ({ info: { id: 1, username: "testuser" } }),
+}));
+vi.mock("@mapomodule/store/runtime/stores/snack", () => ({
+  useSnackStore: () => ({ show: vi.fn() }),
+}));
+
+// provide/inject called outside setup() emits a warning; silence it in tests.
+beforeEach(() => {
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+interface Article {
+  title: string;
+  slug: string;
+  is_draft: boolean;
+  count: number;
+  translations: Record<string, Partial<Article>>;
+}
+
+function makeForm(overrides: Partial<Article> = {}) {
+  const model = ref<Article>({
+    title: "",
+    slug: "",
+    is_draft: false,
+    count: 0,
+    translations: {},
+    ...overrides,
+  });
+
+  const fields = ref<FieldDescriptor<Article>[]>([
+    { key: "title", type: "text" as const },
+    { key: "slug", type: "text" as const },
+    { key: "is_draft", type: "switch" as const },
+    { key: "count", type: "number" as const },
+  ]);
+
+  const form = useMapoForm({
+    model,
+    fields,
+    registry: defaultRegistry,
+    immediate: true,
+  });
+
+  return { model, form };
+}
+
+// ─── isDirty ─────────────────────────────────────────────────────────────────
+
+describe("isDirty", () => {
+  it("is false on init", () => {
+    const { form } = makeForm();
+    expect(form.isDirty.value).toBe(false);
+  });
+
+  it("is true after setFieldValue", () => {
+    const { form } = makeForm();
+    form.setFieldValue("title", "Hello");
+    expect(form.isDirty.value).toBe(true);
+  });
+
+  it("resets to false after resetDirty", () => {
+    const { form } = makeForm();
+    form.setFieldValue("title", "Hello");
+    form.resetDirty();
+    expect(form.isDirty.value).toBe(false);
+  });
+});
+
+// ─── setFieldValue / getFieldValue ───────────────────────────────────────────
+
+describe("setFieldValue", () => {
+  it("writes the value to model", () => {
+    const { model, form } = makeForm();
+    form.setFieldValue("title", "Mapo");
+    expect(model.value.title).toBe("Mapo");
+  });
+
+  it("writes nested path (dotted key)", () => {
+    const { model } = makeForm();
+    // meta.slug is intentionally not a key of Article — tests runtime dotted-path writes on arbitrary paths
+    const extendedFields = ref<FieldDescriptor<any>[]>([
+      { key: "meta.slug", type: "text" as const },
+    ]);
+    const extForm = useMapoForm({
+      model,
+      fields: extendedFields,
+      registry: defaultRegistry,
+      immediate: true,
+    });
+    extForm.setFieldValue("meta.slug", "hello");
+    expect((model.value as any).meta.slug).toBe("hello");
+  });
+});
+
+describe("getFieldValue", () => {
+  it("reads the current value", () => {
+    const { form } = makeForm({ title: "Existing" });
+    expect(form.getFieldValue({ key: "title", type: "text" })).toBe("Existing");
+  });
+});
+
+// ─── getPatch ────────────────────────────────────────────────────────────────
+
+describe("getPatch", () => {
+  it("returns empty on no changes", () => {
+    const { form } = makeForm();
+    expect(form.getPatch()).toEqual({});
+  });
+
+  it("returns only changed fields", () => {
+    const { form } = makeForm({ title: "Old", slug: "old-slug" });
+    form.setFieldValue("title", "New");
+    const patch = form.getPatch();
+    expect(patch).toHaveProperty("title", "New");
+    expect(patch).not.toHaveProperty("slug");
+  });
+});
+
+// ─── validateClient ───────────────────────────────────────────────────────────
+
+describe("validateClient", () => {
+  it("returns valid=true when no validate callbacks", () => {
+    const { form } = makeForm();
+    const { valid } = form.validateClient();
+    expect(valid).toBe(true);
+  });
+
+  it("returns valid=false when a validate callback returns error", () => {
+    const model = ref<Article>({
+      title: "",
+      slug: "",
+      is_draft: false,
+      count: 0,
+      translations: {},
+    });
+    const fields = ref<FieldDescriptor<Article>[]>([
+      {
+        key: "title",
+        type: "text" as const,
+        validate: (val: unknown) => (val ? null : "Required"),
+      },
+    ]);
+    const form = useMapoForm({
+      model,
+      fields,
+      registry: defaultRegistry,
+      immediate: true,
+    });
+    const { valid, errors } = form.validateClient();
+    expect(valid).toBe(false);
+    expect(errors.title).toBe("Required");
+  });
+
+  it("returns valid=true when validate callback returns null", () => {
+    const model = ref<Article>({
+      title: "Hello",
+      slug: "",
+      is_draft: false,
+      count: 0,
+      translations: {},
+    });
+    const fields = ref<FieldDescriptor<Article>[]>([
+      {
+        key: "title",
+        type: "text" as const,
+        validate: (val: unknown) => (val ? null : "Required"),
+      },
+    ]);
+    const form = useMapoForm({
+      model,
+      fields,
+      registry: defaultRegistry,
+      immediate: true,
+    });
+    expect(form.validateClient().valid).toBe(true);
+  });
+});
+
+// ─── i18n: translatable + initLang ───────────────────────────────────────────
+
+describe("translatable fields", () => {
+  it("writes to translations.<lang>.<key>", () => {
+    const model = ref<Article>({
+      title: "",
+      slug: "",
+      is_draft: false,
+      count: 0,
+      translations: {},
+    });
+    const fields = ref<FieldDescriptor<Article>[]>([
+      { key: "title", type: "text" as const, translatable: true },
+    ]);
+    const currentLang = ref("it");
+    const form = useMapoForm({
+      model,
+      fields,
+      registry: defaultRegistry,
+      immediate: true,
+      currentLang,
+    });
+    form.setFieldValue("title", "Ciao");
+    expect(model.value.translations?.it?.title).toBe("Ciao");
+  });
+
+  it("auto-initializes translations[lang] = {} (initLang)", () => {
+    const model = ref<Article>({
+      title: "",
+      slug: "",
+      is_draft: false,
+      count: 0,
+      translations: {},
+    });
+    const fields = ref<FieldDescriptor<Article>[]>([
+      { key: "title", type: "text" as const, translatable: true },
+    ]);
+    const currentLang = ref("de");
+    const form = useMapoForm({
+      model,
+      fields,
+      registry: defaultRegistry,
+      immediate: true,
+      currentLang,
+    });
+    form.setFieldValue("title", "Hallo");
+    expect(model.value.translations).toHaveProperty("de");
+  });
+
+  it("propagates synci18n to all languages", () => {
+    const model = ref<Article>({
+      title: "",
+      slug: "",
+      is_draft: false,
+      count: 0,
+      translations: {},
+    });
+    const fields = ref<FieldDescriptor<Article>[]>([
+      {
+        key: "title",
+        type: "text" as const,
+        translatable: true,
+        synci18n: true,
+      },
+    ]);
+    const currentLang = ref("it");
+    const form = useMapoForm({
+      model,
+      fields,
+      registry: defaultRegistry,
+      immediate: true,
+      currentLang,
+      languages: ["en", "it"],
+    });
+    form.setFieldValue("title", "Synced");
+    expect(model.value.translations?.en?.title).toBe("Synced");
+    expect(model.value.translations?.it?.title).toBe("Synced");
+  });
+});
+
+// ─── submit ───────────────────────────────────────────────────────────────────
+
+describe("submit", () => {
+  it("calls handler and resets dirty on success", async () => {
+    const { form } = makeForm();
+    form.setFieldValue("title", "X");
+    const handler = vi.fn().mockResolvedValue(undefined);
+    await form.submit(handler);
+    expect(handler).toHaveBeenCalled();
+    expect(form.isDirty.value).toBe(false);
+  });
+
+  it("does not call handler when validateClient fails", async () => {
+    const model = ref<Article>({
+      title: "",
+      slug: "",
+      is_draft: false,
+      count: 0,
+      translations: {},
+    });
+    const fields = ref<FieldDescriptor<Article>[]>([
+      {
+        key: "title",
+        type: "text" as const,
+        validate: (v: unknown) => (v ? null : "err"),
+      },
+    ]);
+    const form = useMapoForm({
+      model,
+      fields,
+      registry: defaultRegistry,
+      immediate: true,
+    });
+    const handler = vi.fn();
+    await form.submit(handler);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("passes full model when isNew=true, patch when isNew=false", async () => {
+    const { form } = makeForm({ title: "Old" });
+    form.setFieldValue("title", "New");
+    const calls: unknown[] = [];
+    await form.submit(async (data) => {
+      calls.push(data);
+    }, false);
+    expect(calls[0]).toEqual({ title: "New" }); // diff only
+
+    form.setFieldValue("slug", "new-slug");
+    await form.submit(async (data) => {
+      calls.push(data);
+    }, true);
+    expect(calls[1]).toHaveProperty("slug", "new-slug"); // full model
+  });
+});

package/src/index.ts

@@ -0,0 +1,49 @@
+export type { MapoFormOptions } from "./module.js";
+export { useFormFromSchema } from "./runtime/composables/useFormFromSchema.js";
+export type { UseFormFromSchemaOptions } from "./runtime/composables/useFormFromSchema.js";
+export { useFormDraft } from "./runtime/composables/useFormDraft.js";
+export type { UseFormDraftOptions } from "./runtime/composables/useFormDraft.js";
+export { useFocusMode } from "./runtime/composables/useFocusMode.js";
+export type { FocusTarget } from "./runtime/composables/useFocusMode.js";
+export { useUnsavedChangesGuard } from "./runtime/composables/useUnsavedChangesGuard.js";
+export type { UnsavedChangesGuardOptions } from "./runtime/composables/useUnsavedChangesGuard.js";
+// Progressive disclosure DSL
+export {
+  when,
+  whenAny,
+  whenNot,
+  matchesField,
+  isOneOf,
+  isNoneOf,
+  isNotEmpty,
+  isEmpty,
+  greaterThan,
+  lessThan,
+  matches,
+} from "./runtime/composables/useProgressiveDisclosure.js";
+export { flattenFieldGroups } from "./runtime/utils/flattenFieldGroups.js";
+export type { FieldGroupDescriptor } from "./runtime/utils/flattenFieldGroups.js";
+export { KnownFieldType } from "./runtime/types/index.js";
+export type {
+  FieldType,
+  FieldAccessor,
+  FieldDescriptor,
+  AnyFieldDescriptor,
+  TextDescriptor,
+  NumberDescriptor,
+  BooleanDescriptor,
+  SelectDescriptor,
+  FksDescriptor,
+  DateDescriptor,
+  ColorDescriptor,
+  FileDescriptor,
+  EditorDescriptor,
+  SeoDescriptor,
+  MapDescriptor,
+  RepeaterDescriptor,
+  MediaDescriptor,
+  CustomDescriptor,
+  FieldComponentEntry,
+  FieldRegistry,
+  PartialFieldRegistry,
+} from "./runtime/types/index.js";

package/src/module.ts

@@ -0,0 +1,213 @@
+import {
+  defineNuxtModule,
+  addComponent,
+  addPlugin,
+  addTypeTemplate,
+  createResolver,
+  addImports,
+  extendPages,
+} from "@nuxt/kit";
+import type { NuxtModule } from "@nuxt/schema";
+import type { PartialFieldRegistry } from "./runtime/types/index.js";
+
+export interface MapoFormOptions {
+  fields?: PartialFieldRegistry;
+  groups?: { expanded?: boolean };
+  debounce?: number;
+}
+
+export default defineNuxtModule<MapoFormOptions>({
+  meta: {
+    name: "@mapomodule/form",
+    configKey: "mapoForm",
+  },
+
+  defaults: {
+    debounce: 300,
+    groups: { expanded: true },
+  },
+
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+
+    // Only serializable values can go into runtimeConfig.public.
+    // `mapping` and `accessor` contain functions → not SSR-serializable.
+    // To extend mapping/accessor, use an app plugin that accesses $mapoFormRegistry:
+    //   export default defineNuxtPlugin(({ $mapoFormRegistry }) => {
+    //     $mapoFormRegistry.mapping['my-type'] = () => import('~/components/MyField.vue')
+    //   })
+    // `defaults` guarantees groups/debounce at runtime; fall back explicitly
+    // so the assignment type is fully defined.
+    nuxt.options.runtimeConfig.public.mapoForm = {
+      groups: { expanded: options.groups?.expanded ?? true },
+      debounce: options.debounce ?? 300,
+      // attrs is JSON-serialisable (plain objects) — merged in the plugin
+      fields: { attrs: options.fields?.attrs ?? {} },
+    };
+
+    // Plugin: create and inject the global field registry
+    addPlugin(resolver.resolve("./runtime/plugins/form-registry"));
+
+    // Augment NuxtApp with $mapoFormRegistry so consumers get type-safe access.
+    // nuxt-module-builder leaves runtime/*.d.ts empty, so InjectionType cannot
+    // infer the plugin's provide shape — we inject the declaration explicitly.
+    addTypeTemplate({
+      filename: "types/mapo-form-registry.d.ts",
+      getContents: () => `
+import type { FieldRegistry } from '@mapomodule/form/types';
+declare module '#app' {
+  interface NuxtApp {
+    $mapoFormRegistry: FieldRegistry;
+  }
+}
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $mapoFormRegistry: FieldRegistry;
+  }
+}
+export {};
+`,
+    });
+
+    // Devtools tab + route (development only)
+    if (nuxt.options.dev) {
+      // The route is registered inside the consumer app so the page can call useNuxtApp() normally.
+      extendPages((pages) => {
+        pages.push({
+          name: "mapo-devtools-forms",
+          path: "/_mapo/devtools/forms",
+          file: resolver.resolve("./runtime/devtools/DevtoolsFormsPage.vue"),
+        });
+      });
+
+      // Registra il tab via hook nativo di Nuxt DevTools (no dipendenza @nuxt/devtools-kit)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (nuxt as any).hook(
+        "devtools:customTabs",
+        (tabs: Array<Record<string, unknown>>) => {
+          tabs.push({
+            name: "mapo-forms",
+            title: "Mapo Forms",
+            icon: "i-lucide-layout-list",
+            view: { type: "iframe", src: "/_mapo/devtools/forms" },
+          });
+        },
+      );
+    }
+
+    // Form shell components
+    const shellComponents = [
+      "MapoForm",
+      "MapoFormField",
+      "MapoFormGroup",
+      "MapoFormTabs",
+      "MapoUnknownField",
+      "MapoFocusPortal",
+    ];
+    for (const name of shellComponents) {
+      addComponent({
+        name,
+        filePath: resolver.resolve(`./runtime/components/${name}.vue`),
+      });
+    }
+
+    // Public auto-imported composables
+    addImports([
+      {
+        name: "useMapoForm",
+        from: resolver.resolve("./runtime/composables/useMapoForm"),
+      },
+      {
+        name: "useCurrentLang",
+        from: resolver.resolve("./runtime/composables/useCurrentLang"),
+      },
+      {
+        name: "provideCurrentLang",
+        from: resolver.resolve("./runtime/composables/useCurrentLang"),
+      },
+      {
+        name: "useFormFromSchema",
+        from: resolver.resolve("./runtime/composables/useFormFromSchema"),
+      },
+      {
+        name: "useFormDraft",
+        from: resolver.resolve("./runtime/composables/useFormDraft"),
+      },
+      {
+        name: "useFocusMode",
+        from: resolver.resolve("./runtime/composables/useFocusMode"),
+      },
+      {
+        name: "defineFormField",
+        from: resolver.resolve("./runtime/composables/defineFormField"),
+      },
+      // Progressive disclosure DSL
+      {
+        name: "when",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "whenAny",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "whenNot",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "matchesField",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "isOneOf",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "isNoneOf",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "isNotEmpty",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "isEmpty",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "greaterThan",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "lessThan",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+      {
+        name: "matches",
+        from: resolver.resolve(
+          "./runtime/composables/useProgressiveDisclosure",
+        ),
+      },
+    ]);
+  },
+}) satisfies NuxtModule<MapoFormOptions>;