@reblu/site-blocks 0.4.0 → 0.4.2

package/README.md

@@ -26,6 +26,71 @@ a different-looking site for every tenant, with zero forks.
 - **`@reblu/site-blocks`** = organisms + headless data hooks. Higher churn — its
   own package so a breaking change in an organism does not bump the stable atoms.
 
+## Authoring notes
+
+What `MarkdownRenderer` does with tenant-authored Markdown and HTML. These are
+**content** rules, not styling ones — they change what a page says, so they
+matter most on legal pages (privacy policy, terms), which nobody on the platform
+side proofreads before a visitor sees them.
+
+### A single newline is not a line break
+
+```md
+Calle Mayor 1
+28001 Madrid
+```
+
+renders as one paragraph reading `Calle Mayor 1 28001 Madrid`. This is standard
+CommonMark — a lone newline is a *soft* break, i.e. whitespace — and it is what
+this renderer has done since it replaced the interim, non-standard one that
+emitted a `<br>` for every newline. **Text written under the old behaviour reads
+differently now**, so addresses, signature blocks and enumerated clauses typed on
+consecutive lines are worth re-reading.
+
+To force a visible break, use any of:
+
+| Want | Write |
+| ---- | ----- |
+| A new paragraph | A blank line between the two lines |
+| A hard break inside one paragraph | Two spaces at the end of the first line |
+| A hard break, visibly | A trailing `\` at the end of the first line |
+
+### `hidden` hides a block — it does not withhold it
+
+An element marked `hidden` is not rendered and is not announced to a screen
+reader. It **is** still present in the HTML the server sends. Anyone who opens
+the page source reads it, and so does any crawler working on raw HTML.
+
+That is exactly what the HTML specification says `hidden` means, and for most
+uses it is the right behaviour. It is called out here because the wording in
+`0.4.0`'s changelog — "a block the author marked as not-for-publication stays
+unpublished" — promises more than the attribute delivers, and an author who
+believes it will reach for `hidden` to do something it cannot do.
+
+So: a half-written clause left in a privacy policy behind `hidden` is invisible
+on the page and published all the same. **To keep text unpublished, keep it out
+of the page.** Draft it somewhere that is not the document body.
+
+### Ordered lists keep the number you wrote
+
+`4. …` renders as a list starting at 4, not at 1 — so "as established in clause
+4" still points at a `4`. The marker style (`type`) and an item's explicit number
+(`value`) survive too.
+
+### Which authored attributes survive
+
+The renderer rebuilds each element to apply the tenant's design tokens and to
+harden external links, and it forwards only the attributes that carry **meaning**:
+
+- **Kept:** `id` (so in-document `#anchor` links resolve), `lang`, `dir`,
+  `title`, `hidden`, `role`, every `aria-*` and every `data-*`, plus `start`/`type`
+  on `<ol>` and `value`/`type` on `<li>`.
+- **Dropped:** `class` and `style` — presentation belongs to the tenant's theme,
+  not to the document body — and `target`/`rel` on links, which the renderer sets
+  itself so an external link is always `noopener noreferrer`.
+- **Dropped upstream by the sanitiser, before the renderer sees it:** `reversed`
+  on `<ol>`. Number a descending list explicitly with `value` on each `<li>`.
+
 ## Security boundaries
 
 Two sinks, two different helpers, in two different packages — do not reach for

package/dist/index.cjs

