@jfdevelops/react-multi-step-form 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/hooks/use-multi-step-form-data.cjs

@@ -0,0 +1,41 @@
+let __jfdevelops_multi_step_form_core = require("@jfdevelops/multi-step-form-core");
+let use_sync_external_store_shim_with_selector = require("use-sync-external-store/shim/with-selector");
+
+//#region src/hooks/use-multi-step-form-data.ts
+function throwIfInvalidStepNumber(schema, targetStep) {
+	(0, __jfdevelops_multi_step_form_core.invariant)(typeof targetStep === "string", `The target step must be a string, was ${typeof targetStep}`);
+	const { as, isValidStepNumber } = schema.stepSchema.steps;
+	const formattedStepNumbersList = new Intl.ListFormat("en", {
+		type: "disjunction",
+		style: "long"
+	}).format(as("array.string.untyped"));
+	(0, __jfdevelops_multi_step_form_core.invariant)(__jfdevelops_multi_step_form_core.VALIDATED_STEP_REGEX.test(targetStep), `The target step must match the following format: "step{number}". Available steps are ${formattedStepNumbersList}`);
+	const stepNumber = Number.parseInt(targetStep.replace("step", ""));
+	(0, __jfdevelops_multi_step_form_core.invariant)(isValidStepNumber(stepNumber), `The step number "${stepNumber}" is not a valid step number. Valid step numbers include ${formattedStepNumbersList}`, TypeError);
+	return stepNumber;
+}
+function createMultiStepFormDataHook(schema) {
+	function useMultiStepFormData$1(optionsOrSelector) {
+		return (0, use_sync_external_store_shim_with_selector.useSyncExternalStoreWithSelector)(schema.subscribe, () => schema.getSnapshot(), () => schema.getSnapshot(), (snapshot) => {
+			if (typeof optionsOrSelector === "object") {
+				const stepNumber = throwIfInvalidStepNumber(snapshot, optionsOrSelector.targetStep);
+				return snapshot.stepSchema.get({ step: stepNumber }).data;
+			}
+			if (typeof optionsOrSelector === "function") return optionsOrSelector(snapshot);
+			return snapshot;
+		});
+	}
+	return useMultiStepFormData$1;
+}
+function useMultiStepFormData(schema, optionsOrSelector) {
+	const hook = createMultiStepFormDataHook(schema);
+	if (typeof optionsOrSelector === "object") return hook(optionsOrSelector);
+	if (typeof optionsOrSelector === "function") return hook(optionsOrSelector);
+	return hook();
+}
+
+//#endregion
+exports.createMultiStepFormDataHook = createMultiStepFormDataHook;
+exports.throwIfInvalidStepNumber = throwIfInvalidStepNumber;
+exports.useMultiStepFormData = useMultiStepFormData;
+//# sourceMappingURL=use-multi-step-form-data.cjs.map

package/dist/hooks/use-multi-step-form-data.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-multi-step-form-data.cjs","names":["VALIDATED_STEP_REGEX","useMultiStepFormData"],"sources":["../../src/hooks/use-multi-step-form-data.ts"],"sourcesContent":["import type { AnyMultiStepFormSchema, MultiStepFormSchema } from '@/schema';\nimport {\n  invariant,\n  VALIDATED_STEP_REGEX,\n} from '@jfdevelops/multi-step-form-core';\nimport { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';\n\nexport type UseMultiStepFormDataOptions<\n  TSchema extends AnyMultiStepFormSchema,\n  TTarget extends keyof MultiStepFormSchema.resolvedStep<TSchema> = keyof MultiStepFormSchema.resolvedStep<TSchema>\n> = {\n  targetStep: TTarget;\n};\nexport type UseMultiStepFormData<\n  // step extends Step<casing>,\n  // casing extends CasingType,\n  // storageKey extends string,\n  // resolvedStep extends ResolvedStep<step, casing>,\n  // schema extends MultiStepFormSchema<\n  //   step,\n  //   casing,\n  //   storageKey\n  // > = MultiStepFormSchema<step, casing, storageKey>,\n  TSchema extends AnyMultiStepFormSchema,\n  TResolvedStep extends MultiStepFormSchema.resolvedStep<TSchema> = MultiStepFormSchema.resolvedStep<TSchema>\n> = {\n  /**\n   * Returns the entire {@linkcode MultiStepFormSchema instance}.\n   */\n  (): TSchema;\n  /**\n   * Returns the data for the target step.\n   * @param stepNumber The step number to return.\n   * @throws {TypeError} If `options.stepNumber` is invalid.\n   */\n  <targetStep extends keyof TResolvedStep>(\n    options: UseMultiStepFormDataOptions<TSchema, targetStep>\n  ): MultiStepFormSchema.getData<TSchema, targetStep>;\n  /**\n   * Returns the specified data from the {@linkcode MultiStepFormSchema} instance via the callback's return.\n   */\n  <data>(selector: (schema: TSchema) => data): data;\n};\n\nexport function throwIfInvalidStepNumber<\n  // step extends Step<casing>,\n  // casing extends CasingType = DefaultCasing,\n  // storageKey extends string = DefaultStorageKey,\n  // resolvedStep extends ResolvedStep<step, casing> = ResolvedStep<step, casing>,\n  // stepNumbers extends StepNumbers<resolvedStep> = StepNumbers<resolvedStep>\n  schema extends AnyMultiStepFormSchema\n>(schema: schema, targetStep: unknown) {\n  invariant(\n    typeof targetStep === 'string',\n    `The target step must be a string, was ${typeof targetStep}`\n  );\n\n  const { as, isValidStepNumber } = schema.stepSchema.steps;\n  const formatter = new Intl.ListFormat('en', {\n    type: 'disjunction',\n    style: 'long',\n  });\n  const formattedStepNumbersList = formatter.format(as('array.string.untyped'));\n\n  invariant(\n    VALIDATED_STEP_REGEX.test(targetStep),\n    `The target step must match the following format: \"step{number}\". Available steps are ${formattedStepNumbersList}`\n  );\n\n  const stepNumber = Number.parseInt(targetStep.replace('step', ''));\n\n  invariant(\n    isValidStepNumber(stepNumber),\n    `The step number \"${stepNumber}\" is not a valid step number. Valid step numbers include ${formattedStepNumbersList}`,\n    TypeError\n  );\n\n  return stepNumber as MultiStepFormSchema.stepNumbers<schema>;\n}\n\nexport function createMultiStepFormDataHook<\n  // step extends Step<casing>,\n  // casing extends CasingType = DefaultCasing,\n  // storageKey extends string = DefaultStorageKey,\n  // resolvedStep extends ResolvedStep<step, casing> = ResolvedStep<step, casing>,\n  // stepNumbers extends StepNumbers<resolvedStep> = StepNumbers<resolvedStep>\n  schema extends AnyMultiStepFormSchema\n>(schema: schema): UseMultiStepFormData<schema> {\n  function useMultiStepFormData(\n    optionsOrSelector?:\n      | UseMultiStepFormDataOptions<schema>\n      | ((data: schema) => unknown)\n  ) {\n    return useSyncExternalStoreWithSelector(\n      schema.subscribe,\n      () => schema.getSnapshot(),\n      () => schema.getSnapshot(),\n      (snapshot) => {\n        if (typeof optionsOrSelector === 'object') {\n          // @ts-ignore Type instantiation is excessively deep and possibly infinite\n          const stepNumber = throwIfInvalidStepNumber(\n            snapshot,\n            optionsOrSelector.targetStep\n          );\n\n          return snapshot.stepSchema.get({ step: stepNumber as never }).data;\n        }\n\n        if (typeof optionsOrSelector === 'function') {\n          return optionsOrSelector(snapshot);\n        }\n\n        return snapshot;\n      }\n    );\n  }\n\n  return useMultiStepFormData as any;\n}\n\nfunction useMultiStepFormData<schema extends AnyMultiStepFormSchema>(\n  schema: schema\n): schema;\nfunction useMultiStepFormData<\n  schema extends AnyMultiStepFormSchema,\n  targetStep extends keyof MultiStepFormSchema.resolvedStep<schema>\n>(\n  schema: schema,\n  options: UseMultiStepFormDataOptions<schema, targetStep>\n): MultiStepFormSchema.getData<schema, targetStep>;\nfunction useMultiStepFormData<schema extends AnyMultiStepFormSchema, data>(\n  schema: schema,\n  selector: (schema: schema) => data\n): data;\nfunction useMultiStepFormData<\n  // step extends Step<casing>,\n  // casing extends CasingType = DefaultCasing,\n  // storageKey extends string = DefaultStorageKey,\n  // resolvedStep extends ResolvedStep<step, casing> = ResolvedStep<step, casing>,\n  // stepNumbers extends StepNumbers<resolvedStep> = StepNumbers<resolvedStep>\n  schema extends AnyMultiStepFormSchema\n>(\n  schema: schema,\n  optionsOrSelector?:\n    | UseMultiStepFormDataOptions<schema>\n    | ((data: schema) => unknown)\n) {\n  const hook = createMultiStepFormDataHook(schema);\n\n  if (typeof optionsOrSelector === 'object') {\n    return hook(optionsOrSelector);\n  }\n\n  if (typeof optionsOrSelector === 'function') {\n    return hook(optionsOrSelector);\n  }\n\n  return hook();\n}\n\nexport { useMultiStepFormData };\n"],"mappings":";;;;AA4CA,SAAgB,yBAOd,QAAgB,YAAqB;AACrC,kDACE,OAAO,eAAe,UACtB,yCAAyC,OAAO,aACjD;CAED,MAAM,EAAE,IAAI,sBAAsB,OAAO,WAAW;CAKpD,MAAM,2BAJY,IAAI,KAAK,WAAW,MAAM;EAC1C,MAAM;EACN,OAAO;EACR,CAAC,CACyC,OAAO,GAAG,uBAAuB,CAAC;AAE7E,kDACEA,uDAAqB,KAAK,WAAW,EACrC,wFAAwF,2BACzF;CAED,MAAM,aAAa,OAAO,SAAS,WAAW,QAAQ,QAAQ,GAAG,CAAC;AAElE,kDACE,kBAAkB,WAAW,EAC7B,oBAAoB,WAAW,2DAA2D,4BAC1F,UACD;AAED,QAAO;;AAGT,SAAgB,4BAOd,QAA8C;CAC9C,SAASC,uBACP,mBAGA;AACA,0FACE,OAAO,iBACD,OAAO,aAAa,QACpB,OAAO,aAAa,GACzB,aAAa;AACZ,OAAI,OAAO,sBAAsB,UAAU;IAEzC,MAAM,aAAa,yBACjB,UACA,kBAAkB,WACnB;AAED,WAAO,SAAS,WAAW,IAAI,EAAE,MAAM,YAAqB,CAAC,CAAC;;AAGhE,OAAI,OAAO,sBAAsB,WAC/B,QAAO,kBAAkB,SAAS;AAGpC,UAAO;IAEV;;AAGH,QAAOA;;AAiBT,SAAS,qBAQP,QACA,mBAGA;CACA,MAAM,OAAO,4BAA4B,OAAO;AAEhD,KAAI,OAAO,sBAAsB,SAC/B,QAAO,KAAK,kBAAkB;AAGhC,KAAI,OAAO,sBAAsB,WAC/B,QAAO,KAAK,kBAAkB;AAGhC,QAAO,MAAM"}

