@purview-dev/pm-docs-site 0.1.0-pre.1 → 0.1.0-pre.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +130 -18
  2. package/dist/cli.d.ts +2 -0
  3. package/dist/cli.js +91 -0
  4. package/dist/dev-env.d.ts +2 -0
  5. package/dist/dev-env.js +13 -0
  6. package/dist/fs-allow.d.ts +2 -0
  7. package/dist/fs-allow.js +11 -0
  8. package/dist/index.d.ts +7 -0
  9. package/dist/index.js +152 -0
  10. package/dist/options.d.ts +5 -0
  11. package/dist/options.js +46 -0
  12. package/dist/repo-docs.d.ts +33 -0
  13. package/dist/repo-docs.js +94 -0
  14. package/dist/schema-version.d.ts +27 -0
  15. package/dist/schema-version.js +48 -0
  16. package/dist/sidebar.d.ts +10 -0
  17. package/dist/sidebar.js +32 -0
  18. package/dist/site-options.d.ts +9 -0
  19. package/dist/site-options.js +44 -0
  20. package/dist/types.d.ts +47 -0
  21. package/dist/types.js +4 -0
  22. package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
  23. package/lib/schema-version.ts +59 -0
  24. package/{index.d.ts → lib/types.ts} +5 -6
  25. package/package.json +19 -9
  26. package/src/components/FeatureSummary.astro +30 -9
  27. package/src/components/FeatureTable.astro +1 -1
  28. package/src/components/ItemDetail.astro +1 -1
  29. package/src/components/ItemDialog.astro +12 -8
  30. package/src/components/PlanInteractions.astro +15 -3
  31. package/src/components/RefLink.astro +7 -4
  32. package/src/components/board/Board.tsx +252 -0
  33. package/src/components/board/KanbanItemCard.tsx +131 -0
  34. package/src/components/board/LinkRuns.tsx +21 -0
  35. package/src/components/board/TaskKanbanCard.tsx +83 -0
  36. package/src/components/board/useBoardUrlState.ts +41 -0
  37. package/src/components/decisions/Decisions.tsx +162 -0
  38. package/src/components/decisions/useDecisionsUrlState.ts +29 -0
  39. package/src/components/graph/Graph.tsx +290 -0
  40. package/src/components/graph/GraphNodes.tsx +120 -0
  41. package/src/components/graph/useGraphUrlState.ts +58 -0
  42. package/src/components/lib/KanbanItemCard.astro +7 -11
  43. package/src/components/lib/StatusTimelineFeed.astro +3 -2
  44. package/src/components/lib/TaskKanbanCard.astro +2 -1
  45. package/src/components/timeline/Timeline.tsx +192 -0
  46. package/src/components/timeline/useTimelineLayout.ts +39 -0
  47. package/src/content.config.ts +22 -6
  48. package/src/env.d.ts +2 -2
  49. package/src/lib/board-data.ts +84 -0
  50. package/src/lib/board.ts +209 -0
  51. package/src/lib/decisions.ts +100 -0
  52. package/src/lib/graph-layout.ts +270 -0
  53. package/src/lib/graph-state.ts +99 -0
  54. package/src/lib/graph.ts +194 -0
  55. package/src/lib/link-html.ts +39 -0
  56. package/src/lib/planning-types.ts +32 -3
  57. package/src/lib/planning.ts +94 -52
  58. package/src/lib/ref-boundary.ts +19 -0
  59. package/src/lib/references.ts +67 -8
  60. package/src/lib/timeline-state.ts +119 -0
  61. package/src/lib/timeline.ts +51 -0
  62. package/src/loaders/adrs.ts +43 -0
  63. package/src/loaders/repo-docs.ts +3 -3
  64. package/src/pages/404.astro +18 -0
  65. package/src/pages/index.astro +1 -1
  66. package/src/pages/plan/board.astro +14 -113
  67. package/src/pages/plan/log.astro +18 -1
  68. package/src/pages/plan/roadmap.astro +21 -3
  69. package/src/routes/plan/decisions/[id].astro +93 -0
  70. package/src/routes/plan/decisions.astro +52 -0
  71. package/src/routes/plan/graph.astro +80 -0
  72. package/src/routes/plan/milestones/index.astro +2 -2
  73. package/src/routes/plan/now.astro +2 -3
  74. package/src/scripts/plan.ts +32 -46
  75. package/src/styles/components.css +244 -13
  76. package/src/styles/graph.css +296 -0
  77. package/src/styles/kanban.css +277 -0
  78. package/src/styles/timeline.css +210 -0
  79. package/cli.mjs +0 -120
  80. package/index.mjs +0 -97
  81. package/lib/options.mjs +0 -67
  82. package/lib/schema-version.mjs +0 -29
  83. package/lib/sidebar.mjs +0 -47
  84. package/lib/site-options.mjs +0 -38
