@lobb-js/studio 0.45.0 → 0.47.0

package/dist/actions.d.ts

@@ -11,6 +11,14 @@ 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>;
@@ -25,9 +33,13 @@ export interface OpenDataTablePopupProps {
         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;

package/dist/actions.js

@@ -3,9 +3,18 @@ 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 DataTablePopup from "./components/dataTablePopup/dataTablePopup.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");
@@ -81,18 +90,53 @@ export function openDataTableDrawer(studioContext, props) {
         },
     });
 }
-export function openDataTablePopup(studioContext, props) {
+export function openPopup(studioContext, props) {
     const targetElement = document.querySelector("main");
     if (!targetElement)
         throw new Error("main html element doesn't exist");
-    const mounted = mount(DataTablePopup, {
+    closeActivePopupIfRequested(props.replaceLast);
+    const mounted = mount(Popup, {
         target: targetElement,
         context: createStudioContextMap(studioContext),
         props: {
-            ...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,
+    });
 }

package/dist/components/importButton.svelte

@@ -28,7 +28,20 @@
 	let isDragging = $state(false);
 	let parseError = $state("");
 	let transformedRows = $state<any[]>([]);
-	let importResults = $state<{ row: any; error: string | null }[]>([]);
+	// `action` is only set when a `studio.collections.import` workflow takes
+	// ownership of the writes (handled: true) and tells us per row whether
+	// the record was created or updated. The default code path leaves it
+	// undefined; the UI then just says "imported".
+	type ImportAction = "created" | "updated";
+	// Errors are kept structured all the way from the server (or workflow)
+	// to the UI — `details` is the per-field validation map Lobb already
+	// emits as JSON ({ field: ["msg1", "msg2"] }), so the popover can
+	// render a clean labelled list without parsing strings.
+	type ImportError = {
+		message: string;
+		details?: Record<string, string[]>;
+	};
+	let importResults = $state<{ row: any; error: ImportError | null; action?: ImportAction }[]>([]);
 	// Which results tab is visible. Defaults to "failed" when there are
 	// any failures (most users want to fix those first); falls back to
 	// "imported" when everything went through.
@@ -40,6 +53,24 @@
 
 	const collectionColumns = $derived(getCollectionColumns(ctx, collectionName) ?? []);
 
+	// Map a snake_case field id to a friendly label using the column
+	// metadata when available, falling back to Title Casing the id.
+	function fieldLabel(
+		id: string,
+		columns: Array<{ id: string; label?: string }>,
+	): string {
+		const col = columns.find((c) => c.id === id);
+		if (col?.label && col.label !== col.id) return col.label;
+		return id
+			.split("_")
+			.map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+			.join(" ");
+	}
+
+	function capitalise(s: string): string {
+		return s ? s[0].toUpperCase() + s.slice(1) : s;
+	}
+
 	function applyColumnMapping(rows: any[]): {
 		rows: any[];
 		unmapped: Array<{ column: string; sample: string }>;
@@ -168,23 +199,58 @@
 				collectionName,
 				rows: transformedRows.map((r) => ({ ...r })),
 			});
-			const finalRows = eventResult.rows ?? transformedRows;
 
 			importResults = [];
 			let hasSuccess = false;
-			for (const row of finalRows) {
-				const response = await lobb.createOne(collectionName, { data: row });
-				if (response.ok) {
-					importResults.push({ row, error: null });
+
+			if (eventResult?.handled && eventResult.results) {
+				// The workflow took ownership — it did the writes itself
+				// (typical use case: upsert-style imports where the workflow
+				// needs to decide create-vs-update per row). Render its
+				// results verbatim, no extra writes from our side.
+				const r = eventResult.results as {
+					imported?: Array<{ row: any; action: ImportAction }>;
+					failed?: Array<{ row: any; error: ImportError; action?: ImportAction }>;
+				};
+				for (const item of r.imported ?? []) {
+					importResults.push({ row: item.row, error: null, action: item.action });
 					hasSuccess = true;
-				} else {
-					const body = await response.json().catch(() => null);
-					const message = body?.details
-						? Object.entries(body.details).map(([f, msgs]) => `${f}: ${(msgs as string[]).join(", ")}`).join(" | ")
-						: (body?.message ?? `HTTP ${response.status}`);
-					importResults.push({ row, error: message });
+				}
+				for (const item of r.failed ?? []) {
+					importResults.push({ row: item.row, error: item.error, action: item.action });
+				}
+			} else {
+				// Default path — workflow only transformed rows (or did
+				// nothing). Send every row as a single batch call: each op
+				// runs independently and we get a 1:1 result array back, so
+				// one row failing doesn't stop the others and we surface
+				// failures alongside successes in a single round trip.
+				const finalRows = eventResult.rows ?? transformedRows;
+				const ops = finalRows.map((row: any) => ({
+					method: "createOne",
+					collectionName,
+					props: { data: row },
+				}));
+				const batchRes = await lobb.batch(ops);
+				const batchBody: any[] = await batchRes.json();
+				for (let i = 0; i < finalRows.length; i++) {
+					const row = finalRows[i];
+					const entry = batchBody[i];
+					if (entry?.data) {
+						importResults.push({ row, error: null });
+						hasSuccess = true;
+					} else {
+						importResults.push({
+							row,
+							error: {
+								message: entry?.message ?? `Error: ${entry?.code ?? "unknown"}`,
+								details: entry?.details,
+							},
+						});
+					}
 				}
 			}
+
 			if (hasSuccess && onSuccessfullSave) await onSuccessfullSave();
 
 			// Default to the failed tab when there are any failures; if
@@ -379,6 +445,8 @@
 		{:else if step === "results"}
 			{@const failed = importResults.filter((r) => r.error !== null)}
 			{@const succeeded = importResults.filter((r) => r.error === null)}
+			{@const createdCount = succeeded.filter((r) => r.action === "created").length}
+			{@const updatedCount = succeeded.filter((r) => r.action === "updated").length}
 			{@const failedData = failed.map((r) => ({ __error: r.error, ...r.row }))}
 			{#if failed.length === 0}
 				<!-- All rows imported successfully: nothing to audit here —
@@ -392,7 +460,11 @@
 					<div class="text-center">
 						<p class="text-sm font-medium text-foreground">Import complete</p>
 						<p class="mt-1 text-xs text-muted-foreground">
-							{succeeded.length} {succeeded.length === 1 ? "record" : "records"} imported successfully
+							{#if createdCount + updatedCount > 0}
+								{createdCount} created · {updatedCount} updated
+							{:else}
+								{succeeded.length} {succeeded.length === 1 ? "record" : "records"} imported successfully
+							{/if}
 						</p>
 					</div>
 				</div>
@@ -439,26 +511,50 @@
 						>
 							{#snippet overrideCell(value, column)}
 								{#if column.id === "__error"}
-									<!-- Error cell: truncated single-line preview in
-									     the table. Hovering reveals the full message
-									     in a tooltip with monospace + wrap so
-									     multi-line errors / JSON dumps render
-									     legibly. -->
-									<Tooltip.Provider delayDuration={150}>
+									<!-- Error cell: hover to reveal a tooltip with
+									     the structured `details` map rendered as a
+									     labelled list (friendly field names like
+									     "Top Ten" instead of "top_ten") so non-
+									     technical users can see exactly what to
+									     fix per row. -->
+									{@const err = value as ImportError}
+									{@const detailEntries = Object.entries(err?.details ?? {})}
+									<Tooltip.Provider delayDuration={120}>
 										<Tooltip.Root>
 											<Tooltip.Trigger
-												class="block w-full truncate text-left text-destructive"
+												class="group flex w-full items-center gap-1.5 text-left text-destructive"
 											>
-												{value}
+												<AlertCircle size={12} class="shrink-0" />
+												<span class="truncate group-hover:underline">{err?.message ?? ""}</span>
 											</Tooltip.Trigger>
 											<Tooltip.Content
-												class="max-w-md p-0"
+												class="w-96 p-0"
 												side="bottom"
 												align="start"
 											>
-												<div class="max-h-64 overflow-auto p-3">
-													<pre class="whitespace-pre-wrap break-words font-mono text-xs text-destructive">{value}</pre>
+												<div class="border-b px-3 py-2">
+													<p class="text-sm font-medium">This row couldn't be imported</p>
+													<p class="mt-0.5 text-xs text-muted-foreground">
+														{#if detailEntries.length > 0}
+															Fix the issue{detailEntries.length === 1 ? "" : "s"} below and try again.
+														{:else}
+															{err?.message ?? "Unknown error"}
+														{/if}
+													</p>
 												</div>
+												{#if detailEntries.length > 0}
+													<ul class="flex max-h-64 flex-col gap-1.5 overflow-auto px-3 py-2.5">
+														{#each detailEntries as [fieldId, messages]}
+															<li class="flex gap-2 text-xs">
+																<AlertCircle size={11} class="mt-0.5 shrink-0 text-destructive" />
+																<div class="min-w-0">
+																	<span class="font-semibold text-foreground">{fieldLabel(fieldId, collectionColumns)}</span>
+																	<span class="text-muted-foreground"> — {capitalise(messages.join(", "))}</span>
+																</div>
+															</li>
+														{/each}
+													</ul>
+												{/if}
 											</Tooltip.Content>
 										</Tooltip.Root>
 									</Tooltip.Provider>

package/dist/components/popup/popup.svelte

@@ -0,0 +1,79 @@
+<script lang="ts">
+	// Generic centred-modal popup chrome — backdrop, fade/scale
+	// transitions, optional title bar with close button. When
+	// `hideHeader` is true the popup renders no chrome and the body is
+	// responsible for the close affordance (it gets `onClose` as a prop).
+	// `openPopup` mounts this; specialised popup helpers like
+	// `openDataTablePopup` are thin wrappers that supply the body
+	// component + props.
+	import { X } from "lucide-svelte";
+	import { fade, scale } from "svelte/transition";
+	import { cubicOut } from "svelte/easing";
+	import Portal from "svelte-portal";
+	import Button from "../ui/button/button.svelte";
+
+	interface Props {
+		// The component rendered inside the popup body. It receives
+		// `componentProps` spread onto it plus `onClose` so it can
+		// close the popup itself when needed.
+		component: any;
+		componentProps?: Record<string, any>;
+		title?: string;
+		// `default` is wide (max-w-7xl, fixed 85vh) — for data tables.
+		// `sm` is narrow (max-w-2xl, content-height) — for detail views.
+		size?: "default" | "sm";
+		// When true, the popup renders no chrome at all — no title bar,
+		// no close button. The body is responsible for the close
+		// affordance (it can use the `onClose` prop the popup passes in).
+		// Use when the body brings its own header.
+		hideHeader?: boolean;
+		onClose?: () => void;
+	}
+
+	let {
+		component: Body,
+		componentProps = {},
+		title,
+		size = "default",
+		hideHeader = false,
+		onClose,
+	}: Props = $props();
+</script>
+
+<Portal target="body">
+	<button
+		transition:fade={{ duration: 200 }}
+		onclick={() => onClose?.()}
+		class="fixed left-0 top-0 z-40 h-screen w-screen bg-black/50 cursor-default"
+		aria-label="background used to close the popup"
+	></button>
+
+	<div
+		transition:scale={{ duration: 200, easing: cubicOut, start: 0.95 }}
+		class="fixed left-1/2 top-1/2 z-40 flex w-[95vw] -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-lg border bg-card shadow-2xl
+			{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>
+				<Button
+					variant="ghost"
+					size="icon"
+					onclick={() => onClose?.()}
+					class="h-8 w-8 rounded-full text-muted-foreground"
+					Icon={X}
+				/>
+			</div>
+		{/if}
+		<!-- Bodies own their own scrolling so they can decide what's
+		     anchored vs. scrollable (e.g. a static header above a
+		     scrolling section list). The wrapper is itself a flex
+		     column so bodies can claim a bounded height with
+		     `flex-1 min-h-0` — that avoids relying on `h-full`
+		     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} />
+		</div>
+	</div>
+</Portal>

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

@@ -0,0 +1,11 @@
+interface Props {
+    component: any;
+    componentProps?: Record<string, any>;
+    title?: string;
+    size?: "default" | "sm";
+    hideHeader?: boolean;
+    onClose?: () => void;
+}
+declare const Popup: import("svelte").Component<Props, {}, "">;
+type Popup = ReturnType<typeof Popup>;
+export default Popup;

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

@@ -23,7 +23,7 @@ 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 } from "../actions";
+import { showDialog, type OpenDataTableDrawerProps, type OpenDataTablePopupProps, type OpenPopupProps } from "../actions";
 import { toast } from "svelte-sonner";
 import { Switch } from "../components/ui/switch";
 export interface Components {
@@ -68,6 +68,14 @@ export interface ExtensionUtils {
     showDialog: typeof showDialog;
     openDataTableDrawer: (props: OpenDataTableDrawerProps) => void;
     openDataTablePopup: (props: OpenDataTablePopupProps) => void;
+    /**
+     * Mount any Svelte component inside the standard popup chrome
+     * (backdrop, fade/scale transitions, close button, optional title
+     * bar, optional `replaceLast` swap with the active overlay). The
+     * body component receives `componentProps` spread onto it plus
+     * `onClose` so it can dismiss the popup itself.
+     */
+    openPopup: (props: OpenPopupProps) => void;
     emitEvent: (eventName: string, input: any) => Promise<any>;
     /**
      * Shorthand for the standalone `isHidden(ctx, id)` helper — returns

package/dist/extensions/extensionUtils.js

@@ -1,5 +1,5 @@
 import { toast } from "svelte-sonner";
-import { showDialog, openDataTableDrawer, openDataTablePopup } from "../actions";
+import { showDialog, openDataTableDrawer, openDataTablePopup, openPopup } from "../actions";
 import { emitEvent } from "../eventSystem";
 import { Button } from "../components/ui/button";
 import { Input } from "../components/ui/input";
@@ -59,6 +59,7 @@ export function getExtensionUtils(lobb, ctx) {
         showDialog: showDialog,
         openDataTableDrawer: (props) => openDataTableDrawer({ lobb, ctx }, props),
         openDataTablePopup: (props) => openDataTablePopup({ lobb, ctx }, props),
+        openPopup: (props) => openPopup({ lobb, ctx }, props),
         emitEvent: (eventName, input) => emitEvent({ lobb, ctx }, eventName, input),
         isHidden: (id) => ctx.meta?.ui?.hide?.[id] === true,
         components: getComponents(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lobb-js/studio",
   "license": "UNLICENSED",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "postpublish": "./scripts/postpublish.sh"
   },
   "devDependencies": {
-    "@lobb-js/core": "^0.39.0",
+    "@lobb-js/core": "^0.40.0",
     "@chromatic-com/storybook": "^4.1.2",
     "@playwright/test": "^1.60.0",
     "@storybook/addon-a11y": "^10.0.1",
@@ -91,7 +91,7 @@
     "@codemirror/view": "^6.39.12",
     "@dagrejs/dagre": "^1.1.5",
     "@internationalized/date": "^3.12.0",
-    "@lobb-js/sdk": "^0.3.0",
+    "@lobb-js/sdk": "^0.4.0",
     "@lucide/svelte": "^0.563.1",
     "@tailwindcss/vite": "^4.3.0",
     "@tiptap/core": "^3.0.0",

package/src/lib/actions.ts

@@ -3,7 +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 DataTablePopup from "./components/dataTablePopup/dataTablePopup.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";
@@ -21,6 +22,24 @@ 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>;
@@ -32,6 +51,18 @@ export interface OpenDataTablePopupProps {
     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> {
@@ -114,18 +145,53 @@ export function openDataTableDrawer(studioContext: StudioContext, props: OpenDat
     });
 }
 
-export function openDataTablePopup(studioContext: StudioContext, props: OpenDataTablePopupProps) {
+export function openPopup(studioContext: StudioContext, props: OpenPopupProps) {
     const targetElement = document.querySelector("main");
     if (!targetElement) throw new Error("main html element doesn't exist");
 
-    const mounted = mount(DataTablePopup, {
+    closeActivePopupIfRequested(props.replaceLast);
+
+    const mounted = mount(Popup, {
         target: targetElement,
         context: createStudioContextMap(studioContext),
         props: {
-            ...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,
+    });
 }

package/src/lib/components/importButton.svelte

@@ -28,7 +28,20 @@
 	let isDragging = $state(false);
 	let parseError = $state("");
 	let transformedRows = $state<any[]>([]);
-	let importResults = $state<{ row: any; error: string | null }[]>([]);
+	// `action` is only set when a `studio.collections.import` workflow takes
+	// ownership of the writes (handled: true) and tells us per row whether
+	// the record was created or updated. The default code path leaves it
+	// undefined; the UI then just says "imported".
+	type ImportAction = "created" | "updated";
+	// Errors are kept structured all the way from the server (or workflow)
+	// to the UI — `details` is the per-field validation map Lobb already
+	// emits as JSON ({ field: ["msg1", "msg2"] }), so the popover can
+	// render a clean labelled list without parsing strings.
+	type ImportError = {
+		message: string;
+		details?: Record<string, string[]>;
+	};
+	let importResults = $state<{ row: any; error: ImportError | null; action?: ImportAction }[]>([]);
 	// Which results tab is visible. Defaults to "failed" when there are
 	// any failures (most users want to fix those first); falls back to
 	// "imported" when everything went through.
@@ -40,6 +53,24 @@
 
 	const collectionColumns = $derived(getCollectionColumns(ctx, collectionName) ?? []);
 
+	// Map a snake_case field id to a friendly label using the column
+	// metadata when available, falling back to Title Casing the id.
+	function fieldLabel(
+		id: string,
+		columns: Array<{ id: string; label?: string }>,
+	): string {
+		const col = columns.find((c) => c.id === id);
+		if (col?.label && col.label !== col.id) return col.label;
+		return id
+			.split("_")
+			.map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+			.join(" ");
+	}
+
+	function capitalise(s: string): string {
+		return s ? s[0].toUpperCase() + s.slice(1) : s;
+	}
+
 	function applyColumnMapping(rows: any[]): {
 		rows: any[];
 		unmapped: Array<{ column: string; sample: string }>;
@@ -168,23 +199,58 @@
 				collectionName,
 				rows: transformedRows.map((r) => ({ ...r })),
 			});
-			const finalRows = eventResult.rows ?? transformedRows;
 
 			importResults = [];
 			let hasSuccess = false;
-			for (const row of finalRows) {
-				const response = await lobb.createOne(collectionName, { data: row });
-				if (response.ok) {
-					importResults.push({ row, error: null });
+
+			if (eventResult?.handled && eventResult.results) {
+				// The workflow took ownership — it did the writes itself
+				// (typical use case: upsert-style imports where the workflow
+				// needs to decide create-vs-update per row). Render its
+				// results verbatim, no extra writes from our side.
+				const r = eventResult.results as {
+					imported?: Array<{ row: any; action: ImportAction }>;
+					failed?: Array<{ row: any; error: ImportError; action?: ImportAction }>;
+				};
+				for (const item of r.imported ?? []) {
+					importResults.push({ row: item.row, error: null, action: item.action });
 					hasSuccess = true;
-				} else {
-					const body = await response.json().catch(() => null);
-					const message = body?.details
-						? Object.entries(body.details).map(([f, msgs]) => `${f}: ${(msgs as string[]).join(", ")}`).join(" | ")
-						: (body?.message ?? `HTTP ${response.status}`);
-					importResults.push({ row, error: message });
+				}
+				for (const item of r.failed ?? []) {
+					importResults.push({ row: item.row, error: item.error, action: item.action });
+				}
+			} else {
+				// Default path — workflow only transformed rows (or did
+				// nothing). Send every row as a single batch call: each op
+				// runs independently and we get a 1:1 result array back, so
+				// one row failing doesn't stop the others and we surface
+				// failures alongside successes in a single round trip.
+				const finalRows = eventResult.rows ?? transformedRows;
+				const ops = finalRows.map((row: any) => ({
+					method: "createOne",
+					collectionName,
+					props: { data: row },
+				}));
+				const batchRes = await lobb.batch(ops);
+				const batchBody: any[] = await batchRes.json();
+				for (let i = 0; i < finalRows.length; i++) {
+					const row = finalRows[i];
+					const entry = batchBody[i];
+					if (entry?.data) {
+						importResults.push({ row, error: null });
+						hasSuccess = true;
+					} else {
+						importResults.push({
+							row,
+							error: {
+								message: entry?.message ?? `Error: ${entry?.code ?? "unknown"}`,
+								details: entry?.details,
+							},
+						});
+					}
 				}
 			}
+
 			if (hasSuccess && onSuccessfullSave) await onSuccessfullSave();
 
 			// Default to the failed tab when there are any failures; if
@@ -379,6 +445,8 @@
 		{:else if step === "results"}
 			{@const failed = importResults.filter((r) => r.error !== null)}
 			{@const succeeded = importResults.filter((r) => r.error === null)}
+			{@const createdCount = succeeded.filter((r) => r.action === "created").length}
+			{@const updatedCount = succeeded.filter((r) => r.action === "updated").length}
 			{@const failedData = failed.map((r) => ({ __error: r.error, ...r.row }))}
 			{#if failed.length === 0}
 				<!-- All rows imported successfully: nothing to audit here —
@@ -392,7 +460,11 @@
 					<div class="text-center">
 						<p class="text-sm font-medium text-foreground">Import complete</p>
 						<p class="mt-1 text-xs text-muted-foreground">
-							{succeeded.length} {succeeded.length === 1 ? "record" : "records"} imported successfully
+							{#if createdCount + updatedCount > 0}
+								{createdCount} created · {updatedCount} updated
+							{:else}
+								{succeeded.length} {succeeded.length === 1 ? "record" : "records"} imported successfully
+							{/if}
 						</p>
 					</div>
 				</div>
@@ -439,26 +511,50 @@
 						>
 							{#snippet overrideCell(value, column)}
 								{#if column.id === "__error"}
-									<!-- Error cell: truncated single-line preview in
-									     the table. Hovering reveals the full message
-									     in a tooltip with monospace + wrap so
-									     multi-line errors / JSON dumps render
-									     legibly. -->
-									<Tooltip.Provider delayDuration={150}>
+									<!-- Error cell: hover to reveal a tooltip with
+									     the structured `details` map rendered as a
+									     labelled list (friendly field names like
+									     "Top Ten" instead of "top_ten") so non-
+									     technical users can see exactly what to
+									     fix per row. -->
+									{@const err = value as ImportError}
+									{@const detailEntries = Object.entries(err?.details ?? {})}
+									<Tooltip.Provider delayDuration={120}>
 										<Tooltip.Root>
 											<Tooltip.Trigger
-												class="block w-full truncate text-left text-destructive"
+												class="group flex w-full items-center gap-1.5 text-left text-destructive"
 											>
-												{value}
+												<AlertCircle size={12} class="shrink-0" />
+												<span class="truncate group-hover:underline">{err?.message ?? ""}</span>
 											</Tooltip.Trigger>
 											<Tooltip.Content
-												class="max-w-md p-0"
+												class="w-96 p-0"
 												side="bottom"
 												align="start"
 											>
-												<div class="max-h-64 overflow-auto p-3">
-													<pre class="whitespace-pre-wrap break-words font-mono text-xs text-destructive">{value}</pre>
+												<div class="border-b px-3 py-2">
+													<p class="text-sm font-medium">This row couldn't be imported</p>
+													<p class="mt-0.5 text-xs text-muted-foreground">
+														{#if detailEntries.length > 0}
+															Fix the issue{detailEntries.length === 1 ? "" : "s"} below and try again.
+														{:else}
+															{err?.message ?? "Unknown error"}
+														{/if}
+													</p>
 												</div>
+												{#if detailEntries.length > 0}
+													<ul class="flex max-h-64 flex-col gap-1.5 overflow-auto px-3 py-2.5">
+														{#each detailEntries as [fieldId, messages]}
+															<li class="flex gap-2 text-xs">
+																<AlertCircle size={11} class="mt-0.5 shrink-0 text-destructive" />
+																<div class="min-w-0">
+																	<span class="font-semibold text-foreground">{fieldLabel(fieldId, collectionColumns)}</span>
+																	<span class="text-muted-foreground"> — {capitalise(messages.join(", "))}</span>
+																</div>
+															</li>
+														{/each}
+													</ul>
+												{/if}
 											</Tooltip.Content>
 										</Tooltip.Root>
 									</Tooltip.Provider>

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

@@ -0,0 +1,79 @@
+<script lang="ts">
+	// Generic centred-modal popup chrome — backdrop, fade/scale
+	// transitions, optional title bar with close button. When
+	// `hideHeader` is true the popup renders no chrome and the body is
+	// responsible for the close affordance (it gets `onClose` as a prop).
+	// `openPopup` mounts this; specialised popup helpers like
+	// `openDataTablePopup` are thin wrappers that supply the body
+	// component + props.
+	import { X } from "lucide-svelte";
+	import { fade, scale } from "svelte/transition";
+	import { cubicOut } from "svelte/easing";
+	import Portal from "svelte-portal";
+	import Button from "../ui/button/button.svelte";
+
+	interface Props {
+		// The component rendered inside the popup body. It receives
+		// `componentProps` spread onto it plus `onClose` so it can
+		// close the popup itself when needed.
+		component: any;
+		componentProps?: Record<string, any>;
+		title?: string;
+		// `default` is wide (max-w-7xl, fixed 85vh) — for data tables.
+		// `sm` is narrow (max-w-2xl, content-height) — for detail views.
+		size?: "default" | "sm";
+		// When true, the popup renders no chrome at all — no title bar,
+		// no close button. The body is responsible for the close
+		// affordance (it can use the `onClose` prop the popup passes in).
+		// Use when the body brings its own header.
+		hideHeader?: boolean;
+		onClose?: () => void;
+	}
+
+	let {
+		component: Body,
+		componentProps = {},
+		title,
+		size = "default",
+		hideHeader = false,
+		onClose,
+	}: Props = $props();
+</script>
+
+<Portal target="body">
+	<button
+		transition:fade={{ duration: 200 }}
+		onclick={() => onClose?.()}
+		class="fixed left-0 top-0 z-40 h-screen w-screen bg-black/50 cursor-default"
+		aria-label="background used to close the popup"
+	></button>
+
+	<div
+		transition:scale={{ duration: 200, easing: cubicOut, start: 0.95 }}
+		class="fixed left-1/2 top-1/2 z-40 flex w-[95vw] -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-lg border bg-card shadow-2xl
+			{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>
+				<Button
+					variant="ghost"
+					size="icon"
+					onclick={() => onClose?.()}
+					class="h-8 w-8 rounded-full text-muted-foreground"
+					Icon={X}
+				/>
+			</div>
+		{/if}
+		<!-- Bodies own their own scrolling so they can decide what's
+		     anchored vs. scrollable (e.g. a static header above a
+		     scrolling section list). The wrapper is itself a flex
+		     column so bodies can claim a bounded height with
+		     `flex-1 min-h-0` — that avoids relying on `h-full`
+		     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} />
+		</div>
+	</div>
+</Portal>

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

@@ -23,7 +23,7 @@ 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 } from "../actions";
+import { showDialog, type OpenDataTableDrawerProps, type OpenDataTablePopupProps, type OpenPopupProps } from "../actions";
 import { toast } from "svelte-sonner";
 import type Drawer from "../components/drawer.svelte";
 import { Switch } from "../components/ui/switch";
@@ -72,6 +72,14 @@ export interface ExtensionUtils {
     showDialog: typeof showDialog;
     openDataTableDrawer: (props: OpenDataTableDrawerProps) => void;
     openDataTablePopup: (props: OpenDataTablePopupProps) => void;
+    /**
+     * Mount any Svelte component inside the standard popup chrome
+     * (backdrop, fade/scale transitions, close button, optional title
+     * bar, optional `replaceLast` swap with the active overlay). The
+     * body component receives `componentProps` spread onto it plus
+     * `onClose` so it can dismiss the popup itself.
+     */
+    openPopup: (props: OpenPopupProps) => void;
     emitEvent: (eventName: string, input: any) => Promise<any>;
     /**
      * Shorthand for the standalone `isHidden(ctx, id)` helper — returns

package/src/lib/extensions/extensionUtils.ts

@@ -7,7 +7,7 @@ import type {
 import type { LobbClient } from "@lobb-js/sdk";
 import type { CTX } from "../store.types";
 import { toast } from "svelte-sonner";
-import { showDialog, openDataTableDrawer, openDataTablePopup } from "../actions";
+import { showDialog, openDataTableDrawer, openDataTablePopup, openPopup } from "../actions";
 import { emitEvent } from "../eventSystem";
 import { Button } from "../components/ui/button";
 import { Input } from "../components/ui/input";
@@ -69,6 +69,7 @@ export function getExtensionUtils(lobb: LobbClient, ctx: CTX): ExtensionUtils {
     showDialog: showDialog,
     openDataTableDrawer: (props) => openDataTableDrawer({ lobb, ctx }, props),
     openDataTablePopup: (props) => openDataTablePopup({ lobb, ctx }, props),
+    openPopup: (props) => openPopup({ lobb, ctx }, props),
     emitEvent: (eventName, input) => emitEvent({ lobb, ctx }, eventName, input),
     isHidden: (id) => ctx.meta?.ui?.hide?.[id] === true,
     components: getComponents(),

package/dist/components/dataTablePopup/dataTablePopup.svelte

@@ -1,94 +0,0 @@
-<script lang="ts">
-	import { X } from "lucide-svelte";
-	import { untrack } from "svelte";
-	import { fade, scale } from "svelte/transition";
-	import { cubicOut } from "svelte/easing";
-	import Portal from "svelte-portal";
-	import Button from "../ui/button/button.svelte";
-	import DataTable from "../dataTable/dataTable.svelte";
-	import type { TableProps } from "../dataTable/table.svelte";
-	import type { CollectionTab } from "../../store.types";
-
-	interface Props {
-		collectionName: string;
-		filter?: Record<string, any>;
-		sort?: Record<string, "asc" | "desc">;
-		limit?: number;
-		title?: string;
-		showHeader?: boolean;
-		showFooter?: boolean;
-		// Popups are usually opened from chart drill-downs with a
-		// preset filter — re-filtering inside the popup almost never
-		// makes sense, so the filter button is hidden by default here.
-		// Pass showFilter={true} to surface it.
-		showFilter?: boolean;
-		tableProps?: Partial<TableProps>;
-		tabs?: CollectionTab[];
-		view?: { id: string; [key: string]: any };
-		onClose?: () => void;
-	}
-
-	let {
-		collectionName,
-		filter,
-		sort,
-		limit,
-		title,
-		showHeader = true,
-		showFooter = true,
-		showFilter = false,
-		tableProps,
-		tabs,
-		view,
-		onClose,
-	}: Props = $props();
-
-	// Read once on mount — sort/limit are fixed for the popup's lifetime,
-	// and DataTable only reads searchParams during its initial $state setup
-	// so even live updates wouldn't propagate. untrack makes that intent
-	// explicit and silences Svelte's "captures initial value" warning.
-	const searchParams = untrack(() => {
-		const p: Record<string, any> = {};
-		if (sort) p.sort = sort;
-		if (limit != null) p.limit = String(limit);
-		return p;
-	});
-</script>
-
-<Portal target="body">
-	<button
-		transition:fade={{ duration: 200 }}
-		onclick={() => onClose?.()}
-		class="fixed left-0 top-0 z-40 h-screen w-screen bg-black/50 cursor-default"
-		aria-label="background used to close the popup"
-	></button>
-
-	<div
-		transition:scale={{ duration: 200, easing: cubicOut, start: 0.95 }}
-		class="fixed left-1/2 top-1/2 z-40 flex h-[85vh] w-[95vw] max-w-7xl -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-lg border bg-card shadow-2xl"
-	>
-		<div class="flex h-12 shrink-0 items-center justify-between gap-4 border-b px-4">
-			<div class="text-sm font-medium">{title ?? collectionName}</div>
-			<Button
-				variant="ghost"
-				size="icon"
-				onclick={() => onClose?.()}
-				class="h-8 w-8 rounded-full text-muted-foreground"
-				Icon={X}
-			/>
-		</div>
-		<div class="min-h-0 flex-1 overflow-auto">
-			<DataTable
-				{collectionName}
-				{filter}
-				{searchParams}
-				{showHeader}
-				{showFooter}
-				{showFilter}
-				{tableProps}
-				{tabs}
-				{view}
-			/>
-		</div>
-	</div>
-</Portal>

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

@@ -1,22 +0,0 @@
-import type { TableProps } from "../dataTable/table.svelte";
-import type { CollectionTab } from "../../store.types";
-interface Props {
-    collectionName: string;
-    filter?: Record<string, any>;
-    sort?: Record<string, "asc" | "desc">;
-    limit?: number;
-    title?: string;
-    showHeader?: boolean;
-    showFooter?: boolean;
-    showFilter?: boolean;
-    tableProps?: Partial<TableProps>;
-    tabs?: CollectionTab[];
-    view?: {
-        id: string;
-        [key: string]: any;
-    };
-    onClose?: () => void;
-}
-declare const DataTablePopup: import("svelte").Component<Props, {}, "">;
-type DataTablePopup = ReturnType<typeof DataTablePopup>;
-export default DataTablePopup;

package/src/lib/components/dataTablePopup/dataTablePopup.svelte

@@ -1,94 +0,0 @@
-<script lang="ts">
-	import { X } from "lucide-svelte";
-	import { untrack } from "svelte";
-	import { fade, scale } from "svelte/transition";
-	import { cubicOut } from "svelte/easing";
-	import Portal from "svelte-portal";
-	import Button from "../ui/button/button.svelte";
-	import DataTable from "../dataTable/dataTable.svelte";
-	import type { TableProps } from "../dataTable/table.svelte";
-	import type { CollectionTab } from "../../store.types";
-
-	interface Props {
-		collectionName: string;
-		filter?: Record<string, any>;
-		sort?: Record<string, "asc" | "desc">;
-		limit?: number;
-		title?: string;
-		showHeader?: boolean;
-		showFooter?: boolean;
-		// Popups are usually opened from chart drill-downs with a
-		// preset filter — re-filtering inside the popup almost never
-		// makes sense, so the filter button is hidden by default here.
-		// Pass showFilter={true} to surface it.
-		showFilter?: boolean;
-		tableProps?: Partial<TableProps>;
-		tabs?: CollectionTab[];
-		view?: { id: string; [key: string]: any };
-		onClose?: () => void;
-	}
-
-	let {
-		collectionName,
-		filter,
-		sort,
-		limit,
-		title,
-		showHeader = true,
-		showFooter = true,
-		showFilter = false,
-		tableProps,
-		tabs,
-		view,
-		onClose,
-	}: Props = $props();
-
-	// Read once on mount — sort/limit are fixed for the popup's lifetime,
-	// and DataTable only reads searchParams during its initial $state setup
-	// so even live updates wouldn't propagate. untrack makes that intent
-	// explicit and silences Svelte's "captures initial value" warning.
-	const searchParams = untrack(() => {
-		const p: Record<string, any> = {};
-		if (sort) p.sort = sort;
-		if (limit != null) p.limit = String(limit);
-		return p;
-	});
-</script>
-
-<Portal target="body">
-	<button
-		transition:fade={{ duration: 200 }}
-		onclick={() => onClose?.()}
-		class="fixed left-0 top-0 z-40 h-screen w-screen bg-black/50 cursor-default"
-		aria-label="background used to close the popup"
-	></button>
-
-	<div
-		transition:scale={{ duration: 200, easing: cubicOut, start: 0.95 }}
-		class="fixed left-1/2 top-1/2 z-40 flex h-[85vh] w-[95vw] max-w-7xl -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-lg border bg-card shadow-2xl"
-	>
-		<div class="flex h-12 shrink-0 items-center justify-between gap-4 border-b px-4">
-			<div class="text-sm font-medium">{title ?? collectionName}</div>
-			<Button
-				variant="ghost"
-				size="icon"
-				onclick={() => onClose?.()}
-				class="h-8 w-8 rounded-full text-muted-foreground"
-				Icon={X}
-			/>
-		</div>
-		<div class="min-h-0 flex-1 overflow-auto">
-			<DataTable
-				{collectionName}
-				{filter}
-				{searchParams}
-				{showHeader}
-				{showFooter}
-				{showFilter}
-				{tableProps}
-				{tabs}
-				{view}
-			/>
-		</div>
-	</div>
-</Portal>