@shortlink-org/portolan 0.1.0

package/src/pages/StorePage.tsx

@@ -0,0 +1,114 @@
+// One store, full page.
+//
+// The service's Data tab shows every store this service touches, stacked and
+// short. This is the other half of that: one schema, the whole pane, and the
+// detail panel on the right wired to whatever is clicked. A schema of thirty
+// tables is not readable in a 340px strip, and a reader who followed a table
+// link came here to read exactly one.
+
+import { Link, useParams } from "react-router";
+import { catalog } from "../data";
+import { PageHeader } from "../components/PageHeader";
+import { paths } from "../routes";
+import { ContextPill } from "../components/primitives";
+import { WhatLinksHere } from "../components/WhatLinksHere";
+import { ErCanvas } from "../er/ErCanvas";
+import { StoreHeader } from "../er/StoreHeader";
+import { RedisSchema } from "../er/RedisSchema";
+import { storeColumnCount, storeViewCount } from "../lib/data-model";
+import { plural } from "../lib/format";
+import { NotFound } from "./NotFound";
+
+export function StorePage() {
+  const {
+    context: contextId,
+    service: serviceSlug,
+    store: storeSlug,
+  } = useParams();
+
+  const context = catalog.contexts.find((c) => c.id === contextId);
+  const service = context?.services.find((s) => s.slug === serviceSlug);
+  const store = service
+    ? (catalog.stores ?? []).find(
+        (s) => s.slug === storeSlug && s.owner === service.id,
+      )
+    : undefined;
+
+  if (!context || !service || !store) {
+    return <NotFound kind="Store" id={storeSlug} />;
+  }
+
+  const columns = storeColumnCount(store);
+  const views = storeViewCount(store);
+  const keyspaces = store.keyspaces ?? [];
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader
+        kind={
+          <>
+            store ·{" "}
+            <Link
+              to={paths.service(context.id, service.slug)}
+              className="rounded-control hover:text-ink hover:underline"
+            >
+              {service.id}
+            </Link>
+          </>
+        }
+        name={store.name}
+        id={store.id}
+        contextId={context.id}
+        pin={{ kind: "store", id: store.id }}
+        right={<ContextPill id={context.id} name={context.name} />}
+      >
+        <div className="mt-3 max-w-table">
+          <StoreHeader store={store} access="owns" linked={false} />
+        </div>
+        <div className="mono mt-2 flex flex-wrap items-center gap-x-3 text-muted">
+          <span>
+            {keyspaces.length > 0 ? (
+              <>
+                <span className="tnum">{keyspaces.length}</span>{" "}
+                {plural(keyspaces.length, "key pattern")}
+              </>
+            ) : (
+              <>
+                <span className="tnum">{store.tables.length}</span>{" "}
+                {plural(store.tables.length, "table")} ·{" "}
+                <span className="tnum">{columns}</span>{" "}
+                {plural(columns, "column")}
+              </>
+            )}
+            {/* Views are counted apart from the tables rather than added to
+                them: they hold no rows, and one number for both would answer
+                "how much is stored here" with the wrong figure. */}
+            {keyspaces.length === 0 && views > 0 ? (
+              <>
+                {" · "}
+                <span className="tnum">{views}</span> {plural(views, "view")}
+              </>
+            ) : null}
+          </span>
+        </div>
+        {/* Who depends on this schema: the services that read it, and the
+            aggregates its tables hold. A line rather than a section, because
+            the canvas below takes the whole pane. */}
+        <WhatLinksHere
+          variant="line"
+          target={{ kind: "store", id: store.id }}
+        />
+      </PageHeader>
+
+      {/* The canvas takes the rest of the pane rather than a fixed height: on
+          this page the schema IS the content, so it gets the room. */}
+      <div className="min-h-0 flex-1 overflow-auto p-gutter">
+        {keyspaces.length > 0 ? (
+          <RedisSchema store={store} />
+        ) : (
+          <ErCanvas store={store} height="100%" />
+        )}
+      </div>
+    </div>
+  );
+}

