@shortlink-org/portolan 0.1.0

package/src/app/TopBar.tsx

@@ -0,0 +1,393 @@
+import { Link } from "react-router";
+import { Popover, PopoverButton, PopoverPanel } from "@headlessui/react";
+import {
+  Keyboard,
+  Layers3,
+  Map,
+  Menu,
+  MessageSquare,
+  MoreHorizontal,
+  Moon,
+  Network,
+  Rows2,
+  Rows4,
+  Search,
+  Settings2,
+  Sun,
+} from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+import { Breadcrumbs } from "./Breadcrumbs";
+import { BranchPicker } from "./BranchPicker";
+import { BuildStamp } from "./BuildStamp";
+import { useDensity } from "./density";
+import { usePhone } from "./responsive";
+import { useTheme } from "./theme";
+import { useChatAvailable } from "../chat/prefs";
+import { useChatUi } from "../chat/store";
+import { paths } from "../routes";
+import { activeCatalogProfile, catalogProfiles } from "../data";
+
+export function TopBar({
+  onOpenPalette,
+  onOpenHelp,
+  onToggleSidebar,
+  narrow = false,
+}: {
+  onOpenPalette: () => void;
+  onOpenHelp: () => void;
+  onToggleSidebar: () => void;
+  /** Below the narrow breakpoint the tree is a drawer, opened from here. */
+  narrow?: boolean;
+}) {
+  const phone = usePhone();
+
+  return (
+    /* One row while there is room for one, and rows when there is not: the
+       shell degrades to a drawer at the narrow breakpoint, but the bar's own
+       contents have a width of their own and run out before that. Wrapping is
+       what keeps every control reachable - hiding them would take the theme
+       and the shortcuts sheet away from exactly the window that has the least
+       room to do without them.
+
+       The controls wrap as CONTROLS, not as a block. Held together in one box
+       they wrapped as one - a first row carrying nothing but the drawer and
+       the word `portolan`, and the search sixty pixels below it beside a
+       third of a row of white. Flat, each one takes the space left on the row
+       above it, and the bar is two rows where it used to be three. The
+       breadcrumbs keep the left with `mr-auto`; every line is justified to
+       the end, so a control that does drop to the next row drops to the right
+       edge rather than under the crumbs.
+
+       On a phone wrapping is no longer the lesser evil: the bar wrapped to
+       three rows of chrome above a page that had few enough of its own, and
+       chrome that tall is not "reachable", it is in the way. So below the
+       phone breakpoint the bar keeps one row and folds instead - the search
+       box to its icon, the whole-estate views and the two settings into an
+       overflow menu, the build stamp into a popover. What stays on the row is
+       what a reader steers with: the drawer, where they are, and search. */
+    <header
+      className={`flex min-h-12 shrink-0 items-center border-b py-1 px-gutter border-line bg-canvas ${
+        phone ? "gap-x-2" : "flex-wrap justify-end gap-x-3 gap-y-2"
+      }`}
+    >
+      {narrow ? (
+        <button
+          type="button"
+          onClick={onToggleSidebar}
+          aria-label="Open the catalog"
+          aria-keyshortcuts="["
+          title="Catalog — ["
+          className="-ml-2 flex size-8 shrink-0 items-center justify-center rounded-control text-muted t-micro transition-colors hover:bg-surface hover:text-ink"
+        >
+          <Menu size={16} aria-hidden />
+        </button>
+      ) : null}
+
+      {/* The one thing on the row that may be squeezed: a breadcrumb trail
+          truncates, a control does not. */}
+      <div className="mr-auto min-w-0">
+        <Breadcrumbs />
+      </div>
+
+      {/* On the phone the controls stay one box that never wraps: three rows
+          of chrome above a short page is worse than a search box folded to
+          its icon. */}
+      <div
+        className={
+          phone
+            ? "ml-auto flex shrink-0 items-center justify-end gap-1"
+            : "contents"
+        }
+      >
+        <CatalogPicker compact={phone} />
+        <BranchPicker compact={phone} />
+
+        {/* Opens the palette rather than filtering in place: the sidebar box
+            narrows the tree, this one searches the whole catalog. */}
+        {phone ? (
+          <button
+            type="button"
+            onClick={onOpenPalette}
+            aria-label="Search catalog"
+            aria-keyshortcuts="Meta+K Control+K"
+            title="Search catalog"
+            className="flex size-8 shrink-0 items-center justify-center rounded-control border border-line text-muted t-micro transition-colors hover:bg-surface hover:border-line-strong hover:text-ink"
+          >
+            <Search size={16} aria-hidden />
+          </button>
+        ) : (
+          <button
+            type="button"
+            onClick={onOpenPalette}
+            aria-label="Search catalog"
+            aria-keyshortcuts="Meta+K Control+K"
+            className="mono flex w-56 items-center gap-2 rounded-control border px-2 py-1.5 border-line text-muted t-micro transition-colors hover:bg-surface hover:border-line-strong"
+          >
+            <Search size={16} aria-hidden className="shrink-0" />
+            search
+            <span className="ml-auto rounded-[4px] border px-1 border-line">
+              ⌘K
+            </span>
+          </button>
+        )}
+
+        {phone ? (
+          <OverflowMenu onOpenHelp={onOpenHelp} />
+        ) : (
+          /* One border around the set, hairlines between them: four controls,
+             one object. */
+          <Wide onOpenHelp={onOpenHelp} />
+        )}
+
+        <BuildStamp compact={phone} />
+      </div>
+    </header>
+  );
+}
+
+function CatalogPicker({ compact }: { compact: boolean }) {
+  if (catalogProfiles.length < 2) return null;
+
+  const change = (id: string) => {
+    if (id === activeCatalogProfile.id) return;
+    const next = new URL(import.meta.env.BASE_URL, window.location.origin);
+    next.searchParams.set("catalog", id);
+    window.location.assign(next);
+  };
+
+  return (
+    <label
+      className="mono flex shrink-0 items-center gap-1.5 rounded-control border border-line px-2 py-1.5 text-muted hover:border-line-strong hover:text-ink"
+      title="Catalog profile"
+    >
+      <Layers3 size={16} aria-hidden className="shrink-0" />
+      <span className="sr-only">Catalog</span>
+      <select
+        aria-label="Catalog profile"
+        value={activeCatalogProfile.id}
+        onChange={(event) => change(event.target.value)}
+        className={`bg-transparent text-ink outline-none ${compact ? "max-w-20" : "max-w-36"}`}
+      >
+        {catalogProfiles.map((profile) => (
+          <option key={profile.id} value={profile.id}>
+            {profile.title}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}
+
+function Wide({ onOpenHelp }: { onOpenHelp: () => void }) {
+  const { theme, toggle } = useTheme();
+  const { density, toggle: toggleDensity } = useDensity();
+  const compact = density === "compact";
+  const chat = useChatAvailable();
+  const openChat = () => useChatUi.getState().setOpen(true);
+
+  return (
+    <div className="seg">
+      {/* The two whole-estate views, side by side: the map is the domains
+          and what stands between them, the graph is the services and what
+          runs between them. */}
+      <Link
+        to="/map"
+        className="flex items-center gap-1.5"
+        aria-keyshortcuts="g m"
+        title="Context map — g m"
+      >
+        <Map size={16} aria-hidden />
+        map
+      </Link>
+      <Link
+        to="/graph"
+        className="flex items-center gap-1.5"
+        title="Dependency graph"
+      >
+        <Network size={16} aria-hidden />
+        graph
+      </Link>
+      {/* A question to the catalog, when something is set to answer it. */}
+      {chat ? (
+        <button
+          type="button"
+          onClick={openChat}
+          className="flex items-center gap-1.5"
+          title="Ask the catalog"
+        >
+          <MessageSquare size={16} aria-hidden />
+          ask
+        </button>
+      ) : null}
+      {/* Density is a property of the whole app, so it lives beside the
+          theme: both are "how portolan is set", not "what is on screen". */}
+      <button
+        type="button"
+        onClick={toggleDensity}
+        aria-pressed={compact}
+        aria-label={
+          compact ? "Switch to comfortable rows" : "Switch to compact rows"
+        }
+        title={compact ? "Comfortable rows" : "Compact rows"}
+        className="flex items-center"
+      >
+        {compact ? (
+          <Rows2 size={16} aria-hidden />
+        ) : (
+          <Rows4 size={16} aria-hidden />
+        )}
+      </button>
+      <button
+        type="button"
+        onClick={onOpenHelp}
+        aria-label="Keyboard shortcuts"
+        aria-keyshortcuts="?"
+        title="Keyboard shortcuts — ?"
+        className="flex items-center"
+      >
+        <Keyboard size={16} aria-hidden />
+      </button>
+      <button
+        type="button"
+        onClick={toggle}
+        aria-label={
+          theme === "dark" ? "Switch to light theme" : "Switch to dark theme"
+        }
+        className="flex items-center"
+      >
+        {theme === "dark" ? (
+          <Sun size={16} aria-hidden />
+        ) : (
+          <Moon size={16} aria-hidden />
+        )}
+      </button>
+      {/* The page the three controls above are the shortcuts to: what this
+          catalog was built from, and where the same two preferences are set
+          in words. Last, because it is the only one that navigates. */}
+      <Link
+        to={paths.settings()}
+        aria-label="Settings"
+        title="Settings — projects, plugins and appearance"
+        className="flex items-center"
+      >
+        <Settings2 size={16} aria-hidden />
+      </Link>
+    </div>
+  );
+}
+
+const ROW =
+  "mono flex w-full items-center gap-2 rounded-control px-2 py-2 text-left text-muted transition-colors hover:bg-surface hover:text-ink";
+
+/**
+ * Everything the wide bar puts on the row and a phone has no room for. It is a
+ * menu rather than a smaller segmented control because at this width the
+ * controls had shed their labels first, and five unlabelled icons in a strip is
+ * a puzzle - the menu buys the labels back with the space it saves.
+ */
+function OverflowMenu({ onOpenHelp }: { onOpenHelp: () => void }) {
+  const { theme, toggle } = useTheme();
+  const { density, toggle: toggleDensity } = useDensity();
+  const compact = density === "compact";
+  const chat = useChatAvailable();
+
+  return (
+    <Popover className="shrink-0">
+      <PopoverButton
+        aria-label="More"
+        title="More"
+        className={({ open }) =>
+          `flex size-8 items-center justify-center rounded-control border t-micro transition-colors border-line hover:bg-surface ${
+            open ? "text-accent" : "text-muted hover:text-ink"
+          }`
+        }
+      >
+        <MoreHorizontal size={16} aria-hidden />
+      </PopoverButton>
+      <PopoverPanel
+        anchor={{ to: "bottom end", gap: 4, padding: 8 }}
+        className="palette-in z-50 w-56 rounded-control border bg-canvas p-1 border-line-strong shadow-md focus:outline-none"
+      >
+        {({ close }) => (
+          <>
+            <div className="label mt-1 mb-1 px-2">the whole estate</div>
+            <Link to="/map" onClick={() => close()} className={ROW}>
+              <Map size={16} aria-hidden className="shrink-0" />
+              context map
+            </Link>
+            <Link to="/graph" onClick={() => close()} className={ROW}>
+              <Network size={16} aria-hidden className="shrink-0" />
+              dependency graph
+            </Link>
+            {chat ? (
+              <MenuButton
+                icon={MessageSquare}
+                onClick={() => {
+                  useChatUi.getState().setOpen(true);
+                  close();
+                }}
+              >
+                ask the catalog
+              </MenuButton>
+            ) : null}
+
+            <div className="label mt-2 mb-1 px-2">how portolan is set</div>
+            <MenuButton
+              icon={compact ? Rows2 : Rows4}
+              onClick={() => {
+                toggleDensity();
+                close();
+              }}
+            >
+              {compact ? "comfortable rows" : "compact rows"}
+            </MenuButton>
+            <MenuButton
+              icon={theme === "dark" ? Sun : Moon}
+              onClick={() => {
+                toggle();
+                close();
+              }}
+            >
+              {theme === "dark" ? "light theme" : "dark theme"}
+            </MenuButton>
+            <MenuButton
+              icon={Keyboard}
+              onClick={() => {
+                onOpenHelp();
+                close();
+              }}
+            >
+              keyboard shortcuts
+            </MenuButton>
+            <Link
+              to={paths.settings()}
+              onClick={() => close()}
+              className={ROW}
+            >
+              <Settings2 size={16} aria-hidden className="shrink-0" />
+              settings
+            </Link>
+          </>
+        )}
+      </PopoverPanel>
+    </Popover>
+  );
+}
+
+/** A row of the menu that does something rather than going somewhere. */
+function MenuButton({
+  icon: Icon,
+  onClick,
+  children,
+}: {
+  icon: LucideIcon;
+  onClick: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <button type="button" onClick={onClick} className={ROW}>
+      <Icon size={16} aria-hidden className="shrink-0" />
+      {children}
+    </button>
+  );
+}

package/src/app/density.tsx

@@ -0,0 +1,64 @@
+// Density, globally.
+//
+// Two settings, not a slider: comfortable is the default and compact is what a
+// reader switches to when they are scanning a hundred rows rather than reading
+// ten. It is written to <html data-density> rather than threaded through props,
+// because everything that responds to it responds in CSS - a row height and a
+// meta type size, both tokens - and nothing needs to re-render to obey.
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import type { ReactNode } from "react";
+
+export type Density = "comfortable" | "compact";
+
+interface DensityCtx {
+  density: Density;
+  toggle: () => void;
+}
+
+const Ctx = createContext<DensityCtx>({
+  density: "comfortable",
+  toggle: () => {},
+});
+
+const KEY = "portolan.density";
+
+function initial(): Density {
+  try {
+    return localStorage.getItem(KEY) === "compact" ? "compact" : "comfortable";
+  } catch {
+    /* private mode: this session still toggles, it just does not persist */
+    return "comfortable";
+  }
+}
+
+export function DensityProvider({ children }: { children: ReactNode }) {
+  const [density, setDensity] = useState<Density>(initial);
+
+  useEffect(() => {
+    document.documentElement.dataset["density"] = density;
+    try {
+      localStorage.setItem(KEY, density);
+    } catch {
+      /* see above */
+    }
+  }, [density]);
+
+  const toggle = useCallback(
+    () => setDensity((d) => (d === "compact" ? "comfortable" : "compact")),
+    [],
+  );
+  const value = useMemo(() => ({ density, toggle }), [density, toggle]);
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useDensity(): DensityCtx {
+  return useContext(Ctx);
+}

package/src/app/forge-access.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { forgeCredentialScope } from "./forge-access";
+
+describe("forgeCredentialScope", () => {
+  it("shares a token across repositories on one forge origin", () => {
+    expect(
+      forgeCredentialScope({
+        provider: "github",
+        owner: "acme",
+        repo: "shop",
+        webUrl: "https://github.com/acme/shop",
+      }),
+    ).toBe("https://github.com");
+    expect(forgeCredentialScope("https://github.com/acme/payments")).toBe(
+      "https://github.com",
+    );
+  });
+
+  it("keeps self-hosted forges in separate credential scopes", () => {
+    expect(forgeCredentialScope("https://gitlab.one.test/acme/shop")).toBe(
+      "https://gitlab.one.test",
+    );
+    expect(forgeCredentialScope("https://gitlab.two.test/acme/shop")).toBe(
+      "https://gitlab.two.test",
+    );
+  });
+});

package/src/app/forge-access.tsx

@@ -0,0 +1,80 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from "react";
+import type { ReactNode } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import type { ForgeRepo } from "../lib/github-catalog";
+import { forgeKeys, sourceKeys } from "../lib/queries";
+
+interface ForgeAccessState {
+  tokenFor: (repo: ForgeRepo | string) => string;
+  connectedTo: (repo: ForgeRepo | string) => boolean;
+  connect: (repo: ForgeRepo | string, token: string) => void;
+  disconnect: (repo: ForgeRepo | string) => void;
+}
+
+const Context = createContext<ForgeAccessState | null>(null);
+
+/**
+ * Repository credentials deliberately live only in React memory. They never
+ * enter a URL, Web Storage, Cache Storage, build output, or the comparison
+ * memory that remembers branch names.
+ */
+export function ForgeAccessProvider({ children }: { children: ReactNode }) {
+  const [tokens, setTokens] = useState<Readonly<Record<string, string>>>({});
+  const queryClient = useQueryClient();
+  // A token change makes every forge answer somebody else's. Dropping the
+  // queries, not just marking them stale, also drops the old token's keys.
+  const clearRuntimeCaches = useCallback(() => {
+    queryClient.removeQueries({ queryKey: forgeKeys.all });
+    queryClient.removeQueries({ queryKey: sourceKeys.all });
+  }, [queryClient]);
+  const connect = useCallback((repo: ForgeRepo | string, token: string) => {
+    const scope = forgeCredentialScope(repo);
+    const next = token.trim();
+    if (!scope || !next) return;
+    clearRuntimeCaches();
+    setTokens((current) => ({ ...current, [scope]: next }));
+  }, [clearRuntimeCaches]);
+  const disconnect = useCallback((repo: ForgeRepo | string) => {
+    const scope = forgeCredentialScope(repo);
+    clearRuntimeCaches();
+    setTokens((current) => {
+      if (!scope || !(scope in current)) return current;
+      const next = { ...current };
+      delete next[scope];
+      return next;
+    });
+  }, [clearRuntimeCaches]);
+  const value = useMemo<ForgeAccessState>(
+    () => ({
+      tokenFor: (repo) => tokens[forgeCredentialScope(repo)] ?? "",
+      connectedTo: (repo) => Boolean(tokens[forgeCredentialScope(repo)]),
+      connect,
+      disconnect,
+    }),
+    [connect, disconnect, tokens],
+  );
+
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useForgeAccess(): ForgeAccessState {
+  const value = useContext(Context);
+  if (!value) throw new Error("useForgeAccess must be used inside ForgeAccessProvider");
+  return value;
+}
+
+/** Tokens are shared by repositories on one forge host, but never across hosts. */
+export function forgeCredentialScope(repo: ForgeRepo | string): string {
+  const value = typeof repo === "string" ? repo : repo.webUrl;
+  try {
+    return new URL(value).origin.toLowerCase();
+  } catch {
+    return value.trim().replace(/\/$/, "").toLowerCase();
+  }
+}