@shortlink-org/portolan 0.1.0

package/src/app/panels.tsx

@@ -0,0 +1,141 @@
+// Resizable layout, in one place.
+//
+// react-resizable-panels v4 calls them Group / Panel / Separator. Everything
+// portolan needs on top of that is here: a persisted layout keyed by page, a
+// separator that reads as a hairline until you reach for it, and a hook that
+// tells a canvas its box changed.
+
+import { useCallback, useEffect, useRef } from "react";
+import { Group, Separator, useDefaultLayout } from "react-resizable-panels";
+import type { GroupProps } from "react-resizable-panels";
+
+export { Panel, usePanelRef } from "react-resizable-panels";
+export type { PanelImperativeHandle } from "react-resizable-panels";
+
+/** The 100ms every canvas in the app waits before it re-measures. */
+const RESIZE_SETTLE_MS = 100;
+
+/**
+ * localStorage, but a private-mode failure is not worth a crash: a layout that
+ * cannot be remembered is a layout that starts at its defaults.
+ */
+const storage = {
+  getItem(key: string): string | null {
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  },
+  setItem(key: string, value: string): void {
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+      /* private mode: this session still resizes, it just does not persist */
+    }
+  },
+};
+
+/**
+ * A Group whose layout survives a reload. `id` is the storage key and is
+ * spelled "portolan:<page>" at every call site, so one glance at localStorage
+ * says which page a layout belongs to.
+ *
+ * `panelIds` matters when a Group holds a Panel that is not always rendered -
+ * without it the restored layout is applied to the wrong panels.
+ */
+export function SavedGroup({
+  id,
+  panelIds,
+  children,
+  ...rest
+}: Omit<GroupProps, "id" | "defaultLayout" | "onLayoutChanged"> & {
+  id: string;
+  panelIds?: string[];
+}) {
+  const { defaultLayout, onLayoutChanged } = useDefaultLayout({
+    id,
+    storage,
+    ...(panelIds ? { panelIds } : {}),
+  });
+  return (
+    <Group
+      id={id}
+      defaultLayout={defaultLayout}
+      onLayoutChanged={onLayoutChanged}
+      {...rest}
+    >
+      {children}
+    </Group>
+  );
+}
+
+/**
+ * The divider. A 1px hairline that thickens to a 3px accent rule under the
+ * pointer or the keyboard, drawn by a child rather than by the separator's own
+ * border, so the 8px hit area never becomes 8px of visible gutter and nothing
+ * around it reflows when the rule thickens.
+ *
+ * Double-click resets the neighbouring panel to its default size; that is the
+ * library's own behaviour and is left on deliberately.
+ */
+export function ResizeHandle({
+  orientation = "horizontal",
+  id,
+}: {
+  /** Matches the parent Group. Horizontal groups get a vertical divider. */
+  orientation?: "horizontal" | "vertical";
+  id?: string;
+}) {
+  const vertical = orientation === "horizontal";
+  return (
+    <Separator
+      {...(id ? { id } : {})}
+      className={`group relative z-20 flex shrink-0 items-center justify-center ${
+        vertical ? "w-2 cursor-col-resize" : "h-2 cursor-row-resize"
+      }`}
+      title="Drag to resize · double-click to reset"
+    >
+      {/* The library puts data-separator="inactive|hover|focus|active" on the
+          separator itself, and its "hover" accounts for the full 8px target -
+          wider than the 1px rule the reader can actually see. Keying off that
+          rather than :hover is what makes the rule thicken as soon as the
+          pointer is in the hit area, and it covers the keyboard the same way. */}
+      <span
+        aria-hidden
+        className={`bg-line t-micro transition-[background-color,width,height] group-data-[separator=hover]:bg-accent group-data-[separator=focus]:bg-accent group-data-[separator=active]:bg-accent ${
+          vertical
+            ? "h-full w-px group-data-[separator=hover]:w-[3px] group-data-[separator=focus]:w-[3px] group-data-[separator=active]:w-[3px]"
+            : "h-px w-full group-data-[separator=hover]:h-[3px] group-data-[separator=focus]:h-[3px] group-data-[separator=active]:h-[3px]"
+        }`}
+      />
+    </Separator>
+  );
+}
+
+/**
+ * Tells a canvas its box changed, once the dragging has stopped.
+ *
+ * LikeC4 and React Flow both re-measure on the window's resize event, and both
+ * are expensive enough that doing it on every frame of a drag is visible. The
+ * trailing 100ms edge is the whole point: the reader drags, the picture
+ * re-lays-out once, when they let go.
+ */
+export function useCanvasResize(): () => void {
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  return useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      window.dispatchEvent(new Event("resize"));
+    }, RESIZE_SETTLE_MS);
+  }, []);
+}

