@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.
Files changed (60) hide show
  1. package/README.md +70 -10
  2. package/dist/cli.js +4 -3
  3. package/dist/dev-env.d.ts +2 -0
  4. package/dist/dev-env.js +13 -0
  5. package/dist/fs-allow.d.ts +2 -0
  6. package/dist/fs-allow.js +11 -0
  7. package/dist/index.js +38 -4
  8. package/dist/options.js +1 -1
  9. package/dist/schema-version.d.ts +17 -0
  10. package/dist/schema-version.js +30 -1
  11. package/dist/sidebar.js +2 -0
  12. package/dist/site-options.js +5 -0
  13. package/dist/types.d.ts +2 -2
  14. package/lib/schema-version.ts +36 -1
  15. package/lib/types.ts +48 -0
  16. package/package.json +7 -3
  17. package/src/components/FeatureSummary.astro +30 -9
  18. package/src/components/FeatureTable.astro +1 -1
  19. package/src/components/ItemDetail.astro +1 -1
  20. package/src/components/ItemDialog.astro +12 -8
  21. package/src/components/RefLink.astro +7 -4
  22. package/src/components/board/Board.tsx +16 -8
  23. package/src/components/board/KanbanItemCard.tsx +4 -2
  24. package/src/components/board/TaskKanbanCard.tsx +4 -2
  25. package/src/components/decisions/Decisions.tsx +162 -0
  26. package/src/components/decisions/useDecisionsUrlState.ts +29 -0
  27. package/src/components/graph/Graph.tsx +290 -0
  28. package/src/components/graph/GraphNodes.tsx +120 -0
  29. package/src/components/graph/useGraphUrlState.ts +58 -0
  30. package/src/components/lib/KanbanItemCard.astro +7 -11
  31. package/src/components/lib/StatusTimelineFeed.astro +3 -2
  32. package/src/components/lib/TaskKanbanCard.astro +2 -1
  33. package/src/components/timeline/Timeline.tsx +39 -6
  34. package/src/components/timeline/useTimelineLayout.ts +2 -2
  35. package/src/content.config.ts +22 -6
  36. package/src/lib/decisions.ts +100 -0
  37. package/src/lib/graph-layout.ts +270 -0
  38. package/src/lib/graph-state.ts +99 -0
  39. package/src/lib/graph.ts +194 -0
  40. package/src/lib/link-html.ts +39 -0
  41. package/src/lib/planning-types.ts +32 -3
  42. package/src/lib/planning.ts +30 -16
  43. package/src/lib/ref-boundary.ts +19 -0
  44. package/src/lib/references.ts +66 -7
  45. package/src/lib/timeline-state.ts +119 -0
  46. package/src/lib/timeline.ts +22 -127
  47. package/src/loaders/adrs.ts +43 -0
  48. package/src/pages/404.astro +18 -0
  49. package/src/pages/index.astro +1 -1
  50. package/src/pages/plan/log.astro +18 -1
  51. package/src/pages/plan/roadmap.astro +1 -1
  52. package/src/routes/plan/decisions/[id].astro +93 -0
  53. package/src/routes/plan/decisions.astro +52 -0
  54. package/src/routes/plan/graph.astro +80 -0
  55. package/src/routes/plan/milestones/index.astro +2 -2
  56. package/src/routes/plan/now.astro +2 -3
  57. package/src/scripts/plan.ts +33 -1
  58. package/src/styles/components.css +117 -3
  59. package/src/styles/graph.css +296 -0
  60. package/src/styles/timeline.css +1 -1
