/**
 * Phase 7 - PDF template editor field-map type definitions.
 *
 * The editor (deferred to 7.1/7.2) operates on the existing
 * `document_templates.overlay_positions` JSONB column with the extended
 * shape below. No schema migration is required - JSONB already accepts
 * any shape; the only contract is the Zod validator on the API boundary.
 *
 * Coordinates are stored as percent of page width/height (0..1) so
 * field placements survive page-size changes (A4 → US Letter etc.).
 * The legacy overlay schema used absolute coords; the editor migrates
 * those on first save by reading the source PDF's page dimensions.
 */

import { z } from 'zod';

export const fieldMapEntrySchema = z.object({
  /** Must match an entry in VALID_MERGE_TOKENS (validated at the API). */
  token: z.string().min(1).max(100),
  /** 1-indexed page number. */
  page: z.number().int().min(1),
  /** Percent of page width - top-left corner of the marker. */
  x: z.number().min(0).max(1),
  /** Percent of page height - top-left corner of the marker. */
  y: z.number().min(0).max(1),
  /** Percent width - defaults to 0.15 if omitted by an older editor. */
  w: z.number().min(0).max(1).optional(),
  /** Percent height - defaults to 0.04. */
  h: z.number().min(0).max(1).optional(),
  /** Optional explicit font size; otherwise auto-fit to the box. */
  fontSize: z.number().int().min(6).max(72).optional(),
});

export const fieldMapSchema = z.array(fieldMapEntrySchema).max(500);

export type FieldMapEntry = z.infer<typeof fieldMapEntrySchema>;
export type FieldMap = z.infer<typeof fieldMapSchema>;

/**
 * Cross-validate a parsed field-map against the source PDF page count.
 * The editor surfaces a warning when an upload truncates the page set
 * (e.g. uploading a 3-page PDF over a 5-page template). Returns null
 * when valid, or an error message describing the first out-of-range
 * marker.
 */
export function validateFieldMapAgainstPageCount(map: FieldMap, pageCount: number): string | null {
  for (const m of map) {
    if (m.page > pageCount) {
      return `Field "${m.token}" sits on page ${m.page} but the PDF only has ${pageCount} pages.`;
    }
  }
  return null;
}
