@dogsbay/render-html 0.2.0-beta.124 → 0.2.0-beta.125

package/README.md

@@ -27,6 +27,15 @@ const html = renderBlocks(dogsbayMdToTree(markdown).tree, ctx);
 The output uses Tailwind utility classes and the theme tokens. Styling it needs the Dogsbay
 theme CSS, compiled for the classes the page uses.
 
+## Source lines (scroll sync)
+
+Parse with `sourceLines: true` (`dogsbayMdToTree` in format-dogsbay-md, or
+`ditaTopicToTree` in format-dita) and each block carries its 1-based source line
+on `meta.line`. Render with `createRenderContext({ dataLines: true })` and
+it is written as `data-line="N"` on each block's first element and on list
+items, so an editor can map a click in the preview to the source and scroll the
+preview to the cursor. Off by default; only a positive integer is ever written.
+
 ## API reference pages
 
 Autodoc symbols (`api-class`, `api-member`, `api-doc`, `api-params`,

package/css/docs.css

@@ -35,10 +35,11 @@
 .docs-prose {
   line-height: 1.7;
 
-  & h1:not(.dba-api *) { font-family: var(--font-heading); font-size: 2rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem; line-height: 1.2; letter-spacing: -0.025em; }
-  & h2:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.5rem; font-weight: 600; margin-top: 2.5rem; margin-bottom: 0.75rem; line-height: 1.3; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; letter-spacing: -0.015em; }
-  & h3:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
-  & h4:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
+  /* A heading that is part of a component (a card title: h3.not-prose) keeps the component look */
+  & h1:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 2rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem; line-height: 1.2; letter-spacing: -0.025em; }
+  & h2:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 1.5rem; font-weight: 600; margin-top: 2.5rem; margin-bottom: 0.75rem; line-height: 1.3; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; letter-spacing: -0.015em; }
+  & h3:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
+  & h4:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
 
   & p:not(.dba-api *) { margin-top: 0.75rem; margin-bottom: 0.75rem; }
 

package/dist/render.d.ts

@@ -73,6 +73,13 @@ export interface RenderContext {
     lastHeadingLevel?: number;
     /** While rendering an autodoc symbol's body: that symbol's heading level. */
     apiParentLevel?: number;
+    /**
+     * Write each block's source line (`meta.line`, from the parsers'
+     * `sourceLines` option) as `data-line` on its first element, and on list
+     * items, so a host can map the page back to the source (an editor's scroll
+     * sync). Off by default; only a positive integer is ever written.
+     */
+    dataLines?: boolean;
 }
 export { FOREIGN_END, FOREIGN_START };
 export { scriptUrl };

package/dist/render.js

@@ -276,9 +276,22 @@ export function renderBlocks(nodes, ctx) {
         plannedHeadingIds.set(ctx, planHeadingIds(nodes, new Set()));
     let out = "";
     for (const n of nodes)
-        out += block(n, ctx);
+        out += ctx.dataLines ? withDataLine(block(n, ctx), n) : block(n, ctx);
     return out;
 }
+/** A node's source line, when it is a positive integer (ctx.dataLines). */
+const sourceLine = (n) => {
+    const line = n.meta?.line;
+    return typeof line === "number" && Number.isInteger(line) && line > 0 ? line : undefined;
+};
+/** `data-line` on the first element of a block's HTML (none when it starts with text or a comment). */
+function withDataLine(html, n) {
+    const line = sourceLine(n);
+    if (line === undefined)
+        return html;
+    // The source's line wins over a `data-line` already in raw HTML (it would send scroll sync elsewhere)
+    return html.replace(/^(\s*<[A-Za-z][\w:-]*)(?=[\s/>])([^>]*?)(?:\sdata-line=(?:"[^"]*"|'[^']*'|[^\s>]*))?/, `$1 data-line="${line}"$2`);
+}
 const str = (v) => (v == null || v === "" ? undefined : String(v));
 /** A list item or step: the item's own inline run followed by its block children. */
 function itemBody(n, ctx) {
@@ -292,7 +305,8 @@ function listItem(n, ctx) {
     const lead = n.inline && n.inline.length ? renderInline(n.inline, ctx) : "";
     const rest = renderBlocks(n.children, ctx);
     const body = rest && lead ? `<p>${task}${lead}</p>${rest}` : task + lead + rest;
-    return `<li${attrs(passthrough(p))}>${body}</li>`;
+    const line = ctx.dataLines ? sourceLine(n) : undefined;
+    return `<li${attrs(passthrough(p))}${line ? ` data-line="${line}"` : ""}>${body}</li>`;
 }
 function block(n, ctx) {
     const p = (n.props ?? {});
@@ -910,7 +924,7 @@ function card(n, ctx) {
     // An image path is shown as an image, as the Astro pipeline's cardIconHtml does.
     const iconHtml = !ic ? "" : /\.(svg|png|jpe?g|webp|avif)$/i.test(ic) ? `<img src="${esc(assetUrl(ic, ctx))}" alt="" class="size-5 mb-2" loading="lazy">` : namedIcon(ic, "mb-2 size-5 text-muted-foreground", ctx);
     const inner = insideLink(!!href, ctx, () => iconHtml +
-        (title ? `<h3 class="m-0 border-0 p-0 text-base font-semibold">${renderInline(parseInline(title), ctx)}</h3>` : "") +
+        (title ? `<h3 class="not-prose m-0 border-0 p-0 text-base font-semibold">${renderInline(parseInline(title), ctx)}</h3>` : "") +
         (desc ? `<p class="m-0 mt-1 text-sm text-muted-foreground [text-decoration:none]">${renderInline(parseInline(desc), ctx)}</p>` : "") +
         // Body blocks in the same description wrapper as the Astro pipeline's card (a <div>: they carry their own <p>).
         (n.children?.length ? `<div class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${renderBlocks(n.children, ctx)}</div>` : ""));
@@ -918,7 +932,7 @@ function card(n, ctx) {
     const toned = lookup(CARD_TONE_CLASSES, str(p.tone));
     const cls = `rounded-lg border ${toned ?? "bg-card"} p-4 text-card-foreground shadow-sm${href ? ` transition-colors ${toned ? "hover:shadow-md" : "hover:border-foreground/20"}` : ""}`;
     return href
-        ? `<div${attrs(passthrough(p, cls))}><div class="p-0"><a href="${esc(linkUrl(href, ctx))}" class="block text-foreground [text-decoration:none]">${inner}</a></div></div>`
+        ? `<div${attrs(passthrough(p, cls))}><div class="p-0"><a href="${esc(linkUrl(href, ctx))}" class="not-prose block text-foreground [text-decoration:none]">${inner}</a></div></div>`
         : `<div${attrs(passthrough(p, cls))}><div class="p-0">${inner}</div></div>`;
 }
 function linkCard(n, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/render-html",
-  "version": "0.2.0-beta.124",
+  "version": "0.2.0-beta.125",
   "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.124",
-    "@dogsbay/serialize-core": "0.2.0-beta.124",
-    "@dogsbay/types": "0.2.0-beta.124"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.125",
+    "@dogsbay/serialize-core": "0.2.0-beta.125",
+    "@dogsbay/types": "0.2.0-beta.125"
   },
   "peerDependencies": {
     "katex": "^0.16.0"