Allow passing through a 'reason' from useBlocker

[Huulivoide]

What: Add a way to return a custom value from(through) useBlocker

What the possible public API could look like

// Reason field added to blocked state.
// What is the value if a "legacy" boolean BlockerFunction function is used:
// true? null? included but set to undefined? Not included at all. →
interface BlockerBlocked<TReason> {
    state: "blocked";
    reset: () => void;
    proceed: () => void;
    location: Location;
    reason: TReason; // Possibly optional reason?: TReason
}
// Unblocked and proceeding states, in my usecase they do not need the reason field.
// Tough it could probably be included in Proceeding state 🤔
// In unblocked it makes no sense at all.
interface BlockerUnblocked { ...; reason?: never; }
interface BlockerProceeding { ...; reason?: never; }

type Blocker<TReason> = BlockerUnblocked | BlockerBlocked<TReason> | BlockerProceeding;

type BlockerFunctionArgs = {
    currentLocation: Location;
    nextLocation: Location;
    historyAction: Action;
};

// New alternative form of a blocker function.
// One that returns the block-signal in `blocked` field and an extra
// reason value in the `reason` field.
type BooleanBlockerFunction = (args: BlockerFunctionArgs) => boolean;
type ReasonedBlockerFunction<TReason> = (args: BlockerFunctionArgs) =>
  | { blocked: true; reason: TReason; }
  | { blocked: false; reason?: never };

type BlockerFunction<TReason> = BooleanBlockerFunction | ReasonedBlockerFunction<TReason>;

// For compatibilityy, the useBlocker function call could set the TReason to void
// by default, to keep the API compatible with existing code bases.
function useBlocker<TReason = void>(shouldBlock: boolean | BlockerFunction<TReason>): Blocker<TReason>;

// And as for usePrompt, two options as it is still marked unstable.
// 1. Keep current API, and the and the reason value just becomes moot and does nothing.
//    Possibly the only the BooleanBlockerFunction could be allowed.
function usePrompt(message: string, shouldBlock: boolean | BlockerFunction<unknown>): void;

// 2. Leverage the new Reason value to allow for dynamic prompt message:
function usePrompt(shouldBlock: ReasonedBlockerFunction<string>): void;

Why?: Current API is limited when there are multiple blocking elements.

Current API is sufficient for simple scenarios where there is only a single form on the screen at once and the actual useBlocker call can be inlined close to the blocking element and the reaction to changes in the Blocker result can be specific to that call site.

But sometimes there could be multiple elements/reason on the screen that could call for blocking of the navigation. As the current API already accpets a function as the shouldBlock input arg, it is possible to construct a compound blocker that can check for multiple reasons.

type UnregisterBlockerFn = () = void;
type CompoundBlockerResult = {
  blocker: Blocker;
  registerBlocker: (shouldBlock: BlockerFunction) => UnregisterBlockerFn
}
function useCompoundBlocker(): CompoundBlockerResult {
  const [blockers, setBlockers] = useState<BlockerFunction[]>([]);
  const shouldBlock = useCallback((args: BlockerFunctionArgs) =>
    blockers.some(blocker => blocker(args)),
    [blockers]
  );
  
  const blocker = useBlocker(shouldBlock);
  
  const registerBlocker = useCallback((blocker: BlockerFunction): UnregisterBlockerFn => {
    setBlockers(p => p.concat(blocker));
    return () => setBlockers(p => p.filter(it => it !== blocker));
  }, []);
  
  return { blocker, registerBlocker }
}

function BlockingChild({ registerBlocker }: BlockingChildProps) {
  const formState = useFormState();
  useEffect(() => registerBlocker(() => formState.isDirty));
  return (<Form>...</Form>);
}
    

function MyBlockingComponentParent() {
  const { blocker, registerBlocker } = useCompoundBlocker();
  
  return (
    <div>
      <BlockingChild registerBlocker={registerBlocker} />
      <BlockingChild registerBlocker={registerBlocker} />
      
      <NavigationBlockedModal blocker={blocker} />
    </div>
  );
}

That can work, but it has limitations on what can be shown in the NavigationBlockedModal component. That has to stay generic enough that any reason within the scope can apply to it, which puts limitations on how the actual content can be worder.

In my current project the original use case for implementing such a compound blocker was that we had multiple views of high complexity entities where the displaying & editing of details was split onto multiple subsections in view. It was then possible to open any number of those subsections for editing simultaneously, thus creating multiple forms that could block the navigation. As in all cases it were forms that caused the blocking a generic "You have unsaved changes on one or more active forms on the page. Are you sure you want to discard your changes?" -modal was sufficient.

But recently a need has arisen to block the navigation on more variety of situations, for which the message should preferably be worded differently. While "It seems you might have unsaved edits on one or more of the form on the page, or maybe you did not finish downloading a report you were preparing? Are you sure want to discard all unfinished work?" -message is functional, it is not particularly good from the enduser's point of view.

Thus, if it were possible to return some sort of value from the BlockerFunction and then later read that back from the returned Blocker object, it would be easy to create a situation specific BlockerModal with informative conten in usecases that call for a compund-blocker.

Related topic: Allow multiple blockers to exist simultaneously.