Add page parameters to navigation actions

docs/data/toolpad/data-binding.md

@@ -49,3 +49,19 @@ In the example below you can see how after clicking the button, the value is cop
 After clicking the Button:
 
 <img src="/static/toolpad/docs/data-binding/bind-11.png" alt="Binding result 2" width="200" />
+
+### Navigation actions
+
+In the binding editor for event handlers it is also possible to define **navigation actions**, which can open any page in your app when triggered.
+
+You can set a navigation action in the **Navigation** tab of the binding editor for any event handler prop:
+
+<img src="/static/toolpad/docs/data-binding/bind-12.png" alt="Binding editor for navigation actions" width="800" />
+
+<!---
+@TODO: Link "any query string parameters that the destination page supports" to page parameters documentation
+-->
+
+The binding editor for navigation actions allows you to select a page to go to, as well as set values for any query string parameters that the destination page supports.
+
+You can also bind the query parameter values to any page state of the origin page by clicking on the binding button near the respective parameter's input.

packages/toolpad-app/src/appDom/index.ts

@@ -1114,15 +1114,15 @@ export function ref(nodeId: NodeId): NodeReference;
 export function ref(nodeId: null | undefined): null;
 export function ref(nodeId: Maybe<NodeId>): NodeReference | null;
 export function ref(nodeId: Maybe<NodeId>): NodeReference | null {
- return nodeId ? { $$ref: nodeId } : null;
+ return nodeId ? { $ref: nodeId } : null;
 }
 
 export function deref(nodeRef: NodeReference): NodeId;
 export function deref(nodeRef: null | undefined): null;
 export function deref(nodeRef: Maybe<NodeReference>): NodeId | null;
 export function deref(nodeRef: Maybe<NodeReference>): NodeId | null {
  if (nodeRef) {
- return nodeRef.$$ref;
+ return nodeRef.$ref;
  }
  return null;
 }

