yamlover 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamlover",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Browse a yamlover tree in the web: npx yamlover <root> serves a React SPA over a directory.",
   "type": "module",
   "license": "MIT",

package/src/client/App.tsx

@@ -3,7 +3,7 @@ import { fetchInfo, fetchTasks, fetchTree, PasteResult, TaskInfo, TreeNode } fro
 import { Tree } from "./Tree";
 import { TaskStrip } from "./TaskStrip";
 import { NodeView, Format, FORMATS, DEFAULT_FORMAT } from "./NodeView";
-import { rendererName } from "./renderers/registry";
+import { rendererName, tocView } from "./renderers/registry";
 
 const isStandardFormat = (f: Format) => (FORMATS as string[]).includes(f);
 import { crumbs, formatFromUrl, isAncestorPath, pathFromUrl, segsToStr, strToSegs, writeUrl } from "./paths";
@@ -66,6 +66,24 @@ function nextToLoad(tree: TreeNode, current: string): string | null {
   return null;
 }
 
+/** The TOC rows in document (pre-order) order, mirroring exactly what `Tree`
+ *  shows — `tocView` applies the same per-renderer unwrap/filter (chapters
+ *  surface subchapters, dirs show children). Used by Ctrl-PgDn/PgUp to step the
+ *  selection to the neighbouring entry. Covers only the LOADED tree: per-branch
+ *  collapse state lives in each `Tree`'s local `open`, not here — but a branch
+ *  starts open once its children are loaded, so loaded ≈ visible in practice;
+ *  deep unloaded branches simply aren't reachable until expanded (lazy load). */
+function flattenToc(tree: TreeNode | null): string[] {
+  if (!tree) return [];
+  const out: string[] = [];
+  const walk = (n: TreeNode) => {
+    out.push(n.path);
+    for (const c of tocView(n).children) walk(c);
+  };
+  walk(tree);
+  return out;
+}
+
 export function App() {
   const [tree, setTree] = useState<TreeNode | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -73,6 +91,7 @@ export function App() {
   const [format, setFormat] = useState<Format>(formatFromUrl(DEFAULT_FORMAT) as Format);
   const [rootLabel, setRootLabel] = useState<string>(""); // CLI ROOT (breadcrumb head)
   const [leftWidth, setLeftWidth] = useState<number>(320);
+  const mainRef = useRef<HTMLElement>(null); // RHS pane — focused on TOC click so the keyboard drives the viewer
 
   // The breadcrumb head is the ROOT given on the command line (blank if omitted).
   useEffect(() => {
@@ -259,6 +278,39 @@ export function App() {
     [format, tree],
   );
 
+  // Selecting a TOC row navigates AND hands keyboard focus to the RHS pane, so
+  // Ctrl-PgDn/PgUp (and plain scroll keys) drive the viewer right after a click.
+  // Scoped to the tree — crumbs and in-content links keep plain `navigate`.
+  const selectFromToc = useCallback(
+    (p: string) => {
+      navigate(p);
+      mainRef.current?.focus();
+    },
+    [navigate],
+  );
+
+  // Ctrl/Alt + Down / Up step the selection to the next / previous TOC entry in
+  // document order (Alt as well as Ctrl because Ctrl+Up/Down is taken by macOS
+  // Mission Control). Attached once; reads live state through refs so the listener
+  // stays stable. `navigate` reveals + scrolls the new row (Tree's selected effect).
+  const navigateRef = useRef(navigate);
+  navigateRef.current = navigate;
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (!(e.ctrlKey || e.altKey) || (e.key !== "ArrowDown" && e.key !== "ArrowUp")) return;
+      const t = e.target as HTMLElement | null;
+      if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
+      const order = flattenToc(treeRef.current);
+      const i = order.indexOf(currentRef.current);
+      if (i < 0) return; // current not in the loaded TOC yet — nothing to step from
+      const next = Math.min(Math.max(i + (e.key === "ArrowDown" ? 1 : -1), 0), order.length - 1);
+      e.preventDefault();
+      if (next !== i) navigateRef.current(order[next]);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
   const changeFormat = useCallback(
     (f: Format) => {
       writeUrl(current, f, true);
@@ -324,7 +376,7 @@ export function App() {
         <nav className="crumbs">
           {crumbs(current, rootLabel).map((c, i) => (
             <span key={c.path}>
-              {i > 0 && <span className="crumb-sep">/</span>}
+              {i > 0 && <span className="crumb-sep">:</span>}
               <a
                 className="crumb"
                 href={c.path}
@@ -353,7 +405,7 @@ export function App() {
             }
             if (error) return <div className="error">{error}</div>;
             if (!tree) return <div className="loading">loading…</div>;
-            return <Tree node={tree} current={current} onSelect={navigate} onLoadChildren={loadChildren} />;
+            return <Tree node={tree} current={current} onSelect={selectFromToc} onLoadChildren={loadChildren} />;
           })()}
         </aside>
         <div
@@ -363,7 +415,7 @@ export function App() {
             document.body.style.userSelect = "none";
           }}
         />
-        <main className="pane right">
+        <main className="pane right" ref={mainRef} tabIndex={-1}>
           <NodeView path={current} format={format} refreshSignal={refreshSignal} onFormat={changeFormat} onNavigate={navigate} onContentChanged={onContentChanged} onOpenUploaded={onOpenUploaded} />
         </main>
       </div>

package/src/client/renderers/djvu.tsx

@@ -67,6 +67,13 @@ export function DjvuView({ node }: { node: NodeJson }) {
   pagedRef.current = paged;
   useLayoutEffect(() => { paged.restoreAnchor(); }, [zoom]); // eslint-disable-line react-hooks/exhaustive-deps
 
+  // Focus the `.filedjvu` scroller on mount so arrows / space / PageUp-Down scroll the document
+  // natively (it's a nested scroller the focused RHS pane can't reach). Skip when chunk-embedded.
+  useEffect(() => {
+    const el = ref.current;
+    if (el && !el.closest(".chunk-body")) el.focus({ preventScroll: true });
+  }, []);
+
   // Track the pane width so a page fits but is capped (≤1000px) like the PDF viewer.
   useLayoutEffect(() => {
     const el = ref.current;
@@ -205,7 +212,7 @@ export function DjvuView({ node }: { node: NodeJson }) {
   if (error) return <div className="error">djvu: {error}</div>;
   return (
     <>
-      <div className="filedjvu yo-zoomable" ref={ref} onMouseUp={onMouseUp}>
+      <div className="filedjvu yo-zoomable" ref={ref} tabIndex={0} onMouseUp={onMouseUp}>
         {count === 0 && <div className="loading">opening djvu…</div>}
         {width > 0 &&
           Array.from({ length: count }, (_, i) => {

package/src/client/renderers/explorer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { NodeJson, fetchTagged } from "../api";
 import { asLink, Link } from "../render";
 import { typeIcon } from "../icons";
@@ -117,12 +117,46 @@ function isDocFormat(f?: string | null): boolean {
   return !!f && (f.includes("/") || f.startsWith("x-yamlover-"));
 }
 
-function Item({ it, onNavigate }: { it: ExplorerItem; onNavigate: (path: string) => void }) {
+/** The grid item to move to from `cur` for an arrow key. Left/Right step in reading
+ *  order; Up/Down pick the nearest item in the adjacent row, preferring the same
+ *  column — measured from live geometry, so it's correct for the wrapping flex grid
+ *  (variable columns, a short last row) without knowing the column count. */
+function arrowTarget(els: (HTMLElement | null)[], cur: number, key: string, count: number): number {
+  if (key === "ArrowRight") return Math.min(cur + 1, count - 1);
+  if (key === "ArrowLeft") return Math.max(cur - 1, 0);
+  if (key === "Home") return 0;
+  if (key === "End") return count - 1;
+  const a = els[cur];
+  if (!a) return cur;
+  const r = a.getBoundingClientRect();
+  const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+  const down = key === "ArrowDown";
+  let best = cur, bestScore = Infinity;
+  for (let i = 0; i < count; i++) {
+    const el = els[i];
+    if (!el || i === cur) continue;
+    const ri = el.getBoundingClientRect();
+    const ix = ri.left + ri.width / 2, iy = ri.top + ri.height / 2;
+    if (down ? iy <= cy + 1 : iy >= cy - 1) continue; // must lie in the arrow's direction
+    const score = Math.abs(ix - cx) * 2 + Math.abs(iy - cy); // prefer same column, nearest row
+    if (score < bestScore) { bestScore = score; best = i; }
+  }
+  return best;
+}
+
+function Item({ it, active, setRef, onFocus, onNavigate }: {
+  it: ExplorerItem;
+  active: boolean;
+  setRef: (el: HTMLElement | null) => void;
+  onFocus: () => void;
+  onNavigate: (path: string) => void;
+}) {
   const link = it.link;
+  const tabIndex = active ? 0 : -1; // roving tabindex: only the selected item is in the tab order
   if (!link) {
     // not a marker (unexpected at depth 1) — an inert label, no navigation
     return (
-      <span className="dirview-item">
+      <span className="dirview-item" ref={setRef} tabIndex={tabIndex} onFocus={onFocus}>
         <span className="dirview-icon t-bin">•</span>
         <span className="dirview-label">{it.key}: {scalarText(it.raw)}</span>
       </span>
@@ -147,6 +181,9 @@ function Item({ it, onNavigate }: { it: ExplorerItem; onNavigate: (path: string)
       className={"dirview-item" + (it.up ? " dirview-up" : "")}
       href={link.path}
       title={displayPath(link.path)}
+      ref={setRef}
+      tabIndex={tabIndex}
+      onFocus={onFocus}
       onClick={(e) => {
         e.preventDefault();
         onNavigate(link.path);
@@ -189,6 +226,43 @@ export function ExplorerView({ node, onNavigate }: { node: NodeJson; onNavigate:
   }
   const items = [...ups, ...members];
 
+  // Roving keyboard focus over the grid: plain arrows walk the icons, Enter opens the
+  // selected one. The item elements are tracked by index for the geometry-based row moves.
+  const gridRef = useRef<HTMLDivElement>(null);
+  const itemEls = useRef<(HTMLElement | null)[]>([]);
+  itemEls.current.length = items.length; // drop stale refs when the member list shrinks
+  const [active, setActive] = useState(0);
+  useEffect(() => {
+    if (active > items.length - 1) setActive(Math.max(0, items.length - 1));
+  }, [items.length, active]);
+
+  // On navigating to a new directory, reset the selection and re-arm autofocus (this
+  // component is reused across nodes, not remounted, so the flag must follow `node.path`).
+  const wantFocus = useRef(true);
+  useEffect(() => { setActive(0); wantFocus.current = true; }, [node.path]);
+  // Focus the first item once the grid has members (a tag's load async), so arrows work right
+  // after navigating here (the RHS pane handed us focus) — once per node, and never when
+  // embedded as a chapter chunk (several grids would fight over focus).
+  useEffect(() => {
+    if (!wantFocus.current || !items.length) return;
+    wantFocus.current = false;
+    if (gridRef.current?.closest(".chunk-body")) return; // embedded — don't steal focus
+    itemEls.current[0]?.focus({ preventScroll: true });
+  }, [items.length, node.path]);
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    if (e.ctrlKey || e.altKey || e.metaKey || !items.length) return; // Ctrl/Alt+arrows = TOC nav (App)
+    if (e.key === "Enter") {
+      const link = items[active]?.link;
+      if (link) { e.preventDefault(); onNavigate(link.path); }
+      return;
+    }
+    if (!/^(Arrow(Up|Down|Left|Right)|Home|End)$/.test(e.key)) return;
+    e.preventDefault(); // don't also scroll the pane
+    const next = arrowTarget(itemEls.current, active, e.key, items.length);
+    if (next !== active) { setActive(next); itemEls.current[next]?.focus(); }
+  };
+
   // a tag page's description is its BODY (the header bar already names the node)
   const desc = (isTag ? tagBody(node.value) : null) ?? node.description;
   return (
@@ -198,9 +272,20 @@ export function ExplorerView({ node, onNavigate }: { node: NodeJson; onNavigate:
           <p className="tagdesc">{desc}</p>
         </div>
       )}
-      <div className={"dirview" + (explorerViewMode() === "large" ? " dirview-lg" : "")}>
+      <div
+        ref={gridRef}
+        className={"dirview" + (explorerViewMode() === "large" ? " dirview-lg" : "")}
+        onKeyDown={onKeyDown}
+      >
         {items.map((it, i) => (
-          <Item key={`${it.up ? "^" : ""}${it.link?.path ?? it.key}#${i}`} it={it} onNavigate={onNavigate} />
+          <Item
+            key={`${it.up ? "^" : ""}${it.link?.path ?? it.key}#${i}`}
+            it={it}
+            active={i === active}
+            setRef={(el) => { itemEls.current[i] = el; }}
+            onFocus={() => setActive(i)}
+            onNavigate={onNavigate}
+          />
         ))}
         {items.length === 0 && <span className="dirview-empty">empty</span>}
       </div>

package/src/client/renderers/pdf.tsx

@@ -96,6 +96,14 @@ export function PdfView({ node }: { node: NodeJson }) {
   // After a zoom COMMIT reflows the pages, restore the captured reading position.
   useLayoutEffect(() => { paged.restoreAnchor(); }, [zoom]); // eslint-disable-line react-hooks/exhaustive-deps
 
+  // The `.filepdf` scroller is its OWN scroll container nested in the (focused) RHS pane, so the
+  // pane's focus can't drive it — focus it on mount so arrows / space / PageUp-Down / Home-End
+  // scroll the document natively. Skip when embedded as a chapter chunk (several would fight + jump).
+  useEffect(() => {
+    const el = ref.current;
+    if (el && !el.closest(".chunk-body")) el.focus({ preventScroll: true });
+  }, []);
+
   // Track the pane width so pages re-flow on resize.
   useLayoutEffect(() => {
     const el = ref.current;
@@ -226,7 +234,7 @@ export function PdfView({ node }: { node: NodeJson }) {
 
   return (
     <>
-      <div className="filepdf yo-zoomable" ref={ref} onMouseUp={onMouseUp}>
+      <div className="filepdf yo-zoomable" ref={ref} tabIndex={0} onMouseUp={onMouseUp}>
         <Document
           file={blobUrl(node.path)}
           onLoadSuccess={({ numPages }) => setPages(numPages)}

package/src/client/styles.css

@@ -148,6 +148,10 @@ body {
   flex: 1 1 auto;
   padding: 14px 18px;
 }
+/* programmatically focused on TOC click (so the keyboard drives the viewer) — no focus ring */
+.right:focus {
+  outline: none;
+}
 .splitter {
   flex: 0 0 5px;
   cursor: col-resize;
@@ -519,6 +523,11 @@ a.chunk-index:hover {
   height: calc(100vh - 160px);
   min-height: 360px;
 }
+/* focused on mount so the keyboard scrolls the document — no focus ring on the scroller */
+.filepdf:focus,
+.filedjvu:focus {
+  outline: none;
+}
 .fileimage {
   /* keep the image's own aspect ratio — never stretch (007) */
   max-width: 100%;
@@ -1080,6 +1089,12 @@ mark.yo-annotation {
 .dirview-item:hover {
   background: var(--panel);
 }
+/* keyboard selection (roving focus — arrows walk, Enter opens) */
+.dirview-item:focus {
+  outline: none;
+  background: var(--panel);
+  box-shadow: 0 0 0 2px var(--accent) inset;
+}
 .dirview-icon {
   flex: none;
   width: 22px;