@12-apps/forms-core 1.0.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@12-apps/forms-core",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Pure, framework-agnostic form primitives — field validators, the Result type, and createServerAction. Zero dependencies, consumed from source by @12-apps/ui and apps.",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules coverage",
+    "test": "node ../../scripts/vitest-with-teardown.mjs run",
+    "test:watch": "vitest watch",
+    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@12-apps/typescript-config": "^1.1.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/12-apps/shared-packages.git",
+    "directory": "packages/forms-core"
+  },
+  "files": [
+    "src",
+    "dist",
+    "prisma",
+    "*.js",
+    "*.mjs",
+    "*.md"
+  ]
+}

package/src/br.spec.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  cep,
+  CEP_PATTERN,
+  cepDigits,
+  cnpj,
+  cnpjChars,
+  formatCep,
+  formatCnpj,
+  isUf,
+  isValidCep,
+  isValidCnpj,
+  UF_LIST,
+} from './br';
+
+/**
+ * `11.222.333/0001-81` is the canonical all-numeric fixture; `12.ABC.345/01DE-35`
+ * is Receita Federal's own alphanumeric example (IN 2.229/2024).
+ */
+const VALID_NUMERIC = '11.222.333/0001-81';
+const VALID_ALPHANUMERIC = '12.ABC.345/01DE-35';
+
+describe('forms-core/br', () => {
+  describe('UF_LIST / isUf', () => {
+    it('holds the 27 federative units', () => {
+      expect(UF_LIST).toHaveLength(27);
+      expect(new Set(UF_LIST).size).toBe(27);
+    });
+
+    it('accepts a real UF and rejects anything else', () => {
+      expect(isUf('SP')).toBe(true);
+      expect(isUf('sp')).toBe(false);
+      expect(isUf('XX')).toBe(false);
+    });
+  });
+
+  describe('cepDigits', () => {
+    it('keeps only digits, capped at eight', () => {
+      expect(cepDigits('01310-100')).toBe('01310100');
+      expect(cepDigits('01310100999')).toBe('01310100');
+      expect(cepDigits('abc')).toBe('');
+    });
+  });
+
+  describe('formatCep', () => {
+    it('inserts the hyphen once the sixth digit arrives', () => {
+      expect(formatCep('01310')).toBe('01310');
+      expect(formatCep('013101')).toBe('01310-1');
+      expect(formatCep('01310100')).toBe('01310-100');
+    });
+
+    it('is idempotent and forgiving of messy input', () => {
+      expect(formatCep(formatCep('01310100'))).toBe('01310-100');
+      expect(formatCep('01.310-100')).toBe('01310-100');
+    });
+
+    it('produces a value matching CEP_PATTERN once complete', () => {
+      expect(CEP_PATTERN.test(formatCep('01310100'))).toBe(true);
+    });
+  });
+
+  describe('isValidCep', () => {
+    it('accepts a complete CEP in either shape', () => {
+      expect(isValidCep('01310100')).toBe(true);
+      expect(isValidCep('01310-100')).toBe(true);
+    });
+
+    it('rejects an incomplete or oversized CEP', () => {
+      expect(isValidCep('0131010')).toBe(false);
+      expect(isValidCep('')).toBe(false);
+    });
+  });
+
+  describe('cep validator', () => {
+    it('treats empty as valid (the field is optional)', () => {
+      expect(cep()('')).toBeUndefined();
+      expect(cep()('   ')).toBeUndefined();
+    });
+
+    it('returns a message for a malformed CEP', () => {
+      expect(cep()('123')).toBeTruthy();
+      expect(cep('Informe o CEP')('123')).toBe('Informe o CEP');
+    });
+
+    it('returns undefined for a well-formed CEP', () => {
+      expect(cep()('01310-100')).toBeUndefined();
+    });
+  });
+
+  describe('cnpjChars', () => {
+    it('strips punctuation, uppercases and keeps letters', () => {
+      expect(cnpjChars(VALID_NUMERIC)).toBe('11222333000181');
+      expect(cnpjChars('12.abc.345/01de-35')).toBe('12ABC34501DE35');
+    });
+
+    it('caps at fourteen characters', () => {
+      expect(cnpjChars('11222333000181999')).toHaveLength(14);
+    });
+  });
+
+  describe('formatCnpj', () => {
+    it('masks progressively as characters arrive', () => {
+      expect(formatCnpj('11')).toBe('11');
+      expect(formatCnpj('11222')).toBe('11.222');
+      expect(formatCnpj('11222333')).toBe('11.222.333');
+      expect(formatCnpj('112223330001')).toBe('11.222.333/0001');
+      expect(formatCnpj('11222333000181')).toBe(VALID_NUMERIC);
+    });
+
+    it('masks an alphanumeric CNPJ', () => {
+      expect(formatCnpj('12ABC34501DE35')).toBe(VALID_ALPHANUMERIC);
+      expect(formatCnpj('12abc34501de35')).toBe(VALID_ALPHANUMERIC);
+    });
+
+    it('is idempotent', () => {
+      expect(formatCnpj(VALID_NUMERIC)).toBe(VALID_NUMERIC);
+      expect(formatCnpj(VALID_ALPHANUMERIC)).toBe(VALID_ALPHANUMERIC);
+    });
+
+    it('never lets a letter into the check-digit positions', () => {
+      expect(formatCnpj('12ABC34501DEXY')).toBe('12.ABC.345/01DE-');
+    });
+  });
+
+  describe('isValidCnpj', () => {
+    it('accepts an all-numeric CNPJ, masked or bare', () => {
+      expect(isValidCnpj(VALID_NUMERIC)).toBe(true);
+      expect(isValidCnpj('11222333000181')).toBe(true);
+    });
+
+    it("accepts Receita Federal's alphanumeric example", () => {
+      expect(isValidCnpj(VALID_ALPHANUMERIC)).toBe(true);
+      expect(isValidCnpj('12abc34501de35')).toBe(true);
+    });
+
+    it('rejects a wrong check digit', () => {
+      expect(isValidCnpj('11222333000182')).toBe(false);
+      expect(isValidCnpj('12ABC34501DE36')).toBe(false);
+    });
+
+    it('rejects a repeated-character sequence', () => {
+      expect(isValidCnpj('00000000000000')).toBe(false);
+      expect(isValidCnpj('11111111111111')).toBe(false);
+    });
+
+    it('rejects the wrong length', () => {
+      expect(isValidCnpj('')).toBe(false);
+      expect(isValidCnpj('1122233300018')).toBe(false);
+    });
+
+    it('rejects letters in the check-digit positions', () => {
+      expect(isValidCnpj('12ABC34501DEAB')).toBe(false);
+    });
+  });
+
+  describe('cnpj validator', () => {
+    it('treats empty as valid (the field is optional)', () => {
+      expect(cnpj()('')).toBeUndefined();
+      expect(cnpj()('   ')).toBeUndefined();
+    });
+
+    it('returns a message for an invalid CNPJ', () => {
+      expect(cnpj()('11222333000182')).toBeTruthy();
+      expect(cnpj('Confira o CNPJ')('123')).toBe('Confira o CNPJ');
+    });
+
+    it('returns undefined for a valid CNPJ', () => {
+      expect(cnpj()(VALID_NUMERIC)).toBeUndefined();
+      expect(cnpj()(VALID_ALPHANUMERIC)).toBeUndefined();
+    });
+  });
+});

