@mapomodule/form 2.0.0-beta.0

package/src/runtime/components/fields/MapoWygEditor.vue

@@ -0,0 +1,256 @@
+<script setup lang="ts">
+import { watch, onBeforeUnmount } from "vue";
+import { useEditor, EditorContent } from "@tiptap/vue-3";
+import type { AnyExtension } from "@tiptap/vue-3";
+import StarterKit from "@tiptap/starter-kit";
+import Link from "@tiptap/extension-link";
+import Underline from "@tiptap/extension-underline";
+import type { EditorDescriptor } from "../../types/index.js";
+
+const props = defineProps<{
+  modelValue: unknown;
+  descriptor: EditorDescriptor;
+  errors?: string[];
+  readonly?: boolean;
+  disabled?: boolean;
+}>();
+
+const emit = defineEmits<{ "update:modelValue": [value: string] }>();
+
+const extraExtensions =
+  (props.descriptor.attrs?.extensions as AnyExtension[] | undefined) ?? [];
+
+// Protocol allowlist for user-entered links. Without this,
+// `<a href="javascript:...">` would be accepted, leading to XSS when content is
+// rendered elsewhere (preview, server-side, other editors).
+const ALLOWED_LINK_PROTOCOLS = ["http", "https", "mailto", "tel"];
+
+function isSafeUrl(url: string): boolean {
+  try {
+    // URL relativi (es. "/page") non hanno protocol — li accettiamo.
+    if (!/^[a-z][a-z0-9+.-]*:/i.test(url)) return true;
+    const proto = new URL(url, "https://placeholder.local").protocol
+      .replace(":", "")
+      .toLowerCase();
+    return ALLOWED_LINK_PROTOCOLS.includes(proto);
+  } catch {
+    return false;
+  }
+}
+
+// Sanitise incoming HTML from external sources (initial set, server sync)
+// by removing <script>, inline handlers (on*), and href: javascript:. This is
+// intentionally minimal (no DOMPurify) to avoid a heavy dependency: it covers the
+// most common vectors; for truly untrusted HTML the consumer should use DOMPurify
+// at the app level.
+function sanitizeHtml(html: string): string {
+  if (typeof window === "undefined" || !html) return html;
+  const tpl = document.createElement("template");
+  tpl.innerHTML = html;
+  const walker = document.createTreeWalker(
+    tpl.content,
+    NodeFilter.SHOW_ELEMENT,
+  );
+  const toRemove: Element[] = [];
+  let node = walker.nextNode() as Element | null;
+  while (node) {
+    if (node.tagName === "SCRIPT" || node.tagName === "STYLE") {
+      toRemove.push(node);
+    } else {
+      for (const attr of Array.from(node.attributes)) {
+        const name = attr.name.toLowerCase();
+        if (name.startsWith("on")) node.removeAttribute(attr.name);
+        if (
+          (name === "href" || name === "src" || name === "xlink:href") &&
+          !isSafeUrl(attr.value)
+        ) {
+          node.removeAttribute(attr.name);
+        }
+      }
+    }
+    node = walker.nextNode() as Element | null;
+  }
+  toRemove.forEach((el) => el.remove());
+  return tpl.innerHTML;
+}
+
+const editor = useEditor({
+  content: sanitizeHtml((props.modelValue as string) ?? ""),
+  editable: !props.readonly && !props.disabled,
+  extensions: [
+    StarterKit,
+    Link.configure({
+      openOnClick: false,
+      protocols: ALLOWED_LINK_PROTOCOLS,
+      validate: (href: string) => isSafeUrl(href),
+    }),
+    Underline,
+    ...extraExtensions,
+  ] as AnyExtension[],
+  onUpdate: ({ editor: e }) => {
+    emit("update:modelValue", e.getHTML());
+  },
+});
+
+// Sync readonly prop → editor editable
+watch(
+  () => [props.readonly, props.disabled],
+  ([ro, dis]) => editor.value?.setEditable(!ro && !dis),
+);
+
+// Sync modelValue esterno → editor (es. reset dopo save)
+watch(
+  () => props.modelValue,
+  (val) => {
+    if (editor.value && val !== editor.value.getHTML()) {
+      editor.value.commands.setContent(
+        sanitizeHtml((val as string) ?? ""),
+        false,
+      );
+    }
+  },
+);
+
+onBeforeUnmount(() => editor.value?.destroy());
+</script>
+
+<template>
+  <div
+    class="mapo-wyg-editor rounded border"
+    :class="[
+      errors?.length ? 'border-red-300' : 'border-gray-200',
+      readonly || disabled ? 'opacity-60' : '',
+    ]"
+  >
+    <!-- Toolbar -->
+    <div
+      v-if="editor"
+      class="flex flex-wrap gap-1 border-b border-gray-200 bg-gray-50 px-2 py-1.5"
+    >
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        :class="{ 'bg-gray-200': editor.isActive('bold') }"
+        @click="editor.chain().focus().toggleBold().run()"
+      >
+        <strong>B</strong>
+      </UButton>
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        :class="{ 'bg-gray-200': editor.isActive('italic') }"
+        @click="editor.chain().focus().toggleItalic().run()"
+      >
+        <em>I</em>
+      </UButton>
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        :class="{ 'bg-gray-200': editor.isActive('underline') }"
+        @click="editor.chain().focus().toggleUnderline().run()"
+      >
+        <span class="underline">U</span>
+      </UButton>
+
+      <USeparator orientation="vertical" class="mx-1 h-5" />
+
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        :class="{ 'bg-gray-200': editor.isActive('heading', { level: 2 }) }"
+        @click="editor.chain().focus().toggleHeading({ level: 2 }).run()"
+      >
+        H2
+      </UButton>
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        :class="{ 'bg-gray-200': editor.isActive('heading', { level: 3 }) }"
+        @click="editor.chain().focus().toggleHeading({ level: 3 }).run()"
+      >
+        H3
+      </UButton>
+
+      <USeparator orientation="vertical" class="mx-1 h-5" />
+
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        :class="{ 'bg-gray-200': editor.isActive('bulletList') }"
+        icon="i-lucide-list"
+        @click="editor.chain().focus().toggleBulletList().run()"
+      />
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        :class="{ 'bg-gray-200': editor.isActive('orderedList') }"
+        icon="i-lucide-list-ordered"
+        @click="editor.chain().focus().toggleOrderedList().run()"
+      />
+
+      <USeparator orientation="vertical" class="mx-1 h-5" />
+
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        icon="i-lucide-undo"
+        @click="editor.chain().focus().undo().run()"
+      />
+      <UButton
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        :disabled="readonly || disabled"
+        icon="i-lucide-redo"
+        @click="editor.chain().focus().redo().run()"
+      />
+
+      <USeparator orientation="vertical" class="mx-1 h-5" />
+
+      <!-- Insert Image — enabled in Phase 6 when Media Manager is available -->
+      <UTooltip
+        text="Insert image (requires Media Manager — Phase 6)"
+        :delay-open="300"
+      >
+        <UButton
+          size="xs"
+          variant="ghost"
+          color="neutral"
+          icon="i-lucide-image"
+          disabled
+        />
+      </UTooltip>
+    </div>
+
+    <!-- Contenuto editor -->
+    <EditorContent
+      :editor="editor"
+      class="prose prose-sm max-w-none px-3 py-2 focus-within:outline-none"
+    />
+
+    <p
+      v-for="err in errors"
+      :key="err"
+      class="px-3 pb-2 text-sm text-red-500"
+      role="alert"
+    >
+      {{ err }}
+    </p>
+  </div>
+</template>

