@anchrd/intel-ui 0.37.0 → 0.38.0

package/src/frontmatter/frontmatter.tsx

@@ -0,0 +1,184 @@
+import { createReactBlockSpec } from "@blocknote/react";
+import { ChevronRight } from "lucide-react";
+import { createContext, Fragment, useContext, useState } from "react";
+
+/**
+ * The head of a knowledge node, as one block (#657).
+ *
+ * ⚠️ The type lives here rather than in the contract, unlike `documentLink`. The server reads
+ * document links out of the stored blocks and therefore has to know that word; nothing on the
+ * server side ever looks at this one. What the server reads of a head is the `markdown` field
+ * beside the blocks — which is exactly why the export half of this module matters more than the
+ * block does.
+ */
+export const FrontmatterBlockType = "frontmatter";
+
+/**
+ * The head, exactly as it stood between the two fences.
+ *
+ * ⚠️ Stored raw, never as parsed pairs, and this is the whole reason the roundtrip cannot lose
+ * anything. A head that is not valid YAML — a typo, a half-written list, a value somebody is in the
+ * middle of writing — travels through unchanged and comes back out as it went in. Parsing happens
+ * for the DISPLAY only, in `frontmatterEntries`, and a line that will not split is shown as it
+ * stands rather than dropped. The alternative, parsing on the way in and re-emitting on the way
+ * out, turns every gap in the parser into silent data loss at the next save.
+ */
+const FRONTMATTER_PROPS = { raw: { default: "" } } as const;
+
+/**
+ * A head at the very start of the document, and only there.
+ *
+ * ⚠️ No `m` flag, and the `^` is doing real work — though not on the documents one first reaches
+ * for. `exec` without `g` finds a head at position 0 with or without the anchor; what the anchor
+ * decides is a document that has NO head and two rules further down. Unanchored, the first rule and
+ * the text after it are swallowed into an invented head. That is the case its test uses.
+ *
+ * ⚠️ `(?![ \t]*\r?\n)` — a head begins on the line after the fence, never with a blank one. This
+ * is what keeps `---\n\nErster Teil\n\n---` from reading as a head: nothing is lost from
+ * `markdown` when it does, but the rule, the text and the second rule all vanish behind a folded
+ * "Metadata" strip, and the reader has no way to know where their paragraph went.
+ *
+ * `[\s\S]+?` rather than `*?` says the same thing the falsy check in `splitFrontmatter` already
+ * says — an empty capture is no head — and is kept for saying it here rather than two lines later.
+ * It is not what makes `---\n---` two thematic breaks; that check is.
+ *
+ * The blank lines after the closing fence belong to the fence, not to the body. Leaving them on
+ * would make `body` start with an empty line that the head had put there — and the join in
+ * `blocksToMarkdown` writes exactly one back, so taking them here is what keeps a document from
+ * growing a blank line per save.
+ */
+const LEADING_FRONTMATTER =
+  /^---\r?\n(?![ \t]*\r?\n)([\s\S]+?)\r?\n---[ \t]*(?:\r?\n|$)(?:[ \t]*\r?\n)*/;
+
+/**
+ * A document's markdown, cut into its head and the rest.
+ *
+ * `raw` is `null` when there is no head, and then `body` is the whole input — the caller has one
+ * branch, not two shapes to tell apart.
+ */
+export function splitFrontmatter(markdown: string): { raw: string | null; body: string } {
+  const match = LEADING_FRONTMATTER.exec(markdown);
+  if (!match?.[1]) return { raw: null, body: markdown };
+  return { raw: match[1], body: markdown.slice(match[0].length) };
+}
+
+/**
+ * The head split into what a reader sees, for display only.
+ *
+ * ⚠️ It is never the source of the stored value — `raw` is. A line without a colon is not a broken
+ * pair but a normal part of YAML (a list item under the key above it, a folded value's second
+ * line), and it is shown whole rather than split at nothing.
+ */
+export function frontmatterEntries(raw: string): { key: string; value: string }[] {
+  return raw
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const colon = line.indexOf(":");
+      const continues = /^[\s-]/.test(line);
+      if (colon < 0 || continues) return { key: "", value: line.trim() };
+      return { key: line.slice(0, colon).trim(), value: line.slice(colon + 1).trim() };
+    });
+}
+
+/**
+ * The two words the block says. They travel in a context for the same reason the document link's
+ * one word does: a block is rendered by the editor, not by a view that could reach the catalog.
+ */
+export interface FrontmatterLabels {
+  summary: string;
+  expand: string;
+}
+
+const FrontmatterContext = createContext<FrontmatterLabels>({
+  summary: "Metadata",
+  expand: "Show metadata",
+});
+
+export const FrontmatterProvider = FrontmatterContext.Provider;
+
+export function FrontmatterHead({ raw }: { raw: string }) {
+  const labels = useContext(FrontmatterContext);
+  // ⚠️ Local state, deliberately NOT a block prop. The fold is how the head is being looked at, not
+  // what it says — and a prop would put it into the stored document, which means opening the head
+  // to read it would mark the document unsaved and offer to write a "change" nobody made.
+  const [open, setOpen] = useState(false);
+  const entries = frontmatterEntries(raw);
+
+  return (
+    <div
+      // The editor owns the text around this; the head itself is not typed into.
+      contentEditable={false}
+      data-frontmatter={open ? "open" : "closed"}
+      className="my-2 w-full rounded-md border border-border bg-muted/40"
+    >
+      <button
+        type="button"
+        aria-expanded={open}
+        aria-label={labels.expand}
+        onClick={() => setOpen(!open)}
+        className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <ChevronRight
+          aria-hidden="true"
+          className={
+            open ? "size-3.5 rotate-90 transition-transform" : "size-3.5 transition-transform"
+          }
+        />
+        {/* ⚠️ Closed, it says THAT there is a head, never what is in it. A preview of `title` or
+            `status` here would be the H2 from #657 again, one size smaller. */}
+        {labels.summary}
+      </button>
+      {open ? (
+        <dl className="grid grid-cols-[max-content_1fr] gap-x-4 gap-y-1 px-3 pb-3 font-mono text-xs">
+          {entries.map((entry, index) =>
+            entry.key ? (
+              // Nothing in a head is unique — two `- Q-04` lines under `quellen` are the ordinary
+              // case — so the position is the only honest key. It is also a safe one here: the list
+              // is derived from an immutable `raw` and is never sorted, inserted into or filtered.
+              // biome-ignore lint/suspicious/noArrayIndexKey: a head's lines have no other key
+              <Fragment key={index}>
+                <dt className="text-muted-foreground">{entry.key}</dt>
+                <dd className="break-words text-foreground">{entry.value}</dd>
+              </Fragment>
+            ) : (
+              // A line that is not a pair — a list item, a folded value's second line — spans both
+              // columns rather than being squeezed into the value one, and is indented so it still
+              // reads as belonging to the key above it.
+              // biome-ignore lint/suspicious/noArrayIndexKey: a head's lines have no other key
+              <dd key={index} className="col-span-2 break-words pl-4 text-foreground">
+                {entry.value}
+              </dd>
+            ),
+          )}
+        </dl>
+      ) : null}
+    </div>
+  );
+}
+
+export const frontmatterSpec = createReactBlockSpec(
+  {
+    type: FrontmatterBlockType,
+    propSchema: FRONTMATTER_PROPS,
+    // The head is not editable text. It is written by whoever writes the document's markdown, and a
+    // caret inside it would let a reader break `type:` without it looking like anything happened.
+    content: "none",
+  },
+  {
+    render: (props) => <FrontmatterHead raw={String(props.block.props.raw)} />,
+    // ⚠️ The net under `blocksToMarkdown`, for every path that does not go through it. Without a
+    // serialiser BlockNote falls back to the RENDERED DOM, so a head would leave the editor as the
+    // word "Metadata" — its own label, in place of the metadata. A fenced block is not a head, but
+    // it is visible and it is lossless, which is what a fallback owes.
+    //
+    // ⚠️ `<pre><code>`, not `<pre>` alone. Measured: a bare `<pre>` survives the HTML export and is
+    // then dropped by the HTML-to-markdown step, which returns `"\n"` — a net that looks like one
+    // in the HTML and catches nothing where it matters.
+    toExternalHTML: (props) => (
+      <pre>
+        <code>{String(props.block.props.raw)}</code>
+      </pre>
+    ),
+  },
+);