magoo 0.1.0-beta.0

package/dist/src/types/forms.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mensagem ou conjunto de mensagens que um campo pode exibir.
+ *
+ * O formato é intencionalmente independente de qualquer biblioteca de
+ * validação para permitir integração por adaptadores no projeto host.
+ */
+export type MagooFieldError = string | string[];
+/**
+ * Estado de validação e interação consumido pelos componentes de campo.
+ */
+export interface MagooFieldState {
+    error?: MagooFieldError;
+    invalid?: boolean;
+    touched?: boolean;
+    dirty?: boolean;
+    validating?: boolean;
+    submitted?: boolean;
+}
+/**
+ * Estado convertido por um adaptador de validação externa.
+ *
+ * O adaptador deve mapear o estado da biblioteca escolhida pelo host para este
+ * contrato antes de repassá-lo aos componentes Magoo.
+ */
+export interface MagooFieldAdapterState {
+    value?: unknown;
+    error?: MagooFieldError;
+    invalid?: boolean;
+    touched?: boolean;
+    dirty?: boolean;
+    validating?: boolean;
+}

package/dist/src/types/index.d.ts

@@ -0,0 +1 @@
+export type { MagooFieldAdapterState, MagooFieldError, MagooFieldState } from './forms';

package/dist/src/validation/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export { compactErrors, defaultRuleResultAdapter, focusFirstInvalidField, hasErrors, mergeErrors } from './utils';
+export { useFormValidation } from './useFormValidation';
+export type { MagooFieldBinding, MagooFormController, MagooFormValidation, UseFormValidationOptions } from './useFormValidation';

package/dist/src/validation/types.d.ts

@@ -0,0 +1,40 @@
+import { MagooFieldError } from '../types';
+/** Chave reservada para erros que pertencem ao formulário como um todo. */
+export declare const MAGOO_FORM_ERROR_KEY = "$form";
+export type MagooValidationTrigger = 'input' | 'blur' | 'submit';
+/**
+ * Resultado bruto de uma regra. Valores falsy ou `true` significam "válido";
+ * strings representam mensagens de erro.
+ */
+export type MagooRuleResult = MagooFieldError | boolean | null | undefined | void;
+export interface MagooRuleContext<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    field: keyof TValues & string;
+    values: TValues;
+}
+export type MagooValidationRule<TValue = unknown, TValues extends Record<string, unknown> = Record<string, unknown>> = (value: TValue, context: MagooRuleContext<TValues>) => MagooRuleResult | Promise<MagooRuleResult>;
+/**
+ * Regra de formulário: pode devolver mensagens por campo e/ou mensagens
+ * globais sob `MAGOO_FORM_ERROR_KEY`.
+ */
+export type MagooFormRule<TValues extends Record<string, unknown> = Record<string, unknown>> = (values: TValues) => Record<string, MagooRuleResult> | MagooRuleResult | Promise<Record<string, MagooRuleResult> | MagooRuleResult>;
+export interface MagooFieldSchema<TValue = unknown, TValues extends Record<string, unknown> = Record<string, unknown>> {
+    rules?: MagooValidationRule<TValue, TValues>[];
+    /** Campos cuja alteração deve revalidar este campo (ex.: confirmação de senha). */
+    dependsOn?: (keyof TValues & string)[];
+    /** Sobrescreve os gatilhos globais para este campo. */
+    validateOn?: MagooValidationTrigger[];
+    /** Interrompe na primeira regra que falhar. */
+    bail?: boolean;
+}
+export type MagooValidationSchema<TValues extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof TValues & string]?: MagooFieldSchema<TValues[K], TValues> | MagooValidationRule<TValues[K], TValues>[];
+};
+/** Converte a saída de uma regra para uma lista de mensagens. */
+export type MagooRuleResultAdapter = (result: unknown) => string[];
+export type MagooErrorMap = Record<string, string[]>;
+export interface MagooFieldRuntimeState {
+    touched: boolean;
+    dirty: boolean;
+    validating: boolean;
+    validated: boolean;
+}

package/dist/src/validation/useFormValidation.d.ts

