@jarenjs/md 0.34.0

package/src/utils.js

@@ -0,0 +1,107 @@
+//@ts-check
+/**
+ * @file Small shared helpers for the md package.
+ *
+ * The content hash is the package's identity primitive — block vnode
+ * keys, the document `meta.hash`, and the mermaid SVG cache are all keyed
+ * by it — so md re-exports the suite's single `hashContent` from
+ * `@jarenjs/core` rather than carrying its own copy; equal content hits
+ * O(1) fast paths everywhere downstream. `fnv1a` is that same mixing
+ * step, exposed for the two callers that fold a hash incrementally (the
+ * streaming parser's chunks, the structural block-key walk) and so must
+ * seed it themselves from `FNV1A_OFFSET_BASIS`. Heading slugs come from
+ * the same place for the same reason: `slugify` is a pure text→fragment
+ * transform with no Markdown knowledge, so the suite keeps exactly one
+ * of it. The remaining helpers are md's own allocation-light scanner
+ * utilities.
+ */
+
+import { slugify } from '@jarenjs/core/string';
+
+export { hashContent, fnv1a, FNV1A_OFFSET_BASIS, slugify } from '@jarenjs/core/string';
+
+/**
+ * The `id` for one heading, unique within one emission.
+ *
+ * Both emitters mint ids, so the rule lives here once: slug the text,
+ * substitute `section` when nothing slug-worthy survives, number
+ * repeats the way GitHub numbers them (`setup`, `setup-1`, `setup-2`)
+ * and prefix the result. The COUNTER belongs to the caller — one map per
+ * emission, never shared with another numbering (a block key's hash and
+ * a slug share a namespace only by accident, and a collision there would
+ * shift an unrelated heading's number).
+ *
+ * @param {string} text the heading's plain text (`textOf`)
+ * @param {Map<string, number>} seen the emission's slug counter
+ * @param {string} prefix prepended to the result
+ * @returns {string}
+ */
+export function headingId(text, seen, prefix) {
+  const base = slugify(text) || 'section';
+  const count = seen.get(base) ?? 0;
+  seen.set(base, count + 1);
+  return prefix + (count === 0 ? base : base + '-' + count);
+}
+
+/**
+ * The accessible name for a heading's permalink affordance — `#` alone
+ * names nothing, so the link says which section it points at.
+ * @param {string} text the heading's plain text (`textOf`)
+ * @returns {string}
+ */
+export function permalinkLabel(text) {
+  const trimmed = text.trim();
+  return trimmed === '' ? 'Permalink to this section' : 'Permalink to ' + trimmed;
+}
+
+/**
+ * Count leading space characters (U+0020 only; the scanner expands no
+ * tabs here — callers pass detabbed text).
+ * @param {string} line
+ * @returns {number}
+ */
+export function countIndent(line) {
+  let i = 0;
+  while (i < line.length && line.charCodeAt(i) === 32) i++;
+  return i;
+}
+
+/**
+ * Is the line blank (empty or whitespace-only)?
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function isBlankLine(line) {
+  for (let i = 0; i < line.length; i++) {
+    const c = line.charCodeAt(i);
+    if (c !== 32 && c !== 9) return false;
+  }
+  return true;
+}
+
+/**
+ * Replace tabs with spaces to the next 4-column tab stop, counting
+ * columns from `startColumn`. Lines without tabs return the same
+ * string reference (the common case allocates nothing).
+ * @param {string} line
+ * @param {number} [startColumn]
+ * @returns {string}
+ */
+export function expandTabs(line, startColumn = 0) {
+  if (line.indexOf('\t') === -1) return line;
+  let out = '';
+  let column = startColumn;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '\t') {
+      const width = 4 - (column % 4);
+      out += '    '.slice(0, width);
+      column += width;
+    }
+    else {
+      out += ch;
+      column++;
+    }
+  }
+  return out;
+}

package/styles/md.css

