cogsbox-state 0.5.476 → 0.5.478

package/src/plugins.ts

@@ -1,14 +1,71 @@
 import { z } from 'zod';
 import type React from 'react';
 import { StateObject, UpdateTypeDetail } from './CogsState';
-import { getGlobalStore } from './store';
+import {
+  getGlobalStore,
+  getAllFieldElements,
+  setAllFieldsDisabled,
+} from './store';
 import { ClientActivityEvent } from './pluginStore';
+import { RefObject } from 'react';
 
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 
+export type ChainMethodTarget =
+  | 'any'
+  | 'array'
+  | 'object'
+  | 'primitive'
+  | 'boolean';
+
+export type ChainMethodContext<TOptions = any, THookReturn = any> = {
+  stateKey: string;
+  path: string[];
+  pluginName: string;
+  options: TOptions | undefined;
+  hookData?: THookReturn;
+  $get: () => any;
+  $update: (payload: any) => { synced: () => void };
+  $applyOperation: (operation: any, metaData?: Record<string, any>) => void;
+  getFieldMetaData: () => any;
+  setFieldMetaData: (data: Record<string, any>) => void;
+  removeFieldMetaData: () => void;
+  getFieldRefs: () => RefObject<any>[];
+  getFieldElements: () => HTMLElement[];
+  setFieldDisabled: (disabled: boolean) => void;
+};
+
+export type ChainMethodHandler = (
+  ctx: ChainMethodContext<any, any>,
+  ...args: any[]
+) => any;
+
+export type ChainMethodDefinition<
+  THandler extends ChainMethodHandler = ChainMethodHandler,
+> = {
+  target: ChainMethodTarget;
+  pathPattern?: string[];
+  handler: THandler;
+};
+
+export type ChainMethodDefinitions = Record<string, ChainMethodDefinition<any>>;
+
+type ChainMethodCallable<THandler> = THandler extends (
+  ctx: any,
+  ...args: infer TArgs
+) => infer TReturn
+  ? (...args: TArgs) => TReturn
+  : never;
+
+export type ChainMethodCallables<TMethods> = {
+  [K in keyof TMethods]: TMethods[K] extends ChainMethodDefinition<infer TFn>
+    ? ChainMethodCallable<TFn>
+    : never;
+};
+
 export type KeyedTypes<TMap extends Record<string, any>> = {
   __key: 'keyed';
-  map: { [K in keyof TMap]: TMap[K] };
+  map: TMap;
 };
 
 export const keyedSchema = <TMap extends Record<string, any>>() =>
@@ -58,6 +115,9 @@ type ScopedMetadataMethods<TFieldMetaData> = {
   getFieldMetaData: () => TFieldMetaData | undefined;
   setFieldMetaData: (data: Partial<TFieldMetaData>) => void;
   removeFieldMetaData: () => void;
+  getFieldRefs: () => RefObject<any>[];
+  getFieldElements: () => HTMLElement[];
+  setFieldDisabled: (disabled: boolean) => void;
 };
 
 // These are the existing global methods that still require a path.
@@ -65,6 +125,11 @@ type GlobalMetadataMethods<TFieldMetaData> = {
   getFieldMetaData: (path: string[]) => TFieldMetaData | undefined;
   setFieldMetaData: (path: string[], data: Partial<TFieldMetaData>) => void;
   removeFieldMetaData: (path: string[]) => void;
+  getFieldRefs: (path: string[]) => RefObject<any>[];
+  getFieldElements: (path: string[]) => HTMLElement[];
+  setFieldDisabled: (path: string[], disabled: boolean) => void;
+  getAllFieldElements: () => HTMLElement[];
+  setAllFieldsDisabled: (disabled: boolean) => void;
 };
 // Simplified: All params use the same TFieldMetaData type
 export type UseHookParams<
@@ -193,9 +258,12 @@ export type CogsPlugin<
   THookReturn,
   TPluginMetaData,
   TFieldMetaData,