packages/toolpad-app/src/runtime/CanvasHooksContext.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 import { NodeHashes } from '../types';
 
 export interface NavigateToPage {
- (pageNodeId: NodeId): void;
+ (pageNodeId: NodeId, pageParameters?: Record<string, string>): void;
 }
 
 /**

packages/toolpad-app/src/runtime/ToolpadApp.tsx

@@ -131,8 +131,17 @@ const USE_DATA_QUERY_CONFIG_KEYS: readonly (keyof UseDataQueryConfig)[] = [
 function usePageNavigator(): NavigateToPage {
  const navigate = useNavigate();
  const navigateToPage: NavigateToPage = React.useCallback(
- (pageNodeId: NodeId) => {
- navigate(`/pages/${pageNodeId}`);
+ (pageNodeId, pageParameters) => {
+ const urlParams = pageParameters && new URLSearchParams(pageParameters);
+
+ navigate({
+ pathname: `/pages/${pageNodeId}`,
+ ...(urlParams
+ ? {
+ search: urlParams.toString(),
+ }
+ : {}),
+ });
  },
  [navigate],
  );
@@ -345,10 +354,28 @@ function RenderedNodeContent({ node, childNodeGroups, Component }: RenderedNodeC
  const action = (node as appDom.ElementNode).props?.[key];
 
  if (action?.type === 'navigationAction') {
- const handler = () => {
- const { page } = action.value;
+ const handler = async () => {
+ const { page, parameters = {} } = action.value;
  if (page) {
- navigateToPage(appDom.deref(page));
+ const parsedParameterEntries = await Promise.all(
+ Object.keys(parameters).map(async (parameterName) => {
+ const parameterValue = parameters[parameterName];
+
+ if (parameterValue && parameterValue.type === 'jsExpression') {
+ const result = await evaluatePageExpression(
+ parameterValue.value,
+ scopeId,
+ localScopeParams,
+ );
+ return [parameterName, result.value];
+ }
+ return [parameterName, parameterValue?.value];
+ }),
+ );
+
+ const parsedParameters = Object.fromEntries(parsedParameterEntries);
+
+ navigateToPage(appDom.deref(page), parsedParameters);
  }
  };
 
@@ -535,7 +562,7 @@ function flattenNestedBindables(
  return flattenNestedBindables(param[1], `${prefix}[${i}][1]`);
  });
  }
- // TODO: create a marker in bindables (similar to $$ref) to recognize them automatically
+ // TODO: create a marker in bindables (similar to $ref) to recognize them automatically
  // in a nested structure. This would allow us to build deeply nested structures
  if (typeof params.type === 'string') {
  return [[prefix, params as BindableAttrValue<any>]];
@@ -736,9 +763,10 @@ function parseBindings(
  ? `${elm.id}.props.${argType.defaultValueProp}`
  : undefined;
 
+ const propValue = elm.props?.[propName];
+
  const binding: BindableAttrValue<any> =
- elm.props?.[propName] ||
- appDom.createConst(argType ? getArgTypeDefaultValue(argType) : undefined);
+ propValue || appDom.createConst(argType ? getArgTypeDefaultValue(argType) : undefined);
 
  const bindingId = `${elm.id}.props.${propName}`;
 

packages/toolpad-app/src/server/localMode.ts

@@ -410,12 +410,12 @@ function toBindableProp<V>(value: V | { $$jsExpression: string }): BindableAttrV
  if (typeof (value as any).$$jsExpressionAction === 'string') {
  return { type: 'jsExpressionAction', value: (value as any).$$jsExpressionAction };
  }
- if (typeof (value as any).$$navigationAction === 'string') {
+ if (typeof (value as any).$$navigationAction === 'object') {
  const action = value as any as NavigationAction;
  return {
  type: 'navigationAction',
  value: {
- page: { $$ref: action.$$navigationAction.page as NodeId },
+ page: { $ref: action.$$navigationAction.page as NodeId },
  parameters: mapValues(
  action.$$navigationAction.parameters,
  (param) => param && toBindable(param),
@@ -438,7 +438,7 @@ function fromBindableProp<V>(bindable: BindableAttrValue<V>) {
  case 'navigationAction':
  return {
  $$navigationAction: {
- page: bindable.value.page.$$ref,
+ page: bindable.value.page.$ref,
  parameters:
  bindable.value.parameters &&
  mapValues(bindable.value.parameters, (param) => param && fromBindable(param)),

packages/toolpad-app/src/toolpad/AppEditor/BindingEditor.tsx

@@ -1,53 +1,58 @@
+import * as React from 'react';
 import {
  Box,
- Button,
  Checkbox,
- Dialog,
- DialogActions,
- DialogContent,
- DialogTitle,
  Stack,
  Toolbar,
  Tooltip,
  Typography,
  styled,
  tooltipClasses,
  TooltipProps,
+ Button,
+ Dialog,
+ DialogActions,
+ DialogContent,
+ DialogTitle,
+ Tab,
  TextField,
  MenuItem,
- Tab,
 } from '@mui/material';
-import * as React from 'react';
 import LinkIcon from '@mui/icons-material/Link';
 import AddLinkIcon from '@mui/icons-material/AddLink';
 import {
  LiveBinding,
- PropValueType,
- BindableAttrValue,
  JsExpressionAttrValue,
- NavigationAction,
- NodeId,
  JsExpressionAction,
  ScopeMeta,
  ScopeMetaField,
  JsRuntime,
+ PropValueType,
+ BindableAttrValue,
+ NavigationAction,
+ NodeId,
 } from '@mui/toolpad-core';
 import { createProvidedContext } from '@mui/toolpad-utils/react';
 import { TabContext, TabList } from '@mui/lab';
-import { Maybe, WithControlledProp } from '../../utils/types';
+import { mapValues } from '@mui/toolpad-utils/collections';
 import { JsExpressionEditor } from './PageEditor/JsExpressionEditor';
 import JsonView from '../../components/JsonView';
-import { tryFormatExpression } from '../../utils/prettier';
 import useLatest from '../../utils/useLatest';
 import useDebounced from '../../utils/useDebounced';
 import { useEvaluateLiveBinding } from './useEvaluateLiveBinding';
+import GlobalScopeExplorer from './GlobalScopeExplorer';
+import { WithControlledProp, Maybe } from '../../utils/types';
+
+import { tryFormatExpression } from '../../utils/prettier';
 import useShortcut from '../../utils/useShortcut';
+import useUnsavedChangesConfirm from '../hooks/useUnsavedChangesConfirm';
+
+import TabPanel from '../../components/TabPanel';
+
 import { useDom } from '../AppState';
 import * as appDom from '../../appDom';
-import { usePageEditorState } from './PageEditor/PageEditorProvider';
-import GlobalScopeExplorer from './GlobalScopeExplorer';
-import TabPanel from '../../components/TabPanel';
-import useUnsavedChangesConfirm from '../hooks/useUnsavedChangesConfirm';
+// eslint-disable-next-line import/no-cycle
+import BindableEditor from './PageEditor/BindableEditor';
 
 interface BindingEditorContext {
  label: string;
@@ -204,50 +209,142 @@ function JsExpressionActionEditor({ value, onChange }: JsExpressionActionEditorP
  );
 }
 
+export interface NavigationActionParameterEditorProps
+ extends WithControlledProp<BindableAttrValue<string> | null> {
+ label: string;
+}
+
+function NavigationActionParameterEditor({
+ label,
+ value,
+ onChange,
+}: NavigationActionParameterEditorProps) {
+ const { jsRuntime, globalScope, globalScopeMeta } = useBindingEditorContext();
+
+ const liveBinding = useEvaluateLiveBinding({
+ jsRuntime,
+ input: value,
+ globalScope,
+ });
+
+ return (
+ <Box>
+ <BindableEditor<string>
+ liveBinding={liveBinding}
+ jsRuntime={jsRuntime}
+ globalScope={globalScope}
+ globalScopeMeta={globalScopeMeta}
+ label={label}
+ propType={{ type: 'string' }}
+ value={value || null}
+ onChange={onChange}
+ />
+ </Box>
+ );
+}
+
 export interface NavigationActionEditorProps extends WithControlledProp<NavigationAction | null> {}
 
 function NavigationActionEditor({ value, onChange }: NavigationActionEditorProps) {
  const { dom } = useDom();
  const root = appDom.getApp(dom);
  const { pages = [] } = appDom.getChildNodes(dom, root);
- const { nodeId: currentPageNodeId } = usePageEditorState();
+
+ const getDefaultActionParameters = React.useCallback((page: appDom.PageNode) => {
+ const defaultPageParameters = page.attributes.parameters?.value || [];
+
+ return mapValues(Object.fromEntries(defaultPageParameters), (pageParameterValue) =>
+ appDom.createConst(pageParameterValue),
+ );
+ }, []);
 
  const handlePageChange = React.useCallback(
  (event: React.ChangeEvent<HTMLInputElement>) => {
+ const pageId = event.target.value as NodeId;
+ const page = appDom.getNode(dom, pageId);
+
+ const defaultActionParameters = appDom.isPage(page) ? getDefaultActionParameters(page) : {};
+
  onChange({
  type: 'navigationAction',
- value: { page: appDom.ref(event.target.value as NodeId) },
+ value: {
+ page: appDom.ref(pageId),
+ parameters: defaultActionParameters,
+ },
  });
  },
- [onChange],
+ [dom, getDefaultActionParameters, onChange],
  );
 
- const availablePages = React.useMemo(
- () => pages.filter((page) => page.id !== currentPageNodeId),
- [pages, currentPageNodeId],
+ const actionPageRef = value?.value?.page || null;
+ const actionParameters = React.useMemo(
+ () => value?.value.parameters || {},
+ [value?.value.parameters],
  );
 
- const hasPagesAvailable = availablePages.length > 0;
+ const actionPageId = actionPageRef ? appDom.deref(actionPageRef) : null;
+ const actionPage = pages.find((availablePage) => availablePage.id === actionPageId);
+
+ const handleActionParameterChange = React.useCallback(
+ (actionParameterName: string) => (newValue: BindableAttrValue<string> | null) => {
+ if (actionPageRef) {
+ onChange({
+ type: 'navigationAction',
+ value: {
+ page: actionPageRef,
+ parameters: {
+ ...actionParameters,
+ ...(newValue ? { [actionParameterName]: newValue } : {}),
+ },
+ },
+ });
+ }
+ },
+ [actionPageRef, actionParameters, onChange],
+ );
+
+ const hasPagesAvailable = pages.length > 0;
+
+ const defaultActionParameters = actionPage ? getDefaultActionParameters(actionPage) : {};
+
+ const actionParameterEntries = Object.entries(actionParameters || defaultActionParameters);
 
  return (
  <Box sx={{ my: 1 }}>
  <Typography>Navigate to a page on this event</Typography>
  <TextField
  fullWidth
  sx={{ my: 3 }}
- label="page"
+ label="Select a page"
  select
- value={value?.value?.page ? appDom.deref(value.value.page) : ''}
+ value={actionPageId || ''}
  onChange={handlePageChange}
  disabled={!hasPagesAvailable}
  helperText={hasPagesAvailable ? null : 'No other pages available'}
  >
- {availablePages.map((page) => (
+ {pages.map((page) => (
  <MenuItem key={page.id} value={page.id}>
  {page.name}
  </MenuItem>
  ))}
  </TextField>
+ {actionParameterEntries.length > 0 ? (
+ <React.Fragment>
+ <Typography variant="overline">Page parameters:</Typography>
+ {Object.entries(actionParameters || defaultActionParameters).map((actionParameter) => {
+ const [actionParameterName, actionParameterValue] = actionParameter;
+
+ return (
+ <NavigationActionParameterEditor
+ key={actionParameterName}
+ label={actionParameterName}
+ value={actionParameterValue as BindableAttrValue<string>}
+ onChange={handleActionParameterChange(actionParameterName)}
+ />
+ );
+ })}
+ </React.Fragment>
+ ) : null}
  </Box>
  );
 }

packages/toolpad-app/src/toolpad/AppEditor/PageEditor/BindableEditor.tsx

@@ -4,12 +4,13 @@ import {
  BindableAttrValue,
  PropValueType,
  LiveBinding,
- ScopeMeta,
  JsRuntime,
+ ScopeMeta,
 } from '@mui/toolpad-core';
-import { BindingEditor } from '../BindingEditor';
 import { WithControlledProp } from '../../../utils/types';
 import { getDefaultControl } from '../../propertyControls';
+// eslint-disable-next-line import/no-cycle
+import { BindingEditor } from '../BindingEditor';
 
 function renderDefaultControl(params: RenderControlParams<any>) {
  const Control = getDefaultControl({ typeDef: params.propType });

packages/toolpad-app/src/toolpad/AppEditor/PageEditor/QueryEditor/QueryEditorDialog.tsx

@@ -322,7 +322,7 @@ export default function QueryNodeEditorDialog<Q>({
  </MenuItem>
  <MenuItem value="mutation">Only fetch on manual action</MenuItem>
  </TextField>
- <BindableEditor
+ <BindableEditor<boolean>
  liveBinding={liveEnabled}
  globalScope={pageState}
  globalScopeMeta={globalScopeMeta}