New features: sync state with URL (back and forth) and translate this state

[jdupont22]

I remeber a tweet about react-query asking samples / ideas about how to handle the synchronization of the state with the URL, am i dreaming, i can't find it. I would be very interesting to have this with react-query.

I have develop something like that, in a declarative manner:

This code is extract from my account list page.

The state

export declare type ICrudGetAllSort = Partial<{ page: number; size: number; sort: string; order: string; }>;
export declare type ISearchQueryParam = Partial<{ q: string; }>;

export type GetAllAccountQueryParams = Partial<{
  offerId: number;
  states: AccountState[];
}>;

export type GetAllAccounts = GetAllAccountQueryParams & ISearchAllSort;

The hook to retrieve the state from the URL and sync the changes

// queryParams is of type GetAllAccounts
// page, size, sort, order and q are automaticaly manage, no need to declare it except to override it
const { queryParams, pagination, search, sort, filter, clear } = useAdvancedQueryParams<GetAllAccounts>({
    params: {
      offerId: {},
      states: {
        default: defaultStates,
        map: {
          params: 'states',
          transform: (states) => toStatesOrNull<AccountState>(states),
        }
      }
    }
  });

The hook to retrieve accounts, useAccount, based on useQuery and the process state

// args is of type GetAllAccounts == queryParams
export function useAccounts(args: GetAllAccounts, config: UseQueryOptions<PaginatedAccounts> = {}) {
  const {data: paginatedAccounts, ...rest} = useQuery<PaginatedAccounts>(
    [accountsKey, args],
    async () => {
      const response = await getAccounts(args);
      return extractPaginatedResponse(response);
    },
    config
  )

  const data = paginatedAccounts ?? emptyPaginatedList;
  return {data, ...rest};
}

The hook to translate the state to human readable

const { translations, onParamChange } = useDisplayAdvancedQueryParams(queryParams, {
  params: {
    q: {
      label: translate('common.filter.search'),
    },
    offerId: {
      exclude: !!embeddedOfferId,
      label: translate('offer.entity'),
    },
    states: {
      exclude: true,
    }
  }
});

can return a JSX or map the value

const { translations, onParamChange } = useDisplayAdvancedQueryParams(queryParams, {
    params: {
      q: {
        label: translate('common.filter.search'),
      },
      groupsIds: {
        exclude: true,
      },
      assetsIds: {
        exclude: true,
      },
      reportedById: {
        label: translate('issue.reportedBy')
      },
      assignedToId: {
        label: translate('issue.assignedTo')
      },
      assignedToBusinessId: {
        label: translate('business.types.VENDOR')
      },
      priority: {
        label: translate('issue.priority'),
        value: (priority: IIssuePriority) => <IssuePriority priority={priority}/>
      },
      referentId: {
        label: translate('asset.referent')
      },
      states: {
        exclude: true,
      },
      range: {
        label: translate('global.field.range'),
        value: (range: RangeDate) => formatQueryParam(range)
      }
    }
  });

A generic component to display all the translations

<DisplayAdvancedQueryParams translations={translations} clear={clear}/>

A more advance state declaration

// embedded means the value are pass in paramaters of the component, no be part of the url query params
// range is split in the url, something like "url?rangeStart=10&rangeEnd=20"

const { queryParams, pagination, search, filter, clear } = useAdvancedQueryParams<IGetAllIssues>({
    params: {
      groupsIds: {
        embedded: groupsIds
      },
      assetsIds: {
        embedded: assetsIds
      },
      reportedById: {
        embedded: embeddedReportedById
      },
      assignedToId: {
        embedded: embeddedAssignedToId
      },
      assignedToBusinessId: {
        embedded: embeddedAssignedToBusinessId
      },
      priority: {},
      referentId: {},
      states: {
        default: defaultStates,
      },
      range: {
        default: toRangeDate('TODAY'),
        map: {
          params: ['rangeStart', 'rangeEnd'],
          transform: (rangesStr) => parseRangeDate(rangesStr?.[0], rangesStr?.[1])
        }
      }
    }
  });