@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.
- package/README.md +130 -18
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +91 -0
- package/dist/dev-env.d.ts +2 -0
- package/dist/dev-env.js +13 -0
- package/dist/fs-allow.d.ts +2 -0
- package/dist/fs-allow.js +11 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +152 -0
- package/dist/options.d.ts +5 -0
- package/dist/options.js +46 -0
- package/dist/repo-docs.d.ts +33 -0
- package/dist/repo-docs.js +94 -0
- package/dist/schema-version.d.ts +27 -0
- package/dist/schema-version.js +48 -0
- package/dist/sidebar.d.ts +10 -0
- package/dist/sidebar.js +32 -0
- package/dist/site-options.d.ts +9 -0
- package/dist/site-options.js +44 -0
- package/dist/types.d.ts +47 -0
- package/dist/types.js +4 -0
- package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
- package/lib/schema-version.ts +59 -0
- package/{index.d.ts → lib/types.ts} +5 -6
- package/package.json +19 -9
- package/src/components/FeatureSummary.astro +30 -9
- package/src/components/FeatureTable.astro +1 -1
- package/src/components/ItemDetail.astro +1 -1
- package/src/components/ItemDialog.astro +12 -8
- package/src/components/PlanInteractions.astro +15 -3
- package/src/components/RefLink.astro +7 -4
- package/src/components/board/Board.tsx +252 -0
- package/src/components/board/KanbanItemCard.tsx +131 -0
- package/src/components/board/LinkRuns.tsx +21 -0
- package/src/components/board/TaskKanbanCard.tsx +83 -0
- package/src/components/board/useBoardUrlState.ts +41 -0
- package/src/components/decisions/Decisions.tsx +162 -0
- package/src/components/decisions/useDecisionsUrlState.ts +29 -0
- package/src/components/graph/Graph.tsx +290 -0
- package/src/components/graph/GraphNodes.tsx +120 -0
- package/src/components/graph/useGraphUrlState.ts +58 -0
- package/src/components/lib/KanbanItemCard.astro +7 -11
- package/src/components/lib/StatusTimelineFeed.astro +3 -2
- package/src/components/lib/TaskKanbanCard.astro +2 -1
- package/src/components/timeline/Timeline.tsx +192 -0
- package/src/components/timeline/useTimelineLayout.ts +39 -0
- package/src/content.config.ts +22 -6
- package/src/env.d.ts +2 -2
- package/src/lib/board-data.ts +84 -0
- package/src/lib/board.ts +209 -0
- package/src/lib/decisions.ts +100 -0
- package/src/lib/graph-layout.ts +270 -0
- package/src/lib/graph-state.ts +99 -0
- package/src/lib/graph.ts +194 -0
- package/src/lib/link-html.ts +39 -0
- package/src/lib/planning-types.ts +32 -3
- package/src/lib/planning.ts +94 -52
- package/src/lib/ref-boundary.ts +19 -0
- package/src/lib/references.ts +67 -8
- package/src/lib/timeline-state.ts +119 -0
- package/src/lib/timeline.ts +51 -0
- package/src/loaders/adrs.ts +43 -0
- package/src/loaders/repo-docs.ts +3 -3
- package/src/pages/404.astro +18 -0
- package/src/pages/index.astro +1 -1
- package/src/pages/plan/board.astro +14 -113
- package/src/pages/plan/log.astro +18 -1
- package/src/pages/plan/roadmap.astro +21 -3
- package/src/routes/plan/decisions/[id].astro +93 -0
- package/src/routes/plan/decisions.astro +52 -0
- package/src/routes/plan/graph.astro +80 -0
- package/src/routes/plan/milestones/index.astro +2 -2
- package/src/routes/plan/now.astro +2 -3
- package/src/scripts/plan.ts +32 -46
- package/src/styles/components.css +244 -13
- package/src/styles/graph.css +296 -0
- package/src/styles/kanban.css +277 -0
- package/src/styles/timeline.css +210 -0
- package/cli.mjs +0 -120
- package/index.mjs +0 -97
- package/lib/options.mjs +0 -67
- package/lib/schema-version.mjs +0 -29
- package/lib/sidebar.mjs +0 -47
- package/lib/site-options.mjs +0 -38
package/src/lib/references.ts
CHANGED
|
@@ -5,13 +5,15 @@
|
|
|
5
5
|
|
|
6
6
|
import config from 'virtual:pm-docs-site/config';
|
|
7
7
|
|
|
8
|
-
import type { ViewName } from '../../
|
|
9
|
-
import {
|
|
8
|
+
import type { ViewName } from '../../lib/types.ts';
|
|
9
|
+
import { graphData } from './graph';
|
|
10
|
+
import { adrHref, adrsOf, briefAnchor, briefOf, featureHref, features, loadPlanning, milestoneHref, milestoneSummaries, roadmapGroups, type Feature } from './planning';
|
|
10
11
|
import type { Planning } from './planning-types';
|
|
12
|
+
import { refPattern } from './ref-boundary';
|
|
11
13
|
|
|
12
14
|
export type Views = Record<ViewName, boolean>;
|
|
13
15
|
|
|
14
|
-
export type TargetKind = 'item' | 'milestone' | 'risk' | 'brief';
|
|
16
|
+
export type TargetKind = 'item' | 'milestone' | 'risk' | 'brief' | 'adr';
|
|
15
17
|
|
|
16
18
|
export interface Target {
|
|
17
19
|
kind: TargetKind;
|
|
@@ -54,6 +56,10 @@ export function targets(planning: Planning, views: Views): Map<string, Target> {
|
|
|
54
56
|
add({ kind: 'risk', key: risk.id, href: riskHref(risk, true), label: `${risk.id} ${risk.title}` });
|
|
55
57
|
}
|
|
56
58
|
|
|
59
|
+
for (const adr of planning.adrs) {
|
|
60
|
+
add({ kind: 'adr', key: adr.id, href: views.decisions ? adrHref(adr.id) : null, label: `${adr.id} ${adr.title}` });
|
|
61
|
+
}
|
|
62
|
+
|
|
57
63
|
for (const brief of planning.briefs) {
|
|
58
64
|
add({ kind: 'brief', key: brief.path, href: views.briefs ? `/plan/briefs/#${briefAnchor(brief.path)}` : null, label: brief.title });
|
|
59
65
|
}
|
|
@@ -61,19 +67,38 @@ export function targets(planning: Planning, views: Views): Map<string, Target> {
|
|
|
61
67
|
return known;
|
|
62
68
|
}
|
|
63
69
|
|
|
70
|
+
/**
|
|
71
|
+
* The text RefLink prints: a known target's label (`full`) or its key (`id`);
|
|
72
|
+
* for an unknown key, the caller's fallback (an entry title, `No milestone`),
|
|
73
|
+
* else the key itself.
|
|
74
|
+
*/
|
|
75
|
+
export function refText(target: Target | undefined, ref: string | null | undefined, label: 'full' | 'id', fallback?: string): string {
|
|
76
|
+
if (target) return label === 'full' ? target.label : (ref ?? '');
|
|
77
|
+
|
|
78
|
+
return fallback ?? ref ?? '';
|
|
79
|
+
}
|
|
80
|
+
|
|
64
81
|
/** A run of prose: plain text, or the text of one known reference and its target. */
|
|
65
82
|
export interface Run {
|
|
66
83
|
text: string;
|
|
67
84
|
target?: Target;
|
|
68
85
|
}
|
|
69
86
|
|
|
70
|
-
const
|
|
87
|
+
const IDS = [String.raw`ADR-\d{3,}`, String.raw`RK-\d{3,}`, String.raw`R-\d{3,}`, String.raw`M\d+`];
|
|
71
88
|
const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
72
89
|
|
|
73
|
-
/**
|
|
90
|
+
/**
|
|
91
|
+
* Split text into plain runs and runs that are a known ID or brief path with a
|
|
92
|
+
* page, at the link scanner's boundaries (ref-boundary.ts): an ID inside a path
|
|
93
|
+
* or a hyphenated token is never a reference.
|
|
94
|
+
*/
|
|
74
95
|
export function linkify(text: string, known: Map<string, Target>): Run[] {
|
|
75
|
-
const paths = [...known.values()]
|
|
76
|
-
|
|
96
|
+
const paths = [...known.values()]
|
|
97
|
+
.filter((target) => target.kind === 'brief')
|
|
98
|
+
.map((target) => target.key)
|
|
99
|
+
.sort((a, b) => b.length - a.length)
|
|
100
|
+
.map(escape);
|
|
101
|
+
const pattern = refPattern([...paths, ...IDS]);
|
|
77
102
|
const runs: Run[] = [];
|
|
78
103
|
const plain = (value: string) => {
|
|
79
104
|
if (!value) return;
|
|
@@ -98,7 +123,7 @@ export function linkify(text: string, known: Map<string, Target>): Run[] {
|
|
|
98
123
|
return runs;
|
|
99
124
|
}
|
|
100
125
|
|
|
101
|
-
export type Relation = 'depends on' | 'revisits' | 'milestone' | 'affects' | 'mitigation' | 'related' | 'brief' | 'mentions' | 'listed';
|
|
126
|
+
export type Relation = 'depends on' | 'revisits' | 'milestone' | 'affects' | 'mitigation' | 'related' | 'brief' | 'decision' | 'supersedes' | 'superseded by' | 'mentions' | 'listed';
|
|
102
127
|
|
|
103
128
|
/** The order and heading of each relation in a `Linked from` section. */
|
|
104
129
|
export const RELATION_LABELS: Record<Relation, string> = {
|
|
@@ -109,6 +134,9 @@ export const RELATION_LABELS: Record<Relation, string> = {
|
|
|
109
134
|
mitigation: 'Mitigation',
|
|
110
135
|
related: 'Related',
|
|
111
136
|
brief: 'Brief',
|
|
137
|
+
decision: 'Decisions',
|
|
138
|
+
supersedes: 'Supersedes',
|
|
139
|
+
'superseded by': 'Superseded by',
|
|
112
140
|
mentions: 'Mentioned on',
|
|
113
141
|
listed: 'Listed on',
|
|
114
142
|
};
|
|
@@ -163,6 +191,7 @@ export function references(planning: Planning, views: Views): Map<string, Backli
|
|
|
163
191
|
const brief = briefOf(planning, feature);
|
|
164
192
|
|
|
165
193
|
page.link(brief?.path ?? feature.brief, 'brief');
|
|
194
|
+
for (const adr of adrsOf(planning, feature.id)) page.link(adr.id, 'listed');
|
|
166
195
|
for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
|
|
167
196
|
if (risk.affects !== feature.id) continue;
|
|
168
197
|
page.link(risk.id, 'affects');
|
|
@@ -201,6 +230,26 @@ export function references(planning: Planning, views: Views): Map<string, Backli
|
|
|
201
230
|
for (const text of [risk.ragOverride, risk.raised, risk.reviewed, risk.closed]) page.prose(text);
|
|
202
231
|
}
|
|
203
232
|
|
|
233
|
+
if (views.decisions) {
|
|
234
|
+
const page = source('/plan/decisions/', 'Decisions');
|
|
235
|
+
|
|
236
|
+
// Each row: the ADR, its item, and its successor.
|
|
237
|
+
for (const adr of planning.adrs) {
|
|
238
|
+
page.link(adr.id, 'listed');
|
|
239
|
+
page.link(adr.item, 'listed');
|
|
240
|
+
page.link(adr.supersededBy, 'listed');
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
for (const adr of planning.adrs) {
|
|
244
|
+
const own = source(adrHref(adr.id), `${adr.id} ${adr.title}`);
|
|
245
|
+
|
|
246
|
+
own.link(adr.item, 'decision');
|
|
247
|
+
own.link(adr.supersedes, 'supersedes');
|
|
248
|
+
own.link(adr.supersededBy, 'superseded by');
|
|
249
|
+
for (const text of [adr.source, adr.context, adr.decision, adr.alternatives, adr.consequences]) own.prose(text);
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
|
|
204
253
|
const byId = new Map(all.map((feature) => [feature.id, feature]));
|
|
205
254
|
const board = source('/plan/board/', 'Board');
|
|
206
255
|
const { columns } = planning.board;
|
|
@@ -227,6 +276,16 @@ export function references(planning: Planning, views: Views): Map<string, Backli
|
|
|
227
276
|
}
|
|
228
277
|
}
|
|
229
278
|
|
|
279
|
+
if (views.graph) {
|
|
280
|
+
const graph = source('/plan/graph/', 'Graph');
|
|
281
|
+
|
|
282
|
+
// Each node's ID (items, and the chips of the default layout); each item's milestone, in its meta line and its lane label.
|
|
283
|
+
for (const node of graphData(planning, known).nodes) {
|
|
284
|
+
graph.link(node.id, 'listed');
|
|
285
|
+
if (node.kind === 'item') graph.link(milestoneKey(node.milestone), 'listed');
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
|
|
230
289
|
const log = source('/plan/log/', 'Log');
|
|
231
290
|
|
|
232
291
|
for (const entry of planning.board.activity) {
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
// The Timeline island's types, layout URL state, and zoom and wheel maths,
|
|
2
|
+
// kept apart from timeline.ts so the island imports no module that reads
|
|
3
|
+
// planning.json: timeline.ts imports planning.ts, which imports node:fs, and
|
|
4
|
+
// under `pm-docs-site dev` every module an island imports reaches the browser,
|
|
5
|
+
// used or not. timeline.ts re-exports all of it.
|
|
6
|
+
|
|
7
|
+
export type MilestoneState = 'active' | 'planned' | 'done' | 'other';
|
|
8
|
+
|
|
9
|
+
export interface MilestoneStatus {
|
|
10
|
+
state: MilestoneState;
|
|
11
|
+
label: string;
|
|
12
|
+
doneOn: string | null;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export interface TimelineMilestone {
|
|
16
|
+
/** `null` for the no-milestone card. */
|
|
17
|
+
id: string | null;
|
|
18
|
+
/** `id`, or `none` for the no-milestone card. */
|
|
19
|
+
key: string;
|
|
20
|
+
name: string;
|
|
21
|
+
href: string | null;
|
|
22
|
+
isFocus: boolean;
|
|
23
|
+
status: MilestoneStatus;
|
|
24
|
+
target: string | null;
|
|
25
|
+
progress: { done: number; total: number; percent: number };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// Layout URL state, zoom maths, and the wheel rule: the strip's horizontal or
|
|
29
|
+
// vertical layout lives in the URL (never the zoom); zoom lives only in the
|
|
30
|
+
// island's own state, snapped to a fixed step; and the wheel rule tells a
|
|
31
|
+
// plain vertical wheel apart from a pinch-zoom gesture and from a gesture the
|
|
32
|
+
// strip's native horizontal scrolling already handles.
|
|
33
|
+
|
|
34
|
+
export type TimelineLayout = 'horizontal' | 'vertical';
|
|
35
|
+
|
|
36
|
+
/** The layout named by `?layout=`; anything other than the exact value `vertical` is horizontal. */
|
|
37
|
+
export function parseTimelineQuery(search: string): TimelineLayout {
|
|
38
|
+
return new URLSearchParams(search).get('layout') === 'vertical' ? 'vertical' : 'horizontal';
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** `search` with `layout` set for `vertical` (appended last) or removed for `horizontal`; keeps every other parameter. `''` when none remain. */
|
|
42
|
+
export function timelineQuery(layout: TimelineLayout, search: string): string {
|
|
43
|
+
const params = new URLSearchParams(search);
|
|
44
|
+
|
|
45
|
+
params.delete('layout');
|
|
46
|
+
|
|
47
|
+
if (layout === 'vertical') params.append('layout', 'vertical');
|
|
48
|
+
|
|
49
|
+
const query = params.toString();
|
|
50
|
+
|
|
51
|
+
return query === '' ? '' : `?${query}`;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export const ZOOM = { min: 0.5, max: 2, step: 0.25, default: 1 } as const;
|
|
55
|
+
|
|
56
|
+
/** The wheel delta, in pixels, that one pinch-zoom notch accumulates before the zoom steps. */
|
|
57
|
+
export const PINCH_STEP = 50;
|
|
58
|
+
|
|
59
|
+
const ZOOM_TICKS_PER_UNIT = Math.round(1 / ZOOM.step);
|
|
60
|
+
const ZOOM_MIN_TICKS = Math.round(ZOOM.min * ZOOM_TICKS_PER_UNIT);
|
|
61
|
+
const ZOOM_MAX_TICKS = Math.round(ZOOM.max * ZOOM_TICKS_PER_UNIT);
|
|
62
|
+
|
|
63
|
+
/** `zoom` snapped to the nearest step, moved one step in `direction`, then clamped to `[ZOOM.min, ZOOM.max]`. Integer ticks avoid float drift. */
|
|
64
|
+
export function zoomStep(zoom: number, direction: 1 | -1): number {
|
|
65
|
+
const ticks = Math.round(zoom * ZOOM_TICKS_PER_UNIT) + direction;
|
|
66
|
+
const clamped = Math.min(ZOOM_MAX_TICKS, Math.max(ZOOM_MIN_TICKS, ticks));
|
|
67
|
+
|
|
68
|
+
return clamped / ZOOM_TICKS_PER_UNIT;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* One wheel event's effect on zoom. A mouse notch (`deltaMode !== 0`, or
|
|
73
|
+
* pixels already past `PINCH_STEP`) steps immediately and clears `pending`. A
|
|
74
|
+
* trackpad pinch accumulates `pending` in pixels and steps once per
|
|
75
|
+
* `PINCH_STEP` crossed, keeping the remainder. `deltaY` `0` is a no-op.
|
|
76
|
+
*/
|
|
77
|
+
export function zoomFromWheel(zoom: number, pending: number, deltaY: number, deltaMode: number): { zoom: number; pending: number } {
|
|
78
|
+
if (deltaY === 0) return { zoom, pending };
|
|
79
|
+
|
|
80
|
+
if (deltaMode !== 0 || Math.abs(deltaY) >= PINCH_STEP) {
|
|
81
|
+
return { zoom: zoomStep(zoom, deltaY < 0 ? 1 : -1), pending: 0 };
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
let nextZoom = zoom;
|
|
85
|
+
let nextPending = pending + deltaY;
|
|
86
|
+
|
|
87
|
+
while (Math.abs(nextPending) >= PINCH_STEP) {
|
|
88
|
+
const negative = nextPending < 0;
|
|
89
|
+
|
|
90
|
+
nextZoom = zoomStep(nextZoom, negative ? 1 : -1);
|
|
91
|
+
nextPending += negative ? PINCH_STEP : -PINCH_STEP;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
return { zoom: nextZoom, pending: nextPending };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** One wheel event's effect in pixels: `deltaY` as-is in pixel mode (`0`), scaled by `lineHeight` in line mode (`1`), or by `pageSize` in page mode (`2`). */
|
|
98
|
+
export function wheelPixels(deltaY: number, deltaMode: number, lineHeight: number, pageSize: number): number {
|
|
99
|
+
if (deltaMode === 1) return deltaY * lineHeight;
|
|
100
|
+
if (deltaMode === 2) return deltaY * pageSize;
|
|
101
|
+
|
|
102
|
+
return deltaY;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** Whether the strip's own horizontal scrolling should consume this wheel event, with 1px of tolerance at either end. */
|
|
106
|
+
export function wheelScrollsStrip(
|
|
107
|
+
e: { deltaX: number; deltaY: number },
|
|
108
|
+
s: { scrollLeft: number; scrollWidth: number; clientWidth: number },
|
|
109
|
+
): boolean {
|
|
110
|
+
if (Math.abs(e.deltaX) >= Math.abs(e.deltaY)) return false;
|
|
111
|
+
if (s.scrollWidth <= s.clientWidth) return false;
|
|
112
|
+
|
|
113
|
+
const TOLERANCE = 1;
|
|
114
|
+
const maxScrollLeft = s.scrollWidth - s.clientWidth;
|
|
115
|
+
|
|
116
|
+
if (e.deltaY > 0) return s.scrollLeft < maxScrollLeft - TOLERANCE;
|
|
117
|
+
|
|
118
|
+
return s.scrollLeft > TOLERANCE;
|
|
119
|
+
}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
// Pure derivations for the Roadmap page's milestone timeline: the cards in
|
|
2
|
+
// strategy order, their status and target text, and their progress. All from
|
|
3
|
+
// planning.json through milestoneSummaries; nothing here touches the DOM.
|
|
4
|
+
|
|
5
|
+
import { milestoneCards, normaliseTarget } from './planning';
|
|
6
|
+
import type { Planning } from './planning-types';
|
|
7
|
+
import type { MilestoneStatus, TimelineMilestone } from './timeline-state';
|
|
8
|
+
|
|
9
|
+
export { normaliseTarget } from './planning';
|
|
10
|
+
export * from './timeline-state';
|
|
11
|
+
|
|
12
|
+
const DONE = /^done(?:\s*\((\d{4}-\d{2}-\d{2})\))?$/i;
|
|
13
|
+
|
|
14
|
+
/** A milestone's status text as its state, label, and done date, if any. An unrecognised value is `other`, shown with its own text. */
|
|
15
|
+
export function parseMilestoneStatus(status: string | null): MilestoneStatus {
|
|
16
|
+
const text = status?.trim() ?? '';
|
|
17
|
+
|
|
18
|
+
if (!text) return { state: 'other', label: 'No status', doneOn: null };
|
|
19
|
+
|
|
20
|
+
const done = DONE.exec(text);
|
|
21
|
+
|
|
22
|
+
if (done) return { state: 'done', label: 'done', doneOn: done[1] ?? null };
|
|
23
|
+
|
|
24
|
+
const lower = text.toLowerCase();
|
|
25
|
+
|
|
26
|
+
return lower === 'active' || lower === 'planned' ? { state: lower, label: lower, doneOn: null } : { state: 'other', label: text, doneOn: null };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The timeline's cards, in strategy order, then `No milestone` last, from
|
|
31
|
+
* `milestoneCards`: it drops `No milestone` when every one of its items is
|
|
32
|
+
* dropped (its progress is then `0` of `0`, since dropped items are never
|
|
33
|
+
* counted).
|
|
34
|
+
*/
|
|
35
|
+
export function timelineMilestones(planning: Planning, known: Map<string, { href: string | null }>): TimelineMilestone[] {
|
|
36
|
+
return milestoneCards(planning).map((summary) => {
|
|
37
|
+
const key = summary.id ?? 'none';
|
|
38
|
+
const { done, total } = summary.progress;
|
|
39
|
+
|
|
40
|
+
return {
|
|
41
|
+
id: summary.id,
|
|
42
|
+
key,
|
|
43
|
+
name: summary.name,
|
|
44
|
+
href: known.get(key)?.href ?? null,
|
|
45
|
+
isFocus: summary.isFocus,
|
|
46
|
+
status: parseMilestoneStatus(summary.status),
|
|
47
|
+
target: normaliseTarget(summary.target),
|
|
48
|
+
progress: { done, total, percent: total === 0 ? 0 : Math.round((done / total) * 100) },
|
|
49
|
+
};
|
|
50
|
+
});
|
|
51
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// planning.json's ADRs as the `adrs` content collection, with each section's
|
|
2
|
+
// Markdown rendered to HTML by the site's own Markdown processor (ADR-002), so
|
|
3
|
+
// an ADR page shows its tables, lists, and code as written.
|
|
4
|
+
|
|
5
|
+
import type { Loader } from 'astro/loaders';
|
|
6
|
+
|
|
7
|
+
import { loadPlanning } from '../lib/planning';
|
|
8
|
+
import type { Adr } from '../lib/planning-types';
|
|
9
|
+
|
|
10
|
+
export const ADR_SECTIONS = [
|
|
11
|
+
{ key: 'context', label: 'Context' },
|
|
12
|
+
{ key: 'decision', label: 'Decision' },
|
|
13
|
+
{ key: 'alternatives', label: 'Alternatives' },
|
|
14
|
+
{ key: 'consequences', label: 'Consequences' },
|
|
15
|
+
] as const;
|
|
16
|
+
|
|
17
|
+
export type AdrSection = (typeof ADR_SECTIONS)[number]['key'];
|
|
18
|
+
|
|
19
|
+
/** An ADR with each section as HTML: `null` when the section is missing, `''` when it is empty. */
|
|
20
|
+
export type RenderedAdr = Adr & { html: Record<AdrSection, string | null> };
|
|
21
|
+
|
|
22
|
+
export function adrsLoader(): Loader {
|
|
23
|
+
return {
|
|
24
|
+
name: 'adrs',
|
|
25
|
+
async load({ store, parseData, renderMarkdown }) {
|
|
26
|
+
store.clear();
|
|
27
|
+
|
|
28
|
+
for (const adr of loadPlanning().adrs) {
|
|
29
|
+
const html = {} as Record<AdrSection, string | null>;
|
|
30
|
+
|
|
31
|
+
for (const { key } of ADR_SECTIONS) {
|
|
32
|
+
const markdown = adr[key];
|
|
33
|
+
|
|
34
|
+
html[key] = markdown === null ? null : markdown.trim() === '' ? '' : (await renderMarkdown(markdown)).html;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const id = adr.id.toLowerCase();
|
|
38
|
+
|
|
39
|
+
store.set({ id, data: await parseData({ id, data: { ...adr, html } }) });
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
};
|
|
43
|
+
}
|
package/src/loaders/repo-docs.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// Markdown from anywhere in the repository as Starlight's `docs` collection,
|
|
2
|
-
// read in place. The matching and parsing live in lib/repo-docs.
|
|
2
|
+
// read in place. The matching and parsing live in lib/repo-docs.ts, shared with
|
|
3
3
|
// the sidebar.
|
|
4
4
|
|
|
5
5
|
import { readFile } from 'node:fs/promises';
|
|
@@ -8,8 +8,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
|
8
8
|
|
|
9
9
|
import type { Loader } from 'astro/loaders';
|
|
10
10
|
|
|
11
|
-
import type { DocsSource } from '../../
|
|
12
|
-
import { pagesOf, readPage } from '../../lib/repo-docs.
|
|
11
|
+
import type { DocsSource } from '../../lib/types.ts';
|
|
12
|
+
import { pagesOf, readPage } from '../../lib/repo-docs.ts';
|
|
13
13
|
|
|
14
14
|
/** Starlight's `docs` collection over every source; `root` is the docs root, absolute or relative to the site root. */
|
|
15
15
|
export function repoDocsLoader(options: { root: string; sources: DocsSource[] }): Loader {
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
// The not-found page. Starlight's own 404 route is off (`disable404Route` in
|
|
3
|
+
// lib/index.ts): it reads a `404` entry from the docs collection, and Astro
|
|
4
|
+
// warns on every build when there is none, while a draft entry would print
|
|
5
|
+
// Starlight's "This content is a draft" notice on the live page. This page is
|
|
6
|
+
// Starlight's splash 404 without either: the same title and tagline, out of search.
|
|
7
|
+
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
<StarlightPage
|
|
11
|
+
frontmatter={{
|
|
12
|
+
title: '404',
|
|
13
|
+
template: 'splash',
|
|
14
|
+
editUrl: false,
|
|
15
|
+
pagefind: false,
|
|
16
|
+
hero: { tagline: Astro.locals.t('404.text'), actions: [] },
|
|
17
|
+
}}
|
|
18
|
+
/>
|
package/src/pages/index.astro
CHANGED
|
@@ -126,7 +126,7 @@ const redRisks = planning.risks.open.filter((risk) => risk.rag === 'red');
|
|
|
126
126
|
{config.views.inbox && <li><a href="/plan/inbox/">Inbox</a> — parked ideas, bugs and questions</li>}
|
|
127
127
|
{config.views.briefs && <li><a href="/plan/briefs/">Briefs</a> — shaped ideas and their decisions</li>}
|
|
128
128
|
{config.views.strategy && <li><a href="/plan/strategy/">Strategy</a> — the vision, bets, assumptions and decisions</li>}
|
|
129
|
-
<li>Search — every page above is in the site search once
|
|
129
|
+
<li>Search — every page above is in the site search once the site is built (<code>pm-docs-site build</code>)</li>
|
|
130
130
|
{config.docs !== null && <li>Documentation — the repository's Markdown, grouped in the sidebar</li>}
|
|
131
131
|
</ul>
|
|
132
132
|
</section>
|
|
@@ -1,42 +1,28 @@
|
|
|
1
1
|
---
|
|
2
2
|
// The task board, column by column, from planning.json's `board.columns` —
|
|
3
|
-
// the same columns the pm-board skill renders
|
|
4
|
-
//
|
|
3
|
+
// the same columns the pm-board skill renders — as a server-rendered React
|
|
4
|
+
// island (src/components/board/Board.tsx) that filters the cards and
|
|
5
|
+
// collapses columns. Each card links to its item's page; a plain click opens
|
|
6
|
+
// the item popup (src/scripts/plan.ts) from the templates below.
|
|
5
7
|
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
|
|
6
8
|
|
|
9
|
+
import Board from '../../components/board/Board';
|
|
7
10
|
import ExportStamp from '../../components/ExportStamp.astro';
|
|
8
11
|
import ItemDetail from '../../components/ItemDetail.astro';
|
|
9
12
|
import ItemDialog from '../../components/ItemDialog.astro';
|
|
10
|
-
import KanbanItemCard from '../../components/lib/KanbanItemCard.astro';
|
|
11
|
-
import TaskKanbanCard from '../../components/lib/TaskKanbanCard.astro';
|
|
12
13
|
import PlanInteractions from '../../components/PlanInteractions.astro';
|
|
13
|
-
import {
|
|
14
|
+
import { boardCards } from '../../lib/board-data';
|
|
15
|
+
import { loadPlanning } from '../../lib/planning';
|
|
14
16
|
import { siteRefs } from '../../lib/references';
|
|
15
|
-
import type { Card } from '../../lib/planning-types';
|
|
16
17
|
import '../../styles/components.css';
|
|
18
|
+
import '../../styles/kanban.css';
|
|
17
19
|
|
|
18
20
|
const planning = loadPlanning();
|
|
19
|
-
const { columns } = planning.board;
|
|
20
21
|
const { known } = siteRefs();
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
const
|
|
25
|
-
const milestoneKey = (id: string | null) => (id ? (items.get(id)?.milestone ?? 'none') : 'none');
|
|
26
|
-
const tagOf = (id: string | null) => {
|
|
27
|
-
const key = milestoneKey(id);
|
|
28
|
-
|
|
29
|
-
return { tag: key === 'none' ? 'No milestone' : key, tagHref: known.get(key)?.href ?? null };
|
|
30
|
-
};
|
|
31
|
-
|
|
32
|
-
const progress = planProgress(planning.plan);
|
|
33
|
-
const taskPriority = (size: Card['size']) => ({ low: 'low', medium: 'med', high: 'high' } as const)[sizeToPriority(size)];
|
|
34
|
-
|
|
35
|
-
const queued = [
|
|
36
|
-
{ name: 'next', title: 'Next', cards: columns.next },
|
|
37
|
-
{ name: 'foryou', title: 'For you', cards: columns.foryou },
|
|
38
|
-
{ name: 'waiting', title: 'Waiting', cards: columns.waiting },
|
|
39
|
-
];
|
|
22
|
+
const cards = boardCards(planning, known);
|
|
23
|
+
const milestones = planning.strategy.milestones.map(({ id, name }) => ({ id, name }));
|
|
24
|
+
// One popup template per item with a page, even when the same item is on two cards.
|
|
25
|
+
const details = [...new Set(cards.filter((card) => card.href && card.id).map((card) => card.id!))];
|
|
40
26
|
---
|
|
41
27
|
|
|
42
28
|
<StarlightPage
|
|
@@ -47,94 +33,9 @@ const queued = [
|
|
|
47
33
|
|
|
48
34
|
<!-- `not-content`: Starlight's prose spacing would push every column after the first down. -->
|
|
49
35
|
<div class="plan-columns not-content">
|
|
50
|
-
<
|
|
51
|
-
<h2 id="col-now">
|
|
52
|
-
<button type="button" class="plan-column__toggle" aria-expanded="true" aria-controls="col-now-cards">
|
|
53
|
-
<span class="plan-column__name">Now</span> <span class="plan-column__count">{columns.now.length}</span>
|
|
54
|
-
</button>
|
|
55
|
-
</h2>
|
|
56
|
-
<div class="plan-column__cards" id="col-now-cards">
|
|
57
|
-
{columns.now.length === 0 && <p class="plan-empty">Nothing here</p>}
|
|
58
|
-
{
|
|
59
|
-
columns.now.map((card) => (
|
|
60
|
-
<>
|
|
61
|
-
<TaskKanbanCard
|
|
62
|
-
task={`${card.id} ${card.title}`}
|
|
63
|
-
date={planning.now.started ?? ''}
|
|
64
|
-
assigneeInitials={initials(card.owner)}
|
|
65
|
-
priority={taskPriority(card.size)}
|
|
66
|
-
progress={progress}
|
|
67
|
-
href={hrefOf(card.id)}
|
|
68
|
-
itemId={card.id}
|
|
69
|
-
/>
|
|
70
|
-
{hrefOf(card.id) && <ItemDetail id={card.id} />}
|
|
71
|
-
</>
|
|
72
|
-
))
|
|
73
|
-
}
|
|
74
|
-
</div>
|
|
75
|
-
</section>
|
|
76
|
-
|
|
77
|
-
{
|
|
78
|
-
queued.map((column) => (
|
|
79
|
-
<section class="plan-column" data-column={column.name} aria-labelledby={`col-${column.name}`}>
|
|
80
|
-
<h2 id={`col-${column.name}`}>
|
|
81
|
-
<button type="button" class="plan-column__toggle" aria-expanded="true" aria-controls={`col-${column.name}-cards`}>
|
|
82
|
-
<span class="plan-column__name">{column.title}</span> <span class="plan-column__count">{column.cards.length}</span>
|
|
83
|
-
</button>
|
|
84
|
-
</h2>
|
|
85
|
-
<div class="plan-column__cards" id={`col-${column.name}-cards`}>
|
|
86
|
-
{column.cards.length === 0 && <p class="plan-empty">Nothing here</p>}
|
|
87
|
-
{column.cards.map((card) => (
|
|
88
|
-
<>
|
|
89
|
-
<KanbanItemCard
|
|
90
|
-
title={`${card.id} ${card.title}`}
|
|
91
|
-
{...tagOf(card.id)}
|
|
92
|
-
assignee={initials(card.owner)}
|
|
93
|
-
dueDate={card.detail ?? ''}
|
|
94
|
-
priority={sizeToPriority(card.size)}
|
|
95
|
-
commentsCount={0}
|
|
96
|
-
attachmentsCount={0}
|
|
97
|
-
href={hrefOf(card.id)}
|
|
98
|
-
itemId={card.id}
|
|
99
|
-
/>
|
|
100
|
-
{hrefOf(card.id) && <ItemDetail id={card.id} />}
|
|
101
|
-
</>
|
|
102
|
-
))}
|
|
103
|
-
</div>
|
|
104
|
-
</section>
|
|
105
|
-
))
|
|
106
|
-
}
|
|
107
|
-
|
|
108
|
-
<section class="plan-column" data-column="done" aria-labelledby="col-done">
|
|
109
|
-
<h2 id="col-done">
|
|
110
|
-
<button type="button" class="plan-column__toggle" aria-expanded="true" aria-controls="col-done-cards">
|
|
111
|
-
<span class="plan-column__name">Done</span> <span class="plan-column__count">{columns.done.length}</span>
|
|
112
|
-
</button>
|
|
113
|
-
</h2>
|
|
114
|
-
<div class="plan-column__cards" id="col-done-cards">
|
|
115
|
-
{columns.done.length === 0 && <p class="plan-empty">Nothing here</p>}
|
|
116
|
-
{
|
|
117
|
-
columns.done.map((entry) => (
|
|
118
|
-
// The result can run to a paragraph; it is on the Log page, not squeezed into a tag.
|
|
119
|
-
<>
|
|
120
|
-
<KanbanItemCard
|
|
121
|
-
title={entry.id ? `${entry.id} ${entry.title}` : entry.title}
|
|
122
|
-
{...tagOf(entry.id)}
|
|
123
|
-
assignee={initials(entry.owner)}
|
|
124
|
-
dueDate={entry.date}
|
|
125
|
-
priority="low"
|
|
126
|
-
commentsCount={0}
|
|
127
|
-
attachmentsCount={0}
|
|
128
|
-
href={hrefOf(entry.id)}
|
|
129
|
-
itemId={entry.id ?? undefined}
|
|
130
|
-
/>
|
|
131
|
-
{entry.id && hrefOf(entry.id) && <ItemDetail id={entry.id} />}
|
|
132
|
-
</>
|
|
133
|
-
))
|
|
134
|
-
}
|
|
135
|
-
</div>
|
|
136
|
-
</section>
|
|
36
|
+
<Board client:load cards={cards} milestones={milestones} />
|
|
137
37
|
</div>
|
|
138
38
|
|
|
39
|
+
{details.map((id) => <ItemDetail id={id} />)}
|
|
139
40
|
<ItemDialog />
|
|
140
41
|
</StarlightPage>
|
package/src/pages/plan/log.astro
CHANGED
|
@@ -7,10 +7,13 @@ import ExportStamp from '../../components/ExportStamp.astro';
|
|
|
7
7
|
import LinkedText from '../../components/LinkedText.astro';
|
|
8
8
|
import RefLink from '../../components/RefLink.astro';
|
|
9
9
|
import { docsHref, loadPlanning } from '../../lib/planning';
|
|
10
|
+
import { siteRefs } from '../../lib/references';
|
|
10
11
|
import '../../styles/components.css';
|
|
11
12
|
|
|
12
13
|
const planning = loadPlanning();
|
|
13
14
|
// `activity` carries no plan path; the Done log does.
|
|
15
|
+
// An entry whose ID has no page prints the ID, then its title with the known IDs in it linked.
|
|
16
|
+
const { known } = siteRefs();
|
|
14
17
|
const plans = new Map(planning.log.done.filter((entry) => entry.id).map((entry) => [entry.id, entry.plan]));
|
|
15
18
|
---
|
|
16
19
|
|
|
@@ -38,7 +41,21 @@ const plans = new Map(planning.log.done.filter((entry) => entry.id).map((entry)
|
|
|
38
41
|
<span class={`log-kind log-kind--${entry.kind}`}>{entry.kind}</span>
|
|
39
42
|
</td>
|
|
40
43
|
<td>
|
|
41
|
-
{entry.id
|
|
44
|
+
{entry.id && known.get(entry.id)?.href ? (
|
|
45
|
+
<RefLink ref={entry.id} />
|
|
46
|
+
) : entry.id ? (
|
|
47
|
+
<>
|
|
48
|
+
{entry.id}
|
|
49
|
+
{entry.title && (
|
|
50
|
+
<>
|
|
51
|
+
{' '}
|
|
52
|
+
<LinkedText text={entry.title} />
|
|
53
|
+
</>
|
|
54
|
+
)}
|
|
55
|
+
</>
|
|
56
|
+
) : (
|
|
57
|
+
<LinkedText text={entry.title} />
|
|
58
|
+
)}
|
|
42
59
|
{plan && (
|
|
43
60
|
<>
|
|
44
61
|
{' '}
|
|
@@ -1,9 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
// The roadmap by milestone, in strategy order: what is done, what is in
|
|
3
|
-
// progress, and what is queued, all from planning.json.
|
|
3
|
+
// progress, and what is queued, all from planning.json. The milestone
|
|
4
|
+
// timeline (src/components/timeline/Timeline.tsx) sits above the sections.
|
|
5
|
+
// Its inline script runs as the page is parsed, before the strip paints: a
|
|
6
|
+
// `?layout=vertical` link hides the strip until the island has rendered it
|
|
7
|
+
// vertical and deleted the mark (useTimelineLayout.ts), so it never flashes
|
|
8
|
+
// horizontal first. The mark is set on this page only; timeline.css reveals
|
|
9
|
+
// the strip after 3s if the island never loads. It must stay in step with
|
|
10
|
+
// parseTimelineQuery in src/lib/timeline.ts.
|
|
4
11
|
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
|
|
5
12
|
|
|
6
13
|
import ExportStamp from '../../components/ExportStamp.astro';
|
|
14
|
+
import Timeline from '../../components/timeline/Timeline';
|
|
7
15
|
import ItemDetail from '../../components/ItemDetail.astro';
|
|
8
16
|
import ItemDialog from '../../components/ItemDialog.astro';
|
|
9
17
|
import LinkedText from '../../components/LinkedText.astro';
|
|
@@ -12,10 +20,14 @@ import PlanInteractions from '../../components/PlanInteractions.astro';
|
|
|
12
20
|
import RefLink from '../../components/RefLink.astro';
|
|
13
21
|
import { loadPlanning, roadmapGroups } from '../../lib/planning';
|
|
14
22
|
import { siteRefs } from '../../lib/references';
|
|
23
|
+
import { timelineMilestones } from '../../lib/timeline';
|
|
15
24
|
import '../../styles/components.css';
|
|
25
|
+
import '../../styles/timeline.css';
|
|
16
26
|
|
|
17
27
|
const { known } = siteRefs();
|
|
18
|
-
const
|
|
28
|
+
const planning = loadPlanning();
|
|
29
|
+
const milestones = timelineMilestones(planning, known);
|
|
30
|
+
const groups = roadmapGroups(planning).map((group) => ({
|
|
19
31
|
...group,
|
|
20
32
|
events: group.events.map((event) => {
|
|
21
33
|
const href = event.id ? known.get(event.id)?.href : null;
|
|
@@ -28,15 +40,21 @@ const groups = roadmapGroups(loadPlanning()).map((group) => ({
|
|
|
28
40
|
<StarlightPage frontmatter={{ title: 'Roadmap', description: 'Milestones in order, with what is done, in progress and queued.', tableOfContents: false }}>
|
|
29
41
|
<ExportStamp />
|
|
30
42
|
|
|
43
|
+
<script is:inline>
|
|
44
|
+
if (new URLSearchParams(location.search).get('layout') === 'vertical') document.documentElement.dataset.timelinePending = '';
|
|
45
|
+
</script>
|
|
46
|
+
<Timeline client:load milestones={milestones} />
|
|
47
|
+
|
|
31
48
|
{
|
|
32
49
|
groups.map((group) => (
|
|
33
50
|
<section class="roadmap-group">
|
|
34
51
|
<h2>
|
|
35
|
-
<RefLink ref={group.milestone?.id ?? 'none'} />
|
|
52
|
+
<RefLink ref={group.milestone?.id ?? 'none'} fallback={group.milestone ? `${group.milestone.id} ${group.milestone.name}` : 'No milestone'} />
|
|
36
53
|
{group.milestone?.isFocus && <span class="roadmap-focus">Focus</span>}
|
|
37
54
|
</h2>
|
|
38
55
|
<p class="roadmap-meta">
|
|
39
56
|
{group.milestone && <strong>{group.milestone.status}</strong>}
|
|
57
|
+
{group.milestone?.target && ` · target ${group.milestone.target}`}
|
|
40
58
|
{group.milestone && ' · '}
|
|
41
59
|
{group.progress.done} of {group.progress.total} done
|
|
42
60
|
{group.milestone?.exitCriteria && (
|