@mapomodule/form 2.0.0-beta.0

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

@@ -0,0 +1,192 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import {
+  parseDateTime,
+  CalendarDateTime,
+  today,
+  getLocalTimeZone,
+} from "@internationalized/date";
+import type { DateDescriptor } from "../../types/index.js";
+
+/** Datetime field with configurable naive/UTC serialisation semantics. */
+const props = defineProps<{
+  modelValue: unknown;
+  descriptor: DateDescriptor;
+  errors?: string[];
+  readonly?: boolean;
+  disabled?: boolean;
+}>();
+
+const emit = defineEmits<{ "update:modelValue": [value: string | null] }>();
+
+const open = ref(false);
+
+// Timezone strategy configurable through `descriptor.attrs.tz`:
+//   - `naive` (default): the input represents a wall-time with no timezone.
+//     The backend preserves the string as-is. Round-trip safe.
+//   - `utc`: the input is interpreted/emitted as ISO with a `Z` suffix.
+//     Explicit local ↔ UTC conversion; the backend stores UTC.
+type TzMode = "naive" | "utc";
+const tzMode = computed<TzMode>(() => props.descriptor.attrs?.tz ?? "naive");
+
+// ISO string → CalendarDateTime
+const calendarValue = computed<CalendarDateTime | undefined>(() => {
+  const v = props.modelValue as string | null | undefined;
+  if (!v) return undefined;
+  try {
+    if (tzMode.value === "utc") {
+      // Interpret the input as UTC and convert it to local wall-time for the UI.
+      const d = new Date(v);
+      if (Number.isNaN(d.getTime())) return undefined;
+      return new CalendarDateTime(
+        d.getFullYear(),
+        d.getMonth() + 1,
+        d.getDate(),
+        d.getHours(),
+        d.getMinutes(),
+        d.getSeconds(),
+      );
+    }
+    // `naive`: strip any stray Z/offset suffix and parse as wall-time.
+    // split() always returns at least one element.
+    const clean = v
+      .replace(/Z$/, "")
+      .replace(/[+-]\d{2}:\d{2}$/, "")
+      .split(".")[0]!;
+    return parseDateTime(clean);
+  } catch {
+    return undefined;
+  }
+});
+
+function emitFromCalendar(v: CalendarDateTime) {
+  if (tzMode.value === "utc") {
+    // Local wall-time → UTC ISO instant.
+    const d = new Date(v.year, v.month - 1, v.day, v.hour, v.minute, 0, 0);
+    emit("update:modelValue", d.toISOString());
+    return;
+  }
+  emit("update:modelValue", v.toString());
+}
+
+// Displayed label in the trigger button
+const displayLabel = computed(() => {
+  const v = calendarValue.value;
+  if (!v) return "Select date and time";
+  const date = `${String(v.day).padStart(2, "0")}/${String(v.month).padStart(2, "0")}/${v.year}`;
+  const time = `${String(v.hour).padStart(2, "0")}:${String(v.minute).padStart(2, "0")}`;
+  return `${date} ${time}`;
+});
+
+// Separate refs for the time picker
+const timeHour = computed(() => calendarValue.value?.hour ?? 0);
+const timeMinute = computed(() => calendarValue.value?.minute ?? 0);
+
+function onDateSelect(date: unknown) {
+  const d = date as CalendarDateTime | null;
+  if (!d) {
+    emit("update:modelValue", null);
+    return;
+  }
+  // Preserve existing time when changing date
+  const h = calendarValue.value?.hour ?? 0;
+  const m = calendarValue.value?.minute ?? 0;
+  const merged = new CalendarDateTime(d.year, d.month, d.day, h, m);
+  emitFromCalendar(merged);
+}
+
+function onTimeChange(part: "hour" | "minute", val: string) {
+  const n = Math.max(
+    0,
+    Math.min(part === "hour" ? 23 : 59, parseInt(val) || 0),
+  );
+  const base =
+    calendarValue.value ??
+    (() => {
+      const t = today(getLocalTimeZone());
+      return new CalendarDateTime(t.year, t.month, t.day, 0, 0);
+    })();
+  const merged =
+    part === "hour"
+      ? new CalendarDateTime(base.year, base.month, base.day, n, base.minute)
+      : new CalendarDateTime(base.year, base.month, base.day, base.hour, n);
+  emitFromCalendar(merged);
+}
+
+function clear() {
+  emit("update:modelValue", null);
+  open.value = false;
+}
+</script>
+
+<template>
+  <UPopover v-model:open="open" :disabled="readonly || disabled">
+    <UButton
+      variant="outline"
+      color="neutral"
+      icon="i-lucide-calendar"
+      trailing
+      class="w-full justify-between font-normal"
+      :class="{
+        'opacity-50 cursor-not-allowed': readonly || disabled,
+        'ring-2 ring-red-500': errors?.length,
+      }"
+      :disabled="readonly || disabled"
+    >
+      <span
+        :class="
+          calendarValue ? 'text-gray-900 dark:text-white' : 'text-gray-400'
+        "
+      >
+        {{ displayLabel }}
+      </span>
+    </UButton>
+
+    <template #content>
+      <div class="p-3 space-y-3">
+        <UCalendar
+          :model-value="calendarValue"
+          @update:model-value="onDateSelect"
+        />
+
+        <!-- Time picker -->
+        <div
+          class="flex items-center gap-2 border-t border-gray-200 dark:border-gray-700 pt-3"
+        >
+          <UIcon name="i-lucide-clock" class="text-gray-400 shrink-0" />
+          <div class="flex items-center gap-1">
+            <UInput
+              type="number"
+              :model-value="timeHour"
+              min="0"
+              max="23"
+              class="w-14 text-center"
+              @update:model-value="
+                (v: unknown) => onTimeChange('hour', String(v))
+              "
+            />
+            <span class="text-gray-500 font-medium">:</span>
+            <UInput
+              type="number"
+              :model-value="timeMinute"
+              min="0"
+              max="59"
+              class="w-14 text-center"
+              @update:model-value="
+                (v: unknown) => onTimeChange('minute', String(v))
+              "
+            />
+          </div>
+          <UButton
+            variant="ghost"
+            color="neutral"
+            size="xs"
+            icon="i-lucide-x"
+            class="ml-auto"
+            @click="clear"
+          />
+        </div>
+      </div>
+    </template>
+  </UPopover>
+</template>

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