@@ -0,0 +1,93 @@
1
+ ---
2
+ // One ADR from planning.json's `adrs`: its status, header fields, and its four
3
+ // sections rendered from Markdown (src/loaders/adrs.ts), with the IDs in them
4
+ // linked, and what links to it.
5
+ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
6
+ import { getCollection } from 'astro:content';
7
+
8
+ import ExportStamp from '../../../components/ExportStamp.astro';
9
+ import LinkedFrom from '../../../components/LinkedFrom.astro';
10
+ import LinkedText from '../../../components/LinkedText.astro';
11
+ import RefLink from '../../../components/RefLink.astro';
12
+ import { linkHtml } from '../../../lib/link-html';
13
+ import { loadPlanning } from '../../../lib/planning';
14
+ import { siteRefs } from '../../../lib/references';
15
+ import { ADR_SECTIONS, type RenderedAdr } from '../../../loaders/adrs';
16
+ import '../../../styles/components.css';
17
+
18
+ export async function getStaticPaths() {
19
+ // An empty collection is never looked up: Astro warns that it does not exist.
20
+ if (loadPlanning().adrs.length === 0) return [];
21
+
22
+ const entries = await getCollection('adrs');
23
+
24
+ return entries.map((entry: { id: string; data: unknown }) => ({ params: { id: entry.id }, props: { adr: entry.data as RenderedAdr } }));
25
+ }
26
+
27
+ const { adr } = Astro.props as { adr: RenderedAdr };
28
+ const { known } = siteRefs();
29
+ const status = adr.status ?? 'unknown';
30
+ const refs: { label: string; ref: string | null }[] = [
31
+ { label: 'Item', ref: adr.item },
32
+ { label: 'Supersedes', ref: adr.supersedes },
33
+ { label: 'Superseded by', ref: adr.supersededBy },
34
+ ];
35
+ ---
36
+
37
+ <StarlightPage
38
+ frontmatter={{ title: `${adr.id} ${adr.title}`, description: `${status} decision${adr.category ? `, ${adr.category}` : ''}.`, tableOfContents: false }}
39
+ >
40
+ <ExportStamp kind="ADR" state={status} />
41
+
42
+ <p>
43
+ <span class={`adr-status adr-status--${status}`}>{status}</span>
44
+ {' '}
45
+ <a href="/plan/decisions/">All decisions</a>
46
+ </p>
47
+
48
+ <dl class="plan-facts">
49
+ {adr.date && (
50
+ <div>
51
+ <dt>Date</dt>
52
+ <dd>{adr.date}</dd>
53
+ </div>
54
+ )}
55
+ {adr.category && (
56
+ <div>
57
+ <dt>Category</dt>
58
+ <dd>{adr.category}</dd>
59
+ </div>
60
+ )}
61
+ {
62
+ refs
63
+ .filter((entry) => entry.ref)
64
+ .map((entry) => (
65
+ <div>
66
+ <dt>{entry.label}</dt>
67
+ <dd>
68
+ <RefLink ref={entry.ref} />
69
+ </dd>
70
+ </div>
71
+ ))
72
+ }
73
+ {adr.source && (
74
+ <div>
75
+ <dt>Source</dt>
76
+ <dd>
77
+ <LinkedText text={adr.source} />
78
+ </dd>
79
+ </div>
80
+ )}
81
+ </dl>
82
+
83
+ {
84
+ ADR_SECTIONS.filter(({ key }) => adr.html[key] !== null).map(({ key, label }) => (
85
+ <section>
86
+ <h2>{label}</h2>
87
+ {adr.html[key] === '' ? <p>None recorded.</p> : <Fragment set:html={linkHtml(adr.html[key]!, known)} />}
88
+ </section>
89
+ ))
90
+ }
91
+
92
+ <LinkedFrom ref={adr.id} />
93
+ </StarlightPage>
@@ -0,0 +1,52 @@
1
+ ---
2
+ // The architecture decision records from planning.json's `adrs`, as a
3
+ // server-rendered React island (src/components/decisions/Decisions.tsx) that
4
+ // searches, filters by status and category, and groups them. Every ADR is in
5
+ // the HTML; the filters only hide rows, so the default view (superseded hidden)
6
+ // still links every ADR page.
7
+ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
8
+
9
+ import Decisions, { type DecisionRow } from '../../components/decisions/Decisions';
10
+ import ExportStamp from '../../components/ExportStamp.astro';
11
+ import { adrSearchText } from '../../lib/decisions';
12
+ import { adrHref, loadPlanning } from '../../lib/planning';
13
+ import { siteRefs } from '../../lib/references';
14
+ import '../../styles/components.css';
15
+
16
+ const planning = loadPlanning();
17
+ const { known } = siteRefs();
18
+ const named = (ref: string | null) => {
19
+ if (!ref) return null;
20
+ const target = known.get(ref);
21
+
22
+ return { label: target?.label ?? ref, href: target?.href ?? null };
23
+ };
24
+ const rows: DecisionRow[] = planning.adrs.map((adr) => ({
25
+ id: adr.id,
26
+ title: adr.title,
27
+ status: adr.status,
28
+ category: adr.category,
29
+ date: adr.date,
30
+ href: adrHref(adr.id),
31
+ text: adrSearchText(adr),
32
+ item: named(adr.item),
33
+ successor: named(adr.supersededBy),
34
+ }));
35
+ const categories = [...new Set(planning.adrs.map((adr) => adr.category).filter((category): category is string => !!category))].sort();
36
+ ---
37
+
38
+ <StarlightPage
39
+ frontmatter={{ title: 'Decisions', description: 'The architecture decision records: search, filter, and group them.', tableOfContents: false }}
40
+ >
41
+ <ExportStamp />
42
+
43
+ {
44
+ rows.length === 0 ? (
45
+ <p class="plan-empty">No ADRs yet. Record one with pm-adr new.</p>
46
+ ) : (
47
+ <div data-pagefind-ignore>
48
+ <Decisions client:load rows={rows} categories={categories} />
49
+ </div>
50
+ )
51
+ }
52
+ </StarlightPage>
@@ -0,0 +1,80 @@
1
+ ---
2
+ // The dependency graph: open items and their Depends on and Revisits links,
3
+ // grouped by milestone, then the same links as a plain Dependencies list for
4
+ // search, screen readers, and pages without JavaScript. The graph's four
5
+ // layouts are computed here, at build time (graph-layout.ts imports dagre,
6
+ // which must never reach the browser); the island (Graph.tsx) only picks one.
7
+ // Its inline script runs as the page is parsed, before the graph paints: a
8
+ // `?lanes=off` or `?done=off` link hides the graph until the island has
9
+ // rendered that layout and deleted the mark (useGraphUrlState.ts), so it never
10
+ // flashes the default layout first. graph.css reveals the graph after 3s if
11
+ // the island never loads. It must stay in step with parseGraphQuery in
12
+ // src/lib/graph-state.ts.
13
+ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
14
+ import '@xyflow/react/dist/style.css';
15
+
16
+ import ExportStamp from '../../components/ExportStamp.astro';
17
+ import Graph from '../../components/graph/Graph';
18
+ import { dependencyRows, graphData } from '../../lib/graph';
19
+ import type { Ref } from '../../lib/graph';
20
+ import { graphLayouts } from '../../lib/graph-layout';
21
+ import { loadPlanning } from '../../lib/planning';
22
+ import { siteRefs } from '../../lib/references';
23
+ import '../../styles/components.css';
24
+ import '../../styles/graph.css';
25
+
26
+ const { known } = siteRefs();
27
+ const planning = loadPlanning();
28
+ const data = graphData(planning, known);
29
+ const layouts = graphLayouts(data, planning);
30
+ const rows = dependencyRows(data);
31
+ // The milestone pages the lane labels and the item meta lines link to (references.ts lists the Graph in their Linked from).
32
+ const milestoneKeys = new Set([...Object.values(layouts).flatMap((layout) => layout.lanes.map((lane) => lane.key)), ...data.nodes.flatMap((node) => (node.milestone ? [node.milestone] : []))]);
33
+ const milestoneHrefs = Object.fromEntries([...milestoneKeys].flatMap((key) => (known.get(key)?.href ? [[key, known.get(key)!.href!]] : [])));
34
+
35
+ /** A row's link lines, in order, with the empty ones left out. */
36
+ const lines = (row: (typeof rows)[number]): { label: string; refs: Ref[] }[] =>
37
+ [
38
+ { label: 'Waits on', refs: row.waitsOn },
39
+ { label: 'Waited on by', refs: row.waitedOnBy },
40
+ { label: 'Revisits', refs: row.revisits ? [row.revisits] : [] },
41
+ { label: 'Revised by', refs: row.revisedBy },
42
+ ].filter((line) => line.refs.length > 0);
43
+ ---
44
+
45
+ <StarlightPage frontmatter={{ title: 'Graph', description: 'Open items and their Depends on and Revisits links, by milestone.', tableOfContents: false }}>
46
+ <ExportStamp />
47
+
48
+ <script is:inline>
49
+ (function (params) {
50
+ if (params.get('lanes') === 'off' || params.get('done') === 'off') document.documentElement.dataset.graphPending = '';
51
+ })(new URLSearchParams(location.search));
52
+ </script>
53
+ {data.nodes.length > 0 ? <Graph client:load nodes={data.nodes} edges={data.edges} layouts={layouts} milestoneHrefs={milestoneHrefs} /> : <p class="plan-empty">No open items</p>}
54
+
55
+ {
56
+ rows.length > 0 && (
57
+ <>
58
+ <h2>Dependencies</h2>
59
+ <ul class="plan-deps">
60
+ {rows.map((row) => (
61
+ <li>
62
+ <p>{row.href ? <a href={row.href}>{`${row.id} ${row.title}`}</a> : `${row.id} ${row.title}`}</p>
63
+ {lines(row).map((line) => (
64
+ <p class="plan-deps__links">
65
+ {line.label}:{' '}
66
+ {line.refs.map((ref, index) => (
67
+ <>
68
+ {index > 0 && ', '}
69
+ {ref.href ? <a href={ref.href}>{ref.label}</a> : ref.label}
70
+ </>
71
+ ))}
72
+ </p>
73
+ ))}
74
+ </li>
75
+ ))}
76
+ </ul>
77
+ </>
78
+ )
79
+ }
80
+ </StarlightPage>
@@ -6,11 +6,11 @@ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
6
6
  import ExportStamp from '../../../components/ExportStamp.astro';