package/src/br.ts

@@ -0,0 +1,190 @@
+/**
+ * Brazilian document + address primitives (FUT-306).
+ *
+ * Masks, shape checks and check-digit validation for the two fields every
+ * pt-BR form asks for — CEP and CNPJ — plus the UF list. Pure and dependency
+ * free like the rest of `forms-core`, so the SAME rules run in the browser
+ * (input mask + inline validation), in a route handler (before hitting a
+ * lookup provider) and in a test.
+ *
+ * @module forms-core/br
+ */
+
+import type { Validator } from './validators';
+
+/** Brazilian federative units, for UF selects and client-side validation. */
+export const UF_LIST = [
+  'AC', 'AL', 'AP', 'AM', 'BA', 'CE', 'DF', 'ES', 'GO',
+  'MA', 'MT', 'MS', 'MG', 'PA', 'PB', 'PR', 'PE', 'PI',
+  'RJ', 'RN', 'RS', 'RO', 'RR', 'SC', 'SP', 'SE', 'TO',
+] as const;
+
+/** A Brazilian federative unit. */
+export type Uf = (typeof UF_LIST)[number];
+
+/** True when `value` is one of the 27 {@link UF_LIST} entries (case-sensitive). */
+export function isUf(value: string): value is Uf {
+  return (UF_LIST as readonly string[]).includes(value);
+}
+
+// ---------------------------------------------------------------------------
+// CEP
+// ---------------------------------------------------------------------------
+
+/** Canonical CEP shape after masking/normalization: `01310-100`. */
+export const CEP_PATTERN = /^\d{5}-\d{3}$/;
+
+/** The bare digits of a CEP, capped at the 8 a CEP has. */
+export function cepDigits(raw: string): string {
+  return raw.replace(/\D/g, '').slice(0, 8);
+}
+
+/**
+ * Mask raw CEP input to `#####-###`: strips non-digits, caps at 8 digits and
+ * inserts the hyphen once the sixth digit arrives. Pure — safe to run on every
+ * keystroke and to normalize before matching {@link CEP_PATTERN}.
+ */
+export function formatCep(raw: string): string {
+  const digits = cepDigits(raw);
+  return digits.length > 5 ? `${digits.slice(0, 5)}-${digits.slice(5)}` : digits;
+}
+
+/**
+ * True when `raw` holds a complete, well-formed CEP.
+ *
+ * Shape only: a CEP is a postal RANGE allocated by the Correios, so there is no
+ * check digit to verify. Whether it actually EXISTS is answered by a lookup,
+ * not by this function.
+ */
+export function isValidCep(raw: string): boolean {
+  return CEP_PATTERN.test(formatCep(raw));
+}
+
+/** Empty ⇒ valid (optional field); otherwise the value must be a full CEP. */
+export const cep =
+  (message = 'CEP inválido — use o formato 00000-000.'): Validator =>
+  (value) =>
+    value.trim() === '' || isValidCep(value) ? undefined : message;
+
+// ---------------------------------------------------------------------------
+// CNPJ
+// ---------------------------------------------------------------------------
+
+/** Canonical CNPJ shape after masking: `12.ABC.345/01DE-35`. */
+export const CNPJ_PATTERN = /^[0-9A-Z]{2}\.[0-9A-Z]{3}\.[0-9A-Z]{3}\/[0-9A-Z]{4}-\d{2}$/;
+
+/** How many characters a CNPJ has, check digits included. */
+const CNPJ_LENGTH = 14;
+
+/**
+ * Strip a CNPJ to its 14 significant characters, uppercased.
+ *
+ * Alphanumeric-aware (Receita Federal IN 2.229/2024, live in production since
+ * 2026-07-06): the first 12 positions may be letters OR digits, so only
+ * punctuation is removed — never letters.
+ */
+export function cnpjChars(raw: string): string {
+  return raw.toUpperCase().replace(/[^0-9A-Z]/g, '').slice(0, CNPJ_LENGTH);
+}
+
+/**
+ * Mask raw CNPJ input to `##.###.###/####-##`, accepting letters in the first
+ * twelve positions and digits in the two check positions.
+ */
+export function formatCnpj(raw: string): string {
+  const chars = cnpjChars(raw);
+  const parts = [
+    chars.slice(0, 2),
+    chars.slice(2, 5),
+    chars.slice(5, 8),
+    chars.slice(8, 12),
+    // The check digits are always numeric, even on an alphanumeric CNPJ.
+    chars.slice(12, 14).replace(/\D/g, ''),
+  ];
+  let masked = parts[0] as string;
+  if (chars.length > 2) masked += `.${parts[1]}`;
+  if (chars.length > 5) masked += `.${parts[2]}`;
+  if (chars.length > 8) masked += `/${parts[3]}`;
+  if (chars.length > 12) masked += `-${parts[4]}`;
+  return masked;
+}
+
+/**
+ * The mod-11 weights, right-to-left cycling 2…9. `slice(-n)` takes the tail so
+ * the same table serves the 12-char first pass and the 13-char second.
+ */
+const CNPJ_WEIGHTS = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2] as const;
+
+/**
+ * A character's numeric contribution: its ASCII code minus 48. Digits `0`–`9`
+ * map to 0–9 (identical to the legacy rule, so existing CNPJs keep validating)
+ * and letters `A`–`Z` map to 17–42.
+ */
+function cnpjValue(char: string): number {
+  return char.charCodeAt(0) - 48;
+}
+
+/** One mod-11 check digit over the first `base.length` characters. */
+function cnpjCheckDigit(base: string): number {
+  const weights = CNPJ_WEIGHTS.slice(-base.length);
+  const sum = [...base].reduce((acc, char, i) => acc + cnpjValue(char) * (weights[i] as number), 0);
+  const remainder = sum % 11;
+  return remainder < 2 ? 0 : 11 - remainder;
+}
+
+/**
+ * Validate a CNPJ's check digits (mod 11), alphanumeric-aware.
+ *
+ * Rejects the repeated-character sequences (`00000000000000`, `AAAAAAAAAAAA35`)
+ * that satisfy the arithmetic but are never issued. Returns false for anything
+ * that is not exactly 14 characters with numeric check digits.
+ */
+export function isValidCnpj(raw: string): boolean {
+  const chars = cnpjChars(raw);
+  if (chars.length !== CNPJ_LENGTH) return false;
+  // Only the 12-character root/establishment may be alphanumeric; the two check
+  // digits stay numeric.
+  if (!/^\d{2}$/.test(chars.slice(12))) return false;
+  if (new Set(chars).size === 1) return false;
+
+  const base = chars.slice(0, 12);
+  const first = cnpjCheckDigit(base);
+  if (first !== Number(chars[12])) return false;
+  return cnpjCheckDigit(`${base}${first}`) === Number(chars[13]);
+}
+
+/** Empty ⇒ valid (optional field); otherwise the check digits must match. */
+export const cnpj =
+  (message = 'CNPJ inválido — confira os dígitos.'): Validator =>
+  (value) =>
+    value.trim() === '' || isValidCnpj(value) ? undefined : message;
+
+// ---------------------------------------------------------------------------
+// Telefone
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a Brazilian phone as `(11) 3214-5600` / `(11) 91234-5678`.
+ *
+ * Both sources that hand us a phone give it as bare concatenated digits — the
+ * Receita Federal's `ddd_telefone_1` and an NF-e's `<fone>` — so the same
+ * formatting rule serves the CNPJ lookup and the nota importer.
+ *
+ * Anything that is not a 10- or 11-digit national number is returned trimmed
+ * but otherwise untouched: an unrecognized phone (a foreign issuer, an extension
+ * appended by the emitter's software) is still better dropped into the field
+ * than discarded.
+ *
+ * @param raw - Digits as the source supplies them, e.g. `1132145600`.
+ * @returns The formatted phone, or `null` when there is nothing to format.
+ */
+export function formatBrPhone(raw: string | null | undefined): string | null {
+  const trimmed = raw?.trim();
+  if (!trimmed) return null;
+  const digits = trimmed.replace(/\D/g, '');
+  if (digits.length !== 10 && digits.length !== 11) return trimmed;
+  const ddd = digits.slice(0, 2);
+  const subscriber = digits.slice(2);
+  const split = subscriber.length - 4;
+  return `(${ddd}) ${subscriber.slice(0, split)}-${subscriber.slice(split)}`;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Pure form primitives barrel.
+ *
+ * The field validators, the `Result<T>` type with its `ok`/`err` constructors,
+ * and the `createServerAction` wrapper + `ActionError`. Zero dependencies — safe
+ * to import from a client component, a server action, or a plain node context
+ * alike.
+ *
+ * @module forms-core
+ */
+export * from './validators';
+export * from './result';
+export * from './serverAction';
+export * from './br';

package/src/result.ts

@@ -0,0 +1,44 @@
+/**
+ * Discriminated-union result type for operations that can fail.
+ *
+ * Pure and framework-agnostic. The `ok` discriminant narrows the union so
+ * consumers can safely read `data` on success or `error` on failure.
+ *
+ * @typeParam T - The success payload type.
+ * @module forms-core/result
+ */
+export type Result<T> =
+  | { ok: true; data: T }
+  | {
+      ok: false;
+      error: string;
+      /**
+       * Per-field error messages, keyed by form field name, when the failure is
+       * attributable to specific input(s). Lets a form highlight the exact
+       * offending field(s) instead of only showing the summary `error`.
+       */
+      fieldErrors?: Record<string, string>;
+    };
+
+/**
+ * Builds a successful {@link Result} wrapping `data`.
+ *
+ * @typeParam T - The success payload type.
+ * @param data - The value to wrap.
+ * @returns `{ ok: true, data }`.
+ */
+export const ok = <T>(data: T): Result<T> => ({ ok: true, data });
+
+/**
+ * Builds a failed {@link Result} wrapping an error `message`.
+ *
+ * @param error - A user-safe error message (never an internal/stack detail).
+ * @param fieldErrors - Optional per-field messages so a form can highlight the
+ *   exact offending field(s). Omitted when the failure isn't field-specific.
+ * @returns `{ ok: false, error, fieldErrors? }`.
+ */
+export const err = (
+  error: string,
+  fieldErrors?: Record<string, string>,
+): Result<never> =>
+  fieldErrors ? { ok: false, error, fieldErrors } : { ok: false, error };

package/src/serverAction.spec.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ActionError,
+  createServerAction,
+  email,
+  err,
+  ok,
+  required,
+} from './index';
+
+describe('forms-core/result', () => {
+  describe('ok', () => {
+    it('returns the success shape wrapping the data', () => {
+      expect(ok(42)).toEqual({ ok: true, data: 42 });
+    });
+  });
+
+  describe('err', () => {
+    it('returns the error shape wrapping the message', () => {
+      expect(err('bad')).toEqual({ ok: false, error: 'bad' });
+    });
+
+    it('includes fieldErrors when provided', () => {
+      expect(err('bad name', { name: 'bad name' })).toEqual({
+        ok: false,
+        error: 'bad name',
+        fieldErrors: { name: 'bad name' },
+      });
+    });
+  });
+});
+
+describe('forms-core/createServerAction', () => {
+  const schema = { email: [required(), email()] };
+
+  it('returns ok and calls the handler exactly once on valid input', async () => {
+    const handler = vi.fn(async (input: { email: string }) => input.email);
+    const action = createServerAction(schema, handler);
+
+    const result = await action({ email: 'a@b.com' });
+
+    expect(result).toEqual({ ok: true, data: 'a@b.com' });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns err and never calls the handler on invalid input', async () => {
+    const handler = vi.fn(async (input: { email: string }) => input.email);
+    const action = createServerAction(schema, handler);
+
+    const result = await action({ email: '' });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(typeof result.error).toBe('string');
+      expect(result.error).toBeTruthy();
+    }
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('maps a throwing handler to a generic err with no stack trace leak', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const secret = 'INTERNAL_STACK_DETAIL';
+    const handler = vi.fn(async () => {
+      throw new Error(secret);
+    });
+    const action = createServerAction(schema, handler);
+
+    const result = await action({ email: 'a@b.com' });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(typeof result.error).toBe('string');
+      expect(result.error).toBeTruthy();
+      expect(result.error).not.toContain(secret);
+      expect(result.error).not.toContain('at ');
+    }
+    // The real cause is logged server-side for diagnosis, never returned.
+    expect(errorSpy).toHaveBeenCalled();
+    errorSpy.mockRestore();
+  });
+
+  it('passes through the message of a thrown ActionError verbatim', async () => {
+    const handler = vi.fn(async () => {
+      throw new ActionError('A product with this name already exists.');
+    });
+    const action = createServerAction(schema, handler);
+
+    const result = await action({ email: 'a@b.com' });
+
+    expect(result).toEqual({
+      ok: false,
+      error: 'A product with this name already exists.',
+    });
+  });
+
+  it('attributes a validation failure to the offending field', async () => {
+    const handler = vi.fn(async (input: { email: string }) => input.email);
+    const action = createServerAction(schema, handler);
+
+    const result = await action({ email: '' });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.fieldErrors).toEqual({ email: result.error });
+    }
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('surfaces an ActionError field as fieldErrors so the form can highlight it', async () => {
+    const handler = vi.fn(async () => {
+      throw new ActionError('Já existe um produto com esse nome.', 'name');
+    });
+    const action = createServerAction(schema, handler);
+
+    const result = await action({ email: 'a@b.com' });
+
+    expect(result).toEqual({
+      ok: false,
+      error: 'Já existe um produto com esse nome.',
+      fieldErrors: { name: 'Já existe um produto com esse nome.' },
+    });
+  });
+
+  it('passes an ActionError fieldErrors map straight through (multi-field)', async () => {
+    const fieldErrors = { 'sku:ABC': 'ABC já usado', 'sku:XYZ': 'XYZ já usado' };
+    const handler = vi.fn(async () => {
+      throw new ActionError('SKUs duplicados.', undefined, fieldErrors);
+    });
+    const action = createServerAction(schema, handler);
+
+    const result = await action({ email: 'a@b.com' });
+
+    expect(result).toEqual({ ok: false, error: 'SKUs duplicados.', fieldErrors });
+  });
+});