package/src/runtime/components/fields/nui/NuiCheckbox.vue

@@ -0,0 +1,8 @@
+<script setup lang="ts">
+import { useNuiFieldAttrs } from "./useNuiFieldAttrs";
+defineOptions({ inheritAttrs: false });
+const attrs = useNuiFieldAttrs();
+</script>
+<template>
+  <UCheckbox v-bind="attrs" />
+</template>

package/src/runtime/components/fields/nui/NuiInput.vue

@@ -0,0 +1,8 @@
+<script setup lang="ts">
+import { useNuiFieldAttrs } from "./useNuiFieldAttrs";
+defineOptions({ inheritAttrs: false });
+const attrs = useNuiFieldAttrs();
+</script>
+<template>
+  <UInput v-bind="attrs" />
+</template>

package/src/runtime/components/fields/nui/NuiSelectMenu.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { useNuiFieldAttrs } from "./useNuiFieldAttrs";
+defineOptions({ inheritAttrs: false });
+const rawAttrs = useNuiFieldAttrs();
+// Accepts both `items` (NUI shape `{ label, value }` or plain strings) and the
+// legacy `options` (`{ text, value }`). The registry sets `labelKey: "text"`,
+// so mirror `label` into `text` when missing — otherwise NUI-shaped items
+// would render with empty labels.
+const attrs = computed(() => {
+  const { options, items, ...rest } = rawAttrs.value as Record<string, unknown>;
+  const list = (items ?? options) as
+    | Array<string | Record<string, unknown>>
+    | undefined;
+  const normalised = list?.map((it) =>
+    typeof it === "object" && it !== null
+      ? { ...it, text: it.text ?? it.label ?? String(it.value) }
+      : it,
+  );
+  // This wrapper is an untyped passthrough: cast so the dynamic items array
+  // satisfies USelectMenu's generic `items` prop.
+  return { ...rest, items: normalised as never[] | undefined };
+});
+</script>
+<template>
+  <USelectMenu v-bind="attrs" />
+</template>

