@lobb-js/studio 0.47.0 → 0.48.0

package/dist/actions.d.ts

@@ -11,35 +11,9 @@ export interface OpenDataTableDrawerProps {
     position?: "side" | "bottom";
     tabs?: CollectionTab[];
 }
-export interface OpenPopupProps {
-    component: any;
-    componentProps?: Record<string, any>;
-    title?: string;
-    size?: "default" | "sm";
-    hideHeader?: boolean;
-    replaceLast?: boolean;
-}
-export interface OpenDataTablePopupProps {
-    collectionName: string;
-    filter?: Record<string, any>;
-    sort?: Record<string, "asc" | "desc">;
-    limit?: number;
-    title?: string;
-    showHeader?: boolean;
-    showFooter?: boolean;
-    showFilter?: boolean;
-    tabs?: CollectionTab[];
-    view?: {
-        id: string;
-        [key: string]: any;
-    };
-    replaceLast?: boolean;
-    size?: "default" | "sm";
-    hideHeader?: boolean;
-}
 export declare function showDialog(title: string, description: string): Promise<boolean>;
 export declare function openCreateDetailView(studioContext: StudioContext, props: CreateDetailViewProp): void;
 export declare function openUpdateDetailView(studioContext: StudioContext, props: UpdateDetailViewProp): Promise<void>;
 export declare function openDataTableDrawer(studioContext: StudioContext, props: OpenDataTableDrawerProps): void;
-export declare function openPopup(studioContext: StudioContext, props: OpenPopupProps): void;
-export declare function openDataTablePopup(studioContext: StudioContext, props: OpenDataTablePopupProps): void;
+export { openPopup, openDataTablePopup, goBackPopup } from "./popup";
+export type { OpenPopupProps, OpenDataTablePopupProps } from "./popup";

package/dist/actions.js

@@ -3,18 +3,8 @@ import ConfirmationDialog from "./components/confirmationDialog/confirmationDial
 import CreateDetailView from "./components/detailView/create/createDetailView.svelte";
 import UpdateDetailView from "./components/detailView/update/updateDetailView.svelte";
 import DataTableDrawer from "./components/dataTableDrawer/dataTableDrawer.svelte";
-import DataTable from "./components/dataTable/dataTable.svelte";
-import Popup from "./components/popup/popup.svelte";
 import { createStudioContextMap } from "./context";
 import { getCollectionParamsFields } from "./components/dataTable/utils";
-let activePopup = null;
-function closeActivePopupIfRequested(replaceLast) {
-    if (!replaceLast || !activePopup)
-        return;
-    const toUnmount = activePopup;
-    activePopup = null;
-    unmount(toUnmount, { outro: true });
-}
 export function showDialog(title, description) {
     return new Promise((resolve) => {
         const targetElement = document.querySelector("main");
@@ -90,53 +80,7 @@ export function openDataTableDrawer(studioContext, props) {
         },
     });
 }
-export function openPopup(studioContext, props) {
-    const targetElement = document.querySelector("main");
-    if (!targetElement)
-        throw new Error("main html element doesn't exist");
-    closeActivePopupIfRequested(props.replaceLast);
-    const mounted = mount(Popup, {
-        target: targetElement,
-        context: createStudioContextMap(studioContext),
-        props: {
-            component: props.component,
-            componentProps: props.componentProps,
-            title: props.title,
-            size: props.size,
-            hideHeader: props.hideHeader,
-            onClose: async () => {
-                if (activePopup === mounted)
-                    activePopup = null;
-                await unmount(mounted, { outro: true });
-            },
-        },
-    });
-    activePopup = mounted;
-}
-export function openDataTablePopup(studioContext, props) {
-    // DataTable reads `searchParams` once during its initial $state setup,
-    // so sort/limit need to be folded into the searchParams object before
-    // we mount. Built here in plain TS — no Svelte reactivity to escape.
-    const searchParams = {};
-    if (props.sort)
-        searchParams.sort = props.sort;
-    if (props.limit != null)
-        searchParams.limit = String(props.limit);
-    openPopup(studioContext, {
-        component: DataTable,
-        componentProps: {
-            collectionName: props.collectionName,
-            filter: props.filter,
-            searchParams,
-            showHeader: props.showHeader,
-            showFooter: props.showFooter,
-            showFilter: props.showFilter ?? false,
-            tabs: props.tabs,
-            view: props.view,
-        },
-        title: props.title ?? props.collectionName,
-        size: props.size,
-        hideHeader: props.hideHeader,
-        replaceLast: props.replaceLast,
-    });
-}
+// Popup helpers (openPopup, openDataTablePopup, goBackPopup) live in
+// `./popup` — they share enough state (active overlay, back-history)
+// to warrant their own module.
+export { openPopup, openDataTablePopup, goBackPopup } from "./popup";

