@mapomodule/form 2.0.0-beta.1 → 2.0.0-beta.10

package/dist/runtime/composables/useFormDraft.d.ts

@@ -0,0 +1,60 @@
+import { type Ref } from "vue";
+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 declare function useFormDraft<T>(options: UseFormDraftOptions<T>): {
+    clearDraft: () => void;
+    getDraft: () => DraftEntry<T> | null;
+    hasDraft: () => boolean;
+};
+export {};
+//# sourceMappingURL=useFormDraft.d.ts.map

package/dist/runtime/composables/useFormDraft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFormDraft.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/useFormDraft.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAG9D,UAAU,UAAU,CAAC,CAAC;IACpB,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACd,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACtB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,KAAK,IAAI,CAAC;IAC9C,0DAA0D;IAC1D,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;;oBAmCxC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;oBAqBpB,OAAO;EAK7B"}

package/dist/runtime/composables/useFormDraft.js

@@ -0,0 +1,52 @@
+import { watch, onMounted, onUnmounted } from "vue";
+import { debounce } from "@mapomodule/utils";
+export function useFormDraft(options) {
+  const storageKey = options.userId != null ? `mapo:draft:${options.userId}:${options.key}` : `mapo:draft:${options.key}`;
+  const ttl = options.ttl ?? 864e5;
+  const canUseStorage = typeof localStorage !== "undefined";
+  const debouncedSave = debounce(() => {
+    if (!canUseStorage) return;
+    if (!options.isDirty.value) return;
+    const entry = {
+      model: options.model.value,
+      savedAt: Date.now()
+    };
+    try {
+      localStorage.setItem(storageKey, JSON.stringify(entry));
+      options.onSave?.(new Date(entry.savedAt));
+    } catch {
+    }
+  }, options.debounce ?? 2e3);
+  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() {
+    if (!canUseStorage) return null;
+    try {
+      const raw = localStorage.getItem(storageKey);
+      if (!raw) return null;
+      const entry = JSON.parse(raw);
+      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() {
+    return getDraft() !== null;
+  }
+  return { clearDraft, getDraft, hasDraft };
+}

package/dist/runtime/composables/useFormFromSchema.d.ts

@@ -0,0 +1,21 @@
+import type { JSONSchema } from "@mapomodule/utils";
+import type { AnyFieldDescriptor } from "../types/index.js";
+/** Options for generating field descriptors from a JSON Schema document. */
+export interface UseFormFromSchemaOptions {
+    /** Keys to exclude from generation, for example `id` or `created_at`. */
+    exclude?: string[];
+    /** Per-field overrides that shallow-merge onto the generated descriptor. */
+    overrides?: Record<string, Partial<AnyFieldDescriptor>>;
+}
+/**
+ * Builds a `AnyFieldDescriptor[]` array from a JSON Schema.
+ * Supports Pydantic v2 (`$defs`, nullable `anyOf`), DRF Spectacular, and `if/then/else` conditionals.
+ *
+ * @example
+ * const fields = useFormFromSchema(myApiSchema, {
+ *   exclude: ['id', 'created_at'],
+ *   overrides: { body: { type: 'editor', translatable: true } },
+ * })
+ */
+export declare function useFormFromSchema(schema: JSONSchema, options?: UseFormFromSchemaOptions): AnyFieldDescriptor[];
+//# sourceMappingURL=useFormFromSchema.d.ts.map

package/dist/runtime/composables/useFormFromSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFormFromSchema.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/useFormFromSchema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,mBAAmB,CAAC;AAyMvE,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,EAAE,CA+BtB"}

package/dist/runtime/composables/useFormFromSchema.js

@@ -0,0 +1,145 @@
+import { resolveSchema, extractDefs, matchesSchema } from "@mapomodule/utils";
+function mapType(schema, key) {
+  if (schema.enum) return "select";
+  const t = Array.isArray(schema.type) ? schema.type.find((v) => v !== "null") : schema.type;
+  const fmt = schema.format;
+  if (t === "string") {
+    if (fmt === "textarea") return "textarea";
+    if (fmt === "date") return "date";
+    if (fmt === "date-time") return "datetime";
+    if (fmt === "time") return "time";
+    if (fmt === "color") return "color";
+    if (typeof schema.maxLength === "number" && schema.maxLength > 255)
+      return "textarea";
+    return "text";
+  }
+  if (t === "integer" || t === "number") return "number";
+  if (t === "boolean") return "boolean";
+  if (t === "relation") {
+    return schema.multiple ? "m2m" : "fks";
+  }
+  if (t === "array") {
+    const items = schema.items;
+    if (items?.type === "relation") return "m2m";
+    if (items?.type === "object" || items?.properties) return "repeater";
+    return "select";
+  }
+  if (t === "object") {
+    const props = Object.keys(schema.properties ?? {});
+    if (props.includes("title") && props.includes("description") && (props.includes("url") || props.includes("slug")))
+      return "seo";
+    return `object:${key}`;
+  }
+  return "text";
+}
+function buildAttrs(schema, type) {
+  const attrs = {};
+  if (type === "select") {
+    if (schema.enum) {
+      attrs.options = schema.enum.map((v) => ({
+        text: String(v),
+        value: v
+      }));
+    }
+  }
+  if (type === "number") {
+    if (schema.minimum !== void 0) attrs.min = schema.minimum;
+    if (schema.maximum !== void 0) attrs.max = schema.maximum;
+  }
+  if (type === "text" || type === "textarea") {
+    if (schema.maxLength !== void 0) attrs.maxLength = schema.maxLength;
+    if (schema.minLength !== void 0) attrs.minLength = schema.minLength;
+  }
+  if (type === "fks" || type === "m2m") {
+    const ext = schema;
+    attrs.endpoint = ext.endpoint ?? ext.relation ?? "";
+    attrs.returnObject = true;
+    if (type === "m2m") attrs.multiple = true;
+  }
+  if (type === "date" || type === "datetime") {
+    if (schema.minimum) attrs.min = schema.minimum;
+    if (schema.maximum) attrs.max = schema.maximum;
+  }
+  return attrs;
+}
+function collectRules(schema) {
+  const rules = [];
+  function addRule(ifSchema, then, elseBranch) {
+    rules.push({
+      ifSchema,
+      thenKeys: new Set(Object.keys(then?.properties ?? {})),
+      elseKeys: new Set(Object.keys(elseBranch?.properties ?? {}))
+    });
+  }
+  if (schema.if) addRule(schema.if, schema.then, schema.else);
+  if (Array.isArray(schema.allOf)) {
+    for (const entry of schema.allOf) {
+      if (entry?.if) addRule(entry.if, entry.then, entry.else);
+    }
+  }
+  return rules;
+}
+function makeVisible(ifSchema, side) {
+  return ({ model }) => {
+    const matches = matchesSchema(model, ifSchema);
+    return side === "then" ? matches : !matches;
+  };
+}
+function propertyToDescriptor(key, rawSchema, defs, requiredKeys, rules) {
+  const schema = resolveSchema(rawSchema, defs);
+  const type = mapType(schema, key);
+  const attrs = buildAttrs(schema, type);
+  let visible;
+  for (const rule of rules) {
+    if (rule.thenKeys.has(key) && !rule.elseKeys.has(key)) {
+      visible = makeVisible(rule.ifSchema, "then");
+      break;
+    }
+    if (rule.elseKeys.has(key) && !rule.thenKeys.has(key)) {
+      visible = makeVisible(rule.ifSchema, "else");
+      break;
+    }
+  }
+  const base = {
+    key,
+    type,
+    label: schema.title ?? void 0,
+    required: requiredKeys.has(key),
+    ...schema.readOnly ? { readonly: true } : {},
+    ...schema.translatable ? { translatable: true } : {},
+    ...visible ? { visible } : {},
+    ...Object.keys(attrs).length ? { attrs } : {}
+  };
+  if (type === "repeater" && schema.items) {
+    const itemSchema = resolveSchema(schema.items, defs);
+    const childRequired = new Set(itemSchema.required ?? []);
+    const childProps = itemSchema.properties ?? {};
+    const childRules = collectRules(itemSchema);
+    base.fields = Object.entries(childProps).map(
+      ([k, v]) => propertyToDescriptor(k, v, defs, childRequired, childRules)
+    );
+  }
+  return base;
+}
+export function useFormFromSchema(schema, options = {}) {
+  const { exclude = [], overrides = {} } = options;
+  const defs = extractDefs(schema);
+  const properties = schema.properties ?? {};
+  const requiredKeys = new Set(schema.required ?? []);
+  const rules = collectRules(schema);
+  const descriptors = [];
+  for (const [key, rawProp] of Object.entries(properties)) {
+    if (exclude.includes(key)) continue;
+    const descriptor = propertyToDescriptor(
+      key,
+      rawProp,
+      defs,
+      requiredKeys,
+      rules
+    );
+    const override = overrides[key];
+    const final = override ? { ...descriptor, ...override } : descriptor;
+    descriptors.push(final);
+  }
+  return descriptors;
+}

package/dist/runtime/composables/useMapoForm.d.ts

@@ -0,0 +1,96 @@
+import { type Ref, type MaybeRef } from "vue";
+import type { AnyFieldDescriptor, FieldRegistry } from "../types/index.js";
+/** Options accepted by `useMapoForm()`. */
+export interface UseMapoFormOptions<T extends object> {
+    model: Ref<T>;
+    fields: MaybeRef<AnyFieldDescriptor<T>[]>;
+    errors?: Ref<Record<string, string[]>>;
+    languages?: string[];
+    currentLang?: Ref<string>;
+    immediate?: boolean;
+    /** Global debounce in milliseconds. Override per field with `descriptor.debounce`. Default: `300`. */
+    debounce?: number;
+    /**
+     * When `false`, suppresses the toast that lists server-side field errors.
+     * Set this for sub-forms (e.g. each repeater item) so they don't duplicate the
+     * root form's error toast. Default: `true`.
+     */
+    notifyErrors?: boolean;
+    registry: FieldRegistry;
+    /**
+     * When set, enables automatic draft persistence to localStorage.
+     * Key is prefixed with `mapo:draft:`. Drafts expire after 24 h.
+     * Call the returned `checkDraft()` after the model is populated to offer restore.
+     * Example: `"article:42"` → `mapo:draft:article:42`.
+     */
+    draftKey?: MaybeRef<string | undefined>;
+}
+/** State exposed when a pending draft is found in localStorage. */
+export interface MapoDraftBanner {
+    savedAt: Date;
+    restore: () => void;
+    discard: () => void;
+}
+/** Reactive context shared with child form fields via provide/inject. */
+export interface MapoFormContext<T extends object> {
+    model: Ref<T>;
+    fields: MaybeRef<AnyFieldDescriptor<T>[]>;
+    errors: Ref<Record<string, string[]>>;
+    languages: string[];
+    currentLang: Ref<string>;
+    readonly: Ref<boolean>;
+    immediate: boolean;
+    debounce: number;
+    registry: FieldRegistry;
+    setFieldValue: (key: string, val: unknown) => void;
+    getClientError: (key: string) => string | null;
+    markTouched: (key: string) => void;
+    isTouched: (key: string) => boolean;
+    submitted: Ref<boolean>;
+}
+/** Injection key for the current Mapo form context. */
+export declare const FORM_KEY: unique symbol;
+/** Injects the nearest form context, if present. */
+export declare function injectMapoForm<T extends object>(): MapoFormContext<T> | undefined;
+/**
+ * Creates the core reactive state and helpers for a Mapo form.
+ * Handles dirty tracking, field accessors, sync validation, and submit flows.
+ */
+export declare function useMapoForm<T extends object>(options: UseMapoFormOptions<T>): {
+    state: import("vue").ComputedRef<{
+        model: T;
+        errors: Record<string, string[]>;
+        isDirty: boolean;
+        currentLang: string;
+        isLoading: boolean;
+    }>;
+    isDirty: import("vue").ComputedRef<boolean>;
+    isLoading: Ref<boolean, boolean>;
+    readonly: Ref<boolean, boolean>;
+    currentLang: Ref<string, string>;
+    getFieldValue: (descriptor: AnyFieldDescriptor<T>) => unknown;
+    setFieldValue: (keyOrDescriptor: string | AnyFieldDescriptor<T>, val: unknown) => void;
+    getClientError: (keyOrDescriptor: string | AnyFieldDescriptor<T>) => string | null;
+    markTouched: (key: string) => void;
+    isTouched: (key: string) => boolean;
+    validateClient: () => {
+        valid: boolean;
+        errors: Record<string, string>;
+    };
+    resetDirty: () => void;
+    getPatch: () => Partial<T>;
+    submit: (handler: (model: T | Partial<T>, isNew: boolean) => Promise<void>, isNew?: boolean) => Promise<void>;
+    ctx: MapoFormContext<T>;
+    draftBanner: Ref<{
+        savedAt: Date;
+        restore: () => void;
+        discard: () => void;
+    } | null, MapoDraftBanner | {
+        savedAt: Date;
+        restore: () => void;
+        discard: () => void;
+    } | null>;
+    checkDraft: () => void;
+    clearDraft: () => void;
+};
+//# sourceMappingURL=useMapoForm.d.ts.map

package/dist/runtime/composables/useMapoForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMapoForm.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/useMapoForm.ts"],"names":[],"mappings":"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"}