@dogsbay/render-html 0.0.0-stage → 0.2.0-beta.117

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @dogsbay/render-html
+
+Dogsbay MD (`TreeNode[]` from `@dogsbay/format-dogsbay-md`) to HTML, with the
+markup and Tailwind classes of the Dogsbay Astro components.
+
+- **Works without a highlighter, math or a CSS compiler.** With no `highlighter`, code
+  renders as plain text in the same markup. With no `math`, LaTeX stays as source.
+- **Worker- and browser-safe:** the main entry imports no Node built-ins.
+
+```ts
+import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md/browser";
+import { renderBlocks, type RenderContext } from "@dogsbay/render-html";
+
+const ctx: RenderContext = {
+  link: (href) => href,
+  asset: (src) => src,
+  headings: [], ids: new Set(), unknown: new Set(), seq: 0,
+  t: (key) => key,
+  // highlighter: await createHighlighter(),   // @dogsbay/highlight
+  // math: katexMath,                           // @dogsbay/render-html/math (needs katex)
+};
+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.
+
+## Stylesheets
+
+`css/` holds the stylesheets for this markup: the theme presets (`theme-default.css`,
+`theme-mintlify.css`), `docs.css`, `steps.css` and `code-rich.css`. Import them as
+`@dogsbay/render-html/css/<file>`. They are Tailwind 4 sources (`@apply`, `@utility`,
+tokens), so compile them with the page's classes.
+
+## Copied sources
+
+`alert-icons.ts`, `badge-variants.ts`, `kbd-variants.ts`, `file-tree.ts`,
+`code-markers.ts`, `tone-classes.ts` and everything in `css/` are copies from `@dogsbay/ui` and
+`@dogsbay/format-astro`. Copying them keeps this package free of Astro.
+
+After changing them upstream, run `pnpm --filter @dogsbay/render-html sync-sources`.
+`tests/sources.test.ts` fails while a copy is stale.
+
+## Favicon
+
+`@dogsbay/render-html/favicon` exports the Dogsbay paw (`FAVICON_SVG`, and
+`FAVICON_DATA_URI` for a self-contained page); the source with its design notes
+is `assets/favicon.svg`. The code in this package is MIT licensed; the Dogsbay
+name and paw mark are not licensed for use as your own branding. Pages Dogsbay
+renders use it as their default favicon.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/assets/favicon.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <!--
+    Drawn, not traced. The photographic source was pale mint on white and
+    its glass texture survived any threshold as speckle.
+
+    FILLED, not stroked. An outlined version read as a face at size: the
+    negative space between the toes and the pad became two eyes and a
+    mouth once adjacent strokes merged.
+
+    Toes sit slightly high and the pad slightly low so the gaps survive
+    downsampling — at 16px a tighter arrangement fuses the toes into a
+    single bar.
+
+    Theme-aware: the browser composites a favicon against the tab strip,
+    so one fixed colour disappears on either a light or a dark UI.
+  -->
+  <style>
+    .paw { fill: #1e6e7d; }
+    @media (prefers-color-scheme: dark) { .paw { fill: #7fd3e0; } }
+  </style>
+  <g class="paw">
+    <ellipse cx="14.5" cy="29.5" rx="6.3" ry="8.6" transform="rotate(-22 14.5 29.5)"/>
+    <ellipse cx="26" cy="17.5" rx="6.3" ry="9.2" transform="rotate(-8 26 17.5)"/>
+    <ellipse cx="40" cy="17.5" rx="6.3" ry="9.2" transform="rotate(8 40 17.5)"/>
+    <ellipse cx="51.5" cy="29.5" rx="6.3" ry="8.6" transform="rotate(22 51.5 29.5)"/>
+    <path d="M32 36c9.8 0 16.8 6.8 16.8 13.8S41.8 59.5 32 59.5 15.2 54.3 15.2 47.3 22.2 36 32 36Z"/>
+  </g>
+</svg>

package/css/code-rich.css

@@ -0,0 +1,88 @@
+/* Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/ui code-rich.css. Do not edit. */
+/* CodeRich annotation styles — applied via CSS classes from Shiki transformers */
+
+/* ── All lines ────────────────────────────────────────── */
+.code-rich-body .line {
+  /* inline-block, not inline-flex: a flex line makes each token span a flex item, and
+     browsers then copy a hand-made selection with a line break between tokens. */
+  display: inline-block;
+  width: 100%;
+}
+
+/* ── Gutter (single column: line number + diff marker) ── */
+.code-rich-body .gutter {
+  display: inline-block;
+  min-width: 4ch;
+  margin-right: 1.5ch;
+  text-align: right;
+  /* Theme-aware, and NO alpha. This was a fixed dark grey at 70%
+     opacity: fine on a light code background, 1.3:1 against the dark
+     one — line numbers were effectively invisible in dark mode.
+     Opacity compounds it, since it blends toward whatever is behind.
+     --muted-foreground already flips per theme (L 0.45 / 0.708). */
+  color: var(--muted-foreground);
+  user-select: none;
+  flex-shrink: 0;
+}
+.code-rich-body .gutter.add {
+  color: oklch(0.55 0.2 145);
+}
+.code-rich-body .gutter.remove {
+  color: oklch(0.55 0.2 25);
+}
+
+/* Dark mode: the diff gutters sit on TINTED line backgrounds, not on
+   the plain code background, and at L0.55 they measure 2.89:1 (add)
+   and 2.63:1 (remove) there — both well under AA. Light mode is
+   unaffected, so these are overrides rather than a changed base.
+   Raised to L0.72 for headroom over the 4.5:1 floor. */
+.dark .code-rich-body .gutter.add {
+  color: oklch(0.72 0.2 145);
+}
+.dark .code-rich-body .gutter.remove {
+  color: oklch(0.72 0.14 25);
+}
+
+/* ── Diff line backgrounds ────────────────────────────── */
+.code-rich-body .line.diff.add {
+  background-color: oklch(0.75 0.18 145 / 0.15);
+}
+.code-rich-body .line.diff.remove {
+  background-color: oklch(0.65 0.2 25 / 0.15);
+}
+
+/* ── Focus ─────────────────────────────────────────────── */
+.code-rich-body pre.has-focused .line:not(.focused) {
+  opacity: 0.7;
+  transition: opacity 0.3s;
+}
+.code-rich-body pre.has-focused:hover .line:not(.focused) {
+  opacity: 0.9;
+}
+.code-rich-body pre.has-focused .line.focused {
+  opacity: 1;
+}
+
+/* ── Highlight (background only) ──────────────────────── */
+.code-rich-body .line.highlighted {
+  background-color: oklch(0.7 0.1 250 / 0.08);
+}
+
+/* ── Error / Warning / Info levels ─────────────────────── */
+.code-rich-body .line.highlighted.error {
+  background-color: oklch(0.65 0.2 25 / 0.08);
+}
+.code-rich-body .line.highlighted.warning {
+  background-color: oklch(0.75 0.18 65 / 0.08);
+}
+.code-rich-body .line.highlighted.info {
+  background-color: oklch(0.7 0.15 250 / 0.08);
+}
+
+/* ── Word highlight ────────────────────────────────────── */
+.code-rich-body .highlighted-word {
+  background-color: oklch(0.7 0.1 250 / 0.25);
+  border-radius: 3px;
+  padding: 1px 4px;
+  margin: 0 -1px;
+}

package/css/docs.css

@@ -0,0 +1,207 @@
+/* Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/format-astro (generateGlobalCss). Do not edit. */
+
+/* Custom elements have no user-agent style, so an unstyled one is
+   display:inline — on which w-full does nothing and a border paints
+   as detached fragments rather than around the content. @dogsbay/elements
+   injects these same defaults at runtime, which is what reaches EXISTING
+   sites (global.css is scaffolded once and never rewritten). Having them
+   here too means a new site is correct at CSS time, with no flash before
+   the module script runs.
+
+   :where() keeps specificity at zero, so any utility class wins. */
+:where(db-tabs, db-accordion, db-collapsible, db-card, db-steps, db-code-block) {
+  display: block;
+}
+:where(db-link-button) {
+  display: inline-block;
+}
+
+/* Scan @dogsbay packages for Tailwind classes */
+
+/* Pin the grid-tone palette. These classes are emitted into
+   markdown-generated .astro pages by the grid-item serializer
+   (TONE_CLASSES in @dogsbay/format-astro). Without inlining,
+   opacity-modified utilities like bg-primary/10 get purged when
+   Tailwind doesn't see them in the scanned globs, leaving grid
+   demo cells with no visible background. */
+@source inline("bg-amber-500/15 bg-blue-500/15 bg-green-500/15 bg-muted bg-primary bg-primary/10 bg-primary/20 bg-primary/50 bg-primary/60 bg-primary/80 bg-purple-500/15 bg-red-500/15 dark:text-amber-300 dark:text-blue-300 dark:text-green-300 dark:text-purple-300 dark:text-red-300 text-amber-700 text-blue-700 text-green-700 text-muted-foreground text-primary text-primary-foreground text-purple-700 text-red-700");
+
+/* Prose typography for rendered content.
+   Every element rule is guarded with :not(.dba-api *): API-reference
+   regions (ApiLayout root carries the dba-api marker) compose their own
+   typography from utility classes, and unguarded .docs-prose rules would
+   out-specify them. The guard lets mixed prose+endpoint pages (MDX
+   imports) keep full typography outside the cards. */
+.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; }
+
+  & p:not(.dba-api *) { margin-top: 0.75rem; margin-bottom: 0.75rem; }
+
+  /* The :not([data-variant]) guard exempts anchors that ARE components. A
+     link-button renders as an <a> carrying bg-primary + text-primary-foreground
+     and a data-variant attribute, and this rule repainted its text with
+     var(--primary) — primary on primary: an unreadable solid block in light
+     mode, a blank one in dark. The secondary variant survived only because its
+     background is light enough to read primary-coloured text, which is why it
+     looked like a colour bug in one button rather than a cascade bug in both.
+     (No backticks in this comment: the whole stylesheet is a template
+     literal.) */
+  & a:not(.dba-api *):not([data-variant]) { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
+  & a:hover:not(.dba-api *):not([data-variant]) { opacity: 0.8; }
+
+  & strong:not(.dba-api *) { font-weight: 600; }
+  & code:not(.dba-api *) { font-size: 0.875em; padding: 0.15em 0.35em; border-radius: 0.25rem; background: var(--muted); font-family: var(--font-code, ui-monospace, monospace); }
+  & pre code:not(.dba-api *) { padding: 0; background: none; font-size: 1em; }
+
+  /* Spacing between consecutive block elements (code blocks, alerts, etc.) */
+  & > * + * { margin-top: 0.75rem; }
+  & li > * + *:not(.dba-api *) { margin-top: 0.75rem; }
+
+  & ul:not(.dba-api *) { list-style: disc; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & ol:not(.dba-api *) { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & li:not(.dba-api *) { margin: 0.25rem 0; }
+  & li > ul:not(.dba-api *), & li > ol:not(.dba-api *) { margin: 0.25rem 0; }
+
+  & blockquote:not(.dba-api *) { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
+
+  & hr:not(.dba-api *) { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
+
+  & table:not(.dba-api *) { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.875rem; }
+  & th:not(.dba-api *) { text-align: left; vertical-align: bottom; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
+  & td:not(.dba-api *) { padding: 0.5rem; vertical-align: top; border-bottom: 1px solid var(--border); }
+  /* A table's caption is its title, above it; the same for Table components and raw HTML tables */
+  & caption:not(.dba-api *) { caption-side: top; text-align: left; font-weight: 500; color: var(--foreground); padding-bottom: 0.5rem; }
+
+    /* Tailwind Preflight sets display: block on every img, which turns an
+       INLINE icon into its own line and splits the sentence around it —
+       AsciiDoc UI macros render mid-step and were breaking every procedure
+       that used one. inline-block restores the flow and leaves a standalone
+       image (the only child of its paragraph) looking exactly as before. */
+    & img:not(.dba-api *) { display: inline-block; max-width: 100%; border-radius: 0.5rem; }
+    /* A standalone image — the only child of its paragraph — keeps block
+       layout, so the vertical rhythm and the absence of baseline descender
+       space are exactly what they were before inline icons were fixed. */
+    & p > img:only-child:not(.dba-api *) { display: block; }
+
+  & .heading-anchor { text-decoration: none; opacity: 0; margin-right: 0.25rem; transition: opacity 0.2s; }
+  & h1:hover .heading-anchor, & h2:hover .heading-anchor, & h3:hover .heading-anchor, & h4:hover .heading-anchor { opacity: 0.4; }
+
+  & details:not(.dba-api *) { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
+  & summary:not(.dba-api *) { cursor: pointer; font-weight: 600; }
+
+  /* mark is emitted by the highlight directive AND can arrive as raw HTML
+     from an importer. Without a rule here it renders as the browser default
+     yellow, which clashes in light mode and is unreadable on a dark page
+     (nothing declares color-scheme). Token-based so it follows the theme. */
+  & mark:not(.dba-api *) { background: var(--dsb-mark-bg, rgb(254 240 138 / 0.6)); color: inherit; border-radius: 0.125rem; padding: 0 0.125rem; }
+  &:where(.dark *) mark:not(.dba-api *), .dark & mark:not(.dba-api *) { background: var(--dsb-mark-bg-dark, rgb(234 179 8 / 0.3)); }
+
+  & dl:not(.dba-api *) { margin: 1rem 0; }
+  & dt:not(.dba-api *) { font-weight: 600; margin-top: 0.75rem; }
+  & dd:not(.dba-api *) { margin-left: 1.5rem; color: var(--muted-foreground); }
+
+  /* In-cell admonitions. Inside a raw HTML table cell nothing
+     markdown-native works, so the AsciiDoc engine emits a neutral
+     dl.db-admonition shape (DD-010) and this rule renders it as a compact
+     callout box — same contract the Obsidian plugin styles. Per-type
+     accent from theme tokens; overrides the generic dl/dt/dd rules above. */
+  & dl.db-admonition {
+    margin: 0.75rem 0;
+    padding: 0.5rem 0.75rem;
+    border-left: 3px solid var(--info);
+    border-radius: 0.25rem;
+    background: color-mix(in oklab, var(--info) 8%, transparent);
+  }
+  /* The LABEL blends the accent toward the foreground; the border and the
+     tint keep the accent at full strength, so the callout still reads as
+     its colour while the text stays legible.
+  
+     Measured from painted pixels on a real page, light mode, 13px/600 —
+     the accent used raw is a genuine AA failure, not one of axe's oklch
+     misreads:
+  
+       --info        raw 2.18:1   mixed 5.66:1
+       --warning     raw 2.25:1   mixed 5.74:1
+       --destructive raw 5.97:1   mixed 10.98:1
+  
+     Mixed with var(--foreground), not black, on purpose. Black fixes
+     light and BREAKS dark: 70% black measures 5.21:1 light but 3.25:1
+     dark, because the tint it sits on is dark too. --foreground is
+     near-black in light and near-white in dark, so one rule serves both
+     (dark measures 10.96 / 10.87 / 9.79). A fixed colour used in both
+     themes is a bug waiting. */
+  & dl.db-admonition > dt {
+    margin-top: 0;
+    font-weight: 600;
+    font-size: 0.8125rem;
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+    color: color-mix(in oklab, var(--info) 60%, var(--foreground));
+  }
+  & dl.db-admonition > dd { margin-left: 0; margin-top: 0.25rem; color: var(--foreground); }
+  & dl.db-admonition-warning, & dl.db-admonition-caution {
+    border-left-color: var(--warning);
+    background: color-mix(in oklab, var(--warning) 8%, transparent);
+  }
+  & dl.db-admonition-warning > dt, & dl.db-admonition-caution > dt { color: color-mix(in oklab, var(--warning) 60%, var(--foreground)); }
+  & dl.db-admonition-important {
+    border-left-color: var(--destructive);
+    background: color-mix(in oklab, var(--destructive) 8%, transparent);
+  }
+  & dl.db-admonition-important > dt { color: color-mix(in oklab, var(--destructive) 60%, var(--foreground)); }
+
+  /* Granularity book-view affordances (plans/granularity-views.md):
+     "Read as single page →" on topics, "Open as page ↗" on book sections.
+     Deliberately subtle/muted — the book has one per section. */
+  & .dsb-read-single-page {
+    display: inline-block;
+    margin: 0 0 1.25rem;
+    font-size: 0.8125rem;
+    color: var(--muted-foreground);
+    text-decoration: none;
+  }
+  & .dsb-read-single-page:hover { color: var(--foreground); text-decoration: underline; }
+  & .dsb-open-as-page { margin: -0.25rem 0 0.5rem; font-size: 0.75rem; }
+  & .dsb-open-as-page a { color: var(--muted-foreground); text-decoration: none; }
+  & .dsb-open-as-page a:hover { color: var(--foreground); text-decoration: underline; }
+
+  /* AsciiDoc block roles ([role="x"] / [.x]) preserved as classes (#384).
+     _abstract marks a module's lead/intro paragraph; .lead/.small are
+     Asciidoctor built-ins; _additional-resources marks the trailing
+     "Additional resources" section heading. */
+  & ._abstract, & .abstract, & .lead {
+    font-size: 1.05rem;
+    line-height: 1.6;
+    color: var(--muted-foreground);
+  }
+  & .small { font-size: 0.875rem; }
+  & h2._additional-resources, & h3._additional-resources {
+    font-size: 1.15rem;
+    margin-top: 2rem;
+  }
+
+  /* Related resources (#384 R3): [role="_additional-resources"] + .Title +
+     list folds to a <section class="related-resources"> (→ DITA related-links). */
+  & .related-resources {
+    margin-top: 2rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+  }
+  & .related-resources-title {
+    font-weight: 600;
+    margin: 0 0 0.5rem;
+  }
+}
+
+@utility scrollbar-none {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}

package/css/steps.css

@@ -0,0 +1,149 @@
+/* Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/ui Steps.astro, SubSteps.astro. Do not edit. */
+
+  .steps-list {
+    position: relative;
+    padding-left: 1.75rem;
+    counter-reset: step;
+    list-style: none;
+    margin: 0;
+  }
+
+  .steps-list > li {
+    position: relative;
+    padding-bottom: 1.5rem;
+    counter-increment: step;
+  }
+
+  .steps-list > li:last-child {
+    padding-bottom: 0;
+  }
+
+  /* Numbered circle */
+  .steps-list > li::before {
+    content: counter(step);
+    position: absolute;
+    left: -1.75rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    border-radius: 9999px;
+    border: 2px solid var(--color-border);
+    background: var(--color-background);
+    color: var(--color-foreground);
+    font-size: 0.75rem;
+    font-weight: 600;
+    line-height: 1;
+  }
+
+  /* Connector line */
+  .steps-list > li:not(:last-child)::after {
+    content: "";
+    position: absolute;
+    left: calc(-1.75rem + 0.6875rem);
+    top: 1.75rem;
+    bottom: 0;
+    width: 1px;
+    background: var(--color-border);
+  }
+
+  /* Sub-steps: nested ol inside li */
+  .steps-list > li ol {
+    position: relative;
+    padding-left: 1.5rem;
+    counter-reset: substep;
+    list-style: none;
+    margin: 0.75rem 0 0 0;
+  }
+
+  .steps-list > li ol > li {
+    position: relative;
+    padding-bottom: 1rem;
+    counter-increment: substep;
+  }
+
+  .steps-list > li ol > li:last-child {
+    padding-bottom: 0;
+  }
+
+  /* Lettered circle (a, b, c) */
+  .steps-list > li ol > li::before {
+    content: counter(substep, lower-alpha);
+    position: absolute;
+    left: -1.5rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.25rem;
+    height: 1.25rem;
+    border-radius: 9999px;
+    border: 1.5px solid var(--color-border);
+    background: var(--color-background);
+    color: var(--color-muted-foreground, #737373);
+    font-size: 0.625rem;
+    font-weight: 600;
+    line-height: 1;
+  }
+
+  /* Sub-step connector line */
+  .steps-list > li ol > li:not(:last-child)::after {
+    content: "";
+    position: absolute;
+    left: calc(-1.5rem + 0.5625rem);
+    top: 1.5rem;
+    bottom: 0;
+    width: 1px;
+    background: var(--color-border);
+    opacity: 0.6;
+  }
+
+
+  .sub-steps-list {
+    position: relative;
+    padding-left: 1.5rem;
+    counter-reset: substep;
+    list-style: none;
+    margin: 0.75rem 0 0 0;
+  }
+
+  .sub-steps-list > li {
+    position: relative;
+    padding-bottom: 1rem;
+    counter-increment: substep;
+  }
+
+  .sub-steps-list > li:last-child {
+    padding-bottom: 0;
+  }
+
+  /* Lettered circle (a, b, c) */
+  .sub-steps-list > li::before {
+    content: counter(substep, lower-alpha);
+    position: absolute;
+    left: -1.5rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.25rem;
+    height: 1.25rem;
+    border-radius: 9999px;
+    border: 1.5px solid var(--color-border);
+    background: var(--color-background);
+    color: var(--color-muted-foreground, #737373);
+    font-size: 0.625rem;
+    font-weight: 600;
+    line-height: 1;
+  }
+
+  /* Connector line (thinner) */
+  .sub-steps-list > li:not(:last-child)::after {
+    content: "";
+    position: absolute;
+    left: calc(-1.5rem + 0.5625rem);
+    top: 1.5rem;
+    bottom: 0;
+    width: 1px;
+    background: var(--color-border);
+    opacity: 0.6;
+  }