feat(custom-widgets): complete Custom JSX v2 (#6390)

packages/widgets/src/_inputs/index.ts

@@ -2,6 +2,7 @@ import type { WidgetOptionType } from "../options";
 import { WidgetAnchorNoteInput } from "./widget-anchor-note-input";
 import { WidgetAppInput } from "./widget-app-input";
 import { WidgetCustomWidgetSelectInput } from "./widget-custom-widget-select-input";
+import { WidgetCustomWidgetConfigurationInput } from "./widget-custom-widget-configuration-input";
 import { WidgetDynamicSelectInput } from "./widget-dynamic-select-input";
 import { WidgetLocationInput } from "./widget-location-input";
 import { WidgetMultiTextInput } from "./widget-multi-text-input";
@@ -18,8 +19,10 @@ import { WidgetUmamiEventNamesInput } from "./widget-umami-event-names-input";
 import { WidgetUmamiWebsiteInput } from "./widget-umami-website-input";
 import { WidgetIntegrationSelectInput } from "./widget-integration-select-input";
 import { WidgetIntegrationMultiSelectInput } from "./widget-integration-multi-select-input";
+import { WidgetInternalInput } from "./widget-internal-input";
 
 const mapping = {
+  internal: WidgetInternalInput,
   anchorNote: WidgetAnchorNoteInput,
   text: WidgetTextInput,
   location: WidgetLocationInput,
@@ -37,6 +40,7 @@ const mapping = {
   umamiEventNames: WidgetUmamiEventNamesInput,
   umamiWebsite: WidgetUmamiWebsiteInput,
   customWidgetSelect: WidgetCustomWidgetSelectInput,
+  customWidgetConfiguration: WidgetCustomWidgetConfigurationInput,
   integrationSelect: WidgetIntegrationSelectInput,
   integrationMultiSelect: WidgetIntegrationMultiSelectInput,
 } satisfies Record<WidgetOptionType, unknown>;

packages/widgets/src/_inputs/widget-custom-widget-configuration-input.tsx

@@ -0,0 +1,330 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import {
+  Accordion,
+  Alert,
+  ColorInput,
+  MultiSelect,
+  NumberInput,
+  Select,
+  Slider,
+  Stack,
+  Switch,
+  Text,
+  Textarea,
+  TextInput,
+} from "@mantine/core";
+import { DateInput, TimeInput } from "@mantine/dates";
+import { IconAlertTriangle } from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import { useOptionalBoard } from "@homarr/boards/context";
+import type { CustomWidgetOption } from "@homarr/custom-widgets/core";
+import { validateCustomWidgetOptions } from "@homarr/custom-widgets/core";
+import { CustomWidgetCodeEditor } from "@homarr/custom-widgets/workbench";
+import type { CustomWidgetEditorMessages } from "@homarr/custom-widgets/workbench";
+import { IconPicker } from "@homarr/forms-collection";
+import { useScopedI18n } from "@homarr/translation/client";
+
+import type { CommonWidgetInputProps } from "./common";
+import { useFormContext } from "./form";
+
+export const WidgetCustomWidgetConfigurationInput = ({
+  property,
+}: CommonWidgetInputProps<"customWidgetConfiguration">) => {
+  const form = useFormContext();
+  const labels = useScopedI18n("widget.customApi.configuration");
+  const board = useOptionalBoard();
+  const definitionId = typeof form.values.options.definitionId === "string" ? form.values.options.definitionId : "";
+  const configurationValue = form.values.options[property];
+  const configuration = useMemo(() => (isRecord(configurationValue) ? configurationValue : {}), [configurationValue]);
+  const available = clientApi.customWidget.available.useQuery(
+    { boardId: board?.id ?? "", currentId: definitionId || undefined },
+    { enabled: board !== null && Boolean(definitionId) },
+  );
+  const definition = available.data?.find((candidate) => candidate.id === definitionId);
+  const options = isRecord(definition?.options) ? (definition.options as Record<string, CustomWidgetOption>) : null;
+  const issues = useMemo(
+    () => (options ? validateCustomWidgetOptions(options, configuration) : []),
+    [configuration, options],
+  );
+
+  useEffect(() => {
+    const path = `options.${property}`;
+    if (issues[0]) form.setFieldError(path, `${issues[0].path}: ${issues[0].message}`);
+    else form.clearFieldError(path);
+  }, [form, issues, property]);
+
+  if (!definitionId || !options) return null;
+  const entries = Object.entries(options);
+  const regular = entries.filter(([, option]) => !option.advanced);
+  const advanced = entries.filter(([, option]) => option.advanced);
+  return (
+    <Stack gap="md">
+      {issues[0] && (
+        <Alert color="yellow" variant="light" icon={<IconAlertTriangle size={16} />}>
+          <Text size="sm">{labels("needsAttention", { message: issues[0].message })}</Text>
+        </Alert>
+      )}
+      {regular.map(([name, option]) => (
+        <OptionField
+          key={name}
+          option={option}
+          path={`options.${property}.${name}`}
+          configuration={configuration}
+          definitionId={definitionId}
+        />
+      ))}
+      {advanced.length > 0 && (
+        <Accordion variant="contained">
+          <Accordion.Item value="advanced-options">
+            <Accordion.Control>{labels("advancedOptions")}</Accordion.Control>
+            <Accordion.Panel>
+              <Stack gap="sm">
+                {advanced.map(([name, option]) => (
+                  <OptionField
+                    key={name}
+                    option={option}
+                    path={`options.${property}.${name}`}
+                    configuration={configuration}
+                    definitionId={definitionId}
+                  />
+                ))}
+              </Stack>
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      )}
+    </Stack>
+  );
+};
+
+function OptionField({
+  option,
+  path,
+  configuration,
+  definitionId,
+}: {
+  option: CustomWidgetOption;
+  path: string;
+  configuration: Record<string, unknown>;
+  definitionId: string;
+}) {
+  const form = useFormContext();
+  const input = form.getInputProps(path, { type: option.control === "switch" ? "checkbox" : "input" });
+  const common = { label: option.label, description: option.description };
+  if (option.choicesFrom)
+    return <DynamicOptionField option={option} path={path} configuration={configuration} definitionId={definitionId} />;
+  if (option.control === "switch") return <Switch {...common} {...input} />;
+  if (["number", "duration"].includes(option.control))
+    return <NumberInput {...common} min={option.min} max={option.max} step={option.step} {...input} />;
+  if (option.control === "slider")
+    return (
+      <Stack gap={4}>
+        <Text size="sm" fw={500}>
+          {option.label}
+        </Text>
+        {option.description && (
+          <Text size="xs" c="dimmed">
+            {option.description}
+          </Text>
+        )}
+        <Slider min={option.min ?? 0} max={option.max ?? 100} step={option.step ?? 1} {...input} />
+      </Stack>
+    );
+  const choices = option.choices?.map((choice) => ({ label: choice.label, value: String(choice.value) })) ?? [];
+  if (option.control === "select")
+    return (
+      <Select
+        {...common}
+        data={choices}
+        value={input.value == null ? null : String(input.value)}
+        onChange={(value) => form.setFieldValue(path, coerceChoice(value, option))}
+      />
+    );
+  if (option.control === "multiSelect")
+    return (
+      <MultiSelect
+        {...common}
+        data={choices}
+        value={Array.isArray(input.value) ? input.value.map(String) : []}
+        onChange={(value) =>
+          form.setFieldValue(
+            path,
+            value.map((entry) => coerceChoice(entry, option)),
+          )
+        }
+      />
+    );
+  if (option.control === "textarea") return <Textarea {...common} autosize minRows={3} {...input} />;
+  if (option.control === "color") return <ColorInput {...common} {...input} />;
+  if (option.control === "date") return <DateInput {...common} valueFormat="YYYY-MM-DD" {...input} />;
+  if (option.control === "time") return <TimeInput {...common} {...input} />;
+  if (option.control === "icon") return <IconPicker withAsterisk={false} {...input} />;
+  if (option.control === "timeZone")
+    return <Select {...common} searchable data={Intl.supportedValuesOf("timeZone")} {...input} />;
+  if (option.control === "json")
+    return (
+      <JsonOption
+        label={option.label}
+        description={option.description}
+        value={input.value}
+        onChange={(value) => form.setFieldValue(path, value)}
+      />
+    );
+  return <TextInput {...common} type={option.control === "url" ? "url" : "text"} {...input} />;
+}
+
+function DynamicOptionField({
+  option,
+  path,
+  configuration,
+  definitionId,
+}: {
+  option: CustomWidgetOption;
+  path: string;
+  configuration: Record<string, unknown>;
+  definitionId: string;
+}) {
+  const form = useFormContext();
+  const board = useOptionalBoard();
+  const source = option.choicesFrom;
+  if (!source) return null;
+  const query = clientApi.customWidget.optionRequest.useQuery(
+    {
+      boardId: board?.id ?? "",
+      definitionId,
+      requestId: source.request,
+      params: primitiveConfiguration(configuration),
+    },
+    { enabled: Boolean(board?.id && definitionId && source.request) },
+  );
+  const collection = source.itemsPath ? getByPath(query.data?.data, source.itemsPath) : query.data?.data;
+  const data = (Array.isArray(collection) ? collection : []).flatMap((row) => {
+    const value = getByPath(row, source.valuePath);
+    const label = getByPath(row, source.labelPath);
+    return typeof value === "string" || typeof value === "number"
+      ? [{ value: String(value), label: String(label ?? value) }]
+      : [];
+  });
+  const input = form.getInputProps(path);
+  const common = {
+    label: option.label,
+    description: option.description,
+    data,
+    searchable: true,
+    disabled: query.isError,
+    rightSection: query.isFetching ? "…" : undefined,
+  };
+  if (option.control === "multiSelect")
+    return (
+      <MultiSelect
+        {...common}
+        value={Array.isArray(input.value) ? input.value.map(String) : []}
+        onChange={(value) =>
+          form.setFieldValue(
+            path,
+            value.map((entry) => coerceChoice(entry, option)),
+          )
+        }
+      />
+    );
+  return (
+    <Select
+      {...common}
+      value={input.value == null ? null : String(input.value)}
+      onChange={(value) => form.setFieldValue(path, coerceChoice(value, option))}
+    />
+  );
+}
+
+const editorMessages: CustomWidgetEditorMessages = {
+  languageJsx: "JSX",
+  languageJson: "JSON",
+  undo: "Undo",
+  redo: "Redo",
+  components: "Components",
+  componentSearch: "Search components",
+  componentEmpty: "No components",
+  componentCount: (count) => `${count} components`,
+  insertStarter: "Insert starter",
+  format: "Format",
+  copy: "Copy",
+  copied: "Copied",
+  schema: "Schema",
+  schemaTab: "JSON Schema",
+  minimalTab: "Minimal",
+  fullTab: "Full",
+  errors: (count) => `${count} errors`,
+  warnings: (count) => `${count} warnings`,
+  ready: "Ready",
+  position: ({ line, column }) => `Ln ${line}, Col ${column}`,
+  characters: (count, limit) => (limit ? `${count} / ${limit}` : `${count} characters`),
+  diagnosticsTitle: "Diagnostics",
+  diagnostic: (diagnostic) => diagnostic.value ?? diagnostic.code,
+};
+
+function JsonOption({
+  label,
+  description,
+  value,
+  onChange,
+}: {
+  label: string;
+  description?: string;
+  value: unknown;
+  onChange(value: unknown): void;
+}) {
+  const [draft, setDraft] = useState(() => JSON.stringify(value ?? null, null, 2));
+  const [error, setError] = useState<string>();
+  return (
+    <CustomWidgetCodeEditor
+      id={`${label}-json-option`}
+      label={label}
+      description={description}
+      language="json"
+      value={draft}
+      height="160px"
+      error={error}
+      onChange={(next) => {
+        setDraft(next);
+        try {
+          onChange(JSON.parse(next) as unknown);
+          setError(undefined);
+        } catch (cause) {
+          setError(cause instanceof Error ? cause.message : "Invalid JSON");
+        }
+      }}
+      messages={editorMessages}
+    />
+  );
+}
+
+function coerceChoice(value: string | null, option: CustomWidgetOption) {
+  if (value === null) return null;
+  return typeof option.default === "number" ||
+    option.choices?.some((choice) => typeof choice.value === "number" && String(choice.value) === value)
+    ? Number(value)
+    : value;
+}
+
+function primitiveConfiguration(value: Record<string, unknown>) {
+  return Object.fromEntries(
+    Object.entries(value).filter((entry): entry is [string, string | number | boolean] =>
+      ["string", "number", "boolean"].includes(typeof entry[1]),
+    ),
+  );
+}
+
+function getByPath(value: unknown, path: string): unknown {
+  return path
+    .replace(/^\$\.?/u, "")
+    .split(".")
+    .filter(Boolean)
+    .reduce<unknown>((current, segment) => (isRecord(current) ? current[segment] : undefined), value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

packages/widgets/src/_inputs/widget-custom-widget-select-input.tsx

@@ -1,10 +1,12 @@
 "use client";
 
 import { useMemo, useState } from "react";
-import { Combobox, InputBase, Loader, useCombobox } from "@mantine/core";
+import { Avatar, Badge, Combobox, Group, InputBase, Loader, Stack, Text, useCombobox } from "@mantine/core";
+import { IconApi } from "@tabler/icons-react";
 
 import { clientApi } from "@homarr/api/client";
 import { useOptionalBoard } from "@homarr/boards/context";
+import { useScopedI18n } from "@homarr/translation/client";
 
 import type { CommonWidgetInputProps } from "./common";
 import { useWidgetInputTranslation } from "./common";
@@ -16,6 +18,7 @@ export const WidgetCustomWidgetSelectInput = ({
   options,
 }: CommonWidgetInputProps<"customWidgetSelect">) => {
   const t = useWidgetInputTranslation(kind, property);
+  const labels = useScopedI18n("widget.customApi.picker");
   const form = useFormContext();
   const board = useOptionalBoard();
   const currentValue = form.values.options[property] as string;
@@ -25,7 +28,10 @@ export const WidgetCustomWidgetSelectInput = ({
   );
   const [search, setSearch] = useState("");
 
-  const definitions = useMemo(() => (data ?? []).map((def) => ({ value: def.id, label: def.name })), [data]);
+  const definitions = useMemo(
+    () => (data ?? []).map((definition) => ({ ...definition, value: definition.id, label: definition.name })),
+    [data],
+  );
 
   const filteredOptions = useMemo(
     () =>
@@ -38,7 +44,6 @@ export const WidgetCustomWidgetSelectInput = ({
   );
 
   const selectedLabel = definitions.find((d) => d.value === currentValue)?.label;
-
   const combobox = useCombobox({
     onDropdownClose: () => {
       combobox.resetSelectedOption();
@@ -47,43 +52,74 @@ export const WidgetCustomWidgetSelectInput = ({
   });
 
   return (
-    <Combobox
-      store={combobox}
-      onOptionSubmit={(val) => {
-        form.setFieldValue(`options.${property}`, val);
-        combobox.closeDropdown();
-      }}
-    >
-      <Combobox.Target>
-        <InputBase
-          label={t("label")}
-          description={options.withDescription ? t("description") : undefined}
-          rightSection={isLoading ? <Loader size="xs" /> : <Combobox.Chevron />}
-          rightSectionPointerEvents="none"
-          value={combobox.dropdownOpened ? search : (selectedLabel ?? currentValue)}
-          onChange={(event) => {
-            setSearch(event.currentTarget.value);
-            form.setFieldValue(`options.${property}`, event.currentTarget.value);
-            combobox.openDropdown();
-            combobox.updateSelectedOptionIndex();
-          }}
-          onClick={() => combobox.openDropdown()}
-          onFocus={() => combobox.openDropdown()}
-          onBlur={() => combobox.closeDropdown()}
-          placeholder={t("label")}
-        />
-      </Combobox.Target>
+    <Stack gap="sm">
+      <Combobox
+        store={combobox}
+        onOptionSubmit={(val) => {
+          const definition = definitions.find((candidate) => candidate.value === val);
+          form.setFieldValue(`options.${property}`, val);
+          form.setFieldValue("options.configuration", definition?.defaultOptions ?? {});
+          form.setFieldValue(
+            "options.configurationVersion",
+            definition?.updatedAt instanceof Date ? definition.updatedAt.getTime() : Date.now(),
+          );
+          combobox.closeDropdown();
+        }}
+      >
+        <Combobox.Target>
+          <InputBase
+            label={t("label")}
+            description={options.withDescription ? t("description") : undefined}
+            rightSection={isLoading ? <Loader size="xs" /> : <Combobox.Chevron />}
+            rightSectionPointerEvents="none"
+            value={combobox.dropdownOpened ? search : (selectedLabel ?? currentValue)}
+            onChange={(event) => {
+              setSearch(event.currentTarget.value);
+              combobox.openDropdown();
+              combobox.updateSelectedOptionIndex();
+            }}
+            onClick={() => combobox.openDropdown()}
+            onFocus={() => combobox.openDropdown()}
+            onBlur={() => combobox.closeDropdown()}
+            placeholder={t("label")}
+          />
+        </Combobox.Target>
 
-      <Combobox.Dropdown>
-        <Combobox.Options>
-          {filteredOptions.map((def) => (
-            <Combobox.Option key={def.value} value={def.value} active={def.value === currentValue}>
-              {def.label}
-            </Combobox.Option>
-          ))}
-          {filteredOptions.length === 0 && !isLoading && <Combobox.Empty>No definitions found</Combobox.Empty>}
-        </Combobox.Options>
-      </Combobox.Dropdown>
-    </Combobox>
+        <Combobox.Dropdown>
+          <Combobox.Options>
+            <Combobox.Group label={labels("group")}>
+              {filteredOptions.map((def) => (
+                <Combobox.Option key={def.value} value={def.value} active={def.value === currentValue}>
+                  <Group wrap="nowrap" gap="sm">
+                    <Avatar src={def.iconUrl} size={36} radius="md" color="blue">
+                      <IconApi size={18} />
+                    </Avatar>
+                    <Stack gap={1} style={{ minWidth: 0 }}>
+                      <Text size="sm" fw={600} truncate>
+                        {def.label}
+                      </Text>
+                      {def.description && (
+                        <Text size="xs" c="dimmed" lineClamp={1}>
+                          {def.description}
+                        </Text>
+                      )}
+                      <Group gap={4} mt={2}>
+                        <Badge size="xs" variant="light">
+                          {labels("sources", { count: def.sources.length })}
+                        </Badge>
+                        <Badge size="xs" variant="light" color="gray">
+                          {labels("requests", { count: def.requestCapabilities.length })}
+                        </Badge>
+                      </Group>
+                    </Stack>
+                  </Group>
+                </Combobox.Option>
+              ))}
+            </Combobox.Group>
+            {filteredOptions.length === 0 && !isLoading && <Combobox.Empty>{labels("empty")}</Combobox.Empty>}
+          </Combobox.Options>
+        </Combobox.Dropdown>
+      </Combobox>
+    </Stack>
   );
 };

packages/widgets/src/_inputs/widget-internal-input.tsx

@@ -0,0 +1,3 @@
+import type { CommonWidgetInputProps } from "./common";
+
+export const WidgetInternalInput = (_props: CommonWidgetInputProps<"internal">) => null;