+  TChainMethods extends ChainMethodDefinitions = {},
 > = {
   name: TName;
 
+  initialState?: () => Record<string, unknown>;
+
   useHook?: (
     params: UseHookParams<TOptions, TPluginMetaData, TFieldMetaData, any>
   ) => THookReturn;
@@ -239,6 +307,8 @@ export type CogsPlugin<
       any
     >
   ) => React.ReactNode;
+
+  chainMethods?: TChainMethods;
 };
 
 // Metadata helpers
@@ -276,6 +346,45 @@ export function createMetadataContext<TPluginMetaData, TFieldMetaData>(
       getGlobalStore
         .getState()
         .removePluginMetaData(stateKey, path, pluginName),
+    getFieldRefs: (path: string[]): RefObject<any>[] => {
+      const meta = getGlobalStore.getState().getShadowMetadata(stateKey, path);
+      if (!meta?.clientActivityState?.elements) return [];
+      const refs: RefObject<any>[] = [];
+      meta.clientActivityState.elements.forEach((entry: any) => {
+        if (entry.domRef?.current) refs.push(entry.domRef);
+      });
+      return refs;
+    },
+
+    getFieldElements: (path: string[]): HTMLElement[] => {
+      const meta = getGlobalStore.getState().getShadowMetadata(stateKey, path);
+      if (!meta?.clientActivityState?.elements) return [];
+      const elements: HTMLElement[] = [];
+      meta.clientActivityState.elements.forEach((entry: any) => {
+        if (entry.domRef?.current) elements.push(entry.domRef.current);
+      });
+      return elements;
+    },
+
+    setFieldDisabled: (path: string[], disabled: boolean) => {
+      const meta = getGlobalStore.getState().getShadowMetadata(stateKey, path);
+      if (!meta?.clientActivityState?.elements) return;
+      meta.clientActivityState.elements.forEach((entry: any) => {
+        const el = entry.domRef?.current;
+        if (!el) return;
+        if ('disabled' in el) el.disabled = disabled;
+        else {
+          el.style.pointerEvents = disabled ? 'none' : '';
+          el.setAttribute('aria-disabled', String(disabled));
+        }
+      });
+    },
+    getAllFieldElements: (): HTMLElement[] => {
+      return getAllFieldElements(stateKey);
+    },
+
+    setAllFieldsDisabled: (disabled: boolean): void =>
+      setAllFieldsDisabled(stateKey, disabled),
   };
 }
 
@@ -290,19 +399,54 @@ export function createScopedMetadataContext<TPluginMetaData, TFieldMetaData>(
   );
 
   return {
-    // Return the global methods for plugin metadata
     ...globalContext,
-    // Override the field methods with new, path-scoped versions
     getFieldMetaData: (): TFieldMetaData | undefined =>
       globalContext.getFieldMetaData(path),
-
     setFieldMetaData: (data: Partial<TFieldMetaData>) =>
       globalContext.setFieldMetaData(path, data),
-
     removeFieldMetaData: () => globalContext.removeFieldMetaData(path),
+
+    // NEW: Direct access to the DOM refs for this field
+    getFieldRefs: (): RefObject<any>[] => {
+      const meta = getGlobalStore.getState().getShadowMetadata(stateKey, path);
+      if (!meta?.clientActivityState?.elements) return [];
+      const refs: RefObject<any>[] = [];
+      meta.clientActivityState.elements.forEach((entry: any) => {
+        if (entry.domRef?.current) {
+          refs.push(entry.domRef);
+        }
+      });
+      return refs;
+    },
+
+    getFieldElements: (): HTMLElement[] => {
+      const meta = getGlobalStore.getState().getShadowMetadata(stateKey, path);
+      if (!meta?.clientActivityState?.elements) return [];
+      const elements: HTMLElement[] = [];
+      meta.clientActivityState.elements.forEach((entry: any) => {
+        if (entry.domRef?.current) {
+          elements.push(entry.domRef.current);
+        }
+      });
+      return elements;
+    },
+
+    setFieldDisabled: (disabled: boolean) => {
+      const meta = getGlobalStore.getState().getShadowMetadata(stateKey, path);
+      if (!meta?.clientActivityState?.elements) return;
+      meta.clientActivityState.elements.forEach((entry: any) => {
+        const el = entry.domRef?.current;
+        if (!el) return;
+        if ('disabled' in el) {
+          el.disabled = disabled;
+        } else {
+          el.style.pointerEvents = disabled ? 'none' : '';
+          el.setAttribute('aria-disabled', String(disabled));
+        }
+      });
+    },
   };
 }
