@mapomodule/form 2.0.0-beta.0

package/README.md

@@ -0,0 +1,155 @@
+# @mapomodule/form
+
+Form engine for Mapo v2 — descriptor-driven, typesafe, headless-ready admin forms for Nuxt 4 + Django/DRF.
+
+## Features
+
+- **Descriptor-driven**: define fields as `FieldDescriptor[]` — layout, validation, i18n in one object
+- **All field types built-in**: text, select, date/time, FK/M2M autocomplete, WYSIWYG editor, SEO preview, map, repeater
+- **Headless composable**: `useMapoForm()` for fully custom layouts; `<MapoForm>` for the default shell
+- **Registry auto-injection**: `<MapoForm>` and `<MapoDetail>` resolve `$mapoFormRegistry` automatically — no boilerplate
+- **Typed extension API**: `defineFormField(type, entry, opts)` to register custom fields with collision detection
+- **JSON Schema bridge**: `useFormFromSchema()` generates descriptors from Pydantic v2 / DRF-spectacular schemas
+- **Multilingual fields**: `translatable: true` writes to `model.translations[lang].field` automatically
+- **Client validation**: `validate(value, ctx)` per descriptor + `required` shorthand
+- **Tab/group layout**: declare `tab` and `group` per field — tabs render automatically (incl. nested tabs), groups are collapsible. Tab panels expose `tab.<name>.before/after`, full override, `.label` and `tab-bar-end` slots
+- **Consistent repeater items**: `MapoRepeater` drives each item through `useMapoForm`, so nested-path keys, `translatable`, accessors, `descriptor.is` overrides and **client validation** behave identically inside a repeater
+- **Draft persistence**: `draftKey` option on `useMapoForm()` auto-saves to localStorage every 2 s; `checkDraft()` / `draftBanner` offer restore/discard; clears on successful `submit()`
+- **Fail-soft**: unknown field types render a non-destructive placeholder, never crash the form
+
+## Install
+
+`@mapomodule/form` is included automatically when you install `mapomodule` (recommended). No additional module entry is needed.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@nuxt/ui", "mapomodule"],
+  mapo: {
+    form: {
+      // optional — global field registry defaults
+    },
+  },
+});
+```
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import type { FieldDescriptor } from "@mapomodule/form";
+
+interface Article {
+  title: string;
+  slug: string;
+  is_draft: boolean;
+}
+
+const article = ref<Article>({ title: "", slug: "", is_draft: true });
+const errors = ref<Record<string, string[]>>({});
+
+const fields: FieldDescriptor<Article>[] = [
+  { key: "title", type: "text", label: "Title", required: true },
+  { key: "slug", type: "text", label: "Slug" },
+  { key: "is_draft", type: "switch", label: "Draft" },
+];
+</script>
+
+<template>
+  <MapoForm v-model="article" :fields="fields" :errors="errors" />
+</template>
+```
+
+The `registry` prop is optional — `<MapoForm>` falls back to the global `$mapoFormRegistry` provided by this module's plugin. Pass it explicitly only when you want to swap the registry for a single form.
+
+## Field types
+
+| Type                         | Component             | Notes                                                       |
+| ---------------------------- | --------------------- | ----------------------------------------------------------- |
+| `text`                       | `UInput`              |                                                             |
+| `textarea`                   | `UTextarea`           |                                                             |
+| `number`                     | `UInput[type=number]` |                                                             |
+| `boolean`                    | `UCheckbox`           |                                                             |
+| `switch`                     | `USwitch`             |                                                             |
+| `color`                      | `UInput[type=color]`  |                                                             |
+| `slider`                     | `USlider`             |                                                             |
+| `file`                       | `MapoFileField`       | Current-file preview, image thumbnail, remove button        |
+| `select`                     | `USelectMenu`         | requires `attrs.options`                                    |
+| `date` / `datetime` / `time` | `MapoDateField` etc.  | ISO string in model; `tz: 'naive' \| 'utc'` for `datetime`  |
+| `fks`                        | `MapoFksField`        | FK autocomplete; `attrs.endpoint` required                  |
+| `m2m`                        | `MapoFksField`        | Multi-select autocomplete, removable chips                  |
+| `editor`                     | `MapoWygEditor`       | Tiptap v2; sanitized output, safe `Link` validator          |
+| `seo`                        | `MapoSeoPreview`      | Title / description with live SERP preview                  |
+| `map`                        | `MapoMapField`        | Leaflet, `{ lat, lng }` in model, SSR-safe via `ClientOnly` |
+| `repeater`                   | `MapoRepeater`        | Nested fields, drag-and-drop, undo stack, templates         |
+
+## JSON Schema → Form
+
+```ts
+const schema = await $fetch("/api/schema/");
+const fields = useFormFromSchema(schema, {
+  exclude: ["id", "created_at"],
+  overrides: {
+    body: { type: "editor", translatable: true },
+  },
+});
+```
+
+## Headless
+
+```ts
+const form = useMapoForm({ model, fields, registry: $mapoFormRegistry });
+
+// form.isDirty, form.isLoading, form.getPatch(), form.submit(handler)
+```
+
+The headless composable still requires the registry explicitly — `useNuxtApp()` is not available in every context where you might want to drive a form (tests, storybook, server-side preview).
+
+## Draft persistence (headless)
+
+```ts
+const form = useMapoForm({
+  model,
+  fields,
+  registry: $mapoFormRegistry,
+  draftKey: `article:${route.params.id}`,
+});
+
+// After fetch:
+form.checkDraft(); // populates form.draftBanner if a draft is found
+```
+
+`form.draftBanner.value` exposes `{ savedAt, restore(), discard() }`. On `submit()` success the draft is cleared automatically. When using `<MapoDetail :draft="true">`, all of this is handled for you.
+
+## Custom fields
+
+The recommended way to register a custom field is the typed `defineFormField()` helper, called from a Nuxt plugin:
+
+```ts
+// app/plugins/my-fields.ts
+export default defineNuxtPlugin(() => {
+  defineFormField("rich-text", () => import("~/components/RichText.vue"), {
+    attrs: { rows: 6 },
+  });
+});
+```
+
+Plugins in `app/plugins/` run after module plugins, so `$mapoFormRegistry` is always available. Re-registering an existing type prints a development warning unless you pass `{ override: true }` explicitly.
+
+Any component with `modelValue` + `descriptor` + `errors` + `readonly` props works as a field.
+
+## Documentation
+
+Full docs: [Form Engine — Quickstart](../../../docs/uikit/form/index.md)
+
+- [All field types](../../../docs/uikit/form/add-fields.md)
+- [Validation](../../../docs/uikit/form/validation.md)
+- [i18n / multilingual fields](../../../docs/uikit/form/i18n.md)
+- [`useMapoForm()` headless](../../../docs/uikit/form/composable.md)
+- [Custom fields & registry](../../../docs/uikit/form/custom-fields.md)
+- [Slot system](../../../docs/uikit/form/slots.md)
+- [JSON Schema bridge](../../../docs/uikit/form/schema-to-form.md)
+
+## License
+
+MIT

