@purview-dev/pm-docs-site 0.0.0-stage → 0.1.0-pre.2

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 (69) hide show
  1. package/LICENSE.md +9 -0
  2. package/README.md +219 -2
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +90 -0
  5. package/dist/index.d.ts +7 -0
  6. package/dist/index.js +118 -0
  7. package/dist/options.d.ts +5 -0
  8. package/dist/options.js +46 -0
  9. package/dist/repo-docs.d.ts +33 -0
  10. package/dist/repo-docs.js +94 -0
  11. package/dist/schema-version.d.ts +10 -0
  12. package/dist/schema-version.js +19 -0
  13. package/dist/sidebar.d.ts +10 -0
  14. package/dist/sidebar.js +30 -0
  15. package/dist/site-options.d.ts +9 -0
  16. package/dist/site-options.js +39 -0
  17. package/dist/types.d.ts +47 -0
  18. package/dist/types.js +4 -0
  19. package/lib/repo-docs.ts +124 -0
  20. package/lib/schema-version.ts +24 -0
  21. package/package.json +68 -5
  22. package/src/components/ExportStamp.astro +29 -0
  23. package/src/components/FeatureSummary.astro +160 -0
  24. package/src/components/FeatureTable.astro +64 -0
  25. package/src/components/ItemDetail.astro +16 -0
  26. package/src/components/ItemDialog.astro +16 -0
  27. package/src/components/LinkedFrom.astro +33 -0
  28. package/src/components/LinkedText.astro +12 -0
  29. package/src/components/PlanInteractions.astro +30 -0
  30. package/src/components/RefLink.astro +18 -0
  31. package/src/components/StateBadge.astro +15 -0
  32. package/src/components/board/Board.tsx +244 -0
  33. package/src/components/board/KanbanItemCard.tsx +129 -0
  34. package/src/components/board/LinkRuns.tsx +21 -0
  35. package/src/components/board/TaskKanbanCard.tsx +81 -0
  36. package/src/components/board/useBoardUrlState.ts +41 -0
  37. package/src/components/lib/KanbanItemCard.astro +264 -0
  38. package/src/components/lib/StatusTimelineFeed.astro +194 -0
  39. package/src/components/lib/TaskKanbanCard.astro +215 -0
  40. package/src/components/timeline/Timeline.tsx +159 -0
  41. package/src/components/timeline/useTimelineLayout.ts +39 -0
  42. package/src/content.config.ts +16 -0
  43. package/src/env.d.ts +7 -0
  44. package/src/lib/board-data.ts +84 -0
  45. package/src/lib/board.ts +209 -0
  46. package/src/lib/planning-types.ts +207 -0
  47. package/src/lib/planning.ts +415 -0
  48. package/src/lib/references.ts +360 -0
  49. package/src/lib/timeline.ts +156 -0
  50. package/src/loaders/repo-docs.ts +69 -0
  51. package/src/pages/index.astro +158 -0
  52. package/src/pages/plan/board.astro +41 -0
  53. package/src/pages/plan/log.astro +83 -0
  54. package/src/pages/plan/risks/[id].astro +72 -0
  55. package/src/pages/plan/risks.astro +263 -0
  56. package/src/pages/plan/roadmap.astro +108 -0
  57. package/src/routes/plan/briefs.astro +66 -0
  58. package/src/routes/plan/features/[id].astro +113 -0
  59. package/src/routes/plan/features/index.astro +29 -0
  60. package/src/routes/plan/inbox.astro +78 -0
  61. package/src/routes/plan/milestones/[milestone].astro +113 -0
  62. package/src/routes/plan/milestones/index.astro +56 -0
  63. package/src/routes/plan/now.astro +135 -0
  64. package/src/routes/plan/strategy.astro +194 -0
  65. package/src/scripts/plan.ts +40 -0
  66. package/src/styles/components.css +491 -0
  67. package/src/styles/kanban.css +277 -0
  68. package/src/styles/timeline.css +210 -0
  69. package/src/styles/width.css +4 -0
