Documentation

[iamogbz]

Demo

The app has three components

1. Parent input; simple useValue
2. Child input that is updated when the parent changes and also sends updates to the parent useSyncedValue
3. Child input that is updated when the parent changes only; use case useTrackedValue

react-global-local-state/src/App.tsx

Lines 12 to 37 in da2d401

	const [value, setValue] = React.useState<string | undefined>(
	"initial parent value",
	);
	return (
	<div className="App">
	<LabelledInput
	id="parentValue"
	label={{ text: " parent: ", style: labelStyle }}
	onValueChange={setValue}
	value={value}
	/>
	<hr />
	<SourceTargetInput
	id="childValue"
	label={{ text: " child that updates parent: ", style: labelStyle }}
	source={{ value, setValue }}
	/>
	<hr />
	<SourceTargetInput
	id="childValue"
	label={{ text: " child that only receives: ", style: labelStyle }}
	source={{ value }}
	/>
	</div>
	);

react-global-local-state/src/components/SourceTargetInput.tsx

Lines 15 to 30 in da2d401

	export function SourceTargetInput({
	id,
	label,
	source,
	}: SourceTargetInputProps): JSX.Element {
	const synced = useSyncedValue({ source });
	return (
	<LabelledInput
	id={id}
	label={label}
	value={synced.value}
	onValueChange={synced.setValue}
	/>
	);
	}

useValue

react-global-local-state/src/hooks/useValue.ts

Lines 52 to 71 in d632987

	/** Params for `useValue` which include the updateable initial value and time stamper */
	interface UseValueOptions<T, U> {
	initial?: Partial<UpdateableValue<T>>;
	stamper?: U;
	}
	/** Results from `useValue` which includes the recent value, time stamp and updater */
	interface UseValueResult<T, U> extends UpdateableValue<T> {
	value: MaybeValue<T>;
	stamp: Stamp<U>;
	}
	/**
	* Keep track of set value changes and triggers change handler on difference.
	* Uses {@link isEqual} to compare values when checking for a change.
	*/
	export function useValue<T, U>({
	initial,
	stamper,
	}: UseValueOptions<T, U> = {}): UseValueResult<T, U> {

useTrackedValue

react-global-local-state/src/hooks/useValue.ts

Lines 93 to 120 in d632987

	/**
	* Params for `useTrackedValue` which include the source value, stamper and a predicate.
	*/
	interface UseTrackedValueOptions<T, U> {
	source?: Partial<UseValueResult<T, U>>;
	stamper?: U;
	shouldUpdate: ShouldUpdateCallback<T, U>;
	}
	export type ShouldUpdateCallback<T, U> = (
	source?: ShouldUpdateArg<T, U>,
	target?: ShouldUpdateArg<T, U>,
	) => boolean;
	type ShouldUpdateArg<T, U> = Pick<
	Partial<UseValueResult<T, U>>,
	"stamp" | "value"
	>;
	/**
	* This keeps track of the source value and updates the internal value using the
	* given update predicate method. This compares the stamp of the incoming source
	* and the internal value, updating the tracked internal value which is returned
	* if there is a change from the incoming source.
	*/
	export function useTrackedValue<T, U>({
	source,
	stamper,
	shouldUpdate,
	}: UseTrackedValueOptions<T, U>): UseValueResult<T, U> {

useSyncedValue

react-global-local-state/src/hooks/useValue.ts

Lines 142 to 157 in d632987

	type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
	type UseSycedValueOptions<T, U> = Optional<
	UseTrackedValueOptions<T, U>,
	"shouldUpdate"
	>;
	/**
	* Sync a parent with a dependent child value. The incoming parent source updates are
	* always tracked, while the child value which is returned can be updated independently
	* only being overwritten by the parent source if there is a more recent stamped value.
	*/
	export function useSyncedValue<T, U>({
	shouldUpdate,
	source: { setValue: setSourceValue, ...source } = {},
	stamper,
	}: UseSycedValueOptions<T, U>): UseValueResult<T, U> {