package/dist/index.d.cts

@@ -0,0 +1 @@
+export * from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/index.js";

package/dist/index.d.mts

@@ -0,0 +1 @@
+export * from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/index.js";

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/index.js";

package/dist/index.mjs

@@ -0,0 +1,34 @@
+import { createJiti } from "file:///Volumes/Development/Lotrek/Projects/mapo-new/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/jiti.mjs";
+
+const jiti = createJiti(import.meta.url, {
+  "interopDefault": true,
+  "alias": {
+    "@mapomodule/form": "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form"
+  },
+  "transformOptions": {
+    "babel": {
+      "plugins": []
+    }
+  }
+})
+
+/** @type {import("/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/index.js")} */
+const _module = await jiti.import("/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/index.ts");
+
+export const useFormFromSchema = _module.useFormFromSchema;
+export const useFormDraft = _module.useFormDraft;
+export const useFocusMode = _module.useFocusMode;
+export const useUnsavedChangesGuard = _module.useUnsavedChangesGuard;
+export const when = _module.when;
+export const whenAny = _module.whenAny;
+export const whenNot = _module.whenNot;
+export const matchesField = _module.matchesField;
+export const isOneOf = _module.isOneOf;
+export const isNoneOf = _module.isNoneOf;
+export const isNotEmpty = _module.isNotEmpty;
+export const isEmpty = _module.isEmpty;
+export const greaterThan = _module.greaterThan;
+export const lessThan = _module.lessThan;
+export const matches = _module.matches;
+export const flattenFieldGroups = _module.flattenFieldGroups;
+export const KnownFieldType = _module.KnownFieldType;