package/src/runtime/components/fields/nui/NuiSlider.vue

@@ -0,0 +1,8 @@
+<script setup lang="ts">
+import { useNuiFieldAttrs } from "./useNuiFieldAttrs";
+defineOptions({ inheritAttrs: false });
+const attrs = useNuiFieldAttrs();
+</script>
+<template>
+  <USlider v-bind="attrs" />
+</template>

package/src/runtime/components/fields/nui/NuiSwitch.vue

@@ -0,0 +1,8 @@
+<script setup lang="ts">
+import { useNuiFieldAttrs } from "./useNuiFieldAttrs";
+defineOptions({ inheritAttrs: false });
+const attrs = useNuiFieldAttrs();
+</script>
+<template>
+  <USwitch v-bind="attrs" />
+</template>

package/src/runtime/components/fields/nui/NuiTextarea.vue

@@ -0,0 +1,8 @@
+<script setup lang="ts">
+import { useNuiFieldAttrs } from "./useNuiFieldAttrs";
+defineOptions({ inheritAttrs: false });
+const attrs = useNuiFieldAttrs();
+</script>
+<template>
+  <UTextarea v-bind="attrs" />
+</template>

package/src/runtime/components/fields/nui/useNuiFieldAttrs.ts

@@ -0,0 +1,30 @@
+import { computed, useAttrs, type ComputedRef } from "vue";
+
+/**
+ * Shared logic for NUI wrappers: strips internal props (`descriptor`, `errors`)
+ * from the binding passed to the underlying NUI component and derives visual
+ * error flags (`color: 'error'` + `aria-invalid`).
+ *
+ * Note: NUI v3 form components accept `color="error"` for the red border.
+ * We apply it here as a fallback when the caller has not set it already,
+ * so consumers that do not go through `MapoFormField` still get the correct
+ * color when `errors` is non-empty.
+ */
+export function useNuiFieldAttrs(): ComputedRef<Record<string, unknown>> {
+  const rawAttrs = useAttrs();
+  return computed(() => {
+    const {
+      descriptor: _d,
+      errors,
+      color,
+      ...rest
+    } = rawAttrs as Record<string, unknown>;
+    const errs = (errors as string[] | undefined) ?? [];
+    const hasError = errs.length > 0;
+    return {
+      ...rest,
+      color: color ?? (hasError ? "error" : undefined),
+      "aria-invalid": hasError ? "true" : undefined,
+    };
+  });
+}

package/src/runtime/composables/defineFormField.ts

@@ -0,0 +1,62 @@
+import { useNuxtApp } from "#app";
+import type {
+  FieldComponentEntry,
+  FieldAccessor,
+  FieldRegistry,
+} from "../types/index.js";
+
+/** Options for registering or overriding a custom field type. */
+export interface DefineFormFieldOptions {
+  /** Default attrs applied to all descriptors of this `type`. */
+  attrs?: Record<string, unknown>;
+  /** Default get/set accessor for this `type`. */
+  accessor?: FieldAccessor;
+  /** Replaces an existing registration without warning. */
+  override?: boolean;
+}
+
+/**
+ * Typed API for registering a custom field component.
+ * Must be called from a Nuxt plugin (the load order guarantees that `$mapoFormRegistry`
+ * is already present — the `@mapomodule/form` plugin is loaded first).
+ *
+ * @example
+ *   // app/plugins/my-fields.ts
+ *   export default defineNuxtPlugin(() => {
+ *     defineFormField('rich-text', () => import('~/components/RichText.vue'), {
+ *       attrs: { rows: 6 },
+ *     })
+ *   })
+ */
+export function defineFormField(
+  type: string,
+  entry: FieldComponentEntry,
+  opts: DefineFormFieldOptions = {},
+): void {
+  const nuxt = useNuxtApp() as unknown as { $mapoFormRegistry?: FieldRegistry };
+  const registry = nuxt.$mapoFormRegistry;
+  if (!registry) {
+    if (import.meta.dev) {
+      console.warn(
+        `[Mapo] defineFormField('${type}') called before $mapoFormRegistry is available. ` +
+          `Make sure the plugin is loaded after @mapomodule/form.`,
+      );
+    }
+    return;
+  }
+  if (registry.mapping[type] && !opts.override) {
+    if (import.meta.dev) {
+      console.warn(
+        `[Mapo] defineFormField: type "${type}" already registered. ` +
+          `Pass { override: true } to replace it intentionally.`,
+      );
+    }
+  }
+  registry.mapping[type] = entry;
+  if (opts.attrs) {
+    registry.attrs[type] = { ...(registry.attrs[type] ?? {}), ...opts.attrs };
+  }
+  if (opts.accessor) {
+    registry.accessor[type] = opts.accessor;
+  }
+}

