Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

19.2 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import type { JSONContent } from "@carbon/react";
import { z } from "zod";

/**
 * Tiptap document content. We keep validation loose (the editor owns the real
 * shape) and only pin the static TS type — mirrors how `terms` is stored.
 */
const jsonContentSchema = z.custom<JSONContent>(
  (val) => typeof val === "object" && val !== null
);

/** Fields shared by every block, built-in or extension. */
const baseFields = {
  id: z.string(),
  visible: z.boolean().default(true)
};

/**
 * Built-in blocks map 1:1 to the hardcoded sections of a document. They are
 * data-bound (the renderer fills them from the document) so they carry no
 * user-authored props — only identity + visibility.
 */
const builtInBlock = <T extends string>(type: T) =>
  z.object({ ...baseFields, type: z.literal(type) });

/**
 * A crop rectangle, normalized to the source image (0..1). `aspect` is the
 * pixel aspect ratio of the cropped region (cropPxW / cropPxH) so renderers can
 * size a clip box without knowing the image's intrinsic dimensions. Shared by
 * the document header logo and the tracking-label logo block.
 */
export const cropSchema = z.object({
  x: z.number().min(0).max(1),
  y: z.number().min(0).max(1),
  width: z.number().min(0).max(1),
  height: z.number().min(0).max(1),
  aspect: z.number().positive()
});
export type LogoCrop = z.infer<typeof cropSchema>;

/** Per-block display options for the Header block (logo + which fields show). */
export const DEFAULT_HEADER_OPTIONS = {
  showLogo: true,
  logoVariant: "mark",
  logoHeight: 50,
  showCompanyDetails: true,
  showDocumentTitle: true,
  showDocumentId: true
} as const;

export const headerOptionsSchema = z.object({
  showLogo: z.boolean().default(true),
  /** Which company logo to use: full logo (`mark`) or the square `icon`. */
  logoVariant: z.enum(["mark", "icon"]).default("mark"),
  logoHeight: z.number().min(16).max(120).default(50),
  /** Optional crop applied before rendering (PDF clip box). */
  logoCrop: cropSchema.optional(),
  showCompanyDetails: z.boolean().default(true),
  showDocumentTitle: z.boolean().default(true),
  showDocumentId: z.boolean().default(true)
});

/** Per-block display options for the Line Items table. */
export const DEFAULT_LINE_ITEMS_OPTIONS = {
  showThumbnails: true,
  zebra: true,
  textOverflow: "truncate"
} as const;

const lineItemsOptionsSchema = z.object({
  showThumbnails: z.boolean().default(true),
  zebra: z.boolean().default(true),
  /** How the item title/description behave: wrap to new lines or truncate. */
  textOverflow: z.enum(["wrap", "truncate"]).default("truncate")
});

/** Per-block options for the Summary totals. */
export const DEFAULT_SUMMARY_OPTIONS = {
  taxLabel: "Taxes"
} as const;

const summaryOptionsSchema = z.object({
  taxLabel: z.string().default("Taxes")
});

const headerBlock = z.object({
  ...baseFields,
  type: z.literal("header"),
  options: headerOptionsSchema.optional()
});
const partiesBlock = builtInBlock("parties");
const notesBlock = builtInBlock("notes");
/** Data-bound metadata block (e.g. shipment/transfer details). */
const detailsBlock = builtInBlock("details");
const lineItemsBlock = z.object({
  ...baseFields,
  type: z.literal("lineItems"),
  options: lineItemsOptionsSchema.optional()
});
const summaryBlock = z.object({
  ...baseFields,
  type: z.literal("summary"),
  options: summaryOptionsSchema.optional()
});
/**
 * Terms & Conditions. Built-in (not addable/removable) but carries its own
 * rich-text `content` — per-document, seeded from the company terms setting.
 * Empty content falls back to that setting at render time.
 */
