@nuucognition/ncm-ui 0.1.0-dev.1 → 0.1.1-beta.1

package/README.md

@@ -102,6 +102,81 @@ import { NcmDocument, SanitizedHtmlBlock } from "@nuucognition/ncm-ui"
 markup. Keep `HtmlBlock` as the default for untrusted documents. Use
 `SanitizedHtmlBlock` only when the surface intentionally supports HTML.
 
+## Embeds
+
+`![[target]]` and `![alt](url)` render through `EmbeddingsConfig` on `NcmConfig`.
+Everything below is optional; a config that omits a key gets the behaviour the
+package has always had.
+
+| Key | Effect |
+|---|---|
+| `resolveUrl(target, embedType)` | Turn an authored target into a fetchable URL. |
+| `renderers` | Per-embed-type block renderers. |
+| `imageClassName` / `videoClassName` / `audioClassName` | Class names on the media elements. |
+| `renderImageError` | Draw a failed image instead of leaving the browser's broken-image box. |
+| `onEmbedClick` | Make a non-media embed a real control instead of an `<a href>`. |
+
+### Failed images
+
+Whether an `<img>` actually loads is only learned by trying, and what to say
+about the failure is the host's vocabulary — a mesh embedder can retry against
+its own blob cache; a static-site embedder has nothing to retry.
+
+```tsx
+<NcmProvider config={{
+  embeddings: {
+    renderImageError: ({ target, retry }) => (
+      <button type="button" onClick={() => { myCache.refresh(target); retry() }}>
+        {target} didn’t load — retry
+      </button>
+    ),
+  },
+}}>
+```
+
+**Opt-in, strictly.** With no renderer supplied the `<img>` carries no `onError`
+handler at all, so the emitted DOM is identical to what it has always been — not
+merely visually identical. `retry` re-keys the element, so it is a real second
+request rather than the browser replaying its cached failure.
+
+### Non-media embeds
+
+An `![[target]]` with no player — an embedded document, or any unrecognised type
+— renders as `<a href={resolveUrl(...)}>`. That is only honest when the target
+really has a URL. In a title-addressed mesh a document does not: the host
+navigates in its own state, so the href ends up being the raw target.
+
+Supply `onEmbedClick` and the same content renders as a `<button>` instead,
+claiming nothing about URLs — the shape `inline.onWikiLinkClick` already
+produces for a wikilink with no href.
+
+```tsx
+<NcmProvider config={{
+  embeddings: {
+    onEmbedClick: (target, result) => openDocument(result?.resolved?.title ?? target),
+  },
+}}>
+```
+
+### Reference states in the shipped themes
+
+`nuu.css` and `paper.css` paint three states of a wikilink or embed, and they
+mean the same thing in both themes:
+
+| State | Treatment | Why |
+|---|---|---|
+| resolved | link colour, solid underline | it goes somewhere |
+| `missing` | muted foreground, **dashed** | not an error — a link to a document that is not in this mesh is very often a plan. Matches Obsidian, where an unresolved link is the link colour faded, never red. |
+| `ambiguous` | warning amber, **dotted** | several targets match; something to decide, nothing has failed |
+
+Red is reserved for genuine failure — an embed whose bytes did not arrive.
+
+> **Changed in the 513 batch:** `ambiguous` used to be painted with
+> `--fire-text`/`--destructive`, i.e. red, in both themes. That is a deliberate
+> visual change for every embedder. It was made because the editor surface in
+> the same product paints red for a *missing* link, so one hue carried two
+> different facts depending on which mode a reader was in.
+
 ## Math And Code Rendering
 
 KaTeX is lazy-loaded and memoized, so documents without math do not pay the
@@ -116,8 +191,23 @@ pnpm --filter @nuucognition/ncm-ui lint
 pnpm --filter @nuucognition/ncm-ui typecheck
 pnpm --filter @nuucognition/ncm-ui build
 pnpm --filter @nuucognition/ncm-ui test
