feat(core/best-practices): custom labels via data-label

src/core/best-practices.js

@@ -12,6 +12,7 @@ export const name = "core/best-practices";
 const localizationStrings = {
   en: {
     best_practice: "Best Practice ",
+    best_practice_summary: "Best Practices Summary",
   },
   ja: {
     best_practice: "最良実施例 ",
@@ -22,6 +23,10 @@ const localizationStrings = {
   zh: {
     best_practice: "最佳实践 ",
   },
+  fr: {
+    best_practice: "Bonne pratique ",
+    best_practice_summary: "Résumé des bonnes pratiques",
+  },
 };
 const l10n = getIntlData(localizationStrings);
 const lang = defaultLang in localizationStrings ? defaultLang : "en";
@@ -33,8 +38,13 @@ export function run() {
   const summaryItems = bpSummary ? document.createElement("ul") : null;
   [...bps].forEach((bp, num) => {
     const id = addId(bp, "bp");
+    const customLabel = bp.dataset.label;
+    const rawLabel = customLabel || l10n.best_practice;
+    const label = `${rawLabel.trimEnd()} `;
+    const bdi = html`<bdi>${label}${num + 1}</bdi>`;
+    if (!customLabel) bdi.lang = lang;
     const localizedBpName = html`<a class="marker self-link" href="${`#${id}`}"
-      ><bdi lang="${lang}">${l10n.best_practice}${num + 1}</bdi></a
+      >${bdi}</a
     >`;
 
     // Make the summary items, if we have a summary
@@ -57,7 +67,9 @@ export function run() {
   });
   if (bps.length) {
     if (bpSummary) {
-      bpSummary.appendChild(html`<h1>Best Practices Summary</h1>`);
+      const summaryLabel =
+        bpSummary.dataset.label || l10n.best_practice_summary;
+      bpSummary.appendChild(html`<h1>${summaryLabel}</h1>`);
       if (summaryItems) bpSummary.appendChild(summaryItems);
     }
   } else if (bpSummary) {

tests/spec/core/best-practices-spec.js

@@ -81,4 +81,79 @@ describe("Core — Best Practices", () => {
     );
     expect(bps.querySelectorAll("ul li")).toHaveSize(3);
   });
+
+  it("uses custom labels from data-label attribute", async () => {
+    const body = `
+      <section id="principles">
+        <h2>Section</h2>
+        <span class='practicelab' data-label="Principle ">P1</span>
+        <div>
+          <p class='practicelab' data-label="Principle ">P2</p>
+        </div>
+        <section id='bp-summary' data-label="Principles Summary">
+        </section>
+      </section>
+    `;
+    const ops = {
+      config: makeBasicConfig(),
+      body,
+    };
+    const doc = await makeRSDoc(ops);
+    const summary = doc.getElementById("bp-summary");
+    expect(summary).toBeTruthy();
+    const listItems = summary.querySelectorAll("li");
+    expect(listItems[0].textContent.trim()).toBe("Principle 1: P1");
+    expect(listItems[1].textContent.trim()).toBe("Principle 2: P2");
+    const heading = summary.querySelector("h3");
+    expect(heading.textContent).toContain("Principles Summary");
+
+    // Boxed practice: verify custom label appears in the visible marker
+    const selfLink = doc.querySelector(".advisement .self-link");
+    expect(selfLink.textContent).toBe("Principle 2");
+
+    // Custom labels must not carry the built-in locale's lang attribute
+    const bdi = selfLink.querySelector("bdi");
+    expect(bdi.hasAttribute("lang")).toBeFalse();
+  });
+
+  it("sets lang attribute on bdi only for built-in localized labels", async () => {
+    const body = `
+      <section id="bps">
+        <h2>Section</h2>
+        <div>
+          <p class='practicelab'>BP1</p>
+        </div>
+      </section>
+    `;
+    const ops = {
+      config: makeBasicConfig(),
+      body,
+    };
+    const doc = await makeRSDoc(ops);
+    const bdi = doc.querySelector(".advisement .self-link bdi");
+    expect(bdi.hasAttribute("lang")).toBeTrue();
+  });
+
+  it("uses custom labels in boxed best practice containers", async () => {
+    const body = `
+      <section>
+        <h2>Section</h2>
+        <div>
+          <span class='practicelab' data-label="Principle">Boxed P1</span>
+          <p>Details here.</p>
+        </div>
+      </section>
+    `;
+    const ops = {
+      config: makeBasicConfig(),
+      body,
+    };
+    const doc = await makeRSDoc(ops);
+    const container = doc.querySelector(".advisement");
+    expect(container).toBeTruthy();
+    const marker = container.querySelector(".marker");
+    expect(marker.textContent).toContain("Principle 1");
+    const bdi = marker.querySelector("bdi");
+    expect(bdi.hasAttribute("lang")).toBeFalse();
+  });
 });