@lotics/ui 41.3.0 → 41.4.0

package/MIGRATION.md

@@ -4,6 +4,23 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 41.4.0 — embedded markdown is demoted in the OUTLINE, not only on the type ladder
+
+`<Markdown variant="embedded">` sized its headings down and left them as the tags the author
+wrote, so an `h2` inside a record value still landed in heading navigation as a PEER of the
+page's own sections. Measured on a record surface, the outline read:
+
+> Activity · "Tóm tắt cuộc họp (AI) — …" · "Bài học …" · Details · Next action
+
+— a model's call-summary title between two real sections, contributed from inside ONE row of a
+feed that can hold twenty more. Nothing visual finds this, and fixing the size is what makes it
+invisible: the defect stops looking wrong at the moment it stops being measurable.
+
+Embedded headings now render `h4`/`h5`/`h6` (h1→h4, h2→h5, h3 and deeper→h6). They stay
+headings, so a reader can still navigate inside a long summary; they simply can no longer reach
+a section's level. **Nothing to migrate** — document-scale markdown is untouched, and the
+embedded type scale is unchanged.
+
 ## 41.3.0 — `Timeline` rows, embedded markdown, and a disclosure that is not a link
 
 Nothing here removes an API or breaks a type. Two of the changes alter what your rows render on

package/docs/catalog.md

@@ -413,7 +413,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   field on a record, a summary in a feed row. Reach for `"embedded"` whenever the
   text was not written by whoever built the screen, which is now the common case
   because the writer is routinely a model; at document scale an `h1` it emits is
-  the same rung as your `SectionHeadingTitle`.
+  the same rung as your `SectionHeadingTitle`. Embedded demotes the heading LEVEL as well as
+  the scale (h1→h4, h2→h5, h3+→h6): sizing alone leaves a model's `##` announcing as a PEER of
+  your own sections in heading navigation, which no visual check can see.
 - **`markdown_types`** — `MarkdownProps`; types only.
 - **`markdown.css`** — import once for the web markdown styling.
 - **`format_date`** — `formatDate` / `parseDate` / `toISODate` + `DateFormatStyle`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "41.3.0",
+  "version": "41.4.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/markdown.web.tsx

@@ -8,10 +8,14 @@ import { colors } from "./colors";
 import type { MarkdownProps } from "./markdown_types";
 
 export function Markdown({ children, variant = "document" }: MarkdownProps) {
+  const embedded = variant === "embedded";
   return (
     <View>
-      <div className={variant === "embedded" ? "ui-markdown ui-markdown-embedded" : "ui-markdown"}>
-        <ReactMarkdown remarkPlugins={[remarkGfmSafe]} components={markdownComponents}>
+      <div className={embedded ? "ui-markdown ui-markdown-embedded" : "ui-markdown"}>
+        <ReactMarkdown
+          remarkPlugins={[remarkGfmSafe]}
+          components={embedded ? embeddedComponents : markdownComponents}
+        >
           {children}
         </ReactMarkdown>
       </div>
@@ -24,6 +28,56 @@ const markdownComponents = {
   table: CopyableTable,
 };
 
+/**
+ * EMBEDDED MARKDOWN IS DEMOTED IN THE OUTLINE, not only on the type ladder.
+ *
+ * Sizing the headings down fixes what a screen SHOWS and nothing about what it
+ * ANNOUNCES: an `h2` the author of the text happened to write is still an `h2`,
+ * so it lands in heading navigation as a PEER of the page's own sections.
+ * Measured on a record surface, the outline read
+ *
+ *   Activity · "Tóm tắt cuộc họp (AI) — …" · "Bài học …" · Details · Next action
+ *
+ * — a model's call-summary title sitting between two real sections, from inside
+ * one row of a feed that can hold twenty more. No visual probe finds this, and
+ * fixing the size is what makes it invisible: the defect stops looking wrong at
+ * the exact moment it stops being measurable.
+ *
+ * The page's sections are `h2` (`SectionHeading`), and embedded markdown is a
+ * VALUE inside one — inside a row, usually — so it starts at `h4`: deep enough
+ * that it can never be a section's peer, shallow enough to keep its own
+ * hierarchy. It stays a heading rather than becoming a `<div>`, because a long
+ * summary genuinely has parts and a reader navigating INSIDE it should still
+ * find them.
+ */
+const EMBEDDED_HEADING_LEVEL: Record<string, "h4" | "h5" | "h6"> = {
+  h1: "h4",
+  h2: "h5",
+  h3: "h6",
+  h4: "h6",
+  h5: "h6",
+  h6: "h6",
+};
+
+type HeadingProps = React.ComponentPropsWithoutRef<"h4"> & { node?: unknown };
+
+function embeddedHeading(from: keyof typeof EMBEDDED_HEADING_LEVEL) {
+  const Tag = EMBEDDED_HEADING_LEVEL[from];
+  return function EmbeddedHeading({ node: _node, children, ...rest }: HeadingProps) {
+    return <Tag {...rest}>{children}</Tag>;
+  };
+}
+
+const embeddedComponents = {
+  ...markdownComponents,
+  h1: embeddedHeading("h1"),
+  h2: embeddedHeading("h2"),
+  h3: embeddedHeading("h3"),
+  h4: embeddedHeading("h4"),
+  h5: embeddedHeading("h5"),
+  h6: embeddedHeading("h6"),
+};
+
 function CopyableTable(props: React.ComponentPropsWithoutRef<"table"> & { node?: unknown }) {
   const { node: _node, children, ...rest } = props;
   const tableRef = useRef<HTMLTableElement>(null);