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 {
createContext,
useCallback,
useContext,
useEffect,
useId,
useMemo,
useState,
} from "react";
import { match } from "ts-pattern";
import { t } from "ttag";
import { SdkError } from "embedding-sdk-bundle/components/private/PublicComponentWrapper";
import { useSdkInternalNavigationOptional } from "embedding-sdk-bundle/components/private/SdkInternalNavigation/context";
import { SdkQuestionAlertListModal } from "embedding-sdk-bundle/components/private/notifications/SdkQuestionAlertListModal";
import { QuestionAlertModalProvider } from "embedding-sdk-bundle/components/private/notifications/context/QuestionAlertModalProvider";
import { useExtractResourceIdFromJwtToken } from "embedding-sdk-bundle/hooks/private/use-extract-resource-id-from-jwt-token";
import { useLoadQuestion } from "embedding-sdk-bundle/hooks/private/use-load-question";
import { useSdkControlledSqlParameters } from "embedding-sdk-bundle/hooks/private/use-sdk-controlled-sql-parameters";
import { useSetupContentTranslations } from "embedding-sdk-bundle/hooks/private/use-setup-content-translations";
import { useWarnConflictingParameterProps } from "embedding-sdk-bundle/hooks/private/use-warn-conflicting-parameter-props";
import { getEffectiveParameterValues } from "embedding-sdk-bundle/lib/controlled-parameters";
import { EmbeddingSdkMode } from "embedding-sdk-bundle/lib/modes/EmbeddingSdkMode";
import { getEmbeddingMode } from "embedding-sdk-bundle/lib/modes/getEmbeddingMode";
import { useSdkDispatch, useSdkSelector } from "embedding-sdk-bundle/store";
import {
clearGuestToken,
setInitialGuestToken,
} from "embedding-sdk-bundle/store/guest-embed";
import {
getError,
getGuestTokenForMount,
getIsGuestEmbed,
getPlugins,
getSessionTokenState,
} from "embedding-sdk-bundle/store/selectors";
import type { NavigateToNewCardParams } from "embedding-sdk-bundle/types";
import type { MetabasePluginsConfig } from "embedding-sdk-bundle/types/plugins";
import { transformSdkQuestion } from "metabase/embedding-sdk/lib/transform-question";
import type { MetabasePluginsConfig as InternalMetabasePluginsConfig } from "metabase/embedding-sdk/types/plugins";
import { EmbeddingEntityContextProvider } from "metabase/embedding/context";
import {
type OnCreateOptions,
useCreateQuestion,
useSaveQuestion,
} from "metabase/query_builder";
import { EmbeddingDataPickerContextProvider } from "metabase/querying/notebook/components/NotebookDataPicker/EmbeddingDataPicker/context";
import * as Lib from "metabase-lib";
import type Question from "metabase-lib/v1/Question";
import { getLastVisibleStageIndex } from "../utils/stages";
import type { SdkQuestionContextType, SdkQuestionProviderProps } from "./types";
/**
* Note: This context should only be used as a wrapper for the SdkQuestionDefaultView
* component. The idea behind this context is to allow the SdkQuestionDefaultView component
* to use components within the ./components folder, which use the context for display
* and functions.
* */
export const SdkQuestionContext = createContext<
SdkQuestionContextType | undefined
>(undefined);
const DEFAULT_OPTIONS = {};
export const SdkQuestionProvider = ({
questionId: rawQuestionId,
token: rawToken,
options = DEFAULT_OPTIONS,
deserializedCard,
componentPlugins,
onNavigateBack,
children,
onBeforeSave,
onSave,
onRun,
isSaveEnabled = true,
entityTypes,
dataPicker,
targetCollection,
initialCollection,
initialSqlParameters,
sqlParameters,
onSqlParametersChange,
hiddenParameters,
withDownloads,
withAlerts,
targetDashboardId,
backToDashboard,
clickActionMode: userClickActionMode,
navigateToNewCard: userNavigateToNewCard,
onDrillThrough,
navigatedEntity,
onVisualizationChange,
initialVisualization,
}: SdkQuestionProviderProps) => {
const isGuestEmbed = useSdkSelector(getIsGuestEmbed);
const dispatch = useSdkDispatch();
const navigation = useSdkInternalNavigationOptional();
const [isFirstRender, setIsFirstRender] = useState(true);
// Stable per-mount id: keeps this mount's guest token isolated from any
// other guest StaticQuestion/StaticDashboard sharing the same MetabaseProvider.
const mountId = useId();
const { error: tokenFetchError } = useSdkSelector(getSessionTokenState);
const tokenFromStore = useSdkSelector((state) =>
getGuestTokenForMount(state, mountId),
);
const effectiveInitialSqlParameters = getEffectiveParameterValues(
sqlParameters,
initialSqlParameters,
);
// Store token so the refresh handler can check expiry. No need to await — not used here.
useEffect(() => {
if (rawToken && isGuestEmbed) {
dispatch(setInitialGuestToken({ mountId, token: rawToken }));
}
}, [rawToken, isGuestEmbed, dispatch, mountId]);
// Own effect: folding this into the one above would clear the token on every
// rawToken change, leaving a window with no token for the refresh handler.
useEffect(
() => () => {
dispatch(clearGuestToken(mountId));
},
[dispatch, mountId],
);
useEffect(() => {
setIsFirstRender(false);
}, []);
const {
resourceId: questionId,
token,
tokenError,
} = useExtractResourceIdFromJwtToken({
isGuestEmbed,
resourceId: rawQuestionId,
// Skip stale Redux token on first render (e.g. wizard re-issuing a token when toggling parameters); rawToken prop takes precedence.
// From the next render onward, tokenFromStore is used and the value is from a refreshed token.
token: (!isFirstRender ? tokenFromStore : null) ?? rawToken ?? undefined,
});
useSetupContentTranslations({ token });
const isNewQuestion = questionId === "new" || questionId === "new-native";
const error = useSdkSelector(getError);
const handleCreateQuestion = useCreateQuestion();
const handleSaveQuestion = useSaveQuestion();
const handleSave = async (question: Question) => {
if (isSaveEnabled) {
const saveContext = { isNewQuestion: false };
const sdkQuestion = transformSdkQuestion(question);
await onBeforeSave?.(sdkQuestion, saveContext);
await handleSaveQuestion(question);
onSave?.(sdkQuestion, saveContext);
await loadAndQueryQuestion();
}
};
const handleCreate = async (
question: Question,
options?: OnCreateOptions,
): Promise<Question> => {
if (isSaveEnabled) {
const saveContext = {
isNewQuestion: true,
dashboardTabId: options?.dashboardTabId,
};
const sdkQuestion = transformSdkQuestion(question);
await onBeforeSave?.(sdkQuestion, saveContext);
const createdQuestion = await handleCreateQuestion(question, options);
onSave?.(transformSdkQuestion(createdQuestion), saveContext);
// Set the latest saved question object to update the question title.
replaceQuestion(createdQuestion);
return createdQuestion;
}
return question;
};
const {
question,
originalQuestion,
parameterValues,
queryResults,
isQuestionLoading,
isQueryRunning,
queryQuestion,
replaceQuestion,
loadAndQueryQuestion,
updateQuestion,
updateParameterValues,
navigateToNewCard,
} = useLoadQuestion({
questionId,
isGuestEmbed,
token,
options,
deserializedCard,
initialSqlParameters: effectiveInitialSqlParameters,
targetDashboardId,
initialVisualization,
});
useWarnConflictingParameterProps({
initialParameters: initialSqlParameters,
parameters: sqlParameters,
initialParameterPropName: "initialSqlParameters",
parameterPropName: "sqlParameters",
});
useSdkControlledSqlParameters({
sqlParameters,
onSqlParametersChange,
navigatedEntity,
question,
parameterValues: parameterValues ?? {},
updateParameterValues,
});
const globalPlugins = useSdkSelector(getPlugins);
const plugins: MetabasePluginsConfig = useMemo(() => {
return { ...globalPlugins, ...componentPlugins };
}, [globalPlugins, componentPlugins]);
const mode = useMemo(
() =>
userClickActionMode ??
getEmbeddingMode({
queryMode: EmbeddingSdkMode,
// Unjustified type cast. FIXME
plugins: plugins as InternalMetabasePluginsConfig,
}),
[userClickActionMode, plugins],
);
// Wrap navigateToNewCard to intercept navigation to new card
const navigateToNewCardWithDrillThrough = useCallback(
async (params: NavigateToNewCardParams) => {
if (onDrillThrough) {
await onDrillThrough(
{
drillName: params.drillName,
nextCard: params.nextCard,
},
async () => {
await navigateToNewCard?.(params);
},
);
} else {
await navigateToNewCard?.(params);
}
},
[navigateToNewCard, onDrillThrough],
);
// Wrap navigateToNewCard to push the virtual entry for the internal navigation system
const navigateToNewCardWithSdkInternalNavigation = useCallback(
async (params: NavigateToNewCardParams) => {
// This actually changes what gets rendered
await navigateToNewCardWithDrillThrough(params);
// Push virtual entry if last entry is NOT already a question drill
const currentEntry = navigation?.stack.at(-1);
if (currentEntry?.type !== "question-drill") {
navigation?.push({
type: "question-drill",
virtual: true,
name: question?.displayName() ?? t`Question`,
onPop: () => loadAndQueryQuestion(),
});
}
},
[
navigateToNewCardWithDrillThrough,
navigation,
question,
loadAndQueryQuestion,
],
);
const query = question?.query();
const lastVisibleStageIndex = useMemo(
() => getLastVisibleStageIndex(query),
[query],
);
const updateAndNormalizeQuestion = useCallback(
(nextQuestion: Question, options?: { run?: boolean }) =>
updateQuestion(
nextQuestion.setQuery(Lib.dropEmptyStages(nextQuestion.query())),
options,
),
[updateQuestion],
);
// How the user's `navigateToNewCard` prop maps to the context value:
// - null → navigation disabled (e.g. StaticQuestion / ad-hoc questions).
// Passed through as null; `Visualization` turns it into
// `undefined`, so the chart never wires `onChangeCardAndRun`
// (which would load a card by its undefined id → `/card/undefined`).
// - undefined → the SDK's internal navigation (the default).
// - a handler → run through the drill-through wrapper.
const contextNavigateToNewCard: SdkQuestionContextType["navigateToNewCard"] =
match(userNavigateToNewCard)
.with(null, () => null)
.with(undefined, () => navigateToNewCardWithSdkInternalNavigation)
.otherwise(() => navigateToNewCardWithDrillThrough);
const questionContext: SdkQuestionContextType = {
originalId: questionId,
lastVisibleStageIndex,
token,
isQuestionLoading,
isQueryRunning,
resetQuestion: loadAndQueryQuestion,
onReset: loadAndQueryQuestion,
onNavigateBack,
queryQuestion,
replaceQuestion,
updateQuestion,
updateAndNormalizeQuestion,
updateParameterValues,
navigateToNewCard: contextNavigateToNewCard,
plugins,
question,
originalQuestion,
parameterValues,
queryResults,
mode,
onSave: handleSave,
onCreate: handleCreate,
isSaveEnabled,
targetCollection,
initialCollection,
withDownloads,
withAlerts,
onRun,
backToDashboard,
hiddenParameters,
onVisualizationChange,
};
useEffect(() => {
if (tokenError) {
return;
}
loadAndQueryQuestion();
}, [loadAndQueryQuestion, tokenError]);
// Push the question name to the stack if the stack is empty (ie: this is the root question)
// We need to wait for the question to load to have the name
useEffect(() => {
if (question && navigation && navigation.stack.length === 0) {
navigation.push({
type: "question",
id: questionId ?? null,
name: question.displayName() || t`Question`,
});
}
}, [questionId, question, navigation]);
if (isGuestEmbed && isNewQuestion) {
return (
<SdkError
message={t`You can't explore or save questions in Guest Embed mode`}
/>
);
}
if (tokenError) {
return <SdkError message={tokenError} />;
}
if (tokenFetchError) {
return <SdkError message={tokenFetchError.message} />;
}
if (error) {
return <SdkError message={error.message} />;
}
return (
<SdkQuestionContext.Provider value={questionContext}>
<EmbeddingEntityContextProvider uuid={null} token={token}>
<QuestionAlertModalProvider>
<EmbeddingDataPickerContextProvider
dataPicker={dataPicker}
entityTypes={entityTypes}
>
{children}
</EmbeddingDataPickerContextProvider>
<SdkQuestionAlertListModal />
</QuestionAlertModalProvider>
</EmbeddingEntityContextProvider>
</SdkQuestionContext.Provider>
);
};
export const useSdkQuestionContext = () => {
const context = useContext(SdkQuestionContext);
if (context === undefined) {
throw new Error(
"useSdkQuestionContext must be used within a SdkQuestionProvider",
);
}
return context;
};