@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
|
@@ -50,7 +50,7 @@ const when = (feature: Feature) => (state === 'done' || state === 'dropped' ? fe
|
|
|
50
50
|
<td class="plan-nowrap">{when(feature) ?? '–'}</td>
|
|
51
51
|
{!hideMilestone && (
|
|
52
52
|
<td>
|
|
53
|
-
<RefLink ref={feature.milestone ?? 'none'} />
|
|
53
|
+
<RefLink ref={feature.milestone ?? 'none'} fallback={feature.milestone ?? 'No milestone'} />
|
|
54
54
|
</td>
|
|
55
55
|
)}
|
|
56
56
|
<td>{feature.owner ?? '–'}</td>
|
|
@@ -1,16 +1,20 @@
|
|
|
1
1
|
---
|
|
2
2
|
// The one item dialog on the Board and Roadmap. src/scripts/plan.ts fills it
|
|
3
3
|
// from a card's <template> and opens it on a plain click; without JavaScript
|
|
4
|
-
// the card link goes to the item's page instead.
|
|
4
|
+
// the card link goes to the item's page instead. The head, body, and foot sit
|
|
5
|
+
// in a `.plan-dialog__frame` so the dialog element's own box is backdrop: a
|
|
6
|
+
// click there (never on the frame) closes the popup.
|
|
5
7
|
---
|
|
6
8
|
|
|
7
9
|
<dialog class="plan-dialog" data-item-dialog aria-labelledby="plan-dialog-title" data-pagefind-ignore>
|
|
8
|
-
<div class="plan-
|
|
9
|
-
<
|
|
10
|
-
|
|
10
|
+
<div class="plan-dialog__frame">
|
|
11
|
+
<div class="plan-dialog__head">
|
|
12
|
+
<h2 id="plan-dialog-title"></h2>
|
|
13
|
+
<button type="button" class="plan-dialog__close" data-item-dialog-close aria-label="Close">×</button>
|
|
14
|
+
</div>
|
|
15
|
+
<div class="plan-dialog__body" data-item-dialog-body></div>
|
|
16
|
+
<p class="plan-dialog__foot">
|
|
17
|
+
<a data-item-dialog-open href="">Open page</a>
|
|
18
|
+
</p>
|
|
11
19
|
</div>
|
|
12
|
-
<div class="plan-dialog__body" data-item-dialog-body></div>
|
|
13
|
-
<p class="plan-dialog__foot">
|
|
14
|
-
<a data-item-dialog-open href="">Open page</a>
|
|
15
|
-
</p>
|
|
16
20
|
</dialog>
|
|
@@ -1,18 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
// One item, milestone, risk or brief as a link to its page, named with its
|
|
3
|
-
// title, or as plain text when that page is not built
|
|
4
|
-
|
|
3
|
+
// title, or as plain text when that page is not built. An unknown key prints
|
|
4
|
+
// the fallback the caller gives (an entry title, `No milestone`), else the key.
|
|
5
|
+
import { refText, siteRefs } from '../lib/references';
|
|
5
6
|
|
|
6
7
|
interface Props {
|
|
7
8
|
/** An ID (`R-012`, `M1`, `RK-002`), `none` for the No-milestone page, or a brief path. */
|
|
8
9
|
ref: string | null | undefined;
|
|
9
10
|
/** `full` shows the target's label (`R-012 Invoice export`); `id` the key only. */
|
|
10
11
|
label?: 'full' | 'id';
|
|
12
|
+
/** The text for a key with no target. */
|
|
13
|
+
fallback?: string;
|
|
11
14
|
}
|
|
12
15
|
|
|
13
|
-
const { ref, label = 'full' } = Astro.props;
|
|
16
|
+
const { ref, label = 'full', fallback } = Astro.props;
|
|
14
17
|
const target = ref ? siteRefs().known.get(ref) : undefined;
|
|
15
|
-
const text = target
|
|
18
|
+
const text = refText(target, ref, label, fallback);
|
|
16
19
|
---
|
|
17
20
|
|
|
18
21
|
{target?.href ? <a href={target.href} title={target.label}>{text}</a> : text}
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
// The Board island: the filter bar, the five column headers with their
|
|
2
2
|
// collapse toggles, and the cards in lanes, in one CSS grid (.plan-columns in
|
|
3
3
|
// board.astro, components.css). It is server-rendered, so without JavaScript
|
|
4
|
-
// every card shows and the filter bar stays hidden
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
//
|
|
8
|
-
//
|
|
4
|
+
// every card shows and the filter bar stays hidden; the collapse toggles
|
|
5
|
+
// appear only once the island has hydrated (a static, unclickable span holds
|
|
6
|
+
// their place before then). The item popup is not here: a card's title keeps
|
|
7
|
+
// `a.plan-item-link[data-item]`, which src/scripts/plan.ts opens from the
|
|
8
|
+
// page's ItemDetail templates. The filter and group state lives in the URL
|
|
9
|
+
// (useBoardUrlState.ts); `.plan-board__body` (the header row and the lanes)
|
|
10
|
+
// is hidden while <html> has the pending mark.
|
|
9
11
|
import { useEffect, useState } from 'react';
|
|
10
12
|
|
|
11
13
|
import { COLUMNS, DEFAULT_STATE, isFiltered, lanes, matches } from '../../lib/board';
|
|
@@ -209,9 +211,15 @@ export default function Board({ cards, milestones }: Props) {
|
|
|
209
211
|
return (
|
|
210
212
|
<section key={name} className={grouped ? 'plan-column' : 'plan-column plan-column--joined'} data-column={name} data-collapsed={shut ? '' : undefined} aria-labelledby={`col-${name}`}>
|
|
211
213
|
<h2 id={`col-${name}`}>
|
|
212
|
-
|
|
213
|
-
<
|
|
214
|
-
|
|
214
|
+
{hydrated ? (
|
|
215
|
+
<button type="button" className="plan-column__toggle" aria-expanded={!shut} aria-controls={rows.map((lane) => cellId(name, lane.key)).join(' ')} onClick={() => toggle(name)}>
|
|
216
|
+
<span className="plan-column__name">{title}</span> <span className="plan-column__count">{visible.filter((card) => card.column === name).length}</span>
|
|
217
|
+
</button>
|
|
218
|
+
) : (
|
|
219
|
+
<span className="plan-column__toggle plan-column__toggle--static">
|
|
220
|
+
<span className="plan-column__name">{title}</span> <span className="plan-column__count">{visible.filter((card) => card.column === name).length}</span>
|
|
221
|
+
</span>
|
|
222
|
+
)}
|
|
215
223
|
</h2>
|
|
216
224
|
</section>
|
|
217
225
|
);
|
|
@@ -9,7 +9,9 @@
|
|
|
9
9
|
* tagHref), and the due-date line (and a title that is not a link) links known IDs; the pill
|
|
10
10
|
* shows the item's size (S, M, L in the kit's low, medium, high colours) and is omitted without
|
|
11
11
|
* one; a RAG dot sits beside it; the assignee chip is omitted for a card with no owner; and the
|
|
12
|
-
* card is not focusable and has no role.
|
|
12
|
+
* card is not focusable and has no role. The title link carries
|
|
13
|
+
* `aria-haspopup="dialog"` when it is the popup trigger. Its styles are in
|
|
14
|
+
* src/styles/kanban.css.
|
|
13
15
|
*/
|
|
14
16
|
import type { CardRag, LinkRun } from '../../lib/board';
|
|
15
17
|
import type { Size } from '../../lib/planning-types';
|
|
@@ -79,7 +81,7 @@ export default function KanbanItemCard({ title, titleRuns, size, rag, tag, tagHr
|
|
|
79
81
|
|
|
80
82
|
<h4 className="k-item__title">
|
|
81
83
|
{href ? (
|
|
82
|
-
<a className="plan-item-link" href={href} data-item={itemId ?? undefined}>
|
|
84
|
+
<a className="plan-item-link" href={href} data-item={itemId ?? undefined} aria-haspopup={itemId ? 'dialog' : undefined}>
|
|
83
85
|
{title}
|
|
84
86
|
</a>
|
|
85
87
|
) : (
|
|
@@ -8,7 +8,9 @@
|
|
|
8
8
|
* the task can be a link, for the site's item popup and backlinks (href, itemId), and a task that
|
|
9
9
|
* is not a link links known IDs; the tag shows the item's size (S, M, L as the kit's low, med,
|
|
10
10
|
* high) and is omitted without one; a RAG dot sits beside it; the assignee chip is omitted for a card with no
|
|
11
|
-
* owner; and the card has no role.
|
|
11
|
+
* owner; and the card has no role. The task link carries
|
|
12
|
+
* `aria-haspopup="dialog"` when it is the popup trigger. Its styles are in
|
|
13
|
+
* src/styles/kanban.css.
|
|
12
14
|
*/
|
|
13
15
|
import type { CardRag, LinkRun } from '../../lib/board';
|
|
14
16
|
import type { Size } from '../../lib/planning-types';
|
|
@@ -47,7 +49,7 @@ export default function TaskKanbanCard({ task, taskRuns, date, assigneeInitials,
|
|
|
47
49
|
|
|
48
50
|
<p className="task-card__desc">
|
|
49
51
|
{href ? (
|
|
50
|
-
<a className="plan-item-link" href={href} data-item={itemId ?? undefined}>
|
|
52
|
+
<a className="plan-item-link" href={href} data-item={itemId ?? undefined} aria-haspopup={itemId ? 'dialog' : undefined}>
|
|
51
53
|
{task}
|
|
52
54
|
</a>
|
|
53
55
|
) : (
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
// The Decisions view: every ADR as a row, with a text search, status and
|
|
2
|
+
// category chips (superseded off by default), and grouping by category or
|
|
3
|
+
// status. Rows that do not match are hidden, never left out, so the page's
|
|
4
|
+
// links stay the same in every state. The state lives in the URL
|
|
5
|
+
// (useDecisionsUrlState).
|
|
6
|
+
import { ADR_STATUSES, DEFAULT_DECISIONS_STATE, decisionsQuery, groupDecisions, matchesDecision, type DecisionsGroup } from '../../lib/decisions';
|
|
7
|
+
import type { AdrStatus } from '../../lib/planning-types';
|
|
8
|
+
import { useDecisionsUrlState } from './useDecisionsUrlState';
|
|
9
|
+
|
|
10
|
+
/** A link to a known page, or plain text when that page is not built. */
|
|
11
|
+
export interface NamedRef {
|
|
12
|
+
label: string;
|
|
13
|
+
href: string | null;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** One ADR as the island shows it; `text` is adrSearchText, computed at build time. */
|
|
17
|
+
export interface DecisionRow {
|
|
18
|
+
id: string;
|
|
19
|
+
title: string;
|
|
20
|
+
status: AdrStatus | null;
|
|
21
|
+
category: string | null;
|
|
22
|
+
date: string | null;
|
|
23
|
+
href: string;
|
|
24
|
+
text: string;
|
|
25
|
+
item: NamedRef | null;
|
|
26
|
+
successor: NamedRef | null;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
interface Props {
|
|
30
|
+
rows: DecisionRow[];
|
|
31
|
+
categories: string[];
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const GROUPS: { value: DecisionsGroup; label: string }[] = [
|
|
35
|
+
{ value: 'category', label: 'Category' },
|
|
36
|
+
{ value: 'status', label: 'Status' },
|
|
37
|
+
{ value: 'none', label: 'None' },
|
|
38
|
+
];
|
|
39
|
+
|
|
40
|
+
function Ref({ named }: { named: NamedRef }) {
|
|
41
|
+
return named.href ? (
|
|
42
|
+
<a href={named.href} title={named.label}>
|
|
43
|
+
{named.label}
|
|
44
|
+
</a>
|
|
45
|
+
) : (
|
|
46
|
+
<>{named.label}</>
|
|
47
|
+
);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const toggle = <T,>(list: T[], value: T) => (list.includes(value) ? list.filter((entry) => entry !== value) : [...list, value]);
|
|
51
|
+
|
|
52
|
+
export default function Decisions({ rows, categories }: Props) {
|
|
53
|
+
const [state, setState] = useDecisionsUrlState(categories);
|
|
54
|
+
const matches = (row: DecisionRow) => matchesDecision(row, state, row.text);
|
|
55
|
+
const groups = groupDecisions(rows, state.group);
|
|
56
|
+
const shown = rows.filter(matches).length;
|
|
57
|
+
const isDefault = decisionsQuery(state) === '';
|
|
58
|
+
|
|
59
|
+
return (
|
|
60
|
+
<div className="decisions">
|
|
61
|
+
<div className="decisions-controls">
|
|
62
|
+
<label className="decisions-search">
|
|
63
|
+
Search decisions
|
|
64
|
+
<input type="search" value={state.q} onChange={(event) => setState({ ...state, q: event.currentTarget.value })} />
|
|
65
|
+
</label>
|
|
66
|
+
<div role="group" aria-label="Status" className="decisions-chips">
|
|
67
|
+
{ADR_STATUSES.map((status) => (
|
|
68
|
+
<button
|
|
69
|
+
key={status}
|
|
70
|
+
type="button"
|
|
71
|
+
className="decisions-chip"
|
|
72
|
+
aria-pressed={state.status.includes(status)}
|
|
73
|
+
onClick={() => setState({ ...state, status: toggle(state.status, status) })}
|
|
74
|
+
>
|
|
75
|
+
{status}
|
|
76
|
+
</button>
|
|
77
|
+
))}
|
|
78
|
+
</div>
|
|
79
|
+
{categories.length > 1 && (
|
|
80
|
+
<div role="group" aria-label="Category" className="decisions-chips">
|
|
81
|
+
{categories.map((category) => (
|
|
82
|
+
<button
|
|
83
|
+
key={category}
|
|
84
|
+
type="button"
|
|
85
|
+
className="decisions-chip"
|
|
86
|
+
aria-pressed={state.category.includes(category)}
|
|
87
|
+
onClick={() => setState({ ...state, category: toggle(state.category, category) })}
|
|
88
|
+
>
|
|
89
|
+
{category}
|
|
90
|
+
</button>
|
|
91
|
+
))}
|
|
92
|
+
</div>
|
|
93
|
+
)}
|
|
94
|
+
<label className="decisions-group">
|
|
95
|
+
Group by
|
|
96
|
+
<select value={state.group} onChange={(event) => setState({ ...state, group: event.currentTarget.value as DecisionsGroup })}>
|
|
97
|
+
{GROUPS.map((group) => (
|
|
98
|
+
<option key={group.value} value={group.value}>
|
|
99
|
+
{group.label}
|
|
100
|
+
</option>
|
|
101
|
+
))}
|
|
102
|
+
</select>
|
|
103
|
+
</label>
|
|
104
|
+
<button type="button" className="decisions-clear" disabled={isDefault} onClick={() => setState(DEFAULT_DECISIONS_STATE)}>
|
|
105
|
+
Clear
|
|
106
|
+
</button>
|
|
107
|
+
</div>
|
|
108
|
+
|
|
109
|
+
<p className="decisions-count" aria-live="polite">
|
|
110
|
+
{shown} of {rows.length} decisions
|
|
111
|
+
</p>
|
|
112
|
+
|
|
113
|
+
{groups.map((group) => {
|
|
114
|
+
const visible = group.adrs.filter(matches).length;
|
|
115
|
+
|
|
116
|
+
return (
|
|
117
|
+
<section key={group.key} hidden={visible === 0}>
|
|
118
|
+
{state.group !== 'none' && (
|
|
119
|
+
<h2>
|
|
120
|
+
{group.label} ({visible})
|
|
121
|
+
</h2>
|
|
122
|
+
)}
|
|
123
|
+
<ul className="decisions-list">
|
|
124
|
+
{group.adrs.map((row) => (
|
|
125
|
+
<li key={row.id} hidden={!matches(row)} data-adr={row.id}>
|
|
126
|
+
<a href={row.href}>
|
|
127
|
+
<strong>{row.id}</strong> {row.title}
|
|
128
|
+
</a>{' '}
|
|
129
|
+
<span className={`adr-status adr-status--${row.status ?? 'unknown'}`}>{row.status ?? 'unknown'}</span>
|
|
130
|
+
<span className="decisions-meta">
|
|
131
|
+
{[row.category, row.date].filter(Boolean).join(' · ')}
|
|
132
|
+
{row.item && (
|
|
133
|
+
<>
|
|
134
|
+
{' · '}
|
|
135
|
+
<Ref named={row.item} />
|
|
136
|
+
</>
|
|
137
|
+
)}
|
|
138
|
+
{row.successor && (
|
|
139
|
+
<>
|
|
140
|
+
{' · Superseded by '}
|
|
141
|
+
<Ref named={row.successor} />
|
|
142
|
+
</>
|
|
143
|
+
)}
|
|
144
|
+
</span>
|
|
145
|
+
</li>
|
|
146
|
+
))}
|
|
147
|
+
</ul>
|
|
148
|
+
</section>
|
|
149
|
+
);
|
|
150
|
+
})}
|
|
151
|
+
|
|
152
|
+
{shown === 0 && (
|
|
153
|
+
<p className="decisions-empty">
|
|
154
|
+
No decisions match
|
|
155
|
+
{state.q ? ` "${state.q}"` : ''}
|
|
156
|
+
{` with status ${state.status.length ? state.status.join(', ') : 'none'}`}
|
|
157
|
+
{state.category.length ? ` in ${state.category.join(', ')}` : ''}.
|
|
158
|
+
</p>
|
|
159
|
+
)}
|
|
160
|
+
</div>
|
|
161
|
+
);
|
|
162
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// The Decisions view's search, filters, and grouping, kept in the page URL. The
|
|
2
|
+
// server has no location, so the first render is DEFAULT_DECISIONS_STATE
|
|
3
|
+
// (hydration must match it); the query is read in an effect on mount, and
|
|
4
|
+
// every later change is written back with history.replaceState.
|
|
5
|
+
import { useEffect, useState } from 'react';
|
|
6
|
+
import type { Dispatch, SetStateAction } from 'react';
|
|
7
|
+
|
|
8
|
+
import { DEFAULT_DECISIONS_STATE, decisionsQuery, parseDecisionsQuery, type DecisionsState } from '../../lib/decisions';
|
|
9
|
+
|
|
10
|
+
export function useDecisionsUrlState(categories: string[]): [DecisionsState, Dispatch<SetStateAction<DecisionsState>>] {
|
|
11
|
+
const [state, setState] = useState<DecisionsState>(DEFAULT_DECISIONS_STATE);
|
|
12
|
+
const [applied, setApplied] = useState(false);
|
|
13
|
+
|
|
14
|
+
useEffect(() => {
|
|
15
|
+
setState(parseDecisionsQuery(location.search, categories));
|
|
16
|
+
setApplied(true);
|
|
17
|
+
// Mount only: the categories are fixed at build time.
|
|
18
|
+
}, []);
|
|
19
|
+
|
|
20
|
+
useEffect(() => {
|
|
21
|
+
if (!applied) return;
|
|
22
|
+
|
|
23
|
+
const url = location.pathname + decisionsQuery(state) + location.hash;
|
|
24
|
+
|
|
25
|
+
if (url !== location.pathname + location.search + location.hash) history.replaceState(null, '', url);
|
|
26
|
+
}, [state, applied]);
|
|
27
|
+
|
|
28
|
+
return [state, setState];
|
|
29
|
+
}
|
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
// The Graph island on the Graph page: open items, the done, dropped, and
|
|
2
|
+
// missing IDs they point at, and their Depends on and Revisits links, drawn
|
|
3
|
+
// with React Flow. Every position comes from the four build-time layouts
|
|
4
|
+
// (src/lib/graph-layout.ts, run in graph.astro's frontmatter); this file only
|
|
5
|
+
// picks one, so no layout code reaches the browser. It may only `import type`
|
|
6
|
+
// from graph-layout.ts, which imports dagre, and from graph.ts, which imports
|
|
7
|
+
// planning.ts (node:fs); its runtime helpers come from graph-state.ts.
|
|
8
|
+
//
|
|
9
|
+
// The server renders the default layout (lanes on, done chips on) fitted to a
|
|
10
|
+
// nominal canvas size, and hydration starts from the same nodes and the same
|
|
11
|
+
// transform (`defaultViewport`), so the two match; the island then fits the
|
|
12
|
+
// real canvas. The switches and the
|
|
13
|
+
// selection live in the URL (useGraphUrlState.ts). Clicking a node, or Enter
|
|
14
|
+
// on it, selects it and highlights its chain (chainOf); everything else gets
|
|
15
|
+
// `data-dimmed`. Clicking the selected node again, or an item's ID link,
|
|
16
|
+
// opens its feature page. Escape, or a click on the background or a lane,
|
|
17
|
+
// clears the selection. The wheel zooms only over the canvas, as React Flow
|
|
18
|
+
// does by default, so the page still scrolls past it.
|
|
19
|
+
import { getViewportForBounds, MarkerType, Position, ReactFlow, ReactFlowProvider, useReactFlow } from '@xyflow/react';
|
|
20
|
+
import type { Edge, NodeMouseHandler, Viewport } from '@xyflow/react';
|
|
21
|
+
import { useEffect, useMemo } from 'react';
|
|
22
|
+
import type { KeyboardEvent } from 'react';
|
|
23
|
+
|
|
24
|
+
import type { GraphEdge, GraphNode } from '../../lib/graph';
|
|
25
|
+
import { chainOf, layoutKey } from '../../lib/graph-state';
|
|
26
|
+
import type { GraphState } from '../../lib/graph-state';
|
|
27
|
+
import type { GraphLayout, LayoutKey } from '../../lib/graph-layout';
|
|
28
|
+
import { NODE_TYPES } from './GraphNodes';
|
|
29
|
+
import type { GraphFlowNode } from './GraphNodes';
|
|
30
|
+
import { DEFAULT_GRAPH_STATE, useGraphUrlState } from './useGraphUrlState';
|
|
31
|
+
|
|
32
|
+
interface Props {
|
|
33
|
+
nodes: GraphNode[];
|
|
34
|
+
edges: GraphEdge[];
|
|
35
|
+
layouts: Record<LayoutKey, GraphLayout>;
|
|
36
|
+
/** Milestone page by milestone ID (and `none`), for the lane labels and item meta lines; absent without a page. */
|
|
37
|
+
milestoneHrefs: Record<string, string>;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** The canvas size the server render (and so the first client render) is fitted to. */
|
|
41
|
+
const SERVER_VIEW = { width: 960, height: 540 };
|
|
42
|
+
/** How far a lane band reaches past the outermost nodes on each side. */
|
|
43
|
+
const LANE_PAD = 16;
|
|
44
|
+
/** The lane and tray label band's height (graph-layout.ts LABEL_BAND). */
|
|
45
|
+
const LABEL_BAND = 32;
|
|
46
|
+
const ZOOM = { min: 0.25, max: 2 };
|
|
47
|
+
/** The space kept around the graph when it is fitted. */
|
|
48
|
+
const FIT = { padding: '16px' } as const;
|
|
49
|
+
|
|
50
|
+
/** Data attributes on a node's or edge's React Flow element: present when `true`, absent otherwise. */
|
|
51
|
+
function flag(on: boolean): string | undefined {
|
|
52
|
+
return on ? '' : undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** React Flow's `domAttributes` take no data attributes in their type; they are spread onto the element. */
|
|
56
|
+
function dataAttributes(attributes: Record<string, string | undefined>): Record<string, string> {
|
|
57
|
+
return Object.fromEntries(Object.entries(attributes).filter((entry): entry is [string, string] => entry[1] !== undefined));
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** The React Flow nodes for one layout: lane bands and the tray label first, then every boxed item and chip. */
|
|
61
|
+
function flowNodes(data: GraphNode[], layout: GraphLayout, state: GraphState, chain: Set<string> | null, milestoneHrefs: Record<string, string>): GraphFlowNode[] {
|
|
62
|
+
const backdrop: GraphFlowNode[] = layout.lanes.map((lane) => ({
|
|
63
|
+
id: `lane:${lane.key}`,
|
|
64
|
+
type: 'lane',
|
|
65
|
+
position: { x: -LANE_PAD, y: lane.y },
|
|
66
|
+
width: layout.width + LANE_PAD * 2,
|
|
67
|
+
height: lane.height,
|
|
68
|
+
zIndex: -1,
|
|
69
|
+
selectable: false,
|
|
70
|
+
focusable: false,
|
|
71
|
+
draggable: false,
|
|
72
|
+
data: { lane, href: milestoneHrefs[lane.key] ?? null },
|
|
73
|
+
}));
|
|
74
|
+
|
|
75
|
+
if (layout.tray) {
|
|
76
|
+
backdrop.push({
|
|
77
|
+
id: 'tray',
|
|
78
|
+
type: 'tray',
|
|
79
|
+
position: { x: 0, y: layout.tray.y },
|
|
80
|
+
width: layout.width,
|
|
81
|
+
height: LABEL_BAND,
|
|
82
|
+
zIndex: -1,
|
|
83
|
+
selectable: false,
|
|
84
|
+
focusable: false,
|
|
85
|
+
draggable: false,
|
|
86
|
+
data: {},
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const boxed = data.flatMap((node): GraphFlowNode[] => {
|
|
91
|
+
const box = layout.boxes[node.id];
|
|
92
|
+
|
|
93
|
+
if (!box) return [];
|
|
94
|
+
|
|
95
|
+
const shared = {
|
|
96
|
+
id: node.id,
|
|
97
|
+
position: { x: box.x, y: box.y },
|
|
98
|
+
width: box.width,
|
|
99
|
+
height: box.height,
|
|
100
|
+
selected: state.focus === node.id,
|
|
101
|
+
draggable: false,
|
|
102
|
+
// The accessible name carries the full title, which the node truncates.
|
|
103
|
+
ariaLabel: node.title === null ? `${node.id} not found` : node.kind === 'item' ? `${node.id} ${node.title}` : `${node.id} ${node.title} (${node.kind})`,
|
|
104
|
+
// Fixed handles, so edges are placed without measuring the DOM (and on the server).
|
|
105
|
+
handles: [
|
|
106
|
+
{ type: 'target' as const, position: Position.Left, x: 0, y: Math.round(box.height / 2), width: 1, height: 1 },
|
|
107
|
+
{ type: 'source' as const, position: Position.Right, x: box.width - 1, y: Math.round(box.height / 2), width: 1, height: 1 },
|
|
108
|
+
],
|
|
109
|
+
domAttributes: dataAttributes({
|
|
110
|
+
'data-graph-node': node.id,
|
|
111
|
+
'data-kind': node.kind,
|
|
112
|
+
'data-selected': flag(state.focus === node.id),
|
|
113
|
+
'data-dimmed': flag(chain !== null && !chain.has(node.id)),
|
|
114
|
+
}),
|
|
115
|
+
};
|
|
116
|
+
|
|
117
|
+
return [node.kind === 'item' ? { ...shared, type: 'item', data: { node, showDoneCount: !state.done, milestoneHref: node.milestone ? (milestoneHrefs[node.milestone] ?? null) : null } } : { ...shared, type: 'chip', data: { node } }];
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
return [...backdrop, ...boxed];
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** The React Flow edges drawn in one layout: both ends boxed. */
|
|
124
|
+
function flowEdges(edges: GraphEdge[], layout: GraphLayout, chain: Set<string> | null): Edge[] {
|
|
125
|
+
return edges
|
|
126
|
+
.filter((edge) => layout.boxes[edge.source] && layout.boxes[edge.target])
|
|
127
|
+
.map((edge) => ({
|
|
128
|
+
id: edge.id,
|
|
129
|
+
source: edge.source,
|
|
130
|
+
target: edge.target,
|
|
131
|
+
type: 'default',
|
|
132
|
+
className: ['plan-graph__edge', `plan-graph__edge--${edge.kind}`, edge.fromChip ? 'plan-graph__edge--muted' : ''].filter(Boolean).join(' '),
|
|
133
|
+
...(edge.kind === 'revisits' ? { label: 'revisits' } : {}),
|
|
134
|
+
// A muted (from-chip) edge colours its own arrowhead; a full-contrast one is
|
|
135
|
+
// left uncoloured inline so the CSS rule on .react-flow__arrowhead polyline applies.
|
|
136
|
+
markerEnd: { type: MarkerType.ArrowClosed, width: 16, height: 16, ...(edge.fromChip ? { color: 'var(--sl-color-gray-5)' } : {}) },
|
|
137
|
+
selectable: false,
|
|
138
|
+
focusable: false,
|
|
139
|
+
domAttributes: dataAttributes({
|
|
140
|
+
'data-graph-edge': edge.id,
|
|
141
|
+
'data-kind': edge.kind,
|
|
142
|
+
'data-dimmed': flag(chain !== null && !chain.has(edge.id)),
|
|
143
|
+
}),
|
|
144
|
+
}));
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The default layout fitted to SERVER_VIEW: the transform the provider's `fitView` gives the server render.
|
|
149
|
+
* React Flow's pan and zoom start from `defaultViewport` on the client, so passing this keeps hydration on the
|
|
150
|
+
* server's frame until the island fits the real canvas.
|
|
151
|
+
*/
|
|
152
|
+
function fittedViewport(list: GraphFlowNode[]): Viewport {
|
|
153
|
+
const left = Math.min(...list.map((node) => node.position.x));
|
|
154
|
+
const top = Math.min(...list.map((node) => node.position.y));
|
|
155
|
+
const right = Math.max(...list.map((node) => node.position.x + (node.width ?? 0)));
|
|
156
|
+
const bottom = Math.max(...list.map((node) => node.position.y + (node.height ?? 0)));
|
|
157
|
+
|
|
158
|
+
return getViewportForBounds({ x: left, y: top, width: right - left, height: bottom - top }, SERVER_VIEW.width, SERVER_VIEW.height, ZOOM.min, ZOOM.max, FIT.padding);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
function GraphView({ nodes, edges, layouts, milestoneHrefs, initialViewport }: Props & { initialViewport: Viewport }) {
|
|
162
|
+
const [state, update, applied] = useGraphUrlState(layouts);
|
|
163
|
+
const { zoomIn, zoomOut, fitView } = useReactFlow();
|
|
164
|
+
const key = layoutKey(state);
|
|
165
|
+
const layout = layouts[key];
|
|
166
|
+
const chain = useMemo(() => (state.focus ? chainOf(edges, state.focus, layout) : null), [edges, state.focus, layout]);
|
|
167
|
+
const flowNodeList = useMemo(() => flowNodes(nodes, layout, state, chain, milestoneHrefs), [nodes, layout, state, chain, milestoneHrefs]);
|
|
168
|
+
const flowEdgeList = useMemo(() => flowEdges(edges, layout, chain), [edges, layout, chain]);
|
|
169
|
+
const hrefs = useMemo(() => new Map(nodes.map((node) => [node.id, node.href])), [nodes]);
|
|
170
|
+
|
|
171
|
+
// A new layout has new extents: fit it once its nodes are in the store.
|
|
172
|
+
useEffect(() => {
|
|
173
|
+
if (applied) void fitView(FIT);
|
|
174
|
+
}, [key, applied]);
|
|
175
|
+
|
|
176
|
+
const open = (id: string) => {
|
|
177
|
+
const href = hrefs.get(id);
|
|
178
|
+
|
|
179
|
+
if (href) location.assign(href);
|
|
180
|
+
};
|
|
181
|
+
|
|
182
|
+
const onNodeClick: NodeMouseHandler<GraphFlowNode> = (event, node) => {
|
|
183
|
+
if (node.type === 'lane' || node.type === 'tray') {
|
|
184
|
+
update({ focus: null });
|
|
185
|
+
return;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// A link inside the node follows itself (a chip's link only once it is selected).
|
|
189
|
+
if (event.target instanceof Element && event.target.closest('a')) {
|
|
190
|
+
if (state.focus !== node.id) update({ focus: node.id });
|
|
191
|
+
return;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
if (state.focus === node.id) open(node.id);
|
|
195
|
+
else update({ focus: node.id });
|
|
196
|
+
};
|
|
197
|
+
|
|
198
|
+
const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
|
|
199
|
+
if (event.key === 'Escape') {
|
|
200
|
+
update({ focus: null });
|
|
201
|
+
return;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
if (event.key !== 'Enter' || !(event.target instanceof HTMLElement)) return;
|
|
205
|
+
|
|
206
|
+
const id = event.target.dataset.graphNode;
|
|
207
|
+
|
|
208
|
+
if (!id) return;
|
|
209
|
+
|
|
210
|
+
event.preventDefault();
|
|
211
|
+
if (state.focus === id) open(id);
|
|
212
|
+
else update({ focus: id });
|
|
213
|
+
};
|
|
214
|
+
|
|
215
|
+
return (
|
|
216
|
+
<div className="plan-graph not-content" data-layout={key} data-pagefind-ignore onKeyDown={onKeyDown}>
|
|
217
|
+
<div className="plan-graph__toolbar" hidden={!applied}>
|
|
218
|
+
<div className="plan-graph__group" role="group" aria-label="View">
|
|
219
|
+
<button type="button" role="switch" aria-checked={state.lanes} onClick={() => update({ lanes: !state.lanes })}>
|
|
220
|
+
Milestone lanes
|
|
221
|
+
</button>
|
|
222
|
+
<button type="button" role="switch" aria-checked={state.done} onClick={() => update({ done: !state.done })}>
|
|
223
|
+
Show done prerequisites
|
|
224
|
+
</button>
|
|
225
|
+
</div>
|
|
226
|
+
<div className="plan-graph__group" role="group" aria-label="Zoom">
|
|
227
|
+
<button type="button" aria-label="Zoom out" onClick={() => void zoomOut()}>
|
|
228
|
+
−
|
|
229
|
+
</button>
|
|
230
|
+
<button type="button" aria-label="Zoom in" onClick={() => void zoomIn()}>
|
|
231
|
+
+
|
|
232
|
+
</button>
|
|
233
|
+
<button type="button" onClick={() => void fitView(FIT)}>
|
|
234
|
+
Fit
|
|
235
|
+
</button>
|
|
236
|
+
</div>
|
|
237
|
+
</div>
|
|
238
|
+
|
|
239
|
+
<div className="plan-graph__canvas">
|
|
240
|
+
<ReactFlow<GraphFlowNode, Edge>
|
|
241
|
+
nodes={flowNodeList}
|
|
242
|
+
edges={flowEdgeList}
|
|
243
|
+
nodeTypes={NODE_TYPES}
|
|
244
|
+
nodesDraggable={false}
|
|
245
|
+
nodesConnectable={false}
|
|
246
|
+
elementsSelectable
|
|
247
|
+
fitView
|
|
248
|
+
fitViewOptions={FIT}
|
|
249
|
+
defaultViewport={initialViewport}
|
|
250
|
+
minZoom={ZOOM.min}
|
|
251
|
+
maxZoom={ZOOM.max}
|
|
252
|
+
defaultMarkerColor={null}
|
|
253
|
+
deleteKeyCode={null}
|
|
254
|
+
selectionKeyCode={null}
|
|
255
|
+
multiSelectionKeyCode={null}
|
|
256
|
+
onNodeClick={onNodeClick}
|
|
257
|
+
onPaneClick={() => update({ focus: null })}
|
|
258
|
+
aria-label="Dependency graph"
|
|
259
|
+
/>
|
|
260
|
+
</div>
|
|
261
|
+
</div>
|
|
262
|
+
);
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/** The Graph island: `nodes` and `edges` once, the four build-time layouts they are placed by, and the milestone pages. */
|
|
266
|
+
export default function Graph({ nodes, edges, layouts, milestoneHrefs }: Props) {
|
|
267
|
+
// The provider's first state is the default layout fitted to SERVER_VIEW, on the server and on hydration alike.
|
|
268
|
+
const initial = useMemo(() => {
|
|
269
|
+
const layout = layouts[layoutKey(DEFAULT_GRAPH_STATE)];
|
|
270
|
+
|
|
271
|
+
const first = flowNodes(nodes, layout, DEFAULT_GRAPH_STATE, null, milestoneHrefs);
|
|
272
|
+
|
|
273
|
+
return { nodes: first, edges: flowEdges(edges, layout, null), viewport: fittedViewport(first) };
|
|
274
|
+
}, [nodes, edges, layouts, milestoneHrefs]);
|
|
275
|
+
|
|
276
|
+
return (
|
|
277
|
+
<ReactFlowProvider
|
|
278
|
+
initialNodes={initial.nodes}
|
|
279
|
+
initialEdges={initial.edges}
|
|
280
|
+
initialWidth={SERVER_VIEW.width}
|
|
281
|
+
initialHeight={SERVER_VIEW.height}
|
|
282
|
+
initialMinZoom={ZOOM.min}
|
|
283
|
+
initialMaxZoom={ZOOM.max}
|
|
284
|
+
initialFitViewOptions={FIT}
|
|
285
|
+
fitView
|
|
286
|
+
>
|
|
287
|
+
<GraphView nodes={nodes} edges={edges} layouts={layouts} milestoneHrefs={milestoneHrefs} initialViewport={initial.viewport} />
|
|
288
|
+
</ReactFlowProvider>
|
|
289
|
+
);
|
|
290
|
+
}
|