@@ -0,0 +1,238 @@
+/*
+ * @jarenjs/md — the visual component's stylesheet.
+ *
+ * Scoped under the `.md` article the vnode emitter produces, plus the
+ * `tok-*` token classes of the highlight plugin (docs/PLUGINS.md §6.2)
+ * and the mermaid placeholder. Colors come in a light set and a dark
+ * override activated by a `.dark` class on any ancestor (the
+ * convention the jarenjs website uses); everything sizes in em so the
+ * component inherits its host's type scale.
+ */
+
+.md {
+  line-height: 1.6;
+  overflow-wrap: break-word;
+}
+
+.md > :first-child { margin-top: 0; }
+.md > :last-child { margin-bottom: 0; }
+
+.md h1, .md h2, .md h3, .md h4, .md h5, .md h6 {
+  line-height: 1.25;
+  margin: 1.4em 0 0.5em;
+}
+.md h1 { font-size: 1.7em; }
+.md h2 { font-size: 1.4em; }
+.md h3 { font-size: 1.2em; }
+
+/* A fragment scrolled into view lands under a sticky header unless the
+   target reserves the room itself. That is a layout concern, so it lives
+   here and not in whatever scrolls the page: a host with a header of its
+   own sets `--md-scroll-margin`, one without keeps a little breathing
+   room above the heading. */
+.md :is(h1, h2, h3, h4, h5, h6) { scroll-margin-top: var(--md-scroll-margin, 4.5rem); }
+
+/* --- heading anchors (`headingAnchors: true`) ---------------------- */
+/* The affordance is quiet until the heading is hovered or the link is
+   focused, so a document does not read as a column of `#`. It stays in
+   the DOM either way — hiding it with `display: none` would take it off
+   the keyboard, and it is the keyboard path that needs it most. */
+.md .md-anchor {
+  margin-left: 0.35em;
+  color: var(--md-muted, #5b6472);
+  font-weight: 400;
+  text-decoration: none;
+  opacity: 0;
+  transition: opacity 120ms ease;
+}
+.md :is(h1, h2, h3, h4, h5, h6):hover .md-anchor,
+.md .md-anchor:focus-visible { opacity: 1; }
+.md .md-anchor:hover { color: var(--md-link, #2456c4); }
+.md .md-anchor:focus-visible {
+  outline: 2px solid var(--md-link, #2456c4);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .md .md-anchor { transition: none; }
+}
+
+.md p, .md ul, .md ol, .md table { margin: 0.6em 0; }
+.md ul, .md ol { padding-left: 1.5em; }
+.md li > ul, .md li > ol { margin: 0.15em 0; }
+.md li { margin: 0.15em 0; }
+
+.md blockquote {
+  margin: 0.8em 0;
+  padding: 0.1em 1em;
+  border-left: 3px solid var(--md-rule, #d0d4dc);
+  color: var(--md-muted, #5b6472);
+}
+
+.md hr {
+  border: 0;
+  border-top: 1px solid var(--md-rule, #d0d4dc);
+  margin: 1.4em 0;
+}
+
+.md a { color: var(--md-link, #2456c4); }
+
+.md code {
+  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;
+  font-size: 0.92em;
+  background: var(--md-code-bg, #f2f4f8);
+  border-radius: 4px;
+  padding: 0.1em 0.35em;
+}
+
+.md pre {
+  margin: 0.8em 0;
+  padding: 0.8em 1em;
+  overflow-x: auto;
+  background: var(--md-code-bg, #f2f4f8);
+  border-radius: 8px;
+}
+.md pre code {
+  background: none;
+  padding: 0;
+  font-size: 0.88em;
+}
+
+.md table {
+  border-collapse: collapse;
+  display: block;
+  overflow-x: auto;
+}
+.md th, .md td {
+  border: 1px solid var(--md-rule, #d0d4dc);
+  padding: 0.35em 0.7em;
+}
+.md th { background: var(--md-code-bg, #f2f4f8); }
+
+.md img { max-width: 100%; }
+
+/* --- GFM footnotes ------------------------------------------------- */
+/* The section is appended after the last block of the document, so it
+   needs the rule a reader expects between a document and its notes —
+   the emitter writes no `<hr>` of its own, because that would be a
+   thematic break the author did not write. Small type, muted, and the
+   back-arrow sized so a thumb can hit it. */
+.md .footnotes {
+  margin-top: 2em;
+  padding-top: 0.8em;
+  border-top: 1px solid var(--md-rule, #d0d4dc);
+  font-size: 0.9em;
+  color: var(--md-muted, #5b6472);
+}
+.md .footnotes > ol { margin: 0; }
+.md .footnotes li { margin: 0.3em 0; }
+.md .footnotes p { margin: 0.3em 0; }
+/* The cited note is highlighted when a reader jumps to it, so a landing
+   in the middle of a list of notes says which one it landed on. */
+.md .footnotes li:target { background: var(--md-code-bg, #f2f4f8); }
+
+.md .footnote-backref {
+  text-decoration: none;
+  padding: 0 0.25em;
+  font-size: 1.1em;
+  line-height: 1;
+}
+.md .footnote-backref sup { font-size: 0.7em; }
+
+/* A citation is small and easy to miss; give it a target a pointer can
+   land on without shifting the line it sits in. */
+.md sup > a { text-decoration: none; padding: 0 0.15em; }
+.md sup > a:hover { text-decoration: underline; }
+
+.md input[type='checkbox'] { margin-right: 0.4em; }
+
+/* --- highlight plugin token colors (PLUGINS.md §6.2) --------------- */
+
+.md .tok-kw  { color: var(--md-tok-kw, #0550ae); }
+.md .tok-str { color: var(--md-tok-str, #50a14f); }
+.md .tok-num { color: var(--md-tok-num, #b76b01); }
+.md .tok-com { color: var(--md-tok-com, #8b919c); font-style: italic; }
+.md .tok-pun { color: var(--md-tok-pun, #526069); }
+.md .tok-op  { color: var(--md-tok-op, #0184bc); }
+.md .tok-lit { color: var(--md-tok-lit, #b76b01); }
+
+/* --- mermaid placeholder / upgrade (PLUGINS.md §6.1) --------------- */
+
+.md-mermaid {
+  /* A diagram is a figure, not a run of text: giving it a surface and a
+     frame separates it from the prose around it and stops a wide diagram
+     from reading as part of the paragraph above. */
+  margin: 1.2em 0;
+  padding: 1rem;
+  text-align: center;
+  background: var(--md-figure-bg, #fbfcfe);
+  border: 1px solid var(--md-rule, #d0d4dc);
+  border-radius: 10px;
+}
+.md-mermaid .md-mermaid-src {
+  text-align: left;
+  color: var(--md-muted, #5b6472);
+}
+/* The diagram's own sizing (natural size, scroll rather than shrink) lives in
+   @jarenjs/mermaid's stylesheet, which owns the element the plugin emits. */
+
+/* --- the optional interactive viewer ------------------------------- */
+/* Only present once `mermaidPlugin({ interactive: true })` has hydrated:
+   the server-rendered figure carries none of this. */
+.md-mermaid.mm-interactive {
+  position: relative;
+  cursor: grab;
+}
+.md-mermaid.mm-interactive:focus-visible {
+  outline: 2px solid var(--md-link, #2563eb);
+  outline-offset: 2px;
+}
+.md-mermaid.mm-interactive:active { cursor: grabbing; }
+.md-mermaid .mm-controls {
+  position: absolute;
+  right: 0.5rem;
+  bottom: 0.5rem;
+  display: flex;
+  gap: 0.25rem;
+  opacity: 0.35;
+  transition: opacity 120ms ease;
+}
+.md-mermaid:hover .mm-controls,
+.md-mermaid:focus-within .mm-controls { opacity: 1; }
+.md-mermaid .mm-control {
+  /* 32px is below the 44px touch target the site requires elsewhere, so
+     these are a convenience: every action they offer is also on the
+     keyboard and in the pinch gesture. */
+  min-width: 2rem;
+  min-height: 2rem;
+  padding: 0;
+  font-size: 1rem;
+  line-height: 1;
+  color: var(--md-muted, #5b6472);
+  background: var(--md-figure-bg, #fbfcfe);
+  border: 1px solid var(--md-rule, #d0d4dc);
+  border-radius: 8px;
+  cursor: pointer;
+}
+.md-mermaid .mm-control:hover { color: var(--md-link, #2563eb); }
+
+@media (prefers-reduced-motion: reduce) {
+  .md-mermaid .mm-controls { transition: none; }
+}
+
+/* --- dark scheme --------------------------------------------------- */
+
+.dark .md, .md.dark {
+  --md-figure-bg: #171b22;
+  --md-rule: #39414e;
+  --md-muted: #9aa4b2;
+  --md-link: #7aa2ff;
+  --md-code-bg: #1d232c;
+  --md-tok-kw: #79b8ff;
+  --md-tok-str: #98c379;
+  --md-tok-num: #d19a66;
+  --md-tok-com: #7f848e;
+  --md-tok-pun: #9aa4b2;
+  --md-tok-op: #56b6c2;
+  --md-tok-lit: #d19a66;
+}