package/src/runtime/composables/useCurrentLang.ts

@@ -0,0 +1,16 @@
+import { getCurrentInstance, inject, provide, ref, type Ref } from "vue";
+
+const LANG_KEY = Symbol("mapoCurrentLang");
+
+/** Provides the current form language to descendant components. */
+export function provideCurrentLang(lang: Ref<string>) {
+  provide(LANG_KEY, lang);
+}
+
+/** Returns the current form language, falling back to the provided ref when needed. */
+export function useCurrentLang(fallback?: Ref<string>): Ref<string> {
+  // Outside setup() (for example in tests), Vue 3 returns `undefined` from inject()
+  // and ignores the default value, so the "no instance" case must be handled explicitly.
+  if (!getCurrentInstance()) return fallback ?? ref("");
+  return inject<Ref<string>>(LANG_KEY, fallback ?? ref(""));
+}

package/src/runtime/composables/useFocusMode.ts

@@ -0,0 +1,86 @@
+import {
+  computed,
+  readonly,
+  shallowRef,
+  type Ref,
+  type DeepReadonly,
+  type ShallowRef,
+} from "vue";
+import type { AnyFieldDescriptor, FieldRegistry } from "../types/index.js";
+
+/** Describes the currently focused repeater item in focus mode. */
+export interface FocusTarget {
+  /** Descriptor of the repeater field that contains the focused item. */
+  descriptor: AnyFieldDescriptor;
+  /** Fields for the focused item, resolved from the template when needed. */
+  fields: AnyFieldDescriptor[];
+  /**
+   * Initial snapshot of the item model at the time the portal was opened.
+   * Stored as a plain object (not a Ref) to avoid Vue's auto-unwrap behaviour
+   * when placed inside Nuxt's useState reactive container.
+   */
+  model: Record<string, unknown>;
+  /** Errors for this item (already filtered). */
+  errors: Ref<Record<string, string[]>>;
+  /** Callback invoked when the item model is updated. */
+  onUpdate: (val: Record<string, unknown>) => void;
+  /** Field component registry passed to the sub-form. */
+  registry: FieldRegistry;
+  /** Available language codes. */
+  languages: string[];
+  /** Currently active language code. */
+  currentLang: string;
+  /** Visual breadcrumb trail: ['Article', 'Blocks', 'Block 3'] */
+  breadcrumb: string[];
+}
+
+/** Shared focus-mode API used by nested repeater editors. */
+export interface FocusModeReturn {
+  focusTarget: DeepReadonly<ShallowRef<FocusTarget | null>>;
+  isActive: Ref<boolean>;
+  enter: (target: FocusTarget) => void;
+  exit: () => void;
+}
+
+// Fallback for non-Nuxt environments (tests, Storybook): a client-only singleton is
+// acceptable. In Nuxt we use `useState` to guarantee per-request isolation in SSR
+// and avoid cross-tenant state leaks.
+const _clientFallback = shallowRef<FocusTarget | null>(null);
+
+function getStateRef(): Ref<FocusTarget | null> {
+  // `useState` is auto-imported by Nuxt; in vanilla environments we fall back to the singleton.
+  const nuxtUseState = (
+    globalThis as { useState?: <X>(key: string, init: () => X) => Ref<X> }
+  ).useState;
+  if (typeof nuxtUseState === "function") {
+    return nuxtUseState<FocusTarget | null>(
+      "mapo:form:focusTarget",
+      () => null,
+    );
+  }
+  return _clientFallback;
+}
+
+/**
+ * Exposes a shared focus-mode state for nested repeater items.
+ * In Nuxt it uses `useState()` for SSR-safe request isolation.
+ */
+export function useFocusMode(): FocusModeReturn {
+  const state = getStateRef();
+
+  function enter(target: FocusTarget): void {
+    state.value = target;
+  }
+  function exit(): void {
+    state.value = null;
+  }
+
+  return {
+    focusTarget: readonly(state) as DeepReadonly<
+      ShallowRef<FocusTarget | null>
+    >,
+    isActive: computed(() => state.value !== null),
+    enter,
+    exit,
+  };
+}