package/src/peek/PeekCard.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { CARD_WIDTH, placeCard } from "./PeekCard";
+
+const viewport = { width: 1200, height: 800 };
+
+describe("placeCard", () => {
+  it("opens below the anchor, at its left", () => {
+    expect(placeCard({ left: 100, top: 200, bottom: 220 }, 150, viewport)).toEqual({
+      left: 100,
+      top: 226,
+    });
+  });
+
+  it("flips above when the bottom of the window is too close", () => {
+    expect(placeCard({ left: 100, top: 700, bottom: 720 }, 150, viewport)).toEqual({
+      left: 100,
+      top: 700 - 6 - 150,
+    });
+  });
+
+  it("stays below when there is no room above either", () => {
+    const at = placeCard({ left: 100, top: 20, bottom: 40 }, 790, viewport);
+    expect(at.top).toBe(46);
+  });
+
+  it("keeps the card inside the window on the right", () => {
+    const at = placeCard({ left: 1150, top: 200, bottom: 220 }, 150, viewport);
+    expect(at.left).toBe(viewport.width - CARD_WIDTH - 8);
+  });
+
+  it("keeps the card inside the window on the left", () => {
+    const at = placeCard({ left: -40, top: 200, bottom: 220 }, 150, viewport);
+    expect(at.left).toBe(8);
+  });
+});

package/src/peek/PeekCard.tsx

@@ -0,0 +1,118 @@
+// The card itself: one glance at a thing, drawn next to where the pointer is.
+//
+// It is the detail panel's first screen at a third of the width, and it says
+// nothing the panel would not: the same icon, the same kind, the same names.
+// A card that used a vocabulary of its own would be one more thing to learn
+// on the way to the thing it describes.
+//
+// It opens below the anchor and flips above it when the bottom of the window
+// is closer than the card is tall. Left is the anchor's left, held inside the
+// window; the card never covers what was hovered, because the pointer is
+// still there and the reader is about to click it.
+
+import { useLayoutEffect, useRef, useState } from "react";
+import type { CSSProperties } from "react";
+import { KindIcon } from "../components/kind";
+import { ctxStyle } from "../lib/context-color";
+import { KIND_LABEL } from "../lib/kinds";
+import { m, scaleIn } from "../lib/motion";
+import type { Peek } from "./model";
+
+/** Wide enough for two lines of prose, narrow enough not to be a panel. */
+export const CARD_WIDTH = 300;
+/** Air between the anchor and the card, and between the card and the window. */
+const GAP = 6;
+const MARGIN = 8;
+
+/**
+ * Where to put a card of `height` for an anchor at `rect`, in viewport
+ * coordinates. Exported for the test: the flip and the clamp are the whole
+ * of what can go wrong with a floating box.
+ */
+export function placeCard(
+  rect: Pick<DOMRect, "left" | "top" | "bottom">,
+  height: number,
+  viewport: { width: number; height: number },
+): { left: number; top: number } {
+  const left = Math.max(
+    MARGIN,
+    Math.min(rect.left, viewport.width - CARD_WIDTH - MARGIN),
+  );
+  const below = rect.bottom + GAP;
+  const fitsBelow = below + height <= viewport.height - MARGIN;
+  const above = rect.top - GAP - height;
+  const top = fitsBelow || above < MARGIN ? below : above;
+  return { left, top: Math.max(MARGIN, top) };
+}
+
+export function PeekCard({ peek, rect }: { peek: Peek; rect: DOMRect }) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  // Placed below first, then measured and moved before paint when it does not
+  // fit: useLayoutEffect runs ahead of the frame, so nothing flashes.
+  const [at, setAt] = useState(() =>
+    placeCard(rect, 0, { width: window.innerWidth, height: window.innerHeight }),
+  );
+
+  useLayoutEffect(() => {
+    const height = ref.current?.offsetHeight ?? 0;
+    setAt(
+      placeCard(rect, height, {
+        width: window.innerWidth,
+        height: window.innerHeight,
+      }),
+    );
+  }, [rect, peek]);
+
+  const clamp: CSSProperties = {
+    display: "-webkit-box",
+    WebkitLineClamp: 2,
+    WebkitBoxOrient: "vertical",
+    overflow: "hidden",
+  };
+
+  return (
+    <m.div
+      ref={ref}
+      {...scaleIn}
+      data-peek-card
+      role="tooltip"
+      className="fixed z-40 rounded-control border p-3 shadow-md border-line bg-canvas text-ink"
+      style={{ left: at.left, top: at.top, width: CARD_WIDTH }}
+    >
+      <div className="flex items-center gap-2">
+        <span className="flex shrink-0" style={ctxStyle(peek.contextId)}>
+          <KindIcon kind={peek.kind} contextId={peek.contextId ?? undefined} />
+        </span>
+        <span className="mono min-w-0 flex-1 truncate text-sm font-medium">
+          {peek.name}
+        </span>
+        <span className="chip shrink-0">{KIND_LABEL[peek.kind]}</span>
+      </div>
+      <div className="mono mt-0.5 truncate t-micro text-muted" title={peek.where}>
+        {peek.where}
+      </div>
+      {peek.blurb ? (
+        <p className="mt-2 text-xs" style={clamp}>
+          {peek.blurb}
+        </p>
+      ) : null}
+      {peek.facts.length > 0 ? (
+        <div className="mono mt-2 flex flex-wrap gap-x-3 gap-y-1 t-micro text-muted">
+          {peek.facts.map((f) =>
+            f.countable ? (
+              <span key={f.label}>
+                <span className="tnum font-medium text-ink">{f.value}</span>{" "}
+                {f.label}
+              </span>
+            ) : (
+              <span key={f.label}>
+                {f.label}{" "}
+                <span className="font-medium text-ink">{f.value}</span>
+              </span>
+            ),
+          )}
+        </div>
+      ) : null}
+    </m.div>
+  );
+}

