cogsbox-state 0.5.486 → 0.5.488

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-state",
-  "version": "0.5.486",
+  "version": "0.5.488",
   "description": "React state management library with form controls and server sync",
   "type": "module",
   "main": "./dist/index.js",

package/src/CogsState.tsx

@@ -58,11 +58,26 @@ import { ZodType } from 'zod/v4';
 
 export type Prettify<T> = T extends any ? { [K in keyof T]: T[K] } : never;
 
-export type SyncInfo = {
-  timeStamp: number;
-  userId: number;
-};
-
+export type SyncInfo = {
+  timeStamp: number;
+  userId: number;
+};
+
+export type ValidationFieldSummary = {
+  status: ValidationStatus;
+  severity: ValidationSeverity;
+  hasErrors: boolean;
+  hasWarnings: boolean;
+  message: string;
+  errors: string[];
+  warnings: string[];
+  allErrors: Array<ValidationError & { path: string[] }>;
+  path: string[];
+  getData: () => unknown;
+};
+
+type ValidationSummaryArray = ValidationFieldSummary[];
+
 export type FormElementParams<T> = StateObject<T> & {
   $inputProps: {
     ref?: RefObject<any>;
@@ -193,8 +208,14 @@ export type EndType<
   $$derive: <R>(fn: EffectFunction<T, R>) => R;
   $_status: 'fresh' | 'dirty' | 'synced' | 'restored' | 'unknown';
   $getStatus: () => 'fresh' | 'dirty' | 'synced' | 'restored' | 'unknown';
-  $showValidationErrors: () => string[];
-  $setValidation: (ctx: string) => void;
+  $showValidationErrors: () => string[];
+  $validationErrors: {
+    (): ValidationSummaryArray;
+    <K extends Extract<keyof NonNullable<T>, string>>(
+      keys: readonly K[]
+    ): ValidationSummaryArray;
+  };
+  $setValidation: (ctx: string) => void;
   $removeValidation: (ctx: string) => void;
   $isSelected: boolean;
   $setSelected: (value: boolean) => void;
@@ -362,7 +383,21 @@ export type StateObject<
     : {}) & // Fallback to {} since we intersect EndType below anyway
   EndType<T, TPlugins> & {
     $toggle: NonNullable<T> extends boolean ? () => void : never;
-    $validate: () => { success: boolean; data?: T; error?: any };
+    $validate: {
+      (): { success: boolean; data?: T; error?: any };
+      <K extends Extract<keyof NonNullable<T>, string>>(
+        keys: readonly K[]
+      ): {
+        success: boolean;
+        results: Array<{
+          key: K;
+          path: string[];
+          success: boolean;
+          data?: unknown;
+          error?: any;
+        }>;
+      };
+    };
     $_componentId: string | null;
     $getComponents: () => ComponentsType;
     $_initialState: T;
@@ -2558,14 +2593,75 @@ function createProxyHandler<
             setShadowMetadata(stateKey, path, { ...currentMeta, isRaw: true });
             effectiveSetState(value, path, { updateType: 'update' });
           };
-        }
-
-        if (prop === '$validate') {
-          return () => {
-            const store = getGlobalStore.getState();
-
-            // 1. Get Data & Schema
-            const { value } = getScopedData(stateKey, path, meta);
+        }
+
+        if (prop === '$validate') {
+          return (keys?: readonly string[]) => {
+            const store = getGlobalStore.getState();
+
+            if (keys) {
+              const results = keys.map((key) => {
+                const targetPath = [...path, key];
+                const targetValue = store.getShadowValue(stateKey, targetPath);
+                const currentMeta =
+                  store.getShadowMetadata(stateKey, targetPath) || {};
+                const fieldSchema = currentMeta.typeInfo?.schema;
+
+                if (!fieldSchema) {
+                  return {
+                    key,
+                    path: targetPath,
+                    success: true,
+                    data: targetValue,
+                  };
+                }
+
+                const result = (fieldSchema as any).safeParse(targetValue);
+                const zodErrors =
+                  result.error?.issues || result.error?.errors || [];
+
+                store.setShadowMetadata(stateKey, targetPath, {
+                  ...currentMeta,
+                  validation: {
+                    status: result.success ? 'VALID' : 'INVALID',
+                    errors: result.success
+                      ? []
+                      : [
+                          {
+                            source: 'client',
+                            message:
+                              zodErrors[0]?.message || 'Invalid value',
+                            severity: 'error',
+                            code: zodErrors[0]?.code,
+                          },
+                        ],
+                    lastValidated: Date.now(),
+                    validatedValue: targetValue,
+                  },
+                });
+                store.notifyPathSubscribers([stateKey, ...targetPath].join('.'), {
+                  type: 'VALIDATION_UPDATE',
+                });
+
+                return {
+                  key,
+                  path: targetPath,
+                  success: result.success,
+                  data: result.success ? result.data : undefined,
+                  error: result.success ? undefined : result.error,
+                };
+              });
+
+              notifyComponents(stateKey);
+
+              return {
+                success: results.every((result) => result.success),
+                results,
+              };
+            }
+
+            // 1. Get Data & Schema
+            const { value } = getScopedData(stateKey, path, meta);
             const opts = store.getInitialOptions(stateKey);
             const schema =
               opts?.validation?.zodSchemaV4 || opts?.validation?.zodSchemaV3;
@@ -2623,11 +2719,11 @@ function createProxyHandler<
             return result;
           };
         }
-        if (prop === '$showValidationErrors') {
-          return () => {
-            const { shadowMeta } = getScopedData(stateKey, path, meta);
-            if (
-              shadowMeta?.validation?.status === 'INVALID' &&
+        if (prop === '$showValidationErrors') {
+          return () => {
+            const { shadowMeta } = getScopedData(stateKey, path, meta);
+            if (
+              shadowMeta?.validation?.status === 'INVALID' &&
               shadowMeta.validation.errors.length > 0
             ) {
               // Return only error-severity messages (not warnings)
@@ -2635,11 +2731,55 @@ function createProxyHandler<
                 .filter((err) => err.severity === 'error')
                 .map((err) => err.message);
             }
-            return [];
-          };
-        }
-
-        if (prop === '$getSelected') {
+            return [];
+          };
+        }
+        if (prop === '$validationErrors') {
+          return (keys?: readonly string[]) => {
+            const store = getGlobalStore.getState();
+            const summarizePath = (targetPath: string[]) => {
+              const validationState =
+                store.getShadowMetadata(stateKey, targetPath)?.validation;
+              const allErrors = (validationState?.errors || []).map((err) => ({
+                ...err,
+                path: targetPath,
+              }));
+              const errors = allErrors.filter((err) => err.severity === 'error');
+              const warnings = allErrors.filter(
+                (err) => err.severity === 'warning'
+              );
+              const severity: ValidationSeverity =
+                errors.length > 0
+                  ? 'error'
+                  : warnings.length > 0
+                    ? 'warning'
+                    : undefined;
+
+              return {
+                status: validationState?.status || 'NOT_VALIDATED',
+                severity,
+                hasErrors: errors.length > 0,
+                hasWarnings: warnings.length > 0,
+                message: errors[0]?.message || warnings[0]?.message || '',
+                errors: errors.map((err) => err.message),
+                warnings: warnings.map((err) => err.message),
+                allErrors,
+                path: targetPath,
+                getData: () => store.getShadowValue(stateKey, targetPath),
+              } satisfies ValidationFieldSummary;
+            };
+
+            const childKeys =
+              keys ??
+              Object.keys(store.getShadowNode(stateKey, path) ?? {}).filter(
+                (key) => key !== '_meta'
+              );
+
+            return childKeys.map((key) => summarizePath([...path, key]));
+          };
+        }
+
+        if (prop === '$getSelected') {
           return () => {
             const arrayKey = [stateKey, ...path].join('.');
             registerComponentDependency(stateKey, componentId, [