@dogsbay/render-html 0.2.0-beta.118 → 0.2.0-beta.119

package/css/api.css

@@ -1,5 +1,8 @@
 /* Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/ui api-symbol.css, api-source.css, EndpointSection.astro, PropertyItem.astro. Do not edit. */
-/* API Symbol badges — colored by kind */
+/* API Symbol badges, coloured by kind. Text on its own 20% tint must reach
+   WCAG AA (4.5:1) on the page background: the light colours were L 0.5–0.6
+   (3.2–4.0:1) and are L 0.44 (5.0:1 or more); render-html's
+   tests/contrast.test.ts measures every kind in both modes. */
 .api-badge {
   display: inline-flex;
   align-items: center;
@@ -14,8 +17,8 @@
 }
 
 .api-badge-class {
-  background-color: oklch(0.55 0.18 265 / 0.2);
-  color: oklch(0.55 0.18 265);
+  background-color: oklch(0.44 0.18 265 / 0.2);
+  color: oklch(0.44 0.18 265);
 }
 .dark .api-badge-class {
   background-color: oklch(0.7 0.15 265 / 0.2);
@@ -23,8 +26,8 @@
 }
 
 .api-badge-meth {
-  background-color: oklch(0.55 0.15 155 / 0.2);
-  color: oklch(0.55 0.15 155);
+  background-color: oklch(0.44 0.15 155 / 0.2);
+  color: oklch(0.44 0.15 155);
 }
 .dark .api-badge-meth {
   background-color: oklch(0.7 0.15 155 / 0.2);
@@ -32,8 +35,8 @@
 }
 
 .api-badge-attr {
-  background-color: oklch(0.6 0.15 55 / 0.2);
-  color: oklch(0.6 0.15 55);
+  background-color: oklch(0.44 0.15 55 / 0.2);
+  color: oklch(0.44 0.15 55);
 }
 .dark .api-badge-attr {
   background-color: oklch(0.75 0.15 55 / 0.2);
@@ -41,8 +44,8 @@
 }
 
 .api-badge-func {
-  background-color: oklch(0.55 0.18 330 / 0.2);
-  color: oklch(0.55 0.18 330);
+  background-color: oklch(0.44 0.18 330 / 0.2);
+  color: oklch(0.44 0.18 330);
 }
 .dark .api-badge-func {
   background-color: oklch(0.7 0.15 330 / 0.2);
@@ -50,8 +53,8 @@
 }
 
 .api-badge-module {
-  background-color: oklch(0.5 0.12 200 / 0.2);
-  color: oklch(0.5 0.12 200);
+  background-color: oklch(0.44 0.12 200 / 0.2);
+  color: oklch(0.44 0.12 200);
 }
 .dark .api-badge-module {
   background-color: oklch(0.65 0.12 200 / 0.2);

package/dist/api-markdown.d.ts

@@ -1,4 +1,4 @@
-/** Block Markdown → HTML (an operation's description). */
+/** Block Markdown → HTML (an operation's description); headings become bold paragraphs. */
 export declare function apiBlockHtml(text: string): string;
 /** One line of Markdown → inline HTML (a parameter or property). */
 export declare function apiInlineHtml(text: string): string;

package/dist/api-markdown.js

@@ -13,9 +13,18 @@
  */
 import MarkdownIt from "markdown-it";
 const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
-/** Block Markdown → HTML (an operation's description). */
+/**
+ * The description's own headings as bold paragraphs: an operation sits
+ * under the page's outline (a tag h2, or only the page h1), and an `## Auth`
+ * in a spec description put an h2 inside the card, skipping or breaking the
+ * page's heading order (axe heading-order).
+ */
+const blockMd = new MarkdownIt({ html: false, linkify: false, typographer: false });
+blockMd.renderer.rules.heading_open = () => "<p><strong>";
+blockMd.renderer.rules.heading_close = () => "</strong></p>\n";
+/** Block Markdown → HTML (an operation's description); headings become bold paragraphs. */
 export function apiBlockHtml(text) {
-    return md.render(text).trim();
+    return blockMd.render(text).trim();
 }
 /** One line of Markdown → inline HTML (a parameter or property). */
 export function apiInlineHtml(text) {

package/dist/api.js

@@ -30,7 +30,9 @@ function apiSymbol(n, ctx) {
     const kind = str(p.kind) ?? "func";
     const signature = str(p.signature);
     const bases = Array.isArray(p.bases) ? p.bases.map(String) : [];
-    const level = n.type === "api-class" ? 2 : 3;
+    // apiSymbolLevels' rule (@dogsbay/serialize-core), applied as the page renders: one below the
+    // last heading before the symbol (h2 with none), or one below the enclosing symbol.
+    const level = Math.min(6, (ctx.apiParentLevel ?? ctx.lastHeadingLevel ?? 1) + 1);
     const badgeKind = kind === "method" ? "meth" : kind;
     // ApiSymbol's slug, so a link to #mypkg-client reaches the same symbol on both pipelines.
     const id = uniqueId(ctx, name.toLowerCase().replace(/[^\w]/g, "-").replace(/-+/g, "-"));
@@ -41,7 +43,17 @@ function apiSymbol(n, ctx) {
         `<h${level} id="${esc(id)}" class="!mt-0 !mb-0 !border-0"><code class="text-lg font-semibold">${esc(name)}</code></h${level}></div>` +
         (signature ? codeHtml(signature, "python", ctx) : "") +
         (bases.length ? `<p class="api-symbol-bases">Bases: ${bases.map((b) => `<code>${esc(b)}</code>`).join("")}</p>` : "") +
-        `<div class="mt-3">${renderBlocks(n.children, ctx)}</div></div>\n`);
+        `<div class="mt-3">${nested(ctx, level, () => renderBlocks(n.children, ctx))}</div></div>\n`);
+}
+function nested(ctx, level, f) {
+    const was = ctx.apiParentLevel;
+    ctx.apiParentLevel = level;
+    try {
+        return f();
+    }
+    finally {
+        ctx.apiParentLevel = was;
+    }
 }
 const CODE_IN_HTML = /<pre><code(?:\s+class="language-(\w+)")?>([\s\S]*?)<\/code><\/pre>/g;
 const decodeCode = (s) => s.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"');
@@ -172,12 +184,12 @@ const LOCATIONS = [
     ["header", "Header Parameters"],
     ["cookie", "Cookie Parameters"],
 ];
-/** PropertyList.astro: parameters grouped by location. */
+/** PropertyList.astro: parameters grouped by location, each group's label a <p> (an h4 skipped a level under an h2). */
 function propertyList(params, ctx) {
     const groups = LOCATIONS.map(([loc, label]) => ({ label, items: params.filter((p) => p.in === loc) })).filter((g) => g.items.length);
     return (`<div>` +
         groups
-            .map((g) => `<div class="mb-4 last:mb-0"><h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">${g.label}</h4>` +
+            .map((g) => `<div class="mb-4 last:mb-0"><p class="mb-1 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">${g.label}</p>` +
             `<div class="rounded-lg border bg-card">${g.items.map((p) => propertyItem(p, 0, ctx)).join("")}</div></div>`)
             .join("") +
         `</div>`);
@@ -268,7 +280,8 @@ function exampleLang(contentType) {
         return "yaml";
     return "json";
 }
-const PANEL_HEADING = "mb-3 text-xs font-semibold uppercase tracking-wider text-white/60";
+/** The code column's titles: labels, not headings (an operation page has only its h1 above them). */
+const PANEL_LABEL = "mb-3 text-xs font-semibold uppercase tracking-wider text-white/60";
 /** The code column's blocks, in format-astro's order: samples, the request body example, response examples. */
 function codePanels(p) {
     const out = [];
@@ -310,8 +323,8 @@ function endpoint(n, ctx) {
         `<div class="space-y-3">${sections}</div></div>`;
     const panels = codePanels(p)
         .map((c) => c.samples
-        ? `<div><h3 class="${PANEL_HEADING}">${esc(c.title)}</h3>${codeSamples(c.samples, ctx)}</div>`
-        : `<div><h3 class="${PANEL_HEADING}">${esc(c.title)}</h3>${codeHtml(c.code, c.lang, ctx)}</div>`)
+        ? `<div><p class="${PANEL_LABEL}">${esc(c.title)}</p>${codeSamples(c.samples, ctx)}</div>`
+        : `<div><p class="${PANEL_LABEL}">${esc(c.title)}</p>${codeHtml(c.code, c.lang, ctx)}</div>`)
         .join("");
     // Embedded among prose unless the host says the page is an operation page (apiPageLayout in @dogsbay/serialize-core).
     const page = ctx.embeddedEndpoints === false;

package/dist/render.d.ts

@@ -75,6 +75,10 @@ export interface RenderContext {
      * would flood the TOC. Their ids are reserved either way.
      */
     apiSymbolHeadings?: boolean;
+    /** The level of the last heading rendered outside an autodoc symbol (set as rendering goes). */
+    lastHeadingLevel?: number;
+    /** While rendering an autodoc symbol's body: that symbol's heading level. */
+    apiParentLevel?: number;
 }
 export { FOREIGN_END, FOREIGN_START };
 export { scriptUrl };

package/dist/render.js

@@ -302,6 +302,8 @@ function block(n, ctx) {
             const id = uniqueId(ctx, str(p.id) ?? str(p.slug) ?? slugify(text));
             if (level === 2 || level === 3)
                 ctx.headings.push({ depth: level, id, text });
+            if (ctx.apiParentLevel === undefined)
+                ctx.lastHeadingLevel = level;
             // Astro serializer: a hover pilcrow link, hidden from assistive tech (the heading is the target).
             const anchor = level > 1 ? `<a href="#${esc(id)}" class="ml-2 text-muted-foreground no-underline opacity-0 group-hover:opacity-100 focus:opacity-100" aria-hidden="true" tabindex="-1">&para;</a>` : "";
             const { id: _i, ...rest } = passthrough(p, "group scroll-mt-20");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/render-html",
-  "version": "0.2.0-beta.118",
+  "version": "0.2.0-beta.119",
   "description": "Dogsbay MD TreeNode → HTML with the Astro components' markup and classes. No highlighter, math or CSS compiler unless you pass one; Worker- and browser-safe",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,9 +30,9 @@
   "dependencies": {
     "htmlparser2": "^10.1.0",
     "markdown-it": "^14.3.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.118",
-    "@dogsbay/types": "0.2.0-beta.118",
-    "@dogsbay/serialize-core": "0.2.0-beta.118"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.119",
+    "@dogsbay/serialize-core": "0.2.0-beta.119",
+    "@dogsbay/types": "0.2.0-beta.119"
   },
   "peerDependencies": {
     "katex": "^0.16.0"