package/dist/components/popup/popup.svelte

@@ -6,7 +6,7 @@
 	// `openPopup` mounts this; specialised popup helpers like
 	// `openDataTablePopup` are thin wrappers that supply the body
 	// component + props.
-	import { X } from "lucide-svelte";
+	import { ArrowLeft, X } from "lucide-svelte";
 	import { fade, scale } from "svelte/transition";
 	import { cubicOut } from "svelte/easing";
 	import Portal from "svelte-portal";
@@ -28,6 +28,12 @@
 		// Use when the body brings its own header.
 		hideHeader?: boolean;
 		onClose?: () => void;
+		// Set by the action layer when there's a popup-history entry to
+		// pop. The chrome renders a back arrow in the title bar; bodies
+		// that `hideHeader: true` get `canGoBack` + `onBack` forwarded
+		// so they can render their own back affordance.
+		canGoBack?: boolean;
+		onBack?: () => void;
 	}
 
 	let {
@@ -37,6 +43,8 @@
 		size = "default",
 		hideHeader = false,
 		onClose,
+		canGoBack = false,
+		onBack,
 	}: Props = $props();
 </script>
 
@@ -54,8 +62,19 @@
 			{size === 'sm' ? 'max-h-[calc(100vh-6rem)] max-w-2xl' : 'h-[85vh] max-w-7xl'}"
 	>
 		{#if !hideHeader}
-			<div class="flex h-12 shrink-0 items-center justify-between gap-4 border-b px-4">
-				<div class="text-sm font-medium">{title ?? ""}</div>
+			<div class="flex h-12 shrink-0 items-center justify-between gap-2 border-b px-4">
+				<div class="flex min-w-0 items-center gap-2">
+					{#if canGoBack}
+						<Button
+							variant="ghost"
+							size="icon"
+							onclick={() => onBack?.()}
+							class="h-8 w-8 rounded-full text-muted-foreground"
+							Icon={ArrowLeft}
+						/>
+					{/if}
+					<div class="truncate text-sm font-medium">{title ?? ""}</div>
+				</div>
 				<Button
 					variant="ghost"
 					size="icon"
@@ -73,7 +92,7 @@
 		     percentages, which don't resolve when the popup uses
 		     `max-h` (size="sm") instead of a fixed `h`. -->
 		<div class="flex min-h-0 flex-1 flex-col overflow-hidden">
-			<Body {...componentProps} {onClose} />
+			<Body {...componentProps} {onClose} {canGoBack} {onBack} />
 		</div>
 	</div>
 </Portal>

package/dist/components/popup/popup.svelte.d.ts

@@ -5,6 +5,8 @@ interface Props {
     size?: "default" | "sm";
     hideHeader?: boolean;
     onClose?: () => void;
+    canGoBack?: boolean;
+    onBack?: () => void;
 }
 declare const Popup: import("svelte").Component<Props, {}, "">;
 type Popup = ReturnType<typeof Popup>;

package/dist/extensions/extension.types.d.ts

@@ -23,7 +23,8 @@ import * as Icons from "lucide-svelte";
 import { ContextMenu } from "bits-ui";
 import * as Tooltip from "../components/ui/tooltip";
 import * as Breadcrumb from "../components/ui/breadcrumb";
-import { showDialog, type OpenDataTableDrawerProps, type OpenDataTablePopupProps, type OpenPopupProps } from "../actions";
+import { showDialog, type OpenDataTableDrawerProps } from "../actions";
+import type { OpenDataTablePopupProps, OpenPopupProps } from "../popup";
 import { toast } from "svelte-sonner";
 import { Switch } from "../components/ui/switch";
 export interface Components {

package/dist/extensions/extensionUtils.js

@@ -1,5 +1,6 @@
 import { toast } from "svelte-sonner";
-import { showDialog, openDataTableDrawer, openDataTablePopup, openPopup } from "../actions";
+import { showDialog, openDataTableDrawer } from "../actions";
+import { openDataTablePopup, openPopup } from "../popup";
 import { emitEvent } from "../eventSystem";
 import { Button } from "../components/ui/button";
 import { Input } from "../components/ui/input";

package/dist/popup.d.ts

@@ -0,0 +1,31 @@
+import { type StudioContext } from "./context";
+import type { CollectionTab } from "./store.types";
+export interface OpenPopupProps {
+    component: any;
+    componentProps?: Record<string, any>;
+    title?: string;
+    size?: "default" | "sm";
+    hideHeader?: boolean;
+    replaceLast?: boolean;
+}
+export interface OpenDataTablePopupProps {
+    collectionName: string;
+    filter?: Record<string, any>;
+    sort?: Record<string, "asc" | "desc">;
+    limit?: number;
+    title?: string;
+    showHeader?: boolean;
+    showFooter?: boolean;
+    showFilter?: boolean;
+    tabs?: CollectionTab[];
+    view?: {
+        id: string;
+        [key: string]: any;
+    };
+    replaceLast?: boolean;
+    size?: "default" | "sm";
+    hideHeader?: boolean;
+}
+export declare function openPopup(studioContext: StudioContext, props: OpenPopupProps): void;
+export declare function goBackPopup(studioContext: StudioContext): void;
+export declare function openDataTablePopup(studioContext: StudioContext, props: OpenDataTablePopupProps): void;

package/dist/popup.js

@@ -0,0 +1,104 @@
+import { mount, unmount } from "svelte";
+import DataTable from "./components/dataTable/dataTable.svelte";
+import Popup from "./components/popup/popup.svelte";
+import { createStudioContextMap } from "./context";
+let activePopup = null;
+// Props that produced the currently-mounted popup. Tracked so we can
+// push them onto `popupHistory` when this popup is swapped out by a
+// `replaceLast: true` opener, enabling back navigation.
+let activePopupProps = null;
+// Stack of popup-props that were swapped out via `replaceLast: true`.
+// The back arrow re-opens the top of the stack; closing via X or the
+// backdrop wipes the whole stack (a deliberate full-reset, not back).
+const popupHistory = [];
+// Internal mount path used by both `openPopup` (user-initiated) and
+// `goBackPopup` (history-driven). The `fromBack` flag suppresses
+// pushing the outgoing popup onto the history stack — when the user
+// hits Back, the popup they're leaving shouldn't reappear if they hit
+// Back again.
+function mountPopup(studioContext, props, opts = {}) {
+    const targetElement = document.querySelector("main");
+    if (!targetElement)
+        throw new Error("main html element doesn't exist");
+    if (props.replaceLast && activePopup) {
+        // Swap: archive the outgoing popup's props (unless this open is
+        // itself a back-navigation) and unmount it. Outro plays in
+        // parallel with the new popup's intro.
+        if (!opts.fromBack && activePopupProps) {
+            popupHistory.push(activePopupProps);
+        }
+        const toUnmount = activePopup;
+        activePopup = null;
+        activePopupProps = null;
+        unmount(toUnmount, { outro: true });
+    }
+    else if (!props.replaceLast) {
+        // A fresh, non-stacking popup starts a new context — drop any
+        // accumulated back history from the previous chain.
+        popupHistory.length = 0;
+    }
+    const canGoBack = popupHistory.length > 0;
+    const mounted = mount(Popup, {
+        target: targetElement,
+        context: createStudioContextMap(studioContext),
+        props: {
+            component: props.component,
+            componentProps: props.componentProps,
+            title: props.title,
+            size: props.size,
+            hideHeader: props.hideHeader,
+            canGoBack,
+            onBack: () => goBackPopup(studioContext),
+            onClose: async () => {
+                if (activePopup === mounted) {
+                    activePopup = null;
+                    activePopupProps = null;
+                    // X / backdrop is a full reset — nuke the back
+                    // stack so reopening anything starts fresh.
+                    popupHistory.length = 0;
+                }
+                await unmount(mounted, { outro: true });
+            },
+        },
+    });
+    activePopup = mounted;
+    activePopupProps = props;
+}
+export function openPopup(studioContext, props) {
+    mountPopup(studioContext, props);
+}
+export function goBackPopup(studioContext) {
+    const prev = popupHistory.pop();
+    if (!prev)
+        return;
+    // Force `replaceLast: true` so the swap+outro path runs, and tell
+    // `mountPopup` not to push the current popup onto history.
+    mountPopup(studioContext, { ...prev, replaceLast: true }, { fromBack: true });
+}
+export function openDataTablePopup(studioContext, props) {
+    // DataTable reads `searchParams` once during its initial $state setup,
+    // so sort/limit need to be folded into the searchParams object before
+    // we mount. Built here in plain TS — no Svelte reactivity to escape.
+    const searchParams = {};
+    if (props.sort)
+        searchParams.sort = props.sort;
+    if (props.limit != null)
+        searchParams.limit = String(props.limit);
+    openPopup(studioContext, {
+        component: DataTable,
+        componentProps: {
+            collectionName: props.collectionName,
+            filter: props.filter,
+            searchParams,
+            showHeader: props.showHeader,
+            showFooter: props.showFooter,
+            showFilter: props.showFilter ?? false,
+            tabs: props.tabs,
+            view: props.view,
+        },
+        title: props.title ?? props.collectionName,
+        size: props.size,
+        hideHeader: props.hideHeader,
+        replaceLast: props.replaceLast,
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lobb-js/studio",
   "license": "UNLICENSED",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/lib/actions.ts

@@ -3,8 +3,6 @@ import ConfirmationDialog from "./components/confirmationDialog/confirmationDial
 import CreateDetailView from "./components/detailView/create/createDetailView.svelte";
 import UpdateDetailView from "./components/detailView/update/updateDetailView.svelte";
 import DataTableDrawer from "./components/dataTableDrawer/dataTableDrawer.svelte";
-import DataTable from "./components/dataTable/dataTable.svelte";
-import Popup from "./components/popup/popup.svelte";
 import type { CreateDetailViewProp } from "./components/detailView/create/createDetailView.svelte";
 import type { UpdateDetailViewProp } from "./components/detailView/update/updateDetailView.svelte";
 import type { StudioContext } from "./context";
@@ -22,49 +20,6 @@ export interface OpenDataTableDrawerProps {
     tabs?: CollectionTab[];
 }
 
-export interface OpenPopupProps {
-    // Component rendered inside the popup. It receives `componentProps`
-    // spread onto it plus `onClose` so it can close the popup itself.
-    component: any;
-    componentProps?: Record<string, any>;
-    title?: string;
-    // `default` is the wide data-table popup (max-w-7xl, fixed 85vh).
-    // `sm` is the narrow detail-view variant (max-w-2xl, content-height).
-    size?: "default" | "sm";
-    // When true, the popup renders no chrome at all (no title bar, no
-    // close button). The body uses the `onClose` prop the popup passes
-    // it to render its own close affordance.
-    hideHeader?: boolean;
-    // Close the previously-opened popup before mounting this one —
-    // drill-down semantics. Only popups participate; drawers don't.
-    replaceLast?: boolean;
-}
-
-export interface OpenDataTablePopupProps {
-    collectionName: string;
-    filter?: Record<string, any>;
-    sort?: Record<string, "asc" | "desc">;
-    limit?: number;
-    title?: string;
-    showHeader?: boolean;
-    showFooter?: boolean;
-    showFilter?: boolean;
-    tabs?: CollectionTab[];
-    view?: { id: string; [key: string]: any };
-    replaceLast?: boolean;
-    size?: "default" | "sm";
-    hideHeader?: boolean;
-}
-
-let activePopup: any = null;
-
-function closeActivePopupIfRequested(replaceLast: boolean | undefined) {
-    if (!replaceLast || !activePopup) return;
-    const toUnmount = activePopup;
-    activePopup = null;
-    unmount(toUnmount, { outro: true });
-}
-
 export function showDialog(title: string, description: string): Promise<boolean> {
     return new Promise((resolve) => {
         const targetElement = document.querySelector("main");
@@ -145,53 +100,8 @@ export function openDataTableDrawer(studioContext: StudioContext, props: OpenDat
     });
 }
 
-export function openPopup(studioContext: StudioContext, props: OpenPopupProps) {
-    const targetElement = document.querySelector("main");
-    if (!targetElement) throw new Error("main html element doesn't exist");
-
-    closeActivePopupIfRequested(props.replaceLast);
-
-    const mounted = mount(Popup, {
-        target: targetElement,
-        context: createStudioContextMap(studioContext),
-        props: {
-            component: props.component,
-            componentProps: props.componentProps,
-            title: props.title,
-            size: props.size,
-            hideHeader: props.hideHeader,
-            onClose: async () => {
-                if (activePopup === mounted) activePopup = null;
-                await unmount(mounted, { outro: true });
-            },
-        },
-    });
-    activePopup = mounted;
-}
-
-export function openDataTablePopup(studioContext: StudioContext, props: OpenDataTablePopupProps) {
-    // DataTable reads `searchParams` once during its initial $state setup,
-    // so sort/limit need to be folded into the searchParams object before
-    // we mount. Built here in plain TS — no Svelte reactivity to escape.
-    const searchParams: Record<string, any> = {};
-    if (props.sort) searchParams.sort = props.sort;
-    if (props.limit != null) searchParams.limit = String(props.limit);
-
-    openPopup(studioContext, {
-        component: DataTable,
-        componentProps: {
-            collectionName: props.collectionName,
-            filter: props.filter,
-            searchParams,
-            showHeader: props.showHeader,
-            showFooter: props.showFooter,
-            showFilter: props.showFilter ?? false,
-            tabs: props.tabs,
-            view: props.view,
-        },
-        title: props.title ?? props.collectionName,
-        size: props.size,
-        hideHeader: props.hideHeader,
-        replaceLast: props.replaceLast,
-    });
-}
+// Popup helpers (openPopup, openDataTablePopup, goBackPopup) live in
+// `./popup` — they share enough state (active overlay, back-history)
+// to warrant their own module.
+export { openPopup, openDataTablePopup, goBackPopup } from "./popup";
+export type { OpenPopupProps, OpenDataTablePopupProps } from "./popup";

package/src/lib/components/popup/popup.svelte

@@ -6,7 +6,7 @@
 	// `openPopup` mounts this; specialised popup helpers like
 	// `openDataTablePopup` are thin wrappers that supply the body
 	// component + props.
-	import { X } from "lucide-svelte";
+	import { ArrowLeft, X } from "lucide-svelte";
 	import { fade, scale } from "svelte/transition";
 	import { cubicOut } from "svelte/easing";
 	import Portal from "svelte-portal";
@@ -28,6 +28,12 @@
 		// Use when the body brings its own header.
 		hideHeader?: boolean;
 		onClose?: () => void;
+		// Set by the action layer when there's a popup-history entry to
+		// pop. The chrome renders a back arrow in the title bar; bodies
+		// that `hideHeader: true` get `canGoBack` + `onBack` forwarded
+		// so they can render their own back affordance.
+		canGoBack?: boolean;
+		onBack?: () => void;
 	}
 
 	let {
@@ -37,6 +43,8 @@
 		size = "default",
 		hideHeader = false,
 		onClose,
+		canGoBack = false,
+		onBack,
 	}: Props = $props();
 </script>
 
@@ -54,8 +62,19 @@
 			{size === 'sm' ? 'max-h-[calc(100vh-6rem)] max-w-2xl' : 'h-[85vh] max-w-7xl'}"
 	>
 		{#if !hideHeader}
-			<div class="flex h-12 shrink-0 items-center justify-between gap-4 border-b px-4">
-				<div class="text-sm font-medium">{title ?? ""}</div>
+			<div class="flex h-12 shrink-0 items-center justify-between gap-2 border-b px-4">
+				<div class="flex min-w-0 items-center gap-2">
+					{#if canGoBack}
+						<Button
+							variant="ghost"
+							size="icon"
+							onclick={() => onBack?.()}
+							class="h-8 w-8 rounded-full text-muted-foreground"
+							Icon={ArrowLeft}
+						/>
+					{/if}
+					<div class="truncate text-sm font-medium">{title ?? ""}</div>
+				</div>
 				<Button
 					variant="ghost"
 					size="icon"
@@ -73,7 +92,7 @@
 		     percentages, which don't resolve when the popup uses
 		     `max-h` (size="sm") instead of a fixed `h`. -->
 		<div class="flex min-h-0 flex-1 flex-col overflow-hidden">
-			<Body {...componentProps} {onClose} />
+			<Body {...componentProps} {onClose} {canGoBack} {onBack} />
 		</div>
 	</div>
 </Portal>

package/src/lib/extensions/extension.types.ts

@@ -23,7 +23,8 @@ import * as Icons from "lucide-svelte"
 import { ContextMenu } from "bits-ui";
 import * as Tooltip from "../components/ui/tooltip";
 import * as Breadcrumb from "../components/ui/breadcrumb";
-import { showDialog, type OpenDataTableDrawerProps, type OpenDataTablePopupProps, type OpenPopupProps } from "../actions";
+import { showDialog, type OpenDataTableDrawerProps } from "../actions";
+import type { OpenDataTablePopupProps, OpenPopupProps } from "../popup";
 import { toast } from "svelte-sonner";
 import type Drawer from "../components/drawer.svelte";
 import { Switch } from "../components/ui/switch";

package/src/lib/extensions/extensionUtils.ts

@@ -7,7 +7,8 @@ import type {
 import type { LobbClient } from "@lobb-js/sdk";
 import type { CTX } from "../store.types";
 import { toast } from "svelte-sonner";
-import { showDialog, openDataTableDrawer, openDataTablePopup, openPopup } from "../actions";
+import { showDialog, openDataTableDrawer } from "../actions";
+import { openDataTablePopup, openPopup } from "../popup";
 import { emitEvent } from "../eventSystem";
 import { Button } from "../components/ui/button";
 import { Input } from "../components/ui/input";

package/src/lib/popup.ts

@@ -0,0 +1,147 @@
+import { mount, unmount } from "svelte";
+import DataTable from "./components/dataTable/dataTable.svelte";
+import Popup from "./components/popup/popup.svelte";
+import { createStudioContextMap, type StudioContext } from "./context";
+import type { CollectionTab } from "./store.types";
+
+export interface OpenPopupProps {
+    // Component rendered inside the popup. It receives `componentProps`
+    // spread onto it plus `onClose` so it can close the popup itself.
+    component: any;
+    componentProps?: Record<string, any>;
+    title?: string;
+    // `default` is the wide data-table popup (max-w-7xl, fixed 85vh).
+    // `sm` is the narrow detail-view variant (max-w-2xl, content-height).
+    size?: "default" | "sm";
+    // When true, the popup renders no chrome at all (no title bar, no
+    // close button). The body uses the `onClose` prop the popup passes
+    // it to render its own close affordance.
+    hideHeader?: boolean;
+    // Close the previously-opened popup before mounting this one —
+    // drill-down semantics. Only popups participate; drawers don't.
+    replaceLast?: boolean;
+}
+
+export interface OpenDataTablePopupProps {
+    collectionName: string;
+    filter?: Record<string, any>;
+    sort?: Record<string, "asc" | "desc">;
+    limit?: number;
+    title?: string;
+    showHeader?: boolean;
+    showFooter?: boolean;
+    showFilter?: boolean;
+    tabs?: CollectionTab[];
+    view?: { id: string; [key: string]: any };
+    replaceLast?: boolean;
+    size?: "default" | "sm";
+    hideHeader?: boolean;
+}
+
+let activePopup: any = null;
+// Props that produced the currently-mounted popup. Tracked so we can
+// push them onto `popupHistory` when this popup is swapped out by a
+// `replaceLast: true` opener, enabling back navigation.
+let activePopupProps: OpenPopupProps | null = null;
+// Stack of popup-props that were swapped out via `replaceLast: true`.
+// The back arrow re-opens the top of the stack; closing via X or the
+// backdrop wipes the whole stack (a deliberate full-reset, not back).
+const popupHistory: OpenPopupProps[] = [];
+
+// Internal mount path used by both `openPopup` (user-initiated) and
+// `goBackPopup` (history-driven). The `fromBack` flag suppresses
+// pushing the outgoing popup onto the history stack — when the user
+// hits Back, the popup they're leaving shouldn't reappear if they hit
+// Back again.
+function mountPopup(
+    studioContext: StudioContext,
+    props: OpenPopupProps,
+    opts: { fromBack?: boolean } = {},
+) {
+    const targetElement = document.querySelector("main");
+    if (!targetElement) throw new Error("main html element doesn't exist");
+
+    if (props.replaceLast && activePopup) {
+        // Swap: archive the outgoing popup's props (unless this open is
+        // itself a back-navigation) and unmount it. Outro plays in
+        // parallel with the new popup's intro.
+        if (!opts.fromBack && activePopupProps) {
+            popupHistory.push(activePopupProps);
+        }
+        const toUnmount = activePopup;
+        activePopup = null;
+        activePopupProps = null;
+        unmount(toUnmount, { outro: true });
+    } else if (!props.replaceLast) {
+        // A fresh, non-stacking popup starts a new context — drop any
+        // accumulated back history from the previous chain.
+        popupHistory.length = 0;
+    }
+
+    const canGoBack = popupHistory.length > 0;
+
+    const mounted = mount(Popup, {
+        target: targetElement,
+        context: createStudioContextMap(studioContext),
+        props: {
+            component: props.component,
+            componentProps: props.componentProps,
+            title: props.title,
+            size: props.size,
+            hideHeader: props.hideHeader,
+            canGoBack,
+            onBack: () => goBackPopup(studioContext),
+            onClose: async () => {
+                if (activePopup === mounted) {
+                    activePopup = null;
+                    activePopupProps = null;
+                    // X / backdrop is a full reset — nuke the back
+                    // stack so reopening anything starts fresh.
+                    popupHistory.length = 0;
+                }
+                await unmount(mounted, { outro: true });
+            },
+        },
+    });
+    activePopup = mounted;
+    activePopupProps = props;
+}
+
+export function openPopup(studioContext: StudioContext, props: OpenPopupProps) {
+    mountPopup(studioContext, props);
+}
+
+export function goBackPopup(studioContext: StudioContext) {
+    const prev = popupHistory.pop();
+    if (!prev) return;
+    // Force `replaceLast: true` so the swap+outro path runs, and tell
+    // `mountPopup` not to push the current popup onto history.
+    mountPopup(studioContext, { ...prev, replaceLast: true }, { fromBack: true });
+}
+
+export function openDataTablePopup(studioContext: StudioContext, props: OpenDataTablePopupProps) {
+    // DataTable reads `searchParams` once during its initial $state setup,
+    // so sort/limit need to be folded into the searchParams object before
+    // we mount. Built here in plain TS — no Svelte reactivity to escape.
+    const searchParams: Record<string, any> = {};
+    if (props.sort) searchParams.sort = props.sort;
+    if (props.limit != null) searchParams.limit = String(props.limit);
+
+    openPopup(studioContext, {
+        component: DataTable,
+        componentProps: {
+            collectionName: props.collectionName,
+            filter: props.filter,
+            searchParams,
+            showHeader: props.showHeader,
+            showFooter: props.showFooter,
+            showFilter: props.showFilter ?? false,
+            tabs: props.tabs,
+            view: props.view,
+        },
+        title: props.title ?? props.collectionName,
+        size: props.size,
+        hideHeader: props.hideHeader,
+        replaceLast: props.replaceLast,
+    });
+}