@@ -0,0 +1,56 @@
+import { ComputedRef, Ref } from 'vue';
+import { MagooFieldError, MagooFieldState } from '../types';
+import { MagooErrorMap, MagooFormRule, MagooRuleResultAdapter, MagooValidationSchema, MagooValidationTrigger } from './types';
+export interface UseFormValidationOptions<TValues extends Record<string, unknown>> {
+    /** Objeto de valores. Objetos reativos são usados diretamente; objetos simples são envolvidos em `reactive`. */
+    values: TValues;
+    schema?: MagooValidationSchema<TValues>;
+    formRules?: MagooFormRule<TValues>[];
+    /** Gatilhos padrão para todos os campos. */
+    validateOn?: MagooValidationTrigger[];
+    /** Revalida no `input` um campo que já exibe erro, para que a correção seja refletida imediatamente. */
+    revalidateOnInput?: boolean;
+    /** Interrompe na primeira regra que falhar (pode ser sobrescrito por campo). */
+    bail?: boolean;
+    adapter?: MagooRuleResultAdapter;
+}
+export interface MagooFieldBinding<TValue = unknown> {
+    name: string;
+    modelValue: TValue;
+    'onUpdate:modelValue': (value: TValue) => void;
+    onBlur: () => void;
+    error: string[];
+    submitTriggered: boolean;
+}
+/** Contrato mínimo que o `MForm` precisa; qualquer `MagooFormValidation<T>` o satisfaz. */
+export interface MagooFormController {
+    values: Record<string, unknown>;
+    allErrors: ComputedRef<MagooErrorMap>;
+    handleSubmit: () => Promise<boolean>;
+}
+export interface MagooFormValidation<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    values: TValues;
+    errors: Readonly<Ref<MagooErrorMap>>;
+    serverErrors: Readonly<Ref<MagooErrorMap>>;
+    allErrors: ComputedRef<MagooErrorMap>;
+    visibleErrors: ComputedRef<MagooErrorMap>;
+    formErrors: ComputedRef<string[]>;
+    isValid: ComputedRef<boolean>;
+    isValidating: ComputedRef<boolean>;
+    submitted: Readonly<Ref<boolean>>;
+    submitCount: Readonly<Ref<number>>;
+    fieldState: (name: keyof TValues & string) => MagooFieldState;
+    field: <K extends keyof TValues & string>(name: K) => MagooFieldBinding<TValues[K]>;
+    setValue: <K extends keyof TValues & string>(name: K, value: TValues[K]) => void;
+    handleInput: <K extends keyof TValues & string>(name: K, value: TValues[K]) => void;
+    handleBlur: (name: keyof TValues & string) => void;
+    touch: (name: keyof TValues & string) => void;
+    validateField: (name: keyof TValues & string) => Promise<string[]>;
+    validateForm: () => Promise<boolean>;
+    handleSubmit: (onValid?: (values: TValues) => void | Promise<void>) => Promise<boolean>;
+    setFieldErrors: (name: string, messages: MagooFieldError) => void;
+    setServerErrors: (errors: Record<string, MagooFieldError>) => void;
+    clearServerErrors: (name?: string) => void;
+    reset: (nextValues?: Partial<TValues>) => void;
+}
+export declare function useFormValidation<TValues extends Record<string, unknown>>(options: UseFormValidationOptions<TValues>): MagooFormValidation<TValues>;

package/dist/src/validation/useFormValidation.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/validation/utils.d.ts

@@ -0,0 +1,17 @@
+import { MagooErrorMap, MagooRuleResultAdapter } from './types';
+/**
+ * Adaptador padrão: aceita `string`, `string[]`, `boolean`, `null`,
+ * `undefined` e objetos `{ message }` (formato comum em bibliotecas externas).
+ */
+export declare const defaultRuleResultAdapter: MagooRuleResultAdapter;
+export declare function hasErrors(errors: MagooErrorMap): boolean;
+/** Remove chaves sem mensagens e deduplica mensagens por campo. */
+export declare function compactErrors(errors: MagooErrorMap): MagooErrorMap;
+export declare function mergeErrors(...maps: MagooErrorMap[]): MagooErrorMap;
+/**
+ * Foca o primeiro controle inválido dentro do container.
+ *
+ * Prioriza `aria-invalid="true"` (estado real exposto pelos campos) e recorre
+ * ao `name` do primeiro erro quando o estado ainda não foi refletido no DOM.
+ */
+export declare function focusFirstInvalidField(container: ParentNode | null | undefined, errors?: MagooErrorMap): HTMLElement | null;

package/dist/src/validation/utils.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "magoo",
+  "private": false,
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/magoo.umd.js",
+  "module": "./dist/magoo.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/magoo.es.js",
+      "require": "./dist/magoo.umd.js",
+      "default": "./dist/magoo.es.js"
+    },
+    "./styles": "./dist/magoo.css",
+    "./theme.css": "./dist/magoo.css"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "publishConfig": {
+    "tag": "beta"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "typecheck": "vue-tsc --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run build",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "vue": "^3.5.40"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.13.3",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vue/test-utils": "^2.4.6",
+    "@vue/tsconfig": "^0.9.1",
+    "jsdom": "^26.0.1",
+    "typescript": "~6.0.2",
+    "vite": "^8.2.0",
+    "vite-plugin-dts": "^4.1.0",
+    "vitest": "^3.2.4",
+    "vue-tsc": "^3.3.8",
+    "storybook": "^10.5.7",
+    "@storybook/vue3-vite": "^10.5.7",
+    "@chromatic-com/storybook": "latest",
+    "@storybook/addon-vitest": "^10.5.7",
+    "@storybook/addon-a11y": "^10.5.7",
+    "@storybook/addon-docs": "^10.5.7",
+    "@storybook/addon-onboarding": "^10.5.7",
+    "@vitest/browser": "3.2.7",
+    "@vitest/coverage-v8": "3.2.7",
+    "playwright": "latest",
+    "eslint": "^10.9.1",
+    "eslint-plugin-vue": "^10.10.0",
+    "globals": "^17.12.0",
+    "typescript-eslint": "^8.69.0"
+  }
+}