package/src/app/pins.tsx

@@ -0,0 +1,242 @@
+// Pinning, everywhere it is offered.
+//
+// The store holds kinds and ids; `resolvePin` turns one back into a row the
+// tree can draw. Resolution happening at render rather than at pin time is the
+// whole point: a pin survives a rebuild that renamed the event, and quietly
+// stops resolving when the event is gone, rather than pointing at a page the
+// catalog no longer has.
+
+import { Pin as PinIcon, PinOff } from "lucide-react";
+import { create } from "zustand";
+import { catalog, index } from "../data";
+import { adrNumber } from "../lib/adr";
+import { flowOwner } from "../lib/flow-tree";
+import { addPin, isPinned, movePin, removePin } from "../lib/pins";
+import type { Pin, PinKind } from "../lib/pins";
+import { readPins, writePins } from "../lib/sidebar-prefs";
+import type { Kind } from "../lib/kinds";
+import {
+  adrPath,
+  aggregatePath,
+  eventPath,
+  modulePath,
+  paths,
+  servicePath,
+  storePath,
+  tablePath,
+} from "../routes";
+import { useToastStore } from "./toast";
+
+interface PinsState {
+  pins: Pin[];
+  toggle: (pin: Pin) => void;
+  reorder: (from: number, to: number) => void;
+}
+
+export const usePinsStore = create<PinsState>()((set, get) => ({
+  pins: readPins(),
+  toggle: (pin) => {
+    const current = get().pins;
+    if (isPinned(current, pin)) {
+      const next = removePin(current, pin);
+      writePins(next);
+      set({ pins: next });
+      return;
+    }
+    const { pins: next, evicted } = addPin(current, pin);
+    writePins(next);
+    set({ pins: next });
+    if (evicted) {
+      const gone = resolvePin(evicted);
+      useToastStore
+        .getState()
+        .say(`pinned — ${gone?.name ?? evicted.id} was unpinned to make room`);
+    }
+  },
+  reorder: (from, to) => {
+    const next = movePin(get().pins, from, to);
+    writePins(next);
+    set({ pins: next });
+  },
+}));
+
+/** True while this exact thing is on the list. Re-renders only when it flips. */
+function useIsPinned(pin: Pin | null): boolean {
+  return usePinsStore((s) => (pin ? isPinned(s.pins, pin) : false));
+}
+
+export interface ResolvedPin {
+  pin: Pin;
+  /** The kind's icon in the shared taxonomy, which is not always the pin kind. */
+  kind: Kind;
+  name: string;
+  /** What the row is titled with - the catalog id, as it is spelled. */
+  title: string;
+  path: string;
+  contextId: string | null;
+}
+
+/**
+ * A pin, as a row. Null when the catalog no longer has what was pinned: the
+ * tree drops the row rather than drawing a name with nowhere to go.
+ */
+export function resolvePin(pin: Pin): ResolvedPin | null {
+  const base = { pin, title: pin.id };
+  switch (pin.kind) {
+    case "context": {
+      const context = catalog.contexts.find((c) => c.id === pin.id);
+      if (!context) return null;
+      return {
+        ...base,
+        kind: "context",
+        name: context.name,
+        path: paths.context(context.id),
+        contextId: context.id,
+      };
+    }
+    case "store": {
+      const store = index.storeById.get(pin.id);
+      const to = storePath(pin.id);
+      if (!store || !to) return null;
+      return {
+        ...base,
+        kind: "store",
+        name: store.name,
+        path: to,
+        contextId: index.serviceContext.get(store.owner)?.id ?? null,
+      };
+    }
+    case "flow": {
+      const flow = catalog.flows.find((f) => f.id === pin.id);
+      if (!flow) return null;
+      return {
+        ...base,
+        kind: "flow",
+        name: flow.name,
+        title: flow.slug,
+        path: paths.flow(flow.slug),
+        contextId: flowOwner(flow),
+      };
+    }
+    case "event": {
+      const event = index.eventById.get(pin.id);
+      const owner = index.eventOwner.get(pin.id);
+      const to = eventPath(pin.id);
+      if (!event || !owner || !to) return null;
+      return {
+        ...base,
+        kind: "event",
+        name: event.name,
+        path: to,
+        contextId: index.serviceContext.get(owner.service.id)?.id ?? null,
+      };
+    }
+    case "adr": {
+      const adr = index.adrById.get(pin.id);
+      const to = adrPath(pin.id);
+      if (!adr || !to) return null;
+      return {
+        ...base,
+        kind: "adr",
+        name: `${adrNumber(adr).replace(/^ADR-/, "")}  ${adr.title}`,
+        path: to,
+        contextId: adr.scope.kind === "context" ? adr.scope.context : null,
+      };
+    }
+    case "module": {
+      const module = index.moduleById.get(pin.id);
+      const to = modulePath(pin.id);
+      if (!module || !to) return null;
+      return {
+        ...base,
+        kind: "module",
+        name: module.name,
+        path: to,
+        // A module belongs to no single context: it is published by one
+        // service and read by four, which is why it has no context colour.
+        contextId: null,
+      };
+    }
+    case "service": {
+      const service = index.serviceById.get(pin.id);
+      const to = servicePath(pin.id);
+      if (!service || !to) return null;
+      return {
+        ...base,
+        kind: "service",
+        name: service.name,
+        path: to,
+        contextId: index.serviceContext.get(pin.id)?.id ?? null,
+      };
+    }
+    case "aggregate": {
+      const aggregate = index.aggregateById.get(pin.id);
+      const owner = index.aggregateOwner.get(pin.id);
+      const to = aggregatePath(pin.id);
+      if (!aggregate || !owner || !to) return null;
+      return {
+        ...base,
+        kind: "aggregate",
+        name: aggregate.name,
+        path: to,
+        contextId: index.serviceContext.get(owner.id)?.id ?? null,
+      };
+    }
+    case "table": {
+      const held = index.tableById.get(pin.id);
+      const to = tablePath(pin.id);
+      if (!held || !to) return null;
+      return {
+        ...base,
+        kind: "table",
+        name: held.table.name,
+        path: to,
+        contextId: index.serviceContext.get(held.store.owner)?.id ?? null,
+      };
+    }
+  }
+}
+
+/**
+ * The pin control, and the only one. It says what it will do rather than what
+ * the state is - "Pin" / "Unpin" - because a filled pin icon on its own reads
+ * as decoration on a page a reader has never pinned.
+ */
+export function PinButton({
+  kind,
+  id,
+  label,
+  size = 16,
+}: {
+  kind: PinKind;
+  id: string;
+  /** What the tooltip names, when the catalog id is not what a reader calls it. */
+  label?: string;
+  size?: number;
+}) {
+  const pin: Pin = { kind, id };
+  const pinned = useIsPinned(pin);
+  const toggle = usePinsStore((s) => s.toggle);
+  const what = label ?? id;
+  const title = pinned
+    ? `Unpin ${what}`
+    : `Pin ${what} to the top of the catalog`;
+  return (
+    <button
+      type="button"
+      onClick={() => toggle(pin)}
+      aria-pressed={pinned}
+      aria-label={title}
+      title={title}
+      className={`flex size-7 shrink-0 items-center justify-center rounded-control t-micro transition-colors hover:bg-surface ${
+        pinned ? "text-accent" : "text-muted hover:text-ink"
+      }`}
+    >
+      {pinned ? (
+        <PinOff size={size} aria-hidden />
+      ) : (
+        <PinIcon size={size} aria-hidden />
+      )}
+    </button>
+  );
+}