-
 // Add this type export - derives from what createScopedMetadataContext returns
 export type ScopedMetadataContext<TFieldMetaData = any> = {
   getFieldMetaData: () => TFieldMetaData | undefined;
@@ -323,13 +467,88 @@ type ZodObjOutput<T extends z.ZodObject<any>> = {
 type OutputOf<T extends z.ZodTypeAny> =
   T extends z.ZodObject<any> ? Prettify<ZodObjOutput<T>> : z.output<T>;
 
+type MethodFactory = <THandler extends ChainMethodHandler>(
+  handler: THandler
+) => ChainMethodDefinition<THandler>;
+
+type PathMethodFactory = MethodFactory & {
+  array: MethodFactory;
+  object: MethodFactory;
+  primitive: MethodFactory;
+  boolean: MethodFactory;
+  field: MethodFactory;
+};
+
+type MethodsBuilderParams = {
+  path: (selector: (state: any) => any) => PathMethodFactory;
+  array: MethodFactory;
+  object: MethodFactory;
+  primitive: MethodFactory;
+  boolean: MethodFactory;
+  field: MethodFactory;
+};
+
+const createMethodDefinition =
+  (target: ChainMethodTarget, pathPattern?: string[]): MethodFactory =>
+  (handler) => ({
+    target,
+    pathPattern,
+    handler,
+  });
+
+const createPathRecorder = () => {
+  const path: string[] = [];
+
+  const recorder = new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop !== 'string') return recorder;
+        if (prop === 'then') return undefined;
+        path.push(prop === '$' ? '*' : prop);
+        return recorder;
+      },
+    }
+  );
+
+  return { recorder, path };
+};
+
+const createMethodsBuilderParams = (): MethodsBuilderParams => {
+  const path = (selector: (state: any) => any): PathMethodFactory => {
+    const { recorder, path: pathPattern } = createPathRecorder();
+    selector(recorder);
+
+    const base = createMethodDefinition(
+      'any',
+      pathPattern
+    ) as PathMethodFactory;
+    base.array = createMethodDefinition('array', pathPattern);
+    base.object = createMethodDefinition('object', pathPattern);
+    base.primitive = createMethodDefinition('primitive', pathPattern);
+    base.boolean = createMethodDefinition('boolean', pathPattern);
+    base.field = createMethodDefinition('any', pathPattern);
+
+    return base;
+  };
+
+  return {
+    path,
+    array: createMethodDefinition('array'),
+    object: createMethodDefinition('object'),
+    primitive: createMethodDefinition('primitive'),
+    boolean: createMethodDefinition('boolean'),
+    field: createMethodDefinition('any'),
+  };
+};
+
 export function createPluginContext<
-  O extends z.ZodTypeAny,
+  O extends z.ZodTypeAny | undefined = undefined,
   PM extends z.ZodTypeAny | undefined = undefined,
   FM extends z.ZodTypeAny | undefined = undefined,