package/src/runtime/composables/useFormDraft.ts

@@ -0,0 +1,119 @@
+import { watch, onMounted, onUnmounted, type Ref } from "vue";
+import { debounce } from "@mapomodule/utils";
+
+interface DraftEntry<T> {
+  model: T;
+  savedAt: number;
+}
+
+/** Options for draft persistence and restoration. */
+export interface UseFormDraftOptions<T> {
+  model: Ref<T>;
+  isDirty: Ref<boolean>;
+  /**
+   * Unique draft key. It is prefixed with `mapo:draft:{userId}:` when `userId` is provided,
+   * otherwise `mapo:draft:`. Example: `article:42` → `mapo:draft:1:article:42`.
+   */
+  key: string;
+  /**
+   * User identifier used to scope the draft so it is never shared across accounts.
+   * Without this, a draft survives logout and may be seen by the next user on the same browser.
+   * Pass `useAuthStore().user?.id` (or equivalent) from the calling composable.
+   */
+  userId?: string | number;
+  /** Milliseconds between debounced writes to localStorage. Default: `2000`. */
+  debounce?: number;
+  /** TTL in milliseconds before the draft is discarded. Default: `86_400_000` (24h). */
+  ttl?: number;
+  /**
+   * Called on mount when a valid, non-expired draft exists.
+   * Show a notification here and decide whether to restore it.
+   */
+  onRestore?: (draft: T, savedAt: Date) => void;
+  /** Called after each successful write to localStorage. */
+  onSave?: (savedAt: Date) => void;
+}
+
+/**
+ * Persists form drafts to `localStorage` and restores them on mount when available.
+ *
+ * The draft is written debounced while `isDirty` is `true`. On mount, if a valid
+ * non-expired draft is found, `onRestore` is called so the caller can decide
+ * whether to apply it (e.g. show a snack notification first).
+ *
+ * @param options - Configuration for key, TTL, debounce interval and lifecycle callbacks.
+ * @returns An object with `{ clearDraft, getDraft, hasDraft }` for manual control.
+ *
+ * @example
+ * useFormDraft({
+ *   model,
+ *   isDirty,
+ *   key: `article:${route.params.id}`,
+ *   onRestore: (draft, savedAt) => {
+ *     snack.show(`Draft from ${savedAt.toLocaleString()} restored`)
+ *     Object.assign(model.value, draft)
+ *   },
+ * })
+ */
+export function useFormDraft<T>(options: UseFormDraftOptions<T>) {
+  const storageKey =
+    options.userId != null
+      ? `mapo:draft:${options.userId}:${options.key}`
+      : `mapo:draft:${options.key}`;
+  const ttl = options.ttl ?? 86_400_000;
+  const canUseStorage = typeof localStorage !== "undefined";
+
+  const debouncedSave = debounce(() => {
+    if (!canUseStorage) return;
+    if (!options.isDirty.value) return;
+    const entry: DraftEntry<T> = {
+      model: options.model.value,
+      savedAt: Date.now(),
+    };
+    try {
+      localStorage.setItem(storageKey, JSON.stringify(entry));
+      options.onSave?.(new Date(entry.savedAt));
+    } catch {
+      // quota exceeded — silently ignore
+    }
+  }, options.debounce ?? 2000);
+
+  const stopWatch = watch(options.model, debouncedSave, { deep: true });
+
+  onMounted(() => {
+    const draft = getDraft();
+    if (!draft) return;
+    options.onRestore?.(draft.model, new Date(draft.savedAt));
+  });
+
+  onUnmounted(() => {
+    stopWatch();
+  });
+
+  function getDraft(): DraftEntry<T> | null {
+    if (!canUseStorage) return null;
+    try {
+      const raw = localStorage.getItem(storageKey);
+      if (!raw) return null;
+      const entry = JSON.parse(raw) as DraftEntry<T>;
+      if (Date.now() - entry.savedAt > ttl) {
+        localStorage.removeItem(storageKey);
+        return null;
+      }
+      return entry;
+    } catch {
+      return null;
+    }
+  }
+
+  function clearDraft() {
+    if (!canUseStorage) return;
+    localStorage.removeItem(storageKey);
+  }
+
+  function hasDraft(): boolean {
+    return getDraft() !== null;
+  }
+
+  return { clearDraft, getDraft, hasDraft };
+}