package/dist/hooks/use-multi-step-form-data.d.cts

@@ -0,0 +1,28 @@
+import { AnyMultiStepFormSchema, MultiStepFormSchema } from "../schema.cjs";
+
+//#region src/hooks/use-multi-step-form-data.d.ts
+type UseMultiStepFormDataOptions<TSchema extends AnyMultiStepFormSchema, TTarget extends keyof MultiStepFormSchema.resolvedStep<TSchema> = keyof MultiStepFormSchema.resolvedStep<TSchema>> = {
+  targetStep: TTarget;
+};
+type UseMultiStepFormData<TSchema extends AnyMultiStepFormSchema, TResolvedStep extends MultiStepFormSchema.resolvedStep<TSchema> = MultiStepFormSchema.resolvedStep<TSchema>> = {
+  /**
+   * Returns the entire {@linkcode MultiStepFormSchema instance}.
+   */
+  (): TSchema;
+  /**
+   * Returns the data for the target step.
+   * @param stepNumber The step number to return.
+   * @throws {TypeError} If `options.stepNumber` is invalid.
+   */
+  <targetStep extends keyof TResolvedStep>(options: UseMultiStepFormDataOptions<TSchema, targetStep>): MultiStepFormSchema.getData<TSchema, targetStep>;
+  /**
+   * Returns the specified data from the {@linkcode MultiStepFormSchema} instance via the callback's return.
+   */
+  <data>(selector: (schema: TSchema) => data): data;
+};
+declare function useMultiStepFormData<schema extends AnyMultiStepFormSchema>(schema: schema): schema;
+declare function useMultiStepFormData<schema extends AnyMultiStepFormSchema, targetStep extends keyof MultiStepFormSchema.resolvedStep<schema>>(schema: schema, options: UseMultiStepFormDataOptions<schema, targetStep>): MultiStepFormSchema.getData<schema, targetStep>;
+declare function useMultiStepFormData<schema extends AnyMultiStepFormSchema, data>(schema: schema, selector: (schema: schema) => data): data;
+//#endregion
+export { UseMultiStepFormData, useMultiStepFormData };
+//# sourceMappingURL=use-multi-step-form-data.d.cts.map

package/dist/hooks/use-multi-step-form-data.d.mts

@@ -0,0 +1,28 @@
+import { AnyMultiStepFormSchema, MultiStepFormSchema } from "../schema.mjs";
+
+//#region src/hooks/use-multi-step-form-data.d.ts
+type UseMultiStepFormDataOptions<TSchema extends AnyMultiStepFormSchema, TTarget extends keyof MultiStepFormSchema.resolvedStep<TSchema> = keyof MultiStepFormSchema.resolvedStep<TSchema>> = {
+  targetStep: TTarget;
+};
+type UseMultiStepFormData<TSchema extends AnyMultiStepFormSchema, TResolvedStep extends MultiStepFormSchema.resolvedStep<TSchema> = MultiStepFormSchema.resolvedStep<TSchema>> = {
+  /**
+   * Returns the entire {@linkcode MultiStepFormSchema instance}.
+   */
+  (): TSchema;
+  /**
+   * Returns the data for the target step.
+   * @param stepNumber The step number to return.
+   * @throws {TypeError} If `options.stepNumber` is invalid.
+   */
+  <targetStep extends keyof TResolvedStep>(options: UseMultiStepFormDataOptions<TSchema, targetStep>): MultiStepFormSchema.getData<TSchema, targetStep>;
+  /**
+   * Returns the specified data from the {@linkcode MultiStepFormSchema} instance via the callback's return.
+   */
+  <data>(selector: (schema: TSchema) => data): data;
+};
+declare function useMultiStepFormData<schema extends AnyMultiStepFormSchema>(schema: schema): schema;
+declare function useMultiStepFormData<schema extends AnyMultiStepFormSchema, targetStep extends keyof MultiStepFormSchema.resolvedStep<schema>>(schema: schema, options: UseMultiStepFormDataOptions<schema, targetStep>): MultiStepFormSchema.getData<schema, targetStep>;
+declare function useMultiStepFormData<schema extends AnyMultiStepFormSchema, data>(schema: schema, selector: (schema: schema) => data): data;
+//#endregion
+export { UseMultiStepFormData, useMultiStepFormData };
+//# sourceMappingURL=use-multi-step-form-data.d.mts.map

package/dist/hooks/use-multi-step-form-data.mjs