const termsBlock = z.object({
  ...baseFields,
  type: z.literal("terms"),
  content: jsonContentSchema.optional()
});
/** Job Traveler built-ins (data-bound; render the existing bespoke content). */
const jobDetailsBlock = builtInBlock("jobDetails");
const operationsBlock = z.object({
  ...baseFields,
  type: z.literal("operations"),
  /** Print the full work instructions / procedure steps under each operation. */
  showWorkInstructions: z.boolean().default(false)
});
/** Issue built-ins (data-bound; render the existing bespoke content). */
const issueDetailsBlock = builtInBlock("issueDetails");
const associationsBlock = builtInBlock("associations");
const actionTasksBlock = builtInBlock("actionTasks");
const reviewersBlock = builtInBlock("reviewers");
/**
 * Who approved the document: a heading, the approver's signature over a line,
 * and a rich-text caption with merge fields (the approver and the date by
 * default). Prints nothing until the document is approved.
 */
const approvalBlock = z.object({
  ...baseFields,
  type: z.literal("approval"),
  /** Absent: "Approved By". An empty string prints no heading. */
  heading: z.string().optional(),
  showSignature: z.boolean().optional(),
  /** Empty: `DEFAULT_APPROVAL_CAPTION`. */
  content: jsonContentSchema.optional()
});
/** Tracking-label fields (data-bound; one per label element). */
const labelHeadingBlock = builtInBlock("labelHeading");
/** A label field whose printed name (the prefix before the value) is editable. */
const labelNamedField = <T extends string>(type: T) =>
  z.object({
    ...baseFields,
    type: z.literal(type),
    label: z.string().optional()
  });
const labelRevisionBlock = labelNamedField("labelRevision");
const labelQuantityBlock = labelNamedField("labelQuantity");
const labelTrackingBlock = labelNamedField("labelTracking");
/** A human-readable identifier line (defaults to the tracked-entity id). */
const labelEntityIdBlock = z.object({
  ...baseFields,
  type: z.literal("labelEntityId"),
  value: z.string().default("{label.trackedEntityId}")
});
/**
 * A scannable code (QR / PDF417 / Code128 / DataMatrix). `placement` is "right"
 * (small, top-right next to the logo) or "full" (full-width band, e.g. PDF417).
 */
const labelBarcodeBlock = z.object({
  ...baseFields,
  type: z.literal("labelBarcode"),
  symbology: z
    .enum(["qrcode", "pdf417", "code128", "datamatrix"])
    .default("qrcode"),
  value: z.string().default("{label.trackedEntityId}"),
  placement: z.enum(["right", "full", "center"]).default("right"),
  height: z.number().min(16).max(300).optional()
});
/** The company logo. Color in the PDF by default; `monochrome` for B&W / ZPL. */
const labelLogoBlock = z.object({
  ...baseFields,
  type: z.literal("labelLogo"),
  /** Which company logo to use: full logo (`mark`) or the square `icon`. */
  variant: z.enum(["mark", "icon"]).default("mark"),
  monochrome: z.boolean().optional(),
  /** Optional crop applied before rendering (PDF clip box / ZPL pre-crop). */
  crop: cropSchema.optional(),
  height: z.number().min(16).max(160).optional()
});

/** Extension blocks are user-authored and fully removable. */
const richTextBlock = z.object({
  ...baseFields,
  type: z.literal("richText"),
  title: z.string().optional(),
  content: jsonContentSchema
});

const keyValueBlock = z.object({
  ...baseFields,
  type: z.literal("keyValue"),
  title: z.string().optional(),
  rows: z.array(z.object({ label: z.string(), value: z.string() })).default([])
});

const spacerBlock = z.object({
  ...baseFields,
  type: z.literal("spacer"),
  variant: z.enum(["space", "divider", "pageBreak"]).default("space"),
  /** Height in pt, only used by the "space" variant. */
  size: z.number().min(0).max(200).optional()
});

/** Reference to a shared documentSection, resolved at render time. */
const sharedBlock = z.object({
  ...baseFields,
  type: z.literal("shared"),
  sectionId: z.string()
});

/**
 * A single authored line: an optional `label` plus a `value`. With no label it
 * is plain text; with a label it is a single key-value. Maps 1:1 to one ZPL
 * `^FD` line, so it's the label-safe alternative to rich text / key-value lists.
 */
const fieldBlock = z.object({
  ...baseFields,
  type: z.literal("field"),
  label: z.string().optional(),
  value: z.string().default("")
});