package/src/serverAction.ts

@@ -0,0 +1,90 @@
+import { err, ok, type Result } from './result';
+import { validateFields, type ValidatorSchema } from './validators';
+
+/** Generic, user-safe message returned when a handler throws. */
+const GENERIC_ERROR = 'Something went wrong. Please try again.';
+
+/**
+ * An error whose `message` is safe to show to the end user.
+ *
+ * Handlers throw this to surface a *specific, actionable* failure (e.g. "a
+ * product with this name already exists") through {@link createServerAction}
+ * instead of collapsing into the {@link GENERIC_ERROR}. Any error that is NOT
+ * an `ActionError` is treated as unexpected: it is logged server-side and the
+ * caller receives the generic message so internal details never leak.
+ */
+export class ActionError extends Error {
+  /**
+   * The form field this failure is attributable to (e.g. `"name"` for a
+   * duplicate-name conflict). When set, {@link createServerAction} surfaces it
+   * as `fieldErrors` so the form can highlight that exact field.
+   */
+  readonly field?: string;
+
+  /**
+   * Per-field messages when a single failure attributes to MORE than one field
+   * (e.g. several duplicate SKUs across a product's variation rows). Takes
+   * precedence over {@link field}; when set, {@link createServerAction} passes
+   * this map straight through as `fieldErrors`.
+   */
+  readonly fieldErrors?: Record<string, string>;
+
+  constructor(message: string, field?: string, fieldErrors?: Record<string, string>) {
+    super(message);
+    this.name = 'ActionError';
+    this.field = field;
+    this.fieldErrors = fieldErrors;
+  }
+}
+
+/**
+ * Wraps a handler-agnostic server action with validate-first semantics.
+ *
+ * The returned action:
+ * 1. Runs {@link validateFields} against `input` using `schema`. On the first
+ *    field error it returns `err(message)` **without invoking `handler`**.
+ * 2. Otherwise invokes `handler(input)` and returns `ok` with its resolved
+ *    value.
+ * 3. Passes through the message of an {@link ActionError} thrown by `handler`
+ *    (a deliberate, user-safe failure), and maps any *other* exception to a
+ *    generic `err` message — logging the real cause server-side so production
+ *    failures stay diagnosable without leaking internals to the client.
+ *
+ * @typeParam I - The validated input shape (string fields keyed by name).
+ * @typeParam O - The handler's success payload type.
+ * @param schema - Per-field validators applied before the handler runs.
+ * @param handler - The business logic, run only when input is valid.
+ * @returns An async action that resolves to a {@link Result}.
+ */
+export const createServerAction = <I extends Record<string, string>, O>(
+  schema: ValidatorSchema<I>,
+  handler: (input: I) => Promise<O> | O,
+): ((input: I) => Promise<Result<O>>) => {
+  return async (input: I): Promise<Result<O>> => {
+    const errors = validateFields(input, schema);
+    // Surface the first failing field by name so the form highlights it.
+    const firstField = (Object.keys(errors) as (keyof I)[]).find(
+      (field) => typeof errors[field] === 'string',
+    );
+    if (firstField !== undefined) {
+      const message = errors[firstField] as string;
+      return err(message, { [String(firstField)]: message });
+    }
+
+    try {
+      return ok(await handler(input));
+    } catch (error) {
+      if (error instanceof ActionError) {
+        // A multi-field map (fieldErrors) wins over the single-field shorthand so
+        // one failure can highlight several inputs (e.g. duplicate variation SKUs).
+        const fieldErrors =
+          error.fieldErrors ?? (error.field ? { [error.field]: error.message } : undefined);
+        return err(error.message, fieldErrors);
+      }
+      // Unexpected: log the real cause server-side (never sent to the client)
+      // so prod failures are diagnosable, and return a safe generic message.
+      console.error('[serverAction] handler threw an unexpected error:', error);
+      return err(GENERIC_ERROR);
+    }
+  };
+};

