The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
import {
type CSSProperties,
type ReactNode,
useCallback,
useContext,
useMemo,
useState,
} from "react";
import { match } from "ts-pattern";
import { SdkDashboardStyledWrapper } from "embedding-sdk-bundle/components/public/dashboard/SdkDashboardStyleWrapper";
import { buildClickParameters } from "embedding-sdk-bundle/lib/controlled-parameters";
import { useSdkDispatch, useSdkStore } from "embedding-sdk-bundle/store";
import { setInitialDashboardTabId } from "embedding-sdk-bundle/store/reducer";
import type { SdkDashboardId } from "embedding-sdk-bundle/types/dashboard";
import { setParameterValue } from "metabase/dashboard/actions";
import {
getDashboardComplete,
getParameters,
getSelectedTabId,
} from "metabase/dashboard/selectors";
import { useSelector } from "metabase/redux";
import { selectTab } from "metabase/redux/dashboard";
import { Stack } from "metabase/ui";
import { uuid } from "metabase/utils/uuid";
import { SdkQuestion } from "../../public/SdkQuestion";
import type {
DrillThroughQuestionProps,
SdkQuestionProps,
} from "../../public/SdkQuestion/SdkQuestion";
import { InteractiveDashboardContent } from "../../public/dashboard/InteractiveDashboard/InteractiveDashboard";
import type { SdkDashboardInnerProps } from "../../public/dashboard/SdkDashboard";
import { SdkAdHocQuestion } from "../SdkAdHocQuestion";
import { SdkInternalNavigationBackButton } from "./SdkInternalNavigationBackButton";
import {
SdkInternalNavigationContext,
type SdkInternalNavigationEntry,
type SdkInternalNavigationStackEntry,
} from "./context";
// Strips props that are only meant for the root dashboard before forwarding to a drill-through target.
function getDrillThroughDashboardProps({
parameters: _parameters,
onParametersChange: _onParametersChange,
initialParameters: _initialParameters,
navigatedEntityParameters: _navigatedEntityParameters,
onNavigatedEntityParametersChange: _onNavigatedEntityParametersChange,
...props
}: Partial<SdkDashboardInnerProps> = {}): Omit<
SdkDashboardInnerProps,
| "dashboardId"
| "parameters"
| "onParametersChange"
| "initialParameters"
| "navigatedEntityParameters"
| "onNavigatedEntityParametersChange"
> {
return props;
}
type Props = {
children: ReactNode;
dashboardProps?: Partial<Omit<SdkDashboardInnerProps, "dashboardId">>;
/** Custom renderer for drill-through questions */
renderDrillThroughQuestion?: () => ReactNode;
/** Props to pass to drill-through question components */
drillThroughQuestionProps?: DrillThroughQuestionProps;
/** When true, children are kept mounted (but hidden) during navigation instead of being unmounted */
keepChildrenMounted?: boolean;
style?: CSSProperties;
className?: string;
};
const SdkInternalNavigationProviderInner = ({
style,
className,
children,
dashboardProps,
renderDrillThroughQuestion: RenderDrillThroughQuestion,
drillThroughQuestionProps,
keepChildrenMounted = false,
}: Props) => {
const [stack, setStack] = useState<SdkInternalNavigationStackEntry[]>([]);
const dispatch = useSdkDispatch();
const currentDashboard = useSelector(getDashboardComplete);
const selectedTabId = useSelector(getSelectedTabId);
const push = useCallback(
(entry: SdkInternalNavigationEntry) => {
// Click behaviors that target the currently loaded dashboard should
// switch tab / apply parameters in place rather than push a new stack
// entry (which would re-mount the dashboard from scratch and lose the
// requested tab).
if (
entry.type === "dashboard" &&
currentDashboard != null &&
entry.id === currentDashboard.id
) {
if (entry.tabId != null) {
dispatch(selectTab({ tabId: entry.tabId }));
}
if (entry.parameterIdValuePairs) {
// Merge per-parameter (matches core app DashboardClickAction) so
// unrelated filters keep their current values.
for (const [id, value] of entry.parameterIdValuePairs) {
dispatch(setParameterValue(id, value));
}
}
return;
}
// Handle cross dashboard navigation with initial tab.
if (entry.type === "dashboard") {
dispatch(setInitialDashboardTabId(entry.tabId ?? null));
}
const navigationId = uuid();
setStack((prev) => {
const top = prev.at(-1);
// Capture the live selected tab onto the outgoing dashboard entry so
// that popping back restores the tab the user was actually viewing
// (which may differ from the tab the entry was opened on).
const updated =
top?.type === "dashboard"
? [
...prev.slice(0, -1),
{ ...top, tabId: selectedTabId ?? top.tabId },
]
: prev;
return [...updated, { ...entry, navigationId }];
});
},
[dispatch, currentDashboard, selectedTabId],
);
const pop = useCallback(() => {
setStack((prev) => {
const poppedEntry = prev.at(-1);
// Call onPop for placeholder entries that require special logic
if (poppedEntry && "onPop" in poppedEntry && poppedEntry.onPop) {
poppedEntry.onPop();
}
const next = prev.slice(0, -1);
const newTop = next.at(-1);
if (newTop?.type === "dashboard") {
// Seed the initial tab so the re-mounted dashboard lands on the tab
// the user was last viewing instead of defaulting to the first tab.
dispatch(setInitialDashboardTabId(newTop.tabId ?? null));
}
return next;
});
}, [dispatch]);
// Initialize the stack with a dashboard entry (called by dashboard components when the dashboard loads and we have the name)
const initWithDashboard = useCallback(
(dashboard: { id: SdkDashboardId; name: string }) => {
if (stack.length === 0) {
setStack([
{
type: "dashboard",
id: dashboard.id,
name: dashboard.name,
navigationId: uuid(),
},
]);
}
},
[stack.length],
);
// "Virtual" entries are entries that are rendered by the previous entity (ie: drills, new question from dashboard)
// we don't have to render them, but we need them in the stack to make the back button work correctly
const nonVirtualEntries = useMemo(
() => stack.filter((entry) => !entry.virtual),
[stack],
);
const entryToRender = nonVirtualEntries.at(-1);
const entryIndex = entryToRender ? stack.indexOf(entryToRender) : -1;
// If the entry is the original entry, we just need to return the children.
const entryIsOriginalEntity = stack.length === 0 || entryIndex === 0;
const hasNavigatedToEntity = !entryIsOriginalEntity;
const navigatedEntityParameters = dashboardProps?.navigatedEntityParameters;
const onNavigatedEntityParametersChange =
dashboardProps?.onNavigatedEntityParametersChange;
const store = useSdkStore();
const controlledParameters = entryToRender
? navigatedEntityParameters?.[entryToRender.navigationId]
: undefined;
const value = useMemo(
() => ({
stack,
push,
pop,
currentEntry: stack.at(-1),
previousEntry: stack.at(-2),
// When starting from the `metabase-browser`, we need to have > 2 items in
// the stack to be able to go back, as the first navigation is handled by
// the breadcrumbs.
canGoBack: stack.filter((e) => e.type !== "metabase-browser").length > 1,
initWithDashboard,
hasNavigatedToEntity,
}),
[stack, push, pop, initWithDashboard, hasNavigatedToEntity],
);
const shouldRenderBackButton = match(stack.at(-1)?.type ?? null)
.with(null, () => false)
.with("dashboard", () => true)
.with("question", () => false) // questions render their button in the header toolbar
.otherwise(() => false); // all other navigations end up rendering a question (ad-hoc, new question etc)
const maybeButton = shouldRenderBackButton ? (
// Same padding as when the button is rendered inside the question, to minimize movement while navigating
<Stack align="flex-start" p="lg">
<SdkInternalNavigationBackButton />
</Stack>
) : null;
// We try to infer question props from the starting dashboard when they have a 1:1 mapping
const questionPropsInferredFromDashboard: Partial<SdkQuestionProps> = {
withDownloads: dashboardProps?.withDownloads,
};
const content = match({ activeEntry: entryToRender })
.with({ activeEntry: { type: "dashboard" } }, ({ activeEntry }) => {
const { entityId, navigationId } = activeEntry;
return (
<InteractiveDashboardContent
{...getDrillThroughDashboardProps(dashboardProps)}
dashboardId={activeEntry.id}
{...(controlledParameters
? { parameters: controlledParameters }
: { initialParameters: activeEntry.parameters })}
onParametersChange={
entityId !== undefined
? (payload) =>
onNavigatedEntityParametersChange?.({
...payload,
entityType: "dashboard",
entityId,
navigationId,
// Read the store now: on the first load, the render still has the previous dashboard
clickParameters: buildClickParameters(
activeEntry.parameters ?? {},
getParameters(store.getState()),
),
})
: undefined
}
enableEntityNavigation
/>
);
})
.with({ activeEntry: { type: "ad-hoc-question" } }, ({ activeEntry }) => (
<SdkAdHocQuestion
questionPath={activeEntry.adHocQuestionPath}
onNavigateBack={pop}
isSaveEnabled
{...questionPropsInferredFromDashboard}
{...drillThroughQuestionProps}
>
{RenderDrillThroughQuestion && <RenderDrillThroughQuestion />}
</SdkAdHocQuestion>
))
.with({ activeEntry: { type: "question" } }, ({ activeEntry }) => {
const { entityId, navigationId } = activeEntry;
return (
<SdkQuestion
questionId={activeEntry.id}
onNavigateBack={pop}
// When using controlled parameters we pass `sqlParameters`, not `initialSqlParameters`
initialSqlParameters={
controlledParameters ? undefined : activeEntry.parameters
}
isSaveEnabled
{...questionPropsInferredFromDashboard}
{...drillThroughQuestionProps}
sqlParameters={controlledParameters}
navigatedEntity={
entityId !== undefined
? {
rawClickParameters: activeEntry.parameters ?? {},
onParametersChange: (payload) =>
onNavigatedEntityParametersChange?.({
...payload,
entityType: "question",
entityId,
navigationId,
}),
}
: undefined
}
>
{RenderDrillThroughQuestion && <RenderDrillThroughQuestion />}
</SdkQuestion>
);
})
.otherwise(() => children);
return (
<SdkInternalNavigationContext.Provider value={value}>
{/* When `keepChildrenMounted` is true, we keep the children mounted but hide them */}
<div style={{ display: entryIsOriginalEntity ? "contents" : "none" }}>
{entryIsOriginalEntity || keepChildrenMounted ? children : null}
</div>
{entryIsOriginalEntity ? null : (
// When we don't render the children directly, we need to render a wrapper with the styles applied.
// Otherwise we don't pass `style` and `className` to anything, we can't always wrap it otherwise we may render
// paddings and borders twice.
<SdkDashboardStyledWrapper className={className} style={style}>
{maybeButton}
{content}
</SdkDashboardStyledWrapper>
)}
</SdkInternalNavigationContext.Provider>
);
};
/**
* Outer component that handles the nesting check.
* If already inside a navigation provider, just render children directly.
* This allows us to just wrap components with this and this will make sure to not
* re-render the actual context provider.
*/
export const SdkInternalNavigationProvider = (props: Props) => {
const isNested = useContext(SdkInternalNavigationContext);
if (isNested) {
return props.children;
}
return <SdkInternalNavigationProviderInner {...props} />;
};