/** Displays a single custom-field value (label + value) from the record. */
const customFieldBlock = z.object({
  ...baseFields,
  type: z.literal("customField"),
  /** The custom field's id (key into the record's `customFields` JSON). */
  fieldId: z.string(),
  /** Display label — defaults to the field's name at insert time. */
  label: z.string().default("")
});

/** Faint full-page company watermark (uses the company's watermark logo). */
const watermarkBlock = z.object({
  ...baseFields,
  type: z.literal("watermark"),
  opacity: z.number().min(0).max(1).default(0.07),
  placement: z.enum(["center", "top", "bottom"]).default("center"),
  size: z.number().min(10).max(100).default(50)
});

export const blockSchema = z.discriminatedUnion("type", [
  headerBlock,
  watermarkBlock,
  partiesBlock,
  notesBlock,
  detailsBlock,
  lineItemsBlock,
  summaryBlock,
  termsBlock,
  jobDetailsBlock,
  operationsBlock,
  issueDetailsBlock,
  associationsBlock,
  actionTasksBlock,
  reviewersBlock,
  approvalBlock,
  labelHeadingBlock,
  labelRevisionBlock,
  labelQuantityBlock,
  labelTrackingBlock,
  labelEntityIdBlock,
  labelBarcodeBlock,
  labelLogoBlock,
  richTextBlock,
  keyValueBlock,
  spacerBlock,
  sharedBlock,
  fieldBlock,
  customFieldBlock
]);

/** Shared, reusable rich-text section. `placement` scopes where it's used. */
export const documentSectionPlacementSchema = z.enum([
  "body",
  "header",
  "footer"
]);

/** Default registration number shown in the footer when none is configured. */
export const DEFAULT_REGISTRATION_NUMBER = "{company.registrationNumber}";

export const DEFAULT_FOOTER_OPTIONS = {
  showRegistrationLine: true,
  registrationNumber: DEFAULT_REGISTRATION_NUMBER
} as const;

/** Registration-line config carried by a footer section. */
export const footerOptionsSchema = z.object({
  /** Show the "{company} is registered in {country}" line. */
  showRegistrationLine: z.boolean().default(true),
  /**
   * Free-text registration number appended as "Company Registration Number
   * {value}". Supports `{token}` merge fields (e.g. `{company.taxId}`).
   */
  registrationNumber: z.string().default(DEFAULT_REGISTRATION_NUMBER)
});

/**
 * Config carried by a shared section. Header sections store layout (logo +
 * which company fields show); footer sections store the registration line.
 * Global: sections are reused across every document, so this config is too.
 */
export const sectionConfigSchema = headerOptionsSchema
  .partial()
  .merge(footerOptionsSchema.partial());

export const documentSectionSchema = z.object({
  name: z.string().min(1),
  placement: documentSectionPlacementSchema.default("body"),
  content: jsonContentSchema,
  config: sectionConfigSchema.optional()
});

const HEX_COLOR = /^#([0-9a-fA-F]{6})$/;

export const DEFAULT_THEME = {
  /** Strong brand color — fills the line-items header bar. */
  accent: "#1f2937",
  /** Text/icons drawn on top of the accent color. */
  accentForeground: "#ffffff",
  /** Section headings (BILL TO, INVOICE DETAILS, NOTES…). Maps gray-600. */
  heading: "#4b5563",
  /** Body text: addresses, line-item values, the document title. Maps gray-800. */
  text: "#1f2937"
} as const;

export const themeSchema = z.object({
  accent: z.string().regex(HEX_COLOR).default(DEFAULT_THEME.accent),
  accentForeground: z
    .string()
    .regex(HEX_COLOR)
    .default(DEFAULT_THEME.accentForeground),
  heading: z.string().regex(HEX_COLOR).default(DEFAULT_THEME.heading),
  text: z.string().regex(HEX_COLOR).default(DEFAULT_THEME.text)
});