@@ -0,0 +1,106 @@
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import type { FileDescriptor } from "../../types/index.js";
+
+const props = defineProps<{
+  modelValue: unknown;
+  descriptor: FileDescriptor;
+  errors?: string[];
+  readonly?: boolean;
+  disabled?: boolean;
+}>();
+
+const emit = defineEmits<{ "update:modelValue": [value: File | null] }>();
+
+const inputRef = ref<HTMLInputElement | null>(null);
+
+const currentFileName = computed<string | null>(() => {
+  if (props.modelValue instanceof File) return props.modelValue.name;
+  if (typeof props.modelValue === "string" && props.modelValue)
+    return props.modelValue.split("/").pop() ?? props.modelValue;
+  return null;
+});
+
+const previewUrl = computed<string | null>(() => {
+  if (props.modelValue instanceof File) {
+    if (props.modelValue.type.startsWith("image/"))
+      return URL.createObjectURL(props.modelValue);
+  }
+  if (typeof props.modelValue === "string" && props.modelValue) {
+    const ext = props.modelValue.split(".").pop()?.toLowerCase() ?? "";
+    if (["jpg", "jpeg", "png", "gif", "webp", "svg", "avif"].includes(ext))
+      return props.modelValue;
+  }
+  return null;
+});
+
+function onFileChange(e: Event) {
+  const file = (e.target as HTMLInputElement).files?.[0] ?? null;
+  emit("update:modelValue", file);
+}
+
+function clear() {
+  emit("update:modelValue", null);
+  if (inputRef.value) inputRef.value.value = "";
+}
+
+const hasError = computed(() => (props.errors?.length ?? 0) > 0);
+const accept = computed(
+  () => (props.descriptor.attrs?.accept as string) ?? undefined,
+);
+</script>
+
+<template>
+  <div class="mapo-file-field space-y-2">
+    <!-- Current file preview -->
+    <div
+      v-if="currentFileName"
+      class="flex items-center gap-2 rounded border px-3 py-2 text-sm"
+      :class="
+        hasError ? 'border-red-300 bg-red-50' : 'border-gray-200 bg-gray-50'
+      "
+    >
+      <img
+        v-if="previewUrl"
+        :src="previewUrl"
+        class="h-8 w-8 rounded object-cover shrink-0"
+        alt=""
+      />
+      <UIcon
+        v-else
+        name="i-lucide-file"
+        class="size-4 shrink-0 text-gray-400"
+      />
+      <span class="flex-1 truncate text-gray-700">{{ currentFileName }}</span>
+      <UButton
+        v-if="!readonly && !disabled"
+        size="xs"
+        variant="ghost"
+        color="neutral"
+        icon="i-lucide-x"
+        aria-label="Remove file"
+        @click="clear"
+      />
+    </div>
+
+    <!-- File input -->
+    <UInput
+      v-if="!readonly && !disabled"
+      ref="inputRef"
+      type="file"
+      :accept="accept"
+      :color="hasError ? 'error' : undefined"
+      :aria-invalid="hasError ? 'true' : undefined"
+      @change="onFileChange"
+    />
+
+    <p
+      v-for="err in errors"
+      :key="err"
+      class="text-sm text-red-500"
+      role="alert"
+    >
+      {{ err }}
+    </p>
+  </div>
+</template>

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