@@ -0,0 +1,39 @@
+import { VALIDATED_STEP_REGEX, invariant } from "@jfdevelops/multi-step-form-core";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+
+//#region src/hooks/use-multi-step-form-data.ts
+function throwIfInvalidStepNumber(schema, targetStep) {
+	invariant(typeof targetStep === "string", `The target step must be a string, was ${typeof targetStep}`);
+	const { as, isValidStepNumber } = schema.stepSchema.steps;
+	const formattedStepNumbersList = new Intl.ListFormat("en", {
+		type: "disjunction",
+		style: "long"
+	}).format(as("array.string.untyped"));
+	invariant(VALIDATED_STEP_REGEX.test(targetStep), `The target step must match the following format: "step{number}". Available steps are ${formattedStepNumbersList}`);
+	const stepNumber = Number.parseInt(targetStep.replace("step", ""));
+	invariant(isValidStepNumber(stepNumber), `The step number "${stepNumber}" is not a valid step number. Valid step numbers include ${formattedStepNumbersList}`, TypeError);
+	return stepNumber;
+}
+function createMultiStepFormDataHook(schema) {
+	function useMultiStepFormData$1(optionsOrSelector) {
+		return useSyncExternalStoreWithSelector(schema.subscribe, () => schema.getSnapshot(), () => schema.getSnapshot(), (snapshot) => {
+			if (typeof optionsOrSelector === "object") {
+				const stepNumber = throwIfInvalidStepNumber(snapshot, optionsOrSelector.targetStep);
+				return snapshot.stepSchema.get({ step: stepNumber }).data;
+			}
+			if (typeof optionsOrSelector === "function") return optionsOrSelector(snapshot);
+			return snapshot;
+		});
+	}
+	return useMultiStepFormData$1;
+}
+function useMultiStepFormData(schema, optionsOrSelector) {
+	const hook = createMultiStepFormDataHook(schema);
+	if (typeof optionsOrSelector === "object") return hook(optionsOrSelector);
+	if (typeof optionsOrSelector === "function") return hook(optionsOrSelector);
+	return hook();
+}
+
+//#endregion
+export { createMultiStepFormDataHook, throwIfInvalidStepNumber, useMultiStepFormData };
+//# sourceMappingURL=use-multi-step-form-data.mjs.map

package/dist/hooks/use-multi-step-form-data.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-multi-step-form-data.mjs","names":["useMultiStepFormData"],"sources":["../../src/hooks/use-multi-step-form-data.ts"],"sourcesContent":["import type { AnyMultiStepFormSchema, MultiStepFormSchema } from '@/schema';\nimport {\n  invariant,\n  VALIDATED_STEP_REGEX,\n} from '@jfdevelops/multi-step-form-core';\nimport { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';\n\nexport type UseMultiStepFormDataOptions<\n  TSchema extends AnyMultiStepFormSchema,\n  TTarget extends keyof MultiStepFormSchema.resolvedStep<TSchema> = keyof MultiStepFormSchema.resolvedStep<TSchema>\n> = {\n  targetStep: TTarget;\n};\nexport type UseMultiStepFormData<\n  // step extends Step<casing>,\n  // casing extends CasingType,\n  // storageKey extends string,\n  // resolvedStep extends ResolvedStep<step, casing>,\n  // schema extends MultiStepFormSchema<\n  //   step,\n  //   casing,\n  //   storageKey\n  // > = MultiStepFormSchema<step, casing, storageKey>,\n  TSchema extends AnyMultiStepFormSchema,\n  TResolvedStep extends MultiStepFormSchema.resolvedStep<TSchema> = MultiStepFormSchema.resolvedStep<TSchema>\n> = {\n  /**\n   * Returns the entire {@linkcode MultiStepFormSchema instance}.\n   */\n  (): TSchema;\n  /**\n   * Returns the data for the target step.\n   * @param stepNumber The step number to return.\n   * @throws {TypeError} If `options.stepNumber` is invalid.\n   */\n  <targetStep extends keyof TResolvedStep>(\n    options: UseMultiStepFormDataOptions<TSchema, targetStep>\n  ): MultiStepFormSchema.getData<TSchema, targetStep>;\n  /**\n   * Returns the specified data from the {@linkcode MultiStepFormSchema} instance via the callback's return.\n   */\n  <data>(selector: (schema: TSchema) => data): data;\n};\n\nexport function throwIfInvalidStepNumber<\n  // step extends Step<casing>,\n  // casing extends CasingType = DefaultCasing,\n  // storageKey extends string = DefaultStorageKey,\n  // resolvedStep extends ResolvedStep<step, casing> = ResolvedStep<step, casing>,\n  // stepNumbers extends StepNumbers<resolvedStep> = StepNumbers<resolvedStep>\n  schema extends AnyMultiStepFormSchema\n>(schema: schema, targetStep: unknown) {\n  invariant(\n    typeof targetStep === 'string',\n    `The target step must be a string, was ${typeof targetStep}`\n  );\n\n  const { as, isValidStepNumber } = schema.stepSchema.steps;\n  const formatter = new Intl.ListFormat('en', {\n    type: 'disjunction',\n    style: 'long',\n  });\n  const formattedStepNumbersList = formatter.format(as('array.string.untyped'));\n\n  invariant(\n    VALIDATED_STEP_REGEX.test(targetStep),\n    `The target step must match the following format: \"step{number}\". Available steps are ${formattedStepNumbersList}`\n  );\n\n  const stepNumber = Number.parseInt(targetStep.replace('step', ''));\n\n  invariant(\n    isValidStepNumber(stepNumber),\n    `The step number \"${stepNumber}\" is not a valid step number. Valid step numbers include ${formattedStepNumbersList}`,\n    TypeError\n  );\n\n  return stepNumber as MultiStepFormSchema.stepNumbers<schema>;\n}\n\nexport function createMultiStepFormDataHook<\n  // step extends Step<casing>,\n  // casing extends CasingType = DefaultCasing,\n  // storageKey extends string = DefaultStorageKey,\n  // resolvedStep extends ResolvedStep<step, casing> = ResolvedStep<step, casing>,\n  // stepNumbers extends StepNumbers<resolvedStep> = StepNumbers<resolvedStep>\n  schema extends AnyMultiStepFormSchema\n>(schema: schema): UseMultiStepFormData<schema> {\n  function useMultiStepFormData(\n    optionsOrSelector?:\n      | UseMultiStepFormDataOptions<schema>\n      | ((data: schema) => unknown)\n  ) {\n    return useSyncExternalStoreWithSelector(\n      schema.subscribe,\n      () => schema.getSnapshot(),\n      () => schema.getSnapshot(),\n      (snapshot) => {\n        if (typeof optionsOrSelector === 'object') {\n          // @ts-ignore Type instantiation is excessively deep and possibly infinite\n          const stepNumber = throwIfInvalidStepNumber(\n            snapshot,\n            optionsOrSelector.targetStep\n          );\n\n          return snapshot.stepSchema.get({ step: stepNumber as never }).data;\n        }\n\n        if (typeof optionsOrSelector === 'function') {\n          return optionsOrSelector(snapshot);\n        }\n\n        return snapshot;\n      }\n    );\n  }\n\n  return useMultiStepFormData as any;\n}\n\nfunction useMultiStepFormData<schema extends AnyMultiStepFormSchema>(\n  schema: schema\n): schema;\nfunction useMultiStepFormData<\n  schema extends AnyMultiStepFormSchema,\n  targetStep extends keyof MultiStepFormSchema.resolvedStep<schema>\n>(\n  schema: schema,\n  options: UseMultiStepFormDataOptions<schema, targetStep>\n): MultiStepFormSchema.getData<schema, targetStep>;\nfunction useMultiStepFormData<schema extends AnyMultiStepFormSchema, data>(\n  schema: schema,\n  selector: (schema: schema) => data\n): data;\nfunction useMultiStepFormData<\n  // step extends Step<casing>,\n  // casing extends CasingType = DefaultCasing,\n  // storageKey extends string = DefaultStorageKey,\n  // resolvedStep extends ResolvedStep<step, casing> = ResolvedStep<step, casing>,\n  // stepNumbers extends StepNumbers<resolvedStep> = StepNumbers<resolvedStep>\n  schema extends AnyMultiStepFormSchema\n>(\n  schema: schema,\n  optionsOrSelector?:\n    | UseMultiStepFormDataOptions<schema>\n    | ((data: schema) => unknown)\n) {\n  const hook = createMultiStepFormDataHook(schema);\n\n  if (typeof optionsOrSelector === 'object') {\n    return hook(optionsOrSelector);\n  }\n\n  if (typeof optionsOrSelector === 'function') {\n    return hook(optionsOrSelector);\n  }\n\n  return hook();\n}\n\nexport { useMultiStepFormData };\n"],"mappings":";;;;AA4CA,SAAgB,yBAOd,QAAgB,YAAqB;AACrC,WACE,OAAO,eAAe,UACtB,yCAAyC,OAAO,aACjD;CAED,MAAM,EAAE,IAAI,sBAAsB,OAAO,WAAW;CAKpD,MAAM,2BAJY,IAAI,KAAK,WAAW,MAAM;EAC1C,MAAM;EACN,OAAO;EACR,CAAC,CACyC,OAAO,GAAG,uBAAuB,CAAC;AAE7E,WACE,qBAAqB,KAAK,WAAW,EACrC,wFAAwF,2BACzF;CAED,MAAM,aAAa,OAAO,SAAS,WAAW,QAAQ,QAAQ,GAAG,CAAC;AAElE,WACE,kBAAkB,WAAW,EAC7B,oBAAoB,WAAW,2DAA2D,4BAC1F,UACD;AAED,QAAO;;AAGT,SAAgB,4BAOd,QAA8C;CAC9C,SAASA,uBACP,mBAGA;AACA,SAAO,iCACL,OAAO,iBACD,OAAO,aAAa,QACpB,OAAO,aAAa,GACzB,aAAa;AACZ,OAAI,OAAO,sBAAsB,UAAU;IAEzC,MAAM,aAAa,yBACjB,UACA,kBAAkB,WACnB;AAED,WAAO,SAAS,WAAW,IAAI,EAAE,MAAM,YAAqB,CAAC,CAAC;;AAGhE,OAAI,OAAO,sBAAsB,WAC/B,QAAO,kBAAkB,SAAS;AAGpC,UAAO;IAEV;;AAGH,QAAOA;;AAiBT,SAAS,qBAQP,QACA,mBAGA;CACA,MAAM,OAAO,4BAA4B,OAAO;AAEhD,KAAI,OAAO,sBAAsB,SAC/B,QAAO,KAAK,kBAAkB;AAGhC,KAAI,OAAO,sBAAsB,WAC/B,QAAO,KAAK,kBAAkB;AAGhC,QAAO,MAAM"}