// Body fonts offered in the editor. Helvetica/Times/Courier are PDF built-ins; the
// rest are bundled (see pdf/fonts.ts).
export const DOCUMENT_FONTS = [
  { value: "Inter", label: "Inter", kind: "Sans" },
  { value: "Helvetica", label: "Helvetica", kind: "Sans" },
  { value: "Times-Roman", label: "Times", kind: "Serif" },
  { value: "Courier", label: "Courier", kind: "Mono" },
  { value: "Roboto", label: "Roboto", kind: "Sans" },
  { value: "Open Sans", label: "Open Sans", kind: "Sans" },
  { value: "Lato", label: "Lato", kind: "Sans" },
  { value: "Montserrat", label: "Montserrat", kind: "Sans" },
  { value: "Merriweather", label: "Merriweather", kind: "Serif" },
  { value: "Playfair Display", label: "Playfair Display", kind: "Serif" },
  { value: "Lora", label: "Lora", kind: "Serif" }
] as const;

export type DocumentFont = (typeof DOCUMENT_FONTS)[number]["value"];

/** Document-level settings (font + footer page numbers). */
export const DEFAULT_DOCUMENT_SETTINGS = {
  fontFamily: "Inter",
  showPageNumbers: true,
  pageNumberFormat: "pageOfTotal",
  showRegistrationLine: true
} as const;

export const documentSettingsSchema = z.object({
  fontFamily: z
    .enum([
      "Inter",
      "Helvetica",
      "Times-Roman",
      "Courier",
      "Roboto",
      "Open Sans",
      "Lato",
      "Montserrat",
      "Merriweather",
      "Playfair Display",
      "Lora"
    ])
    .default("Inter"),
  showPageNumbers: z.boolean().default(true),
  /** "pageOfTotal" → "Page 1 of 3"; "page" → "Page 1". */
  pageNumberFormat: z.enum(["pageOfTotal", "page"]).default("pageOfTotal"),
  /**
   * Legacy per-template toggle for the footer registration line. The footer
   * section's config (`sectionConfigSchema.showRegistrationLine`) takes
   * precedence when set — edit it via the footer section modal.
   */
  showRegistrationLine: z.boolean().default(true)
});

/** Document types that support a customizable template. Widen as docs ship. */
export const documentTemplateTypeSchema = z.enum([
  "salesInvoice",
  "salesOrder",
  "salesReturnOrder",
  "purchaseOrder",
  "purchaseReturnOrder",
  "purchasingRfq",
  "quote",
  "packingSlip",
  "stockTransfer",
  "jobTraveler",
  "issue",
  "trackingLabel"
]);

/**
 * Doc types whose PDFs render the footer registration line (via
 * `resolveRegistrationLine`). Add a type here when its PDF adopts it — the
 * footer section modal derives its helper text from this list.
 */
export const REGISTRATION_LINE_DOCUMENT_TYPES: DocumentTemplateType[] = [
  "salesInvoice",
  "salesOrder",
  "salesReturnOrder",
  "purchaseOrder",
  "purchaseReturnOrder",
  "purchasingRfq",
  "quote",
  "packingSlip"
];

/**
 * Schema version of the stored template JSON. Bump when the block/theme shape
 * changes in a non-additive way; `resolveTemplate` migrates older versions
 * forward on read. (Idea borrowed from Bindery's `formatVersion`.)
 */
export const CURRENT_TEMPLATE_FORMAT_VERSION = 1;

export const documentTemplateSchema = z.object({
  formatVersion: z.number().int().default(CURRENT_TEMPLATE_FORMAT_VERSION),
  documentType: documentTemplateTypeSchema,
  blocks: z.array(blockSchema),
  theme: themeSchema.default(DEFAULT_THEME),
  settings: documentSettingsSchema.default(DEFAULT_DOCUMENT_SETTINGS),
  /** Shared sections used as the repeating page header/footer (or none). */
  headerSectionId: z.string().nullable().default(null),
  footerSectionId: z.string().nullable().default(null)
});

export type DocumentBlock = z.infer<typeof blockSchema>;
export type DocumentBlockType = DocumentBlock["type"];
export type SharedBlock = Extract<DocumentBlock, { type: "shared" }>;
export type DocumentSection = z.infer<typeof documentSectionSchema>;
export type DocumentSectionPlacement = z.infer<
  typeof documentSectionPlacementSchema