package/src/app/query-client.ts

@@ -0,0 +1,24 @@
+import { QueryClient } from "@tanstack/react-query";
+
+/**
+ * One client for everything the app reads over the network at runtime: forge
+ * branches and catalogs, source previews, the local API's status.
+ *
+ * The defaults are deliberately quiet. A forge answers 401, 404 or a rate
+ * limit, and repeating those only hides the message and spends the limit, so
+ * nothing retries. Nothing refetches on focus or reconnect either: a reader
+ * flipping between tabs must not spend GitHub requests. Data stays fresh for
+ * the session, which is what the hand-written promise caches did before; the
+ * comparison page's "Try again" resets the forge queries explicitly.
+ */
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: false,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      staleTime: Infinity,
+      gcTime: 30 * 60 * 1000,
+    },
+  },
+});

package/src/app/responsive.ts

@@ -0,0 +1,55 @@
+// Two breakpoints, named once.
+//
+// 1100px is not a phone. It is the width a 13" laptop has left after the reader
+// has put something else beside portolan, and below it the three-pane shell
+// stops being three panes: the tree becomes a drawer and the detail rail
+// becomes a sheet. That is graceful degradation of a desktop tool, not a mobile
+// design, and nothing below this line pretends otherwise.
+//
+// 640px is a phone held upright, and it is a second thing entirely. The shell
+// has already degraded by then; what runs out at this width is the top bar's
+// own row, which carries a search box, five controls and a build stamp beside
+// the breadcrumbs. Wrapping turned that into three rows of chrome above a page
+// that had four rows of its own, so below this width the bar keeps one row and
+// puts what does not fit behind an icon.
+
+import { useEffect, useState } from "react";
+
+const NARROW_QUERY = "(max-width: 1099px)";
+const PHONE_QUERY = "(max-width: 639px)";
+
+function match(query: string): boolean {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia(query).matches;
+}
+
+function useMediaQuery(query: string): boolean {
+  const [on, setOn] = useState(() => match(query));
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia(query);
+    const onChange = () => setOn(mq.matches);
+    mq.addEventListener("change", onChange);
+    // The resize listener is the belt to matchMedia's braces. Under a viewport
+    // that is emulated rather than dragged - devtools, a screenshot harness -
+    // the media query updates but its change event never fires, and the shell
+    // would sit in the wrong layout until the next reload.
+    window.addEventListener("resize", onChange);
+    onChange();
+    return () => {
+      mq.removeEventListener("change", onChange);
+      window.removeEventListener("resize", onChange);
+    };
+  }, [query]);
+  return on;
+}
+
+/** True while the viewport is too narrow to hold the panes side by side. */
+export function useNarrow(): boolean {
+  return useMediaQuery(NARROW_QUERY);
+}
+
+/** True while the viewport is too narrow to hold the top bar on one row. */
+export function usePhone(): boolean {
+  return useMediaQuery(PHONE_QUERY);
+}

