mvc-kit 2.13.1 → 2.14.0

package/dist/react/use-model.cjs

@@ -1,19 +1,38 @@
 const require_guards = require("./guards.cjs");
 let react = require("react");
 //#region src/react/use-model.ts
+var __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
+function assertModelExists(model, hookName) {
+	if (model) return;
+	throw new Error(`${hookName}: received an undefined/null model. This usually means the component rendered before the ViewModel finished creating the model. Either (a) create the model in the ViewModel constructor when the initial data is available (so it exists from the first render), or (b) if the model is created in onInit() after an async fetch, guard the component render with \`if (!vm.model) return <Spinner />\` before calling this hook. Do not use \`public model!: FormModel\` — the \`!\` lies to TypeScript about runtime state.`);
+}
 /**
 * Bind to a component-scoped Model with validation and dirty state exposed.
 */
 function useModel(factory) {
 	const modelRef = (0, react.useRef)(null);
 	const mountedRef = (0, react.useRef)(false);
-	if (!modelRef.current || modelRef.current.disposed) modelRef.current = factory();
-	const modelSubscribe = (0, react.useCallback)((onStoreChange) => modelRef.current.subscribe(onStoreChange), []);
-	const modelSnapshot = (0, react.useCallback)(() => modelRef.current.state, []);
+	let model = modelRef.current;
+	if (!model || model.disposed) {
+		model = factory();
+		if (__DEV__) assertModelExists(model, "useModel");
+		modelRef.current = model;
+	}
+	const modelSubscribe = (0, react.useCallback)((onStoreChange) => {
+		const m = modelRef.current;
+		return m ? m.subscribe(onStoreChange) : () => {};
+	}, []);
+	const modelSnapshot = (0, react.useCallback)(() => {
+		const m = modelRef.current;
+		if (!m) throw new Error("useModel: model accessed before creation");
+		return m.state;
+	}, []);
 	(0, react.useSyncExternalStore)(modelSubscribe, modelSnapshot, modelSnapshot);
 	(0, react.useEffect)(() => {
+		const m = modelRef.current;
+		if (!m) return;
 		mountedRef.current = true;
-		if (require_guards.isInitializable(modelRef.current)) modelRef.current.init();
+		if (require_guards.isInitializable(m)) m.init();
 		return () => {
 			mountedRef.current = false;
 			setTimeout(() => {
@@ -21,7 +40,6 @@ function useModel(factory) {
 			}, 0);
 		};
 	}, []);
-	const model = modelRef.current;
 	return {
 		state: model.state,
 		errors: model.errors,
@@ -41,10 +59,17 @@ function useModel(factory) {
 function useModelRef(factory) {
 	const modelRef = (0, react.useRef)(null);
 	const mountedRef = (0, react.useRef)(false);
-	if (!modelRef.current || modelRef.current.disposed) modelRef.current = factory();
+	let model = modelRef.current;
+	if (!model || model.disposed) {
+		model = factory();
+		if (__DEV__) assertModelExists(model, "useModelRef");
+		modelRef.current = model;
+	}
 	(0, react.useEffect)(() => {
+		const m = modelRef.current;
+		if (!m) return;
 		mountedRef.current = true;
-		if (require_guards.isInitializable(modelRef.current)) modelRef.current.init();
+		if (require_guards.isInitializable(m)) m.init();
 		return () => {
 			mountedRef.current = false;
 			setTimeout(() => {
@@ -52,12 +77,13 @@ function useModelRef(factory) {
 			}, 0);
 		};
 	}, []);
-	return modelRef.current;
+	return model;
 }
 /**
 * Bind to a single Model field with surgical re-renders.
 */
 function useField(model, field) {
+	if (__DEV__) assertModelExists(model, "useField");
 	const getSnapshot = (0, react.useCallback)(() => {
 		return {
 			value: model.state[field],

package/dist/react/use-model.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-model.cjs","names":[],"sources":["../../src/react/use-model.ts"],"sourcesContent":["import { useRef, useEffect, useSyncExternalStore, useCallback } from 'react';\nimport type { Model } from '../Model';\nimport type { ValidationErrors } from '../types';\nimport type { StateOf } from './types';\nimport { isInitializable } from './guards';\n\n/** Return type of `useModel`, providing state, validation, and model access. */\nexport interface ModelHandle<S extends object, M extends Model<S>> {\n  state: S;\n  errors: ValidationErrors<S>;\n  valid: boolean;\n  dirty: boolean;\n  model: M;\n}\n\n/**\n * Bind to a component-scoped Model with validation and dirty state exposed.\n */\nexport function useModel<M extends Model<any>>(\n  factory: () => M\n): ModelHandle<StateOf<M>, M> {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  if (!modelRef.current || modelRef.current.disposed) {\n    modelRef.current = factory();\n  }\n\n  const modelSubscribe = useCallback(\n    (onStoreChange: () => void) => modelRef.current!.subscribe(onStoreChange),\n    []\n  );\n  const modelSnapshot = useCallback(\n    () => modelRef.current!.state,\n    []\n  );\n  useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);\n\n  useEffect(() => {\n    mountedRef.current = true;\n    if (isInitializable(modelRef.current)) {\n      modelRef.current.init();\n    }\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  const model = modelRef.current;\n\n  return {\n    state: model.state,\n    errors: model.errors,\n    valid: model.valid,\n    dirty: model.dirty,\n    model,\n  };\n}\n\n/**\n * Create a component-scoped Model with lifecycle management (init + dispose)\n * but NO state subscription. The parent component never re-renders from\n * model state changes.\n *\n * Designed for the per-field isolation pattern: parent creates the model\n * via `useModelRef`, children subscribe to individual fields via `useField`.\n */\nexport function useModelRef<M extends Model<any>>(factory: () => M): M {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  if (!modelRef.current || modelRef.current.disposed) {\n    modelRef.current = factory();\n  }\n\n  useEffect(() => {\n    mountedRef.current = true;\n    if (isInitializable(modelRef.current)) {\n      modelRef.current.init();\n    }\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  return modelRef.current;\n}\n\n/** Return type of `useField`, providing a single field's value, error, and setter. */\nexport interface FieldHandle<V> {\n  value: V;\n  error: string | undefined;\n  set: (value: V) => void;\n}\n\n/**\n * Bind to a single Model field with surgical re-renders.\n */\nexport function useField<S extends object, K extends keyof S>(\n  model: Model<S>,\n  field: K\n): FieldHandle<S[K]> {\n  // Track the field value and error for comparison\n  const getSnapshot = useCallback(() => {\n    return {\n      value: model.state[field],\n      error: model.errors[field],\n    };\n  }, [model, field]);\n\n  // Use object comparison for subscription\n  const cachedRef = useRef(getSnapshot());\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      return model.subscribe(() => {\n        const next = getSnapshot();\n        const current = cachedRef.current;\n\n        // Only trigger re-render if field value or error changed\n        if (next.value !== current.value || next.error !== current.error) {\n          cachedRef.current = next;\n          onStoreChange();\n        }\n      });\n    },\n    [model, getSnapshot]\n  );\n\n  const snapshot = useSyncExternalStore(\n    subscribe,\n    () => cachedRef.current,\n    () => cachedRef.current\n  );\n\n  const set = useCallback(\n    (value: S[K]) => {\n      // Access the protected set method through type assertion\n      // The Model subclass should expose a setter method\n      const partial: Partial<S> = { [field]: value } as unknown as Partial<S>;\n      (model as unknown as { set: (partial: Partial<S>) => void }).set(partial);\n    },\n    [model, field]\n  );\n\n  return {\n    value: snapshot.value,\n    error: snapshot.error,\n    set,\n  };\n}\n"],"mappings":";;;;;;AAkBA,SAAgB,SACd,SAC4B;CAC5B,MAAM,YAAA,GAAA,MAAA,QAA4B,KAAK;CACvC,MAAM,cAAA,GAAA,MAAA,QAAoB,MAAM;AAEhC,KAAI,CAAC,SAAS,WAAW,SAAS,QAAQ,SACxC,UAAS,UAAU,SAAS;CAG9B,MAAM,kBAAA,GAAA,MAAA,cACH,kBAA8B,SAAS,QAAS,UAAU,cAAc,EACzE,EAAE,CACH;CACD,MAAM,iBAAA,GAAA,MAAA,mBACE,SAAS,QAAS,OACxB,EAAE,CACH;AACD,EAAA,GAAA,MAAA,sBAAqB,gBAAgB,eAAe,cAAc;AAElE,EAAA,GAAA,MAAA,iBAAgB;AACd,aAAW,UAAU;AACrB,MAAI,eAAA,gBAAgB,SAAS,QAAQ,CACnC,UAAS,QAAQ,MAAM;AAEzB,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;CAEN,MAAM,QAAQ,SAAS;AAEvB,QAAO;EACL,OAAO,MAAM;EACb,QAAQ,MAAM;EACd,OAAO,MAAM;EACb,OAAO,MAAM;EACb;EACD;;;;;;;;;;AAWH,SAAgB,YAAkC,SAAqB;CACrE,MAAM,YAAA,GAAA,MAAA,QAA4B,KAAK;CACvC,MAAM,cAAA,GAAA,MAAA,QAAoB,MAAM;AAEhC,KAAI,CAAC,SAAS,WAAW,SAAS,QAAQ,SACxC,UAAS,UAAU,SAAS;AAG9B,EAAA,GAAA,MAAA,iBAAgB;AACd,aAAW,UAAU;AACrB,MAAI,eAAA,gBAAgB,SAAS,QAAQ,CACnC,UAAS,QAAQ,MAAM;AAEzB,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;AAEN,QAAO,SAAS;;;;;AAalB,SAAgB,SACd,OACA,OACmB;CAEnB,MAAM,eAAA,GAAA,MAAA,mBAAgC;AACpC,SAAO;GACL,OAAO,MAAM,MAAM;GACnB,OAAO,MAAM,OAAO;GACrB;IACA,CAAC,OAAO,MAAM,CAAC;CAGlB,MAAM,aAAA,GAAA,MAAA,QAAmB,aAAa,CAAC;CAkBvC,MAAM,YAAA,GAAA,MAAA,uBAAA,GAAA,MAAA,cAfH,kBAA8B;AAC7B,SAAO,MAAM,gBAAgB;GAC3B,MAAM,OAAO,aAAa;GAC1B,MAAM,UAAU,UAAU;AAG1B,OAAI,KAAK,UAAU,QAAQ,SAAS,KAAK,UAAU,QAAQ,OAAO;AAChE,cAAU,UAAU;AACpB,mBAAe;;IAEjB;IAEJ,CAAC,OAAO,YAAY,CACrB,QAIO,UAAU,eACV,UAAU,QACjB;CAED,MAAM,OAAA,GAAA,MAAA,cACH,UAAgB;EAGf,MAAM,UAAsB,GAAG,QAAQ,OAAO;AAC7C,QAA4D,IAAI,QAAQ;IAE3E,CAAC,OAAO,MAAM,CACf;AAED,QAAO;EACL,OAAO,SAAS;EAChB,OAAO,SAAS;EAChB;EACD"}
+{"version":3,"file":"use-model.cjs","names":[],"sources":["../../src/react/use-model.ts"],"sourcesContent":["import { useRef, useEffect, useSyncExternalStore, useCallback } from 'react';\nimport type { Model } from '../Model';\nimport type { ValidationErrors } from '../types';\nimport type { StateOf } from './types';\nimport { isInitializable } from './guards';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\nfunction assertModelExists(\n  model: unknown,\n  hookName: 'useModel' | 'useModelRef' | 'useField',\n): asserts model {\n  if (model) return;\n  throw new Error(\n    `${hookName}: received an undefined/null model. ` +\n    'This usually means the component rendered before the ViewModel finished creating the model. ' +\n    'Either (a) create the model in the ViewModel constructor when the initial data is available ' +\n    '(so it exists from the first render), or (b) if the model is created in onInit() after an async ' +\n    'fetch, guard the component render with `if (!vm.model) return <Spinner />` before calling this hook. ' +\n    'Do not use `public model!: FormModel` — the `!` lies to TypeScript about runtime state.',\n  );\n}\n\n/** Return type of `useModel`, providing state, validation, and model access. */\nexport interface ModelHandle<S extends object, M extends Model<S>> {\n  state: S;\n  errors: ValidationErrors<S>;\n  valid: boolean;\n  dirty: boolean;\n  model: M;\n}\n\n/**\n * Bind to a component-scoped Model with validation and dirty state exposed.\n */\nexport function useModel<M extends Model<any>>(\n  factory: () => M\n): ModelHandle<StateOf<M>, M> {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  let model = modelRef.current;\n  if (!model || model.disposed) {\n    model = factory();\n    if (__DEV__) assertModelExists(model, 'useModel');\n    modelRef.current = model;\n  }\n\n  const modelSubscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const m = modelRef.current;\n      return m ? m.subscribe(onStoreChange) : () => {};\n    },\n    []\n  );\n  const modelSnapshot = useCallback(\n    () => {\n      const m = modelRef.current;\n      if (!m) throw new Error('useModel: model accessed before creation');\n      return m.state;\n    },\n    []\n  );\n  useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);\n\n  useEffect(() => {\n    const m = modelRef.current;\n    if (!m) return;\n    mountedRef.current = true;\n    if (isInitializable(m)) m.init();\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  return {\n    state: model.state,\n    errors: model.errors,\n    valid: model.valid,\n    dirty: model.dirty,\n    model,\n  };\n}\n\n/**\n * Create a component-scoped Model with lifecycle management (init + dispose)\n * but NO state subscription. The parent component never re-renders from\n * model state changes.\n *\n * Designed for the per-field isolation pattern: parent creates the model\n * via `useModelRef`, children subscribe to individual fields via `useField`.\n */\nexport function useModelRef<M extends Model<any>>(factory: () => M): M {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  let model = modelRef.current;\n  if (!model || model.disposed) {\n    model = factory();\n    if (__DEV__) assertModelExists(model, 'useModelRef');\n    modelRef.current = model;\n  }\n\n  useEffect(() => {\n    const m = modelRef.current;\n    if (!m) return;\n    mountedRef.current = true;\n    if (isInitializable(m)) m.init();\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  return model;\n}\n\n/** Return type of `useField`, providing a single field's value, error, and setter. */\nexport interface FieldHandle<V> {\n  value: V;\n  error: string | undefined;\n  set: (value: V) => void;\n}\n\n/**\n * Bind to a single Model field with surgical re-renders.\n */\nexport function useField<S extends object, K extends keyof S>(\n  model: Model<S>,\n  field: K\n): FieldHandle<S[K]> {\n  if (__DEV__) assertModelExists(model, 'useField');\n  // Track the field value and error for comparison\n  const getSnapshot = useCallback(() => {\n    return {\n      value: model.state[field],\n      error: model.errors[field],\n    };\n  }, [model, field]);\n\n  // Use object comparison for subscription\n  const cachedRef = useRef(getSnapshot());\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      return model.subscribe(() => {\n        const next = getSnapshot();\n        const current = cachedRef.current;\n\n        // Only trigger re-render if field value or error changed\n        if (next.value !== current.value || next.error !== current.error) {\n          cachedRef.current = next;\n          onStoreChange();\n        }\n      });\n    },\n    [model, getSnapshot]\n  );\n\n  const snapshot = useSyncExternalStore(\n    subscribe,\n    () => cachedRef.current,\n    () => cachedRef.current\n  );\n\n  const set = useCallback(\n    (value: S[K]) => {\n      // Access the protected set method through type assertion\n      // The Model subclass should expose a setter method\n      const partial: Partial<S> = { [field]: value } as unknown as Partial<S>;\n      (model as unknown as { set: (partial: Partial<S>) => void }).set(partial);\n    },\n    [model, field]\n  );\n\n  return {\n    value: snapshot.value,\n    error: snapshot.error,\n    set,\n  };\n}\n"],"mappings":";;;AAMA,IAAM,UAAU,OAAO,oBAAoB,eAAe;AAE1D,SAAS,kBACP,OACA,UACe;AACf,KAAI,MAAO;AACX,OAAM,IAAI,MACR,GAAG,SAAS,ggBAMb;;;;;AAeH,SAAgB,SACd,SAC4B;CAC5B,MAAM,YAAA,GAAA,MAAA,QAA4B,KAAK;CACvC,MAAM,cAAA,GAAA,MAAA,QAAoB,MAAM;CAEhC,IAAI,QAAQ,SAAS;AACrB,KAAI,CAAC,SAAS,MAAM,UAAU;AAC5B,UAAQ,SAAS;AACjB,MAAI,QAAS,mBAAkB,OAAO,WAAW;AACjD,WAAS,UAAU;;CAGrB,MAAM,kBAAA,GAAA,MAAA,cACH,kBAA8B;EAC7B,MAAM,IAAI,SAAS;AACnB,SAAO,IAAI,EAAE,UAAU,cAAc,SAAS;IAEhD,EAAE,CACH;CACD,MAAM,iBAAA,GAAA,MAAA,mBACE;EACJ,MAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG,OAAM,IAAI,MAAM,2CAA2C;AACnE,SAAO,EAAE;IAEX,EAAE,CACH;AACD,EAAA,GAAA,MAAA,sBAAqB,gBAAgB,eAAe,cAAc;AAElE,EAAA,GAAA,MAAA,iBAAgB;EACd,MAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG;AACR,aAAW,UAAU;AACrB,MAAI,eAAA,gBAAgB,EAAE,CAAE,GAAE,MAAM;AAChC,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;AAEN,QAAO;EACL,OAAO,MAAM;EACb,QAAQ,MAAM;EACd,OAAO,MAAM;EACb,OAAO,MAAM;EACb;EACD;;;;;;;;;;AAWH,SAAgB,YAAkC,SAAqB;CACrE,MAAM,YAAA,GAAA,MAAA,QAA4B,KAAK;CACvC,MAAM,cAAA,GAAA,MAAA,QAAoB,MAAM;CAEhC,IAAI,QAAQ,SAAS;AACrB,KAAI,CAAC,SAAS,MAAM,UAAU;AAC5B,UAAQ,SAAS;AACjB,MAAI,QAAS,mBAAkB,OAAO,cAAc;AACpD,WAAS,UAAU;;AAGrB,EAAA,GAAA,MAAA,iBAAgB;EACd,MAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG;AACR,aAAW,UAAU;AACrB,MAAI,eAAA,gBAAgB,EAAE,CAAE,GAAE,MAAM;AAChC,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;AAEN,QAAO;;;;;AAaT,SAAgB,SACd,OACA,OACmB;AACnB,KAAI,QAAS,mBAAkB,OAAO,WAAW;CAEjD,MAAM,eAAA,GAAA,MAAA,mBAAgC;AACpC,SAAO;GACL,OAAO,MAAM,MAAM;GACnB,OAAO,MAAM,OAAO;GACrB;IACA,CAAC,OAAO,MAAM,CAAC;CAGlB,MAAM,aAAA,GAAA,MAAA,QAAmB,aAAa,CAAC;CAkBvC,MAAM,YAAA,GAAA,MAAA,uBAAA,GAAA,MAAA,cAfH,kBAA8B;AAC7B,SAAO,MAAM,gBAAgB;GAC3B,MAAM,OAAO,aAAa;GAC1B,MAAM,UAAU,UAAU;AAG1B,OAAI,KAAK,UAAU,QAAQ,SAAS,KAAK,UAAU,QAAQ,OAAO;AAChE,cAAU,UAAU;AACpB,mBAAe;;IAEjB;IAEJ,CAAC,OAAO,YAAY,CACrB,QAIO,UAAU,eACV,UAAU,QACjB;CAED,MAAM,OAAA,GAAA,MAAA,cACH,UAAgB;EAGf,MAAM,UAAsB,GAAG,QAAQ,OAAO;AAC7C,QAA4D,IAAI,QAAQ;IAE3E,CAAC,OAAO,MAAM,CACf;AAED,QAAO;EACL,OAAO,SAAS;EAChB,OAAO,SAAS;EAChB;EACD"}

package/dist/react/use-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-model.d.ts","sourceRoot":"","sources":["../../src/react/use-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,gFAAgF;AAChF,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC;IAC/D,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,CAAC,CAAC;CACV;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EAC3C,OAAO,EAAE,MAAM,CAAC,GACf,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CA0C5B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAwBrE;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC1D,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,KAAK,EAAE,CAAC,GACP,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAiDnB"}
+{"version":3,"file":"use-model.d.ts","sourceRoot":"","sources":["../../src/react/use-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAoBvC,gFAAgF;AAChF,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC;IAC/D,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,CAAC,CAAC;CACV;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EAC3C,OAAO,EAAE,MAAM,CAAC,GACf,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAkD5B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CA2BrE;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC1D,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,KAAK,EAAE,CAAC,GACP,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAkDnB"}

package/dist/react/use-model.js

@@ -1,19 +1,38 @@
 import { isInitializable } from "./guards.js";
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 //#region src/react/use-model.ts
+var __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
+function assertModelExists(model, hookName) {
+	if (model) return;
+	throw new Error(`${hookName}: received an undefined/null model. This usually means the component rendered before the ViewModel finished creating the model. Either (a) create the model in the ViewModel constructor when the initial data is available (so it exists from the first render), or (b) if the model is created in onInit() after an async fetch, guard the component render with \`if (!vm.model) return <Spinner />\` before calling this hook. Do not use \`public model!: FormModel\` — the \`!\` lies to TypeScript about runtime state.`);
+}
 /**
 * Bind to a component-scoped Model with validation and dirty state exposed.
 */
 function useModel(factory) {
 	const modelRef = useRef(null);
 	const mountedRef = useRef(false);
-	if (!modelRef.current || modelRef.current.disposed) modelRef.current = factory();
-	const modelSubscribe = useCallback((onStoreChange) => modelRef.current.subscribe(onStoreChange), []);
-	const modelSnapshot = useCallback(() => modelRef.current.state, []);
+	let model = modelRef.current;
+	if (!model || model.disposed) {
+		model = factory();
+		if (__DEV__) assertModelExists(model, "useModel");
+		modelRef.current = model;
+	}
+	const modelSubscribe = useCallback((onStoreChange) => {
+		const m = modelRef.current;
+		return m ? m.subscribe(onStoreChange) : () => {};
+	}, []);
+	const modelSnapshot = useCallback(() => {
+		const m = modelRef.current;
+		if (!m) throw new Error("useModel: model accessed before creation");
+		return m.state;
+	}, []);
 	useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);
 	useEffect(() => {
+		const m = modelRef.current;
+		if (!m) return;
 		mountedRef.current = true;
-		if (isInitializable(modelRef.current)) modelRef.current.init();
+		if (isInitializable(m)) m.init();
 		return () => {
 			mountedRef.current = false;
 			setTimeout(() => {
@@ -21,7 +40,6 @@ function useModel(factory) {
 			}, 0);
 		};
 	}, []);
-	const model = modelRef.current;
 	return {
 		state: model.state,
 		errors: model.errors,
@@ -41,10 +59,17 @@ function useModel(factory) {
 function useModelRef(factory) {
 	const modelRef = useRef(null);
 	const mountedRef = useRef(false);
-	if (!modelRef.current || modelRef.current.disposed) modelRef.current = factory();
+	let model = modelRef.current;
+	if (!model || model.disposed) {
+		model = factory();
+		if (__DEV__) assertModelExists(model, "useModelRef");
+		modelRef.current = model;
+	}
 	useEffect(() => {
+		const m = modelRef.current;
+		if (!m) return;
 		mountedRef.current = true;
-		if (isInitializable(modelRef.current)) modelRef.current.init();
+		if (isInitializable(m)) m.init();
 		return () => {
 			mountedRef.current = false;
 			setTimeout(() => {
@@ -52,12 +77,13 @@ function useModelRef(factory) {
 			}, 0);
 		};
 	}, []);
-	return modelRef.current;
+	return model;
 }
 /**
 * Bind to a single Model field with surgical re-renders.
 */
 function useField(model, field) {
+	if (__DEV__) assertModelExists(model, "useField");
 	const getSnapshot = useCallback(() => {
 		return {
 			value: model.state[field],

package/dist/react/use-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-model.js","names":[],"sources":["../../src/react/use-model.ts"],"sourcesContent":["import { useRef, useEffect, useSyncExternalStore, useCallback } from 'react';\nimport type { Model } from '../Model';\nimport type { ValidationErrors } from '../types';\nimport type { StateOf } from './types';\nimport { isInitializable } from './guards';\n\n/** Return type of `useModel`, providing state, validation, and model access. */\nexport interface ModelHandle<S extends object, M extends Model<S>> {\n  state: S;\n  errors: ValidationErrors<S>;\n  valid: boolean;\n  dirty: boolean;\n  model: M;\n}\n\n/**\n * Bind to a component-scoped Model with validation and dirty state exposed.\n */\nexport function useModel<M extends Model<any>>(\n  factory: () => M\n): ModelHandle<StateOf<M>, M> {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  if (!modelRef.current || modelRef.current.disposed) {\n    modelRef.current = factory();\n  }\n\n  const modelSubscribe = useCallback(\n    (onStoreChange: () => void) => modelRef.current!.subscribe(onStoreChange),\n    []\n  );\n  const modelSnapshot = useCallback(\n    () => modelRef.current!.state,\n    []\n  );\n  useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);\n\n  useEffect(() => {\n    mountedRef.current = true;\n    if (isInitializable(modelRef.current)) {\n      modelRef.current.init();\n    }\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  const model = modelRef.current;\n\n  return {\n    state: model.state,\n    errors: model.errors,\n    valid: model.valid,\n    dirty: model.dirty,\n    model,\n  };\n}\n\n/**\n * Create a component-scoped Model with lifecycle management (init + dispose)\n * but NO state subscription. The parent component never re-renders from\n * model state changes.\n *\n * Designed for the per-field isolation pattern: parent creates the model\n * via `useModelRef`, children subscribe to individual fields via `useField`.\n */\nexport function useModelRef<M extends Model<any>>(factory: () => M): M {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  if (!modelRef.current || modelRef.current.disposed) {\n    modelRef.current = factory();\n  }\n\n  useEffect(() => {\n    mountedRef.current = true;\n    if (isInitializable(modelRef.current)) {\n      modelRef.current.init();\n    }\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  return modelRef.current;\n}\n\n/** Return type of `useField`, providing a single field's value, error, and setter. */\nexport interface FieldHandle<V> {\n  value: V;\n  error: string | undefined;\n  set: (value: V) => void;\n}\n\n/**\n * Bind to a single Model field with surgical re-renders.\n */\nexport function useField<S extends object, K extends keyof S>(\n  model: Model<S>,\n  field: K\n): FieldHandle<S[K]> {\n  // Track the field value and error for comparison\n  const getSnapshot = useCallback(() => {\n    return {\n      value: model.state[field],\n      error: model.errors[field],\n    };\n  }, [model, field]);\n\n  // Use object comparison for subscription\n  const cachedRef = useRef(getSnapshot());\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      return model.subscribe(() => {\n        const next = getSnapshot();\n        const current = cachedRef.current;\n\n        // Only trigger re-render if field value or error changed\n        if (next.value !== current.value || next.error !== current.error) {\n          cachedRef.current = next;\n          onStoreChange();\n        }\n      });\n    },\n    [model, getSnapshot]\n  );\n\n  const snapshot = useSyncExternalStore(\n    subscribe,\n    () => cachedRef.current,\n    () => cachedRef.current\n  );\n\n  const set = useCallback(\n    (value: S[K]) => {\n      // Access the protected set method through type assertion\n      // The Model subclass should expose a setter method\n      const partial: Partial<S> = { [field]: value } as unknown as Partial<S>;\n      (model as unknown as { set: (partial: Partial<S>) => void }).set(partial);\n    },\n    [model, field]\n  );\n\n  return {\n    value: snapshot.value,\n    error: snapshot.error,\n    set,\n  };\n}\n"],"mappings":";;;;;;AAkBA,SAAgB,SACd,SAC4B;CAC5B,MAAM,WAAW,OAAiB,KAAK;CACvC,MAAM,aAAa,OAAO,MAAM;AAEhC,KAAI,CAAC,SAAS,WAAW,SAAS,QAAQ,SACxC,UAAS,UAAU,SAAS;CAG9B,MAAM,iBAAiB,aACpB,kBAA8B,SAAS,QAAS,UAAU,cAAc,EACzE,EAAE,CACH;CACD,MAAM,gBAAgB,kBACd,SAAS,QAAS,OACxB,EAAE,CACH;AACD,sBAAqB,gBAAgB,eAAe,cAAc;AAElE,iBAAgB;AACd,aAAW,UAAU;AACrB,MAAI,gBAAgB,SAAS,QAAQ,CACnC,UAAS,QAAQ,MAAM;AAEzB,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;CAEN,MAAM,QAAQ,SAAS;AAEvB,QAAO;EACL,OAAO,MAAM;EACb,QAAQ,MAAM;EACd,OAAO,MAAM;EACb,OAAO,MAAM;EACb;EACD;;;;;;;;;;AAWH,SAAgB,YAAkC,SAAqB;CACrE,MAAM,WAAW,OAAiB,KAAK;CACvC,MAAM,aAAa,OAAO,MAAM;AAEhC,KAAI,CAAC,SAAS,WAAW,SAAS,QAAQ,SACxC,UAAS,UAAU,SAAS;AAG9B,iBAAgB;AACd,aAAW,UAAU;AACrB,MAAI,gBAAgB,SAAS,QAAQ,CACnC,UAAS,QAAQ,MAAM;AAEzB,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;AAEN,QAAO,SAAS;;;;;AAalB,SAAgB,SACd,OACA,OACmB;CAEnB,MAAM,cAAc,kBAAkB;AACpC,SAAO;GACL,OAAO,MAAM,MAAM;GACnB,OAAO,MAAM,OAAO;GACrB;IACA,CAAC,OAAO,MAAM,CAAC;CAGlB,MAAM,YAAY,OAAO,aAAa,CAAC;CAkBvC,MAAM,WAAW,qBAhBC,aACf,kBAA8B;AAC7B,SAAO,MAAM,gBAAgB;GAC3B,MAAM,OAAO,aAAa;GAC1B,MAAM,UAAU,UAAU;AAG1B,OAAI,KAAK,UAAU,QAAQ,SAAS,KAAK,UAAU,QAAQ,OAAO;AAChE,cAAU,UAAU;AACpB,mBAAe;;IAEjB;IAEJ,CAAC,OAAO,YAAY,CACrB,QAIO,UAAU,eACV,UAAU,QACjB;CAED,MAAM,MAAM,aACT,UAAgB;EAGf,MAAM,UAAsB,GAAG,QAAQ,OAAO;AAC7C,QAA4D,IAAI,QAAQ;IAE3E,CAAC,OAAO,MAAM,CACf;AAED,QAAO;EACL,OAAO,SAAS;EAChB,OAAO,SAAS;EAChB;EACD"}
+{"version":3,"file":"use-model.js","names":[],"sources":["../../src/react/use-model.ts"],"sourcesContent":["import { useRef, useEffect, useSyncExternalStore, useCallback } from 'react';\nimport type { Model } from '../Model';\nimport type { ValidationErrors } from '../types';\nimport type { StateOf } from './types';\nimport { isInitializable } from './guards';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\nfunction assertModelExists(\n  model: unknown,\n  hookName: 'useModel' | 'useModelRef' | 'useField',\n): asserts model {\n  if (model) return;\n  throw new Error(\n    `${hookName}: received an undefined/null model. ` +\n    'This usually means the component rendered before the ViewModel finished creating the model. ' +\n    'Either (a) create the model in the ViewModel constructor when the initial data is available ' +\n    '(so it exists from the first render), or (b) if the model is created in onInit() after an async ' +\n    'fetch, guard the component render with `if (!vm.model) return <Spinner />` before calling this hook. ' +\n    'Do not use `public model!: FormModel` — the `!` lies to TypeScript about runtime state.',\n  );\n}\n\n/** Return type of `useModel`, providing state, validation, and model access. */\nexport interface ModelHandle<S extends object, M extends Model<S>> {\n  state: S;\n  errors: ValidationErrors<S>;\n  valid: boolean;\n  dirty: boolean;\n  model: M;\n}\n\n/**\n * Bind to a component-scoped Model with validation and dirty state exposed.\n */\nexport function useModel<M extends Model<any>>(\n  factory: () => M\n): ModelHandle<StateOf<M>, M> {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  let model = modelRef.current;\n  if (!model || model.disposed) {\n    model = factory();\n    if (__DEV__) assertModelExists(model, 'useModel');\n    modelRef.current = model;\n  }\n\n  const modelSubscribe = useCallback(\n    (onStoreChange: () => void) => {\n      const m = modelRef.current;\n      return m ? m.subscribe(onStoreChange) : () => {};\n    },\n    []\n  );\n  const modelSnapshot = useCallback(\n    () => {\n      const m = modelRef.current;\n      if (!m) throw new Error('useModel: model accessed before creation');\n      return m.state;\n    },\n    []\n  );\n  useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);\n\n  useEffect(() => {\n    const m = modelRef.current;\n    if (!m) return;\n    mountedRef.current = true;\n    if (isInitializable(m)) m.init();\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  return {\n    state: model.state,\n    errors: model.errors,\n    valid: model.valid,\n    dirty: model.dirty,\n    model,\n  };\n}\n\n/**\n * Create a component-scoped Model with lifecycle management (init + dispose)\n * but NO state subscription. The parent component never re-renders from\n * model state changes.\n *\n * Designed for the per-field isolation pattern: parent creates the model\n * via `useModelRef`, children subscribe to individual fields via `useField`.\n */\nexport function useModelRef<M extends Model<any>>(factory: () => M): M {\n  const modelRef = useRef<M | null>(null);\n  const mountedRef = useRef(false);\n\n  let model = modelRef.current;\n  if (!model || model.disposed) {\n    model = factory();\n    if (__DEV__) assertModelExists(model, 'useModelRef');\n    modelRef.current = model;\n  }\n\n  useEffect(() => {\n    const m = modelRef.current;\n    if (!m) return;\n    mountedRef.current = true;\n    if (isInitializable(m)) m.init();\n    return () => {\n      mountedRef.current = false;\n      setTimeout(() => {\n        if (!mountedRef.current) {\n          modelRef.current?.dispose();\n        }\n      }, 0);\n    };\n  }, []);\n\n  return model;\n}\n\n/** Return type of `useField`, providing a single field's value, error, and setter. */\nexport interface FieldHandle<V> {\n  value: V;\n  error: string | undefined;\n  set: (value: V) => void;\n}\n\n/**\n * Bind to a single Model field with surgical re-renders.\n */\nexport function useField<S extends object, K extends keyof S>(\n  model: Model<S>,\n  field: K\n): FieldHandle<S[K]> {\n  if (__DEV__) assertModelExists(model, 'useField');\n  // Track the field value and error for comparison\n  const getSnapshot = useCallback(() => {\n    return {\n      value: model.state[field],\n      error: model.errors[field],\n    };\n  }, [model, field]);\n\n  // Use object comparison for subscription\n  const cachedRef = useRef(getSnapshot());\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      return model.subscribe(() => {\n        const next = getSnapshot();\n        const current = cachedRef.current;\n\n        // Only trigger re-render if field value or error changed\n        if (next.value !== current.value || next.error !== current.error) {\n          cachedRef.current = next;\n          onStoreChange();\n        }\n      });\n    },\n    [model, getSnapshot]\n  );\n\n  const snapshot = useSyncExternalStore(\n    subscribe,\n    () => cachedRef.current,\n    () => cachedRef.current\n  );\n\n  const set = useCallback(\n    (value: S[K]) => {\n      // Access the protected set method through type assertion\n      // The Model subclass should expose a setter method\n      const partial: Partial<S> = { [field]: value } as unknown as Partial<S>;\n      (model as unknown as { set: (partial: Partial<S>) => void }).set(partial);\n    },\n    [model, field]\n  );\n\n  return {\n    value: snapshot.value,\n    error: snapshot.error,\n    set,\n  };\n}\n"],"mappings":";;;AAMA,IAAM,UAAU,OAAO,oBAAoB,eAAe;AAE1D,SAAS,kBACP,OACA,UACe;AACf,KAAI,MAAO;AACX,OAAM,IAAI,MACR,GAAG,SAAS,ggBAMb;;;;;AAeH,SAAgB,SACd,SAC4B;CAC5B,MAAM,WAAW,OAAiB,KAAK;CACvC,MAAM,aAAa,OAAO,MAAM;CAEhC,IAAI,QAAQ,SAAS;AACrB,KAAI,CAAC,SAAS,MAAM,UAAU;AAC5B,UAAQ,SAAS;AACjB,MAAI,QAAS,mBAAkB,OAAO,WAAW;AACjD,WAAS,UAAU;;CAGrB,MAAM,iBAAiB,aACpB,kBAA8B;EAC7B,MAAM,IAAI,SAAS;AACnB,SAAO,IAAI,EAAE,UAAU,cAAc,SAAS;IAEhD,EAAE,CACH;CACD,MAAM,gBAAgB,kBACd;EACJ,MAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG,OAAM,IAAI,MAAM,2CAA2C;AACnE,SAAO,EAAE;IAEX,EAAE,CACH;AACD,sBAAqB,gBAAgB,eAAe,cAAc;AAElE,iBAAgB;EACd,MAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG;AACR,aAAW,UAAU;AACrB,MAAI,gBAAgB,EAAE,CAAE,GAAE,MAAM;AAChC,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;AAEN,QAAO;EACL,OAAO,MAAM;EACb,QAAQ,MAAM;EACd,OAAO,MAAM;EACb,OAAO,MAAM;EACb;EACD;;;;;;;;;;AAWH,SAAgB,YAAkC,SAAqB;CACrE,MAAM,WAAW,OAAiB,KAAK;CACvC,MAAM,aAAa,OAAO,MAAM;CAEhC,IAAI,QAAQ,SAAS;AACrB,KAAI,CAAC,SAAS,MAAM,UAAU;AAC5B,UAAQ,SAAS;AACjB,MAAI,QAAS,mBAAkB,OAAO,cAAc;AACpD,WAAS,UAAU;;AAGrB,iBAAgB;EACd,MAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG;AACR,aAAW,UAAU;AACrB,MAAI,gBAAgB,EAAE,CAAE,GAAE,MAAM;AAChC,eAAa;AACX,cAAW,UAAU;AACrB,oBAAiB;AACf,QAAI,CAAC,WAAW,QACd,UAAS,SAAS,SAAS;MAE5B,EAAE;;IAEN,EAAE,CAAC;AAEN,QAAO;;;;;AAaT,SAAgB,SACd,OACA,OACmB;AACnB,KAAI,QAAS,mBAAkB,OAAO,WAAW;CAEjD,MAAM,cAAc,kBAAkB;AACpC,SAAO;GACL,OAAO,MAAM,MAAM;GACnB,OAAO,MAAM,OAAO;GACrB;IACA,CAAC,OAAO,MAAM,CAAC;CAGlB,MAAM,YAAY,OAAO,aAAa,CAAC;CAkBvC,MAAM,WAAW,qBAhBC,aACf,kBAA8B;AAC7B,SAAO,MAAM,gBAAgB;GAC3B,MAAM,OAAO,aAAa;GAC1B,MAAM,UAAU,UAAU;AAG1B,OAAI,KAAK,UAAU,QAAQ,SAAS,KAAK,UAAU,QAAQ,OAAO;AAChE,cAAU,UAAU;AACpB,mBAAe;;IAEjB;IAEJ,CAAC,OAAO,YAAY,CACrB,QAIO,UAAU,eACV,UAAU,QACjB;CAED,MAAM,MAAM,aACT,UAAgB;EAGf,MAAM,UAAsB,GAAG,QAAQ,OAAO;AAC7C,QAA4D,IAAI,QAAQ;IAE3E,CAAC,OAAO,MAAM,CACf;AAED,QAAO;EACL,OAAO,SAAS;EAChB,OAAO,SAAS;EAChB;EACD"}

package/dist/react/use-subscribe-only.cjs

@@ -10,18 +10,19 @@ function useSubscribeOnly(target) {
 	const ref = (0, react.useRef)(null);
 	if (!ref.current || ref.current.target !== target) {
 		const version = { current: ref.current?.version ?? 0 };
-		ref.current = {
+		const entry = {
 			target,
 			version: version.current,
 			subscribe: (onStoreChange) => {
 				return target.subscribe(() => {
 					version.current++;
-					ref.current.version = version.current;
+					entry.version = version.current;
 					onStoreChange();
 				});
 			},
 			getSnapshot: () => version.current
 		};
+		ref.current = entry;
 	}
 	(0, react.useSyncExternalStore)(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);
 }

package/dist/react/use-subscribe-only.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-subscribe-only.cjs","names":[],"sources":["../../src/react/use-subscribe-only.ts"],"sourcesContent":["import { useSyncExternalStore, useRef } from 'react';\n\ninterface SubscribeOnlyRef {\n  target: { subscribe(cb: () => void): () => void };\n  version: number;\n  subscribe: (onStoreChange: () => void) => () => void;\n  getSnapshot: () => number;\n}\n\nconst SERVER_SNAPSHOT = () => 0;\n\n/**\n * Subscribe to a notification-only object (has subscribe() but no state).\n * Triggers React re-renders via version counter when the target notifies.\n * @internal\n */\nexport function useSubscribeOnly(\n  target: { subscribe(cb: () => void): () => void },\n): void {\n  const ref = useRef<SubscribeOnlyRef | null>(null);\n\n  if (!ref.current || ref.current.target !== target) {\n    const version = { current: ref.current?.version ?? 0 };\n    ref.current = {\n      target,\n      version: version.current,\n      subscribe: (onStoreChange: () => void) => {\n        return target.subscribe(() => {\n          version.current++;\n          ref.current!.version = version.current;\n          onStoreChange();\n        });\n      },\n      getSnapshot: () => version.current,\n    };\n  }\n\n  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);\n}\n"],"mappings":";;AASA,IAAM,wBAAwB;;;;;;AAO9B,SAAgB,iBACd,QACM;CACN,MAAM,OAAA,GAAA,MAAA,QAAsC,KAAK;AAEjD,KAAI,CAAC,IAAI,WAAW,IAAI,QAAQ,WAAW,QAAQ;EACjD,MAAM,UAAU,EAAE,SAAS,IAAI,SAAS,WAAW,GAAG;AACtD,MAAI,UAAU;GACZ;GACA,SAAS,QAAQ;GACjB,YAAY,kBAA8B;AACxC,WAAO,OAAO,gBAAgB;AAC5B,aAAQ;AACR,SAAI,QAAS,UAAU,QAAQ;AAC/B,oBAAe;MACf;;GAEJ,mBAAmB,QAAQ;GAC5B;;AAGH,EAAA,GAAA,MAAA,sBAAqB,IAAI,QAAQ,WAAW,IAAI,QAAQ,aAAa,gBAAgB"}
+{"version":3,"file":"use-subscribe-only.cjs","names":[],"sources":["../../src/react/use-subscribe-only.ts"],"sourcesContent":["import { useSyncExternalStore, useRef } from 'react';\n\ninterface SubscribeOnlyRef {\n  target: { subscribe(cb: () => void): () => void };\n  version: number;\n  subscribe: (onStoreChange: () => void) => () => void;\n  getSnapshot: () => number;\n}\n\nconst SERVER_SNAPSHOT = () => 0;\n\n/**\n * Subscribe to a notification-only object (has subscribe() but no state).\n * Triggers React re-renders via version counter when the target notifies.\n * @internal\n */\nexport function useSubscribeOnly(\n  target: { subscribe(cb: () => void): () => void },\n): void {\n  const ref = useRef<SubscribeOnlyRef | null>(null);\n\n  if (!ref.current || ref.current.target !== target) {\n    const version = { current: ref.current?.version ?? 0 };\n    const entry: SubscribeOnlyRef = {\n      target,\n      version: version.current,\n      subscribe: (onStoreChange: () => void) => {\n        return target.subscribe(() => {\n          version.current++;\n          entry.version = version.current;\n          onStoreChange();\n        });\n      },\n      getSnapshot: () => version.current,\n    };\n    ref.current = entry;\n  }\n\n  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);\n}\n"],"mappings":";;AASA,IAAM,wBAAwB;;;;;;AAO9B,SAAgB,iBACd,QACM;CACN,MAAM,OAAA,GAAA,MAAA,QAAsC,KAAK;AAEjD,KAAI,CAAC,IAAI,WAAW,IAAI,QAAQ,WAAW,QAAQ;EACjD,MAAM,UAAU,EAAE,SAAS,IAAI,SAAS,WAAW,GAAG;EACtD,MAAM,QAA0B;GAC9B;GACA,SAAS,QAAQ;GACjB,YAAY,kBAA8B;AACxC,WAAO,OAAO,gBAAgB;AAC5B,aAAQ;AACR,WAAM,UAAU,QAAQ;AACxB,oBAAe;MACf;;GAEJ,mBAAmB,QAAQ;GAC5B;AACD,MAAI,UAAU;;AAGhB,EAAA,GAAA,MAAA,sBAAqB,IAAI,QAAQ,WAAW,IAAI,QAAQ,aAAa,gBAAgB"}

package/dist/react/use-subscribe-only.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-subscribe-only.d.ts","sourceRoot":"","sources":["../../src/react/use-subscribe-only.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAAE,GAChD,IAAI,CAoBN"}
+{"version":3,"file":"use-subscribe-only.d.ts","sourceRoot":"","sources":["../../src/react/use-subscribe-only.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAAE,GAChD,IAAI,CAqBN"}

package/dist/react/use-subscribe-only.js

@@ -10,18 +10,19 @@ function useSubscribeOnly(target) {
 	const ref = useRef(null);
 	if (!ref.current || ref.current.target !== target) {
 		const version = { current: ref.current?.version ?? 0 };
-		ref.current = {
+		const entry = {
 			target,
 			version: version.current,
 			subscribe: (onStoreChange) => {
 				return target.subscribe(() => {
 					version.current++;
-					ref.current.version = version.current;
+					entry.version = version.current;
 					onStoreChange();
 				});
 			},
 			getSnapshot: () => version.current
 		};
+		ref.current = entry;
 	}
 	useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);
 }

package/dist/react/use-subscribe-only.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-subscribe-only.js","names":[],"sources":["../../src/react/use-subscribe-only.ts"],"sourcesContent":["import { useSyncExternalStore, useRef } from 'react';\n\ninterface SubscribeOnlyRef {\n  target: { subscribe(cb: () => void): () => void };\n  version: number;\n  subscribe: (onStoreChange: () => void) => () => void;\n  getSnapshot: () => number;\n}\n\nconst SERVER_SNAPSHOT = () => 0;\n\n/**\n * Subscribe to a notification-only object (has subscribe() but no state).\n * Triggers React re-renders via version counter when the target notifies.\n * @internal\n */\nexport function useSubscribeOnly(\n  target: { subscribe(cb: () => void): () => void },\n): void {\n  const ref = useRef<SubscribeOnlyRef | null>(null);\n\n  if (!ref.current || ref.current.target !== target) {\n    const version = { current: ref.current?.version ?? 0 };\n    ref.current = {\n      target,\n      version: version.current,\n      subscribe: (onStoreChange: () => void) => {\n        return target.subscribe(() => {\n          version.current++;\n          ref.current!.version = version.current;\n          onStoreChange();\n        });\n      },\n      getSnapshot: () => version.current,\n    };\n  }\n\n  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);\n}\n"],"mappings":";;AASA,IAAM,wBAAwB;;;;;;AAO9B,SAAgB,iBACd,QACM;CACN,MAAM,MAAM,OAAgC,KAAK;AAEjD,KAAI,CAAC,IAAI,WAAW,IAAI,QAAQ,WAAW,QAAQ;EACjD,MAAM,UAAU,EAAE,SAAS,IAAI,SAAS,WAAW,GAAG;AACtD,MAAI,UAAU;GACZ;GACA,SAAS,QAAQ;GACjB,YAAY,kBAA8B;AACxC,WAAO,OAAO,gBAAgB;AAC5B,aAAQ;AACR,SAAI,QAAS,UAAU,QAAQ;AAC/B,oBAAe;MACf;;GAEJ,mBAAmB,QAAQ;GAC5B;;AAGH,sBAAqB,IAAI,QAAQ,WAAW,IAAI,QAAQ,aAAa,gBAAgB"}
+{"version":3,"file":"use-subscribe-only.js","names":[],"sources":["../../src/react/use-subscribe-only.ts"],"sourcesContent":["import { useSyncExternalStore, useRef } from 'react';\n\ninterface SubscribeOnlyRef {\n  target: { subscribe(cb: () => void): () => void };\n  version: number;\n  subscribe: (onStoreChange: () => void) => () => void;\n  getSnapshot: () => number;\n}\n\nconst SERVER_SNAPSHOT = () => 0;\n\n/**\n * Subscribe to a notification-only object (has subscribe() but no state).\n * Triggers React re-renders via version counter when the target notifies.\n * @internal\n */\nexport function useSubscribeOnly(\n  target: { subscribe(cb: () => void): () => void },\n): void {\n  const ref = useRef<SubscribeOnlyRef | null>(null);\n\n  if (!ref.current || ref.current.target !== target) {\n    const version = { current: ref.current?.version ?? 0 };\n    const entry: SubscribeOnlyRef = {\n      target,\n      version: version.current,\n      subscribe: (onStoreChange: () => void) => {\n        return target.subscribe(() => {\n          version.current++;\n          entry.version = version.current;\n          onStoreChange();\n        });\n      },\n      getSnapshot: () => version.current,\n    };\n    ref.current = entry;\n  }\n\n  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);\n}\n"],"mappings":";;AASA,IAAM,wBAAwB;;;;;;AAO9B,SAAgB,iBACd,QACM;CACN,MAAM,MAAM,OAAgC,KAAK;AAEjD,KAAI,CAAC,IAAI,WAAW,IAAI,QAAQ,WAAW,QAAQ;EACjD,MAAM,UAAU,EAAE,SAAS,IAAI,SAAS,WAAW,GAAG;EACtD,MAAM,QAA0B;GAC9B;GACA,SAAS,QAAQ;GACjB,YAAY,kBAA8B;AACxC,WAAO,OAAO,gBAAgB;AAC5B,aAAQ;AACR,WAAM,UAAU,QAAQ;AACxB,oBAAe;MACf;;GAEJ,mBAAmB,QAAQ;GAC5B;AACD,MAAI,UAAU;;AAGhB,sBAAqB,IAAI,QAAQ,WAAW,IAAI,QAAQ,aAAa,gBAAgB"}

package/examples/react/AuthExample/src/components/AdminPage.tsx

@@ -3,6 +3,8 @@ import { AuthViewModel } from '../viewmodels/AuthViewModel';
 
 export function AdminPage() {
   const [state, vm] = useSingleton(AuthViewModel);
+  const { user } = state;
+  if (!user) return null; // AuthGuard renders this page only when signed in
 
   // Role check is done inside the page, not via a route wrapper.
   // This keeps routing simple and the access-denied message inline.
@@ -13,7 +15,7 @@ export function AdminPage() {
           <h2>Access Denied</h2>
           <p>
             You are signed in as <strong>{vm.displayName}</strong> with
-            the <span className={`badge badge-${state.user!.role}`}>{state.user!.role}</span> role.
+            the <span className={`badge badge-${user.role}`}>{user.role}</span> role.
           </p>
           <p>This page requires the <span className="badge badge-admin">admin</span> role.</p>
         </div>

package/examples/react/AuthExample/src/components/DashboardPage.tsx

@@ -3,6 +3,8 @@ import { AuthViewModel } from '../viewmodels/AuthViewModel';
 
 export function DashboardPage() {
   const [state, vm] = useSingleton(AuthViewModel);
+  const { user } = state;
+  if (!user) return null; // AuthGuard renders this page only when signed in
 
   return (
     <div className="page-content">
@@ -11,8 +13,8 @@ export function DashboardPage() {
       <div className="card" style={{ marginBottom: '1.5rem' }}>
         <h2 style={{ marginBottom: '0.5rem' }}>Welcome, {vm.displayName}!</h2>
         <p style={{ color: 'var(--color-text-secondary)' }}>
-          You are signed in as <strong>{state.user!.email}</strong> with
-          the <span className={`badge badge-${state.user!.role}`}>{state.user!.role}</span> role.
+          You are signed in as <strong>{user.email}</strong> with
+          the <span className={`badge badge-${user.role}`}>{user.role}</span> role.
         </p>
       </div>
 

package/examples/react/AuthExample/src/components/ProfilePage.tsx

@@ -3,7 +3,8 @@ import { AuthViewModel } from '../viewmodels/AuthViewModel';
 
 export function ProfilePage() {
   const [state, vm] = useSingleton(AuthViewModel);
-  const user = state.user!;
+  const { user } = state;
+  if (!user) return null; // AuthGuard renders this page only when signed in
 
   return (
     <div className="page-content">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvc-kit",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "Zero-magic, class-based reactive ViewModel library",
   "type": "module",
   "main": "./dist/mvc-kit.cjs",

package/src/Model.md

@@ -386,11 +386,22 @@ The returned `FieldHandle` provides:
 
 ## Model Inside a ViewModel
 
-The typical pattern for a form page: the ViewModel handles async operations and coordination, the Model handles editing state.
+The typical pattern for a form: the ViewModel handles async operations and coordination, the Model handles editing state. There are two shapes, and the right choice depends on whether the form's initial data is already in hand.
+
+| If the initial data is... | Shape |
+|---|---|
+| **Available at construction** (create modal, edit modal taking an entity prop) | Create the Model in the **constructor** as `readonly`. Non-nullable, no guard. |
+| **Fetched by ID** after mount (edit page that loads from the server) | Declare it `\| null = null` and create it in `onInit()`. Component must guard. |
+
+> **Never** write `public model!: FormModel`. The `!` definite-assignment assertion lies to TypeScript about runtime state — first render runs before `onInit`, so `vm.model` is `undefined`, and `useField` / `useModel` crash with "Cannot read properties of undefined."
+
+### Shape 1 — Data available at construction
+
+The ViewModel receives everything it needs via `useLocal`'s initial state. Create the Model in the constructor so it exists from the first render onward.
 
 ```typescript
 interface EditState {
-  draft: UserState | null;
+  existing: UserState | null;
 }
 
 interface EditEvents {
@@ -398,7 +409,47 @@ interface EditEvents {
 }
 
 class EditUserViewModel extends ViewModel<EditState, EditEvents> {
-  public model!: UserFormModel;
+  // `readonly` refers to the *reference* — the model's state still changes via set().
+  public readonly model: UserFormModel;
+  private service = singleton(UserService);
+
+  constructor(initialState: EditState) {
+    super(initialState);
+    this.model = new UserFormModel(initialState.existing ?? INITIAL_FORM_STATE);
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    const result = await this.service.save(this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: result.id });
+  }
+
+  protected onDispose() {
+    this.model.dispose();
+  }
+}
+```
+
+```tsx
+function EditUserModal({ existing, onClose }: Props) {
+  const [, vm] = useLocal(EditUserViewModel, { existing });
+  const { loading: saving } = vm.async.save;
+
+  useEvent(vm, 'saved', onClose);
+
+  // No guard — vm.model is non-null from the first render.
+  return <EditUserForm model={vm.model} onSave={vm.save} saving={saving} />;
+}
+```
+
+### Shape 2 — Data fetched by ID
+
+Only an ID is known at construction; the entity is loaded in `onInit()`. The Model is nullable until the fetch resolves.
+
+```typescript
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model: UserFormModel | null = null;
   private service = singleton(UserService);
 
   protected async onInit() {
@@ -408,7 +459,7 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
   }
 
   async save() {
-    if (!this.model.valid) return;
+    if (!this.model || !this.model.valid) return;
     await this.service.update(this.userId, this.model.state, this.disposeSignal);
     this.model.commit();
     this.emit('saved', { id: this.userId });
@@ -420,8 +471,6 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
 }
 ```
 
-The component:
-
 ```tsx
 function EditUserPage() {
   const [state, vm] = useLocal(EditUserViewModel, { draft: null });

package/src/Service.md

@@ -92,7 +92,10 @@ class ConfigService extends Service {
   }
 
   getConfig(): AppConfig {
-    return this.config!;
+    if (!this.config) {
+      throw new Error('ConfigService not initialized — await init() before getConfig()');
+    }
+    return this.config;
   }
 }
 

package/src/react/components/DataTable.tsx

@@ -153,13 +153,9 @@ export function DataTable<T>({
   // ── Resolve props ──
   const resolvedSelection = selection ? resolveSelectionProp(selection) : undefined;
 
-  let resolvedSorts: readonly SortDescriptor[] | undefined;
-  let resolvedOnSort: ((key: string) => void) | undefined;
-  if (sort) {
-    const resolved = resolveSortProp(sort, onSort);
-    resolvedSorts = resolved.sorts;
-    resolvedOnSort = resolved.onSort;
-  }
+  const resolvedSort = sort ? resolveSortProp(sort, onSort) : undefined;
+  const resolvedSorts = resolvedSort?.sorts;
+  const resolvedOnSort = resolvedSort?.onSort;
 
   let displayItems = items;
   let paginationInfo: PaginationInfo | undefined;
@@ -171,8 +167,8 @@ export function DataTable<T>({
 
   // Selection: check indeterminate state
   const allKeys = resolvedSelection ? displayItems.map(item => keyOf(item)) : [];
-  const allSelected = resolvedSelection && allKeys.length > 0 && allKeys.every(k => resolvedSelection!.selected.has(k));
-  const someSelected = resolvedSelection && allKeys.some(k => resolvedSelection!.selected.has(k));
+  const allSelected = !!resolvedSelection && allKeys.length > 0 && allKeys.every(k => resolvedSelection.selected.has(k));
+  const someSelected = !!resolvedSelection && allKeys.some(k => resolvedSelection.selected.has(k));
 
   return (
     <div data-component="data-table" className={className}>
@@ -187,7 +183,7 @@ export function DataTable<T>({
                   ref={(el) => {
                     if (el) el.indeterminate = !!someSelected && !allSelected;
                   }}
-                  onChange={() => resolvedSelection!.onToggleAll(allKeys)}
+                  onChange={() => resolvedSelection.onToggleAll(allKeys)}
                   aria-label="Select all"
                 />
               </th>
@@ -208,13 +204,13 @@ export function DataTable<T>({
                   aria-sort={isSortable ? getAriaSortValue(col.key, resolvedSorts) : undefined}
                 >
                   {isSortable ? (
-                    <button type="button" onClick={() => resolvedOnSort!(col.key)}>
+                    <button type="button" onClick={() => resolvedOnSort(col.key)}>
                       {col.header}
                       {renderSortIndicator?.({
                         active: isActive,
                         direction: sortDesc?.direction ?? 'asc',
                         index: sortIndex,
-                        onToggle: () => resolvedOnSort!(col.key),
+                        onToggle: () => resolvedOnSort(col.key),
                       })}
                     </button>
                   ) : (
@@ -237,7 +233,7 @@ export function DataTable<T>({
                     <input
                       type="checkbox"
                       checked={!!isSelected}
-                      onChange={() => resolvedSelection!.onToggle(key)}
+                      onChange={() => resolvedSelection.onToggle(key)}
                       aria-label={`Select row ${key}`}
                     />
                   </td>

package/src/react/use-instance.ts

@@ -1,6 +1,8 @@
 import { useSyncExternalStore, useRef } from 'react';
 import type { Subscribable } from '../types';
 
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
 function hasAsyncSubscription(obj: unknown): obj is { subscribeAsync(cb: () => void): () => void } {
   return (
     obj !== null &&
@@ -27,24 +29,32 @@ interface InstanceRef<S> {
  * trigger React re-renders.
  */
 export function useInstance<S>(subscribable: Subscribable<S>): S {
+  if (__DEV__ && !subscribable) {
+    throw new Error(
+      'useInstance: received an undefined/null subscribable. ' +
+      'Make sure the instance is created synchronously (in a parent ViewModel\'s constructor or as a singleton) ' +
+      'before the component that calls useInstance renders. ' +
+      'If it\'s created in onInit(), guard the component with `if (!vm.child) return <Spinner />` first.',
+    );
+  }
   const ref = useRef<InstanceRef<S> | null>(null);
 
   if (!ref.current || ref.current.subscribable !== subscribable) {
     const version = { current: ref.current?.version ?? 0 };
-    ref.current = {
+    const entry: InstanceRef<S> = {
       version: version.current,
       subscribable,
       subscribe: (onStoreChange: () => void) => {
         const unsub1 = subscribable.subscribe(() => {
           version.current++;
-          ref.current!.version = version.current;
+          entry.version = version.current;
           onStoreChange();
         });
         let unsub2: (() => void) | undefined;
         if (hasAsyncSubscription(subscribable)) {
           unsub2 = subscribable.subscribeAsync(() => {
             version.current++;
-            ref.current!.version = version.current;
+            entry.version = version.current;
             onStoreChange();
           });
         }
@@ -52,6 +62,7 @@ export function useInstance<S>(subscribable: Subscribable<S>): S {
       },
       getSnapshot: () => version.current,
     };
+    ref.current = entry;
   }
 
   useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);

package/src/react/use-local.ts

@@ -133,7 +133,8 @@ export function useLocal<T extends Disposable, S = StateOf<T>>(
 
   // ── Effect: init + deferred cleanup ──
   useEffect(() => {
-    const instance = instanceRef.current!; // capture for cleanup closure
+    const instance = instanceRef.current;
+    if (!instance) return;
     mountedRef.current = true;
     if (isInitializable(instance)) {
       instance.init();