@shortlink-org/portolan 0.1.0

package/src/pages/BlockPage.tsx

@@ -0,0 +1,478 @@
+// One template for both structural building blocks. An entity and a value
+// object differ in whether identity matters, not in what there is to say about
+// them, so they share a page and are told apart by the header and the icon.
+
+import { useCallback, useMemo, useState } from "react";
+import { Link, useParams } from "react-router";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import { catalog, index } from "../data";
+import { blockFields, rootEntity } from "../catalog";
+import type { Block, BlockKind, Field } from "../catalog";
+import { openablePaths, resolveShape } from "../lib/shape";
+import type { Scope } from "../lib/shape";
+import { ShapeBody, TypeCell } from "../components/FieldTree";
+import { backlinkCount } from "../lib/backlinks";
+import { storedFields } from "../lib/data-model";
+import { plural } from "../lib/format";
+import { KIND_LABEL, KIND_PLURAL } from "../lib/kinds";
+import { KindIcon } from "../components/kind";
+import { Empty, PageHeader, SectionTitle } from "../components/PageHeader";
+import { Ident } from "../components/Ident";
+import { DataTable } from "../table/DataTable";
+import type { ColumnSpec } from "../table/types";
+import { Toc } from "../components/Toc";
+import type { TocItem } from "../components/Toc";
+import {
+  BLOCK_ANCHOR,
+  BLOCK_STORED_AS,
+  LINKS_HERE,
+  blockPath,
+  paths,
+  tablePath,
+} from "../routes";
+import { useBacklinks, WhatLinksHere } from "../components/WhatLinksHere";
+import { InLanguage } from "../language/InLanguage";
+import { NotFound } from "./NotFound";
+
+/**
+ * The shape of a value object or an entity. Three columns and usually few
+ * rows, so the toolbar stays out of the way until there is enough here to
+ * need one. A field whose type is another block of the aggregate - a Line's
+ * Money - opens under its row, the way an event's schema does.
+ */
+function shapeColumns(
+  scope: Scope,
+  open: ReadonlySet<string>,
+  onToggle: (path: string) => void,
+): ColumnSpec<Field>[] {
+  return [
+    {
+      id: "name",
+      header: "name",
+      type: "mono",
+      value: (field) => field.name,
+      primary: true,
+      // Plain, not an <Ident>: the name is a field of this block, not an id
+      // anything else refers to. The type beside it is the copyable one.
+      cell: (field) => {
+        const shape = resolveShape(catalog, field, scope);
+        const nameClass = field.deprecated ? "mono line-through" : "mono";
+        const title = field.deprecated ? "deprecated" : undefined;
+        return shape ? (
+          <button
+            type="button"
+            onClick={() => onToggle(field.name)}
+            className="mono flex items-center gap-1 rounded-control"
+            aria-expanded={open.has(field.name)}
+            title={`${open.has(field.name) ? "collapse" : "expand"} ${shape.name}`}
+          >
+            {open.has(field.name) ? (
+              <ChevronDown size={11} aria-hidden className="text-muted" />
+            ) : (
+              <ChevronRight size={11} aria-hidden className="text-muted" />
+            )}
+            <span className={nameClass} title={title}>
+              {field.name}
+            </span>
+          </button>
+        ) : (
+          <span className={`${nameClass} pl-4`} title={title}>
+            {field.name}
+          </span>
+        );
+      },
+    },
+    {
+      id: "type",
+      header: "type",
+      type: "mono",
+      value: (field) => field.ref ?? field.type,
+      cell: (field) => (
+        <TypeCell field={field} shape={resolveShape(catalog, field, scope)} />
+      ),
+    },
+    {
+      id: "doc",
+      header: "doc",
+      type: "text",
+      value: (field) => field.doc,
+      cell: (field) => <span className="meta">{field.doc}</span>,
+    },
+  ];
+}
+
+function ShapeTable({
+  id,
+  fields,
+  scope,
+  open,
+  onToggle,
+}: {
+  id: string;
+  fields: Field[];
+  scope: Scope;
+  open: ReadonlySet<string>;
+  onToggle: (path: string) => void;
+}) {
+  const columns = useMemo(
+    () => shapeColumns(scope, open, onToggle),
+    [scope, open, onToggle],
+  );
+  return (
+    <div className="max-w-table">
+      <DataTable
+        tableId={`block-shape.${id}`}
+        caption={`Shape of ${id}`}
+        columns={columns}
+        rows={fields}
+        rowId={(field) => field.name}
+        subRow={(field) => {
+          if (!open.has(field.name)) return null;
+          const shape = resolveShape(catalog, field, scope);
+          return shape ? (
+            <ShapeBody
+              shape={shape}
+              scope={scope}
+              path={field.name}
+              open={open}
+              onToggle={onToggle}
+              seen={new Set([shape.id])}
+              depth={1}
+              root
+            />
+          ) : null;
+        }}
+      />
+    </div>
+  );
+}
+
+export function BlockPage({ kind }: { kind: BlockKind }) {
+  const {
+    context: contextId,
+    service: serviceSlug,
+    aggregate: aggSlug,
+    block: blockSlug,
+  } = useParams();
+
+  const context = catalog.contexts.find((c) => c.id === contextId);
+  const service = context?.services.find((s) => s.slug === serviceSlug);
+  const aggregate = service?.aggregates.find((a) => a.slug === aggSlug);
+  const list: Block[] =
+    (kind === "vo" ? aggregate?.valueObjects : aggregate?.entities) ?? [];
+  const block = list.find((b) => b.slug === blockSlug);
+
+  // "Used in" was this page's own answer to a question every page has; it is
+  // the shared section now, and the block's shape is what it walks.
+  const links = useBacklinks({ kind, id: block?.id ?? "" });
+
+  // The rows opened under this block's fields, as dotted paths. The block
+  // itself is what its own fields must not open again: an Order whose Line
+  // names its Order stops at the name.
+  const [open, setOpen] = useState<Set<string>>(new Set());
+  const toggle = useCallback(
+    (path: string) =>
+      setOpen((prev) => {
+        const next = new Set(prev);
+        if (next.has(path)) next.delete(path);
+        else next.add(path);
+        return next;
+      }),
+    [],
+  );
+  const scope = useMemo<Scope>(
+    () => ({ aggregate: aggregate ?? null, service: service ?? null }),
+    [aggregate, service],
+  );
+  const fields = useMemo(
+    () => (block ? blockFields(catalog, block) : []),
+    [block],
+  );
+  const openable = useMemo(
+    () =>
+      block
+        ? openablePaths(catalog, fields, scope, "", new Set([block.id]))
+        : [],
+    [block, fields, scope],
+  );
+
+  if (!context || !service || !aggregate || !block) {
+    return <NotFound kind={KIND_LABEL[kind]} id={blockSlug} />;
+  }
+
+  const stored = storedFields(catalog, index, block.id);
+  const toc: TocItem[] = [
+    { id: BLOCK_ANCHOR.shape, label: "Shape" },
+    ...(stored.length > 0
+      ? [{ id: BLOCK_STORED_AS, label: "Stored as" }]
+      : []),
+    { id: BLOCK_ANCHOR.siblings, label: "Siblings" },
+    { id: LINKS_HERE, label: "What links here" },
+  ];
+
+  const isRoot =
+    kind === "entity" && rootEntity(aggregate)?.slug === block.slug;
+
+  return (
+    <div className="h-full overflow-y-auto">
+      <PageHeader
+        kind={
+          <>
+            {KIND_LABEL[kind]} ·{" "}
+            <Link
+              to={paths.aggregate(context.id, service.slug, aggregate.slug)}
+              className="rounded-control hover:text-ink hover:underline"
+            >
+              {aggregate.id}
+            </Link>
+          </>
+        }
+        name={block.name}
+        id={block.id}
+        right={
+          <span className="flex items-center gap-2">
+            {isRoot ? (
+              <span className="chip status-verified" title="aggregate root">
+                <span aria-hidden className="dot" />
+                root
+              </span>
+            ) : null}
+            {block.deprecated ? (
+              <span className="chip" title="marked @deprecated in the source">
+                deprecated
+              </span>
+            ) : null}
+            <Link
+              to={paths.aggregate(context.id, service.slug, aggregate.slug)}
+              className="chip-lg border-line-strong text-muted"
+            >
+              <KindIcon kind="aggregate" />
+              {aggregate.name}
+            </Link>
+          </span>
+        }
+      >
+        <p className="mt-2 max-w-prose text-muted">{block.doc}</p>
+        <div className="mono mt-1.5 flex flex-wrap items-center gap-x-4 gap-y-1 text-muted">
+          {block.ref ? (
+            <span className="flex items-center gap-1.5">
+              shared type
+              <Ident value={block.ref} className="text-ink" />— the same shape
+              wherever it is named
+            </span>
+          ) : (
+            <span>local to {aggregate.id} — no shared type</span>
+          )}
+          <span aria-hidden className="h-4 w-px bg-line-strong" />
+          <a
+            href={`#${BLOCK_ANCHOR.shape}`}
+            className="rounded-control hover:text-ink"
+          >
+            <span className="tnum">{fields.length}</span> fields
+          </a>
+          {block.ref ? (
+            <a
+              href={`#${LINKS_HERE}`}
+              className="rounded-control hover:text-ink"
+            >
+              <span className="tnum">{backlinkCount(links)}</span>{" "}
+              {plural(backlinkCount(links), "reference")}
+            </a>
+          ) : null}
+        </div>
+      </PageHeader>
+
+      <div className="flex gap-section p-gutter">
+        <div className="min-w-0 flex-1">
+          <InLanguage id={block.id} />
+
+          <section id={BLOCK_ANCHOR.shape}>
+            <SectionTitle
+              anchor={BLOCK_ANCHOR.shape}
+              right={
+                <span className="flex items-center gap-x-3">
+                  {openable.length > 0 ? (
+                    <span className="mono flex items-center gap-x-2">
+                      {openable.some((path) => !open.has(path)) ? (
+                        <button
+                          type="button"
+                          onClick={() => setOpen(new Set(openable))}
+                          className="rounded-control text-muted hover:text-ink"
+                          title={`open every nested shape (${openable.length})`}
+                        >
+                          expand all
+                        </button>
+                      ) : null}
+                      {openable.some((path) => open.has(path)) ? (
+                        <button
+                          type="button"
+                          onClick={() => setOpen(new Set())}
+                          className="rounded-control text-muted hover:text-ink"
+                        >
+                          collapse all
+                        </button>
+                      ) : null}
+                    </span>
+                  ) : null}
+                  <span>
+                    {fields.length} {plural(fields.length, "field")}
+                  </span>
+                </span>
+              }
+            >
+              Shape
+            </SectionTitle>
+            {fields.length === 0 ? (
+              <Empty>the catalog knows this block by name only</Empty>
+            ) : (
+              <ShapeTable
+                id={block.id}
+                fields={fields}
+                scope={scope}
+                open={open}
+                onToggle={toggle}
+              />
+            )}
+          </section>
+
+          {/* The columns that carry these fields. Only drawn when there are
+              any: a block nothing persists is not missing a section, it is a
+              shape that lives inside another row. */}
+          {stored.length > 0 ? (
+            <section className="mt-section max-w-table" id={BLOCK_STORED_AS}>
+              <SectionTitle
+                anchor={BLOCK_STORED_AS}
+                right={
+                  <span>
+                    db type beside domain type
+                  </span>
+                }
+              >
+                Stored as
+              </SectionTitle>
+              <table className="w-full max-w-table">
+                <thead>
+                  <tr className="label border-b border-line text-left">
+                    <th className="py-1 pr-3 font-normal">column</th>
+                    <th className="py-1 pr-3 font-normal">db type</th>
+                    <th className="py-1 pr-3 font-normal">field</th>
+                    <th className="py-1 font-normal">domain type</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {stored.map(({ owner, path, field, mismatch }) => {
+                    const to = tablePath(owner.table.id);
+                    const id = `${owner.table.id}.${owner.column.name}`;
+                    return (
+                      <tr key={id} className="border-b border-line align-top">
+                        <td className="mono py-1.5 pr-3 whitespace-nowrap">
+                          {to ? (
+                            <Link
+                              to={to}
+                              className="rounded-control hover:underline"
+                              title={id}
+                            >
+                              {owner.table.name}.{owner.column.name}
+                            </Link>
+                          ) : (
+                            <span title={id}>
+                              {owner.table.name}.{owner.column.name}
+                            </span>
+                          )}
+                        </td>
+                        <td className="mono py-1.5 pr-3 whitespace-nowrap text-muted">
+                          {owner.column.type}
+                          {owner.column.nullable ? "?" : ""}
+                        </td>
+                        <td className="mono py-1.5 pr-3 whitespace-nowrap">
+                          {path}
+                        </td>
+                        <td className="mono py-1.5 whitespace-nowrap">
+                          {field ? (
+                            <span className="flex items-center gap-1.5">
+                              {/* An amber dot, not a red one: neither side is
+                                  wrong on its own, and which one moved is the
+                                  reader's call. */}
+                              {mismatch ? (
+                                <span
+                                  aria-hidden
+                                  className="size-1.5 shrink-0 rounded-full"
+                                  style={{
+                                    background: "var(--status-declared)",
+                                  }}
+                                  title={`${owner.column.type} in the column, ${field.type} in the model`}
+                                />
+                              ) : null}
+                              <span
+                                className={
+                                  mismatch ? "text-declared" : "text-muted"
+                                }
+                              >
+                                {field.type}
+                              </span>
+                            </span>
+                          ) : (
+                            <span
+                              className="text-unresolved"
+                              title={`${block.name} declares no field "${path}"`}
+                            >
+                              no such field
+                            </span>
+                          )}
+                        </td>
+                      </tr>
+                    );
+                  })}
+                </tbody>
+              </table>
+            </section>
+          ) : null}
+
+          <div className="mt-section max-w-prose" id={BLOCK_ANCHOR.siblings}>
+            <SectionTitle anchor={BLOCK_ANCHOR.siblings}>Siblings</SectionTitle>
+            <div className="flex flex-wrap gap-1.5">
+              {list
+                .filter((b) => b.slug !== block.slug)
+                .map((sibling) => (
+                  <Link
+                    key={sibling.id}
+                    to={
+                      (blockPath(sibling.id) as string) ??
+                      paths.aggregate(context.id, service.slug, aggregate.slug)
+                    }
+                    className="chip-lg border-line-strong text-muted"
+                  >
+                    <KindIcon kind={kind} />
+                    {sibling.name}
+                  </Link>
+                ))}
+              {list.length <= 1 ? (
+                <Empty>
+                  the only {KIND_LABEL[kind]} in {aggregate.name}
+                </Empty>
+              ) : null}
+            </div>
+            <div className="mono mt-2 text-muted">
+              {KIND_PLURAL[kind]} of {aggregate.id}
+            </div>
+          </div>
+
+          {/* Two blocks are the same type only if they name the same def, so
+              this walks the shared type rather than the name: a Money here and
+              a Money there are one thing or they are two, and the catalog has
+              already said which. */}
+          <WhatLinksHere
+            target={{ kind, id: block.id }}
+            empty={
+              block.ref
+                ? `nothing else names ${block.ref}`
+                : "an inline shape is used only here — give it a shared type to track it across the catalog"
+            }
+          />
+        </div>
+
+        <Toc items={toc} label={`Sections of this ${KIND_LABEL[kind]}`} />
+      </div>
+    </div>
+  );
+}