@@ -13061,6 +13061,41 @@ var HEADING_CLASSES = {
 function hasClass(el, name) {
   return typeof el.attribs.class === "string" && el.attribs.class.split(/\s+/).includes(name);
 }
+var PRESERVED_GLOBAL_ATTRIBUTES = [
+  // Anchor targets. In-document links ("see clause 4" → `#clause-4`) resolve to
+  // nothing without them.
+  "id",
+  // Language and direction of a passage — a bilingual legal page is the normal case
+  // here, and screen readers switch voice on it.
+  "lang",
+  "dir",
+  // Advisory text the author wrote; it is content, not styling.
+  "title",
+  // Explicit "do not publish this". Without it a block authored as `<p hidden>`
+  // becomes VISIBLE — publishing what the author marked as not-for-publication.
+  "hidden",
+  // Accessible semantics. `../lib/markdown` restores these through the sanitiser
+  // precisely so they are not lost (REB-286's axe gate); dropping them one layer
+  // later would undo that.
+  "role"
+];
+var PRESERVED_ATTRIBUTE_PREFIXES = ["aria-", "data-"];
+var PRESERVED_TAG_ATTRIBUTES = {
+  ol: ["start", "type"],
+  li: ["value", "type"]
+};
+var BOOLEAN_ATTRIBUTES = /* @__PURE__ */ new Set(["hidden"]);
+function authorAttributes(el) {
+  const tagSpecific = PRESERVED_TAG_ATTRIBUTES[el.name] ?? [];
+  const preserved = {};
+  for (const [rawName, value] of Object.entries(el.attribs)) {
+    const name = rawName.toLowerCase();
+    const keep = PRESERVED_GLOBAL_ATTRIBUTES.includes(name) || tagSpecific.includes(name) || PRESERVED_ATTRIBUTE_PREFIXES.some((prefix) => name.startsWith(prefix));
+    if (!keep) continue;
+    preserved[name] = BOOLEAN_ATTRIBUTES.has(name) ? true : value;
+  }
+  return preserved;
+}
 function isExternalHref(href) {
   return !!href && /^(https?:)?\/\//.test(href);
 }
@@ -13070,29 +13105,46 @@ function buildOptions(headingOffset) {
       if (!(node instanceof import_html_react_parser.Element)) return void 0;
       const children2 = () => (0, import_html_react_parser.domToReact)(node.children, options);
       const { name, attribs } = node;
+      const author = authorAttributes(node);
       const headingMatch = /^h([1-6])$/.exec(name);
       if (headingMatch) {
         const rendered = Math.min(6, Number(headingMatch[1]) + headingOffset);
         const Tag = `h${rendered}`;
-        return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Tag, { className: HEADING_CLASSES[rendered], children: children2() });
+        return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Tag, { ...author, className: HEADING_CLASSES[rendered], children: children2() });
       }
       switch (name) {
         case "p":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "my-4 leading-relaxed text-foreground/90", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { ...author, className: "my-4 leading-relaxed text-foreground/90", children: children2() });
         case "ul":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("ul", { className: hasClass(node, "contains-task-list") ? "list-none pl-0 my-4 space-y-1" : "list-disc ml-6 my-4", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("ul", { ...author, className: hasClass(node, "contains-task-list") ? "list-none pl-0 my-4 space-y-1" : "list-disc ml-6 my-4", children: children2() });
         case "ol":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("ol", { className: "list-decimal ml-6 my-4", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("ol", { ...author, className: "list-decimal ml-6 my-4", children: children2() });
         case "li":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("li", { className: hasClass(node, "task-list-item") ? "flex items-start gap-2 my-1" : "my-1", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("li", { ...author, className: hasClass(node, "task-list-item") ? "flex items-start gap-2 my-1" : "my-1", children: children2() });
         case "blockquote":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("blockquote", { className: "border-l-4 border-primary/50 pl-6 italic my-6 text-muted-foreground", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "blockquote",
+            {
+              ...author,
+              className: "border-l-4 border-primary/50 pl-6 italic my-6 text-muted-foreground",
+              children: children2()
+            }
+          );
         case "pre":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("pre", { className: "rounded-lg border border-input bg-muted p-4 my-6 overflow-x-auto font-mono text-sm", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "pre",
+            {
+              ...author,
+              className: "rounded-lg border border-input bg-muted p-4 my-6 overflow-x-auto font-mono text-sm",
+              children: children2()
+            }
+          );
         case "code": {
           const isBlock = node.parent instanceof import_html_react_parser.Element && node.parent.name === "pre";
-          if (isBlock) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("code", { className: "block", children: children2() });
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("code", { className: "rounded bg-muted px-1.5 py-0.5 font-mono text-sm", children: children2() });
+          if (isBlock) {
+            return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("code", { ...author, className: "block", children: children2() });
+          }
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("code", { ...author, className: "rounded bg-muted px-1.5 py-0.5 font-mono text-sm", children: children2() });
         }
         case "a": {
           const href = attribs.href;
@@ -13100,6 +13152,7 @@ function buildOptions(headingOffset) {
           return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
             "a",
             {
+              ...author,
               href,
               className: "text-primary underline underline-offset-4 hover:text-primary/80",
               ...external ? { target: "_blank", rel: "noopener noreferrer" } : {},
@@ -13116,6 +13169,7 @@ function buildOptions(headingOffset) {
             /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
               "img",
               {
+                ...author,
                 src: attribs.src,
                 alt: attribs.alt ?? "",
                 loading: "lazy",
@@ -13127,6 +13181,7 @@ function buildOptions(headingOffset) {
           return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "relative my-6 aspect-video w-full overflow-hidden rounded-lg", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
             "iframe",
             {
+              ...author,
               src: attribs.src,
               title: attribs.title ?? "Embedded video",
               allow: attribs.allow ?? "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture",
@@ -13135,13 +13190,13 @@ function buildOptions(headingOffset) {
             }
           ) });
         case "hr":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("hr", { className: "my-8 border-muted-foreground/30" });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("hr", { ...author, className: "my-8 border-muted-foreground/30" });
         case "strong":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("strong", { className: "font-bold text-foreground", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("strong", { ...author, className: "font-bold text-foreground", children: children2() });
         case "em":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("em", { className: "italic", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("em", { ...author, className: "italic", children: children2() });
         case "del":
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("del", { className: "line-through", children: children2() });
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("del", { ...author, className: "line-through", children: children2() });
         default:
           return void 0;
       }