@@ -0,0 +1,209 @@
1
+ // Pure filter, lane, and query-string model for the Board island. No Astro,
2
+ // no node:*, no runtime import from planning.ts: the island loads this module
3
+ // in the browser, so it only takes types from planning-types.ts.
4
+ import type { Owner, Rag, Size } from './planning-types';
5
+
6
+ export type ColumnName = 'now' | 'next' | 'foryou' | 'waiting' | 'done';
7
+
8
+ export const COLUMNS: readonly { name: ColumnName; title: string }[] = [
9
+ { name: 'now', title: 'Now' },
10
+ { name: 'next', title: 'Next' },
11
+ { name: 'foryou', title: 'For you' },
12
+ { name: 'waiting', title: 'Waiting' },
13
+ { name: 'done', title: 'Done' },
14
+ ];
15
+
16
+ export type CardRag = Rag | 'none';
17
+
18
+ export interface LinkRun {
19
+ text: string;
20
+ href: string | null;
21
+ label: string | null;
22
+ }
23
+
24
+ export interface BoardCard {
25
+ key: string; // unique per card: `${column}:${id ?? index}`
26
+ id: string | null; // null for a Done entry without an ID
27
+ title: string; // "R-013 Email invoices to tenants"
28
+ titleRuns: LinkRun[]; // linked title text, used when href is null
29
+ column: ColumnName;
30
+ owner: Owner | null;
31
+ initials: string | null; // the owner as the card's initials; null with no owner, which every owner filter hides
32
+ milestone: string | null; // a known milestone ID, or null
33
+ tag: string; // milestone ID or "No milestone"
34
+ tagHref: string | null;
35
+ size: Size | null;
36
+ rag: CardRag;
37
+ detail: LinkRun[]; // the detail line (Done: the date)
38
+ href: string | null; // the item page; null when not built
39
+ started: string | null; // Now card only
40
+ progress: number | null; // Now card only, 0..100
41
+ }
42
+
43
+ export interface BoardFilters {
44
+ owner: Owner | null;
45
+ milestone: string | null;
46
+ size: Size | null;
47
+ rag: CardRag | null;
48
+ }
49
+
50
+ export type GroupBy = 'none' | 'milestone' | 'owner';
51
+
52
+ export interface BoardState {
53
+ filters: BoardFilters;
54
+ group: GroupBy;
55
+ }
56
+
57
+ export const DEFAULT_STATE: BoardState = {
58
+ filters: { owner: null, milestone: null, size: null, rag: null },
59
+ group: 'none',
60
+ };
61
+
62
+ const OWNERS: readonly Owner[] = ['agent', 'user', 'both'];
63
+ const SIZES: readonly Size[] = ['S', 'M', 'L'];
64
+ const RAGS: readonly Rag[] = ['red', 'amber', 'green'];
65
+ const GROUPS: readonly GroupBy[] = ['none', 'milestone', 'owner'];
66
+ const RAG_RANK: Record<Rag, number> = { red: 3, amber: 2, green: 1 };
67
+
68
+ /** The worst of red, amber, green over the open risks that affect this card's ID exactly; 'none' otherwise. */
69
+ export function cardRag(id: string | null, openRisks: { affects: string | null; rag: Rag }[]): CardRag {
70
+ if (id === null) {
71
+ return 'none';
72
+ }
73
+
74
+ let worst: Rag | null = null;
75
+
76
+ for (const risk of openRisks) {
77
+ if (risk.affects === id && (worst === null || RAG_RANK[risk.rag] > RAG_RANK[worst])) {
78
+ worst = risk.rag;
79
+ }
80
+ }
81
+
82
+ return worst ?? 'none';
83
+ }
84
+
85
+ /** Parses a board query string (with or without the leading '?'); an unknown or junk value is ignored (All / None). */
86
+ export function parseBoardQuery(search: string, milestoneIds: string[]): BoardState {
87
+ const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
88
+
89
+ const owner = params.get('owner');
90
+ const milestone = params.get('milestone');
91
+ const size = params.get('size');
92
+ const rag = params.get('rag');
93
+ const group = params.get('group');
94
+
95
+ return {
96
+ filters: {
97
+ owner: owner !== null && (OWNERS as string[]).includes(owner) ? (owner as Owner) : null,
98
+ milestone: milestone === 'none' || (milestone !== null && milestoneIds.includes(milestone)) ? milestone : null,
99
+ size: size !== null && (SIZES as string[]).includes(size) ? (size as Size) : null,
100
+ rag: rag === 'none' || (rag !== null && (RAGS as string[]).includes(rag)) ? (rag as CardRag) : null,
101
+ },
102
+ group: group !== null && (GROUPS as string[]).includes(group) ? (group as GroupBy) : 'none',
103
+ };
104
+ }
105
+
106
+ /** The query string for this state, in the fixed key order owner, milestone, size, rag, group; '' for DEFAULT_STATE. */
107
+ export function boardQuery(state: BoardState): string {
108
+ const { filters, group } = state;
109
+ const pairs: [string, string][] = [];
110
+
111
+ if (filters.owner !== null) {
112
+ pairs.push(['owner', filters.owner]);
113
+ }
114
+ if (filters.milestone !== null) {
115
+ pairs.push(['milestone', filters.milestone]);
116
+ }
117
+ if (filters.size !== null) {
118
+ pairs.push(['size', filters.size]);
119
+ }
120
+ if (filters.rag !== null) {
121
+ pairs.push(['rag', filters.rag]);
122
+ }
123
+ if (group !== 'none') {
124
+ pairs.push(['group', group]);
125
+ }
126
+
127
+ if (pairs.length === 0) {
128
+ return '';
129
+ }
130
+
131
+ return `?${pairs.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join('&')}`;
132
+ }
133
+
134
+ /** Any filter set; group alone is not a filter. */
135
+ export function isFiltered(state: BoardState): boolean {
136
+ const { owner, milestone, size, rag } = state.filters;
137
+
138
+ return owner !== null || milestone !== null || size !== null || rag !== null;
139
+ }
140
+
141
+ export function matches(card: BoardCard, filters: BoardFilters): boolean {
142
+ if (filters.owner !== null && card.owner !== filters.owner) {
143
+ return false;
144
+ }
145
+ if (filters.size !== null && card.size !== filters.size) {
146
+ return false;
147
+ }
148
+ if (filters.milestone !== null) {
149
+ const wantsNone = filters.milestone === 'none';
150
+
151
+ if (wantsNone ? card.milestone !== null : card.milestone !== filters.milestone) {
152
+ return false;
153
+ }
154
+ }
155
+ if (filters.rag !== null && card.rag !== filters.rag) {
156
+ return false;
157
+ }
158
+
159
+ return true;
160
+ }
161
+
162
+ export interface Lane {
163
+ key: string;
164
+ label: string;
165
+ cards: BoardCard[];
166
+ }
167
+
168
+ function bucket(cards: BoardCard[], keyOf: (card: BoardCard) => string): Map<string, BoardCard[]> {
169
+ const buckets = new Map<string, BoardCard[]>();
170
+
171
+ for (const card of cards) {
172
+ const key = keyOf(card);
173
+ const existing = buckets.get(key);
174
+
175
+ if (existing) {
176
+ existing.push(card);
177
+ } else {
178
+ buckets.set(key, [card]);
179
+ }
180
+ }
181
+
182
+ return buckets;
183
+ }
184
+
185
+ /** Groups cards into lanes: ungrouped is one lane holding every card in order; milestone and owner follow a fixed lane order and omit empty lanes. */
186
+ export function lanes(cards: BoardCard[], group: GroupBy, milestones: { id: string; name: string }[]): Lane[] {
187
+ if (group === 'none') {
188
+ return [{ key: 'all', label: '', cards }];
189
+ }
190
+
191
+ if (group === 'milestone') {
192
+ const knownIds = new Set(milestones.map((milestone) => milestone.id));
193
+ const buckets = bucket(cards, (card) => (card.milestone !== null && knownIds.has(card.milestone) ? card.milestone : 'none'));
194
+ const order = [...milestones.map((milestone) => ({ key: milestone.id, label: `${milestone.id} ${milestone.name}` })), { key: 'none', label: 'No milestone' }];
195
+
196
+ return order.filter(({ key }) => (buckets.get(key)?.length ?? 0) > 0).map(({ key, label }) => ({ key, label, cards: buckets.get(key)! }));
197
+ }
198
+
199
+ // group === 'owner'
200
+ const buckets = bucket(cards, (card) => card.owner ?? 'none');
201
+ const order = [
202
+ { key: 'agent', label: 'agent' },
203
+ { key: 'user', label: 'user' },
204
+ { key: 'both', label: 'both' },
205
+ { key: 'none', label: 'No owner' },
206
+ ];
207
+
208
+ return order.filter(({ key }) => (buckets.get(key)?.length ?? 0) > 0).map(({ key, label }) => ({ key, label, cards: buckets.get(key)! }));
209
+ }
@@ -0,0 +1,100 @@
1
+ // The Decisions view's state: search, status and category filters, grouping,
2
+ // and the query string that keeps them in the URL. Pure, so the island and its
3
+ // tests share it. All from planning.json's `adrs`.
4
+
5
+ import type { Adr, AdrStatus } from './planning-types';
6
+
7
+ /** Every status, in lifecycle order; also the order of status groups. */
8
+ export const ADR_STATUSES: readonly AdrStatus[] = ['proposed', 'accepted', 'deprecated', 'superseded'];
9
+
10
+ export type DecisionsGroup = 'category' | 'status' | 'none';
11
+
12
+ export interface DecisionsState {
13
+ q: string;
14
+ status: AdrStatus[];
15
+ /** Empty means every category. */
16
+ category: string[];
17
+ group: DecisionsGroup;
18
+ }
19
+
20
+ /** Superseded ADRs are hidden until their chip is pressed. */
21
+ export const DEFAULT_DECISIONS_STATE: DecisionsState = { q: '', status: ['proposed', 'accepted', 'deprecated'], category: [], group: 'category' };
22
+
23
+ const GROUPS: readonly DecisionsGroup[] = ['category', 'status', 'none'];
24
+
25
+ const sameList = (a: readonly string[], b: readonly string[]) => a.length === b.length && a.every((value, i) => value === b[i]);
26
+
27
+ /** Parse a query string (with or without `?`); unknown values are dropped and an empty status list falls back to the default. */
28
+ export function parseDecisionsQuery(search: string, categories: string[]): DecisionsState {
29
+ const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
30
+ const listed = (key: string) => (params.get(key) ?? '').split(',').filter((value) => value !== '');
31
+ const status = ADR_STATUSES.filter((value) => listed('status').includes(value));
32
+ const group = params.get('group');
33
+
34
+ return {
35
+ q: params.get('q') ?? '',
36
+ status: status.length ? status : [...DEFAULT_DECISIONS_STATE.status],
37
+ category: [...categories].sort().filter((value) => listed('category').includes(value)),
38
+ group: group !== null && (GROUPS as string[]).includes(group) ? (group as DecisionsGroup) : DEFAULT_DECISIONS_STATE.group,
39
+ };
40
+ }
41
+
42
+ /** The query string for a state, keys in the order q, status, category, group; `''` for the default. */
43
+ export function decisionsQuery(state: DecisionsState): string {
44
+ const pairs: [string, string][] = [];
45
+ const status = ADR_STATUSES.filter((value) => state.status.includes(value));
46
+
47
+ if (state.q !== '') pairs.push(['q', state.q]);
48
+ if (!sameList(status, DEFAULT_DECISIONS_STATE.status)) pairs.push(['status', status.join(',')]);
49
+ if (state.category.length) pairs.push(['category', [...state.category].sort().join(',')]);
50
+ if (state.group !== DEFAULT_DECISIONS_STATE.group) pairs.push(['group', state.group]);
51
+
52
+ return pairs.length ? `?${pairs.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join('&')}` : '';
53
+ }
54
+
55
+ /** The words a search matches: ID, title, category, and the four sections without Markdown syntax, lower-cased. */
56
+ export function adrSearchText(adr: Adr): string {
57
+ return [adr.id, adr.title, adr.category, adr.context, adr.decision, adr.alternatives, adr.consequences]
58
+ .filter((text): text is string => !!text)
59
+ .join(' ')
60
+ .replace(/[*_`#>|[\]()]/g, ' ')
61
+ .replace(/\s+/g, ' ')
62
+ .trim()
63
+ .toLowerCase();
64
+ }
65
+
66
+ /** Its status and category are selected, and every word of the search appears in its text (adrSearchText, unless given). */
67
+ export function matchesDecision(adr: Pick<Adr, 'status' | 'category'>, state: DecisionsState, text: string = adrSearchText(adr as Adr)): boolean {
68
+ if (adr.status && !state.status.includes(adr.status)) return false;
69
+ if (state.category.length && !state.category.includes(adr.category ?? '')) return false;
70
+
71
+ return state.q
72
+ .toLowerCase()
73
+ .split(/\s+/)
74
+ .filter((word) => word !== '')
75
+ .every((word) => text.includes(word));
76
+ }
77
+
78
+ export interface DecisionGroup<T extends Pick<Adr, 'id' | 'status' | 'category'> = Adr> {
79
+ key: string;
80
+ label: string;
81
+ adrs: T[];
82
+ }
83
+
84
+ const byNumber = <T extends Pick<Adr, 'id'>>(a: T, b: T) => Number(a.id.slice(4)) - Number(b.id.slice(4));
85
+ const capital = (text: string) => text.charAt(0).toUpperCase() + text.slice(1);
86
+
87
+ /** Category groups by name, status groups in lifecycle order, or one group; empty groups are left out, ADRs by ID inside each. */
88
+ export function groupDecisions<T extends Pick<Adr, 'id' | 'status' | 'category'>>(adrs: T[], group: DecisionsGroup): DecisionGroup<T>[] {
89
+ if (group === 'none') return [{ key: 'all', label: 'All decisions', adrs }];
90
+
91
+ const keyOf = (adr: T) => (group === 'status' ? (adr.status ?? 'unknown') : (adr.category ?? 'uncategorised'));
92
+ const keys =
93
+ group === 'status'
94
+ ? [...ADR_STATUSES, 'unknown']
95
+ : [...new Set(adrs.map(keyOf))].sort();
96
+
97
+ return keys
98
+ .map((key) => ({ key, label: capital(key), adrs: adrs.filter((adr) => keyOf(adr) === key).sort(byNumber) }))
99
+ .filter((entry) => entry.adrs.length > 0);
100
+ }
@@ -0,0 +1,270 @@
1
+ // Build-time layouts for the dependency graph: four fixed sets of node boxes
2
+ // (milestone lanes or one flow, with or without done and dropped chips),
3
+ // computed with dagre in page frontmatter and shipped to the island as data.
4
+ // Only this module imports dagre, so the island never bundles it. Edges are
5
+ // not routed here: React Flow draws each as a bezier between node handles.
6
+ //
7
+ // dagre lays out the linked nodes only (those with a drawn edge), so isolated
8
+ // items never stretch the linked graph. In a cycle dagre reverses one edge to
9
+ // rank the nodes, so that edge runs right to left; the left-to-right rule
10
+ // cannot hold for it.
11
+
12
+ import { Graph, layout } from '@dagrejs/dagre';
13
+
14
+ import type { GraphData, GraphEdge, GraphNode } from './graph';
15
+ import { milestoneSummaries } from './planning';
16
+ import type { Planning } from './planning-types';
17
+
18
+ export type LayoutKey = 'lanes-done' | 'lanes-open' | 'flow-done' | 'flow-open';
19
+
20
+ /** A node's box: top-left corner and size, in whole pixels. */
21
+ export interface Box {
22
+ x: number;
23
+ y: number;
24
+ width: number;
25
+ height: number;
26
+ }
27
+
28
+ /** One milestone lane, top to bottom. */
29
+ export interface Lane {
30
+ /** The milestone ID, or `none` for the items with no milestone. */
31
+ key: string;
32
+ /** `<ID> <name>`, or `No milestone`. */
33
+ label: string;
34
+ isFocus: boolean;
35
+ y: number;
36
+ height: number;
37
+ }
38
+
39
+ /** One positioned graph. A node absent from `boxes` is hidden; an edge is drawn only when both ends have boxes. */
40
+ export interface GraphLayout {
41
+ boxes: Record<string, Box>;
42
+ /** Empty in the flow layouts. */
43
+ lanes: Lane[];
44
+ /** The `No links` row of isolated items in the flow layouts; `null` when there is none. */
45
+ tray: { y: number } | null;
46
+ width: number;
47
+ height: number;
48
+ }
49
+
50
+ /** Node sizes, in pixels. */
51
+ export const SIZES = {
52
+ item: { width: 220, height: 64 },
53
+ chip: { width: 120, height: 28 },
54
+ } as const;
55
+
56
+ /** The space between nodes in one column, and between tray boxes. */
57
+ const NODE_SEP = 24;
58
+ const RANK_SEP = 80;
59
+ /** The lane's or tray's label band, above its nodes. */
60
+ const LABEL_BAND = 32;
61
+ /** The space below the label band and below a lane's nodes. */
62
+ const LANE_PADDING = 16;
63
+ /** The space between the linked graph and the tray. */
64
+ const TRAY_GAP = 48;
65
+ /** Tray boxes per row when no node is linked. */
66
+ const TRAY_COLUMNS = 4;
67
+ const NONE = 'none';
68
+
69
+ const byId = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
70
+
71
+ const sizeOf = (node: GraphNode) => (node.kind === 'item' ? SIZES.item : SIZES.chip);
72
+
73
+ /**
74
+ * dagre's position for each linked node, as a whole-pixel top-left box,
75
+ * shifted so the linked graph starts at x 0 and y 0.
76
+ */
77
+ function dagreBoxes(nodes: GraphNode[], edges: GraphEdge[]): Map<string, Box> {
78
+ const boxes = new Map<string, Box>();
79
+
80
+ if (nodes.length === 0) return boxes;
81
+
82
+ const graph = new Graph();
83
+
84
+ graph.setGraph({ rankdir: 'LR', nodesep: NODE_SEP, ranksep: RANK_SEP });
85
+ graph.setDefaultEdgeLabel(() => ({}));
86
+ for (const node of [...nodes].sort((a, b) => byId(a.id, b.id))) graph.setNode(node.id, { ...sizeOf(node) });
87
+
88
+ const pairs = [...new Set(edges.map((edge) => `${edge.source}\n${edge.target}`))].sort(byId);
89
+
90
+ for (const pair of pairs) {
91
+ const [source, target] = pair.split('\n') as [string, string];
92
+
93
+ graph.setEdge(source, target);
94
+ }
95
+ layout(graph);
96
+
97
+ for (const node of nodes) {
98
+ const { x, y, width, height } = graph.node(node.id) as { x: number; y: number; width: number; height: number };
99
+
100
+ boxes.set(node.id, { x: Math.round(x - width / 2), y: Math.round(y - height / 2), width, height });
101
+ }
102
+
103
+ const minX = Math.min(...[...boxes.values()].map((box) => box.x));
104
+ const minY = Math.min(...[...boxes.values()].map((box) => box.y));
105
+
106
+ for (const [id, box] of boxes) boxes.set(id, { ...box, x: box.x - minX, y: box.y - minY });
107
+
108
+ return boxes;
109
+ }
110
+
111
+ /** The candidate lanes, in `milestoneSummaries` order, with `No milestone` last. */
112
+ function laneCandidates(planning: Planning): Omit<Lane, 'y' | 'height'>[] {
113
+ const milestones = milestoneSummaries(planning).filter((summary) => summary.id !== null);
114
+
115
+ return [
116
+ ...milestones.map((summary) => ({ key: summary.id!, label: `${summary.id} ${summary.name}`, isFocus: summary.isFocus })),
117
+ { key: NONE, label: 'No milestone', isFocus: false },
118
+ ];
119
+ }
120
+
121
+ /**
122
+ * Lanes: dagre's columns for linked nodes, each node in its lane, stacked per
123
+ * lane and column in dagre's order; isolated items go in the first column of
124
+ * their lane, below the linked nodes they would otherwise overlap.
125
+ */
126
+ function lanesLayout(nodes: GraphNode[], edges: GraphEdge[], placed: Map<string, Box>, planning: Planning): GraphLayout {
127
+ const candidates = laneCandidates(planning);
128
+ const laneIndex = new Map(candidates.map((lane, index) => [lane.key, index]));
129
+ const nodeById = new Map(nodes.map((node) => [node.id, node]));
130
+ const itemLane = (node: GraphNode): number => laneIndex.get(node.milestone ?? NONE) ?? laneIndex.get(NONE)!;
131
+ const laneOf = (node: GraphNode): number => {
132
+ if (node.kind === 'item') return itemLane(node);
133
+
134
+ const dependants = edges.map((edge) => (edge.source === node.id ? nodeById.get(edge.target) : undefined)).filter((target): target is GraphNode => target?.kind === 'item');
135
+
136
+ return dependants.length > 0 ? Math.min(...dependants.map(itemLane)) : laneIndex.get(NONE)!;
137
+ };
138
+ const firstX = placed.size > 0 ? Math.min(...[...placed.values()].map((box) => box.x)) : 0;
139
+
140
+ // Group linked nodes by lane, then by column (dagre's centre x); isolated items by lane, in node order.
141
+ const linkedByLane = new Map<number, Map<number, GraphNode[]>>();
142
+ const isolatedByLane = new Map<number, GraphNode[]>();
143
+
144
+ for (const node of nodes) {
145
+ const lane = laneOf(node);
146
+ const box = placed.get(node.id);
147
+
148
+ if (!box) {
149
+ isolatedByLane.set(lane, [...(isolatedByLane.get(lane) ?? []), node]);
150
+ continue;
151
+ }
152
+
153
+ const columns = linkedByLane.get(lane) ?? new Map<number, GraphNode[]>();
154
+ const column = box.x + box.width / 2;
155
+
156
+ columns.set(column, [...(columns.get(column) ?? []), node]);
157
+ linkedByLane.set(lane, columns);
158
+ }
159
+
160
+ const boxes: Record<string, Box> = {};
161
+ const lanes: Lane[] = [];
162
+ let top = 0;
163
+
164
+ candidates.forEach((candidate, index) => {
165
+ const columns = linkedByLane.get(index);
166
+ const isolated = isolatedByLane.get(index) ?? [];
167
+
168
+ if (!columns && isolated.length === 0) return;
169
+
170
+ const start = top + LABEL_BAND + LANE_PADDING;
171
+ const laneBoxes: Box[] = [];
172
+
173
+ for (const column of columns?.values() ?? []) {
174
+ column.sort((a, b) => placed.get(a.id)!.y - placed.get(b.id)!.y || byId(a.id, b.id));
175
+
176
+ let y = start;
177
+
178
+ for (const node of column) {
179
+ const box = { ...placed.get(node.id)!, y };
180
+
181
+ boxes[node.id] = box;
182
+ laneBoxes.push(box);
183
+ y += box.height + NODE_SEP;
184
+ }
185
+ }
186
+
187
+ // Isolated items stack in the first column, below any linked box their width would reach.
188
+ const width = SIZES.item.width;
189
+ let y = laneBoxes.filter((box) => box.x < firstX + width && firstX < box.x + box.width).reduce((bottom, box) => Math.max(bottom, box.y + box.height + NODE_SEP), start);
190
+
191
+ for (const node of isolated) {
192
+ const box = { x: firstX, y, ...sizeOf(node) };
193
+
194
+ boxes[node.id] = box;
195
+ laneBoxes.push(box);
196
+ y += box.height + NODE_SEP;
197
+ }
198
+
199
+ const bottom = laneBoxes.reduce((max, box) => Math.max(max, box.y + box.height), start);
200
+ const height = bottom - top + LANE_PADDING;
201
+
202
+ lanes.push({ ...candidate, y: top, height });
203
+ top += height;
204
+ });
205
+
206
+ return { boxes, lanes, tray: null, width: extent(boxes, 'x'), height: top };
207
+ }
208
+
209
+ /** Flow: dagre's positions for linked nodes, and isolated items in a tray below, wrapping at the linked width or TRAY_COLUMNS, whichever is wider. */
210
+ function flowLayout(nodes: GraphNode[], placed: Map<string, Box>): GraphLayout {
211
+ const boxes: Record<string, Box> = Object.fromEntries(nodes.filter((node) => placed.has(node.id)).map((node) => [node.id, placed.get(node.id)!]));
212
+ const isolated = nodes.filter((node) => !placed.has(node.id));
213
+ const linkedWidth = extent(boxes, 'x');
214
+ let tray: GraphLayout['tray'] = null;
215
+
216
+ if (isolated.length > 0) {
217
+ const step = SIZES.item.width + NODE_SEP;
218
+ const perRow = placed.size > 0 ? Math.max(TRAY_COLUMNS, Math.floor((linkedWidth + NODE_SEP) / step)) : TRAY_COLUMNS;
219
+ const trayY = placed.size > 0 ? extent(boxes, 'y') + TRAY_GAP : 0;
220
+
221
+ tray = { y: trayY };
222
+ isolated.forEach((node, index) => {
223
+ boxes[node.id] = {
224
+ x: (index % perRow) * step,
225
+ y: trayY + LABEL_BAND + Math.floor(index / perRow) * (SIZES.item.height + NODE_SEP),
226
+ ...sizeOf(node),
227
+ };
228
+ });
229
+ }
230
+
231
+ return { boxes, lanes: [], tray, width: extent(boxes, 'x'), height: extent(boxes, 'y') };
232
+ }
233
+
234
+ /** The furthest right (`x`) or bottom (`y`) edge of any box, or 0 with none. */
235
+ function extent(boxes: Record<string, Box>, axis: 'x' | 'y'): number {
236
+ return Object.values(boxes).reduce((max, box) => Math.max(max, axis === 'x' ? box.x + box.width : box.y + box.height), 0);
237
+ }
238
+
239
+ /** The two layouts for one set of drawn nodes, from a single dagre run over the linked ones so columns line up across them. */
240
+ function variant(data: GraphData, showDone: boolean, planning: Planning): { lanes: GraphLayout; flow: GraphLayout } {
241
+ const nodes = data.nodes.filter((node) => showDone || (node.kind !== 'done' && node.kind !== 'dropped'));
242
+
243
+ if (nodes.length === 0) {
244
+ const empty = (): GraphLayout => ({ boxes: {}, lanes: [], tray: null, width: 0, height: 0 });
245
+
246
+ return { lanes: empty(), flow: empty() };
247
+ }
248
+
249
+ const drawn = new Set(nodes.map((node) => node.id));
250
+ const edges = data.edges.filter((edge) => drawn.has(edge.source) && drawn.has(edge.target));
251
+ const linkedIds = new Set(edges.flatMap((edge) => [edge.source, edge.target]));
252
+ const placed = dagreBoxes(
253
+ nodes.filter((node) => linkedIds.has(node.id)),
254
+ edges,
255
+ );
256
+
257
+ return { lanes: lanesLayout(nodes, edges, placed, planning), flow: flowLayout(nodes, placed) };
258
+ }
259
+
260
+ /**
261
+ * The graph's four layouts: milestone lanes or one flow, each with done and
262
+ * dropped chips (`*-done`) or without them (`*-open`); missing chips stay in
263
+ * all four. Deterministic, in whole pixels.
264
+ */
265
+ export function graphLayouts(data: GraphData, planning: Planning): Record<LayoutKey, GraphLayout> {
266
+ const done = variant(data, true, planning);
267
+ const open = variant(data, false, planning);
268
+
269
+ return { 'lanes-done': done.lanes, 'lanes-open': open.lanes, 'flow-done': done.flow, 'flow-open': open.flow };
270
+ }
@@ -0,0 +1,99 @@
1
+ // The Graph island's URL state and chain tracing, kept apart from graph.ts so
2
+ // the island imports no module that reads planning.json: graph.ts imports
3
+ // planning.ts, which imports node:fs, and under `pm-docs-site dev` every
4
+ // module an island imports reaches the browser, used or not. `GraphState`
5
+ // lives in the URL like `TimelineLayout` in timeline.ts: defaults write no key,
6
+ // and every other parameter and the hash are kept. graph.ts re-exports all of
7
+ // it.
8
+
9
+ import type { GraphEdge } from './graph';
10
+ import type { GraphLayout, LayoutKey } from './graph-layout';
11
+
12
+ /** The graph page's own URL state: milestone lanes, done and dropped chips, and the focused node. */
13
+ export interface GraphState {
14
+ lanes: boolean;
15
+ done: boolean;
16
+ focus: string | null;
17
+ }
18
+
19
+ /** `GraphState` from `?lanes=off&done=off&focus=<ID>`; a key's absence, or any value other than the exact `off`, is the default `true`. */
20
+ export function parseGraphQuery(search: string): GraphState {
21
+ const params = new URLSearchParams(search);
22
+
23
+ return {
24
+ lanes: params.get('lanes') !== 'off',
25
+ done: params.get('done') !== 'off',
26
+ focus: params.get('focus'),
27
+ };
28
+ }
29
+
30
+ /** `search` with `lanes`, `done`, and `focus` set for each non-default value, in that order (appended last); keeps every other parameter. `''` when none remain. */
31
+ export function graphQuery(state: GraphState, search: string): string {
32
+ const params = new URLSearchParams(search);
33
+
34
+ params.delete('lanes');
35
+ params.delete('done');
36
+ params.delete('focus');
37
+
38
+ if (!state.lanes) params.append('lanes', 'off');
39
+ if (!state.done) params.append('done', 'off');
40
+ if (state.focus !== null) params.append('focus', state.focus);
41
+
42
+ const query = params.toString();
43
+
44
+ return query === '' ? '' : `?${query}`;
45
+ }
46
+
47
+ /** The layout key for the lanes/flow and done/open switches. */
48
+ export function layoutKey(state: Pick<GraphState, 'lanes' | 'done'>): LayoutKey {
49
+ return `${state.lanes ? 'lanes' : 'flow'}-${state.done ? 'done' : 'open'}` as LayoutKey;
50
+ }
51
+
52
+ /** `focus` when it names a node drawn in `layout`, else `null` (no focus, or a hidden or missing ID). */
53
+ export function resolveFocus(focus: string | null, layout: GraphLayout): string | null {
54
+ return focus !== null && layout.boxes[focus] ? focus : null;
55
+ }
56
+
57
+ /**
58
+ * Every node and edge reached from `id` by walking drawn edges (both ends
59
+ * boxed in `layout`) upstream and downstream, each direction with its own
60
+ * visited set so a cycle terminates. Includes `id` itself.
61
+ */
62
+ export function chainOf(edges: GraphEdge[], id: string, layout: GraphLayout): Set<string> {
63
+ const drawn = edges.filter((edge) => Boolean(layout.boxes[edge.source]) && Boolean(layout.boxes[edge.target]));
64
+ const result = new Set<string>([id]);
65
+
66
+ const walk = (endpoint: (edge: GraphEdge) => string, neighbour: (edge: GraphEdge) => string) => {
67
+ const visited = new Set<string>([id]);
68
+ const queue = [id];
69
+
70
+ while (queue.length > 0) {
71
+ const current = queue.shift()!;
72
+
73
+ for (const edge of drawn) {
74
+ if (endpoint(edge) !== current) continue;
75
+
76
+ result.add(edge.id);
77
+
78
+ const other = neighbour(edge);
79
+
80
+ result.add(other);
81
+ if (!visited.has(other)) {
82
+ visited.add(other);
83
+ queue.push(other);
84
+ }
85
+ }
86
+ }
87
+ };
88
+
89
+ walk(
90
+ (edge) => edge.target,
91
+ (edge) => edge.source,
92
+ );
93
+ walk(
94
+ (edge) => edge.source,
95
+ (edge) => edge.target,
96
+ );
97
+
98
+ return result;
99
+ }