package/src/app/shortcuts.test.ts

@@ -0,0 +1,39 @@
+// The "?" sheet is only useful if it is true. These are the two ways it could
+// stop being true: a chord that goes nowhere, and a key bound twice.
+
+import { describe, expect, it } from "vitest";
+import { GO_TO, SHORTCUT_GROUPS } from "./shortcuts";
+import { isRoutable } from "../routes";
+
+describe("go-to chords", () => {
+  it("every destination is a route this app actually serves", () => {
+    for (const target of GO_TO) {
+      expect(isRoutable(target.to), `g ${target.key} -> ${target.to}`).toBe(
+        true,
+      );
+    }
+  });
+
+  it("binds each second key once", () => {
+    const keys = GO_TO.map((g) => g.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it("is what the sheet prints", () => {
+    const listed =
+      SHORTCUT_GROUPS.find((g) => g.group === "Go to")?.items ?? [];
+    expect(listed.map((i) => i.keys)).toEqual(GO_TO.map((g) => ["g", g.key]));
+  });
+});
+
+describe("the sheet", () => {
+  it("names every key the handler implements", () => {
+    const printed = SHORTCUT_GROUPS.flatMap((g) => g.items).flatMap(
+      (i) => i.keys,
+    );
+    // Everything useShortcuts binds outside the go-to chord.
+    for (const key of ["[", "]", "j", "k", "?", "⌘", "K", "Esc", "⏎"]) {
+      expect(printed, `"${key}" is bound but not listed`).toContain(key);
+    }
+  });
+});