@purview-dev/pm-docs-site 0.1.0-pre.2 → 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 +70 -10
- package/dist/cli.js +4 -3
- 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.js +38 -4
- package/dist/options.js +1 -1
- package/dist/schema-version.d.ts +17 -0
- package/dist/schema-version.js +30 -1
- package/dist/sidebar.js +2 -0
- package/dist/site-options.js +5 -0
- package/dist/types.d.ts +2 -2
- package/lib/schema-version.ts +36 -1
- package/lib/types.ts +48 -0
- package/package.json +7 -3
- 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/RefLink.astro +7 -4
- package/src/components/board/Board.tsx +16 -8
- package/src/components/board/KanbanItemCard.tsx +4 -2
- package/src/components/board/TaskKanbanCard.tsx +4 -2
- 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 +39 -6
- package/src/components/timeline/useTimelineLayout.ts +2 -2
- package/src/content.config.ts +22 -6
- 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 +30 -16
- package/src/lib/ref-boundary.ts +19 -0
- package/src/lib/references.ts +66 -7
- package/src/lib/timeline-state.ts +119 -0
- package/src/lib/timeline.ts +22 -127
- package/src/loaders/adrs.ts +43 -0
- package/src/pages/404.astro +18 -0
- package/src/pages/index.astro +1 -1
- package/src/pages/plan/log.astro +18 -1
- package/src/pages/plan/roadmap.astro +1 -1
- 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 +33 -1
- package/src/styles/components.css +117 -3
- package/src/styles/graph.css +296 -0
- package/src/styles/timeline.css +1 -1
package/src/lib/planning.ts
CHANGED
|
@@ -11,8 +11,8 @@ import config from 'virtual:pm-docs-site/config';
|
|
|
11
11
|
|
|
12
12
|
import type { DocsSource } from '../../lib/types.ts';
|
|
13
13
|
import { pagesOf } from '../../lib/repo-docs.ts';
|
|
14
|
-
import {
|
|
15
|
-
import type { Brief, InboxEntry, Level, Milestone, Owner, Planning, Rag, Risk, RoadmapItem, Size, Stage } from './planning-types';
|
|
14
|
+
import { parseExport, PlanningExportError, SUPPORTED_SCHEMA_VERSIONS } from '../../lib/schema-version.ts';
|
|
15
|
+
import type { Adr, Brief, InboxEntry, Level, Milestone, Owner, Planning, Rag, Risk, RoadmapItem, Size, Stage } from './planning-types';
|
|
16
16
|
|
|
17
17
|
export { PlanningExportError, SUPPORTED_SCHEMA_VERSIONS };
|
|
18
18
|
|
|
@@ -26,17 +26,7 @@ export function loadPlanning(path: string = config.planning): Planning {
|
|
|
26
26
|
throw new PlanningExportError(`No plan export at ${path}.`);
|
|
27
27
|
}
|
|
28
28
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
try {
|
|
32
|
-
planning = JSON.parse(text);
|
|
33
|
-
} catch (error) {
|
|
34
|
-
throw new PlanningExportError(`${path} is not valid JSON (${(error as Error).message}).`);
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
checkSchemaVersion(planning.schemaVersion, path);
|
|
38
|
-
|
|
39
|
-
return planning as Planning;
|
|
29
|
+
return parseExport(text, path) as unknown as Planning;
|
|
40
30
|
}
|
|
41
31
|
|
|
42
32
|
/** Board-card priority from item size — the PM state has no priority of its own. */
|
|
@@ -146,7 +136,7 @@ export function roadmapGroups(planning: Planning): RoadmapGroup[] {
|
|
|
146
136
|
progress: progressFor(milestone.id),
|
|
147
137
|
}));
|
|
148
138
|
|
|
149
|
-
// The same rule as
|
|
139
|
+
// The same rule as milestoneCards: shown only when it counts an item.
|
|
150
140
|
const unassignedProgress = progressFor(null);
|
|
151
141
|
|
|
152
142
|
return unassignedProgress.total > 0 ? [...groups, { milestone: null, events: eventsFor(null), progress: unassignedProgress }] : groups;
|
|
@@ -300,8 +290,11 @@ export function features(planning: Planning): Feature[] {
|
|
|
300
290
|
title: planning.now.item.title,
|
|
301
291
|
state: 'now' as const,
|
|
302
292
|
milestone: milestoneId(planning.now.milestone, known),
|
|
303
|
-
owner: planning.
|
|
304
|
-
size: planning.
|
|
293
|
+
owner: planning.now.item.owner,
|
|
294
|
+
size: planning.now.item.size,
|
|
295
|
+
serves: planning.now.item.serves,
|
|
296
|
+
dependsOn: planning.now.item.dependsOn,
|
|
297
|
+
revisits: planning.now.item.revisits,
|
|
305
298
|
doneWhen: planning.now.doneWhen,
|
|
306
299
|
brief: planning.now.brief,
|
|
307
300
|
stage: planning.now.stage,
|
|
@@ -347,6 +340,16 @@ export function dependents(all: Feature[], id: string): Feature[] {
|
|
|
347
340
|
return all.filter((feature) => feature.dependsOn.includes(id));
|
|
348
341
|
}
|
|
349
342
|
|
|
343
|
+
/** The ADRs whose `Item` is this item, by ID number. */
|
|
344
|
+
export function adrsOf(planning: Planning, itemId: string): Adr[] {
|
|
345
|
+
return planning.adrs.filter((adr) => adr.item === itemId).sort((a, b) => Number(a.id.slice(4)) - Number(b.id.slice(4)));
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/** The page of one ADR on this site. */
|
|
349
|
+
export function adrHref(id: string): string {
|
|
350
|
+
return `/plan/decisions/${id.toLowerCase()}/`;
|
|
351
|
+
}
|
|
352
|
+
|
|
350
353
|
/** The brief a feature links to, by its `Brief` path, else by the brief's own ID. */
|
|
351
354
|
export function briefOf(planning: Planning, feature: Pick<Feature, 'id' | 'brief'>): Brief | null {
|
|
352
355
|
return planning.briefs.find((brief) => brief.path === feature.brief) ?? planning.briefs.find((brief) => brief.id === feature.id) ?? null;
|
|
@@ -394,6 +397,17 @@ export function milestoneSummaries(planning: Planning, all: Feature[] = features
|
|
|
394
397
|
return unassigned.features.length > 0 ? [...groups, unassigned] : groups;
|
|
395
398
|
}
|
|
396
399
|
|
|
400
|
+
/**
|
|
401
|
+
* `milestoneSummaries`, with `No milestone` dropped when every unassigned
|
|
402
|
+
* item is dropped (its `progress.total` is then `0`, since dropped items are
|
|
403
|
+
* never counted). The Milestones page and the Roadmap page's timeline share
|
|
404
|
+
* this rule; `milestoneSummaries` itself is unchanged, because the `none`
|
|
405
|
+
* milestone page still lists a dropped unassigned item.
|
|
406
|
+
*/
|
|
407
|
+
export function milestoneCards(planning: Planning, all: Feature[] = features(planning)): MilestoneSummary[] {
|
|
408
|
+
return milestoneSummaries(planning, all).filter((summary) => summary.id !== null || summary.progress.total > 0);
|
|
409
|
+
}
|
|
410
|
+
|
|
397
411
|
/** An inbox file's source as a card's initials: `agent (…)` → `AG`, anything else (the user) → `YOU`. */
|
|
398
412
|
export function sourceInitials(source: string | null): string {
|
|
399
413
|
return /^agent\b/i.test(source?.trim() ?? '') ? 'AG' : 'YOU';
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// Where a reference (an ID or a brief path) may start and end in prose. The
|
|
2
|
+
// site's links (linkify) and the link test's scanner (test/scan.ts) both build
|
|
3
|
+
// their patterns here, so a reference is linked exactly where the test looks
|
|
4
|
+
// for one. No imports, so the test helper can load it outside Astro.
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Not inside a word, a path, or a hyphenated token. An ID after `/` is
|
|
8
|
+
* deliberately not linked (`M1/M2` links only `M1`, and `./planning/briefs/x.md`
|
|
9
|
+
* stays plain), because a `/` also starts a path segment (`src/M1`).
|
|
10
|
+
* test/references.test.ts pins it.
|
|
11
|
+
*/
|
|
12
|
+
export const REF_BEFORE = String.raw`(?<![\w/-])`;
|
|
13
|
+
/** Not followed by more of a word or a hyphenated token. */
|
|
14
|
+
export const REF_AFTER = String.raw`(?![\w-])`;
|
|
15
|
+
|
|
16
|
+
/** A global pattern for any of `alternatives` (already escaped; longest first) at reference boundaries. */
|
|
17
|
+
export function refPattern(alternatives: string[]): RegExp {
|
|
18
|
+
return new RegExp(`${REF_BEFORE}(?:${alternatives.join('|')})${REF_AFTER}`, 'g');
|
|
19
|
+
}
|
package/src/lib/references.ts
CHANGED
|
@@ -6,12 +6,14 @@
|
|
|
6
6
|
import config from 'virtual:pm-docs-site/config';
|
|
7
7
|
|
|
8
8
|
import type { ViewName } from '../../lib/types.ts';
|
|
9
|
-
import {
|
|
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
|
+
}
|
package/src/lib/timeline.ts
CHANGED
|
@@ -2,31 +2,12 @@
|
|
|
2
2
|
// strategy order, their status and target text, and their progress. All from
|
|
3
3
|
// planning.json through milestoneSummaries; nothing here touches the DOM.
|
|
4
4
|
|
|
5
|
-
import {
|
|
5
|
+
import { milestoneCards, normaliseTarget } from './planning';
|
|
6
6
|
import type { Planning } from './planning-types';
|
|
7
|
+
import type { MilestoneStatus, TimelineMilestone } from './timeline-state';
|
|
7
8
|
|
|
8
9
|
export { normaliseTarget } from './planning';
|
|
9
|
-
|
|
10
|
-
export type MilestoneState = 'active' | 'planned' | 'done' | 'other';
|
|
11
|
-
|
|
12
|
-
export interface MilestoneStatus {
|
|
13
|
-
state: MilestoneState;
|
|
14
|
-
label: string;
|
|
15
|
-
doneOn: string | null;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
export interface TimelineMilestone {
|
|
19
|
-
/** `null` for the no-milestone card. */
|
|
20
|
-
id: string | null;
|
|
21
|
-
/** `id`, or `none` for the no-milestone card. */
|
|
22
|
-
key: string;
|
|
23
|
-
name: string;
|
|
24
|
-
href: string | null;
|
|
25
|
-
isFocus: boolean;
|
|
26
|
-
status: MilestoneStatus;
|
|
27
|
-
target: string | null;
|
|
28
|
-
progress: { done: number; total: number; percent: number };
|
|
29
|
-
}
|
|
10
|
+
export * from './timeline-state';
|
|
30
11
|
|
|
31
12
|
const DONE = /^done(?:\s*\((\d{4}-\d{2}-\d{2})\))?$/i;
|
|
32
13
|
|
|
@@ -46,111 +27,25 @@ export function parseMilestoneStatus(status: string | null): MilestoneStatus {
|
|
|
46
27
|
}
|
|
47
28
|
|
|
48
29
|
/**
|
|
49
|
-
* The timeline's cards, in strategy order, then `No milestone` last
|
|
50
|
-
* `No milestone`
|
|
51
|
-
* then `0` of `0`, since dropped items are never
|
|
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).
|
|
52
34
|
*/
|
|
53
35
|
export function timelineMilestones(planning: Planning, known: Map<string, { href: string | null }>): TimelineMilestone[] {
|
|
54
|
-
return
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
};
|
|
70
|
-
});
|
|
71
|
-
}
|
|
72
|
-
|
|
73
|
-
// Layout URL state, zoom maths, and the wheel rule: the strip's horizontal or
|
|
74
|
-
// vertical layout lives in the URL (never the zoom); zoom lives only in the
|
|
75
|
-
// island's own state, snapped to a fixed step; and the wheel rule tells a
|
|
76
|
-
// plain vertical wheel apart from a pinch-zoom gesture and from a gesture the
|
|
77
|
-
// strip's native horizontal scrolling already handles.
|
|
78
|
-
|
|
79
|
-
export type TimelineLayout = 'horizontal' | 'vertical';
|
|
80
|
-
|
|
81
|
-
/** The layout named by `?layout=`; anything other than the exact value `vertical` is horizontal. */
|
|
82
|
-
export function parseTimelineQuery(search: string): TimelineLayout {
|
|
83
|
-
return new URLSearchParams(search).get('layout') === 'vertical' ? 'vertical' : 'horizontal';
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
/** `search` with `layout` set for `vertical` (appended last) or removed for `horizontal`; keeps every other parameter. `''` when none remain. */
|
|
87
|
-
export function timelineQuery(layout: TimelineLayout, search: string): string {
|
|
88
|
-
const params = new URLSearchParams(search);
|
|
89
|
-
|
|
90
|
-
params.delete('layout');
|
|
91
|
-
|
|
92
|
-
if (layout === 'vertical') params.append('layout', 'vertical');
|
|
93
|
-
|
|
94
|
-
const query = params.toString();
|
|
95
|
-
|
|
96
|
-
return query === '' ? '' : `?${query}`;
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
export const ZOOM = { min: 0.5, max: 2, step: 0.25, default: 1 } as const;
|
|
100
|
-
|
|
101
|
-
/** The wheel delta, in pixels, that one pinch-zoom notch accumulates before the zoom steps. */
|
|
102
|
-
export const PINCH_STEP = 50;
|
|
103
|
-
|
|
104
|
-
const ZOOM_TICKS_PER_UNIT = Math.round(1 / ZOOM.step);
|
|
105
|
-
const ZOOM_MIN_TICKS = Math.round(ZOOM.min * ZOOM_TICKS_PER_UNIT);
|
|
106
|
-
const ZOOM_MAX_TICKS = Math.round(ZOOM.max * ZOOM_TICKS_PER_UNIT);
|
|
107
|
-
|
|
108
|
-
/** `zoom` snapped to the nearest step, moved one step in `direction`, then clamped to `[ZOOM.min, ZOOM.max]`. Integer ticks avoid float drift. */
|
|
109
|
-
export function zoomStep(zoom: number, direction: 1 | -1): number {
|
|
110
|
-
const ticks = Math.round(zoom * ZOOM_TICKS_PER_UNIT) + direction;
|
|
111
|
-
const clamped = Math.min(ZOOM_MAX_TICKS, Math.max(ZOOM_MIN_TICKS, ticks));
|
|
112
|
-
|
|
113
|
-
return clamped / ZOOM_TICKS_PER_UNIT;
|
|
114
|
-
}
|
|
115
|
-
|
|
116
|
-
/**
|
|
117
|
-
* One wheel event's effect on zoom. A mouse notch (`deltaMode !== 0`, or
|
|
118
|
-
* pixels already past `PINCH_STEP`) steps immediately and clears `pending`. A
|
|
119
|
-
* trackpad pinch accumulates `pending` in pixels and steps once per
|
|
120
|
-
* `PINCH_STEP` crossed, keeping the remainder. `deltaY` `0` is a no-op.
|
|
121
|
-
*/
|
|
122
|
-
export function zoomFromWheel(zoom: number, pending: number, deltaY: number, deltaMode: number): { zoom: number; pending: number } {
|
|
123
|
-
if (deltaY === 0) return { zoom, pending };
|
|
124
|
-
|
|
125
|
-
if (deltaMode !== 0 || Math.abs(deltaY) >= PINCH_STEP) {
|
|
126
|
-
return { zoom: zoomStep(zoom, deltaY < 0 ? 1 : -1), pending: 0 };
|
|
127
|
-
}
|
|
128
|
-
|
|
129
|
-
let nextZoom = zoom;
|
|
130
|
-
let nextPending = pending + deltaY;
|
|
131
|
-
|
|
132
|
-
while (Math.abs(nextPending) >= PINCH_STEP) {
|
|
133
|
-
const negative = nextPending < 0;
|
|
134
|
-
|
|
135
|
-
nextZoom = zoomStep(nextZoom, negative ? 1 : -1);
|
|
136
|
-
nextPending += negative ? PINCH_STEP : -PINCH_STEP;
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
return { zoom: nextZoom, pending: nextPending };
|
|
140
|
-
}
|
|
141
|
-
|
|
142
|
-
/** Whether the strip's own horizontal scrolling should consume this wheel event, with 1px of tolerance at either end. */
|
|
143
|
-
export function wheelScrollsStrip(
|
|
144
|
-
e: { deltaX: number; deltaY: number },
|
|
145
|
-
s: { scrollLeft: number; scrollWidth: number; clientWidth: number },
|
|
146
|
-
): boolean {
|
|
147
|
-
if (Math.abs(e.deltaX) >= Math.abs(e.deltaY)) return false;
|
|
148
|
-
if (s.scrollWidth <= s.clientWidth) return false;
|
|
149
|
-
|
|
150
|
-
const TOLERANCE = 1;
|
|
151
|
-
const maxScrollLeft = s.scrollWidth - s.clientWidth;
|
|
152
|
-
|
|
153
|
-
if (e.deltaY > 0) return s.scrollLeft < maxScrollLeft - TOLERANCE;
|
|
154
|
-
|
|
155
|
-
return s.scrollLeft > TOLERANCE;
|
|
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
|
+
});
|
|
156
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
|
+
}
|
|
@@ -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>
|
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
|
{' '}
|
|
@@ -49,7 +49,7 @@ const groups = roadmapGroups(planning).map((group) => ({
|
|
|
49
49
|
groups.map((group) => (
|
|
50
50
|
<section class="roadmap-group">
|
|
51
51
|
<h2>
|
|
52
|
-
<RefLink ref={group.milestone?.id ?? 'none'} />
|
|
52
|
+
<RefLink ref={group.milestone?.id ?? 'none'} fallback={group.milestone ? `${group.milestone.id} ${group.milestone.name}` : 'No milestone'} />
|
|
53
53
|
{group.milestone?.isFocus && <span class="roadmap-focus">Focus</span>}
|
|
54
54
|
</h2>
|
|
55
55
|
<p class="roadmap-meta">
|