@purview-dev/pm-docs-site 0.1.0-pre.1 → 0.1.0-pre.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +130 -18
  2. package/dist/cli.d.ts +2 -0
  3. package/dist/cli.js +91 -0
  4. package/dist/dev-env.d.ts +2 -0
  5. package/dist/dev-env.js +13 -0
  6. package/dist/fs-allow.d.ts +2 -0
  7. package/dist/fs-allow.js +11 -0
  8. package/dist/index.d.ts +7 -0
  9. package/dist/index.js +152 -0
  10. package/dist/options.d.ts +5 -0
  11. package/dist/options.js +46 -0
  12. package/dist/repo-docs.d.ts +33 -0
  13. package/dist/repo-docs.js +94 -0
  14. package/dist/schema-version.d.ts +27 -0
  15. package/dist/schema-version.js +48 -0
  16. package/dist/sidebar.d.ts +10 -0
  17. package/dist/sidebar.js +32 -0
  18. package/dist/site-options.d.ts +9 -0
  19. package/dist/site-options.js +44 -0
  20. package/dist/types.d.ts +47 -0
  21. package/dist/types.js +4 -0
  22. package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
  23. package/lib/schema-version.ts +59 -0
  24. package/{index.d.ts → lib/types.ts} +5 -6
  25. package/package.json +19 -9
  26. package/src/components/FeatureSummary.astro +30 -9
  27. package/src/components/FeatureTable.astro +1 -1
  28. package/src/components/ItemDetail.astro +1 -1
  29. package/src/components/ItemDialog.astro +12 -8
  30. package/src/components/PlanInteractions.astro +15 -3
  31. package/src/components/RefLink.astro +7 -4
  32. package/src/components/board/Board.tsx +252 -0
  33. package/src/components/board/KanbanItemCard.tsx +131 -0
  34. package/src/components/board/LinkRuns.tsx +21 -0
  35. package/src/components/board/TaskKanbanCard.tsx +83 -0
  36. package/src/components/board/useBoardUrlState.ts +41 -0
  37. package/src/components/decisions/Decisions.tsx +162 -0
  38. package/src/components/decisions/useDecisionsUrlState.ts +29 -0
  39. package/src/components/graph/Graph.tsx +290 -0
  40. package/src/components/graph/GraphNodes.tsx +120 -0
  41. package/src/components/graph/useGraphUrlState.ts +58 -0
  42. package/src/components/lib/KanbanItemCard.astro +7 -11
  43. package/src/components/lib/StatusTimelineFeed.astro +3 -2
  44. package/src/components/lib/TaskKanbanCard.astro +2 -1
  45. package/src/components/timeline/Timeline.tsx +192 -0
  46. package/src/components/timeline/useTimelineLayout.ts +39 -0
  47. package/src/content.config.ts +22 -6
  48. package/src/env.d.ts +2 -2
  49. package/src/lib/board-data.ts +84 -0
  50. package/src/lib/board.ts +209 -0
  51. package/src/lib/decisions.ts +100 -0
  52. package/src/lib/graph-layout.ts +270 -0
  53. package/src/lib/graph-state.ts +99 -0
  54. package/src/lib/graph.ts +194 -0
  55. package/src/lib/link-html.ts +39 -0
  56. package/src/lib/planning-types.ts +32 -3
  57. package/src/lib/planning.ts +94 -52
  58. package/src/lib/ref-boundary.ts +19 -0
  59. package/src/lib/references.ts +67 -8
  60. package/src/lib/timeline-state.ts +119 -0
  61. package/src/lib/timeline.ts +51 -0
  62. package/src/loaders/adrs.ts +43 -0
  63. package/src/loaders/repo-docs.ts +3 -3
  64. package/src/pages/404.astro +18 -0
  65. package/src/pages/index.astro +1 -1
  66. package/src/pages/plan/board.astro +14 -113
  67. package/src/pages/plan/log.astro +18 -1
  68. package/src/pages/plan/roadmap.astro +21 -3
  69. package/src/routes/plan/decisions/[id].astro +93 -0
  70. package/src/routes/plan/decisions.astro +52 -0
  71. package/src/routes/plan/graph.astro +80 -0
  72. package/src/routes/plan/milestones/index.astro +2 -2
  73. package/src/routes/plan/now.astro +2 -3
  74. package/src/scripts/plan.ts +32 -46
  75. package/src/styles/components.css +244 -13
  76. package/src/styles/graph.css +296 -0
  77. package/src/styles/kanban.css +277 -0
  78. package/src/styles/timeline.css +210 -0
  79. package/cli.mjs +0 -120
  80. package/index.mjs +0 -97
  81. package/lib/options.mjs +0 -67
  82. package/lib/schema-version.mjs +0 -29
  83. package/lib/sidebar.mjs +0 -47
  84. package/lib/site-options.mjs +0 -38