package/src/validators.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import { email, min, minLength, required, validateFields } from './validators';
+
+describe('forms-core/validators', () => {
+  describe('required', () => {
+    it('returns an error message for an empty string', () => {
+      const result = required()('');
+      expect(typeof result).toBe('string');
+      expect(result).toBeTruthy();
+    });
+
+    it('returns undefined for a non-empty value', () => {
+      expect(required()('hello')).toBeUndefined();
+    });
+
+    it('supports a custom message', () => {
+      expect(required('Campo obrigatório')('')).toBe('Campo obrigatório');
+    });
+  });
+
+  describe('email', () => {
+    it('returns an error message for a malformed address', () => {
+      const result = email()('not-an-email');
+      expect(typeof result).toBe('string');
+      expect(result).toBeTruthy();
+    });
+
+    it('returns undefined for a valid address', () => {
+      expect(email()('a@b.com')).toBeUndefined();
+    });
+
+    it('supports a custom message', () => {
+      expect(email('E-mail inválido')('bad')).toBe('E-mail inválido');
+    });
+  });
+
+  describe('minLength / min', () => {
+    it('returns an error message when the value is shorter than the minimum', () => {
+      const result = minLength(3)('ab');
+      expect(typeof result).toBe('string');
+      expect(result).toBeTruthy();
+    });
+
+    it('returns undefined when the value meets the minimum length', () => {
+      expect(minLength(3)('abc')).toBeUndefined();
+    });
+
+    it('exposes min as an alias of minLength', () => {
+      expect(min).toBe(minLength);
+      expect(min(3)('ab')).toBeTruthy();
+      expect(min(3)('abc')).toBeUndefined();
+    });
+
+    it('supports a custom message', () => {
+      expect(minLength(3, 'Muito curto')('ab')).toBe('Muito curto');
+    });
+  });
+
+  describe('validateFields', () => {
+    it('returns an entry per failing field using the first failing validator', () => {
+      const requiredMsg = required()('') as string;
+      const errors = validateFields(
+        { email: '' },
+        { email: [required(), email()] },
+      );
+      expect(errors).toEqual({ email: requiredMsg });
+    });
+
+    it('returns an empty object when all fields are valid', () => {
+      const errors = validateFields(
+        { email: 'a@b.com' },
+        { email: [required(), email()] },
+      );
+      expect(errors).toEqual({});
+    });
+  });
+});