package/dist/module.d.cts

@@ -0,0 +1,2 @@
+export * from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.js";
+export { default } from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.js";

package/dist/module.d.mts

@@ -0,0 +1,2 @@
+export * from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.js";
+export { default } from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.js";

package/dist/module.d.ts

@@ -0,0 +1,2 @@
+export * from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.js";
+export { default } from "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.js";

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@mapomodule/form",
+  "configKey": "mapoForm",
+  "version": "2.0.0-beta.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,18 @@
+import { createJiti } from "file:///Volumes/Development/Lotrek/Projects/mapo-new/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/jiti.mjs";
+
+const jiti = createJiti(import.meta.url, {
+  "interopDefault": true,
+  "alias": {
+    "@mapomodule/form": "/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form"
+  },
+  "transformOptions": {
+    "babel": {
+      "plugins": []
+    }
+  }
+})
+
+/** @type {import("/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.js")} */
+const _module = await jiti.import("/Volumes/Development/Lotrek/Projects/mapo-new/packages/@mapomodule/form/src/module.ts");
+
+export default _module?.default ?? _module;

package/dist/types.d.mts

@@ -0,0 +1,13 @@
+import type { ModuleHooks, ModuleRuntimeHooks, ModuleRuntimeConfig, ModulePublicRuntimeConfig } from './module.mjs'
+
+declare module '#app' {
+  interface RuntimeNuxtHooks extends ModuleRuntimeHooks {}
+}
+
+declare module '@nuxt/schema' {
+  interface NuxtHooks extends ModuleHooks {}
+  interface RuntimeConfig extends ModuleRuntimeConfig {}
+  interface PublicRuntimeConfig extends ModulePublicRuntimeConfig {}
+}
+
+export * from "./module.mjs"

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@mapomodule/form",
+  "version": "2.0.0-beta.0",
+  "description": "Mapo declarative typed form engine and field components",
+  "type": "module",
+  "license": "MIT",
+  "author": "Lotrek Agency (https://lotrek.it)",
+  "homepage": "https://lotrekagency.github.io/mapo-new/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lotrekagency/mapo-new.git",
+    "directory": "packages/@mapomodule/form"
+  },
+  "bugs": {
+    "url": "https://github.com/lotrekagency/mapo-new/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./types": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./runtime/*": {
+      "types": "./src/runtime/*.ts",
+      "import": "./dist/runtime/*.js",
+      "default": "./src/runtime/*"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "nuxt-module-build build && vue-tsc -p tsconfig.build-types.json && node ../../../scripts/clean-empty-vue-dts.mjs dist",
+    "dev": "nuxt-module-build build --stub --watch",
+    "prepare": "nuxt-module-build build --stub",
+    "dev:prepare": "nuxt-module-build build --stub",
+    "typecheck": "vue-tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@internationalized/date": "^3.7.0",
+    "@mapomodule/store": "workspace:*",
+    "@mapomodule/utils": "workspace:*",
+    "@tiptap/extension-link": "^2.11.5",
+    "@tiptap/extension-underline": "^2.11.5",
+    "@tiptap/starter-kit": "^2.11.5",
+    "@tiptap/vue-3": "^2.11.5",
+    "leaflet": "^1.9.4",
+    "vue-draggable-plus": "^0.6.0"
+  },
+  "optionalDependencies": {
+    "@types/leaflet": "^1.9.18"
+  },
+  "peerDependencies": {
+    "nuxt": ">=4.0.0",
+    "vue": ">=3.5.0"
+  },
+  "devDependencies": {
+    "@nuxt/kit": "4.4.2",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "4.4.2",
+    "nuxt": "^4.4.2",
+    "vitest": "^3.2.0",
+    "vue": "^3.5.32",
+    "vue-router": "^5.0.4",
+    "vue-tsc": "^3.3.4",
+    "zod": "^3.23.8"
+  }
+}

package/src/__tests__/__mocks__/nuxt-imports.ts

@@ -0,0 +1,5 @@
+import { vi } from "vitest";
+
+export const useSnackStore = vi.fn(() => ({
+  show: vi.fn(),
+}));

package/src/__tests__/registry.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from "vitest";
+import {
+  resolveFieldComponent,
+  resolveFieldAttrs,
+  resolveFieldAccessor,
+} from "../runtime/types/registry.js";
+import { defaultRegistry } from "../runtime/registry/defaults.js";
+import type {
+  AnyFieldDescriptor,
+  FieldDescriptor,
+} from "../runtime/types/descriptor.js";
+
+describe("resolveFieldComponent", () => {
+  it("returns a lazy function for text type", () => {
+    const d = { key: "title", type: "text" } as FieldDescriptor;
+    expect(typeof resolveFieldComponent(d, defaultRegistry)).toBe("function");
+  });
+
+  it("returns a lazy function for select type", () => {
+    const d = {
+      key: "cat",
+      type: "select",
+      attrs: { options: [] },
+    } as FieldDescriptor;
+    expect(typeof resolveFieldComponent(d, defaultRegistry)).toBe("function");
+  });
+
+  it("returns a lazy function for date type", () => {
+    const d = { key: "pub", type: "date" } as FieldDescriptor;
+    const entry = resolveFieldComponent(d, defaultRegistry);
+    expect(typeof entry).toBe("function");
+  });
+
+  it("descriptor.is overrides registry", () => {
+    const CustomComp = {} as any;
+    const d = { key: "x", type: "text", is: CustomComp } as FieldDescriptor;
+    expect(resolveFieldComponent(d, defaultRegistry)).toBe(CustomComp);
+  });
+
+  it("returns null for unknown type", () => {
+    const d = { key: "x", type: "unknown-xyz" } as AnyFieldDescriptor;
+    expect(resolveFieldComponent(d, defaultRegistry)).toBeNull();
+  });
+
+  it("user registry override wins over default", () => {
+    const CustomFn = () => Promise.resolve({ default: {} as any });
+    const registry = {
+      ...defaultRegistry,
+      mapping: { ...defaultRegistry.mapping, text: CustomFn },
+    };
+    const d = { key: "title", type: "text" } as FieldDescriptor;
+    expect(resolveFieldComponent(d, registry)).toBe(CustomFn);
+  });
+});
+
+describe("resolveFieldAttrs", () => {
+  it("applies All attrs to every field", () => {
+    const d = { key: "x", type: "text" } as FieldDescriptor;
+    const attrs = resolveFieldAttrs(d, defaultRegistry);
+    expect(attrs.class).toBe("w-full");
+  });
+
+  it("merges type-specific attrs", () => {
+    const d = { key: "n", type: "number" } as FieldDescriptor;
+    const attrs = resolveFieldAttrs(d, defaultRegistry);
+    expect(attrs.type).toBe("number");
+    expect(attrs.class).toBe("w-full");
+  });
+
+  it("descriptor.attrs wins over registry", () => {
+    const d = {
+      key: "n",
+      type: "text",
+      attrs: { placeholder: "Hello" },
+    } as FieldDescriptor;
+    const attrs = resolveFieldAttrs(d, defaultRegistry);
+    expect(attrs.placeholder).toBe("Hello");
+  });
+});
+
+describe("resolveFieldAccessor", () => {
+  it("returns empty accessor for types without registry accessor", () => {
+    const d = { key: "title", type: "text" } as FieldDescriptor;
+    const acc = resolveFieldAccessor(d, defaultRegistry);
+    expect(acc.get).toBeUndefined();
+    expect(acc.set).toBeUndefined();
+  });
+
+  it("returns accessor for seo type", () => {
+    const d = { key: "seo", type: "seo" } as FieldDescriptor;
+    const acc = resolveFieldAccessor(d, defaultRegistry);
+    expect(typeof acc.get).toBe("function");
+  });
+
+  it("descriptor.accessor.get overrides registry", () => {
+    const customGet = () => "custom";
+    const d = {
+      key: "x",
+      type: "seo",
+      accessor: { get: customGet },
+    } as FieldDescriptor;
+    const acc = resolveFieldAccessor(d, defaultRegistry);
+    expect(acc.get).toBe(customGet);
+  });
+});