@@ -0,0 +1,120 @@
1
+ // The Graph island's React Flow node components: an open item, a chip (a
2
+ // done, dropped, or missing ID an item points at), a milestone lane band, and
3
+ // the `No links` tray label. Sizes come from the build-time layout (each node
4
+ // has an explicit width and height), so nothing here is measured. Every item
5
+ // and chip has one target handle on its left and one source handle on its
6
+ // right; the edges run between them. Styles are in src/styles/graph.css.
7
+ import { Handle, Position } from '@xyflow/react';
8
+ import type { Node, NodeProps } from '@xyflow/react';
9
+ import type { MouseEvent } from 'react';
10
+
11
+ import type { GraphNode } from '../../lib/graph';
12
+ import type { Lane } from '../../lib/graph-layout';
13
+
14
+ /** `milestoneHref`: the item's milestone page, or `null` when it has none or the Milestones view is off. */
15
+ export type ItemFlowNode = Node<{ node: GraphNode; showDoneCount: boolean; milestoneHref: string | null }, 'item'>;
16
+ export type ChipFlowNode = Node<{ node: GraphNode }, 'chip'>;
17
+ /** `href`: the lane's milestone page, or `null`. */
18
+ export type LaneFlowNode = Node<{ lane: Lane; href: string | null }, 'lane'>;
19
+ export type TrayFlowNode = Node<Record<string, never>, 'tray'>;
20
+ export type GraphFlowNode = ItemFlowNode | ChipFlowNode | LaneFlowNode | TrayFlowNode;
21
+
22
+ const SECTIONS = { now: 'Now', next: 'Next', later: 'Later' } as const;
23
+
24
+ /** The fixed handles: edges leave an item or chip on its right and enter on its left. */
25
+ function Handles() {
26
+ return (
27
+ <>
28
+ <Handle type="target" position={Position.Left} isConnectable={false} className="plan-graph__handle" />
29
+ <Handle type="source" position={Position.Right} isConnectable={false} className="plan-graph__handle" />
30
+ </>
31
+ );
32
+ }
33
+
34
+ /** An open item: its ID (a link to its feature page), title, meta line, and notices. */
35
+ export function ItemNode({ data }: NodeProps<ItemFlowNode>) {
36
+ const { node, showDoneCount, milestoneHref } = data;
37
+ const rest = [node.size, node.section ? SECTIONS[node.section] : null, node.owner ?? 'agent'].filter(Boolean).join(' · ');
38
+ const notes = [showDoneCount && node.donePrerequisites > 0 ? `✓ ${node.donePrerequisites} done` : null].filter(Boolean);
39
+
40
+ return (
41
+ <div className="plan-graph__item" data-active={node.active ? '' : undefined} data-blocked={node.blocked ? '' : undefined}>
42
+ <Handles />
43
+ <p className="plan-graph__head">
44
+ {node.href ? (
45
+ <a className="plan-graph__id" href={node.href}>
46
+ {node.id}
47
+ </a>
48
+ ) : (
49
+ <span className="plan-graph__id">{node.id}</span>
50
+ )}{' '}
51
+ <span className="plan-graph__title">{node.title}</span>
52
+ </p>
53
+ <p className="plan-graph__meta">
54
+ {milestoneHref ? <a href={milestoneHref}>{node.milestone}</a> : (node.milestone ?? 'No milestone')}
55
+ {` · ${rest}`}
56
+ </p>
57
+ {notes.length > 0 && <p className="plan-graph__note">{notes.join(' · ')}</p>}
58
+ </div>
59
+ );
60
+ }
61
+
62
+ /** The chip text: `✓ R-008` (done), `✗ R-003` (dropped), `? R-099 not found` (missing). */
63
+ function chipText(node: GraphNode): string {
64
+ if (node.kind === 'done') return `✓ ${node.id}`;
65
+ if (node.kind === 'dropped') return `✗ ${node.id}`;
66
+
67
+ return `? ${node.id} not found`;
68
+ }
69
+
70
+ /**
71
+ * A done, dropped, or missing ID. A chip with a feature page is a link, but
72
+ * the first click only selects it (the island's node click handler); the
73
+ * click on the selected chip follows the link.
74
+ */
75
+ export function ChipNode({ data, selected }: NodeProps<ChipFlowNode>) {
76
+ const { node } = data;
77
+ const text = chipText(node);
78
+ const follow = (event: MouseEvent<HTMLAnchorElement>) => {
79
+ if (!selected) event.preventDefault();
80
+ };
81
+
82
+ return (
83
+ <div className="plan-graph__chip" data-chip={node.kind}>
84
+ <Handles />
85
+ {node.href ? (
86
+ <a className="plan-graph__chip-text" href={node.href} onClick={follow}>
87
+ {text}
88
+ </a>
89
+ ) : (
90
+ <span className="plan-graph__chip-text">{text}</span>
91
+ )}
92
+ </div>
93
+ );
94
+ }
95
+
96
+ /** A milestone lane band, drawn behind its nodes, with its label and the `Focus` badge. */
97
+ export function LaneNode({ data }: NodeProps<LaneFlowNode>) {
98
+ const { lane, href } = data;
99
+
100
+ return (
101
+ <div className="plan-graph__lane" data-lane={lane.key}>
102
+ <p className="plan-graph__lane-label">
103
+ {href ? <a href={href}>{lane.label}</a> : lane.label}
104
+ {lane.isFocus && <span className="plan-graph__focus">Focus</span>}
105
+ </p>
106
+ </div>
107
+ );
108
+ }
109
+
110
+ /** The `No links` label above the flow layouts' row of isolated items. */
111
+ export function TrayNode() {
112
+ return (
113
+ <div className="plan-graph__tray">
114
+ <p className="plan-graph__lane-label">No links</p>
115
+ </div>
116
+ );
117
+ }
118
+
119
+ /** The island's node types, defined once so React Flow never sees a new object. */
120
+ export const NODE_TYPES = { item: ItemNode, chip: ChipNode, lane: LaneNode, tray: TrayNode };
@@ -0,0 +1,58 @@
1
+ // The Graph's switches and selection, kept in the page URL as `lanes=off`,
2
+ // `done=off`, and `focus=<ID>`. The server has no location, so the first render
3
+ // is always the default (lanes on, done chips on, nothing selected; hydration
4
+ // must match it); the query is read in an effect on mount, and a `focus` from
5
+ // it is kept only when it names a node drawn in that layout. Every later
6
+ // change is written back with history.replaceState through graphQuery, which
7
+ // keeps every other parameter and the hash. A change of switches that hides
8
+ // the focused node clears the focus. The pending mark (`data-graph-pending` on
9
+ // <html>, set before paint by the inline script in graph.astro when the URL
10
+ // turns a switch off) keeps the graph hidden until the parsed layout has
11
+ // rendered, so such a link never flashes the default layout first.
12
+ import { useCallback, useEffect, useState } from 'react';
13
+
14
+ import { graphQuery, layoutKey, parseGraphQuery, resolveFocus } from '../../lib/graph-state';
15
+ import type { GraphState } from '../../lib/graph-state';
16
+ import type { GraphLayout, LayoutKey } from '../../lib/graph-layout';
17
+
18
+ /** The default view: lanes on, done chips on, nothing selected. */
19
+ export const DEFAULT_GRAPH_STATE: GraphState = { lanes: true, done: true, focus: null };
20
+
21
+ /** `state` with its focus dropped unless the node is drawn in the state's layout. */
22
+ function resolved(state: GraphState, layouts: Record<LayoutKey, GraphLayout>): GraphState {
23
+ return { ...state, focus: resolveFocus(state.focus, layouts[layoutKey(state)]) };
24
+ }
25
+
26
+ /**
27
+ * The graph's URL state, a setter that merges a partial change (and clears a
28
+ * focus the new layout does not draw), and whether the URL's state is applied.
29
+ */
30
+ export function useGraphUrlState(layouts: Record<LayoutKey, GraphLayout>): [GraphState, (change: Partial<GraphState>) => void, boolean] {
31
+ const [state, setState] = useState<GraphState>(DEFAULT_GRAPH_STATE);
32
+ // True once the URL's state is applied: the render after it shows the parsed layout.
33
+ const [applied, setApplied] = useState(false);
34
+
35
+ useEffect(() => {
36
+ setState(resolved(parseGraphQuery(location.search), layouts));
37
+ setApplied(true);
38
+ // Mount only: the layouts are fixed at build time.
39
+ }, []);
40
+
41
+ useEffect(() => {
42
+ if (!applied) {
43
+ return;
44
+ }
45
+
46
+ // This effect runs after the render that committed the parsed state, so the graph is already laid out when it shows.
47
+ delete document.documentElement.dataset.graphPending;
48
+ const url = location.pathname + graphQuery(state, location.search) + location.hash;
49
+
50
+ if (url !== location.pathname + location.search + location.hash) {
51
+ history.replaceState(history.state, '', url);
52
+ }
53
+ }, [state, applied]);
54
+
55
+ const update = useCallback((change: Partial<GraphState>) => setState((current) => resolved({ ...current, ...change }, layouts)), [layouts]);
56
+
57
+ return [state, update, applied];
58
+ }
@@ -4,9 +4,12 @@
4
4
  *