package/src/validators.ts

@@ -0,0 +1,103 @@
+/**
+ * Field-level form validators
+ *
+ * Pure, framework-agnostic validators — NO zod, NO react-hook-form. Each
+ * validator is curried and returns a `string` error message for invalid input
+ * or `undefined` when the value is valid.
+ *
+ * @module forms-core/validators
+ */
+
+/** A field validator: returns an error message, or `undefined` when valid. */
+export type Validator = (value: string) => string | undefined;
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Requires a non-empty value (after trimming whitespace).
+ *
+ * @param message - Custom error message for empty input.
+ * @returns A validator returning the message for empty input, else `undefined`.
+ */
+export const required =
+  (message = 'This field is required'): Validator =>
+  (value) =>
+    value.trim().length === 0 ? message : undefined;
+
+/**
+ * Validates that the value is a well-formed email address.
+ *
+ * @param message - Custom error message for malformed input.
+ * @returns A validator returning the message for invalid input, else `undefined`.
+ */
+export const email =
+  (message = 'Enter a valid email address'): Validator =>
+  (value) =>
+    EMAIL_PATTERN.test(value) ? undefined : message;
+
+/**
+ * Validates that the value has at least `length` characters.
+ *
+ * @param length - The minimum number of characters required.
+ * @param message - Custom error message for too-short input.
+ * @returns A validator returning the message for short input, else `undefined`.
+ */
+export const minLength =
+  (length: number, message = `Must be at least ${length} characters`): Validator =>
+  (value) =>
+    value.length < length ? message : undefined;
+
+/** Alias of {@link minLength}. */
+export const min = minLength;
+
+/** A map of field names to the list of validators applied to that field. */
+export type ValidatorSchema<T> = {
+  [K in keyof T]?: Validator[];
+};
+
+/** A map of field names to the first error message produced for that field. */
+export type FieldErrors<T> = {
+  [K in keyof T]?: string;
+};
+
+/**
+ * The first error message a field's validators produce, or `undefined` when
+ * every validator passes. Short-circuits on the first failure.
+ */
+const firstFieldError = (validators: Validator[], value: string): string | undefined => {
+  for (const validate of validators) {
+    const error = validate(value);
+    if (error !== undefined) {
+      return error;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Runs each field's validators against `values`, short-circuiting on the first
+ * failing validator per field.
+ *
+ * @param values - The field values to validate (keyed by field name).
+ * @param schema - Validators to apply per field.
+ * @returns A record containing one entry per failing field; `{}` when all valid.
+ */
+export const validateFields = <T extends Record<string, string>>(
+  values: T,
+  schema: ValidatorSchema<T>,
+): FieldErrors<T> => {
+  const errors: FieldErrors<T> = {};
+
+  for (const field of Object.keys(schema) as (keyof T)[]) {
+    const validators = schema[field];
+    if (!validators) {
+      continue;
+    }
+    const error = firstFieldError(validators, values[field] ?? '');
+    if (error !== undefined) {
+      errors[field] = error;
+    }
+  }
+
+  return errors;
+};