+pnpm --filter @nuucognition/ncm-ui exec tsx scripts/render-compat.mjs
 ```
 
+`render-compat.mjs` is the **published-API compatibility gate**. This package
+has backward-compatibility obligations, so an added optional callback has one
+test that matters: a consumer that does not pass it must get the same *bytes*.
+The script renders fixed fixtures under a bare config, under the shape a real
+host passes today, and under a config with every option supplied, and compares
+against hand-written expected markup. The expectations are literal strings on
+purpose — a snapshot a worker can re-bless is not a gate. It also mounts into
+jsdom and dispatches a real `error` event, because a check written only against
+server markup would report the failure path working while it was unreachable.
+
+Note that `vitest.config.ts` pins `NODE_ENV=test`. React's production build does
+not export `act`, so a shell that exports `NODE_ENV=production` makes four tests
+fail for reasons that have nothing to do with this package.
+
 The root NCM gate runs both `@nuucognition/ncm-tests` and `@nuucognition/ncm-ui`:
 
 ```bash

package/dist/blocks/admonition/index.d.ts

@@ -1,13 +1,12 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { AdmonitionBlock as AdmonitionBlock$1 } from '@nuucognition/ncm';
 import { a as BlockRendererProps } from '../../renderers-C5f41FCy.js';
-import 'react';
 
 type AdmonitionBlockProps = BlockRendererProps<AdmonitionBlock$1>;
 /**
  * Admonition (callout) renderer. Collapsible admonitions render as `<details>`;
  * static ones as a titled region. Child blocks render through `NcmBlock`.
  */
-declare function AdmonitionBlock({ block, className }: AdmonitionBlockProps): react_jsx_runtime.JSX.Element;
+declare function AdmonitionBlock({ block, className }: AdmonitionBlockProps): react.JSX.Element;
 
 export { AdmonitionBlock, type AdmonitionBlockProps };

package/dist/blocks/admonition/index.js

