@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.
- package/LICENSE.md +9 -0
- package/README.md +219 -2
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +90 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +118 -0
- package/dist/options.d.ts +5 -0
- package/dist/options.js +46 -0
- package/dist/repo-docs.d.ts +33 -0
- package/dist/repo-docs.js +94 -0
- package/dist/schema-version.d.ts +10 -0
- package/dist/schema-version.js +19 -0
- package/dist/sidebar.d.ts +10 -0
- package/dist/sidebar.js +30 -0
- package/dist/site-options.d.ts +9 -0
- package/dist/site-options.js +39 -0
- package/dist/types.d.ts +47 -0
- package/dist/types.js +4 -0
- package/lib/repo-docs.ts +124 -0
- package/lib/schema-version.ts +24 -0
- package/package.json +68 -5
- package/src/components/ExportStamp.astro +29 -0
- package/src/components/FeatureSummary.astro +160 -0
- package/src/components/FeatureTable.astro +64 -0
- package/src/components/ItemDetail.astro +16 -0
- package/src/components/ItemDialog.astro +16 -0
- package/src/components/LinkedFrom.astro +33 -0
- package/src/components/LinkedText.astro +12 -0
- package/src/components/PlanInteractions.astro +30 -0
- package/src/components/RefLink.astro +18 -0
- package/src/components/StateBadge.astro +15 -0
- package/src/components/board/Board.tsx +244 -0
- package/src/components/board/KanbanItemCard.tsx +129 -0
- package/src/components/board/LinkRuns.tsx +21 -0
- package/src/components/board/TaskKanbanCard.tsx +81 -0
- package/src/components/board/useBoardUrlState.ts +41 -0
- package/src/components/lib/KanbanItemCard.astro +264 -0
- package/src/components/lib/StatusTimelineFeed.astro +194 -0
- package/src/components/lib/TaskKanbanCard.astro +215 -0
- package/src/components/timeline/Timeline.tsx +159 -0
- package/src/components/timeline/useTimelineLayout.ts +39 -0
- package/src/content.config.ts +16 -0
- package/src/env.d.ts +7 -0
- package/src/lib/board-data.ts +84 -0
- package/src/lib/board.ts +209 -0
- package/src/lib/planning-types.ts +207 -0
- package/src/lib/planning.ts +415 -0
- package/src/lib/references.ts +360 -0
- package/src/lib/timeline.ts +156 -0
- package/src/loaders/repo-docs.ts +69 -0
- package/src/pages/index.astro +158 -0
- package/src/pages/plan/board.astro +41 -0
- package/src/pages/plan/log.astro +83 -0
- package/src/pages/plan/risks/[id].astro +72 -0
- package/src/pages/plan/risks.astro +263 -0
- package/src/pages/plan/roadmap.astro +108 -0
- package/src/routes/plan/briefs.astro +66 -0
- package/src/routes/plan/features/[id].astro +113 -0
- package/src/routes/plan/features/index.astro +29 -0
- package/src/routes/plan/inbox.astro +78 -0
- package/src/routes/plan/milestones/[milestone].astro +113 -0
- package/src/routes/plan/milestones/index.astro +56 -0
- package/src/routes/plan/now.astro +135 -0
- package/src/routes/plan/strategy.astro +194 -0
- package/src/scripts/plan.ts +40 -0
- package/src/styles/components.css +491 -0
- package/src/styles/kanban.css +277 -0
- package/src/styles/timeline.css +210 -0
- package/src/styles/width.css +4 -0
|
@@ -0,0 +1,159 @@
|
|
|
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
|
+
import { useEffect, useLayoutEffect, useRef, useState } from 'react';
|
|
12
|
+
import type { CSSProperties } from 'react';
|
|
13
|
+
|
|
14
|
+
import { wheelScrollsStrip, ZOOM, zoomFromWheel, zoomStep } from '../../lib/timeline';
|
|
15
|
+
import type { TimelineMilestone } from '../../lib/timeline';
|
|
16
|
+
import { useTimelineLayout } from './useTimelineLayout';
|
|
17
|
+
|
|
18
|
+
function Card({ milestone }: { milestone: TimelineMilestone }) {
|
|
19
|
+
const { key, id, name, href, isFocus, status, target, progress } = milestone;
|
|
20
|
+
const title = id === null ? 'No milestone' : `${id} ${name}`;
|
|
21
|
+
|
|
22
|
+
return (
|
|
23
|
+
<li className="plan-timeline__card" data-milestone={key} data-state={status.state} data-focus={isFocus ? '' : undefined}>
|
|
24
|
+
<span className="plan-timeline__marker" aria-hidden="true" />
|
|
25
|
+
<p className="plan-timeline__title">
|
|
26
|
+
{href ? <a href={href}>{title}</a> : <span>{title}</span>}
|
|
27
|
+
{isFocus && <span className="plan-timeline__focus">Focus</span>}
|
|
28
|
+
</p>
|
|
29
|
+
{key !== 'none' && (
|
|
30
|
+
<p className="plan-timeline__status">
|
|
31
|
+
{status.label}
|
|
32
|
+
{status.doneOn && ` · ${status.doneOn}`}
|
|
33
|
+
</p>
|
|
34
|
+
)}
|
|
35
|
+
{key !== 'none' && <p className="plan-timeline__target">{target ? `target ${target}` : 'No target'}</p>}
|
|
36
|
+
<p className="plan-timeline__count">
|
|
37
|
+
{progress.done} of {progress.total} done
|
|
38
|
+
</p>
|
|
39
|
+
{progress.total > 0 && <progress className="plan-timeline__bar" max={progress.total} value={progress.done} />}
|
|
40
|
+
</li>
|
|
41
|
+
);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export default function Timeline({ milestones }: { milestones: TimelineMilestone[] }) {
|
|
45
|
+
const [layout, setLayout, applied] = useTimelineLayout();
|
|
46
|
+
const [zoom, setZoom] = useState<number>(ZOOM.default);
|
|
47
|
+
const zoomRef = useRef<number>(ZOOM.default);
|
|
48
|
+
// Accumulated small (trackpad pinch) wheel deltas, in pixels, not yet a whole step.
|
|
49
|
+
const pending = useRef(0);
|
|
50
|
+
const strip = useRef<HTMLOListElement>(null);
|
|
51
|
+
// The horizontal strip's scroll position and zoom just before a zoom change, so the centre stays put.
|
|
52
|
+
const anchor = useRef<{ scrollLeft: number; prev: number } | null>(null);
|
|
53
|
+
const scrolledToFocus = useRef(false);
|
|
54
|
+
|
|
55
|
+
const changeZoom = (next: number) => {
|
|
56
|
+
if (next === zoomRef.current) return;
|
|
57
|
+
|
|
58
|
+
const element = strip.current;
|
|
59
|
+
|
|
60
|
+
// Keep the earliest snapshot: a second zoom before the render must not read the
|
|
61
|
+
// old scroll position against the new zoom. The layout effect clears it once applied.
|
|
62
|
+
if (element && layout === 'horizontal') anchor.current ??= { scrollLeft: element.scrollLeft, prev: zoomRef.current };
|
|
63
|
+
// Back at the rendered zoom before the render: the layout effect will not run, so drop the snapshot.
|
|
64
|
+
if (anchor.current?.prev === next) anchor.current = null;
|
|
65
|
+
zoomRef.current = next;
|
|
66
|
+
setZoom(next);
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
// After the cards have their new size, before paint: keep the point at the strip's centre at its centre.
|
|
70
|
+
useLayoutEffect(() => {
|
|
71
|
+
const element = strip.current;
|
|
72
|
+
const from = anchor.current;
|
|
73
|
+
|
|
74
|
+
anchor.current = null;
|
|
75
|
+
if (!element || !from) return;
|
|
76
|
+
|
|
77
|
+
const half = element.clientWidth / 2;
|
|
78
|
+
|
|
79
|
+
element.scrollLeft = ((from.scrollLeft + half) * zoom) / from.prev - half;
|
|
80
|
+
}, [zoom]);
|
|
81
|
+
|
|
82
|
+
// On first load, bring the focus card into view by scrolling the strip itself, never the page.
|
|
83
|
+
useEffect(() => {
|
|
84
|
+
if (!applied || scrolledToFocus.current) return;
|
|
85
|
+
|
|
86
|
+
scrolledToFocus.current = true;
|
|
87
|
+
const element = strip.current;
|
|
88
|
+
const focus = element?.querySelector<HTMLElement>('.plan-timeline__card[data-focus]');
|
|
89
|
+
|
|
90
|
+
if (!element || !focus || layout !== 'horizontal') return;
|
|
91
|
+
|
|
92
|
+
if (focus.offsetLeft < element.scrollLeft || focus.offsetLeft + focus.offsetWidth > element.scrollLeft + element.clientWidth) {
|
|
93
|
+
element.scrollLeft = Math.max(0, focus.offsetLeft - (element.clientWidth - focus.offsetWidth) / 2);
|
|
94
|
+
}
|
|
95
|
+
}, [applied, layout]);
|
|
96
|
+
|
|
97
|
+
useEffect(() => {
|
|
98
|
+
const element = strip.current;
|
|
99
|
+
|
|
100
|
+
if (!element) return;
|
|
101
|
+
|
|
102
|
+
const onWheel = (event: WheelEvent) => {
|
|
103
|
+
if (event.ctrlKey || event.metaKey) {
|
|
104
|
+
event.preventDefault();
|
|
105
|
+
const next = zoomFromWheel(zoomRef.current, pending.current, event.deltaY, event.deltaMode);
|
|
106
|
+
|
|
107
|
+
pending.current = next.pending;
|
|
108
|
+
changeZoom(next.zoom);
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
if (layout === 'horizontal' && wheelScrollsStrip(event, element)) {
|
|
113
|
+
event.preventDefault();
|
|
114
|
+
element.scrollLeft += event.deltaY;
|
|
115
|
+
}
|
|
116
|
+
// Every other wheel passes through, so the page scrolls.
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
element.addEventListener('wheel', onWheel, { passive: false });
|
|
120
|
+
|
|
121
|
+
return () => element.removeEventListener('wheel', onWheel);
|
|
122
|
+
// changeZoom reads refs and `layout`, which is a dependency.
|
|
123
|
+
}, [layout]);
|
|
124
|
+
|
|
125
|
+
return (
|
|
126
|
+
<div className="plan-timeline not-content">
|
|
127
|
+
<div className="plan-timeline__toolbar" hidden={!applied}>
|
|
128
|
+
<div className="plan-timeline__group" role="group" aria-label="Layout">
|
|
129
|
+
<button type="button" aria-pressed={layout === 'horizontal'} onClick={() => setLayout('horizontal')}>
|
|
130
|
+
Left to right
|
|
131
|
+
</button>
|
|
132
|
+
<button type="button" aria-pressed={layout === 'vertical'} onClick={() => setLayout('vertical')}>
|
|
133
|
+
Top to bottom
|
|
134
|
+
</button>
|
|
135
|
+
</div>
|
|
136
|
+
<div className="plan-timeline__group" role="group" aria-label="Zoom">
|
|
137
|
+
<button type="button" aria-label="Zoom out" disabled={zoom <= ZOOM.min} onClick={() => changeZoom(zoomStep(zoom, -1))}>
|
|
138
|
+
−
|
|
139
|
+
</button>
|
|
140
|
+
<output className="plan-timeline__zoom" aria-live="polite">
|
|
141
|
+
{Math.round(zoom * 100)}%
|
|
142
|
+
</output>
|
|
143
|
+
<button type="button" aria-label="Zoom in" disabled={zoom >= ZOOM.max} onClick={() => changeZoom(zoomStep(zoom, 1))}>
|
|
144
|
+
+
|
|
145
|
+
</button>
|
|
146
|
+
<button type="button" disabled={zoom === ZOOM.default} onClick={() => changeZoom(ZOOM.default)}>
|
|
147
|
+
Reset zoom
|
|
148
|
+
</button>
|
|
149
|
+
</div>
|
|
150
|
+
</div>
|
|
151
|
+
|
|
152
|
+
<ol ref={strip} className="plan-timeline__strip" aria-label="Milestones in order" tabIndex={0} data-layout={layout} style={{ '--timeline-zoom': zoom } as CSSProperties}>
|
|
153
|
+
{milestones.map((milestone) => (
|
|
154
|
+
<Card key={milestone.key} milestone={milestone} />
|
|
155
|
+
))}
|
|
156
|
+
</ol>
|
|
157
|
+
</div>
|
|
158
|
+
);
|
|
159
|
+
}
|
|
@@ -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';
|
|
12
|
+
import type { TimelineLayout } from '../../lib/timeline';
|
|
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
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { docsLoader } from '@astrojs/starlight/loaders';
|
|
2
|
+
import { docsSchema } from '@astrojs/starlight/schema';
|
|
3
|
+
import { defineCollection } from 'astro:content';
|
|
4
|
+
import config from 'virtual:pm-docs-site/config';
|
|
5
|
+
|
|
6
|
+
import { repoDocsLoader } from './loaders/repo-docs';
|
|
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.
|
|
11
|
+
export const collections = {
|
|
12
|
+
docs: defineCollection({
|
|
13
|
+
loader: config.docs ? repoDocsLoader({ root: config.docs.root, sources: config.docs.sources }) : docsLoader(),
|
|
14
|
+
schema: docsSchema(),
|
|
15
|
+
}),
|
|
16
|
+
};
|
package/src/env.d.ts
ADDED
|
@@ -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
|
+
}
|
package/src/lib/board.ts
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
// Pure filter, lane, and query-string model for the Board island. No Astro,
|
|
2
|
+
// no node:*, no runtime import from planning.ts: the island loads this module
|
|
3
|
+
// in the browser, so it only takes types from planning-types.ts.
|
|
4
|
+
import type { Owner, Rag, Size } from './planning-types';
|
|
5
|
+
|
|
6
|
+
export type ColumnName = 'now' | 'next' | 'foryou' | 'waiting' | 'done';
|
|
7
|
+
|
|
8
|
+
export const COLUMNS: readonly { name: ColumnName; title: string }[] = [
|
|
9
|
+
{ name: 'now', title: 'Now' },
|
|
10
|
+
{ name: 'next', title: 'Next' },
|
|
11
|
+
{ name: 'foryou', title: 'For you' },
|
|
12
|
+
{ name: 'waiting', title: 'Waiting' },
|
|
13
|
+
{ name: 'done', title: 'Done' },
|
|
14
|
+
];
|
|
15
|
+
|
|
16
|
+
export type CardRag = Rag | 'none';
|
|
17
|
+
|
|
18
|
+
export interface LinkRun {
|
|
19
|
+
text: string;
|
|
20
|
+
href: string | null;
|
|
21
|
+
label: string | null;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface BoardCard {
|
|
25
|
+
key: string; // unique per card: `${column}:${id ?? index}`
|
|
26
|
+
id: string | null; // null for a Done entry without an ID
|
|
27
|
+
title: string; // "R-013 Email invoices to tenants"
|
|
28
|
+
titleRuns: LinkRun[]; // linked title text, used when href is null
|
|
29
|
+
column: ColumnName;
|
|
30
|
+
owner: Owner | null;
|
|
31
|
+
initials: string | null; // the owner as the card's initials; null with no owner, which every owner filter hides
|
|
32
|
+
milestone: string | null; // a known milestone ID, or null
|
|
33
|
+
tag: string; // milestone ID or "No milestone"
|
|
34
|
+
tagHref: string | null;
|
|
35
|
+
size: Size | null;
|
|
36
|
+
rag: CardRag;
|
|
37
|
+
detail: LinkRun[]; // the detail line (Done: the date)
|
|
38
|
+
href: string | null; // the item page; null when not built
|
|
39
|
+
started: string | null; // Now card only
|
|
40
|
+
progress: number | null; // Now card only, 0..100
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export interface BoardFilters {
|
|
44
|
+
owner: Owner | null;
|
|
45
|
+
milestone: string | null;
|
|
46
|
+
size: Size | null;
|
|
47
|
+
rag: CardRag | null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export type GroupBy = 'none' | 'milestone' | 'owner';
|
|
51
|
+
|
|
52
|
+
export interface BoardState {
|
|
53
|
+
filters: BoardFilters;
|
|
54
|
+
group: GroupBy;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export const DEFAULT_STATE: BoardState = {
|
|
58
|
+
filters: { owner: null, milestone: null, size: null, rag: null },
|
|
59
|
+
group: 'none',
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
const OWNERS: readonly Owner[] = ['agent', 'user', 'both'];
|
|
63
|
+
const SIZES: readonly Size[] = ['S', 'M', 'L'];
|
|
64
|
+
const RAGS: readonly Rag[] = ['red', 'amber', 'green'];
|
|
65
|
+
const GROUPS: readonly GroupBy[] = ['none', 'milestone', 'owner'];
|
|
66
|
+
const RAG_RANK: Record<Rag, number> = { red: 3, amber: 2, green: 1 };
|
|
67
|
+
|
|
68
|
+
/** The worst of red, amber, green over the open risks that affect this card's ID exactly; 'none' otherwise. */
|
|
69
|
+
export function cardRag(id: string | null, openRisks: { affects: string | null; rag: Rag }[]): CardRag {
|
|
70
|
+
if (id === null) {
|
|
71
|
+
return 'none';
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
let worst: Rag | null = null;
|
|
75
|
+
|
|
76
|
+
for (const risk of openRisks) {
|
|
77
|
+
if (risk.affects === id && (worst === null || RAG_RANK[risk.rag] > RAG_RANK[worst])) {
|
|
78
|
+
worst = risk.rag;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
return worst ?? 'none';
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Parses a board query string (with or without the leading '?'); an unknown or junk value is ignored (All / None). */
|
|
86
|
+
export function parseBoardQuery(search: string, milestoneIds: string[]): BoardState {
|
|
87
|
+
const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
|
|
88
|
+
|
|
89
|
+
const owner = params.get('owner');
|
|
90
|
+
const milestone = params.get('milestone');
|
|
91
|
+
const size = params.get('size');
|
|
92
|
+
const rag = params.get('rag');
|
|
93
|
+
const group = params.get('group');
|
|
94
|
+
|
|
95
|
+
return {
|
|
96
|
+
filters: {
|
|
97
|
+
owner: owner !== null && (OWNERS as string[]).includes(owner) ? (owner as Owner) : null,
|
|
98
|
+
milestone: milestone === 'none' || (milestone !== null && milestoneIds.includes(milestone)) ? milestone : null,
|
|
99
|
+
size: size !== null && (SIZES as string[]).includes(size) ? (size as Size) : null,
|
|
100
|
+
rag: rag === 'none' || (rag !== null && (RAGS as string[]).includes(rag)) ? (rag as CardRag) : null,
|
|
101
|
+
},
|
|
102
|
+
group: group !== null && (GROUPS as string[]).includes(group) ? (group as GroupBy) : 'none',
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** The query string for this state, in the fixed key order owner, milestone, size, rag, group; '' for DEFAULT_STATE. */
|
|
107
|
+
export function boardQuery(state: BoardState): string {
|
|
108
|
+
const { filters, group } = state;
|
|
109
|
+
const pairs: [string, string][] = [];
|
|
110
|
+
|
|
111
|
+
if (filters.owner !== null) {
|
|
112
|
+
pairs.push(['owner', filters.owner]);
|
|
113
|
+
}
|
|
114
|
+
if (filters.milestone !== null) {
|
|
115
|
+
pairs.push(['milestone', filters.milestone]);
|
|
116
|
+
}
|
|
117
|
+
if (filters.size !== null) {
|
|
118
|
+
pairs.push(['size', filters.size]);
|
|
119
|
+
}
|
|
120
|
+
if (filters.rag !== null) {
|
|
121
|
+
pairs.push(['rag', filters.rag]);
|
|
122
|
+
}
|
|
123
|
+
if (group !== 'none') {
|
|
124
|
+
pairs.push(['group', group]);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
if (pairs.length === 0) {
|
|
128
|
+
return '';
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
return `?${pairs.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join('&')}`;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Any filter set; group alone is not a filter. */
|
|
135
|
+
export function isFiltered(state: BoardState): boolean {
|
|
136
|
+
const { owner, milestone, size, rag } = state.filters;
|
|
137
|
+
|
|
138
|
+
return owner !== null || milestone !== null || size !== null || rag !== null;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
export function matches(card: BoardCard, filters: BoardFilters): boolean {
|
|
142
|
+
if (filters.owner !== null && card.owner !== filters.owner) {
|
|
143
|
+
return false;
|
|
144
|
+
}
|
|
145
|
+
if (filters.size !== null && card.size !== filters.size) {
|
|
146
|
+
return false;
|
|
147
|
+
}
|
|
148
|
+
if (filters.milestone !== null) {
|
|
149
|
+
const wantsNone = filters.milestone === 'none';
|
|
150
|
+
|
|
151
|
+
if (wantsNone ? card.milestone !== null : card.milestone !== filters.milestone) {
|
|
152
|
+
return false;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
if (filters.rag !== null && card.rag !== filters.rag) {
|
|
156
|
+
return false;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
return true;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
export interface Lane {
|
|
163
|
+
key: string;
|
|
164
|
+
label: string;
|
|
165
|
+
cards: BoardCard[];
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function bucket(cards: BoardCard[], keyOf: (card: BoardCard) => string): Map<string, BoardCard[]> {
|
|
169
|
+
const buckets = new Map<string, BoardCard[]>();
|
|
170
|
+
|
|
171
|
+
for (const card of cards) {
|
|
172
|
+
const key = keyOf(card);
|
|
173
|
+
const existing = buckets.get(key);
|
|
174
|
+
|
|
175
|
+
if (existing) {
|
|
176
|
+
existing.push(card);
|
|
177
|
+
} else {
|
|
178
|
+
buckets.set(key, [card]);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
return buckets;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/** Groups cards into lanes: ungrouped is one lane holding every card in order; milestone and owner follow a fixed lane order and omit empty lanes. */
|
|
186
|
+
export function lanes(cards: BoardCard[], group: GroupBy, milestones: { id: string; name: string }[]): Lane[] {
|
|
187
|
+
if (group === 'none') {
|
|
188
|
+
return [{ key: 'all', label: '', cards }];
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
if (group === 'milestone') {
|
|
192
|
+
const knownIds = new Set(milestones.map((milestone) => milestone.id));
|
|
193
|
+
const buckets = bucket(cards, (card) => (card.milestone !== null && knownIds.has(card.milestone) ? card.milestone : 'none'));
|
|
194
|
+
const order = [...milestones.map((milestone) => ({ key: milestone.id, label: `${milestone.id} ${milestone.name}` })), { key: 'none', label: 'No milestone' }];
|
|
195
|
+
|
|
196
|
+
return order.filter(({ key }) => (buckets.get(key)?.length ?? 0) > 0).map(({ key, label }) => ({ key, label, cards: buckets.get(key)! }));
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
// group === 'owner'
|
|
200
|
+
const buckets = bucket(cards, (card) => card.owner ?? 'none');
|
|
201
|
+
const order = [
|
|
202
|
+
{ key: 'agent', label: 'agent' },
|
|
203
|
+
{ key: 'user', label: 'user' },
|
|
204
|
+
{ key: 'both', label: 'both' },
|
|
205
|
+
{ key: 'none', label: 'No owner' },
|
|
206
|
+
];
|
|
207
|
+
|
|
208
|
+
return order.filter(({ key }) => (buckets.get(key)?.length ?? 0) > 0).map(({ key, label }) => ({ key, label, cards: buckets.get(key)! }));
|
|
209
|
+
}
|