@@ -0,0 +1,360 @@
1
+ // Every reference the site links: what an ID or brief path points at, how prose
2
+ // is split into plain text and links, and (references) which pages link to
3
+ // each target. Links and `Linked from` lists both come from here, so they
4
+ // cannot disagree. All from planning.json.
5
+
6
+ import config from 'virtual:pm-docs-site/config';
7
+
8
+ import type { ViewName } from '../../lib/types.ts';
9
+ import { briefAnchor, briefOf, featureHref, features, loadPlanning, milestoneHref, milestoneSummaries, roadmapGroups, type Feature } from './planning';
10
+ import type { Planning } from './planning-types';
11
+
12
+ export type Views = Record<ViewName, boolean>;
13
+
14
+ export type TargetKind = 'item' | 'milestone' | 'risk' | 'brief';
15
+
16
+ export interface Target {
17
+ kind: TargetKind;
18
+ /** The ID, `none` for the No-milestone page, or the brief's path. */
19
+ key: string;
20
+ /** The page or anchor; `null` when that page is not built. */
21
+ href: string | null;
22
+ label: string;
23
+ }
24
+
25
+ /** The page of one open or closed risk, or a removed risk's row on the Risks page. */
26
+ export function riskHref(risk: { id: string }, removed = false): string {
27
+ return removed ? `/plan/risks/#${risk.id.toLowerCase()}` : `/plan/risks/${risk.id.toLowerCase()}/`;
28
+ }
29
+
30
+ /** Every link target in the export, keyed by `Target.key`. */
31
+ export function targets(planning: Planning, views: Views): Map<string, Target> {
32
+ const known = new Map<string, Target>();
33
+ const add = (target: Target) => known.set(target.key, target);
34
+ const all = features(planning);
35
+
36
+ for (const feature of all) {
37
+ add({ kind: 'item', key: feature.id, href: views.features ? featureHref(feature.id) : null, label: `${feature.id} ${feature.title}` });
38
+ }
39
+
40
+ for (const summary of milestoneSummaries(planning, all)) {
41
+ add({
42
+ kind: 'milestone',
43
+ key: summary.id ?? 'none',
44
+ href: views.milestones ? milestoneHref(summary.id) : null,
45
+ label: summary.id ? `${summary.id} ${summary.name}` : summary.name,
46
+ });
47
+ }
48
+
49
+ for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
50
+ add({ kind: 'risk', key: risk.id, href: riskHref(risk), label: `${risk.id} ${risk.title}` });
51
+ }
52
+
53
+ for (const risk of planning.risks.removed) {
54
+ add({ kind: 'risk', key: risk.id, href: riskHref(risk, true), label: `${risk.id} ${risk.title}` });
55
+ }
56
+
57
+ for (const brief of planning.briefs) {
58
+ add({ kind: 'brief', key: brief.path, href: views.briefs ? `/plan/briefs/#${briefAnchor(brief.path)}` : null, label: brief.title });
59
+ }
60
+
61
+ return known;
62
+ }
63
+
64
+ /** A run of prose: plain text, or the text of one known reference and its target. */
65
+ export interface Run {
66
+ text: string;
67
+ target?: Target;
68
+ }
69
+
70
+ const ID = String.raw`\b(?:RK-\d{3,}|R-\d{3,}|M\d+)\b`;
71
+ const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
72
+
73
+ /** Split text into plain runs and runs that are a known ID or brief path with a page. */
74
+ export function linkify(text: string, known: Map<string, Target>): Run[] {
75
+ const paths = [...known.values()].filter((target) => target.kind === 'brief').map((target) => escape(target.key));
76
+ const pattern = new RegExp([...paths, ID].join('|'), 'g');
77
+ const runs: Run[] = [];
78
+ const plain = (value: string) => {
79
+ if (!value) return;
80
+ const last = runs.at(-1);
81
+
82
+ if (last && !last.target) last.text += value;
83
+ else runs.push({ text: value });
84
+ };
85
+ let at = 0;
86
+
87
+ for (const match of text.matchAll(pattern)) {
88
+ const target = known.get(match[0]);
89
+
90
+ plain(text.slice(at, match.index));
91
+ if (target?.href) runs.push({ text: match[0], target });
92
+ else plain(match[0]);
93
+ at = match.index + match[0].length;
94
+ }
95
+
96
+ plain(text.slice(at));
97
+
98
+ return runs;
99
+ }
100
+
101
+ export type Relation = 'depends on' | 'revisits' | 'milestone' | 'affects' | 'mitigation' | 'related' | 'brief' | 'mentions' | 'listed';
102
+
103
+ /** The order and heading of each relation in a `Linked from` section. */
104
+ export const RELATION_LABELS: Record<Relation, string> = {
105
+ 'depends on': 'Depends on',
106
+ revisits: 'Revisits',
107
+ milestone: 'Milestone',
108
+ affects: 'Affects',
109
+ mitigation: 'Mitigation',
110
+ related: 'Related',
111
+ brief: 'Brief',
112
+ mentions: 'Mentioned on',
113
+ listed: 'Listed on',
114
+ };
115
+
116
+ /** One page that links a target, and how. */
117
+ export interface Backlink {
118
+ href: string;
119
+ label: string;
120
+ relation: Relation;
121
+ }
122
+
123
+ /**
124
+ * For every target, the pages that link to it. Each source page below must
125
+ * render exactly these links (through RefLink and LinkedText); the link test
126
+ * checks that every rendered link appears in its target's list.
127
+ */
128
+ export function references(planning: Planning, views: Views): Map<string, Backlink[]> {
129
+ const known = targets(planning, views);
130
+ const back = new Map<string, Backlink[]>([...known.keys()].map((key) => [key, []]));
131
+ const all = features(planning);
132
+ const summaries = milestoneSummaries(planning, all);
133
+ const milestoneKey = (id: string | null) => (id ?? (summaries.some((summary) => summary.id === null) ? 'none' : null));
134
+ // What a FeatureTable row shows in its last column.
135
+ const decision = (feature: Feature) => (feature.state === 'done' ? feature.result : feature.state === 'dropped' ? feature.reason : feature.doneWhen.join(' '));
136
+
137
+ const source = (href: string, label: string) => {
138
+ const link = (key: string | null | undefined, relation: Relation) => {
139
+ const target = key ? known.get(key) : undefined;
140
+ const list = key ? back.get(key) : undefined;
141
+
142
+ if (!target?.href || !list || target.href === href) return;
143
+ if (!list.some((entry) => entry.href === href && entry.relation === relation)) list.push({ href, label, relation });
144
+ };
145
+ const prose = (text: string | null | undefined, relation: Relation = 'mentions') => {
146
+ for (const run of linkify(text ?? '', known)) if (run.target) link(run.target.key, relation);
147
+ };
148
+
149
+ return { link, prose };
150
+ };
151
+
152
+ if (views.features) {
153
+ for (const feature of all) {
154
+ const page = source(featureHref(feature.id), `${feature.id} ${feature.title}`);
155
+
156
+ for (const dep of feature.dependsOn) page.link(dep, 'depends on');
157
+ page.link(feature.revisits, 'revisits');
158
+ page.link(milestoneKey(feature.milestone), 'milestone');
159
+ for (const other of all) {
160
+ if (other.dependsOn.includes(feature.id) || other.revisits === feature.id) page.link(other.id, 'related');
161
+ }
162
+
163
+ const brief = briefOf(planning, feature);
164
+
165
+ page.link(brief?.path ?? feature.brief, 'brief');
166
+ for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
167
+ if (risk.affects !== feature.id) continue;
168
+ page.link(risk.id, 'affects');
169
+ page.prose(risk.title);
170
+ }
171
+ for (const text of [...feature.doneWhen, feature.result, feature.reason, feature.note, feature.status?.reason, brief?.status, brief?.problem, brief?.decision]) page.prose(text);
172
+ for (const entry of planning.inbox) if (entry.affects === feature.id || entry.related.includes(feature.id)) page.prose(entry.title);
173
+ }
174
+ }
175
+
176
+ if (views.milestones) {
177
+ for (const summary of summaries) {
178
+ const page = source(milestoneHref(summary.id), summary.id ? `${summary.id} ${summary.name}` : summary.name);
179
+
180
+ for (const feature of summary.features) {
181
+ page.link(feature.id, 'listed');
182
+ page.prose(decision(feature));
183
+ }
184
+ page.prose(summary.exitCriteria);
185
+ if (summary.id) {
186
+ for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
187
+ if (risk.affects !== summary.id) continue;
188
+ page.link(risk.id, 'affects');
189
+ page.prose(risk.title);
190
+ }
191
+ }
192
+ }
193
+ }
194
+
195
+ for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
196
+ const page = source(riskHref(risk), `${risk.id} ${risk.title}`);
197
+
198
+ page.prose(risk.affects, 'affects');
199
+ page.prose(risk.trigger);
200
+ page.prose(risk.mitigation, 'mitigation');
201
+ for (const text of [risk.ragOverride, risk.raised, risk.reviewed, risk.closed]) page.prose(text);
202
+ }
203
+
204
+ const byId = new Map(all.map((feature) => [feature.id, feature]));
205
+ const board = source('/plan/board/', 'Board');
206
+ const { columns } = planning.board;
207
+
208
+ for (const card of [...columns.now, ...columns.next, ...columns.foryou, ...columns.waiting]) {
209
+ board.link(card.id, 'listed');
210
+ board.prose(card.detail);
211
+ if (columns.now.every((now) => now.id !== card.id)) board.link(milestoneKey(byId.get(card.id)?.milestone ?? null), 'listed');
212
+ }
213
+
214
+ for (const entry of columns.done) {
215
+ board.link(entry.id, 'listed');
216
+ board.link(milestoneKey(byId.get(entry.id ?? '')?.milestone ?? null), 'listed');
217
+ }
218
+
219
+ const roadmap = source('/plan/roadmap/', 'Roadmap');
220
+
221
+ for (const group of roadmapGroups(planning)) {
222
+ roadmap.link(group.milestone?.id ?? milestoneKey(null), 'listed');
223
+ roadmap.prose(group.milestone?.exitCriteria);
224
+ for (const event of group.events) {
225
+ roadmap.link(event.id, 'listed');
226
+ roadmap.prose(event.desc);
227
+ }
228
+ }
229
+
230
+ const log = source('/plan/log/', 'Log');
231
+
232
+ for (const entry of planning.board.activity) {
233
+ if (entry.id) log.link(entry.id, 'listed');
234
+ else log.prose(entry.title);
235
+ log.prose(entry.result);
236
+ }
237
+
238
+ const risks = source('/plan/risks/', 'Risks');
239
+
240
+ // Open risks show their detail; closed ones their title and closing reason; removed ones their reason.
241
+ for (const risk of planning.risks.open) {
242
+ risks.link(risk.id, 'listed');
243
+ risks.prose(risk.title);
244
+ risks.prose(risk.affects, 'affects');
245
+ risks.prose(risk.trigger);
246
+ risks.prose(risk.ragOverride);
247
+ risks.prose(risk.mitigation, 'mitigation');
248
+ }
249
+
250
+ for (const risk of planning.risks.closed) {
251
+ risks.link(risk.id, 'listed');
252
+ risks.prose(risk.title);
253
+ risks.prose(risk.closed);
254
+ }
255
+
256
+ for (const risk of planning.risks.removed) {
257
+ risks.link(risk.id, 'listed');
258
+ risks.prose(risk.title);
259
+ risks.prose(risk.reason);
260
+ }
261
+
262
+ if (views.features) {
263
+ const page = source('/plan/features/', 'Features');
264
+
265
+ for (const feature of all) {
266
+ page.link(feature.id, 'listed');
267
+ page.link(milestoneKey(feature.milestone), 'listed');
268
+ page.prose(decision(feature));
269
+ }
270
+ }
271
+
272
+ if (views.milestones) {
273
+ const page = source('/plan/milestones/', 'Milestones');
274
+
275
+ for (const summary of summaries) {
276
+ page.link(summary.id ?? 'none', 'listed');
277
+ page.prose(summary.exitCriteria);
278
+ }
279
+ }
280
+
281
+ if (views.now && planning.now.item) {
282
+ const page = source('/plan/now/', 'Now');
283
+ const checkpoint = planning.now.checkpoint;
284
+
285
+ page.link(planning.now.item.id, 'listed');
286
+ page.link(planning.now.brief, 'listed');
287
+ for (const text of [...planning.now.doneWhen, checkpoint?.stoppedAt, checkpoint?.nextAction, checkpoint?.startWith, checkpoint?.decisions, checkpoint?.context, checkpoint?.openQuestion]) page.prose(text);
288
+ for (const task of planning.plan?.tasks ?? []) page.prose(task.title);
289
+ }
290
+
291
+ if (views.inbox) {
292
+ const page = source('/plan/inbox/', 'Inbox');
293
+
294
+ for (const entry of planning.inbox) {
295
+ page.prose(entry.title);
296
+ page.prose(entry.affects, 'affects');
297
+ for (const id of entry.related) page.link(id, 'related');
298
+ page.link(entry.brief, 'brief');
299
+ page.prose(entry.idea);
300
+ }
301
+ }
302
+
303
+ if (views.briefs) {
304
+ const page = source('/plan/briefs/', 'Briefs');
305
+
306
+ for (const brief of planning.briefs) {
307
+ page.link(brief.id, 'listed');
308
+ for (const text of [brief.status, brief.origin, brief.problem, brief.decision, brief.doneWhen, ...brief.revisions.map((revision) => revision.text)]) page.prose(text);
309
+ }
310
+ }
311
+
312
+ if (views.strategy) {
313
+ const page = source('/plan/strategy/', 'Strategy');
314
+ const { strategy, vision } = planning;
315
+
316
+ page.prose(strategy.focus.milestone, 'listed');
317
+ for (const text of [
318
+ vision.problem,
319
+ vision.customer,
320
+ ...vision.outcomes.map((outcome) => outcome.text),
321
+ ...vision.outOfScope,
322
+ vision.constraints.timeAvailable,
323
+ vision.constraints.budget,
324
+ vision.constraints.stack,
325
+ strategy.focus.whyNow,
326
+ ...strategy.bets.flatMap((bet) => [bet.statement, bet.evidence, bet.signal, bet.status]),
327
+ ...strategy.assumptions.flatMap((assumption) => [assumption.statement, assumption.test, assumption.status]),
328
+ ...strategy.notDoing.flatMap((entry) => [entry.thing, entry.why, entry.revisit]),
329
+ ...strategy.decisions.flatMap((decision) => [decision.date, decision.decision, decision.why, decision.rejected]),
330
+ ])
331
+ page.prose(text);
332
+ }
333
+
334
+ const home = source('/', 'Home');
335
+
336
+ home.prose(planning.strategy.focus.milestone, 'listed');
337
+ home.prose(planning.strategy.focus.whyNow);
338
+ if (!views.now && planning.now.item) home.link(planning.now.item.id, 'listed');
339
+ for (const id of planning.checks.claimable) home.link(id, 'listed');
340
+ for (const risk of planning.risks.open.filter((candidate) => candidate.rag === 'red')) {
341
+ home.link(risk.id, 'listed');
342
+ home.prose(risk.title);
343
+ home.prose(risk.mitigation, 'mitigation');
344
+ }
345
+
346
+ return back;
347
+ }
348
+
349
+ let cache: { known: Map<string, Target>; back: Map<string, Backlink[]> } | null = null;
350
+
351
+ /** The site's targets and backlinks, computed once per build from the integration's options. */
352
+ export function siteRefs(): { known: Map<string, Target>; back: Map<string, Backlink[]> } {
353
+ if (!cache) {
354
+ const planning = loadPlanning();
355
+
356
+ cache = { known: targets(planning, config.views), back: references(planning, config.views) };
357
+ }
358
+
359
+ return cache;
360
+ }
@@ -0,0 +1,156 @@
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 { milestoneSummaries, normaliseTarget } from './planning';
6
+ import type { Planning } from './planning-types';
7
+
8
+ 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
+ }
30
+
31
+ const DONE = /^done(?:\s*\((\d{4}-\d{2}-\d{2})\))?$/i;
32
+
33
+ /** A milestone's status text as its state, label, and done date, if any. An unrecognised value is `other`, shown with its own text. */
34
+ export function parseMilestoneStatus(status: string | null): MilestoneStatus {
35
+ const text = status?.trim() ?? '';
36
+
37
+ if (!text) return { state: 'other', label: 'No status', doneOn: null };
38
+
39
+ const done = DONE.exec(text);
40
+
41
+ if (done) return { state: 'done', label: 'done', doneOn: done[1] ?? null };
42
+
43
+ const lower = text.toLowerCase();
44
+
45
+ return lower === 'active' || lower === 'planned' ? { state: lower, label: lower, doneOn: null } : { state: 'other', label: text, doneOn: null };
46
+ }
47
+
48
+ /**
49
+ * The timeline's cards, in strategy order, then `No milestone` last. Drops the
50
+ * `No milestone` card when every one of its items is dropped (its progress is
51
+ * then `0` of `0`, since dropped items are never counted).
52
+ */
53
+ export function timelineMilestones(planning: Planning, known: Map<string, { href: string | null }>): TimelineMilestone[] {
54
+ return milestoneSummaries(planning)
55
+ .filter((summary) => summary.id !== null || summary.progress.total > 0)
56
+ .map((summary) => {
57
+ const key = summary.id ?? 'none';
58
+ const { done, total } = summary.progress;
59
+
60
+ return {
61
+ id: summary.id,
62
+ key,
63
+ name: summary.name,
64
+ href: known.get(key)?.href ?? null,
65
+ isFocus: summary.isFocus,
66
+ status: parseMilestoneStatus(summary.status),
67
+ target: normaliseTarget(summary.target),
68
+ progress: { done, total, percent: total === 0 ? 0 : Math.round((done / total) * 100) },
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;
156
+ }
@@ -0,0 +1,69 @@
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.ts, shared with
3
+ // the sidebar.
4
+
5
+ import { readFile } from 'node:fs/promises';
6
+ import { relative, resolve, sep } from 'node:path';
7
+ import { fileURLToPath, pathToFileURL } from 'node:url';
8
+
9
+ import type { Loader } from 'astro/loaders';
10
+
11
+ import type { DocsSource } from '../../lib/types.ts';
12
+ import { pagesOf, readPage } from '../../lib/repo-docs.ts';
13
+
14
+ /** Starlight's `docs` collection over every source; `root` is the docs root, absolute or relative to the site root. */
15
+ export function repoDocsLoader(options: { root: string; sources: DocsSource[] }): Loader {
16
+ return {
17
+ name: 'repo-docs',
18
+ async load({ config, store, parseData, renderMarkdown, generateDigest, watcher, logger }) {
19
+ const siteRoot = fileURLToPath(config.root);
20
+ const repoRoot = resolve(siteRoot, options.root);
21
+ const pages = new Map<string, string>();
22
+
23
+ // The first source to claim a file wins, so a hidden catch-all can follow the listed sources.
24
+ for (const source of options.sources) {
25
+ for (const page of pagesOf(source, repoRoot)) {
26
+ if (![...pages.values()].includes(page.file) && !pages.has(page.id)) pages.set(page.id, page.file);
27
+ }
28
+ }
29
+
30
+ async function sync(id: string, file: string): Promise<void> {
31
+ const content = (await readFile(file, 'utf8')).replace(/\r\n/g, '\n');
32
+ const { title, description, body } = readPage(content, file);
33
+ const data = await parseData({ id, data: { title, ...(description ? { description } : {}) } });
34
+
35
+ store.set({
36
+ id,
37
+ data,
38
+ body,
39
+ filePath: relative(siteRoot, file).split(sep).join('/'),
40
+ digest: generateDigest(content),
41
+ // The file URL lets Markdown plugins name the page in what they report.
42
+ rendered: await renderMarkdown(body, { fileURL: pathToFileURL(file) }),
43
+ });
44
+ }
45
+
46
+ store.clear();
47
+ await Promise.all([...pages].map(([id, file]) => sync(id, file)));
48
+ logger.info(`loaded ${pages.size} pages from ${options.sources.length} sources`);
49
+
50
+ if (!watcher) return;
51
+
52
+ // The loaded files only: watching a source folder that is the repository root
53
+ // would watch node_modules too. A new file shows up on the next start.
54
+ const byFile = new Map([...pages].map(([id, file]) => [resolve(file), id]));
55
+
56
+ watcher.add([...byFile.keys()]);
57
+ watcher.on('change', (path) => {
58
+ const id = byFile.get(resolve(path));
59
+
60
+ if (id) void sync(id, path);
61
+ });
62
+ watcher.on('unlink', (path) => {
63
+ const id = byFile.get(resolve(path));
64
+
65
+ if (id) store.delete(id);
66
+ });
67
+ },
68
+ };
69
+ }