feat(core)!: implement template loading state with pending/resolved status

packages/core/src/form/index.ts

@@ -1,6 +1,11 @@
 import { useRef } from 'react';
 import { SugarInner } from '../sugar';
-import { Sugar, SugarValue, SugarGetResult } from '../sugar/types';
+import {
+  Sugar,
+  SugarValue,
+  SugarGetResult,
+  SugarTemplateState,
+} from '../sugar/types';
 
 export interface UseFormResult<T extends SugarValue> {
   sugar: Sugar<T>;
@@ -10,7 +15,7 @@ export interface UseFormResult<T extends SugarValue> {
 export const useForm = <T extends SugarValue>({
   template,
 }: {
-  template?: T;
+  template?: SugarTemplateState<T>;
 } = {}): UseFormResult<T> => {
   const sugar = useRef<Sugar<T>>(undefined);
   if (!sugar.current) {

packages/core/src/lib.ts

@@ -2,4 +2,4 @@ export { useForm } from './form';
 export type { UseFormResult } from './form';
 export { TextInput } from './components/textInput';
 export { NumberInput } from './components/numberInput';
-export type { Sugar } from './sugar/types';
+export type { Sugar, SugarTemplateState } from './sugar/types';

packages/core/src/sugar/index.ts

@@ -7,6 +7,7 @@
   SugarSetResult,
   SugarSetter,
   SugarTemplateSetter,
+  SugarTemplateState,
   SugarValue,
   SugarValueObject,
 } from './types';
@@ -17,6 +18,7 @@
   ValidationStage,
   FailFn,
 } from './useValidation';
+import { useIsPending, SugarUseIsPending } from './useIsPending';
 
 export class SugarInner<T extends SugarValue> {
   // Sugarは、get/setができるようになるまでに、Reactのレンダリングを待つ必要があります。
@@ -63,12 +65,12 @@
         status: 'unavailable';
       };
 
-  template: T | undefined;
+  template: SugarTemplateState<T>;
   private validators: Set<
     (stage: ValidationStage, value: T) => Promise<boolean>
   > = new Set();
 
-  constructor(template?: T) {
+  constructor(template?: SugarTemplateState<T>) {
     const { promise: getPromise, resolve: resolveGetPromise } =
       Promise.withResolvers<SugarGetResult<T>>();
     const { promise: setPromise, resolve: resolveSetPromise } =
@@ -155,7 +157,7 @@
   }
 
   setTemplate(value: T, executeSet = true): Promise<SugarSetResult<T>> {
-    this.template = value;
+    this.template = { status: 'resolved', value };
 
     switch (this.status.status) {
       case 'unavailable':
@@ -181,6 +183,20 @@
     }
   }
 
+  setPendingTemplate(): void {
+    this.template = { status: 'pending' };
+    if (this.status.status === 'ready' && this.status.templateSetter) {
+      this.status.templateSetter(undefined as T, false);
+    }
+  }
+
+  private getTemplateValue(): T | undefined {
+    if (this.template?.status === 'resolved') {
+      return this.template.value;
+    }
+    return undefined;
+  }
+
   private eventTarget: EventTarget = new EventTarget();
 
   addEventListener<K extends keyof SugarEvent>(
@@ -214,7 +230,7 @@
       const status = this.status;
       status.lock = true;
 
-      const initial = status.recentValue ?? this.template;
+      const initial = status.recentValue ?? this.getTemplateValue();
       if (initial !== undefined) {
         status.resolveSetPromise(await setter(initial));
       }
@@ -273,4 +289,7 @@
     deps?: React.DependencyList
   ) =>
     useValidation(this as Sugar<T>, validator, deps)) as SugarUseValidation<T>;
+
+  useIsPending: SugarUseIsPending = (() =>
+    useIsPending(this as Sugar<T>)) as SugarUseIsPending;
 }

packages/core/src/sugar/types.ts

@@ -1,6 +1,11 @@
 export type SugarValue = unknown;
 export type SugarValueObject = SugarValue & Record<string, SugarValue>;
 
+export type SugarTemplateState<T extends SugarValue> =
+  | { status: 'pending' }
+  | { status: 'resolved'; value: T }
+  | undefined;
+
 export type SugarGetResult<T extends SugarValue> =
   | {
       result: 'success';
@@ -34,6 +39,7 @@ export type SugarTemplateSetter<T extends SugarValue> = (
 
 import type { SugarUseObject } from './useObject';
 import type { SugarUseValidation } from './useValidation';
+import type { SugarUseIsPending } from './useIsPending';
 
 type SugarType<T extends SugarValue> = {
   get: SugarGetter<T>;
@@ -47,6 +53,7 @@ type SugarType<T extends SugarValue> = {
   destroy: () => void;
   useObject: SugarUseObject<T>;
   useValidation: SugarUseValidation<T>;
+  useIsPending: SugarUseIsPending;
   addEventListener: <K extends keyof SugarEvent>(
     type: K,
     listener: CustomEventListener<SugarEvent[K]>

packages/core/src/sugar/useIsPending.ts

@@ -0,0 +1,48 @@
+import { useEffect, useState } from 'react';
+import { SugarInner } from '.';
+import { Sugar, SugarValue } from './types';
+
+export type SugarUseIsPending = () => boolean;
+
+export function useIsPending<T extends SugarValue>(sugar: Sugar<T>): boolean {
+  const [isPending, setIsPending] = useState<boolean>(() => {
+    const sugarInner = sugar as unknown as SugarInner<T>;
+    return sugarInner.template?.status === 'pending';
+  });
+
+  useEffect(() => {
+    const checkPendingState = () => {
+      const sugarInner = sugar as unknown as SugarInner<T>;
+      const newIsPending = sugarInner.template?.status === 'pending';
+      setIsPending(newIsPending);
+    };
+
+    checkPendingState();
+
+    const originalSetTemplate = sugar.setTemplate.bind(sugar);
+    sugar.setTemplate = async (value: T, executeSet = true) => {
+      const result = await originalSetTemplate(value, executeSet);
+      checkPendingState();
+      return result;
+    };
+
+    const sugarInner = sugar as unknown as SugarInner<T>;
+    const originalSetPendingTemplate =
+      sugarInner.setPendingTemplate?.bind(sugarInner);
+    if (originalSetPendingTemplate) {
+      sugarInner.setPendingTemplate = () => {
+        originalSetPendingTemplate();
+        checkPendingState();
+      };
+    }
+
+    return () => {
+      sugar.setTemplate = originalSetTemplate;
+      if (originalSetPendingTemplate) {
+        sugarInner.setPendingTemplate = originalSetPendingTemplate;
+      }
+    };
+  }, [sugar]);
+
+  return isPending;
+}

packages/core/src/sugar/useObject.ts

@@ -3,6 +3,7 @@
   Sugar,
   SugarGetResult,
   SugarSetResult,
+  SugarTemplateState,
   SugarValue,
   SugarValueObject,
 } from './types';
@@ -36,7 +37,33 @@
       {
         get: (target: Record<string, SugarInner<unknown>>, prop: string, _) => {
           if (!(prop in target)) {
-            const s = new SugarInner((sugar as SugarInner<T>).template?.[prop]);
+            const parentTemplate = (sugar as SugarInner<T>).template;
+            let childTemplate: SugarTemplateState<unknown>;
+
+            if (parentTemplate?.status === 'pending') {
+              childTemplate = { status: 'pending' };
+            } else if (parentTemplate?.status === 'resolved') {
+              const parentValue = parentTemplate.value as Record<
+                string,
+                unknown
+              >;
+              if (
+                parentValue &&
+                typeof parentValue === 'object' &&
+                prop in parentValue
+              ) {
+                childTemplate = {
+                  status: 'resolved',
+                  value: parentValue[prop],
+                };
+              } else {
+                childTemplate = undefined;
+              }
+            } else {
+              childTemplate = undefined;
+            }
+
+            const s = new SugarInner(childTemplate);
             sugarInitializer.current.forEach((initializer) => {
               s.addEventListener('change', initializer.dispatchChange);
               s.addEventListener('blur', initializer.dispatchBlur);
@@ -63,6 +90,7 @@
       sugar.addEventListener('change', dispatchChange);
       sugar.addEventListener('blur', dispatchBlur);
     });
+
     sugarInitializer.current.push(initializer);
 
     sugar.ready(
@@ -157,30 +185,74 @@
         //   return { result: 'unavailable' };
         // }
 
-        const results: [string, SugarSetResult<unknown>][] = await Promise.all(
-          Object.entries(fields.current!).map(async ([key, s]) => {
-            if (key in value) {
-              const nestedValue = (value as Record<string, unknown>)[key];
-              const result = await s.setTemplate(nestedValue, executeSet);
-              return [key, result];
-            }
-            return [key, { result: 'success' as const }];
-          })
-        );
+        const parentTemplate = (sugar as SugarInner<T>).template;
 
-        const unavailables = results.filter(
-          ([_, value]) => value.result === 'unavailable'
-        );
-        if (unavailables.length > 0) {
-          console.error(
-            `Setting template for useObject sugar: ${unavailables
-              .map(([key, _]) => key)
-              .join(', ')} is unavailable.`
+        if (parentTemplate?.status === 'pending') {
+          await Promise.all(
+            Object.entries(fields.current!).map(async ([_, s]) => {
+              (s as SugarInner<unknown>).setPendingTemplate();
+            })
           );
-          return { result: 'unavailable' };
-        }
+          return { result: 'success' };
+        } else if (parentTemplate?.status === 'resolved') {
+          const parentValue = parentTemplate.value as Record<string, unknown>;
+          const results: [string, SugarSetResult<unknown>][] =
+            await Promise.all(
+              Object.entries(fields.current!).map(async ([key, s]) => {
+                if (
+                  parentValue &&
+                  typeof parentValue === 'object' &&
+                  key in parentValue
+                ) {
+                  const result = await s.setTemplate(
+                    parentValue[key],
+                    executeSet
+                  );
+                  return [key, result];
+                }
+                return [key, { result: 'success' as const }];
+              })
+            );
 
-        return { result: 'success' };
+          const unavailables = results.filter(
+            ([_, value]) => value.result === 'unavailable'
+          );
+          if (unavailables.length > 0) {
+            console.error(
+              `Setting template for useObject sugar: ${unavailables
+                .map(([key, _]) => key)
+                .join(', ')} is unavailable.`
+            );
+            return { result: 'unavailable' };
+          }
+
+          return { result: 'success' };
+        } else {
+          const results: [string, SugarSetResult<unknown>][] =
+            await Promise.all(
+              Object.entries(fields.current!).map(async ([key, s]) => {
+                const result = await s.setTemplate(
+                  undefined as unknown,
+                  executeSet
+                );
+                return [key, result];
+              })
+            );
+
+          const unavailables = results.filter(
+            ([_, value]) => value.result === 'unavailable'
+          );
+          if (unavailables.length > 0) {
+            console.error(
+              `Setting template for useObject sugar: ${unavailables
+                .map(([key, _]) => key)
+                .join(', ')} is unavailable.`
+            );
+            return { result: 'unavailable' };
+          }
+
+          return { result: 'success' };
+        }
       }
     );
 
@@ -189,7 +261,7 @@
       sugar.destroy();
       if (fields.current) {
         Object.values(fields.current).forEach((sugar) => {
-          sugar.removeEventListener('change', dispatchEvent);
+          sugar.removeEventListener('change', dispatchChange);
           sugar.removeEventListener('blur', dispatchBlur);
         });
         sugarInitializer.current = sugarInitializer.current.filter(

tests/core-unittest/src/collect.spec.tsx

@@ -6,7 +6,7 @@ import { describeWithStrict } from '../util/describeWithStrict';
 describeWithStrict('useForm#collect', () => {
   test('collect method should be equivalent to sugar.get(true)', async () => {
     const { result } = renderHook(() =>
-      useForm<string>({ template: 'initial' })
+      useForm({ template: { status: 'resolved', value: 'initial' } })
     );
 
     render(<TextInput sugar={result.current.sugar} />);
@@ -23,7 +23,9 @@ describeWithStrict('useForm#collect', () => {
   });
 
   test('collect method should trigger validation like sugar.get(true)', async () => {
-    const { result } = renderHook(() => useForm({ template: { a: '' } }));
+    const { result } = renderHook(() =>
+      useForm({ template: { status: 'resolved', value: { a: '' } } })
+    );
     const { result: obj } = renderHook(() => result.current.sugar.useObject());
 
     const validate = async (
@@ -48,8 +50,8 @@ describeWithStrict('useForm#collect', () => {
 
   test('collect method should return the same type as sugar.get(true)', async () => {
     const { result } = renderHook(() =>
-      useForm<{ name: string; age: number }>({
-        template: { name: 'John', age: 25 },
+      useForm({
+        template: { status: 'resolved', value: { name: 'John', age: 25 } },
       })
     );
     const { result: obj } = renderHook(() => result.current.sugar.useObject());

tests/core-unittest/src/component.spec.tsx

@@ -22,7 +22,9 @@ type Component = {
 describeWithStrict('Component requirements', () => {
   describe.each<Component>(Components)('$name', (c) => {
     test('Component should be ready after render', async () => {
-      const { result } = renderHook(() => useForm({ template: c.template }));
+      const { result } = renderHook(() =>
+        useForm({ template: { status: 'resolved', value: c.template } })
+      );
       const get = result.current.sugar.get();
 
       expect(await checkPending(get)).toStrictEqual({ resolved: false });
@@ -39,7 +41,9 @@ describeWithStrict('Component requirements', () => {
     });
 
     test('Sugar should be destroyed after unmount', async () => {
-      const { result } = renderHook(() => useForm({ template: c.template }));
+      const { result } = renderHook(() =>
+        useForm({ template: { status: 'resolved', value: c.template } })
+      );
       const { unmount } = render(<c.Component sugar={result.current.sugar} />);
       await expect(result.current.sugar.get()).resolves.toStrictEqual({
         result: 'success',