package/dist/hooks/use-selector.cjs

@@ -0,0 +1,64 @@
+let react = require("react");
+
+//#region src/hooks/use-selector.ts
+/**
+* Deep equality check that compares values regardless of property order.
+* Handles objects, arrays, primitives, and null/undefined.
+*/
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return a === b;
+	if (typeof a !== typeof b) return false;
+	if (typeof a !== "object") return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+		return true;
+	}
+	if (Array.isArray(a) || Array.isArray(b)) return false;
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) {
+		if (!keysB.includes(key)) return false;
+		if (!deepEqual(a[key], b[key])) return false;
+	}
+	return true;
+}
+function createUseSelector(createCtx, subscribe) {
+	return (selectorFn, logger, debugOptions) => {
+		const snapshotCacheRef = (0, react.useRef)(null);
+		const selectorRef = (0, react.useRef)(selectorFn);
+		selectorRef.current = selectorFn;
+		const getSnapshot = () => {
+			const currentCtx = createCtx();
+			const newValue = selectorRef.current(currentCtx);
+			if (snapshotCacheRef.current === null) {
+				snapshotCacheRef.current = { value: newValue };
+				logger?.info(debugOptions?.onInitialValue?.(newValue) ?? `Initial value: ${JSON.stringify(newValue)}`);
+				return newValue;
+			}
+			const isPrimitive = newValue === null || typeof newValue !== "object" && typeof newValue !== "function";
+			let hasChanged;
+			if (isPrimitive) hasChanged = !Object.is(snapshotCacheRef.current.value, newValue);
+			else {
+				const oldValue = snapshotCacheRef.current.value;
+				if (oldValue === newValue) hasChanged = false;
+				else hasChanged = !deepEqual(oldValue, newValue);
+			}
+			if (hasChanged) {
+				const oldValue = snapshotCacheRef.current.value;
+				snapshotCacheRef.current = { value: newValue };
+				logger?.info(debugOptions?.onValueChanged?.(oldValue, newValue) ?? `Value changed: ${JSON.stringify(oldValue)} -> ${JSON.stringify(newValue)}`);
+				return newValue;
+			}
+			logger?.info(debugOptions?.onValueUnchanged?.(newValue) ?? `Value unchanged: ${JSON.stringify(newValue)}`);
+			return snapshotCacheRef.current.value;
+		};
+		return (0, react.useSyncExternalStore)(subscribe, () => getSnapshot(), () => getSnapshot());
+	};
+}
+
+//#endregion
+exports.createUseSelector = createUseSelector;
+//# sourceMappingURL=use-selector.cjs.map