@@ -506,9 +506,10 @@ function TokenRenderer({ token, disableBionic, disableBeeline }) {
     case "image": {
       const src = config.inline?.resolveAssetPath?.(token.src) ?? token.src;
       return /* @__PURE__ */ jsx(
-        "img",
+        EmbedImage,
         {
-          "data-ncm-token": "image",
+          attrs: { "data-ncm-token": "image" },
+          target: token.src,
           src,
           alt: token.alt,
           title: token.title
@@ -542,10 +543,13 @@ function TokenRenderer({ token, disableBionic, disableBeeline }) {
       }
       if (embedType === "image") {
         return /* @__PURE__ */ jsx(
-          "img",
+          EmbedImage,
           {
-            "data-ncm-token": "wiki_embed",
-            "data-ncm-wikiembed-type": embedType,
+            attrs: {
+              "data-ncm-token": "wiki_embed",
+              "data-ncm-wikiembed-type": embedType
+            },
+            target: token.target,
             src: url,
             alt: token.display ?? token.target,
             className: config.embeddings?.imageClassName
@@ -576,6 +580,22 @@ function TokenRenderer({ token, disableBionic, disableBeeline }) {
           }
         );
       }
+      const onEmbedClick = config.embeddings?.onEmbedClick;
+      if (onEmbedClick) {
+        const handleClick = (e) => {
+          onEmbedClick(token.target, result, e);
+        };
+        return /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            "data-ncm-token": "wiki_embed",
+            "data-ncm-wikiembed-type": embedType,
+            onClick: handleClick,
+            children: token.display ?? token.target
+          }
+        );
+      }
       return /* @__PURE__ */ jsx(
         "a",
         {
@@ -594,6 +614,31 @@ function TokenRenderer({ token, disableBionic, disableBeeline }) {
       return null;
   }
 }
+function EmbedImage({ attrs, target, src, alt, title, className }) {
+  const config = useNcmConfig();
+  const Fallback = config.embeddings?.renderImageError;
+  const [failedSrc, setFailedSrc] = useState(null);
+  useEffect(() => {
+    setFailedSrc(null);
+  }, [src]);
+  if (!Fallback) {
+    return /* @__PURE__ */ jsx("img", { ...attrs, src, alt, title, className });
+  }
+  if (failedSrc === src) {
+    return /* @__PURE__ */ jsx(Fallback, { target, src, alt, retry: () => setFailedSrc(null) });
+  }
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      ...attrs,
+      src,
+      alt,
+      title,
+      className,
+      onError: () => setFailedSrc(src)
+    }
+  );
+}
 function renderReadingText(content, opts) {
   if (!content) return /* @__PURE__ */ jsx(Fragment, { children: content });
   const { bionic = false, beeline = false } = opts;
@@ -629,7 +674,7 @@ function renderReadingText(content, opts) {
   return /* @__PURE__ */ jsx(Fragment, { children: pieces });
 }
 function BlockquoteBlock({ block, className }) {
-  const lines = block.content.split("\n").filter((line) => line.trim() !== "");
+  const lines = block.content.split("\n");
   return /* @__PURE__ */ jsx(
     "blockquote",
     {
@@ -639,7 +684,7 @@ function BlockquoteBlock({ block, className }) {
       "data-block-id": block.id,
       "data-ncm-blockquote": "",
       className,
-      children: lines.length <= 1 ? /* @__PURE__ */ jsx(InlineContent, { content: block.content }) : lines.map((line, index) => /* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsx(InlineContent, { content: line }) }, index))
+      children: lines.length <= 1 ? /* @__PURE__ */ jsx(InlineContent, { content: block.content }) : lines.map((line, index) => /* @__PURE__ */ jsx("p", { children: line.trim().length > 0 ? /* @__PURE__ */ jsx(InlineContent, { content: line }) : /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xA0" }) }, index))
     }
   );
 }
@@ -654,7 +699,8 @@ function ChartBlock({ block, className }) {
       "data-ncm-chart": "",
       "data-ncm-chart-type": block.chartType ?? "unknown",
       className: cn(
-        "overflow-x-auto rounded-lg border border-border bg-muted p-4 font-mono text-sm",
+        // `overflow-y-hidden` pairs with `overflow-x-auto` on purpose — see the note in `lib/defaults.ts`.
+        "overflow-x-auto overflow-y-hidden rounded-lg border border-border bg-muted p-4 font-mono text-sm",
         className
       ),
       children: /* @__PURE__ */ jsx("code", { children: block.content })
@@ -779,7 +825,7 @@ function CodeBlock({ block, className }) {
         "data-ncm-language": block.language,
         className: cn("relative", className),
         children: [
-          codeConfig.copyButton !== false && /* @__PURE__ */ jsx(CopyButton, { content: block.content }),
+          codeConfig.copyButton === true && /* @__PURE__ */ jsx(CopyButton, { content: block.content }),
           /* @__PURE__ */ jsx(CustomRenderer, { code: block.content, language: block.language }),
           languageLabel
         ]
@@ -798,7 +844,7 @@ function CodeBlock({ block, className }) {
       "data-ncm-language": block.language,
       className: cn("relative", className),
       children: [
-        codeConfig?.copyButton !== false && /* @__PURE__ */ jsx(CopyButton, { content: block.content }),
+        codeConfig?.copyButton === true && /* @__PURE__ */ jsx(CopyButton, { content: block.content }),
         /* @__PURE__ */ jsx("pre", { "data-ncm-code-pre": "", children: /* @__PURE__ */ jsxs("div", { className: "flex", children: [
           codeConfig?.lineNumbers && /* @__PURE__ */ jsx(LineNumbers, { count: lineCount }),
           /* @__PURE__ */ jsx("code", { "data-ncm-code": "", className: "flex-1", children: /* @__PURE__ */ jsx(DefaultShikiRenderer, { code: block.content, language: block.language }) })
@@ -834,7 +880,8 @@ function DataviewBlock({ block, className }) {
       "data-ncm-dataview": "",
       "data-ncm-query-type": block.queryType,
       className: cn(
-        "overflow-x-auto rounded-lg border border-border bg-muted p-4 font-mono text-sm",
+        // `overflow-y-hidden` pairs with `overflow-x-auto` on purpose — see the note in `lib/defaults.ts`.
+        "overflow-x-auto overflow-y-hidden rounded-lg border border-border bg-muted p-4 font-mono text-sm",
         className
       ),
       children: /* @__PURE__ */ jsx("code", { children: block.query })
@@ -1173,7 +1220,8 @@ function HtmlBlock({ block, className }) {
       "data-block-id": block.id,
       "data-ncm-html": "",
       className: cn(
-        "overflow-x-auto rounded-lg border border-border bg-muted p-4 font-mono text-sm",
+        // `overflow-y-hidden` pairs with `overflow-x-auto` on purpose — see the note in `lib/defaults.ts`.
+        "overflow-x-auto overflow-y-hidden rounded-lg border border-border bg-muted p-4 font-mono text-sm",
         className
       ),
       children: /* @__PURE__ */ jsx("code", { children: block.content })
@@ -1211,7 +1259,7 @@ function LatexDisplayBlock({ block, className }) {
         "data-ncm-type": block.type,
         "data-block-id": block.id,
         "data-ncm-latex-display": "",
-        className: cn("overflow-x-auto", className),
+        className: cn("overflow-x-auto overflow-y-hidden", className),
         dangerouslySetInnerHTML: { __html: html }
       }
     );
@@ -1226,7 +1274,7 @@ function LatexDisplayBlock({ block, className }) {
       "data-ncm-type": block.type,
       "data-block-id": block.id,
       "data-ncm-latex-display": "",
-      className: cn("overflow-x-auto rounded-lg border border-border bg-muted p-4 font-mono text-sm", className),
+      className: cn("overflow-x-auto overflow-y-hidden rounded-lg border border-border bg-muted p-4 font-mono text-sm", className),
       children: /* @__PURE__ */ jsx("code", { children: block.content })
     }
   );
@@ -1250,10 +1298,12 @@ function LinkBlock({ block, className }) {
 function ListBlock({ block, className }) {
   const isOrdered = block.type === "list_ordered";
   const Tag = isOrdered ? "ol" : "ul";
+  const start = isOrdered && typeof block.marker === "number" && block.marker !== 1 ? block.marker : void 0;
   return /* @__PURE__ */ jsx(
     Tag,
     {
       role: "list",
+      start,
       "data-ncm-block": block.id,
       "data-ncm-stable": block.stableId,
       "data-ncm-type": block.type,
@@ -1265,6 +1315,9 @@ function ListBlock({ block, className }) {
     }
   );
 }
+function ItemContent({ content }) {
+  return content.length > 0 ? /* @__PURE__ */ jsx(InlineContent, { content }) : /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xA0" });
+}
 function nestedItemIdKey(id) {
   if (!id) {
     return void 0;
@@ -1281,7 +1334,7 @@ function ListItems({ items, itemIds, ordered }) {
   return /* @__PURE__ */ jsx(Fragment, { children: items.map((item, index) => {
     const key = nestedItemIdKey(itemIds?.[index]) ?? `item-${index}`;
     if (typeof item === "string") {
-      return /* @__PURE__ */ jsx("li", { "data-ncm-list-item": "", children: /* @__PURE__ */ jsx(InlineContent, { content: item }) }, key);
+      return /* @__PURE__ */ jsx("li", { "data-ncm-list-item": "", children: /* @__PURE__ */ jsx(ItemContent, { content: item }) }, key);
     }
     if (isTypedNestedList(item)) {
       return /* @__PURE__ */ jsx(NestedTypedList, { list: item }, key);
@@ -1291,7 +1344,7 @@ function ListItems({ items, itemIds, ordered }) {
       const content = typeof first === "string" ? first : "";
       const nestedContent = processNestedItems(rest, ordered);
       return /* @__PURE__ */ jsxs("li", { "data-ncm-list-item": "", children: [
-        /* @__PURE__ */ jsx(InlineContent, { content }),
+        /* @__PURE__ */ jsx(ItemContent, { content }),
         nestedContent
       ] }, key);
     }
@@ -1341,7 +1394,7 @@ function MathBlock({ block, className }) {
         "data-ncm-type": block.type,
         "data-block-id": block.id,
         "data-ncm-math": "",
-        className: cn("overflow-x-auto", className),
+        className: cn("overflow-x-auto overflow-y-hidden", className),
         dangerouslySetInnerHTML: { __html: html }
       }
     );
@@ -1357,7 +1410,8 @@ function MathBlock({ block, className }) {
       "data-block-id": block.id,
       "data-ncm-math": "",
       className: cn(
-        "overflow-x-auto rounded-lg border border-border bg-muted p-4 font-mono text-sm",
+        // `overflow-y-hidden` pairs with `overflow-x-auto` on purpose — see the note in `lib/defaults.ts`.
+        "overflow-x-auto overflow-y-hidden rounded-lg border border-border bg-muted p-4 font-mono text-sm",
         className
       ),
       children: /* @__PURE__ */ jsx("code", { children: block.content })
@@ -1375,7 +1429,8 @@ function MermaidBlock({ block, className }) {
       "data-ncm-mermaid": "",
       "data-ncm-diagram-type": block.diagramType,
       className: cn(
-        "overflow-x-auto rounded-lg border border-border bg-muted p-4 font-mono text-sm",
+        // `overflow-y-hidden` pairs with `overflow-x-auto` on purpose — see the note in `lib/defaults.ts`.
+        "overflow-x-auto overflow-y-hidden rounded-lg border border-border bg-muted p-4 font-mono text-sm",
         className
       ),
       children: /* @__PURE__ */ jsx("code", { children: block.content })
@@ -1436,7 +1491,7 @@ function TableBlock({ block, className }) {
       "data-ncm-type": block.type,
       "data-block-id": block.id,
       "data-ncm-table": "",
-      className: cn("w-full overflow-x-auto", className),
+      className: cn("w-full overflow-x-auto overflow-y-hidden", className),
       children: /* @__PURE__ */ jsxs("table", { role: "table", "data-ncm-table-element": "", children: [
         /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsx("tr", { "data-ncm-table-row": "", children: block.headers.map((header, index) => /* @__PURE__ */ jsx("th", { "data-ncm-table-header": "", children: /* @__PURE__ */ jsx(InlineContent, { content: header }) }, index)) }) }),
         /* @__PURE__ */ jsx("tbody", { children: block.rows.map((row, rowIndex) => {
@@ -1450,6 +1505,7 @@ function TableBlock({ block, className }) {
 function TaskItems({ items }) {
   return /* @__PURE__ */ jsx(Fragment, { children: items.map((item) => {
     const status = item.checked ? "Completed" : "Incomplete";
+    const text = serializeInlineContent(item.content);
     return /* @__PURE__ */ jsxs(
       "li",
       {
@@ -1476,7 +1532,7 @@ function TaskItems({ items }) {
                 ":",
                 " "
               ] }),
-              /* @__PURE__ */ jsx(InlineContent, { content: serializeInlineContent(item.content) })
+              text.length > 0 ? /* @__PURE__ */ jsx(InlineContent, { content: text }) : /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xA0" })
             ] })
           ] }),
           item.children ? /* @__PURE__ */ jsx("ul", { role: "list", "data-ncm-list-nested": "", className: "ml-6 list-none", children: /* @__PURE__ */ jsx(TaskItems, { items: item.children.items }) }) : null
@@ -1521,7 +1577,7 @@ function FallbackBlock({ block, className }) {
       "data-block-id": block.id,
       "data-ncm-fallback": "",
       className: cn(
-        "overflow-x-auto rounded-lg border border-border bg-muted p-4 font-mono text-sm",
+        "overflow-x-auto overflow-y-hidden rounded-lg border border-border bg-muted p-4 font-mono text-sm",
         className
       )
     },
@@ -1577,7 +1633,7 @@ function CustomCodeBlock({ block, className }) {
       "data-block-id": block.id,
       "data-ncm-custom-code": "",
       "data-ncm-language": block.language,
-      className: cn("overflow-x-auto", className),
+      className: cn("overflow-x-auto overflow-y-hidden", className),
       children: [
         /* @__PURE__ */ jsx("div", { className: "mb-2 text-xs font-medium text-muted-foreground", children: block.language }),
         /* @__PURE__ */ jsx("pre", { children: /* @__PURE__ */ jsx("code", { children: block.content }) })

package/dist/blocks/aside/index.d.ts

@@ -1,13 +1,12 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { AsideBlock as AsideBlock$1 } from '@nuucognition/ncm';
 import { a as BlockRendererProps } from '../../renderers-C5f41FCy.js';
-import 'react';
 
 type AsideBlockProps = BlockRendererProps<AsideBlock$1>;
 /**
  * Aside renderer — parenthetical / sidebar content wrapped in `(( ))`. Child
  * blocks render through `NcmBlock`.
  */
-declare function AsideBlock({ block, className }: AsideBlockProps): react_jsx_runtime.JSX.Element;
+declare function AsideBlock({ block, className }: AsideBlockProps): react.JSX.Element;
 
 export { AsideBlock, type AsideBlockProps };