7
7
  import LinkedText from '../../../components/LinkedText.astro';
8
8
  import RefLink from '../../../components/RefLink.astro';
9
- import { FEATURE_STATES, loadPlanning, milestoneSummaries, type FeatureState } from '../../../lib/planning';
9
+ import { FEATURE_STATES, loadPlanning, milestoneCards, type FeatureState } from '../../../lib/planning';
10
10
  import '../../../styles/components.css';
11
11
 
12
12
  const planning = loadPlanning();
13
- const summaries = milestoneSummaries(planning);
13
+ const summaries = milestoneCards(planning);
14
14
  const states = Object.keys(FEATURE_STATES) as FeatureState[];
15
15
  const byState = (summary: (typeof summaries)[number]) =>
16
16
  states
@@ -13,8 +13,7 @@ import '../../styles/components.css';
13
13
 
14
14
  const planning = loadPlanning();
15
15
  const { now, plan } = planning;
16
- const card = planning.board.columns.now[0];
17
- const priority = ({ low: 'low', medium: 'med', high: 'high' } as const)[sizeToPriority(card?.size ?? null)];
16
+ const priority = ({ low: 'low', medium: 'med', high: 'high' } as const)[sizeToPriority(now.item?.size ?? null)];
18
17
 
19
18
  const paths = [
20
19
  { label: 'Brief', path: now.brief },
@@ -121,7 +120,7 @@ const checkpoint = now.checkpoint
121
120
  <TaskKanbanCard
122
121
  task={`Task ${task.number}: ${task.title}`}
123
122
  date={`${task.checked}/${task.total} steps`}
124
- assigneeInitials={initials(card?.owner ?? null)}
123
+ assigneeInitials={initials(now.item?.owner ?? null)}
125
124
  priority={priority}
126
125
  progress={planProgress(task)}
127
126
  />
@@ -1,7 +1,18 @@
1
1
  // The Board and Roadmap in the browser: a plain click on a card opens its item
2
2
  // popup (any other click is the browser's). Without this script every card is
3
- // a link. The Board's column collapse lives in its island
3
+ // a link. A click on the dialog element itself (the backdrop; its content
4
+ // sits in `.plan-dialog__frame`, never directly in the dialog) closes the
5
+ // popup. The Board's column collapse lives in its island
4
6
  // (src/components/board/Board.tsx).
7
+ //
8
+ // When a mousedown and the matching mouseup land on different elements (a
9
+ // drag, or a text selection released past the dialog's edge), the browser
10
+ // retargets the synthesised `click` event to their nearest common ancestor,
11
+ // which is the dialog itself whenever either end was the backdrop. So a
12
+ // click's own target cannot tell a genuine backdrop click from a drag that
13
+ // merely started or ended there: `pointerdown` and `pointerup` are not
14
+ // retargeted, so this records both separately and closes only when neither
15
+ // end of the gesture left the backdrop.
5
16
 
6
17
  function openItem(link: HTMLAnchorElement): void {
7
18
  const dialog = document.querySelector<HTMLDialogElement>('dialog[data-item-dialog]');
@@ -19,7 +30,23 @@ function openItem(link: HTMLAnchorElement): void {
19
30
  dialog.showModal();
20
31
  }
21
32
 
33
+ /** True for the dialog element itself (the backdrop), never its frame. */
34
+ function isDialogBackdrop(target: EventTarget | null): target is HTMLDialogElement {
35
+ return target instanceof HTMLDialogElement && target.matches('dialog[data-item-dialog]');
36
+ }
37
+
22
38
  function start(): void {
39
+ let pointerDownOnBackdrop = false;
40
+ let pointerUpOnBackdrop = false;
41
+
42
+ document.addEventListener('pointerdown', (event) => {
43
+ pointerDownOnBackdrop = isDialogBackdrop(event.target);
44
+ });
45
+
46
+ document.addEventListener('pointerup', (event) => {
47
+ pointerUpOnBackdrop = isDialogBackdrop(event.target);
48
+ });
49
+
23
50
  document.addEventListener('click', (event) => {
24
51
  const target = event.target as Element | null;
25
52
  const link = target?.closest<HTMLAnchorElement>('a[data-item]');
@@ -31,6 +58,11 @@ function start(): void {
31
58
  return;
32
59
  }
33
60
 
61
+ if (isDialogBackdrop(target) && pointerDownOnBackdrop && pointerUpOnBackdrop) {
62
+ target.close();
63
+ return;
64
+ }
65
+
34
66
  if (target?.closest('[data-item-dialog-close]')) {
35
67
  target.closest('dialog')?.close();
36
68
  }
@@ -162,11 +162,15 @@
162
162
  justify-content: space-between;
163
163
  gap: 0.5rem;
164
164
  width: 100%;
165
- cursor: pointer;
166
165
  border-radius: 6px;
167
166
  }
168
167
 
169
- .plan-column__toggle:focus-visible {
168
+ /* Only the hydrated button is clickable; the pre-hydration static span (plan-column__toggle--static) shares its layout but never looks interactive. */
169
+ button.plan-column__toggle {
170
+ cursor: pointer;
171
+ }
172
+
173
+ button.plan-column__toggle:focus-visible {
170
174
  outline: 2px solid var(--sl-color-accent);
171
175
  outline-offset: 2px;
172
176
  }
@@ -260,17 +264,36 @@
260
264
  .plan-dialog {
261
265
  width: min(42rem, calc(100vw - 2rem));
262
266
  max-height: calc(100vh - 4rem);
263
- padding: 1.25rem 1.5rem;
267
+ padding: 0;
264
268
  border: 1px solid var(--sl-color-hairline);
265
269
  border-radius: 12px;
266
270
  background: var(--sl-color-bg);
267
271
  color: var(--sl-color-text);
272
+ /* Not the default `auto`: with the rounded corners above, a browser clips
273
+ a child's hit box out of the corners, so a click just inside an edge
274
+ would miss .plan-dialog__frame and land on this element (the backdrop
275
+ click target in src/scripts/plan.ts) instead. The frame scrolls itself. */
276
+ overflow: visible;
268
277
  }
269
278
 
270
279
  .plan-dialog::backdrop {
271
280
  background: rgb(0 0 0 / 0.45);
272
281
  }
273
282
 
283
+ /* Fills the dialog's box, so only a click on the dialog element itself (the
284
+ backdrop, never this frame) closes the popup (src/scripts/plan.ts). Not
285
+ rounded, so it scrolls long content itself without the parent's corner
286
+ clipping taking its hit box away (see .plan-dialog's overflow above).
287
+ max-height is not `inherit`: that copies .plan-dialog's own max-height
288
+ value, which bounds its border box, not its content box; with the 1px
289
+ border on each side, inheriting it would let the frame (and its
290
+ scrollbar) run 2px past the dialog's border. */
291
+ .plan-dialog__frame {
292
+ padding: 1.25rem 1.5rem;
293
+ max-height: calc(100vh - 4rem - 2px);
294
+ overflow: auto;
295
+ }
296
+
274
297
  .plan-dialog__head {
275
298
  display: flex;
276
299
  justify-content: space-between;
@@ -489,3 +512,94 @@
489
512
  .plan-card p {
490
513
  margin: 0.35rem 0 0;
491
514
  }
515
+
516
+ /* An ADR's status (Decisions view and ADR pages): the word is always printed. */
517
+ .adr-status {
518
+ display: inline-block;
519
+ padding: 0.1rem 0.45rem;
520
+ border-radius: 4px;
521
+ border: 1px solid var(--sl-color-hairline);
522
+ font-size: var(--sl-text-xs);
523
+ font-weight: 600;
524
+ }
525
+
526
+ .adr-status--accepted {
527
+ color: #15803d;
528
+ background: #22c55e1a;
529
+ border-color: #22c55e66;
530
+ }
531
+
532
+ .adr-status--proposed {
533
+ color: #1d4ed8;
534
+ background: #3b82f61a;
535
+ border-color: #3b82f666;
536
+ }
537
+
538
+ .adr-status--superseded,
539
+ .adr-status--deprecated,
540
+ .adr-status--unknown {
541
+ color: var(--sl-color-gray-3);
542
+ }
543
+
544
+ /* The Decisions view: search, chips, grouping, and the rows. */
545
+ .decisions-controls {
546
+ display: flex;
547
+ flex-wrap: wrap;
548
+ gap: 0.75rem;
549
+ align-items: end;
550
+ }
551
+
552
+ .decisions-search,
553
+ .decisions-group {
554
+ display: flex;
555
+ flex-direction: column;
556
+ gap: 0.25rem;
557
+ font-size: var(--sl-text-sm);
558
+ }
559
+
560
+ .decisions-chips {
561
+ display: flex;
562
+ flex-wrap: wrap;
563
+ gap: 0.35rem;
564
+ }
565
+
566
+ .decisions-chip,
567
+ .decisions-clear {
568
+ padding: 0.2rem 0.6rem;
569
+ border: 1px solid var(--sl-color-hairline-shade);
570
+ border-radius: 999px;
571
+ background: transparent;
572
+ color: inherit;
573
+ font-size: var(--sl-text-sm);
574
+ cursor: pointer;
575
+ }
576
+
577
+ .decisions-chip[aria-pressed='true'] {
578
+ background: var(--sl-color-accent-low);
579
+ border-color: var(--sl-color-accent);
580
+ }
581
+
582
+ .decisions-clear:disabled {
583
+ opacity: 0.5;
584
+ cursor: default;
585
+ }
586
+
587
+ .decisions-count,
588
+ .decisions-meta,
589
+ .decisions-empty {
590
+ color: var(--sl-color-gray-3);
591
+ font-size: var(--sl-text-sm);
592
+ }
593
+
594
+ .decisions-list {
595
+ list-style: none;
596
+ padding-inline-start: 0;
597
+ }
598
+
599
+ .decisions-meta {
600
+ display: block;
601
+ }
602
+
603
+ .decisions [hidden] {
604
+ display: none;
605
+ }