>;
/** A section row resolved for rendering (id + name + content + layout config). */
export interface ResolvedSection {
  id: string;
  name: string;
  placement: DocumentSectionPlacement;
  content: JSONContent;
  /** Header layout (logo, which fields show) or footer registration line. */
  config?: SectionConfig;
  /** True for code-provided system sections — shown read-only in the library. */
  builtIn?: boolean;
}
export type DocumentTheme = z.infer<typeof themeSchema>;
export type DocumentSettings = z.infer<typeof documentSettingsSchema>;
export type DocumentTemplate = z.infer<typeof documentTemplateSchema>;
export type DocumentTemplateType = z.infer<typeof documentTemplateTypeSchema>;

/** The stored `documentTemplate` row shape (JSON columns are untyped here). */
export interface StoredDocumentTemplateRow {
  formatVersion?: number | null;
  blocks?: unknown;
  theme?: unknown;
  settings?: unknown;
  headerSectionId?: string | null;
  footerSectionId?: string | null;
}

/**
 * Map a stored `documentTemplate` row to a `DocumentTemplate` (or null). The one
 * place the JSON columns are cast — callers (services + PDF/ZPL routes) use this
 * instead of re-deriving the shape. The result still passes through
 * `resolveTemplate` at render, which applies defaults/validation.
 */
export function toDocumentTemplate(
  row: unknown,
  documentType: DocumentTemplateType
): DocumentTemplate | null {
  if (!row) return null;
  const r = row as StoredDocumentTemplateRow;
  return {
    formatVersion: r.formatVersion ?? CURRENT_TEMPLATE_FORMAT_VERSION,
    documentType,
    blocks: r.blocks as DocumentTemplate["blocks"],
    theme: r.theme as DocumentTemplate["theme"],
    settings: r.settings as DocumentTemplate["settings"],
    headerSectionId: r.headerSectionId ?? null,
    footerSectionId: r.footerSectionId ?? null
  };
}

/** Narrowing helpers for the extension blocks (used by editor + renderers). */
export type RichTextBlock = Extract<DocumentBlock, { type: "richText" }>;
export type KeyValueBlock = Extract<DocumentBlock, { type: "keyValue" }>;
export type SpacerBlock = Extract<DocumentBlock, { type: "spacer" }>;
export type TermsBlock = Extract<DocumentBlock, { type: "terms" }>;
export type HeaderBlock = Extract<DocumentBlock, { type: "header" }>;
export type HeaderOptions = z.infer<typeof headerOptionsSchema>;
export type FooterOptions = z.infer<typeof footerOptionsSchema>;
export type SectionConfig = z.infer<typeof sectionConfigSchema>;
export type LineItemsBlock = Extract<DocumentBlock, { type: "lineItems" }>;
export type LineItemsOptions = z.infer<typeof lineItemsOptionsSchema>;
export type SummaryBlock = Extract<DocumentBlock, { type: "summary" }>;
export type SummaryOptions = z.infer<typeof summaryOptionsSchema>;
export type FieldBlock = Extract<DocumentBlock, { type: "field" }>;
export type CustomFieldBlock = Extract<DocumentBlock, { type: "customField" }>;
export type JobDetailsBlock = Extract<DocumentBlock, { type: "jobDetails" }>;
export type OperationsBlock = Extract<DocumentBlock, { type: "operations" }>;
export type IssueDetailsBlock = Extract<
  DocumentBlock,
  { type: "issueDetails" }
>;
export type AssociationsBlock = Extract<
  DocumentBlock,
  { type: "associations" }
>;
export type ActionTasksBlock = Extract<DocumentBlock, { type: "actionTasks" }>;
export type ReviewersBlock = Extract<DocumentBlock, { type: "reviewers" }>;
export type ApprovalBlock = Extract<DocumentBlock, { type: "approval" }>;
export type LabelHeadingBlock = Extract<
  DocumentBlock,
  { type: "labelHeading" }
>;
/** Label fields whose printed name is editable. */
export type LabelNamedBlock = Extract<
  DocumentBlock,
  { type: "labelRevision" | "labelQuantity" | "labelTracking" }
>;
export type LabelBarcodeBlock = Extract<
  DocumentBlock,
  { type: "labelBarcode" }
>;
export type LabelLogoBlock = Extract<DocumentBlock, { type: "labelLogo" }>;
export type WatermarkBlock = Extract<DocumentBlock, { type: "watermark" }>;
export type LabelEntityIdBlock = Extract<
  DocumentBlock,
  { type: "labelEntityId" }
>;