->(schemas: { options: O; pluginMetaData?: PM; fieldMetaData?: FM }) {
+>(schemas?: { options?: O; pluginMetaData?: PM; fieldMetaData?: FM }) {
   // Crucial: compute from the generic params, not from an object-indexed optional type
-  type Options = OutputOf<O>;
+  type Options = O extends z.ZodTypeAny ? OutputOf<O> : undefined;
   type PluginMetaData = PM extends z.ZodTypeAny ? OutputOf<PM> : unknown;
   type FieldMetaData = FM extends z.ZodTypeAny ? OutputOf<FM> : unknown;
 
@@ -361,34 +580,51 @@ export function createPluginContext<
       >
     ) => void;
 
-    type Plugin<THookReturn> = Prettify<
-      CogsPlugin<TName, Options, THookReturn, PluginMetaData, FieldMetaData>
+    type Plugin<
+      THookReturn,
+      TChainMethods extends ChainMethodDefinitions = {},
+    > = Prettify<
+      CogsPlugin<
+        TName,
+        Options,
+        THookReturn,
+        PluginMetaData,
+        FieldMetaData,
+        TChainMethods
+      >
     >;
 
-    const createPluginObject = <THookReturn = never>(
+    const createPluginObject = <
+      THookReturn = never,
+      TChainMethods extends ChainMethodDefinitions = {},
+    >(
       hookFn?: (
         params: UseHookParams<Options, PluginMetaData, FieldMetaData>
       ) => THookReturn,
       transformFn?: TransformFn<THookReturn>,
       updateHandler?: UpdateFn<THookReturn>,
-      formUpdateHandler?: FormUpdateFn<THookReturn>
-    ): Plugin<THookReturn> => {
+      formUpdateHandler?: FormUpdateFn<THookReturn>,
+      chainMethods?: TChainMethods
+    ): Plugin<THookReturn, TChainMethods> => {
       return {
         name,
         useHook: hookFn as any,
         transformState: transformFn as any,
         onUpdate: updateHandler as any,
         onFormUpdate: formUpdateHandler as any,
+        chainMethods,
       };
     };
 
     type BuildRet<
       THookReturn,
+      TChainMethods extends ChainMethodDefinitions,
       HasTransform extends boolean,
       HasUpdate extends boolean,
       HasFormUpdate extends boolean,
+      HasMethods extends boolean,
       HasWrapper extends boolean,
-    > = Plugin<THookReturn> &
+    > = Plugin<THookReturn, TChainMethods> &
       (HasTransform extends true
         ? {}
         : {
@@ -396,9 +632,11 @@ export function createPluginContext<
               fn: TransformFn<THookReturn>
             ): BuildRet<
               THookReturn,
+              TChainMethods,
               true,
               HasUpdate,
               HasFormUpdate,
+              HasMethods,
               HasWrapper
             >;
           }) &
@@ -409,9 +647,11 @@ export function createPluginContext<
               fn: UpdateFn<THookReturn>
             ): BuildRet<
               THookReturn,
+              TChainMethods,
               HasTransform,
               true,
               HasFormUpdate,
+              HasMethods,
               HasWrapper
             >;
           }) &
@@ -420,14 +660,39 @@ export function createPluginContext<
         : {
             onFormUpdate(
               fn: FormUpdateFn<THookReturn>
-            ): BuildRet<THookReturn, HasTransform, HasUpdate, true, HasWrapper>;
+            ): BuildRet<
+              THookReturn,
+              TChainMethods,
+              HasTransform,
+              HasUpdate,
+              true,
+              HasMethods,
+              HasWrapper
+            >;
+          }) &
+      (HasMethods extends true
+        ? {}
+        : {
+            methods<TNextMethods extends ChainMethodDefinitions>(
+              fn: (helpers: MethodsBuilderParams) => TNextMethods
+            ): BuildRet<
+              THookReturn,
+              TNextMethods,
+              HasTransform,
+              HasUpdate,
+              HasFormUpdate,
+              true,
+              HasWrapper
+            >;
           });
 
     function createBuilder<
       THookReturn = never,
+      TChainMethods extends ChainMethodDefinitions = {},
       HasTransform extends boolean = false,
       HasUpdate extends boolean = false,
       HasFormUpdate extends boolean = false,
+      HasMethods extends boolean = false,
       HasWrapper extends boolean = false,
     >(
       hookFn?: (
@@ -435,27 +700,33 @@ export function createPluginContext<
       ) => THookReturn,
       transformFn?: TransformFn<THookReturn>,
       updateHandler?: UpdateFn<THookReturn>,
-      formUpdateHandler?: FormUpdateFn<THookReturn>
+      formUpdateHandler?: FormUpdateFn<THookReturn>,
+      chainMethods?: TChainMethods
     ): BuildRet<
       THookReturn,
