cogsbox-state 0.5.486 → 0.5.487

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-state",
-  "version": "0.5.486",
+  "version": "0.5.487",
   "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;
@@ -2623,11 +2644,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 +2656,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, [