fix(custom-widgets): stabilize authoring flows

This commit is contained in:
Thomas Camlong committed 2026-07-20 17:55:57 +02:00
1 parent e4388b0712
commit 091eca3192
22 files changed
+454 -203

No files matched your search

@@ -7,6 +7,7 @@ import { auth } from "@homarr/auth/next";
import { BoardProvider } from "@homarr/boards/context";
import { EditModeProvider } from "@homarr/boards/edit-mode";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { ModalProvider } from "@homarr/modals";
import { MainHeader } from "~/components/layout/header";
import { BoardLogoWithTitle } from "~/components/layout/logo/board-logo";
@@ -68,17 +69,19 @@ export const createBoardLayout = <TParams extends Params>({
<BoardReadyProvider>
<EditModeProvider>
<BoardMantineProvider defaultColorScheme={colorScheme}>
<CustomCss />
<BoardTourWrapper hasSession={withTour && !!session}>
<ClientShell hasNavigation={false}>
<MainHeader
logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
actions={headerActions}
hasNavigation={false}
/>
<AppShellMain>{children}</AppShellMain>
</ClientShell>
</BoardTourWrapper>
<ModalProvider>
<CustomCss />
<BoardTourWrapper hasSession={withTour && !!session}>
<ClientShell hasNavigation={false}>
<MainHeader
logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
actions={headerActions}
hasNavigation={false}
/>
<AppShellMain>{children}</AppShellMain>
</ClientShell>
</BoardTourWrapper>
</ModalProvider>
</BoardMantineProvider>
</EditModeProvider>
</BoardReadyProvider>
@@ -39,13 +39,15 @@ export function EditorSection({
export function SaveActions({
dirty,
pending,
savePending,
previewPending,
invalid,
mode,
onPreview,
}: {
dirty: boolean;
pending: boolean;
savePending: boolean;
previewPending: boolean;
invalid: boolean;
mode: "create" | "edit";
onPreview(): void;
@@ -64,10 +66,17 @@ export function SaveActions({
</Text>
</Group>
<Group gap="xs" wrap="nowrap">
<Button type="button" variant="light" leftSection={<IconPlayerPlay size={16} />} onClick={onPreview}>
{t("action.preview")}
<Button
type="button"
variant="light"
leftSection={<IconPlayerPlay size={16} />}
onClick={onPreview}
loading={previewPending}
disabled={invalid || savePending}
>
{previewPending ? t("action.previewLoading") : t("action.preview")}
</Button>
<Button type="submit" loading={pending} disabled={invalid}>
<Button type="submit" loading={savePending} disabled={invalid || previewPending}>
{mode === "create" ? t("action.create") : t("action.save")}
</Button>
</Group>
@@ -83,7 +83,7 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
const [mobilePane, setMobilePane] = useState<"configure" | "preview">("configure");
const [request, setRequest] = useState("");
const [documentationUrl, setDocumentationUrl] = useState("");
const [preview, setPreview] = useState<PreviewState>({ data: {}, status: {}, session: null });
const [preview, setPreview] = useState<PreviewState>({ data: {}, status: {}, session: null, outcome: "idle" });
const [previewSize, setPreviewSize] = useState("standard");
const [previewTheme, setPreviewTheme] = useState<"light" | "dark">("dark");
const [optionsSnapshot, setOptionsSnapshot] = useState<Record<string, unknown>>({});
@@ -119,20 +119,21 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
[candidate, requestDiagnostics, templateDiagnostics],
);
const { save, runPreview, pasteAiResponse, copyDiagnostics, pending } = useCustomWidgetFormActions({
mode,
definitionId,
form,
candidate,
templateDiagnostics,
requestDiagnostics,
preview,
setPreview,
setMobilePane,
setOptionsSnapshot,
request,
documentationUrl,
});
const { save, runPreview, pasteAiResponse, copyDiagnostics, savePending, previewPending } =
useCustomWidgetFormActions({
mode,
definitionId,
form,
candidate,
templateDiagnostics,
requestDiagnostics,
preview,
setPreview,
setMobilePane,
setOptionsSnapshot,
request,
documentationUrl,
});
useEffect(() => {
const beforeUnload = (event: BeforeUnloadEvent) => {
@@ -254,7 +255,8 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
<Paper p="md" className={classes.mobileSaveBar} shadow="sm">
<SaveActions
dirty={form.isDirty()}
pending={pending}
savePending={savePending}
previewPending={previewPending}
invalid={invalid}
mode={mode}
onPreview={() => void runPreview()}
@@ -265,7 +267,8 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
<Paper p="md" className={classes.actionBar} shadow="sm">
<SaveActions
dirty={form.isDirty()}
pending={pending}
savePending={savePending}
previewPending={previewPending}
invalid={invalid}
mode={mode}
onPreview={() => void runPreview()}
@@ -25,6 +25,8 @@ import CustomJsxDisplay from "@homarr/widgets/custom-api/custom-jsx-display";
import { CodeEditor } from "./_code-editor";
import { isRecord, parseJson } from "./_custom-widget-form-utils";
import { getPreviewSummary, PreviewResult, PreviewStatusDot } from "./_custom-widget-preview-status";
import type { PreviewOutcome } from "./_custom-widget-preview-status";
import { PreviewActionControl } from "./_custom-widget-preview-action";
import classes from "./_custom-widget-form.module.css";
@@ -32,6 +34,7 @@ export interface PreviewState {
data: Record<string, unknown>;
status: Record<string, unknown>;
session: { id: string; expiresAt: number; liveActions: boolean } | null;
outcome: PreviewOutcome;
}
interface PreviewPanelProps {
@@ -89,6 +92,21 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
queriesDisabled: fixture !== "live",
isEditMode: fixture !== "live",
};
const previewSummary = getPreviewSummary(props.preview.status);
const previewResult =
props.preview.outcome === "success"
? {
title: t("result.success.title"),
description: t("result.success.description", previewSummary),
}
: props.preview.outcome === "error"
? {
title: t("result.error.title"),
description: t("result.error.description", previewSummary),
}
: props.preview.outcome === "loading"
? { title: t("result.loading.title"), description: t("result.loading.description") }
: { title: "", description: "" };
return (
<Card withBorder p="md">
@@ -125,11 +143,21 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
{ value: "error", label: t("fixture.error") },
]}
/>
<PreviewResult
outcome={props.preview.outcome}
title={previewResult.title}
description={previewResult.description}
/>
<Tabs defaultValue="widget" keepMounted={false}>
<Tabs.List grow>
{(["widget", "data", "options", "actions", "diagnostics"] as const).map((tab) => (
<Tabs.Tab key={tab} value={tab}>
{t(`tab.${tab}`)}
<Group gap={6} wrap="nowrap" justify="center">
{t(`tab.${tab}`)}
{tab === "data" && (
<PreviewStatusDot outcome={props.preview.outcome} label={t(`status.${props.preview.outcome}`)} />
)}
</Group>
</Tabs.Tab>
))}
</Tabs.List>
@@ -0,0 +1,54 @@
"use client";
import { Alert, Box, Text, Tooltip } from "@mantine/core";
import { isRecord } from "./_custom-widget-form-utils";
export type PreviewOutcome = "idle" | "loading" | "success" | "error";
export function PreviewResult({
outcome,
title,
description,
}: {
outcome: PreviewOutcome;
title: string;
description: string;
}) {
if (outcome === "idle") return null;
return (
<Alert color={outcome === "error" ? "red" : outcome === "success" ? "green" : "yellow"}>
<Text size="sm" fw={600}>
{title}
</Text>
<Text size="sm">{description}</Text>
</Alert>
);
}
export function PreviewStatusDot({ outcome, label }: { outcome: PreviewOutcome; label: string }) {
const colors = { idle: "gray", loading: "yellow", success: "green", error: "red" } as const;
return (
<Tooltip label={label}>
<Box
component="output"
aria-label={label}
w={8}
h={8}
bg={`var(--mantine-color-${colors[outcome]}-6)`}
style={{ borderRadius: "50%", flexShrink: 0 }}
/>
</Tooltip>
);
}
export function getPreviewSummary(status: Record<string, unknown>) {
return Object.values(status).reduce<{ succeeded: number; failed: number }>(
(summary, value) => {
if (isRecord(value) && value.ok === false) summary.failed += 1;
else summary.succeeded += 1;
return summary;
},
{ succeeded: 0, failed: 0 },
);
}
@@ -13,10 +13,10 @@ import {
parseCustomWidgetAiResponse,
} from "@homarr/custom-widgets/core";
import type { EditorDiagnostic, CustomWidgetFormValues } from "@homarr/custom-widgets/workbench";
import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
import { showErrorNotification, showSuccessNotification, showWarningNotification } from "@homarr/notifications";
import { useScopedI18n } from "@homarr/translation/client";
import { applyDefinition, buildDefinition, loadPreviewQueries } from "./_custom-widget-form-utils";
import { applyDefinition, buildDefinition, isRecord, loadPreviewQueries } from "./_custom-widget-form-utils";
import type { PreviewState } from "./_custom-widget-preview-panel";
interface FormActionsInput {
@@ -43,6 +43,7 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
const updateMutation = clientApi.customWidget.update.useMutation();
const previewMutation = clientApi.customWidget.previewCreate.useMutation();
const [importIssues, setImportIssues] = useState<string[]>([]);
const [previewPending, setPreviewPending] = useState(false);
const save = input.form.onSubmit(async (values) => {
const definition = buildDefinition(values);
@@ -93,6 +94,7 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
});
const runPreview = async () => {
if (previewPending) return;
if (!input.candidate.success) {
showErrorNotification({
title: w("section.preview"),
@@ -101,6 +103,8 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
return;
}
input.setMobilePane("preview");
input.setPreview({ data: {}, status: {}, session: null, outcome: "loading" });
setPreviewPending(true);
try {
const created = await previewMutation.mutateAsync({
definition: input.candidate.data,
@@ -115,9 +119,34 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
});
input.setOptionsSnapshot(input.candidate.data.defaultOptions);
const snapshot = await loadPreviewQueries(input.candidate.data, created.previewSession.id);
input.setPreview({ ...snapshot, session: created.previewSession });
const failed = Object.values(snapshot.status).filter((status) => isRecord(status) && status.ok === false).length;
input.setPreview({
...snapshot,
session: created.previewSession,
outcome: failed > 0 ? "error" : "success",
});
if (failed > 0) {
showWarningNotification({
title: w("preview.result.error.title"),
message: w("preview.result.error.description", {
succeeded: Object.keys(snapshot.status).length - failed,
failed,
}),
});
} else {
showSuccessNotification({
title: w("preview.result.success.title"),
message: w("preview.result.success.description", {
succeeded: Object.keys(snapshot.status).length,
failed: 0,
}),
});
}
} catch {
input.setPreview((current) => ({ ...current, outcome: "error" }));
showErrorNotification({ title: w("section.preview"), message: t("notification.previewError") });
} finally {
setPreviewPending(false);
}
};
@@ -130,7 +159,7 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
}
setImportIssues([]);
applyDefinition(input.form, customWidgetDefinitionSchema.parse(result.widget));
input.setPreview({ data: {}, status: {}, session: null });
input.setPreview({ data: {}, status: {}, session: null, outcome: "idle" });
showSuccessNotification({
title: w("ai.response"),
message:
@@ -176,6 +205,7 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
runPreview,
pasteAiResponse,
copyDiagnostics,
pending: createMutation.isPending || updateMutation.isPending,
savePending: createMutation.isPending || updateMutation.isPending,
previewPending,
};
}