package/dist/hooks/use-selector.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-selector.cjs","names":["hasChanged: boolean"],"sources":["../../src/hooks/use-selector.ts"],"sourcesContent":["import type {\n  AnyResolvedStep,\n  StepNumbers,\n  HelperFnChosenSteps,\n  Expand,\n  HelperFnCtx,\n  MultiStepFormLogger,\n  MultiStepFormLoggerOptions,\n} from '@jfdevelops/multi-step-form-core';\nimport { useSyncExternalStore, useRef } from 'react';\n\n/**\n * Deep equality check that compares values regardless of property order.\n * Handles objects, arrays, primitives, and null/undefined.\n */\nfunction deepEqual(a: unknown, b: unknown): boolean {\n  // Same reference or both are the same primitive value\n  if (a === b) {\n    return true;\n  }\n\n  // Handle null/undefined\n  if (a == null || b == null) {\n    return a === b;\n  }\n\n  // Type mismatch\n  if (typeof a !== typeof b) {\n    return false;\n  }\n\n  // Both are primitives (but not equal due to first check)\n  if (typeof a !== 'object') {\n    return false;\n  }\n\n  // Both are arrays\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) {\n      return false;\n    }\n    for (let i = 0; i < a.length; i++) {\n      if (!deepEqual(a[i], b[i])) {\n        return false;\n      }\n    }\n    return true;\n  }\n\n  // One is array, other is not\n  if (Array.isArray(a) || Array.isArray(b)) {\n    return false;\n  }\n\n  // Both are objects (not arrays)\n  const keysA = Object.keys(a as Record<string, unknown>);\n  const keysB = Object.keys(b as Record<string, unknown>);\n\n  if (keysA.length !== keysB.length) {\n    return false;\n  }\n\n  // Check if all keys in A exist in B with equal values\n  for (const key of keysA) {\n    if (!keysB.includes(key)) {\n      return false;\n    }\n    if (\n      !deepEqual(\n        (a as Record<string, unknown>)[key],\n        (b as Record<string, unknown>)[key]\n      )\n    ) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\ntype PrefixOptions = {\n  /**\n   * The action to perform on the prefix.\n   *\n   * @default 'prepend'\n   */\n  action?: 'prepend' | 'append';\n  /**\n   * The value to add to the prefix.\n   */\n  value: string | ((prefix: string) => string);\n  /**\n   * The delimiter to use between the original prefix and the added prefix.\n   * @default '-'\n   * @example\n   * ```tsx\n   * <Selector debug={{ prefix: { action: 'prepend', value: 'MySelector', delimiter: '|' } }}>\n   *   {(value) => <p>First name: {value}</p>}\n   * </Selector>\n   * ```\n   */\n  delimiter?: string;\n};\n\n/**\n * Debug options for customizing logging behavior in the Selector component.\n * All options are optional - you can provide any combination of these functions\n * to customize how debug information is logged.\n */\nexport type DebugOptions<TSelected> = {\n  /**\n   * The prefix to use for the logger.\n   *\n   * If a string or function is provided, it will replace the default prefix.\n   * If you need to prepend or append to the default prefix, you can provide {@linkcode PrefixOptions}.\n   * @default 'MultiStepFormSchema-Selector'\n   *\n   * @example\n   * ```tsx\n   * <Selector debug={{ prefix: 'MySelector' }}>\n   *   {(value) => <p>First name: {value}</p>}\n   * </Selector>\n   * ```\n   *\n   */\n  prefix?: MultiStepFormLoggerOptions['prefix'] | PrefixOptions;\n  /**\n   * Called when the Selector component renders with the selected value.\n   * This is called on every render of the Selector component, regardless of\n   * whether the selected value has changed.\n   *\n   * @param selected - The current selected value from the selector function\n   */\n  onRender?: (selected: TSelected) => string;\n\n  /**\n   * Called when the Selector component renders its children.\n   * This is only called when the Selector has a children render prop.\n   */\n  onChildrenRender?: () => string;\n\n  /**\n   * Called when the initial value is set for the first time.\n   * This is called once when the selector first evaluates and caches its value.\n   *\n   * @param value - The initial selected value\n   */\n  onInitialValue?: (value: TSelected) => string;\n\n  /**\n   * Called when the selected value changes from one value to another.\n   * This is called whenever the selector detects that the value has changed\n   * (using Object.is() for primitives or deep comparison for objects/arrays).\n   *\n   * @param oldValue - The previous selected value\n   * @param newValue - The new selected value\n   */\n  onValueChanged?: (oldValue: TSelected, newValue: TSelected) => string;\n\n  /**\n   * Called when the selected value is checked but hasn't changed.\n   * This is called when the selector evaluates but determines that the value\n   * is the same as the previously cached value.\n   *\n   * @param value - The current selected value (unchanged from previous check)\n   */\n  onValueUnchanged?: (value: TSelected) => string;\n};\n\nexport type UseSelector<\n  TResolvedStep extends AnyResolvedStep,\n  TSteps extends StepNumbers<TResolvedStep>,\n  TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>\n> = ReturnType<typeof createUseSelector<TResolvedStep, TSteps, TChosenSteps>>;\nexport type SelectorFn<\n  TResolvedStep extends AnyResolvedStep,\n  TSteps extends StepNumbers<TResolvedStep>,\n  TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>,\n  TSelected\n> = (\n  ctx: Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>\n) => TSelected;\n\nexport function createUseSelector<\n  TResolvedStep extends AnyResolvedStep,\n  TSteps extends StepNumbers<TResolvedStep>,\n  TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>\n>(\n  createCtx: () => Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>,\n  subscribe: (listener: () => void) => () => void\n) {\n  return <selected>(\n    selectorFn: SelectorFn<TResolvedStep, TSteps, TChosenSteps, selected>,\n    logger?: MultiStepFormLogger,\n    debugOptions?: DebugOptions<selected>\n  ) => {\n    const snapshotCacheRef = useRef<{ value: selected } | null>(null);\n    const selectorRef = useRef(selectorFn);\n\n    // Update the selector ref on every render to ensure we always use the latest selector\n    selectorRef.current = selectorFn;\n\n    const getSnapshot = () => {\n      const currentCtx = createCtx();\n      const newValue = selectorRef.current(currentCtx);\n\n      // Cache the result to ensure stable reference\n      if (snapshotCacheRef.current === null) {\n        snapshotCacheRef.current = { value: newValue };\n\n        logger?.info(\n          debugOptions?.onInitialValue?.(newValue) ??\n            `Initial value: ${JSON.stringify(newValue)}`\n        );\n\n        return newValue;\n      }\n\n      // Check if the value actually changed\n      // For primitive values, use Object.is() for fast comparison\n      // For complex values, use deep comparison\n      const isPrimitive =\n        newValue === null ||\n        (typeof newValue !== 'object' && typeof newValue !== 'function');\n\n      let hasChanged: boolean;\n\n      if (isPrimitive) {\n        // Use Object.is() for primitives (faster and more reliable)\n        hasChanged = !Object.is(snapshotCacheRef.current.value, newValue);\n      } else {\n        // For objects/arrays, we need to do a deep comparison\n        // First check reference equality (fast path)\n        const oldValue = snapshotCacheRef.current.value;\n        if (oldValue === newValue) {\n          hasChanged = false;\n        } else {\n          // Deep comparison using a proper deep equality function\n          // This correctly handles property order differences\n          hasChanged = !deepEqual(oldValue, newValue);\n        }\n      }\n\n      if (hasChanged) {\n        const oldValue = snapshotCacheRef.current.value;\n\n        snapshotCacheRef.current = { value: newValue };\n\n        logger?.info(\n          debugOptions?.onValueChanged?.(oldValue, newValue) ??\n            `Value changed: ${JSON.stringify(oldValue)} -> ${JSON.stringify(\n              newValue\n            )}`\n        );\n        // Return the new value so useSyncExternalStore can detect the change via Object.is()\n        return newValue;\n      }\n\n      // Return the cached value to maintain stable reference when value hasn't changed\n      logger?.info(\n        debugOptions?.onValueUnchanged?.(newValue) ??\n          `Value unchanged: ${JSON.stringify(newValue)}`\n      );\n\n      return snapshotCacheRef.current.value;\n    };\n\n    return useSyncExternalStore(\n      subscribe,\n      () => getSnapshot(),\n      () => getSnapshot()\n    );\n  };\n}\n"],"mappings":";;;;;;;AAeA,SAAS,UAAU,GAAY,GAAqB;AAElD,KAAI,MAAM,EACR,QAAO;AAIT,KAAI,KAAK,QAAQ,KAAK,KACpB,QAAO,MAAM;AAIf,KAAI,OAAO,MAAM,OAAO,EACtB,QAAO;AAIT,KAAI,OAAO,MAAM,SACf,QAAO;AAIT,KAAI,MAAM,QAAQ,EAAE,IAAI,MAAM,QAAQ,EAAE,EAAE;AACxC,MAAI,EAAE,WAAW,EAAE,OACjB,QAAO;AAET,OAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,IAC5B,KAAI,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CACxB,QAAO;AAGX,SAAO;;AAIT,KAAI,MAAM,QAAQ,EAAE,IAAI,MAAM,QAAQ,EAAE,CACtC,QAAO;CAIT,MAAM,QAAQ,OAAO,KAAK,EAA6B;CACvD,MAAM,QAAQ,OAAO,KAAK,EAA6B;AAEvD,KAAI,MAAM,WAAW,MAAM,OACzB,QAAO;AAIT,MAAK,MAAM,OAAO,OAAO;AACvB,MAAI,CAAC,MAAM,SAAS,IAAI,CACtB,QAAO;AAET,MACE,CAAC,UACE,EAA8B,MAC9B,EAA8B,KAChC,CAED,QAAO;;AAIX,QAAO;;AA0GT,SAAgB,kBAKd,WACA,WACA;AACA,SACE,YACA,QACA,iBACG;EACH,MAAM,qCAAsD,KAAK;EACjE,MAAM,gCAAqB,WAAW;AAGtC,cAAY,UAAU;EAEtB,MAAM,oBAAoB;GACxB,MAAM,aAAa,WAAW;GAC9B,MAAM,WAAW,YAAY,QAAQ,WAAW;AAGhD,OAAI,iBAAiB,YAAY,MAAM;AACrC,qBAAiB,UAAU,EAAE,OAAO,UAAU;AAE9C,YAAQ,KACN,cAAc,iBAAiB,SAAS,IACtC,kBAAkB,KAAK,UAAU,SAAS,GAC7C;AAED,WAAO;;GAMT,MAAM,cACJ,aAAa,QACZ,OAAO,aAAa,YAAY,OAAO,aAAa;GAEvD,IAAIA;AAEJ,OAAI,YAEF,cAAa,CAAC,OAAO,GAAG,iBAAiB,QAAQ,OAAO,SAAS;QAC5D;IAGL,MAAM,WAAW,iBAAiB,QAAQ;AAC1C,QAAI,aAAa,SACf,cAAa;QAIb,cAAa,CAAC,UAAU,UAAU,SAAS;;AAI/C,OAAI,YAAY;IACd,MAAM,WAAW,iBAAiB,QAAQ;AAE1C,qBAAiB,UAAU,EAAE,OAAO,UAAU;AAE9C,YAAQ,KACN,cAAc,iBAAiB,UAAU,SAAS,IAChD,kBAAkB,KAAK,UAAU,SAAS,CAAC,MAAM,KAAK,UACpD,SACD,GACJ;AAED,WAAO;;AAIT,WAAQ,KACN,cAAc,mBAAmB,SAAS,IACxC,oBAAoB,KAAK,UAAU,SAAS,GAC/C;AAED,UAAO,iBAAiB,QAAQ;;AAGlC,yCACE,iBACM,aAAa,QACb,aAAa,CACpB"}

package/dist/hooks/use-selector.d.cts

@@ -0,0 +1,92 @@
+import { AnyResolvedStep, Expand, HelperFnChosenSteps, HelperFnCtx, MultiStepFormLogger, MultiStepFormLoggerOptions, StepNumbers } from "@jfdevelops/multi-step-form-core";
+
+//#region src/hooks/use-selector.d.ts
+type PrefixOptions = {
+  /**
+   * The action to perform on the prefix.
+   *
+   * @default 'prepend'
+   */
+  action?: 'prepend' | 'append';
+  /**
+   * The value to add to the prefix.
+   */
+  value: string | ((prefix: string) => string);
+  /**
+   * The delimiter to use between the original prefix and the added prefix.
+   * @default '-'
+   * @example
+   * ```tsx
+   * <Selector debug={{ prefix: { action: 'prepend', value: 'MySelector', delimiter: '|' } }}>
+   *   {(value) => <p>First name: {value}</p>}
+   * </Selector>
+   * ```
+   */
+  delimiter?: string;
+};
+/**
+ * Debug options for customizing logging behavior in the Selector component.
+ * All options are optional - you can provide any combination of these functions
+ * to customize how debug information is logged.
+ */
+type DebugOptions<TSelected> = {
+  /**
+   * The prefix to use for the logger.
+   *
+   * If a string or function is provided, it will replace the default prefix.
+   * If you need to prepend or append to the default prefix, you can provide {@linkcode PrefixOptions}.
+   * @default 'MultiStepFormSchema-Selector'
+   *
+   * @example
+   * ```tsx
+   * <Selector debug={{ prefix: 'MySelector' }}>
+   *   {(value) => <p>First name: {value}</p>}
+   * </Selector>
+   * ```
+   *
+   */
+  prefix?: MultiStepFormLoggerOptions['prefix'] | PrefixOptions;
+  /**
+   * Called when the Selector component renders with the selected value.
+   * This is called on every render of the Selector component, regardless of
+   * whether the selected value has changed.
+   *
+   * @param selected - The current selected value from the selector function
+   */
+  onRender?: (selected: TSelected) => string;
+  /**
+   * Called when the Selector component renders its children.
+   * This is only called when the Selector has a children render prop.
+   */
+  onChildrenRender?: () => string;
+  /**
+   * Called when the initial value is set for the first time.
+   * This is called once when the selector first evaluates and caches its value.
+   *
+   * @param value - The initial selected value
+   */
+  onInitialValue?: (value: TSelected) => string;
+  /**
+   * Called when the selected value changes from one value to another.
+   * This is called whenever the selector detects that the value has changed
+   * (using Object.is() for primitives or deep comparison for objects/arrays).
+   *
+   * @param oldValue - The previous selected value
+   * @param newValue - The new selected value
+   */
+  onValueChanged?: (oldValue: TSelected, newValue: TSelected) => string;
+  /**
+   * Called when the selected value is checked but hasn't changed.
+   * This is called when the selector evaluates but determines that the value
+   * is the same as the previously cached value.
+   *
+   * @param value - The current selected value (unchanged from previous check)
+   */
+  onValueUnchanged?: (value: TSelected) => string;
+};
+type UseSelector<TResolvedStep extends AnyResolvedStep, TSteps extends StepNumbers<TResolvedStep>, TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>> = ReturnType<typeof createUseSelector<TResolvedStep, TSteps, TChosenSteps>>;
+type SelectorFn<TResolvedStep extends AnyResolvedStep, TSteps extends StepNumbers<TResolvedStep>, TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>, TSelected> = (ctx: Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>) => TSelected;
+declare function createUseSelector<TResolvedStep extends AnyResolvedStep, TSteps extends StepNumbers<TResolvedStep>, TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>>(createCtx: () => Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>, subscribe: (listener: () => void) => () => void): <selected>(selectorFn: SelectorFn<TResolvedStep, TSteps, TChosenSteps, selected>, logger?: MultiStepFormLogger, debugOptions?: DebugOptions<selected>) => selected;
+//#endregion
+export { DebugOptions, SelectorFn, UseSelector };
+//# sourceMappingURL=use-selector.d.cts.map

package/dist/hooks/use-selector.d.mts

@@ -0,0 +1,92 @@
+import { AnyResolvedStep, Expand, HelperFnChosenSteps, HelperFnCtx, MultiStepFormLogger, MultiStepFormLoggerOptions, StepNumbers } from "@jfdevelops/multi-step-form-core";
+
+//#region src/hooks/use-selector.d.ts
+type PrefixOptions = {
+  /**
+   * The action to perform on the prefix.
+   *
+   * @default 'prepend'
+   */
+  action?: 'prepend' | 'append';
+  /**
+   * The value to add to the prefix.
+   */
+  value: string | ((prefix: string) => string);
+  /**
+   * The delimiter to use between the original prefix and the added prefix.
+   * @default '-'
+   * @example
+   * ```tsx
+   * <Selector debug={{ prefix: { action: 'prepend', value: 'MySelector', delimiter: '|' } }}>
+   *   {(value) => <p>First name: {value}</p>}
+   * </Selector>
+   * ```
+   */
+  delimiter?: string;
+};
+/**
+ * Debug options for customizing logging behavior in the Selector component.
+ * All options are optional - you can provide any combination of these functions
+ * to customize how debug information is logged.
+ */
+type DebugOptions<TSelected> = {
+  /**
+   * The prefix to use for the logger.
+   *
+   * If a string or function is provided, it will replace the default prefix.
+   * If you need to prepend or append to the default prefix, you can provide {@linkcode PrefixOptions}.
+   * @default 'MultiStepFormSchema-Selector'
+   *
+   * @example
+   * ```tsx
+   * <Selector debug={{ prefix: 'MySelector' }}>
+   *   {(value) => <p>First name: {value}</p>}
+   * </Selector>
+   * ```
+   *
+   */
+  prefix?: MultiStepFormLoggerOptions['prefix'] | PrefixOptions;
+  /**
+   * Called when the Selector component renders with the selected value.
+   * This is called on every render of the Selector component, regardless of
+   * whether the selected value has changed.
+   *
+   * @param selected - The current selected value from the selector function
+   */
+  onRender?: (selected: TSelected) => string;
+  /**
+   * Called when the Selector component renders its children.
+   * This is only called when the Selector has a children render prop.
+   */
+  onChildrenRender?: () => string;
+  /**
+   * Called when the initial value is set for the first time.
+   * This is called once when the selector first evaluates and caches its value.
+   *
+   * @param value - The initial selected value
+   */
+  onInitialValue?: (value: TSelected) => string;
+  /**
+   * Called when the selected value changes from one value to another.
+   * This is called whenever the selector detects that the value has changed
+   * (using Object.is() for primitives or deep comparison for objects/arrays).
+   *
+   * @param oldValue - The previous selected value
+   * @param newValue - The new selected value
+   */
+  onValueChanged?: (oldValue: TSelected, newValue: TSelected) => string;
+  /**
+   * Called when the selected value is checked but hasn't changed.
+   * This is called when the selector evaluates but determines that the value
+   * is the same as the previously cached value.
+   *
+   * @param value - The current selected value (unchanged from previous check)
+   */
+  onValueUnchanged?: (value: TSelected) => string;
+};
+type UseSelector<TResolvedStep extends AnyResolvedStep, TSteps extends StepNumbers<TResolvedStep>, TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>> = ReturnType<typeof createUseSelector<TResolvedStep, TSteps, TChosenSteps>>;
+type SelectorFn<TResolvedStep extends AnyResolvedStep, TSteps extends StepNumbers<TResolvedStep>, TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>, TSelected> = (ctx: Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>) => TSelected;
+declare function createUseSelector<TResolvedStep extends AnyResolvedStep, TSteps extends StepNumbers<TResolvedStep>, TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>>(createCtx: () => Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>, subscribe: (listener: () => void) => () => void): <selected>(selectorFn: SelectorFn<TResolvedStep, TSteps, TChosenSteps, selected>, logger?: MultiStepFormLogger, debugOptions?: DebugOptions<selected>) => selected;
+//#endregion
+export { DebugOptions, SelectorFn, UseSelector };
+//# sourceMappingURL=use-selector.d.mts.map

package/dist/hooks/use-selector.mjs

@@ -0,0 +1,64 @@
+import { useRef, useSyncExternalStore } from "react";
+
+//#region src/hooks/use-selector.ts
+/**
+* Deep equality check that compares values regardless of property order.
+* Handles objects, arrays, primitives, and null/undefined.
+*/
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return a === b;
+	if (typeof a !== typeof b) return false;
+	if (typeof a !== "object") return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+		return true;
+	}
+	if (Array.isArray(a) || Array.isArray(b)) return false;
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) {
+		if (!keysB.includes(key)) return false;
+		if (!deepEqual(a[key], b[key])) return false;
+	}
+	return true;
+}
+function createUseSelector(createCtx, subscribe) {
+	return (selectorFn, logger, debugOptions) => {
+		const snapshotCacheRef = useRef(null);
+		const selectorRef = useRef(selectorFn);
+		selectorRef.current = selectorFn;
+		const getSnapshot = () => {
+			const currentCtx = createCtx();
+			const newValue = selectorRef.current(currentCtx);
+			if (snapshotCacheRef.current === null) {
+				snapshotCacheRef.current = { value: newValue };
+				logger?.info(debugOptions?.onInitialValue?.(newValue) ?? `Initial value: ${JSON.stringify(newValue)}`);
+				return newValue;
+			}
+			const isPrimitive = newValue === null || typeof newValue !== "object" && typeof newValue !== "function";
+			let hasChanged;
+			if (isPrimitive) hasChanged = !Object.is(snapshotCacheRef.current.value, newValue);
+			else {
+				const oldValue = snapshotCacheRef.current.value;
+				if (oldValue === newValue) hasChanged = false;
+				else hasChanged = !deepEqual(oldValue, newValue);
+			}
+			if (hasChanged) {
+				const oldValue = snapshotCacheRef.current.value;
+				snapshotCacheRef.current = { value: newValue };
+				logger?.info(debugOptions?.onValueChanged?.(oldValue, newValue) ?? `Value changed: ${JSON.stringify(oldValue)} -> ${JSON.stringify(newValue)}`);
+				return newValue;
+			}
+			logger?.info(debugOptions?.onValueUnchanged?.(newValue) ?? `Value unchanged: ${JSON.stringify(newValue)}`);
+			return snapshotCacheRef.current.value;
+		};
+		return useSyncExternalStore(subscribe, () => getSnapshot(), () => getSnapshot());
+	};
+}
+
+//#endregion
+export { createUseSelector };
+//# sourceMappingURL=use-selector.mjs.map

