paperlint 14.3.0 → 14.5.0

package/skills/build-label-page/scripts/label-page-browser.test.ts

@@ -1357,3 +1357,281 @@ test(
   },
   BROWSER_TEST_MS,
 );
+
+/** Where a part of a card sits, by its `data-test`: the first one of that kind. */
+const boxOf = async (card: Locator, kind: string) =>
+  card.getByTestId(kind).first().boundingBox();
+const Panel = z.object({
+  border: z.number(),
+  radius: z.number(),
+  padding: z.number(),
+});
+test(
+  "🔴 a quote card reads once from top to bottom, quote, code, question, answers, wait bar, inside a panel of its own; its «still needs» line is not shown",
+  async () => {
+    await onV7Page(
+      "browser-v7-order",
+      async (page, cardOf) => {
+        const card = await cardOf("card-docstring");
+        const parts = ["quote", "excerpt-path", "question", "answer", "wait"];
+        const boxes = await Promise.all(parts.map((k) => boxOf(card, k)));
+        // Guards: each part starts below the one before it ends, so the eye never goes back up.
+        assert.deepEqual(
+          R.zip(boxes, boxes.slice(1)).map(
+            ([a, b]) => a !== null && b !== null && b.y >= a.y + a.height,
+          ),
+          [true, true, true, true],
+          JSON.stringify(boxes),
+        );
+        const status = card.getByTestId("status");
+        assert.deepEqual(
+          [await metaOf(status), await status.isVisible()],
+          [{ state: "missing", missing: ["forbid"] }, false],
+        );
+        // A panel: a border all round, rounded, padded, and wide space before the next card.
+        const panel = Panel.parse(
+          await card.evaluate((e) => {
+            const s = getComputedStyle(e);
+            return {
+              border: parseFloat(s.borderBottomWidth),
+              radius: parseFloat(s.borderTopLeftRadius),
+              padding: parseFloat(s.paddingLeft),
+            };
+          }),
+        );
+        assert.ok(
+          panel.border >= 1 && panel.radius >= 8 && panel.padding >= 12,
+          JSON.stringify(panel),
+        );
+        const cards = await page.getByTestId("item").all();
+        const [first, second] = await Promise.all(
+          cards.slice(0, 2).map(async (c) => c.boundingBox()),
+        );
+        assert.ok(first && second, "two cards drawn");
+        assert.ok(
+          second.y - (first.y + first.height) >= 32,
+          JSON.stringify([first, second]),
+        );
+      },
+      true,
+    );
+  },
+  BROWSER_TEST_MS,
+);
+
+// ── a second language for the page's own words (#394) ──────────────────────────────────────────
+const RU_FIXTURE = join(import.meta.dirname, "fixtures", "v7-cards-ru.json");
+const Words = z.object({
+  labels: z.object({ for_example: z.string() }).loose(),
+  questions: z.array(
+    z.object({
+      id: z.string(),
+      text: z.string(),
+      options: z.array(
+        z.object({
+          value: z.string(),
+          label: z.string(),
+          example: z.string(),
+          icon: z.string(),
+        }),
+      ),
+    }),
+  ),
+});
+const RU_RAW = z.json().parse(JSON.parse(readFileSync(RU_FIXTURE, "utf8")));
+const RU_WORDS = z
+  .object({
+    situation_question: z.string(),
+    labels: z.object({ for_example: z.string() }).loose(),
+    questions: z.record(
+      z.string(),
+      z.object({
+        text: z.string(),
+        options: z.record(
+          z.string(),
+          z.object({ label: z.string(), example: z.string() }),
+        ),
+      }),
+    ),
+  })
+  .parse(RU_RAW);
+/** The fixture's page words in one language: the base's, or the Russian translation laid over them. */
+function wordsIn(lang: "en" | "ru") {
+  const base = Words.parse({
+    labels: { for_example: "For example: " },
+    questions: z.object({ questions: z.unknown() }).loose().parse(V7_CONFIG)
+      .questions,
+  });
+  if (lang === "en") return base;
+  return {
+    labels: RU_WORDS.labels,
+    questions: base.questions.map((q) => ({
+      ...q,
+      text: RU_WORDS.questions[q.id]?.text ?? "",
+      options: q.options.map((o) => ({
+        ...o,
+        ...RU_WORDS.questions[q.id]?.options[o.value],
+      })),
+    })),
+  };
+}
+/** What the docstring card and the how-to rows say in `lang`, as the fixture states it. */
+function expectedIn(lang: "en" | "ru") {
+  const card = fixtureCard("card-docstring");
+  const { situation, quote } = z
+    .object({
+      situation: z.object({ question: z.string() }),
+      quote: z.object({ text: z.string() }),
+    })
+    .loose()
+    .parse(card);
+  const w = wordsIn(lang);
+  const [q] = w.questions;
+  assert.ok(q !== undefined);
+  const notes = card.answer_notes.forbid;
+  return {
+    switch: { lang, langs: ["en", "ru"] },
+    quote: unticked(quote.text),
+    question:
+      lang === "en"
+        ? situation.question
+        : RU_WORDS.situation_question.replace(
+            "{n}",
+            String(card.excerpt.lines.find((l) => l.mark)?.n),
+          ),
+    answers: q.options.map((o) => [
+      { question: q.id, value: o.value },
+      `${o.icon}${o.label}${unticked(notes[o.value] ?? "")}`,
+    ]),
+    howTo: [
+      q.text,
+      ...q.options.map(
+        (o) => `${o.icon} ${o.label}${w.labels.for_example}${o.example}`,
+      ),
+    ],
+  };
+}
+/** The same, read from the page. */
+async function shownIn(page: Page, card: Locator) {
+  const texts = async (scope: Page | Locator, kind: string) =>
+    scope.getByTestId(kind).allTextContents();
+  return {
+    switch: await metaOf(page.getByTestId("lang-switch")),
+    quote: (await texts(card, "quote")).join(""),
+    question: (await texts(card, "question")).join(""),
+    answers: await Promise.all(
+      (await allByKind(card, "answer")).map(async (a) => [
+        a.meta,
+        await a.loc.textContent(),
+      ]),
+    ),
+    howTo: [
+      ...(await texts(page, "how-to-question")),
+      ...(await texts(page, "how-to-answer")),
+    ],
+  };
+}
+test(
+  "🔴 the language switch swaps the page's own words both ways, keeps the quote and the code as built, and is remembered over a reload",
+  async () => {
+    const cfg = {
+      ...R.omit(V7_CONFIG, ["min_seconds"]),
+      translations: { ru: RU_RAW },
+    };
+    const { page: html, key } = build(setup("browser-v7-lang", cfg));
+    const at = "http://label.test/";
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 800 } });
+    try {
+      // A real origin, so the page has a localStorage; every other request is refused, none leaves.
+      await page.route("**/*", (r) =>
+        r.request().url() === at
+          ? r.fulfill({ contentType: "text/html; charset=utf-8", body: html })
+          : r.abort(),
+      );
+      await page.addInitScript(
+        STORE(
+          Object.fromEntries(
+            ["forbid", "allow", "elsewhere"].map((v, n) => [
+              `r1-P${String(n + 1)}`,
+              { answers: { forbid: v }, source: "page" },
+            ]),
+          ),
+          20,
+        ),
+      );
+      await page.goto(at, { waitUntil: "domcontentloaded" });
+      const id = Object.entries(key.ids).find(
+        ([, v]) => v.source_id === "card-docstring",
+      )?.[0];
+      const card = async () => {
+        await page.getByTestId("item").first().waitFor();
+        const found = (await allByKind(page, "item")).find(
+          (c) => Id.parse(c.meta).id === id,
+        );
+        assert.ok(found !== undefined, "the card is drawn");
+        return found.loc;
+      };
+      const option = async (lang: string) =>
+        (await allByKind(page, "lang-option")).find(
+          (o) => z.object({ lang: z.string() }).parse(o.meta).lang === lang,
+        )?.loc;
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("en"));
+      await (await option("ru"))?.click();
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("ru"));
+      await page.reload({ waitUntil: "domcontentloaded" });
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("ru"));
+      await (await option("en"))?.click();
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("en"));
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 a page without translations names its own language on the document: the one it declares, else English",
+  async () => {
+    const htmlLang = async (cfg: Record<string, unknown>, dir: string) => {
+      const { page: html } = build(setup(dir, cfg));
+      const at = "http://label.test/";
+      const page = await (
+        await sharedBrowser()
+      ).newPage({ viewport: { width: 400, height: 800 } });
+      try {
+        await page.route("**/*", (r) =>
+          r.request().url() === at
+            ? r.fulfill({ contentType: "text/html; charset=utf-8", body: html })
+            : r.abort(),
+        );
+        await page.addInitScript(
+          STORE(
+            Object.fromEntries(
+              ["forbid", "allow", "elsewhere"].map((v, n) => [
+                `r1-P${String(n + 1)}`,
+                { answers: { forbid: v }, source: "page" },
+              ]),
+            ),
+            20,
+          ),
+        );
+        await page.goto(at, { waitUntil: "domcontentloaded" });
+        await page.getByTestId("item").first().waitFor();
+        return await page.evaluate(() => document.documentElement.lang);
+      } finally {
+        await page.context().close();
+      }
+    };
+    const plain = R.omit(V7_CONFIG, ["min_seconds"]);
+    assert.deepEqual(
+      [
+        await htmlLang(plain, "browser-v7-lang-none"),
+        await htmlLang({ ...plain, lang: "de" }, "browser-v7-lang-de"),
+      ],
+      ["en", "de"],
+    );
+  },
+  BROWSER_TEST_MS,
+);