@@ -0,0 +1,151 @@
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from "vue";
+import { useNuxtApp } from "#app";
+import { debounce } from "@mapomodule/utils";
+import type { FksDescriptor } from "../../types/index.js";
+
+const props = defineProps<{
+  modelValue: unknown;
+  descriptor: FksDescriptor;
+  errors?: string[];
+  readonly?: boolean;
+  disabled?: boolean;
+}>();
+
+const emit = defineEmits<{ "update:modelValue": [value: unknown] }>();
+
+const attrs = computed(() => props.descriptor.attrs);
+const isMultiple = computed(
+  () => props.descriptor.type === "m2m" || !!attrs.value.multiple,
+);
+const itemText = computed(() => attrs.value.itemText ?? "name");
+const itemValue = computed(() => attrs.value.itemValue ?? "id");
+
+// ─── Remote search ───────────────────────────────────────────────────────────
+
+const items = ref<Record<string, unknown>[]>([]);
+const isLoading = ref(false);
+const searchTerm = ref("");
+
+const $mapoFetch = (useNuxtApp() as any).$mapoFetch;
+
+async function fetchItems(query: string) {
+  isLoading.value = true;
+  try {
+    const rawEndpoint = attrs.value.endpoint as string;
+    const endpoint =
+      rawEndpoint.startsWith("/") || rawEndpoint.startsWith("http")
+        ? rawEndpoint
+        : `/${rawEndpoint}`;
+    const url = query
+      ? `${endpoint}${endpoint.includes("?") ? "&" : "?"}search=${encodeURIComponent(query)}`
+      : endpoint;
+    const data = await ($mapoFetch ?? $fetch)(url);
+    // Supports both a plain array and a paginated DRF response { results: [] }.
+    const raw = Array.isArray(data)
+      ? data
+      : ((data as { results?: unknown[] }).results ?? []);
+    items.value = raw as Record<string, unknown>[];
+  } catch {
+    items.value = [];
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+const debouncedFetch = debounce(fetchItems, 300);
+
+// onMounted: fetching is client-only (the select is interactive, so SSR fetch does not add value).
+onMounted(() => fetchItems(""));
+watch(searchTerm, (q) => debouncedFetch(q));
+
+// ─── Value ───────────────────────────────────────────────────────────────────
+
+// returnObject=true (default): modelValue is an object or array of objects.
+// returnObject=false: modelValue is an id or array of ids.
+const internalValue = computed({
+  get: () => props.modelValue,
+  set: (val) => emit("update:modelValue", val),
+});
+
+// Placeholder
+const placeholder = computed(() =>
+  isMultiple.value ? "Search and select..." : "Search...",
+);
+
+// Chip text shown in the trigger.
+// Handles both returnObject=true (item is a full object) and returnObject=false (item is a raw ID).
+function getLabel(item: unknown): string {
+  if (item !== null && item !== undefined && typeof item !== "object") {
+    // Raw ID — look it up in the loaded items array.
+    const found = items.value.find((i) => i[itemValue.value] === item);
+    return found ? String(found[itemText.value] ?? item) : String(item);
+  }
+  if (!item || typeof item !== "object") return "";
+  return String((item as Record<string, unknown>)[itemText.value] ?? "");
+}
+
+// Extracts the comparable key from an item, regardless of whether it's an object or a raw ID.
+function getItemKey(item: unknown): unknown {
+  if (item !== null && item !== undefined && typeof item !== "object")
+    return item;
+  return (item as Record<string, unknown>)?.[itemValue.value];
+}
+</script>
+
+<template>
+  <USelectMenu
+    v-model="internalValue"
+    v-model:search-term="searchTerm"
+    :items="items"
+    :label-key="itemText"
+    :value-key="attrs.returnObject === false ? itemValue : undefined"
+    :by="attrs.returnObject !== false ? (itemValue as string) : undefined"
+    :multiple="isMultiple"
+    :loading="isLoading"
+    :ignore-filter="true"
+    :placeholder="placeholder"
+    :readonly="readonly"
+    :disabled="disabled"
+    :highlight="!!errors?.length"
+    clear
+  >
+    <!-- Chips for multi-selection -->
+    <template
+      v-if="isMultiple && Array.isArray(internalValue) && internalValue.length"
+      #default
+    >
+      <div class="flex flex-wrap gap-1 py-0.5">
+        <UBadge
+          v-for="item in internalValue as unknown[]"
+          :key="String(getItemKey(item))"
+          variant="soft"
+          color="primary"
+          class="cursor-default"
+        >
+          {{ getLabel(item) }}
+          <UButton
+            v-if="!readonly && !disabled"
+            size="xs"
+            variant="ghost"
+            color="primary"
+            icon="i-lucide-x"
+            class="-mr-1 ml-0.5 h-3.5 w-3.5"
+            @click.stop="
+              internalValue = (internalValue as unknown[]).filter(
+                (i) => getItemKey(i) !== getItemKey(item),
+              )
+            "
+          />
+        </UBadge>
+      </div>
+    </template>
+
+    <!-- Empty state -->
+    <template #empty>
+      <span class="text-sm text-gray-500">
+        {{ searchTerm ? "No results found" : "No items available" }}
+      </span>
+    </template>
+  </USelectMenu>
+</template>

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

@@ -0,0 +1,117 @@
+<script setup lang="ts">
+import { ref, computed, defineAsyncComponent } from "vue";
+import type { MapDescriptor } from "../../types/index.js";
+
+// Leaflet is loaded only on the client because it is not SSR-safe.
+const LeafletMap = defineAsyncComponent(
+  () => import("./MapoMapFieldClient.vue"),
+);
+
+/** Geographic coordinates stored by the map field. */
+interface LatLng {
+  lat: number;
+  lng: number;
+}
+
+/** Map field with manual lat/lng inputs plus a client-only Leaflet picker. */
+const props = defineProps<{
+  modelValue: unknown;
+  descriptor: MapDescriptor;
+  errors?: string[];
+  readonly?: boolean;
+  disabled?: boolean;
+}>();
+
+const emit = defineEmits<{ "update:modelValue": [value: LatLng | null] }>();
+
+const attrs = computed(() => props.descriptor.attrs ?? {});
+
+const value = computed<LatLng | null>(() => {
+  const v = props.modelValue;
+  if (!v || typeof v !== "object") return null;
+  const { lat, lng } = v as LatLng;
+  return typeof lat === "number" && typeof lng === "number"
+    ? { lat, lng }
+    : null;
+});
+
+const latInput = ref(value.value?.lat?.toString() ?? "");
+const lngInput = ref(value.value?.lng?.toString() ?? "");
+
+function onMapClick(coords: LatLng) {
+  latInput.value = coords.lat.toFixed(6);
+  lngInput.value = coords.lng.toFixed(6);
+  emit("update:modelValue", coords);
+}
+
+function onManualInput() {
+  const lat = parseFloat(latInput.value);
+  const lng = parseFloat(lngInput.value);
+  if (!isNaN(lat) && !isNaN(lng)) emit("update:modelValue", { lat, lng });
+}
+
+function clear() {
+  latInput.value = "";
+  lngInput.value = "";
+  emit("update:modelValue", null);
+}
+</script>
+
+<template>
+  <div class="mapo-map-field space-y-2">
+    <!-- Manual coordinate inputs -->
+    <div class="flex gap-2">
+      <UInput
+        v-model="latInput"
+        placeholder="Latitude"
+        class="flex-1"
+        :readonly="readonly"
+        :disabled="disabled"
+        @blur="onManualInput"
+      />
+      <UInput
+        v-model="lngInput"
+        placeholder="Longitude"
+        class="flex-1"
+        :readonly="readonly"
+        :disabled="disabled"
+        @blur="onManualInput"
+      />
+      <UButton
+        v-if="value && !readonly && !disabled"
+        variant="ghost"
+        color="neutral"
+        icon="i-lucide-x"
+        @click="clear"
+      />
+    </div>
+
+    <!-- Leaflet map (client only) -->
+    <ClientOnly>
+      <LeafletMap
+        :value="value"
+        :default-lat="attrs.defaultLat ?? 41.9"
+        :default-lng="attrs.defaultLng ?? 12.5"
+        :zoom="attrs.zoom ?? 6"
+        :readonly="readonly ?? false"
+        @click="onMapClick"
+      />
+      <template #fallback>
+        <div
+          class="flex h-48 items-center justify-center rounded border border-gray-200 bg-gray-50 text-sm text-gray-400"
+        >
+          Loading map...
+        </div>
+      </template>
+    </ClientOnly>
+
+    <p
+      v-for="err in errors"
+      :key="err"
+      class="text-sm text-red-500"
+      role="alert"
+    >
+      {{ err }}
+    </p>
+  </div>
+</template>

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

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import { ref, watch, onMounted, onBeforeUnmount } from "vue";
+
+/** Geographic coordinates emitted by the interactive Leaflet client. */
+interface LatLng {
+  lat: number;
+  lng: number;
+}
+
+const props = defineProps<{
+  value: LatLng | null;
+  defaultLat: number;
+  defaultLng: number;
+  zoom: number;
+  readonly: boolean;
+}>();
+
+const emit = defineEmits<{ click: [coords: LatLng] }>();
+
+const mapEl = ref<HTMLElement | null>(null);
+let L: typeof import("leaflet") | null = null;
+let map: import("leaflet").Map | null = null;
+let marker: import("leaflet").Marker | null = null;
+
+onMounted(async () => {
+  // Dynamic import: Leaflet is not SSR-safe.
+  L = (await import("leaflet")).default;
+  await import("leaflet/dist/leaflet.css");
+
+  // Bundle marker icons directly from the npm package (no external CDN):
+  // this avoids exposing the user's IP, CSP issues, and extra runtime dependencies.
+  // Vite resolves `?url` to bundled asset URLs at build time.
+  const [iconRetinaUrl, iconUrl, shadowUrl] = await Promise.all([
+    import("leaflet/dist/images/marker-icon-2x.png?url").then((m) => m.default),
+    import("leaflet/dist/images/marker-icon.png?url").then((m) => m.default),
+    import("leaflet/dist/images/marker-shadow.png?url").then((m) => m.default),
+  ]);
+
+  // @ts-expect-error — _getIconUrl is not part of the public typings
+  delete L.Icon.Default.prototype._getIconUrl;
+  L.Icon.Default.mergeOptions({ iconRetinaUrl, iconUrl, shadowUrl });
+
+  if (!mapEl.value) return;
+
+  map = L.map(mapEl.value).setView(
+    [
+      props.value?.lat ?? props.defaultLat,
+      props.value?.lng ?? props.defaultLng,
+    ],
+    props.zoom,
+  );
+
+  L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
+    attribution:
+      '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>',
+  }).addTo(map);
+
+  if (props.value) {
+    marker = L.marker([props.value.lat, props.value.lng]).addTo(map);
+  }
+
+  if (!props.readonly) {
+    map.on("click", (e: import("leaflet").LeafletMouseEvent) => {
+      const { lat, lng } = e.latlng;
+      if (marker) marker.setLatLng([lat, lng]);
+      else if (L && map) marker = L.marker([lat, lng]).addTo(map);
+      emit("click", { lat, lng });
+    });
+  }
+});
+
+watch(
+  () => props.value,
+  (val) => {
+    if (!map || !L) return;
+    if (val) {
+      if (marker) marker.setLatLng([val.lat, val.lng]);
+      else marker = L.marker([val.lat, val.lng]).addTo(map);
+      map.panTo([val.lat, val.lng]);
+    } else {
+      marker?.remove();
+      marker = null;
+    }
+  },
+);
+
+onBeforeUnmount(() => map?.remove());
+</script>
+
+<template>
+  <div ref="mapEl" class="h-64 w-full rounded border border-gray-200" />
+</template>