govoplan/tests/test-heading-help.mjs

import assert from "node:assert/strict";
import { test } from "node:test";
import { findDetachedDocumentation } from "../tools/checks/check-heading-help.mjs";
import "./test-heading-translations.mjs";

const inspect = (source) => findDetachedDocumentation([{ path: "/fixture/Page.tsx", source }]).findings;
const book = '<DocumentationHelpLink reference={topic} />';

test("heading and text contracts accept contextual help", () => {
  for (const component of ["PageHeader", "PageLayout", "AdminPageLayout", "Card", "Dialog", "PageActionBar", "WorkspaceActionBar"]) {
    assert.equal(inspect(`const Page=()=> <${component} title="Topic" titleHelp={${book}} />`).length, 0, component);
  }
  assert.equal(inspect(`const Page=()=> <PageTitle titleHelp={${book}}>Topic</PageTitle>`).length, 0);
  assert.equal(inspect(`const Page=()=> <TextWithHelp help={${book}}>Existing label</TextWithHelp>`).length, 0);
});

test("detached action and body links are rejected", () => {
  for (const source of [`<PageActionBar helpAction={${book}} />`, `<Card title="Topic" actions={${book}} />`, `<div>${book}</div>`, `<Card title={${book}} />`]) {
    assert.equal(inspect(`const Page=()=> ${source}`).length, 1, source);
  }
});

test("aliases, conditional help and simple local references remain checked", () => {
  assert.equal(inspect(`import {DocumentationHelpLink as Book, Card as Box} from '@govoplan/core-webui'; const Page=()=> <Box title="Topic" titleHelp={<Book reference={topic}/>} />`).length, 0);
  assert.equal(inspect(`import {DocumentationHelpLink as Book} from '@govoplan/core-webui'; const Page=()=> <div><Book reference={topic}/></div>`).length, 1);
  assert.equal(inspect(`const help=${book}; const Page=()=> <Card title="Topic" titleHelp={enabled ? help : null}/>`).length, 0);
  assert.equal(inspect(`const help=${book}; const Page=()=> <><Card title="Topic" titleHelp={help}/><PageActionBar helpAction={help}/></>`).length, 1);
  assert.equal(inspect(`const help=${book}; const again=help; const Page=()=> <Card title="Topic" titleHelp={again}/>`).length, 0);
});

test("empty anchors, unknown contracts and nested interactive elements fail", () => {
  for (const source of [`<Card titleHelp={${book}}/>`, `<TextWithHelp help={${book}}/>`, `<TextWithHelp help={${book}}> </TextWithHelp>`, `<Unknown title="Topic" titleHelp={${book}}/>`, `<Card title="Topic" titleHelp={<button>${book}</button>}/>`]) {
    assert.equal(inspect(`const Page=()=> ${source}`).length, 1, source);
  }
});

test("namespace and explicit component default imports cannot bypass placement", () => {
  for (const source of [
    `import * as UI from '@govoplan/core-webui'; const Page=()=> <div><UI.DocumentationHelpLink reference={topic}/></div>`,
    `import Book from './components/help/DocumentationHelpLink'; const Page=()=> <div><Book reference={topic}/></div>`,
  ]) assert.equal(inspect(source).length, 1, source);
  assert.equal(inspect(`import * as UI from '@govoplan/core-webui'; const Page=()=> <UI.Card title="Topic" titleHelp={<UI.DocumentationHelpLink reference={topic}/>}/>`).length, 0);
  assert.equal(inspect(`import Book from './components/help/DocumentationHelpLink'; import Label from './components/help/TextWithHelp'; const Page=()=> <Label help={<Book reference={topic}/>}>Topic</Label>`).length, 0);
  assert.equal(findDetachedDocumentation([{ path: "/fixture/Page.tsx", source: `import Book from './business/Book'; const Page=()=> <div><Book/></div>` }]).links, 0);
});

test("outer interactive containers and statically absent text are rejected", () => {
  for (const source of [
    `<button><TextWithHelp help={${book}}>Topic</TextWithHelp></button>`,
    `<a href="/other"><Card title="Topic" titleHelp={${book}}/></a>`,
    `<Card title="" titleHelp={${book}}/>`,
    `<Card title={false} titleHelp={${book}}/>`,
    `<PageTitle titleHelp={${book}}>{null}</PageTitle>`,
    `<TextWithHelp help={${book}}>{/* Topic */}</TextWithHelp>`,
    `<TextWithHelp help={${book}}>{undefined}</TextWithHelp>`,
    `<TextWithHelp help={${book}}><span hidden>Topic</span></TextWithHelp>`,
    `<TextWithHelp hidden help={${book}}>Topic</TextWithHelp>`,
  ]) assert.equal(inspect(`const Page=()=> ${source}`).length, 1, source);
  assert.equal(inspect(`const help=${book}; const Page=()=> <Button><TextWithHelp help={help}>Topic</TextWithHelp></Button>`).length, 1);
  assert.equal(inspect(`const title=null; const Page=()=> <Card title={title} titleHelp={${book}}/>`).length, 1);
  assert.equal(inspect(`const Page=()=> <Card title={translateText(title)} titleHelp={${book}}/>`).length, 0);
  assert.equal(inspect(`const Page=()=> <TextWithHelp help={${book}}><TranslatedTitle/></TextWithHelp>`).length, 0);
  assert.equal(inspect(`let title=""; title=translateText(key); const Page=()=> <Card title={title} titleHelp={${book}}/>`).length, 0);
});