package/skills/build-label-page/scripts/label-page-core.js

@@ -347,6 +347,34 @@ const QUESTION_SCHEMA = obj({
     short: string(false),
     options: array(OPTION_SCHEMA, true, 2),
 });
+// Page-level words the blocks use (references/closed-choice-generator.md §«Content blocks»).
+const LABELS = optional({
+    place: string(false),
+    body: string(false),
+    line: string(false),
+    line_part: string(false),
+    repeat: string(false),
+    practice_example: string(false),
+    hidden: string(false),
+    hidden_one: string(false),
+    wait: string(false),
+    how_to: string(false),
+    for_example: string(false),
+});
+// The page's own words in another language (#394): never the quote, code, notes or any card text
+// the labeller judges. Keyed like the page, so a translation names its questions and answers by id.
+const TRANSLATION = obj({
+    title: string(false),
+    intro: string(false),
+    labels: LABELS,
+    // the first question as the cards with a `situation` ask it; `{n}` is the marked line's number
+    situation_question: string(false),
+    questions: mapping(obj({
+        text: string(),
+        short: string(false),
+        options: mapping(obj({ label: string(), example: string(), ask_why: string(false) }), NAME_PATTERN, 1),
+    }), NAME_PATTERN, 1),
+});
 const configSchema = (kind) => obj({
     study: string(true, NAME_PATTERN), // becomes a file name
     kind: string(true, Object.keys(KINDS).join("|"), `one of ${KIND_NAMES}`),
@@ -366,18 +394,10 @@ const configSchema = (kind) => obj({
     questions: array(QUESTION_SCHEMA, true, 1),
     practice: array(practiceSchema(kind), true, MIN_PRACTICE),
     practice_round: integer(false),
-    // Page-level words the blocks use (references/closed-choice-generator.md §«Content blocks»).
-    labels: optional({
-        place: string(false),
-        body: string(false),
-        line: string(false),
-        line_part: string(false),
-        repeat: string(false),
-        practice_example: string(false),
-        hidden: string(false),
-        hidden_one: string(false),
-        wait: string(false),
-    }),
+    labels: LABELS,
+    // the language of the page's own words, and the same words in more languages, with a switch
+    lang: string(false, NAME_PATTERN),
+    translations: mapping(TRANSLATION, NAME_PATTERN, 1, false),
     items: array(itemSchema(kind), true, 1),
 });
 /** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
@@ -765,6 +785,94 @@ function checkNoSourceShown(cfg) {
         }
     }
 }
+// ── a second language for the page's own words (#394) ─────────────────────────────────────────
+/** The language of the page's own words when items.json does not name it. */
+const BASE_LANG = "en";
+/** In a translated `situation_question`, the number of the card's marked line. */
+const NUMBER_TOKEN = "{n}";
+/** A translated text is given exactly when the page shows the text it translates. */
+function checkPresence(where, shown, given) {
+    if (shown !== undefined && given === undefined)
+        fail(`${where}: is required and missing — ${shown}`);
+    if (shown === undefined && given !== undefined)
+        fail(`${where}: is never shown — the page has no text it translates`);
+}
+/** The cards' first question, translated: given exactly when a card has a `situation`. */
+function checkSituationWords(cfg, at, t) {
+    const cards = cardsOf(cfg).filter(([, c]) => c.situation !== undefined);
+    const first = cards[0];
+    checkPresence(`${at}.situation_question`, first &&
+        `${first[0]}.situation asks the first question in the card's own words`, t.situation_question);
+    const q = t.situation_question ?? "";
+    const bare = cards.find(([, c]) => lineOf(c) === undefined);
+    if (bare !== undefined &&
+        [NUMBER_TOKEN, LINE_TOKEN].some((token) => q.includes(token)))
+        fail(`${at}.situation_question: names the marked line, and ${bare[0]} has no \`excerpt\` — add it, or write the question without \`${NUMBER_TOKEN}\` and \`${LINE_TOKEN}\``);
+}
+/** One answer in the translation's words; refused when the translation leaves it out. */
+const optionIn = (o, words, where) => {
+    const w = words.options[o.value] ??
+        fail(`${where}.options.${o.value}: is required and missing — every answer is translated`);
+    checkPresence(`${where}.options.${o.value}.ask_why`, o.ask_why && "this answer asks why", w.ask_why);
+    return {
+        ...R.omit(o, ["ask_why"]),
+        label: w.label,
+        example: w.example,
+        ...R.pickBy({ ask_why: w.ask_why }, R.isDefined),
+    };
+};
+/** One question in the translation's words: every answer of it, no answer it does not have. */
+function questionIn(q, t, at) {
+    const where = `${at}.questions.${q.id}`;
+    const words = t.questions[q.id] ??
+        fail(`${where}: is required and missing — every question of the page is translated`);
+    const values = q.options.map((o) => o.value);
+    const stray = Object.keys(words.options).find((v) => !values.includes(v));
+    if (stray !== undefined)
+        fail(`${where}.options.${stray}: not one of ${values.join(", ")}`);
+    const options = q.options.map((o) => optionIn(o, words, where));
+    const twice = firstRepeat(options.map((o) => o.label));
+    if (twice !== undefined)
+        fail(`${where}.options.${String(values[twice.at])}.label: ${repr(options[twice.at]?.label)} reads the same as options.${String(values[twice.earlier])}.label — each button needs its own label`);
+    return {
+        id: q.id,
+        text: words.text,
+        ...R.pickBy({ short: words.short }, R.isDefined),
+        options,
+    };
+}
+/**
+ * Every language of the page with its words whole, the translations checked: each covers every
+ * question and answer of the page and names none it does not have, and gives an intro, a reason
+ * prompt and a situation question exactly where the page shows one. A label it leaves out reads as
+ * in the page's own language.
+ */
+function translationsOf(cfg) {
+    const base = cfg.lang ?? BASE_LANG;
+    return R.mapValues(cfg.translations ?? {}, (t, lang) => {
+        const at = `translations.${lang}`;
+        if (lang === base)
+            fail(`${at}: is the page's own language (\`lang\` is ${repr(base)}) — translate into another one`);
+        checkPresence(`${at}.intro`, cfg.intro && "the page has an `intro`", t.intro);
+        checkSituationWords(cfg, at, t);
+        const ids = cfg.questions.map((q) => q.id);
+        const stray = Object.keys(t.questions).find((id) => !ids.includes(id));
+        if (stray !== undefined)
+            fail(`${at}.questions.${stray}: not a question of this page (${ids.join(", ")})`);
+        return {
+            title: t.title ?? cfg.title,
+            intro: t.intro ?? "",
+            labels: { ...DEFAULT_LABELS, ...cfg.labels, ...t.labels },
+            ...R.pickBy({ situation_question: t.situation_question }, R.isDefined),
+            questions: cfg.questions.map((q) => questionIn(q, t, at)),
+        };
+    });
+}
+/** The languages: the page's own when items.json names it, and with translations always (English when unnamed).
+ *  A page that names neither is as it was. */
+const languagesOf = (cfg, translated) => cfg.translations === undefined
+    ? R.pickBy({ lang: cfg.lang }, R.isDefined)
+    : { lang: cfg.lang ?? BASE_LANG, translations: translated };
 /** key.json is this script's own output, written by `build`; its shape is trusted, not re-checked. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- an assertion signature, no body to run
 function assertOwnKey(_value) { }
@@ -882,11 +990,13 @@ const DEFAULT_LABELS = {
     hidden: "lines {from}\u2013{to}",
     hidden_one: "line {from}",
     wait: "\u23f3 You can answer in {s} s",
+    how_to: "📖 How to answer",
+    for_example: "For example: ",
 };
 /** The answerers and the dwell, only when items.json sets them: a page without them is as it was. */
 const twoKeys = (cfg) => R.pickBy({ answerers: cfg.answerers, min_seconds: cfg.min_seconds }, R.isDefined);
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
-function payloadOf(cfg, page, described) {
+function payloadOf(cfg, page, described, translated) {
     const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
     return {
         title: cfg.title,
@@ -899,6 +1009,7 @@ function payloadOf(cfg, page, described) {
         familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
         allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
         ...twoKeys(cfg),
+        ...languagesOf(cfg, translated),
         questions: cfg.questions,
         practice: {
             round: practiceRound(cfg),
@@ -983,6 +1094,7 @@ export function prepareBuild(configPath, outDir) {
     checkBlocks(cfg);
     checkCardText(cfg);
     checkNoSourceShown(cfg);
+    const translated = translationsOf(cfg);
     const described = describeRules(cfg, dirname(configPath));
     mkdirSync(outDir, { recursive: true });
     const keyPath = join(outDir, "key.json");
@@ -990,7 +1102,7 @@ export function prepareBuild(configPath, outDir) {
     const page = itemsOnPage(cfg, keyPath);
     writeJson(keyPath, keyOf(cfg, page, earlier));
     return {
-        payload: payloadOf(cfg, page, described),
+        payload: payloadOf(cfg, page, described, translated),
         dropped: cfg.items.length - page.items.length,
     };
 }

package/skills/build-label-page/scripts/label-page-core.test.ts

@@ -139,6 +139,42 @@ const CARD = {
   },
   repeat: { group: "g", index: 1, of: 1 },
 };
+/** The translation of FULL's page, with every optional field present. */
+const RU_FULL = {
+  title: "Т",
+  intro: "Разметьте.",
+  labels: {
+    place: "К",
+    body: "Т",
+    line: "С",
+    line_part: "{line} {part}/{of}",
+    repeat: "П",
+    practice_example: "П",
+    hidden: "С {from}-{to}",
+    hidden_one: "С {from}",
+    wait: "Ж {s}",
+    how_to: "Как",
+    for_example: "Н: ",
+  },
+  situation_question: "В?",
+  questions: {
+    label: {
+      text: "Верно?",
+      short: "верно?",
+      options: {
+        yes: { label: "Да", example: "1, 2, 3" },
+        no: { label: "Нет", example: "3, 1, 2", ask_why: "Что не так?" },
+      },
+    },
+    boundary: {
+      text: "Граница?",
+      options: {
+        clear: { label: "Ясно", example: "[]" },
+        boundary: { label: "Граница", example: "равные ключи" },
+      },
+    },
+  },
+};
 /** A config with EVERY optional field present, so every schema path has a value to spoil. */
 const FULL: DocObject = (() => {
   const doc = Doc.parse(
@@ -169,7 +205,11 @@ const FULL: DocObject = (() => {
         hidden: "H {from}-{to}",
         hidden_one: "H {from}",
         wait: "W {s}",
+        how_to: "How",
+        for_example: "E: ",
       },
+      lang: "en",
+      translations: { ru: RU_FULL },
       practice: PRACTICE.map((p, n) => (n === 0 ? { ...p, ...CARD } : p)),
       items: ITEMS.map((i, n) =>
         n === 0 ? { ...i, ...CARD, answerers: ["author"] } : i,
@@ -304,6 +344,15 @@ function badCases({ node, member }: Leaf): readonly BadCase[] {
   return [...wrongType, ...extra];
 }
 
+/** `doc` without the value at `steps`. */
+function without(
+  doc: DocObject,
+  steps: readonly (string | number)[],
+): DocObject {
+  const out = put(doc, steps, undefined);
+  assert.ok(isObject(out));
+  return out;
+}
 /** `doc` with its first item's own answerers taken out. */
 function withoutItemAnswerers(doc: DocObject): DocObject {
   const out = put(doc, ["items", 0, "answerers"], undefined);
@@ -317,6 +366,25 @@ function withoutItemAnswerers(doc: DocObject): DocObject {
 const RELAX: Partial<Record<string, (doc: DocObject) => DocObject>> = {
   familiarity: (doc) => R.omit(doc, ["familiarity_question"]),
   answerers: withoutItemAnswerers,
+  // A translation gives an intro, a reason prompt and a card question exactly where the page has one.
+  intro: (doc) => without(doc, ["translations", "ru", "intro"]),
+  "translations.ru.intro": (doc) => R.omit(doc, ["intro"]),
+  "questions[0].options[1].ask_why": (doc) =>
+    without(doc, [
+      "translations",
+      "ru",
+      "questions",
+      "label",
+      "options",
+      "no",
+      "ask_why",
+    ]),
+  "translations.ru.situation_question": (doc) =>
+    without(without(doc, ["items", 0, "situation"]), [
+      "practice",
+      0,
+      "situation",
+    ]),
 };
 
 /** Spoil `leaf` each way in `badCases`; every one must stop the build and name the path. */