@shortlink-org/portolan 0.1.0

package/src/components/LifecycleDiagram.tsx

@@ -0,0 +1,110 @@
+import { Link } from "react-router";
+import type { Aggregate } from "../catalog";
+import { layoutLifecycle, METRICS } from "../lib/lifecycle";
+import { KindIcon } from "./kind";
+
+/**
+ * The aggregate's state machine, as the code wrote it down. Boxes and arrows
+ * are SVG; the labels are HTML laid over it, because a label holds a link to
+ * the event the move publishes, and a link belongs in the document, not in a
+ * picture of one.
+ */
+export function LifecycleDiagram({
+  aggregate,
+  eventPath,
+}: {
+  aggregate: Aggregate;
+  eventPath: (eventId: string) => string | null;
+}) {
+  const lifecycle = aggregate.lifecycle;
+  if (!lifecycle) return null;
+  const { width, height, boxes, edges } = layoutLifecycle(lifecycle);
+  const eventName = (id: string) => aggregate.events.find((e) => e.id === id)?.name ?? id;
+
+  return (
+    <div className="overflow-x-auto">
+      <div className="relative" style={{ width, height }}>
+        <svg width={width} height={height} aria-hidden className="absolute inset-0">
+          <defs>
+            <marker id="lc-arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+              <path d="M 0 0 L 8 4 L 0 8 z" fill="var(--fg-muted)" />
+            </marker>
+          </defs>
+          {edges.map((e) => (
+            <path
+              key={`${e.from}-${e.to}-${e.on}`}
+              d={e.path}
+              fill="none"
+              stroke="var(--fg-muted)"
+              strokeWidth={1.25}
+              strokeDasharray={e.back ? "4 3" : undefined}
+              markerEnd="url(#lc-arrow)"
+            />
+          ))}
+          {boxes.map((b) => (
+            <g key={b.state}>
+              <rect
+                x={b.x}
+                y={b.y}
+                width={METRICS.boxWidth}
+                height={METRICS.boxHeight}
+                rx={6}
+                fill={b.terminal ? "var(--surface)" : "var(--bg)"}
+                stroke={b.initial ? "var(--accent)" : "var(--border-strong)"}
+                strokeWidth={b.initial ? 1.5 : 1}
+              />
+              {/* A terminal state carries a second, inner edge: the record it becomes. */}
+              {b.terminal ? (
+                <rect
+                  x={b.x + 3}
+                  y={b.y + 3}
+                  width={METRICS.boxWidth - 6}
+                  height={METRICS.boxHeight - 6}
+                  rx={4}
+                  fill="none"
+                  stroke="var(--border)"
+                />
+              ) : null}
+            </g>
+          ))}
+        </svg>
+        {boxes.map((b) => (
+          <div
+            key={b.state}
+            className="mono absolute flex items-center justify-center text-ink"
+            style={{ left: b.x, top: b.y, width: METRICS.boxWidth, height: METRICS.boxHeight }}
+            title={b.initial ? "where a new one starts" : b.terminal ? "nothing leads out of here" : undefined}
+          >
+            {b.state}
+          </div>
+        ))}
+        {edges.map((e) => {
+          const to = e.emits ? eventPath(e.emits) : null;
+          return (
+            <div
+              key={`${e.from}-${e.to}-${e.on}-label`}
+              className="mono absolute flex -translate-x-1/2 -translate-y-1/2 items-center gap-1 whitespace-nowrap rounded-control bg-bg px-1 text-muted"
+              style={{ left: e.labelX, top: e.labelY }}
+              title={e.source ? `made at ${e.source}` : undefined}
+            >
+              {e.on}
+              {e.emits ? (
+                <>
+                  <span aria-hidden>·</span>
+                  {to ? (
+                    <Link to={to} className="flex items-center gap-0.5 rounded-control text-ink hover:underline">
+                      <KindIcon kind="event" size={11} />
+                      {eventName(e.emits)}
+                    </Link>
+                  ) : (
+                    <span>{eventName(e.emits)}</span>
+                  )}
+                </>
+              ) : null}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/components/MachineDocs.tsx

@@ -0,0 +1,42 @@
+import { FileText } from "lucide-react";
+import { activeCatalogProfile } from "../data";
+
+// The site as a language model reads it. The build (scripts/site-docs.mjs)
+// places the generated markdown under docs/ and llms.txt at the root, in the
+// shape llmstxt.org asks for, and the same script's Vite plugin answers the
+// paths in development. Plain anchors, not router links: these are files
+// beside the app, and a full navigation is the point.
+
+const base = import.meta.env.BASE_URL;
+
+const suffix = activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
+const docs = `${base}docs/${suffix}`;
+const FILES = [
+  { href: suffix ? `${docs}llms.txt` : `${base}llms.txt`, label: "llms.txt", title: "An index of every page, for a model that fetches on demand" },
+  { href: suffix ? `${docs}llms-full.txt` : `${base}llms-full.txt`, label: "llms-full.txt", title: "Every page in one file, for a model with a context window" },
+  { href: docs, label: "docs/", title: "The generated markdown, page by page" },
+  { href: `${base}exports/mermaid/${suffix}`, label: "Mermaid", title: "Standalone sequence diagrams for every architecture flow" },
+  ...(activeCatalogProfile.id === "example"
+    ? [{ href: `${base}exports/backstage/catalog-info.yaml`, label: "Backstage", title: "Components, systems, APIs and resources for a Backstage catalog" }]
+    : []),
+];
+
+/** Links to the generated documentation, one line. */
+export function MachineDocs({ className = "" }: { className?: string }) {
+  return (
+    <div className={`mono flex flex-wrap items-center gap-x-3 gap-y-1 text-muted ${className}`}>
+      <FileText size={14} aria-hidden />
+      <span>for language models:</span>
+      {FILES.map((file) => (
+        <a
+          key={file.label}
+          href={file.href}
+          title={file.title}
+          className="rounded-control text-accent hover:underline"
+        >
+          {file.label}
+        </a>
+      ))}
+    </div>
+  );
+}

package/src/components/Markdown.tsx

@@ -0,0 +1,173 @@
+import { Children, isValidElement } from "react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import {
+  Info,
+  Lightbulb,
+  MessageSquareWarning,
+  OctagonAlert,
+  TriangleAlert,
+} from "lucide-react";
+import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+import { ADMONITION_LABEL, parseAdmonition } from "../lib/admonition";
+import { AnchorLink } from "./AnchorLink";
+import type { AdmonitionKind } from "../lib/admonition";
+import { headingSlug } from "../lib/derive";
+import { Mermaid } from "./Mermaid";
+import { MarkdownTable } from "./MarkdownTable";
+import { remarkTableDirective } from "../lib/table-directive";
+
+function textOf(node: React.ReactNode): string {
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(textOf).join("");
+  if (node && typeof node === "object" && "props" in node) {
+    const props = (node as { props?: { children?: React.ReactNode } }).props;
+    return textOf(props?.children);
+  }
+  return "";
+}
+
+/**
+ * Headings get ids so the outline rail can jump to them - and, having an id,
+ * they get the link back out. A readme heading is where an invariant is
+ * written down, so "send me the rule about cancelling" is a link, not a
+ * screenshot.
+ */
+function heading(level: 1 | 2 | 3) {
+  return function Heading(props: ComponentPropsWithoutRef<"h1">) {
+    const Tag = `h${level}` as const;
+    const text = textOf(props.children);
+    const id = headingSlug(text);
+    // A heading whose text slugs to nothing has no anchor to offer.
+    if (!id) return <Tag>{props.children}</Tag>;
+    return (
+      <Tag id={id} className="anchored">
+        {props.children}
+        <AnchorLink id={id} label={text} />
+      </Tag>
+    );
+  };
+}
+
+/** The visual half of src/lib/admonition.ts, in the manner of kind.tsx. */
+const ADMONITION_ICON: Record<AdmonitionKind, LucideIcon> = {
+  note: Info,
+  tip: Lightbulb,
+  important: MessageSquareWarning,
+  warning: TriangleAlert,
+  caution: OctagonAlert,
+};
+
+/**
+ * Four of the five borrow the meaning they already have in the app: an alert
+ * that says "careful" is painted like a check that failed. Only `important`
+ * needs a colour of its own.
+ */
+const ADMONITION_COLOR: Record<AdmonitionKind, string> = {
+  note: "var(--accent)",
+  tip: "var(--status-verified)",
+  important: "var(--alert-important)",
+  warning: "var(--status-declared)",
+  caution: "var(--status-unresolved)",
+};
+
+/**
+ * Splits a blockquote into `[!KIND]` and the prose under it. The marker is not
+ * a node of its own - remark leaves it as the first characters of the first
+ * paragraph - so the paragraph is rebuilt without it, and dropped entirely
+ * when the marker was all it held.
+ */
+function asAdmonition(
+  children: ReactNode,
+): { kind: AdmonitionKind; body: ReactNode[] } | null {
+  const blocks = Children.toArray(children).filter(
+    (block) => typeof block !== "string" || block.trim() !== "",
+  );
+  const [first, ...rest] = blocks;
+  if (!isValidElement<{ children?: ReactNode }>(first)) return null;
+  if (first.type !== "p") return null;
+
+  const inline = Children.toArray(first.props.children);
+  if (typeof inline[0] !== "string") return null;
+  const marker = parseAdmonition(inline[0]);
+  if (!marker) return null;
+
+  const lead = marker.rest
+    ? [marker.rest, ...inline.slice(1)]
+    : inline.slice(1);
+  return {
+    kind: marker.kind,
+    body: [...(lead.length ? [<p key="lead">{lead}</p>] : []), ...rest],
+  };
+}
+
+function Blockquote(props: ComponentPropsWithoutRef<"blockquote">) {
+  const alert = asAdmonition(props.children);
+  if (!alert) return <blockquote>{props.children}</blockquote>;
+
+  const Icon = ADMONITION_ICON[alert.kind];
+  return (
+    <div
+      className="callout"
+      style={{ "--callout": ADMONITION_COLOR[alert.kind] } as CSSProperties}
+    >
+      <p className="callout-title">
+        <Icon aria-hidden size={14} />
+        {ADMONITION_LABEL[alert.kind]}
+      </p>
+      {alert.body}
+    </div>
+  );
+}
+
+/** The fence language of a <pre>'s single <code> child, if it has one. */
+function fenceLanguage(children: ReactNode): string | null {
+  if (!isValidElement<{ className?: string }>(children)) return null;
+  const match = /language-([\w-]+)/.exec(children.props.className ?? "");
+  return match?.[1] ?? null;
+}
+
+function Pre(props: ComponentPropsWithoutRef<"pre">) {
+  if (fenceLanguage(props.children) === "mermaid") {
+    return <Mermaid code={textOf(props.children).replace(/\n$/, "")} />;
+  }
+  return <pre>{props.children}</pre>;
+}
+
+/**
+ * Mermaid fences are drawn where the prose they sit in was written by hand:
+ * decision records, and the readmes of a service or an aggregate. What is
+ * drawn there is a quotation, never a fact — portolan’s own diagrams come
+ * from the catalog and are drawn from measurements — but a lifecycle somebody
+ * sketched in a readme reads as a picture and not as twelve lines of source.
+ * Pass `mermaid` where the markdown is somebody’s writing.
+ */
+export function Markdown({
+  children,
+  mermaid = false,
+}: {
+  children: string;
+  mermaid?: boolean;
+}) {
+  return (
+    <div className="prose">
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm, remarkTableDirective]}
+        components={{
+          h1: heading(1),
+          h2: heading(2),
+          h3: heading(3),
+          blockquote: Blockquote,
+          // Every GFM table in the app is the app's table, on the same terms
+          // as an index page's - unless it is small enough, or the author
+          // said not to.
+          table: MarkdownTable,
+          ...(mermaid ? { pre: Pre } : {}),
+        }}
+      >
+        {children}
+      </ReactMarkdown>
+    </div>
+  );
+}

package/src/components/MarkdownTable.tsx

@@ -0,0 +1,206 @@
+// A table in a README, rendered as the same table as everywhere else.
+//
+// The point is not consistency for its own sake: a README table is often the
+// one place a fact is written down, and a fact you can sort, filter and copy
+// out is more useful than a fact you have to read past. So the renderer takes
+// the GFM table apart, works out what each column HOLDS by looking at it, and
+// hands the pieces to the same primitive the index pages use.
+//
+// Two limits keep it quiet. A table of three rows or fewer stays a plain
+// table - there is nothing to sort in three rows, and a toolbar over them is
+// furniture. And an author who knows better can say so in a comment.
+
+import { Children, isValidElement, useMemo } from "react";
+import type { ReactElement, ReactNode } from "react";
+import { DataTable } from "../table/DataTable";
+import { inferColumnTypes } from "../table/infer";
+import { defaultAlign } from "../table/types";
+import type { ColumnSpec } from "../table/types";
+import {
+  NO_DIRECTIVE,
+  TABLE_DIRECTIVE_ATTR,
+  columnSlug,
+  parseTableDirective,
+} from "../lib/table-directive";
+import type { TableDirective } from "../lib/table-directive";
+
+/** Below this many rows a table is left as it was written. */
+const ENHANCE_ABOVE = 3;
+/** A README's toolbar waits longer than an index page's. */
+const TOOLBAR_AT = 10;
+
+function textOf(node: ReactNode): string {
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(textOf).join("");
+  if (node && typeof node === "object" && "props" in node) {
+    const props = (node as { props?: { children?: ReactNode } }).props;
+    return textOf(props?.children);
+  }
+  return "";
+}
+
+/** The children of a React element, as an array, whatever shape they arrived in. */
+function kids(node: ReactNode): ReactNode[] {
+  if (!isValidElement<{ children?: ReactNode }>(node)) return [];
+  return Children.toArray(node.props.children);
+}
+
+/** Every element of one tag name among a node's children, at any depth of one. */
+function elements(
+  nodes: ReactNode[],
+  tag: string,
+): ReactElement<{ children?: ReactNode; style?: { textAlign?: string } }>[] {
+  const out: ReactElement<{
+    children?: ReactNode;
+    style?: { textAlign?: string };
+  }>[] = [];
+  for (const node of nodes) {
+    if (!isValidElement(node)) continue;
+    if (node.type === tag) {
+      out.push(
+        node as ReactElement<{
+          children?: ReactNode;
+          style?: { textAlign?: string };
+        }>,
+      );
+    }
+    // remark wraps rows in <thead>/<tbody>; a bare <tr> is possible too.
+    else out.push(...elements(kids(node), tag));
+  }
+  return out;
+}
+
+/** GFM's colon syntax, as react-markdown leaves it: an inline text-align. */
+function alignOf(cell: {
+  props: { style?: { textAlign?: string } };
+}): "left" | "right" | undefined {
+  const style = cell.props.style;
+  if (style?.textAlign === "right") return "right";
+  if (style?.textAlign === "left" || style?.textAlign === "center") {
+    return "left";
+  }
+  return undefined;
+}
+
+interface MarkdownRow {
+  id: string;
+  /** The cell as the author wrote it: links, code and emphasis intact. */
+  cells: ReactNode[];
+  /** The same cell as plain text, for sorting, filtering and export. */
+  text: string[];
+}
+
+interface Parsed {
+  headers: string[];
+  aligns: (("left" | "right") | undefined)[];
+  rows: MarkdownRow[];
+}
+
+/** Pulls a rendered GFM table apart into headers, alignments and rows. */
+function parseTable(children: ReactNode): Parsed {
+  const nodes = Children.toArray(children);
+  const headerRow = elements(
+    elements(nodes, "thead").flatMap((thead) => kids(thead)),
+    "tr",
+  )[0];
+  const headerCells = headerRow ? elements(kids(headerRow), "th") : [];
+  const headers = headerCells.map((cell) => textOf(cell.props.children));
+  const aligns = headerCells.map(alignOf);
+
+  const bodyRows = elements(
+    elements(nodes, "tbody").flatMap((tbody) => kids(tbody)),
+    "tr",
+  );
+  const rows = bodyRows.map((row, index) => {
+    const cells = elements(kids(row), "td");
+    return {
+      id: String(index),
+      cells: cells.map((cell) => cell.props.children),
+      text: cells.map((cell) => textOf(cell.props.children).trim()),
+    };
+  });
+
+  return { headers, aligns, rows };
+}
+
+/**
+ * The directive left on the table by the remark plugin. Reading it off the
+ * hast node rather than off props keeps it out of the DOM.
+ */
+function directiveOf(node: unknown): TableDirective {
+  const properties = (node as { properties?: Record<string, unknown> })
+    ?.properties;
+  const raw = properties?.[TABLE_DIRECTIVE_ATTR];
+  return typeof raw === "string" ? parseTableDirective(raw) : NO_DIRECTIVE;
+}
+
+export function MarkdownTable({
+  node,
+  children,
+}: {
+  node?: unknown;
+  children?: ReactNode;
+}) {
+  const directive = directiveOf(node);
+  const { headers, aligns, rows } = useMemo(
+    () => parseTable(children),
+    [children],
+  );
+
+  const types = useMemo(
+    () => inferColumnTypes(rows.map((row) => row.text), headers.length),
+    [rows, headers.length],
+  );
+
+  const columns = useMemo<ColumnSpec<MarkdownRow>[]>(() => {
+    const taken = new Set<string>();
+    return headers.map((header, i) => {
+      const id = columnSlug(header, taken);
+      taken.add(id);
+      const type = types[i] ?? "text";
+      return {
+        id,
+        header,
+        type,
+        value: (row: MarkdownRow) => row.text[i],
+        // The author's own cell, formatting and all. What the column type
+        // decides here is how it sorts and which way it lines up, not what it
+        // says - a README's dates should read as the README wrote them.
+        cell: (row: MarkdownRow) => row.cells[i],
+        // The colon syntax is the author being explicit, and beats the type.
+        align: aligns[i] ?? defaultAlign(type),
+        primary: i === 0,
+      };
+    });
+  }, [headers, aligns, types]);
+
+  // Stable across reloads for the same table, and different for a different
+  // one: enough for a README, which has no id of its own to offer.
+  const tableId = useMemo(
+    () => `md.${headers.map((h) => columnSlug(h, new Set())).join(".")}`,
+    [headers],
+  );
+
+  // Nothing to take apart, or nothing worth taking apart.
+  if (headers.length === 0 || directive.static || rows.length <= ENHANCE_ABOVE) {
+    return <table>{children}</table>;
+  }
+
+  return (
+    <DataTable
+      tableId={tableId}
+      columns={columns}
+      rows={rows}
+      rowId={(row) => row.id}
+      defaultSort={
+        directive.sort &&
+        columns.some((column) => column.id === directive.sort?.id)
+          ? [directive.sort]
+          : []
+      }
+      toolbarAt={TOOLBAR_AT}
+      minimal
+      className="my-3"
+    />
+  );
+}