package/dist/hooks/use-selector.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-selector.mjs","names":["hasChanged: boolean"],"sources":["../../src/hooks/use-selector.ts"],"sourcesContent":["import type {\n  AnyResolvedStep,\n  StepNumbers,\n  HelperFnChosenSteps,\n  Expand,\n  HelperFnCtx,\n  MultiStepFormLogger,\n  MultiStepFormLoggerOptions,\n} from '@jfdevelops/multi-step-form-core';\nimport { useSyncExternalStore, useRef } from 'react';\n\n/**\n * Deep equality check that compares values regardless of property order.\n * Handles objects, arrays, primitives, and null/undefined.\n */\nfunction deepEqual(a: unknown, b: unknown): boolean {\n  // Same reference or both are the same primitive value\n  if (a === b) {\n    return true;\n  }\n\n  // Handle null/undefined\n  if (a == null || b == null) {\n    return a === b;\n  }\n\n  // Type mismatch\n  if (typeof a !== typeof b) {\n    return false;\n  }\n\n  // Both are primitives (but not equal due to first check)\n  if (typeof a !== 'object') {\n    return false;\n  }\n\n  // Both are arrays\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) {\n      return false;\n    }\n    for (let i = 0; i < a.length; i++) {\n      if (!deepEqual(a[i], b[i])) {\n        return false;\n      }\n    }\n    return true;\n  }\n\n  // One is array, other is not\n  if (Array.isArray(a) || Array.isArray(b)) {\n    return false;\n  }\n\n  // Both are objects (not arrays)\n  const keysA = Object.keys(a as Record<string, unknown>);\n  const keysB = Object.keys(b as Record<string, unknown>);\n\n  if (keysA.length !== keysB.length) {\n    return false;\n  }\n\n  // Check if all keys in A exist in B with equal values\n  for (const key of keysA) {\n    if (!keysB.includes(key)) {\n      return false;\n    }\n    if (\n      !deepEqual(\n        (a as Record<string, unknown>)[key],\n        (b as Record<string, unknown>)[key]\n      )\n    ) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\ntype PrefixOptions = {\n  /**\n   * The action to perform on the prefix.\n   *\n   * @default 'prepend'\n   */\n  action?: 'prepend' | 'append';\n  /**\n   * The value to add to the prefix.\n   */\n  value: string | ((prefix: string) => string);\n  /**\n   * The delimiter to use between the original prefix and the added prefix.\n   * @default '-'\n   * @example\n   * ```tsx\n   * <Selector debug={{ prefix: { action: 'prepend', value: 'MySelector', delimiter: '|' } }}>\n   *   {(value) => <p>First name: {value}</p>}\n   * </Selector>\n   * ```\n   */\n  delimiter?: string;\n};\n\n/**\n * Debug options for customizing logging behavior in the Selector component.\n * All options are optional - you can provide any combination of these functions\n * to customize how debug information is logged.\n */\nexport type DebugOptions<TSelected> = {\n  /**\n   * The prefix to use for the logger.\n   *\n   * If a string or function is provided, it will replace the default prefix.\n   * If you need to prepend or append to the default prefix, you can provide {@linkcode PrefixOptions}.\n   * @default 'MultiStepFormSchema-Selector'\n   *\n   * @example\n   * ```tsx\n   * <Selector debug={{ prefix: 'MySelector' }}>\n   *   {(value) => <p>First name: {value}</p>}\n   * </Selector>\n   * ```\n   *\n   */\n  prefix?: MultiStepFormLoggerOptions['prefix'] | PrefixOptions;\n  /**\n   * Called when the Selector component renders with the selected value.\n   * This is called on every render of the Selector component, regardless of\n   * whether the selected value has changed.\n   *\n   * @param selected - The current selected value from the selector function\n   */\n  onRender?: (selected: TSelected) => string;\n\n  /**\n   * Called when the Selector component renders its children.\n   * This is only called when the Selector has a children render prop.\n   */\n  onChildrenRender?: () => string;\n\n  /**\n   * Called when the initial value is set for the first time.\n   * This is called once when the selector first evaluates and caches its value.\n   *\n   * @param value - The initial selected value\n   */\n  onInitialValue?: (value: TSelected) => string;\n\n  /**\n   * Called when the selected value changes from one value to another.\n   * This is called whenever the selector detects that the value has changed\n   * (using Object.is() for primitives or deep comparison for objects/arrays).\n   *\n   * @param oldValue - The previous selected value\n   * @param newValue - The new selected value\n   */\n  onValueChanged?: (oldValue: TSelected, newValue: TSelected) => string;\n\n  /**\n   * Called when the selected value is checked but hasn't changed.\n   * This is called when the selector evaluates but determines that the value\n   * is the same as the previously cached value.\n   *\n   * @param value - The current selected value (unchanged from previous check)\n   */\n  onValueUnchanged?: (value: TSelected) => string;\n};\n\nexport type UseSelector<\n  TResolvedStep extends AnyResolvedStep,\n  TSteps extends StepNumbers<TResolvedStep>,\n  TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>\n> = ReturnType<typeof createUseSelector<TResolvedStep, TSteps, TChosenSteps>>;\nexport type SelectorFn<\n  TResolvedStep extends AnyResolvedStep,\n  TSteps extends StepNumbers<TResolvedStep>,\n  TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>,\n  TSelected\n> = (\n  ctx: Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>\n) => TSelected;\n\nexport function createUseSelector<\n  TResolvedStep extends AnyResolvedStep,\n  TSteps extends StepNumbers<TResolvedStep>,\n  TChosenSteps extends HelperFnChosenSteps<TResolvedStep, TSteps>\n>(\n  createCtx: () => Expand<HelperFnCtx<TResolvedStep, TSteps, TChosenSteps>>,\n  subscribe: (listener: () => void) => () => void\n) {\n  return <selected>(\n    selectorFn: SelectorFn<TResolvedStep, TSteps, TChosenSteps, selected>,\n    logger?: MultiStepFormLogger,\n    debugOptions?: DebugOptions<selected>\n  ) => {\n    const snapshotCacheRef = useRef<{ value: selected } | null>(null);\n    const selectorRef = useRef(selectorFn);\n\n    // Update the selector ref on every render to ensure we always use the latest selector\n    selectorRef.current = selectorFn;\n\n    const getSnapshot = () => {\n      const currentCtx = createCtx();\n      const newValue = selectorRef.current(currentCtx);\n\n      // Cache the result to ensure stable reference\n      if (snapshotCacheRef.current === null) {\n        snapshotCacheRef.current = { value: newValue };\n\n        logger?.info(\n          debugOptions?.onInitialValue?.(newValue) ??\n            `Initial value: ${JSON.stringify(newValue)}`\n        );\n\n        return newValue;\n      }\n\n      // Check if the value actually changed\n      // For primitive values, use Object.is() for fast comparison\n      // For complex values, use deep comparison\n      const isPrimitive =\n        newValue === null ||\n        (typeof newValue !== 'object' && typeof newValue !== 'function');\n\n      let hasChanged: boolean;\n\n      if (isPrimitive) {\n        // Use Object.is() for primitives (faster and more reliable)\n        hasChanged = !Object.is(snapshotCacheRef.current.value, newValue);\n      } else {\n        // For objects/arrays, we need to do a deep comparison\n        // First check reference equality (fast path)\n        const oldValue = snapshotCacheRef.current.value;\n        if (oldValue === newValue) {\n          hasChanged = false;\n        } else {\n          // Deep comparison using a proper deep equality function\n          // This correctly handles property order differences\n          hasChanged = !deepEqual(oldValue, newValue);\n        }\n      }\n\n      if (hasChanged) {\n        const oldValue = snapshotCacheRef.current.value;\n\n        snapshotCacheRef.current = { value: newValue };\n\n        logger?.info(\n          debugOptions?.onValueChanged?.(oldValue, newValue) ??\n            `Value changed: ${JSON.stringify(oldValue)} -> ${JSON.stringify(\n              newValue\n            )}`\n        );\n        // Return the new value so useSyncExternalStore can detect the change via Object.is()\n        return newValue;\n      }\n\n      // Return the cached value to maintain stable reference when value hasn't changed\n      logger?.info(\n        debugOptions?.onValueUnchanged?.(newValue) ??\n          `Value unchanged: ${JSON.stringify(newValue)}`\n      );\n\n      return snapshotCacheRef.current.value;\n    };\n\n    return useSyncExternalStore(\n      subscribe,\n      () => getSnapshot(),\n      () => getSnapshot()\n    );\n  };\n}\n"],"mappings":";;;;;;;AAeA,SAAS,UAAU,GAAY,GAAqB;AAElD,KAAI,MAAM,EACR,QAAO;AAIT,KAAI,KAAK,QAAQ,KAAK,KACpB,QAAO,MAAM;AAIf,KAAI,OAAO,MAAM,OAAO,EACtB,QAAO;AAIT,KAAI,OAAO,MAAM,SACf,QAAO;AAIT,KAAI,MAAM,QAAQ,EAAE,IAAI,MAAM,QAAQ,EAAE,EAAE;AACxC,MAAI,EAAE,WAAW,EAAE,OACjB,QAAO;AAET,OAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,IAC5B,KAAI,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CACxB,QAAO;AAGX,SAAO;;AAIT,KAAI,MAAM,QAAQ,EAAE,IAAI,MAAM,QAAQ,EAAE,CACtC,QAAO;CAIT,MAAM,QAAQ,OAAO,KAAK,EAA6B;CACvD,MAAM,QAAQ,OAAO,KAAK,EAA6B;AAEvD,KAAI,MAAM,WAAW,MAAM,OACzB,QAAO;AAIT,MAAK,MAAM,OAAO,OAAO;AACvB,MAAI,CAAC,MAAM,SAAS,IAAI,CACtB,QAAO;AAET,MACE,CAAC,UACE,EAA8B,MAC9B,EAA8B,KAChC,CAED,QAAO;;AAIX,QAAO;;AA0GT,SAAgB,kBAKd,WACA,WACA;AACA,SACE,YACA,QACA,iBACG;EACH,MAAM,mBAAmB,OAAmC,KAAK;EACjE,MAAM,cAAc,OAAO,WAAW;AAGtC,cAAY,UAAU;EAEtB,MAAM,oBAAoB;GACxB,MAAM,aAAa,WAAW;GAC9B,MAAM,WAAW,YAAY,QAAQ,WAAW;AAGhD,OAAI,iBAAiB,YAAY,MAAM;AACrC,qBAAiB,UAAU,EAAE,OAAO,UAAU;AAE9C,YAAQ,KACN,cAAc,iBAAiB,SAAS,IACtC,kBAAkB,KAAK,UAAU,SAAS,GAC7C;AAED,WAAO;;GAMT,MAAM,cACJ,aAAa,QACZ,OAAO,aAAa,YAAY,OAAO,aAAa;GAEvD,IAAIA;AAEJ,OAAI,YAEF,cAAa,CAAC,OAAO,GAAG,iBAAiB,QAAQ,OAAO,SAAS;QAC5D;IAGL,MAAM,WAAW,iBAAiB,QAAQ;AAC1C,QAAI,aAAa,SACf,cAAa;QAIb,cAAa,CAAC,UAAU,UAAU,SAAS;;AAI/C,OAAI,YAAY;IACd,MAAM,WAAW,iBAAiB,QAAQ;AAE1C,qBAAiB,UAAU,EAAE,OAAO,UAAU;AAE9C,YAAQ,KACN,cAAc,iBAAiB,UAAU,SAAS,IAChD,kBAAkB,KAAK,UAAU,SAAS,CAAC,MAAM,KAAK,UACpD,SACD,GACJ;AAED,WAAO;;AAIT,WAAQ,KACN,cAAc,mBAAmB,SAAS,IACxC,oBAAoB,KAAK,UAAU,SAAS,GAC/C;AAED,UAAO,iBAAiB,QAAQ;;AAGlC,SAAO,qBACL,iBACM,aAAa,QACb,aAAa,CACpB"}