package/src/pages/CatalogFailure.tsx

@@ -0,0 +1,111 @@
+// What the reader sees when data/catalog.json cannot be trusted.
+//
+// This page exists because the alternative is worse in a specific way: a
+// validator that throws at import time takes the bundle down, and the reader
+// gets a white rectangle while the only useful sentence in the building sits in
+// a console nobody has open. So the message is printed verbatim - it already
+// names the offending flow, step or field - along with where to look and what
+// to do about it.
+
+import type { CatalogError } from "../catalog";
+import { Ident } from "../components/Ident";
+import { CompassRose } from "../components/logo";
+
+/**
+ * What to do about it, matched on the message the validator wrote. The
+ * fallback is the honest one: something upstream produced a catalog that does
+ * not describe a consistent estate, and the fix is in the generator, not here.
+ */
+const HINTS: { test: RegExp; hint: string }[] = [
+  {
+    test: /references unknown def/,
+    hint: "The named shape is not in `catalog.defs`. Either the generator dropped the definition, or the ref is a typo — check the proto or the source file the field was read from.",
+  },
+  {
+    test: /is not a declared participant/,
+    hint: "A step names a lane the flow never declared. Add the service to the flow's `participants`, or point the step at one that is already there.",
+  },
+  {
+    test: /resolves to neither an Event nor an RpcCall/,
+    hint: "Either the ref is stale — the event was renamed or removed — or the step really does point at something outside the catalog, in which case its status belongs as `unresolved`.",
+  },
+  {
+    test: /must have id/,
+    hint: "Ids are composed, not free text: a service is `<context>.<slug>`, a block is `<aggregate>.<slug>`. The generator built one of them from the wrong parts.",
+  },
+  {
+    test: /is not unique/,
+    hint: "Two things claim the same slug or id. Slugs are what the URLs are built from, so one of them would be unreachable.",
+  },
+  {
+    test: /alt|loop|branch|terminal/,
+    hint: "A frame that does not state a choice is drawn as an ordinary sequence, which is the misreading the validator exists to stop. Give the frame its title, its second branch, or move the steps that follow it.",
+  },
+  {
+    test: /names root|names no root/,
+    hint: "An aggregate is a root entity plus what it owns. The root has to be one of the entities the aggregate lists.",
+  },
+  {
+    test: /adr/,
+    hint: "A decision record points at something that is not in the catalog, or records only half of a supersession. Both would draw a link to nowhere.",
+  },
+];
+
+function hintFor(message: string): string {
+  return (
+    HINTS.find((h) => h.test.test(message))?.hint ??
+    "The catalog does not describe a consistent estate. Fix the source the generator read, then re-run it — nothing here can be drawn until the shape holds."
+  );
+}
+
+export function CatalogFailure({ error }: { error: CatalogError }) {
+  return (
+    <div className="pane h-full overflow-y-auto bg-canvas">
+      <div className="mx-auto max-w-prose px-gutter py-16">
+        <div className="flex items-center gap-2 text-muted">
+          <CompassRose size={16} />
+          <span className="label">portolan</span>
+        </div>
+
+        <h1 className="mt-6 text-xl font-semibold">
+          The catalog did not survive validation.
+        </h1>
+        <p className="mt-3 text-muted">
+          Nothing is drawn from a catalog that has already been shown to be
+          wrong — a chart with one bad sounding on it is worse than no chart.
+          Here is the sounding.
+        </p>
+
+        <div className="mt-section overflow-hidden rounded-card border shadow-xs border-unresolved">
+          <div className="label border-b px-4 py-2 border-line bg-surface">
+            validator
+          </div>
+          {/* Verbatim, wrapped, selectable: this string is the thing to paste
+              into the generator's issue, so it is not summarised or truncated. */}
+          <pre className="mono overflow-x-auto px-4 py-3 whitespace-pre-wrap text-unresolved">
+            {error.message}
+          </pre>
+          {error.path ? (
+            <div className="flex flex-wrap items-baseline gap-2 border-t px-4 py-3 border-line">
+              <span className="label">where</span>
+              <Ident value={error.path} className="text-ink" />
+            </div>
+          ) : null}
+        </div>
+
+        <div className="mt-grid rounded-card border p-card border-line">
+          <div className="label mb-2">how to fix</div>
+          <p>{hintFor(error.message)}</p>
+          <p className="mt-3 text-muted">Then regenerate and reload:</p>
+          <pre className="mono mt-2 overflow-x-auto rounded-control border px-3 py-2 border-line bg-surface">
+            npm run likec4:gen
+          </pre>
+        </div>
+
+        <p className="mono mt-section text-muted">
+          data/catalog.json — validated by src/catalog.ts
+        </p>
+      </div>
+    </div>
+  );
+}