5
5
  * From the Astro Components Kit by Konstantin (https://astrocomponents.dev/docs/kanban-item-card/,
6
6
  * https://github.com/konstantinWDK/astro-components), MIT License. Copied from its manual-install
7
- * source; the only changes are that hard-coded dark-theme colours use Starlight theme variables,
7
+ * source; the changes are that hard-coded dark-theme colours use Starlight theme variables,
8
8
  * so the card reads in light and dark themes, and that the title (and tag) can be a link, for the
9
9
  * site's item popup and backlinks (href, itemId, tagHref), and the due-date line (and a title that is not a link) links known IDs.
10
+ * The title link carries `aria-haspopup="dialog"` when it is the popup trigger. The card is not
11
+ * focusable and has no role (one tab stop per link), and the drag cursor is gone, matching the
12
+ * React port.
10
13
  *
11
14
  * @param {string} title - The description or summary of the task ticket.
12
15
  * @param {'low'|'medium'|'high'|'urgent'} priority - Priority level flag. Default is 'high'.
@@ -57,7 +60,7 @@ const priorityMap = {
57
60
  const currentPriority = priorityMap[priority] || priorityMap.high;
58
61
  ---
59
62
 
60
- <div class="k-item" tabindex="0" role="article" aria-label={`Task: ${title}`}>
63
+ <div class="k-item">
61
64
  <div class="k-item__head">
62
65
  {tagHref ? <a class="k-item__tag" href={tagHref}>{tag}</a> : <span class="k-item__tag">{tag}</span>}
63
66
  <span
@@ -69,7 +72,7 @@ const currentPriority = priorityMap[priority] || priorityMap.high;
69
72
  </span>
70
73
  </div>
71
74
 
72
- <h4 class="k-item__title">{href ? <a class="plan-item-link" href={href} data-item={itemId}>{title}</a> : <LinkedText text={title} />}</h4>
75
+ <h4 class="k-item__title">{href ? <a class="plan-item-link" href={href} data-item={itemId} aria-haspopup={itemId ? 'dialog' : undefined}>{title}</a> : <LinkedText text={title} />}</h4>
73
76
 
74
77
  <div class="k-item__footer">
75
78
  <div class="k-item__meta">
@@ -153,27 +156,20 @@ const currentPriority = priorityMap[priority] || priorityMap.high;
153
156
  display: flex;
154
157
  flex-direction: column;
155
158
  gap: 0.65rem;
156
- cursor: grab;
157
159
  transition:
158
160
  transform 0.2s cubic-bezier(0.16, 1, 0.3, 1),
159
161
  border-color 0.2s ease,
160
162
  box-shadow 0.2s ease;
161
163
  max-width: 300px;
162
164
  box-sizing: border-box;
163
- outline: none;
164
165
  }
165
166
 
166
- .k-item:hover,
167
- .k-item:focus-visible {
167
+ .k-item:hover {
168
168
  transform: translateY(-2px);
169
169
  border-color: var(--sl-color-accent, rgba(99, 102, 241, 0.4));
170
170
  box-shadow: 0 10px 24px -6px rgba(0, 0, 0, 0.25);
171
171
  }
172
172
 
173
- .k-item:focus-visible {
174
- box-shadow: 0 0 0 2px var(--c-primary, #6366f1);
175
- }
176
-
177
173
  .k-item__head {
178
174
  display: flex;
179
175
  justify-content: space-between;
@@ -6,7 +6,8 @@
6
6
  * https://github.com/konstantinWDK/astro-components), MIT License. Copied from its manual-install
7
7
  * source; the only changes are that hard-coded dark-theme colours use Starlight theme variables,
8
8
  * the feed fills its column instead of stopping at 440px, and an event's title can be a link (href,
9
- * itemId) and its description links known IDs, for the site's item popup and backlinks.
9
+ * itemId) and its description links known IDs, for the site's item popup and backlinks. The title
10
+ * link carries `aria-haspopup="dialog"` when it is the popup trigger.
10
11
  *
11
12
  * @param {Array<{title: string, desc: string, time: string, status: 'done' | 'active' | 'pending', href?: string, itemId?: string}>} events - Timeline events.
12
13
  */
@@ -65,7 +66,7 @@ const {
65
66
  </div>
66
67
  <div class="status-feed__content">
67
68
  <div class="status-feed__header">
68
- <h5 class="status-feed__title">{evt.href ? <a class="plan-item-link" href={evt.href} data-item={evt.itemId}>{evt.title}</a> : evt.title}</h5>
69
+ <h5 class="status-feed__title">{evt.href ? <a class="plan-item-link" href={evt.href} data-item={evt.itemId} aria-haspopup={evt.itemId ? 'dialog' : undefined}>{evt.title}</a> : evt.title}</h5>
69
70
  <span class="status-feed__time">{evt.time}</span>
70
71
  </div>
71
72
  <p class="status-feed__desc">
@@ -7,6 +7,7 @@
7
7
  * source; the only changes are that hard-coded dark-theme colours use Starlight theme variables,
8
8
  * so the card reads in light and dark themes, and that the task can be a link, for the site's
9
9
  * item popup and backlinks (href, itemId), and a task that is not a link links known IDs.
10
+ * The task link carries `aria-haspopup="dialog"` when it is the popup trigger.
10
11
  *
11
12
  * @param {string} task - The description of the task being managed.
12
13
  * @param {string} date - Visual date string indicator (e.g. 'Oct 28').
@@ -50,7 +51,7 @@ const priorityLabels = { low: 'Low', med: 'Medium', high: 'High' };
50
51
  <span class="task-card__pct">{progress}%</span>
51
52
  </div>
52
53
 
53
- <p class="task-card__desc">{href ? <a class="plan-item-link" href={href} data-item={itemId}>{task}</a> : <LinkedText text={task} />}</p>
54
+ <p class="task-card__desc">{href ? <a class="plan-item-link" href={href} data-item={itemId} aria-haspopup={itemId ? 'dialog' : undefined}>{task}</a> : <LinkedText text={task} />}</p>
54
55
 
55
56
  <div
56
57
  class="task-card__progress-wrap"
@@ -0,0 +1,192 @@
1
+ // The Timeline island on the Roadmap page: the milestone cards in strategy
2
+ // order, as a strip laid out left to right or top to bottom, with a toolbar
3
+ // for the layout and the zoom. It is server-rendered horizontal at 100%, so
4
+ // without JavaScript the strip still shows and only the toolbar stays hidden.
5
+ // The layout lives in the URL (useTimelineLayout.ts); the zoom lives only here
6
+ // and sizes the cards through `--timeline-zoom` (src/styles/timeline.css), so
7
+ // text stays sharp and the scroll extents stay real. The strip scrolls with
8
+ // the browser's own scrolling; the wheel listener below only adds Ctrl/Cmd +
9
+ // wheel zoom and a plain vertical wheel that scrolls a horizontal strip
10
+ // sideways while it can. It never calls scrollIntoView, which would move the page.
11
+ // This island imports nothing from `lib/timeline` (which re-exports from and
12
+ // pulls in server-only `lib/planning`); its types and values both come from
13
+ // `lib/timeline-state.ts`, so the browser bundle never includes `lib/planning`.
14
+ import { useEffect, useLayoutEffect, useRef, useState } from 'react';
15
+ import type { CSSProperties } from 'react';
16
+
17
+ import { wheelPixels, wheelScrollsStrip, ZOOM, zoomFromWheel, zoomStep } from '../../lib/timeline-state';
18
+ import type { TimelineMilestone } from '../../lib/timeline-state';
19
+ import { useTimelineLayout } from './useTimelineLayout';
20
+
21
+ /** The element's computed line height in pixels, falling back to `16` when it is `normal` (`NaN`). */
22
+ function lineHeightOf(element: HTMLElement): number {
23
+ const parsed = parseFloat(getComputedStyle(element).lineHeight);
24
+
25
+ return Number.isNaN(parsed) ? 16 : parsed;
26
+ }
27
+
28
+ function Card({ milestone }: { milestone: TimelineMilestone }) {
29
+ const { key, id, name, href, isFocus, status, target, progress } = milestone;
30
+ const title = id === null ? 'No milestone' : `${id} ${name}`;
31
+
32
+ return (
33
+ <li className="plan-timeline__card" data-milestone={key} data-state={status.state} data-focus={isFocus ? '' : undefined}>
34
+ <span className="plan-timeline__marker" aria-hidden="true" />
35
+ <p className="plan-timeline__title">
36
+ {href ? <a href={href}>{title}</a> : <span>{title}</span>}
37
+ {isFocus && <span className="plan-timeline__focus">Focus</span>}
38
+ </p>
39
+ {key !== 'none' && (
40
+ <p className="plan-timeline__status">
41
+ {status.label}
42
+ {status.doneOn && ` · ${status.doneOn}`}
43
+ </p>
44
+ )}
45
+ {key !== 'none' && <p className="plan-timeline__target">{target ? `target ${target}` : 'No target'}</p>}
46
+ <p className="plan-timeline__count">
47
+ {progress.done} of {progress.total} done
48
+ </p>
49
+ {progress.total > 0 && <progress className="plan-timeline__bar" max={progress.total} value={progress.done} />}
50
+ </li>
51
+ );
52
+ }
53
+
54
+ export default function Timeline({ milestones }: { milestones: TimelineMilestone[] }) {
55
+ const [layout, setLayout, applied] = useTimelineLayout();
56
+ const [zoom, setZoom] = useState<number>(ZOOM.default);
57
+ const zoomRef = useRef<number>(ZOOM.default);
58
+ // Accumulated small (trackpad pinch) wheel deltas, in pixels, not yet a whole step.
59
+ const pending = useRef(0);
60
+ const strip = useRef<HTMLOListElement>(null);
61
+ // The horizontal strip's scroll position and zoom just before a zoom change, so the centre stays put.
62
+ const anchor = useRef<{ scrollLeft: number; prev: number } | null>(null);
63
+ const scrolledToFocus = useRef(false);
64
+
65
+ const changeZoom = (next: number) => {
66
+ if (next === zoomRef.current) return;
67
+
68
+ const element = strip.current;
69
+
70
+ // Keep the earliest snapshot: a second zoom before the render must not read the
71
+ // old scroll position against the new zoom. The layout effect clears it once applied.
72
+ if (element && layout === 'horizontal') anchor.current ??= { scrollLeft: element.scrollLeft, prev: zoomRef.current };
73
+ // Back at the rendered zoom before the render: the layout effect will not run, so drop the snapshot.
74
+ if (anchor.current?.prev === next) anchor.current = null;
75
+ zoomRef.current = next;
76
+ setZoom(next);
77
+ };
78
+
79
+ // After the cards have their new size, before paint: keep the point at the strip's centre at its centre.
80
+ useLayoutEffect(() => {
81
+ const element = strip.current;
82
+ const from = anchor.current;
83
+
84
+ anchor.current = null;
85
+ if (!element || !from) return;
86
+
87
+ const half = element.clientWidth / 2;
88
+
89
+ element.scrollLeft = ((from.scrollLeft + half) * zoom) / from.prev - half;
90
+ }, [zoom]);
91
+
92
+ // On first load, bring the focus card into view by scrolling the strip itself, never the page.
93
+ useEffect(() => {
94
+ if (!applied || scrolledToFocus.current) return;
95
+
96
+ scrolledToFocus.current = true;
97
+ const element = strip.current;
98
+ const focus = element?.querySelector<HTMLElement>('.plan-timeline__card[data-focus]');
99
+
100
+ if (!element || !focus || layout !== 'horizontal') return;
101
+
102
+ if (focus.offsetLeft < element.scrollLeft || focus.offsetLeft + focus.offsetWidth > element.scrollLeft + element.clientWidth) {
103
+ element.scrollLeft = Math.max(0, focus.offsetLeft - (element.clientWidth - focus.offsetWidth) / 2);
104
+ }
105
+ }, [applied, layout]);
106
+
107
+ useEffect(() => {
108
+ const element = strip.current;
109
+
110
+ if (!element) return;
111
+
112
+ const onWheel = (event: WheelEvent) => {
113
+ if (event.ctrlKey || event.metaKey) {
114
+ event.preventDefault();
115
+ const next = zoomFromWheel(zoomRef.current, pending.current, event.deltaY, event.deltaMode);
116
+
117
+ pending.current = next.pending;
118
+ changeZoom(next.zoom);
119
+ return;
120
+ }
121
+
122
+ if (layout === 'horizontal' && wheelScrollsStrip(event, element)) {
123
+ event.preventDefault();
124
+ element.scrollLeft += wheelPixels(event.deltaY, event.deltaMode, lineHeightOf(element), element.clientWidth);
125
+ }
126
+ // Every other wheel passes through, so the page scrolls.
127
+ };
128
+
129
+ element.addEventListener('wheel', onWheel, { passive: false });
130
+
131
+ return () => element.removeEventListener('wheel', onWheel);
132
+ // changeZoom reads refs and `layout`, which is a dependency.
133
+ }, [layout]);
134
+
135
+ return (
136
+ <div className="plan-timeline not-content">
137
+ <div className="plan-timeline__toolbar" hidden={!applied}>
138
+ <div className="plan-timeline__group" role="group" aria-label="Layout">
139
+ <button type="button" aria-pressed={layout === 'horizontal'} onClick={() => setLayout('horizontal')}>
140
+ Left to right
141
+ </button>
142
+ <button type="button" aria-pressed={layout === 'vertical'} onClick={() => setLayout('vertical')}>
143
+ Top to bottom
144
+ </button>
145
+ </div>
146
+ <div className="plan-timeline__group" role="group" aria-label="Zoom">
147
+ <button
148
+ type="button"
149
+ aria-label="Zoom out"
150
+ aria-disabled={zoom <= ZOOM.min}
151
+ onClick={() => {
152
+ if (zoom <= ZOOM.min) return;
153
+ changeZoom(zoomStep(zoom, -1));
154
+ }}
155
+ >
156
+ −
157
+ </button>
158
+ <output className="plan-timeline__zoom" aria-live="polite">
159
+ {Math.round(zoom * 100)}%
160
+ </output>
161
+ <button
162
+ type="button"
163
+ aria-label="Zoom in"
164
+ aria-disabled={zoom >= ZOOM.max}
165
+ onClick={() => {
166
+ if (zoom >= ZOOM.max) return;
167
+ changeZoom(zoomStep(zoom, 1));
168
+ }}
169
+ >
170
+ +
171
+ </button>
172
+ <button
173
+ type="button"
174
+ aria-disabled={zoom === ZOOM.default}
175
+ onClick={() => {
176
+ if (zoom === ZOOM.default) return;
177
+ changeZoom(ZOOM.default);
178
+ }}
179
+ >
180
+ Reset zoom
181
+ </button>
182
+ </div>
183
+ </div>
184
+
185
+ <ol ref={strip} className="plan-timeline__strip" aria-label="Milestones in order" tabIndex={0} data-layout={layout} style={{ '--timeline-zoom': zoom } as CSSProperties}>
186
+ {milestones.map((milestone) => (
187
+ <Card key={milestone.key} milestone={milestone} />
188
+ ))}
189
+ </ol>
190
+ </div>
191
+ );
192
+ }
@@ -0,0 +1,39 @@
1
+ // The Timeline's layout, kept in the page URL as `?layout=vertical`. The
2
+ // server has no location, so the first render is always horizontal (hydration
3
+ // must match it); the query is read in an effect on mount. Every later change
4
+ // is written back with history.replaceState through timelineQuery, which keeps
5
+ // every other parameter and the hash. The pending mark (`data-timeline-pending`
6
+ // on <html>, set before paint by the inline script in roadmap.astro when the
7
+ // URL asks for vertical) keeps the strip hidden until the vertical layout has
8
+ // rendered, so a vertical link never flashes horizontal first.
9
+ import { useEffect, useState } from 'react';
10
+
11
+ import { parseTimelineQuery, timelineQuery } from '../../lib/timeline-state';
12
+ import type { TimelineLayout } from '../../lib/timeline-state';
13
+
14
+ export function useTimelineLayout(): [TimelineLayout, (layout: TimelineLayout) => void, boolean] {
15
+ const [layout, setLayout] = useState<TimelineLayout>('horizontal');
16
+ // True once the URL's layout is applied: the render after it shows that layout.
17
+ const [applied, setApplied] = useState(false);
18
+
19
+ useEffect(() => {
20
+ setLayout(parseTimelineQuery(location.search));
21
+ setApplied(true);
22
+ }, []);
23
+
24
+ useEffect(() => {
25
+ if (!applied) {
26
+ return;
27
+ }
28
+
29
+ // This effect runs after the render that committed the parsed layout, so the strip is already laid out when it shows.
30
+ delete document.documentElement.dataset.timelinePending;
31
+ const url = location.pathname + timelineQuery(layout, location.search) + location.hash;
32
+
33
+ if (url !== location.pathname + location.search + location.hash) {
34
+ history.replaceState(history.state, '', url);
35
+ }
36
+ }, [layout, applied]);
37
+
38
+ return [layout, setLayout, applied];
39
+ }
@@ -1,16 +1,32 @@
1
- import { docsLoader } from '@astrojs/starlight/loaders';
2
- import { docsSchema } from '@astrojs/starlight/schema';
1
+ import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
3
2
  import { defineCollection } from 'astro:content';
4
3
  import config from 'virtual:pm-docs-site/config';
5
4
 
5
+ import { adrsLoader } from './loaders/adrs';
6
6
  import { repoDocsLoader } from './loaders/repo-docs';
7
7
 
8
- // Starlight requires a `docs` collection. With the `docs` option it is the
9
- // repository's Markdown, read where it lives; without it, Starlight's own loader
10
- // finds no src/content/docs/ and the collection is empty.
8
+ // Starlight reads a `docs` and an `i18n` collection. Astro registers a
9
+ // collection only once it holds an entry, and warns that a collection read
10
+ // before then "does not exist or is empty".
11
+ //
12
+ // With the `docs` option, `docs` is the repository's Markdown, read where it
13
+ // lives. Without it, `docs` holds one draft entry: Starlight never routes a
14
+ // draft in a production build, so no page is built, and Starlight's own loader
15
+ // never looks for a src/content/docs/ folder inside this package. `i18n` holds
16
+ // one entry for Starlight's default language with no overrides, so every UI
17
+ // string stays Starlight's own.
18
+ const NO_DOCS = [{ id: 'pm-docs-site/no-docs', title: 'No repository docs', draft: true }];
19
+
11
20
  export const collections = {
12
21
  docs: defineCollection({
13
- loader: config.docs ? repoDocsLoader({ root: config.docs.root, sources: config.docs.sources }) : docsLoader(),
22
+ loader: config.docs ? repoDocsLoader({ root: config.docs.root, sources: config.docs.sources }) : () => NO_DOCS,
14
23
  schema: docsSchema(),
15
24
  }),
25
+ i18n: defineCollection({
26
+ loader: () => [{ id: 'en' }],
27
+ schema: i18nSchema(),
28
+ }),
29
+ // planning.json's ADRs with their sections rendered (src/loaders/adrs.ts). Read
30
+ // only when the export has ADRs, so an empty collection is never looked up.
31
+ adrs: defineCollection({ loader: adrsLoader() }),
16
32
  };
package/src/env.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  /// <reference types="astro/client" />
2
2
 
3
- // The integration's options, resolved and served by index.mjs.
3
+ // The integration's options, resolved and served by lib/index.ts.
4
4
  declare module 'virtual:pm-docs-site/config' {
5
- const config: import('../index').ResolvedOptions;
5
+ const config: import('../lib/types.ts').ResolvedOptions;
6
6
  export default config;
7
7
  }
@@ -0,0 +1,84 @@
1
+ // Builds the Board's flat, serialisable card list at build time, from
2
+ // planning.json and the site's known targets. All filter, lane, and query
3
+ // logic lives in board.ts and runs in the browser; this module only shapes
4
+ // the data once, at build time, the same way board.astro did before it.
5
+
6
+ import { cardRag, COLUMNS } from './board';
7
+ import type { BoardCard, ColumnName, LinkRun } from './board';
8
+ import { features, initials, milestoneId, planProgress } from './planning';
9
+ import type { Owner, Planning } from './planning-types';
10
+ import { linkify } from './references';
11
+ import type { Target } from './references';
12
+
13
+ /** The milestone tag and its page, exactly as board.astro's `tagOf` computes it today. */
14
+ function tagOf(milestone: string | null, known: Map<string, Target>): { tag: string; tagHref: string | null } {
15
+ const key = milestone ?? 'none';
16
+
17
+ return { tag: key === 'none' ? 'No milestone' : key, tagHref: known.get(key)?.href ?? null };
18
+ }
19
+
20
+ /**
21
+ * The card's owner as initials. No owner shows none: the owner filter and the
22
+ * Owner lanes treat it as "No owner", so an AG label would disagree with them.
23
+ */
24
+ function initialsOf(owner: Owner | null): string | null {
25
+ return owner === null ? null : initials(owner);
26
+ }
27
+
28
+ /** Every board card, flat, in `COLUMNS` order and export order, for the Board island. */
29
+ export function boardCards(planning: Planning, known: Map<string, Target>): BoardCard[] {
30
+ const items = new Map(features(planning).map((feature) => [feature.id, feature]));
31
+ const openRisks = planning.risks.open;
32
+ const runsOf = (text: string): LinkRun[] => linkify(text, known).map((run) => ({ text: run.text, href: run.target?.href ?? null, label: run.target?.label ?? null }));
33
+
34
+ const queueCard = (column: Exclude<ColumnName, 'done'>, card: Planning['board']['columns']['now'][number]): BoardCard => {
35
+ const feature = items.get(card.id);
36
+ const milestone = feature?.milestone ?? null;
37
+ const title = `${card.id} ${card.title}`;
38
+ const owner = card.owner ?? ((feature?.owner ?? null) as Owner | null);
39
+
40
+ return {
41
+ key: `${column}:${card.id}`,
42
+ id: card.id,
43
+ title,
44
+ titleRuns: runsOf(title),
45
+ column,
46
+ owner,
47
+ initials: initialsOf(owner),
48
+ milestone,
49
+ ...tagOf(milestone, known),
50
+ size: card.size ?? feature?.size ?? null,
51
+ rag: cardRag(card.id, openRisks),
52
+ detail: runsOf(card.detail ?? ''),
53
+ href: known.get(card.id)?.href ?? null,
54
+ started: column === 'now' ? planning.now.started : null,
55
+ progress: column === 'now' ? planProgress(planning.plan) : null,
56
+ };
57
+ };
58
+
59
+ const doneCard = (entry: Planning['board']['columns']['done'][number], index: number): BoardCard => {
60
+ const title = entry.id ? `${entry.id} ${entry.title}` : entry.title;
61
+ const milestone = milestoneId(entry.milestone, planning.strategy.milestones);
62
+ const owner = (entry.owner ?? null) as Owner | null;
63
+
64
+ return {
65
+ key: `done:${entry.id ?? index}`,
66
+ id: entry.id,
67
+ title,
68
+ titleRuns: runsOf(title),
69
+ column: 'done',
70
+ owner,
71
+ initials: initialsOf(owner),
72
+ milestone,
73
+ ...tagOf(milestone, known),
74
+ size: null,
75
+ rag: cardRag(entry.id, openRisks),
76
+ detail: runsOf(entry.date),
77
+ href: entry.id ? (known.get(entry.id)?.href ?? null) : null,
78
+ started: null,
79
+ progress: null,
80
+ };
81
+ };
82
+
83
+ return COLUMNS.flatMap(({ name }) => (name === 'done' ? planning.board.columns.done.map(doneCard) : planning.board.columns[name].map((card) => queueCard(name, card))));
84
+ }