package/src/peek/PeekLayer.tsx

@@ -0,0 +1,147 @@
+// Where peeks come from: one listener, the whole document.
+//
+// Every row that can be selected already says which catalog id it stands for
+// - `data-sel` on the tree, the canvases and the tables - and anything else
+// that leads to an entity says so with `data-peek`. One handler on the
+// document reads that attribute off whatever the pointer is over, which is
+// how a card appears on a row written before this file existed.
+//
+// The rules of the card, in order of how often they matter:
+//
+//   - It waits 400ms. A pointer crossing a list on its way somewhere else
+//     must not leave a trail of cards behind it.
+//   - Anything the reader does dismisses it: a key, a click, a scroll. The
+//     card is for the moment before deciding, and each of those is a decision.
+//   - Moving from the row into the card keeps it, for 150ms of grace across
+//     the gap. It holds no controls, but a reader who wants to read the whole
+//     blurb should be able to put the pointer on it.
+//   - There is no card for what the panel is already showing, and none on a
+//     touch screen or a narrow window, where there is no hover to speak of.
+
+import { useEffect, useRef, useState } from "react";
+import { useNarrow } from "../app/responsive";
+import { AnimatePresence } from "../lib/motion";
+import { useSelectionStore } from "../selection/store";
+import { PeekCard } from "./PeekCard";
+import { peekOf } from "./model";
+import type { Peek } from "./model";
+
+export const PEEK_DELAY_MS = 400;
+const GRACE_MS = 150;
+
+/** What the pointer is over, or null when it is over nothing that peeks. */
+export function anchorOf(
+  target: EventTarget | null,
+): { el: HTMLElement; id: string } | null {
+  if (!(target instanceof Element)) return null;
+  const el = target.closest<HTMLElement>("[data-peek],[data-sel]");
+  if (!el || el.closest("[data-peek-card]")) return null;
+  const id = el.dataset.peek || el.dataset.sel;
+  return id ? { el, id } : null;
+}
+
+interface Shown {
+  peek: Peek;
+  rect: DOMRect;
+}
+
+export function PeekLayer() {
+  const narrow = useNarrow();
+  const [shown, setShown] = useState<Shown | null>(null);
+  // Read at hover time, not subscribed: the handler is installed once.
+  const selectedId = useRef<string | null>(null);
+  selectedId.current = useSelectionStore((s) => s.selection?.id ?? null);
+
+  useEffect(() => {
+    if (narrow) return;
+    if (typeof window.matchMedia === "function" && !window.matchMedia("(hover: hover)").matches) return;
+
+    let showTimer: ReturnType<typeof setTimeout> | null = null;
+    let hideTimer: ReturnType<typeof setTimeout> | null = null;
+    // The element a pending or shown card belongs to; entering its children
+    // again is not a new hover.
+    let anchor: HTMLElement | null = null;
+
+    const cancelShow = () => {
+      if (showTimer) clearTimeout(showTimer);
+      showTimer = null;
+    };
+    const cancelHide = () => {
+      if (hideTimer) clearTimeout(hideTimer);
+      hideTimer = null;
+    };
+    const hide = () => {
+      cancelShow();
+      cancelHide();
+      anchor = null;
+      setShown(null);
+    };
+    const hideSoon = () => {
+      cancelShow();
+      if (hideTimer) return;
+      hideTimer = setTimeout(hide, GRACE_MS);
+    };
+
+    const arm = (el: HTMLElement, id: string) => {
+      if (anchor === el) {
+        cancelHide();
+        return;
+      }
+      cancelShow();
+      cancelHide();
+      anchor = el;
+      showTimer = setTimeout(() => {
+        showTimer = null;
+        if (id === selectedId.current) return;
+        const peek = peekOf(id);
+        if (!peek || !el.isConnected) return;
+        setShown({ peek, rect: el.getBoundingClientRect() });
+      }, PEEK_DELAY_MS);
+    };
+
+    const onOver = (e: MouseEvent) => {
+      if (e.target instanceof Element && e.target.closest("[data-peek-card]")) {
+        cancelHide();
+        return;
+      }
+      const a = anchorOf(e.target);
+      if (a) arm(a.el, a.id);
+      else hideSoon();
+    };
+    const onFocusIn = (e: FocusEvent) => {
+      const a = anchorOf(e.target);
+      if (a) arm(a.el, a.id);
+      else hide();
+    };
+    const onLeaveWindow = (e: MouseEvent) => {
+      if (e.relatedTarget === null) hide();
+    };
+    // A scroll moves the anchor out from under the card; a pending card
+    // reads its rect when it fires, so only what is on screen goes.
+    const onScroll = () => setShown(null);
+
+    document.addEventListener("mouseover", onOver);
+    document.addEventListener("mouseout", onLeaveWindow);
+    document.addEventListener("focusin", onFocusIn);
+    document.addEventListener("keydown", hide);
+    document.addEventListener("pointerdown", hide);
+    document.addEventListener("scroll", onScroll, true);
+    return () => {
+      hide();
+      document.removeEventListener("mouseover", onOver);
+      document.removeEventListener("mouseout", onLeaveWindow);
+      document.removeEventListener("focusin", onFocusIn);
+      document.removeEventListener("keydown", hide);
+      document.removeEventListener("pointerdown", hide);
+      document.removeEventListener("scroll", onScroll, true);
+    };
+  }, [narrow]);
+
+  return (
+    <AnimatePresence>
+      {shown ? (
+        <PeekCard key={shown.peek.id} peek={shown.peek} rect={shown.rect} />
+      ) : null}
+    </AnimatePresence>
+  );
+}

