@shortlink-org/portolan 0.1.0

package/src/app/shortcuts.tsx

@@ -0,0 +1,282 @@
+// The keyboard.
+//
+// One handler, one table. The table below is what the "?" sheet prints and what
+// the handler implements, so the sheet cannot drift from the app: adding a
+// shortcut without listing it is not possible without editing both halves of
+// the same object.
+//
+// Two rules hold everywhere. Nothing fires while a text field has focus - a
+// reader typing "flows" into a table's filter must not be teleported four
+// times - and ⌘K keeps working regardless, because opening the palette is the
+// one thing a reader does *from* a field.
+
+import { useEffect, useRef } from "react";
+import { useNavigate } from "react-router";
+import { X } from "lucide-react";
+import { Modal } from "../components/Overlay";
+import { OVERVIEW_ANCHOR, paths } from "../routes";
+
+export interface Shortcut {
+  /** Rendered as separate keycaps; a chord is two entries. */
+  keys: string[];
+  what: string;
+}
+
+/**
+ * The "g" chord, once. The handler navigates from this table and the sheet
+ * prints it, so a destination cannot exist in one and not the other.
+ */
+export const GO_TO: { key: string; to: string; what: string }[] = [
+  { key: "f", to: paths.flows(), what: "flows" },
+  {
+    key: "d",
+    to: `${paths.overview()}#${OVERVIEW_ANCHOR.contexts}`,
+    what: "the contexts, on the overview",
+  },
+  { key: "m", to: paths.map(), what: "the context map" },
+  { key: "p", to: paths.problems(), what: "problems" },
+  { key: "o", to: paths.overview(), what: "overview" },
+  { key: "a", to: paths.adrs(), what: "decisions" },
+  { key: "g", to: paths.graph(), what: "the dependency graph" },
+  { key: "l", to: paths.language(), what: "language" },
+  { key: "r", to: paths.registry(), what: "registry" },
+  { key: "c", to: paths.changes(), what: "changes" },
+  { key: "s", to: paths.settings(), what: "settings" },
+];
+
+export const SHORTCUT_GROUPS: { group: string; items: Shortcut[] }[] = [
+  {
+    group: "Go to",
+    items: GO_TO.map((g) => ({ keys: ["g", g.key], what: g.what })),
+  },
+  {
+    group: "Layout",
+    items: [
+      { keys: ["["], what: "show or hide the catalog tree" },
+      { keys: ["]"], what: "show or hide the detail panel" },
+    ],
+  },
+  {
+    group: "Lists, tables and the steps of a flow",
+    items: [
+      { keys: ["j"], what: "next row or step" },
+      { keys: ["k"], what: "previous row or step" },
+      { keys: ["⏎"], what: "open the row, or select the step" },
+    ],
+  },
+  {
+    group: "The catalog tree",
+    items: [
+      { keys: ["↓"], what: "next row" },
+      { keys: ["↑"], what: "previous row" },
+      { keys: ["→"], what: "open the branch, or step into it" },
+      { keys: ["←"], what: "close the branch, or go up to its parent" },
+    ],
+  },
+  {
+    group: "Everywhere",
+    items: [
+      { keys: ["⌘", "K"], what: "search the whole catalog" },
+      { keys: ["?"], what: "this sheet" },
+      { keys: ["Esc"], what: "clear the selection, or close what is open" },
+    ],
+  },
+];
+
+/** True while the keystroke belongs to something the reader is typing into. */
+function inField(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return (
+    target.tagName === "INPUT" ||
+    target.tagName === "TEXTAREA" ||
+    target.tagName === "SELECT" ||
+    target.isContentEditable
+  );
+}
+
+/**
+ * j / k walk whatever list the reader is standing in, and the first one on the
+ * page when they are standing in none. Movement is DOM focus rather than a
+ * highlight of our own, so Enter is the browser's Enter and the focus ring is
+ * the one every other control uses.
+ */
+function moveListFocus(delta: number): boolean {
+  const active = document.activeElement as HTMLElement | null;
+  // Standing in a list walks that list. Standing nowhere walks the page's own
+  // list before the catalog tree's - the tree is always on screen, and always
+  // first in the DOM, so preferring it would mean j never touched the thing
+  // the reader is actually looking at.
+  const list =
+    active?.closest<HTMLElement>("[data-nav-list]") ??
+    document.querySelector<HTMLElement>("main [data-nav-list]") ??
+    document.querySelector<HTMLElement>("[data-nav-list]");
+  if (!list) return false;
+  const items = [...list.querySelectorAll<HTMLElement>("[data-nav-item]")];
+  if (items.length === 0) return false;
+  const at = active ? items.indexOf(active) : -1;
+  const next =
+    at < 0
+      ? delta > 0
+        ? 0
+        : items.length - 1
+      : Math.min(items.length - 1, Math.max(0, at + delta));
+  items[next]?.focus();
+  items[next]?.scrollIntoView({ block: "nearest" });
+  return true;
+}
+
+export interface ShortcutActions {
+  openPalette: () => void;
+  openHelp: () => void;
+  toggleSidebar: () => void;
+  toggleDetail: () => void;
+}
+
+/** How long a "g" waits for its second key before it goes back to being a "g". */
+const CHORD_MS = 1200;
+
+export function useShortcuts(actions: ShortcutActions, enabled: boolean): void {
+  const navigate = useNavigate();
+  // Refs so the listener is installed once: rebinding it on every render would
+  // drop a chord half-typed.
+  const act = useRef(actions);
+  act.current = actions;
+  const on = useRef(enabled);
+  on.current = enabled;
+
+  useEffect(() => {
+    let chord = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const endChord = () => {
+      chord = false;
+      if (timer) clearTimeout(timer);
+      timer = null;
+    };
+
+    const onKey = (e: KeyboardEvent) => {
+      // ⌘K first, and from anywhere at all - including a field.
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
+        e.preventDefault();
+        act.current.openPalette();
+        return;
+      }
+      if (!on.current) return;
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      if (inField(e.target)) return;
+      if (e.defaultPrevented) return;
+
+      const key = e.key;
+
+      if (chord) {
+        endChord();
+        const target = GO_TO.find((g) => g.key === key);
+        if (target) {
+          e.preventDefault();
+          navigate(target.to);
+        }
+        return;
+      }
+
+      if (key === "g") {
+        chord = true;
+        timer = setTimeout(endChord, CHORD_MS);
+        return;
+      }
+
+      // "?" is Shift+/ on most layouts and a key of its own on some.
+      if (key === "?") {
+        e.preventDefault();
+        act.current.openHelp();
+        return;
+      }
+      if (key === "[") {
+        e.preventDefault();
+        act.current.toggleSidebar();
+        return;
+      }
+      if (key === "]") {
+        e.preventDefault();
+        act.current.toggleDetail();
+        return;
+      }
+      if (key === "j" || key === "k") {
+        if (moveListFocus(key === "j" ? 1 : -1)) e.preventDefault();
+        return;
+      }
+    };
+
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      if (timer) clearTimeout(timer);
+    };
+  }, [navigate]);
+}
+
+function Cap({ children }: { children: React.ReactNode }) {
+  return (
+    <kbd className="mono inline-flex min-w-5 items-center justify-center rounded-[4px] border px-1 py-px border-line-strong text-ink">
+      {children}
+    </kbd>
+  );
+}
+
+export function ShortcutsSheet({
+  open,
+  onClose,
+}: {
+  open: boolean;
+  onClose: () => void;
+}) {
+  return (
+    <Modal
+      open={open}
+      onClose={onClose}
+      label="Keyboard shortcuts"
+      width="min(560px,92vw)"
+    >
+      <>
+        <div className="flex shrink-0 items-center gap-2 border-b px-4 py-2.5 border-line">
+          <span className="label">keyboard</span>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close (Esc)"
+            title="Esc"
+            className="ml-auto rounded-control p-1 text-muted t-micro transition-colors hover:bg-surface hover:text-ink"
+          >
+            <X size={16} aria-hidden />
+          </button>
+        </div>
+
+        <div className="flex-1 overflow-y-auto px-4 py-3">
+          {SHORTCUT_GROUPS.map((group) => (
+            <section key={group.group} className="mb-4 last:mb-0">
+              <div className="label mb-1.5">{group.group}</div>
+              <ul>
+                {group.items.map((item) => (
+                  <li
+                    key={item.keys.join("+")}
+                    className="flex items-baseline gap-3 py-1"
+                  >
+                    <span className="flex shrink-0 items-center gap-1">
+                      {item.keys.map((k, i) => (
+                        <Cap key={`${k}-${i}`}>{k}</Cap>
+                      ))}
+                    </span>
+                    <span className="text-muted">{item.what}</span>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+          <p className="meta border-t pt-3 border-line">
+            none of these fire while a text field has focus — ⌘K is the one
+            exception, because that is what a field is for
+          </p>
+        </div>
+      </>
+    </Modal>
+  );
+}

package/src/app/theme.tsx

@@ -0,0 +1,51 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import type { ReactNode } from "react";
+
+type Theme = "dark" | "light";
+
+interface ThemeCtx {
+  theme: Theme;
+  toggle: () => void;
+}
+
+const Ctx = createContext<ThemeCtx>({ theme: "dark", toggle: () => {} });
+
+const KEY = "portolan.theme";
+
+function initial(): Theme {
+  const stored =
+    typeof localStorage === "undefined" ? null : localStorage.getItem(KEY);
+  if (stored === "light" || stored === "dark") return stored;
+  return "dark";
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState<Theme>(initial);
+
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", theme === "dark");
+    try {
+      localStorage.setItem(KEY, theme);
+    } catch {
+      /* private mode: the toggle still works for this session */
+    }
+  }, [theme]);
+
+  const toggle = useCallback(
+    () => setTheme((t) => (t === "dark" ? "light" : "dark")),
+    [],
+  );
+  const value = useMemo(() => ({ theme, toggle }), [theme, toggle]);
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useTheme(): ThemeCtx {
+  return useContext(Ctx);
+}

package/src/app/title.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { pageTitle } from "./title";
+
+describe("pageTitle", () => {
+  it("puts the page's name before the app's", () => {
+    expect(pageTitle("Orders")).toBe("Orders · portolan");
+  });
+
+  it("falls back to the app's name when the page has none", () => {
+    expect(pageTitle(undefined)).toBe("portolan");
+    expect(pageTitle(null)).toBe("portolan");
+    expect(pageTitle("   ")).toBe("portolan");
+  });
+});

package/src/app/title.ts

@@ -0,0 +1,30 @@
+// The tab's name.
+//
+// Every page used to be called "portolan": twelve tabs open on twelve pages
+// read as twelve copies of one, history was a list of the same word, and a
+// screen reader announced nothing on a route change. The page that knows its
+// own name says it here, and the app's name follows so the tab is still
+// findable among a reader's others.
+
+import { useEffect } from "react";
+
+const APP = "portolan";
+
+/** "Orders · portolan", or the bare app name when a page has no name yet. */
+export function pageTitle(name: string | null | undefined): string {
+  const trimmed = name?.trim();
+  return trimmed ? `${trimmed} · ${APP}` : APP;
+}
+
+/**
+ * Sets the document title while the caller is mounted, and hands it back on
+ * the way out so a page that sets none is not called by the last one that did.
+ */
+export function useDocumentTitle(name: string | null | undefined): void {
+  useEffect(() => {
+    document.title = pageTitle(name);
+    return () => {
+      document.title = APP;
+    };
+  }, [name]);
+}

package/src/app/toast.tsx

@@ -0,0 +1,59 @@
+// One line, bottom left, gone in four seconds.
+//
+// The app has exactly one thing to say this way: that a pin pushed another pin
+// out. It is not an error and it is not a page, but it must not be silent
+// either - a reader who watches their oldest pin vanish with no word learns
+// that the pin list loses things at random.
+
+import { useEffect } from "react";
+import { create } from "zustand";
+import { AnimatePresence, m, rise } from "../lib/motion";
+
+interface ToastState {
+  message: string | null;
+  /** Bumped per call, so the same message twice restarts the timer. */
+  nonce: number;
+  say: (message: string) => void;
+  clear: () => void;
+}
+
+export const useToastStore = create<ToastState>()((set) => ({
+  message: null,
+  nonce: 0,
+  say: (message) => set((s) => ({ message, nonce: s.nonce + 1 })),
+  clear: () => set({ message: null }),
+}));
+
+const SHOWN_MS = 4000;
+
+export function Toaster() {
+  const message = useToastStore((s) => s.message);
+  const nonce = useToastStore((s) => s.nonce);
+  const clear = useToastStore((s) => s.clear);
+
+  useEffect(() => {
+    if (!message) return;
+    const timer = setTimeout(clear, SHOWN_MS);
+    return () => clearTimeout(timer);
+  }, [message, nonce, clear]);
+
+  // It rises in and sinks out. A second message while one is up swaps the
+  // text in place: the box is the same box, only its line changed.
+  return (
+    <AnimatePresence>
+      {message && (
+        <m.div
+          {...rise}
+          role="status"
+          aria-live="polite"
+          /* Bottom RIGHT, not left: the foot of the sidebar is where Problems
+             and the build line are pinned, and a message that covers them for
+             four seconds hides the one row that promised never to leave. */
+          className="mono pointer-events-none fixed right-4 bottom-4 z-50 max-w-80 rounded-control border px-3 py-2 shadow-md border-line bg-canvas text-ink"
+        >
+          {message}
+        </m.div>
+      )}
+    </AnimatePresence>
+  );
+}

package/src/app/tree-keys.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { parentOf, treeKey } from "./tree-keys";
+import type { TreeRow } from "./tree-keys";
+
+// shop (open)
+//   oms (open)
+//     Order (closed)
+//     Cart (leaf)
+//   billing (closed)
+// auth (closed)
+const rows: TreeRow[] = [
+  { depth: 0, open: true },
+  { depth: 1, open: true },
+  { depth: 2, open: false },
+  { depth: 2, open: null },
+  { depth: 1, open: false },
+  { depth: 0, open: false },
+];
+
+describe("parentOf", () => {
+  it("is the nearest shallower row above", () => {
+    expect(parentOf(rows, 3)).toBe(1);
+    expect(parentOf(rows, 4)).toBe(0);
+    expect(parentOf(rows, 1)).toBe(0);
+  });
+
+  it("is -1 at the top level", () => {
+    expect(parentOf(rows, 0)).toBe(-1);
+    expect(parentOf(rows, 5)).toBe(-1);
+  });
+});
+
+describe("treeKey", () => {
+  it("walks down and up, and stops at the ends", () => {
+    expect(treeKey(rows, 0, "ArrowDown")).toEqual({ type: "focus", index: 1 });
+    expect(treeKey(rows, 5, "ArrowDown")).toEqual({ type: "focus", index: 5 });
+    expect(treeKey(rows, 3, "ArrowUp")).toEqual({ type: "focus", index: 2 });
+    expect(treeKey(rows, 0, "ArrowUp")).toEqual({ type: "focus", index: 0 });
+  });
+
+  it("enters the tree at either end when nothing is focused", () => {
+    expect(treeKey(rows, -1, "ArrowDown")).toEqual({ type: "focus", index: 0 });
+    expect(treeKey(rows, -1, "ArrowUp")).toEqual({ type: "focus", index: 5 });
+    expect(treeKey(rows, -1, "ArrowRight")).toBeNull();
+    expect(treeKey(rows, -1, "ArrowLeft")).toBeNull();
+  });
+
+  it("jumps to the first and last row", () => {
+    expect(treeKey(rows, 3, "Home")).toEqual({ type: "focus", index: 0 });
+    expect(treeKey(rows, 3, "End")).toEqual({ type: "focus", index: 5 });
+  });
+
+  it("opens a closed branch, then steps into it", () => {
+    expect(treeKey(rows, 2, "ArrowRight")).toEqual({ type: "toggle", index: 2 });
+    expect(treeKey(rows, 1, "ArrowRight")).toEqual({ type: "focus", index: 2 });
+  });
+
+  it("does nothing on a leaf, or on an open branch with no children", () => {
+    expect(treeKey(rows, 3, "ArrowRight")).toBeNull();
+    const childless: TreeRow[] = [{ depth: 0, open: true }, { depth: 0, open: null }];
+    expect(treeKey(childless, 0, "ArrowRight")).toBeNull();
+  });
+
+  it("closes an open branch, and goes up from anything else", () => {
+    expect(treeKey(rows, 1, "ArrowLeft")).toEqual({ type: "toggle", index: 1 });
+    expect(treeKey(rows, 3, "ArrowLeft")).toEqual({ type: "focus", index: 1 });
+    expect(treeKey(rows, 2, "ArrowLeft")).toEqual({ type: "focus", index: 1 });
+    expect(treeKey(rows, 4, "ArrowLeft")).toEqual({ type: "focus", index: 0 });
+  });
+
+  it("does nothing going up from the top level, or on an empty tree", () => {
+    expect(treeKey(rows, 5, "ArrowLeft")).toBeNull();
+    expect(treeKey([], -1, "ArrowDown")).toBeNull();
+  });
+
+  it("ignores keys it does not own", () => {
+    expect(treeKey(rows, 1, "Enter")).toBeNull();
+    expect(treeKey(rows, 1, "j")).toBeNull();
+  });
+});

package/src/app/tree-keys.ts

@@ -0,0 +1,87 @@
+// The arrow keys in the catalog tree, as a function of the rows on screen.
+//
+// j and k already walk the tree the way they walk every list, but a tree is
+// more than a list: a branch opens and closes, and a reader on a leaf wants
+// the branch it hangs from. This is the tree's own grammar - the one every
+// file browser and outliner taught - and it is decided here, on a description
+// of the rows, so the Sidebar has only to describe its rows and carry out
+// the answer.
+//
+//   ↓ ↑     the next or previous row, whatever depth it is at
+//   →       open a closed branch; on an open one, step into its first child
+//   ←       close an open branch; on anything else, go up to the parent
+//   Home    the first row
+//   End     the last row
+
+export interface TreeRow {
+  depth: number;
+  /** true or false for a branch; null for a leaf, which has nothing to open. */
+  open: boolean | null;
+}
+
+export type TreeMove =
+  | { type: "focus"; index: number }
+  | { type: "toggle"; index: number };
+
+export const TREE_KEYS = new Set([
+  "ArrowDown",
+  "ArrowUp",
+  "ArrowRight",
+  "ArrowLeft",
+  "Home",
+  "End",
+]);
+
+/** The nearest row above `at` that is shallower than it: the parent. */
+export function parentOf(rows: readonly TreeRow[], at: number): number {
+  const depth = rows[at]?.depth ?? 0;
+  for (let i = at - 1; i >= 0; i--) {
+    if (rows[i]!.depth < depth) return i;
+  }
+  return -1;
+}
+
+/**
+ * What `key` does when the reader is on row `at` (or on none, when `at` is
+ * -1) of `rows`, or null when the key does nothing there - so the caller can
+ * leave the event alone and let the page scroll.
+ */
+export function treeKey(
+  rows: readonly TreeRow[],
+  at: number,
+  key: string,
+): TreeMove | null {
+  const last = rows.length - 1;
+  if (last < 0) return null;
+
+  switch (key) {
+    case "ArrowDown":
+      return { type: "focus", index: at < 0 ? 0 : Math.min(last, at + 1) };
+    case "ArrowUp":
+      return { type: "focus", index: at < 0 ? last : Math.max(0, at - 1) };
+    case "Home":
+      return { type: "focus", index: 0 };
+    case "End":
+      return { type: "focus", index: last };
+  }
+
+  const row = rows[at];
+  if (!row) return null;
+
+  if (key === "ArrowRight") {
+    if (row.open === false) return { type: "toggle", index: at };
+    const next = rows[at + 1];
+    if (row.open === true && next && next.depth > row.depth) {
+      return { type: "focus", index: at + 1 };
+    }
+    return null;
+  }
+
+  if (key === "ArrowLeft") {
+    if (row.open === true) return { type: "toggle", index: at };
+    const parent = parentOf(rows, at);
+    return parent >= 0 ? { type: "focus", index: parent } : null;
+  }
+
+  return null;
+}

package/src/app/ui-store.ts

@@ -0,0 +1,52 @@
+// Shell state that more than one place has to agree about.
+//
+// Two flags, and both exist because a keystroke fired at the window has to
+// reach a panel rendered several routes deep. `detailHidden` is the reader
+// saying "not now" to the detail rail without giving up their selection;
+// `drawer` is the catalog tree, below the narrow breakpoint, where it is an
+// overlay rather than a pane.
+
+import { create } from "zustand";
+import { readZebra, writeZebra } from "../table/persist";
+
+interface UiState {
+  /** True while "]" has folded the detail rail away. Selection is untouched. */
+  detailHidden: boolean;
+  toggleDetail: () => void;
+  setDetailHidden: (hidden: boolean) => void;
+  /** Narrow layouts only: the catalog tree, open over the page. */
+  drawer: boolean;
+  setDrawer: (open: boolean) => void;
+  toggleDrawer: () => void;
+  /**
+   * Bumped by "reveal in tree". The tree follows the selection on its own; what
+   * it cannot do is give itself back the width it was collapsed out of, so the
+   * shell watches this counter and opens the pane - or the drawer - around it.
+   */
+  revealNonce: number;
+  requestReveal: () => void;
+  /**
+   * Zebra striping, for every table at once. It is a statement about how the
+   * reader wants rows separated, not about the table they happen to be
+   * looking at, so it is one flag and it outlives the session.
+   */
+  zebra: boolean;
+  toggleZebra: () => void;
+}
+
+export const useUiStore = create<UiState>()((set) => ({
+  detailHidden: false,
+  toggleDetail: () => set((s) => ({ detailHidden: !s.detailHidden })),
+  setDetailHidden: (hidden) => set({ detailHidden: hidden }),
+  drawer: false,
+  setDrawer: (open) => set({ drawer: open }),
+  toggleDrawer: () => set((s) => ({ drawer: !s.drawer })),
+  revealNonce: 0,
+  requestReveal: () => set((s) => ({ revealNonce: s.revealNonce + 1 })),
+  zebra: readZebra(),
+  toggleZebra: () =>
+    set((s) => {
+      writeZebra(!s.zebra);
+      return { zebra: !s.zebra };
+    }),
+}));