govoplan-core/webui/tests/documentation-help-link.test.tsx

function assert(condition: unknown, message = "assertion failed"): void {
  if (!condition) throw new Error(message);
}

import { renderToStaticMarkup } from "react-dom/server";
import DocumentationHelpLink, { DocumentationHelpProvider } from "../src/components/help/DocumentationHelpLink";
import FieldLabel from "../src/components/help/FieldLabel";
import { documentationHelpHref } from "../src/components/help/documentationHelp";
import PageLayout from "../src/components/PageLayout";
import PageTitle from "../src/components/PageTitle";
import Card from "../src/components/Card";
import Dialog from "../src/components/Dialog";
import AdminPageLayout from "../src/components/admin/AdminPageLayout";
import WorkspaceActionBar from "../src/components/WorkspaceActionBar";
import TextWithHelp from "../src/components/help/TextWithHelp";
import { PlatformLanguageProvider } from "../src/i18n/LanguageContext";

assert(
  documentationHelpHref({ topicId: "campaigns.workflow.complete-review" }) ===
    "/docs?type=user&topic=campaigns.workflow.complete-review",
  "topic references use the stable Help Center query contract"
);
assert(
  documentationHelpHref({ contextId: "campaign.review-send", documentationType: "admin" }) ===
    "/docs?type=admin&context=campaign.review-send",
  "context references retain the requested audience projection"
);
assert(
  documentationHelpHref({ contextId: "calendar.field.title", fallbackContextId: "calendar.page", moduleId: "calendar" }) ===
    "/docs?type=user&context=calendar.field.title&fallback_context=calendar.page&module=calendar",
  "focused controls retain their page and module documentation fallback"
);
assert(
  documentationHelpHref({ topicId: "topic", anchorId: "details" }) ===
    "/docs?type=user&topic=topic#details",
  "optional stable anchors are preserved"
);
assert(documentationHelpHref({}) === null, "an empty reference does not create a misleading link");

const hostedMarkup = renderToStaticMarkup(
  <DocumentationHelpLink reference={{ contextId: "files.list" }} />
);
assert(hostedMarkup.includes("https://govoplan.add-ideas.de/?type=user&amp;context=files.list"), "the link falls back to hosted documentation when Docs is absent");
assert(hostedMarkup.includes('target="_blank"'), "hosted documentation is clearly external");

const localMarkup = renderToStaticMarkup(
  <DocumentationHelpProvider localDocsAvailable>
    <DocumentationHelpLink reference={{ topicId: "docs.pattern.field-help" }} />
  </DocumentationHelpProvider>
);
assert(localMarkup.includes("/docs?type=user&amp;topic=docs.pattern.field-help"), "an enabled Docs module uses the local Help Center");
assert(!localMarkup.includes('target="_blank"'), "local documentation stays in the application");

const fieldMarkup = renderToStaticMarkup(
  <DocumentationHelpProvider localDocsAvailable>
    <FieldLabel documentation={{ topicId: "access.reference.admin-access-fields" }}>Role</FieldLabel>
  </DocumentationHelpProvider>
);
assert(fieldMarkup.includes("topic=access.reference.admin-access-fields"), "field labels can link to stable reference topics");

for (const language of ["en", "de"]) {
  const helpLabel = language === "de" ? "Benutzerdokumentation öffnen" : "Open user documentation";
  const help = <DocumentationHelpLink reference={{ contextId: "dashboard" }} />;
  for (const [name, element] of [
    ["page", <PageLayout archetype="overview" title="Dashboard" titleHelp={help} headerLoading actions={<button>Configure</button>}>Data</PageLayout>],
    ["title", <PageTitle loading titleHelp={help}>Dashboard</PageTitle>],
    ["administration", <AdminPageLayout title="Dashboard" description="Summary" titleHelp={help}>Data</AdminPageLayout>],
    ["card", <Card title="Dashboard" titleHelp={help} collapsible>Data</Card>],
    ["dialog", <Dialog open title="Dashboard" titleHelp={help} onClose={() => undefined}>Data</Dialog>],
    ["workspace", <WorkspaceActionBar variant="workspace" title="Dashboard" titleHelp={help} titleLevel={1} primaryActions={<button>Edit</button>} />],
    ["section", <TextWithHelp as="div" help={help}><h3>Dashboard</h3></TextWithHelp>]
  ] as const) {
    const markup = renderToStaticMarkup(<PlatformLanguageProvider preferredLanguageCode={language}>{element}</PlatformLanguageProvider>);
    const heading = markup.match(/<h[123]\b[^>]*>[\s\S]*?<\/h[123]>/)?.[0];
    assert(heading?.includes("Dashboard"), `${name} retains a visible semantic heading`);
    assert(!heading?.includes("documentation-help-link") && !heading?.includes("loading-indicator"), `${name} heading name excludes help and progress controls`);
    assert(markup.includes(`aria-label="${helpLabel}"`), `${name} keeps translated documentation access in ${language}`);
    assert(markup.indexOf('class="documentation-help-link"') > markup.indexOf(heading!), `${name} help follows its visible heading`);
    assert(!/<button\b[^>]*>[\s\S]*?documentation-help-link[\s\S]*?<\/button>/.test(markup), `${name} never nests documentation inside an action`);
  }
}

const titleWithoutText = renderToStaticMarkup(<WorkspaceActionBar variant="workspace" titleHelp={<DocumentationHelpLink reference={{ contextId: "dashboard" }} />} />);
assert(!titleWithoutText.includes("documentation-help-link"), "workspace help cannot appear without a visible context heading");
const unheadedCard = renderToStaticMarkup(<Card titleHelp={<DocumentationHelpLink reference={{ contextId: "dashboard" }} />}>Data</Card>);
assert(!unheadedCard.includes("documentation-help-link"), "card help cannot appear without a visible title");