package/src/peek/model.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it, vi } from "vitest";
+import { allEvents, allServices, walkSteps } from "../catalog";
+import { catalog, index } from "../testing/estate";
+import { flowStepId } from "../selection/model";
+import { BLURB_CHARS, blurbOf, count, peekOf } from "./model";
+
+// The live catalog under test is Portolan's own: three services, no
+// aggregate, no event. A card is about what an event or a table says of
+// itself, so the frozen estate is what these run against.
+vi.mock("../data", async () => {
+  const estate = await import("../testing/estate");
+  return { catalog: estate.catalog, index: estate.index };
+});
+
+describe("blurbOf", () => {
+  it("is null for nothing written", () => {
+    expect(blurbOf(undefined)).toBeNull();
+    expect(blurbOf("")).toBeNull();
+    expect(blurbOf("```go\nfunc main() {}\n```")).toBeNull();
+  });
+
+  it("flattens markdown, drops the heading, and keeps short prose whole", () => {
+    expect(blurbOf("# Orders\n\nThe **order** book.\n\n## States\n\nOpen.")).toBe(
+      "The order book. Open.",
+    );
+  });
+
+  it("cuts long prose at a word and says so", () => {
+    const words = Array.from({ length: 60 }, (_, i) => `word${i}`).join(" ");
+    const blurb = blurbOf(words)!;
+    expect(blurb.length).toBeLessThanOrEqual(BLURB_CHARS + 1);
+    expect(blurb.endsWith("…")).toBe(true);
+    expect(
+      blurb
+        .slice(0, -1)
+        .split(" ")
+        .every((w) => /^word\d+$/.test(w)),
+    ).toBe(true);
+  });
+
+  it("does not leave a comma hanging before the ellipsis", () => {
+    const text = `${"a".repeat(150)}, ${"b".repeat(40)}`;
+    expect(blurbOf(text)).toBe(`${"a".repeat(150)}…`);
+  });
+});
+
+describe("count", () => {
+  it("agrees the noun with the number", () => {
+    expect(count(1, "flow")).toEqual({
+      countable: true,
+      label: "flow",
+      value: "1",
+    });
+    expect(count(0, "flow")).toEqual({
+      countable: true,
+      label: "flows",
+      value: "0",
+    });
+    expect(count(2, "entity", "entities")).toEqual({
+      countable: true,
+      label: "entities",
+      value: "2",
+    });
+  });
+});
+
+describe("peekOf", () => {
+  it("answers for every context, service, aggregate and event", () => {
+    expect(allEvents(catalog).length).toBeGreaterThan(0);
+    for (const context of catalog.contexts) {
+      const peek = peekOf(context.id);
+      expect(peek?.kind, context.id).toBe("context");
+      expect(peek?.contextId).toBe(context.id);
+      for (const service of context.services) {
+        expect(peekOf(service.id)?.kind, service.id).toBe("service");
+        for (const aggregate of service.aggregates) {
+          expect(peekOf(aggregate.id)?.kind, aggregate.id).toBe("aggregate");
+          for (const event of aggregate.events) {
+            expect(peekOf(event.id)?.kind, event.id).toBe("event");
+          }
+        }
+      }
+    }
+  });
+
+  it("answers for every store, table, view and column", () => {
+    expect((catalog.stores ?? []).length).toBeGreaterThan(0);
+    for (const store of catalog.stores ?? []) {
+      expect(peekOf(store.id)?.kind, store.id).toBe("store");
+      for (const table of store.tables) {
+        expect(peekOf(table.id)?.kind, table.id).toBe("table");
+        for (const column of table.columns) {
+          const peek = peekOf(`${table.id}.${column.name}`);
+          expect(peek?.kind, column.name).toBe("table");
+          expect(peek?.facts[0]).toEqual({ label: "type", value: column.type });
+        }
+      }
+      for (const view of store.views ?? []) {
+        expect(peekOf(view.id)?.kind, view.id).toBe("view");
+      }
+    }
+  });
+
+  it("answers for every shared type", () => {
+    expect(Object.keys(catalog.defs).length).toBeGreaterThan(0);
+    for (const defId of Object.keys(catalog.defs)) {
+      expect(peekOf(defId)?.kind, defId).toBe("def");
+    }
+  });
+
+  it("says who publishes an event and how many consume it", () => {
+    const event = allEvents(catalog).find((e) => e.consumers.length > 0)!;
+    expect(event).toBeDefined();
+    const owner = index.eventOwner.get(event.id)!;
+    const peek = peekOf(event.id)!;
+    expect(peek.name).toBe(event.name);
+    expect(peek.where).toContain(owner.service.name);
+    expect(peek.where).toContain(owner.aggregate.name);
+    const consumers = peek.facts.find((f) => f.label.startsWith("consumer"));
+    expect(consumers?.value).toBe(String(event.consumers.length));
+    const latest = event.versions[event.versions.length - 1]!;
+    expect(peek.facts.find((f) => f.label === "version")?.value).toBe(
+      latest.version,
+    );
+  });
+
+  it("counts a service's aggregates and events", () => {
+    const service = allServices(catalog).find((s) => s.aggregates.length > 0)!;
+    expect(service).toBeDefined();
+    const peek = peekOf(service.id)!;
+    const events = service.aggregates.reduce((n, a) => n + a.events.length, 0);
+    expect(peek.facts.find((f) => f.label.startsWith("aggregate"))?.value).toBe(
+      String(service.aggregates.length),
+    );
+    expect(peek.facts.find((f) => f.label.startsWith("event"))?.value).toBe(
+      String(events),
+    );
+  });
+
+  it("keeps every blurb to two lines", () => {
+    const blurbs = allServices(catalog)
+      .map((s) => peekOf(s.id)?.blurb)
+      .filter((b): b is string => !!b);
+    expect(blurbs.length).toBeGreaterThan(0);
+    for (const blurb of blurbs) {
+      expect(blurb.length).toBeLessThanOrEqual(BLURB_CHARS + 1);
+    }
+  });
+
+  it("is null for what the catalog does not know, and for a flow step", () => {
+    expect(peekOf("nope.nothing.Here")).toBeNull();
+    const flow = catalog.flows[0]!;
+    const step = walkSteps(flow.steps)[0]!;
+    expect(peekOf(flowStepId(flow.slug, step.id))).toBeNull();
+  });
+});