+      TChainMethods,
       HasTransform,
       HasUpdate,
       HasFormUpdate,
+      HasMethods,
       HasWrapper
     > {
-      const plugin = createPluginObject<THookReturn>(
+      const plugin = createPluginObject<THookReturn, TChainMethods>(
         hookFn,
         transformFn,
         updateHandler,
-        formUpdateHandler
+        formUpdateHandler,
+        chainMethods
       );
 
       const methods = {} as Partial<
         BuildRet<
           THookReturn,
+          TChainMethods,
           HasTransform,
           HasUpdate,
           HasFormUpdate,
+          HasMethods,
           HasWrapper
         >
       >;
@@ -464,58 +735,97 @@ export function createPluginContext<
         (methods as any).transformState = (fn: TransformFn<THookReturn>) =>
           createBuilder<
             THookReturn,
+            TChainMethods,
             true,
             HasUpdate,
             HasFormUpdate,
+            HasMethods,
             HasWrapper
-          >(hookFn, fn, updateHandler, formUpdateHandler);
+          >(hookFn, fn, updateHandler, formUpdateHandler, chainMethods);
       }
       if (!updateHandler) {
         (methods as any).onUpdate = (fn: UpdateFn<THookReturn>) =>
           createBuilder<
             THookReturn,
+            TChainMethods,
             HasTransform,
             true,
             HasFormUpdate,
+            HasMethods,
             HasWrapper
-          >(hookFn, transformFn, fn, formUpdateHandler);
+          >(hookFn, transformFn, fn, formUpdateHandler, chainMethods);
       }
       if (!formUpdateHandler) {
         (methods as any).onFormUpdate = (fn: FormUpdateFn<THookReturn>) =>
-          createBuilder<THookReturn, HasTransform, HasUpdate, true, HasWrapper>(
+          createBuilder<
+            THookReturn,
+            TChainMethods,
+            HasTransform,
+            HasUpdate,
+            true,
+            HasMethods,
+            HasWrapper
+          >(hookFn, transformFn, updateHandler, fn, chainMethods);
+      }
+      if (!chainMethods) {
+        (methods as any).methods = <
+          TNextMethods extends ChainMethodDefinitions,
+        >(
+          fn: (helpers: MethodsBuilderParams) => TNextMethods
+        ) =>
+          createBuilder<
+            THookReturn,
+            TNextMethods,
+            HasTransform,
+            HasUpdate,
+            HasFormUpdate,
+            true,
+            HasWrapper
+          >(
             hookFn,
             transformFn,
             updateHandler,
-            fn
+            formUpdateHandler,
+            fn(createMethodsBuilderParams())
           );
       }
 
       return Object.assign(plugin, methods) as BuildRet<
         THookReturn,
+        TChainMethods,
         HasTransform,
         HasUpdate,
         HasFormUpdate,
+        HasMethods,
         HasWrapper
       >;
     }
 
     const start = Object.assign(
-      createBuilder<never, false, false, false, false>(),
+      createBuilder<never, {}, false, false, false, false, false>(),
       {
         useHook<THookReturn>(
           hookFn: (
             params: UseHookParams<Options, PluginMetaData, FieldMetaData>
           ) => THookReturn
         ) {
-          return createBuilder<THookReturn, false, false, false, false>(hookFn);
+          return createBuilder<
+            THookReturn,
+            {},
+            false,
+            false,
+            false,
+            false,
+            false
+          >(hookFn);
         },
       }
-    ) as BuildRet<never, false, false, false, false> & {
+    ) as BuildRet<never, {}, false, false, false, false, false> & {
       useHook<THookReturn>(
         hookFn: (
           params: UseHookParams<Options, PluginMetaData, FieldMetaData>
         ) => THookReturn
-      ): BuildRet<THookReturn, false, false, false, false>;
+      ): BuildRet<THookReturn, {}, false, false, false, false, false>;
     };
 
     return start;