+
-
) : (
-
-
+
-
+
{skill.categoryLabel}
+
{/* A real link so it can be opened in a new tab and read by
assistive tech, intercepted only where a preview panel exists
to update instead. */}
@@ -145,45 +121,55 @@ function SkillCard({
e.preventDefault();
onSelect();
}}
- className="rounded-sm outline-none after:absolute after:inset-0 after:rounded-[14px] after:content-[''] focus-visible:underline focus-visible:decoration-2 focus-visible:underline-offset-4"
+ className="rounded-sm outline-none after:absolute after:inset-0 after:rounded-[12px] after:content-[''] focus-visible:underline focus-visible:decoration-2 focus-visible:underline-offset-4"
>
{skill.handle}
-
{skill.title}
+{skill.title}
- {skill.summary || skill.description} -
+ {/* Handle, title, then what the skill is for — the same three facts in + the same order a node on the map gives, so the two surfaces read as + one product. The trigger phrase becomes the secondary line it always + was. */} + {skill.purpose && ( +{skill.purpose}
+ )} -
- {/* One phrase, not the whole trigger list: the card is for recognising
- a skill, and version, file and reference counts moved to the detail
- surface where someone is actually comparing them. */}
-
+ (null);
const [recent, setRecent] = useState([]);
const [initialised, setInitialised] = useState(false);
+ const [filtersOpen, setFiltersOpen] = useState(false);
const inputRef = useRef(null);
const initialDeepLinkSkill = useRef(null);
@@ -330,6 +317,33 @@ export function SkillCatalog({
const filtered = query.trim() !== "" || category !== ALL || flags.length > 0;
+ // Default view only: once someone searches, filters by category or sorts,
+ // grouping by category would fight the ordering they asked for.
+ const grouped = useMemo(() => {
+ if (query.trim() !== "" || category !== ALL || sort !== "name") return null;
+ const groups = new Map();
+ for (const skill of results) {
+ const list = groups.get(skill.categoryLabel) ?? [];
+ list.push(skill);
+ groups.set(skill.categoryLabel, list);
+ }
+ return Array.from(groups.entries()).sort(([a], [b]) => a.localeCompare(b));
+ }, [results, query, category, sort]);
+
+ const activeFilters = [
+ ...(category !== ALL
+ ? [{ key: `category:${category}`, label: categories.find((c) => c.id === category)?.label ?? category, clear: () => setCategory(ALL) }]
+ : []),
+ ...flags.map((flag) => ({
+ key: `flag:${flag}`,
+ label: FLAGS.find((f) => f.value === flag)?.label ?? flag,
+ clear: () => toggleFlag(flag),
+ })),
+ ...(sort !== "name"
+ ? [{ key: "sort", label: SORTS.find((o) => o.value === sort)?.label ?? sort, clear: () => setSort("name") }]
+ : []),
+ ];
+
const controls = (
+ {filtersOpen && (
+
setCategory(ALL)}>
All {skills.length}
@@ -399,13 +440,24 @@ export function SkillCatalog({
{c.label} {c.count}
))}
-
- {FLAGS.map((flag) => (
- toggleFlag(flag.value)}>
- {flag.label}
-
- ))}
+
+ {activeFilters.length > 0 && (
+
);
@@ -429,8 +481,12 @@ export function SkillCatalog({
+
{firstTrigger ? (
<>
- Use when
+ Ask with
“{firstTrigger}”
{restTriggers.length > 0 && (
- +{restTriggers.length}
+ +{restTriggers.length}
)}
- ) : null}
+ ) : (
+ No trigger phrase
+ )}
- Open workspace
-
);
@@ -208,6 +194,7 @@ export function SkillCatalog({
const [selectedId, setSelectedId] = useState
@@ -370,26 +384,53 @@ export function SkillCatalog({
)}
-
+ Filters
+
+
+
+ {FLAGS.map((flag) => (
+ toggleFlag(flag.value)}>
+ {flag.label}
+
+ ))}
+
+ )}
+
+ {activeFilters.map((filter) => (
+
+ ))}
+
+ )}
- {results.map((skill) => (
+ (() => {
+ // Two columns wherever the inspector is absent. A third column has nowhere
+ // to live: the inspector takes over at 1440, so the only band wide enough
+ // for three is the one the split already owns.
+ const gridClass = splitView ? "flex flex-col gap-2.5" : "grid gap-2.5 sm:grid-cols-2";
+ const card = (skill: SkillSummary) => (
setSelectedId(skill.id)}
/>
- ))}
-
+ );
+
+ // Category headings are the default organisation: at 34 skills across
+ // nine groups, category is the first useful cut, and a flat
+ // alphabetical wall makes the reader do that grouping themselves.
+ if (grouped) {
+ return (
+
+ {grouped.map(([label, group]) => (
+
+
+ ))}
+
+ );
+ }
+
+ return + {label} + [{group.length}] +
+{group.map(card)}
+ {results.map(card)}
;
+ })()
);
return (
diff --git a/components/skills/skill-detail.tsx b/components/skills/skill-detail.tsx
index 6f0238f..9e629a0 100644
--- a/components/skills/skill-detail.tsx
+++ b/components/skills/skill-detail.tsx
@@ -200,17 +200,19 @@ export function SkillDetail({
className="grid gap-5 rounded-[14px] border border-[var(--border-subtle)] bg-[var(--glass-surface)] p-4 sm:grid-cols-2"
aria-label="Related skills"
>
+ {/* Same two words the map and the browse list use, so a reader who
+ learned the direction on one surface does not relearn it here. */}
+ {data.label}
+ {/* Tertiary, not disabled: the count is information, and on the light
+ palette --text-disabled measures 2.54:1 against the canvas. */}
+ [{data.count}]
+
+ );
+}
+
+function SkillFlowNodeCard({ id, data }: NodeProps data.onSelect(id)}
+ onKeyDown={(e) => {
+ if (e.key === "Enter" || e.key === " ") {
+ e.preventDefault();
+ data.onSelect(id);
+ }
+ }}
+ style={{
+ width: SKILL_NODE_SIZE.width,
+ height: SKILL_NODE_SIZE.height,
+ // Inline, not a Tailwind arbitrary value: a color-mix() with commas
+ // inside shadow-[...] does not survive the class parser, and it failed
+ // silently — the pin lost its halo and became indistinguishable from a
+ // hover, which is the one distinction this component has to keep.
+ boxShadow: selected
+ ? "0 0 0 4px color-mix(in srgb, var(--skill-node-active) 24%, transparent)"
+ : undefined,
+ }}
+ className={`flex cursor-pointer flex-col justify-center gap-0.5 rounded-[10px] border px-3.5 text-left outline-none transition-opacity focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--skill-node-active)] ${
+ selected
+ ? "border-[var(--skill-node-active)] bg-[var(--bg-surface)]"
+ : traced
+ ? "border-[var(--skill-node-active)] bg-[var(--bg-surface)]"
+ : related === "out"
+ ? "border-[var(--skill-edge-out)] bg-[var(--bg-surface)]"
+ : related === "in"
+ ? "border-[var(--skill-edge-in)] bg-[var(--bg-surface)]"
+ : "border-[var(--border-subtle)] bg-[var(--bg-surface)]"
+ } ${dimmed ? "opacity-30" : "opacity-100"}`}
+ >
+ {/* Edges need anchors to attach to. They carry no affordance of their
+ own: connecting is disabled, so these exist purely as geometry. */}
+
+ );
+}
+
+const NODE_TYPES: NodeTypes = { skill: SkillFlowNodeCard, lane: LaneHeading };
+
+export function SkillGraphCanvas({
+ nodes,
+ edges,
+ lanes,
+ laneWidth,
+ graphHeight,
+ selectedId,
+ hoveredId,
+ initialLane,
+ positions,
+ showMiniMap,
+ miniMapSide = "left",
+ rightInset = 0,
+ reduceMotion,
+ onSelect,
+ onHover,
+ onPositionsChange,
+ onReady,
+}: {
+ nodes: PositionedSkillNode[];
+ edges: SkillEdge[];
+ lanes: SkillGraphLane[];
+ laneWidth: number;
+ graphHeight: number;
+ selectedId: string | null;
+ hoveredId: string | null;
+ /** a group the reader asked for before this canvas existed */
+ initialLane?: string | null;
+ /** dragged overrides on top of the canonical layout */
+ positions: Record
+
+ nodes={flowNodes}
+ edges={flowEdges}
+ nodeTypes={NODE_TYPES}
+ onInit={(i) => {
+ instance.current = i;
+ if (framed.current) return;
+ framed.current = true;
+ // The map opens readable, not fitted. Fitting eight lanes into a
+ // panel drove every card to roughly a centimetre of unreadable
+ // colour; the frame now starts where the reader is going to look —
+ // the deep-linked skill, or the first lane — and "Fit all" is a
+ // deliberate action rather than the default.
+ // A group asked for from the browse list arrives before this
+ // renderer exists, so it is honoured here rather than through the
+ // imperative call, which would land on an instance that is not yet
+ // holding a viewport.
+ if (initialLaneRef.current) {
+ apiRef.current?.revealLane(initialLaneRef.current);
+ return;
+ }
+ const start = initialSelection.current
+ ? placedRef.current.get(initialSelection.current)
+ : undefined;
+ if (start) {
+ // Clamped like every other framing move: a deep link to a skill in
+ // the first row would otherwise open with a third of the canvas
+ // showing nothing above the map.
+ const box = wrapper.current?.getBoundingClientRect();
+ if (box && box.width > 0) {
+ const frame = clamped(
+ (box.width - rightInsetRef.current) / 2 - (start.x + SKILL_NODE_SIZE.width / 2) * 1.1,
+ box.height / 2 - (start.y + SKILL_NODE_SIZE.height / 2) * 1.1,
+ 1.1,
+ box,
+ );
+ i.setViewport({ ...frame, zoom: 1.1 }, { duration: 0 });
+ }
+ return;
+ }
+ anchorHome();
+ }}
+ onNodeDragStop={handleDragStop}
+ onNodeMouseEnter={(_, node) => {
+ if (node.type === "skill") onHover(node.id);
+ }}
+ onNodeMouseLeave={() => onHover(null)}
+ onPaneClick={() => onSelect("")}
+ /* One focus stop per node, ours, so the accessible name and the
+ Enter/Space handling are the card's rather than the wrapper's. */
+ nodesFocusable={false}
+ edgesFocusable={false}
+ nodesConnectable={false}
+ elementsSelectable={false}
+ proOptions={{ hideAttribution: true }}
+ minZoom={MIN_ZOOM}
+ maxZoom={MAX_ZOOM}
+ >
+
+ );
+}
+
+export default SkillGraphCanvas;
diff --git a/components/skills/skill-graph-view.tsx b/components/skills/skill-graph-view.tsx
index bd62f5a..0a330f3 100644
--- a/components/skills/skill-graph-view.tsx
+++ b/components/skills/skill-graph-view.tsx
@@ -1,368 +1,852 @@
"use client";
+import dynamic from "next/dynamic";
import Link from "next/link";
-import { useEffect, useMemo, useState } from "react";
-import { AnimatePresence, motion, useReducedMotion } from "motion/react";
-import { ArrowDownLeft, ArrowUpRight, ExternalLink, List, Share2, X } from "lucide-react";
-import type { SkillGraph } from "@/lib/skill-graph";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useReducedMotion } from "motion/react";
+import {
+ ArrowDownLeft,
+ ArrowUpRight,
+ HelpCircle,
+ List,
+ Maximize2,
+ Minimize2,
+ Minus,
+ Plus,
+ RotateCcw,
+ Scan,
+ Share2,
+ X,
+} from "lucide-react";
+import type { SkillGraph, SkillNode } from "@/lib/skill-graph";
+import {
+ clearStoredLayout,
+ layoutSkillGraph,
+ readStoredLayout,
+ writeStoredLayout,
+ type SkillGraphPosition,
+} from "@/lib/skill-graph-layout";
import { normalizeSkillId } from "@/lib/skill-id";
+import { useMediaQuery } from "@/lib/use-media-query";
+import type { SkillCanvasApi } from "./skill-graph-canvas";
-// A circular (chord) layout rather than a force simulation: with 34 nodes and
-// 108 edges a physics layout settles differently on every load, which makes
-// the picture impossible to refer back to. Fixed positions mean "the hub at
-// the top right" stays the hub at the top right, and it needs no animation
-// frame budget next to the fluid background already running on this page.
-
-const SIZE = 900;
-const C = SIZE / 2;
-const R = 310;
-// Read from the shell's tokens so the graph carries meaning in both themes;
-// see the --skill-* block in globals.css.
-const OUT_COLOR = "var(--skill-edge-out)";
-const IN_COLOR = "var(--skill-edge-in)";
-const NODE_COLOR = "var(--skill-node)";
-const NODE_ACTIVE = "var(--skill-node-active)";
-const EDGE_COLOR = "var(--skill-edge)";
-
-type Pt = { x: number; y: number; angle: number };
-
-// Coordinates are rounded before they reach the DOM. Full-precision floats
-// serialize differently on the server and the client (…4313 vs …43124), which
-// React reports as a hydration mismatch on every label in the ring.
-const r2 = (n: number) => Math.round(n * 100) / 100;
+// Three things live here and nowhere else: which view is showing, which skill
+// is selected, and what the URL says about both. The canvas is a renderer it
+// mounts; the inspector is rendered by this component directly, so its content
+// never waits on the canvas or on an animation finishing — the previous
+// version could leave the panel blank behind an exit transition that never
+// completed.
+
+const SkillGraphCanvas = dynamic(
+ () => import("./skill-graph-canvas").then((m) => m.SkillGraphCanvas),
+ {
+ ssr: false,
+ loading: () => (
+
+ Loading the map…
+
+ ),
+ },
+);
+
+export type SkillGraphViewMode = "canvas" | "list";
+
+const CANVAS_MIN_WIDTH = "(min-width: 768px)";
+/** Where a docked inspector still leaves the canvas about three quarters of
+ * the panel. Below it the inspector is a sheet over the map instead. */
+const DOCKED_INSPECTOR = "(min-width: 1280px)";
+const HINT_KEY = "ai-devkit-skill-graph-hint";
+
+function toggleClass(on: boolean) {
+ return `inline-flex h-7 items-center gap-1.5 rounded-[6px] px-2.5 text-[12px] transition-colors ${
+ on
+ ? "bg-[var(--bg-elevated)] font-medium text-[var(--text-primary)]"
+ : "text-[var(--text-tertiary)] hover:text-[var(--text-primary)]"
+ }`;
+}
+
+const actionClass =
+ "inline-flex h-8 items-center gap-1.5 rounded-lg border border-[var(--border-subtle)] bg-[var(--glass-elevated)] px-2.5 text-[12px] text-[var(--text-secondary)] transition-colors hover:border-[var(--border-strong)] hover:text-[var(--text-primary)]";
+
+const iconButtonClass =
+ "inline-flex h-8 w-8 items-center justify-center rounded-lg border border-[var(--border-subtle)] bg-[var(--glass-elevated)] text-[var(--text-secondary)] transition-colors hover:border-[var(--border-strong)] hover:text-[var(--text-primary)]";
+
+function RelationGroup({
+ title,
+ icon,
+ color,
+ note,
+ ids,
+ byId,
+ onPick,
+}: {
+ title: string;
+ icon?: React.ReactNode;
+ color?: string;
+ note: string;
+ ids: string[];
+ byId: Map rather than a hand-rolled disclosure: the open/closed state, the
+ // keyboard handling and the announced role all come for free, and this panel
+ // has to stay light enough that the map keeps the attention.
+ return (
+ (null);
- const [pinned, setPinned] = useState(null);
- const [view, setView] = useState<"graph" | "list">("graph");
- const [focused, setFocused] = useState(null);
- // Hover traces a different skill without taking the pin away: `active`
- // drives the trace, `pinned` keeps its own marker regardless. Losing the
- // selection the moment the cursor moved made the pin useless.
- const active = hovered ?? pinned;
-
- // A skill page links here as …?focus=delivery-review, so "see what this
- // connects to" lands on that node already traced instead of on 34
- // undifferentiated dots. Read after mount to keep the page static.
+ const reduce = useReducedMotion() ?? false;
+ const wideEnoughForCanvas = useMediaQuery(CANVAS_MIN_WIDTH);
+ const canDockInspector = useMediaQuery(DOCKED_INSPECTOR) === true;
+
+ const [selectedId, setSelectedId] = useState(null);
+ const [hoveredId, setHoveredId] = useState(null);
+ const [requestedView, setRequestedView] = useState(null);
+ const [positions, setPositions] = useState>({});
+ const [initialised, setInitialised] = useState(false);
+ const [focus, setFocus] = useState(false);
+ const [api, setApi] = useState(null);
+ const [hintOpen, setHintOpen] = useState(false);
+ const [pendingLane, setPendingLane] = useState(null);
+ const deepLinkRead = useRef(false);
+ const drawerRef = useRef(null);
+
+ const layout = useMemo(() => layoutSkillGraph(graph.nodes), [graph.nodes]);
+ const byId = useMemo(() => new Map(graph.nodes.map((n) => [n.id, n])), [graph.nodes]);
+
+ // Read once, ever: the sync effect below rewrites the query string, and a
+ // second read would pick up what it just wrote.
useEffect(() => {
+ if (deepLinkRead.current) return;
+ deepLinkRead.current = true;
+
const params = new URLSearchParams(window.location.search);
- const requested = normalizeSkillId(params.get("skill") ?? params.get("focus"));
- if (requested && graph.nodes.some((n) => n.id === requested)) setPinned(requested);
+ const skill = normalizeSkillId(params.get("skill"));
+ if (skill && graph.nodes.some((n) => n.id === skill)) setSelectedId(skill);
+
+ const view = params.get("view");
+ if (view === "canvas" || view === "list") setRequestedView(view);
+ if (params.get("focus") === "canvas") setFocus(true);
+
+ const stored = readStoredLayout();
+ if (stored) setPositions(stored);
+
+ try {
+ if (!sessionStorage.getItem(HINT_KEY)) setHintOpen(true);
+ } catch {
+ // storage unavailable: the hint just does not auto-open
+ }
+ setInitialised(true);
}, [graph.nodes]);
- const { points, byId } = useMemo(() => {
- const points = new Map();
- const n = graph.nodes.length || 1;
- graph.nodes.forEach((node, i) => {
- // start at 12 o'clock so the ordering reads clockwise from the top
- const angle = (i / n) * Math.PI * 2 - Math.PI / 2;
- points.set(node.id, { x: r2(C + Math.cos(angle) * R), y: r2(C + Math.sin(angle) * R), angle });
- });
- return { points, byId: new Map(graph.nodes.map((nd) => [nd.id, nd])) };
- }, [graph]);
-
- const related = useMemo(() => {
- if (!active) return null;
- const out = graph.edges.filter((e) => e.source === active).map((e) => e.target);
- const inc = graph.edges.filter((e) => e.target === active).map((e) => e.source);
- return { out, inc, touching: new Set([...out, ...inc, active]) };
- }, [active, graph.edges]);
-
- const activeNode = active ? byId.get(active) : null;
- const maxDeg = Math.max(...graph.nodes.map((n) => n.inDegree + n.outDegree), 1);
+ // Canvas where there is room for one, list where there is not, and an
+ // explicit ?view= wins on any viewport.
+ const view: SkillGraphViewMode =
+ requestedView ?? (wideEnoughForCanvas === false ? "list" : "canvas");
- return (
-
+
+ );
+}
+
+/**
+ * What the panel says before anything is selected. The old copy described the
+ * gestures — hover to trace, click to pin — which tells a reader how to
+ * operate a thing they have not been given a reason to operate. This one
+ * hands them two ways in: a group, or a skill nothing else depends on.
+ */
+function StartPanel({
+ groups,
+ startingPoints,
+ onJumpToGroup,
+ onPickSkill,
+}: {
+ groups: { category: string; label: string; count: number }[];
+ startingPoints: SkillNode[];
+ onJumpToGroup: (category: string) => void;
+ onPickSkill: (id: string) => void;
+}) {
+ return (
+ + + {icon && {icon}} + {title} + + {note} +
+
+ {ids.length === 0 ? (
+
+ none
+ ) : ( +
+ {ids.map((id) => (
+
+ ))}
+
+ )}
+
+
+ );
+}
export function SkillGraphView({ graph }: { graph: SkillGraph }) {
- const reduce = useReducedMotion();
- const [hovered, setHovered] = useState
+
+
+ Start with a skill
++ Select any skill to see what it uses and what uses it. +
+
+
+
+ {startingPoints.length > 0 && (
+ + Not sure where to begin? Jump to a group. +
+
+ {groups.map((group) => (
+
+ ))}
+
+
+
+ )}
+ + Starting points +
++ Nothing else pulls these in, so they are where a chain begins. +
+
+ {startingPoints.map((node) => (
+
+ ))}
+
+
-
-
-
+ useEffect(() => {
+ if (!initialised || wideEnoughForCanvas === null) return;
+ const params = new URLSearchParams(window.location.search);
+ if (selectedId) params.set("skill", selectedId);
+ else params.delete("skill");
+ if (requestedView) params.set("view", requestedView);
+ else params.delete("view");
+ if (focus) params.set("focus", "canvas");
+ else params.delete("focus");
+ const search = params.toString();
+ window.history.replaceState(null, "", search ? `?${search}` : window.location.pathname);
+ }, [initialised, selectedId, requestedView, focus, wideEnoughForCanvas]);
+
+ // Focus mode is application-level, not the browser's Fullscreen API: it
+ // collapses the shell's own chrome from a single attribute on , so the
+ // canvas grows into the space its ancestors were using without being
+ // unmounted and re-created in a new part of the tree. One canvas, one
+ // viewport, no remount on the way in or out.
+ useEffect(() => {
+ const root = document.documentElement;
+ if (focus) root.setAttribute("data-skills-focus", "");
+ else root.removeAttribute("data-skills-focus");
+ return () => root.removeAttribute("data-skills-focus");
+ }, [focus]);
+
+ const select = useCallback((id: string) => {
+ setSelectedId((current) => (id === "" || current === id ? null : id));
+ }, []);
+
+ const handlePositions = useCallback((next: Record) => {
+ setPositions(next);
+ writeStoredLayout(next);
+ }, []);
+
+ const resetLayout = useCallback(() => {
+ clearStoredLayout();
+ setPositions({});
+ }, []);
+
+ const handleReady = useCallback((next: SkillCanvasApi | null) => setApi(next), []);
+
+ const dismissHint = useCallback(() => {
+ setHintOpen(false);
+ try {
+ sessionStorage.setItem(HINT_KEY, "seen");
+ } catch {
+ // nothing to remember it with
+ }
+ }, []);
+
+ // Keyboard: F toggles focus, R resets the layout, Escape peels one layer at
+ // a time — the open panel first, then focus mode itself.
+ useEffect(() => {
+ const onKey = (e: KeyboardEvent) => {
+ if (e.metaKey || e.ctrlKey || e.altKey) return;
+ const target = e.target as HTMLElement | null;
+ if (
+ target &&
+ (target.tagName === "INPUT" ||
+ target.tagName === "TEXTAREA" ||
+ target.tagName === "SELECT" ||
+ target.isContentEditable)
+ ) {
+ return;
+ }
+
+ if (e.key === "Escape") {
+ if (hintOpen) dismissHint();
+ else if (selectedId) setSelectedId(null);
+ else if (focus) setFocus(false);
+ return;
+ }
+
+ const key = e.key.toLowerCase();
+ if (key === "f" && wideEnoughForCanvas) {
+ e.preventDefault();
+ setFocus((on) => !on);
+ } else if (key === "r" && view === "canvas") {
+ e.preventDefault();
+ resetLayout();
+ }
+ };
+ window.addEventListener("keydown", onKey);
+ return () => window.removeEventListener("keydown", onKey);
+ }, [dismissHint, focus, hintOpen, resetLayout, selectedId, view, wideEnoughForCanvas]);
+
+ // Bring the selection into view without yanking the canvas: the renderer
+ // only moves when the node is off-frame or too small to read.
+ useEffect(() => {
+ if (!api || !selectedId || view !== "canvas") return;
+ api.reveal(selectedId);
+ }, [api, selectedId, view]);
+
+ // The docked rail exists only while something is selected. An empty 300px
+ // panel reading "pick a skill" was taking a third of the canvas at 1280 to
+ // say what the page's own subtitle already says, which is the opposite of
+ // canvas-first.
+ // The rail is always there at 1280 and up outside focus mode. It used to
+ // appear only on selection, which meant the one moment a reader most needs
+ // a way in — before they have clicked anything — was the moment the page
+ // offered them nothing but dots.
+ const dockInspector = canDockInspector && !focus;
+
+ // Wherever the inspector floats over the map rather than sitting beside it,
+ // it gets the workspace drawer's treatment: focus moves in and Tab stays
+ // inside while it is open. Escape is handled by the global handler above.
+ const overlayInspector = selectedId !== null && !dockInspector;
+ /** Where the rail cannot fit, the way in is a strip of chips over the map. */
+ const showStartStrip = selectedId === null && !dockInspector;
+ useEffect(() => {
+ if (!overlayInspector) return;
+ const panel = drawerRef.current;
+ if (!panel) return;
+
+ // Where focus came from, so closing the panel puts it back on the node
+ // rather than dropping it at the top of the document.
+ const returnTo = document.activeElement as HTMLElement | null;
+ panel.querySelector("button, a")?.focus();
+
+ const onKey = (e: KeyboardEvent) => {
+ if (e.key !== "Tab") return;
+ const focusable = panel.querySelectorAll(
+ 'a[href], button:not([disabled]), summary',
+ );
+ if (focusable.length === 0) return;
+ const first = focusable[0];
+ const last = focusable[focusable.length - 1];
+ const active = document.activeElement;
+ if (e.shiftKey && (active === first || !panel.contains(active))) {
+ e.preventDefault();
+ last.focus();
+ } else if (!e.shiftKey && active === last) {
+ e.preventDefault();
+ first.focus();
+ }
+ };
+ window.addEventListener("keydown", onKey);
+ return () => {
+ window.removeEventListener("keydown", onKey);
+ if (returnTo && returnTo.isConnected && document.body.contains(returnTo)) returnTo.focus();
+ };
+ }, [overlayInspector, selectedId]);
+
+ // Skills nothing else pulls in, and that lead somewhere: the honest answer
+ // to "where do I start". A skill with no inbound AND no outbound edges is
+ // not a starting point, it is an orphan, and sending a reader there is the
+ // opposite of help.
+ const startingPoints = useMemo(
+ () =>
+ graph.nodes
+ .filter((n) => n.inDegree === 0 && n.outDegree > 0)
+ .sort((a, b) => b.outDegree - a.outDegree)
+ .slice(0, 4),
+ [graph.nodes],
+ );
+
+ const groups = useMemo(() => {
+ const counts = new Map();
+ for (const node of graph.nodes) {
+ const row = counts.get(node.category) ?? {
+ category: node.category,
+ label: node.categoryLabel,
+ count: 0,
+ };
+ row.count += 1;
+ counts.set(node.category, row);
+ }
+ return Array.from(counts.values()).sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+ }, [graph.nodes]);
+
+ // Asking for a group from the browse list means there is no canvas to move
+ // yet. The request is handed to the renderer as its opening frame instead;
+ // calling the live one would land on an instance that has no viewport, and
+ // the reader would arrive at the top of the map wondering what their click
+ // did.
+ const jumpToGroup = useCallback(
+ (category: string) => {
+ setSelectedId(null);
+ setPendingLane(category);
+ setRequestedView("canvas");
+ api?.revealLane(category);
+ },
+ [api],
+ );
+
+ const selected = selectedId ? (byId.get(selectedId) ?? null) : null;
+ const relations = useMemo(() => {
+ if (!selectedId) return { out: [] as string[], inc: [] as string[] };
+ return {
+ out: graph.edges.filter((e) => e.source === selectedId).map((e) => e.target).sort(),
+ inc: graph.edges.filter((e) => e.target === selectedId).map((e) => e.source).sort(),
+ };
+ }, [graph.edges, selectedId]);
+
+ const inspector = selected ? (
+
+
+ ) : (
+
+
+
+
+
+
+ + {selected.label} +
++ {selected.title} +
+ {/* Category and the one count a reader can act on. The pair of + degree numbers moved into the group headings below, where each + one sits next to the list it describes. */} ++ {selected.categoryLabel} · used by {selected.inDegree}{" "} + {selected.inDegree === 1 ? "skill" : "skills"} +
+
+ {selected.purpose && (
+
+
+ + {selected.purpose}. +
+ )} + {selected.trigger && ( ++ Ask for it with{" "} + “{selected.trigger}” +
+ )} + + {selected.oftenUsedWith.length > 0 && ( +
+
+ Open detail
+
+
+ Open workspace
+
+
+
+
+ );
+ }
+
+ const viewToggle = (
+ No skills were found in this build.
+
+
+
+
+ );
+
+ const canvasActions = view === "canvas" && (
+ <>
+
+
+
+
+
+ );
+
+ const focusToggle = wideEnoughForCanvas ? (
+
+ ) : null;
+
+ const help = (
+
+
+ {hintOpen && (
+
+ );
- {view === "list" ? (
- /* The same relationships without an SVG in the way: every skill is
- a focusable row, and focusing one traces it in the inspector, so
- this graph is navigable by keyboard and by screen reader too. */
-
+
+ )}
+ Select a skill to see what it uses and what uses it.
+Drag to rearrange · Scroll to zoom
++ F focus · R reset ·{" "} + Esc back +
-
- ) : (
- -
- {graph.nodes.map((node) => {
- const on = node.id === active;
- return (
-
- - - - ); - })} -